@gemboss/ui 0.25.0 → 0.30.2

package/src/minichart.tsx

@@ -0,0 +1,165 @@
+/**
+ * Two charts small enough to sit inside a card or a table cell — @gemboss/ui 0.30.0.
+ *
+ * `Sparkline`: the trend line every surface was drawing by hand. Counted 08/10/2026: the admin (intelligence `Spark`,
+ * analytics KPIs, operator), talent-radar trends, search-radar `Spark.jsx`, gemwatcher's pulse, content-radar's archive,
+ * gemform's form cards: six hand copies, three ways of choosing the baseline, one with gaps for a missing day.
+ * `ShareBar`: one bar split by share, e.g. a form's registrations by status (gemform). The kit's `ui-progress` is one
+ * value, `ui-barlist` one bar per row; neither says "how these N parts divide one whole" in one line.
+ *
+ * Server-renderable (no state, no effect). Colours are tokens (`--ui-spark-c`, `--c`), so the dark palette follows.
+ * ShareBar sizes its segments with an inline `flex-grow`: a plain-HTML page under a CSP that forbids inline style
+ * (gemcare: `style-src 'self'`) has to size them from its own stylesheet or script.
+ * A page that writes the markup itself (no React) computes the path with `sparklinePaths` (pure, `@gemboss/ui` index)
+ * or by hand, and links `minichart.css`.
+ */
+import "./minichart.css"; // its own entry (0.30.0): a surface that draws no mini chart never downloads it
+import React from "react";
+
+const cx = (...p: Array<string | false | null | undefined>) => p.filter(Boolean).join(" ");
+const r1 = (n: number) => Math.round(n * 10) / 10;
+
+/** A value, or a gap (`null` / `undefined` / NaN): a day with no reading breaks the line instead of drawing a zero. */
+export type SparkPoint = number | null | undefined;
+
+export interface SparklineGeometry {
+  width: number;
+  height: number;
+  /** One `d` per unbroken run of two or more points. */
+  lines: string[];
+  /** One closed `d` per run, down to the baseline (empty when `area` is off). */
+  areas: string[];
+  /** Points with no neighbour on either side: drawn as dots, a line of one point is invisible. */
+  dots: Array<[number, number]>;
+  /** The newest point, when the newest reading is a number (the "now" dot). */
+  last: [number, number] | null;
+}
+
+const isNum = (v: SparkPoint): v is number => typeof v === "number" && Number.isFinite(v);
+
+/**
+ * The geometry of a sparkline, oldest point first, as SVG path data in a `width` x `height` box.
+ *
+ * The scale is honest by default: from 0 when every value is >= 0 (a count drawn from its own minimum turns 5, 4, 5
+ * into a cliff), otherwise from the smallest value. `min` / `max` fix it, e.g. a 30-day window that must not rescale.
+ * `invert` puts small values at the top (a rank: #1 is best).
+ */
+export function sparklinePaths(points: readonly SparkPoint[], opts: {
+  width?: number; height?: number; pad?: number; min?: number; max?: number; invert?: boolean; area?: boolean;
+} = {}): SparklineGeometry | null {
+  const { width = 120, height = 28, pad = 3, invert = false, area = true } = opts;
+  const vals = points.filter(isNum);
+  if (!vals.length) return null;
+  const lo = opts.min ?? (Math.min(...vals) >= 0 ? 0 : Math.min(...vals));
+  const hi = Math.max(opts.max ?? Math.max(...vals), lo + 1e-9);
+  const span = hi - lo || 1;
+  const n = points.length;
+  const x = (i: number) => r1(n === 1 ? width / 2 : pad + (i * (width - 2 * pad)) / (n - 1));
+  const y = (v: number) => {
+    const t = (Math.min(Math.max(v, lo), hi) - lo) / span;
+    return r1(invert ? pad + t * (height - 2 * pad) : height - pad - t * (height - 2 * pad));
+  };
+  // The area always fills DOWN to the bottom edge: under an inverted scale too, so the better (higher) a rank, the more
+  // ground under it; filled up to the top it read as shading above the line.
+  const base = height - pad;
+  const runs: Array<Array<[number, number]>> = [];
+  let cur: Array<[number, number]> | null = null;
+  // An index loop, not forEach: forEach skips the holes of a sparse array (`new Array(7)` with two days filled), and a
+  // hole is a day with no reading, which must break the line like `null` does.
+  for (let i = 0; i < n; i++) {
+    const v = points[i];
+    if (!isNum(v)) { cur = null; continue; }
+    if (!cur) { cur = []; runs.push(cur); }
+    cur.push([x(i), y(v)]);
+  }
+  const lines: string[] = [];
+  const areas: string[] = [];
+  const dots: Array<[number, number]> = [];
+  for (const run of runs) {
+    if (run.length === 1) { dots.push(run[0]); continue; }
+    const d = run.map(([px, py], j) => `${j ? "L" : "M"}${px} ${py}`).join(" ");
+    lines.push(d);
+    if (area) areas.push(`${d} L${run[run.length - 1][0]} ${base} L${run[0][0]} ${base} Z`);
+  }
+  const lastV = points[n - 1];
+  return { width, height, lines, areas, dots, last: isNum(lastV) ? [x(n - 1), y(lastV)] : null };
+}
+
+export type SparkTone = "neutral" | "series" | "success" | "critical";
+// Whole class names, never built from a template: a class written out is a class grep (and the admin's orphan-rule gate,
+// a-tap-target-rule-outlived-its-markup) can find.
+const SPARK_TONE: Record<SparkTone, string> = { neutral: "", series: "ui-spark--series", success: "ui-spark--success", critical: "ui-spark--critical" };
+
+/**
+ * A trend line. The line is muted ink and the newest point is one iris dot: the accent marks "now" and nothing else.
+ * `tone` colours the line for a series that means something (`success` / `critical`), `series` for iris.
+ * With `label` it is an image with that name (say what it shows: "Registrations, last 7 days: 3 then 5"); without it,
+ * it is decoration beside a number that already says it (aria-hidden).
+ */
+export function Sparkline({ points, width = 120, height = 28, label, tone = "neutral", area = true, endDot = true, min, max, invert, className }: {
+  points: readonly SparkPoint[];
+  width?: number;
+  height?: number;
+  label?: string;
+  tone?: SparkTone;
+  area?: boolean;
+  endDot?: boolean;
+  min?: number;
+  max?: number;
+  invert?: boolean;
+  className?: string;
+}) {
+  const g = sparklinePaths(points, { width, height, min, max, invert, area });
+  if (!g) return null;
+  const a11y = label ? { role: "img", "aria-label": label } : { "aria-hidden": true as const, focusable: "false" as const };
+  return (
+    <svg className={cx("ui-spark", SPARK_TONE[tone], className)} width={width} height={height}
+      viewBox={`0 0 ${width} ${height}`} {...a11y}>
+      {label ? <title>{label}</title> : null}
+      {g.areas.map((d) => <path key={`a${d}`} className="ui-spark__area" d={d} />)}
+      {g.lines.map((d) => <path key={`l${d}`} className="ui-spark__line" d={d} />)}
+      {g.dots.map(([cx_, cy]) => <circle key={`p${cx_}`} className="ui-spark__pt" cx={cx_} cy={cy} r={1.5} />)}
+      {endDot && g.last ? <circle className="ui-spark__end" cx={g.last[0]} cy={g.last[1]} r={2.5} /> : null}
+    </svg>
+  );
+}
+
+/** A part's colour: a status tone (the same five the kit's badges use) or a chart series. */
+export type ShareTone = "neutral" | "info" | "success" | "warning" | "critical" | "series-1" | "series-2" | "series-3" | "series-4" | "series-5";
+
+const SEG: Record<ShareTone, string> = {
+  neutral: "ui-sharebar__seg--neutral", info: "ui-sharebar__seg--info", success: "ui-sharebar__seg--success",
+  warning: "ui-sharebar__seg--warning", critical: "ui-sharebar__seg--critical", "series-1": "ui-sharebar__seg--series-1",
+  "series-2": "ui-sharebar__seg--series-2", "series-3": "ui-sharebar__seg--series-3", "series-4": "ui-sharebar__seg--series-4",
+  "series-5": "ui-sharebar__seg--series-5",
+};
+const SERIES: ShareTone[] = ["series-1", "series-2", "series-3", "series-4", "series-5"];
+
+export interface SharePart {
+  label: string;
+  value: number;
+  /** Defaults to the series colours in order. */
+  tone?: ShareTone;
+  key?: string;
+}
+
+/**
+ * One bar, split by share. Parts at 0 take no room; an all-zero bar is the empty track. The bar is one image whose
+ * name lists every part ("Status: New 25, Contacted 2, Qualified 4"), so a screen reader hears the numbers the
+ * colours stand for; each segment's `title` says its own on hover.
+ */
+export function ShareBar({ parts, label, className }: { parts: readonly SharePart[]; label?: string; className?: string }) {
+  const shown = parts.map((p, i) => ({ ...p, tone: p.tone ?? SERIES[i % 5] })).filter((p) => p.value > 0);
+  const total = shown.reduce((a, p) => a + p.value, 0);
+  const said = parts.map((p) => `${p.label} ${p.value}`).join(", ");
+  return (
+    <div className={cx("ui-sharebar", className)} role="img" aria-label={label ? `${label}: ${said}` : said}>
+      {shown.map((p) => (
+        // The SHARE, not the raw value: flex-grow values that add up to less than 1 hand out only that fraction of the
+        // track (0.2 + 0.3 filled half the bar). Shares always add up to 1.
+        <span key={p.key ?? p.label} className={cx("ui-sharebar__seg", SEG[p.tone])} style={{ flexGrow: +(p.value / total).toFixed(4) }}
+          title={`${p.label} ${p.value}`} />
+      ))}
+    </div>
+  );
+}

package/src/setup-guide.css

@@ -0,0 +1 @@
+.ui-setup,.ui-setup__inner{display:grid;gap:var(--ui-space-3, 12px)}.ui-setup__head,.ui-setup__row{display:flex;align-items:center;gap:var(--ui-space-3, 12px);list-style:none;cursor:pointer;border-radius:var(--ui-radius-md, 8px);color:inherit;transition:background-color .12s ease}.ui-setup__head::-webkit-details-marker,.ui-setup__row::-webkit-details-marker{display:none}div.ui-setup__head{cursor:auto}summary.ui-setup__head{padding:6px 8px;margin:-6px -8px 0}.ui-setup__title{margin:0;font-size:var(--ui-fs-body, 13px);line-height:20px;font-weight:650;color:var(--ui-text-strong, var(--ui-text))}.ui-setup__desc{margin:0;font-size:var(--ui-fs-body, 13px);line-height:20px;color:var(--ui-text-muted)}.ui-setup__row{padding:8px;margin:0 -8px}summary.ui-setup__head:hover,summary.ui-setup__row:hover{background:var(--ui-surface-2, #eceef2)}.ui-setup__row--static{cursor:auto}.ui-setup__row.ui-setup__row--static:after{content:none}summary.ui-setup__head:active,summary.ui-setup__row:active{background:var(--ui-border, #e5e7ea)}summary.ui-setup__head:focus-visible,summary.ui-setup__row:focus-visible{outline:2px solid var(--ui-focus, #5661f5);outline-offset:2px}summary.ui-setup__head:after,.ui-setup__row:after{content:"\25be";margin-left:auto;font-size:11px;color:var(--ui-text-muted);transition:transform .12s ease}.ui-setup:not([open])>summary.ui-setup__head:after,.ui-setup__step:not([open])>.ui-setup__row:after{transform:rotate(-90deg)}.ui-setup__bar{appearance:none;-webkit-appearance:none;display:block;width:100%;height:6px;border:0;border-radius:999px;overflow:hidden;background:var(--ui-border, #e5e7ea);color:var(--ui-accent, #1b1c1e)}.ui-setup__bar::-webkit-progress-bar{background:var(--ui-border, #e5e7ea);border-radius:inherit}.ui-setup__bar::-webkit-progress-value{background:currentColor;border-radius:inherit;transition:width .15s ease}.ui-setup__bar::-moz-progress-bar{background:currentColor;border-radius:inherit}.ui-setup__bar--done{color:var(--ui-success-fg, #007f5f)}.ui-setup__steps{display:grid;gap:2px}.ui-setup__mark{flex:0 0 16px;text-align:center;line-height:20px;color:var(--ui-text-muted)}.ui-setup__step[data-state=done] .ui-setup__mark{color:var(--ui-success-fg, #007f5f)}.ui-setup__label{min-width:0;overflow-wrap:anywhere;font-size:var(--ui-fs-body, 13px);line-height:20px;font-weight:550;color:var(--ui-text)}.ui-setup__step[data-state=done] .ui-setup__label{font-weight:450;color:var(--ui-text-muted)}.ui-setup__body{padding:4px 0 12px 28px;font-size:var(--ui-fs-body, 13px);line-height:20px;color:var(--ui-text)}.ui-setup__body>:first-child{margin-top:0}.ui-setup__body>:last-child{margin-bottom:0}@media (pointer: coarse),(max-width: 47.9975em){summary.ui-setup__head,.ui-setup__row{min-height:44px;box-sizing:border-box}}@media (prefers-reduced-motion: reduce){.ui-setup__head,.ui-setup__row,summary.ui-setup__head:after,.ui-setup__row:after,.ui-setup__bar::-webkit-progress-value{transition:none}}

package/src/setup-guide.tsx

@@ -0,0 +1,116 @@
+"use client";
+
+/**
+ * Setup guide — @gemboss/ui 0.30.0. The admin's "Set up your store" card (apps/admin StoreChecklistCard, Shopify's own
+ * Setup guide) as a component any surface can give its steps to: a title with the count, a bar, and collapsed step
+ * rows of which one is open. Six steps expanded is a wall; collapsed rows scan in a second and the open one is the next
+ * thing worth doing.
+ *
+ * Why it moved here (08/10/2026): gemform's Telegram alerts page drew its own numbered steps (1 The bot, 2 Where alerts
+ * go), the admin has this one in Polaris, and a third surface with a "connect this, then that" page would write a third.
+ *
+ * Native `<details>` all the way down, so a page that writes the markup by hand gets the same behaviour with no script:
+ * the guide is a `<details>` whose `<summary>` folds it away, each step is a `<details name>` of one group, which the
+ * browser keeps to one open at a time. The ROW reveals; what changes something is a button the surface puts in the
+ * step's body (one gesture, one meaning, as in the admin). A step with no body is a plain row, not a toggle that opens
+ * nothing.
+ *
+ * The step open at first is the first one not done, decided ONCE, like the admin: a step's state changing while the
+ * person reads it must not slam it shut (finishing step 1 leaves its confirmation on screen). The bar is a <progress>,
+ * not a width in a style attribute, so it fills under a CSP that forbids inline style.
+ */
+import "./setup-guide.css"; // its own entry (0.30.0)
+import React, { useEffect, useId, useRef, useState } from "react";
+
+const cx = (...p: Array<string | false | null | undefined>) => p.filter(Boolean).join(" ");
+
+/** `unknown`: could not be read, so neither done nor to do; counted apart, never as progress. */
+export type SetupState = "todo" | "done" | "unknown";
+
+export interface SetupStep {
+  id: string;
+  title: React.ReactNode;
+  state?: SetupState;
+  /** What the open step shows: a sentence and the control that does it. Without one the row is not a toggle. */
+  body?: React.ReactNode;
+}
+
+const MARK: Record<SetupState, string> = { done: "✓", todo: "○", unknown: "?" };
+
+export function SetupGuide({ title, description, steps, open, collapsible = true, rememberKey, group, labels, className }: {
+  title: React.ReactNode;
+  description?: React.ReactNode;
+  steps: readonly SetupStep[];
+  /** The step to show open at first; defaults to the first one not done. */
+  open?: string;
+  /** false: the head is a plain heading, the guide cannot be folded away. */
+  collapsible?: boolean;
+  /** Remember a folded guide in localStorage under this key, so someone not setting up today is not asked again on every
+   *  visit. Give each place its own key (folding it on one page is not folding it everywhere). */
+  rememberKey?: string;
+  /** The steps' shared `name`. Defaults to a useId(), unique within one React root; pass one when two guides render in
+   *  separate roots or separate static renders. */
+  group?: string;
+  labels?: { progress?: string; notMeasured?: (n: number) => string };
+  className?: string;
+}) {
+  const auto = useId();
+  const name = group ?? `gb-setup${auto}`;
+  // Decided once (see the header): later renders keep whatever the person opened.
+  const [first] = useState(() => open ?? steps.find((s) => s.state !== "done" && s.body)?.id);
+  const guide = useRef<HTMLDetailsElement>(null);
+  useEffect(() => {
+    const el = guide.current;
+    if (!el || !rememberKey) return undefined;
+    try { if (localStorage.getItem(rememberKey) === "folded") el.open = false; } catch { /* storage blocked: stay open */ }
+    const onToggle = () => { try { localStorage.setItem(rememberKey, el.open ? "open" : "folded"); } catch { /* ignore */ } };
+    el.addEventListener("toggle", onToggle);
+    return () => el.removeEventListener("toggle", onToggle);
+  }, [rememberKey]);
+
+  if (!steps.length) return null; // nothing to set up is no guide, not a "0/0" card
+  const total = steps.length;
+  const done = steps.filter((s) => s.state === "done").length;
+  const unknown = steps.filter((s) => s.state === "unknown").length;
+  const all = done === total;
+  const head = (
+    <>
+      <h2 className="ui-setup__title">{title}</h2>
+      <span className={cx("ui-badge", all ? "ui-badge--success" : "ui-badge--warning")}>{`${done}/${total}`}</span>
+      {unknown > 0 ? <span className="ui-badge">{labels?.notMeasured?.(unknown) ?? `${unknown} not measured`}</span> : null}
+    </>
+  );
+  // One wrapper for everything under the head: a <details> lays out its summary and ONE content slot, so a gap set on
+  // the guide never reaches between the description, the bar and the steps (measured in Chromium 148).
+  const inner = (
+    <div className="ui-setup__inner">
+      {description ? <p className="ui-setup__desc">{description}</p> : null}
+      <progress className={cx("ui-setup__bar", all && "ui-setup__bar--done")} value={done} max={total}
+        aria-label={labels?.progress ?? "Setup progress"}>{`${done}/${total}`}</progress>
+      <div className="ui-setup__steps">
+        {steps.map((s) => {
+          const state = s.state ?? "todo";
+          const row = (as: "summary" | "div") => React.createElement(as, { className: cx("ui-setup__row", as === "div" && "ui-setup__row--static") },
+            <span className="ui-setup__mark" aria-hidden="true">{MARK[state]}</span>,
+            <span className="ui-setup__label">{s.title}</span>);
+          if (!s.body) return <div key={s.id} className="ui-setup__step" data-state={state}>{row("div")}</div>;
+          return (
+            <details key={s.id} className="ui-setup__step" name={name} open={s.id === first} data-state={state}>
+              {row("summary")}
+              <div className="ui-setup__body">{s.body}</div>
+            </details>
+          );
+        })}
+      </div>
+    </div>
+  );
+  if (!collapsible) {
+    return <section className={cx("ui-card ui-setup", className)}><div className="ui-setup__head">{head}</div>{inner}</section>;
+  }
+  return (
+    <details className={cx("ui-card ui-setup", className)} open ref={guide}>
+      <summary className="ui-setup__head">{head}</summary>
+      {inner}
+    </details>
+  );
+}