@eduardoalvarez/arrecife 0.9.0 → 0.11.0

package/dist/index.d.cts

@@ -26,9 +26,8 @@ import * as ToastPrimitive from '@radix-ui/react-toast';
 import * as TooltipPrimitive from '@radix-ui/react-tooltip';
 import { F as Face, P as Pose } from './catalog-D13txprv.cjs';
 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.cjs';
-export { Isotype, IsotypeProps, Logo, LogoProps, Mascot, MascotFace, MascotFaceProps, MascotProps } from './brand/index.cjs';
+export { Isotype, IsotypeBackground, IsotypeProps, Logo, LogoProps, Mascot, MascotFace, MascotFaceProps, MascotProps } from './brand/index.cjs';
 import { ClassValue } from 'clsx';
-export { i as social } from './index-BbRplw_B.cjs';
 import '@radix-ui/react-label';
 
 /**
@@ -81,8 +80,8 @@ declare function AccordionContent({ className, children, ...props }: ComponentPr
 type AlertProps = Omit<ComponentPropsWithoutRef<'div'>, 'title'> & VariantProps<typeof alert> & {
     title?: ReactNode;
     /**
-     * Replaces the variant's mono glyph. Never an emoji: if you need something
-     * else, it is an SVG from `glyphs`.
+     * Replaces the variant's glyph. Never an emoji: if you need something else,
+     * it is `<Icon as={…} />` from `@eduardoalvarez/arrecife/icons`.
      */
     icon?: ReactNode;
 };
@@ -545,6 +544,40 @@ type TextareaProps = ComponentProps<'textarea'> & {
 declare function Textarea({ className, invalid, ...props }: TextareaProps): react.JSX.Element;
 
 declare const ToastAction: react.ForwardRefExoticComponent<ToastPrimitive.ToastActionProps & react.RefAttributes<HTMLButtonElement>>;
+/**
+ * THE TONE IS A SURFACE, NOT A LINE, and that is what 0.10.0 changed.
+ *
+ * It used to be `bg-surface` for all three and the whole difference between a
+ * confirmation and a failure was `border-success/40` against `border-error/40`:
+ * two hairlines at 40 % opacity, on a box that floats over whatever page it
+ * happens to land on, with no mark on it and the text in `textSecondary`. At the
+ * size a toast actually appears at, that is not a colour — it is two greys.
+ *
+ * What it is now is the recipe `Alert` already carries and had already argued:
+ * the semantic colour SOLID on the border and at 10 % as a tint, which is
+ * `emphasis="strong"` in `variants/alert.ts`. That variant exists for the alert
+ * that has to read UNDER a form field, and a toast has the same problem from the
+ * other side — it reads over content it did not choose, so the subtle 8 %/22 %
+ * recipe is not enough on its own.
+ *
+ * THE TINT RIDES ON A GRADIENT and not on `background-color`, which is the one
+ * odd line here. A toast has to be OPAQUE: it floats, and `bg-success/10` alone
+ * would let the article underneath show through it. `bg-surface` paints the
+ * opaque ground and the flat `linear-gradient` paints the tint on top of it, in
+ * one element, without a wrapper or a `::before` that would need its own
+ * stacking context. The two `from-`/`to-` stops are the same colour on purpose:
+ * it is a fill, not a gradient.
+ *
+ * MEASURED over the resulting surface, dark then light, worst case of the two:
+ *
+ *   text-text-primary over the success tint   14.9   14.6
+ *   text-text-secondary over the success tint  8.4    7.1
+ *   the border against the tint                4.2    3.6   (3:1 graphical)
+ *
+ * The body stays `textSecondary` and the title `textPrimary`, which is the same
+ * split `Alert` uses and for the same reason: a semantic colour is not a text
+ * colour over its own tint.
+ */
 declare const toast$1: (props?: ({
     variant?: "error" | "neutral" | "success" | null | undefined;
 } & class_variance_authority_types.ClassProp) | undefined) => string;
@@ -734,15 +767,19 @@ declare function AuthorCard({ name, role, src, bio, action, className, ...props
  * the same. What changed is the skin and the two dependencies a package cannot
  * have:
  *
- * - the portfolio's `Icon` → the glyphs now live in `src/lib/glyphs.tsx`, with
- *   the same paths.
+ * - the portfolio's `Icon` → the library's own `Icon` over Phosphor. The eight
+ *   paths this file used to carry verbatim from the portfolio are gone with
+ *   `lib/glyphs.tsx`; `Play`, `Pause`, `SpeakerHigh` and `SpeakerSlash` are the
+ *   same symbols in Phosphor's hand, and the ±15s skips are `ArrowCounterClockwise`
+ *   and `ArrowClockwise`. See `docs/decisions/0.10.md` § 51.
  * - analytics' `trackEvent` → the `onFirstPlay` prop, which the consumer wires
  *   to whatever they use. It still fires exactly once per load.
  *
  * And three things the system does not allow:
  *
- * - The waveform no longer animates `scaleY`. The bars are still there and still
- *   tell playback from pause by opacity, but they do not scale.
+ * - The waveform no longer animates `scaleY`. Since 0.10.0 it is not even drawn
+ *   here: it is Phosphor's `Waveform`, which is the same five bars. It still
+ *   tells playback from pause by opacity, and it does not move.
  * - The floating player appears and disappears instead of sliding.
  * - The progress bar no longer interpolates its width.
  *
@@ -832,7 +869,13 @@ type CodeBlockProps = Omit<ComponentPropsWithoutRef<'div'>, 'children'> & {
 };
 declare function CodeBlock({ children, language, copyText, className, ...props }: CodeBlockProps): react.JSX.Element;
 
-type CourseCardProps = Omit<CardShellProps, 'children' | 'title'> & {
+/**
+ * `media` is left out of the shell's props because `<a>` already has an
+ * attribute by that name — a media query for the linked resource, a string —
+ * and intersected with the slot it would make the slot accept only strings.
+ * No browser acts on it and no project was passing it.
+ */
+type CourseCardProps = Omit<CardShellProps, 'children' | 'title' | 'media'> & {
     title: ReactNode;
     summary?: ReactNode;
     /** Level, duration, number of lessons: whatever the project wants to list. */
@@ -844,8 +887,42 @@ type CourseCardProps = Omit<CardShellProps, 'children' | 'title'> & {
      * when passed, the bar goes in sand, which is the color of course progress.
      */
     progress?: number | undefined;
+    /**
+     * The cover, at the top and bleeding to the card's edges, with `alt=""`: the
+     * whole card is one link and `title` already names it.
+     *
+     * The project owns the element — an `<img>`, a framework's `Image`, a
+     * generated cover — and its ratio; the card clips it to its own corners. An
+     * `alt` that repeats the title makes a screen reader say the course twice
+     * before anything else.
+     */
+    media?: ReactNode;
+    /**
+     * The closing row, under `meta`: the rating, the price, whatever the project
+     * sells the course with. It sits at the bottom of the card, so the rows of a
+     * grid line up whatever the length of each summary.
+     */
+    footer?: ReactNode;
 };
-declare function CourseCard({ title, summary, meta, status, progress, className, ...props }: CourseCardProps): react.JSX.Element;
+/**
+ * The course, as a card that links to it.
+ *
+ * `media` and `footer` are slots rather than props for a cover URL, a rating
+ * and a price, because none of those three is the identity's. The price comes
+ * formatted in a currency the library does not know, the rating is drawn by a
+ * component the project already has, and the cover is an image pipeline. What
+ * IS the identity's stays here: the title's scale and its hover, the sand bar,
+ * the status badge. See `docs/decisions/0.11.md` § 59.
+ *
+ * The title does NOT go over the cover. It stays in the body at `h3`, with the
+ * hover every other card has. Text on a photograph needs a scrim, and a scrim's
+ * contrast depends on the photograph: it cannot be measured once and recorded,
+ * which is the only way contrast is decided in this system.
+ *
+ * And the cover does not move on hover. Rule 6 is the border and nothing else:
+ * no zoom, no scale, no displacement.
+ */
+declare function CourseCard({ title, summary, meta, status, progress, media, footer, className, ...props }: CourseCardProps): react.JSX.Element;
 
 /**
  * The mascot's most important rule, finally as code.
@@ -982,8 +1059,10 @@ type SocialLink = {
     label: string;
     href: string;
     /**
-     * The glyph, at 19px. Brands are SOLID (`fill`) and functional icons use a 1.6
-     * stroke. Never an emoji.
+     * The glyph, at 19px. It is the PROJECT's — the library ships no catalogue of
+     * social marks since 0.10.0 — and the drawing rule it should follow is the
+     * system's: a brand is SOLID, so `<Icon as={GithubLogo} tone="current" />`,
+     * and a functional mark keeps the default `action`. Never an emoji.
      */
     icon: ReactNode;
 };
@@ -1353,6 +1432,15 @@ declare function NewsletterForm({ title, description, state, onSubmitEmail, succ
  *
  * `display` for covers, `page` for section headers.
  *
+ * The size picks the title's scale by default, and `titleVariant` lets the
+ * screen pick another one. The default is the document's — «h1 44/700» on the
+ * six interior pages of the reading site — and it is right there. It is not
+ * right in the two admin apps: `blog-content-manager` titles its twelve screens
+ * at 24px, and `cursos` titles 29 of its 32 at `h3` — every one in the panel —
+ * and the other three, the public catalog pages, at `h2`. Both are rungs the
+ * scale already has, and a third `size` could only have named one of them. See
+ * `docs/decisions/0.11.md` § 57.
+ *
  * It takes no mascot face, at either scale: faces go in empty states,
  * confirmations, errors, course progress and celebration.
  *
@@ -1377,8 +1465,21 @@ type PageHeaderProps = Omit<ComponentPropsWithoutRef<'header'>, 'title'> & Varia
     action?: ReactNode | undefined;
     /** The headline's level. `h1` unless the page already has one. */
     as?: 'h1' | 'h2' | undefined;
+    /**
+     * The headline's scale, when the screen needs a different one from what
+     * `size` gives — `display` for `display`, `h1` for `page`.
+     *
+     * It is the same split `Text` makes: `as` is the level, this is how big it
+     * looks. A panel's `<h1>` at `h3` is still the page's only `h1`. The padding
+     * stays with `size`, so a header inside a layout that already spaces its
+     * content passes `className="py-0"`.
+     *
+     * Only the four headline scales, all in the display family. `stat` is for
+     * numbers and `body` is not a headline.
+     */
+    titleVariant?: 'display' | 'h1' | 'h2' | 'h3' | undefined;
 };
-declare function PageHeader({ title, eyebrow, description, action, size, as, className, ...props }: PageHeaderProps): react.JSX.Element;
+declare function PageHeader({ title, eyebrow, description, action, size, as, titleVariant, className, ...props }: PageHeaderProps): react.JSX.Element;
 
 /**
  * How much you have read. It is NOT `Progress` under another name.

package/dist/index.d.ts

@@ -26,9 +26,8 @@ import * as ToastPrimitive from '@radix-ui/react-toast';
 import * as TooltipPrimitive from '@radix-ui/react-tooltip';
 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';
+export { Isotype, IsotypeBackground, 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';
 
 /**
@@ -81,8 +80,8 @@ declare function AccordionContent({ className, children, ...props }: ComponentPr
 type AlertProps = Omit<ComponentPropsWithoutRef<'div'>, 'title'> & VariantProps<typeof alert> & {
     title?: ReactNode;
     /**
-     * Replaces the variant's mono glyph. Never an emoji: if you need something
-     * else, it is an SVG from `glyphs`.
+     * Replaces the variant's glyph. Never an emoji: if you need something else,
+     * it is `<Icon as={…} />` from `@eduardoalvarez/arrecife/icons`.
      */
     icon?: ReactNode;
 };
@@ -545,6 +544,40 @@ type TextareaProps = ComponentProps<'textarea'> & {
 declare function Textarea({ className, invalid, ...props }: TextareaProps): react.JSX.Element;
 
 declare const ToastAction: react.ForwardRefExoticComponent<ToastPrimitive.ToastActionProps & react.RefAttributes<HTMLButtonElement>>;
+/**
+ * THE TONE IS A SURFACE, NOT A LINE, and that is what 0.10.0 changed.
+ *
+ * It used to be `bg-surface` for all three and the whole difference between a
+ * confirmation and a failure was `border-success/40` against `border-error/40`:
+ * two hairlines at 40 % opacity, on a box that floats over whatever page it
+ * happens to land on, with no mark on it and the text in `textSecondary`. At the
+ * size a toast actually appears at, that is not a colour — it is two greys.
+ *
+ * What it is now is the recipe `Alert` already carries and had already argued:
+ * the semantic colour SOLID on the border and at 10 % as a tint, which is
+ * `emphasis="strong"` in `variants/alert.ts`. That variant exists for the alert
+ * that has to read UNDER a form field, and a toast has the same problem from the
+ * other side — it reads over content it did not choose, so the subtle 8 %/22 %
+ * recipe is not enough on its own.
+ *
+ * THE TINT RIDES ON A GRADIENT and not on `background-color`, which is the one
+ * odd line here. A toast has to be OPAQUE: it floats, and `bg-success/10` alone
+ * would let the article underneath show through it. `bg-surface` paints the
+ * opaque ground and the flat `linear-gradient` paints the tint on top of it, in
+ * one element, without a wrapper or a `::before` that would need its own
+ * stacking context. The two `from-`/`to-` stops are the same colour on purpose:
+ * it is a fill, not a gradient.
+ *
+ * MEASURED over the resulting surface, dark then light, worst case of the two:
+ *
+ *   text-text-primary over the success tint   14.9   14.6
+ *   text-text-secondary over the success tint  8.4    7.1
+ *   the border against the tint                4.2    3.6   (3:1 graphical)
+ *
+ * The body stays `textSecondary` and the title `textPrimary`, which is the same
+ * split `Alert` uses and for the same reason: a semantic colour is not a text
+ * colour over its own tint.
+ */
 declare const toast$1: (props?: ({
     variant?: "error" | "neutral" | "success" | null | undefined;
 } & class_variance_authority_types.ClassProp) | undefined) => string;
@@ -734,15 +767,19 @@ declare function AuthorCard({ name, role, src, bio, action, className, ...props
  * the same. What changed is the skin and the two dependencies a package cannot
  * have:
  *
- * - the portfolio's `Icon` → the glyphs now live in `src/lib/glyphs.tsx`, with
- *   the same paths.
+ * - the portfolio's `Icon` → the library's own `Icon` over Phosphor. The eight
+ *   paths this file used to carry verbatim from the portfolio are gone with
+ *   `lib/glyphs.tsx`; `Play`, `Pause`, `SpeakerHigh` and `SpeakerSlash` are the
+ *   same symbols in Phosphor's hand, and the ±15s skips are `ArrowCounterClockwise`
+ *   and `ArrowClockwise`. See `docs/decisions/0.10.md` § 51.
  * - analytics' `trackEvent` → the `onFirstPlay` prop, which the consumer wires
  *   to whatever they use. It still fires exactly once per load.
  *
  * And three things the system does not allow:
  *
- * - The waveform no longer animates `scaleY`. The bars are still there and still
- *   tell playback from pause by opacity, but they do not scale.
+ * - The waveform no longer animates `scaleY`. Since 0.10.0 it is not even drawn
+ *   here: it is Phosphor's `Waveform`, which is the same five bars. It still
+ *   tells playback from pause by opacity, and it does not move.
  * - The floating player appears and disappears instead of sliding.
  * - The progress bar no longer interpolates its width.
  *
@@ -832,7 +869,13 @@ type CodeBlockProps = Omit<ComponentPropsWithoutRef<'div'>, 'children'> & {
 };
 declare function CodeBlock({ children, language, copyText, className, ...props }: CodeBlockProps): react.JSX.Element;
 
-type CourseCardProps = Omit<CardShellProps, 'children' | 'title'> & {
+/**
+ * `media` is left out of the shell's props because `<a>` already has an
+ * attribute by that name — a media query for the linked resource, a string —
+ * and intersected with the slot it would make the slot accept only strings.
+ * No browser acts on it and no project was passing it.
+ */
+type CourseCardProps = Omit<CardShellProps, 'children' | 'title' | 'media'> & {
     title: ReactNode;
     summary?: ReactNode;
     /** Level, duration, number of lessons: whatever the project wants to list. */
@@ -844,8 +887,42 @@ type CourseCardProps = Omit<CardShellProps, 'children' | 'title'> & {
      * when passed, the bar goes in sand, which is the color of course progress.
      */
     progress?: number | undefined;
+    /**
+     * The cover, at the top and bleeding to the card's edges, with `alt=""`: the
+     * whole card is one link and `title` already names it.
+     *
+     * The project owns the element — an `<img>`, a framework's `Image`, a
+     * generated cover — and its ratio; the card clips it to its own corners. An
+     * `alt` that repeats the title makes a screen reader say the course twice
+     * before anything else.
+     */
+    media?: ReactNode;
+    /**
+     * The closing row, under `meta`: the rating, the price, whatever the project
+     * sells the course with. It sits at the bottom of the card, so the rows of a
+     * grid line up whatever the length of each summary.
+     */
+    footer?: ReactNode;
 };
-declare function CourseCard({ title, summary, meta, status, progress, className, ...props }: CourseCardProps): react.JSX.Element;
+/**
+ * The course, as a card that links to it.
+ *
+ * `media` and `footer` are slots rather than props for a cover URL, a rating
+ * and a price, because none of those three is the identity's. The price comes
+ * formatted in a currency the library does not know, the rating is drawn by a
+ * component the project already has, and the cover is an image pipeline. What
+ * IS the identity's stays here: the title's scale and its hover, the sand bar,
+ * the status badge. See `docs/decisions/0.11.md` § 59.
+ *
+ * The title does NOT go over the cover. It stays in the body at `h3`, with the
+ * hover every other card has. Text on a photograph needs a scrim, and a scrim's
+ * contrast depends on the photograph: it cannot be measured once and recorded,
+ * which is the only way contrast is decided in this system.
+ *
+ * And the cover does not move on hover. Rule 6 is the border and nothing else:
+ * no zoom, no scale, no displacement.
+ */
+declare function CourseCard({ title, summary, meta, status, progress, media, footer, className, ...props }: CourseCardProps): react.JSX.Element;
 
 /**
  * The mascot's most important rule, finally as code.
@@ -982,8 +1059,10 @@ type SocialLink = {
     label: string;
     href: string;
     /**
-     * The glyph, at 19px. Brands are SOLID (`fill`) and functional icons use a 1.6
-     * stroke. Never an emoji.
+     * The glyph, at 19px. It is the PROJECT's — the library ships no catalogue of
+     * social marks since 0.10.0 — and the drawing rule it should follow is the
+     * system's: a brand is SOLID, so `<Icon as={GithubLogo} tone="current" />`,
+     * and a functional mark keeps the default `action`. Never an emoji.
      */
     icon: ReactNode;
 };
@@ -1353,6 +1432,15 @@ declare function NewsletterForm({ title, description, state, onSubmitEmail, succ
  *
  * `display` for covers, `page` for section headers.
  *
+ * The size picks the title's scale by default, and `titleVariant` lets the
+ * screen pick another one. The default is the document's — «h1 44/700» on the
+ * six interior pages of the reading site — and it is right there. It is not
+ * right in the two admin apps: `blog-content-manager` titles its twelve screens
+ * at 24px, and `cursos` titles 29 of its 32 at `h3` — every one in the panel —
+ * and the other three, the public catalog pages, at `h2`. Both are rungs the
+ * scale already has, and a third `size` could only have named one of them. See
+ * `docs/decisions/0.11.md` § 57.
+ *
  * It takes no mascot face, at either scale: faces go in empty states,
  * confirmations, errors, course progress and celebration.
  *
@@ -1377,8 +1465,21 @@ type PageHeaderProps = Omit<ComponentPropsWithoutRef<'header'>, 'title'> & Varia
     action?: ReactNode | undefined;
     /** The headline's level. `h1` unless the page already has one. */
     as?: 'h1' | 'h2' | undefined;
+    /**
+     * The headline's scale, when the screen needs a different one from what
+     * `size` gives — `display` for `display`, `h1` for `page`.
+     *
+     * It is the same split `Text` makes: `as` is the level, this is how big it
+     * looks. A panel's `<h1>` at `h3` is still the page's only `h1`. The padding
+     * stays with `size`, so a header inside a layout that already spaces its
+     * content passes `className="py-0"`.
+     *
+     * Only the four headline scales, all in the display family. `stat` is for
+     * numbers and `body` is not a headline.
+     */
+    titleVariant?: 'display' | 'h1' | 'h2' | 'h3' | undefined;
 };
-declare function PageHeader({ title, eyebrow, description, action, size, as, className, ...props }: PageHeaderProps): react.JSX.Element;
+declare function PageHeader({ title, eyebrow, description, action, size, as, titleVariant, className, ...props }: PageHeaderProps): react.JSX.Element;
 
 /**
  * How much you have read. It is NOT `Progress` under another name.