@superhuman/squire-rte

Squire
======

Squire is an HTML5 rich text editor, which provides powerful cross-browser normalisation, whilst being supremely lightweight and flexible. It is built for the present and the future, and as such does not support truly ancient browsers. It should work fine back to around Opera 12, Firefox 3.5, Safari 5, Chrome 9 and IE9.

An example UI integration can be tried at http://neilj.github.io/Squire/.

Unlike other HTML5 rich text editors, Squire was written as a component for writing documents (emails, essays, etc.), not doing wysiwyg websites. If you are looking for support for inserting form controls or flash components or the like, you'll need to look elsewhere. However for many purposes, Squire may be just what you need, providing the power without the bloat. The key features are:

$3

* Only 11.5KB of JS after minification and gzip (35KB before gzip).
* Does not include its own XHR wrapper, widget library or lightbox overlays.
* No dependencies.
* No UI for a toolbar is supplied, allowing you to integrate seamlessly with the rest of your application and lose the bloat of having two UI toolkits loaded. Instead, you get a component you can insert in place of a </code> and manipulate programatically.</p><p class="my-3"><h3 class="text-lg font-medium mt-4 mb-2">$3</h3></p><p class="my-3">Squire provides an engine that handles the heavy work for you, making it easy to add extra features. With the <code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">changeFormat</code> method you can easily add or remove any inline formatting you wish. And the <code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">modifyBlocks</code> method can be used to make complicated block-level changes in a relatively easy manner.</p><p class="my-3">If you need more commands than in the simple API, I suggest you check out the source code (it's not very long), and see how a lot of the other API methods are implemented in terms of these two methods.</p><p class="my-3">The general philosophy of Squire is to allow the browser to do as much as it can (which unfortunately is not very much), but take control anywhere it deviates from what is required, or there are significant cross-browser differences. As such, the <a href="https://developer.mozilla.org/en-US/docs/Web/API/Document/execCommand" class="text-primary hover:underline" target="_blank" rel="noopener noreferrer"><code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">document.execCommand</code></a> method is not used at all; instead all formatting is done via custom functions, and certain keys, such as 'enter' and 'backspace' are handled by the editor.</p><p class="my-3">Installation and usage<br />----------------------</p><p class="my-3">1. Copy the contents of the <code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">build/</code> directory onto your server.<br />2. Edit the <code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"><style></code> block in document.html to add the default styles you<br /> would like the editor to use (or link to an external stylesheet).<br />3. In your application, instead of a <code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"><textarea></code>, use an<br /> <code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"><iframe src="path/to/document.html"></code>.<br />4. In your JS, attach an event listener to the <a href="https://developer.mozilla.org/en-US/docs/Web/Events/load" class="text-primary hover:underline" target="_blank" rel="noopener noreferrer"><code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">load</code> event</a> of the iframe. When<br /> this fires you can grab a reference to the editor object through<br /> <code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">iframe.contentWindow.editor</code>.<br />5. Use the API below with the <code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">editor</code> object to set and get data and integrate<br /> with your application or framework.</p><p class="my-3"><h3 class="text-lg font-medium mt-4 mb-2">$3</h3></p><p class="my-3">Squire can also be used without an iframe for the document. To use it this way:</p><p class="my-3">1. Add a <code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"><script></code> tag to load in <code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">build/squire.js</code> (or <code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">squire-raw.js</code> for the debuggable unminified version).<br />2. Get a reference to the DOM node in the document that you want to make into the rich textarea, e.g. <code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">node = document.getElementById( 'editor-div' )</code>.<br />3. Call <code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">editor = new Squire( node )</code>. This will instantiate a new Squire instance. Please note, this will remove any current children of the node; you must use the <code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">setHTML</code> command after initialising to set any content.</p><p class="my-3">You can have multiple squire instances in a single page without issue. If you are using the editor as part of a long lived single-page app, be sure to call <code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">editor.destroy()</code> once you have finished using an instance to ensure it doesn't leak resources.</p><p class="my-3"><h3 class="text-lg font-medium mt-4 mb-2">$3</h3></p><p class="my-3">Malicious HTML can be a source of XSS and other security issues. I highly recommended you use <a href="https://github.com/cure53/DOMPurify" class="text-primary hover:underline" target="_blank" rel="noopener noreferrer">DOMPurify</a> with Squire to prevent these security issues. If DOMPurify is included in the page (with the standard global variable), Squire will automatically sanitise any HTML passed in via <code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">setHTML</code> or <code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">insertHTML</code> (which includes HTML the user pastes from the clipboard).</p><p class="my-3">You can override this by setting properties on the config object (the second argument passed to the constructor, see below). The properties are:</p><p class="my-3">* <strong>isSetHTMLSanitized</strong>: <code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">Boolean</code><br /> Should the HTML passed via calls to <code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">setHTML</code> be passed to the sanitizer? If your app always sanitizes the HTML in some other way before calling this, you may wish to set this to <code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">false</code> to avoid the overhead.<br />* <strong>isInsertedHTMLSanitized</strong>: <code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">Boolean</code> (defaults to <code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">true</code>) – Should the HTML passed via calls to <code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">insertHTML</code> be passed to the sanitizer? This includes when the user pastes from the clipboard. Since you cannot control what other apps put on the clipboard, it is highly recommended you do not set this to <code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">false</code>.<br />* <strong>sanitizeToDOMFragment</strong>: <code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">(html: String, isPaste: Boolean, self: Squire) -> DOMFragment</code><br /> A custom sanitization function. This will be called instead of the default call to DOMPurify to sanitize the potentially dangerous HTML. It is passed three arguments: the first is the string of HTML, the second is a boolean indicating if this content has come from the clipboard, rather than an explicit call by your own code, the third is the squire instance. It must return a DOM Fragment node belonging to the same document as the editor's root node, with the contents being clean DOM nodes to set/insert.</p><p class="my-3">Advanced usage<br />--------------</p><p class="my-3">If you load the library into a top-level document (rather than an iframe), or load it in an iframe without the <code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">data-squireinit="true"</code> attribute on its <code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"><html></code> element, it will not turn the page into an editable document, but will instead add a constructor named <code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">Squire</code> to the global scope.</p><p class="my-3">You can also require the NPM package <a href="https://www.npmjs.com/package/squire-rte" class="text-primary hover:underline" target="_blank" rel="noopener noreferrer">squire-rte</a> to import <code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">Squire</code> in a modular program without adding names to the global namespace.</p><p class="my-3">Call <code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">new Squire( document )</code>, with the <code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">document</code> from an iframe to instantiate multiple rich text areas on the same page efficiently. Note, for compatibility with all browsers (particularly Firefox), you MUST wait for the iframe's <code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">onload</code> event to fire before instantiating Squire.</p><p class="my-3"><h3 class="text-lg font-medium mt-4 mb-2">$3</h3></p><p class="my-3">By default, the editor will use a <code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"><div></code> for blank lines, as most users have been conditioned by Microsoft Word to expect <kbd>Enter</kbd> to act like pressing <kbd>return</kbd> on a typewriter. If you would like to use <code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"><p></code> tags (or anything else) for the default block type instead, you can pass a config object as the second parameter to the squire constructor. You can also<br />pass a set of attributes to apply to each default block:</p><p class="my-3"> var editor = new Squire( document, {<br /> blockTag: 'P',<br /> blockAttributes: { style: 'font-size: 16px;' }<br /> })</p><p class="my-3">If using the simple setup, call <code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">editor.setConfig(…);</code> with your<br />config object instead. Be sure to do this <em>before</em> calling <code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">editor.setHTML()</code>.</p><p class="my-3"><h3 class="text-lg font-medium mt-4 mb-2">$3</h3></p><p class="my-3">If you are adding a UI to Squire, you'll probably want to show a button in different states depending on whether a particular style is active in the current selection or not. For example, a "Bold" button would be in a depressed state if the text under the cursor is already bold.</p><p class="my-3">The efficient way to determine the state for most buttons is to monitor the "pathChange" event in the editor, and determine the state from the new path. If the selection goes across nodes, you will need to call the <code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">hasFormat</code> method for each of your buttons to determine whether the styles are active. See the <code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">getPath</code> and <code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">hasFormat</code> documentation for more information.</p><p class="my-3">License<br />-------</p><p class="my-3">Squire is released under the MIT license. See LICENSE for full license.</p><p class="my-3">API<br />---</p><p class="my-3"><h3 class="text-lg font-medium mt-4 mb-2">$3</h3></p><p class="my-3">Attach an event listener to the editor. The handler can be either a function or an object with a <code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">handleEvent</code> method. This function or method will be called whenever the event fires, with an event object as the sole argument. The following events may be observed:</p><p class="my-3">* <strong>focus</strong>: The editor gained focus.<br />* <strong>blur</strong>: The editor lost focus<br />* <strong>keydown</strong>: Standard <a href="https://developer.mozilla.org/en-US/docs/Web/Events/keydown" class="text-primary hover:underline" target="_blank" rel="noopener noreferrer">DOM keydown event</a>.<br />* <strong>keypress</strong>: Standard <a href="https://developer.mozilla.org/en-US/docs/Web/Events/keypress" class="text-primary hover:underline" target="_blank" rel="noopener noreferrer">DOM keypress event</a>.<br />* <strong>keyup</strong>: Standard <a href="https://developer.mozilla.org/en-US/docs/Web/Events/keyup" class="text-primary hover:underline" target="_blank" rel="noopener noreferrer">DOM keyup event</a>.<br />* <strong>input</strong>: The user inserted, deleted or changed the style of some text; in other words, the result for <code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">editor.getHTML()</code> will have changed.<br />* <strong>pathChange</strong>: The path (see getPath documentation) to the cursor has changed. The new path is available as the <code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">path</code> property on the event object.<br />* <strong>select</strong>: The user selected some text.<br />* <strong>undoStateChange</strong>: The availability of undo and/or redo has changed. The event object has two boolean properties, <code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">canUndo</code> and <code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">canRedo</code> to let you know the new state.<br />* <strong>willPaste</strong>: The user is pasting content into the document. The content that will be inserted is available as the <code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">fragment</code> property on the event object. You can modify this fragment in your event handler to change what will be pasted. You can also call the <code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">preventDefault</code> on the event object to cancel the paste operation.</p><p class="my-3">The method takes two arguments:</p><p class="my-3">* <strong>type</strong>: The event to listen for. e.g. 'focus'.<br />* <strong>handler</strong>: The callback function to invoke</p><p class="my-3">Returns self (the Squire instance).</p><p class="my-3"><h3 class="text-lg font-medium mt-4 mb-2">$3</h3></p><p class="my-3">Remove an event listener attached via the addEventListener method.</p><p class="my-3">The method takes two arguments:</p><p class="my-3">* <strong>type</strong>: The event type the handler was registered for.<br />* <strong>handler</strong>: The handler to remove.</p><p class="my-3">Returns self (the Squire instance).</p><p class="my-3"><h3 class="text-lg font-medium mt-4 mb-2">$3</h3></p><p class="my-3">Adds or removes a keyboard shortcut. You can use this to override the default keyboard shortcuts (e.g. Ctrl-B for bold – see the bottom of KeyHandlers.js for the list).</p><p class="my-3">This method takes two arguments:</p><p class="my-3">* <strong>key</strong>: The key to handle, including any modifiers in alphabetical order. e.g. <code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">"alt-ctrl-meta-shift-enter"</code><br />* <strong>fn</strong>: The function to be called when this key is pressed, or <code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">null</code> if removing a key handler. The function will be passed three arguments when called:<br /> * <strong>self</strong>: A reference to the Squire instance.<br /> * <strong>event</strong>: The key event object.<br /> * <strong>range</strong>: A Range object representing the current selection.</p><p class="my-3">Returns self (the Squire instance).</p><p class="my-3"><h3 class="text-lg font-medium mt-4 mb-2">$3</h3></p><p class="my-3">Focuses the editor.</p><p class="my-3">The method takes no arguments.</p><p class="my-3">Returns self (the Squire instance).</p><p class="my-3"><h3 class="text-lg font-medium mt-4 mb-2">$3</h3></p><p class="my-3">Removes focus from the editor.</p><p class="my-3">The method takes no arguments.</p><p class="my-3">Returns self (the Squire instance).</p><p class="my-3"><h3 class="text-lg font-medium mt-4 mb-2">$3</h3></p><p class="my-3">Returns the <code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">document</code> object of the editable area. May be useful to do transformations outside the realm of the API.</p><p class="my-3"><h3 class="text-lg font-medium mt-4 mb-2">$3</h3></p><p class="my-3">Returns the HTML value of the editor in its current state. This value is equivalent to the contents of the <code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"><body></code> tag and does not include any surrounding boilerplate.</p><p class="my-3"><h3 class="text-lg font-medium mt-4 mb-2">$3</h3></p><p class="my-3">Sets the HTML value for the editor. The value supplied should not contain <code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"><body></code> tags or anything outside of that.</p><p class="my-3">The method takes one argument:</p><p class="my-3">* <strong>html</strong>: The html to set.</p><p class="my-3">Returns self (the Squire instance).</p><p class="my-3"><h3 class="text-lg font-medium mt-4 mb-2">$3</h3></p><p class="my-3">Returns the text currently selected in the editor.</p><p class="my-3"><h3 class="text-lg font-medium mt-4 mb-2">$3</h3></p><p class="my-3">Inserts an image at the current cursor location.</p><p class="my-3">The method takes two arguments:</p><p class="my-3">* <strong>src</strong>: The source path for the image.<br />* <strong>attributes</strong>: (optional) An object containing other attributes to set on the <code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"><img></code> node. e.g. <code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">{ class: 'class-name' }</code>. Any <code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">src</code> attribute will be overwritten by the url given as the first argument.</p><p class="my-3">Returns a reference to the newly inserted image element.</p><p class="my-3"><h3 class="text-lg font-medium mt-4 mb-2">$3</h3></p><p class="my-3">Inserts an HTML fragment at the current cursor location, or replaces the selection if selected. The value supplied should not contain <code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"><body></code> tags or anything outside of that.</p><p class="my-3">The method takes one argument:</p><p class="my-3">* <strong>html</strong>: The html to insert.</p><p class="my-3">Returns self (the Squire instance).</p><p class="my-3"><h3 class="text-lg font-medium mt-4 mb-2">$3</h3></p><p class="my-3">Returns the path through the DOM tree from the <code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"><body></code> element to the current current cursor position. This is a string consisting of the tag, id, class, font, and color names in CSS format. For example <code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">BODY>BLOCKQUOTE>DIV#id>STRONG>SPAN.font[fontFamily=Arial,sans-serif]>EM</code>. If a selection has been made, so different parts of the selection may have different paths, the value will be <code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">(selection)</code>. The path is useful for efficiently determining the current formatting for bold, italic, underline etc, and thus determining button state. If a selection has been made, you can has the <code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">hasFormat</code> method instead to get the current state for the properties you care about.</p><p class="my-3"><h3 class="text-lg font-medium mt-4 mb-2">$3</h3></p><p class="my-3">Returns an object containing the active font family, size, colour and background colour for the the current cursor position, if any are set. The property names are respectively <code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">family</code>, <code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">size</code>, <code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">color</code> and <code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">backgroundColor</code>. It looks at style attributes to detect this, so will not detect <code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"><FONT></code> tags or non-inline styles. If a selection across multiple elements has been made, it will return an empty object.</p><p class="my-3"><h3 class="text-lg font-medium mt-4 mb-2">$3</h3></p><p class="my-3">Returns a bounding client rect (top/left/right/bottom properties relative to<br />the viewport) for the current selection/cursor.</p><p class="my-3"><h3 class="text-lg font-medium mt-4 mb-2">$3</h3></p><p class="my-3">Returns a <a href="https://developer.mozilla.org/en-US/docs/Web/API/Range" class="text-primary hover:underline" target="_blank" rel="noopener noreferrer">W3C Range object</a> representing the current selection/cursor position.</p><p class="my-3"><h3 class="text-lg font-medium mt-4 mb-2">$3</h3></p><p class="my-3">Changes the current selection/cursor position.</p><p class="my-3">The method takes one argument:</p><p class="my-3">* <strong>range</strong>: The <a href="https://developer.mozilla.org/en-US/docs/Web/API/Range" class="text-primary hover:underline" target="_blank" rel="noopener noreferrer">W3C Range object</a> representing the desired selection.</p><p class="my-3">Returns self (the Squire instance).</p><p class="my-3"><h3 class="text-lg font-medium mt-4 mb-2">$3</h3></p><p class="my-3">Removes any current selection and moves the cursor to the very beginning of the<br />document.</p><p class="my-3">Returns self (the Squire instance).</p><p class="my-3"><h3 class="text-lg font-medium mt-4 mb-2">$3</h3></p><p class="my-3">Removes any current selection and moves the cursor to the very end of the<br />document.</p><p class="my-3">Returns self (the Squire instance).</p><p class="my-3"><h3 class="text-lg font-medium mt-4 mb-2">$3</h3></p><p class="my-3">Saves an undo checkpoint with the current editor state. Methods that modify the<br />state (e.g. bold/setHighlightColour/modifyBlocks) will automatically save undo<br />checkpoints; you only need this method if you want to modify the DOM outside of<br />one of these methods, and you want to save an undo checkpoint first.</p><p class="my-3">Returns self (the Squire instance).</p><p class="my-3"><h3 class="text-lg font-medium mt-4 mb-2">$3</h3></p><p class="my-3">Undoes the most recent change.</p><p class="my-3">Returns self (the Squire instance).</p><p class="my-3"><h3 class="text-lg font-medium mt-4 mb-2">$3</h3></p><p class="my-3">If the user has just undone a change, this will reapply that change.</p><p class="my-3">Returns self (the Squire instance).</p><p class="my-3"><h3 class="text-lg font-medium mt-4 mb-2">$3</h3></p><p class="my-3">Queries the editor for whether a particular format is applied anywhere in the current selection.</p><p class="my-3">The method takes two arguments:</p><p class="my-3">* <strong>tag</strong>: The tag of the format<br />* <strong>attributes</strong>: (optional) Any attributes the format.</p><p class="my-3">Returns <code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">true</code> if any of the selection is contained within an element with the specified tag and attributes, otherwise returns <code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">false</code>.</p><p class="my-3"><h3 class="text-lg font-medium mt-4 mb-2">$3</h3></p><p class="my-3">Makes any non-bold currently selected text bold (by wrapping it in a <code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"><b></code> tag).</p><p class="my-3">Returns self (the Squire instance).</p><p class="my-3"><h3 class="text-lg font-medium mt-4 mb-2">$3</h3></p><p class="my-3">Makes any non-italic currently selected text italic (by wrapping it in an <code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"><i></code> tag).</p><p class="my-3">Returns self (the Squire instance).</p><p class="my-3"><h3 class="text-lg font-medium mt-4 mb-2">$3</h3></p><p class="my-3">Makes any non-underlined currently selected text underlined (by wrapping it in a <code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"><u></code> tag).</p><p class="my-3">Returns self (the Squire instance).</p><p class="my-3"><h3 class="text-lg font-medium mt-4 mb-2">$3</h3></p><p class="my-3">Removes any bold formatting from the selected text.</p><p class="my-3">Returns self (the Squire instance).</p><p class="my-3"><h3 class="text-lg font-medium mt-4 mb-2">$3</h3></p><p class="my-3">Removes any italic formatting from the selected text.</p><p class="my-3">Returns self (the Squire instance).</p><p class="my-3"><h3 class="text-lg font-medium mt-4 mb-2">$3</h3></p><p class="my-3">Removes any underline formatting from the selected text.</p><p class="my-3">Returns self (the Squire instance).</p><p class="my-3"><h3 class="text-lg font-medium mt-4 mb-2">$3</h3></p><p class="my-3">Makes the currently selected text a link. If no text is selected, the URL or email will be inserted as text at the current cursor point and made into a link.</p><p class="my-3">This method takes two arguments:</p><p class="my-3">* <strong>url</strong>: The url or email to link to.<br />* <strong>attributes</strong>: (optional) An object containing other attributes to set on the <code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"><a></code> node. e.g. <code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">{ target: '_blank' }</code>. Any <code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">href</code> attribute will be overwritten by the url given as the first argument.</p><p class="my-3">Returns self (the Squire instance).</p><p class="my-3"><h3 class="text-lg font-medium mt-4 mb-2">$3</h3></p><p class="my-3">Removes any link that is currently at least partially selected.</p><p class="my-3">Returns self (the Squire instance).</p><p class="my-3"><h3 class="text-lg font-medium mt-4 mb-2">$3</h3></p><p class="my-3">Sets the font face for the selected text.</p><p class="my-3">This method takes one argument:</p><p class="my-3">* <strong>font</strong>: A comma-separated list of fonts (in order of preference) to set.</p><p class="my-3">Returns self (the Squire instance).</p><p class="my-3"><h3 class="text-lg font-medium mt-4 mb-2">$3</h3></p><p class="my-3">Sets the font size for the selected text.</p><p class="my-3">This method takes one argument:</p><p class="my-3">* <strong>size</strong>: A size to set. Any CSS <a href="https://developer.mozilla.org/en-US/docs/Web/CSS/length" class="text-primary hover:underline" target="_blank" rel="noopener noreferrer">length value</a> or <a href="https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_values_syntax#syntax-absolute-size" class="text-primary hover:underline" target="_blank" rel="noopener noreferrer">absolute-size value</a> is accepted, e.g. '13px', or 'small'.</p><p class="my-3">Returns self (the Squire instance).</p><p class="my-3"><h3 class="text-lg font-medium mt-4 mb-2">$3</h3></p><p class="my-3">Sets the colour of the selected text.</p><p class="my-3">This method takes one argument:</p><p class="my-3">* <strong>colour</strong>: The colour to set. Any <a href="https://developer.mozilla.org/en-US/docs/Web/CSS/color_value" class="text-primary hover:underline" target="_blank" rel="noopener noreferrer">CSS colour value</a> is accepted, e.g. '#f00', or 'hsl(0,0,0)'.</p><p class="my-3">Returns self (the Squire instance).</p><p class="my-3"><h3 class="text-lg font-medium mt-4 mb-2">$3</h3></p><p class="my-3">Sets the colour of the background of the selected text.</p><p class="my-3">This method takes one argument:</p><p class="my-3">* <strong>colour</strong>: The colour to set. Any <a href="https://developer.mozilla.org/en-US/docs/Web/CSS/color_value" class="text-primary hover:underline" target="_blank" rel="noopener noreferrer">CSS colour value</a> is accepted, e.g. '#f00', or 'hsl(0,0,0)'.</p><p class="my-3">Returns self (the Squire instance).</p><p class="my-3"><h3 class="text-lg font-medium mt-4 mb-2">$3</h3></p><p class="my-3">Sets the text alignment in all blocks at least partially contained by the selection.</p><p class="my-3">This method takes one argument:</p><p class="my-3">* <strong>alignment</strong>: The direction to align to. Can be 'left', 'right', 'center' or 'justify'.</p><p class="my-3">Returns self (the Squire instance).</p><p class="my-3"><h3 class="text-lg font-medium mt-4 mb-2">$3</h3></p><p class="my-3">Sets the text direction in all blocks at least partially contained by the selection.</p><p class="my-3">This method takes one argument:</p><p class="my-3">* <strong>direction</strong>: The text direction. Can be 'ltr' or 'rtl'.</p><p class="my-3">Returns self (the Squire instance).</p><p class="my-3"><h3 class="text-lg font-medium mt-4 mb-2">$3</h3></p><p class="my-3">Executes a function on each block in the current selection, or until the function returns a truthy value.</p><p class="my-3">This method takes two arguments:</p><p class="my-3">* <strong>fn</strong> The function to execute on each block node at least partially contained in the current selection. The function will be called with the block node as the only argument.<br />* <strong>mutates</strong> A boolean indicating whether your function may modify anything in the document in any way.</p><p class="my-3">Returns self (the Squire instance).</p><p class="my-3"><h3 class="text-lg font-medium mt-4 mb-2">$3</h3></p><p class="my-3">Extracts a portion of the DOM tree (up to the block boundaries of the current selection), modifies it and then reinserts it and merges the edges. See the code for examples if you're interested in using this function.</p><p class="my-3">This method takes one argument:</p><p class="my-3">* <strong>modify</strong> The function to apply to the extracted DOM tree; gets a document fragment as a sole argument. <code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">this</code> is bound to the Squire instance. Should return the node or fragment to be reinserted in the DOM.</p><p class="my-3">Returns self (the Squire instance).</p><p class="my-3"><h3 class="text-lg font-medium mt-4 mb-2">$3</h3></p><p class="my-3">Increases by 1 the quote level (number of <code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"><blockquote></code> tags wrapping) all blocks at least partially selected.</p><p class="my-3">Returns self (the Squire instance).</p><p class="my-3"><h3 class="text-lg font-medium mt-4 mb-2">$3</h3></p><p class="my-3">Decreases by 1 the quote level (number of <code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"><blockquote></code> tags wrapping) all blocks at least partially selected.</p><p class="my-3">Returns self (the Squire instance).</p><p class="my-3"><h3 class="text-lg font-medium mt-4 mb-2">$3</h3></p><p class="my-3">Changes all at-least-partially selected blocks to be part of an unordered list.</p><p class="my-3">Returns self (the Squire instance).</p><p class="my-3"><h3 class="text-lg font-medium mt-4 mb-2">$3</h3></p><p class="my-3">Changes all at-least-partially selected blocks to be part of an ordered list.</p><p class="my-3">Returns self (the Squire instance).</p><p class="my-3"><h3 class="text-lg font-medium mt-4 mb-2">$3</h3></p><p class="my-3">Changes any at-least-partially selected blocks which are part of a list to no longer be part of a list.</p><p class="my-3">Returns self (the Squire instance).</p><p class="my-3"><h3 class="text-lg font-medium mt-4 mb-2">$3</h3></p><p class="my-3">Increases by 1 the nesting level of any at-least-partially selected blocks which are part of a list.</p><p class="my-3">Returns self (the Squire instance).</p><p class="my-3"><h3 class="text-lg font-medium mt-4 mb-2">$3</h3></p><p class="my-3">Decreases by 1 the nesting level of any at-least-partially selected blocks which are part of a list.</p><p class="my-3">Returns self (the Squire instance).</p><p class="my-3"><h3 class="text-lg font-medium mt-4 mb-2">$3</h3></p><p class="my-3">Removes all formatting from the selection. Block elements (list items, table cells, etc.) are kept as separate blocks.</p><p class="my-3">Returns self (the Squire instance).</p><p class="my-3"><h3 class="text-lg font-medium mt-4 mb-2">$3</h3></p><p class="my-3">Change the <strong>inline</strong> formatting of the current selection. This is a high-level method which is used to implement the bold, italic etc. helper methods. THIS METHOD IS ONLY FOR USE WITH INLINE TAGS, NOT BLOCK TAGS. It takes 4 arguments:</p><p class="my-3">1. An object describing the formatting to add, or <code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">null</code> if you only wish to remove formatting. If supplied, this object should have a <code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">tag</code> property with the string name of the tag to wrap around the selected text (e.g. <code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">"STRONG"</code>) and optionally an <code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">attributes</code> property, consisting of an object of attributes to apply to the tag (e.g. <code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">{"class": "bold"}</code>).<br />2. An object describing the formatting to remove, in the same format as the object given to add formatting, or <code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">null</code> if you only wish to add formatting.<br />3. A Range object with the range to apply the formatting changes to (or <code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">null</code>/omit to apply to current selection).<br />4. A boolean (defaults to <code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">false</code> if omitted). If <code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">true</code>, any formatting nodes that cover at least part of the selected range will be removed entirely (so will potentially be removed from text outside the selected range as well). If <code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">false</code>, the formatting nodes will continue to apply to any text outside the selection. This is useful, for example, when removing links. If any of the text in the selection is part of a link, the whole link is removed, rather than the link continuing to apply to bits of text outside the selection.</p><p class="my-3"><h3 class="text-lg font-medium mt-4 mb-2">$3</h3></p><p class="my-3">Takes in a function that can modify the document without the modifications being treated as input.</p><p class="my-3">This is useful when the document needs to be changed programmatically, but those changes should not raise input events or modify the undo state.<br /></p></div><div class="flex justify-center absolute inset-x-0 bottom-0 bg-gradient-to-t from-background via-background to-transparent pb-4 pt-16"><button data-slot="button" class="inline-flex items-center justify-center whitespace-nowrap text-sm font-medium transition-all disabled:pointer-events-none disabled:opacity-50 [&_svg]:pointer-events-none [&_svg:not([class*='size-'])]:size-4 shrink-0 [&_svg]:shrink-0 outline-none focus-visible:border-ring focus-visible:ring-ring/50 focus-visible:ring-[3px] aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive border bg-background shadow-xs hover:bg-accent hover:text-accent-foreground dark:bg-input/30 dark:border-input dark:hover:bg-input/50 h-8 rounded-md gap-1.5 px-3 has-[>svg]:px-2.5"><svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-chevron-down mr-1 h-4 w-4"><path d="m6 9 6 6 6-6"></path></svg>Show more</button></div></div></div><template id="P:3"></template><template id="P:4"></template></div></div></div><script>self.__next_f.push([1,"26:[\"$\",\"path\",\"mthhwq\",{\"d\":\"m9 18 6-6-6-6\"}]\n27:[\"$\",\"span\",null,{\"className\":\"ml-2 shrink-0 font-mono text-xs text-muted-foreground\",\"children\":\"8.2.0\"}]\n"])</script><div hidden id="S:3"><div data-state="inactive" data-orientation="horizontal" role="tabpanel" aria-labelledby="radix-_R_aav5ubrb_-trigger-dependencies" hidden="" id="radix-_R_aav5ubrb_-content-dependencies" tabindex="0" data-slot="tabs-content" class="flex-1 outline-none mt-6"></div></div><script>$RS=function(a,b){a=document.getElementById(a);b=document.getElementById(b);for(a.parentNode.removeChild(a);a.firstChild;)b.parentNode.insertBefore(a.firstChild,b);b.parentNode.removeChild(b)};$RS("S:3","P:3")</script><div hidden id="S:4"><div data-state="inactive" data-orientation="horizontal" role="tabpanel" aria-labelledby="radix-_R_aav5ubrb_-trigger-versions" hidden="" id="radix-_R_aav5ubrb_-content-versions" tabindex="0" data-slot="tabs-content" class="flex-1 outline-none mt-6"></div></div><script>$RS("S:4","P:4")</script><script>$RC("B:1","S:1")</script></body></html>