@godxjp/ui 18.4.0 → 18.5.0

package/dist/components/navigation/tabs-scroll.d.ts

@@ -0,0 +1,70 @@
+import * as React from "react";
+/**
+ * Keep-the-active-tab-visible logic for the horizontal `TabsList` scroll strip (gh#204).
+ *
+ * `TabsList` scrolls its own overflow (gh#175) so long localized labels never clip. That fixed
+ * clipping but not the SCROLL POSITION: after a responsive resize / route re-render the strip kept
+ * (or shifted) its internal `scrollLeft`, so the ACTIVE trigger — typically the FIRST one — could
+ * end up completely outside the scrollport while still carrying `data-state="active"` /
+ * `aria-selected="true"`. A tab you cannot see is a tab you cannot use.
+ *
+ * The fix observes the strip (size changes) and its triggers (`data-state` changes) and scrolls the
+ * element that must stay reachable back into view. Deliberate constraints:
+ *
+ *  - **Never fights the user.** The scroll only runs when the target is NOT already fully inside the
+ *    scrollport, so an intentional manual/touch scroll that leaves the active tab visible is left
+ *    alone, and a click (target is under the pointer) or arrow-key move (the browser already
+ *    scrolled focus into view) is a no-op.
+ *  - **Focus wins over selection.** With `activationMode="manual"` the roving focus can sit on a
+ *    trigger that is not the selected one; yanking the strip to the selected tab would strand the
+ *    keyboard user. The focused trigger inside the list is therefore the preferred target.
+ *  - **Reduced motion.** `prefers-reduced-motion: reduce` downgrades every correction to an instant
+ *    jump; resize corrections are instant regardless (a smooth animation mid-resize reads as jank).
+ *  - **RTL / vertical safe.** All geometry is physical viewport rects and the scroll uses
+ *    `scrollIntoView({ block: "nearest", inline: "nearest" })`, which resolves direction natively —
+ *    so a first trigger in `dir="rtl"` (visually on the right) and a vertical rail both work
+ *    without direction branches. `nearest` also means no ancestor/page scroll when the strip is
+ *    already where it should be.
+ */
+/** Minimal rect shape — only the edges the visibility test needs. */
+export type TabsScrollBox = {
+    left: number;
+    right: number;
+    top: number;
+    bottom: number;
+};
+/**
+ * True when `trigger` sits entirely inside the `scrollport` box. Pure geometry — physical viewport
+ * coordinates, so it is direction- and orientation-agnostic (LTR, RTL, vertical rail alike).
+ *
+ * A zero-area scrollport (unmounted, `display:none`, or an environment without layout such as
+ * jsdom) reports `true`: there is no measurable overflow to correct, and scrolling a hidden strip
+ * would be meaningless.
+ */
+export declare function isTabFullyVisible(scrollport: TabsScrollBox, trigger: TabsScrollBox): boolean;
+/**
+ * The trigger the strip must keep reachable: the focused trigger when the roving focus is inside
+ * this list (manual activation can park focus off the selected tab), otherwise the active one.
+ */
+export declare function resolveTabScrollTarget(list: HTMLElement): HTMLElement | null;
+/** `true` when the user has asked for reduced motion (falsy/unsupported environments say no). */
+export declare function prefersReducedMotion(): boolean;
+/**
+ * Scrolls the list's keep-visible target back into the scrollport when — and only when — it is not
+ * already fully inside it. Returns the element it scrolled, or `null` when nothing needed doing
+ * (which is the common case, and what keeps this from fighting a deliberate user scroll).
+ */
+export declare function syncActiveTabIntoView(list: HTMLElement | null, behavior?: ScrollBehavior): HTMLElement | null;
+/**
+ * Wires the two signals that can strand the active tab off-screen:
+ *
+ *  - a `ResizeObserver` on the strip — a responsive width change (1440 → 1024 → 390) keeps/shifts
+ *    the old `scrollLeft`; the observer's initial delivery also covers first mount at a new width;
+ *  - a `MutationObserver` on descendant `data-state` — the selected tab changing from outside the
+ *    strip (router/URL state, a controlled parent) must bring the newly-selected trigger into view.
+ *
+ * Resize corrections are instant; a selection change animates unless reduced motion is requested.
+ * Both observers are optional: without them (SSR, ancient runtimes) the component degrades to the
+ * pre-fix behaviour instead of throwing.
+ */
+export declare function useKeepActiveTabVisible(listRef: React.RefObject<HTMLElement | null>): void;

package/dist/components/navigation/tabs-scroll.js

@@ -0,0 +1,76 @@
+"use client";
+import * as React from "react";
+const VISIBILITY_EPSILON = 1;
+function isTabFullyVisible(scrollport, trigger) {
+  const width = scrollport.right - scrollport.left;
+  const height = scrollport.bottom - scrollport.top;
+  if (width <= 0 && height <= 0) return true;
+  return trigger.left >= scrollport.left - VISIBILITY_EPSILON && trigger.right <= scrollport.right + VISIBILITY_EPSILON && trigger.top >= scrollport.top - VISIBILITY_EPSILON && trigger.bottom <= scrollport.bottom + VISIBILITY_EPSILON;
+}
+function resolveTabScrollTarget(list) {
+  const focused = list.ownerDocument?.activeElement;
+  if (focused instanceof HTMLElement && focused !== list && list.contains(focused) && focused.getAttribute("role") === "tab") {
+    return focused;
+  }
+  return list.querySelector('[role="tab"][data-state="active"]');
+}
+function prefersReducedMotion() {
+  if (typeof window === "undefined" || typeof window.matchMedia !== "function") return false;
+  try {
+    return window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+  } catch {
+    return false;
+  }
+}
+function syncActiveTabIntoView(list, behavior = "auto") {
+  if (!list) return null;
+  const target = resolveTabScrollTarget(list);
+  if (!target || typeof target.scrollIntoView !== "function") return null;
+  if (isTabFullyVisible(list.getBoundingClientRect(), target.getBoundingClientRect())) return null;
+  target.scrollIntoView({
+    block: "nearest",
+    inline: "nearest",
+    behavior: prefersReducedMotion() ? "auto" : behavior
+  });
+  return target;
+}
+function useKeepActiveTabVisible(listRef) {
+  React.useEffect(() => {
+    const list = listRef.current;
+    if (!list) return void 0;
+    syncActiveTabIntoView(list, "auto");
+    const cleanups = [];
+    if (typeof ResizeObserver !== "undefined") {
+      const resizeObserver = new ResizeObserver(() => {
+        syncActiveTabIntoView(list, "auto");
+      });
+      resizeObserver.observe(list);
+      cleanups.push(() => {
+        resizeObserver.disconnect();
+      });
+    }
+    if (typeof MutationObserver !== "undefined") {
+      const mutationObserver = new MutationObserver(() => {
+        syncActiveTabIntoView(list, "smooth");
+      });
+      mutationObserver.observe(list, {
+        subtree: true,
+        attributes: true,
+        attributeFilter: ["data-state"]
+      });
+      cleanups.push(() => {
+        mutationObserver.disconnect();
+      });
+    }
+    return () => {
+      for (const cleanup of cleanups) cleanup();
+    };
+  }, [listRef]);
+}
+export {
+  isTabFullyVisible,
+  prefersReducedMotion,
+  resolveTabScrollTarget,
+  syncActiveTabIntoView,
+  useKeepActiveTabVisible
+};

package/dist/components/navigation/tabs.js

@@ -3,6 +3,7 @@ import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 import * as React from "react";
 import * as TabsPrimitive from "@radix-ui/react-tabs";
 import { cn } from "../../lib/utils.js";
+import { useKeepActiveTabVisible } from "./tabs-scroll.js";
 function resolveFallbackTabValue(items, requested) {
   if (!items || items.length === 0) return requested;
   if (requested !== void 0) {
@@ -75,26 +76,40 @@ function Tabs({
     }
   );
 }
-const TabsList = React.forwardRef(({ className, variant = "default", ...props }, ref) => /* @__PURE__ */ jsx(
-  TabsPrimitive.List,
-  {
-    ref,
-    "data-slot": "tabs-list",
-    "data-variant": variant,
-    className: cn(
-      // `min-w-0 max-w-full` let the list shrink to (and never exceed) whatever width its
-      // ancestors actually give it instead of forcing them wider; horizontal orientation then
-      // scrolls its own overflow rather than clipping/hiding long localized labels in a narrow
-      // container (gh#175). Hidden scrollbar keeps the strip visually clean while staying
-      // swipeable on touch and reachable via keyboard (arrow-key roving focus still scrolls the
-      // newly-focused trigger into view natively). Vertical orientation is untouched — it already
-      // stacks in a column and is sized by its own `h-*`/`w-*` overrides.
-      "group/tabs-list text-muted-foreground data-[variant=default]:bg-muted inline-flex w-fit max-w-full min-w-0 items-center justify-center rounded-lg p-1 group-data-[orientation=vertical]/tabs:flex-col data-[orientation=horizontal]:[scrollbar-width:none] data-[orientation=horizontal]:overflow-x-auto data-[orientation=horizontal]:overflow-y-hidden data-[variant=line]:gap-1 data-[variant=line]:rounded-none data-[variant=line]:bg-transparent [&[data-orientation=horizontal]::-webkit-scrollbar]:hidden",
-      className
-    ),
-    ...props
-  }
-));
+const TabsList = React.forwardRef(({ className, variant = "default", ...props }, ref) => {
+  const listRef = React.useRef(null);
+  const setListRef = React.useCallback(
+    (node) => {
+      listRef.current = node;
+      if (typeof ref === "function") ref(node);
+      else if (ref) ref.current = node;
+    },
+    [ref]
+  );
+  useKeepActiveTabVisible(listRef);
+  return /* @__PURE__ */ jsx(
+    TabsPrimitive.List,
+    {
+      ref: setListRef,
+      "data-slot": "tabs-list",
+      "data-variant": variant,
+      className: cn(
+        // `min-w-0 max-w-full` let the list shrink to (and never exceed) whatever width its
+        // ancestors actually give it instead of forcing them wider; horizontal orientation then
+        // scrolls its own overflow rather than clipping/hiding long localized labels in a narrow
+        // container (gh#175). Hidden scrollbar keeps the strip visually clean while staying
+        // swipeable on touch and reachable via keyboard (arrow-key roving focus still scrolls the
+        // newly-focused trigger into view natively); `useKeepActiveTabVisible` above re-pins the
+        // active trigger when a resize would otherwise strand it off-strip (gh#204). Vertical
+        // orientation is untouched — it already stacks in a column and is sized by its own
+        // `h-*`/`w-*` overrides.
+        "group/tabs-list text-muted-foreground data-[variant=default]:bg-muted inline-flex w-fit max-w-full min-w-0 items-center justify-center rounded-lg p-1 group-data-[orientation=vertical]/tabs:flex-col data-[orientation=horizontal]:[scrollbar-width:none] data-[orientation=horizontal]:overflow-x-auto data-[orientation=horizontal]:overflow-y-hidden data-[variant=line]:gap-1 data-[variant=line]:rounded-none data-[variant=line]:bg-transparent [&[data-orientation=horizontal]::-webkit-scrollbar]:hidden",
+        className
+      ),
+      ...props
+    }
+  );
+});
 TabsList.displayName = TabsPrimitive.List.displayName;
 const TabsTrigger = React.forwardRef(({ className, ...props }, ref) => /* @__PURE__ */ jsx(
   TabsPrimitive.Trigger,

package/dist/email/brand-mark.d.ts

@@ -0,0 +1,92 @@
+/**
+ * The canonical GoDX brand mark, as email-safe markup.
+ *
+ * The mark is an emerald CAPSULE with an internal light GLYPH bar — the same artwork the React
+ * `<Logo mark="godx" />` paints, at the same 32×32 viewBox and the same coordinates (a test asserts
+ * the capsule path is byte-identical to the component's, so the two can never diverge). A capsule
+ * WITHOUT the internal glyph is the incomplete mark and must not ship.
+ *
+ * Nothing here references an external or relative asset: an email template has no base URL it can
+ * trust, remote images are blocked by default in most clients, and a `cid:` attachment needs
+ * transport support. So the mark is delivered three ways, in order of fidelity:
+ *
+ *  1. `svg` — inline `<svg>`. Apple Mail, iOS Mail, Thunderbird, Samsung Mail. Best fidelity.
+ *  2. `dataUri` — the same SVG as a `data:` URL for `<img src>`. No network fetch.
+ *  3. `tableHtml` — bulletproof `<table>`/`<div>` markup with background-color + border-radius.
+ *     Renders everywhere; degrades to a square emerald block with a light bar in Outlook's Word
+ *     renderer (which drops `border-radius`) — still recognisably the mark, never a broken image.
+ *
+ * Colours come from `EMAIL_COLORS` (derived from `--success` / `--success-foreground`, the roles
+ * `--logo-godx-color` already points at), so a re-themed identity role re-tints the mark.
+ */
+import { type EmailHex } from "./color.js";
+/** A rounded rectangle in the mark's 32×32 coordinate space. */
+export interface EmailBrandMarkRect {
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+    readonly radius: number;
+}
+/** Intrinsic coordinate space of the mark artwork. */
+export declare const EMAIL_BRAND_MARK_VIEWBOX = "0 0 32 32";
+/** The emerald capsule. */
+export declare const EMAIL_BRAND_MARK_CAPSULE: EmailBrandMarkRect;
+/** The internal light glyph bar inside the capsule. */
+export declare const EMAIL_BRAND_MARK_GLYPH: EmailBrandMarkRect;
+/**
+ * Path data for a rounded rectangle, in the exact serialisation the canonical mark uses — so the
+ * generated capsule string equals the artwork shipped by `<Logo mark="godx" />` character for
+ * character.
+ */
+export declare function roundedRectPath({ x, y, width, height, radius }: EmailBrandMarkRect): string;
+/** Options for rendering the mark. Every default comes from the token contract. */
+export interface EmailBrandMarkOptions {
+    /** Rendered width in px. Default `EMAIL_BRAND_MARK.widthPx` (32). */
+    width?: number;
+    /** Rendered height in px. Default `EMAIL_BRAND_MARK.heightPx` (32). */
+    height?: number;
+    /** Capsule fill. Default `EMAIL_COLORS.brand`. */
+    color?: EmailHex;
+    /** Internal glyph fill. Default `EMAIL_COLORS.brandForeground`. */
+    glyphColor?: EmailHex;
+    /**
+     * Accessible name. Pass `""` for a decorative mark that sits next to a readable wordmark — the
+     * markup then carries `alt=""` / `aria-hidden` instead of a redundant announcement.
+     */
+    label?: string;
+}
+/**
+ * Inline `<svg>` markup for the mark — self-contained, no external or relative asset reference.
+ * The `xmlns` attribute is required: an email body is not always parsed as HTML5.
+ */
+export declare function emailBrandMarkSvg(o?: EmailBrandMarkOptions): string;
+/**
+ * The mark as a `data:image/svg+xml` URL for `<img src>`. Percent-encoded (not base64) so it stays
+ * readable in a template and needs no `Buffer`/`btoa`. Still zero network requests.
+ */
+export declare function emailBrandMarkDataUri(o?: EmailBrandMarkOptions): string;
+/**
+ * Bulletproof `<table>` markup for clients with no SVG support. Uses only `background-color`,
+ * `border-radius`, fixed cell sizes and `font-size:0` — the intersection every client renders.
+ */
+export declare function emailBrandMarkTableHtml(o?: EmailBrandMarkOptions): string;
+/** The canonical mark at its default size and colours, in all three delivery forms. */
+export interface EmailBrandMark {
+    readonly viewBox: string;
+    readonly width: string;
+    readonly widthPx: number;
+    readonly height: string;
+    readonly heightPx: number;
+    readonly capsule: EmailBrandMarkRect;
+    readonly glyph: EmailBrandMarkRect;
+    readonly capsulePath: string;
+    readonly glyphPath: string;
+    /** Inline `<svg>` — highest fidelity. */
+    readonly svg: string;
+    /** `data:` URL of the same SVG, for `<img src>`. */
+    readonly dataUri: string;
+    /** `<table>` fallback for clients with no SVG support. */
+    readonly tableHtml: string;
+}
+export declare const EMAIL_BRAND_MARK: EmailBrandMark;

package/dist/email/brand-mark.js

@@ -0,0 +1,83 @@
+import { EMAIL_COLORS } from "./color.js";
+import { EMAIL_GEOMETRY_SOURCE } from "./tokens.generated.js";
+const EMAIL_BRAND_MARK_VIEWBOX = "0 0 32 32";
+const EMAIL_BRAND_MARK_CAPSULE = Object.freeze({
+  x: 1,
+  y: 7,
+  width: 30,
+  height: 18,
+  radius: 7
+});
+const EMAIL_BRAND_MARK_GLYPH = Object.freeze({
+  x: 7,
+  y: 13,
+  width: 18,
+  height: 6,
+  radius: 1
+});
+const sep = (value) => value < 0 ? String(value) : ` ${value}`;
+const arc = (r, dx, dy) => `a${r} ${r} 0 0 1${sep(dx)}${sep(dy)}`;
+function roundedRectPath({ x, y, width, height, radius }) {
+  const h = width - 2 * radius;
+  const v = height - 2 * radius;
+  return `M${x + radius} ${y}h${h}${arc(radius, radius, radius)}v${v}${arc(radius, -radius, radius)}H${x + radius}${arc(radius, -radius, -radius)}v-${v}${arc(radius, radius, -radius)}Z`;
+}
+const CAPSULE_PATH = roundedRectPath(EMAIL_BRAND_MARK_CAPSULE);
+const GLYPH_PATH = roundedRectPath(EMAIL_BRAND_MARK_GLYPH);
+const DEFAULT_WIDTH = Number.parseFloat(EMAIL_GEOMETRY_SOURCE["--email-mark-width"]);
+const DEFAULT_HEIGHT = Number.parseFloat(EMAIL_GEOMETRY_SOURCE["--email-mark-height"]);
+function options(o = {}) {
+  return {
+    width: o.width ?? DEFAULT_WIDTH,
+    height: o.height ?? DEFAULT_HEIGHT,
+    color: o.color ?? EMAIL_COLORS.brand,
+    glyphColor: o.glyphColor ?? EMAIL_COLORS.brandForeground,
+    label: o.label ?? "GoDX"
+  };
+}
+const attr = (value) => value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+function emailBrandMarkSvg(o = {}) {
+  const { width, height, color, glyphColor, label } = options(o);
+  const a11y = label ? ` role="img" aria-label="${attr(label)}"` : ` role="presentation" aria-hidden="true"`;
+  return `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}" viewBox="${EMAIL_BRAND_MARK_VIEWBOX}" focusable="false"${a11y} style="display:block;border:0;outline:none;text-decoration:none"><path fill="${color}" d="${CAPSULE_PATH}"/><path fill="${glyphColor}" d="${GLYPH_PATH}"/></svg>`;
+}
+function emailBrandMarkDataUri(o = {}) {
+  return `data:image/svg+xml;charset=utf-8,${encodeURIComponent(emailBrandMarkSvg(o))}`;
+}
+function emailBrandMarkTableHtml(o = {}) {
+  const { width, height, color, glyphColor, label } = options(o);
+  const scale = width / 32;
+  const box = (rect) => ({
+    width: Math.round(rect.width * scale),
+    height: Math.round(rect.height * scale * height / width),
+    radius: Math.round(rect.radius * scale)
+  });
+  const capsule = box(EMAIL_BRAND_MARK_CAPSULE);
+  const glyph = box(EMAIL_BRAND_MARK_GLYPH);
+  const a11y = label ? ` role="img" aria-label="${attr(label)}"` : ` role="presentation" aria-hidden="true"`;
+  return `<table${a11y} border="0" cellpadding="0" cellspacing="0" width="${capsule.width}" style="border-collapse:separate;border-spacing:0;width:${capsule.width}px"><tr><td width="${capsule.width}" height="${capsule.height}" align="center" valign="middle" style="width:${capsule.width}px;height:${capsule.height}px;line-height:${capsule.height}px;font-size:0;mso-line-height-rule:exactly;background-color:${color};border-radius:${capsule.radius}px"><div style="width:${glyph.width}px;height:${glyph.height}px;line-height:${glyph.height}px;font-size:0;background-color:${glyphColor};border-radius:${glyph.radius}px">&#8203;</div></td></tr></table>`;
+}
+const EMAIL_BRAND_MARK = Object.freeze({
+  viewBox: EMAIL_BRAND_MARK_VIEWBOX,
+  width: EMAIL_GEOMETRY_SOURCE["--email-mark-width"],
+  widthPx: DEFAULT_WIDTH,
+  height: EMAIL_GEOMETRY_SOURCE["--email-mark-height"],
+  heightPx: DEFAULT_HEIGHT,
+  capsule: EMAIL_BRAND_MARK_CAPSULE,
+  glyph: EMAIL_BRAND_MARK_GLYPH,
+  capsulePath: CAPSULE_PATH,
+  glyphPath: GLYPH_PATH,
+  svg: emailBrandMarkSvg(),
+  dataUri: emailBrandMarkDataUri(),
+  tableHtml: emailBrandMarkTableHtml()
+});
+export {
+  EMAIL_BRAND_MARK,
+  EMAIL_BRAND_MARK_CAPSULE,
+  EMAIL_BRAND_MARK_GLYPH,
+  EMAIL_BRAND_MARK_VIEWBOX,
+  emailBrandMarkDataUri,
+  emailBrandMarkSvg,
+  emailBrandMarkTableHtml,
+  roundedRectPath
+};

package/dist/email/color.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Email colour contract — semantic web roles resolved to LITERAL hex.
+ *
+ * HTML email has no cascade worth trusting: Gmail strips <style>, Outlook ignores custom
+ * properties, and every colour must appear inline as `#rrggbb` on the element that paints it. The
+ * web tokens, meanwhile, are HSL channel triplets (`--primary: 204 100% 39%`) so they can be
+ * alpha-composed. This module bridges the two — the triplets are GENERATED from
+ * src/tokens/foundation.css (scripts/gen-email-tokens.mjs) and converted here, at module load, by
+ * the same `hslToHex` a consumer can call on its own brand roles. There is no hex literal in this
+ * directory, so an email palette that drifts from the web palette is structurally impossible.
+ */
+import { EMAIL_COLOR_SOURCE } from "./tokens.generated.js";
+/**
+ * The email palette slots. Each maps 1:1 to a semantic role in `src/tokens/foundation.css`
+ * (`EMAIL_COLOR_SOURCE[token].cssVar` names it), so a re-themed role re-tints the email.
+ */
+export type EmailColorToken = keyof typeof EMAIL_COLOR_SOURCE;
+/** A `#rrggbb` string — the only colour form every email client renders identically. */
+export type EmailHex = `#${string}`;
+/**
+ * Convert a CSS HSL channel triplet (`"204 100% 39%"` — the shape every `@godxjp/ui` colour role
+ * uses) into the `#rrggbb` literal an email client needs. Rounds each channel the way a browser
+ * does, so the hex is exactly what `hsl(var(--role))` paints on the web.
+ *
+ * Consumers with a custom brand role can call this directly:
+ * `hslToHex(getComputedStyle(el).getPropertyValue("--primary"))`.
+ *
+ * @throws if the input is not a bare `H S% L%` triplet (a hex or `hsl(...)` wrapper is rejected
+ * rather than silently mis-parsed).
+ */
+export declare function hslToHex(triplet: string): EmailHex;
+/**
+ * The canonical (light-scheme) transactional-email palette, as literal hex.
+ *
+ * | slot                          | web role                          | used for                          |
+ * | ----------------------------- | --------------------------------- | --------------------------------- |
+ * | `background`                  | `--background`                    | the page wrapper behind the card  |
+ * | `foreground`                  | `--foreground`                    | body copy                         |
+ * | `surface` / `surfaceForeground`| `--card` / `--card-foreground`   | the 480px card                    |
+ * | `muted` / `mutedForeground`   | `--muted` / `--muted-foreground`  | quiet bands, legal copy           |
+ * | `border`                      | `--border`                        | card edge, footer hairline        |
+ * | `primary` / `primaryForeground`| `--primary` / `--primary-foreground` | the one CTA                  |
+ * | `focus`                       | `--ring`                          | focus affordance in webmail panes |
+ * | `brand` / `brandForeground`   | `--success` / `--success-foreground` | the GoDX capsule + its glyph   |
+ */
+export declare const EMAIL_COLORS: Readonly<Record<EmailColorToken, EmailHex>>;
+/**
+ * The dark-scheme palette, derived from the same roles under `.dark` /
+ * `:root[data-theme="dark"]`. Use it inside `@media (prefers-color-scheme: dark)` for the clients
+ * that honour it — never as the only palette, since most clients do not.
+ */
+export declare const EMAIL_COLORS_DARK: Readonly<Record<EmailColorToken, EmailHex>>;

package/dist/email/color.js

@@ -0,0 +1,37 @@
+import { EMAIL_COLOR_SOURCE, EMAIL_COLOR_SOURCE_DARK } from "./tokens.generated.js";
+const TRIPLET = /^\s*(-?\d+(?:\.\d+)?)\s+(\d+(?:\.\d+)?)%\s+(\d+(?:\.\d+)?)%\s*$/;
+const channel = (n) => Math.round(Math.min(255, Math.max(0, n * 255))).toString(16).padStart(2, "0");
+function hslToHex(triplet) {
+  const parsed = TRIPLET.exec(triplet);
+  if (!parsed) {
+    throw new TypeError(
+      `hslToHex expects a bare HSL channel triplet like "204 100% 39%", received "${triplet}".`
+    );
+  }
+  const hue = (Number(parsed[1]) % 360 + 360) % 360 / 60;
+  const saturation = Number(parsed[2]) / 100;
+  const lightness = Number(parsed[3]) / 100;
+  const chroma = (1 - Math.abs(2 * lightness - 1)) * saturation;
+  const second = chroma * (1 - Math.abs(hue % 2 - 1));
+  const base = lightness - chroma / 2;
+  const [r, g, b] = hue < 1 ? [chroma, second, 0] : hue < 2 ? [second, chroma, 0] : hue < 3 ? [0, chroma, second] : hue < 4 ? [0, second, chroma] : hue < 5 ? [second, 0, chroma] : [chroma, 0, second];
+  return `#${channel(r + base)}${channel(g + base)}${channel(b + base)}`;
+}
+function resolve(source) {
+  const out = {};
+  for (const [token, entry] of Object.entries(source)) {
+    out[token] = hslToHex(entry.hsl);
+  }
+  return Object.freeze(out);
+}
+const EMAIL_COLORS = resolve(
+  EMAIL_COLOR_SOURCE
+);
+const EMAIL_COLORS_DARK = resolve(
+  EMAIL_COLOR_SOURCE_DARK
+);
+export {
+  EMAIL_COLORS,
+  EMAIL_COLORS_DARK,
+  hslToHex
+};

package/dist/email/geometry.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Email geometry + typography contract — the `--email-*` component tokens resolved to the two
+ * forms an email template actually needs: a CSS string (`"480px"`, for `style="width:480px"`) and a
+ * bare number (`480`, for the legacy HTML attribute form `<table width="480">` that Outlook's Word
+ * renderer still prefers). Both come from src/tokens/components/email.css via
+ * scripts/gen-email-tokens.mjs — nothing here is hand-typed.
+ */
+import { EMAIL_GEOMETRY_SOURCE } from "./tokens.generated.js";
+/** Every `--email-*` token name declared in the component token tier. */
+export type EmailTokenName = keyof typeof EMAIL_GEOMETRY_SOURCE;
+/** The 480px transactional shell — the card and the page gutter around it. */
+export interface EmailShellTokens {
+    /** Card width as a CSS length. */
+    readonly width: string;
+    /** Card width as a number, for `<table width="…">`. */
+    readonly widthPx: number;
+    /** Width of the column INSIDE the card padding (`width − 2 × padding`). */
+    readonly contentWidth: string;
+    readonly contentWidthPx: number;
+    /** Card inset on desktop. */
+    readonly padding: string;
+    readonly paddingPx: number;
+    /** Gutter between the client viewport and the card. */
+    readonly pagePadding: string;
+    readonly pagePaddingPx: number;
+    /** Card edge hairline. */
+    readonly borderWidth: string;
+    readonly borderWidthPx: number;
+    /** Card corner radius (ignored by Outlook's Word renderer — degrade to square, never to an image). */
+    readonly radius: string;
+    readonly radiusPx: number;
+    /** Vertical rhythm between blocks. */
+    readonly gap: string;
+    readonly gapPx: number;
+    /** Tight rhythm (heading ↔ lede). */
+    readonly gapSm: string;
+    readonly gapSmPx: number;
+    /**
+     * Height the canonical invitation reference card measures at this geometry (480×407). A
+     * visual-regression target, NOT a layout input — never set a fixed height on an email card.
+     */
+    readonly referenceHeight: string;
+    readonly referenceHeightPx: number;
+}
+export declare const EMAIL_SHELL: EmailShellTokens;
+/** Type ramp. Sizes are literal px — no email client resolves the rem scale reliably. */
+export interface EmailTypographyTokens {
+    /** Email-safe font stack. Web-font `@font-face` is unavailable in most clients — never rely on it. */
+    readonly fontFamily: string;
+    readonly bodyFontSize: string;
+    readonly bodyFontSizePx: number;
+    readonly bodyLineHeight: number;
+    readonly bodyFontWeight: number;
+    readonly headingFontSize: string;
+    readonly headingFontSizePx: number;
+    readonly headingLineHeight: number;
+    readonly headingFontWeight: number;
+}
+export declare const EMAIL_TYPOGRAPHY: EmailTypographyTokens;
+/** The single primary call-to-action. */
+export interface EmailCtaTokens {
+    readonly height: string;
+    readonly heightPx: number;
+    /** Equal to the height so the label centres without flexbox (Outlook has none). */
+    readonly lineHeight: string;
+    readonly lineHeightPx: number;
+    readonly paddingX: string;
+    readonly paddingXPx: number;
+    readonly radius: string;
+    readonly radiusPx: number;
+    readonly fontSize: string;
+    readonly fontSizePx: number;
+    readonly fontWeight: number;
+}
+export declare const EMAIL_CTA: EmailCtaTokens;
+/** The legal band under the body — quiet type, a hairline, and the inter-link spacing. */
+export interface EmailFooterTokens {
+    readonly fontSize: string;
+    readonly fontSizePx: number;
+    readonly lineHeight: number;
+    /** Horizontal separation between adjacent footer links. */
+    readonly linkGap: string;
+    readonly linkGapPx: number;
+    readonly paddingTop: string;
+    readonly paddingTopPx: number;
+    readonly borderWidth: string;
+    readonly borderWidthPx: number;
+}
+export declare const EMAIL_FOOTER: EmailFooterTokens;
+/** Focus affordance for the webmail preview panes that DO honour `:focus` (WCAG 2.4.7/2.4.11). */
+export interface EmailFocusTokens {
+    readonly borderWidth: string;
+    readonly borderWidthPx: number;
+}
+export declare const EMAIL_FOCUS: EmailFocusTokens;
+/** Narrow-viewport reflow — apply under `@media (max-width: …)` and via `width="100%"` fallbacks. */
+export interface EmailMobileTokens {
+    /** The reflow breakpoint (card width + both gutters). */
+    readonly maxWidth: string;
+    readonly maxWidthPx: number;
+    /** The card goes fluid below the breakpoint. */
+    readonly width: string;
+    readonly padding: string;
+    readonly paddingPx: number;
+    readonly pagePadding: string;
+    readonly pagePaddingPx: number;
+    readonly headingFontSize: string;
+    readonly headingFontSizePx: number;
+    /** The CTA goes full-bleed so the tap target spans the card. */
+    readonly ctaWidth: string;
+}
+export declare const EMAIL_MOBILE: EmailMobileTokens;