@ultimat3/ui 20.1.6 → 20.2.0

package/src/components/Kbd.module.scss

@@ -0,0 +1,15 @@
+@use '../tokens' as t;
+
+.kbd {
+  @include t.data-text;
+
+  padding: t.space(1) t.space(2);
+  border: 1px solid t.role('line');
+  border-radius: t.radius(sm);
+  background: t.role('bg-soft');
+  color: t.role('fg-strong');
+  font-size: t.text(xs);
+  line-height: t.leading(tight);
+  box-shadow: t.shadow(sm);
+  white-space: nowrap;
+}

package/src/components/Kbd.tsx

@@ -0,0 +1,17 @@
+// A keyboard key or chord as the user reads it — "⌘K", "Esc", "/". A native `<kbd>`, because a
+// keyboard hint is inline code, not a badge: the element carries the meaning, so it works with no
+// script and reads as a key to a screen reader.
+
+import type { JSX } from 'solid-js';
+import { cx } from '../cx';
+import styles from './Kbd.module.scss';
+
+export interface KbdProps {
+  /** The key or chord, already translated where a key name is a word. */
+  children: JSX.Element;
+  class?: string | undefined;
+}
+
+export function Kbd(props: KbdProps): JSX.Element {
+  return <kbd class={cx(styles['kbd'], props.class)}>{props.children}</kbd>;
+}

package/src/components/Meter.module.scss

@@ -0,0 +1,18 @@
+@use '../tokens' as t;
+
+@include t.tone-classes;
+
+.meter {
+  display: block;
+  inline-size: 100%;
+  block-size: 0.25rem;
+  overflow: visible;
+}
+
+.track {
+  fill: t.role('line', 0.5);
+}
+
+.fill {
+  fill: var(--tone);
+}

package/src/components/Meter.tsx

@@ -0,0 +1,58 @@
+// A thin horizontal bar showing one value against a maximum — a table cell's "how busy is this
+// row" beside the number, or a quota. Decorative by default: with no `label` it is hidden from
+// the accessibility tree, because the number beside it is the fact. With one it is a `meter` role
+// with the value spoken.
+//
+// An SVG with a `width` ATTRIBUTE rather than a styled box: it paints identically on the server
+// copy and the hydrated one and asks nothing of the CSP's `style-src-attr`.
+
+import type { JSX } from 'solid-js';
+import { cx } from '../cx';
+import styles from './Meter.module.scss';
+import { meterShare, meterWidth } from './meter-view';
+import type { Tone } from './variants';
+
+export interface MeterProps {
+  value: number;
+  max: number;
+  /** The accessible name. Omit for a purely decorative bar beside a visible number. */
+  label?: string | undefined;
+  tone?: Tone | undefined;
+  class?: string | undefined;
+}
+
+export function Meter(props: MeterProps): JSX.Element {
+  const share = (): number => meterShare(props.value, props.max);
+  const classes = (): string =>
+    cx(styles['meter'], styles[`tone-${props.tone ?? 'accent'}`], props.class);
+  const bars = (): JSX.Element => [
+    <rect class={styles['track']} width={100} height={4} rx={2} />,
+    <rect class={styles['fill']} width={meterWidth(share())} height={4} rx={2} />,
+  ];
+  // Two literal elements rather than one with conditional ARIA: the `meter` role's value
+  // attributes are only valid ON that role, and a lint that reads roles statically has to see it.
+  if (props.label === undefined) {
+    return (
+      <svg class={classes()} viewBox="0 0 100 4" preserveAspectRatio="none" aria-hidden="true">
+        {bars()}
+      </svg>
+    );
+  }
+  return (
+    // A native <meter> paints its fill through a vendor pseudo-element per browser, so it cannot
+    // be drawn with tokens or identically everywhere; the role goes on the SVG that draws it.
+    // biome-ignore lint/a11y/useSemanticElements: <meter> cannot be styled from tokens
+    <svg
+      class={classes()}
+      viewBox="0 0 100 4"
+      preserveAspectRatio="none"
+      role="meter"
+      aria-label={props.label}
+      aria-valuemin={0}
+      aria-valuemax={props.max}
+      aria-valuenow={props.value}
+    >
+      {bars()}
+    </svg>
+  );
+}

package/src/components/QrCode.module.scss

@@ -0,0 +1,41 @@
+@use '../tokens' as t;
+
+.qr {
+  display: block;
+  inline-size: 100%;
+  block-size: auto;
+  max-inline-size: 10rem;
+}
+
+// why: this is the ONE component allowed a theme selector. A QR code is a machine-readable
+// symbol, not themed decoration: scanners expect DARK modules on a LIGHT ground, and many refuse
+// the inverse. The tokens are theme-bound and raw colours are refused, so the ROLES swap per
+// theme instead — whichever role is light becomes the ground, whichever is dark the modules — and
+// the swap has to cover BOTH ways a document goes dark: the OS preference with no `data-theme`
+// set (the media path), and an explicit `data-theme='dark'` (the attribute path). A page that
+// followed the theme drew a light-on-dark code no phone would read.
+.ground {
+  fill: t.role('surface-raised');
+}
+
+.module {
+  fill: t.role('fg-strong');
+}
+
+@media (prefers-color-scheme: dark) {
+  html:not([data-theme='light']) .ground {
+    fill: t.role('fg-strong');
+  }
+
+  html:not([data-theme='light']) .module {
+    fill: t.role('bg');
+  }
+}
+
+html[data-theme='dark'] .ground {
+  fill: t.role('fg-strong');
+}
+
+html[data-theme='dark'] .module {
+  fill: t.role('bg');
+}

package/src/components/QrCode.tsx

@@ -0,0 +1,49 @@
+// A QR code of one short value — a link's short URL, a join code — as static SVG from the
+// pure-TypeScript encoder in `qr-encode.ts` / `qr-matrix.ts`. No QR library: a route's JS budget
+// counts raw minified bytes, and one `<rect>` per dark module costs nothing to hydrate, so the
+// server-rendered shell IS the code. Versions 1-3 only (42 bytes); longer is `X_UI_QR_CAPACITY`.
+
+import type { JSX } from 'solid-js';
+import { cx } from '../cx';
+import styles from './QrCode.module.scss';
+import { encodeQr, quietZoneOf } from './qr-matrix';
+
+export interface QrCodeProps {
+  /** What the code encodes — a short URL, at most 42 UTF-8 bytes. Longer throws. */
+  value: string;
+  /** The accessible name, already translated — say what scanning it does, not "QR code". */
+  label: string;
+  /** Light modules on every side. Default 4, the minimum a scanner needs to find the finders. */
+  quietZone?: number | undefined;
+  class?: string | undefined;
+}
+
+export function QrCode(props: QrCodeProps): JSX.Element {
+  const matrix = (): ReturnType<typeof encodeQr> => encodeQr(props.value);
+  const quiet = (): number => quietZoneOf(props.quietZone);
+  const dimension = (): number => matrix().size + quiet() * 2;
+  return (
+    <svg
+      role="img"
+      aria-label={props.label}
+      viewBox={`0 0 ${dimension()} ${dimension()}`}
+      class={cx(styles['qr'], props.class)}
+      shape-rendering="crispEdges"
+    >
+      <rect class={styles['ground']} x={0} y={0} width={dimension()} height={dimension()} />
+      {matrix().modules.flatMap((row, rowIndex) =>
+        row.map((dark, colIndex) =>
+          dark ? (
+            <rect
+              class={styles['module']}
+              x={quiet() + colIndex}
+              y={quiet() + rowIndex}
+              width={1}
+              height={1}
+            />
+          ) : null,
+        ),
+      )}
+    </svg>
+  );
+}

package/src/components/Sparkline.module.scss

@@ -0,0 +1,20 @@
+@use '../tokens' as t;
+
+.sparkline {
+  display: block;
+  inline-size: 100%;
+  block-size: auto;
+}
+
+.line {
+  stroke: t.role('accent');
+  stroke-width: 2;
+  // The box scales with its column; the line must not (it rendered ~7px thick at full width).
+  vector-effect: non-scaling-stroke;
+  stroke-linejoin: round;
+  stroke-linecap: round;
+}
+
+.last {
+  fill: t.role('accent');
+}

package/src/components/Sparkline.tsx

@@ -0,0 +1,40 @@
+// One series as a single line with no axes — the trend beside a figure, in a table cell, on a
+// detail page. Static SVG for `BarChart`'s reason: the framework's own docs use a sparkline
+// pulling in a chart library as the cautionary example, and this file IS that sparkline written
+// the way the docs say to. The path comes from `sparkline-view.ts`.
+
+import type { JSX } from 'solid-js';
+import { cx } from '../cx';
+import type { ChartPoint } from './bar-chart-view';
+import styles from './Sparkline.module.scss';
+import { SPARKLINE, sparklinePath, sparkPoints } from './sparkline-view';
+
+export interface SparklineProps {
+  /** The accessible name for the whole chart, already translated. */
+  label: string;
+  /** Oldest first. Every point comes from exactly this array — the caller zero-fills gaps. */
+  points: readonly ChartPoint[];
+  class?: string | undefined;
+}
+
+export function Sparkline(props: SparklineProps): JSX.Element {
+  const last = (): ChartPoint | undefined => props.points.at(-1);
+  const lastPoint = () => sparkPoints(props.points).at(-1);
+  return (
+    <svg
+      role="img"
+      aria-label={props.label}
+      viewBox={`0 0 ${SPARKLINE.width} ${SPARKLINE.height}`}
+      class={cx(styles['sparkline'], props.class)}
+    >
+      <path class={styles['line']} d={sparklinePath(props.points)} fill="none" />
+      {last() === undefined ? null : (
+        <circle class={styles['last']} cx={lastPoint()?.x} cy={lastPoint()?.y} r={2}>
+          <title>
+            {last()?.key}: {last()?.value}
+          </title>
+        </circle>
+      )}
+    </svg>
+  );
+}

package/src/components/StatTile.module.scss

@@ -0,0 +1,86 @@
+@use '../tokens' as t;
+
+.tile {
+  display: flex;
+  flex-direction: column;
+  gap: t.space(2);
+  min-inline-size: 0;
+  padding: t.space(5);
+  border: 1px solid t.role('line', 0.6);
+  border-radius: t.radius(lg);
+  background: t.role('surface');
+  transition: border-color t.duration(fast) t.easing(out);
+
+  &:hover {
+    border-color: t.role('line');
+  }
+}
+
+.label {
+  @include t.label-caps;
+
+  margin: 0;
+  color: t.role('fg-muted');
+}
+
+.figure {
+  display: flex;
+  align-items: baseline;
+  flex-wrap: wrap;
+  gap: t.space(3);
+}
+
+.value {
+  @include t.truncate;
+  @include t.data-text;
+
+  margin: 0;
+  font-size: t.text('2xl');
+  font-weight: t.weight(medium);
+  letter-spacing: t.tracking(tight);
+  line-height: t.leading(tight);
+  color: t.role('fg-strong');
+}
+
+.delta {
+  @include t.data-text;
+
+  display: inline-flex;
+  align-items: center;
+  gap: t.space(1);
+  padding: 0 t.space(2);
+  border-radius: t.radius(pill);
+  font-size: t.text(xs);
+  line-height: t.leading(loose);
+}
+
+.arrow {
+  inline-size: 0.625rem;
+  block-size: 0.625rem;
+  fill: none;
+  stroke: currentcolor;
+  stroke-width: 1.75;
+  stroke-linecap: round;
+  stroke-linejoin: round;
+}
+
+.trend-up {
+  background: t.role('success-soft');
+  color: t.role('success');
+}
+
+.trend-down {
+  background: t.role('danger-soft');
+  color: t.role('danger');
+}
+
+.trend-flat {
+  background: t.role('surface-raised');
+  color: t.role('fg-muted');
+}
+
+.hint {
+  margin: 0;
+  color: t.role('fg-muted');
+  font-size: t.text(xs);
+}

package/src/components/StatTile.tsx

@@ -0,0 +1,49 @@
+// One labelled figure with an optional trend chip and a line of context — the tile a dashboard's
+// top row is made of. The figure arrives formatted: number formatting is the caller's
+// (`Intl.NumberFormat` against the page locale), so the tile never guesses a locale.
+//
+// Intrinsic tags only: a runtime-chosen root (`const Tag = props.as ?? 'div'`) is called as a
+// component by the island build, so a tile built on `Card` hydrated differently from how it was
+// served. A `<div>` renders identically on both sides.
+
+import type { JSX } from 'solid-js';
+import { cx } from '../cx';
+import styles from './StatTile.module.scss';
+import type { StatDelta } from './stat-delta';
+import { DELTA_ARROW_PATH } from './stat-delta';
+
+export interface StatTileProps {
+  /** The tile's caption, already translated — "Total links", "Clicks today". */
+  label: string;
+  /** The figure, already formatted as the string this tile shows. */
+  value: string;
+  /** The stable hook a test or a live check reads the figure through: `data-stat`. */
+  stat: string;
+  /** The trend chip; `deltaOf()` builds one from a current and a baseline. */
+  delta?: StatDelta | undefined;
+  /** One short line of context under the figure: "vs yesterday", "849 clicks". */
+  hint?: string | undefined;
+  class?: string | undefined;
+}
+
+export function StatTile(props: StatTileProps): JSX.Element {
+  return (
+    <div class={cx(styles['tile'], props.class)}>
+      <p class={styles['label']}>{props.label}</p>
+      <div class={styles['figure']}>
+        <p class={styles['value']} data-stat={props.stat}>
+          {props.value}
+        </p>
+        {props.delta === undefined ? null : (
+          <span class={cx(styles['delta'], styles[`trend-${props.delta.trend}`])}>
+            <svg viewBox="0 0 10 10" aria-hidden="true" class={styles['arrow']}>
+              <path d={DELTA_ARROW_PATH[props.delta.trend]} />
+            </svg>
+            {props.delta.text}
+          </span>
+        )}
+      </div>
+      {props.hint === undefined ? null : <p class={styles['hint']}>{props.hint}</p>}
+    </div>
+  );
+}

package/src/components/bar-chart-view.ts

@@ -0,0 +1,55 @@
+// The geometry of a BarChart, apart from its markup: where each bar sits, how tall it is, where
+// the grid lines fall. Pure, so the server render and a hydrated one cannot draw two charts.
+
+export interface ChartPoint {
+  /** The bar's name — a day, a bucket, a label. Read by `<title>` and the axis. */
+  readonly key: string;
+  readonly value: number;
+}
+
+export interface BarRect {
+  readonly x: number;
+  readonly y: number;
+  readonly width: number;
+  readonly height: number;
+}
+
+/**
+ * 600 × 128 at a 5:1-ish ratio, not 3:1: at dashboard width a taller box pushed the table — the
+ * thing people came for — below the fold. `plot` is where bars live; the strip under it belongs
+ * to the axis labels, which drawn ON the first and last bars were unreadable there.
+ */
+export const BAR_CHART = { width: 600, top: 12, plot: 104, height: 128, gap: 3 } as const;
+
+/** Quarter lines. Four is what a reader can use to judge a bar's height without a y-axis. */
+export const GRID_STEPS = [0.25, 0.5, 0.75, 1] as const;
+
+/** The busiest point, and never below 1, so an all-zero series still divides. */
+export function maxOf(points: readonly ChartPoint[]): number {
+  let max = 1;
+  for (const point of points)
+    if (Number.isFinite(point.value) && point.value > max) max = point.value;
+  return max;
+}
+
+/** The y of a grid line at `step` of the plot height (1 = the top line = the busiest point). */
+export function gridY(step: number): number {
+  return BAR_CHART.top + BAR_CHART.plot - step * BAR_CHART.plot;
+}
+
+/** One rect per point, oldest first. At least 2px tall so a zero still draws a visible bar. */
+export function barRects(points: readonly ChartPoint[]): readonly BarRect[] {
+  const count = Math.max(points.length, 1);
+  const width = (BAR_CHART.width - BAR_CHART.gap * (count - 1)) / count;
+  const max = maxOf(points);
+  return points.map((point, index) => {
+    const value = Number.isFinite(point.value) ? Math.max(0, point.value) : 0;
+    const height = Math.max(2, (value / max) * BAR_CHART.plot);
+    return {
+      x: index * (width + BAR_CHART.gap),
+      y: BAR_CHART.top + BAR_CHART.plot - height,
+      width,
+      height,
+    };
+  });
+}

package/src/components/command-palette-view.ts

@@ -0,0 +1,61 @@
+// The rules of a command palette, apart from its markup: which items a query keeps, where the
+// roving selection goes on an arrow key, and what a key means. Pure, so the caller's island and
+// a page test decide the same thing — and so the component owns no rule a caller could get wrong.
+
+export interface CommandPaletteItem {
+  /** Stable across a re-filter — what roving selection and `onRunItem` both key off. */
+  readonly id: string;
+  readonly label: string;
+  /** Secondary text — a target URL, a slug, a key chord. Empty renders nothing. */
+  readonly hint: string;
+}
+
+/** Case-insensitive substring over label and hint; an empty query keeps everything. */
+export function filterItems(
+  items: readonly CommandPaletteItem[],
+  query: string,
+): readonly CommandPaletteItem[] {
+  const needle = query.trim().toLowerCase();
+  if (needle === '') return items;
+  return items.filter(
+    (item) => item.label.toLowerCase().includes(needle) || item.hint.toLowerCase().includes(needle),
+  );
+}
+
+/** The active id after a step, wrapping at both ends; the first item when nothing was active. */
+export function stepActive(
+  items: readonly CommandPaletteItem[],
+  activeId: string | undefined,
+  delta: 1 | -1,
+): string | undefined {
+  if (items.length === 0) return undefined;
+  const index = items.findIndex((item) => item.id === activeId);
+  const next = index === -1 ? 0 : (index + delta + items.length) % items.length;
+  return items[next]?.id;
+}
+
+/** The active id a narrowed list should keep: the same one if it survived, else the first. */
+export function settleActive(
+  items: readonly CommandPaletteItem[],
+  activeId: string | undefined,
+): string | undefined {
+  return items.some((item) => item.id === activeId) ? activeId : items[0]?.id;
+}
+
+export type PaletteKeyAction = 'next' | 'previous' | 'run' | 'close';
+
+/** What a key pressed in the filter means, or `null` for a key the palette does not own. */
+export function keyAction(key: string): PaletteKeyAction | null {
+  switch (key) {
+    case 'ArrowDown':
+      return 'next';
+    case 'ArrowUp':
+      return 'previous';
+    case 'Enter':
+      return 'run';
+    case 'Escape':
+      return 'close';
+    default:
+      return null;
+  }
+}

package/src/components/meter-view.ts

@@ -0,0 +1,13 @@
+// The arithmetic of a Meter, apart from its markup: a share of a maximum, clamped, and the width
+// attribute that share becomes. Pure so a server render and a hydrated one cannot disagree.
+
+/** `value / max` clamped to 0..1; a non-positive or non-finite `max` is an empty meter. */
+export function meterShare(value: number, max: number): number {
+  if (!Number.isFinite(value) || !Number.isFinite(max) || max <= 0) return 0;
+  return Math.min(1, Math.max(0, value / max));
+}
+
+/** The fill's `width` on a 100-unit viewBox, to one decimal — stable across renders. */
+export function meterWidth(share: number): string {
+  return (share * 100).toFixed(1);
+}