Round dashboards: shape and ring, the ring drawn and turned in every look, Knob preset and face guide in the editor

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Melvin Strobl
2026-10-14 14:23:55 +02:00
co-authored by Claude Opus 5.5
parent f067fb60d4
commit 8b8cb5cda9
21 changed files with 1447 additions and 57 deletions
@@ -0,0 +1,524 @@
import { motion, useTransform } from "motion/react"
import { useEffect, useRef } from "react"
import type { WidgetDef } from "@/client"
import { cn } from "@/lib/utils"
import { canvasOf, type Dashboard, ringOf, widgetsOf } from "./DashboardView"
import { useBoundValue } from "./dataContext"
import { usePublish } from "./publish"
import { LockedProvider } from "./settings"
import {
colorFormatOf,
cssOf,
decodeColor,
encodeColor,
type Triple,
wrap,
} from "./ui/core/color"
import {
config,
format,
fractionOf,
num,
showTitle,
text,
} from "./ui/core/config"
import {
fractionAt,
RING_HANDLE,
RING_INSET,
RING_MARK,
RING_STROKE,
RING_TITLE_RISE,
RING_TITLE_SIZE,
ringArc,
ringPoint,
useRingDraft,
} from "./ui/core/ring"
import { useAnimatedFraction } from "./ui/core/values"
/** How far apart the gap's line may run, centred: inside the face at any size. */
const GAP_WIDTH = 160
/** The centre reading, drawn when the ring is all the dashboard has. */
const CENTRE_VALUE = 72
const CENTRE_LABEL = 36
const CENTRE_SWATCH = 96
/** How much wheel a notch is: what one detent of a mouse wheel reports. */
const WHEEL_NOTCH = 100
/** A key that turns the ring, as a notch would. */
const ARROWS: Record<string, number> = {
ArrowUp: 1,
ArrowRight: 1,
ArrowDown: -1,
ArrowLeft: -1,
}
/** How many strokes the colour ring's hue is drawn in: 2° each. */
const HUE_SEGMENTS = 150
/**
* What one type of ring does with its value.
*
* The value is whatever the type turns — a number, an option's index, a colour
* — and the rest says where it sits along the sweep and how a notch or a
* pointer moves it. No `notch` means a ring that only shows.
*/
type Dial = {
value: unknown
/** Where it sits along the sweep, 0..1; null draws no handle. */
at: (value: unknown) => number | null
notch?: (value: unknown, by: number) => unknown
pick?: (fraction: number, value: unknown) => unknown
/** What it publishes, in the shape the same widget sends from the grid. */
wire: (value: unknown) => unknown
/** Written out; empty for a colour, whose handle is the reading. */
reading: (value: unknown) => string
unit?: string
/** A value arc from the start to the reading: a slider and a gauge. */
fill?: boolean
handle?: boolean
marks?: number[]
hue?: boolean
}
function dialOf(widget: WidgetDef, live: unknown): Dial {
const cfg = config(widget)
const unit = cfg.unit ? text(cfg.unit) : undefined
if (widget.type === "dropdown") {
const options = (cfg.options ?? []) as { label?: string; value?: unknown }[]
const last = options.length - 1
const at = (index: unknown) =>
(index as number) < 0 ? null : last > 0 ? (index as number) / last : 0.5
return {
value: options.findIndex((option) => text(option.value) === text(live)),
at,
// No wrap: the first and last options are the ring's two ends.
notch:
last < 0
? undefined
: (index, by) => Math.min(last, Math.max(0, (index as number) + by)),
pick: (fraction) => Math.round(fraction * last),
wire: (index) =>
options[index as number]?.value ?? options[index as number]?.label,
reading: (index) => {
const option = options[index as number]
return option ? (option.label ?? text(option.value)) : "—"
},
handle: true,
marks: options.map((_, index) => at(index) ?? 0.5),
}
}
if (widget.type === "color") {
const form = colorFormatOf(widget)
const step = num(cfg.hue_step, 5)
// Turning sets the hue alone; saturation and brightness stay what they
// were, or full when nothing has been sent yet.
const hsv: Triple = decodeColor(live, form) ?? [0, 100, 100]
return {
value: hsv,
at: (value) => (value as Triple)[0] / 360,
notch: (value, by) => {
const [h, s, v] = value as Triple
return [wrap(h + by * step), s, v]
},
pick: (fraction, value) => {
const [, s, v] = value as Triple
return [wrap(fraction * 360), s, v]
},
wire: (value) => encodeColor(value as Triple, form),
reading: () => "",
handle: true,
hue: true,
}
}
const min = num(cfg.min, 0)
const max = num(cfg.max, 100)
if (widget.type === "gauge") {
const precision = cfg.precision === undefined ? 1 : num(cfg.precision, 1)
return {
value: typeof live === "number" ? live : null,
at: (value) => fractionOf(value as number | null, min, max),
wire: (value) => value,
reading: (value) => format(value, precision),
unit,
fill: true,
}
}
// A slider. Its value is written to the step's own decimals, as the
// slider in the grid labels its scale.
const step = num(cfg.step, 1) || 1
const digits = (String(step).split(".")[1] ?? "").length
const fit = (value: number) =>
Number(Math.min(max, Math.max(min, value)).toFixed(digits))
return {
value: typeof live === "number" ? live : min,
at: (value) => fractionOf(value as number, min, max),
notch: (value, by) => fit((value as number) + by * step),
pick: (fraction) =>
fit(min + Math.round((fraction * (max - min)) / step) * step),
wire: (value) => value,
reading: (value) => format(value, digits),
unit,
fill: true,
handle: true,
}
}
/**
* A round dashboard's edge: its ring, and what the ring says.
*
* Drawn over the whole face rather than in a cell, at canvas pixels — the
* geometry is in `ui/core/ring.ts`. Nothing for a dashboard without a ring.
* Arranging, a press on the ring picks it as a press on a tile does, and it is
* never locked, for the reason the grid is not.
*/
export function RoundFace({
dashboard,
editing,
selected,
onPick,
}: {
dashboard: Dashboard
editing?: boolean
selected?: boolean
onPick?: (id: string) => void
}) {
const ring = ringOf(dashboard)
if (!ring) return null
const face = (
<Ring
widget={ring}
dashboard={dashboard.name}
size={canvasOf(dashboard).width}
alone={widgetsOf(dashboard).length === 1}
editing={editing}
selected={selected}
onPick={onPick && (() => onPick(ring.id))}
/>
)
return editing ? (
face
) : (
<LockedProvider dashboard={dashboard}>{face}</LockedProvider>
)
}
/**
* One widget, drawn along the edge of a round face.
*
* A slider, a selector, a colour or a gauge — each is one value along a range,
* which is the one thing a knob's ring can set and a circle's edge can show.
* Turned by a drag along it or by the mouse wheel, a notch a step, an option
* or a hue step; the value moves at once and one publish follows once the
* turning stops (`useRingDraft`).
*/
function Ring({
widget,
dashboard,
size,
alone,
editing,
selected,
onPick,
}: {
widget: WidgetDef
dashboard: string
size: number
/** Nothing else on the face: the reading is written large in the middle. */
alone: boolean
editing?: boolean
selected?: boolean
onPick?: () => void
}) {
const { value, send, locked } = usePublish(widget, dashboard)
// A gauge reads its message rather than publishing to a target.
const message = text(config(widget).message)
const bound = useBoundValue(widget.type === "gauge" ? message : undefined)
const dial = dialOf(widget, widget.type === "gauge" ? bound?.value : value)
const { current, latest, move, commit } = useRingDraft(dial.value, (next) =>
send(dial.wire(next)),
)
const svg = useRef<SVGSVGElement>(null)
const face = useRef<HTMLDivElement>(null)
const spin = useRef(0)
const turns = Boolean(dial.notch) && !locked
const at = dial.at(current)
const animated = useAnimatedFraction(at ?? 0)
const shown = useTransform(animated, (fraction) => (fraction > 0 ? 1 : 0))
const turn = (by: number) => {
if (turns && dial.notch) move(dial.notch(latest(), by), true)
}
// On the whole face rather than the ring: a knob turns wherever it is held.
// Up — away from you — is clockwise, which is up the scale.
const onWheel = useRef<(event: WheelEvent) => void>(() => {})
onWheel.current = (event) => {
spin.current += event.deltaMode === 1 ? event.deltaY * 33 : event.deltaY
if (Math.abs(spin.current) < WHEEL_NOTCH / 2) return
const notches = Math.max(
1,
Math.round(Math.abs(spin.current) / WHEEL_NOTCH),
)
turn(spin.current < 0 ? notches : -notches)
spin.current = 0
}
useEffect(() => {
const canvas = face.current?.parentElement
const listener = (event: WheelEvent) => onWheel.current(event)
canvas?.addEventListener("wheel", listener, { passive: true })
return () => canvas?.removeEventListener("wheel", listener)
}, [])
const aim = (event: React.PointerEvent) => {
const box = svg.current?.getBoundingClientRect()
if (!box || !dial.pick) return
move(
dial.pick(
fractionAt(
event.clientX - (box.left + box.width / 2),
event.clientY - (box.top + box.height / 2),
),
latest(),
),
false,
)
}
const title = showTitle(widget) ? widget.title || "" : ""
const reading = dial.reading(current)
const handle = dial.handle && at !== null ? ringPoint(size, at) : null
const whole = ringArc(size, 0, 1)
const name = widget.title || text(config(widget).target, widget.id)
return (
<div
ref={face}
className="pointer-events-none absolute inset-0"
data-testid="ring"
>
{/* biome-ignore lint/a11y/noSvgWithoutTitle: named by `aria-label` in the role spread below, which the rule cannot see. */}
<svg
ref={svg}
width={size}
height={size}
className="dui-ring absolute inset-0"
// A control that turns, or a reading that only shows.
{...(dial.notch
? {
role: "slider",
"aria-label": name,
"aria-valuetext": `${reading}${dial.unit ?? ""}` || undefined,
"aria-valuenow":
typeof current === "number" ? current : undefined,
"aria-disabled": locked || undefined,
}
: {
role: "img",
"aria-label": `${name}: ${reading}${dial.unit ?? ""}`,
})}
tabIndex={turns ? 0 : undefined}
onKeyDown={(event) => {
const by = ARROWS[event.key]
if (!by || !turns) return
event.preventDefault()
turn(by)
}}
>
<path
d={whole}
fill="none"
strokeWidth={RING_STROKE + 8}
strokeLinecap="round"
className="dui-ring-focus"
/>
<g className={cn("dui-ring-arc", locked && "opacity-45")}>
{dial.hue ? (
<HueTrack size={size} />
) : (
<path
d={whole}
fill="none"
strokeWidth={RING_STROKE}
strokeLinecap="round"
className="dui-ring-track"
/>
)}
{/* A slider's reading follows the hand, so it is drawn where it
is. A gauge eases to its reading, revealed rather than re-pathed
as the gauge tile's arc is, and transparent at the minimum where
its round caps would still paint a dot. */}
{dial.fill && dial.notch && at ? (
<path
d={ringArc(size, 0, at)}
fill="none"
strokeWidth={RING_STROKE}
strokeLinecap="round"
className="dui-ring-fill"
/>
) : dial.fill && !dial.notch ? (
<motion.path
d={whole}
fill="none"
strokeWidth={RING_STROKE}
strokeLinecap="round"
className="dui-ring-fill"
style={{ pathLength: animated, opacity: shown }}
/>
) : null}
{dial.marks?.map((mark, index) => {
const point = ringPoint(size, mark)
return (
<circle
// Two options may share a label; position is the identity.
key={`mark-${index}`}
cx={point.x}
cy={point.y}
r={RING_MARK / 2}
className="dui-ring-mark"
/>
)
})}
{handle ? (
<circle
cx={handle.x}
cy={handle.y}
r={RING_HANDLE / 2}
className={cn("dui-ring-handle", dial.hue && "dui-ring-swatch")}
style={dial.hue ? { fill: cssOf(current as Triple) } : undefined}
/>
) : null}
</g>
{selected ? (
<path
d={whole}
fill="none"
strokeWidth={RING_INSET}
className="stroke-primary opacity-15"
/>
) : null}
{turns || editing ? (
<path
d={whole}
fill="none"
stroke="transparent"
strokeWidth={RING_INSET}
className="dui-ring-hit"
data-testid="ring-hit"
onPointerDown={(event) => {
if (editing) {
onPick?.()
return
}
event.currentTarget.setPointerCapture(event.pointerId)
aim(event)
}}
onPointerMove={(event) => {
if (event.currentTarget.hasPointerCapture(event.pointerId)) {
aim(event)
}
}}
// Every way a drag can end publishes, as the grid's slider does:
// a browser taking the gesture over ends it in a cancel.
onPointerUp={commit}
onPointerCancel={commit}
onLostPointerCapture={commit}
/>
) : null}
</svg>
{/* The gap at the bottom: the title, and the reading unless it is
already written large in the middle. */}
<div
className="absolute flex items-center justify-center gap-1.5 whitespace-nowrap"
style={{
left: size / 2 - GAP_WIDTH / 2,
width: GAP_WIDTH,
top: size - RING_TITLE_RISE - RING_TITLE_SIZE,
height: RING_TITLE_SIZE * 2,
fontSize: RING_TITLE_SIZE,
}}
>
{title ? (
<span className="min-w-0 truncate text-muted-foreground">
{title}
</span>
) : null}
{!alone && reading ? (
<span className="shrink-0 tabular-nums">
{reading}
{dial.unit ?? ""}
</span>
) : null}
</div>
{alone ? (
<div className="absolute inset-0 flex items-center justify-center">
{dial.hue ? (
<span
data-testid="ring-centre"
className="rounded-full border border-border"
style={{
width: CENTRE_SWATCH,
height: CENTRE_SWATCH,
background: cssOf(current as Triple),
}}
/>
) : (
<span
data-testid="ring-centre"
className="flex items-baseline gap-1 leading-none tabular-nums"
style={{
fontSize:
widget.type === "dropdown" ? CENTRE_LABEL : CENTRE_VALUE,
}}
>
{reading}
{dial.unit ? (
<span className="text-[0.4em] text-muted-foreground">
{dial.unit}
</span>
) : null}
</span>
)}
</div>
) : null}
</div>
)
}
/**
* The colour ring's track: every hue in order along the sweep, red at both
* ends. Drawn as short strokes — an SVG stroke takes no conic gradient — each
* a hair longer than its share so no seam shows between two.
*/
function HueTrack({ size }: { size: number }) {
return (
<>
{Array.from({ length: HUE_SEGMENTS }, (_, index) => {
const from = index / HUE_SEGMENTS
const to = Math.min(1, (index + 1.5) / HUE_SEGMENTS)
const end = index === 0 || index === HUE_SEGMENTS - 1
return (
<path
// A fixed run of strokes; the index is the identity.
key={`hue-${index}`}
d={ringArc(size, from, to)}
fill="none"
strokeWidth={RING_STROKE}
strokeLinecap={end ? "round" : "butt"}
stroke={`hsl(${((index + 0.5) / HUE_SEGMENTS) * 360} 100% 50%)`}
/>
)
})}
</>
)
}