@d0nj/dsh-ui-custom 0.0.0-stage → 0.2.0

package/dist/client/hosted-fonts.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Families fetched from a font CDN on demand.
+ *
+ * @module @d0nj/dsh-ui-custom/hosted-fonts
+ */
+/** Role a family is suited to, used to group the picker. */
+export type FontCategory = 'sans' | 'serif' | 'mono' | 'display';
+/** One hosted family this package can load. */
+export interface HostedFont {
+    /** CSS family name, exactly as the stylesheet declares it. */
+    readonly family: string;
+    /** Grouping in the picker. */
+    readonly category: FontCategory;
+    /** Weights requested from the CDN; 400 is enough for body text. */
+    readonly weights?: readonly number[];
+}
+export declare const HOSTED_FONTS: readonly HostedFont[];
+/**
+ * @param font - the family to request.
+ * @returns an absolute stylesheet URL.
+ */
+export declare function hostedFontUrl(font: HostedFont): string;
+/**
+ * Load one family into the page; resolves on failure too, because a font that
+ * cannot be fetched must not break the panel.
+ *
+ * @param font - the family to load.
+ * @param doc - document to load into; defaults to the global one.
+ */
+export declare function loadHostedFont(font: HostedFont, doc?: Document | undefined): Promise<void>;
+/**
+ * @param fonts - catalog to read.
+ * @returns family names, sorted.
+ */
+export declare function hostedFamilies(fonts?: readonly HostedFont[]): string[];
+/**
+ * @param family - family name to find.
+ * @param fonts - catalog to search.
+ * @returns the entry, or `undefined` when the name is not hosted here.
+ */
+export declare function findHostedFont(family: string, fonts?: readonly HostedFont[]): HostedFont | undefined;
+//# sourceMappingURL=hosted-fonts.d.ts.map

package/dist/client/hosted-fonts.js

@@ -0,0 +1,98 @@
+/**
+ * Families fetched from a font CDN on demand.
+ *
+ * @module @d0nj/dsh-ui-custom/hosted-fonts
+ */
+export const HOSTED_FONTS = [
+    { family: 'Inter', category: 'sans' },
+    { family: 'IBM Plex Sans', category: 'sans' },
+    { family: 'Source Sans 3', category: 'sans' },
+    { family: 'Public Sans', category: 'sans' },
+    { family: 'Work Sans', category: 'sans' },
+    { family: 'DM Sans', category: 'sans' },
+    { family: 'Manrope', category: 'sans' },
+    { family: 'Figtree', category: 'sans' },
+    { family: 'Nunito Sans', category: 'sans' },
+    { family: 'Open Sans', category: 'sans' },
+    { family: 'Roboto', category: 'sans' },
+    { family: 'Lato', category: 'sans' },
+    { family: 'Montserrat', category: 'sans' },
+    { family: 'Poppins', category: 'sans' },
+    { family: 'Lexend', category: 'sans' },
+    { family: 'Outfit', category: 'sans' },
+    { family: 'Sora', category: 'sans' },
+    { family: 'Space Grotesk', category: 'sans' },
+    { family: 'JetBrains Mono', category: 'mono' },
+    { family: 'Fira Code', category: 'mono' },
+    { family: 'Source Code Pro', category: 'mono' },
+    { family: 'IBM Plex Mono', category: 'mono' },
+    { family: 'Roboto Mono', category: 'mono' },
+    { family: 'Space Mono', category: 'mono' },
+    { family: 'Inconsolata', category: 'mono' },
+    { family: 'Ubuntu Mono', category: 'mono' },
+    { family: 'Anonymous Pro', category: 'mono' },
+    { family: 'Source Serif 4', category: 'serif' },
+    { family: 'IBM Plex Serif', category: 'serif' },
+    { family: 'Lora', category: 'serif' },
+    { family: 'Merriweather', category: 'serif' },
+    { family: 'Newsreader', category: 'serif' },
+    { family: 'Crimson Pro', category: 'serif' },
+    { family: 'Bitter', category: 'serif' },
+    { family: 'Bricolage Grotesque', category: 'display' },
+    { family: 'Instrument Serif', category: 'display' },
+];
+const CDN_BASE = 'https://fonts.googleapis.com/css2';
+/** Stylesheets outlive any one render, and a repeat request is a wasted round-trip. */
+const requested = new Set();
+/**
+ * @param font - the family to request.
+ * @returns an absolute stylesheet URL.
+ */
+export function hostedFontUrl(font) {
+    const name = font.family.trim().replace(/\s+/gu, '+');
+    const weights = (font.weights ?? [400]).join(';');
+    return `${CDN_BASE}?family=${name}:wght@${weights}&display=swap`;
+}
+/**
+ * Load one family into the page; resolves on failure too, because a font that
+ * cannot be fetched must not break the panel.
+ *
+ * @param font - the family to load.
+ * @param doc - document to load into; defaults to the global one.
+ */
+export async function loadHostedFont(font, doc = typeof document === 'undefined' ? undefined : document) {
+    if (doc === undefined)
+        return;
+    const key = font.family.toLowerCase();
+    if (requested.has(key))
+        return;
+    requested.add(key);
+    const stylesheet = doc.createElement('link');
+    stylesheet.rel = 'stylesheet';
+    stylesheet.href = hostedFontUrl(font);
+    stylesheet.dataset.d0njHostedFont = font.family;
+    await new Promise((resolve) => {
+        stylesheet.addEventListener('load', () => resolve(), { once: true });
+        stylesheet.addEventListener('error', () => resolve(), { once: true });
+        doc.head.append(stylesheet);
+    });
+    // Without this the first render after a pick can still measure the fallback.
+    await doc.fonts?.ready.catch(() => { });
+}
+/**
+ * @param fonts - catalog to read.
+ * @returns family names, sorted.
+ */
+export function hostedFamilies(fonts = HOSTED_FONTS) {
+    return fonts.map((font) => font.family).sort((left, right) => left.localeCompare(right));
+}
+/**
+ * @param family - family name to find.
+ * @param fonts - catalog to search.
+ * @returns the entry, or `undefined` when the name is not hosted here.
+ */
+export function findHostedFont(family, fonts = HOSTED_FONTS) {
+    const key = family.trim().replace(/^["']|["']$/gu, '').toLowerCase();
+    return fonts.find((font) => font.family.toLowerCase() === key);
+}
+//# sourceMappingURL=hosted-fonts.js.map

package/dist/client/index.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Client half: keep the theme override layer in step with the document.
+ *
+ * The browser half owns exactly one thing — the `ctx.theme.overrideTokens` layer
+ * this plugin stacks over whatever theme is active. It re-derives that layer
+ * whenever the customization document changes, so a change made in the panel
+ * reaches the screen without a reload, and removing it restores whatever it
+ * covered.
+ *
+ * Two rules matter here:
+ *
+ * - **One source, one layer.** `overrideTokens` allows one layer per source and
+ *   a repeat call replaces it wholesale, so the plugin never leaks layers: every
+ *   update re-registers under the same source id.
+ * - **Both palette modes always travel together.** The resolver guarantees it, and
+ *   the runtime rejects a bare string, so a half-specified token can never
+ *   produce an illegible surface after a scheme switch.
+ *
+ * @module @d0nj/dsh-ui-custom/client
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { ThemeStudio } from './panel.js';
+/** One token's value per palette mode, as ctx.theme.overrideTokens requires. */
+export type ThemeTokenOverrides = Record<string, {
+    light: string;
+    dark: string;
+}>;
+/** Layer identity; the runtime keeps one layer per source. */
+export declare const OVERRIDE_SOURCE = "d0nj-ui-custom";
+/** The slice of the settings client this plugin uses to read and write its document. */
+interface ConfigForm {
+    getSnapshot(): {
+        readonly value: unknown;
+        readonly revision: number | undefined;
+        readonly writable: boolean;
+    };
+    subscribe(listener: () => void): () => void;
+    mutate(ops: readonly {
+        op: 'set';
+        path: readonly string[];
+        value: unknown;
+    }[]): Promise<boolean>;
+    set(field: string, value: unknown): Promise<boolean>;
+}
+/** Services required before `apply` runs. */
+export declare const inject: readonly ["theme", "configForms", "slots"];
+/**
+ * Provide the React namespace to this plugin.
+ * @param react - the namespace the loader resolved.
+ */
+export declare function useReact(react: Parameters<typeof ThemeStudio>[0]): void;
+/**
+ * Client plugin body.
+ * @param ctx - client cordis context with `theme` and `configForms` injected.
+ */
+export declare function apply(ctx: Context): void;
+/**
+ * Register the Theme Studio page into the settings section list.
+ *
+ * Kept separate from `apply` so the section registration can be exercised in a
+ * unit test with a stub slots service, without a browser.
+ *
+ * @param ctx - client context.
+ * @param getState - supplies the current panel state.
+ * @param actions - the reactions the panel invokes.
+ */
+export declare function registerPanel(ctx: Context, getState: () => import('./panel.js').PanelState, actions: import('./panel.js').PanelActions, settingsForm: ConfigForm): void;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/client/index.js

@@ -0,0 +1,324 @@
+import { PRESETS, TOKEN_SPECS } from '../spec.js';
+import { resolveCustomization } from '../resolve.js';
+import { ThemeStudio } from './panel.js';
+/** Layer identity; the runtime keeps one layer per source. */
+export const OVERRIDE_SOURCE = 'd0nj-ui-custom';
+/** Services required before `apply` runs. */
+export const inject = ['theme', 'configForms', 'slots'];
+/**
+ * The React namespace, handed in by the module envelope.
+ *
+ * The browser loader resolves React through its own module table, so a client
+ * half cannot import it. The stamped envelope calls useReact before apply,
+ * which keeps the dependency explicit instead of reading an ambient global.
+ */
+let ReactImpl;
+/**
+ * Provide the React namespace to this plugin.
+ * @param react - the namespace the loader resolved.
+ */
+export function useReact(react) {
+    ReactImpl = react;
+}
+/**
+ * Flatten a preset's per-mode tokens to the single value the `register` arm
+ * expects, picking the mode that matches the preset's own base palette.
+ *
+ * `register` takes a flat `tokens` map rather than the two-mode shape
+ * `overrideTokens` accepts, so the mapping has to happen somewhere; doing it
+ * here keeps the colorScheme and the chosen values from disagreeing.
+ *
+ * @param preset - one shipped preset.
+ * @returns the flat token map for `register`.
+ */
+function flatPresetTokens(preset) {
+    const tokens = {};
+    for (const [name, modes] of Object.entries(preset.tokens)) {
+        tokens[name] = preset.colorScheme === 'dark' ? modes.dark : modes.light;
+    }
+    return tokens;
+}
+/**
+ * Normalize the stored value into a document.
+ *
+ * The settings snapshot carries the parsed namespace value, which is already
+ * shaped like the config; this narrows it without trusting the transport.
+ * @param value - snapshot value.
+ * @returns the document to resolve.
+ */
+function asDocument(value) {
+    const fallback = {
+        basePreset: 'none',
+        tokens: {},
+        typography: {
+            textFontFamily: '',
+            codeFontFamily: '',
+            terminalFontFamily: '',
+            fontSize: 14,
+            codeFontSize: 11,
+            terminalFontSize: 13,
+        },
+        geometry: { radius: 8, density: 'comfortable' },
+    };
+    if (value === null || typeof value !== 'object')
+        return fallback;
+    const record = value;
+    const typography = record.typography;
+    const geometry = record.geometry;
+    return {
+        basePreset: typeof record.basePreset === 'string' ? record.basePreset : 'none',
+        tokens: record.tokens !== null && typeof record.tokens === 'object'
+            ? record.tokens
+            : {},
+        typography: {
+            ...fallback.typography,
+            ...(typography !== null && typeof typography === 'object'
+                ? typography
+                : {}),
+        },
+        geometry: {
+            ...fallback.geometry,
+            ...(geometry !== null && typeof geometry === 'object'
+                ? geometry
+                : {}),
+        },
+    };
+}
+/**
+ * Client plugin body.
+ * @param ctx - client cordis context with `theme` and `configForms` injected.
+ */
+export function apply(ctx) {
+    // A throw here fails the whole web boot (1 entry did not activate), which takes
+    // the UI down for a customization plugin. Every step is therefore guarded: a
+    // problem is reported once and the rest of the harness keeps working.
+    try {
+        applyInner(ctx);
+    }
+    catch (error) {
+        reportFailure(ctx, error);
+    }
+}
+/**
+ * Report one fatal setup failure without rethrowing.
+ * @param ctx - client context.
+ * @param error - the failure.
+ */
+function reportFailure(ctx, error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const logger = ctx.logger;
+    logger?.('ui-custom').error("theme customization disabled: " + message);
+}
+/**
+ * The real client body, called under a guard by {@link apply}.
+ * @param ctx - client context.
+ */
+function applyInner(ctx) {
+    const theme = ctx.theme;
+    const forms = ctx.configForms;
+    // Presets register once, as real themes, so they appear among the normal
+    // choices and survive a reload even if this plugin's override layer is empty.
+    for (const preset of PRESETS) {
+        try {
+            ctx.effect(() => theme.register({
+                id: preset.id,
+                colorScheme: preset.colorScheme,
+                tokens: flatPresetTokens(preset),
+            }));
+        }
+        catch (error) {
+            // A preset id that is already taken (the built-in light/dark pair, or a
+            // re-registration after HMR) must not cost the user the editor.
+            reportFailure(ctx, error);
+        }
+    }
+    const form = forms.get('ui-custom');
+    let disposeLayer;
+    // The last typography this plugin applied, so it writes only real changes and
+    // never fights the shipped Appearance rows on every snapshot.
+    let appliedTypography = '';
+    /**
+     * Recompute the layer from the stored document.
+     */
+    const refresh = () => {
+        const snapshot = form.getSnapshot();
+        if (snapshot.value === undefined)
+            return;
+        const resolved = resolveCustomization(asDocument(snapshot.value));
+        disposeLayer?.();
+        disposeLayer = theme.overrideTokens(OVERRIDE_SOURCE, resolved.tokens);
+        // Typography goes through the theme service's own entries, so the built-in
+        // rows and this panel share one source of truth instead of shadowing each
+        // other. Sizes are only written when they differ, because each write is a
+        // settings mutation.
+        const typography = resolved.typography;
+        const key = JSON.stringify(typography);
+        if (key !== appliedTypography) {
+            appliedTypography = key;
+            const roles = [
+                ['text', typography.textFontFamily, typography.fontSize],
+                ['code', typography.codeFontFamily, typography.codeFontSize],
+                ['terminal', typography.terminalFontFamily, typography.terminalFontSize],
+            ];
+            for (const [role, family, size] of roles) {
+                try {
+                    theme.setFontFamily(role, family);
+                    theme.setFontSize(role, size);
+                }
+                catch {
+                    // A font name the runtime rejects must not stop the colour layer from
+                    // applying; the panel surfaces the rejected value instead.
+                }
+            }
+        }
+    };
+    ctx.effect(() => form.subscribe(refresh));
+    ctx.effect(() => () => {
+        disposeLayer?.();
+    });
+    refresh();
+    try {
+        registerPanel(ctx, () => panelState(form), panelActions(form, readDocument), form);
+    }
+    catch (error) {
+        reportFailure(ctx, error);
+    }
+}
+/**
+ * Register the Theme Studio page into the settings section list.
+ *
+ * Kept separate from `apply` so the section registration can be exercised in a
+ * unit test with a stub slots service, without a browser.
+ *
+ * @param ctx - client context.
+ * @param getState - supplies the current panel state.
+ * @param actions - the reactions the panel invokes.
+ */
+export function registerPanel(ctx, getState, actions, settingsForm) {
+    const slots = ctx.slots;
+    if (ReactImpl === undefined)
+        return;
+    const React = ReactImpl;
+    /**
+     * The slot component.
+     *
+     * It is a real component rather than a direct call, so hooks belong to it and a
+     * settings change re-renders it. The subscription is what makes a panel write
+     * visible without reopening the page: `getState()` reads the same form the
+     * action just wrote, and the subscription fires when the Host echoes it back.
+     *
+     * @returns the Theme Studio element.
+     */
+    const Panel = () => {
+        const [, force] = React.useState(0);
+        React.useEffect(() => {
+            // Re-render when the Host publishes a new section for this namespace.
+            let tick = 0;
+            const dispose = settingsForm.subscribe(() => {
+                tick += 1;
+                force(tick);
+            });
+            return dispose;
+        }, []);
+        return ThemeStudio(React, { state: getState(), actions, presets: PRESETS });
+    };
+    ctx.effect(() => {
+        slots.inject('settings.section', () => slots.register({ name: 'settings.section', id: 'ui-custom', order: 11, label: () => 'Theme Studio' }, Panel));
+        return () => { };
+    });
+}
+/**
+ * Read the stored customization document.
+ * @param form - the settings form for this plugin's namespace.
+ * @returns the document the panel edits.
+ */
+function readDocument(form) {
+    return asDocument(form.getSnapshot().value);
+}
+/**
+ * The document the panel last rendered, so its actions can merge one field
+ * without restating the whole section from a possibly stale snapshot.
+ */
+let currentDocument;
+/**
+ * Supply the current document for the panel's reads.
+ * @param form - the settings form.
+ * @returns the document.
+ */
+function getDocument(form) {
+    currentDocument = readDocument(form);
+    return currentDocument;
+}
+/**
+ * Build the panel's state from the stored document.
+ * @param form - the settings form.
+ * @returns the state the panel renders.
+ */
+function panelState(form) {
+    const document = getDocument(form);
+    const resolved = resolveCustomization(document);
+    const overrides = document.tokens;
+    return {
+        basePreset: document.basePreset,
+        tokens: TOKEN_SPECS.map((spec) => ({
+            name: spec.name,
+            label: spec.label,
+            description: spec.description,
+            override: overrides[spec.name],
+        })),
+        typography: resolved.typography,
+        geometry: document.geometry,
+        warnings: resolved.warnings,
+        writable: form.getSnapshot().writable,
+    };
+}
+/**
+ * Build the panel's write actions.
+ *
+ * Every action writes a whole field through the settings form, which serializes
+ * the mutation against the namespace revision. Tokens are written as one field
+ * (`tokens`) rather than per-name, because the schema models them as a dict and
+ * a partial write would drop the others.
+ *
+ * @param form - the settings form.
+ * @param document - reads the document the action should start from.
+ * @returns the actions the panel invokes.
+ */
+function panelActions(form, document) {
+    const write = (field, value) => {
+        void form.set(field, value);
+    };
+    const withTokens = (mutate) => {
+        const base = document(form);
+        write('tokens', mutate({ ...base.tokens }));
+    };
+    return {
+        setPreset: (id) => write('basePreset', id),
+        setToken: (name, light, dark) => withTokens((tokens) => ({ ...tokens, [name]: { light, dark } })),
+        clearToken: (name) => withTokens((tokens) => {
+            const next = { ...tokens };
+            delete next[name];
+            return next;
+        }),
+        setFont: (role, value) => {
+            const base = document(form);
+            const key = role === 'text' ? 'textFontFamily' : role === 'code' ? 'codeFontFamily' : 'terminalFontFamily';
+            write('typography', { ...base.typography, [key]: value });
+        },
+        setFontSize: (role, px) => {
+            const base = document(form);
+            const key = role === 'text' ? 'fontSize' : role === 'code' ? 'codeFontSize' : 'terminalFontSize';
+            write('typography', { ...base.typography, [key]: px });
+        },
+        setRadius: (px) => {
+            const base = document(form);
+            write('geometry', { ...base.geometry, radius: px });
+        },
+        setDensity: (density) => {
+            const base = document(form);
+            write('geometry', { ...base.geometry, density: density });
+        },
+        resetAll: () => write('tokens', {}),
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/client/panel.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Theme Studio: the settings page.
+ *
+ * Live preview is computed from the same resolver the stored document goes
+ * through, so what the panel shows and what the plugin applies cannot drift.
+ * Writes go through `configForms.get('ui-custom').set/unset`, which means the
+ * panel never touches YAML, never races a revision, and is reversible field by
+ * field.
+ *
+ * Styling follows the plugin rules: theme tokens only (`--dsw-alias-*`, plus the
+ * `--d0nj-*` geometry tokens this plugin derives), no literal colours for
+ * chrome. The swatches themselves are the one place a literal colour is correct,
+ * because they *are* the colour being chosen.
+ *
+ * @module @d0nj/dsh-ui-custom/panel
+ */
+/** One token row's editable state. */
+export interface TokenRowState {
+    readonly name: string;
+    readonly label: string;
+    readonly description: string;
+    /** Stored override, or `undefined` while the token inherits the preset. */
+    readonly override?: {
+        readonly light: string;
+        readonly dark: string;
+    } | undefined;
+}
+/** Panel state handed in by the client apply. */
+export interface PanelState {
+    readonly basePreset: string;
+    readonly tokens: readonly TokenRowState[];
+    readonly typography: {
+        readonly textFontFamily: string;
+        readonly codeFontFamily: string;
+        readonly terminalFontFamily: string;
+        readonly fontSize: number;
+        readonly codeFontSize: number;
+        readonly terminalFontSize: number;
+    };
+    readonly geometry: {
+        readonly radius: number;
+        readonly density: string;
+    };
+    readonly warnings: readonly string[];
+    readonly writable: boolean;
+}
+/** Reactions the panel invokes. */
+export interface PanelActions {
+    setPreset(id: string): void;
+    setToken(name: string, light: string, dark: string): void;
+    clearToken(name: string): void;
+    setFont(role: 'text' | 'code' | 'terminal', value: string): void;
+    setFontSize(role: 'text' | 'code' | 'terminal', px: number): void;
+    setRadius(px: number): void;
+    setDensity(density: string): void;
+    resetAll(): void;
+}
+/** Exported so tests do not inherit an open list between cases. */
+export declare function resetCombos(): void;
+/**
+ * Render the Theme Studio page.
+ *
+ * Written against a minimal `React.createElement` shim rather than JSX so the
+ * module needs no transform at build time; the client bundle supplies React.
+ *
+ * @param React - the React namespace from the module table.
+ * @param props - current state and the actions to invoke.
+ * @returns the section element.
+ */
+export declare function ThemeStudio(React: {
+    createElement: (type: unknown, props?: unknown, ...children: unknown[]) => unknown;
+    useState: <T>(initial: T) => [T, (next: T) => void];
+}, props: {
+    state: PanelState;
+    actions: PanelActions;
+    presets: readonly {
+        id: string;
+        label: string;
+        description: string;
+        colorScheme: 'light' | 'dark';
+        tokens: Record<string, {
+            light: string;
+            dark: string;
+        }>;
+    }[];
+}): unknown;
+//# sourceMappingURL=panel.d.ts.map