@godxjp/ui 18.4.0 → 18.6.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) {
@@ -41,8 +42,9 @@ function Tabs({
           TabsList,
           {
             "data-slot": "tabs-list",
+            variant: variant === "line" ? "line" : "default",
             className: cn(
-              variant === "line" && "h-auto w-full justify-start rounded-none border-b bg-transparent p-0",
+              variant === "line" && "h-auto w-full justify-start border-b p-0",
               variant === "card" && "w-full justify-start",
               listClassName
             ),
@@ -52,7 +54,9 @@ function Tabs({
                 value: item.value,
                 disabled: item.disabled,
                 className: cn(
-                  variant === "line" && "data-[state=active]:border-primary rounded-none border-b-2 border-transparent bg-transparent px-4 py-2 shadow-none data-[state=active]:bg-transparent data-[state=active]:shadow-none",
+                  // Geometry only — the active underline is the token-owned `::after` bar the
+                  // line variant already owns (never a second, hand-rolled border-b indicator).
+                  variant === "line" && "rounded-none px-4 py-2",
                   variant === "card" && "data-[state=active]:shadow-sm"
                 ),
                 children: item.label
@@ -75,26 +79,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,
@@ -102,7 +120,13 @@ const TabsTrigger = React.forwardRef(({ className, ...props }, ref) => /* @__PUR
     ref,
     "data-slot": "tabs-trigger",
     className: cn(
-      "text-muted-foreground ring-offset-background hover:text-foreground focus-visible:border-ring focus-visible:outline-ring focus-visible:ring-ring/50 data-[state=active]:bg-background data-[state=active]:text-foreground data-[state=active]:ring-primary/25 after:bg-foreground relative inline-flex flex-1 items-center justify-center gap-1.5 rounded-md border border-transparent px-3 py-1 text-sm font-medium whitespace-nowrap transition-all group-data-[orientation=vertical]/tabs:w-full group-data-[orientation=vertical]/tabs:justify-start after:absolute after:opacity-0 after:transition-opacity group-data-[orientation=horizontal]/tabs:after:inset-x-0 group-data-[orientation=horizontal]/tabs:after:bottom-[-5px] group-data-[orientation=horizontal]/tabs:after:h-0.5 group-data-[orientation=vertical]/tabs:after:inset-y-0 group-data-[orientation=vertical]/tabs:after:-right-1 group-data-[orientation=vertical]/tabs:after:w-0.5 focus-visible:ring-[3px] focus-visible:outline-1 disabled:pointer-events-none disabled:opacity-50 data-[state=active]:ring-1 group-data-[variant=default]/tabs-list:data-[state=active]:shadow-sm group-data-[variant=line]/tabs-list:data-[state=active]:bg-transparent group-data-[variant=line]/tabs-list:data-[state=active]:shadow-none group-data-[variant=line]/tabs-list:data-[state=active]:after:opacity-100",
+      // The SELECTED-state ring (`ring-1 ring-primary/25`) is scoped to the default/card lists —
+      // the `line` variant is underline-only (gh#248) and must NEVER paint a surrounding ring, or
+      // it competes with (and at equal specificity overrides) the `:focus-visible` ring. The
+      // focus-visible ring/outline below is deliberately left unscoped: every variant keeps a
+      // visible keyboard focus indicator (WCAG 2.4.7). The line indicator itself lives in
+      // src/styles/navigation-layout.css so it reads the --tabs-indicator-* tokens.
+      "text-muted-foreground ring-offset-background hover:text-foreground focus-visible:border-ring focus-visible:outline-ring focus-visible:ring-ring/50 data-[state=active]:bg-background data-[state=active]:text-foreground group-data-[variant=default]/tabs-list:data-[state=active]:ring-primary/25 relative inline-flex flex-1 items-center justify-center gap-1.5 rounded-md border border-transparent px-3 py-1 text-sm font-medium whitespace-nowrap transition-all group-data-[orientation=vertical]/tabs:w-full group-data-[orientation=vertical]/tabs:justify-start group-data-[variant=line]/tabs-list:border-e-0 group-data-[variant=line]/tabs-list:border-b-0 focus-visible:ring-[3px] focus-visible:outline-1 disabled:pointer-events-none disabled:opacity-50 group-data-[variant=default]/tabs-list:data-[state=active]:shadow-sm group-data-[variant=default]/tabs-list:data-[state=active]:ring-1 group-data-[variant=line]/tabs-list:data-[state=active]:bg-transparent group-data-[variant=line]/tabs-list:data-[state=active]:shadow-none",
       className
     ),
     ...props

package/dist/components/ui/avatar.d.ts

@@ -1,5 +1,6 @@
 import * as React from "react";
 import * as AvatarPrimitive from "@radix-ui/react-avatar";
-export declare const Avatar: React.ForwardRefExoticComponent<Omit<AvatarPrimitive.AvatarProps & React.RefAttributes<HTMLSpanElement>, "ref"> & React.RefAttributes<HTMLSpanElement>>;
+import type { AvatarProp } from "../../props/components/data-display.prop.js";
+export declare const Avatar: React.ForwardRefExoticComponent<Omit<AvatarPrimitive.AvatarProps & React.RefAttributes<HTMLSpanElement>, "ref"> & Pick<AvatarProp, "shape"> & React.RefAttributes<HTMLSpanElement>>;
 export declare const AvatarImage: React.ForwardRefExoticComponent<Omit<AvatarPrimitive.AvatarImageProps & React.RefAttributes<HTMLImageElement>, "ref"> & React.RefAttributes<HTMLImageElement>>;
 export declare const AvatarFallback: React.ForwardRefExoticComponent<Omit<AvatarPrimitive.AvatarFallbackProps & React.RefAttributes<HTMLSpanElement>, "ref"> & React.RefAttributes<HTMLSpanElement>>;

package/dist/components/ui/avatar.js

@@ -3,11 +3,12 @@ import { jsx } from "react/jsx-runtime";
 import * as React from "react";
 import * as AvatarPrimitive from "@radix-ui/react-avatar";
 import { cn } from "../../lib/utils.js";
-const Avatar = React.forwardRef(({ className, ...props }, ref) => /* @__PURE__ */ jsx(
+const Avatar = React.forwardRef(({ className, shape = "circle", ...props }, ref) => /* @__PURE__ */ jsx(
   AvatarPrimitive.Root,
   {
     ref,
     "data-slot": "avatar",
+    "data-shape": shape === "square" ? "square" : void 0,
     className: cn("ui-avatar", className),
     ...props
   }

package/dist/components/ui/input-otp.d.ts

@@ -26,7 +26,10 @@ export declare const InputOTP: React.ForwardRefExoticComponent<(Omit<Omit<React.
     render?: never;
     children: React.ReactNode;
 } & React.RefAttributes<HTMLInputElement>, "ref">) & React.RefAttributes<HTMLInputElement>>;
-export declare const InputOTPGroup: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLDivElement> & React.RefAttributes<HTMLDivElement>>;
+export type { InputOTPGroupAppearanceProp, InputOTPGroupProp, InputOTPGroupProp as InputOTPGroupProps, } from "../../props/components/data-entry.prop.js";
+export declare const InputOTPGroup: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLDivElement> & {
+    appearance?: import("./input-otp.js").InputOTPGroupAppearanceProp;
+} & React.RefAttributes<HTMLDivElement>>;
 export declare const InputOTPSlot: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLDivElement> & {
     index: number;
 } & React.RefAttributes<HTMLDivElement>>;

package/dist/components/ui/input-otp.js

@@ -16,11 +16,12 @@ const InputOTP = React.forwardRef(({ className, containerClassName, ...props },
 ));
 InputOTP.displayName = "InputOTP";
 const InputOTPGroup = React.forwardRef(
-  ({ className, ...props }, ref) => /* @__PURE__ */ jsx(
+  ({ appearance = "slots", className, ...props }, ref) => /* @__PURE__ */ jsx(
     "div",
     {
       ref,
       "data-slot": "input-otp-group",
+      "data-appearance": appearance,
       className: cn("ui-otp-group", className),
       ...props
     }

package/dist/components/ui/toggle-group.d.ts

@@ -1,11 +1,14 @@
 import * as React from "react";
 import * as ToggleGroupPrimitive from "@radix-ui/react-toggle-group";
 import { type ToggleProps } from "./toggle.js";
+type ToggleGroupVariant = ToggleProps["variant"];
+type ToggleGroupSize = ToggleProps["size"];
 export declare const ToggleGroup: React.ForwardRefExoticComponent<((Omit<ToggleGroupPrimitive.ToggleGroupSingleProps & React.RefAttributes<HTMLDivElement>, "ref"> | Omit<ToggleGroupPrimitive.ToggleGroupMultipleProps & React.RefAttributes<HTMLDivElement>, "ref">) & {
-    variant?: ToggleProps["variant"];
-    size?: ToggleProps["size"];
+    variant?: ToggleGroupVariant;
+    size?: ToggleGroupSize;
 }) & React.RefAttributes<HTMLDivElement>>;
 export declare const ToggleGroupItem: React.ForwardRefExoticComponent<Omit<ToggleGroupPrimitive.ToggleGroupItemProps & React.RefAttributes<HTMLButtonElement>, "ref"> & {
-    variant?: ToggleProps["variant"];
-    size?: ToggleProps["size"];
+    variant?: ToggleGroupVariant;
+    size?: ToggleGroupSize;
 } & React.RefAttributes<HTMLButtonElement>>;
+export {};

package/dist/components/ui/toggle-group.js

@@ -4,28 +4,39 @@ import * as React from "react";
 import * as ToggleGroupPrimitive from "@radix-ui/react-toggle-group";
 import { cn } from "../../lib/utils.js";
 import { toggleVariants } from "./toggle.js";
-const ToggleGroup = React.forwardRef(({ className, variant = "default", size = "default", children, ...props }, ref) => /* @__PURE__ */ jsx(
-  ToggleGroupPrimitive.Root,
-  {
-    ref,
-    "data-slot": "toggle-group",
-    "data-variant": variant,
-    "data-size": size,
-    className: cn("ui-toggle-group", className),
-    ...props,
-    children
-  }
-));
+const ToggleGroupContext = React.createContext({});
+const ToggleGroup = React.forwardRef(({ className, variant, size, children, ...props }, ref) => {
+  const context = React.useMemo(() => ({ variant, size }), [variant, size]);
+  return /* @__PURE__ */ jsx(
+    ToggleGroupPrimitive.Root,
+    {
+      ref,
+      "data-slot": "toggle-group",
+      "data-variant": variant,
+      "data-size": size,
+      className: cn("ui-toggle-group", className),
+      ...props,
+      children: /* @__PURE__ */ jsx(ToggleGroupContext.Provider, { value: context, children })
+    }
+  );
+});
 ToggleGroup.displayName = ToggleGroupPrimitive.Root.displayName;
-const ToggleGroupItem = React.forwardRef(({ className, variant, size, ...props }, ref) => /* @__PURE__ */ jsx(
-  ToggleGroupPrimitive.Item,
-  {
-    ref,
-    "data-slot": "toggle-group-item",
-    className: cn(toggleVariants({ variant, size }), className),
-    ...props
-  }
-));
+const ToggleGroupItem = React.forwardRef(({ className, variant, size, ...props }, ref) => {
+  const context = React.useContext(ToggleGroupContext);
+  const resolvedVariant = variant ?? context.variant;
+  const resolvedSize = size ?? context.size;
+  return /* @__PURE__ */ jsx(
+    ToggleGroupPrimitive.Item,
+    {
+      ref,
+      "data-slot": "toggle-group-item",
+      "data-variant": resolvedVariant,
+      "data-size": resolvedSize,
+      className: cn(toggleVariants({ variant: resolvedVariant, size: resolvedSize }), className),
+      ...props
+    }
+  );
+});
 ToggleGroupItem.displayName = ToggleGroupPrimitive.Item.displayName;
 export {
   ToggleGroup,

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

@@ -0,0 +1,108 @@
+/**
+ * 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. The ARTWORK matches the
+ * canonical SCR-302 raster exactly; only the rendered BOX is email-specific — the canonical email
+ * header sets it at 22px (`--email-mark-width`) beside the "GoDX" wordmark, where the web
+ * `<Logo mark="godx" />` box is 32px.
+ *
+ * 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 `--brand` / `--brand-foreground`, the roles
+ * `--logo-godx-color` points at), so a re-themed identity role re-tints the mark. NOT `--success`:
+ * that is the wakatake STATUS green, and binding identity to it rendered the mark ~ΔE76 17 away
+ * from the canonical emerald until gh#250 introduced the dedicated `--brand` role.
+ */
+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` (the canonical 22px header box). */
+    width?: number;
+    /** Rendered height in px. Default `EMAIL_BRAND_MARK.heightPx` (the canonical 22px header box). */
+    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;
+    /**
+     * Mark ↔ wordmark separation in the canonical header LOCKUP. The mark alone is not the header:
+     * the canonical card sets the mark beside a readable "GoDX" wordmark, and the wordmark — not the
+     * mark — carries the accessible name (render the mark with `label: ""` in that pairing).
+     */
+    readonly gap: string;
+    readonly gapPx: number;
+    /** Wordmark type size in the lockup. */
+    readonly wordmarkFontSize: string;
+    readonly wordmarkFontSizePx: number;
+    readonly wordmarkFontWeight: number;
+    /** 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,88 @@
+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,
+  gap: EMAIL_GEOMETRY_SOURCE["--email-mark-gap"],
+  gapPx: Number.parseFloat(EMAIL_GEOMETRY_SOURCE["--email-mark-gap"]),
+  wordmarkFontSize: EMAIL_GEOMETRY_SOURCE["--email-wordmark-font-size"],
+  wordmarkFontSizePx: Number.parseFloat(EMAIL_GEOMETRY_SOURCE["--email-wordmark-font-size"]),
+  wordmarkFontWeight: Number.parseFloat(EMAIL_GEOMETRY_SOURCE["--email-wordmark-font-weight"]),
+  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,53 @@
+/**
+ * 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`   | `--brand` / `--brand-foreground`  | the GoDX capsule + its glyph      |
+ * | `urgency` / `urgencyForeground`| `--attention` / `--attention-foreground` | action-required accent / solid large label |
+ */
+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>>;