@godxjp/ui 27.11.0 → 27.12.0

package/dist/components/data-display/card.d.ts

@@ -40,10 +40,31 @@ export type CardProps = React.HTMLAttributes<HTMLDivElement> & {
      *
      * This is a PRESENTATION flag, not an interaction: it announces nothing and binds no handler.
      * A card that looks clickable has to BE clickable for everyone, so pair it with a real control
-     * — a `Link`/`Button` in the header or footer, or the whole card rendered as one — never with a
-     * bare `onClick` on this div, which a keyboard or screen-reader user cannot reach.
+     * — a `Link`/`Button` in the header or footer, or the whole card rendered as one via
+     * {@link CardProps.asChild} — never with a bare `onClick` on this div, which a keyboard or
+     * screen-reader user cannot reach.
      */
     hoverable?: boolean;
+    /**
+     * Borrow the child's element for the card box instead of rendering a `div` — the package's
+     * standard Slot passthrough (`Button`, `AspectRatio`, `ListRow`). The card's chrome and every
+     * `data-*` flag move onto that element, so a card rendered as an `<a>` or a `<button>` measures
+     * byte for byte like the `div` it replaces and stays a SINGLE tab stop.
+     *
+     * This is the other half of `hoverable`: `<Card asChild hoverable><a href="…">` is "the whole
+     * card rendered as one control", reachable by keyboard and announced as one link.
+     *
+     * NESTING CAVEAT — the card is now ONE control, so it may not contain another. An
+     * `<a>`/`<button>` (a `Link`, a `Button`, a menu trigger) inside a card-as-link or
+     * card-as-button is invalid HTML: the inner control is unreachable or mis-announced, and
+     * `tabList` — a strip of `button` triggers — is for the same reason not drawn under `asChild`.
+     * A card that needs interactive children is not one control: drop `asChild` and put the
+     * `Link`/`Button` inside it instead, as `hoverable` also allows.
+     *
+     * Exactly one child, as everywhere else in this package: two children have no element to
+     * borrow, so `Slot`'s `React.Children.only` throws — the same error `Button asChild` throws.
+     */
+    asChild?: boolean;
     /**
      * Ant Design `tabList` — the tab strip that lives IN THE CARD'S HEAD, under the title, inside
      * the same border and on the same surface, so the card and its tabs read as one object. The
@@ -102,10 +123,31 @@ export declare const Card: React.ForwardRefExoticComponent<React.HTMLAttributes<
      *
      * This is a PRESENTATION flag, not an interaction: it announces nothing and binds no handler.
      * A card that looks clickable has to BE clickable for everyone, so pair it with a real control
-     * — a `Link`/`Button` in the header or footer, or the whole card rendered as one — never with a
-     * bare `onClick` on this div, which a keyboard or screen-reader user cannot reach.
+     * — a `Link`/`Button` in the header or footer, or the whole card rendered as one via
+     * {@link CardProps.asChild} — never with a bare `onClick` on this div, which a keyboard or
+     * screen-reader user cannot reach.
      */
     hoverable?: boolean;
+    /**
+     * Borrow the child's element for the card box instead of rendering a `div` — the package's
+     * standard Slot passthrough (`Button`, `AspectRatio`, `ListRow`). The card's chrome and every
+     * `data-*` flag move onto that element, so a card rendered as an `<a>` or a `<button>` measures
+     * byte for byte like the `div` it replaces and stays a SINGLE tab stop.
+     *
+     * This is the other half of `hoverable`: `<Card asChild hoverable><a href="…">` is "the whole
+     * card rendered as one control", reachable by keyboard and announced as one link.
+     *
+     * NESTING CAVEAT — the card is now ONE control, so it may not contain another. An
+     * `<a>`/`<button>` (a `Link`, a `Button`, a menu trigger) inside a card-as-link or
+     * card-as-button is invalid HTML: the inner control is unreachable or mis-announced, and
+     * `tabList` — a strip of `button` triggers — is for the same reason not drawn under `asChild`.
+     * A card that needs interactive children is not one control: drop `asChild` and put the
+     * `Link`/`Button` inside it instead, as `hoverable` also allows.
+     *
+     * Exactly one child, as everywhere else in this package: two children have no element to
+     * borrow, so `Slot`'s `React.Children.only` throws — the same error `Button asChild` throws.
+     */
+    asChild?: boolean;
     /**
      * Ant Design `tabList` — the tab strip that lives IN THE CARD'S HEAD, under the title, inside
      * the same border and on the same surface, so the card and its tabs read as one object. The

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

@@ -2,6 +2,8 @@
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 import { padStyle, padStepToken } from "../../lib/variants.js";
 import * as React from "react";
+import { isDevelopment } from "../../lib/dev.js";
+import { Slot } from "../../lib/slot.js";
 import { cn } from "../../lib/utils.js";
 import { Tabs } from "../navigation/tabs.js";
 function resolveActiveCardTabKey(tabList, requested) {
@@ -37,11 +39,20 @@ const Card = React.forwardRef(
     onTabChange,
     extra,
     tabProps,
+    asChild = false,
     children,
     ...props
   }, ref) => {
+    const slotted = asChild && Boolean(tabList?.length);
+    if (isDevelopment() && slotted) {
+      console.warn(
+        "Card: `asChild` renders the whole card as ONE control, so `tabList` is ignored and the tab strip is NOT drawn \u2014 a strip of `button` triggers inside a link/button is invalid HTML. Drop `asChild` and put a `Link`/`Button` inside the card instead."
+      );
+    }
+    const tabs = slotted ? void 0 : tabList;
+    const Comp = asChild ? Slot : "div";
     const [mirroredKey, setMirroredKey] = React.useState(void 0);
-    const activeKey = tabList?.length ? resolveActiveCardTabKey(tabList, activeTabKey ?? mirroredKey ?? defaultActiveTabKey) : void 0;
+    const activeKey = tabs?.length ? resolveActiveCardTabKey(tabs, activeTabKey ?? mirroredKey ?? defaultActiveTabKey) : void 0;
     const handleTabChange = React.useCallback(
       (key) => {
         setMirroredKey(key);
@@ -49,9 +60,9 @@ const Card = React.forwardRef(
       },
       [onTabChange]
     );
-    const { head, body, foot } = tabList?.length ? splitCardBands(children) : { head: void 0, body: void 0, foot: void 0 };
+    const { head, body, foot } = tabs?.length ? splitCardBands(children) : { head: void 0, body: void 0, foot: void 0 };
     return /* @__PURE__ */ jsx(
-      "div",
+      Comp,
       {
         ref,
         className: cn("group/card", className),
@@ -61,16 +72,16 @@ const Card = React.forwardRef(
         "data-accent-placement": accentPlacement === "perimeter" ? "perimeter" : void 0,
         "data-variant": variant && variant !== "default" ? variant : void 0,
         "data-density": density,
-        "data-tab-list": tabList?.length ? "" : void 0,
+        "data-tab-list": tabs?.length ? "" : void 0,
         ...props,
-        children: tabList?.length ? /* @__PURE__ */ jsxs(Fragment, { children: [
+        children: tabs?.length ? /* @__PURE__ */ jsxs(Fragment, { children: [
           head,
           /* @__PURE__ */ jsx(
             Tabs,
             {
               variant: "line",
               ...tabProps,
-              items: tabList.map((item) => ({
+              items: tabs.map((item) => ({
                 value: item.key,
                 label: item.tab,
                 disabled: item.disabled,

package/dist/contracts/measurement.json

@@ -1,6 +1,6 @@
 {
   "$comment": "AUTO-GENERATED by scripts/gen-measurement-contract.mjs — do not edit. Read this instead of guessing: docs/MEASUREMENT-CONTRACT.md.",
-  "version": "27.11.0",
+  "version": "27.12.0",
   "targetSize": {
     "standard": "WCAG 2.2 SC 2.5.8 Target Size (Minimum), level AA — 24×24 CSS px",
     "min": 24,

package/dist/props/registry.d.ts

@@ -2851,7 +2851,7 @@ export declare const COMPONENT_PROP_REGISTRY: {
     readonly CardProp: {
         readonly group: "data-display";
         readonly file: "components/data-display/card.tsx";
-        readonly vocabulary: readonly ["ToneProp", "ClassNameProp", "ChildrenProp"];
+        readonly vocabulary: readonly ["ToneProp", "ClassNameProp", "ChildrenProp", "AsChildProp"];
     };
     readonly CardTabItemProp: {
         readonly group: "data-display";

package/dist/props/registry.js

@@ -3366,7 +3366,7 @@ const COMPONENT_PROP_REGISTRY = {
   CardProp: {
     group: "data-display",
     file: "components/data-display/card.tsx",
-    vocabulary: ["ToneProp", "ClassNameProp", "ChildrenProp"]
+    vocabulary: ["ToneProp", "ClassNameProp", "ChildrenProp", "AsChildProp"]
   },
   CardTabItemProp: {
     group: "data-display",

package/dist/styles/card-layout.css

@@ -20,6 +20,10 @@
     overflow: hidden;
   }
 
+  button[data-slot="card"] {
+    text-align: inherit;
+  }
+
   [data-slot="card"][data-variant="muted"] {
     background: hsl(var(--secondary));
   }

package/dist/styles/focus-ring.css

@@ -35,6 +35,9 @@
     .ui-carousel-dot,
     .ui-rating-star,
     a.ui-list-row,
+
+    a[data-slot="card"],
+    button[data-slot="card"],
     .ui-text[data-link],
     .sb-nav-item,
     .sb-user,
@@ -96,6 +99,8 @@
       .ui-carousel-dot,
       .ui-rating-star,
       a.ui-list-row,
+      a[data-slot="card"],
+      button[data-slot="card"],
       .ui-text[data-link],
       .sb-nav-item,
       .sb-user,

package/docs/data-display/card/index.tsx

@@ -160,6 +160,47 @@ export default function Demo() {
           </ResponsiveGrid>
         </Flex>
 
+        <Flex direction="col" gap="sm">
+          <Text as="div" weight="medium">
+            asChild · カード全体をひとつのコントロールにする
+          </Text>
+          <ResponsiveGrid columns={{ sm: 1, md: 2 }}>
+            {/*
+             * `hoverable` が約束する「カード全体をひとつのコントロールとして描く」側。
+             * `asChild` はカードの箱を子の要素に譲るので、リンクそのものがカードになり、
+             * Tab は一度しか止まらず、スクリーンリーダーはリンクひとつとして読み上げます。
+             * 入れ子の禁則：これはもうコントロールなので、中に <a>/<Button> は置けません
+             * （HTML として不正）。中にボタンが要るカードは asChild を外し、hoverable +
+             * CardFooter のボタン（上の例）にします。
+             */}
+            <Card asChild hoverable>
+              <a href="#card-as-child">
+                <CardHeader>
+                  <CardTitle level={2}>カード全体がリンク</CardTitle>
+                  <CardDescription>
+                    タブ 1 回で届き、フォーカスリングはカードの箱に出ます
+                  </CardDescription>
+                </CardHeader>
+                <CardContent>
+                  詳細画面へ遷移します。onClick しか無い場合もこの形（router の Link
+                  コンポーネントを子に渡す）にします。
+                </CardContent>
+              </a>
+            </Card>
+            <Card hoverable>
+              <CardHeader>
+                <CardTitle level={2}>中にコントロールがある場合</CardTitle>
+                <CardDescription>
+                  asChild は使わず、本物のコントロールを内側に置きます
+                </CardDescription>
+              </CardHeader>
+              <CardFooter separated>
+                <Button variant="outline">詳細</Button>
+              </CardFooter>
+            </Card>
+          </ResponsiveGrid>
+        </Flex>
+
         <Flex direction="col" gap="sm">
           <Text as="div" weight="medium">
             Accent · accentPlacement=&quot;edge&quot; (既定 · 先頭エッジのレール)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@godxjp/ui",
-  "version": "27.11.0",
-  "godxUiMcp": "27.11.0",
+  "version": "27.12.0",
+  "godxUiMcp": "27.12.0",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",

package/scripts/ui-audit.mjs

@@ -498,15 +498,12 @@ const RULES = [
     id: "icon-button-needs-name",
     severity: "warn",
     spansElement: true,
-    // An icon-only Button (size="icon") with no author-supplied accessible name. A combobox/icon
-    // button's name is computed from author (aria-label / aria-labelledby / title), not glyph content.
-    test: new RegExp(
-      `<Button\\b(?=${ATTRS}\\bsize=["']icon["'])(?!${ATTRS}\\b(?:aria-label|aria-labelledby|title)=)${ATTRS}>`,
-      "g",
-    ),
-    standard: "WCAG 2.2 SC 4.1.2 · 1.1.1 · WAI-ARIA 1.2",
+    // A `<Button size="icon">` with no accessible name AT ALL — neither from the author
+    // (aria-label / aria-labelledby / title) nor from its CONTENT. See `iconButtonMatches`.
+    matches: iconButtonMatches,
+    standard: "WCAG 2.2 SC 4.1.2 · 1.1.1 · WAI-ARIA 1.2 · Accessible Name Computation 1.2",
     message:
-      "Icon-only <Button size=\"icon\"> needs an accessible name — add aria-label={t('…')}. The icon is decorative (aria-hidden); the name comes from the author, not the glyph.",
+      "Icon-only <Button size=\"icon\"> has no accessible name — neither aria-label={t('…')} nor any content that names it. A visually-hidden child names it too: <VisuallyHidden>{t('…')}</VisuallyHidden> (or className=\"sr-only\") beside the aria-hidden glyph. A glyph alone, or text inside an aria-hidden subtree, names nothing.",
   },
   {
     id: "img-needs-alt",
@@ -1074,6 +1071,135 @@ function* lucideGlyphMatches(source) {
   }
 }
 
+/**
+ * Is this subtree hidden from the accessibility tree? `aria-hidden` with anything but a literal
+ * `false` — an author who writes `aria-hidden={busy}` is saying the subtree MAY be hidden, and a
+ * name that may not be there is not a name.
+ */
+const ariaHiddenTag = (openTag) =>
+  !/\baria-hidden\s*=\s*(?:\{\s*false\s*\}|["']false["'])/.test(openTag) &&
+  /\baria-hidden(?=[\s=/>])/.test(openTag);
+
+/** The three attributes accname takes from the AUTHOR, on one opening tag. */
+const authoredNameTag = (openTag) => /\b(?:aria-label|aria-labelledby|title)\s*=/.test(openTag);
+
+/** Where the element whose opening tag ended at `from` closes, counting nesting of the same tag. */
+function closingTagRange(source, tagName, from) {
+  const tag = new RegExp(`<(/?)${tagName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}(?=[\\s/>])`, "g");
+  tag.lastIndex = from;
+  let depth = 0;
+  for (let m; (m = tag.exec(source));) {
+    if (m[1]) {
+      if (depth === 0) {
+        const gt = source.indexOf(">", m.index);
+        return { start: m.index, end: gt < 0 ? source.length : gt + 1 };
+      }
+      depth -= 1;
+      continue;
+    }
+    const end = jsxOpeningEnd(source, m.index);
+    if (!/\/\s*$/.test(source.slice(m.index, end))) depth += 1;
+    tag.lastIndex = end + 1;
+  }
+  return null;
+}
+
+/**
+ * "Name from content" (Accessible Name and Description Computation §2F) over JSX SOURCE: does
+ * anything in these children reach the accessibility tree as text?
+ *
+ *   - an `aria-hidden` subtree contributes NOTHING, however much text it holds;
+ *   - a visually-hidden child does — `sr-only` (and `VisuallyHidden`, which renders `span.sr-only`)
+ *     clips the box, it does not `display:none` the node, so the text is still named;
+ *   - a non-hidden child carrying its own `aria-label`/`title` contributes that name (`asChild`);
+ *   - an `{expression}` renders text, EXCEPT when it holds JSX — then what renders is those
+ *     elements, and `open ? <ChevronUp /> : <ChevronDown />` is still two unnamed glyphs.
+ *
+ * Limits, both deliberate: a bare `{icon}` identifier is read as text (source alone cannot say
+ * what it holds, and guessing "glyph" would re-create the false positive this replaces), and
+ * visual hiding is only recognised as `aria-hidden` — a `hidden`/`display:none` class is not read.
+ */
+function contributesName(source, textCounts = true) {
+  let i = 0;
+  while (i < source.length) {
+    const char = source[i];
+    if (char === "<") {
+      if (source[i + 1] === "/") {
+        const gt = source.indexOf(">", i);
+        i = gt < 0 ? source.length : gt + 1;
+        continue;
+      }
+      const tagName = /^<([A-Za-z][\w.:-]*)/.exec(source.slice(i))?.[1];
+      if (!tagName) {
+        i += 1;
+        continue;
+      }
+      const end = jsxOpeningEnd(source, i);
+      const openTag = source.slice(i, end + 1);
+      const hidden = ariaHiddenTag(openTag);
+      if (!hidden && authoredNameTag(openTag)) return true;
+      if (/\/\s*>$/.test(openTag)) {
+        i = end + 1;
+        continue;
+      }
+      const close = closingTagRange(source, tagName, end + 1);
+      const childrenEnd = close ? close.start : source.length;
+      if (!hidden && contributesName(source.slice(end + 1, childrenEnd))) return true;
+      i = close ? close.end : source.length;
+      continue;
+    }
+    if (char === "{") {
+      const close = matchBracket(source, i);
+      const expr = source.slice(i + 1, close < 0 ? source.length : close);
+      if (/<[A-Za-z]/.test(expr)) {
+        if (contributesName(expr, false)) return true;
+      } else if (
+        /\S/.test(expr.replace(/(["'`])(?:\\.|(?!\1)[\s\S])*?\1/g, (s) => s.slice(1, -1)))
+      ) {
+        // `{t("…")}` / `{label}` name it; prettier's `{" "}` does not.
+        return true;
+      }
+      i = close < 0 ? source.length : close + 1;
+      continue;
+    }
+    // Inside an expression the scaffolding (`cond ? … : …`, `.map(…)`) is not rendered text, but a
+    // string literal in it is.
+    if (!textCounts && (char === '"' || char === "'" || char === "`")) {
+      const end = endOfString(source, i);
+      if (/\S/.test(source.slice(i + 1, end))) return true;
+      i = end + 1;
+      continue;
+    }
+    if (textCounts && char.trim()) return true;
+    i += 1;
+  }
+  return false;
+}
+
+/**
+ * An icon-only `<Button size="icon">` that NOTHING names (gh#739).
+ *
+ * The rule was a single regex over the OPENING TAG, so the most standard naming of an icon button
+ * — an `aria-hidden` glyph beside visually-hidden text — was reported as unnamed: 5/5 findings in
+ * one consumer repo were that shape. Following the message literally adds an `aria-label` on TOP
+ * of a name, and two name sources drift apart the first time one i18n key is edited. So read the
+ * children the way accname does, via `contributesName`.
+ */
+function* iconButtonMatches(source) {
+  for (const m of source.matchAll(/<Button(?=[\s/>])/g)) {
+    const end = jsxOpeningEnd(source, m.index);
+    if (end >= source.length) continue;
+    const openTag = source.slice(m.index, end + 1);
+    if (!/\bsize\s*=\s*["']icon["']/.test(openTag)) continue;
+    if (authoredNameTag(openTag)) continue;
+    if (!/\/\s*>$/.test(openTag)) {
+      const close = closingTagRange(source, "Button", end + 1);
+      if (contributesName(source.slice(end + 1, close ? close.start : source.length))) continue;
+    }
+    yield { 0: openTag, index: m.index };
+  }
+}
+
 /** Match real JSX text after a balanced opening tag, including props with comparisons. */
 function* currencyMatches(source) {
   for (const opening of source.matchAll(/<(?:[A-Za-z][\w.:]*\b|(?=>))/g)) {