@heyramzi/ui 7.0.0 → 8.1.0

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>

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

@@ -0,0 +1,51 @@
+<script lang="ts">
+// =========================
+// IMPORTS
+// =========================
+import { cn } from "@heyramzi/utils";
+import * as Empty from "../../shadcn/empty/index.js";
+import type { PhosphorIcon, IconWeight } from "../../lib/icon-types.js";
+
+// =========================
+// TYPES
+// =========================
+interface Props {
+	// Not `EmptyState`, which has a 48px icon and an action. This says a filter
+	// came back empty, in one sentence that fits a 280px rail.
+	icon?: PhosphorIcon;
+	iconWeight?: IconWeight;
+	iconClass?: string;
+	title: string;
+	hint?: string;
+	class?: string;
+}
+
+// =========================
+// PROPS
+// =========================
+let {
+	icon: Icon,
+	iconWeight,
+	iconClass,
+	title,
+	hint,
+	class: className,
+}: Props = $props();
+</script>
+
+<!-- =========================== -->
+<!-- MARKUP -->
+<!-- =========================== -->
+<Empty.Root class={cn("h-full gap-2 px-6 py-12", className)}>
+	{#if Icon}
+		<Icon
+			weight={iconWeight}
+			class={cn("size-6", iconClass ?? "text-muted-foreground/40")}
+			aria-hidden="true"
+		/>
+	{/if}
+	<Empty.Title>{title}</Empty.Title>
+	{#if hint}
+		<Empty.Description class="max-w-56 text-xs leading-relaxed">{hint}</Empty.Description>
+	{/if}
+</Empty.Root>

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

@@ -0,0 +1,49 @@
+<script lang="ts">
+// =========================
+// IMPORTS
+// =========================
+import type { Snippet } from "svelte";
+import SectionLabel from "./section-label.svelte";
+import { cn } from "@heyramzi/utils";
+
+// =========================
+// TYPES
+// =========================
+type 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;
+	// A low-emphasis control beside the label (compose, refresh).
+	action?: Snippet;
+	// The filter, the search, whatever narrows the list. Optional: a rail of four
+	// records has nothing to narrow, and an empty strip under the label is chrome.
+	children?: Snippet;
+	class?: string;
+};
+
+// =========================
+// PROPS
+// =========================
+let { label, action, children, class: className }: Props = $props();
+</script>
+
+<!-- =========================== -->
+<!-- MARKUP -->
+<!-- =========================== -->
+<div class={cn("shrink-0 space-y-2 border-b border-border px-3 py-2.5", className)}>
+	{#if label || action}
+		<div class="flex min-h-7 items-center justify-between gap-2 pl-1">
+			{#if label}
+				<SectionLabel>{label}</SectionLabel>
+			{:else}
+				<span></span>
+			{/if}
+			{#if action}
+				{@render action()}
+			{/if}
+		</div>
+	{/if}
+	{#if children}
+		{@render children()}
+	{/if}
+</div>