npm - @eduardoalvarez/arrecife - Versions diffs - 0.6.0 → 0.7.0 - Mend

@eduardoalvarez/arrecife 0.6.0 → 0.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (42) hide show

package/CHANGELOG.md +69 -0
package/README.md +185 -20
package/dist/brand/index.js +3 -3
package/dist/chart/index.js +3 -3
package/dist/{chunk-XKYHTOUJ.js → chunk-2WPWEIMD.js} +1 -1
package/dist/chunk-45HVCTB7.js +70 -0
package/dist/{chunk-DKCN7BAL.js → chunk-727HCBD4.js} +1 -1
package/dist/{chunk-25YNFCIF.js → chunk-E6KFUSKB.js} +6 -3
package/dist/{chunk-6O3KWB6P.js → chunk-JN3IS5OS.js} +2 -2
package/dist/{chunk-O4TAH7YJ.js → chunk-OMKSESQB.js} +27 -3
package/dist/{chunk-PMN7NR3G.js → chunk-TA7TLWW4.js} +1 -1
package/dist/{chunk-JMOOFZ3B.js → chunk-WGNIRIN7.js} +1 -1
package/dist/doctor.mjs +166 -0
package/dist/form/index.js +4 -4
package/dist/icons/index.cjs +149 -0
package/dist/icons/index.d.cts +94 -0
package/dist/icons/index.d.ts +94 -0
package/dist/icons/index.js +28 -0
package/dist/index-DlAO2JZs.d.cts +47 -0
package/dist/index-DlAO2JZs.d.ts +47 -0
package/dist/index.cjs +279 -103
package/dist/index.d.cts +186 -57
package/dist/index.d.ts +186 -57
package/dist/index.js +262 -179
package/dist/og/index.cjs +3 -2
package/dist/og/index.js +1 -1
package/dist/shiki/index.js +1 -1
package/dist/social/index.cjs +67 -0
package/dist/social/index.d.cts +2 -0
package/dist/social/index.d.ts +2 -0
package/dist/social/index.js +2 -0
package/dist/tokens/index.cjs +27 -3
package/dist/tokens/index.d.cts +33 -6
package/dist/tokens/index.d.ts +33 -6
package/dist/tokens/index.js +2 -2
package/dist/tokens/theme.css +33 -3
package/dist/variants/index.cjs +6 -3
package/dist/variants/index.d.cts +4 -1
package/dist/variants/index.d.ts +4 -1
package/dist/variants/index.js +1 -1
package/llms.txt +363 -30
package/package.json +24 -2

package/llms.txt CHANGED Viewed

@@ -41,7 +41,7 @@ Radix, `clsx`, `tailwind-merge`, `class-variance-authority`, `date-fns` and
 `react-day-picker` come as dependencies of the library. You do not need to
 install or declare them.
-**It ships no `lucide-react` and no icon library.** The glyphs the components
+**It ships no icon set.** The glyphs the components
 need are inline, inherit `currentColor` and measure 1em.
 ## Tailwind configuration
@@ -116,6 +116,8 @@ that only whoever uses them installs.
 | `@eduardoalvarez/arrecife/og` | **no** | — | The Open Graph templates for Satori |
 | `@eduardoalvarez/arrecife/shiki` | **no** | — | The syntax highlighting theme |
 | `@eduardoalvarez/arrecife/brand` | yes | — | Logo, isotype and mascot as components |
+| `@eduardoalvarez/arrecife/social` | yes, on the server only | — | The nine social icons, loose. No `"use client"` |
+| `@eduardoalvarez/arrecife/icons` | yes | `@phosphor-icons/react` | `Icon`, which draws a Phosphor icon at the system's size, and at the weight its role asks for |
 | `@eduardoalvarez/arrecife/form` | yes | `react-hook-form` | The form layer: labels, errors and `aria-*` |
 | `@eduardoalvarez/arrecife/chart` | yes | `recharts` | The chart chassis and the series palette |
 | `@eduardoalvarez/arrecife/assets/*` | — | — | The brand PNGs |
@@ -124,15 +126,16 @@ Importing the root from a build script to get one token is the mistake the
 subpaths exist to prevent: it drags all of React into a worker that never mounts
 it.
-`./form` and `./chart` sit outside the root for the symmetric reason: if they
-hung off the main index, the projects that draw no charts and use no React Hook
-Form would have to install those dependencies anyway so their bundler could
-resolve an import they never execute.
+`./form`, `./chart` and `./icons` sit outside the root for the symmetric reason:
+if they hung off the main index, the projects that draw no charts, use no React
+Hook Form and need no icons would have to install those dependencies anyway so
+their bundler could resolve an import they never execute. Two of the five consume
+zero icons.
 ### Next, Server Components and `"use client"`
 The root, `./brand`, `./form` and `./chart` ship `"use client"` in the published
-`dist/`. They render React and their Radix primitives call `createContext` at
+`dist/`, and they are the only four. They render React and their Radix primitives call `createContext` at
 module scope, so without the directive a Next project with the App Router cannot
 import them at all: it fails at build time with
 `TypeError: (0 , r.createContext) is not a function`.
@@ -145,7 +148,11 @@ needed it.
 The five portable subpaths do NOT carry the directive, and that is the half that
 matters in a Server Component: `./tokens`, `./theme`, `./variants`, `./og` and
-`./shiki` stay on the server. If all you need are classes — for a `<div>`, an
+`./shiki` stay on the server. Neither does `./social`, which is a third case: it
+renders React — it is nine `<svg>` — so it can never be portable, but it holds no
+state and nothing about it needs a client boundary. It is the only way to put a
+social icon in a Server Component, and § «The social icons come from `./social`»
+below says why the grouped form cannot do it. If all you need are classes — for a `<div>`, an
 `<a>` or an Astro island you do not want to hydrate — import them from
 `./variants` and nothing crosses to the client:
@@ -202,21 +209,256 @@ It has to go INLINE. A `<script src>`, even a synchronous one, gets downloaded,
 and the flash comes back. The script re-attaches on `astro:after-swap` because
 view transitions replace the whole `<html>`.
-### The social icons are namespaced
+### `npx arrecife` — run it once after installing
+Two things break with **no error at all**, and the command catches both.
+**Tailwind purges everything the components emit** unless the stylesheet has
+`@source "<path>/node_modules/@eduardoalvarez/arrecife/dist"`. It does not scan
+`node_modules`. There is no console error and no undefined class: the card mounts
+with no padding, no radius and no border. The path is relative to the SHEET, not
+to the project root, and the command computes it.
+**A `--color-*` of yours silently replaces ours.** A project coming from shadcn
+has `@theme inline { --color-accent: var(--accent); }` — shadcn's `--accent` is
+the hover surface, `#17303E`, and ours is the brand turquoise, `#35D6C0`. That
+one line repainted 88 classes inside the library's own components grey. Five
+names collide in total; four agree on the value and are harmless, and the command
+tells them apart.
+Do not silence it by removing the `@import`: the fix is the `@source` line, or
+renaming your own token.
+### `SidebarNav` groups, and the icon replaces the prompt
+```tsx
+<SidebarNav aria-label="Administración" brand={<>…</>} version="v0.6.0" branch="main">
+  <SidebarItem href="/admin" icon={<Icon as={SquaresFour} />} active>Resumen</SidebarItem>
+  <SidebarGroup label="Ventas">
+    <SidebarItem href="/admin/ventas" icon={<Icon as={CreditCard} />}>Ventas</SidebarItem>
+    <SidebarItem href="/admin/cupones" icon={<Icon as={Ticket} />}>Cupones</SidebarItem>
+  </SidebarGroup>
+</SidebarNav>
+```
+Past about eight items a flat sidebar stops being readable. Each `SidebarGroup`
+is a nested list named by its label, so a screen reader says «lista Ventas, 3
+elementos» instead of one list of eleven. The label is a paragraph and **not** a
+heading on purpose: a sidebar is navigation, and a heading here would land in the
+page's own outline.
+**`icon` replaces the `▸`, it does not join it.** Do not pass a glyph and expect
+the prompt as well. A sidebar with no icons keeps the prompt on every item, which
+is what a four-section blog admin wants.
+**`brand` does not replace `title`.** `title` is the eyebrow and also the `nav`'s
+accessible name when it is a string; a logo is not an accessible name, so pass
+`aria-label` when you use `brand`. See `docs/decisions.md` § 32.
+**It collapses to a rail, and the toggle is CONTROLLED:**
+```tsx
+const [collapsed, setCollapsed] = useState(false);
+<SidebarNav
+  collapsed={collapsed}
+  onCollapsedChange={setCollapsed}
+  brand={<Wordmark />}
+  mark={<Isotype className="h-6" />}
+  user={<Avatar … />}
+>
+```
+There is no uncontrolled mode: this state is almost always persisted, and an
+internal one would fight the cookie you already keep. `onCollapsedChange` is also
+what makes the toggle appear — `collapsed` on its own is a rail with no way out,
+which is a layout and not an accident.
+Collapsed, the widths become `w-sidebar-rail` (56) and `w-sidebar` (256), and the
+component owns them only when it can collapse. It does **not** transition, on
+purpose. `brand` is hidden and `mark` takes its place, because a wordmark does
+not fit in a rail. Every label stays in the accessibility tree as `sr-only`, so
+do not «simplify» by dropping the children of a collapsed item. See
+`docs/decisions.md` § 34.
+### `Nav` is two slots and one height
+Almost everything an app shell wants from a site bar is already a slot:
+```tsx
+<Nav
+  size="compact"                                  // 56px, for a shell with a sidebar
+  brand={<a href="/"><Logo /><span><span className="text-accent">~/</span>cursos</span></a>}
+  actions={session ? <UserMenu /> : <Button size="sm" asChild><Link href="/login">Entrar</Link></Button>}
+>
+  <NavItem href="/cursos" active>cursos</NavItem>
+</Nav>
+```
+`brand` and `actions` are `ReactNode`, so a wordmark, a user menu, a theme toggle
+or a search box go in without the library knowing anything about sessions.
+**Session state does not get a prop** — it is project infrastructure, and the
+library takes none.
+`size="compact"` is 56px instead of 64, for a bar that shares the screen with a
+sidebar. It is a prop and not a class because the height lives on `Nav`'s inner
+container: `className` reaches the `<header>` and stops there, so passing `h-14`
+does nothing.
+**One `Nav` per page.** It renders the site's `banner` landmark, and two banners
+on one page is an accessibility failure — which is also why `PageHeader` goes
+inside `<main>` and is not a landmark. See `docs/decisions.md` § 30.
+### Icons are yours, the way they are drawn is not
+The library ships no icon set and `lib/glyphs.tsx` is not exported: it is the
+minimum set the primitives need and it does not grow. What the library does ship
+is the drawing.
+```tsx
+import { GraduationCap, Trash } from '@phosphor-icons/react';
+import { Icon } from '@eduardoalvarez/arrecife/icons';
+// 1em, and `tone="action"` by default — `regular`, the stroke the document names
+<Icon as={GraduationCap} />
+// Inside a control with no text, the name goes on the CONTROL
+<Button size="icon-sm" variant="secondary" aria-label="Borrar la fila">
+  <Icon as={Trash} />
+</Button>
+// Alone and meaning something on its own, it gets a name
+<Icon as={Trophy} label="Curso completado" />
+```
+**Do not size them by hand.** `size-4`, `size-3.5`, `size-6` scattered through a
+codebase is what this replaces: at 1em the icon takes the size of the text it
+sits in — 13px beside `text-label`, 15px beside `text-ui` — and nobody picks a
+number.
+**The weight is not yours to pick either, but it is not one value.** `tone` names
+what the icon is doing and the weight follows from it. There are three and there
+is no fourth:
+| `tone` | Weight | What it is |
+| --- | --- | --- |
+| `action` · the default | `regular` | An icon that is a control or names one. It is the system's line: 16 on a 256 grid = 0.0625em, against the document's 1.6 on a 24 grid = 0.0667em. Six per cent apart, which is no pixel on any screen |
+| `current` | `fill` | The one of a set you are on — the sidebar item carrying `aria-current` |
+| `quiet` | `light` | Furniture: a marker in a metadata row, not a control and not a state |
+```tsx
+<SidebarItem href="/cursos" active icon={<Icon as={GraduationCap} tone="current" />}>
+  cursos
+</SidebarItem>
+```
+`current` is the one that earns the axis. An active item already paints itself
+biolume, and colour on its own is the channel WCAG 1.4.1 says may not carry
+meaning alone; the fill is the second channel, and it is the one that survives a
+forced-colours mode. `weight` is deliberately **not** a prop: Phosphor ships six
+and this system reads three, because `thin`, `bold` and `duotone` have no role
+behind them here.
+`@phosphor-icons/react` is an **optional** peer dependency. If your project uses
+no icons you install nothing; two of the five do exactly that.
+**An icon is not illustration, and the two never substitute for each other.**
+Tiburoncín — the faces, the poses, the fin — is the mascot; it comes from
+`./brand`, and the manual says where a face may appear: empty states,
+confirmations, errors, course progress, celebration, and nowhere else. An icon is
+functional vocabulary and goes wherever a control needs a label it cannot spell.
+Do not put an icon where the system asks for a face, and do not put a face where
+a control wants an icon.
+**In Next, import from `@phosphor-icons/react/ssr` inside a Server Component.**
+Phosphor's default build reads `IconContext` through `useContext`, and a hook in
+a Server Component throws. It ships no `"use client"` to stop you, so the failure
+arrives at render rather than at build. The `/ssr` entry is the same icons
+without the context read, and `Icon` works with either.
+See `docs/decisions.md` § 29 and § 35.
+### `Stat`'s delta says direction, not judgement
+```tsx
+<Stat
+  label="alumnos"
+  value="1.284"
+  delta={{ value: '+12 esta semana', direction: 'up' }}
+/>
+```
+`direction` picks the arrow and **never the colour**. «+12 alumnos» and «+12
+errores» point the same way and mean opposite things, so whether a number is good
+news is `tone`'s job and yours: `neutral` for a datum, `alert` when the number IS
+the problem, `achievement` when it is the reward. `alert` and `achievement` paint
+the same sand on purpose — the API is the meaning, the colour is the
+implementation. See `docs/decisions.md` § 28.
+`delta.value` arrives already formatted, like `value`: the library imposes no
+locale and computes no percentage. `spark` is a `ReactNode` and the library ships
+no sparkline — pass your own, exactly like `icon`.
+**Do not colour the number.** A neutral `Stat` renders its value in primary ink,
+and biolume goes on the icon badge and the sparkline instead: three accents in
+one card and the figure stops being the loudest thing in it. `alert` and
+`achievement` DO paint the number sand, which is how «this number is not just a
+number» is said. See `docs/decisions.md` § 31.
+**`icon` is a badge in the corner opposite the title**, in a circle tinted at
+10 % of the tone. You pass the glyph; the circle, the tint and the size are the
+component's.
+### The two shapes of `EmptyState`
 ```tsx
-// ❌ does not exist
+// The empty state IS the screen: a search with no results, a 404, a section
+// with nothing in it yet. It carries the face, and `expression` is mandatory.
+<EmptyState expression="waiting" title="Sin resultados" description="…" />
+// The hole INSIDE something else: a table page, a dashboard widget. No face, no
+// surface, no border — the table or the card already draws the region.
+<EmptyState variant="inline" title="No hay lecciones en esta página" />
+// ❌ does not compile: the props are a union, and `inline` has no face
+<EmptyState variant="inline" expression="waiting" title="…" />
+```
+`inline` takes an optional `icon` — a `ReactNode` the project passes and sizes,
+at 1em and in `currentColor`, like `Stat`'s. The library ships no icons.
+Do not reach for `page` inside a table because the face is «nicer»: an admin
+screen with a dozen empty regions gets a dozen mascots, which is what made every
+consuming project write its own empty state instead of using this one.
+### The social icons come from `./social`
+```tsx
+// ❌ does not exist: the root publishes them grouped, not loose
 import { GitHub } from '@eduardoalvarez/arrecife';
-// ✅
+// ✅ the normal form
+import { GitHub } from '@eduardoalvarez/arrecife/social';
+// ✅ for iterating the catalogue
 import { social } from '@eduardoalvarez/arrecife';
 <social.GitHub />
 ```
 All nine: `GitHub`, `LinkedIn`, `X`, `Instagram`, `Discord`, `YouTube`, `Rss`,
-`Email`, `Newsletter`. They live under a namespace because one of them is called
-`X`, and loose it collides. `Newsletter` is the bell: a way to follow, like
-`Rss`, named for what it means.
+`Email`, `Newsletter`. `Newsletter` is the bell: a way to follow, like `Rss`,
+named for what it means.
+**In a Server Component the subpath is mandatory, not preferred.** The root
+carries `"use client"`, and a client reference crosses the boundary per EXPORT —
+the properties of a plain object are not exports, so `social.LinkedIn` is
+`undefined` on the server and `undefined` as an element type kills the build at
+prerender. `./social` carries no directive: it renders on the server and ships no
+client JS. Use `social` only when mapping a list of names onto icons.
+The root keeps the group because one of them is called `X`, and loose at the root
+it collides. In the subpath, alias it: `import { X as XIcon }`.
 The internal glyphs — `Close`, `ChevronDown`, `Sun` — are **not exported** and
 are not going to be: they are the primitives' minimum set. A component that needs
@@ -240,7 +482,7 @@ same value is available in both places and they cannot disagree.
 | `control.md` | `--spacing-control-md` | `px-control-md` |
 | `control.icon` | `--spacing-control-icon` | `size-control-icon` (42×42) |
 | `gradient[mode].hero` | `--gradient-hero` | `gradient-hero` |
-| `size.nav` | `--spacing-nav` | `h-nav` |
+| `size.nav` / `size.navCompact` | `--spacing-nav` / `--spacing-nav-compact` | `h-nav` / `h-nav-compact` |
 | `size.content` / `size.wide` | `--container-content` / `--container-wide` | `max-w-content` / `max-w-wide` |
 | `limits.measure` | `--container-measure` | `max-w-measure` |
 | `shadow.standard` | `--shadow-standard` | `shadow-standard` |
@@ -288,6 +530,11 @@ compiles and looks wrong, or that fails the project's accessibility audit.
 11. **The mascot's faces only appear** in empty states, confirmations, errors,
     course progress and celebration. Never in a hero, pricing, services, contact
     or the CV.
+    **And not in every empty state either**: `EmptyState variant="inline"` is the
+    hole inside a table page or a dashboard widget, and it carries no face — the
+    type does not accept one. `page`, the default, is the one that IS the screen,
+    and there `expression` stays mandatory. A dozen mascots on one admin screen is
+    not the humour contract. See `docs/decisions.md` § 27.
 12. **The fin is not a free parameter**: `foam` on a dark background, `color` on a
     light one. The components already choose it from the background.
@@ -968,7 +1215,7 @@ Source: `src/primitives/typography.tsx`
 ## Components
-Imported from `@eduardoalvarez/arrecife`. 24 exports.
+Imported from `@eduardoalvarez/arrecife`. 25 exports.
 ### ArticleCard
@@ -1078,17 +1325,17 @@ Source: `src/components/course-card/index.tsx`
 Source: `src/components/empty-state/index.tsx`
-The mascot's most important rule, finally as code.
-- Extends: `Omit<ComponentPropsWithoutRef<'div'>, 'title'>`
+- Extends: `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; 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; } )`
 | prop | type | req. | default | what it does |
 | --- | --- | --- | --- | --- |
 | `action` | `ReactNode` |  |  | The action that gets you out of the empty state. Usually a tertiary button. |
 | `basePath` | `string` |  |  | Where the brand PNGs are served from. |
 | `description` | `ReactNode` |  |  | One line explaining what is missing or what to do. |
-| `expression` | `"annoyed" \| "confused" \| "hearts" \| "laughing" \| "shades" \| "waiting" \| "wink"` | yes |  | The face. Mandatory: without it this is a centred paragraph. |
+| `expression` | `"annoyed" \| "confused" \| "hearts" \| "laughing" \| "shades" \| "waiting" \| "wink"` |  |  | 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. |
+| `icon` | `ReactNode` |  |  | 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. |
 | `title` | `ReactNode` | yes |  |  |
+| `variant` | `"inline" \| "page"` |  |  | `page`, the default: the empty state IS the screen or the section, and it carries the face. `inline`: the hole inside a table or a widget. No face, and no way to pass one. |
 ### EventCalendar
@@ -1167,7 +1414,7 @@ Migrated from `links/src/components/Card.astro`. The original scaled the card to
 Source: `src/components/nav/index.tsx`
 **Nav**
-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.
 - Extends: `ComponentPropsWithoutRef<'header'>`
@@ -1175,6 +1422,7 @@ The site bar: 64px, abyss at 86 % and a 14px blur behind it.
 | --- | --- | --- | --- | --- |
 | `actions` | `ReactNode` |  |  | Actions on the right: conversion, theme switch, search. |
 | `brand` | `ReactNode` |  |  | The logo, on the left. |
+| `size` | `"compact" \| "default"` |  | `default` | `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. |
 **NavItem**
 The `./` is put there by the component, not by whoever uses it.
@@ -1198,10 +1446,10 @@ Source: `src/components/newsletter-form/index.tsx`
 | `basePath` | `string` |  |  |  |
 | `description` | `ReactNode` |  |  |  |
 | `disclaimer` | `ReactNode` |  |  | The small print. It is the «sin spam», which is why it accepts a face. |
-| `errorMessage` | `ReactNode` |  | `No se pudo suscribir ese email. Revísalo y vuelve a intentar.` |  |
+| `errorMessage` | `ReactNode` |  | `No se pudo suscribir ese correo. Revísalo y vuelve a intentar.` |  |
 | `expression` | `"annoyed" \| "confused" \| "hearts" \| "laughing" \| "shades" \| "waiting" \| "wink"` |  |  |  |
 | `fieldErrors` | `{ name?: ReactNode; email?: ReactNode; }` |  |  | A message under one specific field, instead of the single alert. |
-| `fieldLabel` | `string` |  | `Email electrónico` |  |
+| `fieldLabel` | `string` |  | `Correo electrónico` |  |
 | `nameField` | `boolean` |  | `false` | Adds the name field ahead of the email one. |
 | `nameInputProps` | `Omit<InputProps, "id" \| "disabled" \| "name">` |  |  | Whatever the project needs to hang off the name field: `minLength`, `maxLength`, `pattern`. The library imposes none of the three. |
 | `nameLabel` | `string` |  | `Nombre` |  |
@@ -1212,7 +1460,7 @@ Source: `src/components/newsletter-form/index.tsx`
 | `resetOnSuccess` | `boolean` |  | `true` | Empties the fields after a successful subscription. On by default. |
 | `state` | `"success" \| "error" \| "idle" \| "sending"` |  | `idle` |  |
 | `submitLabel` | `string` |  | `Suscribirme` |  |
-| `successMessage` | `ReactNode` |  | `Ya estás dentro. Te llega un email cada dos semanas, y nada más.` |  |
+| `successMessage` | `ReactNode` |  | `Ya estás dentro. Te llega un correo cada dos semanas, y nada más.` |  |
 | `title` | `ReactNode` | yes |  |  |
 ### PageHeader
@@ -1246,7 +1494,7 @@ How much you have read. It is NOT `Progress` under another name.
 | `target` | `RefObject<HTMLElement \| null>` |  |  | The element being measured. Without it, the whole document. |
 | `tone` | `"accent" \| "warm"` |  | `accent` | Sand instead of biolume, to match course progress. |
-### SidebarItem, SidebarNav
+### SidebarItem, SidebarGroup, SidebarNav
 Source: `src/components/sidebar-nav/index.tsx`
@@ -1260,6 +1508,16 @@ The blog admin's sidebar.
 | `active` | `boolean \| undefined` |  | `false` |  |
 | `asChild` | `boolean \| undefined` |  | `false` |  |
 | `badge` | `ReactNode` |  |  | Counter on the right: pending drafts, unused media. |
+| `icon` | `ReactNode` |  |  | The section's glyph, on the left. It REPLACES the `▸` rather than joining it, and it inherits `currentColor`, so it follows the item's state without being tinted separately. |
+**SidebarGroup**
+A labelled block of items — «Contenido», «Alumnos», «Ventas».
+- Extends: `Omit<ComponentPropsWithoutRef<'li'>, 'title'>`
+| prop | type | req. | default | what it does |
+| --- | --- | --- | --- | --- |
+| `label` | `ReactNode` | yes |  | The block's name. Sentence case, not a section title. |
 **SidebarNav**
 - Extends: `ComponentPropsWithoutRef<'nav'>`
@@ -1267,6 +1525,13 @@ The blog admin's sidebar.
 | prop | type | req. | default | what it does |
 | --- | --- | --- | --- | --- |
 | `branch` | `ReactNode` |  |  |  |
+| `brand` | `ReactNode` |  |  | The row at the top: isotype and wordmark, `cursos · admin`. It is a slot and not a `logo`/`name` pair because every panel spells its own name differently, and the part that IS the system — the rhythm, the hairline under it — is here. |
+| `collapsed` | `boolean \| undefined` |  | `false` | Turns the sidebar into a rail: icons only, and the widths become the library's — `w-sidebar` and `w-sidebar-rail`. It is CONTROLLED and there is no uncontrolled mode, because this state is almost always persisted in a cookie or in `localStorage`, and an internal state would fight the one the project already keeps. |
+| `collapseLabel` | `string` |  | `Plegar el panel` | The toggle's accessible name, in the two directions. |
+| `expandLabel` | `string` |  | `Desplegar el panel` |  |
+| `mark` | `ReactNode` |  |  | What `brand` becomes in the rail. Usually the isotype with no wordmark. |
+| `onCollapsedChange` | `(collapsed: boolean) => void` |  |  | Called with what the state should become. With it, the toggle appears; with `collapsed` alone the sidebar is a rail with no way out of it, which is a legitimate layout and not an accident. |
+| `user` | `ReactNode` |  |  | Who is signed in, at the bottom above the version. A slot, because an avatar needs a session and a sign-out route and the library takes no project infrastructure — the same reason `Nav`'s user menu goes in `actions`. |
 | `version` | `ReactNode` |  |  | Version and branch, at the bottom. |
 ### Stat
@@ -1279,11 +1544,13 @@ A large metric: the number in the `stat` scale and its name underneath.
 | prop | type | req. | default | what it does |
 | --- | --- | --- | --- | --- |
+| `delta` | `StatDelta` |  |  | How the number moved since last time. |
 | `description` | `ReactNode` |  |  | The standfirst: the nuance the number alone does not give. «12 aplicaciones» does not say whether that is a lot, and this is where that gets said. |
-| `icon` | `ReactNode` |  |  | Glyph beside the title, at 1em. It inherits `currentColor`, so it follows the title's tone and does not have to be tinted separately. |
+| `icon` | `ReactNode` |  |  | 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. |
 | `label` | `ReactNode` | yes |  | What is being counted. It goes in mono small caps. |
 | `progress` | `number` |  |  | With `progress`, the metric reads as progress and adds the bar. |
-| `tone` | `"neutral" \| "alerta"` |  | `neutral` | `alerta` only when the number IS the problem. |
+| `spark` | `ReactNode` |  |  | 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`. |
+| `tone` | `"neutral" \| "alert" \| "achievement"` |  | `neutral` | `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.md` § 28. |
 | `value` | `ReactNode` | yes |  | The number, already formatted. The library imposes no locale. |
 ### TalkCard
@@ -1315,7 +1582,7 @@ The control that was missing. The library defined the whole theming system and e
 | prop | type | req. | default | what it does |
 | --- | --- | --- | --- | --- |
-| `label` | `string` |  | `Cambiar de theme` | Accessible name. The button has no visible text, so it is the only thing naming it. |
+| `label` | `string` |  | `Cambiar de tema` | Accessible name. The button has no visible text, so it is the only thing naming it. |
 | `onThemeChange` | `(theme: Theme) => void` |  |  | Fires with whichever theme ended up set, in case the project wants to record it. |
 | `size` | `"sm" \| "md" \| "lg" \| "icon" \| "icon-sm"` |  | `icon` |  |
 | `variant` | `"primary" \| "conversion" \| "secondary" \| "tertiary" \| "destructive" \| "destructiveOutline"` |  | `secondary` |  |
@@ -1389,6 +1656,59 @@ Tiburoncín's head, with an expression.
 | `basePath` | `string` |  | `ASSETS_PATH` |  |
 | `expression` | `"annoyed" \| "confused" \| "hearts" \| "laughing" \| "shades" \| "waiting" \| "wink"` | yes |  |  |
+## Social icons
+Imported from `@eduardoalvarez/arrecife/social` · or grouped as `social` from the root. 9 exports.
+### GitHub, LinkedIn, X, Instagram, Discord, YouTube, Rss, Email, Newsletter
+Source: `src/social/index.tsx`
+**GitHub**
+- No own props: it passes through those of the element or primitive it wraps.
+**LinkedIn**
+- No own props: it passes through those of the element or primitive it wraps.
+**X**
+- No own props: it passes through those of the element or primitive it wraps.
+**Instagram**
+- No own props: it passes through those of the element or primitive it wraps.
+**Discord**
+- No own props: it passes through those of the element or primitive it wraps.
+**YouTube**
+- No own props: it passes through those of the element or primitive it wraps.
+**Rss**
+- No own props: it passes through those of the element or primitive it wraps.
+**Email**
+- No own props: it passes through those of the element or primitive it wraps.
+**Newsletter**
+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.
+- No own props: it passes through those of the element or primitive it wraps.
+## Icons
+Imported from `@eduardoalvarez/arrecife/icons` · requires `@phosphor-icons/react`. 1 exports.
+### Icon
+Source: `src/icons/index.tsx`
+- Extends: `Omit<PhosphorIconProps, 'size' \| 'weight' \| 'ref'>`
+| prop | type | req. | default | what it does |
+| --- | --- | --- | --- | --- |
+| `as` | `Icon` | yes |  | The Phosphor icon itself, passed as a component: `<Icon as={Books} />`. |
+| `label` | `string` |  |  | The accessible name. WITHOUT it the icon is decorative and gets `aria-hidden`, which is the right default: most icons sit beside their own label and announcing them twice is noise. |
+| `tone` | `"action" \| "current" \| "quiet"` |  | `action` | WHAT THE ICON IS DOING, which is what picks the weight. Three values, and there is no fourth: `action` is the default and the system's line, `current` is the one of a set you are on, `quiet` is furniture that is not a control. `weight` is deliberately not a prop — see `TONE_WEIGHT`. |
 ## Forms
 Imported from `@eduardoalvarez/arrecife/form` · requires `react-hook-form`. 7 exports.
@@ -1521,7 +1841,7 @@ it: if the code does not mount React, that subpath is the one to import.
 | `radius` | `{ readonly chip: 6; readonly control: 10; readonly card: 14; readonly panel: 16; readonly pill: 999; }` |  |
 | `series` | `{ readonly dark: readonly ["#35D6C0", "#F2A65A", "#3E7CB1", "#71919C"]; readonly light: readonly ["#0D7C6F", "#A65B27", "#3E7CB1", "#626A75"]; }` | The chart series palette. FOUR, for the same reason as the syntax palette: the system communicates with color and border, not with chromatic noise. |
 | `shadow` | `{ readonly standard: "0 1px 2px rgba(0, 0, 0, 0.35)"; }` | A single level. There is no elevation scale. |
-| `size` | `{ readonly nav: 64; readonly content: 760; readonly wide: 1180; }` |  |
+| `size` | `{ readonly nav: 64; readonly navCompact: 56; readonly sidebar: 256; readonly sidebarRail: 56; readonly content: 760; readonly wide: 1180; }` |  |
 | `spacing` | `{ readonly stepXs: 8; readonly stepSm: 12; readonly stepMd: 16; readonly stepLg: 26; readonly stepXl: 40; readonly section: 96; }` | Page rhythm. All five steps carry `step` in the name, and that is not decoration: it is the fix for a bug that never surfaced anywhere. |
 | `syntax` | `{ background, identifier, literal, keyword, comment, invalid }` | The syntax highlighting palette. |
 | `tagline` | `{ long, short, en }` |  |
@@ -1530,6 +1850,10 @@ it: if the code does not mount React, that subpath is the one to import.
 Types (13): `BrandToken`, `ColorMode`, `ColorToken`, `ControlToken`, `FontToken`, `GradientToken`, `RadiusToken`, `SeriesToken`, `SizeToken`, `SpacingToken`, `SyntaxToken`, `Tokens`, `TypeScaleToken`.
+### `@eduardoalvarez/arrecife/social`
+Types (1): `SocialIconProps`.
 ### `@eduardoalvarez/arrecife/theme`
 | export | type | what it is |
@@ -1561,6 +1885,15 @@ Types (2): `Theme`, `ThemeOptions`.
 Types (8): `Background`, `Face`, `Fin`, `IsotypeProps`, `LogoProps`, `MascotFaceProps`, `MascotProps`, `Pose`.
+### `@eduardoalvarez/arrecife/icons`
+| export | type | what it is |
+| --- | --- | --- |
+| `ICON_WEIGHT` | `"light" \| "fill" \| "thin" \| "regular" \| "bold" \| "duotone"` | Phosphor's own name for the system's line. It is what `tone="action"` resolves to. |
+| `TONE_WEIGHT` | `Record<IconTone, IconWeight>` | The three roles, and the weight each one is drawn at. This is the whole of the weight axis: Phosphor ships six and this system reads three, because the other three — `thin`, `bold`, `duotone` — have no role behind them here. |
+Types (2): `IconProps`, `IconTone`.
 ### `@eduardoalvarez/arrecife/shiki`
 | export | type | what it is |
@@ -1602,11 +1935,11 @@ Types (6): `ArticleData`, `BaseData`, `CourseData`, `DefaultData`, `SatoriNode`,
 | export | type | what it is |
 | --- | --- | --- |
 | `cn` | `(...inputs: ClassValue[]): string` |  |
-| `social` | `typeof import("src/lib/social")` |  |
+| `social` | `typeof import("src/social/index")` |  |
 | `toast` | `(message: ReactNode, options?: ToastOptions \| undefined): string` | Fires a notice. It returns its id, which is what you keep in order to close it by hand — the «guardando…» case that gets replaced when the request finishes. |
 | `useTheme` | `(): Theme` | The theme set right now, for a project that needs to branch in React — a different logo per mode, an image with no light version. |
-Types (60): `AccordionProps`, `AccordionTriggerProps`, `AlertProps`, `ArticleCardProps`, `AudioPlayerMode`, `AudioPlayerProps`, `AuthorCardProps`, `AvatarProps`, `AvatarUploadProps`, `BadgeProps`, `BlockquoteProps`, `BreadcrumbProps`, `ButtonProps`, `CalendarEvent`, `CalendarProps`, `CategoryBadgeProps`, `CheckboxProps`, `CodeBlockProps`, `CodeProps`, `CourseCardProps`, `Crumb`, `DateFieldProps`, `EmptyStateProps`, `EventCalendarProps`, `FooterLinkProps`, `FooterProps`, `HeroProps`, `InputProps`, `LabelProps`, `LinkRowProps`, `MetricBadgeProps`, `NavItemProps`, `NavProps`, `NewsletterFormProps`, `NewsletterState`, `PageHeaderProps`, `PaginationLinkProps`, `PopoverContentProps`, `ProgressProps`, `RadioGroupItemProps`, `RadioGroupProps`, `ScrollingProgressBarProps`, `SeparatorProps`, `SheetContentProps`, `SidebarItemProps`, `SidebarNavProps`, `SkeletonProps`, `SocialLink`, `StatProps`, `SwitchProps`, `TableOfContentsProps`, `TabsProps`, `TalkCardProps`, `TextProps`, `TextareaProps`, `ThemeToggleProps`, `ToastOptions`, `ToastVariant`, `ToasterProps`, `TocEntry`.
+Types (62): `AccordionProps`, `AccordionTriggerProps`, `AlertProps`, `ArticleCardProps`, `AudioPlayerMode`, `AudioPlayerProps`, `AuthorCardProps`, `AvatarProps`, `AvatarUploadProps`, `BadgeProps`, `BlockquoteProps`, `BreadcrumbProps`, `ButtonProps`, `CalendarEvent`, `CalendarProps`, `CategoryBadgeProps`, `CheckboxProps`, `CodeBlockProps`, `CodeProps`, `CourseCardProps`, `Crumb`, `DateFieldProps`, `EmptyStateProps`, `EventCalendarProps`, `FooterLinkProps`, `FooterProps`, `HeroProps`, `InputProps`, `LabelProps`, `LinkRowProps`, `MetricBadgeProps`, `NavItemProps`, `NavProps`, `NewsletterFormProps`, `NewsletterState`, `PageHeaderProps`, `PaginationLinkProps`, `PopoverContentProps`, `ProgressProps`, `RadioGroupItemProps`, `RadioGroupProps`, `ScrollingProgressBarProps`, `SeparatorProps`, `SheetContentProps`, `SidebarGroupProps`, `SidebarItemProps`, `SidebarNavProps`, `SkeletonProps`, `SocialLink`, `StatDelta`, `StatProps`, `SwitchProps`, `TableOfContentsProps`, `TabsProps`, `TalkCardProps`, `TextProps`, `TextareaProps`, `ThemeToggleProps`, `ToastOptions`, `ToastVariant`, `ToasterProps`, `TocEntry`.
 # Where to look if this is not enough

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@eduardoalvarez/arrecife",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "The component library of Eduardo Álvarez’s visual identity",
   "license": "MIT",
   "author": "Eduardo Esteban Álvarez Castañeda <soy@eduardoalvarez.dev>",
@@ -49,6 +49,16 @@
       "import": "./dist/brand/index.js",
       "require": "./dist/brand/index.cjs"
     },
+    "./social": {
+      "types": "./dist/social/index.d.ts",
+      "import": "./dist/social/index.js",
+      "require": "./dist/social/index.cjs"
+    },
+    "./icons": {
+      "types": "./dist/icons/index.d.ts",
+      "import": "./dist/icons/index.js",
+      "require": "./dist/icons/index.cjs"
+    },
     "./og": {
       "types": "./dist/og/index.d.ts",
       "import": "./dist/og/index.js",
@@ -73,16 +83,23 @@
     "./assets/*": "./assets/*",
     "./package.json": "./package.json"
   },
+  "bin": {
+    "arrecife": "./dist/doctor.mjs"
+  },
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "scripts": {
-    "build": "pnpm check:tokens && pnpm check:namespace && tsup && node scripts/add-use-client.mjs && pnpm build:tokens && pnpm build:llms",
+    "build": "pnpm check:tokens && pnpm check:namespace && tsup && node scripts/add-use-client.mjs && pnpm build:tokens && pnpm build:doctor && pnpm build:llms",
     "build:tokens": "node scripts/build-tokens.mjs",
+    "build:doctor": "node scripts/build-doctor.mjs",
     "build:llms": "node scripts/build-llms.mjs",
     "check:tokens": "node scripts/check-tokens-purity.mjs",
     "check:namespace": "node scripts/check-tokens-namespace.mjs",
     "check:llms": "node scripts/build-llms.mjs --check",
+    "check:copy": "node scripts/check-copy-language.mjs",
+    "check:decisions": "node scripts/check-decisions.mjs",
+    "doctor": "node scripts/doctor.mjs",
     "check:exports": "node scripts/check-package-exports.mjs",
     "check:release": "node scripts/check-release-config.mjs",
     "typecheck": "tsc --noEmit",
@@ -97,12 +114,16 @@
     "test:light": "STORYBOOK_THEME=light vitest run --project storybook"
   },
   "peerDependencies": {
+    "@phosphor-icons/react": "^2.1.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
     "react-hook-form": "^7.0.0",
     "recharts": "^3.0.0"
   },
   "peerDependenciesMeta": {
+    "@phosphor-icons/react": {
+      "optional": true
+    },
     "react-hook-form": {
       "optional": true
     },
@@ -112,6 +133,7 @@
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
+    "@phosphor-icons/react": "^2.1.10",
     "@storybook/addon-a11y": "^10.5.10",
     "@storybook/addon-docs": "^10.5.10",
     "@storybook/addon-themes": "^10.5.10",