neba 1.2.0 → 1.4.0

package/dist/tailwind.css

@@ -47,9 +47,18 @@
 
 /* ---------------------------------------------------------------------------
  * Light theme (default)
+ *
+ * `.light` and `[data-theme='light']` carry the same block rather than only
+ * `:root`, because forcing light has to work on a nested element too — a
+ * preview box inside a dark page has nowhere else to get these values from.
+ * Everything here that is not a colour (the radii, the motion, the grain) is
+ * identical in both themes, so re-declaring it costs a duplicate that resolves
+ * to what was inherited anyway.
  * ------------------------------------------------------------------------- */
 
-:root {
+:root,
+.light,
+[data-theme='light'] {
   /* Neutral surfaces and content */
   --neba-surface: oklch(100% 0 0);
   --neba-fg: oklch(24% 0.015 262);
@@ -86,8 +95,6 @@
      bottom bevel — that is what made the surface read as moulded plastic. */
   --neba-plate-edge: rgb(255 255 255 / 0.18);
   --neba-plate-top: rgb(255 255 255 / 0.26);
-  --neba-plate-solid: inset 0 1px 0 var(--neba-plate-top), inset 0 0 0 1px var(--neba-plate-edge);
-  --neba-plate-glass: inset 0 1px 0 var(--neba-plate-top);
   /* Off-vertical on purpose: light falling across a sheet at an angle, rather
      than the symmetric top-down gradient every framework ships. */
   --neba-sheen: linear-gradient(148deg, rgb(255 255 255 / 0.13), rgb(255 255 255 / 0) 52%);
@@ -138,14 +145,6 @@
      surface in space, not to advertise it. Level 4 is only reachable by
      hovering a level-3 surface. */
   --neba-shadow-ambient: rgb(16 24 40 / 0.13);
-  --neba-shadow-0: 0 0 #0000;
-  --neba-shadow-1: 0 1px 2px -1px var(--neba-shadow-ambient);
-  --neba-shadow-2:
-    0 2px 4px -2px var(--neba-shadow-ambient), 0 5px 12px -7px var(--neba-shadow-ambient);
-  --neba-shadow-3:
-    0 4px 8px -3px var(--neba-shadow-ambient), 0 12px 24px -11px var(--neba-shadow-ambient);
-  --neba-shadow-4:
-    0 6px 12px -4px var(--neba-shadow-ambient), 0 20px 40px -15px var(--neba-shadow-ambient);
 
   /* Corner radius: ~45% of the control height at every step. Held just short of
      the 50% that would make it a pill — the flat run along the top and bottom
@@ -380,6 +379,22 @@
 .light,
 [data-theme='dark'],
 [data-theme='light'] {
+  /* The plate and the elevation ladder are two base tokens spread into shadow
+     lists, so they belong here rather than next to the values they read: left
+     in the light block they would keep the light hairline and the light ambient
+     inside a `.dark` that is not the document root. */
+  --neba-plate-solid: inset 0 1px 0 var(--neba-plate-top), inset 0 0 0 1px var(--neba-plate-edge);
+  --neba-plate-glass: inset 0 1px 0 var(--neba-plate-top);
+
+  --neba-shadow-0: 0 0 #0000;
+  --neba-shadow-1: 0 1px 2px -1px var(--neba-shadow-ambient);
+  --neba-shadow-2:
+    0 2px 4px -2px var(--neba-shadow-ambient), 0 5px 12px -7px var(--neba-shadow-ambient);
+  --neba-shadow-3:
+    0 4px 8px -3px var(--neba-shadow-ambient), 0 12px 24px -11px var(--neba-shadow-ambient);
+  --neba-shadow-4:
+    0 6px 12px -4px var(--neba-shadow-ambient), 0 20px 40px -15px var(--neba-shadow-ambient);
+
   --neba-primary-fill: color-mix(
     in srgb,
     var(--neba-primary-solid) var(--neba-fill-alpha),
@@ -962,6 +977,48 @@
   animation-delay: calc(var(--n-i, 0) * 160ms);
 }
 
+/*
+ * The highlight travelling across a placeholder.
+ *
+ * `inset-inline-start` rather than a transform, the same trade `neba-sweep`
+ * makes and for the same reason: it runs the other way under RTL without being
+ * told, and the layout pass it costs is confined to a box with nothing in it.
+ *
+ * A pseudo-element rather than a child, so a Skeleton is one element per shape
+ * and a stack of ten lines is ten nodes rather than twenty. The gradient is
+ * symmetric, so it needs no direction of its own.
+ */
+@keyframes neba-skeleton-sweep {
+  from {
+    inset-inline-start: -60%;
+  }
+  to {
+    inset-inline-start: 100%;
+  }
+}
+
+.neba-skeleton::after {
+  content: '';
+  position: absolute;
+  inset-block: 0;
+  inline-size: 60%;
+  background-image: linear-gradient(90deg, transparent, var(--n-panel-press), transparent);
+  animation: neba-skeleton-sweep 1.5s var(--neba-ease) infinite;
+}
+
+/* The reduced-motion stand-in: the highlight stops travelling and the whole
+   placeholder breathes instead. Colour, which is the axis every other state in
+   the library already uses. */
+@keyframes neba-skeleton-pulse {
+  0%,
+  100% {
+    background-color: transparent;
+  }
+  50% {
+    background-color: var(--n-panel-press);
+  }
+}
+
 /* The reduced-motion stand-in for the sweep: the segment stops travelling and
    the whole groove pulses instead. Colour, which is the axis every other state
    in the library already uses. */
@@ -975,6 +1032,308 @@
   }
 }
 
+/* ---------------------------------------------------------------------------
+ * Animation
+ *
+ * The `Animate*` components, and the `transition` prop that shares their
+ * effects. Everything below is real CSS for the reason the loading indicators
+ * above are: a keyframe is not a Tailwind variant, so there is nothing to
+ * express one with.
+ *
+ * The whole set is built on one idea. An effect is a single `@keyframes` that
+ * runs from a state written entirely in `--n-anim-*` custom properties to the
+ * element's natural one — so `src/internal/animate.ts` never generates CSS, it
+ * only fills slots, and running an effect backwards is `animation-direction:
+ * reverse` rather than a second keyframe. That is what makes `mode="out"` cost
+ * nothing on all six.
+ *
+ * `fill-mode` is `both` throughout, which is what lets an animation that has
+ * not been triggered yet simply sit paused on its own first frame. Without it,
+ * an element waiting to be scrolled into view would be fully drawn and then
+ * blink out the moment it arrived.
+ *
+ * This is also where the library's rule against transforms is at its narrowest.
+ * A *control* never moves — that rule is about a button resampling its label
+ * under the pointer, and it still holds without exception. An `Animate*` wraps
+ * content the caller asked to have moved, and it moves it with the independent
+ * `translate`, `scale` and `rotate` properties rather than the `transform`
+ * shorthand, so a caller's own transform on the same element survives.
+ * ------------------------------------------------------------------------- */
+
+.neba-anim {
+  animation-duration: var(--n-anim-duration, 320ms);
+  animation-delay: var(--n-anim-delay, 0ms);
+  animation-timing-function: var(--n-anim-ease, var(--neba-ease));
+  animation-iteration-count: var(--n-anim-repeat, 1);
+  animation-direction: var(--n-anim-direction, normal);
+  animation-fill-mode: both;
+  animation-play-state: var(--n-anim-state, running);
+}
+
+@keyframes neba-anim-fade {
+  from {
+    opacity: var(--n-anim-opacity, 0);
+  }
+  to {
+    opacity: 1;
+  }
+}
+
+.neba-anim-fade {
+  animation-name: neba-anim-fade;
+}
+
+/* Grow and Zoom share this one: they are the same arithmetic at two strengths,
+   separated by their defaults and by their origin rather than by their maths. */
+@keyframes neba-anim-scale {
+  from {
+    opacity: var(--n-anim-opacity, 0);
+    scale: var(--n-anim-scale, 0.8);
+  }
+  to {
+    opacity: 1;
+    scale: 1;
+  }
+}
+
+.neba-anim-scale {
+  animation-name: neba-anim-scale;
+}
+
+@keyframes neba-anim-slide {
+  from {
+    opacity: var(--n-anim-opacity, 0);
+    translate: var(--n-anim-x, 0px) var(--n-anim-y, 0px);
+  }
+  to {
+    opacity: 1;
+    translate: 0 0;
+  }
+}
+
+.neba-anim-slide {
+  animation-name: neba-anim-slide;
+}
+
+/* Two angles rather than one, so the same keyframe covers both the quarter turn
+   something arrives on and the endless one a badge spins through. */
+@keyframes neba-anim-rotate {
+  from {
+    opacity: var(--n-anim-opacity, 0);
+    rotate: var(--n-anim-angle, -180deg);
+  }
+  to {
+    opacity: 1;
+    rotate: var(--n-anim-angle-to, 0deg);
+  }
+}
+
+.neba-anim-rotate {
+  animation-name: neba-anim-rotate;
+}
+
+/* Symmetric on purpose: a blink that ended anywhere but where it started would
+   leave the element half drawn whenever the count ran out. */
+@keyframes neba-anim-blink {
+  0%,
+  100% {
+    opacity: 1;
+  }
+  50% {
+    opacity: var(--n-anim-opacity, 0);
+  }
+}
+
+.neba-anim-blink {
+  animation-name: neba-anim-blink;
+}
+
+/*
+ * Lighting: a light travelling around the outside of something.
+ *
+ * The arc is a conic gradient and what moves is its `from` angle, which is only
+ * animatable because the angle is a registered custom property with a type. The
+ * alternative — rotating the pseudo-element itself — swings its corners out
+ * past the element on every quarter turn.
+ *
+ * `z-index: -1` inside an isolated stacking context puts the glow behind the
+ * content but still inside the component, so it reads as light escaping from
+ * under a sheet rather than as a border drawn around one.
+ */
+@property --neba-glow-angle {
+  syntax: '<angle>';
+  initial-value: 0deg;
+  inherits: false;
+}
+
+@keyframes neba-anim-lighting {
+  to {
+    --neba-glow-angle: 360deg;
+  }
+}
+
+.neba-anim-lighting {
+  position: relative;
+  isolation: isolate;
+}
+
+.neba-anim-lighting::before {
+  content: '';
+  position: absolute;
+  z-index: -1;
+  inset: calc(-1 * var(--n-anim-glow-width, 3px));
+  border-radius: inherit;
+  background: conic-gradient(
+    from var(--neba-glow-angle),
+    transparent 0deg,
+    var(--n-anim-glow, var(--n-accent)) var(--n-anim-glow-arc, 50deg),
+    transparent calc(var(--n-anim-glow-arc, 50deg) * 2),
+    transparent 360deg
+  );
+  filter: blur(var(--n-anim-glow-blur, 4px));
+  animation-name: neba-anim-lighting;
+  animation-duration: var(--n-anim-duration, 3s);
+  animation-delay: var(--n-anim-delay, 0ms);
+  animation-timing-function: linear;
+  animation-iteration-count: var(--n-anim-repeat, infinite);
+  animation-direction: var(--n-anim-direction, normal);
+  animation-fill-mode: both;
+  animation-play-state: var(--n-anim-state, running);
+}
+
+/*
+ * Marquee: two identical copies, both moving by exactly one copy plus the gap.
+ *
+ * Which is the whole trick — when the first copy has travelled its own width,
+ * the second is standing precisely where the first began, so there is no seam
+ * and no frame where the strip is empty. A percentage `translate` resolves
+ * against the element's own box, so neither copy has to be measured for this
+ * to hold; measuring only ever decides how *fast* it goes.
+ */
+@keyframes neba-anim-marquee-x {
+  from {
+    translate: 0 0;
+  }
+  to {
+    translate: calc(-100% - var(--n-anim-gap, 0px)) 0;
+  }
+}
+
+@keyframes neba-anim-marquee-y {
+  from {
+    translate: 0 0;
+  }
+  to {
+    translate: 0 calc(-100% - var(--n-anim-gap, 0px));
+  }
+}
+
+.neba-marquee {
+  display: flex;
+  overflow: hidden;
+  gap: var(--n-anim-gap, 0px);
+}
+
+.neba-marquee-vertical {
+  flex-direction: column;
+}
+
+.neba-marquee-track {
+  display: flex;
+  flex: 0 0 auto;
+  align-items: center;
+  gap: var(--n-anim-gap, 0px);
+  animation-name: neba-anim-marquee-x;
+  animation-duration: var(--n-anim-duration, 12s);
+  animation-delay: var(--n-anim-delay, 0ms);
+  /* Linear unless a caller insists otherwise. An eased marquee slows at both
+     ends of a loop that has no ends, which reads as the page stuttering. */
+  animation-timing-function: var(--n-anim-ease, linear);
+  animation-iteration-count: var(--n-anim-repeat, infinite);
+  animation-direction: var(--n-anim-direction, normal);
+  animation-fill-mode: both;
+  animation-play-state: var(--n-anim-state, running);
+}
+
+.neba-marquee-vertical .neba-marquee-track {
+  flex-direction: column;
+  animation-name: neba-anim-marquee-y;
+}
+
+.neba-marquee[data-pause-on-hover]:hover .neba-marquee-track {
+  animation-play-state: paused;
+}
+
+/*
+ * Headline: one line replacing another from below.
+ *
+ * Every item is in the same grid cell, so the box is as tall as the tallest of
+ * them and never resizes as the reel turns. The ones not on screen keep their
+ * space with `visibility` rather than `display`, which is what makes that true.
+ */
+@keyframes neba-anim-headline-in {
+  from {
+    translate: 0 var(--n-anim-rise, 100%);
+    opacity: 0;
+  }
+  to {
+    translate: 0 0;
+    opacity: 1;
+  }
+}
+
+@keyframes neba-anim-headline-out {
+  from {
+    translate: 0 0;
+    opacity: 1;
+  }
+  to {
+    translate: 0 calc(-1 * var(--n-anim-rise, 100%));
+    opacity: 0;
+  }
+}
+
+.neba-headline {
+  display: grid;
+  overflow: hidden;
+}
+
+.neba-headline-item {
+  grid-area: 1 / 1;
+  visibility: hidden;
+  animation-duration: var(--n-anim-duration, 480ms);
+  animation-timing-function: var(--n-anim-ease, var(--neba-ease));
+  animation-fill-mode: both;
+}
+
+.neba-headline-item[data-state='active'] {
+  visibility: visible;
+  animation-name: neba-anim-headline-in;
+}
+
+.neba-headline-item[data-state='leaving'] {
+  visibility: visible;
+  animation-name: neba-anim-headline-out;
+}
+
+/* The block after a typewriter. `step-end` rather than a fade, because a caret
+   that eases is a caret that looks like it is being rendered slowly. */
+@keyframes neba-anim-caret {
+  0%,
+  45% {
+    opacity: 1;
+  }
+  55%,
+  100% {
+    opacity: 0;
+  }
+}
+
+.neba-typing-caret {
+  display: inline-block;
+  animation: neba-anim-caret 1s step-end infinite;
+}
+
 /* Respect a reduced-motion preference. Both layers track the pointer, so they
    are motion in the sense that matters here — drop them entirely. */
 @media (prefers-reduced-motion: reduce) {
@@ -1014,4 +1373,39 @@
   .neba-typing-dot {
     animation-duration: 2.6s;
   }
+
+  /* The highlight stops travelling and the placeholder pulses in place. Kept
+     running for the same reason: a skeleton that holds still is indistinguishable
+     from an empty box that finished loading with nothing in it. */
+  .neba-skeleton::after {
+    inset-inline-start: 0;
+    inline-size: 100%;
+    background-image: none;
+    animation: neba-skeleton-pulse 2.4s var(--neba-ease) infinite;
+  }
+
+  /*
+   * The Animate components go the other way from the indicators above, and the
+   * difference is what each of them is saying. A spinner that stops is lying
+   * about whether anything is happening; an entrance that does not play has
+   * still delivered its content, which is the only thing it was ever carrying.
+   *
+   * `animation: none` rather than a zero duration, because the shorthand also
+   * clears `fill-mode` — and it is the fill that was holding an untriggered
+   * element on its own first frame at `opacity: 0`. Left in place, respecting a
+   * reader's preference would blank the page.
+   */
+  .neba-anim,
+  .neba-marquee-track,
+  .neba-headline-item,
+  .neba-typing-caret {
+    animation: none;
+  }
+
+  /* The arc stops travelling and becomes an even glow. The same trade the
+     skeleton makes: the decoration survives, the motion does not. */
+  .neba-anim-lighting::before {
+    background: var(--n-anim-glow, var(--n-accent));
+    animation: none;
+  }
 }

package/dist/types.d.ts

@@ -129,6 +129,118 @@ export type NebaVariant = 'solid' | 'outline' | 'text';
  * pressing removes one, so a flat control still answers a press without moving.
  */
 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.
+ *
+ * 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.
+ */
+export type NebaAnimation = 'fade' | 'grow' | 'slide' | 'zoom' | 'rotate' | 'blink';
+/**
+ * What makes an animation run.
+ *
+ * - `mount` — as soon as it is on the page. The default, and the only one that
+ *   needs nothing from the caller.
+ * - `visible` — when it is scrolled into view. Once, unless `once` is off.
+ * - `hover` — while the pointer is on it, restarting from the beginning on each
+ *   entry. Keyboard focus counts as a pointer here, or the effect would be
+ *   unreachable without a mouse.
+ * - `manual` — never on its own. `play` is what runs it.
+ */
+export type NebaAnimateTrigger = 'mount' | 'visible' | 'hover' | 'manual';
+/** Whether an effect brings its child in or takes it away. */
+export type NebaAnimateMode = 'in' | 'out';
+/**
+ * How many times an animation runs. `'infinite'` rather than `Infinity`,
+ * because it is written into CSS as that word and a caller who types the
+ * number would be surprised by which one worked.
+ */
+export type NebaAnimateRepeat = number | 'infinite';
+/**
+ * The settings every `Animate*` component takes, and the reason they are one
+ * interface: a `delay` of 200 has to mean the same thing on a fade and on a
+ * marquee, exactly as a `size` of `md` means one height everywhere.
+ *
+ * Durations and delays are milliseconds — numbers, not CSS strings. A prop
+ * whose type is `string` invites `'0.4s'`, and then two components in the same
+ * screen are written in two units.
+ */
+export interface NebaAnimateProps {
+    /** How long one run takes, in milliseconds. */
+    duration?: number;
+    /** How long before it starts, in milliseconds. @default 0 */
+    delay?: number;
+    /** The easing curve, as CSS writes it. @default the house curve */
+    easing?: string;
+    /** How many times it runs. @default 1 */
+    repeat?: NebaAnimateRepeat;
+    /** Runs every other pass backwards, so a repeat returns instead of jumping. */
+    alternate?: boolean;
+    /** Holds the animation where it is. @default false */
+    paused?: boolean;
+    /** What starts it. @default 'mount' */
+    trigger?: NebaAnimateTrigger;
+    /** Runs it, when `trigger` is `manual`. Each `false` → `true` starts it over. */
+    play?: boolean;
+    /**
+     * With `trigger="visible"`, whether it runs only the first time. Off, it runs
+     * again every time the element comes back into view.
+     * @default true
+     */
+    once?: boolean;
+    /**
+     * With `trigger="visible"`, how much of the element has to be on screen
+     * before it counts as visible, from `0` to `1`.
+     * @default 0.2
+     */
+    threshold?: number;
+}
+/** The options a `transition` prop takes when a bare effect name is not enough. */
+export interface NebaTransitionOptions {
+    /** Which effect. */
+    type: NebaAnimation;
+    /** Milliseconds. */
+    duration?: number;
+    /** Milliseconds. @default 0 */
+    delay?: number;
+    /** CSS easing. @default the house curve */
+    easing?: string;
+    /** @default 1 */
+    repeat?: NebaAnimateRepeat;
+    /** Runs every other pass backwards. */
+    alternate?: boolean;
+    /** Which edge a `slide` comes from. @default 'bottom' */
+    from?: NebaSide;
+    /** How far a `slide` travels — a CSS length, or a number in pixels. */
+    distance?: number | string;
+    /** Where a `grow` or a `zoom` starts, as a multiple of its final size. */
+    scale?: number;
+    /** How far a `rotate` turns from, in degrees. */
+    angle?: number;
+}
+/**
+ * An entrance animation on a component that displays something.
+ *
+ * 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
+ * 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.
+ *
+ * It is offered on components that *display* something and on none that are
+ * pressed. A control that moves under the pointer is the one thing the design
+ * language rules out, and a `transition` on a Button would be exactly that.
+ */
+export type NebaTransition = NebaAnimation | NebaTransitionOptions;
 /** Style props shared by most components; spread into their own prop types. */
 export interface NebaStyleProps {
     /** @default 'solid' */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "neba",
-  "version": "1.2.0",
+  "version": "1.4.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",
@@ -23,9 +23,9 @@
     "format": "prettier .",
     "format:fix": "prettier . --write",
     "docs:changelog": "node scripts/copy-changelog.mjs",
-    "docs:dev": "npm run build && npm run docs:changelog && vitepress dev docs",
-    "docs:build": "npm run build && npm run docs:changelog && vitepress build docs",
-    "docs:serve": "npm run build && npm run docs:build && vitepress serve docs",
+    "docs:dev": "npm run docs:changelog && vitepress dev docs",
+    "docs:build": "npm run docs:changelog && vitepress build docs",
+    "docs:serve": "npm run docs:build && vitepress serve docs",
     "test": "vitest run",
     "test:watch": "vitest",
     "typecheck": "tsc --project tsconfig.prod.json --noEmit && tsc --project test/tsconfig.json && tsc --project docs/tsconfig.json"
@@ -103,14 +103,14 @@
     "@types/node": "^26.1.2",
     "@types/react": "^19.2.18",
     "@types/react-dom": "^19.2.4",
-    "@typescript-eslint/parser": "^8.65.0",
-    "@vitejs/plugin-react-swc": "^4.3.3",
+    "@typescript-eslint/parser": "^8.66.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.8.0",
+    "globals": "^17.9.0",
     "jiti": "^2.7.0",
     "playwright": "^1.62.1",
     "postcss": "^8.5.25",
@@ -120,18 +120,18 @@
     "react-dom": "^19.2.8",
     "tailwindcss": "^4.3.3",
     "terser-glob": "^1.2.1",
-    "tsx": "^4.23.1",
-    "typescript": "^5.9.3",
-    "typescript-eslint": "^8.65.0",
+    "tsx": "^4.23.8",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.66.0",
     "vite": "^8.2.0",
     "vitepress": "^1.6.4",
     "vitepress-i18n": "^1.3.5",
-    "vitepress-sidebar": "^1.36.1",
+    "vitepress-sidebar": "^1.38.0",
     "vitest": "^4.1.10",
     "vitest-browser-react": "^2.2.0"
   },
   "dependencies": {
-    "@base-ui/react": "^1.6.0"
+    "@base-ui/react": "^1.7.0"
   },
   "peerDependencies": {
     "@types/react": "^18.0.0 || ^19.0.0",