@preset.nz/ux-kit 0.0.0-stage → 0.1.1

package/src/graphics/curve-edits.ts

@@ -0,0 +1,146 @@
+import {
+  type Basis,
+  type Curve,
+  type CurvePoint,
+  clamp,
+  invlerp,
+  TENSION_STRENGTH,
+} from "@preset.nz/math"
+
+/**
+ * Limits on a curve, applied to every proposed edit: a drag, a nudge, an added or removed
+ * point, a basis or sustain change. Return the curve to show (adjusted if need be), or `null`
+ * to refuse the edit. `prev` is the curve before the edit, or the curve at the start of a
+ * drag. An ADSR envelope is a curve with limits (`constrainAdsr`), not a different editor.
+ */
+export type CurveConstraint = (next: Curve, prev: Curve) => Curve | null
+
+export interface Domain {
+  x: readonly [number, number]
+  y: readonly [number, number]
+}
+
+/** `next` through the constraint, or `next` itself without one. */
+export function propose(next: Curve, prev: Curve, constrain?: CurveConstraint): Curve | null {
+  return constrain ? constrain(next, prev) : next
+}
+
+/**
+ * Point `i` of `start` moved to `(x, y)`, kept inside the domain. After the constraint, the
+ * moved point is held between its neighbours, so the points stay sorted while indices stay put.
+ */
+export function movePoint(
+  start: Curve,
+  i: number,
+  x: number,
+  y: number,
+  domain: Domain,
+  constrain?: CurveConstraint,
+): Curve | null {
+  const points = start.points.map((p) => ({ ...p }))
+  const p = points[i]
+  if (!p) return null
+  p.x = clamp(x, domain.x[0], domain.x[1])
+  p.y = clamp(y, domain.y[0], domain.y[1])
+  const next = propose({ ...start, points }, start, constrain)
+  return next && keepOrder(next, i)
+}
+
+/** Point `i` held between its neighbours. Equal x is allowed: it makes a step. */
+function keepOrder(curve: Curve, i: number): Curve {
+  const pts = curve.points
+  const p = pts[i]
+  if (!p) return curve
+  const lo = pts[i - 1]?.x ?? -Infinity
+  const hi = pts[i + 1]?.x ?? Infinity
+  if (p.x >= lo && p.x <= hi) return curve
+  const points = pts.map((q, j) => (j === i ? { ...q, x: clamp(q.x, lo, hi) } : q))
+  return { ...curve, points }
+}
+
+/**
+ * A point added at `(x, y)`, in order. It takes the basis and tension of the segment it
+ * splits, so the curve around it keeps its character. Returns the new curve and the new
+ * point's index.
+ */
+export function addPoint(
+  curve: Curve,
+  x: number,
+  y: number,
+  domain: Domain,
+  constrain?: CurveConstraint,
+): { curve: Curve; index: number } | null {
+  const px = clamp(x, domain.x[0], domain.x[1])
+  const py = clamp(y, domain.y[0], domain.y[1])
+  let index = curve.points.findIndex((p) => p.x > px)
+  if (index < 0) index = curve.points.length
+  const before = curve.points[index - 1] ?? curve.points[index]
+  const point: CurvePoint = { x: px, y: py, basis: before?.basis ?? "linear" }
+  if (before?.tension !== undefined) point.tension = before.tension
+  const points = [...curve.points.slice(0, index), point, ...curve.points.slice(index)]
+  const next: Curve = { ...curve, points }
+  if (curve.sustain !== undefined && index <= curve.sustain) next.sustain = curve.sustain + 1
+  const out = propose(next, curve, constrain)
+  return out && { curve: out, index }
+}
+
+/** Point `i` removed. The last point can't be. Removing the sustain point clears sustain. */
+export function removePoint(curve: Curve, i: number, constrain?: CurveConstraint): Curve | null {
+  if (curve.points.length <= 1 || !curve.points[i]) return null
+  const next: Curve = { points: curve.points.filter((_, j) => j !== i) }
+  const s = curve.sustain
+  if (s !== undefined && s !== i) next.sustain = s > i ? s - 1 : s
+  return propose(next, curve, constrain)
+}
+
+/** Point `i`'s basis. Tension only means something on a linear segment, so others drop it. */
+export function setBasis(
+  curve: Curve,
+  i: number,
+  basis: Basis,
+  constrain?: CurveConstraint,
+): Curve | null {
+  const points = curve.points.map((p, j) => {
+    if (j !== i) return p
+    const q: CurvePoint = { ...p, basis }
+    if (basis !== "linear") delete q.tension
+    return q
+  })
+  return propose({ ...curve, points }, curve, constrain)
+}
+
+/** Sustain on point `i`, or off when it is already there. */
+export function toggleSustain(curve: Curve, i: number, constrain?: CurveConstraint): Curve | null {
+  const next: Curve = { points: curve.points }
+  if (curve.sustain !== i) next.sustain = i
+  return propose(next, curve, constrain)
+}
+
+/** The tension of the segment from point `i`, -1..1. Zero removes it. */
+export function setTension(
+  curve: Curve,
+  i: number,
+  tension: number,
+  constrain?: CurveConstraint,
+): Curve | null {
+  const t = clamp(tension, -1, 1)
+  const points = curve.points.map((p, j) => {
+    if (j !== i) return p
+    const q: CurvePoint = { ...p }
+    if (Math.abs(t) < 1e-3) delete q.tension
+    else q.tension = t
+    return q
+  })
+  return propose({ ...curve, points }, curve, constrain)
+}
+
+/**
+ * The tension that puts a linear segment's midpoint at `y`. The warp at t = 0.5 is
+ * `1 / (e^(k/2) + 1)`, so `k = 2 ln(1/w − 1)` where `w` is how far up the segment `y` sits.
+ * `null` on a flat segment, where the midpoint can't move.
+ */
+export function tensionForMidpoint(y0: number, y1: number, y: number): number | null {
+  if (Math.abs(y1 - y0) < 1e-9) return null
+  const w = clamp(invlerp(y, y0, y1), 0.005, 0.995)
+  return clamp((2 * Math.log(1 / w - 1)) / TENSION_STRENGTH, -1, 1)
+}

package/src/graphics/index.ts

@@ -0,0 +1,16 @@
+export { type Adsr, adsrCurve, adsrOf, constrainAdsr } from "./adsr"
+export { type CurveEditKind, CurveEditor, type CurveEditorProps } from "./curve-editor"
+export {
+  addPoint,
+  type CurveConstraint,
+  type Domain,
+  movePoint,
+  removePoint,
+  setBasis,
+  setTension,
+  tensionForMidpoint,
+  toggleSustain,
+} from "./curve-edits"
+export { type LinearScale, linearScale } from "./scale"
+export { type Size, useCanvasDraw, useSize } from "./use-canvas"
+export { useTokenColours } from "./use-tokens"

package/src/graphics/scale.ts

@@ -0,0 +1,25 @@
+import { fitUnclamped } from "@preset.nz/math"
+
+/**
+ * One axis's mapping between data and pixels. Both layers of a view draw through it, and
+ * pointer events come back through `invert`, so a handle can't drift off its line.
+ */
+export interface LinearScale {
+  (v: number): number
+  invert: (px: number) => number
+  domain: readonly [number, number]
+  range: readonly [number, number]
+}
+
+export function linearScale(
+  domain: readonly [number, number],
+  range: readonly [number, number],
+): LinearScale {
+  const [d0, d1] = domain
+  const [r0, r1] = range
+  const scale = ((v: number) => fitUnclamped(v, d0, d1, r0, r1)) as LinearScale
+  scale.invert = (px: number) => fitUnclamped(px, r0, r1, d0, d1)
+  scale.domain = domain
+  scale.range = range
+  return scale
+}

package/src/graphics/use-canvas.ts

@@ -0,0 +1,56 @@
+import { type RefObject, useEffect, useLayoutEffect, useRef, useState } from "react"
+
+export interface Size {
+  width: number
+  height: number
+}
+
+/** An element's size in CSS pixels, kept current by a `ResizeObserver`. */
+export function useSize(ref: RefObject<HTMLElement | null>): Size {
+  const [size, setSize] = useState<Size>({ width: 0, height: 0 })
+  useEffect(() => {
+    const el = ref.current
+    if (!el) return
+    const observer = new ResizeObserver(([entry]) => {
+      if (!entry) return
+      const { width, height } = entry.contentRect
+      setSize((s) => (s.width === width && s.height === height ? s : { width, height }))
+    })
+    observer.observe(el)
+    return () => observer.disconnect()
+  }, [ref])
+  return size
+}
+
+/**
+ * Draws on a canvas at the device's pixel ratio, at most once per animation frame. `draw`
+ * gets a context already scaled to CSS pixels. It runs again whenever `deps` change.
+ */
+export function useCanvasDraw(
+  canvas: RefObject<HTMLCanvasElement | null>,
+  size: Size,
+  draw: (ctx: CanvasRenderingContext2D, size: Size) => void,
+  deps: readonly unknown[],
+) {
+  const latest = useRef(draw)
+  useLayoutEffect(() => {
+    latest.current = draw
+  })
+  useEffect(() => {
+    const el = canvas.current
+    if (!el || size.width === 0 || size.height === 0) return
+    const frame = requestAnimationFrame(() => {
+      const dpr = window.devicePixelRatio || 1
+      const w = Math.round(size.width * dpr)
+      const h = Math.round(size.height * dpr)
+      if (el.width !== w) el.width = w
+      if (el.height !== h) el.height = h
+      const ctx = el.getContext("2d")
+      if (!ctx) return
+      ctx.setTransform(dpr, 0, 0, dpr, 0, 0)
+      ctx.clearRect(0, 0, size.width, size.height)
+      latest.current(ctx, size)
+    })
+    return () => cancelAnimationFrame(frame)
+  }, [canvas, size, ...deps]) // eslint-disable-line react-hooks/exhaustive-deps
+}

package/src/graphics/use-tokens.ts

@@ -0,0 +1,35 @@
+import { useEffect, useState } from "react"
+
+/**
+ * The current values of some colour tokens, for drawing on a canvas, which can't read CSS
+ * variables. Read again when the theme changes: the `.dark` class or a style on `<html>`, or
+ * the system appearance.
+ */
+export function useTokenColours<K extends string>(names: readonly K[]): Record<K, string> {
+  const key = names.join(",")
+  const [colours, setColours] = useState(() => read(names))
+  useEffect(() => {
+    const list = key.split(",") as K[]
+    const update = () => setColours(read(list))
+    update()
+    const observer = new MutationObserver(update)
+    observer.observe(document.documentElement, {
+      attributes: true,
+      attributeFilter: ["class", "style", "data-theme"],
+    })
+    const media = window.matchMedia("(prefers-color-scheme: dark)")
+    media.addEventListener("change", update)
+    return () => {
+      observer.disconnect()
+      media.removeEventListener("change", update)
+    }
+  }, [key])
+  return colours
+}
+
+function read<K extends string>(names: readonly K[]): Record<K, string> {
+  const style = getComputedStyle(document.documentElement)
+  const out = {} as Record<K, string>
+  for (const name of names) out[name] = style.getPropertyValue(`--${name}`).trim() || "currentColor"
+  return out
+}

package/src/icons.ts

@@ -0,0 +1,3 @@
+// Phosphor is the kit's icon set. Re-exported here so apps import icons from
+// the kit and one version of the package serves them all.
+export * from "@phosphor-icons/react"

package/src/index.css

@@ -0,0 +1,199 @@
+/* @preset.nz/ux-kit: tokens, palettes and fonts.
+   Import this after tailwindcss, and add an @source line for the kit's src:
+
+     @import "tailwindcss";
+     @source "../node_modules/@preset.nz/ux-kit/src";
+     @import "@preset.nz/ux-kit/index.css";
+
+   Seeded from Strata's index.css. Dark mode is a .dark class on <html>. */
+@import "tw-animate-css";
+@import "./shadcn-tailwind.css";
+
+/* Two families only (Georg 2026-10-03): Geist for the interface, JetBrains Mono for values and code. */
+@import "@fontsource-variable/geist";
+@import "@fontsource-variable/jetbrains-mono";
+
+@custom-variant dark (&:is(.dark *));
+
+@theme inline {
+    /* Headings use the interface face; hierarchy comes from size and weight. */
+    --font-heading: 'Geist Variable', ui-sans-serif, system-ui, sans-serif;
+    /* Body text face. */
+    --font-sans: 'Geist Variable', ui-sans-serif, system-ui, sans-serif;
+    --font-mono: 'JetBrains Mono Variable', monospace;
+    --color-sidebar-ring: var(--sidebar-ring);
+    --color-sidebar-border: var(--sidebar-border);
+    --color-sidebar-accent-foreground: var(--sidebar-accent-foreground);
+    --color-sidebar-accent: var(--sidebar-accent);
+    --color-sidebar-primary-foreground: var(--sidebar-primary-foreground);
+    --color-sidebar-primary: var(--sidebar-primary);
+    --color-sidebar-foreground: var(--sidebar-foreground);
+    --color-sidebar: var(--sidebar);
+    --color-chart-5: var(--chart-5);
+    --color-chart-4: var(--chart-4);
+    --color-chart-3: var(--chart-3);
+    --color-chart-2: var(--chart-2);
+    --color-chart-1: var(--chart-1);
+    --color-ring: var(--ring);
+    --color-input: var(--input);
+    --color-border: var(--border);
+    --color-destructive: var(--destructive);
+    --color-destructive-foreground: var(--destructive-foreground);
+    --color-warning: var(--warning);
+    --color-selection: var(--selection);
+    --color-warning-foreground: var(--warning-foreground);
+    --color-accent-foreground: var(--accent-foreground);
+    --color-accent: var(--accent);
+    --color-muted-foreground: var(--muted-foreground);
+    --color-muted: var(--muted);
+    --color-secondary-foreground: var(--secondary-foreground);
+    --color-secondary: var(--secondary);
+    --color-primary-foreground: var(--primary-foreground);
+    --color-primary: var(--primary);
+    --color-popover-foreground: var(--popover-foreground);
+    --color-popover: var(--popover);
+    --color-card-foreground: var(--card-foreground);
+    --color-card: var(--card);
+    --color-foreground: var(--foreground);
+    --color-background: var(--background);
+    --radius-sm: calc(var(--radius) * 0.6);
+    --radius-md: calc(var(--radius) * 0.8);
+    --radius-lg: var(--radius);
+    --radius-xl: calc(var(--radius) * 1.4);
+    --radius-2xl: calc(var(--radius) * 1.8);
+    --radius-3xl: calc(var(--radius) * 2.2);
+    --radius-4xl: calc(var(--radius) * 2.6);
+}
+
+:root {
+    /* Petrol-tinted neutrals; no background or fill is pure white or black (Georg 2026-10-03). */
+    --background: oklch(0.972 0.006 215);
+    --foreground: oklch(0.2 0.012 215);
+    --card: oklch(0.985 0.004 215);
+    --card-foreground: oklch(0.2 0.012 215);
+    --popover: oklch(0.985 0.004 215);
+    --popover-foreground: oklch(0.2 0.012 215);
+    --primary: oklch(0.5 0.085 210);
+    --primary-foreground: oklch(0.97 0.008 215);
+    --secondary: oklch(0.935 0.006 215);
+    --secondary-foreground: oklch(0.25 0.012 215);
+    --muted: oklch(0.935 0.006 215);
+    --muted-foreground: oklch(0.5 0.012 215);
+    --accent: oklch(0.93 0.025 210);
+    --accent-foreground: oklch(0.3 0.05 210);
+    --destructive: oklch(0.55 0.14 27);
+    --destructive-foreground: oklch(0.97 0.008 215);
+    --warning: oklch(0.7 0.12 70);
+    --warning-foreground: oklch(0.25 0.04 70);
+    --border: oklch(0.87 0.008 215);
+    --input: oklch(0.87 0.008 215);
+    --selection: oklch(0.66 0.04 210); /* quieter than primary: selected things, not actions */
+    --ring: oklch(0.5 0.085 210);
+    --chart-1: oklch(0.5 0.085 210);
+    --chart-2: oklch(0.7 0.12 70);
+    --chart-3: oklch(0.62 0.07 180);
+    --chart-4: oklch(0.42 0.05 240);
+    --chart-5: oklch(0.6 0.01 215);
+    --sidebar: oklch(0.955 0.006 215);
+    --sidebar-foreground: oklch(0.2 0.012 215);
+    --sidebar-primary: oklch(0.5 0.085 210);
+    --sidebar-primary-foreground: oklch(0.97 0.008 215);
+    --sidebar-accent: oklch(0.92 0.025 210);
+    --sidebar-accent-foreground: oklch(0.3 0.05 210);
+    --sidebar-border: oklch(0.87 0.008 215);
+    --sidebar-ring: oklch(0.5 0.085 210);
+    --radius: 0.125rem; /* 2px: industrial, not soft SaaS (Georg 2026-10-03; iterating) */
+}
+
+.dark {
+    /* Petrol-tinted neutrals; no background or fill is pure white or black (Georg 2026-10-03). */
+    --background: oklch(0.19 0.01 215);
+    --foreground: oklch(0.93 0.006 215);
+    --card: oklch(0.23 0.012 215);
+    --card-foreground: oklch(0.93 0.006 215);
+    --popover: oklch(0.23 0.012 215);
+    --popover-foreground: oklch(0.93 0.006 215);
+    --primary: oklch(0.68 0.09 205);
+    --primary-foreground: oklch(0.18 0.02 215);
+    --secondary: oklch(0.28 0.012 215);
+    --secondary-foreground: oklch(0.93 0.006 215);
+    --muted: oklch(0.28 0.012 215);
+    --muted-foreground: oklch(0.68 0.012 215);
+    --accent: oklch(0.32 0.04 210);
+    --accent-foreground: oklch(0.93 0.006 215);
+    --destructive: oklch(0.66 0.13 25);
+    --destructive-foreground: oklch(0.18 0.02 215);
+    --warning: oklch(0.76 0.11 70);
+    --warning-foreground: oklch(0.22 0.04 70);
+    --border: oklch(0.32 0.012 215);
+    --input: oklch(0.35 0.012 215);
+    --selection: oklch(0.56 0.045 205);
+    --ring: oklch(0.68 0.09 205);
+    --chart-1: oklch(0.68 0.09 205);
+    --chart-2: oklch(0.76 0.11 70);
+    --chart-3: oklch(0.7 0.07 175);
+    --chart-4: oklch(0.6 0.06 245);
+    --chart-5: oklch(0.55 0.01 215);
+    --sidebar: oklch(0.215 0.012 215);
+    --sidebar-foreground: oklch(0.93 0.006 215);
+    --sidebar-primary: oklch(0.68 0.09 205);
+    --sidebar-primary-foreground: oklch(0.18 0.02 215);
+    --sidebar-accent: oklch(0.3 0.035 210);
+    --sidebar-accent-foreground: oklch(0.93 0.006 215);
+    --sidebar-border: oklch(0.32 0.012 215);
+    --sidebar-ring: oklch(0.68 0.09 205);
+}
+
+@layer base {
+  * {
+    @apply border-border outline-ring/50;
+  }
+  body {
+    @apply bg-background text-foreground;
+  }
+  html {
+    @apply font-sans;
+  }
+
+  /* Make it feel like a native desktop app, not a webpage. */
+  html,
+  body {
+    user-select: none;
+    -webkit-user-select: none;
+    cursor: default;
+    overscroll-behavior: none;
+  }
+
+  /* Restore text selection where typing happens. */
+  input,
+  textarea,
+  [contenteditable] {
+    user-select: text;
+    -webkit-user-select: text;
+  }
+
+  /* Opt-in class for selectable content (filenames, error messages, etc). */
+  .select-text {
+    user-select: text;
+    -webkit-user-select: text;
+  }
+
+  /* No drag-image ghost when grabbing an <img>. */
+  img {
+    -webkit-user-drag: none;
+    user-drag: none;
+  }
+}
+
+/* Selection is a faint tint with a 1px edge; focus is the ring. Never two rings (ux-patterns.md,
+   Georg 2026-10-03). Put `selectable` on a row, card or item and set `data-selected` (or
+   aria-selected="true") on the selected one. The edge is a background gradient, not a border or a
+   shadow, so it never shifts the layout and never competes with a focus ring's box-shadow. */
+@utility selectable {
+  &:is([data-selected], [aria-selected="true"]) {
+    background-color: color-mix(in oklab, var(--selection) 12%, transparent);
+    background-image: linear-gradient(var(--selection), var(--selection));
+    background-size: 1px 100%;
+    background-repeat: no-repeat;
+  }
+}

package/src/index.ts

@@ -0,0 +1,35 @@
+export * from "./components/avatar"
+export * from "./components/badge"
+export * from "./components/breadcrumb"
+export * from "./components/button"
+export * from "./components/card"
+export * from "./components/checkbox"
+export * from "./components/color-field"
+export * from "./components/color-swatch"
+export * from "./components/context-menu"
+export * from "./components/dialog"
+export * from "./components/dropdown-menu"
+export * from "./components/empty-state"
+export * from "./components/input"
+export * from "./components/label"
+export * from "./components/navigation-menu"
+export * from "./components/number-field"
+export * from "./components/popover"
+export * from "./components/select"
+export * from "./components/separator"
+export * from "./components/sheet"
+export * from "./components/side-panel"
+export * from "./components/sidebar"
+export * from "./components/skeleton"
+export * from "./components/slider"
+export * from "./components/snackbar"
+export * from "./components/status-bar"
+export * from "./components/tabs"
+export * from "./components/textarea"
+export * from "./components/toggle"
+export * from "./components/toggle-group"
+export * from "./components/toolbar"
+export * from "./components/tooltip"
+export * as Icons from "./icons"
+export { useIsMobile } from "./lib/use-mobile"
+export { cn } from "./lib/utils"

package/src/lib/use-mobile.ts

@@ -0,0 +1,18 @@
+import * as React from "react"
+
+const MOBILE_BREAKPOINT = 768
+const QUERY = `(max-width: ${MOBILE_BREAKPOINT - 1}px)`
+
+function subscribe(onChange: () => void) {
+  const mql = window.matchMedia(QUERY)
+  mql.addEventListener("change", onChange)
+  return () => mql.removeEventListener("change", onChange)
+}
+
+export function useIsMobile() {
+  return React.useSyncExternalStore(
+    subscribe,
+    () => window.matchMedia(QUERY).matches,
+    () => false,
+  )
+}

package/src/lib/utils.ts

@@ -0,0 +1,6 @@
+import { type ClassValue, clsx } from "clsx"
+import { twMerge } from "tailwind-merge"
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs))
+}