@boxcc/maildeno-editor 0.0.0-stage → 0.4.14

package/dist/theme.d.ts

@@ -0,0 +1,206 @@
+/**
+ * Theming via CSS custom properties.
+ *
+ * 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 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`,
+ * `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. */
+    primary?: string;
+    primaryHover?: string;
+    /** Text/icon colour on top of `primary`. Set this when using a light brand
+     *  colour, or the primary button's label will be unreadable. */
+    onPrimary?: string;
+    /** Page background behind the canvas. */
+    background?: string;
+    /** 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;
+    danger?: string;
+    onDanger?: string;
+    success?: string;
+    warning?: string;
+    info?: string;
+    /** Box-shadow used by popovers and dialogs. Feeds `overlayShadow`. */
+    shadow?: string;
+    /** Backdrop behind modal dialogs. */
+    scrim?: string;
+    headerBg?: string;
+    headerText?: string;
+    headerBorder?: string;
+    sidebarBg?: string;
+    sidebarText?: string;
+    sidebarBorder?: string;
+    /** Selected tab / segmented-control fill. Defaults to `primary`. */
+    accentBg?: string;
+    accentText?: string;
+    canvasBg?: string;
+    /** Dialogs, toasts, dropdowns, date picker and floating toolbars. */
+    overlayBg?: string;
+    overlayText?: string;
+    overlayBorder?: string;
+    overlayShadow?: string;
+    toolbarBg?: string;
+    toolbarText?: string;
+    toolbarBorder?: string;
+    /** Canvas component-selection accent. Drives hover/selected outlines on
+     *  canvas components, the floating action bar's ring, and drag/drop
+     *  indicators. Kept independent of `primary` so the brand button and the
+     *  canvas's own interaction colour can differ — as they do by default
+     *  (a dark brand button, a green canvas accent). */
+    selection?: string;
+    /** Pale fill for `selection` — hover backgrounds on the same controls. */
+    selectionBg?: string;
+    /** Readable text/icon tone for `selection` when placed on `selectionBg`. */
+    selectionFg?: string;
+    /** 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. */
+    rowSelection?: string;
+    rowSelectionBg?: string;
+    rowSelectionFg?: string;
+    /** Small dark tooltips on icon buttons throughout the canvas and
+     *  toolbars. Kept distinct from `overlay` because tooltips are
+     *  conventionally dark even in an otherwise light theme; set both if you
+     *  want them to follow the rest of the theme instead. */
+    tooltipBg?: string;
+    tooltipText?: string;
+    /** The Save / Update button — the most commonly branded control. */
+    buttonPrimaryBg?: string;
+    buttonPrimaryText?: string;
+    buttonPrimaryHoverBg?: string;
+    buttonSecondaryBg?: string;
+    buttonSecondaryText?: string;
+    buttonSecondaryHoverBg?: string;
+    successBg?: string;
+    successFg?: string;
+    successBorder?: string;
+    infoBg?: string;
+    infoFg?: string;
+    infoBorder?: string;
+    warningBg?: string;
+    warningFg?: string;
+    warningBorder?: string;
+    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 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`. */
+    primaryColor?: string;
+    /** @deprecated Use `surface`. */
+    surfaceColor?: string;
+}
+/**
+ * Applies theme tokens.
+ *
+ * ```ts
+ * setEditorTheme({
+ *   primary: "#6366f1",
+ *   buttonPrimaryText: "#ffffff",
+ *   dark: { primary: "#818cf8", headerBg: "#0f172a" },
+ * });
+ * ```
+ *
+ * @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;
+/**
+ * Expands one hex colour into a 50–950 shade scale.
+ *
+ * The editor's own tokens no longer need this — `primary` and
+ * `primaryHover` are set directly — but it stays exported because hosts use
+ * it to derive matching shades for their own UI around the editor.
+ */
+export declare function palette(hex: string): Record<string, string>;

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;
+}