@d0nj/dsh-ui-custom 0.1.0 → 0.2.0

package/cordis.patch.yml

@@ -1,22 +1,22 @@
-# Contributes the customization document and its defaults.
-#
-# The browser half reads this row's namespace ("ui-custom") through the settings
-# client, so a choice made in Theme Studio persists here and survives a reload.
-# Selecting the preset below is a starting point, not a requirement: the panel
-# changes it through the same namespace.
-- insert:
-    - id: ui-custom
-      name: '@d0nj/dsh-ui-custom'
-      config:
-        basePreset: none
-        tokens: {}
-        typography:
-          textFontFamily: ''
-          codeFontFamily: ''
-          terminalFontFamily: ''
-          fontSize: 14
-          codeFontSize: 11
-          terminalFontSize: 13
-        geometry:
-          radius: 8
-          density: comfortable
+# Contributes the customization document and its defaults.
+#
+# The browser half reads this row's namespace ("ui-custom") through the settings
+# client, so a choice made in Theme Studio persists here and survives a reload.
+# Selecting the preset below is a starting point, not a requirement: the panel
+# changes it through the same namespace.
+- insert:
+    - id: ui-custom
+      name: '@d0nj/dsh-ui-custom'
+      config:
+        basePreset: none
+        tokens: {}
+        typography:
+          textFontFamily: ''
+          codeFontFamily: ''
+          terminalFontFamily: ''
+          fontSize: 14
+          codeFontSize: 11
+          terminalFontSize: 13
+        geometry:
+          radius: 8
+          density: comfortable

package/dist/client/client.js

@@ -874,6 +874,13 @@ window.__ModuleLoader__.load({
         const { DENSITIES, FONT_SIZE_RANGES, RADIUS_MAX, RADIUS_MIN, TOKEN_NAMES, findPreset, tokenSpec } = __require('./spec.js');
         /** A colour in one of the forms the theme service and browsers accept. */
         const COLOR_PATTERN = /^(#(?:[0-9a-f]{3}|[0-9a-f]{4}|[0-9a-f]{6}|[0-9a-f]{8})|(?:rgb|hsl|oklch|lab|lch|color)\([^)]*\)|[a-z]+)$/iu;
+        /** CSS generic families, which always resolve and so never need a local match. */
+        const GENERIC_FAMILIES = new Set([
+            'serif', 'sans-serif', 'monospace', 'cursive', 'fantasy', 'system-ui',
+            'ui-serif', 'ui-sans-serif', 'ui-monospace', 'ui-rounded', 'emoji', 'math',
+            'fangsong', '-apple-system', 'blinkmacsystemfont',
+            'inherit', 'initial', 'unset',
+        ]);
         /**
          * Whether a value is a plausible CSS colour.
          *
@@ -942,6 +949,16 @@ window.__ModuleLoader__.load({
         function isDensity(value) {
             return DENSITIES.includes(value);
         }
+        /**
+         * @param stack - comma-separated font stack.
+         * @returns the concrete family names, in order, without generics.
+         */
+        function familyNames(stack) {
+            return stack
+                .split(',')
+                .map((part) => part.trim().replace(/^["']|["']$/gu, '').trim())
+                .filter((name) => name !== '' && !GENERIC_FAMILIES.has(name.toLowerCase()));
+        }
         /**
          * Resolve a customization document into theme tokens and typography.
          *
@@ -1004,7 +1021,7 @@ window.__ModuleLoader__.load({
         /** Every documented token name, re-exported for the panel's reset action. */
         Object.assign(exports, { TOKEN_NAMES: TOKEN_NAMES });
         //# sourceMappingURL=resolve.js.map
-        Object.assign(exports, { isColor: isColor, clamp: clamp, geometryTokens: geometryTokens, correctFontSize: correctFontSize, isDensity: isDensity, resolveCustomization: resolveCustomization });
+        Object.assign(exports, { isColor: isColor, clamp: clamp, geometryTokens: geometryTokens, correctFontSize: correctFontSize, isDensity: isDensity, familyNames: familyNames, resolveCustomization: resolveCustomization });
         
       },
       "./client/panel.js": (module, exports, __require) => {
@@ -1024,6 +1041,7 @@ window.__ModuleLoader__.load({
          *
          * @module @d0nj/dsh-ui-custom/panel
          */
+        const { findHostedFont, hostedFamilies, loadHostedFont } = __require('./client/hosted-fonts.js');
         /** Shared inline styles, computed from theme tokens. */
         function styles() {
             return {
@@ -1093,6 +1111,47 @@ window.__ModuleLoader__.load({
                     font: 'inherit',
                     fontSize: 12,
                 },
+                select: {
+                    width: 260,
+                    padding: '4px 6px',
+                    borderRadius: 'var(--d0nj-radius-sm, 4px)',
+                    border: '1px solid var(--dsw-alias-border-l1)',
+                    background: 'var(--dsw-alias-bg-base)',
+                    color: 'var(--dsw-alias-label-primary)',
+                    font: 'inherit',
+                    fontSize: 12,
+                },
+                fontStack: { display: 'flex', flexDirection: 'column', gap: 4, width: 260 },
+                fontRow: { gap: 18 },
+                combo: { position: 'relative', width: 260 },
+                listbox: {
+                    position: 'absolute',
+                    zIndex: 10,
+                    top: '100%',
+                    left: 0,
+                    right: 0,
+                    marginTop: 4,
+                    maxHeight: 240,
+                    overflowY: 'auto',
+                    padding: 4,
+                    borderRadius: 'var(--d0nj-radius-sm, 4px)',
+                    border: '1px solid var(--dsw-alias-border-l2)',
+                    // A popup over arbitrary content cannot inherit the surface behind it, so
+                    // it paints the module fill; only the element's own list uses this literal.
+                    background: 'var(--dsw-alias-bg-module-platform, var(--dsw-alias-bg-layer-1))',
+                    boxShadow: 'var(--dsw-elevation-lv2, 0 4px 12px rgba(0, 0, 0, 0.2))',
+                },
+                option: {
+                    padding: '4px 6px',
+                    borderRadius: 'var(--d0nj-radius-sm, 4px)',
+                    fontSize: 12,
+                    color: 'var(--dsw-alias-label-primary)',
+                    cursor: 'pointer',
+                    whiteSpace: 'nowrap',
+                    overflow: 'hidden',
+                    textOverflow: 'ellipsis',
+                },
+                optionActive: { background: 'var(--dsw-alias-interactive-bg-hover, var(--dsw-alias-bg-layer-2))' },
                 colorInput: {
                     width: 34,
                     height: 26,
@@ -1131,6 +1190,41 @@ window.__ModuleLoader__.load({
                 row2: { display: 'flex', gap: 8, alignItems: 'center', flexWrap: 'wrap' },
             };
         }
+        /**
+         * Combobox state per role.
+         *
+         * Kept at module scope because the panel re-renders on every settings echo, and
+         * state created inside the render would reset to closed each pass.
+         */
+        const combos = new Map();
+        /** Exported so tests do not inherit an open list between cases. */
+        function resetCombos() {
+            combos.clear();
+        }
+        /**
+         * @param key - the role's accessible label.
+         * @returns the state for that role, created on first use.
+         */
+        function comboState(key) {
+            const existing = combos.get(key);
+            if (existing !== undefined)
+                return existing;
+            const created = { open: false, query: '', active: 0 };
+            combos.set(key, created);
+            return created;
+        }
+        /**
+         * Fonts offered by the picker.
+         *
+         * Hosted rather than local: a browser cannot enumerate installed fonts without a
+         * permission-gated API most lack, and a local family looks different elsewhere.
+         */
+        let fontChoiceCache;
+        /** @returns the families the picker offers. */
+        function fontChoices() {
+            fontChoiceCache ??= hostedFamilies();
+            return fontChoiceCache;
+        }
         /**
          * Render the Theme Studio page.
          *
@@ -1153,6 +1247,127 @@ window.__ModuleLoader__.load({
             const [localTokens, setLocalTokens] = React.useState({});
             const [localGeometry, setLocalGeometry] = React.useState(state.geometry);
             const [localTypography, setLocalTypography] = React.useState(state.typography);
+            // The counter must keep changing: writing the same number makes React bail out.
+            const [renderTick, setRender] = React.useState(0);
+            const choices = fontChoices();
+            const rerender = () => setRender(renderTick + 1);
+            /**
+             * @param role - font role being changed.
+             * @param value - CSS stack to apply.
+             */
+            const applyFont = (role, value) => {
+                const hosted = findHostedFont(value);
+                if (hosted === undefined) {
+                    actions.setFont(role, value);
+                    return;
+                }
+                void loadHostedFont(hosted).then(() => actions.setFont(role, value));
+            };
+            /**
+             * @param ariaLabel - accessible name for the input.
+             * @param family - current stack.
+             * @param onChange - writes the chosen stack.
+             * @returns the combobox element.
+             */
+            const fontCombo = (ariaLabel, family, onChange) => {
+                const combo = comboState(ariaLabel);
+                // Not the word "Default", which could collide with a family of that name.
+                const DEFAULT_CHOICE = '\u0000default';
+                const isDefault = (choice) => choice === DEFAULT_CHOICE;
+                const matches = () => {
+                    const query = combo.query.trim().toLowerCase();
+                    if (query === '')
+                        return [DEFAULT_CHOICE, ...choices.slice(0, 39)];
+                    const filtered = choices.filter((choice) => choice.toLowerCase().includes(query));
+                    const keepDefault = 'default (built-in)'.includes(query) || 'built-in'.includes(query);
+                    return (keepDefault ? [DEFAULT_CHOICE, ...filtered] : filtered).slice(0, 40);
+                };
+                const commit = (value) => {
+                    combo.open = false;
+                    combo.query = '';
+                    combo.active = 0;
+                    const next = isDefault(value) ? '' : value;
+                    if (next !== combo.written)
+                        onChange(next);
+                    combo.written = undefined;
+                    rerender();
+                };
+                const visible = combo.open ? matches() : [];
+                return h('div', { style: s.combo }, h('input', {
+                    type: 'text',
+                    role: 'combobox',
+                    style: s.select,
+                    'aria-label': ariaLabel,
+                    'aria-expanded': combo.open,
+                    'aria-autocomplete': 'list',
+                    placeholder: 'Default (built-in stack)',
+                    value: family,
+                    onFocus: (event) => {
+                        combo.open = true;
+                        combo.query = '';
+                        combo.active = 0;
+                        event.target.select?.();
+                        rerender();
+                    },
+                    onInput: (event) => {
+                        combo.open = true;
+                        combo.query = event.target.value;
+                        combo.active = 0;
+                        combo.written = event.target.value;
+                        onChange(event.target.value);
+                        rerender();
+                    },
+                    onKeyDown: (event) => {
+                        const list = visible;
+                        if (event.key === 'Escape') {
+                            combo.open = false;
+                            combo.query = '';
+                            rerender();
+                            return;
+                        }
+                        if (event.key === 'ArrowDown' && list.length > 0) {
+                            event.preventDefault();
+                            combo.active = (combo.active + 1) % list.length;
+                            rerender();
+                            return;
+                        }
+                        if (event.key === 'ArrowUp' && list.length > 0) {
+                            event.preventDefault();
+                            combo.active = (combo.active - 1 + list.length) % list.length;
+                            rerender();
+                            return;
+                        }
+                        if (event.key === 'Enter') {
+                            const picked = list[combo.active];
+                            if (combo.open && picked !== undefined)
+                                commit(picked);
+                            else if (combo.open && combo.query.trim() !== '')
+                                commit(combo.query.trim());
+                        }
+                    },
+                    onBlur: () => {
+                        combo.open = false;
+                        combo.query = '';
+                        rerender();
+                    },
+                }), combo.open && visible.length > 0
+                    ? h('div', { style: s.listbox, role: 'listbox' }, ...visible.map((choice, index) => h('div', {
+                        key: choice,
+                        role: 'option',
+                        'aria-selected': index === combo.active,
+                        style: {
+                            ...s.option,
+                            ...(isDefault(choice) ? {} : { fontFamily: `"${choice}"` }),
+                            ...(index === combo.active ? s.optionActive : {}),
+                        },
+                        // Fires before the input's blur, which would close the list first.
+                        onMouseDown: (event) => {
+                            event.preventDefault();
+                            commit(choice);
+                        },
+                    }, isDefault(choice) ? 'Default (built-in stack)' : choice)))
+                    : null);
+            };
             /** The preset currently selected, for filling a missing mode from its colours. */
             const basePreset = presets.find((preset) => preset.id === (localPreset ?? state.basePreset));
             /**
@@ -1248,31 +1463,27 @@ window.__ModuleLoader__.load({
                     },
                 }, 'Reset')));
             });
-            const fontRow = (role, label, family, size) => h('div', { style: s.row }, h('div', { style: s.rowLabel }, h('span', { style: { fontSize: 12, fontWeight: 600 } }, label)), h('input', {
-                style: { ...s.input, width: 260 },
-                type: 'text',
-                'aria-label': `${label} font stack`,
-                placeholder: 'Font family, fallback, sans-serif',
-                value: family,
-                onChange: (event) => {
+            const fontRow = (role, label, family, size) => {
+                const edit = (value) => {
                     const key = role === 'text' ? 'textFontFamily' : role === 'code' ? 'codeFontFamily' : 'terminalFontFamily';
-                    setLocalTypography({ ...(localTypography ?? state.typography), [key]: event.target.value });
-                    actions.setFont(role, event.target.value);
-                },
-            }), h('div', { style: s.row2 }, h('input', {
-                style: s.input,
-                type: 'number',
-                min: 8,
-                max: 24,
-                'aria-label': `${label} size`,
-                value: size,
-                onChange: (event) => {
-                    const px = Number(event.target.value);
-                    const key = role === 'text' ? 'fontSize' : role === 'code' ? 'codeFontSize' : 'terminalFontSize';
-                    setLocalTypography({ ...(localTypography ?? state.typography), [key]: px });
-                    actions.setFontSize(role, px);
-                },
-            }), h('span', { style: s.hint }, 'px')));
+                    setLocalTypography({ ...(localTypography ?? state.typography), [key]: value });
+                    applyFont(role, value);
+                };
+                return h('div', { style: { ...s.row, ...s.fontRow } }, h('div', { style: s.rowLabel }, h('span', { style: { fontSize: 12, fontWeight: 600 } }, label)), fontCombo(`${label} font family`, family, edit), h('div', { style: s.row2 }, h('input', {
+                    style: s.input,
+                    type: 'number',
+                    min: 8,
+                    max: 24,
+                    'aria-label': `${label} size`,
+                    value: size,
+                    onChange: (event) => {
+                        const px = Number(event.target.value);
+                        const key = role === 'text' ? 'fontSize' : role === 'code' ? 'codeFontSize' : 'terminalFontSize';
+                        setLocalTypography({ ...(localTypography ?? state.typography), [key]: px });
+                        actions.setFontSize(role, px);
+                    },
+                }), h('span', { style: s.hint }, 'px')));
+            };
             return h('div', { style: s.root }, state.writable
                 ? null
                 : h('div', { style: s.warning }, 'This profile does not accept settings writes; changes will not persist.'), h('section', { style: s.section }, h('h3', { style: s.heading }, 'Base theme'), h('p', { style: s.hint }, 'A preset supplies a complete token set. Tune individual values below it.'), h('div', { style: s.grid }, presetCards)), h('section', { style: s.section }, h('h3', { style: s.heading }, 'Live preview'), h('div', { style: s.preview }, h('span', { style: { fontSize: 15, fontWeight: 600 } }, 'The quick brown fox'), h('span', { style: { fontSize: 12, color: 'var(--dsw-alias-label-secondary)' } }, 'Secondary text sits one step down.'), h('div', { style: s.row2 }, h('span', { style: { ...s.button, background: 'var(--dsw-alias-brand-primary)', color: 'var(--dsw-alias-bg-base)' } }, 'Accent'), h('span', { style: { ...s.button, borderColor: 'var(--dsw-alias-state-error-primary)' } }, 'Error'), h('span', { style: { ...s.button, borderColor: 'var(--dsw-alias-state-success-primary)' } }, 'Success'), h('span', { style: { ...s.button, borderColor: 'var(--dsw-alias-state-warn-primary)' } }, 'Warning')))), h('section', { style: s.section }, h('h3', { style: s.heading }, 'Typography'), fontRow('text', 'Interface text', (localTypography ?? state.typography).textFontFamily, (localTypography ?? state.typography).fontSize), fontRow('code', 'Code', (localTypography ?? state.typography).codeFontFamily, (localTypography ?? state.typography).codeFontSize), fontRow('terminal', 'Terminal', (localTypography ?? state.typography).terminalFontFamily, (localTypography ?? state.typography).terminalFontSize)), h('section', { style: s.section }, h('h3', { style: s.heading }, 'Geometry'), h('div', { style: s.row }, h('div', { style: s.rowLabel }, h('span', { style: { fontSize: 12, fontWeight: 600 } }, 'Corner radius')), h('input', {
@@ -1302,7 +1513,109 @@ window.__ModuleLoader__.load({
                 : null, h('section', { style: s.section }, h('button', { type: 'button', style: s.button, onClick: () => actions.resetAll() }, 'Reset all customization')));
         }
         //# sourceMappingURL=panel.js.map
-        Object.assign(exports, { ThemeStudio: ThemeStudio });
+        Object.assign(exports, { resetCombos: resetCombos, ThemeStudio: ThemeStudio });
+        
+      },
+      "./client/hosted-fonts.js": (module, exports, __require) => {
+        /**
+         * Families fetched from a font CDN on demand.
+         *
+         * @module @d0nj/dsh-ui-custom/hosted-fonts
+         */
+        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.
+         */
+        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.
+         */
+        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.
+         */
+        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.
+         */
+        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
+        Object.assign(exports, { hostedFontUrl: hostedFontUrl, loadHostedFont: loadHostedFont, hostedFamilies: hostedFamilies, findHostedFont: findHostedFont, HOSTED_FONTS: HOSTED_FONTS });
         
       },
     }

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/panel.d.ts

@@ -55,6 +55,8 @@ export interface PanelActions {
     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.
  *

package/dist/client/panel.js

@@ -14,6 +14,7 @@
  *
  * @module @d0nj/dsh-ui-custom/panel
  */
+import { findHostedFont, hostedFamilies, loadHostedFont } from './hosted-fonts.js';
 /** Shared inline styles, computed from theme tokens. */
 function styles() {
     return {
@@ -83,6 +84,47 @@ function styles() {
             font: 'inherit',
             fontSize: 12,
         },
+        select: {
+            width: 260,
+            padding: '4px 6px',
+            borderRadius: 'var(--d0nj-radius-sm, 4px)',
+            border: '1px solid var(--dsw-alias-border-l1)',
+            background: 'var(--dsw-alias-bg-base)',
+            color: 'var(--dsw-alias-label-primary)',
+            font: 'inherit',
+            fontSize: 12,
+        },
+        fontStack: { display: 'flex', flexDirection: 'column', gap: 4, width: 260 },
+        fontRow: { gap: 18 },
+        combo: { position: 'relative', width: 260 },
+        listbox: {
+            position: 'absolute',
+            zIndex: 10,
+            top: '100%',
+            left: 0,
+            right: 0,
+            marginTop: 4,
+            maxHeight: 240,
+            overflowY: 'auto',
+            padding: 4,
+            borderRadius: 'var(--d0nj-radius-sm, 4px)',
+            border: '1px solid var(--dsw-alias-border-l2)',
+            // A popup over arbitrary content cannot inherit the surface behind it, so
+            // it paints the module fill; only the element's own list uses this literal.
+            background: 'var(--dsw-alias-bg-module-platform, var(--dsw-alias-bg-layer-1))',
+            boxShadow: 'var(--dsw-elevation-lv2, 0 4px 12px rgba(0, 0, 0, 0.2))',
+        },
+        option: {
+            padding: '4px 6px',
+            borderRadius: 'var(--d0nj-radius-sm, 4px)',
+            fontSize: 12,
+            color: 'var(--dsw-alias-label-primary)',
+            cursor: 'pointer',
+            whiteSpace: 'nowrap',
+            overflow: 'hidden',
+            textOverflow: 'ellipsis',
+        },
+        optionActive: { background: 'var(--dsw-alias-interactive-bg-hover, var(--dsw-alias-bg-layer-2))' },
         colorInput: {
             width: 34,
             height: 26,
@@ -121,6 +163,41 @@ function styles() {
         row2: { display: 'flex', gap: 8, alignItems: 'center', flexWrap: 'wrap' },
     };
 }
+/**
+ * Combobox state per role.
+ *
+ * Kept at module scope because the panel re-renders on every settings echo, and
+ * state created inside the render would reset to closed each pass.
+ */
+const combos = new Map();
+/** Exported so tests do not inherit an open list between cases. */
+export function resetCombos() {
+    combos.clear();
+}
+/**
+ * @param key - the role's accessible label.
+ * @returns the state for that role, created on first use.
+ */
+function comboState(key) {
+    const existing = combos.get(key);
+    if (existing !== undefined)
+        return existing;
+    const created = { open: false, query: '', active: 0 };
+    combos.set(key, created);
+    return created;
+}
+/**
+ * Fonts offered by the picker.
+ *
+ * Hosted rather than local: a browser cannot enumerate installed fonts without a
+ * permission-gated API most lack, and a local family looks different elsewhere.
+ */
+let fontChoiceCache;
+/** @returns the families the picker offers. */
+function fontChoices() {
+    fontChoiceCache ??= hostedFamilies();
+    return fontChoiceCache;
+}
 /**
  * Render the Theme Studio page.
  *
@@ -143,6 +220,127 @@ export function ThemeStudio(React, props) {
     const [localTokens, setLocalTokens] = React.useState({});
     const [localGeometry, setLocalGeometry] = React.useState(state.geometry);
     const [localTypography, setLocalTypography] = React.useState(state.typography);
+    // The counter must keep changing: writing the same number makes React bail out.
+    const [renderTick, setRender] = React.useState(0);
+    const choices = fontChoices();
+    const rerender = () => setRender(renderTick + 1);
+    /**
+     * @param role - font role being changed.
+     * @param value - CSS stack to apply.
+     */
+    const applyFont = (role, value) => {
+        const hosted = findHostedFont(value);
+        if (hosted === undefined) {
+            actions.setFont(role, value);
+            return;
+        }
+        void loadHostedFont(hosted).then(() => actions.setFont(role, value));
+    };
+    /**
+     * @param ariaLabel - accessible name for the input.
+     * @param family - current stack.
+     * @param onChange - writes the chosen stack.
+     * @returns the combobox element.
+     */
+    const fontCombo = (ariaLabel, family, onChange) => {
+        const combo = comboState(ariaLabel);
+        // Not the word "Default", which could collide with a family of that name.
+        const DEFAULT_CHOICE = '\u0000default';
+        const isDefault = (choice) => choice === DEFAULT_CHOICE;
+        const matches = () => {
+            const query = combo.query.trim().toLowerCase();
+            if (query === '')
+                return [DEFAULT_CHOICE, ...choices.slice(0, 39)];
+            const filtered = choices.filter((choice) => choice.toLowerCase().includes(query));
+            const keepDefault = 'default (built-in)'.includes(query) || 'built-in'.includes(query);
+            return (keepDefault ? [DEFAULT_CHOICE, ...filtered] : filtered).slice(0, 40);
+        };
+        const commit = (value) => {
+            combo.open = false;
+            combo.query = '';
+            combo.active = 0;
+            const next = isDefault(value) ? '' : value;
+            if (next !== combo.written)
+                onChange(next);
+            combo.written = undefined;
+            rerender();
+        };
+        const visible = combo.open ? matches() : [];
+        return h('div', { style: s.combo }, h('input', {
+            type: 'text',
+            role: 'combobox',
+            style: s.select,
+            'aria-label': ariaLabel,
+            'aria-expanded': combo.open,
+            'aria-autocomplete': 'list',
+            placeholder: 'Default (built-in stack)',
+            value: family,
+            onFocus: (event) => {
+                combo.open = true;
+                combo.query = '';
+                combo.active = 0;
+                event.target.select?.();
+                rerender();
+            },
+            onInput: (event) => {
+                combo.open = true;
+                combo.query = event.target.value;
+                combo.active = 0;
+                combo.written = event.target.value;
+                onChange(event.target.value);
+                rerender();
+            },
+            onKeyDown: (event) => {
+                const list = visible;
+                if (event.key === 'Escape') {
+                    combo.open = false;
+                    combo.query = '';
+                    rerender();
+                    return;
+                }
+                if (event.key === 'ArrowDown' && list.length > 0) {
+                    event.preventDefault();
+                    combo.active = (combo.active + 1) % list.length;
+                    rerender();
+                    return;
+                }
+                if (event.key === 'ArrowUp' && list.length > 0) {
+                    event.preventDefault();
+                    combo.active = (combo.active - 1 + list.length) % list.length;
+                    rerender();
+                    return;
+                }
+                if (event.key === 'Enter') {
+                    const picked = list[combo.active];
+                    if (combo.open && picked !== undefined)
+                        commit(picked);
+                    else if (combo.open && combo.query.trim() !== '')
+                        commit(combo.query.trim());
+                }
+            },
+            onBlur: () => {
+                combo.open = false;
+                combo.query = '';
+                rerender();
+            },
+        }), combo.open && visible.length > 0
+            ? h('div', { style: s.listbox, role: 'listbox' }, ...visible.map((choice, index) => h('div', {
+                key: choice,
+                role: 'option',
+                'aria-selected': index === combo.active,
+                style: {
+                    ...s.option,
+                    ...(isDefault(choice) ? {} : { fontFamily: `"${choice}"` }),
+                    ...(index === combo.active ? s.optionActive : {}),
+                },
+                // Fires before the input's blur, which would close the list first.
+                onMouseDown: (event) => {
+                    event.preventDefault();
+                    commit(choice);
+                },
+            }, isDefault(choice) ? 'Default (built-in stack)' : choice)))
+            : null);
+    };
     /** The preset currently selected, for filling a missing mode from its colours. */
     const basePreset = presets.find((preset) => preset.id === (localPreset ?? state.basePreset));
     /**
@@ -238,31 +436,27 @@ export function ThemeStudio(React, props) {
             },
         }, 'Reset')));
     });
-    const fontRow = (role, label, family, size) => h('div', { style: s.row }, h('div', { style: s.rowLabel }, h('span', { style: { fontSize: 12, fontWeight: 600 } }, label)), h('input', {
-        style: { ...s.input, width: 260 },
-        type: 'text',
-        'aria-label': `${label} font stack`,
-        placeholder: 'Font family, fallback, sans-serif',
-        value: family,
-        onChange: (event) => {
+    const fontRow = (role, label, family, size) => {
+        const edit = (value) => {
             const key = role === 'text' ? 'textFontFamily' : role === 'code' ? 'codeFontFamily' : 'terminalFontFamily';
-            setLocalTypography({ ...(localTypography ?? state.typography), [key]: event.target.value });
-            actions.setFont(role, event.target.value);
-        },
-    }), h('div', { style: s.row2 }, h('input', {
-        style: s.input,
-        type: 'number',
-        min: 8,
-        max: 24,
-        'aria-label': `${label} size`,
-        value: size,
-        onChange: (event) => {
-            const px = Number(event.target.value);
-            const key = role === 'text' ? 'fontSize' : role === 'code' ? 'codeFontSize' : 'terminalFontSize';
-            setLocalTypography({ ...(localTypography ?? state.typography), [key]: px });
-            actions.setFontSize(role, px);
-        },
-    }), h('span', { style: s.hint }, 'px')));
+            setLocalTypography({ ...(localTypography ?? state.typography), [key]: value });
+            applyFont(role, value);
+        };
+        return h('div', { style: { ...s.row, ...s.fontRow } }, h('div', { style: s.rowLabel }, h('span', { style: { fontSize: 12, fontWeight: 600 } }, label)), fontCombo(`${label} font family`, family, edit), h('div', { style: s.row2 }, h('input', {
+            style: s.input,
+            type: 'number',
+            min: 8,
+            max: 24,
+            'aria-label': `${label} size`,
+            value: size,
+            onChange: (event) => {
+                const px = Number(event.target.value);
+                const key = role === 'text' ? 'fontSize' : role === 'code' ? 'codeFontSize' : 'terminalFontSize';
+                setLocalTypography({ ...(localTypography ?? state.typography), [key]: px });
+                actions.setFontSize(role, px);
+            },
+        }), h('span', { style: s.hint }, 'px')));
+    };
     return h('div', { style: s.root }, state.writable
         ? null
         : h('div', { style: s.warning }, 'This profile does not accept settings writes; changes will not persist.'), h('section', { style: s.section }, h('h3', { style: s.heading }, 'Base theme'), h('p', { style: s.hint }, 'A preset supplies a complete token set. Tune individual values below it.'), h('div', { style: s.grid }, presetCards)), h('section', { style: s.section }, h('h3', { style: s.heading }, 'Live preview'), h('div', { style: s.preview }, h('span', { style: { fontSize: 15, fontWeight: 600 } }, 'The quick brown fox'), h('span', { style: { fontSize: 12, color: 'var(--dsw-alias-label-secondary)' } }, 'Secondary text sits one step down.'), h('div', { style: s.row2 }, h('span', { style: { ...s.button, background: 'var(--dsw-alias-brand-primary)', color: 'var(--dsw-alias-bg-base)' } }, 'Accent'), h('span', { style: { ...s.button, borderColor: 'var(--dsw-alias-state-error-primary)' } }, 'Error'), h('span', { style: { ...s.button, borderColor: 'var(--dsw-alias-state-success-primary)' } }, 'Success'), h('span', { style: { ...s.button, borderColor: 'var(--dsw-alias-state-warn-primary)' } }, 'Warning')))), h('section', { style: s.section }, h('h3', { style: s.heading }, 'Typography'), fontRow('text', 'Interface text', (localTypography ?? state.typography).textFontFamily, (localTypography ?? state.typography).fontSize), fontRow('code', 'Code', (localTypography ?? state.typography).codeFontFamily, (localTypography ?? state.typography).codeFontSize), fontRow('terminal', 'Terminal', (localTypography ?? state.typography).terminalFontFamily, (localTypography ?? state.typography).terminalFontSize)), h('section', { style: s.section }, h('h3', { style: s.heading }, 'Geometry'), h('div', { style: s.row }, h('div', { style: s.rowLabel }, h('span', { style: { fontSize: 12, fontWeight: 600 } }, 'Corner radius')), h('input', {

package/dist/index.d.ts

@@ -26,18 +26,11 @@ export declare const inject: readonly [];
  * naming a preset from a newer version must not stop the plugin mounting.
  */
 export declare const Config: ReturnType<typeof z.object>;
-/**
- * The resolved config value.
- *
- * Fields are mutable and optional where the schema supplies defaults, matching
- * what `z.object` produces; nothing in this package mutates them.
- */
 /**
  * The parsed shape of this plugin's config.
  *
- * Each field is olatile in the schema, so the Host hands pply a
- * Volatile reference for it rather than a plain value; {@link toDocument}
- * unwraps either form.
+ * Each field is volatile in the schema, so the Host hands `apply` a Volatile
+ * reference rather than a plain value; {@link toDocument} unwraps either form.
  */
 export interface PluginConfig {
     basePreset?: string;
@@ -71,10 +64,8 @@ export declare function toDocument(input: unknown): CustomizationDocument;
 /**
  * Host plugin body.
  *
- * The Host contributes no runtime behavior: the browser half owns the theme
- * override layer, and the settings service owns persistence. Returning nothing
- * keeps the mount a pure configuration declaration, so a profile can hold this
- * row without this process doing any work per session.
+ * The Host contributes nothing at runtime: the browser half owns the theme
+ * layer and fonts, and the settings service owns persistence.
  */
 export declare function apply(): void;
 export { PRESETS, TOKEN_SPECS, TOKEN_GROUPS, PRESET_IDS } from './spec.js';

package/dist/index.js

@@ -132,10 +132,8 @@ export function toDocument(input) {
 /**
  * Host plugin body.
  *
- * The Host contributes no runtime behavior: the browser half owns the theme
- * override layer, and the settings service owns persistence. Returning nothing
- * keeps the mount a pure configuration declaration, so a profile can hold this
- * row without this process doing any work per session.
+ * The Host contributes nothing at runtime: the browser half owns the theme
+ * layer and fonts, and the settings service owns persistence.
  */
 export function apply() { }
 export { PRESETS, TOKEN_SPECS, TOKEN_GROUPS, PRESET_IDS } from './spec.js';

package/dist/resolve.d.ts

@@ -100,6 +100,11 @@ export declare function correctFontSize(role: FontRole, px: number): number;
  * @returns true for a known density.
  */
 export declare function isDensity(value: string): value is Density;
+/**
+ * @param stack - comma-separated font stack.
+ * @returns the concrete family names, in order, without generics.
+ */
+export declare function familyNames(stack: string): string[];
 /**
  * Resolve a customization document into theme tokens and typography.
  *

package/dist/resolve.js

@@ -17,6 +17,13 @@
 import { DENSITIES, FONT_SIZE_RANGES, RADIUS_MAX, RADIUS_MIN, TOKEN_NAMES, findPreset, tokenSpec, } from './spec.js';
 /** A colour in one of the forms the theme service and browsers accept. */
 const COLOR_PATTERN = /^(#(?:[0-9a-f]{3}|[0-9a-f]{4}|[0-9a-f]{6}|[0-9a-f]{8})|(?:rgb|hsl|oklch|lab|lch|color)\([^)]*\)|[a-z]+)$/iu;
+/** CSS generic families, which always resolve and so never need a local match. */
+const GENERIC_FAMILIES = new Set([
+    'serif', 'sans-serif', 'monospace', 'cursive', 'fantasy', 'system-ui',
+    'ui-serif', 'ui-sans-serif', 'ui-monospace', 'ui-rounded', 'emoji', 'math',
+    'fangsong', '-apple-system', 'blinkmacsystemfont',
+    'inherit', 'initial', 'unset',
+]);
 /**
  * Whether a value is a plausible CSS colour.
  *
@@ -85,6 +92,16 @@ export function correctFontSize(role, px) {
 export function isDensity(value) {
     return DENSITIES.includes(value);
 }
+/**
+ * @param stack - comma-separated font stack.
+ * @returns the concrete family names, in order, without generics.
+ */
+export function familyNames(stack) {
+    return stack
+        .split(',')
+        .map((part) => part.trim().replace(/^["']|["']$/gu, '').trim())
+        .filter((name) => name !== '' && !GENERIC_FAMILIES.has(name.toLowerCase()));
+}
 /**
  * Resolve a customization document into theme tokens and typography.
  *

package/icon.svg

@@ -1,15 +1,15 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" role="img" aria-label="Theme Studio">
-  <defs>
-    <linearGradient id="paint" x1="0" y1="0" x2="1" y2="1">
-      <stop offset="0" stop-color="#8b5cf6"/>
-      <stop offset="0.5" stop-color="#3f8cff"/>
-      <stop offset="1" stop-color="#22c7a9"/>
-    </linearGradient>
-  </defs>
-  <rect x="6" y="6" width="52" height="52" rx="12" fill="none" stroke="url(#paint)" stroke-width="2.6"/>
-  <path d="M32 16a16 16 0 1 0 0 32a16 16 0 1 0 0-32" fill="none" stroke="url(#paint)" stroke-width="2.2" opacity="0.55"/>
-  <circle cx="32" cy="32" r="6.5" fill="url(#paint)"/>
-  <circle cx="32" cy="14" r="3.6" fill="#8b5cf6"/>
-  <circle cx="48" cy="40" r="3.6" fill="#3f8cff"/>
-  <circle cx="16" cy="40" r="3.6" fill="#22c7a9"/>
-</svg>
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" role="img" aria-label="Theme Studio">
+  <defs>
+    <linearGradient id="paint" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0" stop-color="#8b5cf6"/>
+      <stop offset="0.5" stop-color="#3f8cff"/>
+      <stop offset="1" stop-color="#22c7a9"/>
+    </linearGradient>
+  </defs>
+  <rect x="6" y="6" width="52" height="52" rx="12" fill="none" stroke="url(#paint)" stroke-width="2.6"/>
+  <path d="M32 16a16 16 0 1 0 0 32a16 16 0 1 0 0-32" fill="none" stroke="url(#paint)" stroke-width="2.2" opacity="0.55"/>
+  <circle cx="32" cy="32" r="6.5" fill="url(#paint)"/>
+  <circle cx="32" cy="14" r="3.6" fill="#8b5cf6"/>
+  <circle cx="48" cy="40" r="3.6" fill="#3f8cff"/>
+  <circle cx="16" cy="40" r="3.6" fill="#22c7a9"/>
+</svg>

package/locale/en.json

@@ -1,6 +1,6 @@
-{
-  "meta": {
-    "title": "Theme Studio",
-    "description": "Customize the Web UI's colours, fonts, spacing and corner radius, with presets in the style of popular editor themes and a live editor for individual colour tokens."
-  }
-}
+{
+  "meta": {
+    "title": "Theme Studio",
+    "description": "Customize the Web UI's colours, fonts, spacing and corner radius, with presets in the style of popular editor themes and a live editor for individual colour tokens."
+  }
+}

package/locale/zh.json

@@ -1,6 +1,6 @@
-{
-  "meta": {
-    "title": "主题工作室",
-    "description": "自定义 Web 界面的配色、字体、间距与圆角，内置多款流行编辑器风格预设，并可逐项微调颜色令牌。"
-  }
-}
+{
+  "meta": {
+    "title": "主题工作室",
+    "description": "自定义 Web 界面的配色、字体、间距与圆角，内置多款流行编辑器风格预设，并可逐项微调颜色令牌。"
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@d0nj/dsh-ui-custom",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Theme, colour-token, typography and geometry customisation for the DeepSeek Harness Web UI, with presets and a live editor.",
   "license": "MIT",
   "repository": {