@lyeve-labs/ui-kit 0.11.2 → 0.13.0

package/dist/internal/choice.js

@@ -0,0 +1,179 @@
+/**
+ * The single source of truth for how a checkbox or a radio looks and announces
+ * itself.
+ *
+ * Checkbox, Radio and RadioGroup paint one control three ways. The two label
+ * wrappers hold the same utilities in two orders, Checkbox marks a required
+ * option and Radio marks nothing, RadioGroup rests its box on `border-line`
+ * where the other two use `border-line-strong`, and RadioGroup still keeps its
+ * focus ring inside the selected ternary. That last one is the defect Checkbox
+ * and Radio were already fixed for: selecting an option deleted the only
+ * indicator a keyboard user had, and in a list of a hundred options that loses
+ * your place entirely. Composing from here means a fourth choice control cannot
+ * reintroduce any of it.
+ *
+ * Not exported from the package entry point - this is an implementation detail.
+ */
+import { FIELD_HINT } from './field.js';
+/**
+ * The box and the icon slot share one size map, so the label text starts at the
+ * same x whether or not an option carries an icon. 3.5 is 14px, 4 is 16px and 5
+ * is 20px on the 4px grid.
+ */
+const CHOICE_SQUARE = {
+    sm: 'h-3.5 w-3.5',
+    md: 'h-4 w-4',
+    lg: 'h-5 w-5',
+};
+const WRAP_INLINE = 'inline-flex select-none items-start gap-2.5';
+const WRAP_CARD = 'flex select-none items-start gap-2.5 rounded-lg border p-3 transition-colors duration-150';
+/**
+ * The clickable wrapper. Card is a bordered option the whole surface of which
+ * is the target.
+ *
+ * The cursor is a ternary rather than a `cursor-pointer` that a disabled state
+ * appends `cursor-not-allowed` to. Both set the same property, so a class list
+ * carrying both resolves by stylesheet order and not by the order written here,
+ * which is how a disabled option kept offering a pointer.
+ */
+export function choiceWrap(variant, checked, disabled) {
+    const cursor = disabled ? 'cursor-not-allowed opacity-50' : 'cursor-pointer';
+    if (variant === 'card') {
+        // A selected card is tinted rather than filled: the label sits on it, and
+        // solid brand behind body text drops the contrast below AA.
+        const paint = checked ? 'border-brand bg-brand/8' : 'border-line-strong bg-surface-2';
+        return `${WRAP_CARD} ${paint} ${cursor}`;
+    }
+    return `${WRAP_INLINE} ${cursor}`;
+}
+/**
+ * The transparent input that sits over the painted box and carries every native
+ * semantic.
+ *
+ * `sr-only` leaves the input 1x1 and buried under the box that replaces it, so
+ * a click aimed at what the user sees lands on nothing. It covers the box
+ * instead, and `peer` is what lets the box below read its focus state.
+ */
+export const CHOICE_INPUT = 'peer absolute inset-0 m-0 h-full w-full cursor-pointer opacity-0 disabled:cursor-not-allowed';
+const BOX_BASE = 'pointer-events-none flex shrink-0 items-center justify-center transition-colors duration-150';
+/**
+ * The painted box or circle. Square for a checkbox, round for a radio, sized by
+ * ChoiceSize.
+ *
+ * The resting border is `border-line-strong`. `border-line` reads 1.25:1
+ * against the page, and the border is the only thing identifying an empty
+ * checkbox as a control, so at that contrast the control is invisible until it
+ * is used. A radio keeps a 2px ring because its selected state is a dot inside
+ * the ring rather than a fill, and a 1px ring reads as a smudge beside the dot
+ * at 14px.
+ *
+ * `mixed` paints exactly what `checked` paints. A part-selected parent is on,
+ * not a third state with a colour of its own; only the mark it holds differs.
+ */
+export function choiceBox(kind, size, checked, mixed) {
+    const on = checked || mixed;
+    const shape = kind === 'radio' ? 'rounded-full border-2' : 'rounded-xs border';
+    const paint = on
+        ? kind === 'radio'
+            ? 'border-brand bg-surface-2'
+            : 'border-brand bg-brand text-ink'
+        : 'border-line-strong bg-surface-2';
+    return `${BOX_BASE} ${CHOICE_SQUARE[size]} ${shape} ${paint} ${CHOICE_FOCUS}`;
+}
+/**
+ * The focus ring, stated ONCE and outside every checked branch.
+ *
+ * The ring lived inside the checked ternary in three components, so choosing an
+ * option removed the only indicator a keyboard user had. It is a ring and not a
+ * border colour because a selected box already carries a brand border, which
+ * leaves a border-only focus state with nothing to say.
+ */
+export const CHOICE_FOCUS = 'peer-focus-visible:outline peer-focus-visible:outline-2 peer-focus-visible:outline-brand peer-focus-visible:outline-offset-2';
+/**
+ * The label stack beside or under the box.
+ *
+ * Checkbox and Radio both build this, in different word orders, which is how
+ * two controls in one form ended up with different gaps between a label and its
+ * description.
+ */
+export const CHOICE_LABEL_STACK = 'flex flex-col gap-0.5';
+/**
+ * The label text, sized with the control.
+ *
+ * An option label is not a field label: it names one choice rather than the
+ * group, so it stays regular weight and FIELD_LABEL keeps the medium.
+ */
+export function choiceLabel(size) {
+    const scale = {
+        sm: 'text-xs',
+        md: 'text-sm',
+        lg: 'text-base',
+    };
+    return `${scale[size]} text-fg`;
+}
+/**
+ * Secondary line under the label.
+ *
+ * The same class the hint under a text field uses, taken from field.ts rather
+ * than respelled, because a checkbox hint and an input hint sitting in one form
+ * have no reason to differ and had already drifted apart once.
+ */
+export const CHOICE_DESCRIPTION = FIELD_HINT;
+/**
+ * The icon slot ahead of the label.
+ *
+ * Fixed to the box size so the label starts at the same x in every row of a
+ * list, and given no colour of its own so it inherits the label and dims with
+ * the wrapper when the option is disabled.
+ */
+export function choiceIcon(size) {
+    return `flex shrink-0 items-center justify-center ${CHOICE_SQUARE[size]}`;
+}
+/**
+ * Pixel size for a lucide icon at each ChoiceSize, so a consumer does not
+ * guess.
+ *
+ * A lucide icon takes a number, not a class, so the slot above cannot size it.
+ * These are the same 14, 16 and 20 the slot reserves; an icon rendered at any
+ * other size overflows the slot or floats inside it.
+ */
+export const CHOICE_ICON_PX = {
+    sm: 14,
+    md: 16,
+    lg: 20,
+};
+/**
+ * The fieldset a group renders, so the set is announced as a group rather than
+ * as loose controls.
+ *
+ * `min-w-0` is load bearing: a fieldset defaults to `min-width: min-content`,
+ * so one long option label widened the whole group past its column instead of
+ * wrapping.
+ */
+export const CHOICE_GROUP = 'flex min-w-0 flex-col gap-2';
+/**
+ * The row or column the options sit in.
+ *
+ * A horizontal group gets a wider inline gap than block gap: options read as
+ * separate choices across a row and as one list down a column, and an equal gap
+ * in both axes makes a wrapped row look like a grid.
+ */
+export function choiceGroupList(orientation) {
+    return orientation === 'horizontal'
+        ? 'flex flex-row flex-wrap gap-x-5 gap-y-2'
+        : 'flex flex-col gap-2';
+}
+/**
+ * The check and the mixed marks, as SVG path data on the box's own grid.
+ *
+ * Drawn as paths because the consistency suite rejects a Unicode check outright,
+ * and because a font glyph lands at a different optical weight from every other
+ * icon in the library. Both sit in a 10 by 8 viewBox centred in the box, at
+ * stroke width 1.5 with round caps, so the two marks swap without the box
+ * shifting. The mixed bar stops short of the edges so its round caps do not
+ * touch the border.
+ */
+export const CHOICE_MARK = {
+    check: 'M1 4l3 3 5-6',
+    mixed: 'M1.5 4h7',
+};

package/dist/internal/field.d.ts

@@ -46,3 +46,34 @@ export declare function controlBorder(error: boolean): string;
  * reader announced the control and never the reason it was rejected.
  */
 export declare function describedBy(id: string | undefined, error?: string, hint?: string): string | undefined;
+/**
+ * A control built from several inputs rather than from one.
+ *
+ * CONTROL_BASE is `w-full` and assumes a single input fills the control, so a
+ * time field composed from it stretched three two-character segments across a
+ * whole column and left the separators floating in the gaps. This shrink-wraps
+ * its content instead and keeps `h-control`, so a segmented control and an
+ * Input placed in the same row still line up.
+ *
+ * The focus border is driven by `focus-within`. The wrapper is a div, it never
+ * receives focus itself, and `focus:border-brand` on it can therefore never
+ * match: the control would sit at its resting border while one of its segments
+ * held the caret.
+ */
+export declare const CONTROL_SEGMENTED: string;
+/** As controlBorder, for a wrapper that is only ever focused through a child. */
+export declare function segmentedBorder(error: boolean): string;
+/**
+ * One segment inside CONTROL_SEGMENTED.
+ *
+ * It carries no width. A two-digit segment needs a fixed one so the control
+ * does not resize as the user types, and an AM/PM select needs to size to its
+ * own text; stating a width here would mean one of the two overriding it, and
+ * two width utilities on one element resolve by the order Tailwind emits them
+ * rather than the order they were written.
+ *
+ * The focus ring is inset. The segment sits flush inside the wrapper's border,
+ * so the global 2px outset outline would be drawn over that border and clipped
+ * by the wrapper's own rounding.
+ */
+export declare const CONTROL_SEGMENT: string;

package/dist/internal/field.js

@@ -41,7 +41,10 @@ export const CONTROL_MULTILINE = 'w-full min-h-control rounded-lg bg-surface-2 b
  * `border-danger/70`.
  */
 export function controlBorder(error) {
-    return error ? 'border-danger focus:border-danger' : 'border-line focus:border-brand';
+    // line-strong, not line: at 1.25:1 against the page the resting border was
+    // the only thing marking the control and it failed SC 1.4.11. line stays the
+    // divider colour, where there is no control to identify.
+    return error ? 'border-danger focus:border-danger' : 'border-line-strong focus:border-brand';
 }
 /**
  * Wires a control to whichever of its hint or error is on screen.
@@ -60,3 +63,41 @@ export function describedBy(id, error, hint) {
         return `${id}-hint`;
     return undefined;
 }
+/**
+ * A control built from several inputs rather than from one.
+ *
+ * CONTROL_BASE is `w-full` and assumes a single input fills the control, so a
+ * time field composed from it stretched three two-character segments across a
+ * whole column and left the separators floating in the gaps. This shrink-wraps
+ * its content instead and keeps `h-control`, so a segmented control and an
+ * Input placed in the same row still line up.
+ *
+ * The focus border is driven by `focus-within`. The wrapper is a div, it never
+ * receives focus itself, and `focus:border-brand` on it can therefore never
+ * match: the control would sit at its resting border while one of its segments
+ * held the caret.
+ */
+export const CONTROL_SEGMENTED = 'inline-flex h-control items-center gap-0.5 rounded-lg bg-surface-2 border px-3 ' +
+    'text-sm text-fg transition-colors duration-150';
+/** As controlBorder, for a wrapper that is only ever focused through a child. */
+export function segmentedBorder(error) {
+    return error
+        ? 'border-danger focus-within:border-danger'
+        : 'border-line-strong focus-within:border-brand';
+}
+/**
+ * One segment inside CONTROL_SEGMENTED.
+ *
+ * It carries no width. A two-digit segment needs a fixed one so the control
+ * does not resize as the user types, and an AM/PM select needs to size to its
+ * own text; stating a width here would mean one of the two overriding it, and
+ * two width utilities on one element resolve by the order Tailwind emits them
+ * rather than the order they were written.
+ *
+ * The focus ring is inset. The segment sits flush inside the wrapper's border,
+ * so the global 2px outset outline would be drawn over that border and clipped
+ * by the wrapper's own rounding.
+ */
+export const CONTROL_SEGMENT = 'shrink-0 rounded-sm border-0 bg-transparent p-0 text-center text-sm text-fg tabular-nums ' +
+    'outline-none focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-brand ' +
+    'disabled:cursor-not-allowed';

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;