# XWUIRadialRing One circular geometry for two jobs (plnx REF_06 C11). **Display**: a cycle (a year of days, a day of 24 hours, any period) with labelled periods, arcs on lanes, phase colours, a hand, milestone and deadline buttons, dots orbiting the hub by progress, demand spokes, and a centre readout or a page-filled centre slot. **Select**: a ring of equal sectors, or a 180 or 240 degree dial with stops, as a radiogroup that turns the choice to a pointer, with an optional tour; `readOnly` makes it a gauge. It absorbs the PX-Cycle radial calendar (S-G05) and the web CycleRing and RadialSelector (Solutions role wheel, Projects depth dial, AI autonomy gauge, ForOps 24 hour clock). It composes the basic tier's `_shared/playback` (the tour clock), `hostSlots` (the centre), `XWUIIcon` (sector and marker glyphs) and the style tier's hue and status tokens. ## Basic Usage ```example file: examples/BasicUsage.ts html: examples/BasicUsage.html title: Basic Usage description: A planning year as a ring: stages on a lane, today's hand, a milestone, two departments orbiting by progress. ``` ```example file: examples/RoleWheel.ts html: examples/RoleWheel.html title: Role Wheel description: A select ring that turns the chosen role to the pointer, with a tour that stops when the reader picks. ``` ```example file: examples/DepthDial.ts html: examples/DepthDial.html title: Depth Dial description: A 180 degree dial with three stops; the read-only form is a gauge. ``` ```example file: examples/ShiftClock.ts html: examples/ShiftClock.html title: Shift Clock description: A 24 hour ring with shift bands, demand spokes and the hand at now. ``` ## Data | Field | Shape | Notes | | --- | --- | --- | | `domain` | `{ length, start?, labels: { at, label, sub? }[], labelAt?: 'middle' \| 'start' }` | display. Labels sit mid-period (months) or on their own position (hours). Consecutive labels draw the alternating period band; the period holding the first hand is highlighted. | | `arcs` | `{ id, from, to, lane?, label?, hue?, phase?, status?, badge?, count?, dashed? }[]` | `to < from` wraps (22 to 6). `status` `done`/`past` fades, `active`/`current` carries a moving flow line. Lane 0 is outermost. | | `markers` | `{ id, at, kind: 'hand' \| 'milestone' \| 'deadline' \| 'icon', label, icon? }[]` | A hand is a line plus the elapsed arc; it speaks through the summary. Milestones are numbered circles, deadlines diamonds. | | `orbiters` | `{ id, label, initials?, progress, status?, hue? }[]` | progress 0..1 (or percent): 0 rides lane 0, 1 sits at the hub. | | `spokes` | `{ at, value, state: 'covered' \| 'short' }[]` | Length by value; short spokes are dashed and listed in the summary. | | `sectors` | `{ id, label, icon?, hue?, description?, disabled? }[]` | select. | | `value` | `string \| null` | select: the chosen sector (host-owned). | | `selectedId` | `string \| null` | display: the pressed control. | | `highlight` | `string[] \| null` | Everything else dims. | | `status` | `'ready' \| 'loading' \| 'error'` | Skeleton ring with a status line, or an alert. | Hues are token NAMES (`teal`, `indigo`, `purple`, `sky`, `fuchsia`, `rose`, `slate`, `yellow` exist in every theme; status names `ok`, `info`, `warn`, `error`, `neutral`, `accent` and health names `on-track`, `at-risk`, `off-track` also work). A host may declare more `--xwui-hue-` tokens. ## Options | Option | Default | What it does | | --- | --- | --- | | `semantics` | `'display'` | `'select'` makes a radiogroup. | | `shape` | `'ring'` | `'dial'` (select only): stops on an arc with a needle. | | `sweep` | 360 (ring), 180 (dial) | 360, 240 or 180. | | `startAngle` | 0 | Degrees clockwise from the top: the domain start, sector 0's centre, or the dial's centre. | | `rotate` | `'none'` | `'to-selection'` turns the chosen sector to the pointer the short way round; `'continuous'` also lets orbiters drift (225 s a turn). | | `readOnly` | false | Nothing is operable: display is an image with a text summary, select is a gauge. | | `lanes` | highest lane + 1 | Lane count (1 to 8). | | `centreSlot` | false | An empty host-owned centre; fill it with `setCentreSlot(fill)`. | | `mirrorInRtl` | false | Reflect the drawing under RTL (the Projects dial). Clocks and calendars keep false. | | `tour` | none | `{ intervalMs }` (at least 1500): select advances one sector per interval. | | `listTwin` | `'compact'` | `'always'`, `'compact'` (below `compactBelow`), `'hidden'`. | | `compactBelow` | 480 | Container width in px for the compact list. | | `ariaLabel` | `xwui.radial_ring.aria_label` | Name of the figure or radiogroup. | | `dialFill` | `'single'` | `'cumulative'` lights every stop up to the choice. | | `labels` | locale pack | Copy overrides: `ariaLabel`, `empty`, `loading`, `error`, `range`, `span`, `at`, `progress`, `spokes`, `spokeShort`, `pauseMotion`, `playMotion`, `list`. | | `locale`, `numberingSystem` | page language, `'latn'` | Number formatting. | CSS knobs: `--xwui-radial-ring-inline-size`, `--xwui-radial-ring-max-size` (34rem), `--xwui-radial-ring-turn`, `--xwui-radial-ring-drift`, `--xwui-radial-ring-band`, `--xwui-radial-ring-surface`. Inside a `.xwui-night` scope the ring takes the scene palette (PX-Cycle's night-sky look). ## Events and methods Logic events: `select { id, source }` (source `pointer`, `keyboard`, `tour`, `api`), `preview { id | null }`, `valueChange { value }` (the spec's `change`; the base map owns `change`), `tourChange { running }`. The host element receives DOM `select`, `preview`, `tourChange`, and `input` + `change` (detail `{ value }`) for a choice. Methods: `select(id)`, `getValue()`, `getSelectedId()`, `setFormatAt(fn)` (text of a domain position: dates, hours; trusted code), `setCentreSlot(fill)`, `getCentreSlot()`, `playTour()`, `stopTour()`, `toggleMotion()`, `onSelect`, `onPreview`, `onChange`, `onTourChange`, `updateData`, `setData`, `updateConfig`, `getElement`, `destroy`. Static `XWUIRadialRing.projectView(data, config, context)` composes a still render into a parent tree (no icons, no slot fill). The fifth constructor argument is the seam `{ clock, environment, matchMedia }`. ## Accessibility and RTL - Select: `role="radiogroup"` of `role="radio"` labels with a roving tab stop; arrows move AND choose (WAI-ARIA radios), disabled sectors are skipped, Home and End jump, Space and Enter choose. Labels never rotate: they slide along their circle while the wheel turns. Hover previews into the centre readout and holds the tour; focus inside holds it too; a reader's own choice ends it; the visible Pause / Play control satisfies WCAG 2.2.2. - Display: arcs (through their badge), milestones, deadlines and dots are buttons named with their dates ("Department submissions: 1 Sept to 29 Oct", "Operations: drafting, 62%"), `aria-pressed`, one tab stop, DOM order follows time. The hand and the spokes speak through a summary the figure is described by. Hit areas are 48px (`--xwui-size-lg`). - The list twin repeats every control in words; when it shows (always, or below `compactBelow`) the drawing is `aria-hidden` and pointer-only, so nothing is announced twice. - Read-only: `role="img"` with the value in its name. - Colour is never alone: pressed controls change size and outline, past arcs fade, deadlines are diamonds, short spokes are dashed, the list states everything in words. - The figure is a `dir="ltr"` island: a clock runs clockwise in Arabic too. `mirrorInRtl` reflects the drawing and swaps the horizontal arrow keys; the list twin follows the reading direction. Direction is read from the PARENT `dir`. - Reduced motion: no tour autoplay, no drift, no flow, no transition (CSS media query and the JS `--still` class). ```api ```