@lyeve-labs/ui-kit 0.12.1 → 0.13.1

package/dist/internal/nav-tree.js

@@ -0,0 +1,102 @@
+/**
+ * How a sidebar decides which of its links is the current page.
+ *
+ * The rule every app shell reaches for is
+ *
+ *     pathname === href || pathname.startsWith(href + '/')
+ *
+ * applied to every entry in the list. It is wrong in two ways that only show
+ * up once the list has more than one level. A parent link keeps claiming the
+ * page while the reader is on one of its children, so a settings sub-page
+ * lights two rows at once and neither of them is where the reader is. And two
+ * leaves where one href is a prefix of the other, /settings beside
+ * /settings/team, mark themselves together for the same reason, even though
+ * they are siblings and only one of them can be open.
+ *
+ * The fix is that prefix matching is a property of a node that owns a section,
+ * not of every node. A leaf answers for its own path and nothing below it; a
+ * node with children answers for its whole subtree, because that is what makes
+ * an ancestor able to say "you are somewhere in here" while its child says
+ * "you are here". Either default is overridable per node, and 'none' opts a
+ * node out of path matching entirely.
+ *
+ * Not exported from the package entry point - this is an implementation detail.
+ */
+/**
+ * Trailing slashes are noise: a router hands over /settings on one route and
+ * /settings/ on another, and the two name the same page. Everything else is
+ * left alone, because activePath is documented as a pathname and a query or a
+ * hash that reached here is a caller bug worth seeing rather than absorbing.
+ */
+function normalize(path) {
+    if (path === '')
+        return '';
+    const trimmed = path.replace(/\/+$/, '');
+    return trimmed === '' ? '/' : trimmed;
+}
+/**
+ * A node with children owns a section, so it answers for everything under it.
+ * A leaf answers for its own path alone.
+ */
+function matchMode(node) {
+    if (node.match)
+        return node.match;
+    return node.children && node.children.length > 0 ? 'prefix' : 'exact';
+}
+/**
+ * True when this node is the current page.
+ *
+ * Path only. A disabled node still reports the truth about its href; whether
+ * it is rendered as a link is a separate decision the component makes.
+ */
+export function isActive(node, activePath) {
+    if (!node.href)
+        return false;
+    const mode = matchMode(node);
+    if (mode === 'none')
+        return false;
+    const href = normalize(node.href);
+    const path = normalize(activePath);
+    if (href === '' || path === '')
+        return false;
+    if (path === href)
+        return true;
+    // A root href normalizes to "/", so the prefix it tests for is "//" and it
+    // claims nothing but itself. A dashboard mounted at / would otherwise own
+    // every page in the app.
+    return mode === 'prefix' && path.startsWith(`${href}/`);
+}
+/**
+ * The ids from the root down to the matched leaf, so its ancestors can open
+ * and mark themselves.
+ *
+ * Children are searched before the node itself, so a group never shadows the
+ * child that holds the more specific answer. The first match in document order
+ * wins: two nodes claiming one path is a tree the author has to fix, and
+ * silently picking one of them by length would hide it.
+ */
+export function activeTrail(items, activePath) {
+    for (const node of items) {
+        if (node.children && node.children.length > 0) {
+            const below = activeTrail(node.children, activePath);
+            if (below.length > 0)
+                return [node.id, ...below];
+        }
+        if (isActive(node, activePath))
+            return [node.id];
+    }
+    return [];
+}
+/** Depth-first flatten, for tests and for keyboard order. */
+export function flattenNav(items) {
+    const out = [];
+    const walk = (nodes, depth) => {
+        for (const node of nodes) {
+            out.push({ node, depth });
+            if (node.children && node.children.length > 0)
+                walk(node.children, depth + 1);
+        }
+    };
+    walk(items, 0);
+    return out;
+}

package/dist/internal/panel.d.ts

@@ -0,0 +1,100 @@
+/**
+ * The single source of truth for how a floating panel looks.
+ *
+ * field.ts states the resting control and nothing stated the surface that
+ * opens above it, so each of the four popovers grew its own:
+ *
+ *     MultiSelect  absolute z-50 mt-1 w-full rounded-xl border border-line
+ *                  bg-surface shadow-2xl overflow-hidden
+ *                  and, on an inner region, max-h-60 overflow-y-auto py-1
+ *     Autocomplete absolute z-50 mt-1 w-full max-h-60 overflow-y-auto
+ *                  rounded-xl border border-line bg-surface shadow-2xl py-1
+ *     DatePicker   absolute z-50 mt-1 w-[17rem] rounded-xl border border-line
+ *                  bg-surface shadow-2xl p-3
+ *     Dropdown     absolute z-50 mt-1 py-1 min-w-36 rounded-xl border
+ *                  border-line bg-surface shadow-2xl
+ *
+ * Three of those set a width the consumer cannot influence, and DatePicker
+ * sets it as w-[17rem], a length no token governs. The scroll lives on an
+ * inner region in one, on the surface itself in another and nowhere in the
+ * other two, so a Dropdown of eighty items runs past the bottom of the window
+ * and the last item cannot be reached. Two panels cap their height at max-h-60
+ * and two never cap it. All four draw the boundary with border-line, which
+ * reads 1.25:1 and is the only thing separating the panel from whatever it
+ * happens to float over. The shadow is the one thing they agreed on.
+ *
+ * Width stays at the call site: a menu sized to its trigger and a calendar
+ * sized to seven columns are different requirements. Everything else is here.
+ *
+ * One rule holds these together. No row carries two utilities for the same
+ * property. Colour and background sit on the surface, and a row states only
+ * the override its state earns, because two utilities for one property resolve
+ * in the order Tailwind emits them and not in the order they were written.
+ *
+ * Not exported from the package entry point - this is an implementation detail.
+ */
+/**
+ * The floating surface every popover paints.
+ *
+ * border-line-strong, not border-line: a panel floating over arbitrary content
+ * needs a boundary that clears 3:1, which line does not. It carries the
+ * resting text colour so a row can override it with a single utility.
+ */
+export declare const PANEL_SURFACE = "absolute z-50 mt-1 rounded-xl border border-line-strong bg-surface text-fg shadow-2xl";
+/**
+ * The scrolling region inside it.
+ *
+ * The cap is a token, not max-h-60, so a fifth panel cannot pick a different
+ * one. overscroll-contain stops a wheel that has reached the end of the list
+ * from carrying on into the page behind the open panel.
+ */
+export declare const PANEL_LIST = "max-h-panel-max overflow-y-auto overscroll-contain py-1";
+/**
+ * One row at rest.
+ *
+ * No background and no text colour of its own: it inherits both from the
+ * surface, which leaves each state below a single utility to override.
+ */
+export declare const PANEL_OPTION: string;
+/**
+ * The active descendant.
+ *
+ * A tint alone reads 1.09:1 against the panel, which is not a visible state,
+ * so the active row also carries an inset brand ring. Inset because the row
+ * spans the full width of the panel and an outset ring is clipped by it.
+ */
+export declare const PANEL_OPTION_ACTIVE = "bg-surface-2 ring-1 ring-inset ring-brand";
+/**
+ * A row whose value is selected, which is orthogonal to being active.
+ *
+ * The keyboard sits on one row while any number of rows are chosen, so this
+ * changes the text and never the background the active row is using.
+ */
+export declare const PANEL_OPTION_SELECTED = "font-medium text-brand";
+/**
+ * A row that cannot be chosen.
+ *
+ * pointer-events-none rather than a hover override: :hover still matches a
+ * disabled button, and a second hover background on the same row would resolve
+ * by emitted order, so the row could take the tint and read as choosable.
+ */
+export declare const PANEL_OPTION_DISABLED = "pointer-events-none opacity-40";
+/** The line shown when a filter matched nothing. */
+export declare const PANEL_EMPTY = "px-3 py-2 text-sm text-faint";
+/** A group heading inside the list. Not focusable, so it takes no row classes. */
+export declare const PANEL_GROUP_LABEL = "px-3 pb-1 pt-3 text-xs font-medium uppercase text-faint";
+/**
+ * Composes the option classes for a row's state.
+ *
+ * Exists as a function because three booleans spelled inline at each call site
+ * is how the four panels drifted. A disabled row takes the disabled treatment
+ * and never the active one, even while the keyboard is resting on it: painting
+ * it as the active descendant says Enter will choose it, and Enter will not.
+ * Selection survives both, because a chosen row that has since been disabled
+ * is still chosen.
+ */
+export declare function panelOption(state: {
+    active: boolean;
+    selected: boolean;
+    disabled: boolean;
+}): string;

package/dist/internal/panel.js

@@ -0,0 +1,109 @@
+/**
+ * The single source of truth for how a floating panel looks.
+ *
+ * field.ts states the resting control and nothing stated the surface that
+ * opens above it, so each of the four popovers grew its own:
+ *
+ *     MultiSelect  absolute z-50 mt-1 w-full rounded-xl border border-line
+ *                  bg-surface shadow-2xl overflow-hidden
+ *                  and, on an inner region, max-h-60 overflow-y-auto py-1
+ *     Autocomplete absolute z-50 mt-1 w-full max-h-60 overflow-y-auto
+ *                  rounded-xl border border-line bg-surface shadow-2xl py-1
+ *     DatePicker   absolute z-50 mt-1 w-[17rem] rounded-xl border border-line
+ *                  bg-surface shadow-2xl p-3
+ *     Dropdown     absolute z-50 mt-1 py-1 min-w-36 rounded-xl border
+ *                  border-line bg-surface shadow-2xl
+ *
+ * Three of those set a width the consumer cannot influence, and DatePicker
+ * sets it as w-[17rem], a length no token governs. The scroll lives on an
+ * inner region in one, on the surface itself in another and nowhere in the
+ * other two, so a Dropdown of eighty items runs past the bottom of the window
+ * and the last item cannot be reached. Two panels cap their height at max-h-60
+ * and two never cap it. All four draw the boundary with border-line, which
+ * reads 1.25:1 and is the only thing separating the panel from whatever it
+ * happens to float over. The shadow is the one thing they agreed on.
+ *
+ * Width stays at the call site: a menu sized to its trigger and a calendar
+ * sized to seven columns are different requirements. Everything else is here.
+ *
+ * One rule holds these together. No row carries two utilities for the same
+ * property. Colour and background sit on the surface, and a row states only
+ * the override its state earns, because two utilities for one property resolve
+ * in the order Tailwind emits them and not in the order they were written.
+ *
+ * Not exported from the package entry point - this is an implementation detail.
+ */
+/**
+ * The floating surface every popover paints.
+ *
+ * border-line-strong, not border-line: a panel floating over arbitrary content
+ * needs a boundary that clears 3:1, which line does not. It carries the
+ * resting text colour so a row can override it with a single utility.
+ */
+export const PANEL_SURFACE = 'absolute z-50 mt-1 rounded-xl border border-line-strong bg-surface text-fg shadow-2xl';
+/**
+ * The scrolling region inside it.
+ *
+ * The cap is a token, not max-h-60, so a fifth panel cannot pick a different
+ * one. overscroll-contain stops a wheel that has reached the end of the list
+ * from carrying on into the page behind the open panel.
+ */
+export const PANEL_LIST = 'max-h-panel-max overflow-y-auto overscroll-contain py-1';
+/**
+ * One row at rest.
+ *
+ * No background and no text colour of its own: it inherits both from the
+ * surface, which leaves each state below a single utility to override.
+ */
+export const PANEL_OPTION = 'flex w-full items-center gap-2.5 px-3 py-2 text-left text-sm ' +
+    'transition-colors duration-150 outline-none hover:bg-surface-2 ' +
+    'focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-brand';
+/**
+ * The active descendant.
+ *
+ * A tint alone reads 1.09:1 against the panel, which is not a visible state,
+ * so the active row also carries an inset brand ring. Inset because the row
+ * spans the full width of the panel and an outset ring is clipped by it.
+ */
+export const PANEL_OPTION_ACTIVE = 'bg-surface-2 ring-1 ring-inset ring-brand';
+/**
+ * A row whose value is selected, which is orthogonal to being active.
+ *
+ * The keyboard sits on one row while any number of rows are chosen, so this
+ * changes the text and never the background the active row is using.
+ */
+export const PANEL_OPTION_SELECTED = 'font-medium text-brand';
+/**
+ * A row that cannot be chosen.
+ *
+ * pointer-events-none rather than a hover override: :hover still matches a
+ * disabled button, and a second hover background on the same row would resolve
+ * by emitted order, so the row could take the tint and read as choosable.
+ */
+export const PANEL_OPTION_DISABLED = 'pointer-events-none opacity-40';
+/** The line shown when a filter matched nothing. */
+export const PANEL_EMPTY = 'px-3 py-2 text-sm text-faint';
+/** A group heading inside the list. Not focusable, so it takes no row classes. */
+export const PANEL_GROUP_LABEL = 'px-3 pb-1 pt-3 text-xs font-medium uppercase text-faint';
+/**
+ * Composes the option classes for a row's state.
+ *
+ * Exists as a function because three booleans spelled inline at each call site
+ * is how the four panels drifted. A disabled row takes the disabled treatment
+ * and never the active one, even while the keyboard is resting on it: painting
+ * it as the active descendant says Enter will choose it, and Enter will not.
+ * Selection survives both, because a chosen row that has since been disabled
+ * is still chosen.
+ */
+export function panelOption(state) {
+    const parts = [PANEL_OPTION];
+    if (state.selected)
+        parts.push(PANEL_OPTION_SELECTED);
+    if (state.disabled) {
+        parts.push(PANEL_OPTION_DISABLED);
+    }
+    else if (state.active) {
+        parts.push(PANEL_OPTION_ACTIVE);
+    }
+    return parts.join(' ');
+}

package/dist/internal/rollup.d.ts

@@ -0,0 +1,52 @@
+/**
+ * The tri-state contract behind a permissions matrix and a checkable tree.
+ *
+ * A parent control does two jobs at once: it summarises the rows beneath it,
+ * and a click on it writes every one of them. Both surfaces folded that summary
+ * with `rows.every(has)`, which is true over an empty array, so a group whose
+ * rows were all filtered away or all disabled drew as fully granted and the
+ * click that followed meant clear rather than fill. Summarising by count rather
+ * than by fold, and separating what may be written from what is counted, is the
+ * whole reason this module exists.
+ *
+ * Not exported from the package entry point - this is an implementation detail.
+ */
+/** What a parent control shows: nothing granted, part granted, all granted. */
+export type TriState = 'none' | 'some' | 'all';
+/**
+ * Rolls a set of rows up to one state.
+ *
+ * The empty set rolls up to 'none'. Array.prototype.every returns true on an
+ * empty array, so the obvious implementation reports a fully granted column
+ * over zero rows, and the next click on that column is a bulk write the
+ * operator never asked for.
+ */
+export declare function rollUp<T>(items: readonly T[], has: (item: T) => boolean): TriState;
+/**
+ * What a click on a rolled-up control means: 'all' clears, anything else fills.
+ *
+ * A 'some' state must fill rather than clear, because the partial state most
+ * often means the operator is part way through granting.
+ */
+export declare function nextState(current: TriState): boolean;
+/**
+ * Applies a value across a subtree, skipping items that cannot take it.
+ *
+ * The exclusion is the case that is always got wrong: a disabled row must
+ * neither be written nor counted in the roll-up that follows. Returning the
+ * writes rather than performing them is what lets the caller feed the same list
+ * to both, so the summary can never describe a row the write skipped.
+ */
+export declare function setSubtree<T>(items: readonly T[], value: boolean, canSet: (item: T) => boolean): {
+    item: T;
+    value: boolean;
+}[];
+/**
+ * Rolls up while treating a floor as already granted.
+ *
+ * A grant that is inherited rather than stored cannot be revoked by clearing
+ * the stored row, so a control that offers to clear it is lying. A row that is
+ * floored counts as granted here, which puts the parent at 'all' and makes the
+ * next click fill rather than clear.
+ */
+export declare function rollUpWithFloor<T>(items: readonly T[], has: (item: T) => boolean, floor: (item: T) => boolean): TriState;

package/dist/internal/rollup.js

@@ -0,0 +1,67 @@
+/**
+ * The tri-state contract behind a permissions matrix and a checkable tree.
+ *
+ * A parent control does two jobs at once: it summarises the rows beneath it,
+ * and a click on it writes every one of them. Both surfaces folded that summary
+ * with `rows.every(has)`, which is true over an empty array, so a group whose
+ * rows were all filtered away or all disabled drew as fully granted and the
+ * click that followed meant clear rather than fill. Summarising by count rather
+ * than by fold, and separating what may be written from what is counted, is the
+ * whole reason this module exists.
+ *
+ * Not exported from the package entry point - this is an implementation detail.
+ */
+/**
+ * Rolls a set of rows up to one state.
+ *
+ * The empty set rolls up to 'none'. Array.prototype.every returns true on an
+ * empty array, so the obvious implementation reports a fully granted column
+ * over zero rows, and the next click on that column is a bulk write the
+ * operator never asked for.
+ */
+export function rollUp(items, has) {
+    let granted = 0;
+    for (const item of items) {
+        if (has(item))
+            granted++;
+    }
+    if (granted === 0)
+        return 'none';
+    return granted === items.length ? 'all' : 'some';
+}
+/**
+ * What a click on a rolled-up control means: 'all' clears, anything else fills.
+ *
+ * A 'some' state must fill rather than clear, because the partial state most
+ * often means the operator is part way through granting.
+ */
+export function nextState(current) {
+    return current !== 'all';
+}
+/**
+ * Applies a value across a subtree, skipping items that cannot take it.
+ *
+ * The exclusion is the case that is always got wrong: a disabled row must
+ * neither be written nor counted in the roll-up that follows. Returning the
+ * writes rather than performing them is what lets the caller feed the same list
+ * to both, so the summary can never describe a row the write skipped.
+ */
+export function setSubtree(items, value, canSet) {
+    const writes = [];
+    for (const item of items) {
+        if (canSet(item))
+            writes.push({ item, value });
+    }
+    return writes;
+}
+/**
+ * Rolls up while treating a floor as already granted.
+ *
+ * A grant that is inherited rather than stored cannot be revoked by clearing
+ * the stored row, so a control that offers to clear it is lying. A row that is
+ * floored counts as granted here, which puts the parent at 'all' and makes the
+ * next click fill rather than clear.
+ */
+export function rollUpWithFloor(items, has, floor) {
+    return rollUp(items, (item) => floor(item) || has(item));
+}

package/dist/internal/time.d.ts

@@ -0,0 +1,103 @@
+/**
+ * The arithmetic behind TimePicker's hour, minute and optional second segments.
+ *
+ * The value the field reads and writes is RFC 3339 partial-time with no
+ * fraction:
+ *
+ *     unset            ''
+ *     seconds: false   /^([01]\d|2[0-3]):([0-5]\d)$/            for example '09:30'
+ *     seconds: true    /^([01]\d|2[0-3]):([0-5]\d):([0-5]\d)$/  for example '09:30:15'
+ *
+ * 24-hour, zero padded, no offset, no fractional seconds, no '24:00', no ':60'.
+ *
+ * Every helper here is a step a component author gets wrong on the first
+ * attempt: hours that carry when the arrow key promised one segment, a range
+ * check that cannot express an overnight window, per-segment clamping that
+ * rewrites a legal time, and a modulo that turns midnight into hour zero of a
+ * clock with no hour zero.
+ *
+ * Not exported from the package entry point - this is an implementation detail.
+ */
+/** One time, already range checked. `mi` rather than `m` so it cannot read as months. */
+export interface TimeParts {
+    h: number;
+    mi: number;
+    s: number;
+}
+/** The parts of the field an arrow key can land on. `meridiem` exists only in 12-hour display. */
+export type TimeSegment = 'hour' | 'minute' | 'second' | 'meridiem';
+/**
+ * Range-checks rather than wrapping: '24:00' and '00:60' return null, not a
+ * rolled-over value.
+ *
+ * Parsing through Date was the first attempt and it accepts both, because
+ * '1970-01-01T24:00' is the following midnight. A picker fed that displayed
+ * 00:00 for a string the server had already rejected. A single unpadded digit
+ * such as '9:30' is rejected for the same reason: the segments are fixed width,
+ * and accepting a short one lets a keystroke part way through an entry read as
+ * a committed value.
+ */
+export declare function parseISOTime(s: string | undefined | null): TimeParts | null;
+/**
+ * Writes a time back in the one format the field accepts.
+ *
+ * `seconds` decides whether the third segment is written at all. A picker with
+ * no second segment that emits '09:30:00' round-trips a field the user cannot
+ * see and can never correct.
+ */
+export declare function toISOTime(p: TimeParts, seconds: boolean): string;
+/**
+ * Steps one segment without carrying into its neighbour. Stepping the minute
+ * past 59 wraps to 0 and leaves the hour alone, because a spinner that changes
+ * two fields at once is not what the arrow key promised.
+ *
+ * A step that does not divide its segment lands on the far end rather than
+ * carrying the remainder: the minute 59 with step 15 goes to 0, not to 14, and
+ * stepping down from 0 goes to 59, not to 45. The remainder is a value the user
+ * cannot predict from the key they pressed.
+ *
+ * `meridiem` has two values, so it ignores `step` and moves the hour by twelve
+ * once per unit of delta. An even delta lands back where it started.
+ */
+export declare function stepSegment(p: TimeParts, segment: TimeSegment, delta: number, step: number): TimeParts;
+/**
+ * Inclusive bounds. A range whose min is greater than its max wraps past
+ * midnight and is a legal way to say "overnight", so the check is a disjunction
+ * rather than a conjunction in that case.
+ *
+ * The conjunction alone makes 22:00 to 06:00 match nothing, and a night shift
+ * picker built on it rejected every time a user could enter.
+ */
+export declare function withinTimeRange(p: TimeParts, min: TimeParts | null, max: TimeParts | null): boolean;
+/**
+ * Clamps a whole time to the bounds. Clamping per segment is wrong: with min
+ * 09:30, the time 10:15 is legal and per-segment clamping would push its minute
+ * to 30.
+ *
+ * When the range wraps past midnight the excluded window is the gap between max
+ * and min, so a time inside it moves to whichever end is nearer around the
+ * clock. A tie moves back to max, because the user was on the earlier side of
+ * the window before the step that left it.
+ */
+export declare function clampTime(p: TimeParts, min: TimeParts | null, max: TimeParts | null): TimeParts;
+/**
+ * 24-hour to 12-hour display, returning the hour and the meridiem. Midnight is
+ * 12 AM and noon is 12 PM, which is where the naive modulo gets it wrong: it
+ * gives 0 for both, and a picker showing '0:00 AM' has invented an hour zero
+ * that no 12-hour clock has.
+ */
+export declare function to12Hour(h: number): {
+    hour: number;
+    meridiem: 'AM' | 'PM';
+};
+/**
+ * 12-hour back to 24. 12 AM is hour 0 and 12 PM is hour 12; every other hour is
+ * itself in the morning and itself plus twelve in the afternoon.
+ */
+export declare function from12Hour(hour: number, meridiem: 'AM' | 'PM'): number;
+/**
+ * Zero-pads a segment for display. A minute of 5 written straight into the
+ * value gives '09:5', which parseISOTime then rejects, so the field drops the
+ * time the user just picked and blanks itself.
+ */
+export declare function pad2(n: number): string;