@astryxdesign/core 0.3.0 → 0.4.0-canary.3112e99

package/src/Timestamp/TimestampHoverCard.tsx

@@ -24,12 +24,12 @@
  */
 
 import type {ReactNode} from 'react';
-import {useCallback, useEffect, useRef, useState} from 'react';
+import {useCallback} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import {HoverCard} from '../HoverCard';
 import {IconButton} from '../IconButton';
 import {Icon} from '../Icon';
-import {useAnnounce} from '../hooks/useAnnounce';
+import {useClipboard} from '../hooks/useClipboard';
 import {useTranslator} from '../i18n';
 import {themeProps} from '../utils/themeProps';
 import {
@@ -108,7 +108,9 @@ const COPY_FEEDBACK_MS = 1500;
  * The per-row copy affordance: a compact ghost `IconButton` that writes the
  * row's value to the clipboard, flips `copy` → `check` for a moment, and
  * announces the copy to a polite live region (a swapped aria-label alone
- * isn't reliably announced). A clipboard rejection is a silent no-op.
+ * isn't reliably announced). A clipboard rejection is a silent no-op. The
+ * clipboard write, copied flag, reset timer, and announcement are owned by
+ * `useClipboard` — shared with CodeBlock's built-in copy button.
  *
  * Kept as its own component so its state/timer/effect only exist for rows that
  * actually opt into copying — read-only rows render no button and carry none
@@ -116,36 +118,14 @@ const COPY_FEEDBACK_MS = 1500;
  */
 function CopyButton({value}: {value: string}) {
   const t = useTranslator();
-  const announce = useAnnounce();
-  const [copied, setCopied] = useState(false);
-  const resetTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const {copy, isCopied: copied} = useClipboard({
+    announce: t('@astryx.timestamp.copied'),
+    resetAfterMs: COPY_FEEDBACK_MS,
+  });
 
-  useEffect(() => {
-    return () => {
-      if (resetTimerRef.current != null) {
-        clearTimeout(resetTimerRef.current);
-      }
-    };
-  }, []);
-
-  const handleCopy = useCallback(async () => {
-    try {
-      await navigator.clipboard.writeText(value);
-      setCopied(true);
-      announce(t('@astryx.timestamp.copied'));
-      // Restart the reset timer on every copy so a rapid re-copy isn't
-      // reverted early by the previous click's timer.
-      if (resetTimerRef.current != null) {
-        clearTimeout(resetTimerRef.current);
-      }
-      resetTimerRef.current = setTimeout(() => {
-        resetTimerRef.current = null;
-        setCopied(false);
-      }, COPY_FEEDBACK_MS);
-    } catch {
-      // Clipboard failures leave the copied state unchanged.
-    }
-  }, [value, announce, t]);
+  const handleCopy = useCallback(() => {
+    void copy(value);
+  }, [copy, value]);
 
   return (
     <IconButton
@@ -163,9 +143,7 @@ function CopyButton({value}: {value: string}) {
           ? t('@astryx.timestamp.copied')
           : t('@astryx.timestamp.copyValue', {value})
       }
-      onClick={() => {
-        void handleCopy();
-      }}
+      onClick={handleCopy}
       {...themeProps('timestamp-copy-button')}
     />
   );

package/src/Timestamp/formatInstant.ts

@@ -69,6 +69,16 @@ export interface FormatInstantOptions {
    * @default false
    */
   isTimezoneShown?: boolean;
+  /**
+   * How the zone name is spelled when a format carries one. `'short'` is the
+   * abbreviation ("PST"); `'long'` spells it out ("Pacific Standard Time").
+   * Only `'full'` honours it — it is the one format that always names its zone.
+   * The spelled-out form backs a relative timestamp's accessible name, where an
+   * abbreviation reads as an unexpanded initialism to a screen reader
+   * (WCAG 3.1.4); every visible surface keeps the abbreviation.
+   * @default 'short'
+   */
+  timeZoneNameStyle?: 'short' | 'long';
 }
 
 // =============================================================================
@@ -155,7 +165,11 @@ function getWallClock(date: Date, timeZone: string | undefined): WallClock {
 export function formatInstant(
   date: Date,
   format: InstantFormat,
-  {timeZone, isTimezoneShown = false}: FormatInstantOptions = {},
+  {
+    timeZone,
+    isTimezoneShown = false,
+    timeZoneNameStyle = 'short',
+  }: FormatInstantOptions = {},
 ): string {
   const zone = timeZone === undefined ? {} : {timeZone};
   const zoneName = isTimezoneShown ? {timeZoneName: 'short' as const} : {};
@@ -164,6 +178,7 @@ export function formatInstant(
     case 'full':
       return new Intl.DateTimeFormat(undefined, {
         ...FULL_OPTIONS,
+        timeZoneName: timeZoneNameStyle,
         ...zone,
       }).format(date);
 

package/src/Token/Token.tsx

@@ -36,6 +36,7 @@ import {useInteractiveRole} from '../hooks/useInteractiveRole';
 import {TokenLink} from './TokenLink';
 import type {BaseProps} from '../BaseProps';
 import {themeProps} from '../utils/themeProps';
+import {focusOutlineProps} from '../utils/focusOutline.stylex';
 import {useTranslator} from '../i18n';
 import type {TokenColorMap} from './index';
 
@@ -146,14 +147,6 @@ const styles = stylex.create({
       },
       ':active': `linear-gradient(${colorVars['--color-overlay-pressed']}, ${colorVars['--color-overlay-pressed']})`,
     },
-    outline: {
-      default: null,
-      ':focus-visible': `2px solid ${colorVars['--color-accent']}`,
-    },
-    outlineOffset: {
-      default: '0',
-      ':focus-visible': '2px',
-    },
   },
   disabled: {
     cursor: 'not-allowed',
@@ -180,16 +173,6 @@ const styles = stylex.create({
     overflow: 'hidden',
     minWidth: 0,
   },
-  focusVisibleOutline: {
-    outline: {
-      default: null,
-      ':has(:focus-visible)': `2px solid ${colorVars['--color-accent']}`,
-    },
-    outlineOffset: {
-      default: '0',
-      ':has(:focus-visible)': '2px',
-    },
-  },
   removeButton: {
     all: 'unset',
     display: 'inline-flex',
@@ -203,10 +186,6 @@ const styles = stylex.create({
     width: '16px',
     height: '16px',
     color: 'inherit',
-    outline: {
-      default: null,
-      ':focus-visible': `2px solid ${colorVars['--color-accent']}`,
-    },
     '::after': {
       content: '""',
       position: 'absolute',
@@ -337,7 +316,7 @@ export function Token({
         onRemove(e);
       }}
       disabled={isDisabled}
-      {...stylex.props(styles.removeButton)}>
+      {...focusOutlineProps.focusVisible(styles.removeButton)}>
       <Icon icon="close" size="xsm" color="inherit" />
     </button>
   );
@@ -370,7 +349,7 @@ export function Token({
           {...sharedProps}
           {...mergeProps(
             themeProps('token', {color, size}),
-            stylex.props(
+            focusOutlineProps.focusVisible(
               styles.base,
               sizeStyles[size],
               colorStyles[color],
@@ -415,12 +394,11 @@ export function Token({
         {...sharedProps}
         {...mergeProps(
           themeProps('token', {color, size}),
-          stylex.props(
+          focusOutlineProps.focusWithin(
             styles.base,
             sizeStyles[size],
             colorStyles[color],
             styles.interactive,
-            styles.focusVisibleOutline,
             isDisabled && styles.disabled,
             xstyle,
           ),
@@ -447,12 +425,11 @@ export function Token({
         {...sharedProps}
         {...mergeProps(
           themeProps('token', {color, size}),
-          stylex.props(
+          focusOutlineProps.focusWithin(
             styles.base,
             sizeStyles[size],
             colorStyles[color],
             styles.interactive,
-            styles.focusVisibleOutline,
             isDisabled && styles.disabled,
             xstyle,
           ),

package/src/Tokenizer/Tokenizer.doc.mjs

@@ -210,7 +210,7 @@ export const docs = {
   ],
   theming: {
     targets: [
-      {className: 'astryx-tokenizer', visualProps: ['size', 'status']},
+      {className: 'astryx-tokenizer', visualProps: ['size', 'status'], states: ['disabled']},
     ],
   },
   usage: {
@@ -424,7 +424,7 @@ export const docsZh = {
   ],
   theming: {
     targets: [
-      {className: 'astryx-tokenizer', visualProps: ['size', 'status']},
+      {className: 'astryx-tokenizer', visualProps: ['size', 'status'], states: ['disabled']},
     ],
   },
   usage: {

package/src/Tokenizer/Tokenizer.test.tsx

@@ -1137,11 +1137,16 @@ describe('Tokenizer', () => {
   });
 });
 
-
 describe('Tokenizer statusVariant forwarding', () => {
   it('defaults to attached (status renders with data-variant="attached")', () => {
     const {container} = render(
-      <Tokenizer label="Members" searchSource={userSource} value={[]} onChange={() => {}} status={{type: 'error', message: 'Required'}} />,
+      <Tokenizer
+        label="Members"
+        searchSource={userSource}
+        value={[]}
+        onChange={() => {}}
+        status={{type: 'error', message: 'Required'}}
+      />,
     );
     expect(container.querySelector('.astryx-field-status')).toHaveAttribute(
       'data-variant',
@@ -1151,7 +1156,14 @@ describe('Tokenizer statusVariant forwarding', () => {
 
   it('forwards statusVariant="detached" to the underlying Field status', () => {
     const {container} = render(
-      <Tokenizer label="Members" searchSource={userSource} value={[]} onChange={() => {}} status={{type: 'error', message: 'Required'}} statusVariant="detached" />,
+      <Tokenizer
+        label="Members"
+        searchSource={userSource}
+        value={[]}
+        onChange={() => {}}
+        status={{type: 'error', message: 'Required'}}
+        statusVariant="detached"
+      />,
     );
     expect(container.querySelector('.astryx-field-status')).toHaveAttribute(
       'data-variant',
@@ -1159,3 +1171,33 @@ describe('Tokenizer statusVariant forwarding', () => {
     );
   });
 });
+
+describe('Tokenizer disabled theme state', () => {
+  it('reflects disabled on the root target so themes can gate paint on it', () => {
+    const {container} = render(
+      <Tokenizer
+        label="Members"
+        searchSource={userSource}
+        value={[]}
+        onChange={() => {}}
+        isDisabled
+      />,
+    );
+    const root = container.querySelector('.astryx-tokenizer');
+    expect(root).toHaveAttribute('data-disabled', 'disabled');
+    expect(root).toHaveClass('disabled');
+  });
+
+  it('omits data-disabled when enabled, like status does', () => {
+    const {container} = render(
+      <Tokenizer
+        label="Members"
+        searchSource={userSource}
+        value={[]}
+        onChange={() => {}}
+      />,
+    );
+    const root = container.querySelector('.astryx-tokenizer');
+    expect(root).not.toHaveAttribute('data-disabled');
+  });
+});

package/src/Tokenizer/Tokenizer.tsx

@@ -730,7 +730,11 @@ export function Tokenizer<T extends SearchableItem>({
       onBlurCapture={handleBlurCapture}
       data-testid={testId}
       {...mergeProps(
-        themeProps('tokenizer', {size, status: status?.type}),
+        themeProps('tokenizer', {
+          size,
+          status: status?.type,
+          disabled: isDisabled ? 'disabled' : null,
+        }),
         stylex.props(
           inputWrapperStyles.base,
           styles.wrapper,
@@ -828,7 +832,11 @@ export function Tokenizer<T extends SearchableItem>({
           ref={placeholderRef}
           onClick={handleWrapperClick}
           {...mergeProps(
-            themeProps('tokenizer', {size, status: status?.type}),
+            themeProps('tokenizer', {
+              size,
+              status: status?.type,
+              disabled: isDisabled ? 'disabled' : null,
+            }),
             stylex.props(
               inputWrapperStyles.base,
               styles.wrapper,

package/src/Tooltip/useTooltip.tsx

@@ -15,7 +15,6 @@
 import {
   useCallback,
   useEffect,
-  useMemo,
   useRef,
   type ReactNode,
   type RefCallback,
@@ -57,18 +56,6 @@ const styles = stylex.create({
     lineHeight: typeScaleVars['--text-body-leading'],
   },
   // Position-based margin styles
-  marginBlock: {
-    marginBlockStart: spacingVars['--spacing-1'],
-    marginBlockEnd: spacingVars['--spacing-1'],
-    marginInlineStart: 0,
-    marginInlineEnd: 0,
-  },
-  marginInline: {
-    marginBlockStart: 0,
-    marginBlockEnd: 0,
-    marginInlineStart: spacingVars['--spacing-1'],
-    marginInlineEnd: spacingVars['--spacing-1'],
-  },
   // Content wrapper for padding
   content: {
     paddingBlockStart: spacingVars['--spacing-1'],
@@ -261,22 +248,13 @@ export function useTooltip(options: TooltipOptions = {}): TooltipReturn {
     onHide,
   } = options;
 
-  // Select margin style based on placement axis
-  const marginStyle =
-    placement === 'above' || placement === 'below'
-      ? styles.marginBlock
-      : styles.marginInline;
-
   const layer = useLayer({
     mode: 'context',
     onShow,
     onHide,
   });
 
-  const popoverXstyle = useMemo(
-    () => [styles.container, marginStyle],
-    [marginStyle],
-  );
+  const popoverXstyle = styles.container;
 
   const showTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
   const hideTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
@@ -498,6 +476,7 @@ export function useTooltip(options: TooltipOptions = {}): TooltipReturn {
       const renderProps = {
         placement: renderPlacement,
         alignment: props?.alignment ?? alignment,
+        offset: spacingVars['--spacing-1'],
         role: 'tooltip',
         xstyle: [popoverXstyle, layerAnimations[renderPlacement]],
         className: themeProps('tooltip').className,

package/src/TopNav/TopNav.tsx

@@ -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.tsx

@@ -31,7 +31,7 @@ import {
 } from '../theme/tokens.stylex';
 import {usePopover} from '../Popover/usePopover';
 import {Link} from '../Link';
-import {useIcon} from '../Icon';
+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: {
@@ -313,7 +318,6 @@ export function TopNavHeading({
   ...props
 }: TopNavHeadingProps) {
   const t = useTranslator();
-  const chevronDownIcon = useIcon('chevronDown');
   const LinkComponent = useLinkComponent(as);
   // 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
@@ -404,7 +408,12 @@ export function TopNavHeading({
   );
 
   const chevronElement = showChevron && (
-    <span {...stylex.props(styles.chevron)}>{chevronDownIcon}</span>
+    <Icon
+      icon="chevronDown"
+      size="sm"
+      color="secondary"
+      xstyle={[styles.chevron, styles.chevronGlyph]}
+    />
   );
 
   const headerEndContentElement = headerEndContent && (
@@ -420,7 +429,12 @@ export function TopNavHeading({
       onClick={triggerProps.onClick}>
       {logo && <span {...stylex.props(styles.logo)}>{logo}</span>}
       {renderTextContent(
-        <span {...stylex.props(styles.popoverChevron)}>{chevronDownIcon}</span>,
+        <Icon
+          icon="chevronDown"
+          size="sm"
+          color="secondary"
+          xstyle={[styles.chevron, styles.chevronGlyph, styles.popoverChevron]}
+        />,
       )}
     </button>
   );
@@ -488,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')}
@@ -497,7 +513,12 @@ export function TopNavHeading({
               }}
               {...popover.triggerProps}
               {...stylex.props(styles.chevron, styles.interactive)}>
-              {chevronDownIcon}
+              <Icon
+                icon="chevronDown"
+                size="sm"
+                color="inherit"
+                xstyle={styles.chevronGlyph}
+              />
             </button>,
           )}
           {headerEndContentElement}
@@ -557,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')}
@@ -566,7 +590,12 @@ export function TopNavHeading({
                 }}
                 {...popover.triggerProps}
                 {...stylex.props(styles.chevron, styles.interactive)}>
-                {chevronDownIcon}
+                <Icon
+                  icon="chevronDown"
+                  size="sm"
+                  color="inherit"
+                  xstyle={styles.chevronGlyph}
+                />
               </button>
             ) : undefined,
           )}

package/src/TopNav/TopNavItem.tsx

@@ -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

@@ -7,6 +7,11 @@ export const docs = {
   subComponentOf: 'TopNav',
   displayName: 'Top Nav Mega Menu',
   description: 'Navigation item that displays a full-width mega menu panel on hover. Uses a slots API with items and featured props. TopNavMegaMenuItem renders itself in both desktop and mobile drawer modes. Supports inline collapsible drawer via render mode context.',
+  // The panel anchors to the nearest <nav>; wrap the preview in a TopNav so
+  // it opens below the bar instead of pinning to the viewport corner (#4905).
+  playground: {
+    wrapper: {component: 'TopNav'},
+  },
   props: [
     {
       name: 'label',