@heyramzi/ui 2.12.0 → 2.13.0

package/dist/charts/index.js

@@ -16,3 +16,4 @@ export { default as AnimatedValue } from "../../src/charts/animated-value.svelte
 export { default as EdgeFade } from "../../src/charts/edge-fade.svelte";
 export { resolveEdgeFade, EDGE_FADE_DEFAULT } from "./edge-fade.js";
 export { ChartContainer, ChartTooltip, ChartStyle, getPayloadConfigFromPayload, useChart, setChartContext, THEMES } from "./primitives/index.js";
+export { smoothSeries, smoothMode, ticksForWidth } from "./smoothing.js";

package/dist/charts/smoothing.js

@@ -0,0 +1,93 @@
+/** The tooltip's name for a drawn point, beside its date. */
+export const ROLLING_LABEL = "7-day average";
+export const weekOf = (start) => `Week of ${start}`;
+const DAY = 864e5;
+const WINDOW = 7;
+// =========================
+// FUNCTIONS
+// =========================
+/** About 30 to 60 marks across a chart: raw to a week, a 7-day average to a quarter, whole weeks past it. */
+export function smoothMode(rangeDays) {
+	if (rangeDays <= 14) return "raw";
+	if (rangeDays <= 120) return "rolling";
+	return "weekly";
+}
+function timeOf(value) {
+	return value instanceof Date ? value.getTime() : new Date(String(value)).getTime();
+}
+/** The bucket's start in the same form the series uses, so the axis and the formatter see no change. */
+function sameForm(sample, time) {
+	if (sample instanceof Date) return new Date(time);
+	const iso = new Date(time).toISOString();
+	return String(sample).length === 10 ? iso.slice(0, 10) : iso;
+}
+/**
+* The line a chart draws: a trailing 7-day mean, or 7-day buckets counted back from the last day.
+* Totals stay the caller's raw sums; this only moves the drawn points.
+*/
+export function smoothSeries(data, xKey, yKeys, { rangeDays, kind = "count" }) {
+	const mode = smoothMode(rangeDays);
+	if (mode === "raw" || data.length < WINDOW) return {
+		points: data,
+		mode: "raw"
+	};
+	const times = data.map((d) => timeOf(d[xKey]));
+	if (mode === "rolling") {
+		// A level has no daily noise to average, and a mean draws slopes between its steps.
+		if (kind === "level") return {
+			points: data,
+			mode: "raw"
+		};
+		let from = 0;
+		const sums = Object.fromEntries(yKeys.map((k) => [k, 0]));
+		const points = data.map((d, i) => {
+			for (const k of yKeys) sums[k] += Number(d[k] ?? 0);
+			while (times[i] - times[from] >= WINDOW * DAY) {
+				for (const k of yKeys) sums[k] -= Number(data[from][k] ?? 0);
+				from += 1;
+			}
+			// Divided by the days in the window, so a missing day counts as zero, not skipped.
+			const days = Math.min(WINDOW, Math.round((times[i] - times[0]) / DAY) + 1);
+			const row = { ...d };
+			for (const k of yKeys) row[k] = sums[k] / days;
+			return row;
+		});
+		return {
+			points,
+			mode
+		};
+	}
+	// Weeks end on the last day, so only the oldest can be partial, and a partial week is dropped:
+	// a 3-day sum would draw a dip that never happened.
+	const last = times[times.length - 1];
+	const buckets = new Map();
+	data.forEach((d, i) => {
+		const index = Math.floor(Math.round((last - times[i]) / DAY) / WINDOW);
+		buckets.set(index, [...buckets.get(index) ?? [], d]);
+	});
+	const oldest = Math.max(...buckets.keys());
+	const oldestStart = last - (oldest * WINDOW + WINDOW - 1) * DAY;
+	if (times[0] > oldestStart && buckets.size > 1) buckets.delete(oldest);
+	const points = [...buckets.entries()].toSorted(([a], [b]) => b - a).map(([index, rows]) => {
+		const row = { ...rows[rows.length - 1] };
+		row[xKey] = sameForm(data[0][xKey], last - (index * WINDOW + WINDOW - 1) * DAY);
+		for (const k of yKeys) {
+			row[k] = kind === "level" ? Number(rows[rows.length - 1][k] ?? 0) : rows.reduce((sum, r) => sum + Number(r[k] ?? 0), 0);
+		}
+		return row;
+	});
+	return {
+		points,
+		mode
+	};
+}
+/** Labels at least `spacing` pixels apart, the way a time axis reads at any width. */
+export function ticksForWidth(max, spacing = 72) {
+	return (scale) => {
+		const [start, end] = scale.range();
+		const count = Math.max(2, Math.min(max, Math.floor(Math.abs(end - start) / spacing)));
+		const ticks = scale.ticks?.(count) ?? [];
+		const step = Math.ceil(ticks.length / count);
+		return step > 1 ? ticks.filter((_, i) => i % step === 0) : ticks;
+	};
+}

package/dist/components/chip/index.js

@@ -0,0 +1 @@
+export { default as TagChip } from "../../../src/components/chip/tag-chip.svelte";

package/dist/components/work-parts/index.js

@@ -0,0 +1,6 @@
+export { default as CountChip } from "../../../src/components/work-parts/count-chip.svelte";
+export { default as GroupHead } from "../../../src/components/work-parts/group-head.svelte";
+export { default as PropertyRow } from "../../../src/components/work-parts/property-row.svelte";
+export { default as WorkCard } from "../../../src/components/work-parts/work-card.svelte";
+export { default as WorkWell } from "../../../src/components/work-parts/work-well.svelte";
+export { docLooks, ganttLooks, workLooks } from "./looks.js";

package/dist/components/work-parts/looks.js

@@ -0,0 +1,53 @@
+/**
+* The shapes the work organisms (kanban, task list, gantt) put on wrappers they don't render
+* themselves: a held card's hole, the focus ring around a consumer's card or row. The organism
+* picks the role, this file owns the radius, so a token edit moves every view at once.
+*/
+export const workLooks = {
+	/** A card-sized hole: a drop slot, the held card's own place, an empty column. */
+	hole: "rounded-xl bg-foreground/[0.03] outline-1 outline-dashed outline-border -outline-offset-1",
+	/** The wrapper around a consumer's card, so its focus ring follows the card's corners. */
+	card: "rounded-xl",
+	/** A list row or a rail entry: control radius. */
+	row: "rounded-lg",
+	/** A one-line row: 32px, 44px on touch (DESIGN.md, Patterns: list rows). The snippet stretches to fill it; a two-line row grows. */
+	rowHeight: "grid min-h-8 any-pointer-coarse:min-h-11",
+	/** A row-sized hole: an empty list group. */
+	rowHole: "rounded-lg outline-1 outline-dashed outline-border -outline-offset-1",
+	/** A link wrapped round a chip: the focus ring takes the chip's corners. */
+	chipLink: "rounded-sm outline-none focus-visible:shadow-(--ring-focus)",
+	/** A quiet grey box inside a card: a command, a quote. Chip radius, no edge. */
+	inset: "rounded-sm bg-muted/50",
+	/** A surface that holds a whole list: the card step, whose shadow draws its own hairline. */
+	panel: "rounded-xl bg-card text-card-foreground shadow-card"
+};
+/**
+* The gantt's marks. A bar is a control-sized shape, a mark inside a row is chip-sized, and
+* the two round ones are a progress track and today's date number, which DESIGN rule 15
+* allows as a count.
+*/
+export const ganttLooks = {
+	bar: "rounded-lg",
+	mark: "rounded-sm",
+	/** The readout that follows a dragged bar. */
+	tip: "rounded-sm bg-foreground px-2 py-1 text-[11px] font-medium whitespace-nowrap text-background tabular-nums shadow-raised",
+	/** A title that didn't fit its bar, set beside it. */
+	outsideLabel: "rounded-sm bg-card/90 px-1 text-xs text-muted-foreground",
+	track: "rounded-full",
+	day: "rounded-full"
+};
+/**
+* The doc pages' shapes. Their icon buttons and history button are controls, so they take the
+* Button atom's radius; the edited chip is a chip; the page's icon tile and the demo's frame are
+* card-sized.
+*/
+export const docLooks = {
+	/** A 28px icon button or a full-width row button: control radius, as `Button`. */
+	control: "rounded-lg",
+	/** The "Edited" chip that opens the page's history. */
+	chip: "rounded-sm",
+	/** The icon tile above a page title. */
+	tile: "rounded-xl",
+	/** The frame a demo draws round a whole doc page. */
+	frame: "rounded-xl"
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heyramzi/ui",
-  "version": "2.12.0",
+  "version": "2.13.0",
   "description": "Svelte 5 UI for apps: primitives, effects and animations, plus work (tasks and docs), charts, slides, an editor, onboarding and a canvas as subpaths.",
   "homepage": "https://ui.heyramzi.com",
   "license": "MIT",

package/src/charts/area-chart.svelte

@@ -13,6 +13,13 @@
 	import { DOMAIN_MOTION, TOOLTIP_GAP, TOOLTIP_TOP } from "./motion.js";
 	import Reveal from "./reveal.svelte";
 	import ReferenceLine, { type ChartReference } from "./reference-line.svelte";
+	import {
+		ROLLING_LABEL,
+		smoothSeries,
+		weekOf,
+		ticksForWidth,
+		type Smoothing,
+	} from "./smoothing.js";
 
 	// =========================
 	// TYPES
@@ -47,6 +54,8 @@
 		reference?: ChartReference;
 		/** The headline while no point is hovered, like a period total. Defaults to the last point. */
 		resting?: { value: number; label: string };
+		/** Smooths the drawn line by the window shown; the resting figure stays the caller's total. */
+		smoothing?: Smoothing;
 		class?: string;
 	}
 
@@ -54,7 +63,7 @@
 	// PROPS
 	// =========================
 	let {
-		data,
+		data: input,
 		xKey,
 		yKey,
 		series: seriesInput,
@@ -68,6 +77,7 @@
 		xTicks = 6,
 		reference,
 		resting,
+		smoothing,
 		class: className,
 	}: Props = $props();
 
@@ -83,7 +93,13 @@
 		queueMicrotask(() => {
 			active = d;
 		});
-		return formatX(d[xKey]);
+		return pointLabel(d);
+	}
+
+	/** What a drawn point is: a day, the week it opens, or the end of a 7-day average. */
+	function pointLabel(d: TData): string {
+		const x = formatX(d[xKey]);
+		return mode === "weekly" ? weekOf(x) : x;
 	}
 
 	// =========================
@@ -101,6 +117,20 @@
 				? [{ key: yKey, label: yKey, color }]
 				: [],
 	);
+	const smoothed = $derived(
+		smoothing
+			? smoothSeries(
+					input,
+					xKey,
+					series.map((s) => s.key),
+					smoothing,
+				)
+			: { points: input, mode: "raw" as const },
+	);
+	const data = $derived(smoothed.points);
+	const mode = $derived(smoothed.mode);
+	// The series label in the readout, unless the point is an average of the week before it.
+	const averageLabel = $derived(mode === "rolling" ? ROLLING_LABEL : null);
 	const dataMax = $derived.by(() => {
 		if (stacked) {
 			return Math.max(0, ...data.map((d) => series.reduce((s, k) => s + Number(d[k.key] ?? 0), 0)));
@@ -126,7 +156,11 @@
 	}
 	const figureRows = $derived(
 		display
-			? series.map((s) => ({ value: Number(display[s.key]), label: s.label, color: s.color }))
+			? series.map((s) => ({
+					value: Number(display[s.key]),
+					label: averageLabel ?? s.label,
+					color: s.color,
+				}))
 			: null,
 	);
 </script>
@@ -148,7 +182,7 @@
 			size="md"
 		/>
 	{:else if figureRows && display}
-		<Figure series={figureRows} eyebrow={formatX(display[xKey])} format={formatValue} size="md" />
+		<Figure series={figureRows} eyebrow={pointLabel(display)} format={formatValue} size="md" />
 	{:else}
 		<Figure value="—" eyebrow="Latest" size="md" />
 	{/if}
@@ -169,7 +203,7 @@
 			>
 				<Svg>
 					<Axis placement="left" format={(v) => valueTick(Number(v))} ticks={4} />
-					<Axis placement="bottom" format={(v) => formatX(v)} ticks={xTicks} />
+					<Axis placement="bottom" format={(v) => formatX(v)} ticks={ticksForWidth(xTicks)} />
 					<g class="hr-area-grid">
 						<Axis placement="left" grid rule={false} ticks={4} format={() => ""} />
 					</g>
@@ -210,7 +244,7 @@
 						<Tooltip.List>
 							{#each series as s (s.key)}
 								<Tooltip.Item
-									label={s.label}
+									label={averageLabel ?? s.label}
 									value={formatValue(Number(d[s.key]))}
 									color={s.color}
 								/>

package/src/charts/index.ts

@@ -29,3 +29,11 @@ export {
   setChartContext,
   THEMES,
 } from "./primitives/index.js";
+export {
+  smoothSeries,
+  smoothMode,
+  ticksForWidth,
+  type Smoothing,
+  type SeriesKind,
+  type SmoothMode,
+} from "./smoothing.js";

package/src/charts/smoothing.ts

@@ -0,0 +1,114 @@
+// =========================
+// TYPES
+// =========================
+/** A count sums per bucket (visitors, clicks); a level is a reading at a moment (MRR), never summed. */
+export type SeriesKind = "count" | "level";
+
+export interface Smoothing {
+  /** The window the chart shows, in days. It picks how much the line is smoothed. */
+  rangeDays: number;
+  kind?: SeriesKind;
+}
+
+export type SmoothMode = "raw" | "rolling" | "weekly";
+
+/** The tooltip's name for a drawn point, beside its date. */
+export const ROLLING_LABEL = "7-day average";
+export const weekOf = (start: string) => `Week of ${start}`;
+
+const DAY = 86_400_000;
+const WINDOW = 7;
+
+// =========================
+// FUNCTIONS
+// =========================
+/** About 30 to 60 marks across a chart: raw to a week, a 7-day average to a quarter, whole weeks past it. */
+export function smoothMode(rangeDays: number): SmoothMode {
+  if (rangeDays <= 14) return "raw";
+  if (rangeDays <= 120) return "rolling";
+  return "weekly";
+}
+
+function timeOf(value: unknown): number {
+  return value instanceof Date ? value.getTime() : new Date(String(value)).getTime();
+}
+
+/** The bucket's start in the same form the series uses, so the axis and the formatter see no change. */
+function sameForm(sample: unknown, time: number): unknown {
+  if (sample instanceof Date) return new Date(time);
+  const iso = new Date(time).toISOString();
+  return String(sample).length === 10 ? iso.slice(0, 10) : iso;
+}
+
+/**
+ * The line a chart draws: a trailing 7-day mean, or 7-day buckets counted back from the last day.
+ * Totals stay the caller's raw sums; this only moves the drawn points.
+ */
+export function smoothSeries<TData extends Record<string, unknown>>(
+  data: TData[],
+  xKey: keyof TData & string,
+  yKeys: (keyof TData & string)[],
+  { rangeDays, kind = "count" }: Smoothing,
+): { points: TData[]; mode: SmoothMode } {
+  const mode = smoothMode(rangeDays);
+  if (mode === "raw" || data.length < WINDOW) return { points: data, mode: "raw" };
+  const times = data.map((d) => timeOf(d[xKey]));
+
+  if (mode === "rolling") {
+    // A level has no daily noise to average, and a mean draws slopes between its steps.
+    if (kind === "level") return { points: data, mode: "raw" };
+    let from = 0;
+    const sums = Object.fromEntries(yKeys.map((k) => [k, 0])) as Record<string, number>;
+    const points = data.map((d, i) => {
+      for (const k of yKeys) sums[k] += Number(d[k] ?? 0);
+      while (times[i] - times[from] >= WINDOW * DAY) {
+        for (const k of yKeys) sums[k] -= Number(data[from][k] ?? 0);
+        from += 1;
+      }
+      // Divided by the days in the window, so a missing day counts as zero, not skipped.
+      const days = Math.min(WINDOW, Math.round((times[i] - times[0]) / DAY) + 1);
+      const row: Record<string, unknown> = { ...d };
+      for (const k of yKeys) row[k] = sums[k] / days;
+      return row as TData;
+    });
+    return { points, mode };
+  }
+
+  // Weeks end on the last day, so only the oldest can be partial, and a partial week is dropped:
+  // a 3-day sum would draw a dip that never happened.
+  const last = times[times.length - 1];
+  const buckets = new Map<number, TData[]>();
+  data.forEach((d, i) => {
+    const index = Math.floor(Math.round((last - times[i]) / DAY) / WINDOW);
+    buckets.set(index, [...(buckets.get(index) ?? []), d]);
+  });
+  const oldest = Math.max(...buckets.keys());
+  const oldestStart = last - (oldest * WINDOW + WINDOW - 1) * DAY;
+  if (times[0] > oldestStart && buckets.size > 1) buckets.delete(oldest);
+
+  const points = [...buckets.entries()]
+    .toSorted(([a], [b]) => b - a)
+    .map(([index, rows]) => {
+      const row: Record<string, unknown> = { ...rows[rows.length - 1] };
+      row[xKey] = sameForm(data[0][xKey], last - (index * WINDOW + WINDOW - 1) * DAY);
+      for (const k of yKeys) {
+        row[k] =
+          kind === "level"
+            ? Number(rows[rows.length - 1][k] ?? 0)
+            : rows.reduce((sum, r) => sum + Number(r[k] ?? 0), 0);
+      }
+      return row as TData;
+    });
+  return { points, mode };
+}
+
+/** Labels at least `spacing` pixels apart, the way a time axis reads at any width. */
+export function ticksForWidth(max: number, spacing = 72) {
+  return (scale: { range: () => number[]; ticks?: (count: number) => unknown[] }) => {
+    const [start, end] = scale.range();
+    const count = Math.max(2, Math.min(max, Math.floor(Math.abs(end - start) / spacing)));
+    const ticks = scale.ticks?.(count) ?? [];
+    const step = Math.ceil(ticks.length / count);
+    return step > 1 ? ticks.filter((_, i) => i % step === 0) : ticks;
+  };
+}

package/src/charts/sparkline.svelte

@@ -6,6 +6,7 @@
 	import { Area, Chart, Highlight, LinearGradient, Points, Spline, Svg, Tooltip } from "layerchart";
 	import { curveMonotoneX } from "d3-shape";
 	import Reveal from "./reveal.svelte";
+	import { ROLLING_LABEL, smoothSeries, weekOf, type Smoothing } from "./smoothing.js";
 
 	// =========================
 	// TYPES
@@ -31,6 +32,10 @@
 		 */
 		bare?: boolean;
 		formatValue?: (v: number) => string;
+		/** The tooltip's date. */
+		formatX?: (v: unknown) => string;
+		/** Smooths the drawn line by the window shown, so a year doesn't draw as a barcode. */
+		smoothing?: Smoothing;
 		class?: string;
 	}
 
@@ -38,7 +43,7 @@
 	// PROPS
 	// =========================
 	let {
-		data,
+		data: input,
 		xKey,
 		yKey,
 		color = "var(--chart-1)",
@@ -48,6 +53,8 @@
 		showLast = false,
 		bare = false,
 		formatValue = (v) => v.toLocaleString(),
+		formatX = (v) => String(v),
+		smoothing,
 		class: className,
 	}: Props = $props();
 
@@ -63,13 +70,22 @@
 		queueMicrotask(() => {
 			active = d;
 		});
-		return String(d[xKey]);
+		const x = formatX(d[xKey]);
+		return mode === "weekly" ? weekOf(x) : x;
 	}
 
 	// =========================
 	// DERIVED
 	// =========================
 	const uid = `hr-spark-${Math.random().toString(36).slice(2, 8)}`;
+	const smoothed = $derived(
+		smoothing
+			? smoothSeries(input, xKey, [yKey], smoothing)
+			: { points: input, mode: "raw" as const },
+	);
+	const data = $derived(smoothed.points);
+	const mode = $derived(smoothed.mode);
+	const valueLabel = $derived(mode === "rolling" ? ROLLING_LABEL : String(yKey));
 	const curve = $derived(smooth ? curveMonotoneX : undefined);
 	const last = $derived(data.length > 0 ? data[data.length - 1] : null);
 	const display = $derived(active ?? last);
@@ -128,7 +144,7 @@
 						{#snippet children({ data: d })}
 							<Tooltip.Header value={trackActive(d as TData)} />
 							<Tooltip.List>
-								<Tooltip.Item label={String(yKey)} value={formatValue(Number(d[yKey]))} />
+								<Tooltip.Item label={valueLabel} value={formatValue(Number(d[yKey]))} />
 							</Tooltip.List>
 						{/snippet}
 					</Tooltip.Root>

package/src/components/chip/index.ts

@@ -0,0 +1 @@
+export { default as TagChip } from "./tag-chip.svelte";

package/src/components/chip/tag-chip.svelte

@@ -0,0 +1,63 @@
+<script lang="ts">
+	import type { Snippet } from "svelte";
+	import type { HTMLAttributes } from "svelte/elements";
+	import { X } from "phosphor-svelte";
+	import { cn } from "../../lib/utils.js";
+
+	interface Props extends Omit<HTMLAttributes<HTMLSpanElement>, "class" | "children"> {
+		/** A leading mark: a tag icon, a colour dot, an avatar. */
+		icon?: Snippet;
+		/** Shows a remove button after the label. */
+		onremove?: () => void;
+		/** The remove button's accessible name. */
+		removeLabel?: string;
+		/**
+		 * False keeps the remove button out of the tab order and stops it taking focus on press,
+		 * for a chip inside a field whose input owns the keyboard (Backspace removes).
+		 */
+		removeFocusable?: boolean;
+		children?: Snippet;
+		class?: string;
+	}
+
+	let {
+		icon,
+		onremove,
+		removeLabel = "Remove",
+		removeFocusable = true,
+		children,
+		class: className,
+		...restProps
+	}: Props = $props();
+</script>
+
+<!-- A tag is a label the user wrote, not a state, so it's a bordered grey rectangle at the chip
+     radius and never a pill (DESIGN.md rules 2 and 15). -->
+<span
+	data-slot="tag-chip"
+	class={cn(
+		"inline-flex h-5 max-w-full shrink-0 items-center gap-1 overflow-hidden rounded-sm border border-border bg-muted/60 px-1.5 text-xs text-foreground",
+		"[&>svg]:size-3 [&>svg]:shrink-0 [&>svg]:text-muted-foreground",
+		onremove && "pr-0.5",
+		className,
+	)}
+	{...restProps}
+>
+	{@render icon?.()}
+	<span class="min-w-0 truncate">{@render children?.()}</span>
+	{#if onremove}
+		<!-- The glyph is 12px; the after: box takes the hit area to 24px without growing the chip. -->
+		<button
+			type="button"
+			class="relative grid size-4 shrink-0 place-items-center rounded-sm text-muted-foreground transition-colors duration-quick ease-smooth-out after:absolute after:-inset-1 hover:bg-foreground/8 hover:text-foreground focus-visible:shadow-[var(--ring-focus)] focus-visible:outline-none motion-reduce:transition-none"
+			aria-label={removeLabel}
+			tabindex={removeFocusable ? undefined : -1}
+			onmousedown={(e) => {
+				if (!removeFocusable) e.preventDefault();
+			}}
+			onclick={onremove}
+		>
+			<X class="size-3" weight="bold" />
+		</button>
+	{/if}
+</span>

package/src/components/work-parts/count-chip.svelte

@@ -0,0 +1,20 @@
+<script lang="ts">
+	import { cn } from "../../lib/utils.js";
+
+	interface Props {
+		count: number;
+		class?: string;
+	}
+
+	let { count, class: className }: Props = $props();
+</script>
+
+<!-- A count beside a heading: a quiet square, never a pill, so it reads as a number and not a status. -->
+<span
+	class={cn(
+		"grid h-5 min-w-5 shrink-0 place-items-center rounded-sm bg-foreground/5 px-1 text-xs font-medium text-muted-foreground tabular-nums",
+		className,
+	)}
+>
+	{count.toLocaleString()}
+</span>

package/src/components/work-parts/group-head.svelte

@@ -0,0 +1,48 @@
+<script lang="ts">
+	import type { Snippet } from "svelte";
+	import { Plus } from "phosphor-svelte";
+	import { cn } from "../../lib/utils.js";
+	import { Button } from "../../shadcn/button/index.js";
+	import CountChip from "./count-chip.svelte";
+
+	interface Props {
+		label: string;
+		/** The status colour of the dot. Leave out for no dot. */
+		hue?: string;
+		count: number;
+		/** Shows a plus at the end that adds an item to this group. */
+		onAdd?: () => void;
+		addLabel?: string;
+		/** Extra controls before the plus. */
+		children?: Snippet;
+		class?: string;
+	}
+
+	let { label, hue, count, onAdd, addLabel = "Add", children, class: className }: Props = $props();
+</script>
+
+<!-- A group's head, the same in a kanban column and a list group: dot, name, count, plus. -->
+<div class={cn("flex h-8 min-w-0 flex-1 items-center gap-2", className)}>
+	{#if hue}
+		<span class="size-2 shrink-0 rounded-full" style:background={hue} aria-hidden="true"></span>
+	{/if}
+	<span class="truncate text-sm font-medium text-foreground">{label}</span>
+	<CountChip {count} />
+	{#if children || onAdd}
+		<span class="ms-auto flex shrink-0 items-center gap-0.5">
+			{@render children?.()}
+			{#if onAdd}
+				<Button
+					variant="ghost"
+					size="sm"
+					icon
+					aria-label="{addLabel}: {label}"
+					class="text-muted-foreground"
+					onclick={onAdd}
+				>
+					<Plus weight="bold" aria-hidden="true" />
+				</Button>
+			{/if}
+		</span>
+	{/if}
+</div>

package/src/components/work-parts/index.ts

@@ -0,0 +1,6 @@
+export { default as CountChip } from "./count-chip.svelte";
+export { default as GroupHead } from "./group-head.svelte";
+export { default as PropertyRow } from "./property-row.svelte";
+export { default as WorkCard } from "./work-card.svelte";
+export { default as WorkWell } from "./work-well.svelte";
+export { docLooks, ganttLooks, workLooks } from "./looks.js";

package/src/components/work-parts/looks.ts

@@ -0,0 +1,55 @@
+/**
+ * The shapes the work organisms (kanban, task list, gantt) put on wrappers they don't render
+ * themselves: a held card's hole, the focus ring around a consumer's card or row. The organism
+ * picks the role, this file owns the radius, so a token edit moves every view at once.
+ */
+export const workLooks = {
+  /** A card-sized hole: a drop slot, the held card's own place, an empty column. */
+  hole: "rounded-xl bg-foreground/[0.03] outline-1 outline-dashed outline-border -outline-offset-1",
+  /** The wrapper around a consumer's card, so its focus ring follows the card's corners. */
+  card: "rounded-xl",
+  /** A list row or a rail entry: control radius. */
+  row: "rounded-lg",
+  /** A one-line row: 32px, 44px on touch (DESIGN.md, Patterns: list rows). The snippet stretches to fill it; a two-line row grows. */
+  rowHeight: "grid min-h-8 any-pointer-coarse:min-h-11",
+  /** A row-sized hole: an empty list group. */
+  rowHole: "rounded-lg outline-1 outline-dashed outline-border -outline-offset-1",
+  /** A link wrapped round a chip: the focus ring takes the chip's corners. */
+  chipLink: "rounded-sm outline-none focus-visible:shadow-(--ring-focus)",
+  /** A quiet grey box inside a card: a command, a quote. Chip radius, no edge. */
+  inset: "rounded-sm bg-muted/50",
+  /** A surface that holds a whole list: the card step, whose shadow draws its own hairline. */
+  panel: "rounded-xl bg-card text-card-foreground shadow-card",
+} as const;
+
+/**
+ * The gantt's marks. A bar is a control-sized shape, a mark inside a row is chip-sized, and
+ * the two round ones are a progress track and today's date number, which DESIGN rule 15
+ * allows as a count.
+ */
+export const ganttLooks = {
+  bar: "rounded-lg",
+  mark: "rounded-sm",
+  /** The readout that follows a dragged bar. */
+  tip: "rounded-sm bg-foreground px-2 py-1 text-[11px] font-medium whitespace-nowrap text-background tabular-nums shadow-raised",
+  /** A title that didn't fit its bar, set beside it. */
+  outsideLabel: "rounded-sm bg-card/90 px-1 text-xs text-muted-foreground",
+  track: "rounded-full",
+  day: "rounded-full",
+} as const;
+
+/**
+ * The doc pages' shapes. Their icon buttons and history button are controls, so they take the
+ * Button atom's radius; the edited chip is a chip; the page's icon tile and the demo's frame are
+ * card-sized.
+ */
+export const docLooks = {
+  /** A 28px icon button or a full-width row button: control radius, as `Button`. */
+  control: "rounded-lg",
+  /** The "Edited" chip that opens the page's history. */
+  chip: "rounded-sm",
+  /** The icon tile above a page title. */
+  tile: "rounded-xl",
+  /** The frame a demo draws round a whole doc page. */
+  frame: "rounded-xl",
+} as const;

package/src/components/work-parts/property-row.svelte

@@ -0,0 +1,44 @@
+<script lang="ts">
+	import type { Component, Snippet } from "svelte";
+	import { cn } from "../../lib/utils.js";
+
+	interface Props {
+		label: string;
+		/** A Phosphor icon before the label. */
+		icon?: Component<{ class?: string; "aria-hidden"?: boolean | "true" | "false" }>;
+		/**
+		 * `responsive`: the label hides in a narrow container (a chip row) and shows as a column
+		 * from `@3xl` up. `row`: always icon, label, value.
+		 */
+		layout?: "row" | "responsive";
+		children: Snippet;
+		class?: string;
+	}
+
+	let { label, icon: Icon, layout = "row", children, class: className }: Props = $props();
+</script>
+
+<!-- One property: icon and label on the left in muted text, the value on the right. -->
+<div
+	role="group"
+	aria-label={label}
+	class={cn(
+		"min-h-8 items-center gap-2",
+		layout === "row"
+			? "grid grid-cols-[minmax(0,7rem)_minmax(0,1fr)]"
+			: "flex @3xl:grid @3xl:grid-cols-[7rem_minmax(0,1fr)]",
+		className,
+	)}
+>
+	<span
+		class={cn(
+			"min-w-0 items-center gap-2 text-xs font-medium text-muted-foreground",
+			layout === "row" ? "flex" : "hidden @3xl:flex",
+		)}
+		aria-hidden="true"
+	>
+		{#if Icon}<Icon class="size-4 shrink-0" aria-hidden="true" />{/if}
+		<span class="truncate">{label}</span>
+	</span>
+	<div class="flex min-w-0 items-center">{@render children()}</div>
+</div>

package/src/components/work-parts/work-card.svelte

@@ -0,0 +1,34 @@
+<script lang="ts">
+	import type { Snippet } from "svelte";
+	import type { HTMLAttributes } from "svelte/elements";
+	import { cn } from "../../lib/utils.js";
+	import { Card } from "../../shadcn/card/index.js";
+
+	interface Props extends HTMLAttributes<HTMLElement> {
+		/** The bottom row: dates, subtasks, time, avatars. */
+		meta?: Snippet;
+		children: Snippet;
+		class?: string;
+	}
+
+	let { meta, children, class: className, ...rest }: Props = $props();
+</script>
+
+<!-- A white card on a grey well: the title, then a quiet meta row. Depth comes from the card
+     step and rises one step on hover, so a held card has somewhere to go. -->
+<Card
+	{...rest}
+	class={cn(
+		"gap-2.5 px-3 py-2.5 transition-shadow duration-quick ease-smooth-out hover:shadow-card-hover",
+		className,
+	)}
+>
+	<div class="text-sm leading-snug text-pretty">{@render children()}</div>
+	{#if meta}
+		<div
+			class="flex min-w-0 flex-wrap items-center gap-x-2 gap-y-1 text-xs whitespace-nowrap text-muted-foreground tabular-nums"
+		>
+			{@render meta()}
+		</div>
+	{/if}
+</Card>

package/src/components/work-parts/work-well.svelte

@@ -0,0 +1,36 @@
+<script lang="ts">
+	import type { Snippet } from "svelte";
+	import type { HTMLAttributes } from "svelte/elements";
+	import { cn } from "../../lib/utils.js";
+
+	interface Props extends HTMLAttributes<HTMLDivElement> {
+		/** Any CSS colour. Tints the well only while something is held over it. */
+		hue?: string;
+		/** Something is held over the well. */
+		active?: boolean;
+		children: Snippet;
+		class?: string;
+	}
+
+	let { hue, active = false, children, class: className, ...rest }: Props = $props();
+
+	// A well rests grey. Its hue shows only while a card is held over it.
+	let style = $derived(
+		hue && active
+			? `background: color-mix(in oklch, ${hue} 8%, var(--color-muted)); outline-color: color-mix(in oklch, ${hue} 30%, transparent);`
+			: undefined,
+	);
+</script>
+
+<!-- The grey well white cards sit in. Card radius plus its padding takes the next step up:
+     radius-xl cards, 6px in, a radius-2xl well (DESIGN rule 14). -->
+<div
+	{...rest}
+	class={cn(
+		"flex min-h-0 flex-col gap-1.5 overflow-x-hidden overflow-y-auto rounded-2xl bg-muted/70 p-1.5 outline-1 outline-transparent -outline-offset-1 transition-[background-color,outline-color] duration-quick ease-smooth-out dark:bg-muted/60",
+		className,
+	)}
+	{style}
+>
+	{@render children()}
+</div>