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

package/src/Token/Token.tsx

@@ -9,11 +9,12 @@
  * @position Core implementation; consumed by index.ts, tested by Token.test.tsx
  *
  * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/Token/TokenLink.tsx (interactive wrapper for href+onRemove)
  * - /packages/core/src/Token/Token.doc.mjs (props table, features, implementation notes)
  * - /packages/core/src/Token/Token.test.tsx (tests for new/changed behavior)
  * - /packages/core/src/Token/index.ts (exports if types change)
  * - /apps/storybook/stories/Token.stories.tsx (storybook stories)
- * - /packages/cli/templates/blocks/components/Token/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/Token/ (showcase blocks)
  */
 
 import type {ReactNode} from 'react';
@@ -32,41 +33,17 @@ import {Icon} from '../Icon';
 import {mergeProps} from '../utils';
 import {useLinkComponent} from '../Link/useLinkComponent';
 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';
 
 // =============================================================================
 // Types
 // =============================================================================
 
-/**
- * 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.
@@ -170,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',
@@ -204,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',
@@ -227,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',
@@ -313,7 +268,9 @@ const colorStyles = stylex.create({
  * `<span>` container with an invisible `<button>` when `onClick` is provided.
  * The invisible button pattern provides real button semantics for accessibility
  * while the container uses `:focus-within` to show focus outlines around the
- * entire token.
+ * entire token. When both `href` and `onRemove` are provided, the same
+ * container pattern is used with an invisible `<a>` so the remove `<button>`
+ * renders as a sibling of the link rather than nested inside it.
  *
  * @example
  * ```
@@ -350,6 +307,20 @@ export function Token({
   // if onClick was provided — the popover attaches its own handler.
   const effectiveOnClick = onClick ?? (role === 'button' ? () => {} : null);
 
+  const removeButton = onRemove != null && (
+    <button
+      type="button"
+      aria-label={t('@astryx.token.remove', {label})}
+      onClick={e => {
+        e.stopPropagation();
+        onRemove(e);
+      }}
+      disabled={isDisabled}
+      {...focusOutlineProps.focusVisible(styles.removeButton)}>
+      <Icon icon="close" size="xsm" color="inherit" />
+    </button>
+  );
+
   const content = (
     <>
       {icon}
@@ -358,19 +329,7 @@ export function Token({
         {label}
       </span>
       {endContent}
-      {onRemove != null && (
-        <button
-          type="button"
-          aria-label={t('@astryx.token.remove', {label})}
-          onClick={e => {
-            e.stopPropagation();
-            onRemove(e);
-          }}
-          disabled={isDisabled}
-          {...stylex.props(styles.removeButton)}>
-          <Icon icon="close" size="xsm" color="inherit" />
-        </button>
-      )}
+      {removeButton}
     </>
   );
 
@@ -381,15 +340,61 @@ export function Token({
   };
 
   if (role === 'link') {
+    if (onRemove == null) {
+      return (
+        <LinkComponent
+          ref={ref as React.Ref<HTMLAnchorElement>}
+          href={href as string}
+          aria-disabled={isDisabled || undefined}
+          {...sharedProps}
+          {...mergeProps(
+            themeProps('token', {color, size}),
+            focusOutlineProps.focusVisible(
+              styles.base,
+              sizeStyles[size],
+              colorStyles[color],
+              styles.interactive,
+              isDisabled && styles.disabled,
+              xstyle,
+            ),
+            className,
+            style,
+          )}>
+          {content}
+        </LinkComponent>
+      );
+    }
+
+    // With a remove button, the link cannot be the root — nesting a <button>
+    // inside an <a> is invalid HTML (WCAG 4.1.2). Delegate to TokenLink, a
+    // non-presentational wrapper that renders a <span> container with the link
+    // and the remove button as siblings and wires up useClickableContainer so
+    // the whole token surface activates the link (including middle-click and
+    // cmd/ctrl-click to open in a new tab). Token itself stays presentational
+    // (no refs/effects) per the @astryx/presentational-component rule.
     return (
-      <LinkComponent
-        ref={ref as React.Ref<HTMLAnchorElement>}
+      <TokenLink
+        ref={ref}
         href={href as string}
-        aria-disabled={isDisabled || undefined}
+        isDisabled={isDisabled}
+        LinkComponent={LinkComponent}
+        icon={icon}
+        endContent={endContent}
+        removeButton={removeButton}
+        linkStyleProps={stylex.props(styles.invisibleButton)}
+        labelContent={
+          <span
+            {...stylex.props(
+              styles.label,
+              isLabelHidden && styles.labelHidden,
+            )}>
+            {label}
+          </span>
+        }
         {...sharedProps}
         {...mergeProps(
           themeProps('token', {color, size}),
-          stylex.props(
+          focusOutlineProps.focusWithin(
             styles.base,
             sizeStyles[size],
             colorStyles[color],
@@ -399,9 +404,8 @@ export function Token({
           ),
           className,
           style,
-        )}>
-        {content}
-      </LinkComponent>
+        )}
+      />
     );
   }
 
@@ -421,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,
           ),
@@ -448,19 +451,7 @@ export function Token({
           </span>
         </button>
         {endContent}
-        {onRemove != null && (
-          <button
-            type="button"
-            aria-label={t('@astryx.token.remove', {label})}
-            onClick={e => {
-              e.stopPropagation();
-              onRemove(e);
-            }}
-            disabled={isDisabled}
-            {...stylex.props(styles.removeButton)}>
-            <Icon icon="close" size="xsm" color="inherit" />
-          </button>
-        )}
+        {removeButton}
       </span>
     );
   }

package/src/Token/TokenLink.tsx

@@ -0,0 +1,107 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file TokenLink.tsx
+ * @input Rendered token pieces (icon, label, endContent, remove button) plus
+ *   container/link styling props and the resolved LinkComponent
+ * @output Exports TokenLink, the interactive container for the href+onRemove Token variant
+ * @position Internal to Token; keeps Token.tsx presentational
+ *
+ * Token is a presentational component (see
+ * /internal/eslint-plugin-astryx/presentational-component.js) and must not use
+ * refs or effects. When a Token has both `href` and `onRemove`, the remove
+ * <button> must be a sibling of the link (nesting a button inside an anchor is
+ * invalid HTML — WCAG 4.1.2), so the surface becomes a clickable container that
+ * delegates to an inner link. That delegation needs refs, so it lives here.
+ *
+ * useClickableContainer gives the container middle-click and cmd/ctrl-click
+ * open-in-new-tab behavior for the link, ignores clicks on nested interactive
+ * elements (the remove button), and skips activation during text selection.
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/Token/Token.tsx (renders TokenLink for the href+onRemove case)
+ * - /packages/core/src/Token/Token.test.tsx (tests for delegated behavior)
+ */
+
+import type {ReactNode, CSSProperties, Ref, HTMLAttributes} from 'react';
+import {useRef} from 'react';
+import {mergeRefs} from '../utils';
+import {useClickableContainer} from '../hooks/useClickableContainer';
+import type {LinkComponentType} from '../Link/types';
+
+export interface TokenLinkProps extends HTMLAttributes<HTMLElement> {
+  /** Ref forwarded to the container element. */
+  ref?: Ref<HTMLElement>;
+  /** Link URL. */
+  href: string;
+  /** Whether the token is disabled. */
+  isDisabled: boolean;
+  /** Resolved link component (native `<a>` or a router link). */
+  LinkComponent: LinkComponentType;
+  /** `stylex.props()` output applied to the invisible inner link. */
+  linkStyleProps: {className?: string; style?: CSSProperties};
+  /** Visible (or visually hidden) label node rendered inside the link. */
+  labelContent: ReactNode;
+  /** Optional leading icon. */
+  icon?: ReactNode;
+  /** Content rendered after the label, before the remove button. */
+  endContent?: ReactNode;
+  /** The remove button node, rendered as a sibling of the link. */
+  removeButton: ReactNode;
+  /** Allow data-* attributes (e.g. data-testid, theme targets) on the container. */
+  [dataAttr: `data-${string}`]: unknown;
+}
+
+/**
+ * Interactive container for a Token that is both a link and removable.
+ *
+ * Renders a `<span>` wrapping an invisible inner link and the remove button as
+ * siblings. useClickableContainer delegates clicks on the surface to the link
+ * (including middle-click / cmd+click to open in a new tab) while the remove
+ * button keeps handling its own clicks.
+ */
+export function TokenLink({
+  ref,
+  href,
+  isDisabled,
+  LinkComponent,
+  linkStyleProps,
+  labelContent,
+  icon,
+  endContent,
+  removeButton,
+  ...containerProps
+}: TokenLinkProps) {
+  const containerRef = useRef<HTMLElement | null>(null);
+  const linkRef = useRef<HTMLElement | null>(null);
+
+  const {onClick, onMouseUp} = useClickableContainer({
+    containerRef,
+    interactiveRef: linkRef,
+    href,
+    disabled: isDisabled,
+  });
+
+  return (
+    <span
+      ref={mergeRefs(ref, containerRef)}
+      onClick={isDisabled ? undefined : onClick}
+      onMouseUp={isDisabled ? undefined : onMouseUp}
+      {...containerProps}>
+      {icon}
+      <LinkComponent
+        ref={linkRef as Ref<HTMLAnchorElement>}
+        href={href}
+        aria-disabled={isDisabled || undefined}
+        {...linkStyleProps}>
+        {labelContent}
+      </LinkComponent>
+      {endContent}
+      {removeButton}
+    </span>
+  );
+}
+
+TokenLink.displayName = 'TokenLink';

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, TokenColorMap, TokenSize} 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',
@@ -210,7 +210,7 @@ export const docs = {
   ],
   theming: {
     targets: [
-      {className: 'astryx-tokenizer', visualProps: ['size', 'status']},
+      {className: 'astryx-tokenizer', visualProps: ['size', 'status'], states: ['disabled']},
     ],
   },
   usage: {
@@ -237,7 +237,7 @@ export const docs = {
   },
 };
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 export const docsZh = {
   name: 'Tokenizer',
   displayName: 'Tokenizer',
@@ -424,7 +424,7 @@ export const docsZh = {
   ],
   theming: {
     targets: [
-      {className: 'astryx-tokenizer', visualProps: ['size', 'status']},
+      {className: 'astryx-tokenizer', visualProps: ['size', 'status'], states: ['disabled']},
     ],
   },
   usage: {
@@ -451,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: {

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

@@ -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, {
@@ -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/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.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/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

@@ -281,8 +281,8 @@ describe('TopNavHeading', () => {
     });
   });
 
-  it('renders as anchor when href is provided', () => {
-    render(<TopNavHeading heading="Home" href="/" />);
+  it('renders as anchor when headingHref is provided', () => {
+    render(<TopNavHeading heading="Home" headingHref="/" />);
     const link = screen.getByRole('link');
     expect(link).toHaveAttribute('href', '/');
   });