@supertype.ai/foundations 0.1.36 → 0.1.37

package/README.md

@@ -74,7 +74,7 @@ untagged git dependency resolves to a different commit on a fresh install.
 
 ```jsonc
 // package.json
-"@supertype.ai/foundations": "https://github.com/supertypeai/foundations.git#v0.1.36"
+"@supertype.ai/foundations": "https://github.com/supertypeai/foundations.git#v0.1.37"
 ```
 
 </details>

package/dist/optical.d.ts

@@ -0,0 +1,73 @@
+/**
+ * How far a centred mark misses the letters, per rung of a type ramp.
+ *
+ * `items-center` centres boxes, and the box is the line box: leading, ascent and
+ * descent, only some of which the letters use. The mark beside a label therefore
+ * centres on the font's box rather than on the band of ink a reader sees, and
+ * whether those two agree is a property of the font, not of the design.
+ *
+ * The whole tool is one line of arithmetic, and the rounding is the reason it is
+ * worth shipping. Ratios alone give one constant tilt for a face, 0.0235em for
+ * Ubuntu Sans, which reads as every rung being equally out. Browsers quantise
+ * ascent, descent and cap height to whole pixels before they lay a line out, and
+ * rounded, that same face is half a pixel out at 11px, flat at 13px and half a
+ * pixel out again at 22px. The rendered pages agree, so the rounding is what
+ * separates a rung that needs the trim from one where it buys nothing.
+ *
+ * Build-time only, and only as good as the metrics handed to it. Verify cap
+ * height against the browser rather than a table: `next/font` ships 693 for
+ * Ubuntu Sans where canvas measures 727, and the wrong one flips the answer at
+ * every rung.
+ */
+/** A font's vertical metrics, in font units. The four numbers every metrics
+ *  table carries, `next/font`'s and capsize's alike. */
+export interface FontMetrics {
+    unitsPerEm: number;
+    ascent: number;
+    descent: number;
+    capHeight: number;
+}
+/** One step of a ramp: the name an app knows it by, and its size in px. */
+export interface TypeRung {
+    name: string;
+    fontSize: number;
+}
+export interface OpticalOffset extends TypeRung {
+    /** How far below the cap band's centre a centred mark sits, in px. Positive is
+     *  low, which is the direction rounding takes it. */
+    offset: number;
+    /** The same miss against the height of the letters it misses. Half a pixel is
+     *  a twelfth of an 11px cap band and a thirty-second of a 36px one, so this is
+     *  the number that says whether a reader sees it. */
+    share: number;
+    /** The rounded metrics the offset came out of, for a message worth reading. */
+    used: {
+        ascent: number;
+        descent: number;
+        capHeight: number;
+    };
+}
+/**
+ * The gap between the line box's centre and the cap band's, at one size.
+ *
+ * Half-leading cancels, so line height does not appear: a rung that is out stays
+ * out however loosely it is set, and no retune of the ramp's leading fixes it.
+ * Paint rounds the baseline a second time, in the same direction, so treat this
+ * as the floor of the error rather than the whole of it.
+ */
+export declare function capBandOffset(metrics: FontMetrics, fontSize: number): number;
+/**
+ * Every rung whose centred mark misses the letters by enough to see, worst first.
+ *
+ * A rung that comes back is one where an icon, a badge or a swatch set beside the
+ * text with `items-center` wants `CAP_TRIM` on the text to land on it. Most rungs
+ * of a ramp are half a pixel out, so the pixel is not the question: `tolerance` is
+ * a share of the cap band, and 0.05 is where a miss stops reading as a rounding
+ * artefact and starts reading as two things that do not line up. Raise it for a
+ * surface that only sets headlines, lower it to see the whole ramp.
+ */
+export declare function checkOptical(metrics: FontMetrics, rungs: readonly TypeRung[], { tolerance }?: {
+    tolerance?: number;
+}): OpticalOffset[];
+/** The failures as lines, on the model of `formatFailures` in contrast.ts. */
+export declare function formatOffsets(offsets: readonly OpticalOffset[]): string;

package/dist/optical.js

@@ -0,0 +1,68 @@
+/**
+ * How far a centred mark misses the letters, per rung of a type ramp.
+ *
+ * `items-center` centres boxes, and the box is the line box: leading, ascent and
+ * descent, only some of which the letters use. The mark beside a label therefore
+ * centres on the font's box rather than on the band of ink a reader sees, and
+ * whether those two agree is a property of the font, not of the design.
+ *
+ * The whole tool is one line of arithmetic, and the rounding is the reason it is
+ * worth shipping. Ratios alone give one constant tilt for a face, 0.0235em for
+ * Ubuntu Sans, which reads as every rung being equally out. Browsers quantise
+ * ascent, descent and cap height to whole pixels before they lay a line out, and
+ * rounded, that same face is half a pixel out at 11px, flat at 13px and half a
+ * pixel out again at 22px. The rendered pages agree, so the rounding is what
+ * separates a rung that needs the trim from one where it buys nothing.
+ *
+ * Build-time only, and only as good as the metrics handed to it. Verify cap
+ * height against the browser rather than a table: `next/font` ships 693 for
+ * Ubuntu Sans where canvas measures 727, and the wrong one flips the answer at
+ * every rung.
+ */
+const px = (value, fontSize, unitsPerEm) => Math.round((value * fontSize) / unitsPerEm);
+/**
+ * The gap between the line box's centre and the cap band's, at one size.
+ *
+ * Half-leading cancels, so line height does not appear: a rung that is out stays
+ * out however loosely it is set, and no retune of the ramp's leading fixes it.
+ * Paint rounds the baseline a second time, in the same direction, so treat this
+ * as the floor of the error rather than the whole of it.
+ */
+export function capBandOffset(metrics, fontSize) {
+    const ascent = px(metrics.ascent, fontSize, metrics.unitsPerEm);
+    const descent = px(metrics.descent, fontSize, metrics.unitsPerEm);
+    const capHeight = px(metrics.capHeight, fontSize, metrics.unitsPerEm);
+    return capHeight / 2 - (ascent - descent) / 2;
+}
+/**
+ * Every rung whose centred mark misses the letters by enough to see, worst first.
+ *
+ * A rung that comes back is one where an icon, a badge or a swatch set beside the
+ * text with `items-center` wants `CAP_TRIM` on the text to land on it. Most rungs
+ * of a ramp are half a pixel out, so the pixel is not the question: `tolerance` is
+ * a share of the cap band, and 0.05 is where a miss stops reading as a rounding
+ * artefact and starts reading as two things that do not line up. Raise it for a
+ * surface that only sets headlines, lower it to see the whole ramp.
+ */
+export function checkOptical(metrics, rungs, { tolerance = 0.05 } = {}) {
+    return rungs
+        .map((rung) => {
+        const used = {
+            ascent: px(metrics.ascent, rung.fontSize, metrics.unitsPerEm),
+            descent: px(metrics.descent, rung.fontSize, metrics.unitsPerEm),
+            capHeight: px(metrics.capHeight, rung.fontSize, metrics.unitsPerEm),
+        };
+        const offset = used.capHeight / 2 - (used.ascent - used.descent) / 2;
+        return { ...rung, offset, share: Math.abs(offset) / used.capHeight, used };
+    })
+        .filter((rung) => rung.share > tolerance)
+        .sort((a, b) => b.share - a.share);
+}
+/** The failures as lines, on the model of `formatFailures` in contrast.ts. */
+export function formatOffsets(offsets) {
+    return offsets
+        .map(({ name, fontSize, offset, used }) => `  ${name} (${fontSize}px)  mark sits ${Math.abs(offset)}px ${offset > 0 ? "below" : "above"} the cap band` +
+        `, ${Math.round((Math.abs(offset) / used.capHeight) * 100)}% of it` +
+        `  [ascent ${used.ascent}, descent ${used.descent}, cap ${used.capHeight}]`)
+        .join("\n");
+}

package/dist/typography/index.d.ts

@@ -2,3 +2,4 @@ export type { TypographyTag } from "./as.js";
 export * from "./header.js";
 export * from "./paragraph.js";
 export * from "./highlight.js";
+export * from "./trim.js";

package/dist/typography/index.js

@@ -1,3 +1,4 @@
 export * from "./header.js";
 export * from "./paragraph.js";
 export * from "./highlight.js";
+export * from "./trim.js";

package/dist/typography/trim.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The optical box: cap top to baseline, with the leading either side removed.
+ *
+ * A line box reserves room for the ascenders and descenders a string may not
+ * use, so `items-center` beside an icon centres that reservation rather than
+ * the letters. On an 11px uppercase label the mark next to it renders about a
+ * pixel low, which is a whole device pixel against an eight pixel cap band.
+ * Trimming makes the element as tall as its own ink, so the row centres what
+ * the reader actually sees.
+ *
+ * Two things follow. It goes on the text element, since `text-box` is not
+ * inherited and a row cannot hand it down. And it shortens that element, so a
+ * row of trimmed text needs a height floor of its own: without one, the card
+ * whose label carries no mark sits shorter than the three beside it and its
+ * figure rides high. Chrome and Safari trim, and a browser that does not know
+ * `text-box` keeps the untrimmed box, which is the behaviour of every consumer
+ * today.
+ *
+ * Never on a string that also clips. The bottom edge is the baseline, so
+ * descenders sit outside the box, and `truncate` or any other overflow hidden
+ * cuts the tails off every g and p in it.
+ *
+ * Uppercase is where it pays. A cap band fills half of an 11px line box and the
+ * mark beside it lands a whole device pixel low, where 13px mixed case measures
+ * the same trimmed or not: ascenders reach the top of the line box on their own,
+ * so there is little leading left to take.
+ */
+export declare const CAP_TRIM = "[text-box:trim-both_cap_alphabetic]";

package/dist/typography/trim.js

@@ -0,0 +1,28 @@
+/**
+ * The optical box: cap top to baseline, with the leading either side removed.
+ *
+ * A line box reserves room for the ascenders and descenders a string may not
+ * use, so `items-center` beside an icon centres that reservation rather than
+ * the letters. On an 11px uppercase label the mark next to it renders about a
+ * pixel low, which is a whole device pixel against an eight pixel cap band.
+ * Trimming makes the element as tall as its own ink, so the row centres what
+ * the reader actually sees.
+ *
+ * Two things follow. It goes on the text element, since `text-box` is not
+ * inherited and a row cannot hand it down. And it shortens that element, so a
+ * row of trimmed text needs a height floor of its own: without one, the card
+ * whose label carries no mark sits shorter than the three beside it and its
+ * figure rides high. Chrome and Safari trim, and a browser that does not know
+ * `text-box` keeps the untrimmed box, which is the behaviour of every consumer
+ * today.
+ *
+ * Never on a string that also clips. The bottom edge is the baseline, so
+ * descenders sit outside the box, and `truncate` or any other overflow hidden
+ * cuts the tails off every g and p in it.
+ *
+ * Uppercase is where it pays. A cap band fills half of an 11px line box and the
+ * mark beside it lands a whole device pixel low, where 13px mixed case measures
+ * the same trimmed or not: ascenders reach the top of the line box on their own,
+ * so there is little leading left to take.
+ */
+export const CAP_TRIM = "[text-box:trim-both_cap_alphabetic]";

package/llms.txt

@@ -67,6 +67,7 @@ silently. Full reference: https://github.com/supertypeai/foundations
 | an article whose body is prose or MDX | `EssayHeader` + `ReadingLayout` | `/essay` |
 | a post meta row (date, read time, tags) | `PostMetaRow` and friends | `/essay` |
 | a table of contents | `TableOfContents`, `ReadingRail` | `/essay` |
+| where a centred mark lands on a rung | `checkOptical` | `/optical` |
 | page metadata and JSON-LD | `createSeo` | `/seo` |
 | an OG image | `ogCard`, `OG_SIZE` | `/og` |
 | to merge classnames | `cn` | root |
@@ -75,13 +76,14 @@ silently. Full reference: https://github.com/supertypeai/foundations
 
 | import | exports |
 |---|---|
-| `@supertype.ai/foundations` | `cn`, `TypographyH1`, `TypographyH2`, `TypographyH3`, `TypographyH4`, `TypographyEyebrow`, `TypographyP`, `TypographyMuted`, `TypographyProse`, `TypographyList`, `TypographyProseList`, `TypographyCaption`, `TypographySmall`, `TypographyLabel`, `TypographyStat`, `TypographyInlineCode`, `TypographyLink`, `TypographyHighlight`, `headingClass`, `headingFace`, `eyebrowClass`, `toneClass`, `impliedTone`, `resolveLink`, `isExternalHref`. Types: `TypographyTag`, `ParagraphVariants`, `ListProps`, `CaptionVariants`, `LabelVariants`, `StatVariants`, `Tone`, `HighlightTone`, `LinkBehavior`, `ResolvedLink` |
+| `@supertype.ai/foundations` | `cn`, `TypographyH1`, `TypographyH2`, `TypographyH3`, `TypographyH4`, `TypographyEyebrow`, `TypographyP`, `TypographyMuted`, `TypographyProse`, `TypographyList`, `TypographyProseList`, `TypographyCaption`, `TypographySmall`, `TypographyLabel`, `TypographyStat`, `TypographyInlineCode`, `TypographyLink`, `TypographyHighlight`, `headingClass`, `headingFace`, `eyebrowClass`, `toneClass`, `impliedTone`, `resolveLink`, `isExternalHref`, `CAP_TRIM`. Types: `TypographyTag`, `ParagraphVariants`, `ListProps`, `CaptionVariants`, `LabelVariants`, `StatVariants`, `Tone`, `HighlightTone`, `LinkBehavior`, `ResolvedLink` |
 | `@supertype.ai/foundations/blocks` | `Anchor`, `Cards`, `Card`, `CardHeader`, `CardTitle`, `CardDescription`, `CardContent`, `Callout`, `Button`, `buttonVariants`, `Badge`, `badgeVariants`, `Steps`, `Step`, `Disclosure`, `DisclosureGroup`, `Accordion`, `AccordionItem`, `AccordionTrigger`, `AccordionContent`, `Tabs`, `TabsList`, `TabsTrigger`, `TabsContent`, `TabGroup`, `SEGMENT`, `Bulletin`, `Ribbon`, `EDITORIAL_INKS`, `Colophon`, `BuiltWithFoundations`, `FoundationsMark`, `FOUNDATIONS_URL`. Types: `ButtonLook`, `BadgeLook`, `TabItem`, `BulletinProps`, `BulletinPoint`, `RibbonHue`, `ColophonProps` |
 | `@supertype.ai/foundations/mdx` | `proseMdxComponents` |
 | `@supertype.ai/foundations/essay` | `createEssay`, `EssayHeader`, `EssayLayout`, `EssaySection`, `EssayPullQuote`, `EssayFigure`, `EssayMovements`, `EssayDocument`, `EssayColumns`, `EssayAside`, `EssayBody`, `ReadingLayout`, `TableOfContents`, `ReadingRail`, `ReadingProgressBar`, `Rail`, `RailLink`, `PostMetaRow`, `PostDate`, `ReadTime`, `TagPills`, `MetaDot`, `formatPostDate`, `extractHeadings`, `readingTime`, `createSlugger`, `useReadingProgress`, `useScrollSpy`. Types: `TocHeading`, `EssayDecorations`, `EssayIndexEntry`, `EssayDocSection`, `EssayMovement`, `PostDateFormat` |
 | `@supertype.ai/foundations/seo` | `createSeo`. Types: `SeoConfig`, `ArticleAuthor`, `ArticleOptions`, `PageMetadata` |
 | `@supertype.ai/foundations/og` | `ogCard`, `OG_SIZE`. Types: `OgCardOptions` |
 | `@supertype.ai/foundations/eslint` | `designRules` (every rule as one array, the one to spread), `designConfig` (the same set wrapped as a flat-config entry). The builders `colourRules`, `typographyRules`, `linkRules`, `themeOverrideRules`, `surfaceAsInkRules`, `renamedTokenRules` are exported too, though spreading them by hand is how a consumer ends up missing one. Types: `FlatConfigEntry`, `DesignRuleOptions`, `DesignConfigOptions`, `RestrictedSyntax`, `ColourOptions`, `TypographyOptions` |
+| `@supertype.ai/foundations/optical` | `capBandOffset` (the gap between a line box's centre and its cap band's, at one size), `checkOptical` (every rung of a ramp whose centred mark misses the letters, worst first), `formatOffsets`. Types: `FontMetrics`, `TypeRung`, `OpticalOffset`. Build-time only |
 | `@supertype.ai/foundations/rehype` | `rehypeProseCode`, `proseCodeOptions`, `PROSE_LANGS`, `PROSE_THEMES`. Build-time only, must not resolve React |
 | `@supertype.ai/foundations/contrast` | `checkLegibility` (inks at 4.5:1), `checkSignals` (fills at 3:1 — status hues, the categorical earth hues and the six chart series alike — tinted inks at 4.5:1, `--subtle-foreground` at the 3:1 it is documented for, labels against their own fill: the tone rows are read off `TONE` and each cut is resolved along its `var()` fallback chain, so an app that declares `--brand` without `--brand-foreground` is measured on the label the cascade really reaches for rather than skipped), `checkHairlines` (`--border` and `--input` at 1.4:1 on `--background` and `--card`, `--sidebar-border` on `--sidebar`: a rule is exempt from the ink and mark bars, but it still has to read as the same weight in both themes), `resolveTokens`, `formatFailures`, `specificity`, `parseColor`, `luminance`, `contrast` (WCAG ratio), `lc` (APCA lightness contrast: polarity-aware, for checking that an ink ramp is perceptually ordered rather than merely ordered by ratio), `tokenCuts` (which cuts a token ships: fill, the label printed on it, the hue as words, the taxonomy `checkSignals` measures against). Types: `Rgb`, `Theme`, `LegibilityFailure`, `TokenCuts`. Build-time only |
 
@@ -103,6 +105,16 @@ silently. Full reference: https://github.com/supertypeai/foundations
   trigger. It exists so `target`/`rel` are never written at a call site; `external`
   is for a same-origin path that is not a route, which the router would prefetch.
 - `Tone` is the one semantic colour vocabulary, shared by `Button`, `Badge`, `Callout`, `TypographyLink` and `TabsList`: `"muted" | "primary" | "secondary" | "brand" | "success" | "warn" | "destructive"`, defaulting to `muted` everywhere except a solid `Button`. Seven tones, seven tokens, one to one, which is the bar for adding one. Four names map onto others: `neutral` and `foreground` are `muted`, the word the rest of the package uses; `accent` is `--primary`'s hover tint, so a washed `primary` renders the same thing; `info` is covered by the `success | warn | destructive` triad. `brand` falls back to `--primary` in an app that defines no `--brand`.
+- **`CAP_TRIM` centres a mark on the letters.** `items-center` centres line
+  boxes, and a line box reserves room for ascenders and descenders the string may
+  not use, so an (i) or a badge beside an uppercase micro-label renders about a
+  pixel low. Put `CAP_TRIM` on the text element, never on the row, because
+  `text-box` is not inherited. It shortens the element, so give the row a height
+  floor from whatever sits beside it: a trimmed label with no mark next to it
+  makes a shorter row than its neighbours and the figure under it rides high.
+  Never put it on a string that clips: the box ends at the baseline, so `truncate`
+  cuts the tail off every descender. Which rungs need it is computed rather than
+  eyeballed: `checkOptical` from `/optical` reads a face's metrics and names them.
 - **Ink is handed down by whatever paints.** `toneClass(tone)` is a palette and sets no ink. A surface that fills adds `INK_ON_FILL`; a tinted one adds `INK_ON_CARD`, `INK_ON_POPOVER` or `INK_ON_SIDEBAR`, and one the package does not name spreads `inkOnSurfaceStyle(token)` into `style` rather than building a class. Both declare `--ink` and `--ink-muted`, which every type primitive reads, falling back to the page. Paint a background without them and a nested `TypographyLabel` prints `--foreground` on your fill, which measures 2.34:1 on `--primary`. On a hue fill `--ink-muted` equals `--ink`: a filled control has one ink, and wanting a second rung means wanting a tinted surface.
 - `Button`: `variant?: "solid" | "soft" | "outline" | "ghost" | "link"` (default `solid`), `tone?: Tone` (defaults to `primary` on a solid button and `muted` on every other variant — filling a button in is how a page says this is the action), `size?: "xs" | "sm" | "md" | "lg" | "xl"` (default `md`), `icon?: boolean` for a square glyph box, `pill?: boolean` for full-round corners, `href` to make it a link, `render` for an element that is neither a button nor a link. Variant is how much ink it spends and tone is what the ink means, on separate axes, so a quiet delete is `variant="ghost" tone="destructive"`.
 - `Badge`: `variant?: "solid" | "soft" | "outline" | "ghost"` (default `solid`), `tone?: Tone`, `size?: "xs" | "sm"` (default `sm`), `pill?: boolean`, `href` for a badge that leads somewhere. Same axes and same spellings as `Button`, minus `link`, which belongs to things you click. `warning` and `supertype` were `tone="warn"` and `tone="brand"` under invented names.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supertype.ai/foundations",
-  "version": "0.1.36",
+  "version": "0.1.37",
   "license": "MIT",
   "publishConfig": {
     "access": "public",
@@ -68,6 +68,10 @@
       "require": "./dist/cjs/eslint.js",
       "default": "./dist/eslint.js"
     },
+    "./optical": {
+      "types": "./dist/optical.d.ts",
+      "default": "./dist/optical.js"
+    },
     "./rehype": {
       "types": "./dist/rehype.d.ts",
       "default": "./dist/rehype.js"