@heyramzi/ui 1.53.0 → 1.54.0

package/COMPONENTS.md

@@ -71,7 +71,13 @@ Generic pieces built on the primitives, imported from `@heyramzi/ui/components/<
 - `mark` — Mark, a logo or photo glyph with an initial fallback
 - `open-in` — OpenIn, a link out to a tool that takes the tool's name, label and mark as a prop
 - `picker` — Picker, MarkPicker, pickerTriggerClass, a command palette at popover scale
+- `docs` — DocPage, OnThisPage, ScrollSpy: one page anatomy for documentation, an icon, title and summary header, a reading column and a contents rail that becomes a bar on a narrow pane
+- `section-card` — SectionCard, a card with a fixed-height header, an h3 title, optional actions and a line under it
+- `section-header` — SectionHeader, a section label with a count chip, a line of description and actions
+- `field-row` — FieldRow, a labelled control with its action button at the control's height
+- `table-view` — TableView, a read-only table from columns and rows: numeric columns, footer row, custom cell
 - `segmented` — AnimatedTabs (pill or underline), SegmentedFilter, SegmentedNav, SectionRuns, one bordered track with a sliding pill, a badge note and an overflow menu
+- `theme` — ThemeProvider, mode, userPrefersMode, setMode, toggleMode, resetMode: the one light and dark system (mode-watcher, optional peer). Mount `<ThemeProvider initial onChange themeColors modeStorageKey />` once; flip with `toggleMode()`, read `mode.current`. Pair with `theme-toggle`'s `revealTheme(event, toggleMode)` for the wipe
 - `star-rating-input` — StarRatingInput
 - `svg` — Svg, an SVG file imported with `?raw`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heyramzi/ui",
-  "version": "1.53.0",
+  "version": "1.54.0",
   "description": "Svelte 5 UI primitives: effects, animations, and shared component CSS.",
   "license": "MIT",
   "repository": {
@@ -28,7 +28,7 @@
       "types": "./src/index.ts",
       "default": "./src/index.ts"
     },
-    "./tokens.css": "./src/tokens.css",
+    "./tokens.css": "./src/tokens/index.css",
     "./lib/*.js": {
       "svelte": "./src/lib/*.ts",
       "types": "./src/lib/*.ts",

package/scripts/lib/sync-core.mjs

@@ -15,7 +15,7 @@ const get = (url) => fetch(url, { headers: { "user-agent": "heyramzi-ui-sync" }
 
 export async function fetchText(url) {
   const res = await get(url);
-  if (!res.ok) throw new Error(`${res.status} ${res.statusText} — ${url}`);
+  if (!res.ok) throw new Error(`${res.status} ${res.statusText}: ${url}`);
   return await res.text();
 }
 

package/scripts/sync-shadcn.mjs

@@ -238,14 +238,14 @@ for (const { item, payload } of fetched) {
   };
 
   if (!moved.length && !gone.length) unchanged++;
-  else if (fresh) buckets.added.push(`${item.name} — ${files.length} files, new primitive`);
+  else if (fresh) buckets.added.push(`${item.name}: ${files.length} files, new primitive`);
   else if (blocked)
-    for (const s of moved) buckets.port.push(`${label(s.path)} — upstream moved, ${s.state} here`);
+    for (const s of moved) buckets.port.push(`${label(s.path)}: upstream moved, ${s.state} here`);
   else if (apply.length)
-    buckets.synced.push(`${item.name} — ${apply.map((s) => basename(s.path)).join(", ")}`);
+    buckets.synced.push(`${item.name}: ${apply.map((s) => basename(s.path)).join(", ")}`);
 
   for (const g of gone)
-    buckets.removed.push(`${label(g.path)} — gone upstream${g.ours ? ", kept (ours)" : ""}`);
+    buckets.removed.push(`${label(g.path)}: gone upstream${g.ours ? ", kept (ours)" : ""}`);
 
   if (CHECK) continue;
 
@@ -261,14 +261,14 @@ for (const { item, payload } of fetched) {
 
 for (const name of Object.keys(previous)) {
   if (entries[name]) continue;
-  buckets.removed.push(`${name} — gone from the registry`);
+  buckets.removed.push(`${name}: gone from the registry`);
   if (!CHECK) await removeDeep(`${VENDOR}/${name}`);
 }
 
 const ours = readdirSync(LOCAL, { withFileTypes: true })
   .filter((e) => e.isDirectory() && !entries[e.name] && !LOCAL_ONLY.has(e.name))
   .map((e) => e.name);
-for (const name of ours) buckets.unported.push(`${name} — in src/shadcn, not in the registry`);
+for (const name of ours) buckets.unported.push(`${name}: in src/shadcn, not in the registry`);
 
 /* The docs site's own demo for each primitive, vendored on the same three-way
  * rule. Upstream writes them; the site renders them. */
@@ -284,7 +284,7 @@ for (const name of demoNames) {
     fetchTextIf(`${DOCS}/content/components/${name}.md`),
   ]);
   if (raw === null) {
-    buckets.unported.push(`${name} — no demo upstream`);
+    buckets.unported.push(`${name}: no demo upstream`);
     continue;
   }
 
@@ -296,12 +296,12 @@ for (const name of demoNames) {
   // The imports of the demo that renders: ours when kept, upstream's when written.
   const shown = state === "diverged" ? local : next;
 
-  if (state === "dropped") buckets.removed.push(`${label(path)} — dropped here, kept out`);
+  if (state === "dropped") buckets.removed.push(`${label(path)}: dropped here, kept out`);
   else manifest.push({ name, ...meta(doc, name), imports: publicImports(shown) });
 
   if (base !== raw) {
-    if (state === "diverged") buckets.port.push(`${label(path)} — upstream moved, ours here`);
-    else if (state !== "current") buckets.synced.push(`${name} — demo`);
+    if (state === "diverged") buckets.port.push(`${label(path)}: upstream moved, ours here`);
+    else if (state !== "current") buckets.synced.push(`${name}: demo`);
   }
   if (CHECK) continue;
 
@@ -345,7 +345,7 @@ if (!CHECK) {
 
 process.exit(
   report({
-    title: `shadcn-svelte — ${items.length} primitives`,
+    title: `shadcn-svelte: ${items.length} primitives`,
     buckets,
     unchanged,
     footer: `${Object.values(entries).filter((e) => e.adapted).length} adapted here, ${LOCAL_ONLY.size} ours`,

package/scripts/sync-transitions.mjs

@@ -12,7 +12,7 @@
  */
 
 /*
- * Paid ones are dropped here and never vendored — Ramzi, 14 Sep 2026: "the pro effects we don't need them".
+ * Paid ones are dropped here and never vendored (Ramzi, 14 Sep 2026: "the pro effects we don't need them").
  */
 
 /*
@@ -100,20 +100,20 @@ for (const { slug, name, css } of free) {
   const hash = sha256(css);
   entries[slug] = { name, sha256: hash, local: PORTED[slug] ?? null };
 
-  if (!previous[slug]) buckets.added.push(`${slug} — ${name}`);
-  else if (previous[slug].sha256 !== hash) buckets.changed.push(`${slug} — ${name}`);
+  if (!previous[slug]) buckets.added.push(`${slug}: ${name}`);
+  else if (previous[slug].sha256 !== hash) buckets.changed.push(`${slug}: ${name}`);
   else unchanged++;
 
-  if (!PORTED[slug]) buckets.unported.push(`${slug} — nothing under src/ owns it`);
+  if (!PORTED[slug]) buckets.unported.push(`${slug}: nothing under src/ owns it`);
   else if (!existsSync(`${SRC}/${PORTED[slug]}`))
-    buckets.unported.push(`${slug} — PORTED says ${PORTED[slug]}, which is missing`);
+    buckets.unported.push(`${slug}: PORTED says ${PORTED[slug]}, which is missing`);
 
   if (!CHECK) await writeFileDeep(`${VENDOR}/${slug}.css`, css);
 }
 
 for (const slug of Object.keys(previous)) {
   if (entries[slug]) continue;
-  buckets.removed.push(`${slug} — gone upstream or moved to pro`);
+  buckets.removed.push(`${slug}: gone upstream or moved to pro`);
   if (!CHECK) await removeDeep(`${VENDOR}/${slug}.css`);
 }
 
@@ -138,7 +138,7 @@ if (!CHECK) {
 
 process.exit(
   report({
-    title: `transitions.dev — ${free.length} free`,
+    title: `transitions.dev: ${free.length} free`,
     buckets,
     unchanged,
     footer: `${paid} pro skipped`,

package/src/agents/agent-avatar.svelte

@@ -4,15 +4,15 @@
     BotAvatarShading,
     BotAvatarState,
     BotAvatarType,
-  } from './vendor/types';
-  import type { AgentAvatarProps } from './types';
-  import { botAvatarPresets, stateLabels } from './vendor/presets';
-  import { SHAPE_PATHS, SHAPE_PARTS } from './vendor/shapes';
-  import { autoInk, richer, shade } from './vendor/color';
-  import { Sim, restPose } from './vendor/engine';
-  import { draw, LIGHT_DEFAULTS, OVERSCAN, RISE, type DrawConfig } from './vendor/draw';
-  import { bakesPending, hurry, onLanded, takeMissed, warmPlastic, type FurStyle } from './vendor/plastic';
-  import { subscribe, pointer } from './vendor/ticker';
+  } from './vendor/types.js';
+  import type { AgentAvatarProps } from './types.js';
+  import { botAvatarPresets, stateLabels } from './vendor/presets.js';
+  import { SHAPE_PATHS, SHAPE_PARTS } from './vendor/shapes.js';
+  import { richer, shade } from './vendor/color.js';
+  import { Sim, restPose } from './vendor/engine.js';
+  import { draw, LIGHT_DEFAULTS, OVERSCAN, RISE, type DrawConfig } from './vendor/draw.js';
+  import { bakesPending, hurry, onLanded, takeMissed, warmPlastic, type FurStyle } from './vendor/plastic.js';
+  import { subscribe, pointer } from './vendor/ticker.js';
   import {
     SHOW_WITHIN,
     bodyPath,
@@ -21,21 +21,20 @@
     partPaths,
     showReady,
     waiters,
-  } from './page-state';
+  } from './page-state.js';
   import {
     clamp,
     clampOpt,
     deviceDpr,
     hashSeed,
+    inkFor,
     lightsFor,
     pointerStrength,
     q,
     reducedMotion,
     resolveTheme as themeOf,
     warmIdle,
-  } from './helpers';
-
-  type Props = AgentAvatarProps;
+  } from './helpers.js';
 
   let {
     name,
@@ -106,7 +105,7 @@
     'aria-hidden': ariaHidden,
     onclick: userClick,
     ...rest
-  }: Props = $props();
+  }: AgentAvatarProps = $props();
 
   const shapePath = (t: BotAvatarType) => SHAPE_PATHS[t] ?? SHAPE_PATHS.clover;
 
@@ -140,7 +139,7 @@
       vivid,
     ),
   );
-  const inkColor = $derived(ink ?? autoInk(body));
+  const inkColor = $derived(ink ?? inkFor(body));
   const seedValue = $derived(Math.min(1, Math.max(0, seed ?? hashSeed(uid))));
   const stateKey = $derived((botState in stateLabels ? botState : 'default') as BotAvatarState);
   const frozen = $derived(paused || !(speed > 0));

package/src/agents/agent-cast.svelte

@@ -1,8 +1,8 @@
 <script lang="ts">
   import AgentAvatar from './agent-avatar.svelte';
-  import type { Agent, AgentState } from './types';
+  import type { Agent, AgentState } from './types.js';
 
-  type Props = {
+  interface Props {
     /** The cast to lay out. */
     agents: Agent[];
     /** Selected agent id, when the cast is a picker. */

package/src/agents/demo.svelte

@@ -1,7 +1,7 @@
 <script lang="ts">
   import AgentAvatar from './agent-avatar.svelte';
   import AgentCast from './agent-cast.svelte';
-  import type { Agent, AgentState } from './types';
+  import type { Agent, AgentState } from './types.js';
 
   const cast: Agent[] = [
     { id: 'ada', name: 'Ada', role: 'Researcher', shape: 'clover', color: '#41C4FF', group: 'Research' },

package/src/agents/helpers.ts

@@ -1,5 +1,14 @@
 /* Pure helpers for the avatar: numbers, theme, lights, idle scheduling. */
-import { stockLights } from './vendor/plastic';
+import { DARK_INK, LIGHT_INK, luminance } from './vendor/color.js';
+import { stockLights } from './vendor/plastic.js';
+
+const contrast = (a: number, b: number) => (Math.max(a, b) + 0.05) / (Math.min(a, b) + 0.05);
+
+/** Off-black or off-white eyes, whichever reads stronger on the body: the vendor's fixed cutoff left 2:1 eyes on mid blues. */
+export function inkFor(body: string): string {
+  const l = luminance(body);
+  return contrast(l, luminance(DARK_INK)) >= contrast(l, luminance(LIGHT_INK)) ? DARK_INK : LIGHT_INK;
+}
 
 export const clamp = (v: number, lo: number, hi: number) =>
   Math.min(hi, Math.max(lo, Number.isFinite(v) ? v : 1));

package/src/agents/index.ts

@@ -1,6 +1,6 @@
 export { default as AgentAvatar } from './agent-avatar.svelte';
 export { default as AgentCast } from './agent-cast.svelte';
-export type { Agent, AgentAvatarProps, AgentShape } from './types';
+export type { Agent, AgentAvatarProps, AgentShape } from './types.js';
 export {
   agentPresets,
   agentShapes,
@@ -8,4 +8,4 @@ export {
   agentStates,
   agentPalette,
   agentStateLabels,
-} from './types';
+} from './types.js';

package/src/agents/page-state.ts

@@ -1,6 +1,6 @@
 /* What every avatar on the page shares: the batching shown-gate, so a row of
    them comes in together, the path caches, and one theme watcher. */
-import { bakesPending } from './vendor/plastic';
+import { bakesPending } from './vendor/plastic.js';
 
 export const SHOW_WITHIN = 4000;
 export const waiters = new Map<object, { ready: () => boolean; show: () => void }>();

package/src/agents/types.ts

@@ -1,4 +1,4 @@
-import type { BotAvatarFace, BotAvatarProps, BotAvatarType } from './vendor/types';
+import type { BotAvatarFace, BotAvatarProps, BotAvatarType } from './vendor/types.js';
 
 /** The body shapes an agent can be drawn as. */
 export type AgentShape = BotAvatarType;
@@ -11,7 +11,7 @@ export type {
   BotAvatarHat as AgentHat,
   BotAvatarGlasses as AgentGlasses,
   BotAvatarPreset as AgentPreset,
-} from './vendor/types';
+} from './vendor/types.js';
 
 export {
   botAvatarPresets as agentPresets,
@@ -20,7 +20,7 @@ export {
   botAvatarStates as agentStates,
   botAvatarPalette as agentPalette,
   stateLabels as agentStateLabels,
-} from './vendor/presets';
+} from './vendor/presets.js';
 
 /** One member of a cast: a name, a role, and the face they draw. */
 export type Agent = {

package/src/components/copy/copy-button.test.ts

@@ -16,8 +16,10 @@ function render(props: Props) {
   document.body.appendChild(target);
   const app = mount(CopyButton, { target, props });
   flushSync();
+  const button = target.querySelector("button");
+  if (!button) throw new Error("CopyButton rendered no button");
   return {
-    button: target.querySelector("button")!,
+    button,
     target,
     done: () => {
       void unmount(app);

package/src/components/data-table/infinite-scroll.svelte

@@ -4,7 +4,7 @@ import type { Snippet } from "svelte";
 import { Spinner } from "../../shadcn/spinner/index.js";
 
 // ========================= TYPES
-type Props = {
+interface Props {
 	items: T[];
 	isDone: boolean;
 	isLoading: boolean;

package/src/components/data-table/pagination.svelte

@@ -4,7 +4,7 @@ import { Button } from "../../shadcn/button/index.js";
 import { totalPages as calcTotalPages } from "./data-table.js";
 
 // ========================= TYPES
-type Props = {
+interface Props {
 	page: number;
 	pageSize: number;
 	total: number;

package/src/components/data-table/row-arrow.svelte

@@ -8,7 +8,7 @@ import { cn } from "@heyramzi/utils";
 // =========================
 // TYPES
 // =========================
-type Props = {
+interface Props {
 	class?: string;
 };
 

package/src/components/data-table/row-context-menu.svelte

@@ -10,7 +10,7 @@ import type { Snippet } from "svelte";
 // =========================
 // TYPES
 // =========================
-type Props = {
+interface Props {
 	onDelete: () => void;
 	href?: string;
 	id?: string;

package/src/components/data-table/sortable-head.svelte

@@ -5,7 +5,7 @@ import { cn } from "@heyramzi/utils";
 import type { SortDirection, SortState } from "./data-table.js";
 
 // ========================= TYPES
-type Props = {
+interface Props {
 	key: keyof T & string;
 	sort: SortState<T>;
 	onSort: (key: keyof T & string) => void;
@@ -50,7 +50,7 @@ function handleKeydown(e: KeyboardEvent) {
 		{:else if direction === "desc"}
 			<CaretDown class="size-3.5 text-foreground" weight="bold" />
 		{:else}
-			<CaretUpDown class="size-3.5 text-muted-foreground/50" />
+			<CaretUpDown class="size-3.5 text-muted-foreground/75" />
 		{/if}
 	</span>
 </th>

package/src/components/data-table/table-skeleton.svelte

@@ -10,7 +10,7 @@ type ColumnDef = {
 	circle?: boolean;
 };
 
-type Props = {
+interface Props {
 	/** Number of skeleton rows to render */
 	rows?: number;
 	/** Column definitions control skeleton widths and alignment */

package/src/components/docs/doc-page.svelte

@@ -0,0 +1,161 @@
+<script lang="ts">
+	// =========================
+	// IMPORTS
+	// =========================
+	import type { Component, Snippet } from "svelte";
+	import OnThisPage from "./on-this-page.svelte";
+	import {
+		ScrollSpy,
+		type DocHeading,
+		type LocateHeading,
+	} from "./scroll-spy.svelte.js";
+
+	// =========================
+	// TYPES
+	// =========================
+	interface Props {
+		title: string;
+		/** One line under the title. Optional: a page with nothing to add leaves it out. */
+		summary?: string;
+		icon?: Component<{ class?: string; weight?: "bold" }>;
+		/** Where the page lives, as a reader would say it: "Marketing / Reports". */
+		section?: string;
+		/** Already worded and localised: "Updated 30 Jul 2026". */
+		updated?: string;
+		/** Room at the right of the title for a page's own controls. */
+		actions?: Snippet;
+		/** The document's h2s, which the contents rail walks. Under two, there's no rail. */
+		headings?: DocHeading[];
+		/** The rail's name: "On this page". */
+		contentsLabel: string;
+		/** Supplied by a document that lives in a frame; the default reads the DOM by id. */
+		locate?: LocateHeading;
+		/** Changes when the page is swapped without navigation, so the pane returns to the top. */
+		resetKey?: string;
+		/** The reading column's width. `wide` is for a document that brings tables and boards. */
+		measure?: "prose" | "wide";
+		/** The scroll box, for a document that has to place things inside it. */
+		scroller?: HTMLElement | null;
+		children: Snippet;
+	}
+
+	// =========================
+	// PROPS
+	// =========================
+	let {
+		title,
+		summary,
+		icon: Icon,
+		section,
+		updated,
+		actions,
+		headings = [],
+		contentsLabel,
+		locate,
+		resetKey,
+		measure = "prose",
+		scroller = $bindable(null),
+		children,
+	}: Props = $props();
+
+	// =========================
+	// STATE
+	// =========================
+	const spy = new ScrollSpy();
+
+	// DERIVED
+	let hasRail = $derived(headings.length > 1);
+	let meta = $derived([section, updated].filter(Boolean) as string[]);
+
+	// =========================
+	// EFFECTS
+	// =========================
+	$effect(() => spy.attach(scroller, headings, locate));
+
+	$effect(() => {
+		void resetKey;
+		scroller?.scrollTo({ top: 0 });
+	});
+</script>
+
+<!-- =========================== -->
+<!-- MARKUP -->
+<!-- =========================== -->
+<!-- The anatomy, once: header, then the reading column with its contents rail.
+     A surface supplies content and never lays this out, so two pages can't
+     arrive with different layouts. The pane is its own container, since the
+     room left after the map is what decides the rail, not the window. -->
+<div
+	bind:this={scroller}
+	class="doc-page @container/page thin-scrollbar relative min-h-0 flex-1 overflow-y-auto"
+>
+	{#if hasRail}
+		<!-- Below the rail's width the contents sit on a strip that stays put. -->
+		<div class="sticky top-0 z-20 border-b border-border bg-background/95 backdrop-blur @3xl/page:hidden">
+			<OnThisPage
+				variant="bar"
+				items={headings}
+				active={spy.active}
+				label={contentsLabel}
+				onselect={(id) => spy.jump(id)}
+			/>
+		</div>
+	{/if}
+
+	<div
+		class="mx-auto flex w-full gap-10 px-5 @2xl/page:px-8 {measure === 'wide'
+			? 'max-w-[84rem]'
+			: 'max-w-[68rem]'}"
+	>
+		<article class="min-w-0 flex-1 pb-20 pt-8 @2xl/page:pt-10">
+			<header class="mb-8 border-b border-border pb-6">
+				<div class="flex items-start gap-4">
+					{#if Icon}
+						<span
+							class="flex size-11 shrink-0 items-center justify-center rounded-xl bg-indigo-100 text-brand-indigo dark:bg-indigo-800/30 dark:text-brand-indigo-light"
+						>
+							<Icon class="size-5" weight="bold" />
+						</span>
+					{/if}
+					<div class="min-w-0 flex-1">
+						<h1
+							class="font-heading text-2xl font-semibold leading-tight tracking-tight text-balance text-foreground @2xl/page:text-[1.75rem]"
+						>
+							{title}
+						</h1>
+						{#if summary}
+							<p class="mt-1.5 max-w-[60ch] text-[15px] leading-relaxed text-muted-foreground text-pretty">
+								{summary}
+							</p>
+						{/if}
+						{#if meta.length > 0}
+							<p class="mt-3 flex flex-wrap items-center gap-x-2 text-xs tabular-nums text-muted-foreground">
+								{#each meta as item, i (item)}
+									{#if i > 0}<span aria-hidden="true" class="size-0.5 rounded-full bg-current opacity-50"></span>{/if}
+									<span>{item}</span>
+								{/each}
+							</p>
+						{/if}
+					</div>
+					{#if actions}
+						<div class="flex shrink-0 items-center gap-2">{@render actions()}</div>
+					{/if}
+				</div>
+			</header>
+
+			{@render children()}
+		</article>
+
+		{#if hasRail}
+			<!-- `self-start`, since a sticky child only travels inside its own box. -->
+			<aside class="hidden w-48 shrink-0 self-start pt-10 @3xl/page:sticky @3xl/page:top-0 @3xl/page:block">
+				<OnThisPage
+					items={headings}
+					active={spy.active}
+					label={contentsLabel}
+					onselect={(id) => spy.jump(id)}
+				/>
+			</aside>
+		{/if}
+	</div>
+</div>

package/src/components/docs/index.ts

@@ -0,0 +1,12 @@
+/**
+ * The documentation anatomy: one page component and the contents rail inside it.
+ * A surface supplies a title and a body, and never lays a document out itself.
+ */
+export { default as DocPage } from "./doc-page.svelte";
+export { default as OnThisPage } from "./on-this-page.svelte";
+export {
+  ScrollSpy,
+  READ_LINE,
+  type DocHeading,
+  type LocateHeading,
+} from "./scroll-spy.svelte.js";