@lyeve-labs/ui-kit 0.12.1 → 0.13.0

package/dist/internal/filter.d.ts

@@ -0,0 +1,80 @@
+/**
+ * One filter contract for every list-bearing control.
+ *
+ * MultiSelect and Autocomplete each spelled the same expression by hand, at
+ * MultiSelect.svelte:51-53 and Autocomplete.svelte:60-64:
+ *
+ *     options.filter((o) => o.label.toLowerCase().includes(query.trim().toLowerCase()))
+ *
+ * It reads the label and nothing else, so an option a user knows by its value,
+ * its airport code or a synonym could not be found. It compares raw code
+ * points, so a query of "cafe" missed an option labelled with an acute accent.
+ * It trims and lowercases the query once per option instead of once per
+ * keystroke. And it is not a prop, so a consumer whose list arrives already
+ * narrowed by a server query had no way to switch local filtering off or to say
+ * what a match means for their data. Both controls now call applyFilter, which
+ * takes a matcher the call site can replace or disable.
+ *
+ * Not exported from the package entry point - this is an implementation detail.
+ */
+/** What a matcher is told about the query, computed once per keystroke rather than per option. */
+export interface FilterContext {
+    /** Exactly what the user typed, untouched. */
+    readonly query: string;
+    /**
+     * query trimmed, lowercased and NFD diacritic-folded. Precomputed: folding
+     * per option is O(n) work for a value that cannot change within a pass.
+     */
+    readonly needle: string;
+    /** Position in the unfiltered array, so a rank-aware matcher can weight earlier entries. */
+    readonly index: number;
+}
+/** A matcher. Returning false drops the option. */
+export type FilterFn<T> = (option: T, ctx: FilterContext) => boolean;
+/**
+ * A filter prop: the default matcher, a replacement, or false to disable
+ * filtering entirely (the list is already filtered upstream, for instance by a
+ * server query).
+ */
+export type FilterInput<T> = FilterFn<T> | false | undefined;
+/**
+ * Trim, lowercase, and fold diacritics through NFD so that a query of "e"
+ * matches an option spelled with an acute accent.
+ *
+ * NFD splits an accented letter into its base letter and a combining mark, so
+ * dropping the Mark category afterwards leaves the base letters and nothing
+ * else. That also folds marks in scripts where a mark distinguishes two words,
+ * which shows the user one option too many rather than hiding the one they were
+ * typing toward. A string that is only marks folds to nothing, which is the
+ * same answer as an empty query and is what the callers treat it as.
+ */
+export declare function normalize(value: string): string;
+/**
+ * The default matcher: case- and accent-insensitive substring over the label,
+ * plus any keywords the option carries. Label-only matching is what ships
+ * today; keywords are additive and absent on every existing option, so adopting
+ * this changes no current list.
+ *
+ * An empty needle keeps every option. applyFilter answers an empty query before
+ * it reaches a matcher, so this case is here for a call site that composes the
+ * default into a matcher of its own.
+ */
+export declare function defaultFilter<T extends {
+    label: string;
+    keywords?: readonly string[];
+}>(option: T, ctx: FilterContext): boolean;
+/**
+ * Applies a FilterInput across a list, building the context once.
+ *
+ * An empty or whitespace-only query returns the input array unchanged, by
+ * identity, so a caller can compare references to skip work. A query that folds
+ * away to nothing counts as empty for the same reason: there is no needle left
+ * to look for, and matching every label against "" would drop nothing anyway.
+ *
+ * false is answered before the query is read, so a keystroke that is still in
+ * the box cannot reintroduce local filtering on a list the server already cut.
+ */
+export declare function applyFilter<T extends {
+    label: string;
+    keywords?: readonly string[];
+}>(options: readonly T[], query: string, filter?: FilterInput<T>): readonly T[];

package/dist/internal/filter.js

@@ -0,0 +1,80 @@
+/**
+ * One filter contract for every list-bearing control.
+ *
+ * MultiSelect and Autocomplete each spelled the same expression by hand, at
+ * MultiSelect.svelte:51-53 and Autocomplete.svelte:60-64:
+ *
+ *     options.filter((o) => o.label.toLowerCase().includes(query.trim().toLowerCase()))
+ *
+ * It reads the label and nothing else, so an option a user knows by its value,
+ * its airport code or a synonym could not be found. It compares raw code
+ * points, so a query of "cafe" missed an option labelled with an acute accent.
+ * It trims and lowercases the query once per option instead of once per
+ * keystroke. And it is not a prop, so a consumer whose list arrives already
+ * narrowed by a server query had no way to switch local filtering off or to say
+ * what a match means for their data. Both controls now call applyFilter, which
+ * takes a matcher the call site can replace or disable.
+ *
+ * Not exported from the package entry point - this is an implementation detail.
+ */
+/**
+ * Trim, lowercase, and fold diacritics through NFD so that a query of "e"
+ * matches an option spelled with an acute accent.
+ *
+ * NFD splits an accented letter into its base letter and a combining mark, so
+ * dropping the Mark category afterwards leaves the base letters and nothing
+ * else. That also folds marks in scripts where a mark distinguishes two words,
+ * which shows the user one option too many rather than hiding the one they were
+ * typing toward. A string that is only marks folds to nothing, which is the
+ * same answer as an empty query and is what the callers treat it as.
+ */
+export function normalize(value) {
+    return value.normalize('NFD').replace(/\p{M}/gu, '').trim().toLowerCase();
+}
+/**
+ * The default matcher: case- and accent-insensitive substring over the label,
+ * plus any keywords the option carries. Label-only matching is what ships
+ * today; keywords are additive and absent on every existing option, so adopting
+ * this changes no current list.
+ *
+ * An empty needle keeps every option. applyFilter answers an empty query before
+ * it reaches a matcher, so this case is here for a call site that composes the
+ * default into a matcher of its own.
+ */
+export function defaultFilter(option, ctx) {
+    if (ctx.needle === '')
+        return true;
+    if (normalize(option.label).includes(ctx.needle))
+        return true;
+    const keywords = option.keywords;
+    return keywords !== undefined && keywords.some((word) => normalize(word).includes(ctx.needle));
+}
+/**
+ * Applies a FilterInput across a list, building the context once.
+ *
+ * An empty or whitespace-only query returns the input array unchanged, by
+ * identity, so a caller can compare references to skip work. A query that folds
+ * away to nothing counts as empty for the same reason: there is no needle left
+ * to look for, and matching every label against "" would drop nothing anyway.
+ *
+ * false is answered before the query is read, so a keystroke that is still in
+ * the box cannot reintroduce local filtering on a list the server already cut.
+ */
+export function applyFilter(options, query, filter) {
+    if (filter === false)
+        return options;
+    const needle = normalize(query);
+    if (needle === '')
+        return options;
+    const match = filter ?? defaultFilter;
+    const kept = [];
+    for (let index = 0; index < options.length; index++) {
+        // index counts the input, not kept: a matcher that weights the top of the
+        // list has to see the same number for an option however many entries above
+        // it the query has already removed.
+        const option = options[index];
+        if (match(option, { query, needle, index }))
+            kept.push(option);
+    }
+    return kept;
+}

package/dist/internal/layout.d.ts

@@ -0,0 +1,119 @@
+/**
+ * The single source of truth for how a page, a card, a table and a modal are
+ * spaced.
+ *
+ * Nothing in the library owned the page frame, so every page invented one. The
+ * same gutter ships in four spellings, five content caps are in use with no
+ * rule for picking between them, a section heading is spelled fourteen ways,
+ * and card surfaces are hand-rolled in nine paddings while Card itself goes
+ * unused. The components disagree with each other too: Card pads its header
+ * 16px down and its footer 12px down for no reason a reader can infer, and
+ * Modal insets its panel 20px where Dialog insets the same kind of panel 24px.
+ *
+ * Every value composes from a `--spacing-*` token rather than a Tailwind
+ * number. That is the only thing that makes the tokens real. Of the ten the
+ * theme declares, `--spacing-control` was the one with any uses, and it had
+ * them because the field contract composes from it.
+ *
+ * Not exported from the package entry point - this is an implementation detail.
+ */
+/** How much of the viewport a page's content is allowed to fill. */
+export type PageWidth = 'narrow' | 'default' | 'wide' | 'full';
+/**
+ * The gutter a page sits in, stated once.
+ *
+ * Two pages in the same shell started their content at different distances
+ * from the edge because each spelled its own gutter. The horizontal and
+ * vertical tokens resolve to the same 24px and keep separate names, so a
+ * design that wants a taller page gutter changes one token, not every page.
+ */
+export declare const PAGE_PAD = "mx-auto w-full px-page-x py-page-y";
+/**
+ * Content cap by name. Four named slots replace the five raw max-w values
+ * chosen per page with no rule.
+ *
+ * `narrow` is one column: a form, a settings pane, a page of prose. `default`
+ * is a page of stacked cards. `wide` is a data page whose table needs the
+ * room. `full` opts out, for a canvas or a split pane that owns the viewport.
+ * The names carry the decision, so a page picks a role rather than a number.
+ */
+export declare const PAGE_WIDTH: Record<PageWidth, string>;
+/**
+ * The vertical rhythm between a page's top-level sections. A property of the
+ * shell, so a page cannot choose its own.
+ *
+ * PageHeader already drops 32px below the title and every page that sets a
+ * section gap sets the same 32px, so the value was agreed and unstated. A gap
+ * on the shell also means adding a section is appending a child, rather than
+ * remembering to put a margin on it.
+ */
+export declare const PAGE_STACK = "flex flex-col gap-section";
+/**
+ * The card surface, without its padding.
+ *
+ * Padding is separate because a card wrapping a table or a list wants its
+ * children flush to the border. `overflow-hidden` is deliberately absent: the
+ * focus ring sits 2px outside the element it belongs to, so a clipping surface
+ * crops the ring of every button inside it down to whichever edge fits.
+ */
+export declare const CARD_SURFACE = "bg-surface border border-line rounded-xl";
+/**
+ * Card padding by name.
+ *
+ * `md` is the 20px the theme names `--spacing-card`: the measured mode across
+ * the card surfaces in use, and what Card itself paints. `lg` is the page
+ * gutter, so a card padded `lg` holds its content on the same rhythm as the
+ * page around it. Nine hand-rolled paddings collapse onto these four.
+ */
+export declare const CARD_PAD: Record<'none' | 'sm' | 'md' | 'lg', string>;
+/**
+ * The band above a card's content.
+ *
+ * Card insets its header 20px across and 16px down, and its footer 20px across
+ * and 12px down. Nothing tells the two bands apart, so they share one inset
+ * here and differ only in which edge carries the rule.
+ */
+export declare const CARD_HEADER = "px-card py-card-sm border-b border-line";
+/** The band below a card's content. CARD_HEADER's inset, with the rule on top. */
+export declare const CARD_FOOTER = "px-card py-card-sm border-t border-line bg-surface-2/40";
+/**
+ * A placeholder inside a card, where three spellings of the same centred muted
+ * line currently ship.
+ *
+ * An empty list is not an error, so it reads as muted body copy and not as a
+ * warning. The section gap above and below keeps a card holding nothing from
+ * collapsing to a single line of text.
+ */
+export declare const CARD_EMPTY = "py-section text-center text-sm text-muted";
+/**
+ * The head cell of a table: its padding and the type treatment that marks it
+ * as a label rather than data.
+ *
+ * The hand-rolled tables split four ways on cell padding, so two tables on one
+ * page ran at different row heights. Horizontal is the compact card step, so a
+ * full-bleed table inside a card lines its first column up with the card's own
+ * text. Vertical is the control step: 12px and 8px were both already in use in
+ * near equal numbers, and 8px is the one the token scale names.
+ */
+export declare const TABLE_CELL_HEAD = "px-card-sm py-input-y text-xs font-medium uppercase tracking-wider whitespace-nowrap text-faint";
+/** The body cell of a table. TABLE_CELL_HEAD's padding, at body weight and colour. */
+export declare const TABLE_CELL_BODY = "px-card-sm py-input-y text-fg align-middle";
+/**
+ * The gutter every modal surface uses. Modal paints 20px and Dialog paints
+ * 24px for the same kind of surface.
+ *
+ * A dialog opened over a modal showed both insets at once. A modal panel is a
+ * card lifted off the page, so a banded modal takes CARD_HEADER and
+ * CARD_FOOTER, which resolve to this same inset.
+ */
+export declare const MODAL_PAD = "px-card py-card-sm";
+/**
+ * A section heading below the page title. Level 2 sits under the title, level 3
+ * inside a card.
+ *
+ * Fourteen distinct class strings serve this role, so two sections on the same
+ * page can render at different sizes and weights. Taking the level rather than
+ * a free-form string means the class cannot disagree with the heading element
+ * the caller is already writing.
+ */
+export declare function sectionHeading(level: 2 | 3): string;

package/dist/internal/layout.js

@@ -0,0 +1,132 @@
+/**
+ * The single source of truth for how a page, a card, a table and a modal are
+ * spaced.
+ *
+ * Nothing in the library owned the page frame, so every page invented one. The
+ * same gutter ships in four spellings, five content caps are in use with no
+ * rule for picking between them, a section heading is spelled fourteen ways,
+ * and card surfaces are hand-rolled in nine paddings while Card itself goes
+ * unused. The components disagree with each other too: Card pads its header
+ * 16px down and its footer 12px down for no reason a reader can infer, and
+ * Modal insets its panel 20px where Dialog insets the same kind of panel 24px.
+ *
+ * Every value composes from a `--spacing-*` token rather than a Tailwind
+ * number. That is the only thing that makes the tokens real. Of the ten the
+ * theme declares, `--spacing-control` was the one with any uses, and it had
+ * them because the field contract composes from it.
+ *
+ * Not exported from the package entry point - this is an implementation detail.
+ */
+/**
+ * The gutter a page sits in, stated once.
+ *
+ * Two pages in the same shell started their content at different distances
+ * from the edge because each spelled its own gutter. The horizontal and
+ * vertical tokens resolve to the same 24px and keep separate names, so a
+ * design that wants a taller page gutter changes one token, not every page.
+ */
+export const PAGE_PAD = 'mx-auto w-full px-page-x py-page-y';
+/**
+ * Content cap by name. Four named slots replace the five raw max-w values
+ * chosen per page with no rule.
+ *
+ * `narrow` is one column: a form, a settings pane, a page of prose. `default`
+ * is a page of stacked cards. `wide` is a data page whose table needs the
+ * room. `full` opts out, for a canvas or a split pane that owns the viewport.
+ * The names carry the decision, so a page picks a role rather than a number.
+ */
+export const PAGE_WIDTH = {
+    narrow: 'max-w-3xl',
+    default: 'max-w-5xl',
+    wide: 'max-w-7xl',
+    full: 'max-w-full',
+};
+/**
+ * The vertical rhythm between a page's top-level sections. A property of the
+ * shell, so a page cannot choose its own.
+ *
+ * PageHeader already drops 32px below the title and every page that sets a
+ * section gap sets the same 32px, so the value was agreed and unstated. A gap
+ * on the shell also means adding a section is appending a child, rather than
+ * remembering to put a margin on it.
+ */
+export const PAGE_STACK = 'flex flex-col gap-section';
+/**
+ * The card surface, without its padding.
+ *
+ * Padding is separate because a card wrapping a table or a list wants its
+ * children flush to the border. `overflow-hidden` is deliberately absent: the
+ * focus ring sits 2px outside the element it belongs to, so a clipping surface
+ * crops the ring of every button inside it down to whichever edge fits.
+ */
+export const CARD_SURFACE = 'bg-surface border border-line rounded-xl';
+/**
+ * Card padding by name.
+ *
+ * `md` is the 20px the theme names `--spacing-card`: the measured mode across
+ * the card surfaces in use, and what Card itself paints. `lg` is the page
+ * gutter, so a card padded `lg` holds its content on the same rhythm as the
+ * page around it. Nine hand-rolled paddings collapse onto these four.
+ */
+export const CARD_PAD = {
+    none: '',
+    sm: 'p-card-sm',
+    md: 'p-card',
+    lg: 'p-page-x',
+};
+/**
+ * The band above a card's content.
+ *
+ * Card insets its header 20px across and 16px down, and its footer 20px across
+ * and 12px down. Nothing tells the two bands apart, so they share one inset
+ * here and differ only in which edge carries the rule.
+ */
+export const CARD_HEADER = 'px-card py-card-sm border-b border-line';
+/** The band below a card's content. CARD_HEADER's inset, with the rule on top. */
+export const CARD_FOOTER = 'px-card py-card-sm border-t border-line bg-surface-2/40';
+/**
+ * A placeholder inside a card, where three spellings of the same centred muted
+ * line currently ship.
+ *
+ * An empty list is not an error, so it reads as muted body copy and not as a
+ * warning. The section gap above and below keeps a card holding nothing from
+ * collapsing to a single line of text.
+ */
+export const CARD_EMPTY = 'py-section text-center text-sm text-muted';
+/**
+ * The head cell of a table: its padding and the type treatment that marks it
+ * as a label rather than data.
+ *
+ * The hand-rolled tables split four ways on cell padding, so two tables on one
+ * page ran at different row heights. Horizontal is the compact card step, so a
+ * full-bleed table inside a card lines its first column up with the card's own
+ * text. Vertical is the control step: 12px and 8px were both already in use in
+ * near equal numbers, and 8px is the one the token scale names.
+ */
+export const TABLE_CELL_HEAD = 'px-card-sm py-input-y text-xs font-medium uppercase tracking-wider whitespace-nowrap text-faint';
+/** The body cell of a table. TABLE_CELL_HEAD's padding, at body weight and colour. */
+export const TABLE_CELL_BODY = 'px-card-sm py-input-y text-fg align-middle';
+/**
+ * The gutter every modal surface uses. Modal paints 20px and Dialog paints
+ * 24px for the same kind of surface.
+ *
+ * A dialog opened over a modal showed both insets at once. A modal panel is a
+ * card lifted off the page, so a banded modal takes CARD_HEADER and
+ * CARD_FOOTER, which resolve to this same inset.
+ */
+export const MODAL_PAD = 'px-card py-card-sm';
+/**
+ * A section heading below the page title. Level 2 sits under the title, level 3
+ * inside a card.
+ *
+ * Fourteen distinct class strings serve this role, so two sections on the same
+ * page can render at different sizes and weights. Taking the level rather than
+ * a free-form string means the class cannot disagree with the heading element
+ * the caller is already writing.
+ */
+export function sectionHeading(level) {
+    // Level 3 drops a size rather than a weight. Inside a card it sits under the
+    // card's own semibold title, and two semibold lines at the same size read as
+    // one heading broken in half.
+    return level === 2 ? 'text-lg font-semibold text-fg' : 'text-sm font-semibold text-fg';
+}

package/dist/internal/listbox.svelte.d.ts

@@ -0,0 +1,77 @@
+/**
+ * One owner for the open state, the active row, the keyboard model and the
+ * dismissal that every list-bearing control needs.
+ *
+ * MultiSelect, Autocomplete, DatePicker and Dropdown each hand-rolled all four,
+ * and every copy is wrong somewhere different. The dismiss effect is written
+ * out four times: MultiSelect.svelte:84-93, DatePicker.svelte:151-160 and
+ * Dropdown.svelte:45-54 are byte identical, and Autocomplete.svelte:117-120 is
+ * the same minus the keydown, so Escape does nothing there at all.
+ * Autocomplete.svelte:90-107 is the kit's only arrow-key implementation and it
+ * is incomplete: ArrowUp on a closed list decrements the index without opening
+ * anything, Home and End do nothing, there is no typeahead and there is no
+ * wrap. Nothing in the kit sets aria-activedescendant, so a screen reader is
+ * never told which row the keyboard is resting on, and Autocomplete marks that
+ * row with a background tint alone, which reads 1.09:1. The rows are buttons
+ * carrying role="option" and no tabindex, so Tab walks into the list instead of
+ * leaving the field. Autocomplete.svelte:146 closes on a 150ms blur timer, so
+ * clicking an option works only because mousedown-to-click beats the timer. And
+ * no copy stops the Escape event, so a listbox inside a Modal closes both.
+ *
+ * One thing deliberately stays at the call site: what a selection means. This
+ * fires onSelect and leaves the list open, because MultiSelect collects several
+ * values in one pass and a factory that closed on every pick could not serve
+ * it. A single-value control calls close('select') from its own onSelect, which
+ * is why that reason exists.
+ *
+ * Not exported from the package entry point - this is an implementation detail.
+ */
+/** The least a row has to be for the keyboard model to work on it. */
+export interface ListboxItem {
+    value: string;
+    label: string;
+    disabled?: boolean;
+}
+/**
+ * Why the list closed. A consumer that resets a search query on dismissal but
+ * keeps it on a pick needs to tell the two apart, and the four controls each
+ * guessed.
+ */
+export type ListboxCloseReason = 'escape' | 'select' | 'outside' | 'focusout' | 'tab';
+export interface ListboxConfig<T extends ListboxItem> {
+    items: () => readonly T[];
+    /** Stable across the SSR boundary. Pass $props.id(). */
+    baseId: () => string;
+    onSelect: (item: T, index: number) => void;
+    onOpenChange?: (open: boolean) => void;
+    onClose?: (reason: ListboxCloseReason) => void;
+    /** Typeahead jumps to the next item whose label starts with the typed run. Off for a control with its own text input, where letters are query text. */
+    typeahead?: () => boolean;
+    /** The active row wraps past the ends. */
+    loop?: () => boolean;
+}
+export interface Listbox {
+    readonly open: boolean;
+    readonly activeIndex: number;
+    /** Attributes for the trigger or the combobox input. */
+    readonly triggerAttrs: Record<string, string | undefined>;
+    /** Attributes for the panel. */
+    readonly listAttrs: Record<string, string | undefined>;
+    /** Attributes for one row. tabindex is -1: focus stays on the trigger and position travels by aria-activedescendant. */
+    optionAttrs(index: number): Record<string, string | number | undefined>;
+    openList(active?: number): void;
+    close(reason: ListboxCloseReason): void;
+    toggle(): void;
+    setActive(index: number): void;
+    /** Returns true when it consumed the event. */
+    onkeydown(event: KeyboardEvent): boolean;
+    /** use:listbox.anchor on the wrapper. Registers outside-click and focusout dismissal. */
+    anchor: (node: HTMLElement) => {
+        destroy(): void;
+    };
+    /** use:listbox.panel on the panel. Keeps the active row scrolled into view. */
+    panel: (node: HTMLElement) => {
+        destroy(): void;
+    };
+}
+export declare function createListbox<T extends ListboxItem>(config: ListboxConfig<T>): Listbox;