neba 1.4.0 → 1.5.0

package/dist/tailwind.css

@@ -218,6 +218,111 @@
   --neba-info-solid-active: oklch(36.5% 0.068 223);
   --neba-info-on-solid: oklch(99% 0.004 223);
   --neba-info-accent: oklch(53.5% 0.096 223);
+
+  /* The chart series ramp ------------------------------------------------- */
+
+  /* Eight hues in a fixed order, and the one place in the library where a color
+     is not a semantic role. A series is an *entity* — a region, a plan, a
+     competitor — and nothing about it says success or danger; what the color has
+     to do is stay the same color when the chart is filtered, and be tellable
+     apart from its neighbours by every reader.
+
+     So they are not the six families reused. Those were picked to mean
+     something on a control, they are only six, and two of them (secondary,
+     info) sit close enough in hue that adjacent series would collapse. These
+     eight were solved for instead, and the constraints they satisfy are:
+
+     - every step inside OKLCH L 0.43–0.77, so no slot is louder than another;
+     - chroma at or above 0.10, below which a hue reads as grey and stops
+       carrying identity at all;
+     - each neighbouring pair at least ΔE 8 apart in OKLab under simulated
+       protanopia and deuteranopia — measured at 13.6 here, against a floor of 8;
+     - and at least 3:1 against the surface, so a 2px line is a line. Every slot
+       clears 4:1 on white and 5.3:1 on the dark sheet.
+
+     The order is the mechanism, not a preference: slots are handed out in
+     sequence and never cycled, which is what keeps the *adjacent* pairs — the
+     only ones that touch in a stack or a legend — the ones that were checked.
+     A ninth series is not a ninth colour; it is an "Other" row, or a second
+     chart. Series one is the primary hue because a one-series chart should look
+     like it belongs to the rest of the page. */
+  --neba-chart-1: oklch(60.5% 0.214 262);
+  --neba-chart-2: oklch(61% 0.166 48);
+  --neba-chart-3: oklch(62.5% 0.22 352);
+  --neba-chart-4: oklch(59.5% 0.122 92);
+  --neba-chart-5: oklch(59% 0.12 232);
+  --neba-chart-6: oklch(57.5% 0.18 145);
+  --neba-chart-7: oklch(62% 0.22 305);
+  --neba-chart-8: oklch(58.5% 0.104 182);
+
+  /* The sequential ramp — one hue, light to dark, for a mark whose colour is a
+     *magnitude* rather than an identity.
+
+     A different job from the eight above and so a different set, not a subset
+     of them. The eight are solved to be as far apart as possible, which is
+     exactly what a magnitude must not be: a heatmap coloured from a categorical
+     ramp says its cells are five unrelated things. Here the order is the whole
+     meaning, so what is solved for is the opposite —
+
+     - one hue throughout (spread 0°), because two hues in a ramp is a reader
+       inventing a boundary where the data has none;
+     - lightness strictly falling, in steps of at least ΔL 0.06 so no two are
+       the same shade at a glance;
+     - and the palest step still at 2:1 on the sheet, or the low end of the
+       scale is a cell that reads as empty rather than as small. It is 2.07:1
+       here, which is why step one is not paler than it is.
+
+     Chroma peaks in the middle and eases at both ends: at the pale end because
+     sRGB has none to give, and at the dark end because a saturated near-black
+     reads as a different hue.
+
+     Five steps and not a continuous gradient, because a reader cannot rank a
+     continuum. The scale legend under a heatmap has five swatches and the cells
+     have five values, and that is a picture with an answer in it. */
+  --neba-chart-seq-1: oklch(77% 0.09 262);
+  --neba-chart-seq-2: oklch(69% 0.13 262);
+  --neba-chart-seq-3: oklch(61% 0.17 262);
+  --neba-chart-seq-4: oklch(53% 0.19 262);
+  --neba-chart-seq-5: oklch(43% 0.17 262);
+
+  /* The diverging ramp — two poles and a neutral, for a magnitude with a
+     *middle* that means something: over and under target, gained and lost.
+
+     Reached for only when there is a real zero to diverge about. Used on a
+     plain magnitude it invents one, and the reader spends the chart looking for
+     what changed at the grey.
+
+     The neutral is grey and not a third hue, which is the rule that makes the
+     two arms read as two directions rather than as three categories. Each arm
+     is a one-hue ramp in its own right and passes the same three checks the
+     sequential ramp does; the two poles additionally clear the categorical
+     colour-vision gate at ΔE 17.4 under deuteranopia, because a diverging
+     scale whose ends cannot be told apart has no ends. */
+  --neba-chart-div-1: oklch(45% 0.09 232);
+  --neba-chart-div-2: oklch(63% 0.12 232);
+  --neba-chart-div-3: oklch(77% 0.008 262);
+  --neba-chart-div-4: oklch(63% 0.15 32);
+  --neba-chart-div-5: oklch(45% 0.16 32);
+
+  /* Which ink a label inside a filled tile wears.
+     Inside a mark is the one place text does not wear a text token outright: on
+     the pale end of a ramp the ink is right and on the dark end it is invisible,
+     and where the flip happens is different in each theme. So it is decided per
+     step, here, where the step's own lightness is known — computed rather than
+     eyeballed, and every one of the ten clears 4.5:1 against the fill it sits
+     on (the tightest is 4.58:1, in the middle of the ramp, which is where a
+     sequential scale is always hardest to write on). */
+  --neba-chart-seq-on-1: var(--neba-fg);
+  --neba-chart-seq-on-2: var(--neba-fg);
+  --neba-chart-seq-on-3: var(--neba-fg);
+  --neba-chart-seq-on-4: var(--neba-surface);
+  --neba-chart-seq-on-5: var(--neba-surface);
+
+  --neba-chart-div-on-1: var(--neba-surface);
+  --neba-chart-div-on-2: var(--neba-fg);
+  --neba-chart-div-on-3: var(--neba-fg);
+  --neba-chart-div-on-4: var(--neba-fg);
+  --neba-chart-div-on-5: var(--neba-surface);
 }
 
 /* ---------------------------------------------------------------------------
@@ -293,6 +398,50 @@
     --neba-info-solid-active: oklch(46% 0.082 223);
     --neba-info-on-solid: oklch(99% 0.004 223);
     --neba-info-accent: oklch(79% 0.11 223);
+
+    /* The chart series ramp — the same eight hues, re-solved against the dark
+       sheet rather than lightened from the values above. The band is narrower
+       here (L 0.48–0.67), so every slot sits at one lightness and the identity
+       is carried entirely by hue: on a dark surface a step that also varied in
+       lightness would read as "this series matters more". Re-measured, not
+       flipped: worst adjacent pair ΔE 14.5 under deuteranopia, every slot above
+       5.3:1 on the sheet. */
+    --neba-chart-1: oklch(66% 0.18 262);
+    --neba-chart-2: oklch(66% 0.18 48);
+    --neba-chart-3: oklch(66% 0.22 352);
+    --neba-chart-4: oklch(66% 0.134 92);
+    --neba-chart-5: oklch(66% 0.134 232);
+    --neba-chart-6: oklch(66% 0.206 145);
+    --neba-chart-7: oklch(66% 0.22 305);
+    --neba-chart-8: oklch(66% 0.118 182);
+
+    /* The two ramps, re-solved against the dark sheet rather than flipped. The
+       check that moves is the one at the *dark* end: there it is the deepest
+       step that has to stay clear of the surface, at 2.23:1 here, so the ramp
+       runs from a step lighter than the light theme's would. */
+    --neba-chart-seq-1: oklch(43% 0.12 262);
+    --neba-chart-seq-2: oklch(52% 0.16 262);
+    --neba-chart-seq-3: oklch(61% 0.19 262);
+    --neba-chart-seq-4: oklch(70% 0.15 262);
+    --neba-chart-seq-5: oklch(80% 0.09 262);
+
+    --neba-chart-div-1: oklch(46% 0.092 232);
+    --neba-chart-div-2: oklch(62% 0.125 232);
+    --neba-chart-div-3: oklch(76% 0.008 262);
+    --neba-chart-div-4: oklch(62% 0.15 32);
+    --neba-chart-div-5: oklch(46% 0.15 32);
+
+    --neba-chart-seq-on-1: var(--neba-fg);
+    --neba-chart-seq-on-2: var(--neba-fg);
+    --neba-chart-seq-on-3: var(--neba-surface);
+    --neba-chart-seq-on-4: var(--neba-surface);
+    --neba-chart-seq-on-5: var(--neba-surface);
+
+    --neba-chart-div-on-1: var(--neba-fg);
+    --neba-chart-div-on-2: var(--neba-surface);
+    --neba-chart-div-on-3: var(--neba-surface);
+    --neba-chart-div-on-4: var(--neba-surface);
+    --neba-chart-div-on-5: var(--neba-fg);
   }
 }
 
@@ -362,6 +511,41 @@
   --neba-info-solid-active: oklch(46% 0.082 223);
   --neba-info-on-solid: oklch(99% 0.004 223);
   --neba-info-accent: oklch(79% 0.11 223);
+
+  /* The chart series ramp — see the note in the `prefers-color-scheme` block. */
+  --neba-chart-1: oklch(66% 0.18 262);
+  --neba-chart-2: oklch(66% 0.18 48);
+  --neba-chart-3: oklch(66% 0.22 352);
+  --neba-chart-4: oklch(66% 0.134 92);
+  --neba-chart-5: oklch(66% 0.134 232);
+  --neba-chart-6: oklch(66% 0.206 145);
+  --neba-chart-7: oklch(66% 0.22 305);
+  --neba-chart-8: oklch(66% 0.118 182);
+
+  /* See the note in the `prefers-color-scheme` block. */
+  --neba-chart-seq-1: oklch(43% 0.12 262);
+  --neba-chart-seq-2: oklch(52% 0.16 262);
+  --neba-chart-seq-3: oklch(61% 0.19 262);
+  --neba-chart-seq-4: oklch(70% 0.15 262);
+  --neba-chart-seq-5: oklch(80% 0.09 262);
+
+  --neba-chart-div-1: oklch(46% 0.092 232);
+  --neba-chart-div-2: oklch(62% 0.125 232);
+  --neba-chart-div-3: oklch(76% 0.008 262);
+  --neba-chart-div-4: oklch(62% 0.15 32);
+  --neba-chart-div-5: oklch(46% 0.15 32);
+
+  --neba-chart-seq-on-1: var(--neba-fg);
+  --neba-chart-seq-on-2: var(--neba-fg);
+  --neba-chart-seq-on-3: var(--neba-surface);
+  --neba-chart-seq-on-4: var(--neba-surface);
+  --neba-chart-seq-on-5: var(--neba-surface);
+
+  --neba-chart-div-on-1: var(--neba-fg);
+  --neba-chart-div-on-2: var(--neba-surface);
+  --neba-chart-div-on-3: var(--neba-surface);
+  --neba-chart-div-on-4: var(--neba-surface);
+  --neba-chart-div-on-5: var(--neba-fg);
 }
 
 /* ---------------------------------------------------------------------------
@@ -580,6 +764,27 @@
   --neba-info-line: color-mix(in srgb, var(--neba-info-accent) 22%, transparent);
   --neba-info-line-hover: color-mix(in srgb, var(--neba-info-accent) 40%, transparent);
   --neba-info-ring: color-mix(in srgb, var(--neba-info-accent) 55%, transparent);
+
+  /* A chart's chrome: the grid, the axis rules, the baseline.
+
+     One step off the surface and nothing more. Gridlines are the only ink on a
+     chart that is not data, and the moment they are as dark as a series the eye
+     starts reading them as one. They are derived from `--neba-border` rather
+     than given values of their own so a chart's rules and a Card's dividers are
+     the same family of line, and they are solid — a dashed grid says
+     "projection" or "threshold" when all it is is a grid.
+
+     The baseline is the exception that is allowed to be darker: it is where a
+     bar starts from and where zero is, which is a fact about the data. */
+  --neba-chart-grid: color-mix(in srgb, var(--neba-border) 70%, transparent);
+  --neba-chart-axis: var(--neba-border);
+  --neba-chart-baseline: color-mix(in srgb, var(--neba-muted-fg) 35%, transparent);
+
+  /* What a mark is separated from its neighbour by, and what a marker is ringed
+     with. The surface colour rather than white, so the 2px gap between two
+     stacked segments is the sheet showing through and not a stroke drawn on
+     top — a border around a mark is ink that is not data. */
+  --neba-chart-gap: var(--neba-surface);
 }
 
 /* ---------------------------------------------------------------------------

package/dist/types.d.ts

@@ -6,6 +6,7 @@
  * TextField or a Dialog. Components pick the subset they need from here and
  * never invent a parallel spelling of the same idea.
  */
+import type * as React from 'react';
 /** Scale of a component. `md` is the desktop default. */
 export type NebaSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
 /** Semantic color role. Maps to a token family in `styles.css`. */
@@ -241,6 +242,219 @@ export interface NebaTransitionOptions {
  * language rules out, and a `transition` on a Button would be exactly that.
  */
 export type NebaTransition = NebaAnimation | NebaTransitionOptions;
+/**
+ * Where a point sits along the category axis.
+ *
+ * A `Date` is accepted because a time series is the common case and converting
+ * one to a string at the call site is what makes two charts of the same data
+ * label their axes differently.
+ */
+export type NebaChartCategory = string | number | Date;
+/**
+ * One value, with everything the chart might want to know about it.
+ *
+ * `y` of `null` is a **gap** and not a zero — a sensor that was offline, a month
+ * that has not closed yet. A line breaks across it, an area breaks with it, and
+ * a bar is not drawn. This distinction is the whole reason a datum may be
+ * `null` at all: a chart that renders missing data as zero is a chart that
+ * reports an outage as a collapse.
+ */
+export interface NebaChartPoint {
+    /**
+     * Its place on the category axis. Optional — without it the point is placed
+     * by its index, against `categories` if the chart was given any.
+     */
+    x?: NebaChartCategory;
+    /** The value. `null` is a gap. */
+    y: number | null;
+    /**
+     * A second magnitude, for the marks that have one: the radius of a bubble,
+     * the weight of a tile. Ignored by the charts that do not.
+     */
+    z?: number;
+    /**
+     * Overrides the series' colour for this one point — the slice worth pointing
+     * at, the bar that is over budget. Any CSS colour, or a `NebaColor` family.
+     */
+    color?: string;
+    /** What the tooltip, the legend and any value label say instead of `y`. */
+    label?: React.ReactNode;
+}
+/** A number, a gap, or a point that says more about itself. */
+export type NebaChartDatum = number | null | NebaChartPoint;
+/**
+ * One line, one band of bars, one ring of slices — and the unit identity is
+ * attached to.
+ *
+ * Colour follows the series, never its position in the drawing: a chart whose
+ * legend is filtered keeps every survivor on the colour it had. That is why the
+ * slot a series takes is decided by where it sits in this array and not by how
+ * many of its neighbours are currently visible.
+ */
+export interface NebaChartSeries {
+    /**
+     * Its name in the legend, the tooltip and the data table. A chart with two or
+     * more series always shows a legend, so a series without a name is a series
+     * the reader cannot identify.
+     */
+    name?: string;
+    /** The values, in category order. */
+    data: readonly NebaChartDatum[];
+    /**
+     * Overrides the palette slot this series would otherwise take. A `NebaColor`
+     * family name, or any CSS colour.
+     *
+     * This is the one place in the library where a colour is not a semantic role,
+     * and it is deliberate: a series is an *entity* — a region, a plan, a
+     * competitor — and nothing about it means success or danger. Reach for it to
+     * match a brand or to hold a colour steady across two charts, not to say how
+     * a number should be felt.
+     */
+    color?: NebaColor | (string & {});
+    /**
+     * Starts the series hidden. Only meaningful with an interactive legend, which
+     * is what turns it back on.
+     * @default false
+     */
+    hidden?: boolean;
+}
+/**
+ * One span on a [TimelineChart] — a stretch of time with two ends.
+ *
+ * Its own type rather than a `z2` or an `x2` bolted onto `NebaChartPoint`,
+ * because a second position on the axis is a field the other six charts would
+ * carry and never read. The trade the whole `types.ts` makes is that a name
+ * means one thing everywhere; a `NebaChartPoint` that sometimes has an end and
+ * usually does not is the opposite of that.
+ *
+ * `start` and `end` rather than `x` and `end`: a span has two places on the
+ * axis, and naming one of them `x` only reads correctly to someone who already
+ * knows which one it is.
+ */
+export interface NebaTimelinePoint {
+    /** When it begins. A `Date`, or a number of milliseconds. */
+    start: NebaChartCategory;
+    /** And when it is done. A span that ends before it starts is drawn either way round. */
+    end: NebaChartCategory;
+    /** What the span is called, in the tooltip and the table. */
+    label?: React.ReactNode;
+    /** Overrides its row's colour for this one span. */
+    color?: NebaColor | (string & {});
+}
+/**
+ * One row of a TimelineChart, and everything on it.
+ *
+ * A row is a series — one entity, one name, one colour — but its data are
+ * spans rather than values, so it cannot be a `NebaChartSeries`. There is no
+ * `hidden` here and no legend to pair it with: a Gantt's rows *are* its
+ * category axis, already named down the side, and a twenty-entry legend
+ * restating them is not a filter anyone wants.
+ */
+export interface NebaTimelineSeries {
+    /** Its name on the axis, in the tooltip and in the table. */
+    name?: string;
+    /** The spans on this row. Overlapping ones are drawn over each other. */
+    data: readonly NebaTimelinePoint[];
+    /** Overrides the palette slot this row would otherwise take. */
+    color?: NebaColor | (string & {});
+}
+/** How a line gets from one point to the next. */
+export type NebaChartCurve = 'linear' | 'smooth' | 'step';
+/**
+ * Which values are written onto the marks themselves.
+ *
+ * The default is `none` everywhere, and that is not timidity — a number beside
+ * every point is the most reliable way to make a chart unreadable. Label the
+ * end, or the extremes, and let the axis and the tooltip carry the rest;
+ * `'all'` is there for the eight-bar chart where it genuinely is the answer.
+ */
+export type NebaChartValueLabels = 'none' | 'last' | 'extremes' | 'all';
+/**
+ * What the pointer uncovers.
+ *
+ * - `index` — every series at the category under the pointer, with a crosshair.
+ *   The default on anything with a shared x axis, because the question a line
+ *   chart is asked is "what happened in March", not "what is this pixel".
+ * - `item` — the one mark being pointed at.
+ * - `none` — no tooltip. The values still have to be readable some other way.
+ */
+export type NebaChartTooltipMode = 'index' | 'item' | 'none';
+/** One series' answer at the category the pointer is on. */
+export interface NebaChartTooltipItem {
+    /** Its place in the `series` array — the same index its colour came from. */
+    seriesIndex: number;
+    name?: string;
+    color: string;
+    value: number | null;
+    /** `value` run through the chart's `format`. */
+    formatted: string;
+    /** What the point called itself, if it said. */
+    label?: React.ReactNode;
+}
+/** What a custom tooltip is handed. */
+export interface NebaChartTooltipContext {
+    index: number;
+    category: NebaChartCategory;
+    /** Only the series that are visible and have a value here. */
+    items: readonly NebaChartTooltipItem[];
+}
+/** The tooltip, when a bare `true` or `false` is not enough. */
+export interface NebaChartTooltip {
+    /** @default 'index' */
+    mode?: NebaChartTooltipMode;
+    /**
+     * The line dropped through the plot at the active category. On in `index`
+     * mode, where it is what says which column the numbers belong to.
+     */
+    crosshair?: boolean;
+    /** Draws the panel. Without it the chart draws its own. */
+    render?: (context: NebaChartTooltipContext) => React.ReactNode;
+}
+/** One axis of a cartesian chart. */
+export interface NebaChartAxis {
+    /** Leaves the axis undrawn — its rule, its ticks and its labels. */
+    hidden?: boolean;
+    /** A name for what the axis measures, set beside it. */
+    label?: React.ReactNode;
+    /**
+     * The gridlines this axis casts across the plot. On by default for the value
+     * axis and off for the category axis, which is the only arrangement where the
+     * grid helps read a value without turning the plot into graph paper.
+     */
+    grid?: boolean;
+    /**
+     * Where the scale starts and ends. Left out, both are taken from the data —
+     * the value axis from zero, so a bar's length stays proportional to its
+     * value. Set `min` only when zero is genuinely not the baseline.
+     */
+    min?: number;
+    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 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
+     * name needs more, or when two charts stacked on a dashboard have to line
+     * their plots up.
+     */
+    thickness?: number;
+}
+/** Where the legend sits, and whether it does anything when clicked. */
+export interface NebaChartLegend {
+    /** Which edge of the plot. @default 'bottom' */
+    side?: NebaSide;
+    /** Where along that edge. @default 'center' */
+    align?: NebaAlign;
+    /**
+     * Clicking an entry hides and shows its series; hovering one dims the rest.
+     * @default true
+     */
+    interactive?: boolean;
+    /** Draws each series' current value beside its name. @default false */
+    showValue?: boolean;
+}
 /** Style props shared by most components; spread into their own prop types. */
 export interface NebaStyleProps {
     /** @default 'solid' */

package/package.json

@@ -1,9 +1,12 @@
 {
   "name": "neba",
-  "version": "1.4.0",
+  "version": "1.5.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",
+  "sideEffects": [
+    "**/*.css"
+  ],
   "author": "CDGet <jooy2.contact@gmail.com>",
   "license": "MIT",
   "homepage": "https://neba.cdget.com",
@@ -16,8 +19,8 @@
   },
   "scripts": {
     "build": "npm run format:fix && tsc --project tsconfig.prod.json && npm run minify && node scripts/build-styles.mjs",
-    "lint": "eslint . --ext .js,.ts .",
-    "lint:fix": "eslint . --ext .js,.ts --fix .",
+    "lint": "eslint . --report-unused-disable-directives",
+    "lint:fix": "eslint . --report-unused-disable-directives --fix",
     "minify": "terser-glob 'dist/**/*.js' --config-file terser.config.json",
     "prepare": "npm run build",
     "format": "prettier .",
@@ -100,30 +103,31 @@
   "devDependencies": {
     "@eslint/js": "^9.39.1",
     "@tailwindcss/postcss": "^4.3.3",
-    "@types/node": "^26.1.2",
+    "@types/node": "^26.2.0",
     "@types/react": "^19.2.18",
     "@types/react-dom": "^19.2.4",
-    "@typescript-eslint/parser": "^8.66.0",
+    "@typescript-eslint/parser": "^8.67.0",
     "@vitejs/plugin-react": "^6.0.5",
     "@vitest/browser": "^4.1.10",
     "@vitest/browser-playwright": "^4.1.10",
     "eslint": "^9.39.1",
     "eslint-config-prettier": "^10.1.8",
-    "eslint-plugin-n": "^18.2.2",
-    "globals": "^17.9.0",
+    "eslint-plugin-n": "^18.3.0",
+    "eslint-plugin-react-hooks": "^7.1.1",
+    "globals": "^17.10.0",
     "jiti": "^2.7.0",
     "playwright": "^1.62.1",
-    "postcss": "^8.5.25",
+    "postcss": "^8.5.26",
     "prettier": "^3.9.6",
     "prettier-plugin-tailwindcss": "^0.8.1",
     "react": "^19.2.8",
     "react-dom": "^19.2.8",
     "tailwindcss": "^4.3.3",
     "terser-glob": "^1.2.1",
-    "tsx": "^4.23.8",
+    "tsx": "^4.23.12",
     "typescript": "^6.0.3",
-    "typescript-eslint": "^8.66.0",
-    "vite": "^8.2.0",
+    "typescript-eslint": "^8.67.0",
+    "vite": "^8.2.1",
     "vitepress": "^1.6.4",
     "vitepress-i18n": "^1.3.5",
     "vitepress-sidebar": "^1.38.0",