@eduardoalvarez/arrecife 0.10.0 → 0.12.0

package/CHANGELOG.md

@@ -1,5 +1,42 @@
 # Changelog
 
+## [0.12.0](https://github.com/Proskynete/arrecife/compare/v0.11.0...v0.12.0) (2026-09-12)
+
+
+### 🚀 Novedades
+
+* **components:** the footer can credit the library, and it is off by default ([9b80bd8](https://github.com/Proskynete/arrecife/commit/9b80bd80dc2bc1d4637a132e3b3b9dfbc254f653))
+* **storybook:** the site wears the projects' mark and prints its version ([4c36b94](https://github.com/Proskynete/arrecife/commit/4c36b94d31d7353982eaa58ab75da2b309d972ef))
+
+
+### 🐛 Correcciones
+
+* **storybook:** the docs page stops showing the first story twice ([66f0016](https://github.com/Proskynete/arrecife/commit/66f00163ee6b1f5feb111022762928db112b709e))
+* **tokens:** emit the whole token set, so a var() read from JS resolves ([68836c8](https://github.com/Proskynete/arrecife/commit/68836c861a6a80d74bd6d23c279bfc05978626dc))
+
+
+### 📚 Documentación
+
+* one file per decision, so a reference stops carrying a version ([1deda8e](https://github.com/Proskynete/arrecife/commit/1deda8e3f09585856741e23bceebf5d18e5b5336))
+* **readme:** [@theme](https://github.com/theme) static, builtWith, and how a decision is cited ([ded6f2c](https://github.com/Proskynete/arrecife/commit/ded6f2ca6cc32c4a6746ad66417afa29f66b881d))
+* three decisions, and two of them are about what the library says of itself ([c52c89f](https://github.com/Proskynete/arrecife/commit/c52c89f0507d99bb3886d412e91fc11922debcd4))
+
+## [0.11.0](https://github.com/Proskynete/arrecife/compare/v0.10.0...v0.11.0) (2026-09-11)
+
+
+### 🚀 Novedades
+
+* **brand:** the fin can follow the theme with background="auto" ([3021f24](https://github.com/Proskynete/arrecife/commit/3021f24575c6f9422b7f322bf825a878a735306d))
+* **chart:** valueMax sets the top of the value axis ([ccebe24](https://github.com/Proskynete/arrecife/commit/ccebe24361ce4004916b433819ddf7f53f89907a))
+* **components:** CourseCard takes a cover and a closing row ([a3c73d0](https://github.com/Proskynete/arrecife/commit/a3c73d0b21edffc16c2965475fce9de6e1502926))
+* **components:** PageHeader lets the screen pick the title scale ([99bd553](https://github.com/Proskynete/arrecife/commit/99bd55376992109ea90c8eaedc435ffcadffdb0e))
+
+
+### 📚 Documentación
+
+* four decisions from cursos adopting the whole library ([2a712b8](https://github.com/Proskynete/arrecife/commit/2a712b871edd73f63fddfd2733279bf3e2834e07))
+* **readme:** background="auto", valueMax, and the story count ([149442c](https://github.com/Proskynete/arrecife/commit/149442cb2748da9cb06b3df23254cba46aae378a))
+
 ## [0.10.0](https://github.com/Proskynete/arrecife/compare/v0.9.0...v0.10.0) (2026-09-09)
 
 

package/README.md

@@ -16,7 +16,10 @@ in a project with a `#E05252` that this README has declared wrong for months, an
 nobody saw it because the document was not greppable from the code.
 
 `docs/decisions/` is the other half: the points where the code and the document
-do not say the same thing, each with its resolution and its reason.
+do not say the same thing, each with its resolution and its reason. One file per
+decision, named for its number — `045-signature-halo.md` — so a «§ 45» written
+in a comment, a commit or a PR resolves by sorting the folder, and no reference
+has to carry a version.
 
 ## The two documents for agents
 
@@ -52,6 +55,16 @@ One source, `src/tokens/tokens.ts`. One generated output,
 `scripts/build-tokens.mjs`; it is not edited by hand and it is regenerated on
 every build.
 
+The block is `@theme static`, so **every token reaches `:root` whether or not a
+class asks for it** — you can read any of them with `var(--color-…)` from your
+own JavaScript or an inline style and it will be there. That is one word and it
+is a bug fix: Tailwind v4 emits a theme variable only when some generated
+utility uses one, and the four `--color-series-*` are read by `seriesColor()`
+through `var()` and requested by no class anywhere, so they were being dropped
+as unused and the charts drew black on a dark page with nothing erroring. It
+costs +234 B gzipped for a project using the system's whole vocabulary, and the
+ceiling is the token set. See `docs/decisions/` § 61.
+
 Phase 0 decision: **v4 only**. The portfolio (`eduardoalvarez.dev`) migrates from
 Tailwind v3 to v4 before consuming Arrecife. If that migration slips, publishing
 the v3 preset again is one more emitter in `build-tokens.mjs` reading the same
@@ -404,7 +417,7 @@ now draws Phosphor through `astro-icon` and its own docstring lists the divergen
 «every icon on the page — the six in the cards and the four here — is then one set
 at one weight». `eduardoalvarez.dev` did the same in `site-footer.tsx`. Two
 consumers walking away from a subpath built for them is the library being out of
-step, not the consumers. See `docs/decisions/0.10.md` § 51.
+step, not the consumers. See `docs/decisions/` § 51.
 
 **In a Next Server Component, take the glyph from `@phosphor-icons/react/ssr`.**
 `./icons` carries no `"use client"` on purpose, so an icon renders on the server
@@ -456,7 +469,7 @@ stroke` story shows the bars so the claim can be checked instead of believed.
 `glyphs.tsx` drew at 0.109em — three quarters heavier than both — and 0.7.0
 measured it, said so and left it alone, because aligning it restyles every
 primitive in the library. 0.10.0 is that change: the file is gone and there is
-one line in the system. See `docs/decisions/0.10.md` § 51.
+one line in the system. See `docs/decisions/` § 51.
 
 **The weight is an axis with three values, and `tone` is how you name them.**
 `weight` is not a prop: Phosphor ships six and this system reads three, because
@@ -474,7 +487,7 @@ one channel WCAG 1.4.1 says may not carry meaning** — the fill is the second
 channel, and it is the one that survives a forced-colours mode where the biolume
 does not. `quiet` is the opposite problem: in a metadata row the icon is not the
 point of the line, and at `regular` it draws as heavy as the date beside it.
-`docs/decisions/0.7.md` § 35 has the rest.
+`docs/decisions/` § 35 has the rest.
 
 `@phosphor-icons/react` is an **optional** peer dependency on its own subpath, by
 the same rule as `./form` and `./chart`: two of the five projects use no icons and
@@ -586,7 +599,19 @@ collision is deliberate: what they replace is not an import, it is sixty lines o
 composition — a `linearGradient` with a hardcoded id, a `CartesianGrid
 vertical={false}`, two axes with the line and the tick off, a `type="natural"`
 and a `strokeWidth` — which `cursos` wrote four times, once per chart. None of
-that is a decision the project made. See `docs/decisions/0.8.md` § 43.
+that is a decision the project made. See `docs/decisions/` § 43.
+
+A chart of a quantity with a ceiling passes it: `valueMax={100}` on a percentage.
+Without it the value axis ends at the largest datum, and a horizontal ranking —
+whose value axis is hidden — draws a course watched to 40 % as a full bar. See
+`docs/decisions/` § 58.
+
+`seriesColor(i)` returns `var(--color-series-N)` and not a hexadecimal, so the
+palette follows the mode instead of freezing to whichever one was live when the
+chart mounted. **Do not add a fallback to it**: the variable is always in
+`:root`, because the token block is `@theme static` for exactly this reason. On a
+version before that fix the `var()` resolved to nothing and the bars came out
+black — see `docs/decisions/` § 61.
 
 `check:exports` verifies that the five portable ones — `./tokens`, `./theme`,
 `./variants`, `./og` and `./shiki` — bring no React into the published `dist/`,
@@ -603,7 +628,7 @@ chunk imports it.
 | `pnpm typecheck` | `tsc --noEmit` |
 | `pnpm lint` | ESLint, including the ban on literal hexes outside `tokens.ts` |
 | `pnpm check:tokens` | fails if `src/tokens/` imports anything from outside |
-| `pnpm test` | compiles Tailwind and runs axe over the 208 stories, in both modes |
+| `pnpm test` | compiles Tailwind and runs axe over the 248 stories, in both modes |
 | `pnpm check:exports` | verifies that `dist/` holds what `exports` promises |
 | `pnpm check:release` | validates `release-please-config.json` against the official schema |
 | `pnpm storybook` | generates the tokens and serves Storybook on 6006 |
@@ -657,7 +682,7 @@ cannot see: axe does not evaluate text over a gradient, so both modes passed it.
 
 The light blocks now sweep between `background` and `surface` and never touch
 `surfaceRaised`, so the darkest point of either one is the page itself — a token
-that passes on the page passes at every point of the sweep. `docs/decisions/0.6.md` § 9 has the measurements, including the two other things the first composition
+that passes on the page passes at every point of the sweep. `docs/decisions/` § 9 has the measurements, including the two other things the first composition
 got wrong.
 
 ### The third correction: a semantic color is not a text color over its own tint
@@ -856,7 +881,7 @@ run summary.
   `SidebarNav` was on that list and came off it in 0.8.0. It met the rule below
   on the identity half and never on the consumer half: the two admin projects it
   was built for each wrote their own and never imported it. See
-  `docs/decisions/0.8.md` § 48.
+  `docs/decisions/` § 48.
 
   The criterion for deciding what gets in is still the same: **it encodes an
   identity rule, it has two or more consumers, and it drags in no project
@@ -897,7 +922,7 @@ about as library pieces. They get in anyway: the CLI aesthetic — the bar's
   optional peer on `./icons` so the set a project chooses is drawn at the system's
   weight; and 0.10.0 deleted `glyphs.tsx` and `./social` and made Phosphor
   required, because a library drawing in three hands cannot say which one is
-  right. See «The social icons are yours too» above and `docs/decisions/0.10.md`
+  right. See «The social icons are yours too» above and `docs/decisions/`
   § 51. What survives verbatim is the part that was always the real rule: the
   icons are the project's, the LINE is the system's. The rest of this bullet is
   the 0.7.0 argument, kept because it is what the reversal was measured against:
@@ -934,7 +959,7 @@ about as library pieces. They get in anyway: the CLI aesthetic — the bar's
   than width failed axe on `scrollable-region-focusable` immediately. It is
   unconditional, because whether a table overflows depends on the viewport and
   the only alternative is a ResizeObserver on every table in the system. See
-  `docs/decisions/0.8.md` § 39.
+  `docs/decisions/` § 39.
 
 ### The syntax palette
 
@@ -1047,6 +1072,12 @@ adding a line to the catalog.
 Pixel analysis confirms it — 94 % of `fin-foam.png` is `#EDF4F3`, which is the
 foam token.
 
+On a site that switches theme, `background="auto"` renders both and the `light:`
+variant shows the one that reads, so no call site has to know which theme is on.
+A background that does not follow the theme — a dark panel on a light page —
+still names itself: `auto` reads the page, not the panel. See
+`docs/decisions/` § 60.
+
 **Rule 5 as API.** The wordmark comes from `naming.wordmark` and always reads
 «Eduardo Álvarez». There is no prop that changes that text, and Tiburoncín never
 appears written inside the logo.
@@ -1122,7 +1153,7 @@ spatial continuity. A sixth lands on that or it does not exist.
 The bar is 2px and not a block because a halo needs something thin to radiate
 from, the colour is `var(--color-accent)` so it follows the mode, and
 `motion-safe` is the one thing not copied from `cursos` — whose span animates
-regardless of the setting. See `docs/decisions/0.8.md` § 45, and § 23 for the entry
+regardless of the setting. See `docs/decisions/` § 45, and § 23 for the entry
 it reverses.
 
 ### The second motion exception
@@ -1169,7 +1200,7 @@ text, and `surfaceRaised` is where a toolbar lives.
 `destructiveOutline` fills on hover, and that is a declared exception to
 «secondary is never filled» — a destructive that looks identical to a secondary
 until you read it is the problem the variant exists to fix. See
-`docs/decisions/0.6.md` § 21.
+`docs/decisions/` § 21.
 
 ### `icon-sm`, for the one admin app
 
@@ -1180,7 +1211,7 @@ three actions per table row, and at 42 the row grows with them.
 `size="icon-sm"` is 32×32, and it is 32 and not the 28 that project actually had:
 32 is `sm`'s height, so a dense icon button lines up with a small text button and
 a toolbar mixing the two stays on one baseline. It does not replace `icon` — a
-page's primary action stays at 42. See `docs/decisions/0.6.md` § 22.
+page's primary action stays at 42. See `docs/decisions/` § 22.
 
 ### The theme script, and the mode a site already decided
 

package/dist/brand/index.cjs

@@ -75,7 +75,7 @@ var typeScale = {
    * (plankton 5.57:1 over abyss), which is the part that is not negotiable.
    *
    * At 13 the three badge families grew past the size of a small button and
-   * outweighed the title they accompany. See `docs/decisions/`.
+   * outweighed the title they accompany. See `docs/decisions/` § 10.
    */
   chip: { family: "mono", size: 11.5, lineHeight: 1.4, weight: 400 },
   /**
@@ -121,7 +121,7 @@ var control = {
    * baseline; 28 would have been a fifth height that matches nothing.
    *
    * It does not replace `icon`. A page's primary action stays at 42; this is for
-   * a row of a table. See `docs/decisions/0.6.md` § 22.
+   * a row of a table. See `docs/decisions/` § 22.
    */
   iconSm: 32
 };
@@ -168,18 +168,24 @@ function Isotype({
   className,
   ...props
 }) {
-  const file = background === "dark" ? fins.foam : fins.color;
-  return /* @__PURE__ */ jsxRuntime.jsx(
+  const fin = (file, mode) => /* @__PURE__ */ jsxRuntime.jsx(
     "img",
     {
       src: `${basePath}/${file}`,
       alt,
       width: 147,
       height: 111,
-      className: cn("h-8 w-auto select-none", className),
+      className: cn("h-8 w-auto select-none", className, mode),
       ...props
     }
   );
+  if (background === "auto") {
+    return /* @__PURE__ */ jsxRuntime.jsxs(jsxRuntime.Fragment, { children: [
+      fin(fins.foam, "light:hidden"),
+      fin(fins.color, "not-light:hidden")
+    ] });
+  }
+  return fin(background === "dark" ? fins.foam : fins.color);
 }
 function Logo({
   background = "dark",

package/dist/brand/index.d.cts

@@ -3,21 +3,60 @@ export { A as ASSETS_PATH, a as Fin, f as faceList, b as faceUsage, c as faces,
 import * as react from 'react';
 import { ComponentPropsWithoutRef } from 'react';
 
+/**
+ * Which background the fin sits on, or `auto` to let the theme decide.
+ *
+ * It is its own type and not a third member of `Background`, because
+ * `Background` is also what the OG templates read, and Satori has no CSS to
+ * resolve `auto` with: a template knows its mode and has to say it.
+ */
+type IsotypeBackground = Background | 'auto';
 type IsotypeProps = Omit<ComponentPropsWithoutRef<'img'>, 'src' | 'alt'> & {
     /**
-     * Which background it sits on. Deciding is mandatory even though it has a
-     * default: the fin's body is nearly black, so the two-blue variant disappears
-     * over abyss. Being a prop, the rule stops being something to remember.
+     * Which background it sits on, or `auto` on a site that switches theme: both
+     * fins are rendered and CSS shows the one that reads. Deciding is mandatory
+     * even though it has a default: the fin's body is nearly black, so the
+     * two-blue variant disappears over abyss.
+     *
+     * Use `dark` or `light` when the background does not follow the theme. A
+     * panel that stays dark in both modes is a fixed background, and `auto` would
+     * pick the page's fin instead of the panel's.
      */
-    background?: Background | undefined;
+    background?: IsotypeBackground | undefined;
     basePath?: string | undefined;
     /** Alt text. Empty when the isotype accompanies text that already names it. */
     alt?: string | undefined;
 };
+/**
+ * The fin, in the variant its background asks for.
+ *
+ * `auto` renders both and lets the `light:` variant choose, which is what
+ * `ThemeToggle` already does with its two icons and for the same reason: the
+ * server does not know the theme, and a fin picked in JavaScript would be wrong
+ * on the first paint half the time. `cursos` had written exactly this by hand
+ * after a surface changed mode and its fin vanished — not looked wrong: vanished,
+ * with no error and no gap in the layout. See `docs/decisions/` § 60.
+ *
+ * Dark is the system default, so the foam fin is the one shown unless
+ * `data-theme="light"` says otherwise, and the two-blue one hides everywhere
+ * else. `not-light:hidden` rather than `hidden light:block`: the visible fin
+ * keeps whatever `display` the call site gave it.
+ *
+ * What it costs: the hidden image is still downloaded, 14 or 21 KB. And with
+ * `auto` the props land on BOTH `<img>` — an `id` or a `ref` included — so a
+ * call site that needs to reach the one image passes the background it is on.
+ * The `alt` does not double: an image with `display: none` is out of the
+ * accessibility tree.
+ */
 declare function Isotype({ background, basePath, alt, className, ...props }: IsotypeProps): react.JSX.Element;
 
 type LogoProps = Omit<ComponentPropsWithoutRef<'span'>, 'children'> & {
-    background?: Background | undefined;
+    /**
+     * The background the logo sits on, handed to its fin. `auto` follows the
+     * theme — see `Isotype`. The wordmark needs no help: it is `textPrimary`, which
+     * already follows the mode.
+     */
+    background?: IsotypeBackground | undefined;
     basePath?: string | undefined;
     /** Hides the wordmark and leaves only the fin, for very narrow bars. */
     isotypeOnly?: boolean | undefined;
@@ -69,4 +108,4 @@ type MascotFaceProps = Base & {
  */
 declare function MascotFace({ expression, basePath, alt, className, ...props }: MascotFaceProps): react.JSX.Element;
 
-export { Background, Face, Isotype, type IsotypeProps, Logo, type LogoProps, Mascot, MascotFace, type MascotFaceProps, type MascotProps, Pose };
+export { Background, Face, Isotype, type IsotypeBackground, type IsotypeProps, Logo, type LogoProps, Mascot, MascotFace, type MascotFaceProps, type MascotProps, Pose };

package/dist/brand/index.d.ts

@@ -3,21 +3,60 @@ export { A as ASSETS_PATH, a as Fin, f as faceList, b as faceUsage, c as faces,
 import * as react from 'react';
 import { ComponentPropsWithoutRef } from 'react';
 
+/**
+ * Which background the fin sits on, or `auto` to let the theme decide.
+ *
+ * It is its own type and not a third member of `Background`, because
+ * `Background` is also what the OG templates read, and Satori has no CSS to
+ * resolve `auto` with: a template knows its mode and has to say it.
+ */
+type IsotypeBackground = Background | 'auto';
 type IsotypeProps = Omit<ComponentPropsWithoutRef<'img'>, 'src' | 'alt'> & {
     /**
-     * Which background it sits on. Deciding is mandatory even though it has a
-     * default: the fin's body is nearly black, so the two-blue variant disappears
-     * over abyss. Being a prop, the rule stops being something to remember.
+     * Which background it sits on, or `auto` on a site that switches theme: both
+     * fins are rendered and CSS shows the one that reads. Deciding is mandatory
+     * even though it has a default: the fin's body is nearly black, so the
+     * two-blue variant disappears over abyss.
+     *
+     * Use `dark` or `light` when the background does not follow the theme. A
+     * panel that stays dark in both modes is a fixed background, and `auto` would
+     * pick the page's fin instead of the panel's.
      */
-    background?: Background | undefined;
+    background?: IsotypeBackground | undefined;
     basePath?: string | undefined;
     /** Alt text. Empty when the isotype accompanies text that already names it. */
     alt?: string | undefined;
 };
+/**
+ * The fin, in the variant its background asks for.
+ *
+ * `auto` renders both and lets the `light:` variant choose, which is what
+ * `ThemeToggle` already does with its two icons and for the same reason: the
+ * server does not know the theme, and a fin picked in JavaScript would be wrong
+ * on the first paint half the time. `cursos` had written exactly this by hand
+ * after a surface changed mode and its fin vanished — not looked wrong: vanished,
+ * with no error and no gap in the layout. See `docs/decisions/` § 60.
+ *
+ * Dark is the system default, so the foam fin is the one shown unless
+ * `data-theme="light"` says otherwise, and the two-blue one hides everywhere
+ * else. `not-light:hidden` rather than `hidden light:block`: the visible fin
+ * keeps whatever `display` the call site gave it.
+ *
+ * What it costs: the hidden image is still downloaded, 14 or 21 KB. And with
+ * `auto` the props land on BOTH `<img>` — an `id` or a `ref` included — so a
+ * call site that needs to reach the one image passes the background it is on.
+ * The `alt` does not double: an image with `display: none` is out of the
+ * accessibility tree.
+ */
 declare function Isotype({ background, basePath, alt, className, ...props }: IsotypeProps): react.JSX.Element;
 
 type LogoProps = Omit<ComponentPropsWithoutRef<'span'>, 'children'> & {
-    background?: Background | undefined;
+    /**
+     * The background the logo sits on, handed to its fin. `auto` follows the
+     * theme — see `Isotype`. The wordmark needs no help: it is `textPrimary`, which
+     * already follows the mode.
+     */
+    background?: IsotypeBackground | undefined;
     basePath?: string | undefined;
     /** Hides the wordmark and leaves only the fin, for very narrow bars. */
     isotypeOnly?: boolean | undefined;
@@ -69,4 +108,4 @@ type MascotFaceProps = Base & {
  */
 declare function MascotFace({ expression, basePath, alt, className, ...props }: MascotFaceProps): react.JSX.Element;
 
-export { Background, Face, Isotype, type IsotypeProps, Logo, type LogoProps, Mascot, MascotFace, type MascotFaceProps, type MascotProps, Pose };
+export { Background, Face, Isotype, type IsotypeBackground, type IsotypeProps, Logo, type LogoProps, Mascot, MascotFace, type MascotFaceProps, type MascotProps, Pose };

package/dist/brand/index.js

@@ -1,5 +1,5 @@
 'use client';
-export { Isotype, Logo, Mascot, MascotFace } from '../chunk-IIT3YLYN.js';
-import '../chunk-FAAGZG7A.js';
+export { Isotype, Logo, Mascot, MascotFace } from '../chunk-BRDTB44R.js';
+import '../chunk-TMUGT3Y3.js';
 export { ASSETS_PATH, faceList, faceUsage, faces, fins, poseList, poses } from '../chunk-CKRSQPTX.js';
-import '../chunk-FGFNK72B.js';
+import '../chunk-5YWGOFDX.js';

package/dist/chart/index.cjs

@@ -46,7 +46,7 @@ var typeScale = {
    * (plankton 5.57:1 over abyss), which is the part that is not negotiable.
    *
    * At 13 the three badge families grew past the size of a small button and
-   * outweighed the title they accompany. See `docs/decisions/`.
+   * outweighed the title they accompany. See `docs/decisions/` § 10.
    */
   chip: { family: "mono", size: 11.5, lineHeight: 1.4, weight: 400 },
   /**
@@ -92,7 +92,7 @@ var control = {
    * baseline; 28 would have been a fifth height that matches nothing.
    *
    * It does not replace `icon`. A page's primary action stays at 42; this is for
-   * a row of a table. See `docs/decisions/0.6.md` § 22.
+   * a row of a table. See `docs/decisions/` § 22.
    */
   iconSm: 32
 };
@@ -300,6 +300,7 @@ var color = (series2, index) => series2.color ?? seriesColor(index);
 var MARGIN = { left: 0, right: 12, top: 8, bottom: 0 };
 var AXIS = { tickLine: false, axisLine: false };
 var tickOf = (format) => format ? { tickFormatter: format } : {};
+var domainOf = (max) => max === void 0 ? {} : { domain: [0, max] };
 var legendOf = (series2, legend) => legend ?? series2.length > 1 ? /* @__PURE__ */ jsxRuntime.jsx(ChartLegend, { content: /* @__PURE__ */ jsxRuntime.jsx(ChartLegendContent, {}) }, "legend") : null;
 var tooltipOf = (formatter) => /* @__PURE__ */ jsxRuntime.jsx(
   ChartTooltip,
@@ -316,6 +317,7 @@ function AreaChart({
   formatter,
   xTickFormatter,
   yTickFormatter,
+  valueMax,
   legend,
   stacked = false,
   ...container
@@ -328,7 +330,7 @@ function AreaChart({
     ] }, s.key)) }),
     /* @__PURE__ */ jsxRuntime.jsx(recharts.CartesianGrid, { vertical: false }),
     /* @__PURE__ */ jsxRuntime.jsx(recharts.XAxis, { dataKey: xKey, ...AXIS, tickMargin: 8, ...tickOf(xTickFormatter) }),
-    /* @__PURE__ */ jsxRuntime.jsx(recharts.YAxis, { ...AXIS, width: 40, ...tickOf(yTickFormatter) }),
+    /* @__PURE__ */ jsxRuntime.jsx(recharts.YAxis, { ...AXIS, width: 40, ...tickOf(yTickFormatter), ...domainOf(valueMax) }),
     tooltipOf(formatter),
     legendOf(series2, legend),
     series2.map((s, i) => /* @__PURE__ */ jsxRuntime.jsx(
@@ -354,6 +356,7 @@ function BarChart({
   formatter,
   xTickFormatter,
   yTickFormatter,
+  valueMax,
   legend,
   orientation = "vertical",
   stacked = false,
@@ -380,7 +383,16 @@ function BarChart({
             },
             "category"
           ),
-          /* @__PURE__ */ jsxRuntime.jsx(recharts.XAxis, { type: "number", hide: true, ...tickOf(yTickFormatter) }, "value")
+          /* @__PURE__ */ jsxRuntime.jsx(
+            recharts.XAxis,
+            {
+              type: "number",
+              hide: true,
+              ...tickOf(yTickFormatter),
+              ...domainOf(valueMax)
+            },
+            "value"
+          )
         ] : [
           /* @__PURE__ */ jsxRuntime.jsx(
             recharts.XAxis,
@@ -392,7 +404,16 @@ function BarChart({
             },
             "category"
           ),
-          /* @__PURE__ */ jsxRuntime.jsx(recharts.YAxis, { ...AXIS, width: 40, ...tickOf(yTickFormatter) }, "value")
+          /* @__PURE__ */ jsxRuntime.jsx(
+            recharts.YAxis,
+            {
+              ...AXIS,
+              width: 40,
+              ...tickOf(yTickFormatter),
+              ...domainOf(valueMax)
+            },
+            "value"
+          )
         ],
         tooltipOf(formatter),
         legendOf(series2, legend),
@@ -419,13 +440,14 @@ function LineChart({
   formatter,
   xTickFormatter,
   yTickFormatter,
+  valueMax,
   legend,
   ...container
 }) {
   return /* @__PURE__ */ jsxRuntime.jsx(ChartContainer, { ...container, children: /* @__PURE__ */ jsxRuntime.jsxs(recharts.LineChart, { data: rows(data), margin: MARGIN, children: [
     /* @__PURE__ */ jsxRuntime.jsx(recharts.CartesianGrid, { vertical: false }),
     /* @__PURE__ */ jsxRuntime.jsx(recharts.XAxis, { dataKey: xKey, ...AXIS, tickMargin: 8, ...tickOf(xTickFormatter) }),
-    /* @__PURE__ */ jsxRuntime.jsx(recharts.YAxis, { ...AXIS, width: 40, ...tickOf(yTickFormatter) }),
+    /* @__PURE__ */ jsxRuntime.jsx(recharts.YAxis, { ...AXIS, width: 40, ...tickOf(yTickFormatter), ...domainOf(valueMax) }),
     tooltipOf(formatter),
     legendOf(series2, legend),
     series2.map((s, i) => /* @__PURE__ */ jsxRuntime.jsx(

package/dist/chart/index.d.cts

@@ -29,7 +29,7 @@ import { Legend, Tooltip } from 'recharts';
  * What IS published, since this version, are three CHART TYPES on top of that
  * chassis: `AreaChart`, `BarChart` and `LineChart`. They are not wrappers over
  * Recharts' components of the same name — they take `data`, `series` and `xKey`
- * and draw the whole thing. See `docs/decisions/0.8.md` § 43 for why the names
+ * and draw the whole thing. See `docs/decisions/` § 43 for why the names
  * collide on purpose.
  */
 /**
@@ -175,7 +175,7 @@ type SeriesChartProps = Omit<ChartContainerProps, 'children'> & {
      * `2026-07-15` repeated thirty times, overlapping into a grey band.
      *
      * The library imposes no format: a date key can be a day, a month or a course
-     * name, and only the project knows which. See `docs/decisions/0.9.md` § 50.
+     * name, and only the project knows which. See `docs/decisions/` § 50.
      */
     xTickFormatter?: ((value: unknown) => string) | undefined;
     /**
@@ -187,6 +187,22 @@ type SeriesChartProps = Omit<ChartContainerProps, 'children'> & {
      * «$1200» in the tooltip, and the axis is the one you read while comparing.
      */
     yTickFormatter?: ((value: unknown) => string) | undefined;
+    /**
+     * The top of the value axis, when the scale has one that the data does not
+     * reach — 100 for a percentage.
+     *
+     * Without it the axis ends at the largest datum, and on a chart of «% visto»
+     * a course watched to 40 % draws as a full bar when it is the highest on the
+     * list. On `BarChart orientation="horizontal"` nothing gives that away: the
+     * value axis is hidden by design, so the chart says something false and
+     * looks exactly like one that does not.
+     *
+     * The bottom is always zero. A bar that does not start at zero is a
+     * different lie, and this prop is not a way into it. It is a floor for the
+     * top and not a clip either: a datum above it extends the axis instead of
+     * running off the edge. See `docs/decisions/` § 58.
+     */
+    valueMax?: number | undefined;
     /**
      * Shows the legend. It defaults to «only when there is more than one series»:
      * a legend naming the one line already named by the chart's own heading is a
@@ -217,7 +233,7 @@ type AreaChartProps = SeriesChartProps & {
     /** Adds the series up instead of overlaying them. */
     stacked?: boolean | undefined;
 };
-declare function AreaChart({ data, series, xKey, formatter, xTickFormatter, yTickFormatter, legend, stacked, ...container }: AreaChartProps): react.JSX.Element;
+declare function AreaChart({ data, series, xKey, formatter, xTickFormatter, yTickFormatter, valueMax, legend, stacked, ...container }: AreaChartProps): react.JSX.Element;
 /**
  * Bars, upright or lying down.
  *
@@ -241,7 +257,7 @@ type BarChartProps = SeriesChartProps & {
     /** Stacks the series instead of putting them side by side. */
     stacked?: boolean | undefined;
 };
-declare function BarChart({ data, series, xKey, formatter, xTickFormatter, yTickFormatter, legend, orientation, stacked, ...container }: BarChartProps): react.JSX.Element;
+declare function BarChart({ data, series, xKey, formatter, xTickFormatter, yTickFormatter, valueMax, legend, orientation, stacked, ...container }: BarChartProps): react.JSX.Element;
 /**
  * Lines, for comparing series against each other.
  *
@@ -254,6 +270,6 @@ declare function BarChart({ data, series, xKey, formatter, xTickFormatter, yTick
  * where it means «this one».
  */
 type LineChartProps = SeriesChartProps;
-declare function LineChart({ data, series, xKey, formatter, xTickFormatter, yTickFormatter, legend, ...container }: LineChartProps): react.JSX.Element;
+declare function LineChart({ data, series, xKey, formatter, xTickFormatter, yTickFormatter, valueMax, legend, ...container }: LineChartProps): react.JSX.Element;
 
 export { AreaChart, type AreaChartProps, BarChart, type BarChartProps, ChartContainer, type ChartContainerProps, type ChartDatum, ChartLegend, ChartLegendContent, type ChartLegendContentProps, type ChartPayloadItem, type ChartSeries, ChartTooltip, ChartTooltipContent, type ChartTooltipContentProps, LineChart, type LineChartProps, SERIES_COLORS, type SeriesChartProps, seriesColor };

package/dist/chart/index.d.ts

@@ -29,7 +29,7 @@ import { Legend, Tooltip } from 'recharts';
  * What IS published, since this version, are three CHART TYPES on top of that
  * chassis: `AreaChart`, `BarChart` and `LineChart`. They are not wrappers over
  * Recharts' components of the same name — they take `data`, `series` and `xKey`
- * and draw the whole thing. See `docs/decisions/0.8.md` § 43 for why the names
+ * and draw the whole thing. See `docs/decisions/` § 43 for why the names
  * collide on purpose.
  */
 /**
@@ -175,7 +175,7 @@ type SeriesChartProps = Omit<ChartContainerProps, 'children'> & {
      * `2026-07-15` repeated thirty times, overlapping into a grey band.
      *
      * The library imposes no format: a date key can be a day, a month or a course
-     * name, and only the project knows which. See `docs/decisions/0.9.md` § 50.
+     * name, and only the project knows which. See `docs/decisions/` § 50.
      */
     xTickFormatter?: ((value: unknown) => string) | undefined;
     /**
@@ -187,6 +187,22 @@ type SeriesChartProps = Omit<ChartContainerProps, 'children'> & {
      * «$1200» in the tooltip, and the axis is the one you read while comparing.
      */
     yTickFormatter?: ((value: unknown) => string) | undefined;
+    /**
+     * The top of the value axis, when the scale has one that the data does not
+     * reach — 100 for a percentage.
+     *
+     * Without it the axis ends at the largest datum, and on a chart of «% visto»
+     * a course watched to 40 % draws as a full bar when it is the highest on the
+     * list. On `BarChart orientation="horizontal"` nothing gives that away: the
+     * value axis is hidden by design, so the chart says something false and
+     * looks exactly like one that does not.
+     *
+     * The bottom is always zero. A bar that does not start at zero is a
+     * different lie, and this prop is not a way into it. It is a floor for the
+     * top and not a clip either: a datum above it extends the axis instead of
+     * running off the edge. See `docs/decisions/` § 58.
+     */
+    valueMax?: number | undefined;
     /**
      * Shows the legend. It defaults to «only when there is more than one series»:
      * a legend naming the one line already named by the chart's own heading is a
@@ -217,7 +233,7 @@ type AreaChartProps = SeriesChartProps & {
     /** Adds the series up instead of overlaying them. */
     stacked?: boolean | undefined;
 };
-declare function AreaChart({ data, series, xKey, formatter, xTickFormatter, yTickFormatter, legend, stacked, ...container }: AreaChartProps): react.JSX.Element;
+declare function AreaChart({ data, series, xKey, formatter, xTickFormatter, yTickFormatter, valueMax, legend, stacked, ...container }: AreaChartProps): react.JSX.Element;
 /**
  * Bars, upright or lying down.
  *
@@ -241,7 +257,7 @@ type BarChartProps = SeriesChartProps & {
     /** Stacks the series instead of putting them side by side. */
     stacked?: boolean | undefined;
 };
-declare function BarChart({ data, series, xKey, formatter, xTickFormatter, yTickFormatter, legend, orientation, stacked, ...container }: BarChartProps): react.JSX.Element;
+declare function BarChart({ data, series, xKey, formatter, xTickFormatter, yTickFormatter, valueMax, legend, orientation, stacked, ...container }: BarChartProps): react.JSX.Element;
 /**
  * Lines, for comparing series against each other.
  *
@@ -254,6 +270,6 @@ declare function BarChart({ data, series, xKey, formatter, xTickFormatter, yTick
  * where it means «this one».
  */
 type LineChartProps = SeriesChartProps;
-declare function LineChart({ data, series, xKey, formatter, xTickFormatter, yTickFormatter, legend, ...container }: LineChartProps): react.JSX.Element;
+declare function LineChart({ data, series, xKey, formatter, xTickFormatter, yTickFormatter, valueMax, legend, ...container }: LineChartProps): react.JSX.Element;
 
 export { AreaChart, type AreaChartProps, BarChart, type BarChartProps, ChartContainer, type ChartContainerProps, type ChartDatum, ChartLegend, ChartLegendContent, type ChartLegendContentProps, type ChartPayloadItem, type ChartSeries, ChartTooltip, ChartTooltipContent, type ChartTooltipContentProps, LineChart, type LineChartProps, SERIES_COLORS, type SeriesChartProps, seriesColor };