@aquera/nile-elements 1.9.8 → 1.9.9

package/src/nile-wysiwyg-editor/engine/schema.ts

@@ -1,7 +1,8 @@
-import { Schema, NodeSpec, MarkSpec } from 'prosemirror-model';
+import { Schema, NodeSpec, MarkSpec, Attrs, DOMOutputSpec, ParseRule } from 'prosemirror-model';
 import { addListNodes } from 'prosemirror-schema-list';
 import { tableNodes } from 'prosemirror-tables';
 import OrderedMap from 'orderedmap';
+import { EMBED_SANDBOX, EMBED_REFERRER_POLICY } from './plugins/embeds';
 
 export type Alignment = 'left' | 'center' | 'right' | 'justify';
 
@@ -54,6 +55,100 @@ function blockStyle(attrs: {
   return parts.length ? parts.join('; ') : null;
 }
 
+/* -------------------------------------------------------------------------
+ * Author class / id passthrough
+ *
+ * Content elements keep the `class` and `id` an author gave them, so class/id
+ * CSS (e.g. a scoped author <style> block) can target the document. Values that
+ * collide with the editor's own internal names are dropped so content can never
+ * impersonate or restyle the chrome; the editor's own classes (emitted in
+ * toDOM) are always preserved and merged with the author's.
+ * ------------------------------------------------------------------------- */
+
+const RESERVED_NAME = /^(?:nile-wysiwyg|ProseMirror)/;
+
+export function cleanClass(value: string | null): string | null {
+  if (!value) return null;
+  const kept = value.split(/\s+/).filter(token => token && !RESERVED_NAME.test(token));
+  return kept.length ? kept.join(' ') : null;
+}
+
+export function cleanId(value: string | null): string | null {
+  return value && !RESERVED_NAME.test(value) ? value : null;
+}
+
+const HTML_ATTR_SPEC = { htmlClass: { default: null }, htmlId: { default: null } };
+
+function readHtmlAttrs(dom: HTMLElement): { htmlClass: string | null; htmlId: string | null } {
+  return {
+    htmlClass: cleanClass(dom.getAttribute('class')),
+    htmlId: cleanId(dom.getAttribute('id')),
+  };
+}
+
+/** Wraps a tag-based parse rule so it also captures author class/id. Rules
+ * keyed by `style` (whose getAttrs receives a value string, not an element)
+ * pass through untouched. */
+function augmentParseRule(rule: ParseRule): ParseRule {
+  if (!('tag' in rule) || 'style' in rule) return rule;
+  const inner = rule.getAttrs;
+  return {
+    ...rule,
+    getAttrs(dom: HTMLElement) {
+      const base = inner ? inner(dom) : null;
+      if (base === false) return false;
+      return { ...(base ?? {}), ...readHtmlAttrs(dom) };
+    },
+  } as ParseRule;
+}
+
+/** Wraps a toDOM so stored class/id are written back onto the element, merged
+ * with any class the spec emits itself. Handles the `[tag]`, `[tag, attrs]`,
+ * `[tag, 0]`, and `[tag, attrs, …children]` output shapes. */
+function augmentToDOM(
+  toDOM?: (node: { attrs: Attrs }, ...rest: unknown[]) => DOMOutputSpec
+): ((node: { attrs: Attrs }, ...rest: unknown[]) => DOMOutputSpec) | undefined {
+  if (!toDOM) return toDOM;
+  return (node, ...rest) => {
+    const out = toDOM(node, ...rest);
+    const cls = node.attrs.htmlClass as string | null;
+    const id = node.attrs.htmlId as string | null;
+    if (!Array.isArray(out) || (!cls && !id)) return out;
+    const [tag, ...tail] = out as unknown[];
+    let attrs: Record<string, unknown> = {};
+    let children = tail;
+    if (tail.length && tail[0] && typeof tail[0] === 'object' && !Array.isArray(tail[0])) {
+      attrs = { ...(tail[0] as Record<string, unknown>) };
+      children = tail.slice(1);
+    }
+    if (cls) attrs.class = attrs.class ? `${attrs.class as string} ${cls}` : cls;
+    if (id) attrs.id = id;
+    return [tag, attrs, ...children] as DOMOutputSpec;
+  };
+}
+
+/** Adds `htmlClass`/`htmlId` attrs plus parse/serialize support to a spec. */
+function withHtmlAttrs<S extends NodeSpec | MarkSpec>(spec: S): S {
+  return {
+    ...spec,
+    attrs: { ...(spec.attrs ?? {}), ...HTML_ATTR_SPEC },
+    parseDOM: spec.parseDOM?.map(augmentParseRule),
+    toDOM: augmentToDOM(spec.toDOM as never) as never,
+  };
+}
+
+/** Content nodes/marks that carry author class/id. Excludes structural leaves
+ * (doc, text), atoms with bespoke DOM (image, embeds, mentions, math, …) and
+ * style-only marks (their spans are covered by `html_span`). */
+const HTML_ATTR_NODES = [
+  'paragraph', 'heading', 'blockquote', 'code_block',
+  'bullet_list', 'ordered_list', 'list_item',
+  'table', 'table_row', 'table_cell', 'table_header',
+];
+const HTML_ATTR_MARKS = [
+  'link', 'bold', 'italic', 'underline', 'strike', 'code', 'subscript', 'superscript',
+];
+
 /**
  * Block nodes. `align` is modeled as an attribute on textblocks rather than a
  * wrapper node so alignment survives block-type changes (heading <-> paragraph).
@@ -368,6 +463,8 @@ const nodes: Record<string, NodeSpec> = {
         frameborder: '0',
         allowfullscreen: 'true',
         allow: 'accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture',
+        sandbox: EMBED_SANDBOX,
+        referrerpolicy: EMBED_REFERRER_POLICY,
       };
       if (title) iframeAttrs.title = title;
       const wrapperAttrs: Record<string, string> = {
@@ -389,6 +486,29 @@ const nodes: Record<string, NodeSpec> = {
     },
   },
 
+  /**
+   * Author-supplied `<style>` block, entered via the HTML source view. The CSS
+   * is sanitized on the way in (see sanitizeCss) — `@import`, `expression()`
+   * and external `url()` are neutralized — then stored verbatim and serialized
+   * straight back to a `<style>` element. A node view renders it live in the
+   * editor with a small chip so the otherwise-invisible block stays selectable.
+   */
+  styleBlock: {
+    group: 'block',
+    atom: true,
+    selectable: true,
+    attrs: { css: { default: '' } },
+    parseDOM: [
+      {
+        tag: 'style',
+        getAttrs: (dom: HTMLElement) => ({ css: dom.textContent ?? '' }),
+      },
+    ],
+    toDOM(node) {
+      return ['style', node.attrs.css];
+    },
+  },
+
   /**
    * Bookmark: a named in-text anchor (`<a id="…">`) for intra-document
    * navigation. Invisible in serialized output; the editor draws a flag
@@ -705,6 +825,30 @@ const marks: Record<string, MarkSpec> = {
     },
   },
 
+  /** Carries an author `class`/`id` on an inline `<span>` that has no other
+   * meaning, so class/id CSS can target runs of text. Low priority so styled
+   * spans (color/font marks) and atom spans (mention/merge/math) win. */
+  html_span: {
+    attrs: { htmlClass: { default: null }, htmlId: { default: null } },
+    parseDOM: [
+      {
+        tag: 'span',
+        priority: 5,
+        getAttrs: (dom: HTMLElement) => {
+          const htmlClass = cleanClass(dom.getAttribute('class'));
+          const htmlId = cleanId(dom.getAttribute('id'));
+          return htmlClass || htmlId ? { htmlClass, htmlId } : false;
+        },
+      },
+    ],
+    toDOM(mark) {
+      const attrs: Record<string, string> = {};
+      if (mark.attrs.htmlClass) attrs.class = mark.attrs.htmlClass;
+      if (mark.attrs.htmlId) attrs.id = mark.attrs.htmlId;
+      return ['span', attrs, 0];
+    },
+  },
+
   text_color: {
     attrs: { color: {} },
     parseDOM: [
@@ -843,16 +987,23 @@ const orderedListSpec: NodeSpec = {
 
 /** Builds the editor schema. List nodes are added via prosemirror-schema-list. */
 export function createSchema(): Schema {
-  const nodeMap = addListNodes(
-    OrderedMap.from(nodes),
-    'paragraph block*',
-    'block'
-  )
+  let nodeMap = addListNodes(OrderedMap.from(nodes), 'paragraph block*', 'block')
     .update('bullet_list', bulletListSpec)
     .update('ordered_list', orderedListSpec)
     .append(tableNodeSpecs)
     .update('table', tableSpec);
-  return new Schema({ nodes: nodeMap, marks: OrderedMap.from(marks) });
+  // Thread author class/id through the content nodes and marks (applied last so
+  // it also wraps the list/table specs pulled in from external packages).
+  for (const name of HTML_ATTR_NODES) {
+    const spec = nodeMap.get(name);
+    if (spec) nodeMap = nodeMap.update(name, withHtmlAttrs(spec));
+  }
+  let markMap = OrderedMap.from<MarkSpec>(marks);
+  for (const name of HTML_ATTR_MARKS) {
+    const spec = markMap.get(name);
+    if (spec) markMap = markMap.update(name, withHtmlAttrs(spec));
+  }
+  return new Schema({ nodes: nodeMap, marks: markMap });
 }
 
 /** A shared default schema instance. */

package/src/nile-wysiwyg-editor/index.ts

@@ -1,3 +1,8 @@
 export { NileWysiwygEditor, default } from './nile-wysiwyg-editor';
+export { NileWysiwygToolbarItem } from './nile-wysiwyg-toolbar/nile-wysiwyg-toolbar-item';
+export { NileWysiwygBubbleItem } from './ui/bubble-item';
+export type { AuthoredToolbarItem } from './nile-wysiwyg-toolbar/nile-wysiwyg-toolbar';
 export type { WysiwygChangeDetail, WysiwygCommandDetail, ToolbarConfig } from './types';
 export { DEFAULT_TOOLBAR } from './types';
+export { createKatexRenderer } from './math/katex-renderer';
+export type { KatexLike, KatexRendererOptions } from './math/katex-renderer';

package/src/nile-wysiwyg-editor/math/katex-renderer.ts

@@ -0,0 +1,59 @@
+import type { MathRenderer } from '../engine/plugins/math-view';
+
+/**
+ * The slice of the KaTeX module this helper needs. Declared locally so the
+ * design system never imports `katex` itself — you bundle KaTeX from your own
+ * app's install and pass the instance in.
+ */
+export interface KatexLike {
+  renderToString(latex: string, options?: Record<string, unknown>): string;
+}
+
+export interface KatexRendererOptions {
+  /**
+   * Extra options merged into every `katex.renderToString` call (after the
+   * `displayMode` / `throwOnError` defaults). See the KaTeX options reference.
+   */
+  katexOptions?: Record<string, unknown>;
+}
+
+/**
+ * Builds a {@link MathRenderer} backed by KaTeX for the editor's `mathRenderer`
+ * property. KaTeX is **not** bundled by the design system — install it in your
+ * app and hand the instance to this helper so your bundler ships it (no CDN):
+ *
+ * ```ts
+ * import katex from 'katex';
+ * import 'katex/dist/katex.min.css';
+ * import { createKatexRenderer } from '@aquera/nile-elements';
+ *
+ * editor.mathRenderer = createKatexRenderer(katex);
+ * // or with overrides:
+ * editor.mathRenderer = createKatexRenderer(katex, {
+ *   katexOptions: { macros: { '\\RR': '\\mathbb{R}' } },
+ * });
+ * ```
+ *
+ * Called with no instance it falls back to a global `katex` (e.g. a CDN
+ * `<script>`), which is handy for quick demos. If no engine is available at
+ * render time the raw LaTeX is returned, so content stays visible.
+ */
+export function createKatexRenderer(
+  katex?: KatexLike,
+  options: KatexRendererOptions = {}
+): MathRenderer {
+  return (latex, display) => {
+    const engine = katex ?? (globalThis as { katex?: KatexLike }).katex;
+    if (!engine) return latex;
+    try {
+      return engine.renderToString(latex, {
+        displayMode: display === 'block',
+        throwOnError: false,
+        ...options.katexOptions,
+      });
+    } catch {
+      // Malformed LaTeX (with throwOnError overridden true, say) → show source.
+      return latex;
+    }
+  };
+}

package/src/nile-wysiwyg-editor/math/katex.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Minimal ambient types for KaTeX — the package ships no declarations and we
+ * only use `renderToString`. Keeps the built-in MathML renderer in
+ * `engine/plugins/math-view.ts` type-safe without pulling in @types/katex.
+ */
+declare module 'katex' {
+  interface KatexOptions {
+    displayMode?: boolean;
+    output?: 'html' | 'mathml' | 'htmlAndMathml';
+    throwOnError?: boolean;
+    [option: string]: unknown;
+  }
+  const katex: {
+    renderToString(tex: string, options?: KatexOptions): string;
+  };
+  export default katex;
+}

package/src/nile-wysiwyg-editor/nile-wysiwyg-editor.css.ts

@@ -292,8 +292,10 @@ export const styles = css`
     text-align: left;
   }
 
-  .ProseMirror td > :last-child,
-  .ProseMirror th > :last-child {
+ 
+  .ProseMirror td > *,
+  .ProseMirror th > * {
+    margin-top: 0;
     margin-bottom: 0;
   }
 
@@ -605,11 +607,28 @@ export const styles = css`
     font-weight: 600;
   }
 
-  /* --- Sticky toolbar --- */
+  /* --- Author <style> block (from HTML source) ---
+     Applied live by StyleBlockView (a hidden <style> host, scoped to the
+     content); the block renders nothing in the editor. */
+  .nile-wysiwyg__style-block {
+    display: none;
+  }
+
+  /* --- Sticky toolbar ---
+     Pins to the top of the scroll container. Note: sticky anchors to the
+     container's PADDING box, so if the scroll container has top padding, a
+     band of content shows above the toolbar — set --nile-wysiwyg-sticky-top
+     (or remove the container's top padding) to compensate. The opaque
+     background makes the pinned bar self-backing so content can never bleed
+     through it. */
   :host([sticky-toolbar]) nile-wysiwyg-toolbar {
     position: sticky;
     top: var(--nile-wysiwyg-sticky-top, 0);
     z-index: 12;
+    background: var(
+      --nile-wysiwyg-bg,
+      var(--nile-colors-white-base, var(--ng-colors-bg-primary, #ffffff))
+    );
   }
 
   /* --- Mentions & suggestions --- */

package/src/nile-wysiwyg-editor/nile-wysiwyg-editor.test.ts

@@ -381,9 +381,12 @@ describe('nile-wysiwyg-editor', () => {
     const source = el.shadowRoot!.querySelector('nile-wysiwyg-source-view')!;
     expect(source).to.exist;
     await source.updateComplete;
-    expect(source.textarea!.value).to.equal('<p>original</p>');
+    expect(source.currentValue).to.equal('<p>original</p>');
 
-    source.textarea!.value = '<p>edited</p><script>alert(1)</script>';
+    // Simulate editing the textarea (its input event drives the draft).
+    const textarea = source.shadowRoot!.querySelector('textarea')!;
+    textarea.value = '<p>edited</p><script>alert(1)</script>';
+    textarea.dispatchEvent(new Event('input'));
     el.toggleSourceView();
     await el.updateComplete;
     expect(el.shadowRoot!.querySelector('nile-wysiwyg-source-view')).to.not.exist;

package/src/nile-wysiwyg-editor/nile-wysiwyg-editor.ts

@@ -30,6 +30,7 @@ import {
   ImageView,
   FigureView,
   EmbedView,
+  StyleBlockView,
   MathView,
   isOfficeHtml,
   cleanOfficeHtml,
@@ -64,8 +65,11 @@ import { DEFAULT_TOOLBAR } from './types';
 import { EMOJI } from './emoji';
 
 import './nile-wysiwyg-toolbar/nile-wysiwyg-toolbar';
+import './nile-wysiwyg-toolbar/nile-wysiwyg-toolbar-item';
+import type { AuthoredToolbarItem } from './nile-wysiwyg-toolbar/nile-wysiwyg-toolbar';
 import './ui/link-editor';
 import './ui/bubble-menu';
+import './ui/bubble-item';
 import './ui/image-panel';
 import './ui/table-menu';
 import './ui/suggest-list';
@@ -177,6 +181,22 @@ export class NileWysiwygEditor extends NileElement {
   /** Toolbar config string; `"none"` hides the toolbar. */
   @property({ type: String }) toolbar = DEFAULT_TOOLBAR;
 
+  /**
+   * Toolbar built from authored `<nile-wysiwyg-toolbar-item>` light-DOM
+   * children. When present it takes precedence over the `toolbar` string.
+   */
+  @state() private authoredToolbar?: AuthoredToolbarItem[];
+
+  /**
+   * Bubble menu built from authored `<nile-wysiwyg-bubble-item>` light-DOM
+   * children. When present it replaces the built-in bold/italic/underline/
+   * strike/link set.
+   */
+  @state() private authoredBubble?: AuthoredToolbarItem[];
+
+  /** Watches authored toolbar/bubble children so edits re-render them. */
+  private toolbarObserver?: MutationObserver;
+
   /** Shows a balloon toolbar over text selections. */
   @property({ type: Boolean, attribute: 'bubble-menu' }) bubbleMenu = false;
 
@@ -459,11 +479,34 @@ export class NileWysiwygEditor extends NileElement {
     }
     // Close floating panels when the user clicks anywhere outside them.
     document.addEventListener('pointerdown', this.onOutsidePointerDown, true);
+    // Format painter applies on pointer release so a drag-selection is painted
+    // whole, not on the first mid-drag selection change.
+    document.addEventListener('mouseup', this.onPainterPointerUp);
+
+    // Discover an author-supplied toolbar / bubble menu (light-DOM
+    // <nile-wysiwyg-toolbar-item> / <nile-wysiwyg-bubble-item> children) and
+    // keep them in sync as they change.
+    this.syncAuthoredToolbar();
+    this.syncAuthoredBubble();
+    if (!this.toolbarObserver) {
+      this.toolbarObserver = new MutationObserver(() => {
+        this.syncAuthoredToolbar();
+        this.syncAuthoredBubble();
+      });
+    }
+    this.toolbarObserver.observe(this, {
+      childList: true,
+      subtree: true,
+      attributes: true,
+      attributeFilter: ['name', 'label', 'icon', 'divider', 'overflow'],
+    });
   }
 
   disconnectedCallback(): void {
     super.disconnectedCallback();
     document.removeEventListener('pointerdown', this.onOutsidePointerDown, true);
+    document.removeEventListener('mouseup', this.onPainterPointerUp);
+    this.toolbarObserver?.disconnect();
     if (this.changeTimer) clearTimeout(this.changeTimer);
     if (this.autosaveTimer) clearInterval(this.autosaveTimer);
     if (this.previousBodyOverflow !== null) {
@@ -476,9 +519,57 @@ export class NileWysiwygEditor extends NileElement {
 
   protected firstUpdated(): void {
     this.defaultValue = this.value;
+    // Re-read now that light-DOM children are guaranteed parsed (the initial
+    // connectedCallback read can run mid-parse before children exist).
+    this.syncAuthoredToolbar();
+    this.syncAuthoredBubble();
     this.mountView();
   }
 
+  /**
+   * Reads `<nile-wysiwyg-toolbar-item>` children into a structured toolbar and
+   * stores it on {@link authoredToolbar}. Absent items clear the override
+   * (falling back to the `toolbar` string). No-ops when nothing changed to
+   * avoid needless re-renders.
+   */
+  private syncAuthoredToolbar(): void {
+    const nodes = this.querySelectorAll('nile-wysiwyg-toolbar-item');
+    const next: AuthoredToolbarItem[] | undefined = nodes.length
+      ? Array.from(nodes)
+          .map(el => ({
+            name: el.hasAttribute('divider') ? '|' : el.getAttribute('name') || '',
+            label: el.getAttribute('label') || undefined,
+            icon: el.getAttribute('icon') || undefined,
+            overflow: el.hasAttribute('overflow') || undefined,
+          }))
+          .filter(item => item.name)
+      : undefined;
+    if (JSON.stringify(next) !== JSON.stringify(this.authoredToolbar)) {
+      this.authoredToolbar = next;
+    }
+  }
+
+  /**
+   * Reads `<nile-wysiwyg-bubble-item>` children into a structured bubble-menu
+   * item list stored on {@link authoredBubble}. Absent items clear the override
+   * (falling back to the built-in default). No-ops when nothing changed.
+   */
+  private syncAuthoredBubble(): void {
+    const nodes = this.querySelectorAll('nile-wysiwyg-bubble-item');
+    const next: AuthoredToolbarItem[] | undefined = nodes.length
+      ? Array.from(nodes)
+          .map(el => ({
+            name: el.hasAttribute('divider') ? '|' : el.getAttribute('name') || '',
+            label: el.getAttribute('label') || undefined,
+            icon: el.getAttribute('icon') || undefined,
+          }))
+          .filter(item => item.name)
+      : undefined;
+    if (JSON.stringify(next) !== JSON.stringify(this.authoredBubble)) {
+      this.authoredBubble = next;
+    }
+  }
+
   protected updated(changed: PropertyValues): void {
     if (changed.has('value') && this.view && !this.syncingValue) {
       const current = docToHtml(this.view.state.doc);
@@ -654,23 +745,60 @@ export class NileWysiwygEditor extends NileElement {
           new FigureView(node, view, getPos as () => number | undefined),
         embed: (node, view, getPos) =>
           new EmbedView(node, view, getPos as () => number | undefined),
+        styleBlock: node => new StyleBlockView(node),
         math: node => new MathView(node, this.mathRenderer),
       },
     });
 
+    this.view.dom.addEventListener('mousedown', this.onPainterPointerDown);
+
     this.toolbarState = this.snapshotToolbar(this.view.state);
     this.counter = countWords(this.view.state.doc);
     this.syncFormValue(this.view.state.doc);
   }
 
+  /**
+   * True while a drag-selection is in progress with the format painter armed.
+   * Suppresses the mid-drag auto-apply in {@link handleTransaction} so the
+   * copied formatting lands on the final, complete selection (on mouse-up).
+   */
+  private painterDragActive = false;
+
+  private onPainterPointerDown = (): void => {
+    if (this.view && isFormatPainterArmed(this.view.state)) {
+      this.painterDragActive = true;
+    }
+  };
+
+  private onPainterPointerUp = (): void => {
+    if (!this.painterDragActive) return;
+    this.painterDragActive = false;
+    // Defer a frame so ProseMirror has synced the final DOM selection.
+    requestAnimationFrame(() => {
+      if (!this.view) return;
+      if (this.view.state.selection.empty || !isFormatPainterArmed(this.view.state)) return;
+      const applyTr = applyFormatPainter(this.view.state);
+      if (applyTr) this.view.dispatch(applyTr);
+    });
+  };
+
   private handleTransaction(tr: Transaction): void {
     if (!this.view) return;
     const newState = this.view.state.apply(tr);
     this.view.updateState(newState);
 
     // Format painter: once armed, the next non-empty selection the user makes
-    // receives the copied formatting, then the painter disarms.
-    if (tr.selectionSet && !newState.selection.empty && isFormatPainterArmed(newState)) {
+    // receives the copied formatting, then the painter disarms. While a pointer
+    // drag is building the selection we defer to the mouse-up handler
+    // (onPainterPointerUp) so the whole range is painted, not just the first
+    // mid-drag character. Single-shot selections (double-click, Shift+End,
+    // programmatic) still apply here.
+    if (
+      tr.selectionSet &&
+      !newState.selection.empty &&
+      isFormatPainterArmed(newState) &&
+      !this.painterDragActive
+    ) {
       const applyTr = applyFormatPainter(newState);
       if (applyTr) {
         this.view.dispatch(applyTr);
@@ -1389,7 +1517,7 @@ export class NileWysiwygEditor extends NileElement {
   /** Toggles raw-HTML source editing. Content re-sanitizes on the way back. */
   public toggleSourceView(): void {
     if (this.sourceMode) {
-      this.applySourceView(this.sourceViewEl?.textarea?.value ?? null);
+      this.applySourceView(this.sourceViewEl?.currentValue ?? null);
     } else {
       this.sourceMode = true;
       this.updateComplete.then(() => {
@@ -1924,7 +2052,13 @@ export class NileWysiwygEditor extends NileElement {
   };
 
   public render(): TemplateResult {
-    const showToolbar = this.toolbar !== 'none' && !this.readonly && !this.sourceMode;
+    const hasAuthoredToolbar = (this.authoredToolbar?.length ?? 0) > 0;
+    // Keep the toolbar mounted in source mode too, so the main menu stays put
+    // above the split source/preview view instead of being replaced by it. It
+    // is disabled there — formatting commands would target the hidden rich-text
+    // view — and the source view's own Cancel/Done bar handles exiting.
+    const showToolbar =
+      (this.toolbar !== 'none' || hasAuthoredToolbar) && !this.readonly;
     return html`
       <div
         class="nile-wysiwyg ${this.showBlocks ? 'nile-wysiwyg--show-blocks' : ''}"
@@ -1937,9 +2071,10 @@ export class NileWysiwygEditor extends NileElement {
           ? html`
               <nile-wysiwyg-toolbar
                 part="toolbar"
-                exportparts="button, select, color"
+                exportparts="button, select, color, overflow, overflow-panel"
                 config=${this.toolbar}
-                ?disabled=${this.disabled}
+                .items=${this.authoredToolbar}
+                ?disabled=${this.disabled || this.sourceMode}
                 .toolbarState=${this.toolbarState}
               ></nile-wysiwyg-toolbar>
             `
@@ -1984,7 +2119,7 @@ export class NileWysiwygEditor extends NileElement {
             this.closeShortcutHelp();
           }}
         ></nile-wysiwyg-shortcut-help>
-        <nile-wysiwyg-bubble-menu></nile-wysiwyg-bubble-menu>
+        <nile-wysiwyg-bubble-menu .items=${this.authoredBubble}></nile-wysiwyg-bubble-menu>
         <nile-wysiwyg-table-menu></nile-wysiwyg-table-menu>
         <nile-wysiwyg-code-menu></nile-wysiwyg-code-menu>
         <nile-wysiwyg-image-menu></nile-wysiwyg-image-menu>

package/src/nile-wysiwyg-editor/nile-wysiwyg-toolbar/index.ts

@@ -1 +1,3 @@
 export { NileWysiwygToolbar } from './nile-wysiwyg-toolbar';
+export type { AuthoredToolbarItem } from './nile-wysiwyg-toolbar';
+export { NileWysiwygToolbarItem } from './nile-wysiwyg-toolbar-item';

package/src/nile-wysiwyg-editor/nile-wysiwyg-toolbar/nile-wysiwyg-toolbar-item.ts

@@ -0,0 +1,68 @@
+import { LitElement } from 'lit';
+import { customElement, property } from 'lit/decorators.js';
+
+/**
+ * Declarative, light-DOM marker for a single toolbar control.
+ *
+ * Author these inside a `<nile-wysiwyg-toolbar>` container within a
+ * `<nile-wysiwyg-editor>` to build the toolbar by hand instead of (or in
+ * addition to) the `toolbar` config string:
+ *
+ * ```html
+ * <nile-wysiwyg-editor>
+ *   <nile-wysiwyg-toolbar>
+ *     <nile-wysiwyg-toolbar-item name="bold" label="Bold"></nile-wysiwyg-toolbar-item>
+ *     <nile-wysiwyg-toolbar-item name="italic"></nile-wysiwyg-toolbar-item>
+ *     <nile-wysiwyg-toolbar-item divider></nile-wysiwyg-toolbar-item>
+ *     <nile-wysiwyg-toolbar-item name="heading"></nile-wysiwyg-toolbar-item>
+ *     <!-- goes into the 3-dot "more" menu, wherever it sits in the list -->
+ *     <nile-wysiwyg-toolbar-item name="sourceView" overflow></nile-wysiwyg-toolbar-item>
+ *   </nile-wysiwyg-toolbar>
+ * </nile-wysiwyg-editor>
+ * ```
+ *
+ * The container is optional — items may also be direct children of the editor.
+ *
+ * `name` maps to a built-in control (the same keys the `toolbar` string
+ * accepts, e.g. `bold`, `italic`, `heading`, `textColor`, `table`). `label`
+ * and `icon` override that control's built-in tooltip/glyph; set `divider` to
+ * insert a group separator, or `overflow` to tuck this control into the
+ * toolbar's collapsible 3-dot "more" menu.
+ *
+ * The element renders nothing itself — the editor discovers it and renders the
+ * real control inside its own shadow DOM.
+ *
+ * @tag nile-wysiwyg-toolbar-item
+ */
+@customElement('nile-wysiwyg-toolbar-item')
+export class NileWysiwygToolbarItem extends LitElement {
+  protected createRenderRoot(): this {
+    return this;
+  }
+  protected shouldUpdate(): boolean {
+    return false;
+  }
+
+  /** Built-in control name — same keys accepted by the `toolbar` string. */
+  @property({ type: String, reflect: true }) name = '';
+
+  /** Overrides the control's tooltip / accessible label. */
+  @property({ type: String, reflect: true }) label = '';
+
+  /** Overrides the control's glyph (a `nile-glyph` name). */
+  @property({ type: String, reflect: true }) icon = '';
+
+  /** Renders a group divider instead of a control. */
+  @property({ type: Boolean, reflect: true }) divider = false;
+
+  /** When set, this control is tucked into the toolbar's collapsible 3-dot
+   * "more" menu instead of the main bar — regardless of where it sits among
+   * the items. */
+  @property({ type: Boolean, reflect: true }) overflow = false;
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'nile-wysiwyg-toolbar-item': NileWysiwygToolbarItem;
+  }
+}