@godxjp/ui 19.4.2 → 19.6.0

package/dist/app/app-provider.js

@@ -16,7 +16,8 @@ import {
 } from "../lib/datetime/index.js";
 import { DEFAULT_STORAGE_KEY, readStoredPreferences, writeStoredPreferences } from "./storage.js";
 import {
-  applyThemeAxes
+  applyThemeAxes,
+  PREFERS_DARK_SCHEME_QUERY
 } from "./theme-axes.js";
 import { resolveDefaultTimeFormat } from "./time-format-labels.js";
 import { resolveDefaultTimezone } from "./timezones.js";
@@ -174,6 +175,14 @@ function AppProvider({
     if (typeof document === "undefined") return;
     applyThemeAxes(document.documentElement, { theme, brand, density, fontSize, scaling });
   }, [theme, brand, density, fontSize, scaling]);
+  React.useEffect(() => {
+    if (theme !== "system") return;
+    if (typeof window === "undefined" || typeof window.matchMedia !== "function") return;
+    const query = window.matchMedia(PREFERS_DARK_SCHEME_QUERY);
+    const reapply = () => applyThemeAxes(document.documentElement, { theme: "system" });
+    query.addEventListener("change", reapply);
+    return () => query.removeEventListener("change", reapply);
+  }, [theme]);
   const setLocale = React.useCallback(
     (next) => {
       prefsRef.current = { ...prefsRef.current, locale: next };

package/dist/app/theme-axes.d.ts

@@ -1,13 +1,19 @@
 import type { PageDensityProp } from "../props/vocabulary/layout.prop.js";
-/** Light / dark spine — `data-theme` (alias of the legacy `.dark` class). */
-export type AppTheme = "light" | "dark";
+/**
+ * Theme spine — `data-theme` (alias of the legacy `.dark` class). `"system"` is a CHOICE, not a
+ * rendered value: it defers to the OS `prefers-color-scheme` and is what gets persisted, so the
+ * app keeps following the OS tomorrow morning. `data-theme` only ever carries `light` or `dark`.
+ */
+export type AppTheme = "light" | "dark" | "system";
+/** What `data-theme` actually carries — the resolution of an {@link AppTheme} choice. */
+export type ResolvedAppTheme = Exclude<AppTheme, "system">;
 /** Primary-palette preset — `data-brand`. `null` = keep the app's own `--primary`. */
 export type AppBrand = "brand" | "crm" | "logistics" | "partner" | "slate" | "dxs";
 /** Control / table / spacing density — `data-density` (same vocab as PageContainer). */
 export type AppDensity = PageDensityProp;
 /** Base type size — `data-font-size`; a preset rescales the whole golden scale. */
 export type AppFontSize = "sm" | "default" | "lg";
-export declare const APP_THEMES: readonly ["light", "dark"];
+export declare const APP_THEMES: readonly ["light", "dark", "system"];
 export declare const APP_BRANDS: readonly ["brand", "crm", "logistics", "partner", "slate", "dxs"];
 export declare const APP_DENSITIES: readonly ["compact", "default", "comfortable"];
 export declare const APP_FONT_SIZES: readonly ["sm", "default", "lg"];
@@ -20,6 +26,15 @@ export type AppThemeAxes = {
     scaling: number | null;
 };
 export declare const isAppTheme: (v: unknown) => v is AppTheme;
+/** The media query `theme: "system"` follows. */
+export declare const PREFERS_DARK_SCHEME_QUERY = "(prefers-color-scheme: dark)";
+/** `false` wherever there is no `matchMedia` (SSR, jsdom without the stub) — light is the default. */
+export declare function prefersDarkScheme(): boolean;
+/**
+ * Resolve a stored CHOICE to the value `data-theme` carries. `light`/`dark` pass through
+ * untouched, so a preference stored before `system` existed keeps working.
+ */
+export declare function resolveAppTheme(theme: AppTheme): ResolvedAppTheme;
 export declare const isAppBrand: (v: unknown) => v is AppBrand;
 export declare const isAppDensity: (v: unknown) => v is AppDensity;
 export declare const isAppFontSize: (v: unknown) => v is AppFontSize;

package/dist/app/theme-axes.js

@@ -1,4 +1,4 @@
-const APP_THEMES = ["light", "dark"];
+const APP_THEMES = ["light", "dark", "system"];
 const APP_BRANDS = [
   "brand",
   "crm",
@@ -14,11 +14,20 @@ const APP_DENSITIES = [
 ];
 const APP_FONT_SIZES = ["sm", "default", "lg"];
 const isAppTheme = (v) => APP_THEMES.includes(v);
+const PREFERS_DARK_SCHEME_QUERY = "(prefers-color-scheme: dark)";
+function prefersDarkScheme() {
+  if (typeof window === "undefined" || typeof window.matchMedia !== "function") return false;
+  return window.matchMedia(PREFERS_DARK_SCHEME_QUERY).matches;
+}
+function resolveAppTheme(theme) {
+  if (theme !== "system") return theme;
+  return prefersDarkScheme() ? "dark" : "light";
+}
 const isAppBrand = (v) => APP_BRANDS.includes(v);
 const isAppDensity = (v) => APP_DENSITIES.includes(v);
 const isAppFontSize = (v) => APP_FONT_SIZES.includes(v);
 function applyThemeAxes(el, axes) {
-  if (axes.theme !== void 0) el.dataset.theme = axes.theme;
+  if (axes.theme !== void 0) el.dataset.theme = resolveAppTheme(axes.theme);
   if (axes.density !== void 0) el.dataset.density = axes.density;
   if (axes.fontSize !== void 0) el.dataset.fontSize = axes.fontSize;
   if (axes.brand !== void 0) {
@@ -35,9 +44,12 @@ export {
   APP_DENSITIES,
   APP_FONT_SIZES,
   APP_THEMES,
+  PREFERS_DARK_SCHEME_QUERY,
   applyThemeAxes,
   isAppBrand,
   isAppDensity,
   isAppFontSize,
-  isAppTheme
+  isAppTheme,
+  prefersDarkScheme,
+  resolveAppTheme
 };

package/dist/components/data-display/badge.js

@@ -50,7 +50,10 @@ const STATUS_MAP = {
   ASSIGNMENT_STATUS_TERMINATED: { tone: "destructive", icon: XCircle }
 };
 const badgeVariants = cva(
-  "inline-flex items-center border font-medium transition-colors focus:outline-none focus:ring-2 focus:ring-ring",
+  // `ui-focus-ring` = the system's single focus source (styles/focus-ring.css). It replaces a
+  // hand-rolled `focus:ring-2 focus:ring-ring`, which was token-blind (no --focus-ring-* knob
+  // reached it) and fired on `:focus`, so a mouse click on an interactive badge lit a ring.
+  "ui-focus-ring inline-flex items-center border font-medium transition-colors",
   {
     variants: {
       variant: {

package/dist/components/data-display/data-table.js

@@ -683,8 +683,15 @@ DataTable.Content = function DataTableContent() {
                     rowPadding,
                     // Hover highlight when rows are clickable OR explicitly hoverable…
                     (onRowClick || hoverable) && "hover:bg-muted/50",
-                    // …but the affordance (cursor + focus ring) only when clickable.
-                    onRowClick && "focus-visible:ring-ring cursor-pointer focus-visible:ring-2 focus-visible:outline-none focus-visible:ring-inset",
+                    // …but the affordance (cursor + focus mark) only when clickable.
+                    //
+                    // `ui-focus-ring` = the single focus source (styles/focus-ring.css). It
+                    // replaces `focus-visible:ring-ring focus-visible:ring-2
+                    // focus-visible:ring-inset`, which was a hand-rolled second ring: it read no
+                    // `--focus-ring-*` knob, so a service could not retune it, and — being a
+                    // utility — it painted regardless of the `--focus-outline` switch, which is
+                    // exactly the hole the switch exists to close.
+                    onRowClick && "ui-focus-ring cursor-pointer",
                     isSelected && "bg-muted/30",
                     rowClassName?.(original)
                   ),

package/dist/components/data-entry/checkbox.d.ts

@@ -1,6 +1,18 @@
 import * as React from "react";
 import * as CheckboxPrimitive from "@radix-ui/react-checkbox";
 import { CheckboxGroup } from "./checkbox-group.js";
+/**
+ * Decorative checkbox glyph — a non-interactive `<span>`, NOT the real {@link Checkbox} (which is a
+ * `<button>`). Used where the row itself is the interactive element and a nested `<button>` would
+ * be invalid HTML (Cascader's option rows). Shares {@link CheckboxGlyph} so "partial" can never
+ * drift apart from the real control's rendering again.
+ */
+export declare function CheckboxVisual({ checked, indeterminate, disabled, className, }: {
+    checked: boolean;
+    indeterminate?: boolean;
+    disabled?: boolean;
+    className?: string;
+}): React.JSX.Element;
 /** Checkbox — dùng standalone hoặc `Checkbox.Group` với `options` (Ant Design style). */
 export declare const Checkbox: React.ForwardRefExoticComponent<Omit<CheckboxPrimitive.CheckboxProps & React.RefAttributes<HTMLButtonElement>, "ref"> & React.RefAttributes<HTMLButtonElement>> & {
     Group: typeof CheckboxGroup;

package/dist/components/data-entry/checkbox.js

@@ -2,16 +2,42 @@
 import { jsx } from "react/jsx-runtime";
 import * as React from "react";
 import * as CheckboxPrimitive from "@radix-ui/react-checkbox";
-import { Check } from "lucide-react";
+import { Check, Minus } from "lucide-react";
 import { cn } from "../../lib/utils.js";
 import { useFieldIdentity } from "../../lib/field-a11y.js";
 import { CheckboxGroup } from "./checkbox-group.js";
+function CheckboxGlyph({ state }) {
+  return state === "indeterminate" ? /* @__PURE__ */ jsx(Minus, { className: "ui-checkbox-icon", "aria-hidden": "true" }) : /* @__PURE__ */ jsx(Check, { className: "ui-checkbox-icon", "aria-hidden": "true" });
+}
+function CheckboxVisual({
+  checked,
+  indeterminate,
+  disabled,
+  className
+}) {
+  const state = indeterminate ? "indeterminate" : checked;
+  return /* @__PURE__ */ jsx(
+    "span",
+    {
+      "aria-hidden": "true",
+      "data-slot": "checkbox",
+      "data-state": indeterminate ? "indeterminate" : checked ? "checked" : "unchecked",
+      "data-disabled": disabled ? "" : void 0,
+      className: cn("ui-checkbox inline-flex items-center justify-center", className),
+      children: checked || indeterminate ? /* @__PURE__ */ jsx(CheckboxGlyph, { state }) : null
+    }
+  );
+}
 const CheckboxRoot = React.forwardRef(({ className, ...props }, ref) => {
   const identity = useFieldIdentity({
     id: props.id,
     name: props.name,
     "data-field": props["data-field"]
   });
+  const [uncontrolled, setUncontrolled] = React.useState(
+    props.defaultChecked ?? false
+  );
+  const state = props.checked ?? uncontrolled;
   return /* @__PURE__ */ jsx(
     CheckboxPrimitive.Root,
     {
@@ -31,7 +57,11 @@ const CheckboxRoot = React.forwardRef(({ className, ...props }, ref) => {
       ),
       ...props,
       ...identity,
-      children: /* @__PURE__ */ jsx(CheckboxPrimitive.Indicator, { "data-slot": "checkbox-indicator", className: "ui-choice-indicator", children: /* @__PURE__ */ jsx(Check, { className: "ui-checkbox-icon", "aria-hidden": "true" }) })
+      onCheckedChange: (next) => {
+        setUncontrolled(next);
+        props.onCheckedChange?.(next);
+      },
+      children: /* @__PURE__ */ jsx(CheckboxPrimitive.Indicator, { "data-slot": "checkbox-indicator", className: "ui-choice-indicator", children: /* @__PURE__ */ jsx(CheckboxGlyph, { state }) })
     }
   );
 });
@@ -40,5 +70,6 @@ const Checkbox = Object.assign(CheckboxRoot, {
   Group: CheckboxGroup
 });
 export {
-  Checkbox
+  Checkbox,
+  CheckboxVisual
 };

package/dist/components/data-entry/index.d.ts

@@ -63,5 +63,7 @@ export { Rating } from "./rating.js";
 export type { RatingProps } from "./rating.js";
 export { TagInput } from "./tag-input.js";
 export type { TagInputProps } from "./tag-input.js";
+export { Segmented } from "./segmented.js";
+export type { SegmentedOption, SegmentedProp, SegmentedProps } from "./segmented.js";
 export { BranchScopePicker } from "./branch-scope-picker.js";
 export type { BranchScopeModeProp, BranchScopeOptionProp, BranchScopePickerProp, BranchScopePickerProps, BranchScopeValueProp, } from "./branch-scope-picker.js";

package/dist/components/data-entry/index.js

@@ -51,6 +51,7 @@ import { PasswordStrength, usePasswordStrength } from "./password-strength.js";
 import { InputOTP, InputOTPGroup, InputOTPSlot, InputOTPSeparator } from "./input-otp.js";
 import { Rating } from "./rating.js";
 import { TagInput } from "./tag-input.js";
+import { Segmented } from "./segmented.js";
 import { BranchScopePicker } from "./branch-scope-picker.js";
 export {
   BranchScopePicker,
@@ -93,6 +94,7 @@ export {
   SHOW_CHILD,
   SHOW_PARENT,
   SearchInput,
+  Segmented,
   Select,
   SelectContent,
   SelectGroup,

package/dist/components/data-entry/segmented.d.ts

@@ -0,0 +1,2 @@
+export { Segmented } from "../ui/segmented.js";
+export type { SegmentedOption, SegmentedProp, SegmentedProps } from "../ui/segmented.js";

package/dist/components/data-entry/segmented.js

@@ -0,0 +1,5 @@
+"use client";
+import { Segmented } from "../ui/segmented.js";
+export {
+  Segmented
+};

package/dist/components/data-entry/select.d.ts

@@ -25,6 +25,8 @@ export declare const SelectTrigger: React.ForwardRefExoticComponent<Omit<SelectP
      * `full` (default) fills the field column — right inside a FormField. `auto` sizes to the
      * selected label — right in a PageContainer `extra` slot, a toolbar or a footer row, where a
      * full-width trigger swallows the row and starves its siblings (text truncated to "UA…").
+     * `bounded` holds one width from `--control-bounded-width`, for a trigger whose VALUE varies
+     * in length and must not move its neighbours when it changes (gh#375).
      */
     width?: ControlWidthProp;
     /**

package/dist/components/data-entry/select.js

@@ -98,7 +98,12 @@ const SelectTrigger = React.forwardRef(({ className, children, size = "md", widt
       "data-width": width,
       className: cn(
         controlTriggerClass,
-        width === "auto" ? "w-auto" : "w-full",
+        // `bounded` deliberately emits NO width utility: its width is owned by the
+        // `[data-width="bounded"]` rule in control.css. A utility here would win the layer order
+        // and make that rule — and therefore the token — dead, the way `w-full` did to
+        // `.ui-app-setting-picker-icon` (gh#366, gh#371).
+        width === "auto" && "w-auto",
+        width === "full" && "w-full",
         "aria-invalid:border-destructive data-[placeholder]:text-muted-foreground [&_svg:not([class*='text-'])]:text-muted-foreground whitespace-nowrap transition-[color,box-shadow] outline-none *:data-[slot=select-value]:line-clamp-1 *:data-[slot=select-value]:flex *:data-[slot=select-value]:items-center",
         className
       ),
@@ -143,11 +148,11 @@ const SelectScrollDownButton = React.forwardRef(({ className, ...props }, ref) =
 ));
 SelectScrollDownButton.displayName = SelectPrimitive.ScrollDownButton.displayName;
 const SelectContent = React.forwardRef(({ className, children, position = "popper", ...props }, ref) => {
-  useInertHiddenBackground();
+  const contentRef = useInertHiddenBackground(ref);
   return /* @__PURE__ */ jsx(SelectPrimitive.Portal, { children: /* @__PURE__ */ jsxs(
     SelectPrimitive.Content,
     {
-      ref,
+      ref: contentRef,
       "data-slot": "select-content",
       className: cn(
         "ui-select-content data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2",

package/dist/components/feedback/sheet.js

@@ -127,7 +127,7 @@ const SheetContent = React.forwardRef(
               DialogPrimitive.Close,
               {
                 "data-slot": "sheet-close",
-                className: "ui-sheet-close ring-offset-background focus:ring-ring focus:ring-2 focus:ring-offset-2 focus:outline-hidden disabled:pointer-events-none",
+                className: "ui-sheet-close ui-focus-ring disabled:pointer-events-none",
                 children: [
                   /* @__PURE__ */ jsx(X, { className: "ui-sheet-close-icon", "aria-hidden": "true" }),
                   /* @__PURE__ */ jsx("span", { className: "sr-only", children: t("feedback.alert.dismiss") })

package/dist/components/feedback/sonner.d.ts

@@ -1,4 +1,10 @@
 import * as React from "react";
 import { type ToasterProps } from "sonner";
-declare function Toaster({ style, ...props }: ToasterProps): React.JSX.Element;
+/**
+ * `richColors` defaults ON: it is the switch that makes sonner apply the per-type properties at
+ * all (`[data-rich-colors='true'][data-type='success'] { … }`), so without it the tokens above
+ * are declared and never read. A consumer can still pass `richColors={false}` for a deliberately
+ * monochrome stack.
+ */
+declare function Toaster({ style, richColors, ...props }: ToasterProps): React.JSX.Element;
 export { Toaster };

package/dist/components/feedback/sonner.js

@@ -10,22 +10,42 @@ function useDocumentTheme() {
       const mq = window.matchMedia("(prefers-color-scheme: dark)");
       mq.addEventListener("change", onStoreChange);
       const obs = new MutationObserver(onStoreChange);
-      obs.observe(document.documentElement, { attributes: true, attributeFilter: ["class"] });
+      obs.observe(document.documentElement, {
+        attributes: true,
+        attributeFilter: ["class", "data-theme"]
+      });
       return () => {
         mq.removeEventListener("change", onStoreChange);
         obs.disconnect();
       };
     },
-    () => document.documentElement.classList.contains("dark") ? "dark" : "light",
+    () => document.documentElement.dataset.theme === "dark" || document.documentElement.classList.contains("dark") ? "dark" : "light",
     () => "light"
   );
 }
-function Toaster({ style, ...props }) {
+const TOAST_TONES = [
+  { type: "success", hue: "success", ink: "text-success" },
+  { type: "error", hue: "destructive", ink: "text-error" },
+  { type: "warning", hue: "warning", ink: "text-warning" },
+  { type: "info", hue: "info", ink: "text-info" }
+];
+const toneVars = Object.fromEntries(
+  TOAST_TONES.flatMap(({ type, hue, ink }) => [
+    [
+      `--${type}-bg`,
+      `color-mix(in srgb, hsl(var(--${hue})) calc(var(--alert-bg-alpha) * 100%), hsl(var(--popover)))`
+    ],
+    [`--${type}-border`, `hsl(var(--${hue}) / var(--alert-border-alpha))`],
+    [`--${type}-text`, `hsl(var(--${ink}))`]
+  ])
+);
+function Toaster({ style, richColors = true, ...props }) {
   const theme = useDocumentTheme();
   return /* @__PURE__ */ jsx(
     Sonner,
     {
       theme,
+      richColors,
       className: "toaster group",
       icons: {
         success: /* @__PURE__ */ jsx(CheckCircle2, { className: "ui-toast-icon", "aria-hidden": "true" }),
@@ -43,10 +63,10 @@ function Toaster({ style, ...props }) {
         "--normal-text": "hsl(var(--popover-foreground))",
         "--normal-border": "hsl(var(--border))",
         "--border-radius": "var(--radius)",
-        // MERGED, never spread over.
-        // object and wiped all four vars — and an unset `--normal-bg` renders the toast
-        // transparent.
-        // var by name.
+        ...toneVars,
+        // MERGED LAST, never spread over: a consumer's `style` is an override of these
+        // defaults, one custom property at a time. Assigning it instead of merging would
+        // wipe every var above, and an unset `--normal-bg` renders the toast transparent.
         ...style
       },
       position: "bottom-right",

package/dist/components/general/button.js

@@ -9,7 +9,12 @@ import { useTranslation } from "../../i18n/use-translation.js";
 const buttonVariants = cva("ui-button", {
   variants: {
     variant: {
-      default: "ui-button--default bg-primary text-primary-foreground hover:bg-primary/90",
+      // Colour is the TOKEN LAYER's (`.ui-button--default` in styles/control.css), not a utility's.
+      // The three utilities that used to sit here — `bg-primary text-primary-foreground
+      // hover:bg-primary/90` — restated the fill the components layer already declares and, being
+      // utilities, out-ranked it: the hover step this library generates from antd's algorithm
+      // (`--primary-hover`) could never take effect while `hover:bg-primary/90` was emitted here.
+      default: "ui-button--default",
       destructive: "ui-button--destructive bg-destructive text-destructive-foreground",
       outline: "ui-button--outline border bg-background shadow-xs hover:bg-accent hover:text-accent-foreground",
       dashed: "ui-button--dashed border border-dashed bg-background hover:bg-accent hover:text-accent-foreground",

package/dist/components/general/inert-background.d.ts

@@ -1,5 +1,10 @@
+import * as React from "react";
 /**
- * Call from an overlay's content wrapper (the always-mounted portal wrapper, not the portalled
- * content itself). Idempotent and refcounted: one observer serves every overlay on the page.
+ * Call from an overlay's content wrapper, and spread the returned ref onto the Radix content
+ * element itself — that element is what carries `data-state`, and registering it is what lets the
+ * background be released on close intent rather than on unmount (gh#385).
+ *
+ * The caller's own forwarded ref is composed in, so a content component still hands its node to
+ * the consumer. Idempotent and refcounted: one observer serves every overlay on the page.
  */
-export declare function useInertHiddenBackground(): void;
+export declare function useInertHiddenBackground<T extends HTMLElement>(forwarded?: React.Ref<T>): (node: T | null) => void;

package/dist/components/general/inert-background.js

@@ -2,9 +2,20 @@
 import * as React from "react";
 const TABBABLE = 'a[href], area[href], button, input, select, textarea, iframe, object, embed, details, audio[controls], video[controls], [contenteditable="true"], [tabindex]:not([tabindex^="-"])';
 const owned = /* @__PURE__ */ new Set();
+const anchors = /* @__PURE__ */ new Set();
 let observer = null;
 let mounted = 0;
+function anyOverlayOpen() {
+  for (const anchor of anchors) {
+    if (anchor.isConnected && anchor.getAttribute("data-state") !== "closed") return true;
+  }
+  return false;
+}
 function sync() {
+  if (!anyOverlayOpen()) {
+    release();
+    return;
+  }
   for (const el of document.querySelectorAll("[data-aria-hidden]")) {
     if (owned.has(el) || el.hasAttribute("inert")) continue;
     if (el.matches("[data-radix-focus-guard]")) continue;
@@ -23,7 +34,7 @@ function release() {
   for (const el of owned) el.removeAttribute("inert");
   owned.clear();
 }
-function useInertHiddenBackground() {
+function useInertHiddenBackground(forwarded) {
   React.useEffect(() => {
     mounted += 1;
     if (!observer) {
@@ -31,7 +42,8 @@ function useInertHiddenBackground() {
       observer.observe(document.body, {
         subtree: true,
         attributes: true,
-        attributeFilter: ["data-aria-hidden"]
+        // `data-state` is the close-intent signal; `data-aria-hidden` is the what-to-hide signal.
+        attributeFilter: ["data-aria-hidden", "data-state"]
       });
     }
     sync();
@@ -43,6 +55,18 @@ function useInertHiddenBackground() {
       release();
     };
   }, []);
+  const registered = React.useRef(null);
+  const forwardedRef = React.useRef(forwarded);
+  forwardedRef.current = forwarded;
+  return React.useCallback((node) => {
+    if (registered.current) anchors.delete(registered.current);
+    registered.current = node;
+    if (node) anchors.add(node);
+    sync();
+    const target = forwardedRef.current;
+    if (typeof target === "function") target(node);
+    else if (target) target.current = node;
+  }, []);
 }
 export {
   useInertHiddenBackground

package/dist/components/general/logo.d.ts

@@ -6,6 +6,15 @@ export interface LogoProps extends Omit<React.HTMLAttributes<HTMLSpanElement>, "
     /**
      * The brand glyph — a short mark (a letter/initials, default `"g"`) or a custom node such as an
      * inline `<svg>`. Keep it to 1–2 glyphs; the box is square and centres its content.
+     *
+     * A STRING is classified by the ink band it occupies (`g` x-height→descender, `GX` cap→baseline,
+     * `神` the full em box) and optically centred for that band — a line box is not a letterform, and
+     * the classes' centres are 0.21em apart. Any other node is left alone. Retune a band, or pin one
+     * mark, with the `--logo-glyph-*-optical-offset` tokens.
+     *
+     * A string is also FITTED to the box: two full-width forms want ~2em against a box sized for
+     * roughly one, so `東京` at `xs` is SET SMALLER rather than wrapping. The mark is always one
+     * line. Retune how much of the box a fitted glyph may take with `--logo-glyph-fit-max-width`.
      */
     glyph?: React.ReactNode;
     /**
@@ -37,6 +46,50 @@ export interface LogoProps extends Omit<React.HTMLAttributes<HTMLSpanElement>, "
      */
     label?: string;
 }
+/**
+ * The band the glyph's ink actually occupies, as the (top edge, bottom edge) of the UNION of every
+ * character in the string — `"GX"` is cap→baseline, `"gX"` is cap→descender.
+ */
+export type LogoGlyphInk = "cap-baseline" | "cap-descender" | "x-baseline" | "x-descender";
+/**
+ * Classify a glyph for optical centring. Pure, no layout read, no measurement — the component is
+ * the only layer that can do this at all, because CSS cannot see which character is in the box.
+ * Returns `undefined` for a non-string glyph (an inline `<svg>`, any other node) and for an empty
+ * string: those are not classified and keep the neutral default rather than being guessed at.
+ */
+export declare function logoGlyphInk(glyph: React.ReactNode): LogoGlyphInk | undefined;
+/**
+ * How much INLINE space the glyph string wants, as counts of the four advance classes — the fact
+ * `.ui-logo-glyph`'s fit cap is computed from (gh#377). `fullwidth` is the characters that occupy
+ * a whole em; `wide` is the proportional forms that REACH that em (`M W m`); `space` is the runs
+ * of collapsible white space the paint keeps; `narrow` is everything else.
+ *
+ * The contract is that the FITTED font-size times the PAINTED advance stays inside the box, at
+ * every tier, on every bundled face. Over-stating an advance only sets the mark a little smaller
+ * than it had to be; under-stating it puts the mark outside its own box, which is the defect
+ * these classes exist to remove.
+ */
+export interface LogoGlyphAdvance {
+    fullwidth: number;
+    wide: number;
+    narrow: number;
+    space: number;
+}
+/**
+ * Count a glyph string's characters by advance class. Pure, no layout read, no measurement — the
+ * component is the only layer that can do this, because CSS cannot see which characters are in the
+ * box. Returns `undefined` for a non-string glyph and for an empty string, exactly like
+ * `logoGlyphInk`: those are not classified and keep the neutral default rather than being guessed
+ * at. Iterates code points, so a surrogate pair (CJK Extension B) counts once.
+ *
+ * WHITE SPACE IS COUNTED, NOT DROPPED. `.ui-logo-glyph` sets `white-space: nowrap`, which stops
+ * the mark wrapping but still PAINTS an interior space — measured 0.198em (system) to 0.333em
+ * (Hiragino Sans) — so a string whose space was dropped from the count was fitted to an advance
+ * narrower than the one that reached the screen (`東 京` spilled 2.63px at `md`). CSS's own
+ * processing is mirrored exactly: leading and trailing runs are trimmed away, and an interior run
+ * of any length collapses to ONE space (both verified in Chromium against the shipped `nowrap`).
+ */
+export declare function logoGlyphAdvance(glyph: React.ReactNode): LogoGlyphAdvance | undefined;
 /**
  * Logo — the product brand-mark box: a glyph on the primary fill, or (with `wordmark`) the full
  * mark + wordmark LOCKUP. Size, radius, per-tier font-size, the wordmark's

package/dist/components/general/logo.js

@@ -1,8 +1,60 @@
-import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import { jsx, jsxs } from "react/jsx-runtime";
 import * as React from "react";
 import { cn } from "../../lib/utils.js";
+const X_HEIGHT_TOP = /^[acegmnopqrsuvwxyz]+$/;
+const LATIN_DESCENDER = /[gjpqy]/;
+function logoGlyphInk(glyph) {
+  if (typeof glyph !== "string") return void 0;
+  const text = glyph.replace(/\s+/gu, "");
+  if (!text) return void 0;
+  const top = X_HEIGHT_TOP.test(text) ? "x" : "cap";
+  const bottom = LATIN_DESCENDER.test(text) ? "descender" : "baseline";
+  return `${top}-${bottom}`;
+}
+const FULL_WIDTH_ADVANCE = /[\p{Script=Han}\p{Script=Hiragana}\p{Script=Katakana}\p{Script=Hangul}\u{3000}-\u{303F}\u{FF01}-\u{FF60}\u{FFE0}-\u{FFE6}]/u;
+const EM_WIDE_ADVANCE = /[MWm]/;
+const COLLAPSIBLE_SPACE = /[\t\n\f\r ]/;
+function logoGlyphAdvance(glyph) {
+  if (typeof glyph !== "string") return void 0;
+  const text = glyph.replace(/^[\t\n\f\r ]+|[\t\n\f\r ]+$/g, "");
+  if (!text) return void 0;
+  const counts = { fullwidth: 0, wide: 0, narrow: 0, space: 0 };
+  let inSpaceRun = false;
+  for (const character of text) {
+    if (FULL_WIDTH_ADVANCE.test(character)) {
+      counts.fullwidth += 1;
+    } else if (COLLAPSIBLE_SPACE.test(character)) {
+      if (!inSpaceRun) counts.space += 1;
+      inSpaceRun = true;
+      continue;
+    } else if (EM_WIDE_ADVANCE.test(character)) {
+      counts.wide += 1;
+    } else {
+      counts.narrow += 1;
+    }
+    inSpaceRun = false;
+  }
+  return counts;
+}
 function MarkArtwork({ mark, glyph }) {
-  if (mark !== "godx") return /* @__PURE__ */ jsx(Fragment, { children: glyph });
+  if (mark !== "godx") {
+    const advance = logoGlyphAdvance(glyph);
+    return /* @__PURE__ */ jsx(
+      "span",
+      {
+        "data-slot": "logo-glyph",
+        "data-ink": logoGlyphInk(glyph),
+        className: "ui-logo-glyph",
+        style: advance && {
+          "--logo-glyph-fullwidth-count": advance.fullwidth,
+          "--logo-glyph-wide-count": advance.wide,
+          "--logo-glyph-narrow-count": advance.narrow,
+          "--logo-glyph-space-count": advance.space
+        },
+        children: glyph
+      }
+    );
+  }
   return /* @__PURE__ */ jsx(
     "svg",
     {
@@ -72,5 +124,7 @@ const Logo = React.forwardRef(
 );
 Logo.displayName = "Logo";
 export {
-  Logo
+  Logo,
+  logoGlyphAdvance,
+  logoGlyphInk
 };

package/dist/components/general/typography.d.ts

@@ -5,7 +5,9 @@ export type { TextProp, TextProp as TextProps, HeadingProp, HeadingProp as Headi
  * font-medium text-muted-foreground">`.
  */
 export declare const Text: React.ForwardRefExoticComponent<Omit<React.HTMLAttributes<HTMLElement>, "color"> & {
-    as?: "span" | "p" | "div" | "label" | "strong" | "em" | "small" | "code" | "kbd" | "dt" | "dd" | "caption" | "abbr";
+    as?: "span" | "p" | "div" | "a" | "label" | "strong" | "em" | "small" | "code" | "kbd" | "dt" | "dd" | "caption" | "abbr";
+    asChild?: import("../../props/index.js").AsChildProp;
+    link?: boolean;
     size?: import("../../props/index.js").TextSizeProp;
     tone?: import("../../props/index.js").TextToneProp;
     weight?: import("../../props/index.js").FontWeightProp;
@@ -15,6 +17,10 @@ export declare const Text: React.ForwardRefExoticComponent<Omit<React.HTMLAttrib
     tabular?: boolean;
     mono?: boolean;
     htmlFor?: string;
+    href?: string;
+    target?: React.HTMLAttributeAnchorTarget;
+    rel?: string;
+    download?: React.AnchorHTMLAttributes<HTMLAnchorElement>["download"];
 } & React.RefAttributes<HTMLElement>>;
 /**
  * Heading — h1..h4 sized from the `--heading-h*` tokens. `level` sets both the size token and the