@heyramzi/ui 7.0.0 → 8.1.0

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>

package/src/components/segmented/segmented.test.ts

@@ -0,0 +1,20 @@
+import { describe, expect, it } from "vite-plus/test";
+import { segmentedTrackClass } from "./segmented.js";
+
+describe("segmentedTrackClass", () => {
+  // Every segmented control shares one height, whatever its look.
+  it("holds one height across variants", () => {
+    for (const variant of ["pill", "underline"] as const) {
+      const classes = segmentedTrackClass({ variant }).split(" ");
+      expect(classes).toContain("h-7");
+      expect(classes).toContain("any-pointer-coarse:h-10");
+    }
+  });
+
+  it("draws the pill as a bordered well and the underline as a hairline", () => {
+    expect(segmentedTrackClass({ variant: "pill" })).toContain("rounded-lg");
+    const underline = segmentedTrackClass({ variant: "underline" });
+    expect(underline).toContain("border-b");
+    expect(underline).not.toContain("rounded-lg");
+  });
+});

package/src/components/segmented/segmented.ts

@@ -0,0 +1,80 @@
+import { tv } from "tailwind-variants";
+import { pageGutterClass } from "../../lib/layout.js";
+
+/**
+ * The one look for a segmented control: the track and trigger here, what a
+ * segment says in `segment.svelte`.
+ */
+
+// WHY a recipe, not one component: tabs are a `tablist`, filters a `group` of
+// `aria-pressed` toggles, page links a `nav`. Only the ARIA shape may differ.
+
+// The look used to drift three ways, one with an at-rest shadow. All three read from here now.
+export const segmentedTrackClass = tv({
+  // WHY the height lives on the track: it carries the inset, so an `h-7` trigger
+  // drew 30px beside a 28px button. One toolbar row came out at five heights.
+
+  // WHY no size variant: `sm` drew 24px, and every tab control must share one height.
+  base: "h-7 any-pointer-coarse:h-10 shrink-0 items-stretch",
+  variants: {
+    // `pill`: a bordered well with a travelling highlight. `underline`: bare
+    // labels over one hairline, the active one marked by a rule that travels.
+    variant: {
+      pill: "overflow-hidden rounded-lg border border-border p-0.5",
+      underline: "gap-5 border-b border-border",
+    },
+    // Fill the row rather than sit at its natural width. For a narrow rail.
+    fill: { true: "flex w-full", false: "inline-flex w-fit" },
+  },
+  defaultVariants: { variant: "pill", fill: false },
+});
+
+export type SegmentedVariant = "pill" | "underline";
+
+export const segmentedTriggerClass = tv({
+  base: [
+    // `t-press` is the kit's one press: colour, shadow and a pixel of travel.
+
+    // `relative z-[1]` keeps the label above the travelling pill, or the pill
+    // paints over the word it highlights.
+
+    // `ui-segment` isn't a style. `segmented-track.svelte` matches on it to time
+    // the label colour with the pill.
+    "ui-segment group/segment t-press relative z-[1] inline-flex items-center justify-center gap-1.5 whitespace-nowrap font-medium select-none",
+    "text-muted-foreground hover:text-foreground",
+    "disabled:pointer-events-none disabled:opacity-50",
+    "[&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
+    // WHY an inset focus ring: the track clips to its rounded corners, so an
+    // outside ring was cut in half on the end segments.
+    "focus-visible:ring-ring focus-visible:ring-2 focus-visible:ring-inset focus-visible:outline-none",
+    // WHY no height on the trigger: an icon makes a segment taller than a word.
+    // `h-full` against the track's `items-stretch` keeps every segment the same box.
+    "h-full text-xs",
+  ],
+  variants: {
+    // The pill is concentric with the track's border and its 2px inset. The
+    // underline has no well to be concentric with, so no padding either: the
+    // rule under a label is as wide as the label.
+    variant: {
+      pill: "rounded-[calc(var(--radius-lg)-3px)] px-2.5 any-pointer-coarse:px-3.5",
+      underline: "rounded-sm px-0",
+    },
+    // WHY `min-w-fit flex-auto`, not equal fractions: fractions cut "Approved" to
+    // "Appro…" in a 280px rail. Each segment claims its label and shares the slack.
+    fill: { true: "min-w-fit flex-auto", false: "" },
+    active: { true: "text-foreground", false: "" },
+  },
+  defaultVariants: { variant: "pill", fill: false, active: false },
+});
+
+/**
+ * The row a segmented strip sits in, and the one recipe for a navigation row
+ * under the app header. Written per caller it produced two different left
+ * edges.
+ */
+// WHY no bottom hairline: with a section strip and a page toolbar stacked it
+// drew two rules for one boundary. The gap is the boundary.
+export const segmentedRowClass = `flex shrink-0 flex-wrap items-center gap-x-4 gap-y-2 py-2 ${pageGutterClass}`;
+
+/** The active style, for a strip whose state lives in a `data-active` attribute. */
+export const segmentedActiveClass = "data-active:text-foreground";

package/src/components/star-rating-input/index.ts

@@ -0,0 +1,9 @@
+import Root from "./star-rating-input.svelte";
+
+export type { StarRatingSize } from "./star-rating-input.svelte";
+
+export {
+  Root,
+  //
+  Root as StarRatingInput,
+};