@heyramzi/ui 0.0.0-stage → 1.53.0

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

@@ -0,0 +1,195 @@
+<script lang="ts">
+	// =========================
+	// IMPORTS
+	// =========================
+	import type { Snippet } from "svelte";
+	import EmptyState from "./empty-state.svelte";
+	import { cn } from "@heyramzi/utils";
+	import { pageGutterClass } from "../../lib/layout.js";
+	import { getSectionHost } from "./section-host.js";
+	import SectionRuns from "../segmented/section-runs.svelte";
+	import type { PhosphorIcon, IconWeight } from "../../lib/icon-types.js";
+
+	// =========================
+	// TYPES
+	// =========================
+	type EmptyConfig = {
+		icon?: PhosphorIcon;
+		iconWeight?: IconWeight;
+		title: string;
+		description?: string;
+		actionLabel?: string;
+		onAction?: () => void;
+		actionHref?: string;
+	};
+
+	type Props = {
+		isEmpty?: boolean;
+		emptyState?: EmptyConfig;
+		hideToolbarWhenEmpty?: boolean;
+		maxWidth?: string | false;
+		fillHeight?: boolean;
+		containerClass?: string;
+		toolbarClass?: string;
+		tabs?: Snippet;
+		search?: Snippet;
+		filters?: Snippet;
+		rightActions?: Snippet;
+		summary?: Snippet;
+		content?: Snippet;
+		empty?: Snippet;
+		extra?: Snippet;
+	};
+
+	// =========================
+	// PROPS
+	// =========================
+	let {
+		isEmpty = false,
+		emptyState,
+		hideToolbarWhenEmpty = false,
+		maxWidth = "1600px",
+		fillHeight = false,
+		containerClass,
+		toolbarClass,
+		tabs,
+		search,
+		filters,
+		rightActions,
+		summary,
+		content,
+		empty,
+		extra,
+	}: Props = $props();
+
+	// =========================
+	// STATE
+	// =========================
+	// Null off an app shell, where the toolbar just has no section strip to draw.
+	const section = getSectionHost();
+
+	// =========================
+	// DERIVED
+	// =========================
+	let hideChrome = $derived(isEmpty && hideToolbarWhenEmpty);
+	// WHY the section strip counts: on a page whose only chrome is the section
+	// nav, this row is what draws it, and skipping the row would drop the tabs.
+	let hasToolbar = $derived(
+		Boolean(search || filters || tabs || rightActions || section?.strip) && !hideChrome,
+	);
+	// Whether anything holds the left of the row. With nothing there, the tabs
+	// take that edge instead of floating mid-row beside the actions.
+	let hasLeading = $derived(Boolean(search || filters || section?.strip));
+
+	// =========================
+	// EFFECTS
+	// =========================
+	// Claiming stops the app shell drawing its own strip above this page.
+	// Unmount releases it, so shell-less pages get the standalone row back.
+	$effect(() => {
+		if (!hasToolbar) return;
+		return section?.claim();
+	});
+	// The shared gutter from `lib/layout.ts`. A typed one put the search field
+	// 8px left of the section tabs above it.
+	let outerClass = $derived(
+		cn(
+			`flex flex-col gap-4 py-4 ${pageGutterClass}`,
+			fillHeight && "min-h-0 flex-1",
+			!fillHeight && "flex-1",
+			containerClass,
+		),
+	);
+	// flex-1 lets a snippet pin a footer with mt-auto. min-w-0 keeps wide
+	// tables and chip rows from causing horizontal scroll.
+	let innerClass = $derived(
+		maxWidth === false
+			? cn("flex min-w-0 flex-1 flex-col gap-4", fillHeight && "min-h-0")
+			: cn(
+					"mx-auto flex w-full min-w-0 flex-1 flex-col gap-4",
+					fillHeight && "min-h-0",
+				),
+	);
+	let innerStyle = $derived(maxWidth ? `max-width: ${maxWidth}` : undefined);
+</script>
+
+<!-- =========================== -->
+<!-- MARKUP -->
+<!-- =========================== -->
+<div class={outerClass}>
+	<div class={innerClass} style={innerStyle}>
+		{#if hasToolbar}
+			<!-- One row on every list page: search and filters left, then tabs,
+			     view toggle and primary action right. -->
+			<!-- Without room, `order` keeps the actions beside search and drops
+			     filters to a scrolling line below. flex-wrap stays on at every width. -->
+			<!-- A container query, not a breakpoint: an 834px iPad read as desktop
+			     and clipped a 733px toolbar into a 538px column. -->
+			<!-- Sticky, because the section tabs live here. `-mx-4 px-4` covers the
+			     gutter, `-mt-4 py-4` pulls the top padding inside the sticky box. -->
+			<div
+				class="@container/toolbar sticky top-0 z-20 -mx-4 -mt-4 bg-background/95 px-4 py-4 backdrop-blur supports-[backdrop-filter]:bg-background/70"
+			>
+				<div class={cn("flex flex-wrap items-center gap-2", toolbarClass)}>
+					<!-- The section tabs lead: which page comes before which slice of it.
+					     One row replaces two rows that held four controls. -->
+					{#if section?.strip}
+						<SectionRuns
+							strip={section.strip}
+							class="order-first w-full max-w-full @3xl/toolbar:w-auto"
+						/>
+					{/if}
+					{#if search}
+						<div class="order-1 flex min-w-0 flex-1 items-center @3xl/toolbar:flex-none">
+							{@render search()}
+						</div>
+					{/if}
+					{#if tabs || rightActions}
+						<!-- Shrinks and wraps, not shrink-0: /tasks needs 610px here, and
+						     shrink-0 clipped its last control off an iPad screen. -->
+						<div
+							class={cn(
+								"order-2 flex min-w-0 flex-wrap items-center gap-2 @3xl/toolbar:order-3",
+								hasLeading ? "@3xl/toolbar:ms-auto" : "flex-1",
+							)}
+						>
+							{#if tabs}
+								<div class={cn("flex min-w-0 items-center", !hasLeading && "me-auto")}>
+									{@render tabs()}
+								</div>
+							{/if}
+							{#if rightActions}
+								{@render rightActions()}
+							{/if}
+						</div>
+					{/if}
+					{#if filters}
+						<div
+							class="no-scrollbar order-3 flex w-full max-w-full min-w-0 items-center gap-2 overflow-x-auto @3xl/toolbar:order-2 @3xl/toolbar:w-auto"
+						>
+							{@render filters()}
+						</div>
+					{/if}
+				</div>
+			</div>
+		{/if}
+
+		{#if summary && !hideChrome}
+			{@render summary()}
+		{/if}
+
+		{#if extra && !hideChrome}
+			{@render extra()}
+		{/if}
+
+		{#if isEmpty}
+			{#if empty}
+				{@render empty()}
+			{:else if emptyState}
+				<EmptyState {...emptyState} />
+			{/if}
+		{:else if content}
+			{@render content()}
+		{/if}
+	</div>
+</div>

package/src/components/list-page/list-table.ts

@@ -0,0 +1,19 @@
+import { cn } from "@heyramzi/utils";
+
+/**
+ * The list-page table rhythm, Attio's: one 40px row, a hairline under each, a flat hover.
+ */
+export const listTable = {
+  /** The header row: 36px, a hairline under it. On the cells: `thead` zeroes its row's border. */
+  headRow: (className?: string) =>
+    cn(
+      "hover:translate-y-0 hover:bg-transparent hover:shadow-none [&>th]:h-9 [&>th]:border-b [&>th]:border-border",
+      className,
+    ),
+  /** A body row. The shared row lifts on hover; a flush list row does not. */
+  row: (className?: string) =>
+    cn(
+      "border-b border-border/50 last:border-b-0 hover:translate-y-0 hover:bg-muted/40 hover:shadow-none [&>td]:h-10 [&>td]:py-0",
+      className,
+    ),
+};

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

@@ -0,0 +1,206 @@
+<script lang="ts">
+// =========================
+// IMPORTS
+// =========================
+import type { Snippet } from "svelte";
+import { setContext } from "svelte";
+import { CaretLeft } from "phosphor-svelte";
+import { cn } from "@heyramzi/utils";
+import { Button } from "../../shadcn/button/index.js";
+import { MASTER_DETAIL_PANE, type MasterDetailPane } from "./queue-rail.js";
+
+// =========================
+// TYPES
+// =========================
+type 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;
+	detail: Snippet;
+	// A full-width strip above both columns for facts to read before acting,
+	// like a posting cap. Pages wrapping the shell to add one broke the padding.
+	banner?: Snippet;
+	// WHY: a CSS grid track for the rail column ("16rem", "minmax(280px, 340px)").
+	// Queue pages pass `queueRailWidth` rather than a literal.
+	railWidth?: string;
+	// Stack to one column below this. "lg" because rail and detail can't both be
+	// read under 1024px. null only for a rail narrow enough for a phone.
+	stackBelow?: "lg" | "xl" | null;
+	// WHY: the phone back button says where it goes back to. "Back" alone is the
+	// browser's word and the reader has to remember what they left.
+	backLabel?: string;
+	// Bindable so a url naming a record opens on it after a refresh or a pasted
+	// link. The page sets it. Ignored above the stack breakpoint.
+	pane?: "rail" | "detail";
+	gap?: boolean;
+	pad?: boolean;
+	railClass?: string;
+	detailClass?: string;
+	class?: string;
+};
+
+// =========================
+// PROPS
+// =========================
+let {
+	rail,
+	detail,
+	banner,
+	railWidth = "minmax(260px, 320px)",
+	stackBelow = "lg",
+	backLabel = "Back to the list",
+	// The rail wins by default: an unpicked detail is an empty state or a
+	// guessed row, both worse than the list.
+	pane = $bindable("rail"),
+	gap = true,
+	pad = true,
+	railClass,
+	detailClass,
+	class: className,
+}: Props = $props();
+
+// =========================
+// DERIVED
+// =========================
+// One pane at a time when stacked. Two rows put a 34svh list scroller on top of
+// a record scroller, and neither was readable.
+let gridClass = $derived(
+	stackBelow === "xl"
+		? "grid-cols-1 grid-rows-[minmax(0,1fr)] xl:grid-rows-1 xl:[grid-template-columns:var(--md-cols)]"
+		: stackBelow === "lg"
+			? "grid-cols-1 grid-rows-[minmax(0,1fr)] lg:grid-rows-1 lg:[grid-template-columns:var(--md-cols)]"
+			: "[grid-template-columns:var(--md-cols)]",
+);
+// Hidden while stacked; back to normal above the breakpoint, where both panes show.
+let hideWhileStacked = $derived(stackBelow === "xl" ? "max-xl:hidden" : "max-lg:hidden");
+// Drawn only while stacked. The back bar has no job beside a visible rail.
+let stackedOnly = $derived(stackBelow === "xl" ? "xl:hidden" : "lg:hidden");
+
+// =========================
+// FUNCTIONS
+// =========================
+// `RailRow` calls this when a record is picked. Above the breakpoint the classes
+// that read `pane` are all prefixed away, so the flag changes nothing there.
+setContext<MasterDetailPane>(MASTER_DETAIL_PANE, {
+	open: () => {
+		if (stackBelow) pane = "detail";
+	},
+});
+</script>
+
+<!-- =========================== -->
+<!-- MARKUP -->
+<!-- =========================== -->
+{#snippet columns(inBanner: boolean)}
+	<div
+		class={cn(
+			"md-cols grid min-h-0",
+			inBanner ? "flex-1" : "h-full",
+			gap && "gap-4",
+			pad && !inBanner && "p-4",
+			gridClass,
+			className,
+		)}
+		style="--md-cols: {railWidth} minmax(0, 1fr)"
+		data-pane={stackBelow ? pane : undefined}
+		data-stack={stackBelow ?? undefined}
+	>
+		<aside
+			class={cn(
+				"md-rail min-h-0",
+				railClass,
+				stackBelow && pane === "detail" && hideWhileStacked,
+			)}
+		>
+			{@render rail()}
+		</aside>
+		<div
+			class={cn(
+				"md-detail flex min-h-0 min-w-0 flex-col",
+				stackBelow && pane === "rail" && hideWhileStacked,
+			)}
+		>
+			{#if stackBelow}
+				<!-- WHY a button and not a link: nothing navigated, so there is no url to
+				     go back to and the browser's own back would leave the page. -->
+				<Button
+					variant="ghost"
+					size="sm"
+					class={cn("-mx-1 mb-2 self-start px-1 text-muted-foreground", stackedOnly)}
+					onclick={() => (pane = "rail")}
+				>
+					<CaretLeft size={16} weight="bold" />
+					{backLabel}
+				</Button>
+			{/if}
+			<div class={cn("min-h-0 min-w-0 flex-1", detailClass)}>
+				{@render detail()}
+			</div>
+		</div>
+	</div>
+{/snippet}
+
+{#if banner}
+	<div class={cn("flex h-full min-h-0 flex-col", gap && "gap-4", pad && "p-4")}>
+		{@render banner()}
+		{@render columns(true)}
+	</div>
+{:else}
+	{@render columns(false)}
+{/if}
+
+<!-- =========================== -->
+<!-- STYLE -->
+<!-- =========================== -->
+<style>
+	/* The stacked list-to-record swap. The incoming pane moves: forward from the
+	   right, back from the left. It runs when `data-pane` flips. */
+	@media (max-width: 1023px) {
+		.md-cols[data-stack="lg"][data-pane="detail"] > .md-detail {
+			animation: md-in-forward var(--duration-fast) var(--ease-smooth-out) both;
+		}
+
+		.md-cols[data-stack="lg"][data-pane="rail"] > .md-rail {
+			animation: md-in-back var(--duration-fast) var(--ease-smooth-out) both;
+		}
+	}
+
+	@media (max-width: 1279px) {
+		.md-cols[data-stack="xl"][data-pane="detail"] > .md-detail {
+			animation: md-in-forward var(--duration-fast) var(--ease-smooth-out) both;
+		}
+
+		.md-cols[data-stack="xl"][data-pane="rail"] > .md-rail {
+			animation: md-in-back var(--duration-fast) var(--ease-smooth-out) both;
+		}
+	}
+
+	@keyframes md-in-forward {
+		from {
+			opacity: 0;
+			transform: translateX(var(--distance-large));
+		}
+		to {
+			opacity: 1;
+			transform: none;
+		}
+	}
+
+	@keyframes md-in-back {
+		from {
+			opacity: 0;
+			transform: translateX(calc(var(--distance-large) * -1));
+		}
+		to {
+			opacity: 1;
+			transform: none;
+		}
+	}
+
+	@media (prefers-reduced-motion: reduce) {
+		.md-cols > .md-rail,
+		.md-cols > .md-detail {
+			animation-duration: 1ms;
+		}
+	}
+</style>

package/src/components/list-page/master-detail.test.ts

@@ -0,0 +1,37 @@
+import { readFileSync } from "node:fs";
+import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vite-plus/test";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const shell = readFileSync(resolve(here, "master-detail.svelte"), "utf8");
+const row = readFileSync(resolve(here, "rail-row.svelte"), "utf8");
+
+describe("master detail on a phone", () => {
+  it("shows one pane at a time below the stack breakpoint", () => {
+    // Two rows put a 34svh rail scroller above a second one. One row, one
+    // pane, hidden only while stacked so desktop stays untouched.
+    expect(shell).toContain("grid-rows-[minmax(0,1fr)] lg:grid-rows-1");
+    expect(shell).toContain("grid-rows-[minmax(0,1fr)] xl:grid-rows-1");
+    expect(shell).not.toContain("max-h-[34svh]");
+    expect(shell).toContain('stackBelow === "xl" ? "max-xl:hidden" : "max-lg:hidden"');
+    expect(shell).toContain('stackBelow && pane === "detail" && hideWhileStacked');
+    expect(shell).toContain('stackBelow && pane === "rail" && hideWhileStacked');
+  });
+
+  it("draws a way back to the list, and only while stacked", () => {
+    expect(shell).toContain('stackBelow === "xl" ? "xl:hidden" : "lg:hidden"');
+    expect(shell).toContain('onclick={() => (pane = "rail")}');
+    expect(shell).toContain("{backLabel}");
+  });
+
+  it("lets a page open on the record its url names", () => {
+    expect(shell).toContain('pane = $bindable("rail")');
+  });
+
+  it("moves to the record when a rail row is picked", () => {
+    expect(shell).toContain("setContext<MasterDetailPane>(MASTER_DETAIL_PANE");
+    expect(row).toContain("getContext<MasterDetailPane | undefined>(MASTER_DETAIL_PANE)");
+    expect(row).toContain("pane?.open()");
+  });
+});

package/src/components/list-page/notice-bar.svelte

@@ -0,0 +1,68 @@
+<script lang="ts">
+// =========================
+// IMPORTS
+// =========================
+import type { Snippet } from "svelte";
+import { Warning, Info, CheckCircle, WarningCircle } from "phosphor-svelte";
+import { cn } from "@heyramzi/utils";
+import { Alert } from "../../shadcn/alert/index.js";
+import { TONE_CLASS, type Tone as SeverityTone } from "../../lib/tone.js";
+import type { PhosphorIcon } from "../../lib/icon-types.js";
+
+// =========================
+// TYPES
+// =========================
+// A strip that stops the reader is a severity. Neutral and accent are chip tones.
+type Tone = Extract<SeverityTone, "destructive" | "warning" | "info" | "success">;
+
+interface Props {
+	// The "look at this before you act" strip. Hand-rolled ones used raw amber
+	// and sky, so one severity showed two colours one route apart.
+	tone?: Tone;
+	icon?: PhosphorIcon;
+	// The trailing control: a retry, a jump to the thing that needs fixing.
+	actions?: Snippet;
+	children: Snippet;
+	class?: string;
+}
+
+const TONE_ICON: Record<Tone, PhosphorIcon> = {
+	destructive: Warning,
+	warning: WarningCircle,
+	info: Info,
+	success: CheckCircle,
+};
+
+// =========================
+// PROPS
+// =========================
+let { tone = "destructive", icon, actions, children, class: className }: Props = $props();
+
+// =========================
+// DERIVED
+// =========================
+let Icon = $derived(icon ?? TONE_ICON[tone]);
+</script>
+
+<!-- =========================== -->
+<!-- MARKUP -->
+<!-- =========================== -->
+<!-- WHY `status` for the calm tones: info and success shouldn't interrupt a
+     screen reader the way a failure does. -->
+<Alert
+	variant={tone === "destructive" ? "destructive" : "default"}
+	role={tone === "destructive" || tone === "warning" ? "alert" : "status"}
+	class={cn(
+		"flex flex-wrap items-center gap-x-3 gap-y-2 rounded-xl [&>svg]:translate-y-0",
+		TONE_CLASS[tone],
+		className,
+	)}
+>
+	<Icon class="size-4 shrink-0" aria-hidden="true" />
+	<span class="min-w-0 flex-1 font-medium">{@render children()}</span>
+	{#if actions}
+		<div class="flex shrink-0 items-center gap-2">
+			{@render actions()}
+		</div>
+	{/if}
+</Alert>

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

@@ -0,0 +1,104 @@
+<script lang="ts">
+// =========================
+// IMPORTS
+// =========================
+import { CaretLeft, CaretRight } from "phosphor-svelte";
+import { cn } from "@heyramzi/utils";
+import { Button } from "../../shadcn/button/index.js";
+import { stepTo } from "./step.js";
+
+// =========================
+// TYPES
+// =========================
+type Props = {
+	/** Ids in the order the list shows them. */
+	ids: readonly string[];
+	current: string | null | undefined;
+	onselect: (id: string) => void;
+	previousLabel?: string;
+	nextLabel?: string;
+	/** Off when two steppers share a page, so one key press moves one list. */
+	keys?: boolean;
+	class?: string;
+};
+
+// =========================
+// PROPS
+// =========================
+let {
+	ids,
+	current,
+	onselect,
+	previousLabel = "Previous",
+	nextLabel = "Next",
+	keys = true,
+	class: className,
+}: Props = $props();
+
+// =========================
+// DERIVED
+// =========================
+let index = $derived(current ? ids.indexOf(current) : -1);
+let prev = $derived(stepTo(ids, current, -1));
+let next = $derived(stepTo(ids, current, 1));
+
+// =========================
+// HANDLERS
+// =========================
+function isTyping(event: KeyboardEvent): boolean {
+	const target = event.target as HTMLElement | null;
+	return Boolean(target?.closest("input, textarea, select, [contenteditable='true']"));
+}
+
+function ignored(event: KeyboardEvent): boolean {
+	const modified = event.metaKey || event.ctrlKey || event.altKey;
+	return !keys || modified || event.defaultPrevented || isTyping(event);
+}
+
+// K and J, as in Gmail: the arrows already belong to slide viewers and text fields.
+function targetFor(key: string): string | null {
+	if (key === "k") return prev;
+	if (key === "j") return next;
+	return null;
+}
+
+function onkeydown(event: KeyboardEvent) {
+	if (ignored(event)) return;
+	const id = targetFor(event.key);
+	if (!id) return;
+	event.preventDefault();
+	onselect(id);
+}
+</script>
+
+<svelte:window {onkeydown} />
+
+{#if index >= 0 && ids.length > 1}
+	<div class={cn("flex items-center gap-0.5 text-muted-foreground", className)}>
+		<Button
+			variant="ghost"
+			size="sm"
+			icon
+			class="text-muted-foreground"
+			disabled={!prev}
+			onclick={() => prev && onselect(prev)}
+			aria-label={previousLabel}
+			title={`${previousLabel} (K)`}
+		>
+			<CaretLeft size={15} />
+		</Button>
+		<span class="min-w-9 text-center text-xs tabular-nums">{index + 1}/{ids.length}</span>
+		<Button
+			variant="ghost"
+			size="sm"
+			icon
+			class="text-muted-foreground"
+			disabled={!next}
+			onclick={() => next && onselect(next)}
+			aria-label={nextLabel}
+			title={`${nextLabel} (J)`}
+		>
+			<CaretRight size={15} />
+		</Button>
+	</div>
+{/if}

package/src/components/list-page/queue-rail.ts

@@ -0,0 +1,25 @@
+/**
+ * The rail surface of a queue page, passed to `MasterDetail`'s `railClass`.
+ * A class, not a wrapper: the shell's `<aside>` already owns the scroll height.
+ */
+// Copies of this string drifted to `rounded-lg`, the control radius, not the container one.
+export const queueRailClass =
+  "flex flex-col overflow-hidden rounded-xl border border-border bg-card";
+
+/**
+ * The rail column track, passed to `MasterDetail`'s `railWidth`. One page ran
+ * 20px wider, so the detail pane jumped between pages.
+ */
+// 280px fits a two-line thread title. Past 340px the list competes with the record.
+export const queueRailWidth = "minmax(280px, 340px)";
+
+/**
+ * Context key for the pane `MasterDetail` shows on a phone. Picking a row moves
+ * to the record, so `RailRow` reads this instead of each page passing a callback.
+ */
+export const MASTER_DETAIL_PANE = Symbol("master-detail-pane");
+
+export type MasterDetailPane = {
+  /** Show the detail pane. No-op above the stack breakpoint, where both are visible. */
+  open: () => void;
+};

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

@@ -0,0 +1,29 @@
+<script lang="ts">
+// =========================
+// IMPORTS
+// =========================
+import type { Snippet } from "svelte";
+import { cn } from "@heyramzi/utils";
+
+// =========================
+// TYPES
+// =========================
+type 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;
+	class?: string;
+};
+
+// =========================
+// PROPS
+// =========================
+let { children, class: className }: Props = $props();
+</script>
+
+<!-- =========================== -->
+<!-- MARKUP -->
+<!-- =========================== -->
+<div class={cn("min-h-0 flex-1 overflow-y-auto", className)}>
+	{@render children()}
+</div>