@heyramzi/ui 0.0.0-stage → 1.53.0

package/src/components/segmented/index.ts

@@ -0,0 +1,41 @@
+/**
+ * The segmented control. Three components draw it, one per ARIA shape, and they
+ * share the track (`segmented.ts`) and segment body (`segment.svelte`).
+ */
+
+// WHY no low-level `Tabs.Root`/`List`/`Trigger` here: that's `shadcn/tabs`. This
+// is the data-driven layer on top, and `AnimatedTabs` is the way in.
+
+// Past `SEGMENT_MAX` objects the tail collapses into a menu: `collapse.ts`
+// decides, `segmented-overflow.svelte` draws it. No call site opts in.
+import AnimatedTabs, {
+  type TabDef,
+  type TabsPlacement,
+} from "./animated-tabs.svelte";
+import SegmentedFilter from "./segmented-filter.svelte";
+import SegmentedNav, {
+  type SegmentedNavItem,
+} from "./segmented-nav.svelte";
+import SectionRuns, {
+  type SectionRun,
+  type SectionStrip,
+} from "./section-runs.svelte";
+import { type SegmentContent } from "./segment.svelte";
+import { segmentedRowClass, type SegmentedVariant } from "./segmented.js";
+import { SEGMENT_MAX } from "./collapse.js";
+
+export {
+  AnimatedTabs,
+  SectionRuns,
+  SegmentedFilter,
+  SegmentedNav,
+  SEGMENT_MAX,
+  segmentedRowClass,
+  type SectionRun,
+  type SectionStrip,
+  type SegmentContent,
+  type SegmentedNavItem,
+  type SegmentedVariant,
+  type TabDef,
+  type TabsPlacement,
+};

package/src/components/segmented/section-runs.svelte

@@ -0,0 +1,79 @@
+<script lang="ts" module>
+	import type { SegmentedNavItem } from "./segmented-nav.svelte";
+
+	/** One bordered track on the section row. A run with a `label` is a reference
+	 *  set, not a step, so `SectionRuns` titles it and sends it right. */
+	export interface SectionRun {
+		label?: string;
+		items: readonly SegmentedNavItem[];
+		/** Overrides the strip's `current` for this run, so two nested runs each light one tab. */
+		current?: string;
+	}
+
+	// WHY runs: a section can hold a flow and the references it's read against.
+	// Each run gets its own track so they don't read as one sequence.
+	/** What an app shell publishes so a page's toolbar can draw the section strip. */
+	export interface SectionStrip {
+		runs: readonly SectionRun[];
+		current: string;
+		ariaLabel: string;
+	}
+</script>
+
+<script lang="ts">
+	// =========================
+	// IMPORTS
+	// =========================
+	import { cn } from "@heyramzi/utils";
+	import SegmentedNav from "./segmented-nav.svelte";
+
+	// =========================
+	// TYPES
+	// =========================
+	interface Props {
+		strip: SectionStrip;
+		/** The host row's own constraints: order, width, container queries. */
+		class?: string;
+	}
+
+	// =========================
+	// PROPS
+	// =========================
+	let { strip, class: className }: Props = $props();
+
+	// =========================
+	// DERIVED
+	// =========================
+
+	// The titled run takes the right edge, so a reference set reads apart from the steps.
+	let firstTitled = $derived(strip.runs.findIndex((run) => run.label));
+</script>
+
+<!-- =========================== -->
+<!-- MARKUP -->
+<!-- =========================== -->
+
+<!-- WHY it grows only with a titled run: `ml-auto` needs room to push into, and
+     a one-run strip keeps its width beside the search. -->
+<div
+	class={cn(
+		"no-scrollbar flex min-w-0 items-center gap-x-3 overflow-x-auto",
+		firstTitled >= 0 && "flex-1",
+		className,
+	)}
+>
+	{#each strip.runs as run, index (index)}
+		<div class={cn("flex shrink-0 items-center gap-2", index === firstTitled && "ml-auto")}>
+			{#if run.label}
+				<span class="text-[10px] font-medium tracking-wider text-muted-foreground uppercase">
+					{run.label}
+				</span>
+			{/if}
+			<SegmentedNav
+				items={run.items}
+				current={run.current ?? strip.current}
+				ariaLabel={run.label ?? strip.ariaLabel}
+			/>
+		</div>
+	{/each}
+</div>

package/src/components/segmented/segment.svelte

@@ -0,0 +1,106 @@
+<script lang="ts" module>
+import type { PhosphorIcon } from "../../lib/icon-types.js";
+
+/** Everything a segment may say, for every strip drawn from this folder. */
+
+// WHY one shape: the tab, nav and filter strips each grew an item type and
+// drifted, down to drawing a logo fallback two ways. Now it's one type, one renderer.
+export type SegmentContent = {
+	label: string;
+	/** A number after the label. `0` still renders; omit for "no number". */
+	count?: number;
+	icon?: PhosphorIcon;
+	/** A square mark drawn in place of an icon, for a brand that has one. */
+	image?: string;
+	/**
+	 * This segment's work is finished. Drawn as a dot after the label, and only
+	 * where there is no count, because a count already says the same thing.
+	 */
+	done?: boolean;
+	/**
+	 * A short note after the label, such as "Save 20%". Text where `count` is a
+	 * number, in the accent colour. Drawn before a count or a done dot.
+	 */
+	badge?: string;
+};
+</script>
+
+<script lang="ts">
+// =========================
+// IMPORTS
+// =========================
+import { cn } from "@heyramzi/utils";
+import { Icon } from "../icon/index.js";
+import { Mark } from "../mark/index.js";
+
+// =========================
+// TYPES
+// =========================
+type Props = SegmentContent & {
+	/**
+	 * `true`/`false` when the caller owns the state. `"auto"` when bits-ui owns it
+	 * in a `data-state` on the trigger, and the stylesheet answers.
+	 */
+	active?: boolean | "auto";
+};
+
+// =========================
+// PROPS
+// =========================
+let { label, count, icon, image, done = false, badge, active = false }: Props = $props();
+
+// =========================
+// DERIVED
+// =========================
+let auto = $derived(active === "auto");
+let on = $derived(active === true);
+</script>
+
+<!-- =========================== -->
+<!-- MARKUP -->
+<!-- =========================== -->
+{#if image}
+	<Mark
+		src={image}
+		{label}
+		class={cn(
+			"opacity-75 transition-opacity duration-[var(--duration-fast)] ease-[var(--ease-smooth-out)] group-hover/segment:opacity-100",
+			on && "opacity-100",
+			auto && "group-data-[state=active]/segment:opacity-100",
+		)}
+	/>
+{:else if icon}
+	<Icon {icon} size={16} class="shrink-0" />
+{/if}
+
+{label}
+
+{#if badge}
+	<span class="text-primary text-[10px] font-semibold tracking-wide whitespace-nowrap uppercase">{badge}</span>
+{/if}
+
+{#if count != null}
+	<span
+		class={cn(
+			// WHY 16px, not 18: inside a 22px segment, 18 read as a chip nested in the pill.
+
+			// WHY min-width equals height with 4px padding: `min-w-5 px-1.5` made a digit
+			// 20 by 18, so `rounded-full` drew an ellipse.
+			"inline-flex h-4 min-w-4 items-center justify-center rounded-full px-1 text-[10px] leading-none font-medium tabular-nums",
+			"bg-muted-foreground/15 text-muted-foreground",
+			on && "bg-brand-indigo/14 text-brand-indigo",
+			auto && "group-data-[state=active]/segment:bg-brand-indigo/14 group-data-[state=active]/segment:text-brand-indigo",
+		)}
+	>
+		{count}
+	</span>
+{:else if done}
+	<span
+		class={cn(
+			"size-1.5 shrink-0 rounded-full bg-muted-foreground/50",
+			on && "bg-brand-indigo",
+			auto && "group-data-[state=active]/segment:bg-brand-indigo",
+		)}
+		aria-hidden="true"
+	></span>
+{/if}

package/src/components/segmented/segmented-filter.svelte

@@ -0,0 +1,125 @@
+<script lang="ts" generics="T extends string">
+// =========================
+// IMPORTS
+// =========================
+import { cn } from "@heyramzi/utils";
+import Segment from "./segment.svelte";
+import type { TabDef } from "./animated-tabs.svelte";
+import SegmentedTrack from "./segmented-track.svelte";
+import SegmentedOverflow from "./segmented-overflow.svelte";
+import { SEGMENT_MAX, splitSegments } from "./collapse.js";
+import { segmentedTriggerClass } from "./segmented.js";
+
+// =========================
+// TYPES
+// =========================
+type Props = {
+	// WHY: picks which rows are listed, with no panel of its own. That's a
+	// segmented control, not a tab set.
+
+	// WHY not `AnimatedTabs`: a strip with no tabpanel is a `group` of `aria-pressed`
+	// toggles. "Tab 1 of 4" sends a screen reader looking for a panel.
+
+	// WHY `TabDef`: an option and a tab were the same five fields written twice.
+	options: readonly TabDef<T>[];
+	value: T;
+	// For a caller whose value is derived and can't be bound. Same contract as
+	// `AnimatedTabs`, so the two are picked by ARIA alone.
+	onValueChange?: (value: T) => void;
+	// Count per option, keyed by value. Merged over `options[].count`, because
+	// the counts usually arrive from the data while the labels are a constant.
+	counts?: Partial<Record<T, number>>;
+	ariaLabel: string;
+	/** Fill the row rather than sit at its natural width. On for the list-page
+	 *  filter strip, off for a segment sitting in a toolbar beside others. */
+	block?: boolean;
+	/** Objects the row may draw before its tail becomes a menu. See `collapse.ts`. */
+	max?: number;
+	/** What the menu segment says. Translate at the call site. */
+	moreLabel?: string;
+	class?: string;
+};
+
+// =========================
+// PROPS
+// =========================
+let {
+	options,
+	value = $bindable(),
+	onValueChange,
+	counts,
+	ariaLabel,
+	block = true,
+	max = SEGMENT_MAX,
+	moreLabel,
+	class: className,
+}: Props = $props();
+
+// =========================
+// DERIVED
+// =========================
+
+// Counts arrive from data, labels are constant. Merged once here, so the pill
+// and the overflow hint say the same thing.
+let merged = $derived(
+	options.map((option) => {
+		const count = counts?.[option.value] ?? option.count;
+		return count === option.count ? option : { ...option, count };
+	}),
+);
+let split = $derived(
+	splitSegments(
+		merged,
+		max,
+		merged.findIndex((option) => option.value === value),
+	),
+);
+
+function pick(next: T) {
+	value = next;
+	onValueChange?.(next);
+}
+</script>
+
+<!-- =========================== -->
+<!-- MARKUP -->
+<!-- =========================== -->
+<!-- WHY scroll, not wrap: it's one object. Past `max` the tail collapses into
+     a menu first, so scrolling is the last resort. -->
+<div
+	class={cn("no-scrollbar flex max-w-full min-w-0 overflow-x-auto", className)}
+	role="group"
+	aria-label={ariaLabel}
+>
+	<SegmentedTrack fill={block}>
+		{#each split.visible as option (option.value)}
+			{@const active = value === option.value}
+			<button
+				type="button"
+				class={segmentedTriggerClass({ fill: block, active })}
+				onclick={() => pick(option.value)}
+				aria-pressed={active}
+			>
+				<Segment
+					label={option.label}
+					count={option.count}
+					icon={option.icon}
+					image={option.image}
+					done={option.done}
+					badge={option.badge}
+					{active}
+				/>
+			</button>
+		{/each}
+		{#snippet after()}
+			{#if split.hidden.length > 0}
+				<SegmentedOverflow
+					items={split.hidden}
+					onSelect={pick}
+					label={moreLabel}
+					fill={block}
+				/>
+			{/if}
+		{/snippet}
+	</SegmentedTrack>
+</div>

package/src/components/segmented/segmented-nav.svelte

@@ -0,0 +1,82 @@
+<script lang="ts" module>
+import type { SegmentContent } from "./segment.svelte";
+
+/** One destination. See `SegmentContent` for everything a segment can say. */
+export type SegmentedNavItem = SegmentContent & { href: string };
+</script>
+
+<script lang="ts">
+// =========================
+// IMPORTS
+// =========================
+import { cn } from "@heyramzi/utils";
+import Segment from "./segment.svelte";
+import SegmentedTrack from "./segmented-track.svelte";
+import { segmentedTriggerClass } from "./segmented.js";
+
+// =========================
+// TYPES
+// =========================
+type Props = {
+	// WHY a third component: tabs are a `tablist`, filters a `group` of toggles,
+	// and this goes to sibling pages, so it's a `nav` of links with `aria-current`.
+
+	// Links give middle-click, bookmarks and the back button. The look comes from
+	// `segmented.ts` and `segment.svelte`, so nothing here can drift.
+	items: readonly SegmentedNavItem[];
+	/** The href that is current. Compared after trailing slashes are dropped. */
+	current: string;
+	ariaLabel: string;
+	/** Fill the row rather than sit at its natural width. */
+	block?: boolean;
+	class?: string;
+};
+
+// =========================
+// PROPS
+// =========================
+let {
+	items,
+	current,
+	ariaLabel,
+	block = false,
+	class: className,
+}: Props = $props();
+
+// =========================
+// DERIVED
+// =========================
+let currentHref = $derived(current.replace(/\/$/, ""));
+</script>
+
+<!-- =========================== -->
+<!-- MARKUP -->
+<!-- =========================== -->
+<!-- WHY scroll, not wrap: seven brands outrun a laptop pane. A clipped segment
+     must read as "more to the right", never as a broken row. -->
+<nav
+	class={cn("no-scrollbar flex max-w-full min-w-0 overflow-x-auto", className)}
+	aria-label={ariaLabel}
+>
+	<SegmentedTrack fill={block}>
+		{#each items as item (item.href)}
+			{@const active = item.href.replace(/\/$/, "") === currentHref}
+			<a
+				href={item.href}
+				aria-current={active ? "page" : undefined}
+				title={item.label}
+				class={segmentedTriggerClass({ fill: block, active })}
+			>
+				<Segment
+					label={item.label}
+					count={item.count}
+					icon={item.icon}
+					image={item.image}
+					done={item.done}
+					badge={item.badge}
+					{active}
+				/>
+			</a>
+		{/each}
+	</SegmentedTrack>
+</nav>

package/src/components/segmented/segmented-overflow.svelte

@@ -0,0 +1,85 @@
+<script lang="ts" generics="V extends string">
+// =========================
+// IMPORTS
+// =========================
+import { CaretDown } from "phosphor-svelte";
+import { Picker } from "../picker/index.js";
+import { cn } from "@heyramzi/utils";
+import { segmentedTriggerClass, type SegmentedVariant } from "./segmented.js";
+import type { SegmentContent } from "./segment.svelte";
+
+// =========================
+// TYPES
+// =========================
+/** The last object in an overfull strip: one segment that opens the rest. */
+
+// WHY the `Picker`: every "pick one of these" goes there, so keys and
+// filtering match the command palette.
+
+// WHY never active: `splitSegments` pulls the current item into a visible slot,
+// so this never fights bits-ui's `data-state="open"`.
+type Props = {
+	items: readonly (SegmentContent & { value: V })[];
+	onSelect: (value: V) => void;
+	/** What the segment says. Translate at the call site. */
+	label?: string;
+	fill?: boolean;
+	variant?: SegmentedVariant;
+	searchPlaceholder?: string;
+	emptyLabel?: string;
+};
+
+// =========================
+// PROPS
+// =========================
+let {
+	items,
+	onSelect,
+	label = "More",
+	fill = false,
+	variant = "pill",
+	searchPlaceholder,
+	emptyLabel,
+}: Props = $props();
+
+// =========================
+// DERIVED
+// =========================
+
+// A count rides as the row's hint, where the strip draws it as a pill.
+let options = $derived(
+	items.map((item) => ({
+		value: item.value,
+		label: item.label,
+		hint: item.count != null ? String(item.count) : undefined,
+		icon: item.icon,
+	})),
+);
+</script>
+
+<!-- =========================== -->
+<!-- MARKUP -->
+<!-- =========================== -->
+<Picker
+	{options}
+	value={null}
+	onSelect={(value) => onSelect(value)}
+	triggerClass={cn(
+		segmentedTriggerClass({ variant, fill }),
+		"data-[state=open]:bg-foreground/5 data-[state=open]:text-foreground",
+	)}
+	triggerLabel={label}
+	align="end"
+	{searchPlaceholder}
+	{emptyLabel}
+>
+	{#snippet trigger()}
+		{label}
+		<CaretDown
+			class={cn(
+				"shrink-0 transition-transform duration-150 group-data-[state=open]/segment:rotate-180",
+				"size-3.5",
+			)}
+		/>
+	{/snippet}
+</Picker>

package/src/components/segmented/segmented-track.svelte

@@ -0,0 +1,181 @@
+<script lang="ts">
+// =========================
+// IMPORTS
+// =========================
+import type { Snippet } from "svelte";
+import { cn } from "@heyramzi/utils";
+import { segmentedTrackClass, type SegmentedVariant } from "./segmented.js";
+import { slidingPill } from "../../lib/sliding-pill.js";
+
+// =========================
+// TYPES
+// =========================
+type Props = {
+	/** Fill the row rather than sit at its natural width. */
+	fill?: boolean;
+	/** `pill`, a bordered well with a travelling highlight, or `underline`, a travelling rule. */
+	variant?: SegmentedVariant;
+	class?: string;
+	children: Snippet;
+	/**
+	 * A last segment that isn't an item: today the overflow trigger. It's inside
+	 * the track but outside the ARIA container, so a `tablist` owns only tabs.
+	 */
+	after?: Snippet;
+	// What the ARIA shapes differ by: `role`/`aria-label` for the filter, nothing
+	// for the nav (its <nav> has it), bits-ui's wiring for tabs.
+	[key: string]: unknown;
+};
+
+// =========================
+// PROPS
+// =========================
+let {
+	fill = false,
+	variant = "pill",
+	class: className,
+	children,
+	after,
+	...rest
+}: Props = $props();
+</script>
+
+<!-- =========================== -->
+<!-- MARKUP -->
+<!-- =========================== -->
+<!-- WHY its own component: the active segment is a travelling pill, and the
+     pill needs one element inside the track that no caller can forget. -->
+<div
+	{...rest}
+	data-variant={variant}
+	class={cn("track relative", segmentedTrackClass({ variant, fill }), className)}
+>
+	<!-- Renders at zero width until the attachment measures, so a server-rendered
+	     strip shows the segment's own background and never an empty pill. -->
+	<span class="pill" aria-hidden="true" {@attach slidingPill}></span>
+	{@render children()}
+	{@render after?.()}
+</div>
+
+<!-- =========================== -->
+<!-- STYLES -->
+<!-- =========================== -->
+<style>
+	/* Inset separators keep the strip one bordered object. */
+	.track :global(.ui-segment)::before {
+		content: "";
+		position: absolute;
+		top: 22%;
+		bottom: 22%;
+		left: 0;
+		width: 1px;
+		background-color: var(--color-border);
+		transition: opacity var(--duration-fast) var(--ease-smooth-out);
+		pointer-events: none;
+	}
+
+	.track :global(.pill + .ui-segment)::before,
+	.track :global([data-slot="tabs-list"] > .ui-segment:first-child)::before {
+		display: none;
+	}
+
+	/* The highlight and hover wash hide the seams on either side. */
+	.track :global(.ui-segment[data-state="active"])::before,
+	.track :global(.ui-segment[aria-current="page"])::before,
+	.track :global(.ui-segment[aria-pressed="true"])::before,
+	.track :global(.ui-segment[data-state="active"] + .ui-segment)::before,
+	.track :global(.ui-segment[aria-current="page"] + .ui-segment)::before,
+	.track :global(.ui-segment[aria-pressed="true"] + .ui-segment)::before,
+	.track :global([data-slot="tabs-list"]:has(> .ui-segment:last-child[data-state="active"]) + .ui-segment)::before,
+	.track :global(.ui-segment:hover)::before,
+	.track :global(.ui-segment:hover + .ui-segment)::before {
+		opacity: 0;
+	}
+
+	/* The label's colour lands with the pill, on the same fast step. */
+	.track :global(.ui-segment) {
+		transition:
+			background-color var(--duration-quick) var(--ease-smooth-out),
+			color var(--duration-fast) var(--ease-smooth-out),
+			transform var(--duration-micro) var(--ease-smooth-out);
+	}
+
+	/* A faint wash in the well says which segment the pointer would pick. */
+	@media (hover: hover) {
+		.track
+			:global(
+				.ui-segment:hover:not([data-state="active"], [aria-current="page"], [aria-pressed="true"], [data-state="open"])
+			) {
+			background-color: color-mix(in oklch, var(--color-muted) 55%, transparent);
+		}
+	}
+
+	.pill {
+		position: absolute;
+		top: 2px;
+		bottom: 2px;
+		left: 0;
+		z-index: 0;
+		width: 0;
+		opacity: 0;
+		/* Concentric with the border and the 2px inset. */
+		border-radius: calc(var(--radius-lg) - 3px);
+		background-color: var(--color-muted);
+		box-shadow: inset 0 0 0 1px color-mix(in oklch, var(--color-foreground) 6%, transparent);
+		transform: translateX(0);
+		/* transitions-dev `16-tabs-sliding`: the fast step, 250ms. */
+		transition:
+			transform var(--duration-fast) var(--ease-smooth-out),
+			width var(--duration-fast) var(--ease-smooth-out),
+			opacity var(--duration-quick) var(--ease-smooth-out);
+		will-change: transform, width;
+		pointer-events: none;
+	}
+
+	/* Before the attachment measures, the active segment draws the pill itself,
+	   so a server-rendered strip is right before any JS arrives. */
+	.track:not([data-pill="on"]) :global(:is([data-state="active"], [aria-current="page"], [aria-pressed="true"])) {
+		background-color: var(--color-muted);
+		box-shadow: inset 0 0 0 1px color-mix(in oklch, var(--color-foreground) 6%, transparent);
+	}
+
+	/* The underline: no seams, no wash, and the pill becomes a 2px rule on the
+	   hairline. `--segmented-rule` lets a brand colour it from a class. */
+	.track[data-variant="underline"] :global(.ui-segment)::before {
+		display: none;
+	}
+
+	@media (hover: hover) {
+		.track[data-variant="underline"]
+			:global(
+				.ui-segment:hover:not([data-state="active"], [aria-current="page"], [aria-pressed="true"], [data-state="open"])
+			) {
+			background-color: transparent;
+		}
+	}
+
+	.track[data-variant="underline"] .pill {
+		top: auto;
+		bottom: -1px;
+		height: 2px;
+		border-radius: 1px;
+		background-color: var(--segmented-rule, var(--color-foreground));
+		box-shadow: none;
+	}
+
+	.track[data-variant="underline"]:not([data-pill="on"])
+		:global(:is([data-state="active"], [aria-current="page"], [aria-pressed="true"])) {
+		background-color: transparent;
+		box-shadow: inset 0 -2px 0 var(--segmented-rule, var(--color-foreground));
+	}
+
+	@media (prefers-reduced-motion: reduce) {
+		.pill {
+			transition: opacity var(--duration-quick) var(--ease-smooth-out);
+		}
+
+		.track :global(.ui-segment) {
+			transition: none;
+		}
+	}
+</style>