expo-interface 0.1.1 → 0.3.0

package/src/gauge/gauge.css

@@ -0,0 +1,200 @@
+/*
+ * SwiftUI gauge styles redrawn on web. Sizes are the points measured from
+ * iOS (see shared.ts); the unfilled tracks are iOS `tertiarySystemFill`
+ * (automatic) and `systemFill` (linearCapacity), which `light-dark()`
+ * resolves per scheme.
+ */
+.ui-gauge,
+.ui-gauge-ring {
+  --ui-gauge-accent: var(--color-tint);
+  --ui-gauge-knockout: var(--color-background);
+  --ui-gauge-track: light-dark(rgba(118, 118, 128, 0.12), rgba(118, 118, 128, 0.24));
+  --ui-gauge-fill-track: light-dark(rgba(120, 120, 128, 0.2), rgba(120, 120, 128, 0.36));
+  box-sizing: border-box;
+  font-family: var(--font-display);
+  font-size: 17px;
+  line-height: 22px;
+  color: var(--color-label);
+}
+
+.ui-gauge {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  width: 100%;
+}
+
+.ui-gauge__label {
+  color: var(--color-label);
+}
+
+.ui-gauge__bound,
+.ui-gauge__current {
+  color: var(--ui-gauge-accent);
+  white-space: nowrap;
+}
+
+.ui-gauge__row {
+  display: flex;
+  flex-direction: row;
+  align-items: center;
+  gap: 8px;
+  width: 100%;
+}
+
+.ui-gauge__track {
+  position: relative;
+  display: block;
+  flex: 1;
+  min-width: 0;
+  border-radius: 999px;
+  overflow: hidden;
+}
+
+.ui-gauge__fill {
+  display: block;
+  height: 100%;
+  border-radius: 999px;
+  background: var(--ui-gauge-accent);
+}
+
+/* automatic: thick capacity bar, label centered above, value centered below */
+.ui-gauge--automatic .ui-gauge__label {
+  margin-bottom: 14px;
+}
+
+.ui-gauge--automatic .ui-gauge__track {
+  height: 15px;
+  background: var(--ui-gauge-track);
+}
+
+.ui-gauge--automatic .ui-gauge__current {
+  margin-top: 9px;
+}
+
+/* linear (accessoryLinear): tinted bar with a knocked-out point marker */
+.ui-gauge--linear {
+  flex-direction: row;
+  gap: 8px;
+}
+
+/* The track is as tall as the marker so the knockout can overhang the bar. */
+.ui-gauge--linear .ui-gauge__track {
+  height: 15px;
+  border-radius: 0;
+  overflow: visible;
+}
+
+.ui-gauge--linear .ui-gauge__track::before {
+  content: '';
+  position: absolute;
+  inset: 3.75px 0;
+  border-radius: 999px;
+  background: var(--ui-gauge-accent);
+}
+
+.ui-gauge__marker {
+  position: absolute;
+  top: 50%;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 15px;
+  height: 15px;
+  border-radius: 50%;
+  background: var(--ui-gauge-knockout);
+  transform: translate(-50%, -50%);
+}
+
+.ui-gauge__dot {
+  width: 7.5px;
+  height: 7.5px;
+  border-radius: 50%;
+  background: var(--ui-gauge-accent);
+}
+
+/*
+ * linearCapacity (accessoryLinearCapacity): thin bar in a label/bar/value
+ * stack. The grid columns and rows are set inline per rendered label.
+ */
+.ui-gauge--linear-capacity {
+  display: grid;
+  align-items: center;
+  column-gap: 8px;
+  row-gap: 4px;
+}
+
+.ui-gauge--linear-capacity .ui-gauge__label,
+.ui-gauge--linear-capacity .ui-gauge__current {
+  justify-self: start;
+}
+
+.ui-gauge--linear-capacity .ui-gauge__track {
+  height: 4px;
+  background: var(--ui-gauge-fill-track);
+}
+
+.ui-gauge--linear-capacity .ui-gauge__current {
+  font-size: 12px;
+  line-height: 16px;
+}
+
+/* circular styles: 58pt ring drawn in SVG with HTML labels over it */
+.ui-gauge-ring {
+  position: relative;
+  flex-shrink: 0;
+  display: inline-block;
+}
+
+.ui-gauge-ring__svg {
+  position: absolute;
+  inset: 0;
+  display: block;
+}
+
+.ui-gauge-ring__arc,
+.ui-gauge-ring__fill {
+  stroke: var(--ui-gauge-accent);
+}
+
+.ui-gauge-ring__track {
+  stroke: var(--ui-gauge-accent);
+  opacity: 0.3;
+}
+
+.ui-gauge-ring__knockout {
+  fill: var(--ui-gauge-knockout);
+}
+
+.ui-gauge-ring__dot {
+  fill: var(--ui-gauge-accent);
+}
+
+.ui-gauge-ring__center {
+  position: absolute;
+  inset: 0;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  font-size: 24px;
+  line-height: 29px;
+  color: var(--ui-gauge-accent);
+  white-space: nowrap;
+}
+
+.ui-gauge-ring__center--label {
+  color: var(--color-label);
+}
+
+/* Centered 17px below the ring center (29 + 17 - half the 12px line). */
+.ui-gauge-ring__bounds {
+  position: absolute;
+  top: 40px;
+  left: 12px;
+  display: flex;
+  justify-content: space-between;
+  width: 34px;
+  font-size: 10px;
+  line-height: 12px;
+  color: var(--ui-gauge-accent);
+}

package/src/gauge/index.android.tsx

@@ -0,0 +1,212 @@
+import type {GaugeProps} from './types';
+import type {ModifierConfig} from '@expo/ui/jetpack-compose/modifiers';
+
+import {useColorScheme} from 'react-native';
+import {Box, CircularProgressIndicator, Column, Row, Spacer, Text, useMaterialColors} from '@expo/ui/jetpack-compose';
+import {
+  alpha,
+  background,
+  clip,
+  fillMaxHeight,
+  fillMaxWidth,
+  height,
+  offset,
+  padding,
+  rotate,
+  Shapes,
+  size,
+  testID as testIDModifier,
+  weight,
+  width,
+} from '@expo/ui/jetpack-compose/modifiers';
+import {useColor} from '../theme';
+import {fraction, gauge, markerOffset, track, withAlpha} from './shared';
+
+const pill = Shapes.RoundedCorner(999);
+const circle = Shapes.Circle;
+const body = {fontSize: gauge.fontSize, lineHeight: gauge.lineHeight};
+
+/**
+ * Android redraws each SwiftUI gauge style out of Compose primitives (the
+ * rings are Material 3 `CircularProgressIndicator`s, the bars clipped
+ * `Box`es) with the geometry measured from iOS. The live accent seed tints
+ * the indicator and the value labels, matching the iOS tint cascade; the
+ * descriptive label keeps the surface text color.
+ */
+export function Gauge({
+  value,
+  min = 0,
+  max = 1,
+  variant = 'automatic',
+  label,
+  currentValueLabel,
+  minimumValueLabel,
+  maximumValueLabel,
+  accentColor,
+  testID,
+}: GaugeProps) {
+  const colors = useMaterialColors();
+  const scheme = useColorScheme() === 'dark' ? 'dark' : 'light';
+  const tint = useColor('tint');
+  const knockout = useColor('background');
+  const accent = accentColor ?? tint;
+  const f = fraction(value, min, max);
+  const testMods: ModifierConfig[] = testID ? [testIDModifier(testID)] : [];
+
+  const minText = minimumValueLabel != null
+    ? <Text color={accent} style={body}>{minimumValueLabel}</Text>
+    : null;
+  const maxText = maximumValueLabel != null
+    ? <Text color={accent} style={body}>{maximumValueLabel}</Text>
+    : null;
+
+  if (variant === 'circular' || variant === 'circularCapacity') {
+    const {size: ring, stroke} = gauge.ring;
+    const center = currentValueLabel ?? label;
+    const marker = markerOffset(f);
+    return (
+      <Box contentAlignment="center" modifiers={[size(ring, ring), ...testMods]}>
+        {variant === 'circular' ? (
+          <CircularProgressIndicator
+            progress={gauge.ring.arcSweep / 360}
+            color={accent}
+            trackColor="#00000000"
+            strokeWidth={stroke}
+            strokeCap="round"
+            gapSize={0}
+            modifiers={[size(ring, ring), rotate(gauge.ring.arcStart - 270)]}
+          />
+        ) : (
+          <CircularProgressIndicator
+            progress={f}
+            color={accent}
+            trackColor={withAlpha(accent, gauge.ring.trackOpacity)}
+            strokeWidth={stroke}
+            strokeCap="round"
+            gapSize={0}
+            modifiers={[size(ring, ring)]}
+          />
+        )}
+        {variant === 'circular' ? (
+          <Box
+            contentAlignment="center"
+            modifiers={[
+              offset(marker.x, marker.y),
+              size(gauge.ring.knockout, gauge.ring.knockout),
+              clip(circle),
+              background(knockout),
+            ]}>
+            <Box modifiers={[size(gauge.ring.dot, gauge.ring.dot), clip(circle), background(accent)]}/>
+          </Box>
+        ) : null}
+        {center != null ? (
+          <Text
+            color={currentValueLabel != null ? accent : colors.onSurface}
+            style={{fontSize: gauge.ring.centerFontSize, lineHeight: gauge.ring.centerLineHeight}}>
+            {center}
+          </Text>
+        ) : null}
+        {variant === 'circular' && (minText || maxText) ? (
+          <Row
+            horizontalArrangement="spaceBetween"
+            verticalAlignment="center"
+            modifiers={[offset(0, gauge.ring.boundsOffset), width(gauge.ring.boundsWidth)]}>
+            {minimumValueLabel != null ? (
+              <Text color={accent} style={{fontSize: gauge.ring.boundsFontSize, lineHeight: gauge.ring.boundsLineHeight}}>
+                {minimumValueLabel}
+              </Text>
+            ) : <Spacer/>}
+            {maximumValueLabel != null ? (
+              <Text color={accent} style={{fontSize: gauge.ring.boundsFontSize, lineHeight: gauge.ring.boundsLineHeight}}>
+                {maximumValueLabel}
+              </Text>
+            ) : <Spacer/>}
+          </Row>
+        ) : null}
+      </Box>
+    );
+  }
+
+  if (variant === 'linear') {
+    const {bar, dot, knockout: knock} = gauge.linear;
+    return (
+      <Row verticalAlignment="center" horizontalArrangement={{spacedBy: gauge.rowGap}} modifiers={[fillMaxWidth(), ...testMods]}>
+        {minText}
+        <Box contentAlignment="centerStart" modifiers={[weight(1), height(knock)]}>
+          <Box modifiers={[fillMaxWidth(), height(bar), clip(pill), background(accent)]}/>
+          <Box modifiers={[fillMaxWidth(), fillMaxHeight(), padding(dot / 2, 0, dot / 2, 0)]}>
+            <Box contentAlignment="centerEnd" modifiers={[fillMaxWidth(f), fillMaxHeight()]}>
+              <Box
+                contentAlignment="center"
+                modifiers={[offset(knock / 2, 0), size(knock, knock), clip(circle), background(knockout)]}>
+                <Box modifiers={[size(dot, dot), clip(circle), background(accent)]}/>
+              </Box>
+            </Box>
+          </Box>
+        </Box>
+        {maxText}
+      </Row>
+    );
+  }
+
+  if (variant === 'linearCapacity') {
+    const {bar, gap} = gauge.linearCapacity;
+    // Invisible copy of the bounds label so the stacked label and current
+    // value start at the bar's leading edge, as the SwiftUI layout does.
+    const ghost = minimumValueLabel != null
+      ? <Text style={body} modifiers={[alpha(0)]}>{minimumValueLabel}</Text>
+      : null;
+    return (
+      <Column verticalArrangement={{spacedBy: gap}} modifiers={[fillMaxWidth(), ...testMods]}>
+        {label != null ? (
+          <Row horizontalArrangement={{spacedBy: gauge.rowGap}}>
+            {ghost}
+            <Text color={colors.onSurface} style={body}>{label}</Text>
+          </Row>
+        ) : null}
+        <Row verticalAlignment="center" horizontalArrangement={{spacedBy: gauge.rowGap}} modifiers={[fillMaxWidth()]}>
+          {minText}
+          <Box contentAlignment="centerStart" modifiers={[weight(1), height(bar), clip(pill), background(track.linearCapacity[scheme])]}>
+            <Box modifiers={[fillMaxWidth(f), fillMaxHeight(), clip(pill), background(accent)]}/>
+          </Box>
+          {maxText}
+        </Row>
+        {currentValueLabel != null ? (
+          <Row horizontalArrangement={{spacedBy: gauge.rowGap}}>
+            {ghost}
+            <Text
+              color={accent}
+              style={{fontSize: gauge.linearCapacity.currentFontSize, lineHeight: gauge.linearCapacity.currentLineHeight}}>
+              {currentValueLabel}
+            </Text>
+          </Row>
+        ) : null}
+      </Column>
+    );
+  }
+
+  const {bar, gapAbove, gapBelow} = gauge.automatic;
+  return (
+    <Column horizontalAlignment="center" modifiers={[fillMaxWidth(), ...testMods]}>
+      {label != null ? (
+        <>
+          <Text color={colors.onSurface} style={body}>{label}</Text>
+          <Spacer modifiers={[height(gapAbove)]}/>
+        </>
+      ) : null}
+      <Row verticalAlignment="center" horizontalArrangement={{spacedBy: gauge.rowGap}} modifiers={[fillMaxWidth()]}>
+        {minText}
+        <Box contentAlignment="centerStart" modifiers={[weight(1), height(bar), clip(pill), background(track.automatic[scheme])]}>
+          <Box modifiers={[fillMaxWidth(f), fillMaxHeight(), clip(pill), background(accent)]}/>
+        </Box>
+        {maxText}
+      </Row>
+      {currentValueLabel != null ? (
+        <>
+          <Spacer modifiers={[height(gapBelow)]}/>
+          <Text color={accent} style={body}>{currentValueLabel}</Text>
+        </>
+      ) : null}
+    </Column>
+  );
+}

package/src/gauge/index.ios.tsx

@@ -0,0 +1,40 @@
+import type {GaugeProps} from './types';
+import type {ViewModifier} from '@expo/ui/swift-ui/modifiers';
+
+import {Gauge as SwiftUIGauge, Text} from '@expo/ui/swift-ui';
+import {gaugeStyle, tint} from '@expo/ui/swift-ui/modifiers';
+
+/**
+ * iOS renders SwiftUI's `Gauge` (iOS 16+) in the requested `gaugeStyle`. The
+ * Host-level `tint` cascade colors it with the accent seed; `accentColor`
+ * overrides that per instance. Each text label is a SwiftUI `Text` in the
+ * matching gauge slot, so SwiftUI picks the fonts and placement.
+ */
+export function Gauge({
+  value,
+  min = 0,
+  max = 1,
+  variant = 'automatic',
+  label,
+  currentValueLabel,
+  minimumValueLabel,
+  maximumValueLabel,
+  accentColor,
+  testID,
+}: GaugeProps) {
+  const modifiers: ViewModifier[] = [gaugeStyle(variant)];
+  if (accentColor) modifiers.push(tint(accentColor));
+  return (
+    <SwiftUIGauge
+      value={value}
+      min={min}
+      max={max}
+      currentValueLabel={currentValueLabel != null ? <Text>{currentValueLabel}</Text> : undefined}
+      minimumValueLabel={minimumValueLabel != null ? <Text>{minimumValueLabel}</Text> : undefined}
+      maximumValueLabel={maximumValueLabel != null ? <Text>{maximumValueLabel}</Text> : undefined}
+      modifiers={modifiers}
+      testID={testID}>
+      {label != null ? <Text>{label}</Text> : undefined}
+    </SwiftUIGauge>
+  );
+}

package/src/gauge/index.tsx

@@ -0,0 +1,165 @@
+import './gauge.css';
+import type {CSSProperties} from 'react';
+import type {GaugeProps} from './types';
+import {StyleSheet, type TextStyle} from 'react-native';
+import {flatten} from '../theme';
+import {fraction, gauge, markerOffset} from './shared';
+
+const polar = (angle: number, radius: number, center: number) => ({
+  x: center + radius * Math.cos((angle * Math.PI) / 180),
+  y: center + radius * Math.sin((angle * Math.PI) / 180),
+});
+
+/**
+ * On web each SwiftUI gauge style is redrawn with DOM elements (the bars)
+ * and inline SVG (the rings), sized in CSS pixels to the geometry measured
+ * from iOS. Colors flow through custom properties: the accent tints the
+ * indicator and the value labels, the descriptive label keeps the label
+ * color, and the marker knockout paints the scheme background.
+ */
+export function Gauge({
+  value,
+  min = 0,
+  max = 1,
+  variant = 'automatic',
+  label,
+  currentValueLabel,
+  minimumValueLabel,
+  maximumValueLabel,
+  accentColor,
+  testID,
+  style,
+}: GaugeProps) {
+  const f = fraction(value, min, max);
+  const vars = {
+    ...(accentColor ? {'--ui-gauge-accent': accentColor} : null),
+    ...flatten(StyleSheet.flatten(style) as TextStyle),
+  } as CSSProperties;
+  const meter = {
+    role: 'meter',
+    'aria-label': label,
+    'aria-valuemin': min,
+    'aria-valuemax': max,
+    'aria-valuenow': Math.min(max, Math.max(min, value)),
+    'aria-valuetext': currentValueLabel,
+  } as const;
+  const bounds = {
+    min: minimumValueLabel != null ? <span className="ui-gauge__bound">{minimumValueLabel}</span> : null,
+    max: maximumValueLabel != null ? <span className="ui-gauge__bound">{maximumValueLabel}</span> : null,
+  };
+
+  if (variant === 'circular' || variant === 'circularCapacity') {
+    const {size, stroke, arcStart, arcSweep, dot, knockout} = gauge.ring;
+    const center = size / 2;
+    const radius = (size - stroke) / 2;
+    const start = polar(arcStart, radius, center);
+    const end = polar(arcStart + arcSweep, radius, center);
+    const marker = markerOffset(f);
+    const circumference = 2 * Math.PI * radius;
+    const text = currentValueLabel ?? label;
+    return (
+      <div
+        {...meter}
+        className={`ui-gauge-ring ui-gauge-ring--${variant}`}
+        style={{...vars, width: size, height: size}}
+        data-testid={testID}>
+        <svg className="ui-gauge-ring__svg" width={size} height={size} viewBox={`0 0 ${size} ${size}`} aria-hidden="true">
+          {variant === 'circular' ? (
+            <>
+              <path
+                className="ui-gauge-ring__arc"
+                // The 240° sweep is always the large arc, drawn clockwise.
+                d={`M ${start.x} ${start.y} A ${radius} ${radius} 0 1 1 ${end.x} ${end.y}`}
+                fill="none"
+                strokeWidth={stroke}
+                strokeLinecap="round"
+              />
+              <circle className="ui-gauge-ring__knockout" cx={center + marker.x} cy={center + marker.y} r={knockout / 2}/>
+              <circle className="ui-gauge-ring__dot" cx={center + marker.x} cy={center + marker.y} r={dot / 2}/>
+            </>
+          ) : (
+            <>
+              <circle className="ui-gauge-ring__track" cx={center} cy={center} r={radius} fill="none" strokeWidth={stroke}/>
+              {f > 0 ? (
+                <circle
+                  className="ui-gauge-ring__fill"
+                  cx={center}
+                  cy={center}
+                  r={radius}
+                  fill="none"
+                  strokeWidth={stroke}
+                  strokeLinecap="round"
+                  strokeDasharray={`${f * circumference} ${circumference}`}
+                  transform={`rotate(-90 ${center} ${center})`}
+                />
+              ) : null}
+            </>
+          )}
+        </svg>
+        {text != null ? (
+          <span className={['ui-gauge-ring__center', currentValueLabel == null && 'ui-gauge-ring__center--label'].filter(Boolean).join(' ')}>
+            {text}
+          </span>
+        ) : null}
+        {variant === 'circular' && (bounds.min || bounds.max) ? (
+          <span className="ui-gauge-ring__bounds">
+            {bounds.min ?? <span/>}
+            {bounds.max ?? <span/>}
+          </span>
+        ) : null}
+      </div>
+    );
+  }
+
+  if (variant === 'linear') {
+    return (
+      <div {...meter} className="ui-gauge ui-gauge--linear" style={vars} data-testid={testID}>
+        {bounds.min}
+        <span className="ui-gauge__track">
+          <span className="ui-gauge__marker" style={{left: `calc(${gauge.linear.dot / 2}px + ${f} * (100% - ${gauge.linear.dot}px))`}}>
+            <span className="ui-gauge__dot"/>
+          </span>
+        </span>
+        {bounds.max}
+      </div>
+    );
+  }
+
+  const fill = <span className="ui-gauge__fill" style={{width: `${f * 100}%`}}/>;
+
+  if (variant === 'linearCapacity') {
+    // A grid whose columns exist only for the bounds that are set, so the
+    // stacked label and current value start exactly at the bar's leading edge.
+    const columns = [bounds.min && 'auto', 'minmax(0, 1fr)', bounds.max && 'auto'].filter(Boolean).join(' ');
+    const barColumn = bounds.min ? 2 : 1;
+    const barRow = label != null ? 2 : 1;
+    const stacked = {gridColumn: barColumn} as const;
+    return (
+      <div
+        {...meter}
+        className="ui-gauge ui-gauge--linear-capacity"
+        style={{...vars, gridTemplateColumns: columns}}
+        data-testid={testID}>
+        {label != null ? <span className="ui-gauge__label" style={{...stacked, gridRow: 1}}>{label}</span> : null}
+        {bounds.min ? <span className="ui-gauge__bound" style={{gridColumn: 1, gridRow: barRow}}>{minimumValueLabel}</span> : null}
+        <span className="ui-gauge__track" style={{...stacked, gridRow: barRow}}>{fill}</span>
+        {bounds.max ? <span className="ui-gauge__bound" style={{gridColumn: barColumn + 1, gridRow: barRow}}>{maximumValueLabel}</span> : null}
+        {currentValueLabel != null ? (
+          <span className="ui-gauge__current" style={{...stacked, gridRow: barRow + 1}}>{currentValueLabel}</span>
+        ) : null}
+      </div>
+    );
+  }
+
+  return (
+    <div {...meter} className="ui-gauge ui-gauge--automatic" style={vars} data-testid={testID}>
+      {label != null ? <span className="ui-gauge__label">{label}</span> : null}
+      <span className="ui-gauge__row">
+        {bounds.min}
+        <span className="ui-gauge__track">{fill}</span>
+        {bounds.max}
+      </span>
+      {currentValueLabel != null ? <span className="ui-gauge__current">{currentValueLabel}</span> : null}
+    </div>
+  );
+}

package/src/gauge/shared.ts

@@ -0,0 +1,79 @@
+/**
+ * Geometry of the SwiftUI gauge styles, in points, measured from iOS
+ * screenshots so the Android and web redraws match the native control.
+ */
+export const gauge = {
+  /** Body text of the labels (the SwiftUI default font). */
+  fontSize: 17,
+  lineHeight: 22,
+  /** Space between a bounds label and the bar. */
+  rowGap: 8,
+
+  /** `automatic`: capacity bar height and the gaps to the labels above/below. */
+  automatic: {bar: 15, gapAbove: 14, gapBelow: 9},
+
+  /** `linear`: bar height, marker dot (same size) and its background knockout. */
+  linear: {bar: 7.5, dot: 7.5, knockout: 15},
+
+  /** `linearCapacity`: bar height, stack spacing and the current value font. */
+  linearCapacity: {bar: 4, gap: 4, currentFontSize: 12, currentLineHeight: 16},
+
+  /** Circular styles: ring diameter/stroke, arc, marker and label metrics. */
+  ring: {
+    size: 58,
+    stroke: 5.5,
+    /** Open ring (`circular`): arc start angle (degrees, clockwise from 3 o'clock) and sweep. */
+    arcStart: 150,
+    arcSweep: 240,
+    dot: 5.5,
+    knockout: 10,
+    centerFontSize: 24,
+    centerLineHeight: 29,
+    boundsFontSize: 10,
+    boundsLineHeight: 12,
+    /**
+     * Width of the bounds row and the offset of its center below the ring
+     * center: clear of the 24pt value above it and inside the arc's gap.
+     */
+    boundsWidth: 34,
+    boundsOffset: 17,
+    /** Opacity of the unfilled track in `circularCapacity`. */
+    trackOpacity: 0.3,
+  },
+} as const;
+
+/**
+ * Unfilled track fills, as `#RRGGBBAA` per scheme: iOS `tertiarySystemFill`
+ * behind the `automatic` bar and `systemFill` behind the `linearCapacity` bar.
+ */
+export const track = {
+  automatic: {light: '#7676801F', dark: '#7676803D'},
+  linearCapacity: {light: '#78788033', dark: '#7878805C'},
+} as const;
+
+/** Position of `value` within `[min, max]`, clamped to `0…1`. */
+export function fraction(value: number, min: number, max: number): number {
+  if (max <= min) return 0;
+  return Math.min(1, Math.max(0, (value - min) / (max - min)));
+}
+
+/**
+ * Center of the `circular` marker for a fraction, relative to the ring center
+ * (y grows downwards), on the stroke's center line.
+ */
+export function markerOffset(f: number): {x: number; y: number} {
+  const angle = ((gauge.ring.arcStart + f * gauge.ring.arcSweep) * Math.PI) / 180;
+  const radius = (gauge.ring.size - gauge.ring.stroke) / 2;
+  return {x: radius * Math.cos(angle), y: radius * Math.sin(angle)};
+}
+
+/**
+ * `#RRGGBB` (or `#RGB`/`#RRGGBBAA`) color with its alpha replaced. Other
+ * color syntaxes are returned unchanged.
+ */
+export function withAlpha(color: string, alpha: number): string {
+  const hex = /^#([0-9a-f]{3}|[0-9a-f]{6}|[0-9a-f]{8})$/i.exec(color.trim())?.[1];
+  if (!hex) return color;
+  const rgb = hex.length === 3 ? hex.split('').map(c => c + c).join('') : hex.slice(0, 6);
+  return `#${rgb}${Math.round(alpha * 255).toString(16).padStart(2, '0')}`.toUpperCase();
+}