@eduardoalvarez/arrecife 0.6.0 → 0.8.0

package/dist/index.d.ts

@@ -4,7 +4,7 @@ export { THEME_ATTRIBUTE, THEME_EVENT, THEME_KEY, ThemeOptions, applyTheme, curr
 import { alertVariants as alert, avatarVariants as avatar, badgeVariants as badge, buttonVariants as button, textVariants as text } from './variants/index.js';
 export { CARD, CARD_HOVER, CARD_SURFACE, categoryBadgeVariants, metricBadgeVariants } from './variants/index.js';
 import * as react from 'react';
-import { ComponentPropsWithoutRef, ReactNode, ComponentProps, RefObject, SVGProps } from 'react';
+import { ComponentPropsWithoutRef, ReactNode, ComponentProps, RefObject } from 'react';
 import * as AccordionPrimitive from '@radix-ui/react-accordion';
 import { VariantProps } from 'class-variance-authority';
 import * as AlertDialogPrimitive from '@radix-ui/react-alert-dialog';
@@ -13,7 +13,7 @@ import { DayPicker } from 'react-day-picker';
 import * as CheckboxPrimitive from '@radix-ui/react-checkbox';
 import * as DialogPrimitive from '@radix-ui/react-dialog';
 import * as DropdownMenuPrimitive from '@radix-ui/react-dropdown-menu';
-export { L as Label, a as LabelProps } from './label-MgHFKnFy.js';
+export { L as Label, a as LabelProps } from './label-DJ4HuD-R.js';
 import * as PopoverPrimitive from '@radix-ui/react-popover';
 import * as ProgressPrimitive from '@radix-ui/react-progress';
 import * as RadioGroupPrimitive from '@radix-ui/react-radio-group';
@@ -28,6 +28,7 @@ import { F as Face, P as Pose } from './catalog-D13txprv.js';
 export { A as ASSETS_PATH, B as Background, a as Fin, f as faceList, b as faceUsage, c as faces, d as fins, p as poseList, e as poses } from './catalog-D13txprv.js';
 export { Isotype, IsotypeProps, Logo, LogoProps, Mascot, MascotFace, MascotFaceProps, MascotProps } from './brand/index.js';
 import { ClassValue } from 'clsx';
+export { i as social } from './index-BbRplw_B.js';
 import '@radix-ui/react-label';
 
 /**
@@ -48,7 +49,7 @@ import '@radix-ui/react-label';
  * `--ease-standard`, so it introduces neither a new timing nor a new curve.
  * Whoever asked for less motion still sees the panel appear where it will stay.
  *
- * See `docs/decisions.md` § 20.
+ * See `docs/decisions/0.6.md` § 20.
  *
  * The chevron, by contrast, rotates with no transition: `transition-standard`
  * only covers color and border, so `rotate` snaps even with the class in place.
@@ -111,7 +112,7 @@ declare function Alert({ className, variant, emphasis, title, icon, children, ..
  * «Borrar el artículo», not «Aceptar».
  *
  * `destructive` is for the destructive button that has none of that around it:
- * a table row, a toolbar. See `docs/decisions.md` § 21.
+ * a table row, a toolbar. See `docs/decisions/0.6.md` § 21.
  */
 declare const AlertDialog: react.FC<AlertDialogPrimitive.AlertDialogProps>;
 declare const AlertDialogTrigger: react.ForwardRefExoticComponent<AlertDialogPrimitive.AlertDialogTriggerProps & react.RefAttributes<HTMLButtonElement>>;
@@ -266,7 +267,8 @@ declare function Checkbox({ className, ...props }: CheckboxProps): react.JSX.Ele
 type CodeProps = ComponentPropsWithoutRef<'code'>;
 declare function Code({ className, ...props }: CodeProps): react.JSX.Element;
 
-type DateFieldProps = Omit<ComponentPropsWithoutRef<'input'>, 'type'> & {
+/** `ComponentProps` carries `ref`, which React 19 passes as a prop. See `InputProps`. */
+type DateFieldProps = Omit<ComponentProps<'input'>, 'type'> & {
     invalid?: boolean | undefined;
     /** Adds the time to the field. It is the native `datetime-local`. */
     withTime?: boolean | undefined;
@@ -315,7 +317,29 @@ declare function DropdownMenuSeparator({ className, ...props }: ComponentPropsWi
 declare function DropdownMenuSubTrigger({ className, children, ...props }: ComponentPropsWithoutRef<typeof DropdownMenuPrimitive.SubTrigger>): react.JSX.Element;
 declare function DropdownMenuSubContent({ className, ...props }: ComponentPropsWithoutRef<typeof DropdownMenuPrimitive.SubContent>): react.JSX.Element;
 
-type InputProps = ComponentPropsWithoutRef<'input'> & {
+/**
+ * `ComponentProps` and not `ComponentPropsWithoutRef`, and the difference is a
+ * bug and not a preference.
+ *
+ * `WithoutRef` is what React 18 required: `ref` was not a prop there, it arrived
+ * through `forwardRef`, and a type that included it promised something the
+ * component could not deliver. React 19 passes `ref` as an ordinary prop, so the
+ * `...props` spread below already forwards it — the type was the only thing
+ * still saying otherwise. It WORKED at runtime and failed at `tsc` with
+ * «Property 'ref' does not exist», which is the worst half of the two: the
+ * escape route is a cast or a wrapper element, and both are detours around a
+ * type rather than around a behaviour.
+ *
+ * `blog-content-manager` took the second one — its Giphy dialog focuses the
+ * search field 50 ms after opening, because Radix claims focus first, and it had
+ * to take the `ref` on the wrapping `div` and reach the input with a
+ * `querySelector`.
+ *
+ * The same applies to every primitive that wraps a native control you can focus:
+ * `Textarea`, `Label` and `DateField` change with it. See `docs/decisions/`
+ * § 41.
+ */
+type InputProps = ComponentProps<'input'> & {
     /** Marks the control as invalid and tints the border. */
     invalid?: boolean;
 };
@@ -446,7 +470,50 @@ type SwitchProps = ComponentPropsWithoutRef<typeof SwitchPrimitive.Root>;
  */
 declare function Switch({ className, ...props }: SwitchProps): react.JSX.Element;
 
-/** The container scrolls horizontally: the page never does. */
+/**
+ * The table, and the surface it sits on. The two are one piece.
+ *
+ * The container has always scrolled horizontally so the PAGE never does. What it
+ * did not carry was a shape, and that turned out to be the same omission twice:
+ * `TableRow` tints a `<tr>` on hover, a `<tr>` is a rectangle, and nothing
+ * clipped it — so every project wrapped the table in its own `rounded-xl border`
+ * and the hover of the header row and of the last row spilled out through the
+ * rounded corner. The fix from outside is `overflow-hidden` on that wrapper, and
+ * it worked exactly as far as somebody remembering it: five tables in `cursos`
+ * had it and the nine in `blog-content-manager` did not.
+ *
+ * So the surface comes with the table. `rounded-card` and `border-hairline` are
+ * the same two the system already gives a card — a table IS a panel of content,
+ * not a bare grid — and the clip comes free with the scroll: an element with
+ * `overflow-x: auto` clips its content to the border box, corners included. The
+ * hover cannot spill because there is nowhere left to spill to, and fourteen
+ * copies of the same `div` stop existing.
+ *
+ * There is NO background token on it, and that is not an oversight: `TableRow`'s
+ * hover is `bg-surface`, so painting the container `surface` too would make the
+ * hover invisible. The table sits on the page and the row lifts off it, which is
+ * the direction the tint was written for.
+ *
+ * `className` reaches the `<table>` and not the container, which is the trap
+ * `Nav`'s `size` documents: a `rounded-none` passed from the call site does
+ * nothing, silently. There is one shape on purpose — fourteen call sites wanted
+ * the same one — and a second gets a prop when a second consumer exists, not
+ * before. See `docs/decisions/0.8.md` § 39.
+ *
+ * THE `tabIndex` IS NOT DECORATION and it is not new behaviour dressed up as
+ * markup. A region you can pan with a mouse has to be reachable with a keyboard
+ * — WCAG 2.1.1 — and a table of text contains nothing focusable to land on, so
+ * without it a keyboard user simply cannot read the columns that are off screen.
+ * It has been true since the container started scrolling; it went unseen because
+ * no story had more columns than width, and the first one that did failed axe on
+ * `scrollable-region-focusable` at once.
+ *
+ * It is unconditional because the alternative is worse. Whether the table
+ * overflows depends on the viewport, so the only way to set this correctly at
+ * render is to measure in an effect and re-measure on resize — a ResizeObserver
+ * on every table in the system to avoid a tab stop. A stop that scrolls nothing
+ * is a small cost; a region a keyboard cannot reach is content that is not there.
+ */
 declare function Table({ className, ...props }: ComponentPropsWithoutRef<'table'>): react.JSX.Element;
 declare function TableHeader({ className, ...props }: ComponentPropsWithoutRef<'thead'>): react.JSX.Element;
 declare function TableBody({ className, ...props }: ComponentPropsWithoutRef<'tbody'>): react.JSX.Element;
@@ -454,6 +521,15 @@ declare function TableFooter({ className, ...props }: ComponentPropsWithoutRef<'
 declare function TableRow({ className, ...props }: ComponentPropsWithoutRef<'tr'>): react.JSX.Element;
 declare function TableHead({ className, ...props }: ComponentPropsWithoutRef<'th'>): react.JSX.Element;
 declare function TableCell({ className, ...props }: ComponentPropsWithoutRef<'td'>): react.JSX.Element;
+/**
+ * The caption, at the bottom and INSIDE the surface.
+ *
+ * It carries its own horizontal padding, which the cells get from `px-step-sm`
+ * and it used to get from nobody: with no border drawn around the table it read
+ * as a line under a grid, and with one it would sit flush against the left edge.
+ * The bottom padding is the same reasoning — a caption touching the border below
+ * it reads as an overflow, not as a caption.
+ */
 declare function TableCaption({ className, ...props }: ComponentPropsWithoutRef<'caption'>): react.JSX.Element;
 
 type TabsProps = ComponentPropsWithoutRef<typeof TabsPrimitive.Root>;
@@ -462,7 +538,8 @@ declare function TabsList({ className, ...props }: ComponentPropsWithoutRef<type
 declare function TabsTrigger({ className, ...props }: ComponentPropsWithoutRef<typeof TabsPrimitive.Trigger>): react.JSX.Element;
 declare function TabsContent({ className, ...props }: ComponentPropsWithoutRef<typeof TabsPrimitive.Content>): react.JSX.Element;
 
-type TextareaProps = ComponentPropsWithoutRef<'textarea'> & {
+/** `ComponentProps` carries `ref`, which React 19 passes as a prop. See `InputProps`. */
+type TextareaProps = ComponentProps<'textarea'> & {
     invalid?: boolean;
 };
 declare function Textarea({ className, invalid, ...props }: TextareaProps): react.JSX.Element;
@@ -571,7 +648,7 @@ type CardShellProps = ComponentPropsWithoutRef<'a'> & {
     children: ReactNode;
 };
 
-type ArticleCardProps = Omit<CardShellProps, 'children' | 'title'> & {
+type ArticleCardProps = Omit<CardShellProps, "children" | "title"> & {
     title: ReactNode;
     /** Standfirst. Clamped to two lines so the grid does not fall out of line. */
     excerpt?: ReactNode;
@@ -616,8 +693,8 @@ type ArticleCardProps = Omit<CardShellProps, 'children' | 'title'> & {
     }) => ReactNode) | undefined;
 };
 /**
- * The metadata line uses `meta` and not `eyebrow`: `18 ago 2026 · 8 min de
- * lectura` is a datum, not an overline, and in small caps it was neither.
+ * The metadata line uses `meta` and not `eyebrow`: `18 ago 2026 · 8 min de lectura`
+ * is a datum, not an overline, and in small caps it was neither.
  *
  * The tags are the CATEGORY family — a lowercase sand pill — not the status one.
  * A slug is something you read as `engineering-culture`.
@@ -778,23 +855,50 @@ declare function CourseCard({ title, summary, meta, status, progress, className,
  * not exist, so the rule lived in a comment about a ghost component. Once the
  * brand story started repeating the sentence, it was also a published promise.
  *
- * `expression` is MANDATORY and not optional: an empty state without a face is
- * half the component. It is the only place, alongside the 404, the server error,
- * course progress, celebration, the toast and the newsletter's «sin spam», where
- * a face may appear.
+ * `page` keeps that rule intact and `expression` stays MANDATORY there: an empty
+ * state that IS the screen without a face is half the component. It is the only
+ * place, alongside the 404, the server error, course progress, celebration, the
+ * toast and the newsletter's «sin spam», where a face may appear.
+ *
+ * `inline` is the other situation, and it is a different one rather than a
+ * smaller one: the hole inside a table page or a dashboard widget, competing with
+ * a dozen elements around it. An admin panel has twenty of those on one screen,
+ * and twenty faces is not the humour contract, it is a zoo. The variant carries
+ * no face, and the type does not let one through. See `docs/decisions/0.7.md` § 27.
  */
-type EmptyStateProps = Omit<ComponentPropsWithoutRef<'div'>, 'title'> & {
-    /** The face. Mandatory: without it this is a centred paragraph. */
-    expression: Face;
+type EmptyStateBase = Omit<ComponentPropsWithoutRef<'div'>, 'title'> & {
     title: ReactNode;
     /** One line explaining what is missing or what to do. */
     description?: ReactNode;
     /** The action that gets you out of the empty state. Usually a tertiary button. */
     action?: ReactNode;
+};
+type EmptyStateProps = EmptyStateBase & ({
+    /** `page`, the default: the empty state IS the screen or the section, and it carries the face. */
+    variant?: 'page' | undefined;
+    /**
+     * The face. Mandatory on `page` and impossible on `inline` — the props
+     * are a union, so the generated table cannot show a per-variant «req.»
+     * and the sentence has to carry it. Without it, `page` is a centred
+     * paragraph.
+     */
+    expression: Face;
     /** Where the brand PNGs are served from. */
     basePath?: string | undefined;
-};
-declare function EmptyState({ expression, title, description, action, basePath, className, ...props }: EmptyStateProps): react.JSX.Element;
+    icon?: never;
+} | {
+    /** `inline`: the hole inside a table or a widget. No face, and no way to pass one. */
+    variant: 'inline';
+    /**
+     * A glyph above the line. It measures 1em and inherits `currentColor`,
+     * like `Stat`'s: the project passes its own and sizes it, because the
+     * system has no icon library and is not getting one.
+     */
+    icon?: ReactNode;
+    expression?: never;
+    basePath?: never;
+});
+declare function EmptyState(props: EmptyStateProps): react.JSX.Element;
 
 /**
  * The calendar with events: seeing them, creating, editing and deleting them.
@@ -854,10 +958,23 @@ declare function EventCalendar({ events, onCreateEvent, onUpdateEvent, onDeleteE
  * improvement: it is the only thing that makes them legible. Which is why it is
  * mandatory in the type and not an optional prop that gets forgotten.
  *
- * The signature sits top right, level with the FIRST row that exists, not at the
- * end of the block. That is a composition decision and not a styling one: the
- * footer can carry brand, links and social icons, and hanging the signature off
- * one specific row sinks it the moment that row stops being the first.
+ * IT HAS TWO SHAPES, and the one that already existed is the one you get by
+ * passing nothing. That is not a courtesy: of the three projects that draw a
+ * footer, two want what was already there — `eduardoalvarez.dev` in 56 lines and
+ * `links` in a 64-line Astro replica — and only `cursos` wanted more. Changing
+ * the default would have broken the two that work to serve the one that did not.
+ *
+ * It is the third time the system answers «one component, two shapes» and the
+ * answer has not moved: `EmptyState` is a discriminated union where `page` is
+ * the default and `inline` cannot be handed a face; `Nav` takes a `size` where
+ * `default` is the bar it always was. Both left what was written before exactly
+ * where it was. See `docs/decisions/0.8.md` § 44.
+ *
+ * The union is what holds the rule up. `columns`, `description` and `action`
+ * exist only on `full`, and the default form cannot be handed one. As loose
+ * optional props they would compose into a third shape that nobody designed and
+ * nothing describes — a footer with columns and no description, or with a
+ * description and no columns, laid out by whichever branch happened to run.
  */
 type SocialLink = {
     /** What replaces the visible text. Mandatory. */
@@ -869,12 +986,40 @@ type SocialLink = {
      */
     icon: ReactNode;
 };
-type FooterProps = ComponentPropsWithoutRef<'footer'> & {
+/** One link in a column of the full footer. */
+type FooterColumnLink = {
+    label: ReactNode;
+    href: string;
+    /** Opens in a new tab, with the `rel` that has to go with it. */
+    external?: boolean | undefined;
+};
+/**
+ * A column of the full footer: a mono heading in small caps and its links.
+ *
+ * The columns are not decoration and they are not a sitemap. Two of the three in
+ * `cursos` change with who is looking — «Administración» with panel and metrics
+ * for an admin, «Cuenta» with my courses and my diplomas for everybody else —
+ * and a flat row of nine links cannot express that. Which is why this is data
+ * the project builds and not a `children` the library walks.
+ */
+type FooterColumn = {
+    title: string;
+    links: readonly FooterColumnLink[];
+};
+/**
+ * `children` is OMITTED, and it is the point of the type rather than an
+ * oversight.
+ *
+ * The footer used to take a row of loose text links this way — `./rss`,
+ * `./aviso-legal` — and that row is what `variant="full"`'s columns replace. A
+ * flat row cannot say which block a link belongs to, cannot carry a heading a
+ * screen reader can jump to, and made whoever wrote the label type the `./`
+ * themselves, which the columns put there. See docs/decisions/0.8.md § 47.
+ */
+type FooterBase = Omit<ComponentPropsWithoutRef<'footer'>, 'children'> & {
     social?: readonly SocialLink[];
     /** The signature's year. */
     year?: number;
-    /** Text links: legal notice, RSS, sitemap. */
-    children?: ReactNode;
     /**
      * The brand row: the fin and the wordmark, at the very top.
      *
@@ -884,12 +1029,51 @@ type FooterProps = ComponentPropsWithoutRef<'footer'> & {
      * type.
      */
     brand?: ReactNode;
+    /**
+     * Makes the domain inside the signature a link, keeping the `$`, the path and
+     * the prompt's mark as text.
+     *
+     * Only the domain: linking the whole line would turn a prompt into a button
+     * and put `cd ~/` inside the accessible name of the link. Without it the
+     * signature is text, which is what it has always been.
+     */
+    signatureHref?: string | undefined;
 };
-declare function Footer({ social, year, children, brand, className, ...props }: FooterProps): react.JSX.Element;
-type FooterLinkProps = ComponentPropsWithoutRef<'a'> & {
-    asChild?: boolean | undefined;
-};
-declare function FooterLink({ asChild, className, ...props }: FooterLinkProps): react.JSX.Element;
+type FooterProps = FooterBase & ({
+    /** The shape the library has always had: stacked rows and the signature at the top right. */
+    variant?: 'default' | undefined;
+    columns?: never;
+    description?: never;
+    action?: never;
+    linkAsChild?: never;
+} | {
+    /** `full`: brand and description on the left, link columns on the right, signature closing it. */
+    variant: 'full';
+    /** The link columns. Mandatory: without them `full` is the default form with extra steps. */
+    columns: readonly FooterColumn[];
+    /** One line under the brand, saying what the site is. */
+    description?: ReactNode;
+    /** An action under the row of icons — «Reportar un problema». Usually a tertiary button. */
+    action?: ReactNode;
+    /**
+     * Renders the column links through the child, to plug in the framework's
+     * `Link`. It receives each `href` in the Slot's `props`.
+     *
+     * It is § 24's rule applied where it now bites: a column turns data into
+     * markup, so without a slot the only way to reach one of those links
+     * from a project is to select it by structure or by a style class, and
+     * neither is a contract. `Breadcrumb` and `ArticleCard` have the same
+     * signature on purpose.
+     *
+     * It is also what a client-side transition needs: `cursos` reached for
+     * it the moment its columns stopped being `<a>` tags.
+     */
+    linkAsChild?: ((props: {
+        href: string;
+        children: ReactNode;
+    }) => ReactNode) | undefined;
+});
+declare function Footer({ variant, columns, description, action, linkAsChild, social, brand, year, signatureHref, className, ...rest }: FooterProps): react.JSX.Element;
 
 /**
  * ONE per site. It is the only piece in the system that is spent like the
@@ -950,7 +1134,8 @@ type LinkRowProps = Omit<CardShellProps, 'children'> & {
 declare function LinkRow({ name, description, icon, external, className, ...props }: LinkRowProps): react.JSX.Element;
 
 /**
- * The site bar: 64px, abyss at 86 % and a 14px blur behind it.
+ * The site bar: 64px, abyss at 86 % and a 14px blur behind it — 56 when it
+ * shares the screen with a sidebar.
  *
  * It is page composition and not a primitive, but it lives in the library for a
  * concrete reason: the CLI aesthetic of the items — mono, `./section` format —
@@ -966,6 +1151,13 @@ declare function LinkRow({ name, description, icon, external, className, ...prop
  * floats in the middle of the bar and the eye has to cross the gap twice: once
  * to read the brand and once to come back and find the section. Grouped on the
  * right, brand and navigation are two anchors instead of three.
+ *
+ * `brand` and `actions` are `ReactNode` slots and they are the answer to almost
+ * everything an app shell asks for: a `~/cursos` wordmark goes in `brand`, and a
+ * user menu or a «Entrar» button goes in `actions`. Session state does not get a
+ * prop of its own — it is project infrastructure, which is the third clause of
+ * the criterion that decides what enters this library. See `docs/decisions/`
+ * § 30.
  */
 type NavProps = ComponentPropsWithoutRef<'header'> & {
     /** The logo, on the left. */
@@ -974,8 +1166,19 @@ type NavProps = ComponentPropsWithoutRef<'header'> & {
     children?: ReactNode;
     /** Actions on the right: conversion, theme switch, search. */
     actions?: ReactNode;
+    /**
+     * `compact` is 56px instead of 64, for a bar that shares the screen with a
+     * sidebar: at 64 the two compete for the same corner and together they eat the
+     * top of the content area.
+     *
+     * It is a prop and not a `className` because the height lives on the inner
+     * container, which never sees one — `className` reaches the `<header>` and
+     * stops there. Passing `h-14` from outside did nothing, silently, which is the
+     * kind of failure this repo writes checks for.
+     */
+    size?: 'default' | 'compact' | undefined;
 };
-declare function Nav({ brand, children, actions, className, ...props }: NavProps): react.JSX.Element;
+declare function Nav({ brand, children, actions, size, className, ...props }: NavProps): react.JSX.Element;
 type NavItemProps = ComponentPropsWithoutRef<'a'> & {
     /** Current section: biolume with a 1px underline. */
     active?: boolean | undefined;
@@ -996,6 +1199,15 @@ type NavItemProps = ComponentPropsWithoutRef<'a'> & {
  * than it looks in a mockup. Brackets are how a terminal marks the active path,
  * so they say «you are here» without relying on the color being told apart. They
  * are `aria-hidden`, because whoever is listening already has `aria-current`.
+ *
+ * `children` goes through `Slottable`, and that is what makes `asChild` work at
+ * all. The prompt and the brackets are the component's own nodes, so a plain
+ * `Slot` saw four children where it needs one and threw «Slot failed to slot
+ * onto its children» on EVERY render — the prop was declared, typed and
+ * impossible to call. It passed `tsc` and it passed the build, because the shape
+ * of the children is not something either one looks at. `Slottable` is Radix's
+ * answer to exactly this: it marks which child the router's `Link` replaces and
+ * leaves the decoration where it is. See `docs/decisions/0.8.md` § 40.
  */
 declare function NavItem({ active, asChild, className, children, ...props }: NavItemProps): react.JSX.Element;
 
@@ -1190,34 +1402,6 @@ type ScrollingProgressBarProps = Omit<ComponentPropsWithoutRef<'div'>, 'children
 };
 declare function ScrollingProgressBar({ target, tone, sticky, className, ...props }: ScrollingProgressBarProps): react.JSX.Element;
 
-/**
- * The blog admin's sidebar.
- *
- * The `▸` is put there by the component, same as `NavItem`'s `./` and the
- * breadcrumb's `~`: it is the same CLI aesthetic and the same decision — the
- * format is part of the piece, not a convention to be remembered. It is
- * `aria-hidden`.
- *
- * The footer carries the version and the branch (`v5.0.1 · main`) in the `meta`
- * scale. It is not decoration: in an admin it is the first thing anyone asks
- * when something looks off.
- */
-type SidebarItemProps = ComponentPropsWithoutRef<'a'> & {
-    active?: boolean | undefined;
-    asChild?: boolean | undefined;
-    /** Counter on the right: pending drafts, unused media. */
-    badge?: ReactNode;
-};
-declare function SidebarItem({ active, asChild, badge, className, children, ...props }: SidebarItemProps): react.JSX.Element;
-type SidebarNavProps = ComponentPropsWithoutRef<'nav'> & {
-    /** The panel's heading. */
-    title?: ReactNode;
-    /** Version and branch, at the bottom. */
-    version?: ReactNode;
-    branch?: ReactNode;
-};
-declare function SidebarNav({ title, version, branch, children, className, ...props }: SidebarNavProps): react.JSX.Element;
-
 /**
  * A large metric: the number in the `stat` scale and its name underneath.
  *
@@ -1227,24 +1411,50 @@ declare function SidebarNav({ title, version, branch, children, className, ...pr
  * about. That is why `tone` is not an open palette — there are two values and
  * they mean different things.
  *
- * The reading order is icon + title, the big number, and the standfirst below.
- * The number goes in the MIDDLE and not at the end on purpose: it is what people
+ * The reading order is title, the big number, and the standfirst below. The
+ * number goes in the MIDDLE and not at the end on purpose: it is what people
  * came to read, and a two-line standfirst between the title and the figure
  * buries it. The top says what it is about, the middle says how much, and the
  * bottom holds the nuance only someone who stops will read.
+ *
+ * `delta` and `spark` sit with the number and not with the standfirst, because
+ * both are about the number: how it moved and what shape the movement had. The
+ * order survives — top what, middle how much, bottom the nuance.
+ *
+ * THE ICON IS A BADGE IN THE OPPOSITE CORNER, not a glyph before the title, and
+ * the tone rides on it rather than on the number. In a panel of ten of these the
+ * eyebrow is the same length in none of them, so an inline icon puts the only
+ * coloured mark on a different x in every card; pinned to the corner it lands on
+ * a grid. The circle is the tint pattern the system already has — `bg-accent/10`
+ * as a surface and the colour on the GLYPH, per `docs/decisions/0.6.md` § 4b — and a
+ * glyph clears the 3:1 graphical threshold where text would not clear 4.5.
+ *
+ * WHICH IS WHY A NEUTRAL NUMBER IS PRIMARY INK AND NOT BIOLUME. With a biolume
+ * badge and a biolume sparkline, a biolume number is the third accent in a card
+ * the size of a postcard, and the thing you came to read stops being the loudest
+ * thing in it. `alert` and `achievement` DO still paint the number sand, so the
+ * document's rule survives exactly where it matters: sand when the number is not
+ * just a number. See `docs/decisions/0.7.md` § 31.
  */
 type StatProps = Omit<ComponentPropsWithoutRef<'div'>, 'title'> & {
     /** The number, already formatted. The library imposes no locale. */
     value: ReactNode;
     /** What is being counted. It goes in mono small caps. */
     label: ReactNode;
-    /** `alerta` only when the number IS the problem. */
-    tone?: 'neutral' | 'alerta';
+    /**
+     * `alert` ONLY when the number is the problem, and `achievement` when it is
+     * the opposite — the diplomas issued, the modules finished. The two paint the
+     * same sand today and they are still two names: a system that names by meaning
+     * cannot make «this is bad» the only way to say «this stands out». See
+     * `docs/decisions/0.7.md` § 28.
+     */
+    tone?: 'neutral' | 'alert' | 'achievement';
     /** With `progress`, the metric reads as progress and adds the bar. */
     progress?: number | undefined;
     /**
-     * Glyph beside the title, at 1em. It inherits `currentColor`, so it follows
-     * the title's tone and does not have to be tinted separately.
+     * Glyph in a tinted circle, in the corner opposite the title. At 1em, and it
+     * inherits `currentColor` from the badge, so it takes the tone without being
+     * tinted separately.
      */
     icon?: ReactNode;
     /**
@@ -1252,8 +1462,31 @@ type StatProps = Omit<ComponentPropsWithoutRef<'div'>, 'title'> & {
      * does not say whether that is a lot, and this is where that gets said.
      */
     description?: ReactNode;
+    /** How the number moved since last time. */
+    delta?: StatDelta | undefined;
+    /**
+     * The number's shape over time, under it. A `ReactNode` and not a data prop:
+     * a sparkline needs a charting library, and this component lives in the barrel
+     * that four projects install. The one project that draws them passes its own,
+     * exactly like `icon`.
+     */
+    spark?: ReactNode;
 };
-declare function Stat({ value, label, tone, progress, icon, description, className, ...props }: StatProps): react.JSX.Element;
+type StatDelta = {
+    /**
+     * Already formatted — «+12 esta semana», «↑8 %». The library imposes no
+     * locale, same as `value`.
+     */
+    value: ReactNode;
+    /**
+     * Which way it moved. It picks the GLYPH and never the colour, because a rise
+     * is not automatically good: «+12 alumnos» and «+12 errores» point the same
+     * way and mean opposite things. Whether the number matters is `tone`'s job,
+     * and it is a decision the call site has already made.
+     */
+    direction: 'up' | 'down' | 'flat';
+};
+declare function Stat({ value, label, tone, progress, icon, description, delta, spark, className, ...props }: StatProps): react.JSX.Element;
 
 type TalkContent = {
     title: ReactNode;
@@ -1399,38 +1632,4 @@ declare function TableOfContents({ items, title, activeHref, linkAsChild, classN
 
 declare function cn(...inputs: ClassValue[]): string;
 
-type IconProps = SVGProps<SVGSVGElement>;
-declare const GitHub: (props: IconProps) => react.JSX.Element;
-declare const LinkedIn: (props: IconProps) => react.JSX.Element;
-declare const X: (props: IconProps) => react.JSX.Element;
-declare const Instagram: (props: IconProps) => react.JSX.Element;
-declare const Discord: (props: IconProps) => react.JSX.Element;
-declare const YouTube: (props: IconProps) => react.JSX.Element;
-declare const Rss: (props: IconProps) => react.JSX.Element;
-declare const Email: (props: IconProps) => react.JSX.Element;
-/**
- * The newsletter. It plays the same role as `Rss` — a way to follow, not a
- * social network — which is why it belongs in this catalogue and does not open
- * the door to an icon library.
- *
- * It is named for what it means and not for what it draws, like everything else
- * in the system: it is a bell, and it is called `Newsletter`. `eduardoalvarez.dev`
- * had it drawn in the project, following the contract by hand so it would not
- * clash while it waited.
- */
-declare const Newsletter: (props: IconProps) => react.JSX.Element;
-
-declare const social_Discord: typeof Discord;
-declare const social_Email: typeof Email;
-declare const social_GitHub: typeof GitHub;
-declare const social_Instagram: typeof Instagram;
-declare const social_LinkedIn: typeof LinkedIn;
-declare const social_Newsletter: typeof Newsletter;
-declare const social_Rss: typeof Rss;
-declare const social_X: typeof X;
-declare const social_YouTube: typeof YouTube;
-declare namespace social {
-  export { social_Discord as Discord, social_Email as Email, social_GitHub as GitHub, social_Instagram as Instagram, social_LinkedIn as LinkedIn, social_Newsletter as Newsletter, social_Rss as Rss, social_X as X, social_YouTube as YouTube };
-}
-
-export { Accordion, AccordionContent, AccordionItem, type AccordionProps, AccordionTrigger, type AccordionTriggerProps, Alert, AlertDialog, AlertDialogAction, AlertDialogCancel, AlertDialogContent, AlertDialogDescription, AlertDialogFooter, AlertDialogHeader, AlertDialogOverlay, AlertDialogTitle, AlertDialogTrigger, type AlertProps, ArticleCard, type ArticleCardProps, AudioPlayer, type AudioPlayerMode, type AudioPlayerProps, AuthorCard, type AuthorCardProps, Avatar, AvatarFallback, AvatarImage, type AvatarProps, AvatarUpload, type AvatarUploadProps, Badge, type BadgeProps, Blockquote, type BlockquoteProps, Breadcrumb, type BreadcrumbProps, Button, type ButtonProps, Calendar, type CalendarEvent, type CalendarProps, Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, CategoryBadge, type CategoryBadgeProps, Checkbox, type CheckboxProps, Code, CodeBlock, type CodeBlockProps, type CodeProps, CourseCard, type CourseCardProps, type Crumb, DateField, type DateFieldProps, Dialog, DialogClose, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogOverlay, DialogTitle, DialogTrigger, DropdownMenu, DropdownMenuCheckboxItem, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuLabel, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger, DropdownMenuTrigger, EmptyState, type EmptyStateProps, EventCalendar, type EventCalendarProps, Face, Footer, FooterLink, type FooterLinkProps, type FooterProps, Hero, type HeroProps, Input, type InputProps, LinkRow, type LinkRowProps, MetricBadge, type MetricBadgeProps, Nav, NavItem, type NavItemProps, type NavProps, NewsletterForm, type NewsletterFormProps, type NewsletterState, PageHeader, type PageHeaderProps, Pagination, PaginationContent, PaginationEllipsis, PaginationItem, PaginationLink, type PaginationLinkProps, PaginationNext, PaginationPrevious, Popover, PopoverAnchor, PopoverContent, type PopoverContentProps, PopoverTrigger, Pose, Progress, type ProgressProps, RadioGroup, RadioGroupItem, type RadioGroupItemProps, type RadioGroupProps, ScrollingProgressBar, type ScrollingProgressBarProps, Select, SelectContent, SelectGroup, SelectItem, SelectLabel, SelectSeparator, SelectTrigger, SelectValue, Separator, type SeparatorProps, Sheet, SheetBody, SheetClose, SheetContent, type SheetContentProps, SheetDescription, SheetFooter, SheetHeader, SheetTitle, SheetTrigger, SidebarItem, type SidebarItemProps, SidebarNav, type SidebarNavProps, Skeleton, type SkeletonProps, type SocialLink, Stat, type StatProps, Switch, type SwitchProps, Table, TableBody, TableCaption, TableCell, TableFooter, TableHead, TableHeader, TableOfContents, type TableOfContentsProps, TableRow, Tabs, TabsContent, TabsList, type TabsProps, TabsTrigger, TalkCard, type TalkCardProps, Text, type TextProps, Textarea, type TextareaProps, Theme, ThemeToggle, type ThemeToggleProps, ToastAction, type ToastOptions, type ToastVariant, Toaster, type ToasterProps, type TocEntry, Tooltip, TooltipContent, TooltipProvider, TooltipTrigger, alert as alertVariants, avatar as avatarVariants, badge as badgeVariants, button as buttonVariants, cn, social, text as textVariants, toast, useTheme };
+export { Accordion, AccordionContent, AccordionItem, type AccordionProps, AccordionTrigger, type AccordionTriggerProps, Alert, AlertDialog, AlertDialogAction, AlertDialogCancel, AlertDialogContent, AlertDialogDescription, AlertDialogFooter, AlertDialogHeader, AlertDialogOverlay, AlertDialogTitle, AlertDialogTrigger, type AlertProps, ArticleCard, type ArticleCardProps, AudioPlayer, type AudioPlayerMode, type AudioPlayerProps, AuthorCard, type AuthorCardProps, Avatar, AvatarFallback, AvatarImage, type AvatarProps, AvatarUpload, type AvatarUploadProps, Badge, type BadgeProps, Blockquote, type BlockquoteProps, Breadcrumb, type BreadcrumbProps, Button, type ButtonProps, Calendar, type CalendarEvent, type CalendarProps, Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, CategoryBadge, type CategoryBadgeProps, Checkbox, type CheckboxProps, Code, CodeBlock, type CodeBlockProps, type CodeProps, CourseCard, type CourseCardProps, type Crumb, DateField, type DateFieldProps, Dialog, DialogClose, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogOverlay, DialogTitle, DialogTrigger, DropdownMenu, DropdownMenuCheckboxItem, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuLabel, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger, DropdownMenuTrigger, EmptyState, type EmptyStateProps, EventCalendar, type EventCalendarProps, Face, Footer, type FooterColumn, type FooterColumnLink, type FooterProps, Hero, type HeroProps, Input, type InputProps, LinkRow, type LinkRowProps, MetricBadge, type MetricBadgeProps, Nav, NavItem, type NavItemProps, type NavProps, NewsletterForm, type NewsletterFormProps, type NewsletterState, PageHeader, type PageHeaderProps, Pagination, PaginationContent, PaginationEllipsis, PaginationItem, PaginationLink, type PaginationLinkProps, PaginationNext, PaginationPrevious, Popover, PopoverAnchor, PopoverContent, type PopoverContentProps, PopoverTrigger, Pose, Progress, type ProgressProps, RadioGroup, RadioGroupItem, type RadioGroupItemProps, type RadioGroupProps, ScrollingProgressBar, type ScrollingProgressBarProps, Select, SelectContent, SelectGroup, SelectItem, SelectLabel, SelectSeparator, SelectTrigger, SelectValue, Separator, type SeparatorProps, Sheet, SheetBody, SheetClose, SheetContent, type SheetContentProps, SheetDescription, SheetFooter, SheetHeader, SheetTitle, SheetTrigger, Skeleton, type SkeletonProps, type SocialLink, Stat, type StatDelta, type StatProps, Switch, type SwitchProps, Table, TableBody, TableCaption, TableCell, TableFooter, TableHead, TableHeader, TableOfContents, type TableOfContentsProps, TableRow, Tabs, TabsContent, TabsList, type TabsProps, TabsTrigger, TalkCard, type TalkCardProps, Text, type TextProps, Textarea, type TextareaProps, Theme, ThemeToggle, type ThemeToggleProps, ToastAction, type ToastOptions, type ToastVariant, Toaster, type ToasterProps, type TocEntry, Tooltip, TooltipContent, TooltipProvider, TooltipTrigger, alert as alertVariants, avatar as avatarVariants, badge as badgeVariants, button as buttonVariants, cn, text as textVariants, toast, useTheme };