@react-x11/components 0.1.0 → 0.2.0

package/src/charts/scale.ts

@@ -0,0 +1,214 @@
+// Scales and ticks: the d3-shaped 20% of d3-scale these charts need,
+// written out rather than depended on. Pure functions over numbers — no
+// react-x11, no ntk — so every branch is unit-testable headlessly.
+
+/** A linear mapping from a data domain onto a pixel range. `r0 > r1` is the
+ * normal state for y (pixels grow downward). */
+export interface LinearScale {
+  kind: 'linear';
+  d0: number;
+  d1: number;
+  r0: number;
+  r1: number;
+  scale(v: number): number;
+  invert(px: number): number;
+}
+
+export function linearScale(
+  d0: number,
+  d1: number,
+  r0: number,
+  r1: number,
+): LinearScale {
+  // a degenerate domain still has to map *somewhere*: pin it to the middle
+  // of the range rather than dividing by zero
+  const span = d1 - d0;
+  const k = span === 0 ? 0 : (r1 - r0) / span;
+  return {
+    kind: 'linear',
+    d0,
+    d1,
+    r0,
+    r1,
+    scale: (v) => (span === 0 ? (r0 + r1) / 2 : r0 + (v - d0) * k),
+    invert: (px) => (k === 0 ? d0 : d0 + (px - r0) / k),
+  };
+}
+
+/** A band mapping for categories: index → left edge, with the usual inner
+ * padding. Bars ask for `bandwidth`; ticks ask for `center`. */
+export interface BandScale {
+  kind: 'band';
+  count: number;
+  r0: number;
+  r1: number;
+  bandwidth: number;
+  step: number;
+  scale(index: number): number;
+  center(index: number): number;
+  indexAt(px: number): number;
+}
+
+export function bandScale(
+  count: number,
+  r0: number,
+  r1: number,
+  paddingInner = 0.2,
+  paddingOuter = 0.1,
+): BandScale {
+  const n = Math.max(1, count);
+  const span = r1 - r0;
+  // solve span = step * (n - paddingInner) + 2 * paddingOuter * step
+  const step = span / Math.max(1e-9, n - paddingInner + 2 * paddingOuter);
+  const bandwidth = Math.max(1, step * (1 - paddingInner));
+  const start = r0 + step * paddingOuter;
+  return {
+    kind: 'band',
+    count: n,
+    r0,
+    r1,
+    bandwidth,
+    step,
+    scale: (i) => start + step * i,
+    center: (i) => start + step * i + bandwidth / 2,
+    // nearest band center, clamped — the tooltip's question
+    indexAt: (px) =>
+      Math.max(
+        0,
+        Math.min(n - 1, Math.round((px - start - bandwidth / 2) / step)),
+      ),
+  };
+}
+
+// --- nice numeric ticks ----------------------------------------------------
+
+/** The classic 1-2-5 ladder: the largest of {1,2,5}·10^k not above `raw`. */
+function niceStep(raw: number): number {
+  const pow = Math.pow(10, Math.floor(Math.log10(raw)));
+  const unit = raw / pow;
+  if (unit >= 5) return 5 * pow;
+  if (unit >= 2) return 2 * pow;
+  return pow;
+}
+
+/**
+ * Tick values covering `[d0, d1]` at a nice step, aiming for `target`
+ * ticks. Values land on multiples of the step, so labels come out as the
+ * round numbers a person would have chosen.
+ */
+export function linearTicks(d0: number, d1: number, target = 5): number[] {
+  if (!Number.isFinite(d0) || !Number.isFinite(d1)) return [];
+  if (d1 < d0) [d0, d1] = [d1, d0];
+  if (d0 === d1) return [d0];
+  const step = niceStep((d1 - d0) / Math.max(1, target));
+  const start = Math.ceil(d0 / step) * step;
+  const ticks: number[] = [];
+  // the epsilon keeps a tick sitting exactly on d1 from being dropped to
+  // float noise
+  for (let v = start; v <= d1 + step * 1e-9; v += step) {
+    // snap accumulated float error back onto the step grid
+    ticks.push(Math.abs(v) < step * 1e-9 ? 0 : v);
+  }
+  return ticks;
+}
+
+/** Widen `[d0, d1]` outward onto the tick grid — what "nice: true" domains
+ * mean everywhere else. */
+export function niceDomain(
+  d0: number,
+  d1: number,
+  target = 5,
+): [number, number] {
+  if (!Number.isFinite(d0) || !Number.isFinite(d1) || d0 === d1) {
+    // a flat or empty domain gets a unit of air so the line is visible and
+    // the scale is invertible
+    const v = Number.isFinite(d0) ? d0 : 0;
+    return [v - 1, v + 1];
+  }
+  if (d1 < d0) [d0, d1] = [d1, d0];
+  const step = niceStep((d1 - d0) / Math.max(1, target));
+  return [Math.floor(d0 / step) * step, Math.ceil(d1 / step) * step];
+}
+
+// --- time ticks ------------------------------------------------------------
+
+const SEC = 1000;
+const MIN = 60 * SEC;
+const HOUR = 60 * MIN;
+const DAY = 24 * HOUR;
+
+/** Steps a person expects a time axis to move in, smallest first. Above a
+ * month the numeric 1-2-5 ladder over days takes over — calendars stop
+ * being uniform there and this is a chart axis, not a scheduler. */
+const TIME_STEPS = [
+  SEC,
+  5 * SEC,
+  15 * SEC,
+  30 * SEC,
+  MIN,
+  5 * MIN,
+  15 * MIN,
+  30 * MIN,
+  HOUR,
+  3 * HOUR,
+  6 * HOUR,
+  12 * HOUR,
+  DAY,
+  2 * DAY,
+  7 * DAY,
+  14 * DAY,
+  30 * DAY,
+];
+
+export function timeTicks(d0: number, d1: number, target = 5): number[] {
+  if (!Number.isFinite(d0) || !Number.isFinite(d1) || d1 <= d0) return [];
+  const raw = (d1 - d0) / Math.max(1, target);
+  let step = TIME_STEPS[TIME_STEPS.length - 1];
+  for (const s of TIME_STEPS) {
+    if (s >= raw) {
+      step = s;
+      break;
+    }
+  }
+  if (raw > step) step = niceStep(raw / DAY) * DAY;
+  const ticks: number[] = [];
+  for (let v = Math.ceil(d0 / step) * step; v <= d1; v += step) ticks.push(v);
+  return ticks;
+}
+
+/** A label for a time tick, sized to the span it lives in: a minutes-wide
+ * window shows H:MM:SS, a months-wide one shows "Mar 4". Local time. */
+export function formatTimeTick(v: number, span: number): string {
+  const d = new Date(v);
+  const two = (x: number) => String(x).padStart(2, '0');
+  if (span < MIN) return `${two(d.getMinutes())}:${two(d.getSeconds())}`;
+  if (span < HOUR)
+    return `${d.getHours()}:${two(d.getMinutes())}:${two(d.getSeconds())}`;
+  if (span < 2 * DAY) return `${d.getHours()}:${two(d.getMinutes())}`;
+  const MONTHS = 'Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec'.split(' ');
+  if (span < 300 * DAY) return `${MONTHS[d.getMonth()]} ${d.getDate()}`;
+  return `${MONTHS[d.getMonth()]} ${d.getFullYear()}`;
+}
+
+/** Compact numeric labels: 1200000 → "1.2M". What axis gutters can afford. */
+export function formatNumberTick(v: number): string {
+  if (v === 0) return '0';
+  const abs = Math.abs(v);
+  const fmt = (scaled: number, suffix: string) => {
+    const rounded =
+      Math.abs(scaled) >= 100
+        ? Math.round(scaled)
+        : Math.round(scaled * 10) / 10;
+    return `${rounded}${suffix}`;
+  };
+  if (abs >= 1e9) return fmt(v / 1e9, 'B');
+  if (abs >= 1e6) return fmt(v / 1e6, 'M');
+  if (abs >= 1e3) return fmt(v / 1e3, 'k');
+  if (abs >= 1) {
+    const r = Math.round(v * 100) / 100;
+    return String(r);
+  }
+  // small magnitudes keep enough digits to tell ticks apart
+  const digits = Math.min(6, 1 - Math.floor(Math.log10(abs)));
+  return v.toFixed(digits).replace(/0+$/, '').replace(/\.$/, '');
+}

package/src/charts/spec.ts

@@ -0,0 +1,122 @@
+// The resolved chart description `<chartplot>` paints from. The React
+// layer builds one of these by introspecting its children (recharts'
+// model: series/axis children are config carriers, not renderers) and
+// memoizes it, so an unchanged chart re-rendering costs no damage.
+
+/** The shadcn shape: series key → how to present it. Colours take a CSS
+ * colour or a `$token` resolved against the nearest theme. */
+export type ChartConfig = Record<
+  string,
+  {
+    label?: string;
+    color?: string;
+  }
+>;
+
+export type SeriesType = 'line' | 'area' | 'bar' | 'scatter';
+
+export type CurveKind = 'linear' | 'monotone' | 'step';
+
+export interface SeriesSpec {
+  /** The dataKey — column name, config key, legend identity. */
+  id: string;
+  type: SeriesType;
+  /** Resolved presentation colour (config wins over the default palette).
+   * `$token` values resolve against the theme at paint time. */
+  color: string;
+  label: string;
+  strokeWidth: number;
+  /** Area fill opacity; the stroke on top stays opaque. */
+  fillOpacity: number;
+  curve: CurveKind;
+  /** Line marker dots: false, or a radius in px. Sparse mode only. */
+  dot: number | false;
+  /** Series sharing a stackId stack in child order (bar/area). */
+  stackId: string | null;
+  /** Rounded bar tops. Ignored past BAR_RADIUS_MAX bars per frame. */
+  barRadius: number;
+  /** Scatter point size in px. */
+  size: number;
+}
+
+export type AxisType = 'auto' | 'linear' | 'band' | 'time';
+
+export interface AxisSpec {
+  /** x only: the column holding the axis values. Absent means "the index". */
+  key: string | null;
+  type: AxisType;
+  /** Requested tick count — a target, not a promise. */
+  ticks: number;
+  /** Domain overrides; 'auto' keeps the data extent (nice-rounded for y). */
+  domain: [number | 'auto', number | 'auto'];
+  hide: boolean;
+  /** y: reserved gutter width. 'auto' measures the tick labels. */
+  width: number | 'auto';
+  /** x: reserved gutter height. */
+  height: number;
+}
+
+export interface GridSpec {
+  horizontal: boolean;
+  vertical: boolean;
+}
+
+export interface PlotSpec {
+  series: SeriesSpec[];
+  x: AxisSpec;
+  y: AxisSpec;
+  grid: GridSpec | null;
+}
+
+/** What a painted frame cost — the demo HUD renders it, the tests assert
+ * on it. Estimated wire bytes count 8 per rectangle, 48 per stroked
+ * segment and 4 per image pixel: the real encodings' sizes, near enough to
+ * choose between paths by. */
+export interface ChartFrameStats {
+  /** ms spent preparing (pyramid/index/stack/grid builds), this frame. */
+  prepMs: number;
+  paintMs: number;
+  /** Points the visible index ranges spanned, all series summed. */
+  pointsSpanned: number;
+  /** Drawing commands issued (batched fills count once). */
+  commands: number;
+  estimatedWireBytes: number;
+  series: {
+    id: string;
+    mode: 'polyline' | 'columns' | 'bars' | 'rects' | 'image' | 'skipped';
+    points: number;
+  }[];
+}
+
+/** The default categorical palette. The first series follows the app's
+ * accent, so an unconfigured chart already matches the UI around it; the
+ * rest hold their own on light and dark ground. */
+export const DEFAULT_PALETTE = [
+  '$accent',
+  '#e17055',
+  '#00b894',
+  '#8e6be8',
+  '#e84393',
+];
+
+/**
+ * Resolve a `$token` colour against a theme record. Unknown tokens fall to
+ * a visible grey rather than throwing — a chart with a typo'd token should
+ * mis-colour, not take the frame down.
+ */
+export function resolveThemeColor(
+  color: string,
+  theme: Record<string, unknown> | null,
+): string {
+  if (!color.startsWith('$')) return color;
+  const value = theme?.[color.slice(1)];
+  return typeof value === 'string' ? value : '#888888';
+}
+
+export const SPEC_DEFAULTS = {
+  strokeWidth: 2,
+  fillOpacity: 0.25,
+  ticks: 5,
+  xAxisHeight: 24,
+  scatterSize: 3,
+} as const;

package/src/charts/timers.ts

@@ -0,0 +1,24 @@
+// Runtime globals reached through `globalThis` — `types: []` in the build
+// means a runtime-provided global is typed structurally rather than
+// inherited from `@types/node` (AGENTS.md, "Two tsconfigs"). A copy of
+// `../embed/timers.ts`'s microtask half plus a monotonic clock, and
+// deliberately a copy: importing another component's private module makes
+// the two one bundle unit.
+interface ChartGlobals {
+  queueMicrotask?(fn: () => void): void;
+  performance?: { now(): number };
+}
+
+const g = globalThis as ChartGlobals;
+
+/** Off the current stack — how paint reports stats without re-entering
+ * React from inside a frame. */
+export function microtask(fn: () => void): void {
+  if (g.queueMicrotask) g.queueMicrotask(fn);
+  else void Promise.resolve().then(fn);
+}
+
+/** Milliseconds, monotonic where the runtime has it. */
+export function now(): number {
+  return g.performance ? g.performance.now() : Date.now();
+}

package/src/code/hx.ts

@@ -0,0 +1,51 @@
+// `React.createElement`, typed against react-x11's host elements.
+//
+// The library writes `h(...)` rather than JSX — a convention inherited from
+// core, and worth keeping so moving code between the two repos stays a
+// rename. But `React.createElement`'s own overloads are `@types/react`'s, and
+// they describe the DOM: a `<box onKeyDown>` handler is checked against
+// React's `KeyboardEvent`, not react-x11's, and the whole props object is
+// measured against `DOMAttributes`. Everything interesting fails.
+//
+// So the element name is looked up in react-x11's own element table instead.
+// `hx('box', …)` gets `<box>`'s real props — `ev.keysym` on a key handler,
+// `onDraw` on a `<canvas>` — and `hx('div', …)` is an error, which is the
+// same guarantee the JSX namespace gives `examples/` and `test/types/`.
+import React from 'react';
+import type { Key, ReactElement, ReactNode } from 'react';
+import type { ReactX11Elements, Theme } from 'react-x11';
+
+/** The host elements, by name. */
+export type Host = ReactX11Elements;
+
+/**
+ * What every element takes on top of its own props.
+ *
+ * `theme` is honoured by **every** node — `Node.theme` merges `props.theme`
+ * over the inherited palette, whatever the kind — but react-x11's element
+ * declarations only put it on `<window>`. A widget re-declares the theme it
+ * read from context onto its own root so that `$token` values still resolve
+ * inside a `<popup>`, which is a separate window and does not inherit the
+ * trigger's node tree. So the prop is real; only the declaration is narrow.
+ */
+interface CommonProps {
+  key?: Key;
+  /** `Theme` is listed alongside the record because it is an interface, and
+   *  an interface has no implicit index signature — so the palette `useTheme`
+   *  hands back is not assignable to the record react-x11 declares. */
+  theme?: Theme | Record<string, string | number>;
+}
+
+export function hx<K extends keyof Host>(
+  type: K,
+  // `theme` is dropped from the element's own props before the merge:
+  // `<window>` and `<popup>` already declare it, narrower, and intersecting
+  // the two would demand a value satisfying both.
+  props?: (Omit<Host[K], 'theme'> & CommonProps) | null,
+  ...children: ReactNode[]
+): ReactElement {
+  // The cast is the whole point of the wrapper: `createElement`'s string
+  // overload insists on DOM props, and the signature above has already
+  // checked these against the element that will actually receive them.
+  return React.createElement(type as string, props as never, ...children);
+}

package/src/code/index.ts

@@ -0,0 +1,174 @@
+// <Code> — a static, read-only code block: syntax highlighting through the
+// same language seam `<CodeEditor>` tokenizes with (`../code-language/`), a
+// look shared with `<Markdown>`'s fenced blocks (`../codeblock/`), and text
+// laid out in the same `<richtext>` element `<Markdown>` renders
+// (`../richtext/`). For showing code, not editing it: no caret, no history,
+// no completion — an app that wants those renders `<CodeEditor>` (readOnly
+// or otherwise) and pays for them.
+//
+// The composition is one `<richtext>` for the whole text (unwrapped, in a
+// horizontally scrolling viewport) plus an optional line-number gutter,
+// inside a `selectable` root. Selection, copy, Ctrl+A and PRIMARY are all
+// core's since react-x11#291; what is left here is saying which parts of the
+// block are text a reader would want — the gutter is `selectable={false}`,
+// so copied code never carries the numbering.
+import React from 'react';
+import type { ReactElement } from 'react';
+import { useTheme } from 'react-x11';
+import type { Style } from 'react-x11/style';
+
+import {
+  registerRichText,
+  RICHTEXT_ELEMENT,
+  useSelectionMenu,
+} from '../richtext/index.js';
+import type { RichTextProps, TextRun } from '../richtext/index.js';
+import {
+  codeBlockLook,
+  codeBlockRuns,
+  codeBlockStyle,
+  codeTextStyle,
+} from '../codeblock/index.js';
+import type { Language, TokenStyles } from '../code-language/index.js';
+import { hx } from './hx.js';
+
+const h = React.createElement;
+
+// The shared-module registration, called at this component's module scope —
+// see the note in `../richtext/node.ts`.
+registerRichText();
+
+export interface CodeProps {
+  /** The code, verbatim. */
+  source: string;
+  /** A fence-style tag — `'js'`, `'tsx'`, `'bash'`, `'sql'`… Unknown tags
+   *  fall back to ntk's highlighter when present, then to plain text. */
+  lang?: string;
+  /** An explicit `Language` (a Lezer or TextMate adapter, say). Takes
+   *  precedence over `lang`. */
+  language?: Language;
+  /** A `Language` for a `lang` the built-ins do not cover —
+   *  `hljsLanguage` goes here. Null for a tag it does not know. */
+  resolveLanguage?: (tag: string) => Language | null;
+  /** A line-number gutter. Numbers are not part of the selection, so
+   *  copied code pastes clean. Ignored when `wrap` is on — a wrapped
+   *  source line would put the numbering out of register. */
+  lineNumbers?: boolean;
+  /** Wrap long lines instead of scrolling horizontally. Default false. */
+  wrap?: boolean;
+  /** Mouse selection, Ctrl+A / Ctrl+C, PRIMARY. Default true. */
+  selectable?: boolean;
+  /** Default: 0.9 × the theme `fontSize`, matching `<Markdown>`'s blocks. */
+  fontSize?: number;
+  /** Default `'monospace'` — there is no theme token for it. */
+  monoFamily?: string;
+  /** Token palette override; the default follows the theme background,
+   *  and `'$token'` colours in it resolve against the theme. */
+  tokenStyles?: TokenStyles;
+  /** Selection band fill. Default: theme accent at 35% opacity. */
+  selectionColor?: string;
+  /** The root `<box>`'s style — width, margins, `flexGrow`. */
+  style?: Style | Style[];
+  'data-testname'?: string;
+}
+
+/**
+ * A code block.
+ *
+ * ```jsx
+ * <Code source={snippet} lang="ts" lineNumbers />
+ * ```
+ */
+export function Code(props: CodeProps): ReactElement {
+  const {
+    source,
+    lang = '',
+    language,
+    resolveLanguage,
+    wrap = false,
+    selectable = true,
+    selectionColor,
+  } = props;
+  const lineNumbers = (props.lineNumbers ?? false) && !wrap;
+  // `Theme` is an interface, so it has no implicit index signature — the
+  // same widening `hx.ts` documents for the `theme` prop.
+  const theme = useTheme() as unknown as Record<string, unknown>;
+  const menu = useSelectionMenu(selectable);
+
+  const look = React.useMemo(
+    () =>
+      codeBlockLook(theme, {
+        fontSize: props.fontSize,
+        monoFamily: props.monoFamily,
+        tokenStyles: props.tokenStyles,
+      }),
+    [theme, props.fontSize, props.monoFamily, props.tokenStyles],
+  );
+
+  const runs: TextRun[] = React.useMemo(
+    () => codeBlockRuns(source, look, { lang, language, resolveLanguage }),
+    [source, lang, language, resolveLanguage, look],
+  );
+
+  const lineCount = React.useMemo(() => source.split('\n').length, [source]);
+
+  const codeProps: RichTextProps = { runs, style: codeTextStyle(look) };
+  if (!wrap) codeProps.wrap = false;
+
+  const gutter = lineNumbers
+    ? h(RICHTEXT_ELEMENT, {
+        // one richtext for all the numbers: same font, same line height, so
+        // it stays in register with the code beside it. `selectable={false}`
+        // is what keeps it out of a drag and out of the copied text — the
+        // numbering is chrome, and CSS spells that `user-select: none`.
+        selectable: false,
+        runs: Array.from({ length: lineCount }, (_, i) => ({
+          text: `${i + 1}\n`,
+          family: look.family,
+          size: look.size,
+          color: look.dim,
+        })),
+        wrap: false,
+        style: {
+          lineHeight: look.lineHeight,
+          textAlign: 'right',
+          minWidth:
+            Math.max(String(lineCount).length, 2) * Math.ceil(look.size * 0.62),
+          marginRight: look.padding,
+          flexShrink: 0,
+        },
+      } as Record<string, unknown>)
+    : null;
+
+  const rootStyle: Style = {
+    ...codeBlockStyle(look),
+    flexDirection: 'row',
+    alignItems: 'stretch',
+  };
+
+  return hx(
+    'box',
+    {
+      style: props.style
+        ? [
+            rootStyle,
+            ...(Array.isArray(props.style) ? props.style : [props.style]),
+          ]
+        : rootStyle,
+      // The whole feature: a drag selects across everything below, a double
+      // click takes a word, Ctrl+C copies, PRIMARY follows the release. The
+      // surface is a focus target and shows an I-beam because it said this.
+      selectable,
+      selectionColor,
+      'aria-label': 'Code block',
+      ...menu,
+      'data-testname': props['data-testname'],
+    } as Record<string, unknown>,
+    gutter,
+    hx(
+      'box',
+      { style: { overflow: 'scroll', flexDirection: 'column', flexGrow: 1 } },
+      h(RICHTEXT_ELEMENT, codeProps as unknown as Record<string, unknown>),
+    ),
+  );
+}