kempo-ui 0.4.4 → 0.4.6

package/docs-src/components/chat.page.html

@@ -0,0 +1,230 @@
+<page pageName="Chat" title="Chat - Components - Kempo Docs - A Web Components Solution">
+  <content>
+    <k-accordion persistent-id="toc" class="b r mb">
+      <k-accordion-header for-panel="toc-panel">Table of Contents</k-accordion-header>
+      <k-accordion-panel name="toc-panel">
+      <div class="m pl">
+        <h6>Examples</h6>
+        <a href="#basicUsage">Basic Usage</a><br />
+        <a href="#enterBehavior">Enter Behavior</a><br />
+        <a href="#showStatus">Message Status</a><br />
+        <a href="#disabled">Disabled</a><br />
+
+
+        <h6 class="mt"><a href="#jsRef" class="no-link">JavaScript Reference</a></h6>
+        <a href="#constructor">Constructor</a><br />
+        <a href="#requirements">Requirements</a><br />
+        <a href="#properties">Properties</a><br />
+        <a href="#methods">Methods</a><br />
+        <a href="#cssVariables">CSS Variables</a><br />
+        <a href="#events">Events</a><br />
+        <a href="#security">Security Notes</a><br />
+      </div>
+    </k-accordion-panel>
+    </k-accordion>
+
+    <p>A chat-room widget: scrollable history of messages above, a markdown input + Send button below. The input is a <a href="./markdown-editor.html"><code>&lt;k-markdown-editor&gt;</code></a> &mdash; users type markdown (with a Preview tab to see the rendered output before sending), and the message is rendered to HTML via the vendored <a href="https://marked.js.org" target="_blank">marked</a> parser (CommonMark + GFM, including tables and task lists). The rendered HTML runs through <a href="../utils/sanitizeHtml.html"><code>sanitizeHtml</code></a> on its way into the message bubble so any inline HTML the user types is filtered against the allow-list &mdash; <code>&lt;script&gt;</code>, <code>&lt;iframe&gt;</code>, etc. are always stripped.</p>
+
+    <h3 id="basicUsage"><a href="#basicUsage" class="no-link">Basic Usage</a></h3>
+    <p>The component fires a <code>send</code> event when the user submits. Listen for it and call <code>chat.addMessage(...)</code> for incoming replies. Outgoing messages are added automatically.</p>
+    <div class="row -mx">
+      <div class="col m-span-12 px">
+        <k-card label="HTML">
+          <pre><code class="hljs xml"><span class="hljs-tag">&lt;<span class="hljs-name">k-chat</span> <span class="hljs-attr">id</span>=<span class="hljs-string">&quot;basicChat&quot;</span>&gt;</span><span class="hljs-tag">&lt;/<span class="hljs-name">k-chat</span>&gt;</span><br><span class="hljs-tag">&lt;<span class="hljs-name">script</span>&gt;</span><span class="language-javascript"><br>  <span class="hljs-keyword">const</span> chat = <span class="hljs-variable language_">document</span>.<span class="hljs-title function_">getElementById</span>(<span class="hljs-string">&#x27;basicChat&#x27;</span>);<br>  chat.<span class="hljs-title function_">addEventListener</span>(<span class="hljs-string">&#x27;send&#x27;</span>, <span class="hljs-function">(<span class="hljs-params">e</span>) =&gt;</span> {<br>    <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">&#x27;Sent:&#x27;</span>, e.<span class="hljs-property">detail</span>.<span class="hljs-property">markdown</span>);<br>    <span class="hljs-built_in">setTimeout</span>(<span class="hljs-function">() =&gt;</span> {<br>      chat.<span class="hljs-title function_">addMessage</span>({<br>        <span class="hljs-attr">type</span>: <span class="hljs-string">&#x27;incoming&#x27;</span>,<br>        <span class="hljs-attr">html</span>: <span class="hljs-string">&#x27;Got it!&#x27;</span>,<br>        <span class="hljs-attr">sender</span>: <span class="hljs-string">&#x27;Bot&#x27;</span><br>      });<br>    }, <span class="hljs-number">500</span>);<br>  });<br></span><span class="hljs-tag">&lt;/<span class="hljs-name">script</span>&gt;</span></code></pre>
+        </k-card>
+      </div>
+      <div class="col m-span-12 px">
+        <k-card label="Output">
+          <k-chat id="basicChat"></k-chat>
+          <script type="module">
+            await customElements.whenDefined('k-chat');
+            const chat = document.getElementById('basicChat');
+            chat.addMessage({ type: 'incoming', html: 'Welcome &mdash; say hi!', sender: 'Bot' });
+            chat.addEventListener('send', (e) => {
+              setTimeout(() => {
+                chat.addMessage({
+                  type: 'incoming',
+                  html: '<i>Echo:</i> ' + e.detail.html,
+                  sender: 'Bot'
+                });
+              }, 500);
+            });
+          </script>
+        </k-card>
+      </div>
+    </div>
+
+    <h3 id="enterBehavior"><a href="#enterBehavior" class="no-link">Enter Behavior</a></h3>
+    <p>By default the chat matches Slack/Discord/Messages: <strong>Enter sends</strong>, Shift+Enter inserts a newline. Add the <code>enter-newline</code> attribute to flip it &mdash; Enter inserts a newline, Shift+Enter sends.</p>
+    <div class="row -mx">
+      <div class="col m-span-12 px">
+        <k-card label="HTML">
+          <pre><code class="hljs xml"><span class="hljs-tag">&lt;<span class="hljs-name">k-chat</span> <span class="hljs-attr">enter-newline</span>&gt;</span><span class="hljs-tag">&lt;/<span class="hljs-name">k-chat</span>&gt;</span></code></pre>
+        </k-card>
+      </div>
+      <div class="col m-span-12 px">
+        <k-card label="Output">
+          <k-chat id="newlineChat" enter-newline></k-chat>
+          <script type="module">
+            await customElements.whenDefined('k-chat');
+            const chat = document.getElementById('newlineChat');
+            chat.addMessage({ type: 'incoming', html: 'Enter inserts a newline. Shift+Enter sends.', sender: 'Bot' });
+            chat.addEventListener('send', () => {
+              setTimeout(() => chat.addMessage({ type: 'incoming', html: '&#x1F44D;', sender: 'Bot' }), 400);
+            });
+          </script>
+        </k-card>
+      </div>
+    </div>
+
+    <h3 id="showStatus"><a href="#showStatus" class="no-link">Message Status</a></h3>
+    <p>Add <code>show-status</code> and outgoing messages get an iMessage-style status indicator below the bubble. The four statuses are <code>sending</code>, <code>delivered</code>, <code>read</code>, and <code>failed</code>. When the user submits, the message is added with <code>status: 'sending'</code>; advance it via <code>chat.updateMessage(id, { status })</code> as the backend confirms.</p>
+    <p>The attribute takes one of two display modes:</p>
+    <ul>
+      <li><code>show-status</code> or <code>show-status="text"</code> &mdash; small grey text labels (<em>Sending&hellip;</em>, <em>Delivered</em>, <em>Read</em>, <em>Not Delivered</em>). Default mode.</li>
+      <li><code>show-status="icons"</code> &mdash; spinner / check / double-check / error icons only.</li>
+    </ul>
+    <p>Following iMessage convention, the indicator only renders on the <strong>most recent outgoing message</strong> &mdash; older delivered/read messages stay clean. <code>sending</code> and <code>failed</code> always show regardless of position so the user knows about in-flight or stuck messages immediately.</p>
+    <div class="row -mx">
+      <div class="col m-span-12 px">
+        <k-card label="HTML">
+          <pre><code class="hljs xml"><span class="hljs-tag">&lt;<span class="hljs-name">k-chat</span> <span class="hljs-attr">id</span>=<span class="hljs-string">&quot;ackChat&quot;</span> <span class="hljs-attr">show-status</span>&gt;</span><span class="hljs-tag">&lt;/<span class="hljs-name">k-chat</span>&gt;</span><br><span class="hljs-tag">&lt;<span class="hljs-name">script</span> <span class="hljs-attr">type</span>=<span class="hljs-string">&quot;module&quot;</span>&gt;</span><span class="language-javascript"><br>  <span class="hljs-keyword">await</span> customElements.<span class="hljs-title function_">whenDefined</span>(<span class="hljs-string">&#x27;k-chat&#x27;</span>);<br>  <span class="hljs-keyword">const</span> chat = <span class="hljs-variable language_">document</span>.<span class="hljs-title function_">getElementById</span>(<span class="hljs-string">&#x27;ackChat&#x27;</span>);<br>  chat.<span class="hljs-title function_">addEventListener</span>(<span class="hljs-string">&#x27;send&#x27;</span>, <span class="hljs-title function_">async</span> (e) =&gt; {<br>    <span class="hljs-comment">// Simulate a server round-trip</span><br>    <span class="hljs-keyword">await</span> <span class="hljs-keyword">new</span> <span class="hljs-title class_">Promise</span>(<span class="hljs-function"><span class="hljs-params">r</span> =&gt;</span> <span class="hljs-built_in">setTimeout</span>(r, <span class="hljs-number">800</span>));<br>    chat.<span class="hljs-title function_">updateMessage</span>(e.<span class="hljs-property">detail</span>.<span class="hljs-property">id</span>, {<br>      <span class="hljs-attr">status</span>: <span class="hljs-string">&#x27;delivered&#x27;</span><br>    });<br>    <span class="hljs-keyword">await</span> <span class="hljs-keyword">new</span> <span class="hljs-title class_">Promise</span>(<span class="hljs-function"><span class="hljs-params">r</span> =&gt;</span> <span class="hljs-built_in">setTimeout</span>(r, <span class="hljs-number">1200</span>));<br>    chat.<span class="hljs-title function_">updateMessage</span>(e.<span class="hljs-property">detail</span>.<span class="hljs-property">id</span>, {<br>      <span class="hljs-attr">status</span>: <span class="hljs-string">&#x27;read&#x27;</span><br>    });<br>  });<br></span><span class="hljs-tag">&lt;/<span class="hljs-name">script</span>&gt;</span></code></pre>
+        </k-card>
+      </div>
+      <div class="col m-span-12 px">
+        <k-card label="Output">
+          <k-chat id="ackChat" show-status></k-chat>
+          <script type="module">
+            await customElements.whenDefined('k-chat');
+            const chat = document.getElementById('ackChat');
+            chat.addEventListener('send', async (e) => {
+              await new Promise(r => setTimeout(r, 800));
+              chat.updateMessage(e.detail.id, { status: 'delivered' });
+              await new Promise(r => setTimeout(r, 1200));
+              chat.updateMessage(e.detail.id, { status: 'read' });
+            });
+          </script>
+        </k-card>
+      </div>
+    </div>
+
+    <h4>Icon Mode</h4>
+    <p>Pass <code>show-status="icons"</code> for compact icon-only badges (spinner / single check / double check / red error) instead of text labels &mdash; closer to WhatsApp / Telegram styling.</p>
+    <div class="row -mx">
+      <div class="col m-span-12 px">
+        <k-card label="HTML">
+          <pre><code class="hljs xml"><span class="hljs-tag">&lt;<span class="hljs-name">k-chat</span> <span class="hljs-attr">id</span>=<span class="hljs-string">&quot;iconChat&quot;</span> <span class="hljs-attr">show-status</span>=<span class="hljs-string">&quot;icons&quot;</span>&gt;</span><span class="hljs-tag">&lt;/<span class="hljs-name">k-chat</span>&gt;</span><br><span class="hljs-tag">&lt;<span class="hljs-name">script</span> <span class="hljs-attr">type</span>=<span class="hljs-string">&quot;module&quot;</span>&gt;</span><span class="language-javascript"><br>  <span class="hljs-keyword">await</span> customElements.<span class="hljs-title function_">whenDefined</span>(<span class="hljs-string">&#x27;k-chat&#x27;</span>);<br>  <span class="hljs-keyword">const</span> chat = <span class="hljs-variable language_">document</span>.<span class="hljs-title function_">getElementById</span>(<span class="hljs-string">&#x27;iconChat&#x27;</span>);<br>  chat.<span class="hljs-title function_">addEventListener</span>(<span class="hljs-string">&#x27;send&#x27;</span>, <span class="hljs-title function_">async</span> (e) =&gt; {<br>    <span class="hljs-keyword">await</span> <span class="hljs-keyword">new</span> <span class="hljs-title class_">Promise</span>(<span class="hljs-function"><span class="hljs-params">r</span> =&gt;</span> <span class="hljs-built_in">setTimeout</span>(r, <span class="hljs-number">800</span>));<br>    chat.<span class="hljs-title function_">updateMessage</span>(e.<span class="hljs-property">detail</span>.<span class="hljs-property">id</span>, {<br>      <span class="hljs-attr">status</span>: <span class="hljs-string">&#x27;delivered&#x27;</span><br>    });<br>    <span class="hljs-keyword">await</span> <span class="hljs-keyword">new</span> <span class="hljs-title class_">Promise</span>(<span class="hljs-function"><span class="hljs-params">r</span> =&gt;</span> <span class="hljs-built_in">setTimeout</span>(r, <span class="hljs-number">1200</span>));<br>    chat.<span class="hljs-title function_">updateMessage</span>(e.<span class="hljs-property">detail</span>.<span class="hljs-property">id</span>, {<br>      <span class="hljs-attr">status</span>: <span class="hljs-string">&#x27;read&#x27;</span><br>    });<br>  });<br></span><span class="hljs-tag">&lt;/<span class="hljs-name">script</span>&gt;</span></code></pre>
+        </k-card>
+      </div>
+      <div class="col m-span-12 px">
+        <k-card label="Output">
+          <k-chat id="iconChat" show-status="icons"></k-chat>
+          <script type="module">
+            await customElements.whenDefined('k-chat');
+            const chat = document.getElementById('iconChat');
+            chat.addEventListener('send', async (e) => {
+              await new Promise(r => setTimeout(r, 800));
+              chat.updateMessage(e.detail.id, { status: 'delivered' });
+              await new Promise(r => setTimeout(r, 1200));
+              chat.updateMessage(e.detail.id, { status: 'read' });
+            });
+          </script>
+        </k-card>
+      </div>
+    </div>
+
+    <h3 id="disabled"><a href="#disabled" class="no-link">Disabled</a></h3>
+    <p>The <code>disabled</code> attribute prevents user interaction. Useful while waiting for connection or rate-limiting.</p>
+    <div class="row -mx">
+      <div class="col m-span-12 px">
+        <k-card label="HTML">
+          <pre><code class="hljs xml"><span class="hljs-tag">&lt;<span class="hljs-name">k-chat</span> <span class="hljs-attr">disabled</span>&gt;</span><span class="hljs-tag">&lt;/<span class="hljs-name">k-chat</span>&gt;</span></code></pre>
+        </k-card>
+      </div>
+      <div class="col m-span-12 px">
+        <k-card label="Output">
+          <k-chat disabled></k-chat>
+        </k-card>
+      </div>
+    </div>
+
+    <h2 id="jsRef"><a href="#jsRef" class="no-link">JavaScript Reference</a></h2>
+
+    <h3 id="constructor"><a href="#constructor" class="no-link">Constructor</a></h3>
+    <h6>Extends <a href="./shadow-component.html">ShadowComponent</a></h6>
+    <h5><code>new Chat()</code></h5>
+
+    <h3 id="requirements"><a href="#requirements" class="no-link">Requirements</a></h3>
+    <ul>
+      <li><a href="./shadow-component.html">ShadowComponent</a></li>
+      <li><a href="./markdown-editor.html">MarkdownEditor</a> (used internally for the input)</li>
+      <li><a href="../utils/sanitizeHtml.html">sanitizeHtml</a> utility</li>
+    </ul>
+
+    <h3 id="properties"><a href="#properties" class="no-link">Properties</a></h3>
+    <h5><code>enterNewline<i>: Boolean</i></code></h5>
+    <p>Inverts the default Enter-key behavior. Default is <code>false</code> (Slack-style: Enter sends, Shift+Enter inserts a newline). When <code>true</code>: Enter inserts a newline and Shift+Enter sends. Syncs to <code>enter-newline</code> attribute.</p>
+
+    <h5><code>showStatus<i>: String</i></code></h5>
+    <p>Enables and configures the per-message status indicator. Possible values: <code>null</code>/empty (off, default), <code>"text"</code> (small grey labels &mdash; the default mode when the attribute is set without a value), or <code>"icons"</code> (spinner/check/double-check/error glyphs). The indicator only appears on the most recent outgoing message, except for <code>sending</code> and <code>failed</code> which always show. Outgoing messages submitted via the input start as <code>sending</code> &mdash; advance them via <code>updateMessage(id, { status })</code> as the backend confirms. Syncs to <code>show-status</code> attribute.</p>
+
+    <h5><code>placeholder<i>: String</i></code></h5>
+    <p>Placeholder text for the input. Default <code>"Type a message..."</code>. Syncs to <code>placeholder</code> attribute.</p>
+
+    <h5><code>disabled<i>: Boolean</i></code></h5>
+    <p>When <code>true</code>, the input and Send button are disabled. Syncs to <code>disabled</code> attribute.</p>
+
+    <h5><code>messages<i>: Array</i></code> (read-only state)</h5>
+    <p>The current array of messages. Each entry is <code>{ id, type, html, status, sender, timestamp }</code>. Don't mutate directly &mdash; use the public methods.</p>
+
+    <h3 id="methods"><a href="#methods" class="no-link">Methods</a></h3>
+    <h5><code>addMessage(msg)<i>: string</i></code></h5>
+    <p>Append a message and return its <code>id</code>. <code>msg</code> object accepts <code>{ id, type, html, status, sender, timestamp }</code>; missing fields are filled in (auto-generated id, type defaults to <code>"incoming"</code>, etc.). HTML is sanitized.</p>
+
+    <h5><code>updateMessage(id, updates)<i>: boolean</i></code></h5>
+    <p>Update an existing message's <code>html</code>, <code>status</code>, <code>sender</code>, or <code>timestamp</code>. Returns <code>true</code> if a message with that id was found.</p>
+
+    <h5><code>removeMessage(id)<i>: boolean</i></code></h5>
+    <p>Remove a message. Returns <code>true</code> if found.</p>
+
+    <h5><code>clear()<i>: void</i></code></h5>
+    <p>Remove every message.</p>
+
+    <h5><code>send()<i>: string | null</i></code></h5>
+    <p>Programmatically submit whatever is currently in the input. Returns the new outgoing message's <code>id</code>, or <code>null</code> if the input was empty.</p>
+
+    <h3 id="cssVariables"><a href="#cssVariables" class="no-link">CSS Variables</a></h3>
+    <table class="b">
+      <thead><tr><th>Variable</th><th>Default</th><th>Description</th></tr></thead>
+      <tbody>
+        <tr><td><code>--window_min_height</code></td><td><code>16rem</code></td><td>Minimum height of the message window (the chat won't collapse below this even when empty)</td></tr>
+        <tr><td><code>--window_max_height</code></td><td><code>32rem</code></td><td>Maximum height of the message window before it scrolls internally</td></tr>
+        <tr><td><code>--chat_padding</code></td><td><code>0.5rem</code></td><td>Padding inside both the message window and the input row</td></tr>
+        <tr><td><code>--chat_gap</code></td><td><code>0.5rem</code></td><td>Gap between messages and gap between the editor and the Send button</td></tr>
+        <tr><td><code>--height</code></td><td><code>13rem</code></td><td>Initial height of the embedded markdown editor; the user can drag the resize handle below it to grow or shrink past this</td></tr>
+        <tr><td><code>--message_max_width</code></td><td><code>75%</code></td><td>Max width of a single message bubble</td></tr>
+        <tr><td><code>--message_radius</code></td><td><code>1rem</code></td><td>Border radius of message bubbles</td></tr>
+        <tr><td><code>--bubble_padding</code></td><td><code>0.5rem 0.75rem</code></td><td>Padding inside bubbles</td></tr>
+        <tr><td><code>--bubble_bg__incoming</code></td><td><code>var(--c_bg__alt)</code></td><td>Background color of incoming bubbles</td></tr>
+        <tr><td><code>--bubble_bg__outgoing</code></td><td><code>var(--c_primary)</code></td><td>Background color of outgoing bubbles</td></tr>
+        <tr><td><code>--bubble_tc__outgoing</code></td><td><code>white</code></td><td>Text color of outgoing bubbles</td></tr>
+      </tbody>
+    </table>
+
+    <h3 id="events"><a href="#events" class="no-link">Events</a></h3>
+    <h5><code>send</code></h5>
+    <p>Fires when the user submits. <code>detail</code> contains <code>{ id, html, markdown }</code> &mdash; <code>html</code> is the rendered+sanitized output (the same string used in the bubble) and <code>markdown</code> is the raw source the user typed. The outgoing message is already in the conversation by the time the event fires &mdash; if you need to roll it back (e.g. on a network failure), call <code>updateMessage(id, { status: 'failed' })</code> or <code>removeMessage(id)</code>.</p>
+
+    <h3 id="security"><a href="#security" class="no-link">Security Notes</a></h3>
+    <div class="callout warning b r p mb">
+      <strong>The frontend sanitization in this component is not a substitute for server-side sanitization.</strong>
+    </div>
+    <p>Every message that enters the chat (whether from the user's editor, from <code>addMessage()</code>, or from <code>updateMessage()</code>) runs through <a href="../utils/sanitizeHtml.html"><code>sanitizeHtml</code></a> before it is added to the DOM. That strips <code>&lt;script&gt;</code>, <code>&lt;style&gt;</code>, <code>&lt;iframe&gt;</code>, event-handler attributes, and unsafe URL schemes &mdash; but it only protects content that flows through this component.</p>
+    <p>If you persist messages on a server and rebroadcast them to other users, the server <strong>must</strong> independently sanitize before storing and again before sending. A determined attacker can submit raw HTTP without ever loading your client code.</p>
+  </content>
+  <content location="scripts">
+    <script type="module" src="{{pathToRoot}}src/components/Chat.js"></script>
+    <script type="module" src="{{pathToRoot}}src/components/Accordion.js"></script>
+    <script type="module" src="{{pathToRoot}}src/components/Card.js"></script>
+  </content>
+</page>

package/docs-src/components/code-editor.page.html

@@ -9,6 +9,7 @@
         <a href="#controlsExample">Built-in Controls</a><br />
         <a href="#customControls">Custom Controls</a><br />
         <a href="#height">Setting Height</a><br />
+        <a href="#disabled">Disabled / Read-only</a><br />
         <a href="#jsApi">JavaScript API</a><br />
 
         <h6 class="mt"><a href="#jsRef" class="no-link">JavaScript Reference</a></h6>
@@ -100,6 +101,38 @@ console.log(x);"></k-code-editor>
       </div>
     </div>
 
+    <h3 id="disabled"><a href="#disabled" class="no-link">Disabled / Read-only</a></h3>
+    <p>The <code>disabled</code> attribute makes the editor non-interactive (Monaco is set to <code>readOnly</code>), mutes the toolbar, fades the host, and excludes the field from form submission. The <code>readonly</code> attribute lets the user select and copy text but not edit; the value is still submitted with the form.</p>
+    <div class="row -mx">
+      <div class="col m-span-12 px">
+        <k-card label="HTML">
+          <pre><code class="hljs xml"><span class="hljs-tag">&lt;<span class="hljs-name">k-code-editor</span> <span class="hljs-attr">disabled</span> <span class="hljs-attr">value</span>=<span class="hljs-string">&quot;...&quot;</span>&gt;</span><span class="hljs-tag">&lt;/<span class="hljs-name">k-code-editor</span>&gt;</span><br><span class="hljs-tag">&lt;<span class="hljs-name">k-code-editor</span> <span class="hljs-attr">readonly</span> <span class="hljs-attr">value</span>=<span class="hljs-string">&quot;...&quot;</span>&gt;</span><span class="hljs-tag">&lt;/<span class="hljs-name">k-code-editor</span>&gt;</span></code></pre>
+        </k-card>
+      </div>
+      <div class="col m-span-12 px">
+        <k-card label="Output">
+          <k-code-editor
+            disabled
+            language="javascript"
+            class="b r mb"
+            style="height: 160px"
+            value="// This editor is disabled — toolbar is muted, content is locked.
+const x = 42;
+console.log(x);"
+          ></k-code-editor>
+          <k-code-editor
+            readonly
+            language="javascript"
+            class="b r"
+            style="height: 160px"
+            value="// This editor is read-only — select and copy, just not edit.
+const x = 42;
+console.log(x);"
+          ></k-code-editor>
+        </k-card>
+      </div>
+    </div>
+
     <h3 id="jsApi"><a href="#jsApi" class="no-link">JavaScript API</a></h3>
     <p>Interact with the editor programmatically:</p>
     <div class="row -mx">
@@ -127,6 +160,9 @@ console.log(x);"></k-code-editor>
         <tr><td><code>controls</code></td><td><code>controls</code></td><td>String</td><td><code>''</code></td><td>Set to <code>'full'</code> for built-in toolbar; <code>'none'</code> or empty for no built-in controls</td></tr>
         <tr><td><code>monacoSrc</code></td><td><code>monaco-src</code></td><td>String</td><td><code>''</code></td><td>Custom Monaco CDN base URL</td></tr>
         <tr><td><code>editorTheme</code></td><td><code>editor-theme</code></td><td>String</td><td><code>'auto'</code></td><td>Theme override: <code>'auto'</code> (matches site theme), <code>'light'</code>, or <code>'dark'</code></td></tr>
+        <tr><td><code>disabled</code></td><td><code>disabled</code></td><td>Boolean</td><td><code>false</code></td><td>Editor is non-interactive (Monaco set to <code>readOnly</code>), toolbar is muted, host fades, and the field is excluded from form submission</td></tr>
+        <tr><td><code>readonly</code></td><td><code>readonly</code></td><td>Boolean</td><td><code>false</code></td><td>User can select and copy text but not edit (Monaco set to <code>readOnly</code>); value still submitted with the form</td></tr>
+        <tr><td><code>required</code></td><td><code>required</code></td><td>Boolean</td><td><code>false</code></td><td>When <code>true</code> and the editor is empty, the element reports a <code>valueMissing</code> validity error</td></tr>
       </tbody>
     </table>
 

package/docs-src/components/html-editor.page.html

@@ -16,6 +16,7 @@
           <a href="#customNodes">Custom Nodes Example</a><br />
           <a href="#preConfigured">Pre-Configured Editors</a><br />
           <a href="#height">Setting Height</a><br />
+          <a href="#disabled">Disabled / Read-only</a><br />
           <a href="#javascriptUsage">JavaScript API Example</a><br />
 
           <h6 class="mt"><a
@@ -255,6 +256,37 @@
       </div>
     </div>
 
+    <h3 id="disabled"><a
+        href="#disabled"
+        class="no-link"
+      >Disabled / Read-only</a></h3>
+    <p>The <code>disabled</code> attribute makes the editor non-interactive (Lexical is set to non-editable in visual mode, Monaco is set to <code>readOnly</code> in code mode), mutes the toolbar, fades the host, and excludes the field from form submission. The <code>readonly</code> attribute lets the user select and copy text and switch modes, but they can't edit; the value is still submitted with the form.</p>
+    <div class="row -mx">
+      <div class="col m-span-12 px">
+        <k-card label="HTML">
+          <pre><code class="hljs xml"><span class="hljs-tag">&lt;<span class="hljs-name">k-html-editor</span> <span class="hljs-attr">disabled</span> <span class="hljs-attr">value</span>=<span class="hljs-string">&quot;...&quot;</span>&gt;</span><span class="hljs-tag">&lt;/<span class="hljs-name">k-html-editor</span>&gt;</span><br><span class="hljs-tag">&lt;<span class="hljs-name">k-html-editor</span> <span class="hljs-attr">readonly</span> <span class="hljs-attr">value</span>=<span class="hljs-string">&quot;...&quot;</span>&gt;</span><span class="hljs-tag">&lt;/<span class="hljs-name">k-html-editor</span>&gt;</span></code></pre>
+        </k-card>
+      </div>
+      <div class="col m-span-12 px">
+        <k-card label="Output">
+          <k-html-editor
+            disabled
+            controls="minimal"
+            class="b r mb"
+            style="height: 200px"
+            value="<p>This editor is <b>disabled</b> &mdash; the toolbar, content, and mode toggle are all inert.</p>"
+          ></k-html-editor>
+          <k-html-editor
+            readonly
+            controls="minimal"
+            class="b r"
+            style="height: 200px"
+            value="<p>This editor is <i>read-only</i> &mdash; you can select and copy, just not edit.</p>"
+          ></k-html-editor>
+        </k-card>
+      </div>
+    </div>
+
     <h3 id="javascriptUsage"><a
         href="#javascriptUsage"
         class="no-link"
@@ -392,6 +424,15 @@
         Configuration</a> for the full resolution order.
     </p>
 
+    <h5><code>disabled<i>: Boolean</i></code></h5>
+    <p>When <code>true</code>, the editor is non-interactive (Lexical's <code>setEditable(false)</code> in visual mode, Monaco's <code>readOnly</code> in code mode), the toolbar is muted, the host fades to <code>opacity: 0.6</code>, and the field is excluded from form submission. Syncs to <code>disabled</code> attribute.</p>
+
+    <h5><code>readonly<i>: Boolean</i></code></h5>
+    <p>When <code>true</code>, the user can select and copy text but not edit. The value is still submitted with the form. Syncs to <code>readonly</code> attribute.</p>
+
+    <h5><code>required<i>: Boolean</i></code></h5>
+    <p>When <code>true</code> and the editor is empty (no non-whitespace text), the element reports a <code>valueMissing</code> validity error to its parent <code>&lt;form&gt;</code>. Syncs to <code>required</code> attribute.</p>
+
     <h3 id="globalConfig"><a
         href="#globalConfig"
         class="no-link"