cortena-ui 0.1.0 → 1.0.0

package/src/components/chart/tokens.ts

@@ -0,0 +1,210 @@
+"use client";
+
+import { useEffect, useState } from "react";
+import { vizSeries } from "cortena-design/tokens";
+
+/**
+ * Token plumbing for the chart engines.
+ *
+ * Recharts draws SVG, so it can take `var(--ds-viz-1)` verbatim and the
+ * browser resolves it. Nivo cannot: its canvas renderer hands colours to a
+ * 2D context, and its SVG renderer runs colours through d3-color for label and
+ * border derivation, and neither understands `var()`. So every Nivo value is
+ * read from the `--ds-*` custom property at runtime and handed over as a
+ * concrete hex. Nothing in this file is a literal; on the server (no DOM) the
+ * `var()` form is returned so SSR markup still resolves in the browser.
+ */
+
+/** Number of categorical series colours the design system defines (`--ds-viz-1..n`). */
+export const VIZ_SERIES_COUNT = vizSeries.length;
+
+/** `var(--ds-viz-N)` for a zero-based series index, wrapping past the palette. */
+export function vizVar(index: number): string {
+  const n = VIZ_SERIES_COUNT;
+  return `var(--ds-viz-${(((index % n) + n) % n) + 1})`;
+}
+
+/** The categorical palette as `var()` references, in series order. */
+export const vizSeriesVars: readonly string[] = Array.from({ length: VIZ_SERIES_COUNT }, (_, i) =>
+  vizVar(i),
+);
+
+function hasDom(): boolean {
+  return typeof document !== "undefined" && typeof getComputedStyle === "function";
+}
+
+/** Read a custom property as the browser computes it on `el` (default: `<html>`). */
+export function readToken(name: string, el?: Element | null): string {
+  if (!hasDom()) return "";
+  return getComputedStyle(el ?? document.documentElement).getPropertyValue(name).trim();
+}
+
+/** A `--ds-text-*` size (rem or px) as a pixel number, for engines that want numbers. */
+export function tokenPx(name: string, el?: Element | null): number | undefined {
+  const raw = readToken(name, el);
+  if (!raw) return undefined;
+  const n = Number.parseFloat(raw);
+  if (Number.isNaN(n)) return undefined;
+  if (raw.endsWith("rem")) {
+    const root = Number.parseFloat(getComputedStyle(document.documentElement).fontSize) || 16;
+    return n * root;
+  }
+  return n;
+}
+
+let probe: CanvasRenderingContext2D | null | undefined;
+
+function hex2(n: number): string {
+  return n.toString(16).padStart(2, "0");
+}
+
+/**
+ * Convert any CSS colour the browser understands (oklch, color-mix, rgba…) to
+ * `#rrggbb`, by painting it into an offscreen 2D context. Alpha is composited
+ * against transparent, so translucent tokens come back opaque; chart fills
+ * never use those.
+ */
+export function toHex(css: string): string | undefined {
+  if (!hasDom() || !css) return undefined;
+  if (probe === undefined) {
+    probe = document.createElement("canvas").getContext("2d", { willReadFrequently: true });
+  }
+  if (!probe) return undefined;
+  probe.clearRect(0, 0, 1, 1);
+  probe.fillStyle = css;
+  probe.fillRect(0, 0, 1, 1);
+  const d = probe.getImageData(0, 0, 1, 1).data;
+  return `#${hex2(d[0] ?? 0)}${hex2(d[1] ?? 0)}${hex2(d[2] ?? 0)}`;
+}
+
+/**
+ * A token as a concrete colour. Returns hex in the browser; on the server the
+ * `var()` form, which is fine for SVG markup and irrelevant for canvas.
+ */
+export function resolveColor(token: string, el?: Element | null): string {
+  return toHex(readToken(token, el)) ?? `var(${token})`;
+}
+
+/** The categorical palette resolved to concrete colours, in series order. */
+export function resolveVizSeries(el?: Element | null): string[] {
+  return vizSeriesVars.map((_, i) => resolveColor(`--ds-viz-${i + 1}`, el));
+}
+
+/** Relative luminance of a `#rrggbb`, for choosing a scale direction. */
+function luminance(hex: string): number {
+  const c = (i: number) => {
+    const v = Number.parseInt(hex.slice(i, i + 2), 16) / 255;
+    return v <= 0.03928 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4;
+  };
+  return 0.2126 * c(1) + 0.7152 * c(3) + 0.0722 * c(5);
+}
+
+/**
+ * A label colour that reads on a given fill: the design system's ink on light
+ * fills, its white on dark ones. Nivo cells and arcs paint their labels with
+ * this so a value on a deep sequential cell stays legible.
+ */
+export function contrastLabel(el?: Element | null): (fill: string) => string {
+  const ink = resolveColor("--ds-base-text-ink", el);
+  const white = resolveColor("--ds-base-white", el);
+  return (fill: string) => {
+    const hex = fill.startsWith("#") && fill.length === 7 ? fill : toHex(fill);
+    return hex && luminance(hex) < 0.3 ? white : ink;
+  };
+}
+
+/** True when the resolved `--ds-background` is dark, whatever set the theme (attribute or OS). */
+export function isDarkSurface(el?: Element | null): boolean {
+  const bg = toHex(readToken("--ds-background", el));
+  return bg ? luminance(bg) < 0.4 : false;
+}
+
+/** Linear interpolation through a list of hex stops; `t` in [0, 1]. */
+export function piecewiseHex(stops: string[]): (t: number) => string {
+  const rgb = stops.map((h) => [1, 3, 5].map((i) => Number.parseInt(h.slice(i, i + 2), 16)));
+  return (t: number) => {
+    const clamped = Math.min(1, Math.max(0, Number.isNaN(t) ? 0 : t));
+    const pos = clamped * (rgb.length - 1);
+    const i = Math.max(0, Math.min(rgb.length - 2, Math.floor(pos)));
+    const f = pos - i;
+    const a = rgb[i] ?? [0, 0, 0];
+    const b = rgb[i + 1] ?? a;
+    const mix = (k: number) => Math.round((a[k] ?? 0) + ((b[k] ?? 0) - (a[k] ?? 0)) * f);
+    return `#${hex2(mix(0))}${hex2(mix(1))}${hex2(mix(2))}`;
+  };
+}
+
+export interface ChartScales {
+  /** Low → high, as concrete hex stops. */
+  sequential: string[];
+  /** Negative → neutral → positive, as concrete hex stops. */
+  diverging: string[];
+  /** Interpolators over the stops, `t` in [0, 1], for Nivo's `interpolator` configs. */
+  sequentialInterpolator: (t: number) => string;
+  divergingInterpolator: (t: number) => string;
+  /** `n` evenly spaced sequential swatches, for quantised fills like the calendar. */
+  sequentialSteps: (n: number) => string[];
+  /** Fill for cells with no value. */
+  empty: string;
+  /** The chart's surface (`--ds-background`), for the gaps between cells and arcs. */
+  surface: string;
+}
+
+/**
+ * Sequential and diverging scales from the tokens.
+ *
+ * The token set has only the eight categorical `--ds-viz-*` colours and no
+ * sequential ramp, so the sequential scale is derived from the
+ * `--ds-primary-100..900` ladder: light surfaces run 100 → 700 (pale to deep),
+ * dark surfaces run 900 → 400 (deep to bright), so low values sit near the
+ * background in both themes. The diverging scale runs `--ds-viz-5` (rose)
+ * through the theme's neutral (`--ds-neutral-200` light, `--ds-neutral-700`
+ * dark) to `--ds-viz-1` (blue).
+ */
+export function chartScales(el?: Element | null): ChartScales {
+  const dark = isDarkSurface(el);
+  const seqTokens = dark
+    ? ["--ds-primary-900", "--ds-primary-800", "--ds-primary-600", "--ds-primary-400"]
+    : ["--ds-primary-100", "--ds-primary-300", "--ds-primary-500", "--ds-primary-700"];
+  const sequential = seqTokens.map((t) => resolveColor(t, el));
+  const diverging = ["--ds-viz-5", dark ? "--ds-neutral-700" : "--ds-neutral-200", "--ds-viz-1"].map(
+    (t) => resolveColor(t, el),
+  );
+  const sequentialInterpolator = piecewiseHex(sequential);
+  const divergingInterpolator = piecewiseHex(diverging);
+  return {
+    sequential,
+    diverging,
+    sequentialInterpolator,
+    divergingInterpolator,
+    sequentialSteps: (n) =>
+      Array.from({ length: n }, (_, i) => sequentialInterpolator(n === 1 ? 1 : i / (n - 1))),
+    empty: resolveColor("--ds-muted", el),
+    surface: resolveColor("--ds-background", el),
+  };
+}
+
+/**
+ * A counter that bumps whenever the theme may have changed: the `data-theme`
+ * or `class` attribute on `<html>`, or the OS colour scheme. Resolved token
+ * values are memoised on it so Nivo re-reads them on a flip.
+ */
+export function useThemeVersion(): number {
+  const [version, setVersion] = useState(0);
+  useEffect(() => {
+    if (!hasDom()) return;
+    const bump = () => setVersion((v) => v + 1);
+    const observer = new MutationObserver(bump);
+    observer.observe(document.documentElement, {
+      attributes: true,
+      attributeFilter: ["data-theme", "class", "style"],
+    });
+    const media = window.matchMedia?.("(prefers-color-scheme: dark)");
+    media?.addEventListener?.("change", bump);
+    return () => {
+      observer.disconnect();
+      media?.removeEventListener?.("change", bump);
+    };
+  }, []);
+  return version;
+}

package/src/components/chart/types.ts

@@ -0,0 +1,142 @@
+import type * as React from "react";
+
+/**
+ * Chart types and the data shape each one expects.
+ *
+ * Engine per type (see cortena-docs/cortenaUI&Design/03-charting.md):
+ *
+ * | type                                                     | engine                    |
+ * | -------------------------------------------------------- | ------------------------- |
+ * | bar, line, area, pie, donut, scatter, radar, funnel      | Recharts (static import)  |
+ * | heatmap, calendar, treemap, sunburst                     | Nivo (lazy, per package)  |
+ *
+ * Data shapes (the webchat renderer's legacy shapes are all accepted):
+ *
+ * - **bar**, **radar**: `ChartRow[]` — one object per category with a string
+ *   category key (`indexBy`, inferred as the first string field) and one
+ *   numeric field per series (`keys`, inferred as every numeric field).
+ *   `[{ month: "Jan", revenue: 12, cost: 8 }, …]`. The series shape below is
+ *   also accepted and pivoted.
+ * - **line**, **area**: `ChartSeries[]` — `[{ id: "revenue", data: [{ x, y }] }]`
+ *   (the Nivo line shape the webchat emits). `ChartRow[]` is also accepted.
+ * - **pie**, **donut**, **funnel**: `ChartSlice[]` — `[{ id, label?, value }]`.
+ * - **scatter** (alias `scatterplot`): `ChartSeries[]` — one series per group.
+ * - **heatmap**: `ChartSeries[]` — Nivo heatmap shape, `[{ id: row, data: [{ x: column, y: value }] }]`.
+ * - **calendar**: `ChartDay[]` — `[{ day: "2026-01-31", value }]`; `from`/`to`
+ *   default to the data's range.
+ * - **treemap**, **sunburst**: `ChartTree` — Nivo tree, `{ id, children?: [...], value? }`
+ *   (`name` is accepted in place of `id`).
+ */
+export type ChartType =
+  | "bar"
+  | "line"
+  | "area"
+  | "pie"
+  | "donut"
+  | "scatter"
+  | "scatterplot"
+  | "radar"
+  | "funnel"
+  | "heatmap"
+  | "calendar"
+  | "treemap"
+  | "sunburst";
+
+/** The engine that draws a given type. */
+export type ChartEngine = "recharts" | "nivo";
+
+/** Nivo renderer; only the Nivo types honour it (Recharts is SVG only). */
+export type ChartRenderer = "svg" | "canvas";
+
+/** One category with a numeric value per series. */
+export type ChartRow = Record<string, string | number | null | undefined>;
+
+/** One series of points; x may be a category or a number, y a number. */
+export interface ChartPoint {
+  x: string | number;
+  y: number | null;
+}
+export interface ChartSeries {
+  id: string | number;
+  data: ChartPoint[];
+}
+
+/** One slice of a pie, donut or funnel. */
+export interface ChartSlice {
+  id: string | number;
+  label?: string;
+  value: number;
+}
+
+/** One day of a calendar heatmap. */
+export interface ChartDay {
+  day: string;
+  value: number;
+}
+
+/** A Nivo tree node for treemap and sunburst. */
+export interface ChartTree {
+  id?: string | number;
+  name?: string;
+  value?: number;
+  children?: ChartTree[];
+  [key: string]: unknown;
+}
+
+/** The data type accepted for each chart type. */
+export type ChartDataFor<T extends ChartType> = T extends "bar" | "radar"
+  ? ChartRow[] | ChartSeries[]
+  : T extends "line" | "area"
+    ? ChartSeries[] | ChartRow[]
+    : T extends "pie" | "donut" | "funnel"
+      ? ChartSlice[]
+      : T extends "scatter" | "scatterplot" | "heatmap"
+        ? ChartSeries[]
+        : T extends "calendar"
+          ? ChartDay[]
+          : T extends "treemap" | "sunburst"
+            ? ChartTree
+            : never;
+
+/**
+ * Per-series presentation, keyed by series id (the `keys` of a row chart, the
+ * `id` of a series or slice). Colours default to `var(--ds-viz-1..n)` in key
+ * order, so the same category index gets the same colour in every app; set
+ * `color` only to pin a category to a semantic colour, and then only to a
+ * token (`var(--ds-success)`), never a literal.
+ */
+export type ChartConfig = Record<
+  string,
+  {
+    label?: React.ReactNode;
+    icon?: React.ComponentType;
+    color?: string;
+  }
+>;
+
+/** Which continuous scale a heatmap or calendar uses. */
+export type ChartScale = "sequential" | "diverging";
+
+export const RECHARTS_TYPES: ReadonlySet<ChartType> = new Set<ChartType>([
+  "bar",
+  "line",
+  "area",
+  "pie",
+  "donut",
+  "scatter",
+  "scatterplot",
+  "radar",
+  "funnel",
+]);
+
+export const NIVO_TYPES: ReadonlySet<ChartType> = new Set<ChartType>([
+  "heatmap",
+  "calendar",
+  "treemap",
+  "sunburst",
+]);
+
+/** The engine the package uses for a chart type. */
+export function chartEngine(type: ChartType): ChartEngine {
+  return NIVO_TYPES.has(type) ? "nivo" : "recharts";
+}

package/src/components/checkbox.tsx

@@ -0,0 +1,49 @@
+"use client";
+
+import { Checkbox as BaseCheckbox } from "@base-ui/react/checkbox";
+import { Check, Minus } from "lucide-react";
+import type * as React from "react";
+import { cn } from "@/lib/cn";
+
+/**
+ * Checkbox.
+ *
+ * Base UI renders a `<span role="checkbox">` with a hidden `<input>` beside
+ * it, so it submits with forms and takes `checked`/`defaultChecked`. The
+ * indicator only mounts while checked or indeterminate; the icon inside it is
+ * a lucide Check, or a Minus when `indeterminate` is set.
+ *
+ * The 16px box takes half the small radius: the 8px ladder step would round
+ * it into a circle.
+ */
+export interface CheckboxProps extends React.ComponentProps<typeof BaseCheckbox.Root> {}
+
+function Checkbox({ className, indeterminate, ...props }: CheckboxProps) {
+  return (
+    <BaseCheckbox.Root
+      data-slot="checkbox"
+      indeterminate={indeterminate}
+      className={cn(
+        "peer inline-flex size-4 shrink-0 items-center justify-center rounded-[calc(var(--ds-radius-sm)/2)] border",
+        "border-[var(--ds-input)] bg-[var(--ds-background)]",
+        "transition-[background-color,border-color,box-shadow] duration-[var(--ds-duration-fast)] ease-[var(--ds-ease-out)]",
+        "outline-none focus-visible:ring-[3px] focus-visible:ring-[var(--ds-ring)]/40",
+        "data-[checked]:border-[var(--ds-primary)] data-[checked]:bg-[var(--ds-primary)] data-[checked]:text-[color:var(--ds-primary-foreground)]",
+        "data-[indeterminate]:border-[var(--ds-primary)] data-[indeterminate]:bg-[var(--ds-primary)] data-[indeterminate]:text-[color:var(--ds-primary-foreground)]",
+        "data-[disabled]:pointer-events-none data-[disabled]:opacity-50",
+        "aria-invalid:border-[var(--ds-destructive)] aria-invalid:ring-[3px] aria-invalid:ring-[var(--ds-destructive)]/20",
+        className,
+      )}
+      {...props}
+    >
+      <BaseCheckbox.Indicator
+        data-slot="checkbox-indicator"
+        className="flex items-center justify-center text-current [&_svg]:size-3.5 [&_svg]:shrink-0"
+      >
+        {indeterminate ? <Minus strokeWidth={3} /> : <Check strokeWidth={3} />}
+      </BaseCheckbox.Indicator>
+    </BaseCheckbox.Root>
+  );
+}
+
+export { Checkbox };

package/src/components/chip.tsx

@@ -0,0 +1,49 @@
+"use client";
+
+import { cva, type VariantProps } from "class-variance-authority";
+import type * as React from "react";
+import { cn } from "@/lib/cn";
+
+/**
+ * Chip — a pill for filters, tags and selected values. Unlike Badge it keeps
+ * sentence case and the body font.
+ */
+const chipVariants = cva(
+  [
+    "inline-flex items-center gap-1.5 whitespace-nowrap border font-medium",
+    "rounded-[var(--ds-radius-full)]",
+    "transition-[background-color,border-color,color]",
+    "duration-[var(--ds-duration-fast)] ease-[var(--ds-ease-out)]",
+    "[&_svg]:shrink-0",
+  ],
+  {
+    variants: {
+      variant: {
+        default:
+          "bg-[var(--ds-hover)] border-[var(--ds-border-subtle)] text-[color:var(--ds-muted-foreground)]",
+        accent: "bg-[var(--ds-primary-soft)] border-[var(--ds-ring)] text-[color:var(--ds-primary)]",
+        outline:
+          "bg-transparent border-[var(--ds-border)] text-[color:var(--ds-muted-foreground)]",
+      },
+      size: {
+        default: "px-2.5 py-1 text-[length:var(--ds-text-caption)] [&_svg]:size-3.5",
+        sm: "px-2 py-0.5 text-[length:var(--ds-text-caption-sm)] [&_svg]:size-3",
+      },
+    },
+    defaultVariants: {
+      variant: "default",
+      size: "default",
+    },
+  },
+);
+
+export interface ChipProps
+  extends React.ComponentProps<"span">, VariantProps<typeof chipVariants> {}
+
+function Chip({ className, variant, size, ...props }: ChipProps) {
+  return (
+    <span data-slot="chip" className={cn(chipVariants({ variant, size }), className)} {...props} />
+  );
+}
+
+export { Chip, chipVariants };