@heyramzi/ui 0.0.0-stage → 1.53.0

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

@@ -0,0 +1,107 @@
+<script lang="ts">
+// =========================
+// IMPORTS
+// =========================
+import type { Snippet } from "svelte";
+import { cn } from "@heyramzi/utils";
+
+// =========================
+// TYPES
+// =========================
+type 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;
+	// The state chip beside the title.
+	badge?: Snippet;
+	// A picture ahead of the title, like a video frame or a deck cover. Some
+	// records aren't recognisable from their title alone.
+	leading?: Snippet;
+	// Facts about the record, rendered as one dot-separated line under the
+	// title. Falsy entries drop out, so a caller can inline its conditionals.
+	meta?: Array<string | null | undefined | false>;
+	// A sentence under the meta line, when the record explains itself.
+	note?: string | null;
+	// What you can do to the record. Pinned right of the identity block, EXCEPT
+	// when a picture leads: see the note in the markup.
+	actions?: Snippet;
+	// The top-right control, a record's way out. Pass `undefined` when empty:
+	// an empty snippet is still truthy and reserves the corner.
+	corner?: Snippet;
+	// Hairline-separated rows below the identity block. Use `DetailRow`.
+	children?: Snippet;
+	class?: string;
+};
+
+// =========================
+// PROPS
+// =========================
+let { title, badge, leading, meta, note, actions, corner, children, class: className }: Props =
+	$props();
+
+// =========================
+// DERIVED
+// =========================
+let facts = $derived((meta ?? []).filter((item): item is string => Boolean(item)));
+// Actions stack under the meta when something else claims the right edge:
+// a picture, or the corner. Pinned beside a corner, they left the title
+// a third of the row.
+let stackActions = $derived(Boolean(leading || corner));
+</script>
+
+<!-- =========================== -->
+<!-- MARKUP -->
+<!-- =========================== -->
+<section class={cn("overflow-hidden rounded-xl border border-border bg-card", className)}>
+	<div class="flex flex-wrap items-start justify-between gap-x-4 gap-y-3 p-4">
+		{#if leading}
+			<div class="shrink-0">{@render leading()}</div>
+		{/if}
+		<div class="min-w-0 flow-root flex-1 basis-64">
+			<!-- The corner floats, so only the lines beside it give way. Reserved
+			     across the whole row it took ~150px off every line and wrapped a
+			     normal title to three. -->
+			{#if corner}
+				<div class="float-end ms-3">{@render corner()}</div>
+			{/if}
+			<!-- The badge sits inline in the h2 so it trails the last word. As a
+			     flex sibling it wrapped to its own row on every two-line title. -->
+			<!-- No text-balance: it evens the lines out, so a two-line title stopped
+			     short of the corner instead of running the full width. -->
+			<h2 class="min-w-0 font-heading text-lg font-semibold leading-snug tracking-tight">
+				{title}{#if badge}<span class="ms-2 inline-flex align-middle">{@render badge()}</span
+					>{/if}
+			</h2>
+			{#if facts.length > 0}
+				<!-- Each dot hangs off the fact it leads, so a wrapped line's dot stays
+				     in the gutter. A standalone flex-item dot dangled on the line above. -->
+				<div class="mt-1 overflow-hidden">
+					<p class="-ms-3 flex flex-wrap items-center text-sm text-muted-foreground">
+						{#each facts as fact, i (i)}
+							<span
+								class="relative ps-3 before:absolute before:start-1 before:opacity-40 before:content-['·']"
+								>{fact}</span
+							>
+						{/each}
+					</p>
+				</div>
+			{/if}
+			{#if note}
+				<p class="mt-1 text-sm text-muted-foreground">{note}</p>
+			{/if}
+			<!-- With a picture or a corner, actions sit in this column. Pinned right
+			     they wrapped under the picture and read like its caption. -->
+			{#if actions && stackActions}
+				<div class="clear-both flex flex-wrap items-center gap-2 pt-3">
+					{@render actions()}
+				</div>
+			{/if}
+		</div>
+		{#if actions && !stackActions}
+			<div class="flex flex-wrap items-center gap-2">{@render actions()}</div>
+		{/if}
+	</div>
+	{#if children}
+		{@render children()}
+	{/if}
+</section>

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

@@ -0,0 +1,90 @@
+<script lang="ts">
+// =========================
+// IMPORTS
+// =========================
+import type { Snippet } from "svelte";
+import SectionLabel from "./section-label.svelte";
+import { cn } from "@heyramzi/utils";
+import { panelHeaderClass, panelShellClass } from "../../lib/panel.js";
+import type { PhosphorIcon } from "../../lib/icon-types.js";
+
+// =========================
+// TYPES
+// =========================
+type 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;
+	labelIcon?: PhosphorIcon;
+	// A mark the icon set does not carry (a platform logo), drawn ahead of the
+	// label at the same optical size.
+	labelLead?: Snippet;
+	// The right side of the header bar: a count, a hint, a button cluster.
+	actions?: Snippet;
+	// WHY: a panel whose body is a media grid or a full-bleed list supplies its
+	// own padding, so the shell must be able to step out of the way.
+	pad?: boolean;
+	// Takes the height the panels above it did not use, inside a `fill` stack.
+	// One panel per stack, and it is the one the reader works in.
+	grow?: boolean;
+	children: Snippet;
+	class?: string;
+	bodyClass?: string;
+};
+
+// =========================
+// PROPS
+// =========================
+let {
+	label,
+	labelIcon,
+	labelLead,
+	actions,
+	pad = true,
+	grow = false,
+	children,
+	class: className,
+	bodyClass,
+}: Props = $props();
+
+// =========================
+// DERIVED
+// =========================
+let hasHeader = $derived(Boolean(label || labelLead || actions));
+</script>
+
+<!-- =========================== -->
+<!-- MARKUP -->
+<!-- =========================== -->
+<section
+	class={cn(
+		panelShellClass,
+		grow && "flex min-h-0 flex-1 flex-col",
+		className,
+	)}
+>
+	{#if hasHeader}
+		<div
+			class={panelHeaderClass}
+		>
+			{#if label || labelLead}
+				<SectionLabel icon={labelIcon}>
+					{#if labelLead}
+						{@render labelLead()}
+					{/if}
+					{label}
+				</SectionLabel>
+			{:else}
+				<span></span>
+			{/if}
+			{#if actions}
+				<div class="flex min-w-0 flex-wrap items-center justify-end gap-2">
+					{@render actions()}
+				</div>
+			{/if}
+		</div>
+	{/if}
+	<div class={cn(pad && "p-4", grow && "flex min-h-0 flex-1 flex-col", bodyClass)}>
+		{@render children()}
+	</div>
+</section>

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

@@ -0,0 +1,36 @@
+<script lang="ts">
+// =========================
+// IMPORTS
+// =========================
+import type { Snippet } from "svelte";
+import { cn } from "@heyramzi/utils";
+
+// =========================
+// TYPES
+// =========================
+type Props = {
+	// A hairline band inside `DetailHeader` or `DetailPanel` for the record's
+	// own facts, so the page never nests cards inside cards.
+	muted?: boolean;
+	children: Snippet;
+	class?: string;
+};
+
+// =========================
+// PROPS
+// =========================
+let { muted = false, children, class: className }: Props = $props();
+</script>
+
+<!-- =========================== -->
+<!-- MARKUP -->
+<!-- =========================== -->
+<div
+	class={cn(
+		"border-t border-border px-4 py-3 text-sm leading-relaxed",
+		muted && "text-xs text-muted-foreground",
+		className,
+	)}
+>
+	{@render children()}
+</div>

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

@@ -0,0 +1,33 @@
+<script lang="ts">
+// =========================
+// IMPORTS
+// =========================
+import type { Snippet } from "svelte";
+import { cn } from "@heyramzi/utils";
+
+// =========================
+// TYPES
+// =========================
+type Props = {
+	// A flat stack of panels at one gap. `xl:pr-1` keeps the top panel's
+	// corner clear of the shell's scrollbar.
+
+	// `fill` makes the stack at least as tall as its scroller, so a `grow`
+	// panel (like a writing box) takes the empty bottom third back.
+	fill?: boolean;
+	children: Snippet;
+	class?: string;
+};
+
+// =========================
+// PROPS
+// =========================
+let { fill = false, children, class: className }: Props = $props();
+</script>
+
+<!-- =========================== -->
+<!-- MARKUP -->
+<!-- =========================== -->
+<div class={cn("flex flex-col gap-4 xl:pr-1", fill && "min-h-full", className)}>
+	{@render children()}
+</div>

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

@@ -0,0 +1,91 @@
+<script lang="ts">
+// =========================
+// IMPORTS
+// =========================
+import { Button } from "../../shadcn/button/index.js";
+import * as Empty from "../../shadcn/empty/index.js";
+import type { PhosphorIcon, IconWeight } from "../../lib/icon-types.js";
+
+// =========================
+// TYPES
+// =========================
+interface Props {
+	icon?: PhosphorIcon;
+	iconWeight?: IconWeight;
+	title: string;
+	description?: string;
+	actionLabel?: string;
+	actionHref?: string;
+	onAction?: () => void;
+}
+
+// =========================
+// PROPS
+// =========================
+let {
+	icon: Icon,
+	iconWeight,
+	title,
+	description,
+	actionLabel,
+	actionHref,
+	onAction,
+}: Props = $props();
+</script>
+
+<!-- =========================== -->
+<!-- MARKUP -->
+<!-- =========================== -->
+<!-- The four parts arrive in reading order. The stagger is what says the page
+     finished loading and is simply empty. -->
+<Empty.Root class="t-empty py-16">
+	<Empty.Header class="max-w-md">
+		{#if Icon}
+			<Empty.Media class="mb-4 size-16 rounded-2xl bg-brand-indigo/10 text-brand-indigo">
+				<Icon weight={iconWeight} class="size-8" />
+			</Empty.Media>
+		{/if}
+		<Empty.Title class="font-heading text-lg font-semibold">{title}</Empty.Title>
+		{#if description}
+			<Empty.Description>{description}</Empty.Description>
+		{/if}
+	</Empty.Header>
+	{#if actionLabel && (actionHref || onAction)}
+		<Empty.Content>
+			{#if actionHref}
+				<Button href={actionHref}>{actionLabel}</Button>
+			{:else}
+				<Button onclick={onAction}>{actionLabel}</Button>
+			{/if}
+		</Empty.Content>
+	{/if}
+</Empty.Root>
+
+<!-- =========================== -->
+<!-- STYLE -->
+<!-- =========================== -->
+<style>
+	/* Never `:nth-child` here: one such rule makes every DOM insert on the page restyle its later siblings. */
+	:global(.t-empty) > :global(*) {
+		animation: t-empty-in var(--duration-very-slow) var(--ease-smooth-out) both;
+		animation-delay: calc((sibling-index() - 1) * var(--duration-stagger));
+	}
+
+	@keyframes -global-t-empty-in {
+		from {
+			opacity: 0;
+			transform: translateY(var(--distance-small));
+		}
+		to {
+			opacity: 1;
+			transform: none;
+		}
+	}
+
+	@media (prefers-reduced-motion: reduce) {
+		:global(.t-empty) > :global(*) {
+			animation-duration: 1ms;
+			animation-delay: 0ms;
+		}
+	}
+</style>

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

@@ -0,0 +1,49 @@
+<script lang="ts">
+// =========================
+// IMPORTS
+// =========================
+import type { Snippet } from "svelte";
+import { Checkbox } from "../../shadcn/checkbox/index.js";
+import { Check } from "phosphor-svelte";
+import { cn } from "@heyramzi/utils";
+
+// =========================
+// TYPES
+// =========================
+type Props = {
+	checked: boolean;
+	onclick: () => void;
+	variant?: "checkbox" | "radio";
+	children: Snippet;
+};
+
+// =========================
+// PROPS
+// =========================
+let { checked, onclick, variant = "checkbox", children }: Props = $props();
+</script>
+
+<!-- =========================== -->
+<!-- MARKUP -->
+<!-- =========================== -->
+<button
+	type="button"
+	class="flex items-center gap-2 rounded-lg px-2 py-1.5 text-sm transition-colors hover:bg-muted"
+	{onclick}
+>
+	{#if variant === "radio"}
+		<span
+			class={cn(
+				"grid size-3.5 shrink-0 place-items-center rounded-full border transition-colors",
+				checked ? "border-primary bg-primary text-primary-foreground" : "border-border",
+			)}
+		>
+			{#if checked}
+				<Check class="size-2.5" weight="bold" />
+			{/if}
+		</span>
+	{:else}
+		<Checkbox {checked} />
+	{/if}
+	{@render children()}
+</button>

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

@@ -0,0 +1,88 @@
+<script lang="ts">
+// =========================
+// IMPORTS
+// =========================
+import type { Snippet } from "svelte";
+import * as Popover from "../../shadcn/popover/index.js";
+import { Funnel as FunnelIcon } from "phosphor-svelte";
+import { cn } from "@heyramzi/utils";
+import { Button } from "../../shadcn/button/index.js";
+import { toolbarTriggerClass } from "./toolbar-trigger.js";
+import type { PhosphorIcon } from "../../lib/icon-types.js";
+
+// phosphor-svelte v2 (resolved here) and v3 (what consumers run) differ only in
+// Component generics. The cast bridges that type-only gap.
+const DefaultFunnelIcon = FunnelIcon as unknown as PhosphorIcon;
+
+// =========================
+// TYPES
+// =========================
+type Props = {
+	label: string;
+	icon?: PhosphorIcon;
+	count?: number;
+	active?: boolean;
+	onClear?: () => void;
+	align?: "start" | "center" | "end";
+	width?: `w-${string}`;
+	open?: boolean;
+	clearLabel?: string;
+	triggerClass?: string;
+	contentClass?: string;
+	children: Snippet;
+	trailing?: Snippet;
+};
+
+// =========================
+// PROPS
+// =========================
+let {
+	label,
+	icon: IconComponent = DefaultFunnelIcon,
+	count = 0,
+	active,
+	onClear,
+	align = "start",
+	width = "w-52",
+	open = $bindable(false),
+	clearLabel = "Clear",
+	triggerClass,
+	contentClass,
+	children,
+	trailing,
+}: Props = $props();
+
+// =========================
+// DERIVED
+// =========================
+let hasCount = $derived(count > 0);
+let isActive = $derived(active ?? hasCount);
+</script>
+
+<!-- =========================== -->
+<!-- MARKUP -->
+<!-- =========================== -->
+<Popover.Root bind:open>
+	<Popover.Trigger class={toolbarTriggerClass({ active: isActive, className: triggerClass })}>
+		<IconComponent class="size-3.5" />
+		<span>{label}</span>
+		{#if trailing}
+			{@render trailing()}
+		{/if}
+		{#if hasCount}
+			<span
+				class="ml-0.5 inline-flex size-4 items-center justify-center rounded-full bg-brand-indigo/15 text-[10px] font-semibold text-brand-indigo dark:text-brand-indigo-light"
+			>
+				{count}
+			</span>
+		{/if}
+	</Popover.Trigger>
+	<Popover.Content class={cn("p-2", width, contentClass)} {align}>
+		{@render children()}
+		{#if onClear && hasCount}
+			<Button variant="ghost" size="sm" class="mt-2 w-full text-xs text-muted-foreground" onclick={onClear}>
+				{clearLabel}
+			</Button>
+		{/if}
+	</Popover.Content>
+</Popover.Root>

package/src/components/list-page/filter-section.ts

@@ -0,0 +1,12 @@
+import { cn } from "@heyramzi/utils";
+
+// The header for each control group in a toolbar popover, in one place so
+// sections can't drift in size or weight.
+
+// `first:` drops the leading header's top padding, since the popover pads itself.
+export function filterSectionClass(className?: string): string {
+  return cn(
+    "px-2 pt-2 pb-1 text-[11px] font-medium uppercase tracking-wide text-muted-foreground first:pt-1",
+    className,
+  );
+}

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

@@ -0,0 +1,116 @@
+<script lang="ts" generics="TGroup">
+	// =========================
+	// IMPORTS
+	// =========================
+	import { untrack, type Snippet } from "svelte";
+	import { SvelteSet } from "svelte/reactivity";
+	import { CaretDown } from "phosphor-svelte";
+	import { cn } from "@heyramzi/utils";
+
+	// =========================
+	// TYPES
+	// =========================
+	type Props = {
+		groups: TGroup[];
+		getKey: (group: TGroup) => string;
+		defaultCollapsed?: string[];
+		/** WHY: a page that drives its own keyboard cursor has to know which rows
+		    are on screen, and the collapsed set is the only thing that says so. */
+		onCollapsedChange?: (keys: string[]) => void;
+		header: Snippet<[TGroup, { collapsed: boolean }]>;
+		/** Controls beside the header, outside its toggle button so a click on
+		    one doesn't collapse the group. Shown on hover of the header row. */
+		actions?: Snippet<[TGroup]>;
+		rows: Snippet<[TGroup]>;
+		class?: string;
+		onGroupDragOver?: (e: DragEvent, group: TGroup) => void;
+		onGroupDragLeave?: (e: DragEvent) => void;
+		onGroupDrop?: (e: DragEvent, group: TGroup) => void;
+	};
+
+	// =========================
+	// PROPS
+	// =========================
+	let {
+		groups,
+		getKey,
+		defaultCollapsed = [],
+		onCollapsedChange,
+		header,
+		actions,
+		rows,
+		class: className,
+		onGroupDragOver,
+		onGroupDragLeave,
+		onGroupDrop,
+	}: Props = $props();
+
+	// =========================
+	// STATE
+	// =========================
+	const collapsed = new SvelteSet<string>(untrack(() => defaultCollapsed));
+
+	// =========================
+	// FUNCTIONS
+	// =========================
+	function toggle(key: string) {
+		if (collapsed.has(key)) {
+			collapsed.delete(key);
+		} else {
+			collapsed.add(key);
+		}
+		onCollapsedChange?.([...collapsed]);
+	}
+</script>
+
+<!-- =========================== -->
+<!-- MARKUP -->
+<!-- =========================== -->
+<div class={cn("flex w-full flex-col", className)}>
+	{#each groups as group, index (getKey(group))}
+		{@const key = getKey(group)}
+		{@const isCollapsed = collapsed.has(key)}
+		<div
+			class={cn(index > 0 && "mt-3 border-t border-border/50 pt-3")}
+			role={onGroupDragOver || onGroupDrop ? "group" : undefined}
+			ondragover={onGroupDragOver ? (e) => onGroupDragOver(e, group) : undefined}
+			ondragleave={onGroupDragLeave}
+			ondrop={onGroupDrop ? (e) => onGroupDrop(e, group) : undefined}
+		>
+			<div class="group/header flex items-center gap-1 rounded-lg transition-colors hover:bg-muted/60">
+				<button
+					type="button"
+					class="flex min-w-0 flex-1 cursor-pointer items-center gap-2.5 rounded-lg px-3 py-2 text-left"
+					onclick={() => toggle(key)}
+					aria-expanded={!isCollapsed}
+				>
+					<CaretDown
+						class={cn(
+							"size-3 shrink-0 text-muted-foreground/60 transition-transform duration-[var(--duration-fast)] ease-[var(--ease-smooth-out)]",
+							isCollapsed && "-rotate-90",
+						)}
+						weight="bold"
+					/>
+					{@render header(group, { collapsed: isCollapsed })}
+				</button>
+				{#if actions}
+					<div
+						class="flex shrink-0 items-center gap-1 pe-2 opacity-0 transition-opacity group-hover/header:opacity-100 focus-within:opacity-100 any-pointer-coarse:opacity-100"
+					>
+						{@render actions(group)}
+					</div>
+				{/if}
+			</div>
+
+			{#if !isCollapsed}
+				<div>
+					{@render rows(group)}
+				</div>
+			{/if}
+		</div>
+	{/each}
+</div>
+
+<!-- No entrance motion. Four stacked animations made the last group of a
+     40-row board arrive two seconds late. Working surfaces don't animate in. -->
+<!-- No `overflow: hidden` either: it clipped anything a row opened. -->

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

@@ -0,0 +1,28 @@
+export { default as DetailEmpty } from "./detail-empty.svelte";
+export { default as DetailHeader } from "./detail-header.svelte";
+export { default as DetailPanel } from "./detail-panel.svelte";
+export { default as DetailRow } from "./detail-row.svelte";
+export { default as DetailStack } from "./detail-stack.svelte";
+export { default as EmptyState } from "./empty-state.svelte";
+export { default as FilterItem } from "./filter-item.svelte";
+export { default as PrevNext } from "./prev-next.svelte";
+export { stepTo } from "./step.js";
+export { default as NoticeBar } from "./notice-bar.svelte";
+export { default as RailBody } from "./rail-body.svelte";
+export { default as RailEmpty } from "./rail-empty.svelte";
+export { default as RailHead } from "./rail-head.svelte";
+export { default as RailRow } from "./rail-row.svelte";
+export { default as SectionLabel } from "./section-label.svelte";
+export { queueRailClass, queueRailWidth } from "./queue-rail.js";
+export { default as FilterPopover } from "./filter-popover.svelte";
+export { filterSectionClass } from "./filter-section.js";
+export { default as GroupedList } from "./grouped-list.svelte";
+export { default as ListPageShell } from "./list-page-shell.svelte";
+export { default as MasterDetail } from "./master-detail.svelte";
+// The segmented control isn't re-exported here. Two import paths drifted, so
+// its one home is `@heyramzi/ui/components/segmented`.
+export { default as ToolbarSearch } from "./toolbar-search.svelte";
+export { toolbarTriggerClass } from "./toolbar-trigger.js";
+export { listTable } from "./list-table.js";
+export type { ViewMode } from "./types.js";
+export { getSectionHost, setSectionHost, type SectionHost } from "./section-host.js";