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
@@ -3,23 +3,34 @@
*
* A 240° arc starting at the lower left, which is the shape a gauge is
* expected to have. Both looks draw the same sweep; only the stroke differs.
*
* Angles are degrees clockwise from three o'clock. A round dashboard's ring
* (`ring.ts`) draws with the same function, on a circle of its own.
*/
export const GAUGE_SWEEP = 240
export const GAUGE_START = 150
const RADIUS = 42
const point = (angle: number) => {
const point = (angle: number, radius: number, centre: number) => {
const radians = (angle * Math.PI) / 180
return [50 + RADIUS * Math.cos(radians), 50 + RADIUS * Math.sin(radians)]
return [
centre + radius * Math.cos(radians),
centre + radius * Math.sin(radians),
]
}
/** One arc of the dial, as an SVG path in a `0 0 100 78` box. */
export function arcPath(from: number, to: number): string {
const [x1, y1] = point(from)
const [x2, y2] = point(to)
/** One arc of the dial, as an SVG path — by default in a `0 0 100 78` box. */
export function arcPath(
from: number,
to: number,
radius = RADIUS,
centre = 50,
): string {
const [x1, y1] = point(from, radius, centre)
const [x2, y2] = point(to, radius, centre)
const large = Math.abs(to - from) > 180 ? 1 : 0
return `M ${x1} ${y1} A ${RADIUS} ${RADIUS} 0 ${large} 1 ${x2} ${y2}`
return `M ${x1} ${y1} A ${radius} ${radius} 0 ${large} 1 ${x2} ${y2}`
}
/** The whole track, which the reading is drawn over a fraction of. */
@@ -542,3 +542,88 @@
text-align: left;
}
}
/*
* A round dashboard (`data-shape="round"` on the canvas).
*
* A circle has no corners for a card to sit in, so a tile drops the surface
* its look paints and keeps only what it shows: no fill, no border, no shadow,
* a smaller muted title and half the padding. A face is read about its
* vertical axis, so a title and a single reading are centred on it. Arranging,
* a dashed hairline still says where each tile is.
*/
[data-shape="round"] .dui-frame {
border-color: transparent;
background: none;
box-shadow: none;
backdrop-filter: none;
-webkit-backdrop-filter: none;
padding: 0.5rem;
}
/* Glass's light along the pane's top edge, which has no pane to fall on. */
[data-shape="round"] .dui-frame::before {
content: none;
}
[data-shape="round"] .dui-frame-head,
[data-shape="round"] .dui-frame-body > [data-testid="readout"] {
justify-content: center;
}
[data-shape="round"] .dui-frame-title {
font-size: 0.75rem;
}
[data-shape="round"][data-arranging] .dui-frame {
border: 1px dashed
color-mix(in srgb, var(--muted-foreground) 40%, transparent);
}
/*
* The ring along a round face's edge (`RingWidget.tsx`). Its geometry is in
* `ring.ts`; each look paints the track, the reading and the handle.
* Only the band itself takes a pointer, so the tiles inside stay pressable.
*/
.dui-ring {
overflow: visible;
outline: none;
}
.dui-ring-hit {
pointer-events: stroke;
cursor: pointer;
/* The drag is the control, for the reason the slider's input says. */
touch-action: none;
}
.dui-ring[aria-disabled] .dui-ring-hit {
cursor: default;
}
.dui-ring-focus {
stroke: color-mix(in srgb, var(--ring) 50%, transparent);
opacity: 0;
}
.dui-ring:focus-visible .dui-ring-focus {
opacity: 1;
}
.dui-ring-mark {
fill: var(--muted-foreground);
}
/* Page dots in the ring's gap, where a rect dashboard has its rail. */
.dui-dot-mark {
width: 6px;
height: 6px;
border-radius: 50%;
background: var(--muted-foreground);
opacity: 0.5;
}
.dui-dot[aria-current="page"] .dui-dot-mark {
background: var(--foreground);
opacity: 1;
}
@@ -0,0 +1,113 @@
/**
* A round dashboard's ring: where it runs, and what turning it does.
*
* Everything is in canvas pixels on a face whose diameter `size` is the
* canvas width, and scales with the canvas as the grid's gap does. Angles are
* degrees clockwise from three o'clock — what `arc.ts` and LVGL both use — so
* a device drawing the same dashboard natively ports these numbers as they
* stand. `app/docs/interface/dashboards.md` lists them for that purpose.
*/
import { useEffect, useRef, useState } from "react"
import { arcPath } from "./arc"
/** The band along the face's edge the ring takes; the grid is inset by it. */
export const RING_INSET = 40
/** Where the sweep begins: the lower left. */
export const RING_START = 120
/** Leaves a 60° gap centred at the bottom, which holds the title. */
export const RING_SWEEP = 300
/** The track's and the reading's stroke. */
export const RING_STROKE = 16
/** The handle's diameter. */
export const RING_HANDLE = 28
/** A dropdown's option marks, as a diameter. */
export const RING_MARK = 6
/** How long the ring waits after the last notch before it publishes. */
export const RING_SETTLE_MS = 300
/** The gap's line — title, then the reading — centred this far above the
* bottom of the face, at this size. */
export const RING_TITLE_RISE = 28
export const RING_TITLE_SIZE = 13
/** The ring's centre line, on a face of diameter `size`. */
export const ringRadius = (size: number) => size / 2 - RING_INSET / 2
/** An arc of the ring from `from` to `to`, both fractions of the sweep. */
export const ringArc = (size: number, from: number, to: number) =>
arcPath(
RING_START + from * RING_SWEEP,
RING_START + to * RING_SWEEP,
ringRadius(size),
size / 2,
)
/** A point on the ring's centre line, `at` a fraction along the sweep. */
export function ringPoint(size: number, at: number) {
const radians = ((RING_START + at * RING_SWEEP) * Math.PI) / 180
const radius = ringRadius(size)
return {
x: size / 2 + radius * Math.cos(radians),
y: size / 2 + radius * Math.sin(radians),
}
}
/**
* How far along the sweep a pointer is, from its offset to the face's centre.
*
* In the gap it snaps to the nearer end, so a drag carried past either end
* holds there rather than jumping across to the other.
*/
export function fractionAt(dx: number, dy: number): number {
const angle = (Math.atan2(dy, dx) * 180) / Math.PI
const along = (((angle - RING_START) % 360) + 360) % 360
if (along <= RING_SWEEP) return along / RING_SWEEP
return along < (360 + RING_SWEEP) / 2 ? 1 : 0
}
/**
* Turning a ring: the value moves at once, and one publish follows.
*
* A notch — a wheel, an arrow key, an encoder's detent — moves the draft and
* restarts a `RING_SETTLE_MS` wait; a drag moves it until the pointer lets go.
* Either way exactly one value is sent, the one the ring came to rest on, so a
* fast turn is not a burst of publishes for a lamp to stutter through. Without
* a draft the ring follows the engine, through the caller's hold-until-echo.
*/
export function useRingDraft<T>(value: T, send: (value: T) => void) {
const [draft, setDraft] = useState<{ value: T } | null>(null)
// Read between renders: notches arrive faster than React draws, and each
// one steps from the last rather than from what was last drawn.
const pending = useRef<{ value: T } | null>(null)
const timer = useRef<ReturnType<typeof setTimeout> | null>(null)
const sender = useRef(send)
sender.current = send
const commit = () => {
if (timer.current) clearTimeout(timer.current)
timer.current = null
const next = pending.current
pending.current = null
setDraft(null)
if (next) sender.current(next.value)
}
// A turn still settling when the ring goes away is sent rather than lost.
// biome-ignore lint/correctness/useExhaustiveDependencies: on unmount only.
useEffect(() => commit, [])
return {
current: draft ? draft.value : value,
/** The value a further notch steps from. */
latest: () => (pending.current ? pending.current.value : value),
/** Move the draft; `settle` publishes once nothing has moved it for a while. */
move: (next: T, settle: boolean) => {
pending.current = { value: next }
setDraft({ value: next })
if (timer.current) clearTimeout(timer.current)
timer.current = settle ? setTimeout(commit, RING_SETTLE_MS) : null
},
/** Publish the draft now: the pointer let go. */
commit,
}
}
@@ -315,3 +315,26 @@
outline: none;
box-shadow: 0 0 0 3px color-mix(in srgb, var(--ring) 50%, transparent);
}
/* --- a round dashboard's ring -------------------------------------------- */
[data-look="fluksio"] .dui-ring-track {
stroke: var(--muted);
}
[data-look="fluksio"] .dui-ring-fill {
stroke: var(--primary);
}
/* The slider's handle: a ring of primary around the page colour. */
[data-look="fluksio"] .dui-ring-handle {
fill: var(--background);
stroke: var(--primary);
stroke-width: 2px;
filter: drop-shadow(0 1px 2px rgb(0 0 0 / 0.2));
}
[data-look="fluksio"] .dui-ring-swatch {
stroke: var(--card);
stroke-width: 3px;
}
@@ -415,3 +415,27 @@
outline: 2px solid var(--ring);
outline-offset: 2px;
}
/* --- a round dashboard's ring -------------------------------------------- */
[data-look="glass"] .dui-ring-track {
stroke: var(--gl-track);
}
/* Lit, as the gauge's arc is. */
[data-look="glass"] .dui-ring-fill {
stroke: var(--primary);
filter: drop-shadow(0 0 4px var(--primary));
}
[data-look="glass"] .dui-ring-handle {
fill: #fff;
stroke: var(--gl-border);
stroke-width: 1px;
filter: drop-shadow(0 2px 8px rgb(0 0 0 / 0.35));
}
[data-look="glass"] .dui-ring-swatch {
stroke: rgb(255 255 255 / 0.85);
stroke-width: 2px;
}
@@ -319,3 +319,22 @@
outline: 2px solid var(--primary);
outline-offset: 2px;
}
/* --- a round dashboard's ring -------------------------------------------- */
[data-look="material"] .dui-ring-track {
stroke: var(--m3-sc);
}
[data-look="material"] .dui-ring-fill {
stroke: var(--primary);
}
[data-look="material"] .dui-ring-handle {
fill: var(--primary);
}
[data-look="material"] .dui-ring-swatch {
stroke: var(--card);
stroke-width: 3px;
}