neba 1.1.0 → 1.3.0

package/dist/tailwind.css

@@ -586,6 +586,40 @@
   margin: 0;
 }
 
+/* ---------------------------------------------------------------------------
+ * Links
+ *
+ * `<a>` is, with `<td>`, one of the two tags a host stylesheet still styles by
+ * name — Tailwind Typography's `.prose a`, VitePress's own `.vp-doc a`, every
+ * CSS framework ever written — and always as a class plus a type, which is a
+ * specificity a one-class utility cannot reach. Table answered this by moving
+ * its cell padding inline. A link cannot: half of what it draws only exists on
+ * `:hover`, and inline styles have no `:hover`.
+ *
+ * So the selector is doubled instead. `.neba-link.neba-link` is two classes and
+ * matches nothing extra, which puts these declarations above a host's `a` rule
+ * and still below anything a caller writes with two classes of their own. Only
+ * the invariants are here — the parts of a TextLink that no prop changes. The
+ * colour and whether the line is drawn at all stay in the component, written
+ * through the same doubled class.
+ *
+ * The thickness has a `max()` floor because a hairline that lands between two
+ * device pixels is antialiased into a grey smudge: 0.055em is a real line from
+ * about 18px up, and 1px below that.
+ * ------------------------------------------------------------------------- */
+
+.neba-link.neba-link {
+  font-weight: inherit;
+  text-decoration-thickness: max(1px, 0.055em);
+  text-underline-offset: 0.2em;
+  text-underline-position: from-font;
+  text-decoration-color: var(--n-underline);
+}
+
+.neba-link.neba-link:hover {
+  text-decoration-color: var(--n-underline-hover);
+}
+
 /* ---------------------------------------------------------------------------
  * Grid
  *
@@ -708,6 +742,61 @@
   }
 }
 
+/* ---------------------------------------------------------------------------
+ * Tree guides
+ *
+ * The rail down a level of a TreeView, and — in `folder` — the elbow from that
+ * rail into every row on it.
+ *
+ * Both are drawn on the `<li>` rather than on the row inside it, and that is the
+ * whole trick: an `<li>` in a tree contains its own branch, so a rail that runs
+ * its full height keeps running past an expanded subtree and reaches the next
+ * sibling, exactly as a file manager draws it. The rail under a *last* child
+ * stops at that row's middle, which is the only thing telling the eye a branch
+ * has ended.
+ *
+ * `--n-tree-indent` and `--n-tree-row` are set inline by TreeView from its
+ * `size`. The rail sits half an indent outside the row, in the column the
+ * group's own padding opened up.
+ *
+ * This is CSS rather than Tailwind for the reason the grid is: the geometry is
+ * arithmetic on two per-instance custom properties, and the last child's rail is
+ * a different height from every other one. `[&:last-child::before]:[block-size:
+ * calc(var(--n-tree-row)/2)]` is expressible and unreadable.
+ *
+ * Everything is logical — `inset-inline-start`, `border-inline-start` — so the
+ * whole drawing mirrors under RTL without a second rule.
+ * ------------------------------------------------------------------------- */
+
+.neba-tree-simple :where(ul[role='group']) > li::before,
+.neba-tree-folder :where(ul[role='group']) > li::before {
+  content: '';
+  position: absolute;
+  inset-block-start: 0;
+  inset-inline-start: calc(var(--n-tree-indent, 1.25rem) / -2);
+  block-size: 100%;
+  inline-size: 0;
+  border-inline-start: 1px solid var(--neba-border);
+  pointer-events: none;
+}
+
+.neba-tree-folder :where(ul[role='group']) > li:last-child::before {
+  block-size: calc(var(--n-tree-row, 2rem) / 2);
+}
+
+/* The elbow. It stops 2px short of the row so the corner reads as a turn rather
+   than as a line running into the label. */
+.neba-tree-folder :where(ul[role='group']) > li::after {
+  content: '';
+  position: absolute;
+  inset-block-start: calc(var(--n-tree-row, 2rem) / 2);
+  inset-inline-start: calc(var(--n-tree-indent, 1.25rem) / -2);
+  block-size: 0;
+  inline-size: calc(var(--n-tree-indent, 1.25rem) / 2 - 2px);
+  border-block-start: 1px solid var(--neba-border);
+  pointer-events: none;
+}
+
 /* ---------------------------------------------------------------------------
  * Interaction light
  *
@@ -844,6 +933,77 @@
   animation-delay: calc(var(--n-i, 0) * 120ms);
 }
 
+/*
+ * The three dots under a message somebody is still typing.
+ *
+ * The same idea as the plates and held to the same rule: colour only, delayed
+ * per dot by its own index. Dots that bounce are what every other chat UI does,
+ * and a thread is read while this is running — something jumping in the corner
+ * of the page you are reading is the one kind of motion the design language has
+ * no time for.
+ *
+ * `currentColor` rather than a token, because a bubble's ink is white on
+ * `solid` and the page's own on the other two.
+ */
+@keyframes neba-typing {
+  0%,
+  60%,
+  100% {
+    background-color: color-mix(in oklab, currentColor 28%, transparent);
+  }
+  30% {
+    background-color: currentColor;
+  }
+}
+
+.neba-typing-dot {
+  background-color: color-mix(in oklab, currentColor 28%, transparent);
+  animation: neba-typing 1.25s var(--neba-ease) infinite;
+  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. */
@@ -857,6 +1017,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) {
@@ -889,4 +1351,46 @@
   .neba-plate-wave {
     animation-duration: 2.4s;
   }
+
+  /* Slowed rather than stopped, for the reason the indicators are: three dots
+     holding still say the message has stalled, which is the opposite of what
+     they are there for. */
+  .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' */