@maildeno/editor 0.1.3 → 0.4.2

package/dist/theme.d.ts

@@ -3,20 +3,41 @@
  *
  * Setting variables rather than regenerating a stylesheet is what makes this
  * work in the custom-element build: the bundled shadow-root CSS is static and
- * cannot be re-emitted at runtime, but a custom property set on the host
- * cascades into the shadow tree and updates every rule reading it, live.
+ * cannot be re-emitted at runtime, but a custom property set on the editor
+ * root cascades into the whole subtree and updates every rule reading it,
+ * live.
  */
 /**
  * Every themeable token.
  *
  * Two layers, deliberately. Core tokens (`primary`, `surface`, `text`, …)
  * re-theme the whole editor coherently. Semantic tokens (`headerBg`,
- * `inputBg`, `overlayBg`, …) default to the core ones and exist for hosts
+ * `overlayBg`, `toolbarBg`, …) default to the core ones and exist for hosts
  * that want to change one surface without redefining everything else.
  *
  * Anything left out keeps its default, so a partial theme is always coherent
  * rather than half-applied — setting only `primary` cannot produce unreadable
  * text, and setting only `headerBg` cannot leave the rest inconsistent.
+ *
+ * ── Every token here is read by something ───────────────────────────────────
+ * Twenty-one used to be listed that nothing in the package consumed:
+ * `ring`, the four `input*` tokens, `primarySoft*`, `primaryBorder`,
+ * `onPrimarySoft`, `onAccentSoft`, `inverseSurfaceHover`, `borderSubtle`,
+ * `surfaceSunken`, `shadowSm`, `shadowLg`, the four `code*` tokens and the two
+ * `skeleton*` tokens. They had CSS defaults, they type-checked, they appeared
+ * in the docs — and setting any of them did nothing, because no rule ever read
+ * the variable.
+ *
+ * The `input*` four are the ones worth knowing about: inputs are styled from
+ * `surface` / `border` / `text` / `textSubtle` directly, in the scoped CSS of
+ * InputText.vue, Select.vue and DatePicker.vue. The dark palette's "a field
+ * darker than its panel reads as an input" intent was never realised. Removing
+ * them changes nothing on screen — they were already inert — but it stops the
+ * type surface promising a control the editor does not offer. Wiring them up
+ * instead is three small scoped-CSS edits, if that look is wanted.
+ *
+ * `codeBg` and friends belong to the host dashboard's own CodeBlock component,
+ * never to the editor, which renders no code panels at all.
  */
 export interface ThemeTokens {
     /** Brand/accent colour. Drives the primary button, focus rings, selection. */
@@ -27,13 +48,16 @@ export interface ThemeTokens {
     onPrimary?: string;
     /** Page background behind the canvas. */
     background?: string;
-    /** Panels, header, toolbars, popovers. */
+    /** Panels, header, toolbars, popovers — and, because inputs read it
+     *  directly, field backgrounds. */
     surface?: string;
     /** Subtle fills — inactive tabs, secondary buttons. */
     surfaceMuted?: string;
+    /** Hover fill, and the background of a disabled input. */
     surfaceHover?: string;
     text?: string;
     textMuted?: string;
+    /** Also the input placeholder colour. */
     textSubtle?: string;
     border?: string;
     borderStrong?: string;
@@ -42,9 +66,7 @@ export interface ThemeTokens {
     success?: string;
     warning?: string;
     info?: string;
-    /** Focus ring colour. Defaults to `primary`. */
-    ring?: string;
-    /** Box-shadow used by popovers and dialogs. */
+    /** Box-shadow used by popovers and dialogs. Feeds `overlayShadow`. */
     shadow?: string;
     /** Backdrop behind modal dialogs. */
     scrim?: string;
@@ -58,10 +80,6 @@ export interface ThemeTokens {
     accentBg?: string;
     accentText?: string;
     canvasBg?: string;
-    inputBg?: string;
-    inputText?: string;
-    inputBorder?: string;
-    inputPlaceholder?: string;
     /** Dialogs, toasts, dropdowns, date picker and floating toolbars. */
     overlayBg?: string;
     overlayText?: string;
@@ -83,7 +101,7 @@ export interface ThemeTokens {
     /** Same role as `selection`, one level up: row outlines, the row's
      *  floating toolbar, and "this is a row" indicators in the Layout tab
      *  and Layers panel. Separate token so components and rows can be told
-     *  apart at a glance */
+     *  apart at a glance. */
     rowSelection?: string;
     rowSelectionBg?: string;
     rowSelectionFg?: string;
@@ -112,15 +130,34 @@ export interface ThemeTokens {
     dangerBg?: string;
     dangerFg?: string;
     dangerBorder?: string;
+    /** The dark pill — primary CTA, active tab. FLIPS to a light fill in dark
+     *  mode. Use this, not `text`, for any dark-filled control: a text token
+     *  cannot invert that way without making body copy invisible. */
+    inverseSurface?: string;
+    onInverse?: string;
+    onInverseMuted?: string;
+    /** Secondary signal, distinct from `primary`. Used for AI surfaces and the
+     *  row-selection family. */
+    accent?: string;
+    accentHover?: string;
+    onAccent?: string;
+    accentSoft?: string;
+    accentBorder?: string;
 }
 export interface ThemeOptions extends ThemeTokens {
     /** Tokens applied only in light mode. */
     light?: ThemeTokens;
     /**
-     * Tokens applied only when the editor has the `dark` class.
+     * Tokens applied only when the editor is in dark mode.
      *
      * Dark mode has its own complete set of defaults, so overriding a couple of
      * tokens here is enough — you do not have to restate a whole palette.
+     *
+     * "In dark mode" means the editor root carries the `dark` class, which
+     * useColorScheme.ts puts there by mirroring the host page's own `.dark` on
+     * <html> or <body>. A host with a working theme switcher needs no wiring;
+     * one whose switcher works some other way passes `colorMode` to
+     * <EmailEditor> instead.
      */
     dark?: ThemeTokens;
     /** @deprecated Use `primary`. */
@@ -139,10 +176,24 @@ export interface ThemeOptions extends ThemeTokens {
  * });
  * ```
  *
- * @param target For the plain Vue build, omit — defaults to
- *   `document.documentElement`. For the custom-element build, pass the
- *   `<maildeno-editor>` element, so the properties cascade into its shadow
- *   tree. `handle.setTheme()` does this for you.
+ * @param target Where the tokens are declared. **This must be the editor's own
+ *   root element**, and <EmailEditor> passes it for you — the default below is
+ *   only for callers driving the CSS variables by hand, with no editor
+ *   mounted.
+ *
+ *   Why it matters: the library build runs every injected stylesheet through
+ *   scopeInjectedCss.ts, which rewrites `:root`/`:host` to `.md-editor-scope`
+ *   so the editor's CSS cannot restyle the host page. That puts the package's
+ *   default tokens *directly on the editor root div*. A custom property
+ *   declared on an element beats any value inherited from an ancestor,
+ *   whatever the specificity — so a theme written to <html> is shadowed by the
+ *   defaults and never reaches the editor at all. Writing to the same element
+ *   the defaults land on puts the two in the same cascade, where the runtime
+ *   sheet wins on source order.
+ *
+ *   This is also why theming appeared to work when running from source (the
+ *   playground aliases straight to `src` and never runs the scoper, so `:root`
+ *   stays `:root`) and silently did nothing in a consuming app.
  */
 export declare function setEditorTheme(options: ThemeOptions, target?: HTMLElement): void;
 /**

package/dist/types/assistant.d.ts

@@ -0,0 +1,56 @@
+/**
+ * The canvas API handed to a host-supplied assistant panel.
+ *
+ * Defined once here rather than inline in each place it appears, because it
+ * shows up in three: the #assistant slot's prop, assistant.mount()'s second
+ * argument, and EditorHandle. Three structural copies would drift the first
+ * time a method is added, and the drift would be silent — a slot typed with
+ * five methods and a callback typed with four both compile fine.
+ *
+ * A read/write subset of what EmailEditor exposes, not the whole surface.
+ * An assistant needs to see the canvas, change it, and know when it moved.
+ * It has no business calling destroy() or re-theming the editor, so those
+ * are absent rather than present-and-discouraged.
+ */
+export interface EditorWriteApi {
+    /** Current template as a plain object, or null when the canvas is empty. */
+    getJson(): Record<string, unknown> | null;
+    /**
+     * Replaces the canvas. Accepts what getJson() returns.
+     *
+     * Defaults to an undoable step, which is almost always what an assistant
+     * wants: a user who dislikes a generated design presses Ctrl+Z and has
+     * their own work back. Passing "reset" throws that away, so it is for
+     * document swaps rather than edits.
+     */
+    setJson(data: unknown, opts?: {
+        history?: "undoable" | "reset";
+    }): void;
+    /** The selected block, or null. `type` is the block type ("paragraph",
+     *  "image"), which is what a "rewrite this heading" flow branches on. */
+    getSelection(): {
+        id: string;
+        type: string | null;
+    } | null;
+    /** Selects by id, or clears with null. False if no block has that id. */
+    setSelection(id: string | null): boolean;
+    /** Runs after each committed change. Returns an unsubscribe function —
+     *  call it when the panel tears down, or the callback outlives the panel
+     *  and fires against a dead component. */
+    onChange(cb: () => void): () => void;
+}
+/**
+ * How an init()/custom-element host fills the assistant drawer.
+ *
+ * Imperative rather than a component, because that path has no framework in
+ * common with the editor — a React host renders with createRoot into the
+ * element, a vanilla host sets innerHTML, and neither should need to know
+ * Vue exists.
+ */
+export interface AssistantMount {
+    /** Called on first open, with the drawer's body element. */
+    mount: (el: HTMLElement, editor: EditorWriteApi) => void;
+    /** Called on close and on editor teardown. Tear down listeners and any
+     *  framework root here; the editor only empties the element after this. */
+    unmount?: (el: HTMLElement) => void;
+}