@astryxdesign/core 0.3.0 → 0.4.0

package/src/Stack/Stack.doc.mjs

@@ -15,6 +15,116 @@ export const docs = {
     ],
   },
   components: [
+    {
+      name: 'Stack',
+      displayName: 'Stack',
+      description:
+        'Unified stack layout component with a direction prop. Use direction="horizontal" for left-to-right flow or direction="vertical" (default) for top-to-bottom. For convenience, HStack and VStack are pre-configured wrappers.',
+      props: [
+        {
+          name: 'direction',
+          type: "'horizontal' | 'vertical'",
+          description:
+            "Direction of the stack layout. 'horizontal' flows items left-to-right (like HStack), 'vertical' flows top-to-bottom (like VStack). Note: the value is 'horizontal', NOT 'row'.",
+          default: "'vertical'",
+        },
+        {
+          name: 'gap',
+          type: '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10',
+          description:
+            'Spacing step (number literal): 0, 0.5, 1, 1.5, 2, 3, 4, 5, 6, 8, 10. Pass as a JSX number expression e.g. gap={4}, NOT a string like gap="4".',
+        },
+        {
+          name: 'padding',
+          type: '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10',
+          description:
+            'Inner padding on all sides, using the spacing scale. Pass as a JSX number expression e.g. padding={3}.',
+        },
+        {
+          name: 'paddingInline',
+          type: '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10',
+          description:
+            'Inline (horizontal) padding. Overrides padding on the inline axis when both are set.',
+        },
+        {
+          name: 'paddingBlock',
+          type: '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10',
+          description:
+            'Block (vertical) padding. Overrides padding on the block axis when both are set.',
+        },
+        {
+          name: 'isScrollable',
+          type: 'boolean',
+          description:
+            'Enables scrollable overflow (overflow: auto).',
+          default: 'false',
+        },
+        {
+          name: 'width',
+          type: 'SizeValue',
+          description: "Width of the stack container. Numbers are treated as pixels, strings are used as-is (e.g., '100%').",
+        },
+        {
+          name: 'height',
+          type: 'SizeValue',
+          description: "Height of the stack container. Numbers are treated as pixels, strings are used as-is (e.g., '100%').",
+        },
+        {
+          name: 'maxWidth',
+          type: 'SizeValue',
+          description: "Maximum width of the stack container.",
+        },
+        {
+          name: 'minHeight',
+          type: 'SizeValue',
+          description: "Minimum height of the stack container.",
+        },
+        {
+          name: 'hAlign',
+          type: "'start' | 'center' | 'end' | 'between' | 'around' | 'evenly' | 'stretch'",
+          description: "Horizontal alignment. When direction='horizontal': main-axis (justify-content). When direction='vertical': cross-axis (align-items).",
+        },
+        {
+          name: 'vAlign',
+          type: "'start' | 'center' | 'end' | 'between' | 'around' | 'evenly' | 'stretch'",
+          description: "Vertical alignment. When direction='horizontal': cross-axis (align-items). When direction='vertical': main-axis (justify-content).",
+        },
+        {
+          name: 'justify',
+          type: "'start' | 'center' | 'end' | 'between' | 'around' | 'evenly'",
+          description: "Main-axis alignment alias. Resolves to hAlign (horizontal) or vAlign (vertical). Note: use 'between', NOT 'space-between'.",
+        },
+        {
+          name: 'align',
+          type: "'start' | 'center' | 'end' | 'stretch'",
+          description: 'Cross-axis alignment alias. Mirrors CSS align-items.',
+        },
+        {
+          name: 'wrap',
+          type: "'nowrap' | 'wrap' | 'wrap-reverse'",
+          description: 'Flex wrap behavior.',
+          default: "'nowrap'",
+        },
+        {
+          name: 'as',
+          type: 'ElementType',
+          description: 'HTML element to render as the stack container.',
+          default: "'div'",
+        },
+        {
+          name: 'children',
+          type: 'ReactNode',
+          description: 'Stack content.',
+        },
+        {
+          name: 'xstyle',
+          type: 'StyleXStyles',
+          description:
+            'StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value, not an inline style object like style={{}}.',
+        },
+      ],
+    },
+
     {
       name: 'HStack',
       isHiddenFromOverview: true,

package/src/StatusDot/StatusDot.doc.mjs

@@ -49,10 +49,13 @@ export const docs = {
     description:
       'A small colored dot that communicates status like online/offline presence or severity levels. Supports five semantic variants and an optional pulse animation. Always pair with a visible text label, as color alone should not carry meaning.',
     bestPractices: [
+      { guidance: true, description: 'Use StatusDot as a binary present/absent signal; avoid encoding many distinct states in a single dot, since color and size alone cannot reliably distinguish them.' },
       { guidance: true, description: 'Always pair with a visible text label so status is not conveyed by color alone.' },
       { guidance: true, description: 'Provide a descriptive `label` prop for screen reader accessibility.' },
+      { guidance: true, description: 'Pair the dot with an icon that carries the status as a distinct shape when it must stand on its own without adjacent text, so meaning survives without color.' },
+      { guidance: true, description: 'If you can\'t add a label or an icon, make sure the status is conveyed elsewhere accessibly (e.g. adjacent text, a table column, or a live region).' },
+      { guidance: false, description: 'Rely on color alone to communicate status; StatusDot is not fully accessible in isolation, so the builder must make the status distinguishable in context via a label, an icon, or an accessible alternative.' },
       { guidance: false, description: 'Use the pulse animation for purely decorative purposes; reserve it for states that require immediate attention.' },
-      { guidance: false, description: 'Rely on color alone to communicate status; always include text.' },
     ],
   },
 };
@@ -97,10 +100,13 @@ export const docsZh = {
     description:
       'A small colored dot that communicates status like online/offline presence or severity levels. Supports five semantic variants and an optional pulse animation. Always pair with a visible text label, as color alone should not carry meaning.',
     bestPractices: [
+      { guidance: true, description: 'Use StatusDot as a binary present/absent signal; avoid encoding many distinct states in a single dot, since color and size alone cannot reliably distinguish them.' },
       { guidance: true, description: 'Always pair with a visible text label so status is not conveyed by color alone.' },
       { guidance: true, description: 'Provide a descriptive `label` prop for screen reader accessibility.' },
+      { guidance: true, description: 'Pair the dot with an icon that carries the status as a distinct shape when it must stand on its own without adjacent text, so meaning survives without color.' },
+      { guidance: true, description: 'If you can\'t add a label or an icon, make sure the status is conveyed elsewhere accessibly (e.g. adjacent text, a table column, or a live region).' },
+      { guidance: false, description: 'Rely on color alone to communicate status; StatusDot is not fully accessible in isolation, so the builder must make the status distinguishable in context via a label, an icon, or an accessible alternative.' },
       { guidance: false, description: 'Use the pulse animation for purely decorative purposes; reserve it for states that require immediate attention.' },
-      { guidance: false, description: 'Rely on color alone to communicate status; always include text.' },
     ],
   },
 };
@@ -112,10 +118,13 @@ export const docsDense = {
     description:
       'A small colored dot that communicates status like online/offline presence or severity levels. Supports five semantic variants and an optional pulse animation. Always pair with a visible text label, as color alone should not carry meaning.',
     bestPractices: [
+      { guidance: true, description: 'Use StatusDot as a binary present/absent signal; avoid encoding many distinct states in a single dot, since color and size alone cannot reliably distinguish them.' },
       { guidance: true, description: 'Always pair with a visible text label so status is not conveyed by color alone.' },
       { guidance: true, description: 'Provide a descriptive `label` prop for screen reader accessibility.' },
+      { guidance: true, description: 'Pair the dot with an icon that carries the status as a distinct shape when it must stand on its own without adjacent text, so meaning survives without color.' },
+      { guidance: true, description: 'If you can\'t add a label or an icon, make sure the status is conveyed elsewhere accessibly (e.g. adjacent text, a table column, or a live region).' },
+      { guidance: false, description: 'Rely on color alone to communicate status; StatusDot is not fully accessible in isolation, so the builder must make the status distinguishable in context via a label, an icon, or an accessible alternative.' },
       { guidance: false, description: 'Use the pulse animation for purely decorative purposes; reserve it for states that require immediate attention.' },
-      { guidance: false, description: 'Rely on color alone to communicate status; always include text.' },
     ],
   },
   propDescriptions: {

package/src/Switch/Switch.test.tsx

@@ -636,6 +636,38 @@ describe('Switch', () => {
       expect(data.get('notify')).toBe('on');
     });
 
+    it('does not block form submission when required and disabled with a disabledMessage', () => {
+      const {container} = render(
+        <form>
+          <Switch
+            label="Notify"
+            htmlName="notify"
+            value={false}
+            onChange={() => {}}
+            isRequired
+            isDisabled
+            disabledMessage="Notifications are turned off org-wide"
+          />
+        </form>,
+      );
+      expect(container.querySelector('form')!.checkValidity()).toBe(true);
+    });
+
+    it('still blocks submission when required and off but enabled', () => {
+      const {container} = render(
+        <form>
+          <Switch
+            label="Notify"
+            htmlName="notify"
+            value={false}
+            onChange={() => {}}
+            isRequired
+          />
+        </form>,
+      );
+      expect(container.querySelector('form')!.checkValidity()).toBe(false);
+    });
+
     it('is excluded from form data when disabled, even with a disabledMessage', () => {
       const {container} = render(
         <form>

package/src/Switch/Switch.tsx

@@ -523,6 +523,7 @@ export function Switch({
         // isDisabled guard in onChange below.
         disabled={isDisabled && !showsDisabledMessage}
         aria-disabled={showsDisabledMessage ? 'true' : undefined}
+        form={showsDisabledMessage ? '' : undefined}
         required={isRequired}
         onChange={e => {
           if (isDisabled || isBusy) {
@@ -643,14 +644,13 @@ export function Switch({
         )}
       </div>
       {status?.message && (
-        <div {...stylex.props(styles.statusGap)}>
-          <FieldStatus
-            type={status.type}
-            message={status.message}
-            id={statusMessageID}
-            variant="detached"
-          />
-        </div>
+        <FieldStatus
+          type={status.type}
+          message={status.message}
+          id={statusMessageID}
+          variant="detached"
+          xstyle={styles.statusGap}
+        />
       )}
       {showsDisabledMessage &&
         disabledMessageTooltip.renderTooltip(disabledMessage)}

package/src/TabList/Tab.tsx

@@ -37,6 +37,7 @@ import type {LinkComponentType} from '../Link/types';
 import {mergeProps} from '../utils';
 import {EDGE_COMP_ATTR} from '../Layout/edgeCompensation.stylex';
 import {themeProps} from '../utils/themeProps';
+import {focusOutlineProps} from '../utils/focusOutline.stylex';
 
 export interface TabProps extends BaseProps<HTMLButtonElement> {
   /**
@@ -106,14 +107,6 @@ const styles = stylex.create({
     transitionProperty: 'color',
     transitionDuration: durationVars['--duration-fast'],
     transitionTimingFunction: easeVars['--ease-standard'],
-    outline: {
-      default: null,
-      ':focus-visible': `2px solid ${colorVars['--color-accent']}`,
-    },
-    outlineOffset: {
-      default: '0',
-      ':focus-visible': '2px',
-    },
   },
   hoverBg: {
     position: 'absolute',
@@ -274,7 +267,7 @@ export function Tab({
       themeProps('tab', {
         selected: isSelected ? 'selected' : null,
       }),
-      stylex.props(
+      focusOutlineProps.focusVisible(
         styles.base,
         sizeStyles[size],
         isSelected && styles.selected,

package/src/TabList/TabMenu.tsx

@@ -30,6 +30,7 @@ import {
   fontWeightVars,
   typeScaleVars,
 } from '../theme/tokens.stylex';
+import {focusOutlineProps} from '../utils/focusOutline.stylex';
 import {usePopover} from '../Popover/usePopover';
 import {MENU_ITEM_SELECTOR} from '../DropdownMenu/menuItemRoles';
 import {useListFocus} from '../hooks/useListFocus';
@@ -91,14 +92,6 @@ const styles = stylex.create({
     transitionProperty: 'color',
     transitionDuration: durationVars['--duration-fast'],
     transitionTimingFunction: easeVars['--ease-standard'],
-    outline: {
-      default: null,
-      ':focus-visible': `2px solid ${colorVars['--color-accent']}`,
-    },
-    outlineOffset: {
-      default: '0',
-      ':focus-visible': '2px',
-    },
   },
   triggerSelected: {
     color: colorVars['--color-text-primary'],
@@ -161,6 +154,10 @@ const styles = stylex.create({
     width: spacingVars['--spacing-4'],
     height: spacingVars['--spacing-4'],
     flexShrink: 0,
+  },
+  // Applied to the chevron <Icon> (via `xstyle`) rather than its wrapper, so the
+  // element that rotates is the element a theme targets.
+  chevronIcon: {
     transitionProperty: 'transform',
     transitionDuration: durationVars['--duration-fast'],
     transitionTimingFunction: easeVars['--ease-standard'],
@@ -198,10 +195,6 @@ const styles = stylex.create({
         '@media (hover: hover)': colorVars['--color-overlay-hover'],
       },
     },
-    outline: {
-      default: null,
-      ':focus-visible': `2px solid ${colorVars['--color-accent']}`,
-    },
   },
   menuItemSelected: {
     fontWeight: fontWeightVars['--font-weight-medium'],
@@ -356,7 +349,7 @@ export function TabMenu({
         onClick={handleToggle}
         {...mergeProps(
           themeProps('tab-menu'),
-          stylex.props(
+          focusOutlineProps.focusVisible(
             styles.trigger,
             sizeStyles[size],
             hasSelectedOption && styles.triggerSelected,
@@ -376,13 +369,13 @@ export function TabMenu({
             {triggerLabel}
           </span>
         </span>
-        <span
-          aria-hidden="true"
-          {...stylex.props(
-            styles.chevron,
-            popover.isOpen && styles.chevronOpen,
-          )}>
-          <Icon icon="chevronDown" size="sm" color="inherit" />
+        <span aria-hidden="true" {...stylex.props(styles.chevron)}>
+          <Icon
+            icon="chevronDown"
+            size="sm"
+            color="inherit"
+            xstyle={[styles.chevronIcon, popover.isOpen && styles.chevronOpen]}
+          />
         </span>
         {hasSelectedOption && (
           <span
@@ -429,7 +422,7 @@ export function TabMenu({
                 }}
                 {...mergeProps(
                   themeProps('tab-menu-item'),
-                  stylex.props(
+                  focusOutlineProps.focusVisible(
                     styles.menuItem,
                     isSelected && styles.menuItemSelected,
                   ),

package/src/Table/BaseTable.tsx

@@ -243,6 +243,17 @@ function TableRowInner<T extends Record<string, unknown>>({
     </RowComponent>
   );
 
+  // afterRow: plugins (e.g. row expansion) can append a full-width detail
+  // panel `<tr>` after the row. Rendered as a sibling fragment.
+  if (rowRenderProps.afterRow) {
+    return (
+      <>
+        {row}
+        {rowRenderProps.afterRow}
+      </>
+    );
+  }
+
   return row;
 }
 

package/src/Table/index.ts

@@ -28,11 +28,8 @@ export {useTableColumnResize} from './plugins/columnResize';
 export {useTableStickyColumns} from './plugins/stickyColumns';
 export {useTableGroupedRows} from './plugins/groupedRows';
 export {useTableRowIndex} from './plugins/rowIndex';
-export {
-  useTableRowExpansion,
-  useTableRowExpansionState,
-} from './plugins/rowExpansion';
 export {useTableRowStatus} from './plugins/rowStatus';
+export {useTableRowExpansion} from './plugins/rowExpansion';
 export {useTableTreeData, useTableTreeState} from './plugins/tree';
 export {resolveContextActions} from './tableContextMenu';
 export {

package/src/Table/plugins/groupedRows/useTableGroupedRows.tsx

@@ -20,7 +20,6 @@ import {
   fontWeightVars,
 } from '../../../theme/tokens.stylex';
 import {Icon} from '../../../Icon';
-import {rtlStyles} from '../../../utils';
 import type {TablePlugin} from '../../types';
 import {useTranslator} from '../../../i18n';
 
@@ -153,12 +152,25 @@ const styles = stylex.create({
     },
   },
   chevronIcon: {
-    display: 'inline-flex',
     transitionProperty: 'transform',
     transitionDuration: '150ms',
   },
-  chevronExpanded: {
-    transform: 'rotate(90deg)',
+  // The RTL mirror is folded into each state's transform rather than living on
+  // a parent span. Both are `transform`, so on one element the later value
+  // would win — spelling out `scaleX(-1) rotate(...)` per state composes them
+  // exactly as the nested elements did, while leaving a single element to
+  // carry the glyph's theme target.
+  chevronIconCollapsed: {
+    transform: {
+      default: 'rotate(0deg)',
+      ':is([dir="rtl"] *)': 'scaleX(-1) rotate(0deg)',
+    },
+  },
+  chevronIconExpanded: {
+    transform: {
+      default: 'rotate(90deg)',
+      ':is([dir="rtl"] *)': 'scaleX(-1) rotate(90deg)',
+    },
   },
   // Emphasized body text — same size as body, heavier weight (Ernest #3).
   label: {
@@ -178,7 +190,7 @@ const styles = stylex.create({
  * data rows while keeping the header visible.
  *
  * Mirrors other controlled Table state helpers: the consumer owns the
- * `collapsedGroups` set and this hook returns `{data, plugin, idKey}` —
+ * `collapsedGroups` set and this hook returns `{data, plugin, idKey}`:
  * pass all three to `<Table>`.
  *
  * @example
@@ -334,15 +346,19 @@ export function useTableGroupedRows<T extends Record<string, unknown>>(
                         })
                   }
                   aria-expanded={!collapsed}>
-                  <span {...stylex.props(rtlStyles.mirror)}>
-                    <span
-                      {...stylex.props(
-                        styles.chevronIcon,
-                        !collapsed && styles.chevronExpanded,
-                      )}>
-                      <Icon icon="chevronRight" size="xsm" />
-                    </span>
-                  </span>
+                  <Icon
+                    icon="chevronRight"
+                    size="xsm"
+                    // The rotation rides on the glyph rather than a wrapper
+                    // span so the theme target below reaches both the mark and
+                    // its open/closed transform.
+                    xstyle={[
+                      styles.chevronIcon,
+                      collapsed
+                        ? styles.chevronIconCollapsed
+                        : styles.chevronIconExpanded,
+                    ]}
+                  />
                 </button>
                 {content}
               </span>

package/src/Table/plugins/rowExpansion/index.ts

@@ -1,7 +1,4 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-export {
-  useTableRowExpansion,
-  useTableRowExpansionState,
-} from './useTableRowExpansion';
+export {useTableRowExpansion} from './useTableRowExpansion';
 export type {UseTableRowExpansionConfig} from './useTableRowExpansion';