@astryxdesign/core 0.1.9-canary.d2d84f8 → 0.1.9-canary.e00a241

package/src/Timestamp/tooltipEntries.ts

@@ -0,0 +1,210 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file tooltipEntries.ts
+ * @input A Date and the consumer's tooltip entry list
+ * @output Pure formatting of one tooltip line per entry, plus the entry types
+ * @position Leaf module; owns which zone each tooltip line names and whether
+ *   it needs a zone abbreviation, then defers to formatInstant to render it
+ *
+ * This module holds only the decisions a tooltip makes that the visible text
+ * does not: resolving `timezoneID` (including the `'local'` alias and the
+ * fallback for an unknown identifier), and deciding which lines need a zone
+ * abbreviation to be told apart. The formatting itself is formatInstant's,
+ * shared with the rendered text, so the two surfaces cannot drift.
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/Timestamp/Timestamp.tsx
+ * - /packages/core/src/Timestamp/formatInstant.ts
+ * - /packages/core/src/Timestamp/tooltipEntries.test.ts
+ * - /packages/core/src/Timestamp/Timestamp.doc.mjs
+ * - /packages/core/src/Timestamp/index.ts
+ */
+
+import {devWarn} from '../utils/devWarning';
+import {formatInstant} from './formatInstant';
+import type {InstantFormat} from './formatInstant';
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/**
+ * Formats available to a tooltip line.
+ *
+ * Every `TimestampFormat` that names a fixed instant, plus `'full'` — the long
+ * absolute style the tooltip has always shown ("February 19, 2026 at 5:00:00 PM
+ * UTC"). `'relative'` and `'auto'` are excluded: a relative phrase ignores any
+ * zone, which would make `timezoneID` silently inert on that line.
+ *
+ * `'full'` lives only in this vocabulary, never in `TimestampFormat` — nothing
+ * asked for it as a visible display format, and keeping it out means new
+ * members added to `TimestampFormat` become valid tooltip formats for free.
+ *
+ * The public spelling of {@link InstantFormat}: consumers reading Timestamp's
+ * props should not have to know the name of its internal formatter.
+ */
+export type TimestampTooltipFormat = InstantFormat;
+
+/** One line of the Timestamp tooltip. */
+export interface TimestampTooltipEntry {
+  /**
+   * IANA time zone identifier, e.g. `'UTC'`, `'America/Los_Angeles'`.
+   * Omit it — or pass `'local'` — for the viewer's own zone.
+   *
+   * Prefer region identifiers. Fixed-offset abbreviations such as `'EST'` are
+   * accepted by the platform but never observe daylight saving, so they read
+   * an hour wrong for half the year — `'America/New_York'` is what people
+   * usually mean by "Eastern".
+   *
+   * An identifier the platform does not recognize falls back to the viewer's
+   * zone with a console warning rather than throwing.
+   */
+  timezoneID?: string;
+  /**
+   * How this line renders the instant.
+   * @default 'full'
+   */
+  format?: TimestampTooltipFormat;
+  /**
+   * Text shown beside the time, e.g. `'Local'`, `'UTC'`, `'Pacific'`.
+   * Supplied already translated; Timestamp never invents or localizes labels.
+   */
+  label?: string;
+}
+
+/** A rendered tooltip line. */
+export interface TimestampTooltipLine {
+  label?: string;
+  value: string;
+}
+
+// =============================================================================
+// Zone resolution
+// =============================================================================
+
+/** Spelling that means "the viewer's own zone" without naming it. */
+const LOCAL_ZONE_ALIAS = 'local';
+
+/**
+ * Zone identifiers already reported as unknown.
+ *
+ * Resolution runs once per entry on every render, so without this a single
+ * typo on a live timestamp would emit the same warning every tick, forever.
+ * One report per bad identifier is enough to act on.
+ */
+const warnedTimezoneIDs = new Set<string>();
+
+/**
+ * Resolves an entry's zone to something safe to hand to `Intl`.
+ *
+ * Returns `undefined` for the viewer's own zone, which is also what `Intl`
+ * treats as "use the host zone" — so the local path never constructs a
+ * formatter with an explicit `timeZone` and cannot drift from today's output.
+ */
+function resolveTimezoneID(timezoneID: string | undefined): string | undefined {
+  if (
+    timezoneID === undefined ||
+    timezoneID.toLowerCase() === LOCAL_ZONE_ALIAS
+  ) {
+    return undefined;
+  }
+
+  // An unrecognized identifier makes every Intl.DateTimeFormat constructor
+  // throw a RangeError. Rendering a timestamp must never take down the tree —
+  // degrade to the viewer's zone and say so, mirroring how an unparseable
+  // `value` is handled in Timestamp.tsx.
+  try {
+    new Intl.DateTimeFormat(undefined, {timeZone: timezoneID});
+  } catch {
+    if (!warnedTimezoneIDs.has(timezoneID)) {
+      warnedTimezoneIDs.add(timezoneID);
+      devWarn(
+        'Timestamp',
+        `unknown time zone ${JSON.stringify(timezoneID)} in tooltipEntries. Falling back to the viewer's time zone.`,
+      );
+    }
+    return undefined;
+  }
+
+  return timezoneID;
+}
+
+/**
+ * A stable key for "which zone did the consumer ask for", used to decide
+ * whether the tooltip needs zone abbreviations to disambiguate its lines.
+ *
+ * Deliberately keyed on the *requested* zone, not on the resolved offset: a
+ * consumer who asks for two zones gets both labelled even when the viewer
+ * happens to be sitting in one of them, so the rendering does not change shape
+ * depending on where the reader is. That also keeps this testable under any
+ * machine timezone.
+ */
+function zoneKey(resolved: string | undefined): string {
+  return resolved === undefined ? LOCAL_ZONE_ALIAS : resolved.toLowerCase();
+}
+
+// =============================================================================
+// Zone marking
+// =============================================================================
+
+/**
+ * Whether a format should carry a zone abbreviation.
+ *
+ * `'full'` always has one (that is the style). `system_*` never does — those
+ * are machine shapes and a trailing "PST" would break anything parsing them,
+ * which is also why `isTimezoneShown` has never applied to them.
+ *
+ * The two human formats that can carry one do so when either the reader has
+ * to tell several lines apart, or the line shows a zone the consumer named
+ * explicitly. That second case matters even for a lone entry: the tooltip is
+ * the `<time>` element's `aria-describedby`, and that element's accessible
+ * name is the absolute time in the *viewer's* zone — so an unmarked foreign
+ * time is announced directly after a local one with nothing to distinguish
+ * them. A line the consumer did not steer stays unmarked, matching how the
+ * visible text reads with `isTimezoneShown` off.
+ */
+function shouldShowZoneName(
+  format: TimestampTooltipFormat,
+  hasMultipleZones: boolean,
+  isNamedZone: boolean,
+): boolean {
+  if (format === 'full') {
+    return true;
+  }
+  if (format === 'date_time' || format === 'time') {
+    return hasMultipleZones || isNamedZone;
+  }
+  return false;
+}
+
+/**
+ * Renders one tooltip line per entry, in the order given.
+ *
+ * Pure: the same `date` and `entries` always produce the same lines for a given
+ * host zone and locale.
+ */
+export function formatTooltipLines(
+  date: Date,
+  entries: ReadonlyArray<TimestampTooltipEntry>,
+): ReadonlyArray<TimestampTooltipLine> {
+  const resolved = entries.map(entry => resolveTimezoneID(entry.timezoneID));
+  const hasMultipleZones = new Set(resolved.map(zoneKey)).size > 1;
+
+  return entries.map((entry, index) => {
+    const format = entry.format ?? 'full';
+    const timeZone = resolved[index];
+
+    return {
+      ...(entry.label === undefined ? {} : {label: entry.label}),
+      value: formatInstant(date, format, {
+        timeZone,
+        isTimezoneShown: shouldShowZoneName(
+          format,
+          hasMultipleZones,
+          timeZone !== undefined,
+        ),
+      }),
+    };
+  });
+}

package/src/Token/Token.test.tsx

@@ -13,6 +13,7 @@ import {describe, it, expect, vi} from 'vitest';
 import {render, screen, fireEvent} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {Token} from './Token';
+import type {TokenColor} from './Token';
 
 describe('Token', () => {
   it('renders with label', () => {
@@ -51,6 +52,23 @@ describe('Token', () => {
     }
   });
 
+  it('reflects a custom (theme-augmented) color as a class and data attribute', () => {
+    // Themes extend TokenColorMap via module augmentation and supply the
+    // styling through generated theme CSS; the runtime just forwards the
+    // value as the stable class + data-color reflection so the theme
+    // selector can match. Cast simulates a consumer-augmented color.
+    render(
+      <Token
+        label="Brand"
+        color={'brand' as TokenColor}
+        data-testid="token-custom"
+      />,
+    );
+    const token = screen.getByTestId('token-custom');
+    expect(token).toHaveClass('astryx-token', 'brand');
+    expect(token).toHaveAttribute('data-color', 'brand');
+  });
+
   it('renders as a span with invisible button when onClick is provided', () => {
     const handleClick = vi.fn();
     render(
@@ -135,10 +153,7 @@ describe('Token', () => {
 
   it('renders endContent', () => {
     render(
-      <Token
-        label="Token"
-        endContent={<span data-testid="end">End</span>}
-      />,
+      <Token label="Token" endContent={<span data-testid="end">End</span>} />,
     );
     expect(screen.getByTestId('end')).toBeInTheDocument();
     expect(screen.getByText('End')).toBeInTheDocument();
@@ -241,12 +256,7 @@ describe('Token accessibility', () => {
 
   it('disables both buttons when isDisabled is true', () => {
     render(
-      <Token
-        label="Token"
-        onClick={() => {}}
-        onRemove={() => {}}
-        isDisabled
-      />,
+      <Token label="Token" onClick={() => {}} onRemove={() => {}} isDisabled />,
     );
     const buttons = screen.getAllByRole('button');
     for (const button of buttons) {
@@ -355,11 +365,7 @@ describe('Token focus outline', () => {
   it('invisible button does not show its own focus outline', async () => {
     const user = userEvent.setup();
     render(
-      <Token
-        label="Focusable"
-        onClick={() => {}}
-        data-testid="focus-token"
-      />,
+      <Token label="Focusable" onClick={() => {}} data-testid="focus-token" />,
     );
     const button = screen.getByRole('button', {name: 'Focusable'});
     await user.tab();

package/src/Token/Token.tsx

@@ -5,7 +5,7 @@
 /**
  * @file Token.tsx
  * @input Uses React, ReactNode, StyleXStyles
- * @output Exports Token component, TokenProps, TokenColor types
+ * @output Exports Token component, TokenProps, TokenColor, TokenColorMap types
  * @position Core implementation; consumed by index.ts, tested by Token.test.tsx
  *
  * SYNC: When modified, update these files to stay in sync:
@@ -41,20 +41,37 @@ import {useTranslator} from '../i18n';
 // =============================================================================
 
 /**
- * Available color variants for the token.
+ * Extensible color map for Token.
+ *
+ * Theme packages can add custom colors via TypeScript module augmentation:
+ * @example
+ * ```
+ * declare module '@astryxdesign/core/Token' {
+ *   interface TokenColorMap {
+ *     brand: true;
+ *   }
+ * }
+ * ```
+ */
+export interface TokenColorMap {
+  default: true;
+  red: true;
+  orange: true;
+  yellow: true;
+  green: true;
+  teal: true;
+  cyan: true;
+  blue: true;
+  purple: true;
+  pink: true;
+  gray: true;
+}
+
+/**
+ * Token color type derived from TokenColorMap.
+ * Extensible via module augmentation of TokenColorMap.
  */
-export type TokenColor =
-  | 'default'
-  | 'red'
-  | 'orange'
-  | 'yellow'
-  | 'green'
-  | 'teal'
-  | 'cyan'
-  | 'blue'
-  | 'purple'
-  | 'pink'
-  | 'gray';
+export type TokenColor = keyof TokenColorMap;
 
 export type TokenSize = 'sm' | 'md' | 'lg';
 

package/src/Token/index.ts

@@ -12,4 +12,4 @@
  */
 
 export {Token} from './Token';
-export type {TokenProps, TokenColor, TokenSize} from './Token';
+export type {TokenProps, TokenColor, TokenColorMap, TokenSize} from './Token';

package/src/Tokenizer/Tokenizer.doc.mjs

@@ -192,7 +192,14 @@ export const docs = {
     {
       name: 'handleRef',
       type: 'React.Ref<TokenizerHandle>',
-      description: 'Imperative handle for focus() and blur() control.',
+      description:
+        'Imperative handle exposing focusInput(), focusFirstToken(), focusLastToken(), clearInput(), and selectAll().',
+    },
+    {
+      name: 'width',
+      type: 'SizeValue',
+      description:
+        'Width of the field (number = pixels, string used as-is, e.g. "100%"). Sizes the whole field (label, control, and status) so they stay aligned.',
     },
     {
       name: 'xstyle',

package/src/Tokenizer/Tokenizer.tsx

@@ -739,7 +739,7 @@ export function Tokenizer<T extends SearchableItem>({
           isTruncated && styles.truncatedWrapper,
           isDisabled && inputWrapperStyles.disabled,
           status && inputStatusBorderStyles[status.type],
-          status && inputStatusHoverShadowStyles[status.type],
+          status && !isDisabled && inputStatusHoverShadowStyles[status.type],
           status && inputStatusFocusWithinStyles[status.type],
         ),
       )}>
@@ -837,7 +837,9 @@ export function Tokenizer<T extends SearchableItem>({
               isTruncated && styles.truncatedWrapper,
               isDisabled && inputWrapperStyles.disabled,
               status && inputStatusBorderStyles[status.type],
-              status && inputStatusHoverShadowStyles[status.type],
+              status &&
+                !isDisabled &&
+                inputStatusHoverShadowStyles[status.type],
               status && inputStatusFocusWithinStyles[status.type],
             ),
           )}>

package/src/Tooltip/Tooltip.test.tsx

@@ -221,4 +221,50 @@ describe('Tooltip', () => {
       expect(onOpenChange).not.toHaveBeenCalledWith(false);
     });
   });
+
+  describe('press-to-dismiss', () => {
+    it('hides the tooltip when the trigger is pressed', async () => {
+      const onOpenChange = vi.fn();
+      render(
+        <Tooltip content="Copy link" onOpenChange={onOpenChange} delay={0}>
+          <button type="button">Trigger</button>
+        </Tooltip>,
+      );
+
+      const trigger = screen.getByRole('button', {name: 'Trigger'});
+      fireEvent.mouseEnter(trigger);
+      await waitFor(() => {
+        expect(onOpenChange).toHaveBeenCalledWith(true);
+      });
+
+      fireEvent.pointerDown(trigger);
+      await waitFor(() => {
+        expect(onOpenChange).toHaveBeenCalledWith(false);
+      });
+    });
+
+    it('does not press-dismiss a controlled tooltip', async () => {
+      const onOpenChange = vi.fn();
+      render(
+        <Tooltip
+          content="Controlled"
+          isOpen
+          onOpenChange={onOpenChange}
+          delay={0}>
+          <button type="button">Trigger</button>
+        </Tooltip>,
+      );
+
+      const trigger = screen.getByRole('button', {name: 'Trigger'});
+      await waitFor(() => {
+        expect(onOpenChange).toHaveBeenCalledWith(true);
+      });
+      onOpenChange.mockClear();
+
+      fireEvent.pointerDown(trigger);
+      // Give any (incorrect) async hide a chance to run.
+      await new Promise(r => setTimeout(r, 20));
+      expect(onOpenChange).not.toHaveBeenCalledWith(false);
+    });
+  });
 });

package/src/Tooltip/useTooltip.tsx

@@ -366,6 +366,19 @@ export function useTooltip(options: TooltipOptions = {}): TooltipReturn {
     scheduleHide();
   }, [scheduleHide]);
 
+  // Pressing the trigger hides its own tooltip: once the control is activated
+  // the hint has served its purpose, and a tooltip lingering over a
+  // just-pressed control reads as stale. Fires on pointerdown so it feels
+  // immediate. Uncontrolled tooltips only — a controlled tooltip's visibility
+  // is owned by the consumer. `layer.hide()` self-guards when already closed.
+  const handlePointerDown = useCallback(() => {
+    if (isOpen !== undefined) {
+      return;
+    }
+    clearTimeouts();
+    layer.hide();
+  }, [isOpen, clearTimeouts, layer]);
+
   // Interaction ref that handles event listeners only
   const interactionRef: RefCallback<HTMLElement> = useCallback(
     (el: HTMLElement | null) => {
@@ -375,12 +388,18 @@ export function useTooltip(options: TooltipOptions = {}): TooltipReturn {
         triggerRef.current.removeEventListener('mouseleave', handleMouseLeave);
         triggerRef.current.removeEventListener('focusin', handleFocusIn);
         triggerRef.current.removeEventListener('focusout', handleFocusOut);
+        triggerRef.current.removeEventListener(
+          'pointerdown',
+          handlePointerDown,
+        );
       }
 
       if (el) {
         // Attach hover listeners
         el.addEventListener('mouseenter', handleMouseEnter);
         el.addEventListener('mouseleave', handleMouseLeave);
+        // Press-to-dismiss: activating the trigger hides its own tooltip.
+        el.addEventListener('pointerdown', handlePointerDown);
 
         // Attach focus listeners based on focusTrigger option
         const shouldAttachFocus =
@@ -401,6 +420,7 @@ export function useTooltip(options: TooltipOptions = {}): TooltipReturn {
       handleMouseLeave,
       handleFocusIn,
       handleFocusOut,
+      handlePointerDown,
     ],
   );
 

package/src/TopNav/TopNav.test.tsx

@@ -420,12 +420,103 @@ describe('TopNavItem', () => {
 
   it('applies aria-disabled when isDisabled', () => {
     render(<TopNavItem label="Home" href="#" isDisabled />);
-    expect(screen.getByRole('link')).toHaveAttribute('aria-disabled', 'true');
+    expect(screen.getByText('Home').closest('a')).toHaveAttribute(
+      'aria-disabled',
+      'true',
+    );
   });
 
   it('sets tabIndex to -1 when disabled', () => {
     render(<TopNavItem label="Home" href="#" isDisabled />);
-    expect(screen.getByRole('link')).toHaveAttribute('tabIndex', '-1');
+    expect(screen.getByText('Home').closest('a')).toHaveAttribute(
+      'tabIndex',
+      '-1',
+    );
+  });
+
+  describe('disabled items do not navigate', () => {
+    it('drops href/target and suppresses clicks when disabled (default mode)', () => {
+      const handleClick = vi.fn();
+      render(
+        <TopNavItem
+          label="Home"
+          href="/home"
+          target="_blank"
+          onClick={handleClick}
+          isDisabled
+        />,
+      );
+      // An href-less anchor exposes no link role, so it is not announced
+      // with a live destination.
+      expect(screen.queryByRole('link')).not.toBeInTheDocument();
+      const item = screen.getByText('Home').closest('a') as HTMLAnchorElement;
+      expect(item).not.toHaveAttribute('href');
+      expect(item).not.toHaveAttribute('target');
+      expect(item).toHaveAttribute('aria-disabled', 'true');
+      expect(item).toHaveAttribute('tabIndex', '-1');
+
+      // fireEvent bypasses pointer-events: none, simulating programmatic/AT
+      // activation. It returns false when preventDefault was called, i.e.
+      // any default navigation behavior is cancelled.
+      const notCancelled = fireEvent.click(item);
+      expect(notCancelled).toBe(false);
+      expect(handleClick).not.toHaveBeenCalled();
+    });
+
+    it('drops href/target and suppresses clicks when disabled (drawer mode)', () => {
+      const handleClick = vi.fn();
+      render(
+        <TopNavRenderContext value="drawer">
+          <TopNavItem
+            label="Home"
+            href="/home"
+            target="_blank"
+            onClick={handleClick}
+            isDisabled
+          />
+        </TopNavRenderContext>,
+      );
+      expect(screen.queryByRole('link')).not.toBeInTheDocument();
+      const item = screen.getByText('Home').closest('a') as HTMLAnchorElement;
+      expect(item).not.toHaveAttribute('href');
+      expect(item).not.toHaveAttribute('target');
+      expect(item).toHaveAttribute('aria-disabled', 'true');
+      expect(item).toHaveAttribute('tabIndex', '-1');
+
+      // fireEvent bypasses pointer-events: none, simulating programmatic/AT
+      // activation. It returns false when preventDefault was called.
+      const notCancelled = fireEvent.click(item);
+      expect(notCancelled).toBe(false);
+      expect(handleClick).not.toHaveBeenCalled();
+    });
+
+    it('keeps href and click behavior for enabled items (default mode)', async () => {
+      const user = userEvent.setup();
+      const handleClick = vi.fn();
+      render(<TopNavItem label="Home" href="#" onClick={handleClick} />);
+      const link = screen.getByRole('link', {name: 'Home'});
+      expect(link).toHaveAttribute('href', '#');
+      expect(link).not.toHaveAttribute('aria-disabled');
+
+      await user.click(link);
+      expect(handleClick).toHaveBeenCalledTimes(1);
+    });
+
+    it('keeps href and click behavior for enabled items (drawer mode)', async () => {
+      const user = userEvent.setup();
+      const handleClick = vi.fn();
+      render(
+        <TopNavRenderContext value="drawer">
+          <TopNavItem label="Home" href="#" onClick={handleClick} />
+        </TopNavRenderContext>,
+      );
+      const link = screen.getByRole('link', {name: 'Home'});
+      expect(link).toHaveAttribute('href', '#');
+      expect(link).not.toHaveAttribute('aria-disabled');
+
+      await user.click(link);
+      expect(handleClick).toHaveBeenCalledTimes(1);
+    });
   });
 
   it('renders icon with label', () => {

package/src/TopNav/TopNavItem.doc.mjs

@@ -29,7 +29,7 @@ export const docs = {
     {
       name: 'isDisabled',
       type: 'boolean',
-      description: 'Whether the nav item is disabled. Sets aria-disabled and prevents interaction.',
+      description: 'Whether the nav item is disabled. Sets aria-disabled, drops href/target so the item cannot navigate, and prevents interaction.',
       default: 'false',
     },
     {
@@ -91,7 +91,7 @@ export const docsZh = {
     {
       name: 'isDisabled',
       type: 'boolean',
-      description: '导航项是否被禁用。设置 aria-disabled 并阻止交互。',
+      description: '导航项是否被禁用。设置 aria-disabled，移除 href/target 使其无法导航，并阻止交互。',
       default: 'false',
     },
     {
@@ -121,7 +121,7 @@ export const docsDense = {
     label: 'Visible text or aria-label when isIconOnly is true.',
     href: 'Navigation URL.',
     isSelected: 'Sets aria-current="page"+highlighted styles.',
-    isDisabled: 'Sets aria-disabled, prevents interaction.',
+    isDisabled: 'Sets aria-disabled, drops href/target (no navigation), prevents interaction.',
     icon: 'Icon before label.',
     children: 'Custom content instead of label text.',
     as: 'Custom link component. Overrides LinkProvider default. Must accept href, className, style, children.',