@godxjp/ui 27.12.0 → 28.0.0

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

@@ -49,6 +49,18 @@ const Card = React.forwardRef(
         "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."
       );
     }
+    if (isDevelopment()) {
+      const slots = React.Children.toArray(children).filter(React.isValidElement);
+      const hasHeader = slots.some((child) => child.type === CardHeader);
+      const soloBody = slots.some(
+        (child) => child.type === CardContent && child.props?.solo === true
+      );
+      if (hasHeader && soloBody) {
+        console.warn(
+          "Card: `CardContent solo` says there is NO header above it, so it takes the card's own block padding \u2014 but this card also renders a `CardHeader`. The two cannot both hold, and the padding wins, which is the empty strip above your content. Drop `solo` to keep the header, or drop the header if the body really is alone."
+        );
+      }
+    }
     const tabs = slotted ? void 0 : tabList;
     const Comp = asChild ? Slot : "div";
     const [mirroredKey, setMirroredKey] = React.useState(void 0);

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

@@ -11,6 +11,28 @@ type ToggleGroupBaseProp = Omit<React.ComponentPropsWithoutRef<"div">, "defaultV
     disabled?: boolean;
     /** Which way the arrow keys walk the group. */
     orientation?: "horizontal" | "vertical";
+    /**
+     * May the group end up with NOTHING selected? Omitted (`false`) it may, which is what a tag
+     * filter wants — pressing the selected chip again clears it and reports `""`. Set it and the
+     * selected item stays selected when it is pressed again.
+     *
+     * **It also decides the ARIA role of a `type="single"` group (gh#744)**, because emptiness is
+     * exactly what the two roles disagree about. ARIA has no "press again to deselect" for a radio:
+     * a radiogroup that has a selection always has exactly one checked item, so a radiogroup that
+     * the user just emptied is a state a screen reader cannot read out. Therefore:
+     *
+     * - omitted → `role="group"` + `aria-pressed` per item (a row of toggle buttons, which MAY be
+     *   all-off) — this is the default, so no existing single group changes behaviour;
+     * - set → `role="radiogroup"` + `role="radio"` / `aria-checked` per item, and the arrow keys
+     *   move the SELECTION as APG's radio-group pattern requires, not just the focus.
+     *
+     * The name is React Aria's own (`useToggleGroupState`, which this component is built on) —
+     * neither antd nor Radix names the capability. See `docs/DESIGN-AUTHORITY.md`.
+     *
+     * On `type="multiple"` it only keeps the last remaining item selected; the roles do not move
+     * (a row of `aria-pressed` buttons is already the right reading there).
+     */
+    disallowEmptySelection?: boolean;
     /**
      * Let the row break onto further lines instead of running past its rail (gh#741). Same name,
      * same boolean shape and same `data-wrap` attribute as `Flex` — one spelling answers "what does

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

@@ -13,6 +13,7 @@ import {
   useCounterPill
 } from "./toggle.js";
 const ToggleGroupContext = React.createContext({});
+const ARROW_KEYS = /* @__PURE__ */ new Set(["ArrowLeft", "ArrowRight", "ArrowUp", "ArrowDown"]);
 function toSelectedKeys(value) {
   if (value == null) {
     return void 0;
@@ -39,10 +40,16 @@ const ToggleGroup = React.forwardRef(
     defaultValue,
     onValueChange,
     disabled,
+    disallowEmptySelection,
     loop: _loop,
     ...props
   }, ref) => {
-    const context = React.useMemo(() => ({ variant, size, shape }), [variant, size, shape]);
+    const radioSemantics = type === "single" && disallowEmptySelection === true;
+    const arrowNav = React.useRef(false);
+    const context = React.useMemo(
+      () => ({ variant, size, shape, radioSemantics, arrowNav }),
+      [variant, size, shape, radioSemantics]
+    );
     const selectedKeys = React.useMemo(() => toSelectedKeys(value), [value]);
     const defaultSelectedKeys = React.useMemo(() => toSelectedKeys(defaultValue), [defaultValue]);
     const handleSelectionChange = (keys) => {
@@ -69,7 +76,27 @@ const ToggleGroup = React.forwardRef(
         defaultSelectedKeys,
         onSelectionChange: handleSelectionChange,
         isDisabled: disabled,
-        render: (domProps) => /* @__PURE__ */ jsx("div", { ...props, ...domProps, tabIndex: props.tabIndex ?? domProps.tabIndex }),
+        disallowEmptySelection,
+        render: (domProps) => /* @__PURE__ */ jsx(
+          "div",
+          {
+            ...props,
+            ...domProps,
+            ...type === "single" && !radioSemantics ? { role: "group", "aria-orientation": void 0 } : null,
+            onKeyDownCapture: (event) => {
+              if (radioSemantics) {
+                arrowNav.current = ARROW_KEYS.has(event.key);
+                if (arrowNav.current) {
+                  queueMicrotask(() => {
+                    arrowNav.current = false;
+                  });
+                }
+              }
+              domProps.onKeyDownCapture?.(event);
+            },
+            tabIndex: props.tabIndex ?? domProps.tabIndex
+          }
+        ),
         children: /* @__PURE__ */ jsx(ToggleGroupContext.Provider, { value: context, children })
       }
     );
@@ -105,6 +132,9 @@ const ToggleGroupItem = React.forwardRef(
     });
     const groupState = React.useContext(ToggleGroupStateContext);
     const isPressed = groupState?.selectedKeys.has(value) ?? false;
+    const isSingle = groupState?.selectionMode === "single";
+    const radioSemantics = context.radioSemantics === true;
+    const rovingTabIndex = radioSemantics && groupState && groupState.selectedKeys.size > 0 ? isPressed ? 0 : -1 : void 0;
     return /* @__PURE__ */ jsxs(
       ToggleButton,
       {
@@ -122,7 +152,22 @@ const ToggleGroupItem = React.forwardRef(
         ...props,
         id: value,
         isDisabled: disabled,
-        render: (domProps) => restoreDomProps(props, domProps),
+        render: (domProps) => restoreDomProps(props, {
+          ...domProps,
+          ...isSingle && !radioSemantics ? { role: void 0, "aria-checked": void 0, "aria-pressed": isPressed } : null,
+          ...rovingTabIndex == null ? null : { tabIndex: rovingTabIndex },
+          // Selection follows focus, as APG requires of a radio group — but only when an arrow
+          // key is what moved it. Measured otherwise: RAC's toolbar Tab handler focuses the
+          // LAST item on the way out, which silently moved the selection to it.
+          ...radioSemantics ? {
+            onFocus: (event) => {
+              if (context.arrowNav?.current && groupState && groupState.selectedKeys.size > 0 && !isPressed) {
+                groupState.setSelected(value, true);
+              }
+              domProps.onFocus?.(event);
+            }
+          } : null
+        }),
         children: [
           children,
           pill

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.12.0",
+  "version": "28.0.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

@@ -2471,6 +2471,10 @@ export declare const COMPONENT_PROP_REGISTRY: {
             readonly field: "wrap";
             readonly local: true;
             readonly reason: "The SAME boolean shorthand for flex-wrap that FlexProp carries, on the row that owns a chip set — one spelling for 'what does this row do when it does not fit' (gh#741). Opt-in, and the same default for every variant: paint must not decide geometry.";
+        }, {
+            readonly field: "disallowEmptySelection";
+            readonly local: true;
+            readonly reason: "React Aria's own name for the capability (useToggleGroupState), which this component is built on; neither antd nor Radix names it (docs/DESIGN-AUTHORITY.md). It is not just a state guard: on type=single it DECIDES the ARIA role, because emptiness is the one thing role=group + aria-pressed and role=radiogroup + aria-checked disagree about (gh#744).";
         }];
     };
     readonly ToggleGroupItemProp: {

package/dist/props/registry.js

@@ -2878,6 +2878,11 @@ const COMPONENT_PROP_REGISTRY = {
         field: "wrap",
         local: true,
         reason: "The SAME boolean shorthand for flex-wrap that FlexProp carries, on the row that owns a chip set \u2014 one spelling for 'what does this row do when it does not fit' (gh#741). Opt-in, and the same default for every variant: paint must not decide geometry."
+      },
+      {
+        field: "disallowEmptySelection",
+        local: true,
+        reason: "React Aria's own name for the capability (useToggleGroupState), which this component is built on; neither antd nor Radix names it (docs/DESIGN-AUTHORITY.md). It is not just a state guard: on type=single it DECIDES the ARIA role, because emptiness is the one thing role=group + aria-pressed and role=radiogroup + aria-checked disagree about (gh#744)."
       }
     ]
   },

package/dist/styles/card-layout.css

@@ -85,15 +85,14 @@
 
   [data-slot="card"][data-accent] > [data-slot="card-header"],
   [data-slot="card"][data-accent] > [data-slot="card-content"]:not([data-flush]),
+  [data-slot="card"][data-accent] > [data-slot="card-footer"]:not([data-flush]) {
+    padding-inline-start: calc(var(--card-space-inset) - var(--card-accent-rail-width));
+  }
 
   [data-slot="card"] > [data-slot="card-footer"] {
     margin-block-start: auto;
   }
 
-  [data-slot="card"][data-accent] > [data-slot="card-footer"]:not([data-flush]) {
-    padding-inline-start: calc(var(--card-space-inset) - var(--card-accent-rail-width));
-  }
-
   [data-slot="card"][data-accent][data-accent-placement="perimeter"] {
     border-width: var(--card-accent-perimeter-width);
     border-color: var(--card-accent-color);

package/docs/DESIGN-AUTHORITY.md

@@ -335,6 +335,39 @@ expandable.expandedRowKeys` / `onExpandedRowsChange`. This library already mappe
   role that carries a level without promising the `tree` / `treegrid` arrow-key model. A timeline
   with no `depth > 0` keeps its pre-#724 markup byte for byte.
 
+- **`ToggleGroup.disallowEmptySelection` — React Aria's name, and a deliberate divergence from
+  Radix's MARKUP (gh#744).** antd has no ToggleGroup at all (its nearest controls are `Segmented`
+  and `Radio.Group`, both of which are always-one-selected by construction and name nothing here),
+  and Radix's `ToggleGroup` has no such prop — so there is no antd spelling to port and no Radix
+  spelling to keep. The name is taken from the library this component is actually built on:
+  `react-stately`'s `useToggleGroupState` and `react-aria`'s `AriaToggleButtonGroupProps` both
+  call it `disallowEmptySelection`, and it is already the state hook's own switch, so a second
+  spelling would be a rename of a prop we pass straight through. It is a negative boolean, which
+  the vocabulary otherwise avoids (`allowClear`, `allowEmpty`, `allowEmptySubmit`) — `allowEmpty`
+  was rejected because `RangePicker.allowEmpty` already means `[boolean, boolean]` on the same
+  prop surface, and one word must not carry two shapes.
+
+  The divergence is not the name, it is the markup. Radix's single group emits
+  `role="radiogroup"` / `role="radio"` + `aria-checked` **and still lets the user clear the
+  selection by pressing the checked item again** — React Aria inherited exactly the same shape
+  (`useToggleButtonGroupItem` hardcodes the radio role on `selectionMode === "single"` without
+  ever reading `disallowEmptySelection`). ARIA has no press-again-to-deselect for a radio: a
+  radiogroup that has a selection always has exactly one checked item, so the state a user reaches
+  by pressing the checked chip once more — a radiogroup with nothing checked — is not expressible,
+  and a screen reader reads an empty radio group immediately after the user activated one of its
+  radios. This library's own catalog said as much in two places (`Radio.optionType` and
+  `Segmented`, both of which justify themselves by calling ToggleGroup "a row of aria-pressed
+  buttons" that "permits 'none chosen'"), so the two entries contradicted the ToggleGroup entry
+  about the same case.
+
+  So here the emptiness rule DECIDES the role. Default (`false`, today's behaviour — no existing
+  group changes): `role="group"` + `aria-pressed` per item, and no `aria-orientation`, which
+  `group` does not take. With the prop: `role="radiogroup"` + `role="radio"` / `aria-checked`,
+  the checked item is the single tab stop, and the arrow keys move the SELECTION as APG's
+  radio-group pattern requires rather than only the focus. `type="multiple"` is untouched
+  (`role="toolbar"`, `aria-pressed`); the prop there only keeps the last item selected.
+  Divergence from Radix's markup is the point of the change, not a side effect of it.
+
 **A knob that only a fork could reach is not parity either.** antd's `components`,
 `filterDropdown`, `classNames`/`styles` semantic maps and `prefixCls` all exist to let a consumer
 replace the rendered markup. This library answers that layer with tokens (cardinal rule #45), so

package/docs/data-entry/toggle-group.tsx

@@ -21,6 +21,16 @@ const folderTags = [
   { value: "archive", label: "アーカイブ", count: 311 },
 ];
 
+/** A one-of-N setting: a list always has A sort order, so this row may never be empty (gh#744). */
+const sortOrders = [
+  { value: "updated", label: "更新日" },
+  { value: "created", label: "作成日" },
+  { value: "name", label: "名前" },
+  { value: "size", label: "サイズ" },
+  { value: "owner", label: "所有者" },
+  { value: "relevance", label: "関連度" },
+];
+
 /**
  * ToggleGroup — single or multi-select toggle set. type='single' for mutually
  * exclusive modes; type='multiple' for independent selections. Never raw radio
@@ -31,6 +41,8 @@ export default function Demo() {
   const [formats, setFormats] = useState<string[]>(["pdf"]);
   const [view, setView] = useState<string>("list");
   const [tags, setTags] = useState<string[]>(["design", "runbook"]);
+  const [facet, setFacet] = useState<string>("design");
+  const [sort, setSort] = useState<string>("updated");
 
   return (
     <PageContainer
@@ -50,10 +62,9 @@ export default function Demo() {
             <FormField id="period" label="集計期間">
               <ToggleGroup
                 type="single"
+                disallowEmptySelection
                 value={period}
-                onValueChange={(v) => {
-                  if (v) setPeriod(v);
-                }}
+                onValueChange={setPeriod}
               >
                 <ToggleGroupItem value="daily">日次</ToggleGroupItem>
                 <ToggleGroupItem value="monthly">月次</ToggleGroupItem>
@@ -64,6 +75,76 @@ export default function Demo() {
           </CardContent>
         </Card>
 
+        <Card>
+          <CardHeader>
+            <CardTitle level={2}>disallowEmptySelection · 空を許すかどうかが role を決める</CardTitle>
+            <CardDescription>
+              ARIA には「もう一度押して選択を外す」という radio
+              がない。選択のある radiogroup には必ずちょうど一つ checked
+              な項目があるので、ユーザーが今押したばかりの radiogroup
+              が空になった状態はスクリーンリーダーが読み上げられない。だから空を許すかどうかが
+              role を決める（gh#744）。既定（空を許す）は role=&quot;group&quot; ＋ 各項目
+              aria-pressed で、同じチップをもう一度押せば選択が外れ onValueChange(&quot;&quot;)
+              が飛ぶ。disallowEmptySelection を付けると role=&quot;radiogroup&quot; ＋
+              role=&quot;radio&quot; / aria-checked になり、選択中の項目をもう一度押しても外れず、矢印キーが
+              APG の radio group どおり選択ごと動く。
+            </CardDescription>
+          </CardHeader>
+          <CardContent>
+            <Flex direction="col" gap="md">
+              <Flex direction="col" gap="sm">
+                <Text as="p" size="sm" tone="muted">
+                  既定（空を許す）· タグ絞り込み · role=&quot;group&quot; ＋
+                  aria-pressed。矢印キーはフォーカスだけを動かす
+                </Text>
+                <ToggleGroup
+                  type="single"
+                  variant="soft"
+                  shape="pill"
+                  wrap
+                  value={facet}
+                  onValueChange={(v) => setFacet(v as string)}
+                  aria-label="ファセット絞り込み"
+                >
+                  {folderTags.slice(0, 6).map((tag) => (
+                    <ToggleGroupItem key={tag.value} value={tag.value}>
+                      {tag.label}
+                    </ToggleGroupItem>
+                  ))}
+                </ToggleGroup>
+                <Text as="p" size="sm" tone="muted">
+                  選択中: {facet === "" ? "なし" : facet}
+                </Text>
+              </Flex>
+              <Flex direction="col" gap="sm">
+                <Text as="p" size="sm" tone="muted">
+                  disallowEmptySelection · 並び替え · role=&quot;radiogroup&quot; ＋
+                  aria-checked。タブ位置は選択中の項目ひとつ、矢印キーが選択ごと動く
+                </Text>
+                <ToggleGroup
+                  type="single"
+                  variant="soft"
+                  shape="pill"
+                  wrap
+                  disallowEmptySelection
+                  value={sort}
+                  onValueChange={(v) => setSort(v as string)}
+                  aria-label="並び替え"
+                >
+                  {sortOrders.map((order) => (
+                    <ToggleGroupItem key={order.value} value={order.value}>
+                      {order.label}
+                    </ToggleGroupItem>
+                  ))}
+                </ToggleGroup>
+                <Text as="p" size="sm" tone="muted">
+                  選択中: {sort === "" ? "なし" : sort}
+                </Text>
+              </Flex>
+            </Flex>
+          </CardContent>
+        </Card>
+
         <Card>
           <CardHeader>
             <CardTitle level={2}>Multiple selection (type=“multiple”)</CardTitle>
@@ -98,10 +179,9 @@ export default function Demo() {
           <CardContent>
             <ToggleGroup
               type="single"
+              disallowEmptySelection
               value={view}
-              onValueChange={(v) => {
-                if (v) setView(v);
-              }}
+              onValueChange={setView}
             >
               <ToggleGroupItem value="list">一覧</ToggleGroupItem>
               <ToggleGroupItem value="card">カード</ToggleGroupItem>

package/package.json

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

package/scripts/ui-audit.mjs

@@ -158,6 +158,42 @@ const ATTRS = String.raw`(?:"(?:\\.|[^"\\])*"|'(?:\\.|[^'\\])*'|=>|[^>"'])*`;
  */
 const rawTag = (tag) => new RegExp(`<${tag}(?=[\\s/>])[^\\n]*`, "g");
 
+/**
+ * Is the raw tag at `index` the SLOT CHILD of an `asChild` primitive?
+ *
+ * `<Card asChild hoverable><button onClick={…}>` is not a violation — it is the shape this
+ * package PRESCRIBES. `Card.asChild`'s own docblock says so in as many words:
+ *
+ *     "a card rendered as an `<a>` or a `<button>` measures byte for byte like the `div` it
+ *      replaces and stays a SINGLE tab stop"
+ *
+ * and `hoverable`'s docblock sends the reader there: "the whole card rendered as one via
+ * {@link CardProps.asChild}".
+ *
+ * Reported as gh#740 and closed by shipping `Card asChild` — but the audit was never taught about
+ * it, so a consumer following the fix still got `no-raw-button: error` on the documented answer
+ * (godx-jp/shoots-gemba#8). A package that forbids its own prescription leaves the consumer no
+ * legal move at all, which is exactly what #740 was opened about.
+ *
+ * Walks BACKWARDS to the nearest preceding `>` and asks whether the tag it closes is a
+ * capitalised component carrying `asChild`. That covers both spellings prettier produces —
+ * `<Card asChild><button` on one line, and the attribute wrapped onto its own line — while
+ * `</Card>` or `<div>` before the tag exempts nothing, because neither starts a component.
+ */
+const isAsChildSlot = (content, index) => {
+  const before = content.slice(0, index).replace(/\s+$/, "");
+  if (!before.endsWith(">")) return false;
+  const openStart = before.lastIndexOf("<", before.length - 1);
+  if (openStart === -1) return false;
+  const openTag = before.slice(openStart);
+  // A component, not `</Card>` and not a lowercase host element.
+  return /^<[A-Z][\w.]*\b/.test(openTag) && /\basChild\b/.test(openTag);
+};
+
+/** `rawTag`, minus the matches that are an `asChild` primitive's borrowed element. */
+const rawTagOutsideAsChildSlot = (tag) => (content) =>
+  [...content.matchAll(rawTag(tag))].filter((match) => !isAsChildSlot(content, match.index));
+
 /**
  * @type {{id:string, severity:'error'|'warn', test:RegExp, message:string, standard?:string,
  *         exempt?:RegExp, classOnly?:boolean}[]}
@@ -409,6 +445,12 @@ const RULES = [
     severity: "error",
     spansElement: true,
     test: new RegExp(`<input\\b(?!${ATTRS}\\btype=["']hidden["'])${ATTRS}>`, "g"),
+    matches: (content) =>
+      [
+        ...content.matchAll(
+          new RegExp(`<input\\b(?!${ATTRS}\\btype=["']hidden["'])${ATTRS}>`, "g"),
+        ),
+      ].filter((match) => !isAsChildSlot(content, match.index)),
     message: "Use <Input> from @godxjp/ui, not a raw <input> (rules §3).",
   },
   {
@@ -418,6 +460,7 @@ const RULES = [
     severity: "error",
     spansElement: true,
     test: rawTag("button"),
+    matches: rawTagOutsideAsChildSlot("button"),
     message: "Use <Button> from @godxjp/ui, not a raw <button> (rules §3).",
   },
   {