neba 1.11.0 → 1.13.0

package/dist/types.d.ts

@@ -101,6 +101,23 @@ export type NebaDateGranularity = 'day' | 'month' | 'year';
  * `xs` is 0: it is the value with no media query around it.
  */
 export type NebaBreakpoint = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+/**
+ * How wide content is allowed to get.
+ *
+ * A step of the measure ladder — `xs` 30rem, `sm` 40rem, `md` 48rem, `lg`
+ * 64rem, `xl` 80rem — `none` for no limit, or any CSS length the caller writes:
+ * `'60ch'`, `'min(90vw, 72rem)'`, or a number, which is pixels.
+ *
+ * The ladder shares its five names with `NebaBreakpoint` and four of its five
+ * values, which is deliberate: `maxWidth="md"` holds the content to the width
+ * at which a `md:` variant starts, so the two ladders line up where a layout
+ * needs them to. `xs` is the one step that is not a breakpoint floor, because a
+ * measure of zero is not a thing.
+ *
+ * The `string & {}` is what keeps the five names in a caller's autocomplete: a
+ * bare `| string` would swallow the literals and offer nothing.
+ */
+export type NebaMeasure = NebaSize | 'none' | number | (string & {});
 /**
  * A value that may differ per breakpoint.
  *
@@ -145,19 +162,43 @@ export type NebaVariant = 'solid' | 'outline' | 'text';
  */
 export type NebaElevation = 0 | 1 | 2 | 3;
 /**
- * The six effects the `Animate*` components are built out of, and the six
- * values the `transition` prop takes.
+ * The seven effects the `transition` prop takes, which is the **entrance**
+ * vocabulary: everything a component can be given to arrive on.
  *
  * They are named after what a reader sees rather than after the CSS property
  * underneath: `zoom` and `grow` are both a change of scale, and they are two
  * words because they are two *gestures* — one arrives from the middle of where
  * it will end up, the other unfolds from nothing.
  *
- * Everything past these six is a component rather than a value. Typing, a
- * marquee and a headline reel need to know what their children *are*, and a
- * prop that only sets class names cannot.
+ * Two `Animate*` components are deliberately **not** in it, and not only
+ * because neither is an entrance. This union is two `Record`s in
+ * `internal/animate.tsx`, an object literal cannot be tree-shaken per key, and
+ * those two tables are a fixed cost on every component that offers a
+ * `transition` — so `AnimateFloat`'s drift, which has no arrival in it, and
+ * `AnimateShake`'s reply to a failed form would be paid for by every Chip on
+ * every page that draws one. They bring their own keyframe instead.
+ *
+ * Everything past a keyframe is a component rather than a value. A typewriter,
+ * a marquee, a headline reel, a split line, a settling scramble and a counted
+ * number all need to know what their children *are*, and a prop that only sets
+ * class names cannot.
+ */
+export type NebaAnimation = 'fade' | 'grow' | 'slide' | 'zoom' | 'rotate' | 'blink' | 'reveal';
+/**
+ * What drives an animation's progress.
+ *
+ * - `time` — the clock. The default, and what every other prop on an animation
+ *   is written against.
+ * - `view` — how far the element has travelled through the viewport. The
+ *   animation has no duration of its own any more: scrolling forwards plays it
+ *   forwards, scrolling back plays it back, and stopping halfway holds it
+ *   halfway. `duration`, `delay`, `repeat` and every `trigger` are ignored,
+ *   because the scroll position *is* the trigger.
+ *
+ * Where `animation-timeline` is not supported the effect falls back to `time`
+ * and runs on mount, which is the same content delivered a plainer way.
  */
-export type NebaAnimation = 'fade' | 'grow' | 'slide' | 'zoom' | 'rotate' | 'blink';
+export type NebaAnimateTimeline = 'time' | 'view';
 /**
  * What makes an animation run.
  *
@@ -187,6 +228,43 @@ export type NebaAnimateRepeat = number | 'infinite';
  * whose type is `string` invites `'0.4s'`, and then two components in the same
  * screen are written in two units.
  */
+/**
+ * The three props that turn one effect on a box into the same effect on the
+ * things inside it, one after another.
+ *
+ * They are their own bundle rather than part of `NebaAnimateProps` because only
+ * some of the eleven can take them. An effect that already has to understand its
+ * children — a marquee that duplicates them, a headline that swaps between them,
+ * a typewriter that counts characters — has no second axis to spend on order.
+ *
+ * `delay` and `duration` stay what they were: what *every* child gets. These
+ * three are the difference between them.
+ */
+export interface NebaStaggerProps {
+    /**
+     * How long after one child the next one starts, in milliseconds.
+     *
+     * `0` — the default everywhere but `AnimateAppear` — animates the box itself
+     * and leaves the children alone, which is the plain single-element effect.
+     * Anything above it moves the animation onto each child in turn.
+     * @default 0
+     */
+    stagger?: number;
+    /**
+     * How much longer each successive child takes than the one before it, in
+     * milliseconds. Negative to speed them up down the list.
+     *
+     * A duration never goes below zero however far the list runs.
+     * @default 0
+     */
+    durationStep?: number;
+    /**
+     * Runs the children from the last to the first. Only the *order* reverses —
+     * each child still plays forwards.
+     * @default false
+     */
+    reverse?: boolean;
+}
 export interface NebaAnimateProps {
     /** How long one run takes, in milliseconds. */
     duration?: number;
@@ -217,6 +295,35 @@ export interface NebaAnimateProps {
      */
     threshold?: number;
 }
+/**
+ * The two props that swap the clock for the scrollbar.
+ *
+ * Their own bundle rather than part of `NebaAnimateProps`, for the reason
+ * `NebaStaggerProps` is: only the effects whose motion is one `@keyframes` on
+ * the element itself can be pointed at another timeline. A marquee that measures
+ * its own track, a typewriter counting characters and a light travelling round a
+ * pseudo-element are motion written in other places, and offering them a prop
+ * that quietly did nothing would be worse than not offering it.
+ */
+export interface NebaTimelineProps {
+    /**
+     * What drives the progress: the clock, or how far the element has travelled
+     * through the viewport.
+     *
+     * `view` costs `duration`, `delay`, `repeat` and `trigger` — a scroll-driven
+     * animation has no time in it, and the scroll position is what starts it. It
+     * falls back to `time` where the browser has no `animation-timeline`, which
+     * plays the effect once on mount.
+     * @default 'time'
+     */
+    timeline?: NebaAnimateTimeline;
+    /**
+     * The scroll range a `view` timeline is mapped over, written the way CSS
+     * `animation-range` is: `entry 0% cover 45%` is the default, which plays the
+     * effect out over the first part of the element's journey up the screen.
+     */
+    range?: string;
+}
 /** The options a `transition` prop takes when a bare effect name is not enough. */
 export interface NebaTransitionOptions {
     /** Which effect. */
@@ -239,6 +346,12 @@ export interface NebaTransitionOptions {
     scale?: number;
     /** How far a `rotate` turns from, in degrees. */
     angle?: number;
+    /** Which edge a `reveal` is wiped from. @default 'left' */
+    side?: NebaSide;
+    /** What drives the progress. @default 'time' */
+    timeline?: NebaAnimateTimeline;
+    /** The scroll range a `view` timeline is mapped over, as CSS writes it. */
+    range?: string;
 }
 /**
  * An entrance animation on a component that displays something.

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "neba",
-  "version": "1.11.0",
+  "version": "1.13.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>",
+  "author": "CDGet (https://cdget.com)",
   "license": "MIT",
   "homepage": "https://neba.cdget.com",
   "repository": {
@@ -18,7 +18,8 @@
     "url": "https://github.com/jooy2/neba/issues"
   },
   "scripts": {
-    "build": "npm run format:fix && tsc --project tsconfig.prod.json && node scripts/annotate-pure.mjs && npm run minify && node scripts/build-styles.mjs",
+    "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",
     "lint": "eslint . --report-unused-disable-directives",
     "lint:fix": "eslint . --report-unused-disable-directives --fix",
     "minify": "terser-glob 'dist/**/*.js' --config-file terser.config.json",
@@ -29,9 +30,9 @@
     "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 && vitepress build docs",
+    "docs:build": "npm run docs:changelog && node --max-old-space-size=8192 ./node_modules/vitepress/bin/vitepress.js build docs",
     "docs:serve": "npm run docs:build && vitepress serve docs",
-    "test": "vitest run",
+    "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"
   },
@@ -138,21 +139,21 @@
   "devDependencies": {
     "@eslint/js": "^9.39.1",
     "@tailwindcss/postcss": "^4.3.3",
-    "@types/node": "^26.4.0",
+    "@types/node": "^26.4.1",
     "@types/react": "^19.2.18",
-    "@types/react-dom": "^19.2.5",
-    "@typescript-eslint/parser": "^8.68.0",
+    "@types/react-dom": "^19.2.7",
+    "@typescript-eslint/parser": "^8.69.0",
     "@vitejs/plugin-react": "^6.1.1",
-    "@vitest/browser": "^4.1.11",
-    "@vitest/browser-playwright": "^4.1.11",
+    "@vitest/browser": "^5.0.0",
+    "@vitest/browser-playwright": "^5.0.0",
     "eslint": "^9.39.1",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-n": "^18.3.0",
     "eslint-plugin-react-hooks": "^7.1.1",
-    "globals": "^17.11.0",
+    "globals": "^17.12.0",
     "jiti": "^2.7.0",
-    "playwright": "^1.62.1",
-    "postcss": "^8.5.26",
+    "playwright": "^1.63.0",
+    "postcss": "^8.5.28",
     "prettier": "^3.9.6",
     "prettier-plugin-tailwindcss": "^0.8.1",
     "react": "^19.2.8",
@@ -161,16 +162,16 @@
     "terser-glob": "^1.2.1",
     "tsx": "^4.23.13",
     "typescript": "^6.0.3",
-    "typescript-eslint": "^8.68.0",
+    "typescript-eslint": "^8.69.0",
     "vite": "^8.2.2",
     "vitepress": "^1.6.4",
     "vitepress-i18n": "^1.4.0",
-    "vitepress-sidebar": "^1.39.0",
-    "vitest": "^4.1.11",
-    "vitest-browser-react": "^2.2.0"
+    "vitepress-sidebar": "^1.40.0",
+    "vitest": "^5.0.0",
+    "vitest-browser-react": "^2.3.0"
   },
   "dependencies": {
-    "@base-ui/react": "^1.7.0",
+    "@base-ui/react": "^1.8.0",
     "highlight.js": "^11.12.0"
   },
   "peerDependencies": {

package/dist/components/avatar-group/AvatarGroup.d.ts

@@ -1,47 +0,0 @@
-import * as React from 'react';
-import { type AvatarShape } from '../avatar/Avatar.js';
-import type { NebaColor, NebaElevation, NebaSize, NebaVariant } from '../../types.js';
-export interface AvatarGroupProps extends Omit<React.ComponentPropsWithoutRef<'div'>, 'color'> {
-    /**
-     * How many avatars are drawn before the rest become a count. Left out, every
-     * one of them is drawn.
-     */
-    max?: number;
-    /**
-     * How many there are altogether, when the group was handed only the first
-     * few. Without it the count is worked out from the children, which is right
-     * only when all of them were passed.
-     */
-    total?: number;
-    /**
-     * How far each avatar sits under the one before it — a CSS length, or a
-     * number of pixels. Left out it is a fraction of `size`, which keeps the
-     * overlap looking the same at every step.
-     */
-    overlap?: number | string;
-    /** Passed to every avatar in the group. @default 'md' */
-    size?: NebaSize;
-    /** Passed to every avatar in the group. @default 'circle' */
-    shape?: AvatarShape;
-    /** Passed to every avatar in the group. @default 'text' */
-    variant?: NebaVariant;
-    /** Passed to every avatar in the group. @default 'primary' */
-    color?: NebaColor;
-    /** Passed to every avatar in the group. @default 0 */
-    elevation?: NebaElevation;
-    /** The avatars. */
-    children?: React.ReactNode;
-}
-/**
- * A stack of avatars, overlapping, with the ones that did not fit as a count.
- *
- * `size`, `shape`, `variant`, `color` and `elevation` are set once here rather
- * than on every avatar — a stack whose fourth face is a size out is not a stack
- * — and an avatar's own prop still wins, which is what lets one of them be
- * marked out from the rest.
- *
- * The order is the DOM order, and the first avatar is on top: a stack read
- * left to right is read front to back, so the one the group is *about* comes
- * first rather than last.
- */
-export declare const AvatarGroup: React.ForwardRefExoticComponent<AvatarGroupProps & React.RefAttributes<HTMLDivElement>>;

package/dist/components/avatar-group/AvatarGroup.js

@@ -1 +0,0 @@
-"use client";import{jsx as r,jsxs as e}from"react/jsx-runtime";import*as a from"react";import{Avatar as t}from"../avatar/Avatar.js";import{AvatarGroupContext as i}from"../../internal/avatar-group.js";import{cx as n}from"../../internal/styles.js";import{useStyleDefaults as s}from"../../internal/defaults.js";const l={xs:"0.375rem",sm:"0.5rem",md:"0.625rem",lg:"0.75rem",xl:"0.875rem"};export const AvatarGroup=/*@__PURE__*/a.forwardRef(function(o,m){const{max:c,total:v,overlap:p,size:f="md",shape:d="circle",variant:u="text",color:x="primary",elevation:h=0,className:g,style:j,children:y,...z}=s(o,["size","variant"]),A=a.useMemo(()=>({size:f,shape:d,variant:u,color:x,elevation:h}),[f,d,u,x,h]),M=a.Children.toArray(y),b=void 0===c?M:M.slice(0,Math.max(0,c)),N=v??M.length,$=Math.max(0,N-b.length);return r(i.Provider,{value:A,children:e("div",{ref:m,className:n("isolate inline-flex items-center","[&>*:not(:first-child)]:[margin-inline-start:calc(var(--n-overlap)*-1)]","[&>*]:ring-2 [&>*]:ring-(--neba-surface)",g??""),style:{"--n-overlap":void 0===p?l[f]:"number"==typeof p?`${p}px`:p,...j},...z,children:[b,$>0?r(t,{initials:`+${$}`}):null]})})});

package/dist/components/avatar-group/index.d.ts

@@ -1,2 +0,0 @@
-export { AvatarGroup } from './AvatarGroup.js';
-export type { AvatarGroupProps } from './AvatarGroup.js';

package/dist/components/avatar-group/index.js

@@ -1 +0,0 @@
-export{AvatarGroup}from"./AvatarGroup.js";

package/dist/internal/avatar-group.d.ts

@@ -1,22 +0,0 @@
-import * as React from 'react';
-import type { AvatarShape } from '../components/avatar/Avatar.js';
-import type { NebaColor, NebaElevation, NebaSize, NebaVariant } from '../types.js';
-/**
- * What an Avatar inherits from the AvatarGroup around it.
- *
- * `button-group.ts`'s arrangement, one component over and for the same reason:
- * a stack of avatars where the fourth one is a size out is not a stack, and
- * `React.Children.map` with `cloneElement` stops working the moment a caller
- * wraps one of them in a Tooltip or produces them from a `.map()`.
- *
- * It lives here rather than in the avatar-group folder so that Avatar can read
- * it without the two components importing each other.
- */
-export interface AvatarGroupContextValue {
-    size?: NebaSize;
-    shape?: AvatarShape;
-    variant?: NebaVariant;
-    color?: NebaColor;
-    elevation?: NebaElevation;
-}
-export declare const AvatarGroupContext: React.Context<AvatarGroupContextValue | null>;

package/dist/internal/avatar-group.js

@@ -1 +0,0 @@
-"use client";import*as t from"react";export const AvatarGroupContext=/*@__PURE__*/t.createContext(null);