@heyramzi/ui 1.54.2 → 2.0.0

package/src/canvas/ui/place-panel.ts

@@ -0,0 +1,80 @@
+// Where a contextual panel sits so it never covers the selection's grips: beside the selection, on the side with room.
+
+export interface Box {
+  left: number;
+  top: number;
+  right: number;
+  bottom: number;
+}
+
+export interface Size {
+  width: number;
+  height: number;
+}
+
+export type Side = "right" | "left" | "below" | "above";
+
+/** The panel's gap from the selection: past the grips, which stick out half their size and have a hit area around them. */
+export const CLEARANCE = 20;
+/** The size chip hangs under a selected card, so a panel below leaves room for it. */
+const CHIP_ROOM = 40;
+/** The canvas's own docks: the rail on the left, the pill along the bottom, a small margin elsewhere. */
+const INSET = { left: 72, top: 12, right: 12, bottom: 76 };
+/** The minimap fills the bottom-right corner, so a panel that reaches it stops above it. */
+const MINIMAP = { width: 232, height: 172 };
+
+/**
+ * The first side with room for the panel (right, left, below, above), centred on the
+ * selection. Null when none fits, and the caller docks it at the edge.
+ */
+export function placeBeside(
+  selection: Box,
+  panel: Size,
+  canvas: Size,
+): { x: number; y: number; side: Side } | null {
+  const free = {
+    left: INSET.left,
+    top: INSET.top,
+    right: canvas.width - INSET.right,
+    bottom: canvas.height - INSET.bottom,
+  };
+  const centreX = (selection.left + selection.right) / 2 - panel.width / 2;
+  const centreY = (selection.top + selection.bottom) / 2 - panel.height / 2;
+  // The lowest a panel may reach where it stands: above the minimap when it reaches that corner.
+  const floor = (x: number, width: number) =>
+    x + width > canvas.width - MINIMAP.width ? canvas.height - MINIMAP.height : free.bottom;
+  const clampX = (x: number) => Math.min(Math.max(x, free.left), free.right - panel.width);
+  const clampY = (y: number, x: number) =>
+    Math.min(Math.max(y, free.top), floor(x, panel.width) - panel.height);
+
+  const tries: Array<{ side: Side; x: number; y: number; fits: boolean }> = [
+    {
+      side: "right",
+      x: selection.right + CLEARANCE,
+      y: clampY(centreY, selection.right + CLEARANCE),
+      fits: selection.right + CLEARANCE + panel.width <= free.right,
+    },
+    {
+      side: "left",
+      x: selection.left - CLEARANCE - panel.width,
+      y: clampY(centreY, selection.left - CLEARANCE - panel.width),
+      fits: selection.left - CLEARANCE - panel.width >= free.left,
+    },
+    {
+      side: "below",
+      x: clampX(centreX),
+      y: selection.bottom + CLEARANCE + CHIP_ROOM,
+      fits:
+        selection.bottom + CLEARANCE + CHIP_ROOM + panel.height <=
+        floor(clampX(centreX), panel.width),
+    },
+    {
+      side: "above",
+      x: clampX(centreX),
+      y: selection.top - CLEARANCE - panel.height,
+      fits: selection.top - CLEARANCE - panel.height >= free.top,
+    },
+  ];
+  const found = tries.find((attempt) => attempt.fits);
+  return found ? { x: found.x, y: found.y, side: found.side } : null;
+}

package/src/canvas/ui/shortcut-tip.test.ts

@@ -0,0 +1,16 @@
+import { describe, expect, it } from "vite-plus/test";
+import { shortcutTip } from "./shortcut-tip.js";
+
+describe("shortcutTip", () => {
+  it("joins Mac glyphs with no separator", () => {
+    expect(shortcutTip("Redo", ["mod", "shift", "Z"], true)).toBe("Redo  ⌘⇧Z");
+  });
+
+  it("spells the modifiers out elsewhere", () => {
+    expect(shortcutTip("Undo", ["mod", "Z"], false)).toBe("Undo  Ctrl+Z");
+  });
+
+  it("returns the bare label with no key", () => {
+    expect(shortcutTip("Fit", [])).toBe("Fit");
+  });
+});

package/src/canvas/ui/shortcut-tip.ts

@@ -0,0 +1,17 @@
+// The text a tool bar tooltip shows beside its label, so every button names its key the same way.
+
+const GLYPHS: Record<string, { mac: string; other: string }> = {
+  mod: { mac: "⌘", other: "Ctrl" },
+  shift: { mac: "⇧", other: "Shift" },
+};
+
+export function isMacPlatform(): boolean {
+  return typeof navigator !== "undefined" && navigator.platform.includes("Mac");
+}
+
+/** "Undo  ⌘Z" on a Mac, "Undo  Ctrl+Z" elsewhere. `keys` are the same words the shortcut list uses. */
+export function shortcutTip(label: string, keys: readonly string[], mac = isMacPlatform()): string {
+  if (keys.length === 0) return label;
+  const parts = keys.map((key) => GLYPHS[key]?.[mac ? "mac" : "other"] ?? key);
+  return `${label}  ${parts.join(mac ? "" : "+")}`;
+}

package/src/canvas/ui/tools.ts

@@ -0,0 +1,146 @@
+// The tool bar's tools, their keys and the shortcut list the help panel renders.
+// Pure data and two lookups, so the keyboard, the bar and the panel can't disagree.
+
+import { PEN_DEFAULTS, type PenTool, type ShapeKind } from "../pen/types.js";
+
+export type CanvasTool = "select" | "hand" | "connect" | "frame" | PenTool;
+
+export interface ToolDef {
+  id: CanvasTool;
+  key: string;
+}
+
+/** Every tool with its single-letter key. Shapes share one bar button but keep a key each. */
+export const TOOLS: readonly ToolDef[] = [
+  { id: "select", key: "V" },
+  { id: "hand", key: "H" },
+  { id: "connect", key: "L" },
+  { id: "pen", key: "P" },
+  { id: "highlighter", key: "M" },
+  { id: "eraser", key: "E" },
+  { id: "text", key: "T" },
+  { id: "rectangle", key: "R" },
+  { id: "ellipse", key: "O" },
+  { id: "diamond", key: "D" },
+  { id: "frame", key: "F" },
+];
+
+const TOOL_BY_KEY = new Map(TOOLS.map((tool) => [tool.key.toLowerCase(), tool.id]));
+
+/** The tool a bare letter selects. Callers rule out modifiers and typing targets first. */
+export function toolForKey(key: string): CanvasTool | null {
+  return TOOL_BY_KEY.get(key.toLowerCase()) ?? null;
+}
+
+export function keyForTool(tool: CanvasTool): string {
+  return TOOLS.find((entry) => entry.id === tool)?.key ?? "";
+}
+
+/** True for every tool the pen overlay handles. Select, hand and connect leave the pointer to xyflow, and frame has its own layer. */
+export function isDrawingTool(tool: CanvasTool): tool is PenTool {
+  return tool !== "select" && tool !== "hand" && tool !== "connect" && tool !== "frame";
+}
+
+/** The frame tool drags out a box rather than a mark, so it has its own layer. */
+export function isFrameTool(tool: CanvasTool): tool is "frame" {
+  return tool === "frame";
+}
+
+export function isShapeTool(tool: CanvasTool): tool is ShapeKind {
+  return tool === "rectangle" || tool === "ellipse" || tool === "diamond";
+}
+
+// =========================
+// BRUSH SIZES
+// =========================
+
+export type BrushLevel = 0 | 1 | 2;
+
+const BRUSH_SIZES = {
+  pen: [2, PEN_DEFAULTS.pen.size, 8],
+  highlighter: [12, PEN_DEFAULTS.highlighter.size, 32],
+} as const;
+
+export const DEFAULT_BRUSH_LEVEL: BrushLevel = 1;
+
+/** Flow-unit width for a tool at a level. Tools with no brush return undefined and take their default. */
+export function brushSize(tool: CanvasTool, level: BrushLevel): number | undefined {
+  if (tool === "pen" || tool === "highlighter") return BRUSH_SIZES[tool][level];
+  return undefined;
+}
+
+export function hasBrush(tool: CanvasTool): boolean {
+  return tool === "pen" || tool === "highlighter";
+}
+
+/** The three tools that share one rail button, the last one used. */
+export type BrushTool = "pen" | "highlighter" | "eraser";
+
+export function isBrushTool(tool: CanvasTool): tool is BrushTool {
+  return tool === "pen" || tool === "highlighter" || tool === "eraser";
+}
+
+/** Colour applies to every drawing tool except the eraser. */
+export function hasColor(tool: CanvasTool): boolean {
+  return isDrawingTool(tool) && tool !== "eraser";
+}
+
+// =========================
+// SHORTCUT LIST
+// =========================
+
+export type ShortcutGroup = "tools" | "edit" | "view";
+
+export interface Shortcut {
+  /** A stable id the app maps to a translated label. */
+  id: string;
+  group: ShortcutGroup;
+  /** "mod" renders as Cmd or Ctrl, "shift" as the shift glyph. Anything else is shown as typed. */
+  keys: readonly string[];
+}
+
+/** One row per key the canvas owns. The panel is built from this list and nothing else. */
+export const SHORTCUTS: readonly Shortcut[] = [
+  { id: "select", group: "tools", keys: ["V"] },
+  { id: "hand", group: "tools", keys: ["H"] },
+  { id: "connect", group: "tools", keys: ["L"] },
+  { id: "pen", group: "tools", keys: ["P"] },
+  { id: "highlighter", group: "tools", keys: ["M"] },
+  { id: "eraser", group: "tools", keys: ["E"] },
+  { id: "text", group: "tools", keys: ["T"] },
+  { id: "rectangle", group: "tools", keys: ["R"] },
+  { id: "ellipse", group: "tools", keys: ["O"] },
+  { id: "diamond", group: "tools", keys: ["D"] },
+  { id: "frame", group: "tools", keys: ["F"] },
+  { id: "note", group: "tools", keys: ["N"] },
+  { id: "cards", group: "tools", keys: ["C"] },
+  { id: "comment", group: "tools", keys: ["B"] },
+  { id: "panTemporarily", group: "tools", keys: ["Space"] },
+  { id: "undo", group: "edit", keys: ["mod", "Z"] },
+  { id: "redo", group: "edit", keys: ["mod", "shift", "Z"] },
+  { id: "copy", group: "edit", keys: ["mod", "C"] },
+  { id: "paste", group: "edit", keys: ["mod", "V"] },
+  { id: "selectAll", group: "edit", keys: ["mod", "A"] },
+  { id: "multiSelect", group: "edit", keys: ["shift", "Click"] },
+  { id: "duplicate", group: "edit", keys: ["mod", "D"] },
+  { id: "group", group: "edit", keys: ["mod", "G"] },
+  { id: "ungroup", group: "edit", keys: ["mod", "shift", "G"] },
+  { id: "bringForward", group: "edit", keys: ["]"] },
+  { id: "sendBackward", group: "edit", keys: ["["] },
+  { id: "bringToFront", group: "edit", keys: ["mod", "]"] },
+  { id: "sendToBack", group: "edit", keys: ["mod", "["] },
+  { id: "lock", group: "edit", keys: ["mod", "shift", "L"] },
+  { id: "copyAsPng", group: "edit", keys: ["mod", "shift", "C"] },
+  { id: "nudge", group: "edit", keys: ["Arrows"] },
+  { id: "nudgeFar", group: "edit", keys: ["shift", "Arrows"] },
+  { id: "delete", group: "edit", keys: ["Del"] },
+  { id: "save", group: "edit", keys: ["mod", "S"] },
+  { id: "zoomIn", group: "view", keys: ["+"] },
+  { id: "zoomOut", group: "view", keys: ["-"] },
+  { id: "zoom100", group: "view", keys: ["shift", "0"] },
+  { id: "zoomFit", group: "view", keys: ["shift", "1"] },
+  { id: "zoomSelection", group: "view", keys: ["shift", "2"] },
+  { id: "present", group: "view", keys: ["mod", "Enter"] },
+  { id: "shortcuts", group: "view", keys: ["?"] },
+  { id: "escape", group: "view", keys: ["Esc"] },
+];

package/src/charts/README.md

@@ -0,0 +1,104 @@
+# @heyramzi/ui/charts
+
+Svelte 5 charts on [LayerChart](https://layerchart.com): area, line, bar, donut, ring, gauge, sparkline, time series and stat cards. One set of tokens, a crosshair tooltip, a screen reader data table on the bar chart, and an entrance sweep that respects `prefers-reduced-motion`.
+
+Live demos: [ui.heyramzi.com/charts](https://ui.heyramzi.com/charts).
+
+## Install
+
+```
+pnpm add @heyramzi/ui
+```
+
+`svelte` (5.57 or newer) is a peer. LayerChart, d3-scale and d3-shape come with the package.
+
+## Setup
+
+The charts read the shadcn token set (`--foreground`, `--border`, `--popover`, `--chart-1` to `--chart-5`) and a few motion tokens. The quickest way to get all of them is the token sheet from `@heyramzi/ui`:
+
+```css
+@import "tailwindcss";
+@import "@heyramzi/ui/tokens.css";
+@import "@heyramzi/ui/animations";
+
+@source "../node_modules/@heyramzi/ui";
+```
+
+The `@source` line matters: the chart markup carries Tailwind classes, and Tailwind only scans your own app unless you point it at the package. If you define the tokens yourself, import only the charts subpath. Dark mode keys off a `.dark` class on `html`.
+
+## Usage
+
+```svelte
+<script lang="ts">
+  import { AreaChart } from "@heyramzi/ui/charts";
+
+  const data = [
+    { month: "Jan", revenue: 3200, cost: 1800 },
+    { month: "Feb", revenue: 4100, cost: 2100 },
+    { month: "Mar", revenue: 3800, cost: 2400 },
+  ];
+</script>
+
+<AreaChart
+  {data}
+  xKey="month"
+  series={[
+    { key: "revenue", label: "Revenue", color: "var(--chart-1)" },
+    { key: "cost", label: "Cost", color: "var(--chart-3)" },
+  ]}
+  formatValue={(v) => `$${v.toLocaleString()}`}
+  height={260}
+/>
+```
+
+## What is inside
+
+| Export | What it is |
+| --- | --- |
+| `AreaChart`, `LineChart`, `BarChart` | Cartesian charts with a crosshair, soft edges and an entrance sweep |
+| `TimeSeriesChart` | Dates on the x axis, a comparison line and a tooltip |
+| `DonutChart`, `RingChart`, `GaugeChart` | Round charts, with a hover readout in the middle |
+| `Sparkline` | A tiny trend line for tables and cards |
+| `StatCard`, `NumberChart`, `TrendPill`, `AnimatedValue` | A headline number that counts up, with a delta that knows whether up is good news |
+| `Legend`, `Figure`, `EdgeFade` | Legend rows, a captioned figure frame and an edge mask |
+| `ChartContainer`, `ChartTooltip`, `ChartStyle`, `useChart` | The shadcn-style wrapper, for a chart you build yourself on LayerChart |
+
+## Dashboard
+
+`@heyramzi/ui/charts/dashboard` is the page kit around the charts: the parts a reporting page repeats. It sits on the segmented control, the data table pager and the panel label from the rest of `@heyramzi/ui`.
+
+| Export | What it is |
+| --- | --- |
+| `DashboardSection`, `PanelGrid`, `StatBand` | A named area, a row of panels side by side, a row of number cards |
+| `StatTile` | A number card on `NumberChart`: a delta, a share track, a trend shape behind the figure, an optional link |
+| `DataPanel`, `DashboardEmpty` | A titled panel for a table or chart, and the dashed empty state |
+| `DataTable`, `DataSortHead`, `RatingChip` | The one data table: sortable heads, a row that opens, columns that hide on a phone, share bars, loading and empty states. An A to E grade chip |
+| `PeriodFilter`, `DAY_WINDOWS` | The 7, 30 and 90 day window, as a filter or as links |
+| `CHART_HEIGHT`, `dataTableClass` and friends | The one chart height and the table skin |
+
+```svelte
+<script lang="ts">
+  import { DashboardSection, StatBand, StatTile } from "@heyramzi/ui/charts/dashboard";
+</script>
+
+<DashboardSection title="Revenue" note="Last 30 days">
+  <StatBand>
+    <StatTile label="Sales" value="$12,480" deltaPct={8.2} direction="up-good" lead />
+  </StatBand>
+</DashboardSection>
+```
+
+## Moving from `@heyramzi/ui/charts`
+
+The charts left `@heyramzi/ui` in its next major. Swap the import and install the new package:
+
+```diff
+-import { AreaChart } from "@heyramzi/ui/charts";
++import { AreaChart } from "@heyramzi/ui/charts";
+```
+
+Nothing else changed: the same exports, the same props, the same CSS.
+
+## License
+
+MIT

package/src/charts/ambient.d.ts

@@ -0,0 +1,4 @@
+/**
+ * A stylesheet imported for its side effect, bundled by the consumer's Vite.
+ */
+declare module "*.css";

package/src/charts/animated-value.css

@@ -0,0 +1,7 @@
+/* Styles for AnimatedValue. Plain stylesheet (see area-chart.css for why).
+   `.hr-animated-value` is the component's own namespaced fallback for tabular
+   figures (it also carries the `tabular-nums` utility class). */
+
+.hr-animated-value {
+  font-variant-numeric: tabular-nums;
+}

package/src/charts/animated-value.svelte

@@ -0,0 +1,110 @@
+<script lang="ts">
+	// =========================
+	// IMPORTS
+	// =========================
+	import "./animated-value.css";
+	import { untrack } from "svelte";
+	import { cn } from "../lib/utils.js";
+
+	// =========================
+	// TYPES
+	// =========================
+	interface Props {
+		/** Target number. The display counts up to it on mount and tweens on change. */
+		value: number;
+		/** Fixed decimal places when no `formatOptions` is given. */
+		decimals?: number;
+		/** Count-up duration in ms. */
+		duration?: number;
+		/** Custom formatter for the live number. Wins over `formatOptions`/`decimals`. */
+		format?: (value: number) => string;
+		/** Intl number formatting (currency, compact, percent, ...). Wins over `decimals`. */
+		formatOptions?: Intl.NumberFormatOptions;
+		/** BCP-47 locale for `formatOptions`. */
+		locale?: string;
+		/** Rendered before the number. */
+		prefix?: string;
+		/** Rendered after the number. */
+		suffix?: string;
+		class?: string;
+		style?: string;
+	};
+
+	// =========================
+	// PROPS
+	// =========================
+	let {
+		value,
+		decimals = 0,
+		duration = 800,
+		format,
+		formatOptions,
+		locale,
+		prefix,
+		suffix,
+		class: className,
+		style,
+	}: Props = $props();
+
+	// =========================
+	// STATE
+	// =========================
+	let displayed = $state(0);
+	let started = $state(false);
+
+	// =========================
+	// DERIVED
+	// =========================
+	const formatter = $derived(formatOptions ? new Intl.NumberFormat(locale, formatOptions) : null);
+	const currentValue = $derived(started ? displayed : value);
+	const text = $derived(
+		format
+			? format(currentValue)
+			: formatter
+				? formatter.format(currentValue)
+				: currentValue.toFixed(decimals),
+	);
+
+	// ========================= EFFECTS ========================= WHY: $effect only runs in the browser, so SSR renders the final value (no flash).
+
+	// `value` is the sole tracked dependency; `displayed` is read and written inside untrack() so the per-frame writes don't retrigger the effect (that self-dependency loops and Svelte bails, freezing the number).
+
+	// The first run sweeps from 0; later value changes tween from the current display.
+	$effect(() => {
+		const target = value;
+		let raf = 0;
+		untrack(() => {
+			const reduced =
+				typeof window !== "undefined" &&
+				window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+
+			const from = started ? displayed : 0;
+			started = true;
+
+			// WHY: snap (no tween) when motion is off, the delta is tiny, or the tab
+
+			// is hidden. rAF is paused in background tabs, so animating there would leave the number stale until the tab is shown; snapping keeps it correct.
+			if (reduced || document.hidden || Math.abs(target - from) < 0.005) {
+				displayed = target;
+				return;
+			}
+
+			const start = performance.now();
+			const tick = (now: number) => {
+				const t = Math.min((now - start) / duration, 1);
+				const eased = 1 - (1 - t) ** 3;
+				displayed = from + (target - from) * eased;
+				if (t < 1) raf = requestAnimationFrame(tick);
+			};
+			raf = requestAnimationFrame(tick);
+		});
+		return () => cancelAnimationFrame(raf);
+	});
+</script>
+
+<!-- =========================== -->
+<!-- MARKUP -->
+<!-- =========================== -->
+<span class={cn("hr-animated-value tabular-nums", className)} {style}
+	>{prefix ?? ""}{text}{suffix ?? ""}</span
+>

package/src/charts/area-chart.css

@@ -0,0 +1,29 @@
+/* Styles for AreaChart. Shipped as a plain stylesheet (imported by the
+   component) instead of a Svelte `<style>` block: a `<style>` block becomes a
+   `?type=style&lang.css` virtual module that Tailwind v4's Vite plugin mis-parses
+   when this package is consumed as source from node_modules (tailwindlabs/
+   tailwindcss#20000). Selectors are namespaced under `.hr-area-chart`. */
+
+.hr-area-chart {
+  width: 100%;
+  display: flex;
+  flex-direction: column;
+  gap: 0.5rem;
+}
+.hr-area-chart .hr-chart-body {
+  width: 100%;
+}
+
+.hr-area-chart .empty {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  height: 100%;
+  border: 1px dashed var(--chart-grid, oklch(0.5 0.01 286 / 0.2));
+  border-radius: 0.5rem;
+}
+.hr-area-chart .empty p {
+  font-size: 0.8125rem;
+  color: var(--chart-label, oklch(0.5 0.01 286));
+  margin: 0;
+}