@svgrid/grid 1.2.22 → 1.2.24

package/dist/createCalendar.svelte.js

@@ -0,0 +1,402 @@
+/**
+ * createCalendar - the HEADLESS core behind <SvCalendar>, in the same spirit as
+ * `createListbox` / `createSvGrid`: a runes-based state machine (view page +
+ * drill level, roving focus, every Smart `selectionMode`, range hover preview,
+ * full keyboard) with **prop-getters** you spread onto YOUR OWN markup. No
+ * styles, no DOM assumptions. It reuses the framework-free date engine in
+ * ./datetime for all the actual date math / selection / restriction, so this
+ * file only owns the reactive component-level state + interaction wiring.
+ *
+ * ```svelte
+ * <script lang="ts">
+ *   import { createCalendar } from '@svgrid/grid'
+ *   let value = $state<Date | null>(new Date())
+ *   const cal = createCalendar({ value: () => value, onChange: (d) => (value = d[0] ?? null) })
+ * </script>
+ * <div {...cal.gridProps()}>
+ *   {#each cal.panels[0].matrix as week}
+ *     {#each week as cell}
+ *       <button {...cal.dayProps(cell, cal.panels[0].month)}>{cell.date.getDate()}</button>
+ *     {/each}
+ *   {/each}
+ * </div>
+ * ```
+ *
+ * The styled <SvCalendar> is one renderer over this core; it keeps the render-only
+ * concerns (WAAPI view-change animation, mouse-wheel navigation, DOM refs) itself.
+ */
+import { addDays, addMonths, addYears, monthMatrix, weekdayOrder, startOfDay, isSameDay, isSameMonth, toDate, decadeRange, } from './datetime/date-core';
+import { selectDate, isSelected, rangeDays, emptySelection, } from './datetime/date-selection';
+import { isDisabledDay, isImportant } from './datetime/date-restrict';
+const defaultLocale = () => (typeof navigator !== 'undefined' ? navigator.language : 'en-US');
+/** Normalize a calendar value to an ordered day-midnight list (pure). */
+export function normalizeCalendarValue(v) {
+    if (v == null)
+        return [];
+    const list = Array.isArray(v) ? v : [v];
+    const out = [];
+    for (const item of list) {
+        const d = toDate(item);
+        if (d)
+            out.push(startOfDay(d));
+    }
+    return out;
+}
+export function createCalendar(config) {
+    // --- Config accessors (with the same defaults as the styled component) ------
+    const selectionMode = () => config.selectionMode?.() ?? 'one';
+    const firstDayOfWeek = () => config.firstDayOfWeek?.() ?? 0;
+    const weeksCount = () => config.weeks?.() ?? 6;
+    const monthsCount = () => Math.max(1, config.months?.() ?? 1);
+    const displayMode = () => config.displayMode?.() ?? 'month';
+    const isDisabled = () => config.disabled?.() ?? false;
+    const isReadonly = () => config.readonly?.() ?? false;
+    const locale = () => config.locale?.() ?? defaultLocale();
+    const dayNameFormat = () => config.dayNameFormat?.() ?? 'short';
+    const monthNameFormat = () => config.monthNameFormat?.() ?? 'long';
+    // --- Internal reactive state ------------------------------------------------
+    // Seeded from `value`; range mode also tracks a pending rangeStart between the
+    // two clicks, which `value` alone cannot hold.
+    let sel = $state(emptySelection());
+    // The month currently shown (first panel) + the drill level.
+    let view = $state(startOfDay(new Date()));
+    let mode = $state('month');
+    // Roving focus + range hover preview.
+    let focusDate = $state(startOfDay(new Date()));
+    let hoverDate = $state(null);
+    // View-change animation is a render concern that lives in the styled
+    // component; the core only records why the view changed and bumps a token so
+    // the component can replay a keyframe on the fresh DOM.
+    let navDir = 'fade';
+    let navToken = $state(0);
+    const restrict = $derived({
+        min: config.min?.() ?? null,
+        max: config.max?.() ?? null,
+        restrictedDates: config.restrictedDates?.() ?? null,
+    });
+    const isInteractive = $derived(!isDisabled() && !isReadonly());
+    // --- Value sync + one-time seed of the visible page ------------------------
+    let lastSyncedKey = '￿'; // sentinel so the first sync always fires (incl. null value)
+    let seeded = false;
+    $effect(() => {
+        const dates = normalizeCalendarValue(config.value());
+        const key = dates.map((d) => d.getTime()).join(',');
+        if (key !== lastSyncedKey) {
+            lastSyncedKey = key;
+            sel = { dates, anchor: dates[dates.length - 1] ?? null, rangeStart: null };
+            if (!seeded) {
+                seeded = true;
+                const first = dates[0] ?? startOfDay(new Date());
+                view = startOfDay(first);
+                focusDate = startOfDay(first);
+                mode = displayMode();
+            }
+        }
+    });
+    // --- Intl-driven labels (cached by the browser) ----------------------------
+    const weekdayFmt = $derived(new Intl.DateTimeFormat(locale(), { weekday: dayNameFormat() }));
+    const monthTitleFmt = $derived(new Intl.DateTimeFormat(locale(), { month: monthNameFormat(), year: 'numeric' }));
+    const monthShortFmt = $derived(new Intl.DateTimeFormat(locale(), { month: 'short' }));
+    const fullDateFmt = $derived(new Intl.DateTimeFormat(locale(), { weekday: 'long', year: 'numeric', month: 'long', day: 'numeric' }));
+    const weekdayHeaders = $derived(weekdayOrder(firstDayOfWeek()).map((wd) => {
+        // 2021-08-01 is a Sunday; offset to the requested weekday.
+        const d = new Date(2021, 7, 1 + wd);
+        return { label: weekdayFmt.format(d), weekday: wd };
+    }));
+    /** The month grids to render (1..months panels), each with its own title. */
+    const panels = $derived(Array.from({ length: monthsCount() }, (_, i) => {
+        const panelMonth = addMonths(view, i);
+        return { month: panelMonth, title: monthTitleFmt.format(panelMonth), matrix: monthMatrix(panelMonth, firstDayOfWeek(), weeksCount()) };
+    }));
+    // Range preview: while a range is pending (or being hovered), show the band.
+    const previewRange = $derived.by(() => {
+        if (selectionMode() !== 'range')
+            return null;
+        const start = sel.rangeStart;
+        if (!start || !hoverDate)
+            return null;
+        return rangeDays(start, hoverDate);
+    });
+    const inPreview = (d) => !!previewRange && previewRange.some((p) => isSameDay(p, d));
+    function dayState(d, panelMonth) {
+        return {
+            disabled: isDisabledDay(d, restrict),
+            selected: isSelected(sel.dates, d),
+            important: isImportant(d, config.importantDates?.() ?? null),
+            today: isSameDay(d, new Date()),
+            outside: !isSameMonth(d, panelMonth),
+            focused: isSameDay(d, focusDate),
+            preview: inPreview(d),
+        };
+    }
+    const title = $derived(mode === 'month'
+        ? monthTitleFmt.format(view)
+        : mode === 'year'
+            ? String(view.getFullYear())
+            : (() => {
+                const { start, end } = decadeRange(view.getFullYear());
+                return `${start} - ${end}`;
+            })());
+    // Year-mode cells (12 months) and decade-mode cells (10 years + 2 padding).
+    const yearCells = $derived(Array.from({ length: 12 }, (_, m) => ({
+        index: m,
+        label: monthShortFmt.format(new Date(view.getFullYear(), m, 1)),
+        current: m === new Date().getMonth() && view.getFullYear() === new Date().getFullYear(),
+        selected: sel.dates.some((d) => d.getMonth() === m && d.getFullYear() === view.getFullYear()),
+    })));
+    const decadeCells = $derived.by(() => {
+        const { start } = decadeRange(view.getFullYear());
+        return Array.from({ length: 12 }, (_, i) => {
+            const year = start - 1 + i;
+            return {
+                year,
+                outside: i === 0 || i === 11,
+                current: year === new Date().getFullYear(),
+                selected: sel.dates.some((d) => d.getFullYear() === year),
+            };
+        });
+    });
+    const canClear = $derived(selectionMode() === 'zeroOrOne' || selectionMode() === 'zeroOrMany' || selectionMode() === 'none');
+    // --- Actions ---------------------------------------------------------------
+    function commit(next) {
+        sel = next;
+        lastSyncedKey = next.dates.map((x) => x.getTime()).join(',');
+        config.onChange?.(next.dates.map((x) => new Date(x.getTime())));
+    }
+    function pickDay(d, e) {
+        if (!isInteractive || isDisabledDay(d, restrict))
+            return;
+        focusDate = startOfDay(d);
+        commit(selectDate(sel, d, selectionMode(), { ctrl: e?.ctrlKey || e?.metaKey, shift: e?.shiftKey }, firstDayOfWeek()));
+    }
+    function setView(next, nextMode = mode) {
+        view = startOfDay(next);
+        mode = nextMode;
+        navToken++; // signal the styled component to replay the view-change animation
+        config.onNavigate?.(view, mode);
+    }
+    function drillUp() {
+        navDir = 'drillUp';
+        if (mode === 'month')
+            setView(view, 'year');
+        else if (mode === 'year')
+            setView(view, 'decade');
+    }
+    function step(dir) {
+        navDir = dir === 1 ? 'next' : 'prev';
+        if (mode === 'month')
+            setView(addMonths(view, dir));
+        else if (mode === 'year')
+            setView(addYears(view, dir));
+        else
+            setView(addYears(view, dir * 10));
+    }
+    function pickMonth(monthIndex) {
+        navDir = 'drillDown';
+        setView(new Date(view.getFullYear(), monthIndex, 1), 'month');
+        focusDate = new Date(view.getFullYear(), monthIndex, Math.min(focusDate.getDate(), 28));
+    }
+    function pickYear(year) {
+        navDir = 'drillDown';
+        setView(new Date(year, view.getMonth(), 1), 'year');
+    }
+    function goToday() {
+        navDir = 'fade';
+        const t = new Date();
+        setView(t, 'month');
+        focusDate = startOfDay(t);
+        if (isInteractive)
+            pickDay(t);
+    }
+    const startOfMonthSafe = (d) => new Date(d.getFullYear(), d.getMonth(), 1);
+    function applyPreset(p) {
+        if (!isInteractive)
+            return;
+        const resolved = typeof p.value === 'function' ? p.value() : p.value;
+        const isRange = Array.isArray(resolved);
+        const pair = (isRange ? resolved : [resolved, resolved]);
+        const start = toDate(pair[0]);
+        const end = toDate(pair[1]);
+        if (!start)
+            return;
+        focusDate = startOfDay(start);
+        navDir = 'fade';
+        view = startOfMonthSafe(start);
+        navToken++;
+        if (isRange && end) {
+            commit({ dates: rangeDays(start, end), anchor: startOfDay(end), rangeStart: null });
+        }
+        else {
+            commit({ dates: [startOfDay(start)], anchor: startOfDay(start), rangeStart: null });
+        }
+    }
+    function clearSelection() {
+        if (!isInteractive)
+            return;
+        commit(emptySelection());
+    }
+    const setHover = (d) => (hoverDate = d);
+    // --- Keyboard --------------------------------------------------------------
+    function onNonMonthKeydown(e) {
+        if (e.key === 'Enter' || e.key === ' ') {
+            e.preventDefault();
+            if (mode === 'year')
+                pickMonth(focusDate.getMonth());
+            else
+                pickYear(focusDate.getFullYear());
+        }
+    }
+    function onKeydown(e) {
+        if (mode !== 'month')
+            return onNonMonthKeydown(e);
+        let next = null;
+        switch (e.key) {
+            case 'ArrowLeft':
+                next = addDays(focusDate, -1);
+                break;
+            case 'ArrowRight':
+                next = addDays(focusDate, 1);
+                break;
+            case 'ArrowUp':
+                next = addDays(focusDate, -7);
+                break;
+            case 'ArrowDown':
+                next = addDays(focusDate, 7);
+                break;
+            case 'Home':
+                next = addDays(focusDate, -((focusDate.getDay() - firstDayOfWeek() + 7) % 7));
+                break;
+            case 'End':
+                next = addDays(focusDate, 6 - ((focusDate.getDay() - firstDayOfWeek() + 7) % 7));
+                break;
+            case 'PageUp':
+                next = e.shiftKey ? addYears(focusDate, -1) : addMonths(focusDate, -1);
+                break;
+            case 'PageDown':
+                next = e.shiftKey ? addYears(focusDate, 1) : addMonths(focusDate, 1);
+                break;
+            case 'Enter':
+            case ' ':
+                e.preventDefault();
+                pickDay(focusDate, e);
+                return;
+            default:
+                return;
+        }
+        if (next) {
+            e.preventDefault();
+            focusDate = startOfDay(next);
+            if (!isSameMonth(focusDate, view))
+                setView(focusDate, 'month');
+        }
+    }
+    return {
+        // --- Reactive state -------------------------------------------------------
+        get view() { return view; },
+        get mode() { return mode; },
+        get title() { return title; },
+        get panels() { return panels; },
+        get weekdayHeaders() { return weekdayHeaders; },
+        get yearCells() { return yearCells; },
+        get decadeCells() { return decadeCells; },
+        get selectedDates() { return sel.dates; },
+        get previewRange() { return previewRange; },
+        get focusDate() { return focusDate; },
+        get hoverDate() { return hoverDate; },
+        get canClear() { return canClear; },
+        get isInteractive() { return isInteractive; },
+        /** Increments on every view/drill change; the styled component watches it to
+         *  replay its WAAPI animation on the updated DOM. */
+        get navToken() { return navToken; },
+        /** Why the view last changed (read untracked from the animation effect). */
+        get navDir() { return navDir; },
+        // --- Derived helpers ------------------------------------------------------
+        dayState,
+        inPreview,
+        formatFullDate: (d) => fullDateFmt.format(d),
+        formatMonthTitle: (d) => monthTitleFmt.format(d),
+        // --- Actions --------------------------------------------------------------
+        pickDay,
+        step,
+        drillUp,
+        pickMonth,
+        pickYear,
+        goToday,
+        applyPreset,
+        clearSelection,
+        setHover,
+        onKeydown,
+        // --- Prop-getters (spread onto YOUR markup) -------------------------------
+        /** Previous / Next navigation button. */
+        navProps(dir) {
+            return {
+                type: 'button',
+                disabled: isDisabled(),
+                'aria-label': dir === 1 ? 'Next' : 'Previous',
+                onclick: () => step(dir),
+            };
+        },
+        /** The centered title button that drills up (month -> year -> decade). */
+        titleProps() {
+            return {
+                type: 'button',
+                disabled: isDisabled() || mode === 'decade',
+                'aria-live': 'polite',
+                onclick: drillUp,
+            };
+        },
+        /** The grid container: keyboard + ARIA. Works for month, year and decade
+         *  modes (the handler dispatches on the current mode). */
+        gridProps() {
+            return {
+                role: 'grid',
+                'aria-label': title,
+                tabindex: -1,
+                onkeydown: onKeydown,
+            };
+        },
+        /** A single day button in the month grid. Combine with `dayState` for the
+         *  visual class flags. */
+        dayProps(cell, panelMonth) {
+            const st = dayState(cell.date, panelMonth);
+            return {
+                type: 'button',
+                role: 'gridcell',
+                'aria-selected': st.selected,
+                'aria-disabled': st.disabled,
+                'aria-current': st.today ? 'date' : undefined,
+                'aria-label': fullDateFmt.format(cell.date),
+                title: config.dateTooltip?.()?.(cell.date) ?? undefined,
+                tabindex: st.focused ? 0 : -1,
+                disabled: st.disabled || isDisabled(),
+                onclick: (e) => pickDay(cell.date, e),
+                onpointerenter: () => setHover(cell.date),
+                onpointerleave: () => setHover(null),
+            };
+        },
+        /** A month cell in year mode. */
+        monthCellProps(monthIndex) {
+            return {
+                type: 'button',
+                disabled: isDisabled(),
+                onclick: () => pickMonth(monthIndex),
+            };
+        },
+        /** A year cell in decade mode. */
+        yearCellProps(year) {
+            return {
+                type: 'button',
+                disabled: isDisabled(),
+                onclick: () => pickYear(year),
+            };
+        },
+        /** A preset shortcut button. */
+        presetProps(preset) {
+            return {
+                type: 'button',
+                disabled: !isInteractive,
+                onclick: () => applyPreset(preset),
+            };
+        },
+    };
+}

package/dist/createCheckbox.svelte.d.ts

@@ -0,0 +1,45 @@
+/**
+ * createCheckbox - the HEADLESS core behind <SvCheckBox>: a controlled tri-state
+ * checkbox (checked / unchecked / indeterminate, ARIA `checkbox` with
+ * `aria-checked="mixed"`), exposed as **prop-getters** you spread onto YOUR OWN
+ * markup. A native <button> supplies Space/Enter activation.
+ *
+ * ```svelte
+ * <script lang="ts">
+ *   import { createCheckbox } from '@svgrid/grid'
+ *   let checked = $state(false)
+ *   const cb = createCheckbox({ checked: () => checked, onChange: (v) => (checked = v) })
+ * </script>
+ * <button {...cb.boxProps()}>{cb.checked ? '✓' : ''}</button>
+ * ```
+ *
+ * The styled <SvCheckBox> is just one renderer over this core.
+ */
+export type CheckboxConfig = {
+    checked: () => boolean;
+    indeterminate?: () => boolean;
+    onChange?: (checked: boolean) => void;
+    disabled?: () => boolean;
+    ariaLabel?: () => string | undefined;
+};
+export type CheckboxBoxProps = {
+    type: 'button';
+    role: 'checkbox';
+    'aria-checked': boolean | 'mixed';
+    'aria-label': string | undefined;
+    disabled: boolean;
+    'data-checked': '' | undefined;
+    'data-indeterminate': '' | undefined;
+    onclick: () => void;
+};
+export type Checkbox = {
+    /** True only when fully checked (never in the indeterminate state). */
+    readonly checked: boolean;
+    readonly indeterminate: boolean;
+    readonly disabled: boolean;
+    /** Indeterminate resolves to checked; otherwise flips checked. */
+    toggle: () => void;
+    /** Spread onto the checkbox element. */
+    boxProps: () => CheckboxBoxProps;
+};
+export declare function createCheckbox(config: CheckboxConfig): Checkbox;

package/dist/createCheckbox.svelte.js

@@ -0,0 +1,26 @@
+export function createCheckbox(config) {
+    const checked = () => config.checked();
+    const indeterminate = () => config.indeterminate?.() ?? false;
+    const disabled = () => config.disabled?.() ?? false;
+    function toggle() {
+        if (disabled())
+            return;
+        config.onChange?.(indeterminate() ? true : !checked());
+    }
+    return {
+        get checked() { return checked(); },
+        get indeterminate() { return indeterminate(); },
+        get disabled() { return disabled(); },
+        toggle,
+        boxProps: () => ({
+            type: 'button',
+            role: 'checkbox',
+            'aria-checked': indeterminate() ? 'mixed' : checked(),
+            'aria-label': config.ariaLabel?.(),
+            disabled: disabled(),
+            'data-checked': checked() && !indeterminate() ? '' : undefined,
+            'data-indeterminate': indeterminate() ? '' : undefined,
+            onclick: toggle,
+        }),
+    };
+}

package/dist/createColorInput.svelte.d.ts

@@ -0,0 +1,67 @@
+/**
+ * createColorInput - the HEADLESS core behind <SvColorInput>: a runes-based
+ * state machine that owns hex normalization, the palette, the draft hex field
+ * and the open/close popover state, exposed as **prop-getters** you spread onto
+ * YOUR OWN markup. DOM measurement / portalling stays in the renderer, NOT here.
+ *
+ * ```svelte
+ * <script lang="ts">
+ *   import { createColorInput } from '@svgrid/grid'
+ *   let value = $state('#3b82f6')
+ *   const col = createColorInput({ value: () => value, onChange: (v) => (value = v) })
+ * </script>
+ * <button {...col.swatchProps()}>{col.normalized}</button>
+ * {#if col.popover.open}<div>...palette...</div>{/if}
+ * ```
+ *
+ * The styled <SvColorInput> is just one renderer over this core (it adds the
+ * portal + anchored positioning).
+ */
+export declare const DEFAULT_PALETTE: string[];
+/** Normalize a hex string (#abc / #aabbcc / abc) to lower-case #aabbcc (pure). */
+export declare function normalizeHex(h: string): string | null;
+/** Reactive inputs are passed as getters so the core tracks live prop changes. */
+export type ColorInputConfig = {
+    value: () => string;
+    onChange?: (hex: string) => void;
+    disabled?: () => boolean;
+    readonly?: () => boolean;
+    palette?: () => string[];
+    ariaLabel?: () => string | undefined;
+};
+export declare function createColorInput(config: ColorInputConfig): {
+    /** The normalized current color (#aabbcc). */
+    readonly normalized: string;
+    /** Preset swatches. */
+    readonly palette: string[];
+    /** Draft hex text for the panel field (settable for `bind:value`). */
+    hexDraft: string;
+    /** Whether interaction is allowed. */
+    readonly isInteractive: boolean;
+    /** Popover open state + open/close/toggle controls. */
+    popover: {
+        readonly open: boolean;
+        show: () => void;
+        close: () => void;
+        toggle: () => void;
+    };
+    pick: (hex: string) => void;
+    commitHex: () => void;
+    isActive: (c: string) => boolean;
+    /** Spread onto the swatch trigger button. */
+    swatchProps: () => {
+        type: "button";
+        'aria-haspopup': "dialog";
+        'aria-expanded': boolean;
+        'aria-label': string;
+        disabled: boolean;
+        onclick: () => void;
+    };
+    /** Spread onto a palette chip button for color `c`. */
+    chipProps: (c: string) => {
+        type: "button";
+        'aria-label': string;
+        onclick: () => void;
+    };
+};
+export type ColorInputCore = ReturnType<typeof createColorInput>;

package/dist/createColorInput.svelte.js

@@ -0,0 +1,100 @@
+/**
+ * createColorInput - the HEADLESS core behind <SvColorInput>: a runes-based
+ * state machine that owns hex normalization, the palette, the draft hex field
+ * and the open/close popover state, exposed as **prop-getters** you spread onto
+ * YOUR OWN markup. DOM measurement / portalling stays in the renderer, NOT here.
+ *
+ * ```svelte
+ * <script lang="ts">
+ *   import { createColorInput } from '@svgrid/grid'
+ *   let value = $state('#3b82f6')
+ *   const col = createColorInput({ value: () => value, onChange: (v) => (value = v) })
+ * </script>
+ * <button {...col.swatchProps()}>{col.normalized}</button>
+ * {#if col.popover.open}<div>...palette...</div>{/if}
+ * ```
+ *
+ * The styled <SvColorInput> is just one renderer over this core (it adds the
+ * portal + anchored positioning).
+ */
+export const DEFAULT_PALETTE = [
+    '#ef4444', '#f97316', '#f59e0b', '#eab308', '#84cc16', '#22c55e', '#10b981', '#14b8a6',
+    '#06b6d4', '#0ea5e9', '#3b82f6', '#6366f1', '#8b5cf6', '#a855f7', '#d946ef', '#ec4899',
+    '#f43f5e', '#64748b', '#0f172a', '#ffffff',
+];
+/** Normalize a hex string (#abc / #aabbcc / abc) to lower-case #aabbcc (pure). */
+export function normalizeHex(h) {
+    let s = h.trim();
+    if (!s.startsWith('#'))
+        s = '#' + s;
+    if (/^#[0-9a-fA-F]{3}$/.test(s))
+        s = '#' + s.slice(1).split('').map((c) => c + c).join('');
+    return /^#[0-9a-fA-F]{6}$/.test(s) ? s.toLowerCase() : null;
+}
+export function createColorInput(config) {
+    const disabled = () => config.disabled?.() ?? false;
+    const readonly = () => config.readonly?.() ?? false;
+    const isInteractive = $derived(!disabled() && !readonly());
+    let open = $state(false);
+    let hexDraft = $state('');
+    const normalized = $derived(normalizeHex(config.value()) ?? '#000000');
+    function openPanel() {
+        if (!isInteractive || open)
+            return;
+        hexDraft = normalized;
+        open = true;
+    }
+    function close() { open = false; }
+    function toggle() { open ? (open = false) : openPanel(); }
+    function pick(hex) {
+        const n = normalizeHex(hex);
+        if (n)
+            config.onChange?.(n);
+    }
+    function commitHex() {
+        const n = normalizeHex(hexDraft);
+        if (n)
+            config.onChange?.(n);
+        else
+            hexDraft = normalized;
+    }
+    const isActive = (c) => normalizeHex(c) === normalized;
+    // Popover control surface (open state + show/close/toggle), no DOM measurement.
+    const popover = {
+        get open() { return open; },
+        show: openPanel,
+        close,
+        toggle,
+    };
+    return {
+        /** The normalized current color (#aabbcc). */
+        get normalized() { return normalized; },
+        /** Preset swatches. */
+        get palette() { return config.palette?.() ?? DEFAULT_PALETTE; },
+        /** Draft hex text for the panel field (settable for `bind:value`). */
+        get hexDraft() { return hexDraft; },
+        set hexDraft(v) { hexDraft = v; },
+        /** Whether interaction is allowed. */
+        get isInteractive() { return isInteractive; },
+        /** Popover open state + open/close/toggle controls. */
+        popover,
+        pick,
+        commitHex,
+        isActive,
+        /** Spread onto the swatch trigger button. */
+        swatchProps: () => ({
+            type: 'button',
+            'aria-haspopup': 'dialog',
+            'aria-expanded': open,
+            'aria-label': config.ariaLabel?.() ?? `Color ${normalized}`,
+            disabled: !isInteractive,
+            onclick: toggle,
+        }),
+        /** Spread onto a palette chip button for color `c`. */
+        chipProps: (c) => ({
+            type: 'button',
+            'aria-label': c,
+            onclick: () => { pick(c); open = false; },
+        }),
+    };
+}