@astryxdesign/core 0.2.0 → 0.3.0-canary.041a0ef

package/src/TopNav/TopNav.tsx

@@ -13,7 +13,7 @@
  * - /packages/core/src/TopNav/TopNav.test.tsx
  * - /packages/core/src/TopNav/index.ts
  * - /apps/storybook/stories/TopNav.stories.tsx
- * - /packages/cli/templates/blocks/components/TopNav/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/TopNav/ (showcase blocks)
  */
 
 import type {ReactNode} from 'react';
@@ -243,9 +243,7 @@ export function TopNav({
           </div>
         )}
         {hasCollapsibleContent && mobileContent && (
-          <div {...stylex.props(styles.drawerDivider)}>
-            <Divider />
-          </div>
+          <Divider xstyle={styles.drawerDivider} />
         )}
         {mobileContent && (
           <div {...stylex.props(styles.drawerExtraContent)}>

package/src/TopNav/TopNavHeading.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'TopNavHeading',
@@ -33,11 +33,6 @@ export const docs = {
       type: 'string',
       description: 'Link for the heading text (e.g. product home). When no menu is present and this is the only href, the whole heading becomes one clickable link.',
     },
-    {
-      name: 'href',
-      type: 'string',
-      description: 'Deprecated: use headingHref instead. URL to navigate to when clicked.',
-    },
     {
       name: 'superheading',
       type: 'string',
@@ -122,11 +117,6 @@ export const docsZh = {
       type: 'string',
       description: '标题文本的链接（如产品首页）。当没有菜单且这是唯一的 href 时，整个标题变为一个可点击链接。',
     },
-    {
-      name: 'href',
-      type: 'string',
-      description: '已弃用，请使用 headingHref。点击时导航到的 URL。',
-    },
     {
       name: 'superheading',
       type: 'string',
@@ -179,7 +169,6 @@ export const docsDense = {
     logo: 'Logo before heading text. Image, NavIcon, or ReactNode.',
     heading: 'Product/app name.',
     headingHref: 'Link for heading (product home). Only href + no menu → whole heading is link.',
-    href: 'Deprecated: use headingHref.',
     superheading: 'Text above heading (suite name). Smaller secondary style.',
     superheadingHref: 'Link for superheading. Independent inline link when menu present.',
     subheading: 'Text below heading (account context). Smaller secondary style.',

package/src/TopNav/TopNavHeading.tsx

@@ -17,7 +17,7 @@
  * - /packages/core/src/TopNav/TopNav.test.tsx
  * - /packages/core/src/TopNav/index.ts
  * - /apps/storybook/stories/TopNav.stories.tsx
- * - /packages/cli/templates/blocks/components/TopNav/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/TopNav/ (showcase blocks)
  */
 
 import {useMemo, useRef, type ReactNode} from 'react';
@@ -31,7 +31,7 @@ import {
 } from '../theme/tokens.stylex';
 import {usePopover} from '../Popover/usePopover';
 import {Link} from '../Link';
-import {getIcon} from '../Icon/globalIconRegistry';
+import {Icon} from '../Icon';
 import {useLinkComponent} from '../Link/useLinkComponent';
 import type {LinkComponentType} from '../Link/types';
 import {mergeProps, mergeRefs} from '../utils';
@@ -149,6 +149,16 @@ const styles = stylex.create({
     minHeight: spacingVars['--spacing-7'],
     color: colorVars['--color-icon-secondary'],
   },
+  // The registry chevron is a 1em SVG, so it has always rendered at the
+  // heading's inherited font size. Icon's size box would repin it to a fixed
+  // rem (the nearest, sm, is 1rem = 16px vs the 14px base here), so hold the
+  // glyph on the inherited em — the 28px chevron box above is unchanged, and
+  // the glyph keeps tracking the surrounding text.
+  chevronGlyph: {
+    width: '1em',
+    height: '1em',
+    fontSize: 'inherit',
+  },
   headerEndContent: {
     flexShrink: 0,
     display: 'flex',
@@ -182,14 +192,9 @@ const styles = stylex.create({
     marginInline: spacingVars['--spacing-1'],
     cursor: 'pointer',
   },
+  // Composes over `chevron` — the flipped popover copy differs only by the
+  // rotation, so it carries just that.
   popoverChevron: {
-    flexShrink: 0,
-    display: 'flex',
-    alignItems: 'center',
-    justifyContent: 'center',
-    minWidth: spacingVars['--spacing-7'],
-    minHeight: spacingVars['--spacing-7'],
-    color: colorVars['--color-icon-secondary'],
     transform: 'rotate(180deg)',
   },
   popover: {
@@ -227,14 +232,8 @@ export interface TopNavHeadingProps extends BaseProps<HTMLElement> {
   heading?: string;
   /**
    * Link for the heading (e.g., product home).
-   * Alias: `href` (for backward compatibility).
    */
   headingHref?: string;
-  /**
-   * @deprecated Use `headingHref` instead.
-   * URL to navigate to when the heading is clicked.
-   */
-  href?: string;
   /**
    * Text above the heading (e.g., suite name).
    */
@@ -304,8 +303,7 @@ export function TopNavHeading({
   logo,
   logoLabel,
   heading,
-  headingHref: headingHrefProp,
-  href,
+  headingHref,
   superheading,
   superheadingHref,
   subheading,
@@ -321,8 +319,6 @@ export function TopNavHeading({
 }: TopNavHeadingProps) {
   const t = useTranslator();
   const LinkComponent = useLinkComponent(as);
-  // Support both headingHref and legacy href
-  const headingHref = headingHrefProp ?? href;
   // When the logo is wrapped in a link it needs its own accessible name (the
   // logo image itself is decorative). Prefer an explicit logoLabel, fall back
   // to the heading text. axe: link-name.
@@ -412,7 +408,12 @@ export function TopNavHeading({
   );
 
   const chevronElement = showChevron && (
-    <span {...stylex.props(styles.chevron)}>{getIcon('chevronDown')}</span>
+    <Icon
+      icon="chevronDown"
+      size="sm"
+      color="secondary"
+      xstyle={[styles.chevron, styles.chevronGlyph]}
+    />
   );
 
   const headerEndContentElement = headerEndContent && (
@@ -428,9 +429,12 @@ export function TopNavHeading({
       onClick={triggerProps.onClick}>
       {logo && <span {...stylex.props(styles.logo)}>{logo}</span>}
       {renderTextContent(
-        <span {...stylex.props(styles.popoverChevron)}>
-          {getIcon('chevronDown')}
-        </span>,
+        <Icon
+          icon="chevronDown"
+          size="sm"
+          color="secondary"
+          xstyle={[styles.chevron, styles.chevronGlyph, styles.popoverChevron]}
+        />,
       )}
     </button>
   );
@@ -498,6 +502,8 @@ export function TopNavHeading({
           )}>
           {logo && <span {...stylex.props(styles.logo)}>{logo}</span>}
           {renderTextContent(
+            // Stays a <button>: this box is the popover trigger, so it carries
+            // the accessible name and handlers — only the glyph moves to Icon.
             <button
               type="button"
               aria-label={t('@astryx.topNav.heading.openMenu')}
@@ -507,7 +513,12 @@ export function TopNavHeading({
               }}
               {...popover.triggerProps}
               {...stylex.props(styles.chevron, styles.interactive)}>
-              {getIcon('chevronDown')}
+              <Icon
+                icon="chevronDown"
+                size="sm"
+                color="inherit"
+                xstyle={styles.chevronGlyph}
+              />
             </button>,
           )}
           {headerEndContentElement}
@@ -567,6 +578,9 @@ export function TopNavHeading({
             ))}
           {renderTextContent(
             showChevron ? (
+              // Stays a <button>: this box is the popover trigger, so it
+              // carries the accessible name and handlers — only the glyph
+              // moves to Icon.
               <button
                 type="button"
                 aria-label={t('@astryx.topNav.heading.openMenu')}
@@ -576,7 +590,12 @@ export function TopNavHeading({
                 }}
                 {...popover.triggerProps}
                 {...stylex.props(styles.chevron, styles.interactive)}>
-                {getIcon('chevronDown')}
+                <Icon
+                  icon="chevronDown"
+                  size="sm"
+                  color="inherit"
+                  xstyle={styles.chevronGlyph}
+                />
               </button>
             ) : undefined,
           )}

package/src/TopNav/TopNavItem.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'TopNavItem',

package/src/TopNav/TopNavItem.tsx

@@ -13,7 +13,7 @@
  * - /packages/core/src/TopNav/TopNav.test.tsx
  * - /packages/core/src/TopNav/index.ts
  * - /apps/storybook/stories/TopNav.stories.tsx
- * - /packages/cli/templates/blocks/components/TopNav/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/TopNav/ (showcase blocks)
  */
 
 import type {ReactNode} from 'react';
@@ -35,6 +35,7 @@ import {navItemStyles, type NavItemSize} from '../NavItem/navItemStyles.stylex';
 import {mergeProps} from '../utils';
 import {useAppShellMobile} from '../AppShell/AppShellMobileContext';
 import {themeProps} from '../utils/themeProps';
+import {focusOutlineProps} from '../utils/focusOutline.stylex';
 
 /**
  * NavItem styles with hover/selected states
@@ -63,14 +64,6 @@ const styles = stylex.create({
       },
       ':active': colorVars['--color-overlay-pressed'],
     },
-    outline: {
-      default: null,
-      ':focus-visible': `2px solid ${colorVars['--color-accent']}`,
-    },
-    outlineOffset: {
-      default: '0',
-      ':focus-visible': '2px',
-    },
   },
   selected: {
     color: colorVars['--color-text-primary'],
@@ -87,16 +80,6 @@ const styles = stylex.create({
     paddingInline: spacingVars['--spacing-2'],
   },
   // Drawer mode — focus outline (base item + selected come from navItemStyles)
-  drawerFocus: {
-    outline: {
-      default: null,
-      ':focus-visible': `2px solid ${colorVars['--color-accent']}`,
-    },
-    outlineOffset: {
-      default: '0',
-      ':focus-visible': '2px',
-    },
-  },
 });
 
 export interface TopNavItemProps extends BaseProps<HTMLAnchorElement> {
@@ -246,10 +229,9 @@ export function TopNavItem({
             mode: 'drawer',
             selected: isSelected ? 'selected' : null,
           }),
-          stylex.props(
+          focusOutlineProps.focusVisible(
             navItemStyles.item,
             navItemStyles[size],
-            styles.drawerFocus,
             isSelected && navItemStyles.selected,
             isDisabled && navItemStyles.disabled,
             xstyle,
@@ -283,7 +265,7 @@ export function TopNavItem({
         themeProps('top-nav-item', {
           selected: isSelected ? 'selected' : null,
         }),
-        stylex.props(
+        focusOutlineProps.focusVisible(
           styles.base,
           isSelected && styles.selected,
           isDisabled && navItemStyles.disabled,

package/src/TopNav/TopNavMegaMenu.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'TopNavMegaMenu',

package/src/TopNav/TopNavMegaMenu.tsx

@@ -20,7 +20,7 @@
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/TopNav/TopNav.doc.mjs
  * - /packages/core/src/TopNav/index.ts
- * - /packages/cli/templates/blocks/components/TopNav/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/TopNav/ (showcase blocks)
  */
 
 import React, {
@@ -44,13 +44,14 @@ import {
 } from '../theme/tokens.stylex';
 import {usePopover} from '../Popover/usePopover';
 import {Grid} from '../Grid/Grid';
-import {getIcon} from '../Icon/globalIconRegistry';
+import {Icon} from '../Icon';
 import {mergeProps, mergeRefs} from '../utils';
 import type {BaseProps} from '../BaseProps';
 import {navItemStyles} from '../NavItem/navItemStyles.stylex';
 import {useTopNavSlot} from './TopNavContext';
 import {useTopNavRenderMode} from './TopNavRenderContext';
 import {themeProps} from '../utils/themeProps';
+import {focusOutlineProps} from '../utils/focusOutline.stylex';
 
 // =============================================================================
 // Styles
@@ -79,14 +80,6 @@ const styles = stylex.create({
         '@media (hover: hover)': colorVars['--color-overlay-hover'],
       },
     },
-    outline: {
-      default: null,
-      ':focus-visible': `2px solid ${colorVars['--color-accent']}`,
-    },
-    outlineOffset: {
-      default: '0',
-      ':focus-visible': '2px',
-    },
     border: 'none',
     fontFamily: 'inherit',
   },
@@ -97,6 +90,14 @@ const styles = stylex.create({
   chevron: {
     display: 'inline-flex',
     alignItems: 'center',
+    // The registry chevron is a 1em SVG, so it has always rendered at the
+    // trigger's own font size (--text-label-size). Icon's size box would repin
+    // it to a fixed rem (the nearest, sm, is 1rem = 16px vs the 14px here), so
+    // hold it on the inherited em: same pixels, and still tracks the type
+    // scale when a theme changes the label size.
+    width: '1em',
+    height: '1em',
+    fontSize: 'inherit',
     transitionProperty: 'transform',
     transitionDuration: durationVars['--duration-fast'],
     transitionTimingFunction: easeVars['--ease-standard'],
@@ -123,6 +124,18 @@ const styles = stylex.create({
       transform: 'translateY(-4px)',
     },
   },
+  // Clamp the anchored layer to the space available below the nav so a tall
+  // menu never runs off the bottom of the viewport. The layer is positioned
+  // with position-area: self-block-end, so its containing block spans from
+  // the nav's block-end to the viewport edge — 100% is exactly that space.
+  // The layer is a flex column so panelContainer can shrink and scroll its
+  // own content, keeping the surface radius/shadow static at the edges.
+  // Internal scroll is a stopgap until the mobile bottom-sheet lands.
+  panelViewportFit: {
+    display: 'flex',
+    flexDirection: 'column',
+    maxHeight: `calc(100% - ${spacingVars['--spacing-3']})`,
+  },
   // Visual styles for the panel content container.
   panelContainer: {
     backgroundColor: colorVars['--color-background-popover'],
@@ -132,6 +145,11 @@ const styles = stylex.create({
     borderRadius: radiusVars['--radius-container'],
     boxShadow: shadowVars['--shadow-low'],
     overflow: 'hidden',
+    // Allow the container to shrink inside the height-clamped layer so its
+    // content (panelContent) can scroll rather than overflow the viewport.
+    display: 'flex',
+    flexDirection: 'column',
+    minHeight: 0,
   },
   panelContent: {
     display: 'flex',
@@ -139,7 +157,14 @@ const styles = stylex.create({
     gap: spacingVars['--spacing-6'],
     paddingBlock: spacingVars['--spacing-3'],
     paddingInline: spacingVars['--spacing-3'],
-    maxWidth: 960,
+    // Clamp to the viewport (minus a gutter) so the anchored panel never
+    // overflows the screen edge on narrow viewports; caps at 960px otherwise.
+    maxWidth: `min(960px, calc(100dvw - ${spacingVars['--spacing-4']}))`,
+    boxSizing: 'border-box',
+    // Scroll internally when the menu is taller than the available space
+    // below the nav (paired with panelViewportFit on the layer).
+    overflowY: 'auto',
+    overscrollBehavior: 'contain',
   },
   menuWrapper: {
     flexGrow: 2,
@@ -173,6 +198,11 @@ const styles = stylex.create({
   },
   drawerChevron: {
     display: 'inline-flex',
+    // Same em pin as styles.chevron above — the drawer header inherits
+    // --text-label-size from navItemStyles.item.
+    width: '1em',
+    height: '1em',
+    fontSize: 'inherit',
     transitionProperty: 'transform',
     transitionDuration: durationVars['--duration-fast'],
     transitionTimingFunction: easeVars['--ease-standard'],
@@ -444,16 +474,18 @@ function DefaultMegaMenu({
         onMouseLeave={handleMouseLeave}
         {...mergeProps(
           themeProps('top-nav-mega-menu'),
-          stylex.props(styles.trigger, popover.isOpen && styles.triggerOpen),
+          focusOutlineProps.focusVisible(
+            styles.trigger,
+            popover.isOpen && styles.triggerOpen,
+          ),
         )}>
         {label}
-        <span
-          {...stylex.props(
-            styles.chevron,
-            popover.isOpen && styles.chevronOpen,
-          )}>
-          {getIcon('chevronDown')}
-        </span>
+        <Icon
+          icon="chevronDown"
+          size="sm"
+          color="inherit"
+          xstyle={[styles.chevron, popover.isOpen && styles.chevronOpen]}
+        />
       </button>
       {popover.render(
         <div
@@ -468,11 +500,9 @@ function DefaultMegaMenu({
           <div {...stylex.props(styles.panelContent)}>
             {/* Menu items section */}
             {items != null && (
-              <div {...stylex.props(styles.menuWrapper)}>
-                <Grid columns={2} gap={2}>
-                  {items}
-                </Grid>
-              </div>
+              <Grid columns={2} gap={2} xstyle={styles.menuWrapper}>
+                {items}
+              </Grid>
             )}
 
             {/* Featured section */}
@@ -484,7 +514,7 @@ function DefaultMegaMenu({
         {
           placement: 'below',
           alignment: slot,
-          xstyle: styles.panelAnimation,
+          xstyle: [styles.panelAnimation, styles.panelViewportFit],
         },
       )}
     </>
@@ -516,13 +546,15 @@ function DrawerMegaMenu({
           stylex.props(navItemStyles.item, styles.drawerHeader),
         )}>
         {label}
-        <span
-          {...stylex.props(
+        <Icon
+          icon="chevronDown"
+          size="sm"
+          color="inherit"
+          xstyle={[
             styles.drawerChevron,
             isExpanded && styles.drawerChevronExpanded,
-          )}>
-          {getIcon('chevronDown')}
-        </span>
+          ]}
+        />
       </button>
 
       {/* Animated expand/collapse container */}

package/src/TopNav/TopNavMegaMenuFeaturedCard.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'TopNavMegaMenuFeaturedCard',

package/src/TopNav/TopNavMegaMenuFeaturedCard.tsx

@@ -15,7 +15,7 @@
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/TopNav/TopNav.doc.mjs
  * - /packages/core/src/TopNav/index.ts
- * - /packages/cli/templates/blocks/components/TopNav/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/TopNav/ (showcase blocks)
  */
 
 import React, {type ReactNode} from 'react';

package/src/TopNav/TopNavMegaMenuItem.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'TopNavMegaMenuItem',

package/src/TopNav/TopNavMegaMenuItem.tsx

@@ -12,7 +12,7 @@
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/TopNav/TopNav.doc.mjs
  * - /packages/core/src/TopNav/index.ts
- * - /packages/cli/templates/blocks/components/TopNav/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/TopNav/ (showcase blocks)
  */
 
 import React, {type ReactNode} from 'react';
@@ -34,6 +34,7 @@ import {mergeProps} from '../utils';
 import type {BaseProps} from '../BaseProps';
 import {useAppShellMobile} from '../AppShell/AppShellMobileContext';
 import {themeProps} from '../utils/themeProps';
+import {focusOutlineProps} from '../utils/focusOutline.stylex';
 
 // =============================================================================
 // Styles
@@ -61,14 +62,6 @@ const styles = stylex.create({
       ':active': colorVars['--color-overlay-pressed'],
     },
     border: 'none',
-    outline: {
-      default: null,
-      ':focus-visible': `2px solid ${colorVars['--color-accent']}`,
-    },
-    outlineOffset: {
-      default: '0',
-      ':focus-visible': '2px',
-    },
     color: 'inherit',
     fontFamily: 'inherit',
     textAlign: 'start',
@@ -249,7 +242,7 @@ export function TopNavMegaMenuItem({
       tabIndex={tabIndex}
       {...mergeProps(
         themeProps('top-nav-mega-menu-item'),
-        stylex.props(styles.desktop),
+        focusOutlineProps.focusVisible(styles.desktop),
       )}>
       {icon && <div {...stylex.props(styles.desktopIcon)}>{icon}</div>}
       <div {...stylex.props(styles.desktopContent)}>

package/src/TopNav/TopNavMenu.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'TopNavMenu',