@svgrid/grid 1.2.23 → 1.2.24

package/dist/createAutocomplete.svelte.d.ts

@@ -0,0 +1,77 @@
+/**
+ * createAutocomplete - the HEADLESS core behind <SvAutoComplete>: a free-text
+ * field with a live-filtered suggestion list (accepts ANY typed value; the
+ * suggestions are shortcuts). Roving active index + keyboard, exposed as
+ * **prop-getters** you spread onto YOUR OWN markup. No styles/DOM/portal - those
+ * stay in the styled component.
+ *
+ * ```svelte
+ * <script lang="ts">
+ *   import { createAutocomplete } from '@svgrid/grid'
+ *   let value = $state('')
+ *   const ac = createAutocomplete({ value: () => value, suggestions: () => list, onChange: (v) => (value = v) })
+ * </script>
+ * <input {...ac.inputProps()} />
+ * {#if ac.open}
+ *   <ul {...ac.listboxProps()}>
+ *     {#each ac.filtered as opt, i (opt.value)}<li {...ac.optionProps(i)}>{opt.label}</li>{/each}
+ *   </ul>
+ * {/if}
+ * ```
+ */
+import { type ListOption } from './list-option';
+/** Reactive inputs are passed as getters so the core tracks live prop changes. */
+export type AutocompleteConfig = {
+    value: () => string;
+    onChange?: (value: string) => void;
+    /** Suggestions - strings or {value,label} (label shown, value inserted). */
+    suggestions: () => ReadonlyArray<string | ListOption>;
+    minChars?: () => number;
+    disabled?: () => boolean;
+    ariaLabel?: () => string | undefined;
+    /** DOM focus hook provided by the renderer; the core never touches the DOM. */
+    focusInput?: () => void;
+};
+export declare function createAutocomplete(config: AutocompleteConfig): {
+    /** Panel open state. */
+    readonly open: boolean;
+    /** Highlighted suggestion index into `filtered`. */
+    readonly activeIndex: number;
+    /** Suggestions after the live substring filter (capped at 10). */
+    readonly filtered: ListOption[];
+    /** Controlled text value. */
+    readonly value: string;
+    isActive: (i: number) => boolean;
+    setActive: (i: number) => void;
+    maybeOpen: () => void;
+    close: () => void;
+    pick: (o: ListOption | undefined) => void;
+    onInput: (e: Event) => void;
+    onKeydown: (e: KeyboardEvent) => void;
+    /** Spread onto the text <input>. */
+    inputProps: () => {
+        role: "combobox";
+        'aria-expanded': boolean;
+        'aria-autocomplete': "list";
+        'aria-label': string | undefined;
+        value: string;
+        disabled: boolean;
+        oninput: (e: Event) => void;
+        onfocus: () => void;
+        onkeydown: (e: KeyboardEvent) => void;
+    };
+    /** Spread onto the listbox container. */
+    listboxProps: () => {
+        role: "listbox";
+    };
+    /** Spread onto the suggestion at `index` (index into `filtered`). */
+    optionProps: (index: number) => {
+        role: "option";
+        tabindex: number;
+        'aria-selected': boolean;
+        'data-idx': number;
+        onclick: () => void;
+        onpointermove: () => void;
+    };
+};
+export type Autocomplete = ReturnType<typeof createAutocomplete>;

package/dist/createAutocomplete.svelte.js

@@ -0,0 +1,100 @@
+/**
+ * createAutocomplete - the HEADLESS core behind <SvAutoComplete>: a free-text
+ * field with a live-filtered suggestion list (accepts ANY typed value; the
+ * suggestions are shortcuts). Roving active index + keyboard, exposed as
+ * **prop-getters** you spread onto YOUR OWN markup. No styles/DOM/portal - those
+ * stay in the styled component.
+ *
+ * ```svelte
+ * <script lang="ts">
+ *   import { createAutocomplete } from '@svgrid/grid'
+ *   let value = $state('')
+ *   const ac = createAutocomplete({ value: () => value, suggestions: () => list, onChange: (v) => (value = v) })
+ * </script>
+ * <input {...ac.inputProps()} />
+ * {#if ac.open}
+ *   <ul {...ac.listboxProps()}>
+ *     {#each ac.filtered as opt, i (opt.value)}<li {...ac.optionProps(i)}>{opt.label}</li>{/each}
+ *   </ul>
+ * {/if}
+ * ```
+ */
+import { filterOptions } from './list-option';
+export function createAutocomplete(config) {
+    const minChars = () => config.minChars?.() ?? 1;
+    let open = $state(false);
+    let active = $state(0);
+    const asOptions = $derived(config.suggestions().map((s) => (typeof s === 'string' ? { value: s, label: s } : s)));
+    const filtered = $derived(config.value().length >= minChars() ? filterOptions(asOptions, config.value()).slice(0, 10) : []);
+    function maybeOpen() { open = filtered.length > 0; if (open)
+        active = 0; }
+    function pick(o) { if (!o)
+        return; config.onChange?.(String(o.value)); open = false; config.focusInput?.(); }
+    function close() { open = false; }
+    function onInput(e) { config.onChange?.(e.currentTarget.value); queueMicrotask(maybeOpen); }
+    function onKeydown(e) {
+        if (!open) {
+            if (e.key === 'ArrowDown') {
+                queueMicrotask(maybeOpen);
+            }
+            return;
+        }
+        if (e.key === 'ArrowDown') {
+            e.preventDefault();
+            active = Math.min(active + 1, filtered.length - 1);
+        }
+        else if (e.key === 'ArrowUp') {
+            e.preventDefault();
+            active = Math.max(active - 1, 0);
+        }
+        else if (e.key === 'Enter') {
+            e.preventDefault();
+            pick(filtered[active]);
+        }
+        else if (e.key === 'Escape') {
+            close();
+        }
+    }
+    return {
+        /** Panel open state. */
+        get open() { return open; },
+        /** Highlighted suggestion index into `filtered`. */
+        get activeIndex() { return active; },
+        /** Suggestions after the live substring filter (capped at 10). */
+        get filtered() { return filtered; },
+        /** Controlled text value. */
+        get value() { return config.value(); },
+        isActive: (i) => i === active,
+        setActive: (i) => { active = i; },
+        maybeOpen,
+        close,
+        pick,
+        onInput,
+        onKeydown,
+        /** Spread onto the text <input>. */
+        inputProps: () => ({
+            role: 'combobox',
+            'aria-expanded': open,
+            'aria-autocomplete': 'list',
+            'aria-label': config.ariaLabel?.(),
+            value: config.value(),
+            disabled: config.disabled?.() ?? false,
+            oninput: onInput,
+            onfocus: maybeOpen,
+            onkeydown: onKeydown,
+        }),
+        /** Spread onto the listbox container. */
+        listboxProps: () => ({
+            role: 'listbox',
+        }),
+        /** Spread onto the suggestion at `index` (index into `filtered`). */
+        optionProps: (index) => ({
+            role: 'option',
+            tabindex: -1,
+            'aria-selected': index === active,
+            'data-idx': index,
+            onclick: () => pick(filtered[index]),
+            onpointermove: () => { active = index; },
+        }),
+    };
+}

package/dist/createCalendar.svelte.d.ts

@@ -0,0 +1,192 @@
+/**
+ * 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 { type DateLike, type MonthMatrixCell } from './datetime/date-core';
+import { type SelectionMode } from './datetime/date-selection';
+import { type RestrictOptions } from './datetime/date-restrict';
+export type DisplayMode = 'month' | 'year' | 'decade';
+export type CalendarNameFormat = 'narrow' | 'short' | 'long';
+/** Selected value(s). Single Date for one/zeroOrOne, array for multi modes. */
+export type CalendarValue = Date | number | string | ReadonlyArray<Date | number | string> | null;
+/** A one-click shortcut shown in the presets rail. `value` is a single date
+ *  (or an [start, end] range for range mode); pass a function for "today"-
+ *  relative shortcuts that resolve at click time. */
+export type CalendarPreset = {
+    label: string;
+    value: Date | number | string | readonly [Date | number | string, Date | number | string] | (() => Date | number | string | readonly [Date | number | string, Date | number | string]);
+};
+/** How the calendar animates a navigation / drill (a render concern the styled
+ *  component acts on; the core only reports the direction). */
+export type CalendarAnimation = 'slide' | 'fade' | 'none';
+/** Why the visible view last changed - drives the styled component's animation. */
+export type CalendarNavDir = 'next' | 'prev' | 'drillDown' | 'drillUp' | 'fade';
+/** Per-day interaction/visual state (booleans the renderer maps to classes). */
+export type CalendarDayState = {
+    disabled: boolean;
+    selected: boolean;
+    important: boolean;
+    today: boolean;
+    outside: boolean;
+    focused: boolean;
+    preview: boolean;
+};
+/** Reactive inputs are passed as getters so the core tracks live prop changes;
+ *  callbacks are plain closures. */
+export type CalendarConfig = {
+    value: () => CalendarValue;
+    onChange?: (dates: Date[]) => void;
+    onNavigate?: (viewDate: Date, displayMode: DisplayMode) => void;
+    selectionMode?: () => SelectionMode;
+    min?: () => DateLike | null;
+    max?: () => DateLike | null;
+    restrictedDates?: () => RestrictOptions['restrictedDates'];
+    importantDates?: () => ReadonlyArray<DateLike> | ((d: Date) => boolean) | null;
+    firstDayOfWeek?: () => number;
+    weeks?: () => number;
+    months?: () => number;
+    displayMode?: () => DisplayMode;
+    disabled?: () => boolean;
+    readonly?: () => boolean;
+    locale?: () => string;
+    dayNameFormat?: () => CalendarNameFormat;
+    monthNameFormat?: () => CalendarNameFormat;
+    dateTooltip?: () => ((date: Date) => string | null | undefined) | undefined;
+};
+/** Normalize a calendar value to an ordered day-midnight list (pure). */
+export declare function normalizeCalendarValue(v: CalendarValue): Date[];
+export declare function createCalendar(config: CalendarConfig): {
+    readonly view: Date;
+    readonly mode: DisplayMode;
+    readonly title: string;
+    readonly panels: {
+        month: Date;
+        title: string;
+        matrix: MonthMatrixCell[][];
+    }[];
+    readonly weekdayHeaders: {
+        label: string;
+        weekday: number;
+    }[];
+    readonly yearCells: {
+        index: number;
+        label: string;
+        current: boolean;
+        selected: boolean;
+    }[];
+    readonly decadeCells: {
+        year: number;
+        outside: boolean;
+        current: boolean;
+        selected: boolean;
+    }[];
+    readonly selectedDates: Date[];
+    readonly previewRange: Date[] | null;
+    readonly focusDate: Date;
+    readonly hoverDate: Date | null;
+    readonly canClear: boolean;
+    readonly isInteractive: boolean;
+    /** Increments on every view/drill change; the styled component watches it to
+     *  replay its WAAPI animation on the updated DOM. */
+    readonly navToken: number;
+    /** Why the view last changed (read untracked from the animation effect). */
+    readonly navDir: CalendarNavDir;
+    dayState: (d: Date, panelMonth: Date) => CalendarDayState;
+    inPreview: (d: Date) => boolean;
+    formatFullDate: (d: Date) => string;
+    formatMonthTitle: (d: Date) => string;
+    pickDay: (d: Date, e?: {
+        ctrlKey?: boolean;
+        metaKey?: boolean;
+        shiftKey?: boolean;
+    }) => void;
+    step: (dir: -1 | 1) => void;
+    drillUp: () => void;
+    pickMonth: (monthIndex: number) => void;
+    pickYear: (year: number) => void;
+    goToday: () => void;
+    applyPreset: (p: CalendarPreset) => void;
+    clearSelection: () => void;
+    setHover: (d: Date | null) => Date | null;
+    onKeydown: (e: KeyboardEvent) => void;
+    /** Previous / Next navigation button. */
+    navProps(dir: -1 | 1): {
+        type: "button";
+        disabled: boolean;
+        'aria-label': string;
+        onclick: () => void;
+    };
+    /** The centered title button that drills up (month -> year -> decade). */
+    titleProps(): {
+        type: "button";
+        disabled: boolean;
+        'aria-live': "polite";
+        onclick: () => void;
+    };
+    /** The grid container: keyboard + ARIA. Works for month, year and decade
+     *  modes (the handler dispatches on the current mode). */
+    gridProps(): {
+        role: "grid";
+        'aria-label': string;
+        tabindex: number;
+        onkeydown: (e: KeyboardEvent) => void;
+    };
+    /** A single day button in the month grid. Combine with `dayState` for the
+     *  visual class flags. */
+    dayProps(cell: MonthMatrixCell, panelMonth: Date): {
+        type: "button";
+        role: "gridcell";
+        'aria-selected': boolean;
+        'aria-disabled': boolean;
+        'aria-current': "date" | undefined;
+        'aria-label': string;
+        title: string | undefined;
+        tabindex: number;
+        disabled: boolean;
+        onclick: (e: MouseEvent) => void;
+        onpointerenter: () => Date | null;
+        onpointerleave: () => Date | null;
+    };
+    /** A month cell in year mode. */
+    monthCellProps(monthIndex: number): {
+        type: "button";
+        disabled: boolean;
+        onclick: () => void;
+    };
+    /** A year cell in decade mode. */
+    yearCellProps(year: number): {
+        type: "button";
+        disabled: boolean;
+        onclick: () => void;
+    };
+    /** A preset shortcut button. */
+    presetProps(preset: CalendarPreset): {
+        type: "button";
+        disabled: boolean;
+        onclick: () => void;
+    };
+};
+export type Calendar = ReturnType<typeof createCalendar>;