neba 1.13.0 → 1.16.0

package/dist/types.d.ts

@@ -27,7 +27,7 @@ export type NebaOrientation = 'horizontal' | 'vertical';
  * Which edge of an anchor something is placed against. Tooltip reads this, and
  * so does anything else that hangs a popup off an element.
  *
- * Logical rather than physical — `start`/`end` would be wrong here, because a
+ * Physical rather than logical — `start`/`end` would be wrong here, because a
  * tooltip above a button is above it in every writing direction.
  */
 export type NebaSide = 'top' | 'right' | 'bottom' | 'left';
@@ -86,6 +86,24 @@ export type NebaWeekday = 0 | 1 | 2 | 3 | 4 | 5 | 6;
  * would be reporting a day nobody chose.
  */
 export type NebaDateGranularity = 'day' | 'month' | 'year';
+/**
+ * How far a piece of work an agent is doing has got.
+ *
+ * One vocabulary rather than one per component, for the reason `NebaSize` is
+ * one: a tool call and a step of a plan are the same lifecycle seen at two
+ * scales, and a library that said `running` on one and `current` on the other
+ * would make a caller translate between them in the middle of a transcript.
+ * [Timeline](../components/display/timeline) keeps its own three words on
+ * purpose — a step of a checkout is `upcoming` rather than `pending`, because
+ * nothing is waiting on it.
+ *
+ * Four, and the list is closed. `success` and `error` are two endings and not
+ * one `done` with a flag beside it, because what a reader needs from a failed
+ * step is the thing a boolean would bury; and there is no `cancelled`, because
+ * a run that was stopped ended without succeeding, which is what `error`
+ * already says.
+ */
+export type NebaRunStatus = 'pending' | 'running' | 'success' | 'error';
 /**
  * The viewport widths the layout components branch on, smallest first.
  *
@@ -280,8 +298,12 @@ export interface NebaAnimateProps {
     paused?: boolean;
     /** What starts it. @default 'mount' */
     trigger?: NebaAnimateTrigger;
-    /** Runs it, when `trigger` is `manual`. Each `false` → `true` starts it over. */
-    play?: boolean;
+    /**
+     * Runs it, when `trigger` is `manual`. Each `false` → `true` starts it over,
+     * and so does a number that changes: a count of failed attempts replays a
+     * shake on every failure without remounting what is inside it. `0` is stopped.
+     */
+    play?: boolean | number;
     /**
      * With `trigger="visible"`, whether it runs only the first time. Off, it runs
      * again every time the element comes back into view.
@@ -359,7 +381,8 @@ export interface NebaTransitionOptions {
  * A bare effect name is the whole of what most callers want —
  * `transition="fade"` — and the object form is there for the rest.
  *
- * It runs on mount and once. Anything else — replaying on scroll, on hover, or
+ * It runs on mount and once, except `blink`, which repeats until its `repeat`
+ * says otherwise: a blink that ran once would be a flicker. Anything else — replaying on scroll, on hover, or
  * under your own control — is what the `Animate*` components are, and any
  * component can be wrapped in one. This prop exists so the common case does not
  * need an extra element in the tree.
@@ -444,6 +467,21 @@ export interface NebaChartSeries {
      * @default false
      */
     hidden?: boolean;
+    /**
+     * Which value axis this series is measured against.
+     *
+     * `secondary` is for the series whose units are not the others' — revenue
+     * beside a conversion rate, a count beside a duration. It is read only when
+     * the chart was given a `secondaryAxis`, and never on a stacked chart: a
+     * stack is a total, and a total across two units is not a number.
+     *
+     * Reach for it rarely. Two scales on one plot let a caller make any two
+     * series look like they move together by choosing the ranges, and a reader
+     * has no way to see that it was done — which is why the second axis is drawn
+     * on the far edge and labelled rather than merely implied.
+     * @default 'primary'
+     */
+    axis?: 'primary' | 'secondary';
 }
 /**
  * One span on a [TimelineChart] — a stretch of time with two ends.
@@ -487,6 +525,24 @@ export interface NebaTimelineSeries {
 }
 /** How a line gets from one point to the next. */
 export type NebaChartCurve = 'linear' | 'smooth' | 'step';
+/**
+ * What a line or a band does where a value is missing.
+ *
+ * - `gap` — breaks. The default, and the honest one: a `null` is a month that
+ *   has not closed or a sensor that was offline, and a chart that draws over
+ *   the hole has stated a number nobody measured.
+ * - `connect` — joins the two sides with a straight segment. For a gap that is
+ *   an artefact of how the data was collected rather than a fact about the
+ *   world — a reading that failed to arrive for something that never stopped.
+ * - `zero` — reads the gap as a nought, everywhere: the line goes to the
+ *   baseline, the axis takes the nought into its range, and the tooltip and the
+ *   table say `0` rather than nothing. That last part is the point of it being
+ *   here rather than a change to the drawing alone — a picture that touches
+ *   zero over a table that says "no reading" is two answers to one question.
+ *   Reach for it when a missing row genuinely means none happened, which is
+ *   what an event count usually means and what a rate never does.
+ */
+export type NebaChartNulls = 'gap' | 'connect' | 'zero';
 /**
  * Which values are written onto the marks themselves.
  *
@@ -527,7 +583,7 @@ export interface NebaChartTooltipContext {
 }
 /** The tooltip, when a bare `true` or `false` is not enough. */
 export interface NebaChartTooltip {
-    /** @default 'index' */
+    /** @default 'index', or 'item' on ScatterChart and TimelineChart */
     mode?: NebaChartTooltipMode;
     /**
      * The line dropped through the plot at the active category. On in `index`
@@ -537,6 +593,86 @@ export interface NebaChartTooltip {
     /** Draws the panel. Without it the chart draws its own. */
     render?: (context: NebaChartTooltipContext) => React.ReactNode;
 }
+/**
+ * A line, or a band, drawn across a plot at a value the data has none of.
+ *
+ * A target, an SLA, a budget, last year's average, the window a forecast
+ * covers. It is the one thing on a chart that is neither a mark nor chrome: it
+ * carries meaning, so it is drawn heavier than a gridline — and it is not the
+ * reader's data, so it is dashed and neutral rather than taking one of the
+ * eight series hues.
+ *
+ * The scale is widened to hold it. A target drawn off the top of the plot is a
+ * target nobody can see, and moving every mark down a little to make room is
+ * the cheaper of the two costs.
+ */
+export interface NebaChartReference {
+    /** Where it sits, in the units of the axis it is read against. */
+    value: number;
+    /**
+     * Turns the line into a band that runs from `value` to here — a tolerance, a
+     * quarter, the range a forecast covers. Drawn as a wash with an edge at each
+     * end, so what is inside it stays readable.
+     */
+    to?: number;
+    /**
+     * Which axis the numbers are read against.
+     *
+     * - `value` — the one the marks are measured on. A target, a budget, a limit.
+     * - `category` — the one they are placed along, for a rule that says *when*:
+     *   a release, a policy change. On an axis of columns the number is the
+     *   column's index; on one of dates or numbers it is a point on that scale.
+     * @default 'value'
+     */
+    axis?: 'value' | 'category';
+    /**
+     * What it is called, written at the far end of it. SVG text, so a string:
+     * an element has nowhere to go.
+     */
+    label?: string;
+    /**
+     * Its colour. A `NebaColor` family, or any CSS colour.
+     *
+     * Neutral by default, and that is the right answer more often than it looks:
+     * a reference in `danger` says the line is the bad thing, when usually the
+     * bad thing is the data crossing it.
+     * @default the muted ink
+     */
+    color?: NebaColor | (string & {});
+    /**
+     * Draws it as a solid rule. Dashed otherwise, which is what says a line is a
+     * threshold rather than one more gridline.
+     * @default false
+     */
+    solid?: boolean;
+}
+/**
+ * The strip under a plot that says which part of a long series is drawn.
+ *
+ * A chart of two thousand points is a chart with no points on it: every column
+ * is a fraction of a pixel wide and the shape is a smear. The answer is not to
+ * draw fewer of them — that is the caller's data — but to draw a window of
+ * them, and to put the whole series under the plot small so the reader can see
+ * where the window is and move it.
+ *
+ * The window is in **category indices**, inclusive at both ends, because that
+ * is what a category axis is indexed by whether it holds dates, numbers or
+ * columns.
+ */
+export interface NebaChartBrush {
+    /** Which categories the window covers to begin with. Defaults to all of them. */
+    defaultRange?: readonly [number, number];
+    /** The window, for a chart whose range the caller holds. */
+    range?: readonly [number, number];
+    /** Called with the new window whenever the reader moves it. */
+    onRangeChange?: (range: [number, number]) => void;
+    /**
+     * How tall the strip is, in pixels. Drawn **inside** the chart's own height,
+     * like the axis labels, so a card sized to the chart is a card it fits in.
+     * @default 32
+     */
+    height?: number;
+}
 /** One axis of a cartesian chart. */
 export interface NebaChartAxis {
     /** Leaves the axis undrawn — its rule, its ticks and its labels. */
@@ -558,8 +694,32 @@ export interface NebaChartAxis {
     max?: number;
     /** Roughly how many ticks. The scale still rounds to clean numbers. */
     tickCount?: number;
-    /** How a tick is written, overriding the chart's own `format`. */
-    tickFormat?: (value: NebaChartCategory, index: number) => React.ReactNode;
+    /**
+     * How a tick is written, overriding the chart's own `format`. A tick is SVG
+     * text, so this returns a string or a number: an element has nowhere to go and
+     * was written out as `[object Object]`.
+     */
+    tickFormat?: (value: NebaChartCategory, index: number) => string | number;
+    /**
+     * Turns the labels by this many degrees, between `-90` and `90`. Negative
+     * tilts them up to the right, which is the one most readers have met;
+     * positive tilts them down, and `-90` stands them on end.
+     *
+     * What it buys is **all** of the labels. Flat, a long category name has one
+     * slot to fit in, so the axis either cuts it to an ellipsis or drops every
+     * second one; turned, each label only has to clear its neighbour across its
+     * own height, and a dozen product names fit where three did. What it costs is
+     * a band of the plot and a label nobody can read at a glance, so it is worth
+     * it when the names are what the reader came for and not when the shape is.
+     *
+     * Only the **category** axis reads it, and only on a chart that draws that
+     * axis along the bottom: a horizontal chart already gives each label a row of
+     * its own, and a value tick is a rounded number that was never cut. The band
+     * under the plot grows to hold the turned labels, up to a cap — past that
+     * they are still cut, because a chart that is mostly axis is not a chart.
+     * @default 0
+     */
+    tickAngle?: number;
     /**
      * How much room the axis keeps for its ticks and its label, in pixels.
      * Measured from the ticks themselves otherwise; set it when a long category

package/dist/types.js

@@ -1,8 +0,0 @@
-/**
- * Shared prop vocabulary for every Neba component.
- *
- * These names and values are deliberately generic: a `size` of `md` or a
- * `color` of `primary` has to mean the same thing on a Button, a Chip, a
- * TextField or a Dialog. Components pick the subset they need from here and
- * never invent a parallel spelling of the same idea.
- */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "neba",
-  "version": "1.13.0",
+  "version": "1.16.0",
   "description": "A comprehensive React UI component library — buttons, fields, menus, dialogs, tables and much more — accessible and themeable, sharing one prop vocabulary and a translucent acrylic design language. ESM only, types included, dark mode built in.",
   "type": "module",
   "types": "dist/index.d.ts",
@@ -19,22 +19,24 @@
   },
   "scripts": {
     "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
-    "build": "npm run clean && npm run format:fix && tsc --project tsconfig.prod.json && node scripts/annotate-pure.mjs && npm run minify && node scripts/build-styles.mjs",
+    "build": "npm run clean && npm run format:fix && tsc --project tsconfig.prod.json && node scripts/annotate-pure.mjs && npm run minify && node scripts/build-styles.mjs && node scripts/build-catalog.mjs",
     "lint": "eslint . --report-unused-disable-directives",
     "lint:fix": "eslint . --report-unused-disable-directives --fix",
-    "minify": "terser-glob 'dist/**/*.js' --config-file terser.config.json",
+    "minify": "node scripts/minify.mjs",
     "size": "node scripts/measure-bundle.mjs",
     "size:update": "node scripts/measure-bundle.mjs --update",
+    "compat": "node scripts/check-browsers.mjs",
     "prepare": "npm run build",
     "format": "prettier .",
     "format:fix": "prettier . --write",
     "docs:changelog": "node scripts/copy-changelog.mjs",
-    "docs:dev": "npm run docs:changelog && vitepress dev docs",
-    "docs:build": "npm run docs:changelog && node --max-old-space-size=8192 ./node_modules/vitepress/bin/vitepress.js build docs",
+    "docs:dev": "npm run docs:changelog && npm run docs:catalog && vitepress dev docs",
+    "docs:build": "npm run docs:changelog && npm run docs:catalog && node --max-old-space-size=8192 ./node_modules/vitepress/bin/vitepress.js build docs",
     "docs:serve": "npm run docs:build && vitepress serve docs",
     "test": "node scripts/run-tests.mjs",
     "test:watch": "vitest",
-    "typecheck": "tsc --project tsconfig.prod.json --noEmit && tsc --project test/tsconfig.json && tsc --project docs/tsconfig.json"
+    "typecheck": "tsc --project tsconfig.prod.json --noEmit && tsc --project test/tsconfig.json && tsc --project docs/tsconfig.json",
+    "docs:catalog": "node scripts/build-catalog.mjs --docs"
   },
   "engines": {
     "node": ">=18.0.0"
@@ -69,6 +71,12 @@
     "./styles.css": "./dist/styles.css",
     "./tailwind.css": "./dist/tailwind.css",
     "./package.json": "./package.json",
+    "./a2ui": {
+      "types": "./dist/a2ui/index.d.ts",
+      "module": "./dist/a2ui/index.js",
+      "default": "./dist/a2ui/index.js"
+    },
+    "./a2ui/catalog.json": "./dist/a2ui/catalog.json",
     "./*": {
       "types": "./dist/components/*/index.d.ts",
       "module": "./dist/components/*/index.js",
@@ -89,6 +97,12 @@
       "locales/*": [
         "dist/locales/*.d.ts"
       ],
+      "hooks": [
+        "dist/hooks/index.d.ts"
+      ],
+      "a2ui": [
+        "dist/a2ui/index.d.ts"
+      ],
       "*": [
         "dist/components/*/index.d.ts"
       ]
@@ -137,7 +151,10 @@
     "form"
   ],
   "devDependencies": {
+    "@a2ui/react": "^0.11.1",
+    "@a2ui/web_core": "^0.11.0",
     "@eslint/js": "^9.39.1",
+    "@mdn/browser-compat-data": "^8.1.1",
     "@tailwindcss/postcss": "^4.3.3",
     "@types/node": "^26.4.1",
     "@types/react": "^19.2.18",
@@ -159,7 +176,7 @@
     "react": "^19.2.8",
     "react-dom": "^19.2.8",
     "tailwindcss": "^4.3.3",
-    "terser-glob": "^1.2.1",
+    "terser": "^5.51.2",
     "tsx": "^4.23.13",
     "typescript": "^6.0.3",
     "typescript-eslint": "^8.69.0",
@@ -168,7 +185,8 @@
     "vitepress-i18n": "^1.4.0",
     "vitepress-sidebar": "^1.40.0",
     "vitest": "^5.0.0",
-    "vitest-browser-react": "^2.3.0"
+    "vitest-browser-react": "^2.3.0",
+    "zod": "^3.25.76"
   },
   "dependencies": {
     "@base-ui/react": "^1.8.0",
@@ -177,11 +195,27 @@
   "peerDependencies": {
     "@types/react": "^18.0.0 || ^19.0.0",
     "react": "^18.0.0 || ^19.0.0",
-    "react-dom": "^18.0.0 || ^19.0.0"
+    "react-dom": "^18.0.0 || ^19.0.0",
+    "@a2ui/react": "^0.11.0",
+    "@a2ui/web_core": "^0.11.0",
+    "zod": "^3.25.76"
   },
   "peerDependenciesMeta": {
     "@types/react": {
       "optional": true
+    },
+    "@a2ui/react": {
+      "optional": true
+    },
+    "@a2ui/web_core": {
+      "optional": true
+    },
+    "zod": {
+      "optional": true
     }
+  },
+  "allowScripts": {
+    "esbuild": false,
+    "fsevents": false
   }
 }