@heyramzi/ui 6.1.0 → 8.0.0

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

@@ -0,0 +1,163 @@
+<script lang="ts">
+// =========================
+// IMPORTS
+// =========================
+import type { Snippet } from "svelte";
+import { getContext } from "svelte";
+import { cn } from "@heyramzi/utils";
+import { MASTER_DETAIL_PANE, type MasterDetailPane } from "./queue-rail.js";
+
+// =========================
+// TYPES
+// =========================
+type 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;
+	selected?: boolean;
+	onclick: () => void;
+	// A thumbnail or avatar ahead of the title.
+	leading?: Snippet;
+	// The record's state, at the end of the preview line. Never beside the title,
+	// where it competes with the name.
+	trailing?: Snippet;
+	// One line of the record's own words, under the title.
+	preview?: string | null;
+	// Dot-separated facts under the preview. Falsy entries drop out.
+	meta?: Array<string | null | undefined | false>;
+	// Which fact gives up its width first. The others hold their full text, so
+	// a date or a count never truncates to nonsense.
+	metaTruncate?: "first" | "last";
+	// Icons that qualify the facts (a waiting reply, a removed comment).
+	metaTrail?: Snippet;
+	// Controls that appear on hover, over the row's top-right corner.
+	actions?: Snippet;
+	// Long records (thread titles) need two lines to be recognisable.
+	titleLines?: 1 | 2;
+	class?: string;
+};
+
+// =========================
+// PROPS
+// =========================
+let {
+	title,
+	selected = false,
+	onclick,
+	leading,
+	trailing,
+	preview,
+	meta,
+	metaTruncate = "first",
+	metaTrail,
+	actions,
+	titleLines = 1,
+	class: className,
+}: Props = $props();
+
+// =========================
+// DERIVED
+// =========================
+let facts = $derived((meta ?? []).filter((item): item is string => Boolean(item)));
+
+// =========================
+// FUNCTIONS
+// =========================
+// Picking a row moves a phone from list to record. `undefined` outside a
+// `MasterDetail`, where a rail is just a list.
+let row = $state<HTMLDivElement>();
+
+// A row picked from a link, a shortcut or the next arrow can sit below the fold.
+$effect(() => {
+	if (selected) row?.scrollIntoView({ block: "nearest" });
+});
+
+let pane = getContext<MasterDetailPane | undefined>(MASTER_DETAIL_PANE);
+
+function select() {
+	onclick();
+	pane?.open();
+}
+</script>
+
+<!-- =========================== -->
+<!-- MARKUP -->
+<!-- =========================== -->
+<!-- The hairline belongs to the row, so grouped and flat rails draw it the same.
+     `first:border-t-0` keeps each group's top row clean under its header. -->
+<div
+	bind:this={row}
+	class={cn(
+		// `group/row` too: `CopyHandoff` waits for `group-hover/row`, and a bare
+		// `group` left it invisible on every rail.
+		"group group/row relative border-t border-border first:border-t-0",
+		selected ? "bg-accent" : "hover:bg-muted/50",
+		className,
+	)}
+>
+	<button
+		type="button"
+		class={cn(
+			"t-press flex w-full items-start gap-3 px-4 py-3 text-left any-pointer-coarse:py-3.5",
+			"focus-visible:outline-none focus-visible:ring-3 focus-visible:ring-ring/50 focus-visible:ring-inset",
+			// WHY: the hover actions sit over this corner, so the text stops short
+			// of them rather than sliding underneath when a title is long.
+			actions && "pr-24",
+		)}
+		onclick={select}
+		aria-current={selected ? "page" : undefined}
+	>
+		{#if leading}
+			<span class="shrink-0">{@render leading()}</span>
+		{/if}
+		<!-- The title owns its column. A chip beside it took a third of the width
+		     and clamped two-line titles. -->
+		<span class="flex min-w-0 flex-1 flex-col gap-1">
+			<span
+				class={cn(
+					"text-sm font-medium leading-snug",
+					titleLines === 2 ? "line-clamp-2" : "truncate",
+					selected && "text-accent-foreground",
+				)}
+			>
+				{title}
+			</span>
+			<!-- The state rides the preview, not the facts. Facts are `shrink-0`, so
+			     at 280px the chip got pushed off the row. Prose can give up width. -->
+			{#if preview || trailing}
+				<span class="flex min-w-0 items-center text-xs text-muted-foreground">
+					{#if preview}
+						<span class="truncate">{preview}</span>
+					{/if}
+					{#if trailing}
+						<span class="ml-auto flex shrink-0 items-center gap-1.5 pl-2">{@render trailing()}</span>
+					{/if}
+				</span>
+			{/if}
+			{#if facts.length > 0 || metaTrail}
+				<span class="flex min-w-0 items-center text-xs text-muted-foreground">
+					{#each facts as fact, i (i)}
+						{#if i > 0}
+							<span aria-hidden="true" class="mx-1.5 shrink-0 opacity-40">&middot;</span>
+						{/if}
+						{@const flexible =
+							facts.length > 1 && i === (metaTruncate === "last" ? facts.length - 1 : 0)}
+						<span class={flexible ? "truncate" : "shrink-0"}>{fact}</span>
+					{/each}
+					{#if metaTrail}
+						<span class="ml-1.5 flex shrink-0 items-center gap-1">{@render metaTrail()}</span>
+					{/if}
+				</span>
+			{/if}
+		</span>
+	</button>
+	{#if actions}
+		<!-- WHY visible on a coarse pointer: there is no hover on a touchscreen, so
+		     the row's actions would be unreachable there. -->
+		<div
+			class="absolute right-2 top-2 hidden items-center gap-1 group-hover:flex group-focus-within:flex any-pointer-coarse:flex"
+		>
+			{@render actions()}
+		</div>
+	{/if}
+</div>

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

@@ -0,0 +1,24 @@
+import { getContext, setContext } from "svelte";
+import type { SectionStrip } from "../segmented/section-runs.svelte";
+
+/**
+ * What an app shell gives a list page so the page's toolbar can draw the
+ * section strip. `strip` must be reactive (a `$state` field), and `claim` tells
+ * the shell a toolbar is drawing it and returns the release.
+ */
+export interface SectionHost {
+  readonly strip: SectionStrip | null;
+  claim(): () => void;
+}
+
+// WHY context: the shell decides the strip once and ninety pages draw it, so a prop on every page would be ninety edits.
+const KEY = Symbol("list-page.section-host");
+
+/** Call once in the layout that owns the section strip. */
+export function setSectionHost(host: SectionHost): void {
+  setContext(KEY, host);
+}
+
+export function getSectionHost(): SectionHost | undefined {
+  return getContext<SectionHost | undefined>(KEY);
+}

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

@@ -0,0 +1,39 @@
+<script lang="ts">
+// =========================
+// IMPORTS
+// =========================
+import type { Snippet } from "svelte";
+import { cn } from "@heyramzi/utils";
+import type { PhosphorIcon } from "../../lib/icon-types.js";
+
+// =========================
+// TYPES
+// =========================
+type Props = {
+	// The one label style for panel, rail group and sub-section headers. Retyped
+	// copies drifted to a different tracking value.
+	icon?: PhosphorIcon;
+	children: Snippet;
+	class?: string;
+};
+
+// =========================
+// PROPS
+// =========================
+let { icon: Icon, children, class: className }: Props = $props();
+</script>
+
+<!-- =========================== -->
+<!-- MARKUP -->
+<!-- =========================== -->
+<span
+	class={cn(
+		"flex items-center gap-2 text-xs font-semibold uppercase tracking-[0.14em] text-muted-foreground",
+		className,
+	)}
+>
+	{#if Icon}
+		<Icon class="size-4 text-brand-indigo" aria-hidden="true" />
+	{/if}
+	{@render children()}
+</span>

package/src/components/list-page/step.test.ts

@@ -0,0 +1,21 @@
+import { describe, expect, it } from "vite-plus/test";
+import { stepTo } from "./step.js";
+
+describe("stepTo", () => {
+  const ids = ["a", "b", "c"];
+
+  it("steps both ways from the middle", () => {
+    expect(stepTo(ids, "b", -1)).toBe("a");
+    expect(stepTo(ids, "b", 1)).toBe("c");
+  });
+
+  it("stops at either end", () => {
+    expect(stepTo(ids, "a", -1)).toBe(null);
+    expect(stepTo(ids, "c", 1)).toBe(null);
+  });
+
+  it("goes nowhere without a listed selection", () => {
+    expect(stepTo(ids, null, 1)).toBe(null);
+    expect(stepTo(ids, "z", 1)).toBe(null);
+  });
+});

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

@@ -0,0 +1,10 @@
+/** The id `by` rows away from `current`, or null at either end or when `current` isn't listed. */
+export function stepTo(
+  ids: readonly string[],
+  current: string | null | undefined,
+  by: 1 | -1,
+): string | null {
+  const index = current ? ids.indexOf(current) : -1;
+  if (index < 0) return null;
+  return ids[index + by] ?? null;
+}

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

@@ -0,0 +1,63 @@
+<script lang="ts">
+// =========================
+// IMPORTS
+// =========================
+import { Input } from "../../shadcn/input/index.js";
+import { MagnifyingGlass } from "phosphor-svelte";
+import { cn } from "@heyramzi/utils";
+
+// =========================
+// TYPES
+// =========================
+type Props = {
+	value: string;
+	placeholder?: string;
+	size?: "sm" | "default";
+	class?: string;
+};
+
+// =========================
+// PROPS
+// =========================
+let {
+	value = $bindable(""),
+	placeholder = "Search...",
+	size = "default",
+	class: extraClass,
+}: Props = $props();
+</script>
+
+<!-- =========================== -->
+<!-- MARKUP -->
+<!-- =========================== -->
+<!-- WHY: leading magnifying glass + a fixed height so every list page's toolbar
+     keeps the same rhythm; size="sm" matches the compact filter chips and
+     tabs used on dense list pages. -->
+<!-- Drops the caller's desk width once the toolbar row breaks, read from the
+     shell's container. Outside the shell the caller's width stands. -->
+<div
+	class={cn(
+		"relative",
+		extraClass,
+		"@max-3xl/toolbar:w-auto @max-3xl/toolbar:min-w-0 @max-3xl/toolbar:flex-1"
+	)}
+>
+	<MagnifyingGlass
+		class={cn(
+			"pointer-events-none absolute top-1/2 -translate-y-1/2 text-muted-foreground",
+			size === "sm" ? "left-2 size-3" : "left-2 size-3",
+		)}
+		aria-hidden="true"
+	/>
+	<!-- Keyed to the pointer, not the viewport. On an iPad, 12px text makes
+	     Safari zoom on focus and never zoom back. -->
+	<Input
+		bind:value
+		{placeholder}
+		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",
+		)}
+	/>
+</div>

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

@@ -0,0 +1,23 @@
+import { cn } from "@heyramzi/utils";
+
+type ToolbarTriggerOpts = {
+  active?: boolean;
+  className?: string;
+};
+
+// The trigger class for every toolbar control. Coarse pointers get a taller
+// box at the same type size, since the chip is too small for a thumb.
+
+// One fixed height, matching the `sm` button and the segmented track. A second
+// size put a 24px filter beside 28px controls on the calendar (14 Oct 2026).
+export function toolbarTriggerClass({
+  active = false,
+  className,
+}: 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",
+    active ? "bg-muted text-foreground" : "text-muted-foreground hover:text-foreground",
+    className,
+  );
+}

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

@@ -0,0 +1 @@
+export type ViewMode = "list" | "board" | "grid";

package/src/components/locale-switch/index.ts

@@ -0,0 +1 @@
+export { default as LocaleSwitch } from "./locale-switch.svelte";

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

@@ -0,0 +1,59 @@
+<script lang="ts">
+// =========================
+// IMPORTS
+// =========================
+import { SegmentedFilter, type TabDef } from "../segmented/index.js";
+
+// =========================
+// TYPES
+// =========================
+type LocaleOption = {
+	value: string;
+	label: string;
+	flag: string;
+};
+
+type Props = {
+	// Wraps `SegmentedFilter` so it shares one track with every other strip. It
+	// only adds each language's flag.
+	value: string;
+	onchange: (value: string) => void;
+	options?: LocaleOption[];
+	/** Names the control for a screen reader. Without it the group is two bare letters. */
+	ariaLabel?: string;
+	class?: string;
+};
+
+// =========================
+// PROPS
+// =========================
+let {
+	value,
+	onchange,
+	options = [
+		{ value: "en", label: "EN", flag: "/flags/US.svg" },
+		{ value: "fr", label: "FR", flag: "/flags/FR.svg" },
+	],
+	ariaLabel = "Language",
+	class: className,
+}: Props = $props();
+
+// =========================
+// DERIVED
+// =========================
+let segments = $derived<TabDef<string>[]>(
+	options.map((option) => ({ value: option.value, label: option.label, image: option.flag })),
+);
+</script>
+
+<!-- =========================== -->
+<!-- MARKUP -->
+<!-- =========================== -->
+<SegmentedFilter
+	{value}
+	onValueChange={onchange}
+	options={segments}
+	block={false}
+	{ariaLabel}
+	class={className}
+/>

package/src/components/mark/index.ts

@@ -0,0 +1 @@
+export { default as Mark } from "./mark.svelte";

package/src/components/mark/mark.svelte

@@ -0,0 +1,70 @@
+<script lang="ts">
+// =========================
+// IMPORTS
+// =========================
+import { cn } from "@heyramzi/utils";
+
+// =========================
+// TYPES
+// =========================
+
+/**
+ * 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 = {
+	/** 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. */
+	label: string;
+	/** `circle` crops a photograph to a disc, `square` fits a logo whole. */
+	shape?: "square" | "circle";
+	class?: string;
+};
+
+// =========================
+// PROPS
+// =========================
+let { src, label, shape = "square", class: className }: Props = $props();
+
+// =========================
+// STATE
+// =========================
+/** The src that failed, so a later one gets its own chance to load. */
+let broken = $state("");
+
+// =========================
+// DERIVED
+// =========================
+let round = $derived(shape === "circle");
+</script>
+
+<!-- =========================== -->
+<!-- MARKUP -->
+<!-- =========================== -->
+<!-- WHY the letter is a fallback and not a backdrop: a tile drawn UNDER the mark
+     shows its initial through every logo that is not a full-bleed square. -->
+{#if src && broken !== src}
+	<img
+		{src}
+		alt=""
+		loading="lazy"
+		referrerpolicy="no-referrer"
+		class={cn(
+			"size-4 shrink-0",
+			round ? "rounded-full object-cover" : "object-contain",
+			className,
+		)}
+		onerror={() => (broken = src)}
+	/>
+{:else}
+	<span
+		class={cn(
+			"bg-muted text-muted-foreground flex size-4 shrink-0 items-center justify-center text-[10px] leading-none font-bold",
+			round ? "rounded-full" : "rounded-xs",
+			className,
+		)}
+	>
+		{label.charAt(0)}
+	</span>
+{/if}

package/src/components/open-in/index.ts

@@ -0,0 +1,6 @@
+export { default as OpenIn } from "./open-in.svelte";
+export type {
+  OpenInSize,
+  OpenInTool,
+  OpenInVariant,
+} from "./open-in.svelte";

package/src/components/open-in/open-in.svelte

@@ -0,0 +1,106 @@
+<script lang="ts" module>
+	import type { Component } from "svelte";
+
+	/**
+	 * The one way out to a tool: mark, name, go-to arrow, never the verb, which
+	 * survives as the accessible name.
+	 */
+	export interface OpenInTool {
+		/** The visible text, and the word the tool calls itself. */
+		name: string;
+		/** The default accessible sentence, when the caller passes no translated one. */
+		action: string;
+		icon: Component<{ size?: number; class?: string }>;
+	}
+
+	/** `chip` is the bordered inline tag, `button` sits in a header beside other
+	 *  buttons, `icon` is the bare mark for a dense row. */
+	export type OpenInVariant = "chip" | "button" | "icon";
+	export type OpenInSize = "sm" | "default";
+</script>
+
+<script lang="ts">
+// =========================
+// IMPORTS
+// =========================
+import { ArrowSquareOut } from "phosphor-svelte";
+import { cn } from "@heyramzi/utils";
+import { buttonVariants } from "../../shadcn/button/index.js";
+
+// =========================
+// TYPES
+// =========================
+interface Props {
+	/** The tool to link to: its name, accessible sentence and mark. */
+	tool: OpenInTool;
+	href: string;
+	variant?: OpenInVariant;
+	size?: OpenInSize;
+	/** Overrides the visible text. The accessible name is `title`, never this. */
+	label?: string;
+	/** The accessible sentence, translated by the caller. */
+	title?: string;
+	class?: string;
+}
+
+// =========================
+// PROPS
+// =========================
+let {
+	tool,
+	href,
+	variant = "chip",
+	size = "default",
+	label,
+	title,
+	class: className,
+}: Props = $props();
+
+// =========================
+// DERIVED
+// =========================
+let Icon = $derived(tool.icon);
+let iconSize = $derived(size === "sm" ? 12 : 14);
+let action = $derived(title ?? tool.action);
+let text = $derived(label ?? tool.name);
+</script>
+
+<!-- =========================== -->
+<!-- MARKUP -->
+<!-- =========================== -->
+<!-- The click stops here because these usually sit in a clickable row, and a
+     call site that forgot would open the row as well. -->
+<!-- svelte-ignore a11y_no_static_element_interactions -->
+<div
+	class="inline-flex shrink-0"
+	onclick={(e) => e.stopPropagation()}
+	onkeydown={(e) => e.stopPropagation()}
+>
+	<a
+		{href}
+		target="_blank"
+		rel="noopener noreferrer"
+		aria-label={action}
+		title={action}
+		class={cn(
+			variant === "button"
+				? buttonVariants({ variant: "outline", size: size === "sm" ? "sm" : "default" })
+				: variant === "icon"
+					? "inline-flex shrink-0 items-center justify-center rounded text-muted-foreground transition-colors hover:bg-muted hover:text-foreground"
+					: cn(
+							"inline-flex shrink-0 items-center gap-1.5 whitespace-nowrap rounded-md border border-border text-muted-foreground transition-colors hover:bg-muted hover:text-foreground",
+							size === "sm" ? "px-1.5 py-0.5 text-[11px]" : "px-2 py-1 text-xs",
+						),
+			variant === "icon" && (size === "sm" ? "size-5" : "size-6"),
+			className,
+		)}
+	>
+		<Icon size={iconSize} />
+		{#if variant !== "icon"}
+			{text}
+			<!-- The one thing the mark can't say: this leaves the app. It stays muted
+				     so the eye lands on the tool name first. -->
+			<ArrowSquareOut size={iconSize} class="text-muted-foreground" />
+		{/if}
+	</a>
+</div>

package/src/components/picker/index.ts

@@ -0,0 +1,4 @@
+export { default as Picker } from "./picker.svelte";
+export { default as MarkPicker } from "./mark-picker.svelte";
+export { pickerTriggerClass } from "./trigger.js";
+export type { PickerGroup, PickerOption } from "./types.js";