@lyeve-labs/ui-kit 0.11.2 → 0.13.0

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;

package/dist/internal/time.js

@@ -0,0 +1,166 @@
+/**
+ * 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.
+ */
+/** Highest legal value plus one, per stepped segment. */
+const SEGMENT_SIZE = {
+    hour: 24,
+    minute: 60,
+    second: 60,
+};
+const SECONDS_PER_MINUTE = 60;
+const SECONDS_PER_HOUR = 3600;
+/** The whole time as one number, so a comparison cannot compare the minute first. */
+function secondsOf(p) {
+    return p.h * SECONDS_PER_HOUR + p.mi * SECONDS_PER_MINUTE + p.s;
+}
+/**
+ * The segments are fixed width and the third is optional, which is the whole
+ * grammar. Anchored at both ends so a trailing offset or a fraction fails.
+ */
+const ISO_TIME = /^([01]\d|2[0-3]):([0-5]\d)(?::([0-5]\d))?$/;
+/**
+ * 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 function parseISOTime(s) {
+    if (typeof s !== 'string')
+        return null;
+    const m = ISO_TIME.exec(s);
+    if (!m)
+        return null;
+    const sec = m[3];
+    return { h: Number(m[1]), mi: Number(m[2]), s: sec ? Number(sec) : 0 };
+}
+/**
+ * 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 function toISOTime(p, seconds) {
+    const base = `${pad2(p.h)}:${pad2(p.mi)}`;
+    return seconds ? `${base}:${pad2(p.s)}` : base;
+}
+/**
+ * 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 function stepSegment(p, segment, delta, step) {
+    if (segment === 'meridiem') {
+        const flips = Math.abs(Math.trunc(delta)) % 2;
+        return { ...p, h: (p.h + 12 * flips) % SEGMENT_SIZE.hour };
+    }
+    const size = SEGMENT_SIZE[segment];
+    const current = segment === 'hour' ? p.h : segment === 'minute' ? p.mi : p.s;
+    const next = current + delta * step;
+    const moved = next > size - 1 ? 0 : next < 0 ? size - 1 : next;
+    if (segment === 'hour')
+        return { ...p, h: moved };
+    if (segment === 'minute')
+        return { ...p, mi: moved };
+    return { ...p, s: moved };
+}
+/**
+ * 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 function withinTimeRange(p, min, max) {
+    const t = secondsOf(p);
+    if (min !== null && max !== null) {
+        const lo = secondsOf(min);
+        const hi = secondsOf(max);
+        return lo > hi ? t >= lo || t <= hi : t >= lo && t <= hi;
+    }
+    if (min !== null)
+        return t >= secondsOf(min);
+    if (max !== null)
+        return t <= secondsOf(max);
+    return true;
+}
+/**
+ * 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 function clampTime(p, min, max) {
+    if (withinTimeRange(p, min, max))
+        return p;
+    if (min !== null && max !== null && secondsOf(min) > secondsOf(max)) {
+        const t = secondsOf(p);
+        return t - secondsOf(max) <= secondsOf(min) - t ? max : min;
+    }
+    if (min !== null && secondsOf(p) < secondsOf(min))
+        return min;
+    if (max !== null && secondsOf(p) > secondsOf(max))
+        return max;
+    return p;
+}
+/**
+ * 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 function to12Hour(h) {
+    const wrapped = h % 12;
+    return { hour: wrapped === 0 ? 12 : wrapped, meridiem: h < 12 ? '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 function from12Hour(hour, meridiem) {
+    const base = hour % 12;
+    return meridiem === 'PM' ? base + 12 : base;
+}
+/**
+ * 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 function pad2(n) {
+    return String(n).padStart(2, '0');
+}

package/dist/internal/tree.d.ts

@@ -0,0 +1,86 @@
+/**
+ * The shape of a data tree and the arithmetic a checkable one needs.
+ *
+ * A data tree is not a navigation menu. A menu shows where you can go and one
+ * item is current; a tree shows a structure, and a branch in it summarises
+ * everything beneath it while a click on that branch writes every one of them.
+ * Those two jobs are the reason this module exists: the summary and the write
+ * have to be computed from the same list, or a branch reports a state its own
+ * click does not produce.
+ *
+ * The tri-state itself comes from rollup.ts rather than being written again
+ * here. That module already holds the case a fold gets wrong, and a second
+ * implementation of it would be a second chance to get it wrong.
+ *
+ * Not exported from the package entry point - this is an implementation detail.
+ */
+import type { Component } from 'svelte';
+import { type TriState } from './rollup.js';
+/** Re-exported so a consumer of a branch's state does not have to know where the arithmetic lives. */
+export type { TriState };
+/** One node of a data tree. */
+export interface TreeNode<T = unknown> {
+    /** Stable across renders. */
+    id: string;
+    label: string;
+    icon?: Component<{
+        size?: number;
+        class?: string;
+    }>;
+    children?: TreeNode<T>[];
+    /** A count or status beside the label. */
+    badge?: string | number;
+    disabled?: boolean;
+    /** Whatever the consumer needs on activation. */
+    data?: T;
+}
+/** One visible row, in the order a keyboard walks them. */
+export interface TreeRow<T = unknown> {
+    node: TreeNode<T>;
+    depth: number;
+    parentId?: string;
+}
+/**
+ * Whether a node has anything to descend into.
+ *
+ * An empty `children` array is a leaf, not a branch that happens to be empty.
+ * A node that announces `aria-expanded` and then opens onto nothing tells a
+ * screen reader user there is more to read when there is not.
+ */
+export declare function isBranch<T>(node: TreeNode<T>): boolean;
+/** Every leaf under a node, excluding disabled ones, because a disabled leaf must be neither written nor counted. */
+export declare function leavesOf<T>(node: TreeNode<T>): TreeNode<T>[];
+/**
+ * The tri-state of a branch, from the checked set.
+ *
+ * A leaf is its own only leaf, so a caller can ask this of any node and get an
+ * answer that matches what a click on it will do. A branch whose leaves are all
+ * disabled has none to count and reports 'none': `leaves.every(isChecked)` is
+ * true over an empty array, which would draw that branch as fully checked and
+ * make the next click on it clear rows nobody chose.
+ */
+export declare function branchState<T>(node: TreeNode<T>, checked: ReadonlySet<string>): TriState;
+/**
+ * The ids to add and remove to set a whole subtree.
+ *
+ * Only leaf ids are ever returned. A branch's state is derived from its leaves
+ * on every render, so storing the branch as well gives the two a way to
+ * disagree, and the stored one always wins on the next paint.
+ *
+ * The direction is decided by counting the same list the write is filtered
+ * from, which is what keeps a partly disabled branch honest: the state that
+ * says 'fill' cannot have counted a leaf the fill will skip.
+ */
+export declare function toggleSubtree<T>(node: TreeNode<T>, checked: ReadonlySet<string>): {
+    add: string[];
+    remove: string[];
+};
+/**
+ * The visible rows, in order, with the depth and parent each one needs.
+ *
+ * A collapsed branch contributes its own row and nothing below it. The arrow
+ * keys walk this list, so a row that is not in it cannot be reached by keyboard
+ * either, which is the only way the keyboard order and the painted order stay
+ * the same list.
+ */
+export declare function flattenTree<T>(nodes: TreeNode<T>[], expanded: ReadonlySet<string>): TreeRow<T>[];

package/dist/internal/tree.js

@@ -0,0 +1,111 @@
+/**
+ * The shape of a data tree and the arithmetic a checkable one needs.
+ *
+ * A data tree is not a navigation menu. A menu shows where you can go and one
+ * item is current; a tree shows a structure, and a branch in it summarises
+ * everything beneath it while a click on that branch writes every one of them.
+ * Those two jobs are the reason this module exists: the summary and the write
+ * have to be computed from the same list, or a branch reports a state its own
+ * click does not produce.
+ *
+ * The tri-state itself comes from rollup.ts rather than being written again
+ * here. That module already holds the case a fold gets wrong, and a second
+ * implementation of it would be a second chance to get it wrong.
+ *
+ * Not exported from the package entry point - this is an implementation detail.
+ */
+import { nextState, rollUp, setSubtree } from './rollup.js';
+/**
+ * Whether a node has anything to descend into.
+ *
+ * An empty `children` array is a leaf, not a branch that happens to be empty.
+ * A node that announces `aria-expanded` and then opens onto nothing tells a
+ * screen reader user there is more to read when there is not.
+ */
+export function isBranch(node) {
+    return (node.children?.length ?? 0) > 0;
+}
+/**
+ * Every leaf under a node, disabled ones included, so the write and the count
+ * can be taken from one list.
+ *
+ * The walk stops at a disabled branch. Nothing in the subtree below it can be
+ * reached from any ancestor's control, so counting those leaves would describe
+ * rows the write skips.
+ */
+function walkLeaves(node, out) {
+    if (!isBranch(node)) {
+        out.push(node);
+        return;
+    }
+    if (node.disabled)
+        return;
+    for (const child of node.children ?? [])
+        walkLeaves(child, out);
+}
+/** Every leaf under a node, excluding disabled ones, because a disabled leaf must be neither written nor counted. */
+export function leavesOf(node) {
+    const reachable = [];
+    walkLeaves(node, reachable);
+    return reachable.filter((leaf) => !leaf.disabled);
+}
+/**
+ * The tri-state of a branch, from the checked set.
+ *
+ * A leaf is its own only leaf, so a caller can ask this of any node and get an
+ * answer that matches what a click on it will do. A branch whose leaves are all
+ * disabled has none to count and reports 'none': `leaves.every(isChecked)` is
+ * true over an empty array, which would draw that branch as fully checked and
+ * make the next click on it clear rows nobody chose.
+ */
+export function branchState(node, checked) {
+    return rollUp(leavesOf(node), (leaf) => checked.has(leaf.id));
+}
+/**
+ * The ids to add and remove to set a whole subtree.
+ *
+ * Only leaf ids are ever returned. A branch's state is derived from its leaves
+ * on every render, so storing the branch as well gives the two a way to
+ * disagree, and the stored one always wins on the next paint.
+ *
+ * The direction is decided by counting the same list the write is filtered
+ * from, which is what keeps a partly disabled branch honest: the state that
+ * says 'fill' cannot have counted a leaf the fill will skip.
+ */
+export function toggleSubtree(node, checked) {
+    const reachable = [];
+    walkLeaves(node, reachable);
+    const settable = (leaf) => !leaf.disabled;
+    const value = nextState(rollUp(reachable.filter(settable), (leaf) => checked.has(leaf.id)));
+    const add = [];
+    const remove = [];
+    for (const write of setSubtree(reachable, value, settable)) {
+        const held = checked.has(write.item.id);
+        if (write.value && !held)
+            add.push(write.item.id);
+        if (!write.value && held)
+            remove.push(write.item.id);
+    }
+    return { add, remove };
+}
+/**
+ * The visible rows, in order, with the depth and parent each one needs.
+ *
+ * A collapsed branch contributes its own row and nothing below it. The arrow
+ * keys walk this list, so a row that is not in it cannot be reached by keyboard
+ * either, which is the only way the keyboard order and the painted order stay
+ * the same list.
+ */
+export function flattenTree(nodes, expanded) {
+    const rows = [];
+    const visit = (list, depth, parentId) => {
+        for (const node of list) {
+            rows.push(parentId === undefined ? { node, depth } : { node, depth, parentId });
+            if (isBranch(node) && expanded.has(node.id)) {
+                visit(node.children ?? [], depth + 1, node.id);
+            }
+        }
+    };
+    visit(nodes, 0);
+    return rows;
+}