@astryxdesign/core 0.4.0 → 0.4.1-canary.8138bfc

package/src/SideNav/SideNav.tsx

@@ -36,6 +36,7 @@ import {mergeProps, mergeRefs} from '../utils';
 import {
   SideNavCollapseContext,
   type SideNavCollapseState,
+  type SideNavCollapsibleConfig,
   type SideNavImperativeCollapseHandle,
 } from './SideNavCollapseContext';
 import {SideNavCollapseButton} from './SideNavCollapseButton';
@@ -45,6 +46,7 @@ import {useResizable} from '../Resizable/useResizable';
 import type {ResizableConfig} from '../Resizable/useResizable';
 import {ResizeHandle} from '../Resizable/ResizeHandle';
 import {themeProps} from '../utils/themeProps';
+import {SizeProvider} from '../SizeContext/SizeContext';
 import {useTranslator} from '../i18n';
 
 // =============================================================================
@@ -185,6 +187,13 @@ const styles = stylex.create({
   },
 });
 
+/**
+ * Cascaded to the icon rows through `SizeContext` so the built-in collapse
+ * button and the consumer's `footerIcons` come out one height. An explicit
+ * `size` on a child still wins.
+ */
+const FOOTER_ICON_SIZE = 'sm';
+
 // =============================================================================
 // Types
 // =============================================================================
@@ -197,6 +206,9 @@ export interface SideNavProps extends BaseProps<HTMLElement> {
    * Imperative collapse handle for SideNavCollapseButton instances rendered
    * outside this SideNav. This intentionally stays separate from `ref`, which
    * continues to expose the root HTMLElement.
+   *
+   * @deprecated Hand the same controlled `collapsible` config to SideNav and
+   * to the outside button instead.
    */
   handleRef?: React.Ref<SideNavImperativeCollapseHandle>;
 
@@ -270,21 +282,14 @@ export interface SideNavProps extends BaseProps<HTMLElement> {
    * - `true` — enables collapse with default toggle button and uncontrolled state
    * - Object — enables collapse with advanced configuration:
    *   - `defaultIsCollapsed` — start collapsed (uncontrolled)
-   *   - `isCollapsed` + `onCollapsedChange` — controlled mode
+   *   - `isCollapsed` + `onCollapsedChange` — controlled mode. Pass the same
+   *     object to a `SideNavCollapseButton` rendered outside this SideNav
    *   - `hasButton` — render built-in collapse button (default: true)
    *   - `buttonLabel` — accessibility label for the collapse button
    *
    * @default false
    */
-  collapsible?:
-    | boolean
-    | {
-        defaultIsCollapsed?: boolean;
-        isCollapsed?: boolean;
-        onCollapsedChange?: (isCollapsed: boolean) => void;
-        hasButton?: boolean;
-        buttonLabel?: string;
-      };
+  collapsible?: boolean | SideNavCollapsibleConfig;
 }
 
 // =============================================================================
@@ -375,6 +380,8 @@ export function SideNav({
   const toggle = useCallback(() => {
     const next = !collapsed;
 
+    // Deprecated `handleRef` path only: an out-of-tree button reads this
+    // snapshot while rendering, which can happen before SideNav re-renders.
     collapseStateRef.current = {
       ...collapseStateRef.current,
       isCollapsed: next,
@@ -429,7 +436,9 @@ export function SideNav({
           style,
         )}>
         {header}
-        <div {...stylex.props(styles.topbarIcons)}>{footerIcons}</div>
+        <div {...stylex.props(styles.topbarIcons)}>
+          <SizeProvider value={FOOTER_ICON_SIZE}>{footerIcons}</SizeProvider>
+        </div>
       </div>
     );
   }
@@ -441,7 +450,13 @@ export function SideNav({
 
   if (renderMode === 'drawer') {
     return (
-      <MobileNav header={header} data-testid={testId}>
+      <MobileNav
+        header={header}
+        data-testid={testId}
+        xstyle={xstyle}
+        className={className}
+        style={style}
+        {...props}>
         {topContent}
         {children}
         {hasDrawerFooter && (
@@ -449,7 +464,9 @@ export function SideNav({
             {footer}
             {footerIcons && (
               <div {...stylex.props(styles.drawerFooterIcons)}>
-                {footerIcons}
+                <SizeProvider value={FOOTER_ICON_SIZE}>
+                  {footerIcons}
+                </SizeProvider>
               </div>
             )}
           </div>
@@ -472,7 +489,9 @@ export function SideNav({
             {footer}
             {footerIcons && (
               <div {...stylex.props(styles.drawerFooterIcons)}>
-                {footerIcons}
+                <SizeProvider value={FOOTER_ICON_SIZE}>
+                  {footerIcons}
+                </SizeProvider>
               </div>
             )}
           </div>
@@ -544,8 +563,10 @@ export function SideNav({
               styles.footerRow,
               collapsed && styles.footerRowCollapsed,
             )}>
-            {showCollapseButton && <SideNavCollapseButton />}
-            {footerIcons}
+            <SizeProvider value={FOOTER_ICON_SIZE}>
+              {showCollapseButton && <SideNavCollapseButton />}
+              {footerIcons}
+            </SizeProvider>
           </div>
         </div>
       )}

package/src/SideNav/SideNavCollapseButton.doc.mjs

@@ -7,18 +7,28 @@ export const docs = {
   subComponentOf: 'SideNav',
   displayName: 'Side Nav Collapse Button',
   isHiddenFromOverview: true,
-  description: 'Toggle button for sidenav collapse. Place inside SideNav (reads context automatically) or outside (pass handleRef). Renders as an icon-only ghost button by default.',
+  description: 'Toggle button for sidenav collapse. Place inside SideNav (reads context automatically) or outside it (hand the same controlled collapsible config to both). Renders as an icon-only ghost button by default.',
   props: [
+    {
+      name: 'collapsible',
+      type: '{isCollapsed: boolean, onCollapsedChange: (isCollapsed: boolean) => void}',
+      description: 'The same controlled collapsible config passed to SideNav. Only needed when the button is rendered outside the sidenav, where collapse context cannot reach it.',
+    },
     {
       name: 'handleRef',
       type: 'RefObject<SideNavImperativeCollapseHandle | null>',
-      description: 'Imperative collapse handle from SideNav. Only needed when the button is rendered outside the sidenav.',
+      description: 'Deprecated. Imperative collapse handle from SideNav; pass collapsible instead.',
     },
     {
       name: 'label',
       type: 'string',
       description: 'Custom button label. When provided, renders as a text button with chevron. When omitted, renders icon-only.',
     },
+    {
+      name: 'size',
+      type: "'sm' | 'md' | 'lg'",
+      description: "Button size. Defaults to the size its container cascades — 'sm' inside a SideNav footer — and to 'md' with no container. Set it when the button sits outside a sized container and has to match its neighbours.",
+    },
     {
       name: 'children',
       type: 'ReactNode',
@@ -31,18 +41,28 @@ export const docsZh = {
   name: 'SideNavCollapseButton',
   isHiddenFromOverview: true,
   displayName: 'Side Nav Collapse Button',
-  description: '侧边栏折叠切换按钮。放置在 SideNav 内部（自动读取上下文）或外部（传入 handleRef）。默认渲染为仅图标的 ghost 按钮。',
+  description: '侧边栏折叠切换按钮。放置在 SideNav 内部（自动读取上下文）或外部（向两者传入同一个受控 collapsible 配置）。默认渲染为仅图标的 ghost 按钮。',
   props: [
+    {
+      name: 'collapsible',
+      type: '{isCollapsed: boolean, onCollapsedChange: (isCollapsed: boolean) => void}',
+      description: '与 SideNav 相同的受控 collapsible 配置。仅在按钮渲染在侧边栏外部、无法读取折叠上下文时需要。',
+    },
     {
       name: 'handleRef',
       type: 'RefObject<SideNavImperativeCollapseHandle | null>',
-      description: '来自 SideNav 的命令式折叠句柄。仅在按钮渲染在侧边栏外部时需要。',
+      description: '已废弃。来自 SideNav 的命令式折叠句柄；请改用 collapsible。',
     },
     {
       name: 'label',
       type: 'string',
       description: '自定义按钮标签。提供时渲染为带箭头的文本按钮。省略时渲染为仅图标按钮。',
     },
+    {
+      name: 'size',
+      type: "'sm' | 'md' | 'lg'",
+      description: "按钮尺寸。默认使用容器级联的尺寸（SideNav 页脚内为 'sm'），无容器时为 'md'。当按钮位于已设定尺寸的容器之外且需要与相邻元素保持一致时显式设置。",
+    },
     {
       name: 'children',
       type: 'ReactNode',
@@ -55,10 +75,12 @@ export const docsDense = {
   name: 'SideNavCollapseButton',
   isHiddenFromOverview: true,
   displayName: 'Side Nav Collapse Button',
-  description: 'Toggle button for sidenav collapse. Place inside SideNav (reads context) or outside (pass handleRef). Icon-only ghost button by default.',
+  description: 'Toggle button for sidenav collapse. Place inside SideNav (reads context) or outside (pass the same controlled collapsible config both get). Icon-only ghost button by default.',
   propDescriptions: {
-    handleRef: 'Imperative collapse handle from SideNav. Only needed when button rendered outside sidenav.',
+    collapsible: 'Controlled collapsible config, same object SideNav gets. Only needed when button rendered outside sidenav.',
+    handleRef: 'Deprecated — pass collapsible instead.',
     label: 'Custom label. Text button w/ chevron when provided, icon-only when omitted.',
+    size: "Button size. Inherits from the container ('sm' in a SideNav footer), else 'md'.",
     children: 'Custom content. Overrides default chevron icon + label.',
   },
 };

package/src/SideNav/SideNavCollapseButton.tsx

@@ -9,7 +9,7 @@
  * @position Composable toggle button for sidenav collapse
  *
  * Place inside SideNav (reads context automatically) or outside
- * (pass handleRef to connect). Customizable via label/children.
+ * (pass the same controlled `collapsible` config both get).
  *
  * SYNC: When modified, update:
  * - /packages/core/src/SideNav/SideNav.doc.mjs
@@ -17,7 +17,7 @@
  * - /packages/cli/assets/templates/blocks/components/SideNav/ (showcase blocks)
  */
 
-import React, {type ReactNode} from 'react';
+import React, {useCallback, type ReactNode} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import {durationVars, easeVars} from '../theme/tokens.stylex';
 import {Icon} from '../Icon';
@@ -27,21 +27,34 @@ import {composeEventHandlers, rtlStyles} from '../utils';
 import {
   useSideNavCollapse,
   type SideNavCollapseState,
+  type SideNavControlledCollapsible,
   type SideNavImperativeCollapseHandle,
 } from './SideNavCollapseContext';
 import {useAppShellMobile} from '../AppShell/AppShellMobileContext';
 import {useTranslator} from '../i18n';
+import type {ElementSize} from '../SizeContext/SizeContext';
 
 // =============================================================================
 // Styles
 // =============================================================================
 
 const styles = stylex.create({
+  // A flex container, so the glyph is a flex item. Left to blockify as a flex
+  // item of Button's icon slot, this span gets a line box and seats the
+  // chevron on its text baseline — 2.42px above the button's centre.
+  chevronMirror: {
+    display: 'flex',
+    alignItems: 'center',
+    justifyContent: 'center',
+  },
   chevron: {
     display: 'inline-flex',
     alignItems: 'center',
     transitionProperty: 'transform',
-    transitionDuration: durationVars['--duration-fast'],
+    transitionDuration: {
+      default: durationVars['--duration-fast'],
+      '@media (prefers-reduced-motion: reduce)': '0s',
+    },
     transitionTimingFunction: easeVars['--ease-standard'],
   },
   chevronCollapsed: {
@@ -56,8 +69,16 @@ const styles = stylex.create({
 export interface SideNavCollapseButtonProps extends BaseProps<HTMLButtonElement> {
   ref?: React.Ref<HTMLButtonElement>;
   /**
-   * Imperative handle from SideNav. Only needed when the button is rendered
-   * outside the sidenav, where collapse context is unavailable.
+   * The same controlled `collapsible` config given to SideNav
+   * (`{isCollapsed, onCollapsedChange}`). Needed only when the button is
+   * rendered outside the sidenav, where collapse context cannot reach it.
+   */
+  collapsible?: SideNavControlledCollapsible;
+
+  /**
+   * Imperative handle from SideNav.
+   *
+   * @deprecated Pass `collapsible` instead.
    */
   handleRef?: React.RefObject<SideNavImperativeCollapseHandle | null>;
 
@@ -67,6 +88,13 @@ export interface SideNavCollapseButtonProps extends BaseProps<HTMLButtonElement>
    */
   label?: string;
 
+  /**
+   * Button size. Defaults to the size its container cascades — `sm` in a
+   * SideNav footer — or `md` outside one. Set it for placements with no row
+   * to inherit from, e.g. a button placed in a `TopNav`.
+   */
+  size?: ElementSize;
+
   /**
    * Custom button content. Overrides the default chevron icon and label.
    */
@@ -82,7 +110,8 @@ export interface SideNavCollapseButtonProps extends BaseProps<HTMLButtonElement>
  *
  * Place anywhere inside SideNav (header, topContent, footer, footerIcons)
  * and it reads collapse state from context automatically. For placement
- * outside the sidenav (e.g. in TopNav or content area), pass handleRef.
+ * outside the sidenav (e.g. in TopNav or content area), hold the state and
+ * hand the same `collapsible` config to both.
  *
  * @example
  * ```
@@ -93,22 +122,27 @@ export interface SideNavCollapseButtonProps extends BaseProps<HTMLButtonElement>
  *
  * @example
  * ```
- * const ref = useRef(null);
- * <TopNav endContent={<SideNavCollapseButton handleRef={ref} />} />
- * <SideNav handleRef={ref} collapsible>...</SideNav>
+ * const [isCollapsed, setIsCollapsed] = useState(false);
+ * const collapsible = {isCollapsed, onCollapsedChange: setIsCollapsed};
+ * <TopNav endContent={<SideNavCollapseButton collapsible={collapsible} />} />
+ * <SideNav collapsible={{...collapsible, hasButton: false}}>...</SideNav>
  * ```
  */
 export function SideNavCollapseButton({
   ref,
+  collapsible,
   handleRef,
   label,
+  size,
   children,
   onClick: onClickProp,
   ...props
 }: SideNavCollapseButtonProps) {
   const t = useTranslator();
-  const {isCollapsed, toggle, isCollapsible} =
-    useSideNavCollapseState(handleRef);
+  const {isCollapsed, toggle, isCollapsible} = useSideNavCollapseState(
+    collapsible,
+    handleRef,
+  );
   const {isMobile} = useAppShellMobile();
 
   // Hide when not collapsible, or when in mobile mode (sidenav is in
@@ -127,6 +161,7 @@ export function SideNavCollapseButton({
           : t('@astryx.sideNavCollapseButton.collapseSidebar'))
       }
       variant="ghost"
+      size={size}
       {...props}
       onClick={composeEventHandlers(onClickProp, toggle)}
       icon={
@@ -135,7 +170,7 @@ export function SideNavCollapseButton({
           // into) the state rotation: both are `transform`, so on a single
           // element one would overwrite the other and the chevron would stop
           // mirroring under RTL. See utils/rtlStyles.ts.
-          <span {...stylex.props(rtlStyles.mirror)}>
+          <span {...stylex.props(styles.chevronMirror, rtlStyles.mirror)}>
             {/* `sm` (1rem) matches what this glyph already renders at: Button's
                 icon slot pins its wrapper to 16px, and the registry SVG is
                 1em, so the chevron is 16px today. */}
@@ -156,11 +191,30 @@ export function SideNavCollapseButton({
 SideNavCollapseButton.displayName = 'SideNavCollapseButton';
 
 function useSideNavCollapseState(
+  collapsible: SideNavControlledCollapsible | undefined,
   handleRef:
     React.RefObject<SideNavImperativeCollapseHandle | null> | undefined,
 ): SideNavCollapseState {
   const contextCollapseState = useSideNavCollapse();
 
+  const {isCollapsed, onCollapsedChange} = collapsible ?? {};
+  const toggleCollapsible = useCallback(
+    () => onCollapsedChange?.(!isCollapsed),
+    [isCollapsed, onCollapsedChange],
+  );
+
+  const toggleHandle = useCallback(() => {
+    handleRef?.current?.getCollapseState()?.toggle();
+  }, [handleRef]);
+
+  if (collapsible != null) {
+    return {
+      isCollapsed: isCollapsed ?? false,
+      toggle: toggleCollapsible,
+      isCollapsible: true,
+    };
+  }
+
   if (handleRef == null) {
     return contextCollapseState;
   }
@@ -169,9 +223,7 @@ function useSideNavCollapseState(
 
   return {
     isCollapsed: externalCollapseState?.isCollapsed ?? false,
-    toggle: () => {
-      handleRef.current?.getCollapseState()?.toggle();
-    },
+    toggle: toggleHandle,
     isCollapsible: externalCollapseState?.isCollapsible ?? true,
   };
 }

package/src/SideNav/SideNavCollapseContext.ts

@@ -10,8 +10,8 @@
  *
  * Provides collapse state to SideNavCollapseButton and other
  * sidenav children. Set by SideNav when isCollapsible is true.
- * Also provides a small imperative handle for ref-based collapse buttons
- * rendered outside the SideNav tree.
+ * A button rendered outside the SideNav tree is out of context's reach and
+ * takes the controlled `collapsible` config as a prop instead.
  */
 
 import {createContext, use} from 'react';
@@ -25,18 +25,38 @@ export interface SideNavCollapseState {
   isCollapsible: boolean;
 }
 
+/** Object form of SideNav's `collapsible` prop. */
+export interface SideNavCollapsibleConfig {
+  defaultIsCollapsed?: boolean;
+  isCollapsed?: boolean;
+  onCollapsedChange?: (isCollapsed: boolean) => void;
+  hasButton?: boolean;
+  buttonLabel?: string;
+}
+
+/**
+ * The controlled form: the consumer holds the state, so it can be handed to
+ * both SideNav and a SideNavCollapseButton rendered outside it.
+ */
+export interface SideNavControlledCollapsible extends SideNavCollapsibleConfig {
+  isCollapsed: boolean;
+  onCollapsedChange: (isCollapsed: boolean) => void;
+}
 
+/**
+ * @deprecated Pass the same controlled `collapsible` config to SideNav and to
+ * the out-of-tree SideNavCollapseButton instead. The state then reaches the
+ * button through props rather than through a ref.
+ */
 export interface SideNavImperativeCollapseHandle {
   getCollapseState: () => SideNavCollapseState | null;
 }
 
-export const SideNavCollapseContext = createContext<SideNavCollapseState>(
-  {
-    isCollapsed: false,
-    toggle: () => {},
-    isCollapsible: false,
-  },
-);
+export const SideNavCollapseContext = createContext<SideNavCollapseState>({
+  isCollapsed: false,
+  toggle: () => {},
+  isCollapsible: false,
+});
 SideNavCollapseContext.displayName = 'SideNavCollapseContext';
 
 /**

package/src/SideNav/SideNavHeading.tsx

@@ -36,6 +36,7 @@ import {Link} from '../Link';
 import {Icon} from '../Icon';
 import {Tooltip} from '../Tooltip';
 import {navItemStyles} from '../NavItem/navItemStyles.stylex';
+import {focusOutlineProps} from '../utils/focusOutline.stylex';
 import {useSideNavCollapse} from './SideNavCollapseContext';
 import {useLinkComponent} from '../Link/useLinkComponent';
 import type {LinkComponentType} from '../Link/types';
@@ -415,7 +416,11 @@ export function SideNavHeading({
           data-testid={testId}
           {...mergeProps(
             themeProps('side-nav-heading'),
-            stylex.props(navItemStyles.item, styles.rootCollapsed, xstyle),
+            focusOutlineProps.focusVisible(
+              navItemStyles.item,
+              styles.rootCollapsed,
+              xstyle,
+            ),
             className,
             style,
           )}>
@@ -434,7 +439,7 @@ export function SideNavHeading({
             {...triggerProps}
             {...mergeProps(
               themeProps('side-nav-heading'),
-              stylex.props(
+              focusOutlineProps.focusVisible(
                 navItemStyles.item,
                 styles.rootCollapsed,
                 styles.menuTrigger,
@@ -452,7 +457,7 @@ export function SideNavHeading({
               {...contentProps}>
               <button
                 type="button"
-                {...stylex.props(styles.popoverHeading)}
+                {...focusOutlineProps.focusVisible(styles.popoverHeading)}
                 onClick={triggerProps.onClick}>
                 {icon && <span {...stylex.props(styles.icon)}>{icon}</span>}
                 <span {...stylex.props(styles.textContainer)}>
@@ -549,7 +554,10 @@ export function SideNavHeading({
         {hasAnyHref && headingHref && menu ? (
           <LinkComponent
             href={headingHref}
-            {...stylex.props(styles.heading, styles.headingLink)}>
+            {...focusOutlineProps.focusVisible(
+              styles.heading,
+              styles.headingLink,
+            )}>
             {heading}
           </LinkComponent>
         ) : (
@@ -586,7 +594,7 @@ export function SideNavHeading({
   const popoverHeadingContent = (
     <button
       type="button"
-      {...stylex.props(styles.popoverHeading)}
+      {...focusOutlineProps.focusVisible(styles.popoverHeading)}
       onClick={triggerProps.onClick}>
       {icon && <span {...stylex.props(styles.icon)}>{icon}</span>}
       {renderTextContent(
@@ -609,7 +617,11 @@ export function SideNavHeading({
         data-testid={testId}
         {...mergeProps(
           themeProps('side-nav-heading'),
-          stylex.props(styles.root, styles.menuTrigger, xstyle),
+          focusOutlineProps.focusVisible(
+            styles.root,
+            styles.menuTrigger,
+            xstyle,
+          ),
           className,
           style,
         )}
@@ -646,7 +658,10 @@ export function SideNavHeading({
                 triggerProps.onClick();
               }}
               {...popover.triggerProps}
-              {...stylex.props(styles.chevron, styles.interactive)}>
+              {...focusOutlineProps.focusVisible(
+                styles.chevron,
+                styles.interactive,
+              )}>
               <Icon
                 icon="chevronDown"
                 size="sm"
@@ -701,7 +716,7 @@ export function SideNavHeading({
               <LinkComponent
                 href={headingHref}
                 aria-label={heading}
-                {...stylex.props(styles.icon)}>
+                {...focusOutlineProps.focusVisible(styles.icon)}>
                 {icon}
               </LinkComponent>
             ) : (
@@ -717,7 +732,10 @@ export function SideNavHeading({
                   triggerProps.onClick();
                 }}
                 {...popover.triggerProps}
-                {...stylex.props(styles.chevron, styles.interactive)}>
+                {...focusOutlineProps.focusVisible(
+                  styles.chevron,
+                  styles.interactive,
+                )}>
                 <Icon
                   icon="chevronDown"
                   size="sm"
@@ -770,7 +788,7 @@ export function SideNavHeading({
             <LinkComponent
               href={headingHref}
               aria-label={heading}
-              {...stylex.props(styles.icon)}>
+              {...focusOutlineProps.focusVisible(styles.icon)}>
               {icon}
             </LinkComponent>
           ) : (

package/src/SideNav/SideNavItem.doc.mjs

@@ -91,6 +91,12 @@ export const docs = {
       description: 'Enables collapse behavior for items with children. Pass true for uncontrolled (starts expanded), or an object for controlled mode.',
       default: 'false',
     },
+    {
+      name: 'size',
+      type: "'sm' | 'md' | 'lg'",
+      description: 'Size variant for the nav item row.',
+      default: "'md'",
+    },
   ],
 };
 
@@ -159,6 +165,12 @@ export const docsZh = {
       description: '启用带子项的折叠行为。传 true 为非受控模式（默认展开），或传对象用于受控模式。',
       default: 'false',
     },
+    {
+      name: 'size',
+      type: "'sm' | 'md' | 'lg'",
+      description: '导航项的尺寸变体。',
+      default: "'md'",
+    },
   ],
 };
 
@@ -179,5 +191,6 @@ export const docsDense = {
     endContent: 'Right-side content such as badges or counts.',
     children: 'Sub-items for nesting.',
     collapsible: 'Enables collapse for items w/ children. true=uncontrolled, object=controlled mode.',
+    size: "Row size variant: 'sm' | 'md' | 'lg'.",
   },
 };