@heyramzi/ui 1.53.0 → 1.54.0

package/src/components/docs/on-this-page.svelte

@@ -0,0 +1,217 @@
+<script lang="ts">
+	// =========================
+	// IMPORTS
+	// =========================
+	import { tick } from "svelte";
+	import { CaretDown, List } from "phosphor-svelte";
+	import type { DocHeading } from "./scroll-spy.svelte.js";
+
+	// =========================
+	// TYPES
+	// =========================
+	interface Props {
+		items: DocHeading[];
+		/** The id the reader is in. */
+		active: string;
+		/** What the rail is called: "On this page". Passed in so the library holds no copy. */
+		label: string;
+		onselect: (id: string) => void;
+		/**
+		 * `rail` is the column beside the document. `bar` is the strip that takes
+		 * its place on a narrow pane: it names where you are and opens the list.
+		 */
+		variant?: "rail" | "bar";
+	}
+
+	// =========================
+	// PROPS
+	// =========================
+	let { items, active, label, onselect, variant = "rail" }: Props = $props();
+
+	// =========================
+	// STATE
+	// =========================
+	let list = $state<HTMLElement | null>(null);
+	let open = $state(false);
+	let marker = $state({ y: 0, h: 0, ready: false });
+	// Plain, not state: the effect below writes `marker`, so it can't also read it.
+	let placed = false;
+	let scrollBox = $state<HTMLElement | null>(null);
+	let overflowing = $state(false);
+
+	// =========================
+	// DERIVED
+	// =========================
+	let activeIndex = $derived(Math.max(0, items.findIndex((item) => item.id === active)));
+	let activeLabel = $derived(items.find((item) => item.id === active)?.label ?? items[0]?.label ?? "");
+	// How far through the document: the bar's hairline, and the number a reader
+	// reads at a glance.
+	let progress = $derived(items.length > 1 ? activeIndex / (items.length - 1) : 0);
+
+	// =========================
+	// EFFECTS
+	// =========================
+	// One marker that slides to the active row, rather than a border that blinks
+	// from one row to the next.
+	$effect(() => {
+		void active;
+		void items;
+		if (variant !== "rail" || !list) return;
+		overflowing = !!scrollBox && scrollBox.scrollHeight > scrollBox.clientHeight + 1;
+		const row = list.querySelector<HTMLElement>("[data-current='true']");
+		if (!row) return;
+		const y = row.offsetTop;
+		const h = row.offsetHeight;
+		// First placement lands with no slide, or it would glide in from the top.
+		const wasPlaced = placed;
+		placed = true;
+		marker = { y, h, ready: wasPlaced };
+		if (!wasPlaced) return;
+		// A long list scrolls inside the rail, so keep the current row in view.
+		const box = list.parentElement;
+		if (box && (y < box.scrollTop || y + h > box.scrollTop + box.clientHeight)) {
+			box.scrollTo({ top: y - box.clientHeight / 2, behavior: "auto" });
+		}
+	});
+
+	function pick(id: string) {
+		open = false;
+		onselect(id);
+		void tick();
+	}
+</script>
+
+<svelte:window
+	onkeydown={(event) => {
+		if (event.key === "Escape") open = false;
+	}}
+	onpointerdown={(event) => {
+		if (!open) return;
+		if (!(event.target as HTMLElement).closest("[data-otp-bar]")) open = false;
+	}}
+/>
+
+<!-- =========================== -->
+<!-- MARKUP -->
+<!-- =========================== -->
+{#if variant === "rail"}
+	<nav aria-label={label} class="flex max-h-[calc(100svh-8rem)] flex-col gap-3">
+		<!-- Set like the map's own headings on the left, so the two rails read as one. -->
+		<p class="font-heading text-xs font-semibold uppercase tracking-wider text-muted-foreground">
+			{label}
+		</p>
+		<div
+			bind:this={scrollBox}
+			class="thin-scrollbar -mr-2 min-h-0 overflow-y-auto pr-2"
+			class:otp-fade={overflowing}
+		>
+			<div bind:this={list} class="relative border-l border-border">
+				<!-- The marker sits on the track's own line, so the active row reads as
+				     the part of the line you're standing on. -->
+				<span
+					aria-hidden="true"
+					class="otp-marker absolute -left-px top-0 w-0.5 rounded-full bg-brand-indigo dark:bg-brand-indigo-light"
+					class:is-ready={marker.ready}
+					style="transform: translateY({marker.y}px); height: {marker.h}px;"
+				></span>
+				<ul class="flex flex-col">
+					{#each items as item (item.id)}
+						{@const current = item.id === active}
+						<li>
+							<button
+								type="button"
+								data-current={current}
+								aria-current={current ? "location" : undefined}
+								onclick={() => pick(item.id)}
+								class="otp-row block w-full py-1.5 pl-3 pr-1 text-left text-[13px] leading-snug transition-colors duration-[var(--duration-fast)] ease-[var(--ease-smooth-out)] any-pointer-coarse:py-2.5 {current
+									? 'font-medium text-foreground'
+									: 'text-muted-foreground hover:text-foreground'}"
+							>
+								{item.label}
+							</button>
+						</li>
+					{/each}
+				</ul>
+			</div>
+		</div>
+	</nav>
+{:else}
+	<div data-otp-bar class="relative">
+		<button
+			type="button"
+			aria-expanded={open}
+			aria-label={label}
+			onclick={() => (open = !open)}
+			class="flex h-11 w-full items-center gap-2.5 px-4 text-left transition-colors duration-[var(--duration-fast)] ease-[var(--ease-smooth-out)] hover:bg-muted/50"
+		>
+			<List size={16} class="shrink-0 text-muted-foreground" aria-hidden="true" />
+			<span class="shrink-0 text-xs font-medium text-muted-foreground">{label}</span>
+			<span class="min-w-0 flex-1 truncate text-sm font-medium text-foreground">{activeLabel}</span>
+			<CaretDown
+				size={14}
+				class="shrink-0 text-muted-foreground transition-transform duration-[var(--duration-fast)] ease-[var(--ease-smooth-out)] {open
+					? 'rotate-180'
+					: ''}"
+			/>
+		</button>
+		<!-- How far through the reader is. The only motion here, and it is the state. -->
+		<span aria-hidden="true" class="absolute inset-x-0 bottom-0 h-px bg-border">
+			<span
+				class="otp-progress block h-full origin-left bg-brand-indigo dark:bg-brand-indigo-light"
+				style="transform: scaleX({progress});"
+			></span>
+		</span>
+
+		{#if open}
+			<nav
+				aria-label={label}
+				class="thin-scrollbar absolute inset-x-2 top-full z-20 mt-1 max-h-[60svh] overflow-y-auto rounded-xl border border-border bg-popover p-1.5 shadow-lg"
+			>
+				<ul class="flex flex-col">
+					{#each items as item (item.id)}
+						{@const current = item.id === active}
+						<li>
+							<button
+								type="button"
+								aria-current={current ? "location" : undefined}
+								onclick={() => pick(item.id)}
+								class="block w-full rounded-lg px-3 py-2.5 text-left text-sm leading-snug transition-colors duration-[var(--duration-fast)] ease-[var(--ease-smooth-out)] {current
+									? 'bg-muted font-medium text-foreground'
+									: 'text-muted-foreground hover:bg-muted/60 hover:text-foreground'}"
+							>
+								{item.label}
+							</button>
+						</li>
+					{/each}
+				</ul>
+			</nav>
+		{/if}
+	</div>
+{/if}
+
+<!-- =========================== -->
+<!-- STYLE -->
+<!-- =========================== -->
+<style>
+	.otp-marker.is-ready {
+		transition:
+			transform var(--duration-medium) var(--ease-smooth-out),
+			height var(--duration-medium) var(--ease-smooth-out);
+	}
+
+	.otp-progress {
+		transition: transform var(--duration-medium) var(--ease-smooth-out);
+	}
+
+	/* A long list fades into its edges instead of ending on a hard cut. */
+	.otp-fade {
+		mask-image: linear-gradient(to bottom, transparent, #000 0.5rem, #000 calc(100% - 1.5rem), transparent);
+	}
+
+	@media (prefers-reduced-motion: reduce) {
+		.otp-marker.is-ready,
+		.otp-progress {
+			transition: none;
+		}
+	}
+</style>

package/src/components/docs/scroll-spy.svelte.ts

@@ -0,0 +1,97 @@
+/**
+ * Which heading the reader is in, for a box that scrolls. One spy feeds the
+ * side rail and the compact bar, so the two can never disagree.
+ */
+
+export type DocHeading = { id: string; label: string };
+
+/**
+ * Where a heading sits inside the scroller, in scroller content coordinates.
+ * The default reads the live DOM by id. A framed document supplies its own,
+ * since its headings live in another document.
+ */
+export type LocateHeading = (id: string) => number | null;
+
+/** How far below the scroller's top edge a heading counts as "reached" and lands. */
+export const READ_LINE = 80;
+
+export class ScrollSpy {
+  active = $state("");
+
+  #scroller: HTMLElement | null = null;
+  #items: DocHeading[] = [];
+  #locate: LocateHeading | undefined;
+  #frame = 0;
+
+  /** Point the spy at a scroller and a list. Returns the cleanup. */
+  attach(scroller: HTMLElement | null, items: DocHeading[], locate?: LocateHeading) {
+    this.#scroller = scroller;
+    this.#items = items;
+    this.#locate = locate;
+    if (!scroller || items.length === 0) {
+      this.active = "";
+      return () => {};
+    }
+
+    const schedule = () => {
+      this.#frame ||= requestAnimationFrame(() => {
+        this.#frame = 0;
+        this.update();
+      });
+    };
+    scroller.addEventListener("scroll", schedule, { passive: true });
+    const observer = new ResizeObserver(schedule);
+    observer.observe(scroller);
+    // A document that grows after load (a diagram, a chart) moves every
+    // heading below it, so watch the content too.
+    for (const child of scroller.children) observer.observe(child);
+    this.update();
+
+    return () => {
+      scroller.removeEventListener("scroll", schedule);
+      observer.disconnect();
+      if (this.#frame) cancelAnimationFrame(this.#frame);
+      this.#frame = 0;
+    };
+  }
+
+  topOf(id: string): number | null {
+    const scroller = this.#scroller;
+    if (!scroller) return null;
+    if (this.#locate) return this.#locate(id);
+    const el = scroller.querySelector<HTMLElement>(`#${CSS.escape(id)}`);
+    if (!el) return null;
+    return (
+      el.getBoundingClientRect().top - scroller.getBoundingClientRect().top + scroller.scrollTop
+    );
+  }
+
+  update() {
+    const scroller = this.#scroller;
+    if (!scroller || this.#items.length === 0) return;
+    // At the very bottom the last heading wins, or a short final section could
+    // never be the current one.
+    const atEnd = scroller.scrollTop + scroller.clientHeight >= scroller.scrollHeight - 2;
+    if (atEnd && scroller.scrollTop > 0) {
+      this.active = this.#items[this.#items.length - 1].id;
+      return;
+    }
+    const line = scroller.scrollTop + READ_LINE + 1;
+    let current = this.#items[0].id;
+    for (const item of this.#items) {
+      const top = this.topOf(item.id);
+      if (top !== null && top <= line) current = item.id;
+    }
+    this.active = current;
+  }
+
+  /** Scroll so the heading lands on the read line, instant under reduced motion. */
+  jump(id: string) {
+    const scroller = this.#scroller;
+    const top = this.topOf(id);
+    if (!scroller || top === null) return;
+    const reduced = window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+    this.active = id;
+    scroller.scrollTo({ top: Math.max(0, top - READ_LINE), behavior: reduced ? "auto" : "smooth" });
+  }
+}

package/src/components/field-row/field-row.svelte

@@ -0,0 +1,57 @@
+<script lang="ts">
+	// =========================
+	// IMPORTS
+	// =========================
+	import type { Snippet } from "svelte";
+	import { cn } from "@heyramzi/utils";
+	import * as Field from "../../shadcn/field/index.js";
+
+	// =========================
+	// TYPES
+	// =========================
+	interface Props {
+		label: string;
+		/** Id of the control, so the label focuses it. */
+		for: string;
+		description?: string;
+		error?: string;
+		class?: string;
+		/** The control: an Input, a Select trigger. It takes the width the action leaves. */
+		children: Snippet;
+		/** The button that acts on the control. Same height as the control, bottom of the row. */
+		action?: Snippet;
+	}
+
+	// =========================
+	// PROPS
+	// =========================
+	let { label, for: htmlFor, description, error, class: className, children, action }: Props = $props();
+</script>
+
+<!-- =========================== -->
+<!-- MARKUP -->
+<!-- WHY a measure of its own: a settings card fills the page, but a text field
+     stretched over 1200px is hard to read and to aim at. 36rem, left aligned. -->
+<!-- =========================== -->
+<Field.Simple
+	{label}
+	{description}
+	{error}
+	for={htmlFor}
+	class={cn("max-w-xl", className)}
+>
+	<div
+		class="flex items-start gap-2"
+		data-slot="field-row"
+	>
+		<div class="min-w-0 flex-1">{@render children()}</div>
+		{#if action}
+			<!-- A disabled action reads as a muted button, not a half-faded one. -->
+			<div
+				class="shrink-0 [&_button:disabled]:bg-muted [&_button:disabled]:text-muted-foreground [&_button:disabled]:opacity-100 [&_button:disabled]:shadow-none"
+			>
+				{@render action()}
+			</div>
+		{/if}
+	</div>
+</Field.Simple>

package/src/components/field-row/index.ts

@@ -0,0 +1 @@
+export { default as FieldRow } from "./field-row.svelte";

package/src/components/hold-to-confirm/hold-to-confirm.svelte

@@ -6,7 +6,7 @@
 	import type { HTMLButtonAttributes } from "svelte/elements";
 
 	// ========================= TYPES
-	type Props = {
+	interface Props extends Omit<HTMLButtonAttributes, "class"> {
 		duration?: number;
 		onConfirm: () => void;
 		disabled?: boolean;
@@ -19,7 +19,7 @@
 		class?: string;
 		idle: Snippet;
 		holding: Snippet;
-	} & HTMLButtonAttributes;
+	}
 
 	// ========================= PROPS
 	let {

package/src/components/icon/icon.svelte

@@ -4,7 +4,7 @@ import type { PhosphorIcon, IconWeight } from "../../lib/icon-types.js";
 // =========================
 // TYPES
 // =========================
-type Props = {
+interface Props {
 	icon: PhosphorIcon;
 	size?: number;
 	class?: string;

package/src/components/list-page/detail-empty.svelte

@@ -9,7 +9,7 @@ import type { PhosphorIcon, IconWeight } from "../../lib/icon-types.js";
 // =========================
 // TYPES
 // =========================
-type Props = {
+interface Props {
 	// Shown when nothing is picked or the board is empty. Both mean "content
 	// goes here", so both get a dashed `border-2` edge.
 	icon?: PhosphorIcon;

package/src/components/list-page/detail-header.svelte

@@ -8,7 +8,7 @@ import { cn } from "@heyramzi/utils";
 // =========================
 // TYPES
 // =========================
-type Props = {
+interface Props {
 	// Answers three questions in one order: what is this, what state is it in,
 	// what can I do with it. Each queue page used to order them differently.
 	title: string;

package/src/components/list-page/detail-panel.svelte

@@ -11,7 +11,7 @@ import type { PhosphorIcon } from "../../lib/icon-types.js";
 // =========================
 // TYPES
 // =========================
-type Props = {
+interface Props {
 	// One panel per idea in a detail pane. Hand-rolled copies drifted between
 	// 8px and 12px corners, so rounded-xl lives here once.
 	label?: string;

package/src/components/list-page/detail-row.svelte

@@ -8,7 +8,7 @@ import { cn } from "@heyramzi/utils";
 // =========================
 // TYPES
 // =========================
-type Props = {
+interface Props {
 	// A hairline band inside `DetailHeader` or `DetailPanel` for the record's
 	// own facts, so the page never nests cards inside cards.
 	muted?: boolean;

package/src/components/list-page/detail-stack.svelte

@@ -8,7 +8,7 @@ import { cn } from "@heyramzi/utils";
 // =========================
 // TYPES
 // =========================
-type Props = {
+interface Props {
 	// A flat stack of panels at one gap. `xl:pr-1` keeps the top panel's
 	// corner clear of the shell's scrollbar.
 

package/src/components/list-page/filter-item.svelte

@@ -10,7 +10,7 @@ import { cn } from "@heyramzi/utils";
 // =========================
 // TYPES
 // =========================
-type Props = {
+interface Props {
 	checked: boolean;
 	onclick: () => void;
 	variant?: "checkbox" | "radio";

package/src/components/list-page/filter-popover.svelte

@@ -17,7 +17,7 @@ const DefaultFunnelIcon = FunnelIcon as unknown as PhosphorIcon;
 // =========================
 // TYPES
 // =========================
-type Props = {
+interface Props {
 	label: string;
 	icon?: PhosphorIcon;
 	count?: number;

package/src/components/list-page/grouped-list.svelte

@@ -10,7 +10,7 @@
 	// =========================
 	// TYPES
 	// =========================
-	type Props = {
+	interface Props {
 		groups: TGroup[];
 		getKey: (group: TGroup) => string;
 		defaultCollapsed?: string[];

package/src/components/list-page/list-page-shell.svelte

@@ -23,7 +23,7 @@
 		actionHref?: string;
 	};
 
-	type Props = {
+	interface Props {
 		isEmpty?: boolean;
 		emptyState?: EmptyConfig;
 		hideToolbarWhenEmpty?: boolean;

package/src/components/list-page/master-detail.svelte

@@ -12,7 +12,7 @@ import { MASTER_DETAIL_PANE, type MasterDetailPane } from "./queue-rail.js";
 // =========================
 // TYPES
 // =========================
-type Props = {
+interface Props {
 	// The list rail (an <aside>) and the content pane. Pages style both; this
 	// shell owns the two columns and the min-h-0/min-w-0 scroll containment.
 	rail: Snippet;

package/src/components/list-page/prev-next.svelte

@@ -10,7 +10,7 @@ import { stepTo } from "./step.js";
 // =========================
 // TYPES
 // =========================
-type Props = {
+interface Props {
 	/** Ids in the order the list shows them. */
 	ids: readonly string[];
 	current: string | null | undefined;

package/src/components/list-page/rail-body.svelte

@@ -8,7 +8,7 @@ import { cn } from "@heyramzi/utils";
 // =========================
 // TYPES
 // =========================
-type Props = {
+interface Props {
 	// The scroller under `RailHead`. `min-h-0` makes a flex child scroll instead
 	// of growing its parent, and it's the line hand-rolled rails forgot.
 	children: Snippet;

package/src/components/list-page/rail-head.svelte

@@ -9,7 +9,7 @@ import { cn } from "@heyramzi/utils";
 // =========================
 // TYPES
 // =========================
-type Props = {
+interface Props {
 	// The fixed top of a queue rail: label, filter, search. A fixed height, so
 	// rows start on the same line on every queue page.
 	label?: string;

package/src/components/list-page/rail-row.svelte

@@ -10,7 +10,7 @@ import { MASTER_DETAIL_PANE, type MasterDetailPane } from "./queue-rail.js";
 // =========================
 // TYPES
 // =========================
-type Props = {
+interface Props {
 	// One row shape for every queue rail, in a fixed order: identity, preview,
 	// facts. Three pages used to draw three different rows.
 	title: string;

package/src/components/list-page/section-label.svelte

@@ -9,7 +9,7 @@ import type { PhosphorIcon } from "../../lib/icon-types.js";
 // =========================
 // TYPES
 // =========================
-type Props = {
+interface Props {
 	// The one label style for panel, rail group and sub-section headers. Retyped
 	// copies drifted to a different tracking value.
 	icon?: PhosphorIcon;

package/src/components/list-page/toolbar-search.svelte

@@ -9,7 +9,7 @@ import { cn } from "@heyramzi/utils";
 // =========================
 // TYPES
 // =========================
-type Props = {
+interface Props {
 	value: string;
 	placeholder?: string;
 	size?: "sm" | "default";
@@ -57,7 +57,7 @@ let {
 		class={cn(
 			"w-full",
 			size === "sm" ? "h-7 pl-7 pr-2.5 text-xs" : "h-7 pl-7 pr-2.5 text-xs",
-			"any-pointer-coarse:h-10 any-pointer-coarse:text-base",
+			"any-pointer-coarse:h-11 any-pointer-coarse:text-base",
 		)}
 	/>
 </div>

package/src/components/list-page/toolbar-trigger.ts

@@ -16,7 +16,7 @@ export function toolbarTriggerClass({
 }: ToolbarTriggerOpts = {}): string {
   return cn(
     "inline-flex cursor-pointer items-center gap-1.5 rounded-lg border border-border font-medium transition-colors active:translate-y-px",
-    "h-7 px-2.5 text-xs any-pointer-coarse:h-10 any-pointer-coarse:px-3",
+    "h-7 px-2.5 text-xs any-pointer-coarse:h-11 any-pointer-coarse:px-3",
     active ? "bg-muted text-foreground" : "text-muted-foreground hover:text-foreground",
     className,
   );

package/src/components/locale-switch/locale-switch.svelte

@@ -13,7 +13,7 @@ type LocaleOption = {
 	flag: string;
 };
 
-type Props = {
+interface Props {
 	// Wraps `SegmentedFilter` so it shares one track with every other strip. It
 	// only adds each language's flag.
 	value: string;

package/src/components/mark/mark.svelte

@@ -12,7 +12,7 @@ import { cn } from "@heyramzi/utils";
  * A brand's mark at glyph size: a kit icon, a channel avatar, a client logo.
  * One renderer, because three places each handled a missing file their own way.
  */
-type Props = {
+interface Props {
 	/** The file. A missing or broken one falls back to the label's initial. */
 	src?: string;
 	/** Read for the fallback letter. The mark itself is decorative. */

package/src/components/picker/mark-picker.svelte

@@ -18,7 +18,7 @@ import type { PickerOption } from "./types.js";
  * wraps `Picker` because the kit strip and the channel row wrote the same two
  * snippets.
  */
-type Props = {
+interface Props {
 	options: PickerOption<V>[];
 	value: V | null;
 	onSelect: (value: V) => void;

package/src/components/picker/picker.svelte

@@ -12,7 +12,7 @@
 	// It replaced four pickers in one sidebar, each built differently. Only one
 	// had search, only one had arrow keys, and the check mark sat in three places.
 
-	type Props = {
+	interface Props {
 		/** Flat list. Mutually exclusive with `groups`. */
 		options?: PickerOption<V>[];
 		/** Titled runs, when the menu has a shape worth naming. */

package/src/components/picker/trigger.ts

@@ -25,8 +25,8 @@ export const pickerTriggerClass = tv({
     // Heights match `segmentedTrackClass`, so a strip and a picker line up.
     // Padding is 6px leading, 10px trailing: an even 8px shunted icon rows right.
     size: {
-      sm: "h-6 ps-1.5 pe-2 any-pointer-coarse:h-9 any-pointer-coarse:pe-2.5",
-      default: "h-7 ps-1.5 pe-2.5 any-pointer-coarse:h-10",
+      sm: "h-6 ps-1.5 pe-2 any-pointer-coarse:h-11 any-pointer-coarse:pe-2.5",
+      default: "h-7 ps-1.5 pe-2.5 any-pointer-coarse:h-11",
     },
     /**
      * Fill the row. Off by default: Linear's property rows sit at natural width

package/src/components/section-card/index.ts

@@ -0,0 +1 @@
+export { default as SectionCard } from "./section-card.svelte";