@heyramzi/ui 0.0.0-stage → 6.1.0

package/src/showcase/ShowcaseImport.svelte

@@ -0,0 +1,126 @@
+<script lang="ts" module>
+	export interface ShowcaseImportProps {
+		/** The line a consumer pastes, e.g. `@heyramzi/ui/shadcn/button`. */
+		path: string;
+		/** Accessible name suffix, so two rows on a page do not both read "Copy import". */
+		label?: string;
+		class?: string;
+	}
+</script>
+
+<script lang="ts">
+	import { cn } from "@heyramzi/utils";
+	import checkIcon from "./check.svg?raw";
+	import copyIcon from "./copy.svg?raw";
+
+	let { path, label, class: className }: ShowcaseImportProps = $props();
+
+	let copied = $state(false);
+	let timer: ReturnType<typeof setTimeout> | undefined;
+
+	async function copy() {
+		try {
+			await navigator.clipboard.writeText(path);
+		} catch {
+			// A denied clipboard is not worth an error state on a dev-only surface;
+			// the path is on screen and selectable either way.
+			return;
+		}
+		copied = true;
+		clearTimeout(timer);
+		timer = setTimeout(() => (copied = false), 1600);
+	}
+</script>
+
+<button
+	type="button"
+	class={cn("sc-import", className)}
+	data-copied={copied ? "true" : undefined}
+	onclick={copy}
+	aria-label="Copy import for {label ?? path}"
+>
+	<code>{path}</code>
+	<span class="sc-import-state" aria-hidden="true">
+		{#if copied}
+			{@html checkIcon}
+		{:else}
+			{@html copyIcon}
+		{/if}
+	</span>
+</button>
+
+<style>
+	.sc-import {
+		display: flex;
+		align-items: center;
+		justify-content: space-between;
+		gap: 0.75rem;
+		width: 100%;
+		min-width: 0;
+		padding: 0.375rem 0.5rem 0.375rem 0.625rem;
+		border: 1px solid transparent;
+		border-radius: 0.5rem;
+		background: transparent;
+		color: var(--color-muted-foreground, var(--muted-foreground));
+		cursor: pointer;
+		text-align: start;
+		transition:
+			color 160ms ease,
+			background-color 160ms ease,
+			border-color 160ms ease;
+	}
+
+	.sc-import:hover {
+		color: var(--color-foreground, var(--foreground));
+		background: color-mix(in oklab, var(--color-muted, var(--muted)) 70%, transparent);
+	}
+
+	.sc-import:focus-visible {
+		outline: 2px solid var(--color-ring, var(--ring));
+		outline-offset: 2px;
+	}
+
+	.sc-import[data-copied] {
+		color: var(--color-foreground, var(--foreground));
+		border-color: color-mix(in oklab, var(--color-ring, var(--ring)) 45%, transparent);
+	}
+
+	.sc-import code {
+		font-family: var(--font-mono, ui-monospace, "SF Mono", "JetBrains Mono", monospace);
+		font-size: 0.6875rem;
+		letter-spacing: -0.01em;
+		overflow: hidden;
+		text-overflow: ellipsis;
+		white-space: nowrap;
+	}
+
+	.sc-import-state {
+		display: grid;
+		place-items: center;
+		flex-shrink: 0;
+		width: 0.875rem;
+		height: 0.875rem;
+	}
+
+	.sc-import-state :global(svg) {
+		width: 100%;
+		height: 100%;
+		animation: sc-icon-in 200ms cubic-bezier(0.22, 1, 0.36, 1);
+	}
+
+	@keyframes sc-icon-in {
+		from {
+			opacity: 0;
+			transform: scale(0.6);
+		}
+	}
+
+	@media (prefers-reduced-motion: reduce) {
+		.sc-import {
+			transition: none;
+		}
+		.sc-import-state :global(svg) {
+			animation: none;
+		}
+	}
+</style>

package/src/showcase/ShowcaseList.svelte

@@ -0,0 +1,132 @@
+<script lang="ts" module>
+	export interface ShowcaseListItem {
+		/** Component name, e.g. "Context Menu". */
+		title: string;
+		/** Import line for the copy control. */
+		importPath: string;
+		/** Right-hand detail: a file count, a parts count, a source path. */
+		meta?: string;
+		/** Provenance beside the name, e.g. "shadcn" on a primitive the kit took as is. */
+		tag?: string;
+	}
+
+	export interface ShowcaseListProps {
+		items: ShowcaseListItem[];
+		/** Heading above the rows. Omit inside a section that is list-only. */
+		caption?: string;
+	}
+</script>
+
+<script lang="ts">
+	import ShowcaseImport from "./ShowcaseImport.svelte";
+	import "./showcase-shell.css";
+
+	let { items, caption }: ShowcaseListProps = $props();
+</script>
+
+<!-- WHY a row and not a stage: a component with no demo has one useful fact, its
+     import line. Given a card each, the undemoed majority buries the demos. -->
+<div class="sc-list">
+	{#if caption}
+		<p class="sc-list-caption">{caption}</p>
+	{/if}
+	<ul>
+		{#each items as item (item.importPath)}
+			<li>
+				<span class="sc-list-title">
+					{item.title}
+					{#if item.tag}
+						<span class="sc-tag">{item.tag}</span>
+					{/if}
+				</span>
+				<ShowcaseImport path={item.importPath} label={item.title} class="sc-list-import" />
+				{#if item.meta}
+					<span class="sc-list-meta">{item.meta}</span>
+				{/if}
+			</li>
+		{/each}
+	</ul>
+</div>
+
+<style>
+	.sc-list {
+		display: flex;
+		flex-direction: column;
+		gap: 0.625rem;
+	}
+
+	.sc-list-caption {
+		margin: 0;
+		font-size: 0.6875rem;
+		font-weight: 500;
+		letter-spacing: 0.06em;
+		text-transform: uppercase;
+		color: var(--color-muted-foreground, var(--muted-foreground));
+	}
+
+	.sc-list ul {
+		list-style: none;
+		margin: 0;
+		padding: 0;
+		border: 1px solid var(--color-border, var(--border));
+		border-radius: calc(var(--radius, 0.625rem) + 0.375rem);
+		background: var(--color-card, var(--card));
+		overflow: hidden;
+	}
+
+	.sc-list li {
+		position: relative;
+		display: grid;
+		grid-template-columns: minmax(7rem, 12rem) minmax(0, 1fr) auto;
+		align-items: center;
+		gap: 0.75rem;
+		padding: 0.1875rem 0.75rem 0.1875rem 1rem;
+		min-height: 2.5rem;
+	}
+
+	/* Inset to the title column, so a scan down the names is not cut by a full-bleed
+   rule on every row. */
+	.sc-list li + li::before {
+		content: "";
+		position: absolute;
+		inset-block-start: 0;
+		inset-inline: 1rem 0;
+		height: 1px;
+		background: var(--color-border, var(--border));
+	}
+
+	.sc-list-title {
+		font-size: 0.8125rem;
+		font-weight: 500;
+		color: var(--color-card-foreground, var(--color-foreground, var(--foreground)));
+		overflow: hidden;
+		text-overflow: ellipsis;
+		white-space: nowrap;
+	}
+
+	.sc-list-meta {
+		font-size: 0.6875rem;
+		font-variant-numeric: tabular-nums;
+		color: var(--color-muted-foreground, var(--muted-foreground));
+		white-space: nowrap;
+	}
+
+	@media (max-width: 40rem) {
+		.sc-list li {
+			grid-template-columns: minmax(0, 1fr) auto;
+			grid-template-areas:
+				"title meta"
+				"import import";
+			padding-block: 0.5rem;
+		}
+		.sc-list-title {
+			grid-area: title;
+		}
+		.sc-list-meta {
+			grid-area: meta;
+		}
+		.sc-list :global(.sc-list-import) {
+			grid-area: import;
+		}
+	}
+</style>

package/src/showcase/ShowcaseNav.svelte

@@ -0,0 +1,247 @@
+<script lang="ts" module>
+	import type { ShowcaseSectionMeta } from "./types.js";
+
+	export interface ShowcaseNavProps {
+		sections: ShowcaseSectionMeta[];
+	}
+</script>
+
+<script lang="ts">
+	import { onMount } from "svelte";
+
+	let { sections }: ShowcaseNavProps = $props();
+
+	let active = $state(sections[0]?.id ?? "");
+	// Nothing is written back until the reader's place has been restored, or the
+	// observer's first call would overwrite it with whatever the top of the page is.
+	let restored = $state(false);
+
+	const storeKey = () => `sc-rail-active:${location.pathname}`;
+
+	// Consecutive sections sharing a group are drawn under one heading.
+
+	// Grouping by run rather than by key means the page's own order is the rail's order, and a section can be moved without also moving it in a second list.
+	const runs = $derived(
+		sections.reduce<{ group?: string; items: ShowcaseSectionMeta[] }[]>((acc, section) => {
+			const last = acc.at(-1);
+			if (last && last.group === section.group) last.items.push(section);
+			else acc.push({ group: section.group, items: [section] });
+			return acc;
+		}, []),
+	);
+
+	// The rail follows the reader rather than the last click: an anchor jump and a
+	// scroll both end in the same place, so only one source of truth is needed.
+	$effect(() => {
+		const targets = sections
+			.map((section) => document.getElementById(section.id))
+			.filter((element): element is HTMLElement => element !== null);
+		if (targets.length === 0) return;
+
+		const observer = new IntersectionObserver(
+			(entries) => {
+				const visible = entries
+					.filter((entry) => entry.isIntersecting)
+					.toSorted((a, b) => a.boundingClientRect.top - b.boundingClientRect.top);
+				if (visible[0]) active = visible[0].target.id;
+			},
+			{ rootMargin: "-12% 0px -75% 0px", threshold: 0 },
+		);
+		for (const target of targets) observer.observe(target);
+		return () => observer.disconnect();
+	});
+
+	// The band the observer watches sits near the top of the viewport, and the last section is often too short to reach it,
+
+	// so the rail stopped one entry early at the foot of the page. The bottom of the scroll names the last section.
+	$effect(() => {
+		const onScroll = () => {
+			const last = sections.at(-1)?.id;
+			if (last && window.innerHeight + window.scrollY >= document.body.scrollHeight - 2) {
+				active = last;
+			}
+		};
+		window.addEventListener("scroll", onScroll, { passive: true });
+		return () => window.removeEventListener("scroll", onScroll);
+	});
+
+	// A reload put the reader back at the top.
+
+	// The browser does restore a scroll offset, but the charts, images and fonts on this page settle after it, so the offset it restores is no longer the section it
+
+	// was taken from. The section id survives instead: the hash when the reader followed one, the last section read otherwise.
+	onMount(() => {
+		let wanted = decodeURIComponent(location.hash.slice(1));
+		if (!wanted) {
+			try {
+				wanted = sessionStorage.getItem(storeKey()) ?? "";
+			} catch {
+				wanted = "";
+			}
+		}
+		if (!wanted || !sections.some((section) => section.id === wanted)) {
+			restored = true;
+			return;
+		}
+
+		active = wanted;
+		// Two frames: the first paints the sections, the second lets what is inside
+		// them take its height, so the anchor lands on the heading and not above it.
+		requestAnimationFrame(() =>
+			requestAnimationFrame(() => {
+				document.getElementById(wanted)?.scrollIntoView({ block: "start" });
+				restored = true;
+			}),
+		);
+	});
+
+	$effect(() => {
+		if (!restored || !active) return;
+		try {
+			sessionStorage.setItem(storeKey(), active);
+		} catch {
+			// A private window refuses the write. The rail still follows the reader.
+		}
+	});
+</script>
+
+<nav aria-label="Component sections">
+	{#each runs as run, index (run.group ?? index)}
+		{#if run.group}
+			<p class="sc-rail-group">{run.group}</p>
+		{/if}
+		<ul>
+			{#each run.items as section (section.id)}
+				<li>
+					<a
+						href="#{section.id}"
+						data-active={active === section.id ? "true" : undefined}
+						aria-current={active === section.id ? "page" : undefined}
+					>
+						<span class="sc-rail-label">{section.label}</span>
+						<span class="sc-rail-count">{section.demos || section.listed}</span>
+					</a>
+				</li>
+			{/each}
+		</ul>
+	{/each}
+</nav>
+
+<style>
+	/*
+	 * WHY a rail and not a row of pills: the row was one line of chips that ran to
+	 */
+
+	/*
+	 * nine sections and wrapped, so the reader's place in a long page was a chip somewhere in a block of chips. A vertical list holds a stable order, has room
+	 */
+
+	/*
+	 * for group headings, and leaves the whole content column to the components.
+	 */
+	nav {
+		position: sticky;
+		top: var(--showcase-nav-top, 0px);
+		display: flex;
+		flex-direction: column;
+		gap: 0.125rem;
+		max-height: calc(100dvh - var(--showcase-nav-top, 0px));
+		padding: 1.25rem 0.75rem 2rem 0.4375rem;
+		overflow-y: auto;
+		/* WHY only x: `contain` on y stopped this zero-overflow rail chaining the wheel to the page. */
+		overscroll-behavior-x: contain;
+		scrollbar-width: thin;
+	}
+
+	.sc-rail-group {
+		margin: 1.125rem 0 0.375rem 0.5rem;
+		font-size: 0.625rem;
+		font-weight: 600;
+		letter-spacing: 0.08em;
+		text-transform: uppercase;
+		color: var(--color-muted-foreground, var(--muted-foreground));
+		opacity: 0.75;
+	}
+
+	.sc-rail-group:first-child {
+		margin-top: 0;
+	}
+
+	ul {
+		display: flex;
+		flex-direction: column;
+		gap: 0.0625rem;
+		margin: 0;
+		padding: 0;
+		list-style: none;
+	}
+
+	a {
+		position: relative;
+		display: flex;
+		align-items: center;
+		justify-content: space-between;
+		gap: 0.5rem;
+		padding: 0.3125rem 0.5rem 0.3125rem 0.6875rem;
+		border-radius: var(--radius-lg, 8px);
+		font-size: 0.78125rem;
+		line-height: 1.35;
+		color: var(--color-muted-foreground, var(--muted-foreground));
+		text-decoration: none;
+		transition:
+			color var(--duration-quick, 150ms) var(--ease-smooth-out, ease),
+			background-color var(--duration-quick, 150ms) var(--ease-smooth-out, ease);
+	}
+
+	a:hover {
+		color: var(--color-foreground, var(--foreground));
+		background: color-mix(in oklab, var(--color-muted, var(--muted)) 60%, transparent);
+	}
+
+	/*
+	 * The active row is a filled slot with a bar in the gutter. The bar is what the
+	 */
+
+	/*
+	 * eye finds when it comes back to the rail after reading. A fill alone is too
+	 */
+
+	/*
+	 * quiet at this weight, and a full-strength pill is too loud for a list this long.
+	 */
+	a[data-active] {
+		color: var(--color-foreground, var(--foreground));
+		font-weight: 500;
+		background: color-mix(in oklab, var(--color-muted, var(--muted)) 90%, transparent);
+	}
+
+	a[data-active]::before {
+		content: "";
+		position: absolute;
+		inset-block: 0.3125rem;
+		inset-inline-start: -0.375rem;
+		width: 2px;
+		border-radius: 999px;
+		background: var(--color-ring, var(--ring));
+	}
+
+	.sc-rail-label {
+		overflow: hidden;
+		text-overflow: ellipsis;
+		white-space: nowrap;
+	}
+
+	.sc-rail-count {
+		flex-shrink: 0;
+		font-size: 0.625rem;
+		font-variant-numeric: tabular-nums;
+		color: var(--color-muted-foreground, var(--muted-foreground));
+		opacity: 0.7;
+	}
+
+	@media (prefers-reduced-motion: reduce) {
+		a {
+			transition: none;
+		}
+	}
+</style>

package/src/showcase/ShowcaseSection.svelte

@@ -0,0 +1,112 @@
+<script lang="ts" module>
+	import type { Snippet } from "svelte";
+
+	export interface ShowcaseSectionProps {
+		/** Anchor id. Must match the ShowcaseSectionMeta the nav rail was given. */
+		id: string;
+		label: string;
+		/** What the section is for, in the reader's terms, not a list of its members. */
+		lead?: string;
+		/** Live demos. Stacked one per row unless `bare` is set. */
+		children?: Snippet;
+		/** Skip the stack, for content that brings a layout of its own. */
+		bare?: boolean;
+		/** Everything in the section with no demo, drawn as rows under the stack. */
+		listed?: Snippet;
+	}
+</script>
+
+<script lang="ts">
+	let { id, label, lead, children, listed, bare = false }: ShowcaseSectionProps = $props();
+</script>
+
+<section {id}>
+	<div class="sc-section-head">
+		<h2>{label}</h2>
+		{#if lead}
+			<p>{lead}</p>
+		{/if}
+	</div>
+
+	{#if children}
+		{#if bare}
+			{@render children()}
+		{:else}
+			<div class="sc-stack">
+				{@render children()}
+			</div>
+		{/if}
+	{/if}
+
+	{#if listed}
+		<div class="sc-section-listed">
+			{@render listed()}
+		</div>
+	{/if}
+</section>
+
+<style>
+	section {
+		display: flex;
+		flex-direction: column;
+		/* Clears the sticky controls row, whose height the page declares once. */
+		scroll-margin-top: calc(var(--showcase-nav-top, 0px) + 4.5rem);
+	}
+
+	/*
+	 * WHY the heading sits on its own rule rather than on whitespace: the page is
+	 */
+
+	/*
+	 * one long column of stages now, and a gap alone did not read as a boundary once the stages themselves had air inside them.
+	 */
+	.sc-section-head {
+		display: flex;
+		flex-direction: column;
+		gap: 0.3125rem;
+		margin-top: 2.25rem;
+		padding: 2.25rem 0 1.25rem;
+		border-top: 1px solid var(--color-border, var(--border));
+	}
+
+	section:first-child .sc-section-head {
+		margin-top: 0;
+		padding-top: 1.5rem;
+		border-top: 0;
+	}
+
+	h2 {
+		margin: 0;
+		font-size: 1.125rem;
+		font-weight: 600;
+		line-height: 1.2;
+		letter-spacing: -0.014em;
+		color: var(--color-foreground, var(--foreground));
+	}
+
+	p {
+		margin: 0;
+		max-width: 62ch;
+		font-size: 0.8125rem;
+		line-height: 1.55;
+		color: var(--color-muted-foreground, var(--muted-foreground));
+		text-wrap: pretty;
+	}
+
+	/*
+	 * One stage per row. A grid of narrow cards made every component the size of the smallest one on the page, which is the opposite of what a showcase is
+	 */
+
+	/*
+	 * for: a table and a button both got 20rem, and only one of them survived it.
+	 */
+	.sc-stack {
+		display: flex;
+		flex-direction: column;
+		gap: 0;
+	}
+
+	.sc-section-listed {
+		padding-top: 1rem;
+	}
+</style>

package/src/showcase/ShowcaseShell.svelte

@@ -0,0 +1,55 @@
+<script lang="ts" module>
+	import type { Snippet } from "svelte";
+	import type { ShowcaseSectionMeta } from "./types.js";
+
+	export interface ShowcaseShellProps {
+		/** Every section the rail lists, in the order the page renders them. */
+		sections: ShowcaseSectionMeta[];
+		/** Search box, filters, anything that acts on the whole page. Spans both columns. */
+		controls?: Snippet;
+		/** Sits at the top of the rail, above the index. A title, a count, a legend. */
+		railHead?: Snippet;
+		/** The sections themselves. */
+		children: Snippet;
+		/** Rendered instead of the rail and the sections, e.g. a search result list. */
+		override?: Snippet;
+	}
+</script>
+
+<script lang="ts">
+	import ShowcaseNav from "./ShowcaseNav.svelte";
+	import "./showcase-shell.css";
+
+	let { sections, controls, railHead, children, override }: ShowcaseShellProps = $props();
+</script>
+
+<div class="sc-shell">
+	{#if controls}
+		<div class="sc-shell-controls">
+			{@render controls()}
+		</div>
+	{/if}
+
+	{#if override}
+		<div class="sc-shell-override">
+			{@render override()}
+		</div>
+	{:else}
+		<div class="sc-shell-body">
+			<!-- A landmark of its own, because the index is a second way through the
+           page rather than part of the page's content. -->
+			<aside class="sc-shell-rail">
+				{#if railHead}
+					<div class="sc-shell-rail-head">
+						{@render railHead()}
+					</div>
+				{/if}
+				<ShowcaseNav {sections} />
+			</aside>
+
+			<div class="sc-shell-main">
+				{@render children()}
+			</div>
+		</div>
+	{/if}
+</div>