@astryxdesign/core 0.1.9 → 0.2.0-canary.0b7a99e

package/src/Token/index.ts

@@ -11,5 +11,32 @@
  * SYNC: When adding new Token files, update exports here
  */
 
+/**
+ * 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;
+}
+
 export {Token} from './Token';
 export type {TokenProps, TokenColor, TokenSize} from './Token';

package/src/Tokenizer/Tokenizer.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: 'Tokenizer',
@@ -88,6 +88,13 @@ export const docs = {
       description:
         'Validation status object with type and message for error/warning/success states.',
     },
+    {
+      name: 'statusVariant',
+      type: "'attached' | 'detached'",
+      description:
+        'How the status message is placed relative to the input. attached overlaps directly below the input (bordered treatment); detached floats below as a separate element with spacing.',
+      default: "'attached'",
+    },
     {
       name: 'isLabelHidden',
       type: 'boolean',
@@ -185,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',
@@ -223,7 +237,7 @@ export const docs = {
   },
 };
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 export const docsZh = {
   name: 'Tokenizer',
   displayName: 'Tokenizer',
@@ -307,6 +321,13 @@ export const docsZh = {
       description:
         '\u9a8c\u8bc1\u72b6\u6001\u5bf9\u8c61\uff0c\u5305\u542b\u7c7b\u578b\u548c\u6d88\u606f\uff0c\u7528\u4e8e\u9519\u8bef/\u8b66\u544a/\u6210\u529f\u72b6\u6001\u3002',
     },
+    {
+      name: 'statusVariant',
+      type: "'attached' | 'detached'",
+      description:
+        '状态消息相对于输入框的放置方式。attached 直接叠加在输入框下方（带边框处理）；detached 作为独立元素浮于下方并留有间距。',
+      default: "'attached'",
+    },
     {
       name: 'isLabelHidden',
       type: 'boolean',
@@ -430,7 +451,7 @@ export const docsZh = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description: 'Multi-select typeahead w/ token chips for selected items. Composes BaseTypeahead for search+Token for chips.',
   usage: {
@@ -461,6 +482,7 @@ export const docsDense = {
     isDisabled: 'Disables input+all token interactions.',
     htmlName: 'HTML name attr; one hidden input per selected item id.',
     status: 'Validation status w/ type+message for error/warning/success.',
+    statusVariant: 'How status message is placed: attached overlaps below input; detached floats below w/ spacing.',
     isLabelHidden: 'Visually hides label; keeps a11y.',
     description: 'Helper text below label.',
     isRequired: 'Marks field required.',

package/src/Tokenizer/Tokenizer.test.tsx

@@ -1136,3 +1136,26 @@ 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'}} />,
+    );
+    expect(container.querySelector('.astryx-field-status')).toHaveAttribute(
+      'data-variant',
+      'attached',
+    );
+  });
+
+  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" />,
+    );
+    expect(container.querySelector('.astryx-field-status')).toHaveAttribute(
+      'data-variant',
+      'detached',
+    );
+  });
+});

package/src/Tokenizer/Tokenizer.tsx

@@ -12,7 +12,7 @@
  * SYNC: When modified, update:
  * - /packages/core/src/Tokenizer/index.ts
  * - /apps/storybook/stories/Tokenizer.stories.tsx
- * - /packages/cli/templates/blocks/components/Tokenizer/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/Tokenizer/ (showcase blocks)
  */
 
 import React, {
@@ -37,6 +37,7 @@ import {
   inputStatusBorderStyles,
   inputStatusHoverShadowStyles,
   inputStatusFocusWithinStyles,
+  type FieldStatusVariant,
 } from '../Field';
 import {Token} from '../Token';
 import {renderIconSlot, type IconType} from '../Icon';
@@ -111,6 +112,13 @@ export interface TokenizerProps<T extends SearchableItem> extends Omit<
   isOptional?: boolean;
   /** Validation status. */
   status?: InputStatus;
+  /**
+   * How the status message is placed relative to the input.
+   * - 'attached': message overlaps directly below the input (bordered treatment)
+   * - 'detached': message floats below as a separate element with spacing
+   * @default 'attached'
+   */
+  statusVariant?: FieldStatusVariant;
   /**
    * Icon to display at the start of the input.
    * Accepts a ReactNode (e.g. `<Icon icon={SearchIcon} />`) or an SVG icon component directly.
@@ -370,6 +378,7 @@ export function Tokenizer<T extends SearchableItem>({
   isRequired = false,
   isOptional = false,
   status,
+  statusVariant = 'attached',
   startIcon,
   labelTooltip,
   searchSource,
@@ -730,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],
         ),
       )}>
@@ -828,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],
             ),
           )}>
@@ -891,6 +902,7 @@ export function Tokenizer<T extends SearchableItem>({
             }
           : undefined
       }
+      statusVariant={statusVariant}
       labelTooltip={labelTooltip}
       width={width}
       xstyle={xstyle}

package/src/Toolbar/Toolbar.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: 'Toolbar',
@@ -156,7 +156,7 @@ export const docs = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsZh = {
   components: [
     {
@@ -191,7 +191,7 @@ export const docsZh = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description: 'Horizontal bar w/ left, center, right areas. For contextual actions in content, not page headers. Size cascades to children.',
   usage: {

package/src/Toolbar/Toolbar.tsx

@@ -13,7 +13,7 @@
  * - /packages/core/src/Toolbar/Toolbar.test.tsx
  * - /packages/core/src/Toolbar/index.ts
  * - /apps/storybook/stories/Toolbar.stories.tsx
- * - /packages/cli/templates/blocks/components/Toolbar/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/Toolbar/ (showcase blocks)
  */
 
 import {useCallback, type ReactNode} from 'react';

package/src/Tooltip/Tooltip.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: 'Tooltip',
@@ -109,7 +109,7 @@ export const docs = {
   },
 };
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 export const docsZh = {
   name: 'Tooltip',
   displayName: 'Tooltip',
@@ -208,7 +208,7 @@ export const docsZh = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description: 'Hover/focus triggered tooltip for displaying short, non-interactive text anchored to trigger element.',
   usage: {

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/Tooltip.tsx

@@ -11,7 +11,7 @@
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/Tooltip/index.ts
  * - /apps/storybook/stories/Tooltip.stories.tsx
- * - /packages/cli/templates/blocks/components/Tooltip/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/Tooltip/ (showcase blocks)
  */
 
 import React, {

package/src/Tooltip/useTooltip.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').HookDoc} */
+/** @type {import('@astryxdesign/cli/authoring').HookDoc} */
 export const docs = {
   name: 'useTooltip',
   displayName: 'useTooltip',
@@ -40,7 +40,7 @@ export const docs = {
   category: 'interaction',
 };
 
-/** @type {import('../docs-types').HookTranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').HookTranslationDoc} */
 export const docsDense = {
   description: 'Headless hover/focus tooltip hook. Builds on useLayer w/ hover intent, keyboard focus handling, aria-describedby. Use for custom triggers without wrapper component.',
   paramDescriptions: {

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.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: 'TopNav',
@@ -143,7 +143,7 @@ export const docs = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsZh = {
   usage: {
     description:
@@ -163,7 +163,7 @@ export const docsZh = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description: 'Top navigation bar for app headers w/ slot-based layout+companion nav item components.',
   usage: {

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/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';

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',

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';

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',
@@ -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.',