@syware/jlib 0.0.0-stage → 0.1.3

package/dist/lib/icon-set.d.ts

@@ -0,0 +1,95 @@
+import type { IconNode } from 'lucide';
+/**
+ * The usual icons of an interface, by name: `registerIcons(COMMON_ICONS)` lets pages write any of them
+ * (`<jl-icon name="settings">`, `<jl-button icon="plus">`). It costs about 5 kB compressed; an app that names a few
+ * icons registers just those instead. `@syware/jlib/all` registers them all.
+ */
+export declare const COMMON_ICONS: {
+    'arrow-down': IconNode;
+    'arrow-left': IconNode;
+    'arrow-right': IconNode;
+    'arrow-up': IconNode;
+    'arrow-up-down': IconNode;
+    bell: IconNode;
+    bookmark: IconNode;
+    box: IconNode;
+    calendar: IconNode;
+    chart: IconNode;
+    check: IconNode;
+    'chevron-down': IconNode;
+    'chevron-left': IconNode;
+    'chevron-right': IconNode;
+    'chevron-up': IconNode;
+    'chevrons-left': IconNode;
+    'chevrons-right': IconNode;
+    'chevrons-up-down': IconNode;
+    'circle-alert': IconNode;
+    'circle-check': IconNode;
+    'circle-help': IconNode;
+    'circle-x': IconNode;
+    clock: IconNode;
+    code: IconNode;
+    command: IconNode;
+    copy: IconNode;
+    'corner-down-left': IconNode;
+    'credit-card': IconNode;
+    database: IconNode;
+    download: IconNode;
+    ellipsis: IconNode;
+    'ellipsis-vertical': IconNode;
+    'external-link': IconNode;
+    eye: IconNode;
+    'eye-off': IconNode;
+    file: IconNode;
+    'file-text': IconNode;
+    filter: IconNode;
+    folder: IconNode;
+    'folder-open': IconNode;
+    'git-branch': IconNode;
+    'git-merge': IconNode;
+    globe: IconNode;
+    grip: IconNode;
+    heart: IconNode;
+    house: IconNode;
+    image: IconNode;
+    inbox: IconNode;
+    info: IconNode;
+    layers: IconNode;
+    'layout-grid': IconNode;
+    link: IconNode;
+    list: IconNode;
+    loader: IconNode;
+    lock: IconNode;
+    'log-out': IconNode;
+    mail: IconNode;
+    menu: IconNode;
+    message: IconNode;
+    minus: IconNode;
+    monitor: IconNode;
+    moon: IconNode;
+    package: IconNode;
+    palette: IconNode;
+    'panel-left': IconNode;
+    pencil: IconNode;
+    plus: IconNode;
+    puzzle: IconNode;
+    refresh: IconNode;
+    rocket: IconNode;
+    search: IconNode;
+    settings: IconNode;
+    share: IconNode;
+    'shield-check': IconNode;
+    sparkles: IconNode;
+    star: IconNode;
+    sun: IconNode;
+    terminal: IconNode;
+    trash: IconNode;
+    'trending-down': IconNode;
+    'trending-up': IconNode;
+    'triangle-alert': IconNode;
+    upload: IconNode;
+    user: IconNode;
+    users: IconNode;
+    x: IconNode;
+    zap: IconNode;
+};

package/dist/lib/icon-set.js

@@ -0,0 +1,97 @@
+import { ArrowDown, ArrowLeft, ArrowRight, ArrowUp, ArrowUpDown, Bell, Bookmark, Box, Calendar, ChartBar, Check, ChevronDown, ChevronLeft, ChevronRight, ChevronUp, ChevronsLeft, ChevronsRight, ChevronsUpDown, CircleAlert, CircleCheck, CircleQuestionMark, CircleX, Clock, Code, Command, Copy, CornerDownLeft, CreditCard, Database, Download, Ellipsis, EllipsisVertical, ExternalLink, Eye, EyeOff, File, FileText, Folder, FolderOpen, Funnel, GitBranch, GitMerge, Globe, GripVertical, Heart, House, Image, Inbox, Info, Layers, LayoutGrid, Link, List, LoaderCircle, Lock, LogOut, Mail, Menu, MessageSquare, Minus, Monitor, Moon, Package, Palette, PanelLeft, Pencil, Plus, Puzzle, RefreshCw, Rocket, Search, Settings, Share2, ShieldCheck, Sparkles, Star, Sun, Terminal, Trash, TrendingDown, TrendingUp, TriangleAlert, Upload, User, Users, X, Zap } from "lucide";
+// src/lib/icon-set.ts
+/**
+* The usual icons of an interface, by name: `registerIcons(COMMON_ICONS)` lets pages write any of them
+* (`<jl-icon name="settings">`, `<jl-button icon="plus">`). It costs about 5 kB compressed; an app that names a few
+* icons registers just those instead. `@syware/jlib/all` registers them all.
+*/
+var COMMON_ICONS = {
+	"arrow-down": ArrowDown,
+	"arrow-left": ArrowLeft,
+	"arrow-right": ArrowRight,
+	"arrow-up": ArrowUp,
+	"arrow-up-down": ArrowUpDown,
+	bell: Bell,
+	bookmark: Bookmark,
+	box: Box,
+	calendar: Calendar,
+	chart: ChartBar,
+	check: Check,
+	"chevron-down": ChevronDown,
+	"chevron-left": ChevronLeft,
+	"chevron-right": ChevronRight,
+	"chevron-up": ChevronUp,
+	"chevrons-left": ChevronsLeft,
+	"chevrons-right": ChevronsRight,
+	"chevrons-up-down": ChevronsUpDown,
+	"circle-alert": CircleAlert,
+	"circle-check": CircleCheck,
+	"circle-help": CircleQuestionMark,
+	"circle-x": CircleX,
+	clock: Clock,
+	code: Code,
+	command: Command,
+	copy: Copy,
+	"corner-down-left": CornerDownLeft,
+	"credit-card": CreditCard,
+	database: Database,
+	download: Download,
+	ellipsis: Ellipsis,
+	"ellipsis-vertical": EllipsisVertical,
+	"external-link": ExternalLink,
+	eye: Eye,
+	"eye-off": EyeOff,
+	file: File,
+	"file-text": FileText,
+	filter: Funnel,
+	folder: Folder,
+	"folder-open": FolderOpen,
+	"git-branch": GitBranch,
+	"git-merge": GitMerge,
+	globe: Globe,
+	grip: GripVertical,
+	heart: Heart,
+	house: House,
+	image: Image,
+	inbox: Inbox,
+	info: Info,
+	layers: Layers,
+	"layout-grid": LayoutGrid,
+	link: Link,
+	list: List,
+	loader: LoaderCircle,
+	lock: Lock,
+	"log-out": LogOut,
+	mail: Mail,
+	menu: Menu,
+	message: MessageSquare,
+	minus: Minus,
+	monitor: Monitor,
+	moon: Moon,
+	package: Package,
+	palette: Palette,
+	"panel-left": PanelLeft,
+	pencil: Pencil,
+	plus: Plus,
+	puzzle: Puzzle,
+	refresh: RefreshCw,
+	rocket: Rocket,
+	search: Search,
+	settings: Settings,
+	share: Share2,
+	"shield-check": ShieldCheck,
+	sparkles: Sparkles,
+	star: Star,
+	sun: Sun,
+	terminal: Terminal,
+	trash: Trash,
+	"trending-down": TrendingDown,
+	"trending-up": TrendingUp,
+	"triangle-alert": TriangleAlert,
+	upload: Upload,
+	user: User,
+	users: Users,
+	x: X,
+	zap: Zap
+};
+export { COMMON_ICONS };

package/dist/lib/icons.d.ts

@@ -0,0 +1,12 @@
+import type { IconNode } from 'lucide';
+/**
+ * Adds icons to the ones `jl-icon` knows, by name. Any lucide icon works:
+ * `registerIcons({ rocket: Rocket })` after `import { Rocket } from 'lucide'`, or all the usual ones at once with
+ * `registerIcons(COMMON_ICONS)`.
+ */
+export declare function registerIcons(icons: Record<string, IconNode>): void;
+/** The names `jl-icon` can draw now, in alphabetical order. */
+export declare const iconNames: () => string[];
+export declare const hasIcon: (name: string) => boolean;
+/** An icon as an SVG element; a name nobody registered draws a neutral mark instead of nothing. */
+export declare function iconElement(name: string, size: number): SVGElement;

package/dist/lib/icons.js

@@ -0,0 +1,39 @@
+import { CircleAlert, createElement } from "lucide";
+// src/lib/icons.ts
+var FALLBACK = CircleAlert;
+var STROKE_WIDTH = 1.9;
+/**
+* The icons `jl-icon` can draw, by name. It starts empty: each component registers the icons it draws itself, and
+* a page registers the names it writes, so a bundle holds only the icons in use.
+*/
+var registry = /* @__PURE__ */ new Map();
+var warned = /* @__PURE__ */ new Set();
+/**
+* Adds icons to the ones `jl-icon` knows, by name. Any lucide icon works:
+* `registerIcons({ rocket: Rocket })` after `import { Rocket } from 'lucide'`, or all the usual ones at once with
+* `registerIcons(COMMON_ICONS)`.
+*/
+function registerIcons(icons) {
+	for (const [name, node] of Object.entries(icons)) registry.set(name, node);
+}
+/** The names `jl-icon` can draw now, in alphabetical order. */
+var iconNames = () => [...registry.keys()].sort();
+var hasIcon = (name) => registry.has(name);
+/** The fallback for a name nobody registered, with a warning once per name to say how to fix it. */
+function missing(name) {
+	if (!warned.has(name)) {
+		warned.add(name);
+		console.warn(`jl-icon: no icon named "${name}". Register it: registerIcons({ '${name}': … }) with an icon from lucide, or registerIcons(COMMON_ICONS).`);
+	}
+	return FALLBACK;
+}
+/** An icon as an SVG element; a name nobody registered draws a neutral mark instead of nothing. */
+function iconElement(name, size) {
+	return createElement(registry.get(name) ?? missing(name), {
+		"aria-hidden": "true",
+		height: size,
+		"stroke-width": STROKE_WIDTH,
+		width: size
+	});
+}
+export { hasIcon, iconElement, iconNames, registerIcons };

package/dist/lib/indicator.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Puts a sliding indicator (the underline of a tab, the thumb of a segmented control) over the chosen element:
+ * its offset and size become `--x`, `--y`, `--w` and `--h`, which the component's styles use. The indicator gets
+ * `data-placed` once it has a first position, so the styles can animate its later moves only.
+ */
+export declare function moveIndicator(indicator: HTMLElement, target: HTMLElement | null): void;

package/dist/lib/indicator.js

@@ -0,0 +1,18 @@
+// src/lib/indicator.ts
+/**
+* Puts a sliding indicator (the underline of a tab, the thumb of a segmented control) over the chosen element:
+* its offset and size become `--x`, `--y`, `--w` and `--h`, which the component's styles use. The indicator gets
+* `data-placed` once it has a first position, so the styles can animate its later moves only.
+*/
+function moveIndicator(indicator, target) {
+	indicator.hidden = target === null;
+	if (target === null) return;
+	indicator.style.setProperty("--x", `${target.offsetLeft}px`);
+	indicator.style.setProperty("--y", `${target.offsetTop}px`);
+	indicator.style.setProperty("--w", `${target.offsetWidth}px`);
+	indicator.style.setProperty("--h", `${target.offsetHeight}px`);
+	if (target.offsetWidth > 0 && indicator.dataset.placed === void 0) requestAnimationFrame(() => {
+		indicator.dataset.placed = "";
+	});
+}
+export { moveIndicator };

package/dist/lib/keep-in-view.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Scrolls a list just enough to show one of its items, without scrolling the page as `scrollIntoView` may. The
+ * list must be the item's offset parent (`position: relative`).
+ */
+export declare function keepInView(list: HTMLElement, item: HTMLElement): void;

package/dist/lib/keep-in-view.js

@@ -0,0 +1,15 @@
+// src/lib/keep-in-view.ts
+/**
+* Scrolls a list just enough to show one of its items, without scrolling the page as `scrollIntoView` may. The
+* list must be the item's offset parent (`position: relative`).
+*/
+function keepInView(list, item) {
+	const top = item.offsetTop;
+	const bottom = top + item.offsetHeight;
+	if (top < list.scrollTop) {
+		list.scrollTop = top;
+		return;
+	}
+	if (bottom > list.scrollTop + list.clientHeight) list.scrollTop = bottom - list.clientHeight;
+}
+export { keepInView };

package/dist/lib/key-shortcut.d.ts

@@ -0,0 +1,20 @@
+import type { KeyShortcut } from '../types/key-shortcut.types';
+/** The keys a shortcut's state must match, from the pressed key's modifiers. */
+type PressedKey = Pick<KeyboardEvent, 'key' | 'ctrlKey' | 'metaKey' | 'altKey' | 'shiftKey'>;
+/**
+ * A shortcut from text such as "/", "mod+k" or "ctrl+shift+p". Returns null for empty text or a shortcut without
+ * a key.
+ */
+export declare function parseShortcut(text: string): KeyShortcut | null;
+/** Whether the shortcut asks for a modifier other than Shift: such a shortcut is not typing. */
+export declare const hasCommandModifier: (shortcut: KeyShortcut) => boolean;
+/**
+ * Whether a key press is the shortcut. `mod` is ⌘ on a Mac and Ctrl elsewhere. Shift is only compared when the
+ * shortcut has another modifier or names it: "/" needs Shift on some keyboards, and the key already says "/".
+ */
+export declare function matchesShortcut(event: PressedKey, shortcut: KeyShortcut, mac: boolean): boolean;
+/** The keys to draw for a shortcut, one label per key: ["⌘", "K"] on a Mac, ["Ctrl", "K"] elsewhere. */
+export declare function shortcutLabels(shortcut: KeyShortcut, mac: boolean): string[];
+/** The shortcut as `aria-keyshortcuts` writes it: "Control+K", "/". */
+export declare function shortcutAria(shortcut: KeyShortcut, mac: boolean): string;
+export {};

package/dist/lib/key-shortcut.js

@@ -0,0 +1,100 @@
+// src/lib/key-shortcut.ts
+/** The words a shortcut may use for each modifier: "mod+k", "cmd+shift+p", "ctrl+/". */
+var MODIFIER_WORDS = {
+	alt: "alt",
+	cmd: "meta",
+	command: "meta",
+	control: "ctrl",
+	ctrl: "ctrl",
+	meta: "meta",
+	mod: "mod",
+	option: "alt",
+	shift: "shift"
+};
+var SEPARATOR = "+";
+var isModifierWord = (word) => Object.hasOwn(MODIFIER_WORDS, word);
+var MAC_SYMBOLS = {
+	alt: "⌥",
+	ctrl: "⌃",
+	meta: "⌘",
+	mod: "⌘",
+	shift: "⇧"
+};
+var PC_NAMES = {
+	alt: "Alt",
+	ctrl: "Ctrl",
+	meta: "Meta",
+	mod: "Ctrl",
+	shift: "Shift"
+};
+var ARIA_NAMES = {
+	alt: "Alt",
+	ctrl: "Control",
+	meta: "Meta",
+	mod: "Control",
+	shift: "Shift"
+};
+var MODIFIER_ORDER = [
+	"ctrl",
+	"alt",
+	"shift",
+	"mod",
+	"meta"
+];
+/** Names of keys that read better than their `KeyboardEvent.key`. */
+var KEY_LABELS = {
+	" ": "Space",
+	arrowdown: "↓",
+	arrowleft: "←",
+	arrowright: "→",
+	arrowup: "↑",
+	enter: "↵",
+	escape: "Esc"
+};
+/**
+* A shortcut from text such as "/", "mod+k" or "ctrl+shift+p". Returns null for empty text or a shortcut without
+* a key.
+*/
+function parseShortcut(text) {
+	const parts = text.trim().toLowerCase().split(SEPARATOR).map((part) => part.trim());
+	const key = parts.at(-1) ?? "";
+	if (key === "" || isModifierWord(key)) return null;
+	const modifiers = new Set(parts.slice(0, -1).filter(isModifierWord).map((part) => MODIFIER_WORDS[part]));
+	return {
+		alt: modifiers.has("alt"),
+		ctrl: modifiers.has("ctrl"),
+		key,
+		meta: modifiers.has("meta"),
+		mod: modifiers.has("mod"),
+		shift: modifiers.has("shift")
+	};
+}
+/** Whether the shortcut asks for a modifier other than Shift: such a shortcut is not typing. */
+var hasCommandModifier = (shortcut) => shortcut.mod || shortcut.ctrl || shortcut.meta || shortcut.alt;
+/**
+* Whether a key press is the shortcut. `mod` is ⌘ on a Mac and Ctrl elsewhere. Shift is only compared when the
+* shortcut has another modifier or names it: "/" needs Shift on some keyboards, and the key already says "/".
+*/
+function matchesShortcut(event, shortcut, mac) {
+	const wantsCtrl = shortcut.ctrl || shortcut.mod && !mac;
+	const wantsMeta = shortcut.meta || shortcut.mod && mac;
+	const shiftMatters = shortcut.shift || hasCommandModifier(shortcut);
+	return event.key.toLowerCase() === shortcut.key && event.ctrlKey === wantsCtrl && event.metaKey === wantsMeta && event.altKey === shortcut.alt && (!shiftMatters || event.shiftKey === shortcut.shift);
+}
+var activeModifiers = (shortcut) => MODIFIER_ORDER.filter((modifier) => shortcut[modifier]);
+var keyLabel = (key) => KEY_LABELS[key] ?? (key.length === 1 ? key.toUpperCase() : key);
+/** The keys to draw for a shortcut, one label per key: ["⌘", "K"] on a Mac, ["Ctrl", "K"] elsewhere. */
+function shortcutLabels(shortcut, mac) {
+	const names = mac ? MAC_SYMBOLS : PC_NAMES;
+	return [...activeModifiers(shortcut).map((modifier) => names[modifier]), keyLabel(shortcut.key)];
+}
+/** The shortcut as `aria-keyshortcuts` writes it: "Control+K", "/". */
+function shortcutAria(shortcut, mac) {
+	const names = {
+		...ARIA_NAMES,
+		mod: mac ? "Meta" : "Control"
+	};
+	const key = shortcut.key.length === 1 ? shortcut.key.toUpperCase() : shortcut.key;
+	return [...activeModifiers(shortcut).map((modifier) => names[modifier]), key].join(SEPARATOR);
+}
+export { hasCommandModifier, matchesShortcut, parseShortcut, shortcutAria, shortcutLabels };

package/dist/lib/keycaps.d.ts

@@ -0,0 +1,8 @@
+import type { Keycap, KeyPlatform } from '../types/keycaps.types';
+/**
+ * The keycaps of a shortcut written as "mod+shift+k", in its order: ⌘ ⇧ K on Apple platforms, Ctrl Shift K
+ * elsewhere. `mod` is the command key of the platform.
+ */
+export declare function keycapsOf(keys: string, platform: KeyPlatform): Keycap[];
+/** A shortcut as a screen reader should say it: "Command+Shift+K". */
+export declare const spokenKeys: (keycaps: readonly Keycap[]) => string;

package/dist/lib/keycaps.js

@@ -0,0 +1,162 @@
+// src/lib/keycaps.ts
+var same = (label, name) => ({
+	apple: {
+		label,
+		name
+	},
+	other: {
+		label,
+		name
+	}
+});
+/** The keys drawn differently from their name, by canonical name. */
+var NAMED_KEYS = {
+	alt: {
+		apple: {
+			label: "⌥",
+			name: "Option"
+		},
+		other: {
+			label: "Alt",
+			name: "Alt"
+		}
+	},
+	backspace: {
+		apple: {
+			label: "⌫",
+			name: "Delete"
+		},
+		other: {
+			label: "Backspace",
+			name: "Backspace"
+		}
+	},
+	capslock: {
+		apple: {
+			label: "⇪",
+			name: "Caps Lock"
+		},
+		other: {
+			label: "Caps",
+			name: "Caps Lock"
+		}
+	},
+	cmd: {
+		apple: {
+			label: "⌘",
+			name: "Command"
+		},
+		other: {
+			label: "Win",
+			name: "Windows"
+		}
+	},
+	ctrl: {
+		apple: {
+			label: "⌃",
+			name: "Control"
+		},
+		other: {
+			label: "Ctrl",
+			name: "Control"
+		}
+	},
+	delete: {
+		apple: {
+			label: "⌦",
+			name: "Forward Delete"
+		},
+		other: {
+			label: "Del",
+			name: "Delete"
+		}
+	},
+	down: same("↓", "Down Arrow"),
+	end: same("End", "End"),
+	enter: {
+		apple: {
+			label: "↩",
+			name: "Return"
+		},
+		other: {
+			label: "Enter",
+			name: "Enter"
+		}
+	},
+	esc: same("Esc", "Escape"),
+	home: same("Home", "Home"),
+	left: same("←", "Left Arrow"),
+	mod: {
+		apple: {
+			label: "⌘",
+			name: "Command"
+		},
+		other: {
+			label: "Ctrl",
+			name: "Control"
+		}
+	},
+	pagedown: same("PgDn", "Page Down"),
+	pageup: same("PgUp", "Page Up"),
+	right: same("→", "Right Arrow"),
+	shift: {
+		apple: {
+			label: "⇧",
+			name: "Shift"
+		},
+		other: {
+			label: "Shift",
+			name: "Shift"
+		}
+	},
+	space: same("Space", "Space"),
+	tab: {
+		apple: {
+			label: "⇥",
+			name: "Tab"
+		},
+		other: {
+			label: "Tab",
+			name: "Tab"
+		}
+	},
+	up: same("↑", "Up Arrow")
+};
+/** Other words for the same keys, as `KeyboardEvent.key` and people write them. */
+var ALIASES = {
+	arrowdown: "down",
+	arrowleft: "left",
+	arrowright: "right",
+	arrowup: "up",
+	command: "cmd",
+	control: "ctrl",
+	del: "delete",
+	escape: "esc",
+	meta: "cmd",
+	opt: "alt",
+	option: "alt",
+	return: "enter"
+};
+var KEY_SEPARATOR = /\+(?=.)/;
+var SPOKEN_SEPARATOR = "+";
+var capitalize = (word) => word.charAt(0).toLocaleUpperCase() + word.slice(1);
+function keycapOf(key, platform) {
+	const word = key.toLowerCase();
+	const named = NAMED_KEYS[ALIASES[word] ?? word];
+	if (named !== void 0) return named[platform];
+	const label = capitalize(key);
+	return {
+		label,
+		name: label
+	};
+}
+/**
+* The keycaps of a shortcut written as "mod+shift+k", in its order: ⌘ ⇧ K on Apple platforms, Ctrl Shift K
+* elsewhere. `mod` is the command key of the platform.
+*/
+function keycapsOf(keys, platform) {
+	return keys.split(KEY_SEPARATOR).map((key) => key.trim()).filter((key) => key !== "").map((key) => keycapOf(key, platform));
+}
+/** A shortcut as a screen reader should say it: "Command+Shift+K". */
+var spokenKeys = (keycaps) => keycaps.map((keycap) => keycap.name).join(SPOKEN_SEPARATOR);
+export { keycapsOf, spokenKeys };

package/dist/lib/locale.d.ts

@@ -0,0 +1,4 @@
+/** A locale Intl accepts, in its canonical form; undefined (the runtime's own) for an empty or malformed one. */
+export declare function safeLocale(locale: string): string | undefined;
+/** The locale to write dates and numbers in: the one asked for, else the page's language, else the runtime's. */
+export declare const pageLocale: (preferred?: string) => string | undefined;

package/dist/lib/locale.js

@@ -0,0 +1,13 @@
+// src/lib/locale.ts
+/** A locale Intl accepts, in its canonical form; undefined (the runtime's own) for an empty or malformed one. */
+function safeLocale(locale) {
+	if (locale.trim() === "") return;
+	try {
+		return Intl.getCanonicalLocales(locale)[0];
+	} catch {
+		return;
+	}
+}
+/** The locale to write dates and numbers in: the one asked for, else the page's language, else the runtime's. */
+var pageLocale = (preferred = "") => safeLocale(preferred) ?? safeLocale(document.documentElement.lang);
+export { pageLocale, safeLocale };

package/dist/lib/nav-tree.d.ts

@@ -0,0 +1,9 @@
+import type { SideNavItem, SideNavSection } from '../types/jl-side-nav.types';
+/** The ids from the top of the tree down to the item, the item included; empty when no item has that id. */
+export declare function pathTo(items: readonly SideNavItem[], id: string): string[];
+/** The path to an item, looked for in every section. */
+export declare const pathInSections: (sections: readonly SideNavSection[], id: string) => string[];
+/** The item itself when it has no children, otherwise its first leaf: where a parent leads in the icon rail. */
+export declare function firstLeaf(item: SideNavItem): SideNavItem;
+/** Finds an item by id anywhere in the sections. */
+export declare function findItem(sections: readonly SideNavSection[], id: string): SideNavItem | null;

package/dist/lib/nav-tree.js

@@ -0,0 +1,30 @@
+// src/lib/nav-tree.ts
+var hasChildren = (item) => (item.children?.length ?? 0) > 0;
+/** The ids from the top of the tree down to the item, the item included; empty when no item has that id. */
+function pathTo(items, id) {
+	for (const item of items) {
+		if (item.id === id) return [item.id];
+		const below = pathTo(item.children ?? [], id);
+		if (below.length > 0) return [item.id, ...below];
+	}
+	return [];
+}
+/** The path to an item, looked for in every section. */
+var pathInSections = (sections, id) => pathTo(sections.flatMap((section) => section.items), id);
+/** The item itself when it has no children, otherwise its first leaf: where a parent leads in the icon rail. */
+function firstLeaf(item) {
+	const first = item.children?.[0];
+	return hasChildren(item) && first !== void 0 ? firstLeaf(first) : item;
+}
+/** Finds an item by id anywhere in the sections. */
+function findItem(sections, id) {
+	const search = (items) => {
+		for (const item of items) {
+			const found = item.id === id ? item : search(item.children ?? []);
+			if (found !== null) return found;
+		}
+		return null;
+	};
+	return search(sections.flatMap((section) => section.items));
+}
+export { findItem, firstLeaf, pathInSections, pathTo };

package/dist/lib/numeric.d.ts

@@ -0,0 +1,20 @@
+import type { SliderMark } from '../types/jl-slider.types';
+/** A number written in a field or an attribute; empty or unreadable text gives null. */
+export declare function parseNumber(text: string | null): number | null;
+/** A number kept within bounds; a null bound does not limit that side. */
+export declare function clamp(value: number, min: number | null, max: number | null): number;
+/** How many decimals a number has as written: 0.25 has 2, so sums of steps print without float noise. */
+export declare function decimalsOf(value: number): number;
+export declare function roundTo(value: number, decimals: number): number;
+/**
+ * The value one step up or down, within bounds, rounded to the decimals of the step and the value. An empty value
+ * counts as zero.
+ */
+export declare function stepValue(value: number | null, step: number, direction: 1 | -1, min: number | null, max: number | null): number;
+/** Where a value sits between min and max, from 0 to 1; an empty range gives 0. */
+export declare function fractionOf(value: number, min: number, max: number): number;
+/**
+ * The marks of a slider from what a page wrote: numbers (`[0, 50, 100]`) or objects with a label
+ * (`[{ "value": 0, "label": "Off" }]`). Marks outside the range and unreadable entries are left out.
+ */
+export declare function marksOf(raw: unknown, min: number, max: number): SliderMark[];