@stll/ui 0.2.0 → 0.4.0

package/dist/calendar/index.d.ts

@@ -0,0 +1,4 @@
+import { CalendarCell, CalendarEntryButton, CalendarEntrySurface, CalendarGrid, CalendarHeaderCell, CalendarHeaderRow } from "./primitives.js";
+import { CalendarDateRange, ResourceCalendarLaneLayout, ResourceCalendarLanePlacement, ResourceCalendarPlacement, assertConsecutiveCalendarDates, getResourceCalendarPlacement, layoutResourceCalendarEntries, nextCalendarDate } from "./resource-calendar.logic.js";
+import { ResourceCalendar, ResourceCalendarColumn, ResourceCalendarEntry, ResourceCalendarEntryTone, ResourceCalendarResource } from "./resource-calendar.js";
+export { CalendarCell, type CalendarDateRange, CalendarEntryButton, CalendarEntrySurface, CalendarGrid, CalendarHeaderCell, CalendarHeaderRow, ResourceCalendar, type ResourceCalendarColumn, type ResourceCalendarEntry, type ResourceCalendarEntryTone, type ResourceCalendarLaneLayout, type ResourceCalendarLanePlacement, type ResourceCalendarPlacement, type ResourceCalendarResource, assertConsecutiveCalendarDates, getResourceCalendarPlacement, layoutResourceCalendarEntries, nextCalendarDate };

package/dist/calendar/index.js

@@ -0,0 +1,4 @@
+import { CalendarCell, CalendarEntryButton, CalendarEntrySurface, CalendarGrid, CalendarHeaderCell, CalendarHeaderRow } from "./primitives.js";
+import { assertConsecutiveCalendarDates, getResourceCalendarPlacement, layoutResourceCalendarEntries, nextCalendarDate } from "./resource-calendar.logic.js";
+import { ResourceCalendar } from "./resource-calendar.js";
+export { CalendarCell, CalendarEntryButton, CalendarEntrySurface, CalendarGrid, CalendarHeaderCell, CalendarHeaderRow, ResourceCalendar, assertConsecutiveCalendarDates, getResourceCalendarPlacement, layoutResourceCalendarEntries, nextCalendarDate };

package/dist/calendar/primitives.d.ts

@@ -0,0 +1,10 @@
+import * as React$1 from "react";
+//#region src/calendar/primitives.d.ts
+declare const CalendarGrid: ({ className, ...props }: React$1.ComponentProps<"div">) => React$1.JSX.Element;
+declare const CalendarHeaderRow: ({ className, ...props }: React$1.ComponentProps<"div">) => React$1.JSX.Element;
+declare const CalendarHeaderCell: ({ className, ...props }: React$1.ComponentProps<"div">) => React$1.JSX.Element;
+declare const CalendarCell: ({ className, ...props }: React$1.ComponentProps<"div">) => React$1.JSX.Element;
+declare const CalendarEntryButton: ({ className, ...props }: React$1.ComponentProps<"button">) => React$1.JSX.Element;
+declare const CalendarEntrySurface: ({ className, ...props }: React$1.ComponentProps<"article">) => React$1.JSX.Element;
+//#endregion
+export { CalendarCell, CalendarEntryButton, CalendarEntrySurface, CalendarGrid, CalendarHeaderCell, CalendarHeaderRow };

package/dist/calendar/primitives.js

@@ -0,0 +1,36 @@
+import { cn } from "../lib/utils.js";
+import { jsx } from "react/jsx-runtime";
+//#region src/calendar/primitives.tsx
+const CalendarGrid = ({ className, ...props }) => /* @__PURE__ */ jsx("div", {
+	className: cn("grid", className),
+	"data-slot": "calendar-grid",
+	...props
+});
+const CalendarHeaderRow = ({ className, ...props }) => /* @__PURE__ */ jsx("div", {
+	className: cn("grid border-b", className),
+	"data-slot": "calendar-header-row",
+	...props
+});
+const CalendarHeaderCell = ({ className, ...props }) => /* @__PURE__ */ jsx("div", {
+	className: cn("text-muted-foreground border-e px-2 py-2 text-center text-xs font-medium last:border-e-0", className),
+	"data-slot": "calendar-header-cell",
+	...props
+});
+const CalendarCell = ({ className, ...props }) => /* @__PURE__ */ jsx("div", {
+	className: cn("border-e border-b", className),
+	"data-slot": "calendar-cell",
+	...props
+});
+const CalendarEntryButton = ({ className, ...props }) => /* @__PURE__ */ jsx("button", {
+	className: cn("focus-visible:ring-ring min-w-0 rounded-md text-start text-xs outline-none focus-visible:ring-2 focus-visible:ring-offset-1", className),
+	"data-slot": "calendar-entry",
+	type: "button",
+	...props
+});
+const CalendarEntrySurface = ({ className, ...props }) => /* @__PURE__ */ jsx("article", {
+	className: cn("min-w-0 rounded-md text-start text-xs", className),
+	"data-slot": "calendar-entry",
+	...props
+});
+//#endregion
+export { CalendarCell, CalendarEntryButton, CalendarEntrySurface, CalendarGrid, CalendarHeaderCell, CalendarHeaderRow };

package/dist/calendar/resource-calendar.d.ts

@@ -0,0 +1,35 @@
+import { ReactElement, ReactNode } from "react";
+//#region src/calendar/resource-calendar.d.ts
+type ResourceCalendarColumn = {
+  date: string;
+  label: ReactNode;
+  meta?: ReactNode;
+};
+type ResourceCalendarResource = {
+  id: string;
+  label: ReactNode;
+  meta?: ReactNode;
+};
+type ResourceCalendarEntryTone = "accent" | "neutral" | "warning" | "destructive";
+type ResourceCalendarEntry = {
+  accessibleLabel: string;
+  endDateExclusive: string;
+  id: string;
+  label: ReactNode;
+  meta?: ReactNode;
+  resourceId: string;
+  startDate: string;
+  tone?: ResourceCalendarEntryTone;
+};
+type ResourceCalendarProps = {
+  ariaLabel: string;
+  columns: readonly ResourceCalendarColumn[];
+  empty?: ReactNode;
+  entries: readonly ResourceCalendarEntry[];
+  onSelectEntry?: (entry: ResourceCalendarEntry) => void;
+  resourceHeader: ReactNode;
+  resources: readonly ResourceCalendarResource[];
+};
+declare const ResourceCalendar: ({ ariaLabel, columns, empty, entries, onSelectEntry, resourceHeader, resources }: ResourceCalendarProps) => ReactElement;
+//#endregion
+export { ResourceCalendar, ResourceCalendarColumn, ResourceCalendarEntry, ResourceCalendarEntryTone, ResourceCalendarResource };

package/dist/calendar/resource-calendar.js

@@ -0,0 +1,184 @@
+import { cn } from "../lib/utils.js";
+import { CalendarCell, CalendarEntryButton, CalendarEntrySurface, CalendarHeaderCell, CalendarHeaderRow } from "./primitives.js";
+import { assertConsecutiveCalendarDates, layoutResourceCalendarEntries, nextCalendarDate } from "./resource-calendar.logic.js";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import { useId } from "react";
+//#region src/calendar/resource-calendar.tsx
+const ResourceCalendar = ({ ariaLabel, columns, empty, entries, onSelectEntry, resourceHeader, resources }) => {
+	assertResourceCalendarContract({
+		columns,
+		entries,
+		resources
+	});
+	const calendarId = useId();
+	if (resources.length === 0) return /* @__PURE__ */ jsx("div", {
+		"data-slot": "resource-calendar-empty",
+		children: empty
+	});
+	const gridStyle = { gridTemplateColumns: `14rem repeat(${String(columns.length)}, minmax(7rem, 1fr))` };
+	const calendarWidthStyle = { minWidth: `${String(14 + columns.length * 7)}rem` };
+	const visibleRange = {
+		endDateExclusive: nextCalendarDate(columns.at(-1)?.date ?? ""),
+		startDate: columns.at(0)?.date ?? ""
+	};
+	const entriesByResource = /* @__PURE__ */ new Map();
+	for (const entry of entries) {
+		const existing = entriesByResource.get(entry.resourceId);
+		if (existing === void 0) {
+			entriesByResource.set(entry.resourceId, [entry]);
+			continue;
+		}
+		existing.push(entry);
+	}
+	const getColumnHeaderId = (index) => `${calendarId}-column-${String(index)}`;
+	return /* @__PURE__ */ jsx("section", {
+		"aria-colcount": columns.length + 1,
+		"aria-label": ariaLabel,
+		"aria-rowcount": resources.length + 1,
+		className: "border-border bg-card overflow-x-auto rounded-xl border",
+		"data-slot": "resource-calendar",
+		role: "table",
+		children: /* @__PURE__ */ jsxs("div", {
+			className: "w-full",
+			style: calendarWidthStyle,
+			children: [/* @__PURE__ */ jsxs(CalendarHeaderRow, {
+				role: "row",
+				style: gridStyle,
+				children: [/* @__PURE__ */ jsx(CalendarHeaderCell, {
+					"aria-colindex": 1,
+					className: "bg-card sticky start-0 z-30 text-start font-semibold tracking-wide uppercase",
+					role: "columnheader",
+					children: resourceHeader
+				}), columns.map((column, index) => /* @__PURE__ */ jsxs(CalendarHeaderCell, {
+					"aria-colindex": index + 2,
+					id: getColumnHeaderId(index),
+					role: "columnheader",
+					children: [/* @__PURE__ */ jsx("span", {
+						className: "block",
+						children: column.label
+					}), column.meta === void 0 ? null : /* @__PURE__ */ jsx("span", {
+						className: "text-foreground mt-0.5 block font-semibold",
+						children: column.meta
+					})]
+				}, column.date))]
+			}), resources.map((resource, resourceIndex) => {
+				const resourceEntries = entriesByResource.get(resource.id) ?? [];
+				const layout = layoutResourceCalendarEntries(resourceEntries, visibleRange);
+				const resourceEntryById = new Map(resourceEntries.map((entry) => [entry.id, entry]));
+				const visibleEntriesByColumn = /* @__PURE__ */ new Map();
+				for (const placement of layout.placements) {
+					const entry = resourceEntryById.get(placement.entryId);
+					if (entry === void 0) throw new TypeError(`Resource calendar layout references unknown entry ${placement.entryId}`);
+					const existing = visibleEntriesByColumn.get(placement.columnStart);
+					if (existing === void 0) {
+						visibleEntriesByColumn.set(placement.columnStart, [{
+							entry,
+							placement
+						}]);
+						continue;
+					}
+					existing.push({
+						entry,
+						placement
+					});
+				}
+				const resourceHeaderId = `${calendarId}-resource-${String(resourceIndex)}`;
+				const resourceRowStyle = {
+					...gridStyle,
+					minHeight: `${String(Math.max(5, layout.rowCount * 3.75))}rem`
+				};
+				return /* @__PURE__ */ jsxs("div", {
+					className: "border-border relative grid min-h-20 border-b last:border-b-0",
+					"data-slot": "resource-calendar-row",
+					role: "row",
+					style: resourceRowStyle,
+					children: [/* @__PURE__ */ jsxs(CalendarCell, {
+						"aria-colindex": 1,
+						"aria-rowindex": resourceIndex + 2,
+						className: "bg-card sticky start-0 z-20 border-b-0 px-4 py-3",
+						id: resourceHeaderId,
+						role: "rowheader",
+						children: [/* @__PURE__ */ jsx("span", {
+							className: "block truncate text-sm font-semibold",
+							children: resource.label
+						}), resource.meta === void 0 ? null : /* @__PURE__ */ jsx("span", {
+							className: "text-muted-foreground mt-1 block truncate text-xs",
+							children: resource.meta
+						})]
+					}), columns.map((column, columnIndex) => {
+						const columnStart = columnIndex + 2;
+						const visibleEntries = visibleEntriesByColumn.get(columnStart) ?? [];
+						return /* @__PURE__ */ jsx(CalendarCell, {
+							"aria-colindex": columnStart,
+							"aria-labelledby": `${resourceHeaderId} ${getColumnHeaderId(columnIndex)}`,
+							"aria-rowindex": resourceIndex + 2,
+							className: "bg-background/40 relative border-b-0 last:border-e-0",
+							role: "gridcell",
+							children: visibleEntries.map(({ entry, placement }) => {
+								const labelledBy = [resourceHeaderId, ...Array.from({ length: placement.span }, (_, index) => getColumnHeaderId(columnIndex + index))].join(" ");
+								return /* @__PURE__ */ jsx(ResourceCalendarEntryView, {
+									entry,
+									labelledBy,
+									onSelectEntry,
+									placement,
+									rowCount: layout.rowCount
+								}, entry.id);
+							})
+						}, column.date);
+					})]
+				}, resource.id);
+			})]
+		})
+	});
+};
+const RESOURCE_CALENDAR_ENTRY_TONES = {
+	accent: "bg-primary text-primary-foreground",
+	destructive: "border-destructive/32 bg-destructive/12 text-foreground border",
+	neutral: "border-border bg-muted text-foreground border",
+	warning: "border-warning/30 bg-warning/15 text-foreground border"
+};
+const ResourceCalendarEntryView = ({ entry, labelledBy, onSelectEntry, placement, rowCount }) => {
+	const className = cn("h-full w-full px-3 py-2 font-medium shadow-sm", RESOURCE_CALENDAR_ENTRY_TONES[entry.tone ?? "accent"]);
+	const style = {
+		blockSize: `${String(100 / rowCount)}%`,
+		insetBlockStart: `${String((placement.rowStart - 1) * 100 / rowCount)}%`,
+		insetInlineStart: 0,
+		inlineSize: `calc(${String(placement.span)} * 100%)`
+	};
+	const content = /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsx("span", {
+		className: "block truncate",
+		children: entry.label
+	}), entry.meta === void 0 ? null : /* @__PURE__ */ jsx("span", {
+		className: "block truncate opacity-75",
+		children: entry.meta
+	})] });
+	return /* @__PURE__ */ jsx("div", {
+		className: "absolute z-10 min-w-0 p-2",
+		style,
+		children: onSelectEntry === void 0 ? /* @__PURE__ */ jsx(CalendarEntrySurface, {
+			"aria-describedby": labelledBy,
+			"aria-label": entry.accessibleLabel,
+			className,
+			children: content
+		}) : /* @__PURE__ */ jsx(CalendarEntryButton, {
+			"aria-describedby": labelledBy,
+			"aria-label": entry.accessibleLabel,
+			className,
+			onClick: () => onSelectEntry(entry),
+			children: content
+		})
+	});
+};
+const assertUniqueIds = (ids, label) => {
+	if (new Set(ids).size !== ids.length) throw new TypeError(`${label} ids must be unique`);
+};
+const assertResourceCalendarContract = ({ columns, entries, resources }) => {
+	assertConsecutiveCalendarDates(columns.map(({ date }) => date));
+	assertUniqueIds(resources.map(({ id }) => id), "Resource calendar resource");
+	assertUniqueIds(entries.map(({ id }) => id), "Resource calendar entry");
+	const resourceIds = new Set(resources.map(({ id }) => id));
+	const orphan = entries.find(({ resourceId }) => !resourceIds.has(resourceId));
+	if (orphan !== void 0) throw new TypeError(`Resource calendar entry ${orphan.id} references an unknown resource`);
+};
+//#endregion
+export { ResourceCalendar };

package/dist/calendar/resource-calendar.logic.d.ts

@@ -0,0 +1,28 @@
+//#region src/calendar/resource-calendar.logic.d.ts
+type CalendarDateRange = {
+  endDateExclusive: string;
+  startDate: string;
+};
+type ResourceCalendarPlacement = {
+  columnStart: number;
+  span: number;
+};
+type ResourceCalendarLanePlacement = ResourceCalendarPlacement & {
+  entryId: string;
+  rowStart: number;
+};
+type ResourceCalendarLaneLayout = {
+  placements: ResourceCalendarLanePlacement[];
+  rowCount: number;
+};
+declare const getResourceCalendarPlacement: ({ entry, visibleRange }: {
+  entry: CalendarDateRange;
+  visibleRange: CalendarDateRange;
+}) => ResourceCalendarPlacement | null;
+declare const assertConsecutiveCalendarDates: (dates: readonly string[]) => void;
+declare const nextCalendarDate: (value: string) => string;
+declare const layoutResourceCalendarEntries: (entries: readonly (CalendarDateRange & {
+  id: string;
+})[], visibleRange: CalendarDateRange) => ResourceCalendarLaneLayout;
+//#endregion
+export { CalendarDateRange, ResourceCalendarLaneLayout, ResourceCalendarLanePlacement, ResourceCalendarPlacement, assertConsecutiveCalendarDates, getResourceCalendarPlacement, layoutResourceCalendarEntries, nextCalendarDate };

package/dist/calendar/resource-calendar.logic.js

@@ -0,0 +1,88 @@
+//#region src/calendar/resource-calendar.logic.ts
+const ISO_DATE_PATTERN = /^\d{4}-\d{2}-\d{2}$/u;
+const DAY_IN_MS = 864e5;
+const toUTCDate = (value) => {
+	if (!ISO_DATE_PATTERN.test(value)) return null;
+	const date = /* @__PURE__ */ new Date(`${value}T00:00:00.000Z`);
+	return date.toISOString().slice(0, 10) === value ? date : null;
+};
+const differenceInCalendarDays = (later, earlier) => {
+	const laterDate = toUTCDate(later);
+	const earlierDate = toUTCDate(earlier);
+	if (laterDate === null || earlierDate === null) throw new RangeError("Calendar dates must use normalized YYYY-MM-DD values");
+	return (laterDate.getTime() - earlierDate.getTime()) / DAY_IN_MS;
+};
+const getResourceCalendarPlacement = ({ entry, visibleRange }) => {
+	const visibleDayCount = differenceInCalendarDays(visibleRange.endDateExclusive, visibleRange.startDate);
+	const entryDayCount = differenceInCalendarDays(entry.endDateExclusive, entry.startDate);
+	if (visibleDayCount <= 0 || entryDayCount <= 0) throw new RangeError("Calendar date ranges must be non-empty and half-open");
+	if (entry.startDate >= visibleRange.endDateExclusive || entry.endDateExclusive <= visibleRange.startDate) return null;
+	const clippedStart = entry.startDate < visibleRange.startDate ? visibleRange.startDate : entry.startDate;
+	const clippedEnd = entry.endDateExclusive > visibleRange.endDateExclusive ? visibleRange.endDateExclusive : entry.endDateExclusive;
+	return {
+		columnStart: differenceInCalendarDays(clippedStart, visibleRange.startDate) + 2,
+		span: differenceInCalendarDays(clippedEnd, clippedStart)
+	};
+};
+const assertConsecutiveCalendarDates = (dates) => {
+	if (dates.length === 0) throw new RangeError("A resource calendar needs at least one date column");
+	const first = dates.at(0);
+	if (first === void 0 || toUTCDate(first) === null) throw new RangeError("Resource calendar date columns must be consecutive normalized dates");
+	for (let index = 1; index < dates.length; index += 1) {
+		const previous = dates.at(index - 1);
+		const current = dates.at(index);
+		if (previous === void 0 || current === void 0 || differenceInCalendarDays(current, previous) !== 1) throw new RangeError("Resource calendar date columns must be consecutive normalized dates");
+	}
+};
+const nextCalendarDate = (value) => {
+	const date = toUTCDate(value);
+	if (date === null) throw new RangeError("Calendar dates must use normalized YYYY-MM-DD values");
+	date.setUTCDate(date.getUTCDate() + 1);
+	const nextDate = date.toISOString().slice(0, 10);
+	if (toUTCDate(nextDate) === null) throw new RangeError("Calendar dates must have a following normalized YYYY-MM-DD value");
+	return nextDate;
+};
+const layoutResourceCalendarEntries = (entries, visibleRange) => {
+	const visibleEntries = [];
+	const entryIds = /* @__PURE__ */ new Set();
+	for (const entry of entries) {
+		if (entryIds.has(entry.id)) throw new TypeError("Resource calendar entry ids must be unique");
+		entryIds.add(entry.id);
+		const placement = getResourceCalendarPlacement({
+			entry,
+			visibleRange
+		});
+		if (placement === null) continue;
+		visibleEntries.push({
+			columnStart: placement.columnStart,
+			entryId: entry.id,
+			span: placement.span
+		});
+	}
+	visibleEntries.sort((left, right) => {
+		const startDifference = left.columnStart - right.columnStart;
+		if (startDifference !== 0) return startDifference;
+		if (left.entryId < right.entryId) return -1;
+		if (left.entryId > right.entryId) return 1;
+		return 0;
+	});
+	const laneEnds = [];
+	const placements = [];
+	for (const entry of visibleEntries) {
+		const firstAvailableLane = laneEnds.findIndex((laneEnd) => laneEnd <= entry.columnStart);
+		const lane = firstAvailableLane === -1 ? laneEnds.length : firstAvailableLane;
+		laneEnds[lane] = entry.columnStart + entry.span;
+		placements.push({
+			columnStart: entry.columnStart,
+			entryId: entry.entryId,
+			rowStart: lane + 1,
+			span: entry.span
+		});
+	}
+	return {
+		placements,
+		rowCount: Math.max(1, laneEnds.length)
+	};
+};
+//#endregion
+export { assertConsecutiveCalendarDates, getResourceCalendarPlacement, layoutResourceCalendarEntries, nextCalendarDate };

package/dist/components/button-variants.d.ts

@@ -10,7 +10,7 @@
  */
 declare const buttonAccessibleDisabledClass = "cursor-not-allowed opacity-64";
 declare const buttonVariants: (props?: ({
-  size?: "default" | "icon" | "icon-lg" | "icon-sm" | "icon-xl" | "icon-xs" | "lg" | "sm" | "xl" | "xs" | null | undefined;
+  size?: "icon" | "sm" | "default" | "lg" | "icon-lg" | "icon-sm" | "icon-xl" | "icon-xs" | "xl" | "xs" | null | undefined;
   variant?: "link" | "default" | "destructive" | "destructive-outline" | "ghost" | "outline" | "secondary" | null | undefined;
 } & import("class-variance-authority/types").ClassProp) | undefined) => string;
 //#endregion

package/dist/components/outline-rail.d.ts

@@ -3,9 +3,13 @@ import { ReactNode, RefObject } from "react";
 type OutlineItem = {
   id: string;
   label: string;
+  /** What the entry contains, after the label that names it. The label
+   *  stays whole; the title is what truncates when the row is narrow. */
+  title?: string;
   /** Nesting depth among included items; drives indent + tick taper. */
   level: number;
-  /** Optional trailing annotation in the panel (e.g. a page number). */
+  /** Optional trailing annotation in the panel (e.g. a page number or a
+   *  provision range); never truncated. */
   meta?: string;
   /** Optional CSS custom-property name colouring this entry's tick + chip
    *  (e.g. "--option-blue"). Defaults to the neutral foreground. */

package/dist/components/outline-rail.js

@@ -1,7 +1,7 @@
 "use client";
 import { cn } from "../lib/utils.js";
 import { Tooltip, TooltipContent as TooltipPopup, TooltipTrigger } from "./tooltip.js";
-import { jsx, jsxs } from "react/jsx-runtime";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 import { useCallback, useEffect, useId, useLayoutEffect, useMemo, useRef, useState } from "react";
 //#region src/components/outline-rail.tsx
 /**
@@ -23,6 +23,8 @@ const TICK_BASE_WIDTH = 6;
 const TICK_LEVEL_STEP = 2;
 const TICK_MAX_LEVEL = 5;
 const RAIL_MAX_TICKS = 40;
+/** The entry as one line of text: label, then its title when it has one. */
+const entryText = (item) => item.title === void 0 ? item.label : `${item.label} ${item.title}`;
 const tickWidth = (level) => {
 	return TICK_BASE_WIDTH + (TICK_MAX_LEVEL - Math.min(Math.max(level, 0), TICK_MAX_LEVEL)) * TICK_LEVEL_STEP;
 };
@@ -199,7 +201,8 @@ const OutlineRail = ({ items, scrollContainerRef, resolvePct, onJump, activeId,
 		}
 		onJumpRef.current(id, container);
 	}, [activeId, scrollContainerRef]);
-	const toggleCollapse = useCallback((id, level, rowEl) => {
+	const toggleCollapse = useCallback((id, rowEl) => {
+		const rowTop = rowEl?.getBoundingClientRect().top;
 		setToggled((prev) => new Set(prev).add(id));
 		setCollapsed((prev) => {
 			const next = new Set(prev);
@@ -209,9 +212,8 @@ const OutlineRail = ({ items, scrollContainerRef, resolvePct, onJump, activeId,
 		});
 		requestAnimationFrame(() => {
 			const panel = panelRef.current;
-			if (!panel || !rowEl) return;
-			const target = panel.getBoundingClientRect().top + level * ROW_H;
-			panel.scrollTop += rowEl.getBoundingClientRect().top - target;
+			if (!panel || !rowEl || rowTop === void 0) return;
+			panel.scrollTop += rowEl.getBoundingClientRect().top - rowTop;
 		});
 	}, []);
 	const openPanel = useCallback(() => {
@@ -261,7 +263,7 @@ const OutlineRail = ({ items, scrollContainerRef, resolvePct, onJump, activeId,
 					"aria-expanded": !isCollapsed,
 					"aria-label": isCollapsed ? "Expand" : "Collapse",
 					className: "text-muted-foreground hover:text-foreground flex size-5 shrink-0 items-center justify-center",
-					onClick: (event) => toggleCollapse(node.item.id, node.item.level, event.currentTarget.parentElement),
+					onClick: (event) => toggleCollapse(node.item.id, event.currentTarget.parentElement),
 					style: { marginInlineStart: indent - 4 },
 					type: "button",
 					children: /* @__PURE__ */ jsx(Chevron, { open: !isCollapsed })
@@ -277,12 +279,21 @@ const OutlineRail = ({ items, scrollContainerRef, resolvePct, onJump, activeId,
 				}),
 				/* @__PURE__ */ jsxs(Tooltip, { children: [/* @__PURE__ */ jsx(TooltipTrigger, {
 					render: /* @__PURE__ */ jsx("button", {
-						className: cn("min-w-0 flex-1 truncate py-1.5 text-start text-[13px] leading-snug", rowTextClass(isActive, hasChildren)),
+						className: cn("flex min-w-0 flex-1 items-baseline gap-1.5 py-1.5 text-start text-[13px] leading-snug", rowTextClass(isActive, hasChildren)),
 						onClick: () => jumpTo(node.item.id),
 						type: "button"
 					}),
-					children: node.item.label
-				}), /* @__PURE__ */ jsx(TooltipPopup, { children: node.item.label })] }),
+					children: node.item.title === void 0 ? /* @__PURE__ */ jsx("span", {
+						className: "min-w-0 truncate",
+						children: node.item.label
+					}) : /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsx("span", {
+						className: "shrink-0 font-medium",
+						children: node.item.label
+					}), /* @__PURE__ */ jsx("span", {
+						className: "min-w-0 truncate font-normal",
+						children: node.item.title
+					})] })
+				}), /* @__PURE__ */ jsx(TooltipPopup, { children: entryText(node.item) })] }),
 				node.item.meta !== void 0 && /* @__PURE__ */ jsx("span", {
 					className: "text-foreground-placeholder shrink-0 ps-2 text-[11px] tabular-nums",
 					children: node.item.meta

package/dist/data-table/index.d.ts

@@ -0,0 +1,2 @@
+import { TableColumnCapabilities, TableColumnDescriptor, TableSchema, duplicateColumnIds, findTableColumn, hideableColumnIds, sortableColumnIds, tableColumnIds, tableColumnSizing, visibleColumnIds } from "./schema.js";
+export { type TableColumnCapabilities, type TableColumnDescriptor, type TableSchema, duplicateColumnIds, findTableColumn, hideableColumnIds, sortableColumnIds, tableColumnIds, tableColumnSizing, visibleColumnIds };

package/dist/data-table/index.js

@@ -0,0 +1,2 @@
+import { duplicateColumnIds, findTableColumn, hideableColumnIds, sortableColumnIds, tableColumnIds, tableColumnSizing, visibleColumnIds } from "./schema.js";
+export { duplicateColumnIds, findTableColumn, hideableColumnIds, sortableColumnIds, tableColumnIds, tableColumnSizing, visibleColumnIds };

package/dist/data-table/schema.d.ts

@@ -0,0 +1,70 @@
+//#region src/data-table/schema.d.ts
+/**
+ * A table's schema: which columns exist, what each can do, and how wide it
+ * starts. Not how a cell draws — that is the caller's, and it is the reason
+ * this module holds no React.
+ *
+ * The split matters because "which columns does this view have, and which of
+ * them can be sorted, hidden, resized or pinned" is a question about data, and
+ * a question about data can be answered by a test. It used to be answerable
+ * only by rendering the table and asking TanStack.
+ */
+/** What a reader may do to a column. */
+type TableColumnCapabilities = {
+  sort: boolean;
+  hide: boolean;
+  resize: boolean;
+  pin: boolean;
+};
+/**
+ * One column.
+ *
+ * `render` is whatever the caller needs to draw the column: this module never
+ * looks inside it, which is what keeps the schema free of any idea about what
+ * a row holds.
+ */
+type TableColumnDescriptor<TRender> = {
+  /** Unique within the schema, and stable across renders. */
+  id: string;
+  /** Header text. Empty for a column whose header draws no text. */
+  label: string;
+  render: TRender;
+  /** Starting width, in pixels. */
+  size: number;
+  /** Narrowest this column may be resized to; the schema's default if absent. */
+  minSize?: number | undefined;
+  capabilities: TableColumnCapabilities;
+  /**
+   * Metadata columns read quieter than content ones; a utility column
+   * (a selection checkbox, an add-column affordance) draws no value at all.
+   */
+  emphasis: "content" | "metadata" | "utility";
+};
+type TableSchema<TRender> = {
+  columns: readonly TableColumnDescriptor<TRender>[];
+  /** Narrowest any column may be resized to. */
+  defaultMinSize: number;
+};
+/** Every column a schema declares, in order. */
+declare const tableColumnIds: <TRender>(schema: TableSchema<TRender>) => string[];
+declare const sortableColumnIds: <TRender>(schema: TableSchema<TRender>) => string[];
+declare const hideableColumnIds: <TRender>(schema: TableSchema<TRender>) => string[];
+declare const findTableColumn: <TRender>(schema: TableSchema<TRender>, id: string) => TableColumnDescriptor<TRender> | undefined;
+/**
+ * Which columns a view shows.
+ *
+ * A column that cannot be hidden stays visible whatever the stored hidden list
+ * says, so a stale list — a column that lost its hide capability while it was
+ * hidden — cannot strand the table without its select or name column.
+ */
+declare const visibleColumnIds: <TRender>(schema: TableSchema<TRender>, hiddenColumnIds: readonly string[]) => string[];
+/** The starting width of every column, keyed by id. */
+declare const tableColumnSizing: <TRender>(schema: TableSchema<TRender>) => Record<string, number>;
+/**
+ * A duplicate column id silently drops a column: the table keys by id, so the
+ * second declaration wins and the first disappears with no error anywhere.
+ * Callers that build a schema from user data (a property list) check here.
+ */
+declare const duplicateColumnIds: <TRender>(schema: TableSchema<TRender>) => string[];
+//#endregion
+export { TableColumnCapabilities, TableColumnDescriptor, TableSchema, duplicateColumnIds, findTableColumn, hideableColumnIds, sortableColumnIds, tableColumnIds, tableColumnSizing, visibleColumnIds };

package/dist/data-table/schema.js

@@ -0,0 +1,40 @@
+//#region src/data-table/schema.ts
+/** Every column a schema declares, in order. */
+const tableColumnIds = (schema) => schema.columns.map((column) => column.id);
+const withCapability = (schema, capability) => schema.columns.filter((column) => column.capabilities[capability]).map((column) => column.id);
+const sortableColumnIds = (schema) => withCapability(schema, "sort");
+const hideableColumnIds = (schema) => withCapability(schema, "hide");
+const findTableColumn = (schema, id) => schema.columns.find((column) => column.id === id);
+/**
+* Which columns a view shows.
+*
+* A column that cannot be hidden stays visible whatever the stored hidden list
+* says, so a stale list — a column that lost its hide capability while it was
+* hidden — cannot strand the table without its select or name column.
+*/
+const visibleColumnIds = (schema, hiddenColumnIds) => {
+	const hidden = new Set(hiddenColumnIds);
+	return schema.columns.filter((column) => !column.capabilities.hide || !hidden.has(column.id)).map((column) => column.id);
+};
+/** The starting width of every column, keyed by id. */
+const tableColumnSizing = (schema) => {
+	const sizing = {};
+	for (const column of schema.columns) sizing[column.id] = column.size;
+	return sizing;
+};
+/**
+* A duplicate column id silently drops a column: the table keys by id, so the
+* second declaration wins and the first disappears with no error anywhere.
+* Callers that build a schema from user data (a property list) check here.
+*/
+const duplicateColumnIds = (schema) => {
+	const seen = /* @__PURE__ */ new Set();
+	const duplicates = /* @__PURE__ */ new Set();
+	for (const column of schema.columns) {
+		if (seen.has(column.id)) duplicates.add(column.id);
+		seen.add(column.id);
+	}
+	return [...duplicates];
+};
+//#endregion
+export { duplicateColumnIds, findTableColumn, hideableColumnIds, sortableColumnIds, tableColumnIds, tableColumnSizing, visibleColumnIds };