@astryxdesign/core 0.7.7 → 0.7.8-canary.36cde5e

package/src/FormLayout/FormLayout.doc.mjs

@@ -7,7 +7,16 @@ export const docs = {
   displayName: 'Form Layout',
   group: 'Layout',
   category: 'Layout',
-  keywords: ["formlayout","form","fieldset","formgroup","formcontainer","fields","vertical","horizontal"],
+  keywords: [
+    'formlayout',
+    'form',
+    'fieldset',
+    'formgroup',
+    'formcontainer',
+    'fields',
+    'vertical',
+    'horizontal',
+  ],
   props: [
     {
       name: 'direction',
@@ -20,7 +29,7 @@ export const docs = {
       name: 'defaultOptionality',
       type: "'optional' | 'required'",
       description:
-        'The state the form treats as its default, so only the exception shows an optional/required indicator. With "optional", only fields marked isRequired show an indicator; with "required", only fields marked isOptional do. A field that restates the default shows nothing. Under "required" the unmarked fields also expose aria-required so screen readers match the visual default; aria-required only, never the native required attribute. Leave unset for today\'s per-field behavior.',
+        'The state the form treats as its default, so only the exception shows an optional/required indicator. With "optional", only fields marked isRequired show an indicator; with "required", only fields marked isOptional do. A field that restates the default shows nothing. Under "required" the unmarked fields also expose aria-required so screen readers match the visual default; aria-required only, never the native required attribute. CheckboxInput, Switch and CheckboxList are the exception: an unchecked box, an off switch or an empty group is an answer, so they take no required state from the default. A CheckboxInput or Switch is required only through its own isRequired. Leave unset for today\'s per-field behavior.',
     },
     {
       name: 'children',
@@ -36,25 +45,65 @@ export const docs = {
     },
   ],
   theming: {
-    targets: [
-      {className: 'astryx-form-layout', visualProps: ['direction']},
-    ],
+    targets: [{className: 'astryx-form-layout', visualProps: ['direction']}],
   },
   usage: {
-    description: 'A layout container that arranges form fields with consistent spacing and direction. FormLayout handles where fields go, not state or submission. Wrap it in a <form> for that. Supports vertical (default), horizontal, and horizontal-labels directions, and can be nested to mix them.',
+    description:
+      'A layout container that arranges form fields with consistent spacing and direction. FormLayout handles where fields go, not state or submission. Wrap it in a <form> for that. Supports vertical (default), horizontal, and horizontal-labels directions, and can be nested to mix them.',
     bestPractices: [
-      { guidance: true, description: 'Stack fields vertically for most forms. It\'s the easiest to scan top to bottom.' },
-      { guidance: true, description: 'Nest a horizontal FormLayout inside a vertical one when fields naturally pair up, like First Name + Last Name or City + State + ZIP.' },
-      { guidance: true, description: 'Use horizontal-labels for settings pages where labels sit beside their inputs.' },
-      { guidance: false, description: 'Use FormLayout for form state or submission. It\'s just layout. Wrap it in a <form> for that.' },
-      { guidance: false, description: 'Put unrelated fields side by side in a horizontal layout. Save it for fields that belong together.' },
-      { guidance: false, description: 'Nest horizontal-labels inside another FormLayout. It uses CSS Grid and needs to be the outermost container.' },
+      {
+        guidance: true,
+        description:
+          "Stack fields vertically for most forms. It's the easiest to scan top to bottom.",
+      },
+      {
+        guidance: true,
+        description:
+          'Nest a horizontal FormLayout inside a vertical one when fields naturally pair up, like First Name + Last Name or City + State + ZIP.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use horizontal-labels for settings pages where labels sit beside their inputs.',
+      },
+      {
+        guidance: false,
+        description:
+          "Use FormLayout for form state or submission. It's just layout. Wrap it in a <form> for that.",
+      },
+      {
+        guidance: false,
+        description:
+          'Put unrelated fields side by side in a horizontal layout. Save it for fields that belong together.',
+      },
+      {
+        guidance: false,
+        description:
+          'Nest horizontal-labels inside another FormLayout. It uses CSS Grid and needs to be the outermost container.',
+      },
     ],
     anatomy: [
-      {name: 'Layout container', required: true, description: 'Owns field arrangement, spacing, direction, and form-level optionality.'},
-      {name: 'Form title', required: false, description: 'Heading that describes the purpose of the form.'},
-      {name: 'Fields', required: true, description: 'Input components with labels for collecting user data.'},
-      {name: 'Footer', required: false, description: 'Contains confirmation buttons such as Submit or Cancel.'},
+      {
+        name: 'Layout container',
+        required: true,
+        description:
+          'Owns field arrangement, spacing, direction, and form-level optionality.',
+      },
+      {
+        name: 'Form title',
+        required: false,
+        description: 'Heading that describes the purpose of the form.',
+      },
+      {
+        name: 'Fields',
+        required: true,
+        description: 'Input components with labels for collecting user data.',
+      },
+      {
+        name: 'Footer',
+        required: false,
+        description: 'Contains confirmation buttons such as Submit or Cancel.',
+      },
     ],
   },
 };
@@ -75,7 +124,7 @@ export const docsZh = {
       name: 'defaultOptionality',
       type: "'optional' | 'required'",
       description:
-        '表单视为默认的状态，因此仅例外字段显示可选/必填指示器。设为 "optional" 时，仅标记 isRequired 的字段显示指示器；设为 "required" 时，仅标记 isOptional 的字段显示。与默认一致的字段不显示任何内容。设为 "required" 时，未标记的字段仍会暴露 aria-required，使屏幕阅读器与视觉默认一致——仅作用于 aria-required，不改变原生 required 属性。不设置则保持当前逐字段行为。',
+        '表单视为默认的状态，因此仅例外字段显示可选/必填指示器。设为 "optional" 时，仅标记 isRequired 的字段显示指示器；设为 "required" 时，仅标记 isOptional 的字段显示。与默认一致的字段不显示任何内容。设为 "required" 时，未标记的字段仍会暴露 aria-required，使屏幕阅读器与视觉默认一致——仅作用于 aria-required，不改变原生 required 属性。CheckboxInput、Switch 和 CheckboxList 例外：未勾选的复选框、关闭的开关或空的复选框组本身就是一个回答，因此默认值不会赋予它们必填状态。CheckboxInput 或 Switch 只有通过自身的 isRequired 才会成为必填。不设置则保持当前逐字段行为。',
     },
     {
       name: 'children',
@@ -91,25 +140,65 @@ export const docsZh = {
     },
   ],
   theming: {
-    targets: [
-      {className: 'astryx-form-layout', visualProps: ['direction']},
-    ],
+    targets: [{className: 'astryx-form-layout', visualProps: ['direction']}],
   },
   usage: {
-    description: 'A layout container that arranges form fields with consistent spacing and direction. FormLayout handles where fields go, not state or submission. Wrap it in a <form> for that. Supports vertical (default), horizontal, and horizontal-labels directions, and can be nested to mix them.',
+    description:
+      'A layout container that arranges form fields with consistent spacing and direction. FormLayout handles where fields go, not state or submission. Wrap it in a <form> for that. Supports vertical (default), horizontal, and horizontal-labels directions, and can be nested to mix them.',
     bestPractices: [
-      { guidance: true, description: 'Stack fields vertically for most forms. It\'s the easiest to scan top to bottom.' },
-      { guidance: true, description: 'Nest a horizontal FormLayout inside a vertical one when fields naturally pair up, like First Name + Last Name or City + State + ZIP.' },
-      { guidance: true, description: 'Use horizontal-labels for settings pages where labels sit beside their inputs.' },
-      { guidance: false, description: 'Use FormLayout for form state or submission. It\'s just layout. Wrap it in a <form> for that.' },
-      { guidance: false, description: 'Put unrelated fields side by side in a horizontal layout. Save it for fields that belong together.' },
-      { guidance: false, description: 'Nest horizontal-labels inside another FormLayout. It uses CSS Grid and needs to be the outermost container.' },
+      {
+        guidance: true,
+        description:
+          "Stack fields vertically for most forms. It's the easiest to scan top to bottom.",
+      },
+      {
+        guidance: true,
+        description:
+          'Nest a horizontal FormLayout inside a vertical one when fields naturally pair up, like First Name + Last Name or City + State + ZIP.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use horizontal-labels for settings pages where labels sit beside their inputs.',
+      },
+      {
+        guidance: false,
+        description:
+          "Use FormLayout for form state or submission. It's just layout. Wrap it in a <form> for that.",
+      },
+      {
+        guidance: false,
+        description:
+          'Put unrelated fields side by side in a horizontal layout. Save it for fields that belong together.',
+      },
+      {
+        guidance: false,
+        description:
+          'Nest horizontal-labels inside another FormLayout. It uses CSS Grid and needs to be the outermost container.',
+      },
     ],
     anatomy: [
-      {name: 'Layout container', required: true, description: 'Owns field arrangement, spacing, direction, and form-level optionality.'},
-      {name: 'Form title', required: false, description: 'Heading that describes the purpose of the form.'},
-      {name: 'Fields', required: true, description: 'Input components with labels for collecting user data.'},
-      {name: 'Footer', required: false, description: 'Contains confirmation buttons such as Submit or Cancel.'},
+      {
+        name: 'Layout container',
+        required: true,
+        description:
+          'Owns field arrangement, spacing, direction, and form-level optionality.',
+      },
+      {
+        name: 'Form title',
+        required: false,
+        description: 'Heading that describes the purpose of the form.',
+      },
+      {
+        name: 'Fields',
+        required: true,
+        description: 'Input components with labels for collecting user data.',
+      },
+      {
+        name: 'Footer',
+        required: false,
+        description: 'Contains confirmation buttons such as Submit or Cancel.',
+      },
     ],
   },
 };
@@ -119,26 +208,72 @@ export const docsDense = {
   description:
     'Layout container for form fields w/ consistent spacing + direction.',
   usage: {
-    description: 'A layout container that arranges form fields with consistent spacing and direction. FormLayout handles where fields go, not state or submission. Wrap it in a <form> for that. Supports vertical (default), horizontal, and horizontal-labels directions, and can be nested to mix them.',
+    description:
+      'A layout container that arranges form fields with consistent spacing and direction. FormLayout handles where fields go, not state or submission. Wrap it in a <form> for that. Supports vertical (default), horizontal, and horizontal-labels directions, and can be nested to mix them.',
     bestPractices: [
-      { guidance: true, description: 'Stack fields vertically for most forms. It\'s the easiest to scan top to bottom.' },
-      { guidance: true, description: 'Nest a horizontal FormLayout inside a vertical one when fields naturally pair up, like First Name + Last Name or City + State + ZIP.' },
-      { guidance: true, description: 'Use horizontal-labels for settings pages where labels sit beside their inputs.' },
-      { guidance: false, description: 'Use FormLayout for form state or submission. It\'s just layout. Wrap it in a <form> for that.' },
-      { guidance: false, description: 'Put unrelated fields side by side in a horizontal layout. Save it for fields that belong together.' },
-      { guidance: false, description: 'Nest horizontal-labels inside another FormLayout. It uses CSS Grid and needs to be the outermost container.' },
+      {
+        guidance: true,
+        description:
+          "Stack fields vertically for most forms. It's the easiest to scan top to bottom.",
+      },
+      {
+        guidance: true,
+        description:
+          'Nest a horizontal FormLayout inside a vertical one when fields naturally pair up, like First Name + Last Name or City + State + ZIP.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use horizontal-labels for settings pages where labels sit beside their inputs.',
+      },
+      {
+        guidance: false,
+        description:
+          "Use FormLayout for form state or submission. It's just layout. Wrap it in a <form> for that.",
+      },
+      {
+        guidance: false,
+        description:
+          'Put unrelated fields side by side in a horizontal layout. Save it for fields that belong together.',
+      },
+      {
+        guidance: false,
+        description:
+          'Nest horizontal-labels inside another FormLayout. It uses CSS Grid and needs to be the outermost container.',
+      },
     ],
     anatomy: [
-      {name: 'Layout container', required: true, description: 'Owns field arrangement, spacing, direction, and form-level optionality.'},
-      {name: 'Form title', required: false, description: 'Heading that describes the purpose of the form.'},
-      {name: 'Fields', required: true, description: 'Input components with labels for collecting user data.'},
-      {name: 'Footer', required: false, description: 'Contains confirmation buttons such as Submit or Cancel.'},
+      {
+        name: 'Layout container',
+        required: true,
+        description:
+          'Owns field arrangement, spacing, direction, and form-level optionality.',
+      },
+      {
+        name: 'Form title',
+        required: false,
+        description: 'Heading that describes the purpose of the form.',
+      },
+      {
+        name: 'Fields',
+        required: true,
+        description: 'Input components with labels for collecting user data.',
+      },
+      {
+        name: 'Footer',
+        required: false,
+        description: 'Contains confirmation buttons such as Submit or Cancel.',
+      },
     ],
   },
   propDescriptions: {
-    direction: 'Field arrangement. Vertical stacks top-to-bottom; horizontal uses one fractional grid track per field in logical inline order; horizontal-labels places labels on the inline-start side and collapses when the viewport is <=480px.',
-    defaultOptionality: 'State the form treats as default, so only the exception is marked. "optional" → only isRequired fields show an indicator; "required" → only isOptional fields do. Under "required" unmarked fields also expose aria-required (aria only, not native required). Unset = per-field behavior.',
-    children: 'Form fields to arrange. Accepts Astryx inputs + Field-wrapped custom controls.',
-    xstyle: 'StyleX styles for layout customization. Must be stylex.create() value.',
+    direction:
+      'Field arrangement. Vertical stacks top-to-bottom; horizontal uses one fractional grid track per field in logical inline order; horizontal-labels places labels on the inline-start side and collapses when the viewport is <=480px.',
+    defaultOptionality:
+      'State the form treats as default, so only the exception is marked. "optional" → only isRequired fields show an indicator; "required" → only isOptional fields do. Under "required" unmarked fields also expose aria-required (aria only, not native required), except CheckboxInput, Switch and CheckboxList, which take no required state from it (CheckboxInput and Switch are required only through their own isRequired). Unset = per-field behavior.',
+    children:
+      'Form fields to arrange. Accepts Astryx inputs + Field-wrapped custom controls.',
+    xstyle:
+      'StyleX styles for layout customization. Must be stylex.create() value.',
   },
 };

package/src/FormLayout/FormLayout.tsx

@@ -103,7 +103,11 @@ export interface FormLayoutProps extends BaseProps<HTMLDivElement> {
    *   shows an indicator (the "required" one).
    * - `'required'` — fields read as required; only a field with `isOptional`
    *   shows an indicator (the "optional" one). Fields without `isOptional`
-   *   expose `aria-required` even though they show no indicator.
+   *   expose `aria-required` even though they show no indicator. Checkboxes,
+   *   switches and checkbox groups are the exception: an unchecked box, an off
+   *   switch or an empty group is an answer, so they take no required state
+   *   from the default. A checkbox or switch is required only through its own
+   *   `isRequired`.
    * - unset — today's behavior: `isRequired` and `isOptional` each show their
    *   own indicator independently.
    *

package/src/HoverCard/HoverCard.doc.mjs

@@ -54,7 +54,7 @@ export const docs = {
           name: 'children',
           type: 'ReactNode',
           description:
-            'The trigger. A single string or number is wrapped in a focusable inline span. Text that reaches HoverCard in several pieces, such as `Edited {when}`, gets no trigger, so pass one string, such as a template literal, or wrap it in a focusable element. With element children, HoverCard wires the first element, so that element does not need to accept a ref.',
+            'The trigger. Text children, a string or number or text written around an expression such as `Edited {when}`, are wrapped in a focusable inline span; holes such as `false` and `null` are ignored. With element children, HoverCard wires the first element, so that element does not need to accept a ref.',
         },
         {
           name: 'content',
@@ -98,7 +98,8 @@ export const docs = {
         {
           name: 'focusTrigger',
           type: "'auto' | 'always' | 'never'",
-          description: 'Controls when focus events trigger the hover card.',
+          description:
+            'When focus should open the hover card. auto opens when the trigger itself takes focus, or focus lands inside a trigger that is focusable at that moment, so a roving-tabindex member opens when the arrow keys reach it.',
           default: "'auto'",
         },
         {
@@ -130,7 +131,7 @@ export const docs = {
           name: 'hasHoverIndication',
           type: "'auto' | boolean",
           description:
-            'Shows a dashed underline on a text trigger. auto shows it when children is a single string or number. It has no effect on an element trigger, which keeps its own styling.',
+            'Shows a dashed underline on a text trigger. auto shows it when children is text: strings and numbers, such as `Edited {when}`, with holes such as `false` and `null` ignored. It has no effect on an element trigger, which keeps its own styling.',
           default: "'auto'",
         },
         {
@@ -266,7 +267,7 @@ export const docsZh = {
           name: 'children',
           type: 'ReactNode',
           description:
-            '触发元素。单个字符串或数字会被包裹在可聚焦的内联 span 中。分成多段到达的文本（例如 `Edited {when}`）不会得到触发器，请传入单个字符串（例如模板字符串）或用可聚焦元素包裹。传入元素时，HoverCard 连接第一个元素，因此该元素无需接受 ref。',
+            '触发元素。文本子元素（字符串或数字，或围绕表达式书写的文本，例如 `Edited {when}`）会被包裹在可聚焦的内联 span 中；`false`、`null` 等空位会被忽略。传入元素时，HoverCard 连接第一个元素，因此该元素无需接受 ref。',
         },
         {
           name: 'content',
@@ -303,7 +304,8 @@ export const docsZh = {
         {
           name: 'focusTrigger',
           type: "'auto' | 'always' | 'never'",
-          description: '控制焦点事件何时触发悬浮卡片。',
+          description:
+            '焦点何时打开悬浮卡片。auto 在触发元素自身获得焦点，或焦点落在当时可聚焦的触发元素内部时打开，因此方向键到达漫游 tabindex 成员时也会打开。',
           default: "'auto'",
         },
         {
@@ -335,7 +337,7 @@ export const docsZh = {
           name: 'hasHoverIndication',
           type: "'auto' | boolean",
           description:
-            '在文本触发元素上显示虚线下划线。auto：当 children 是单个字符串或数字时显示。对元素触发器无效，元素保留自身样式。',
+            '在文本触发元素上显示虚线下划线。auto：当 children 是文本（字符串和数字，例如 `Edited {when}`，忽略 `false`、`null` 等空位）时显示。对元素触发器无效，元素保留自身样式。',
           default: "'auto'",
         },
         {
@@ -474,7 +476,7 @@ export const docsDense = {
         'Component wrapper for hover card overlay; richer overlay triggered on hover/focus.',
       propDescriptions: {
         children:
-          'Trigger. A single string/number is wrapped in a focusable inline span; text in several pieces (`Edited {when}`) gets no trigger; pass one string or a focusable element. With elements, the first element is wired (no ref needed).',
+          'Trigger. Text children (strings/numbers, incl. `Edited {when}`; holes like false/null ignored) are wrapped in a focusable inline span. With elements, the first element is wired (no ref needed).',
         content: 'Hover card content.',
         placement:
           "Position relative to anchor element. Logical: start/end follow the popover's inherited direction (RTL mirrors).",
@@ -491,7 +493,7 @@ export const docsDense = {
         onOpenChange:
           'Callback when visibility changes; true=shown, false=hidden.',
         hasHoverIndication:
-          'Dashed underline on a text trigger. auto = single string/number children; no effect on element triggers.',
+          'Dashed underline on a text trigger. auto = text children (strings/numbers, holes ignored); no effect on element triggers.',
         isDefaultOpen: 'Show hover card on mount. Still dismissible.',
         isOpen:
           'Controlled open state. true holds open; false holds closed against hover, but trigger focus still opens it. Escape calls onOpenChange(false) without closing; setting false returns focus inside the card to the trigger.',

package/src/HoverCard/HoverCard.tsx

@@ -16,7 +16,15 @@
  * - /packages/cli/assets/templates/blocks/components/HoverCard/ (showcase blocks)
  */
 
-import {useCallback, useRef, type ReactElement, type ReactNode} from 'react';
+import {
+  useCallback,
+  useRef,
+  useState,
+  type ReactElement,
+  type ReactNode,
+} from 'react';
+import {isRenderable} from '../utils/isRenderable';
+import {observeMutations} from '../utils/sharedMutationObserver';
 import {useIsomorphicLayoutEffect} from '../hooks/useIsomorphicLayoutEffect';
 import * as stylex from '@stylexjs/stylex';
 import {
@@ -148,9 +156,10 @@ export interface HoverCardProps extends Pick<
 
   /**
    * When to trigger on focus:
-   * - `auto`: Only if element is naturally focusable
-   * - `always`: Always attach focus listeners
-   * - `never`: Never attach focus listeners (for composite widgets)
+   * - `auto`: focus on the trigger itself, or within a trigger that is
+   *   focusable when focus arrives
+   * - `always`: focus on the trigger or anything inside it
+   * - `never`: never on focus (for composite widgets)
    *
    * @default 'auto'
    */
@@ -193,7 +202,8 @@ export interface HoverCardProps extends Pick<
   /**
    * Whether to show hover indication (dashed underline) on a text trigger.
    * An element trigger keeps its own styling, so this has no effect on it.
-   * - `'auto'`: Show when children is a single string or number
+   * - `'auto'`: Show when children is text: strings and numbers, such as
+   *   `Edited {when}`, with holes such as `false` and `null` ignored
    * - `true`: Show on a text trigger
    * - `false`: Never show
    *
@@ -227,7 +237,26 @@ export interface HoverCardProps extends Pick<
  * Check if children are text-only (no React elements)
  */
 function isTextOnly(children: ReactNode): boolean {
-  return typeof children === 'string' || typeof children === 'number';
+  if (typeof children === 'string' || typeof children === 'number') {
+    return true;
+  }
+  // Text written around an expression, such as `Edited {when}`, reaches React
+  // as several strings. Holes that render nothing do not change that; one
+  // element does.
+  if (!Array.isArray(children)) {
+    return false;
+  }
+  let hasText = false;
+  for (const child of children.flat(Infinity) as ReactNode[]) {
+    if (!isRenderable(child)) {
+      continue;
+    }
+    if (typeof child !== 'string' && typeof child !== 'number') {
+      return false;
+    }
+    hasText = true;
+  }
+  return hasText;
 }
 
 /**
@@ -303,6 +332,28 @@ export function HoverCard({
     onHide: handleHide,
   });
 
+  // The wrapper's first element is the trigger, and it can be replaced after
+  // mount: by new children, or by a child component that swaps its own root
+  // without a render here. Syncs with the DOM: on a replacement the wiring
+  // below re-runs, so the old element is released before the new one is wired.
+  const [triggerReplacements, setTriggerReplacements] = useState(0);
+  const observedTriggerRef = useRef<Element | null>(null);
+  useIsomorphicLayoutEffect(() => {
+    const wrapper = wrapperRef.current;
+    if (textOnly || wrapper == null) {
+      return;
+    }
+    observedTriggerRef.current = wrapper.firstElementChild;
+    return observeMutations(wrapper, {childList: true}, () => {
+      const trigger = wrapper.firstElementChild;
+      if (trigger === observedTriggerRef.current) {
+        return;
+      }
+      observedTriggerRef.current = trigger;
+      setTriggerReplacements(count => count + 1);
+    });
+  }, [textOnly]);
+
   // For element children with display:contents, attach ref to first child
   useIsomorphicLayoutEffect(() => {
     if (textOnly) {
@@ -407,6 +458,7 @@ export function HoverCard({
     hoverCard.id,
     hoverCard.isOpen,
     hoverCard.describedBy,
+    triggerReplacements,
   ]);
 
   // While closed, useLayer leaves only an inert <template> marker at this JSX