@astryxdesign/core 0.2.0 → 0.3.0

package/src/Toast/ToastViewport.tsx

@@ -3,6 +3,7 @@
 'use client';
 
 import {
+  isValidElement,
   useCallback,
   useEffect,
   useLayoutEffect,
@@ -10,10 +11,12 @@ import {
   useRef,
   useState,
 } from 'react';
+import type {ReactNode} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import {spacingVars, durationVars, easeVars} from '../theme/tokens.stylex';
 import {mergeProps} from '../utils';
 import {INTERACTIVE_SELECTORS} from '../hooks/useClickableContainer';
+import {useAnnounce} from '../hooks/useAnnounce';
 import {Toast} from './Toast';
 import {ToastContext, type ToastContextValue} from './ToastContext';
 import type {ToastEntry, ToastPosition, ToastDismissReason} from './types';
@@ -76,6 +79,29 @@ const styles = stylex.create({
   },
 });
 
+// Flatten a toast's rendered content (title, description, etc.) to the plain
+// text that should be spoken by a screen reader. Only text is announced —
+// interactive endContent is deliberately excluded (it is reachable via F6).
+function getNodeText(node: ReactNode): string {
+  if (node == null || typeof node === 'boolean') {
+    return '';
+  }
+  if (typeof node === 'string') {
+    return node;
+  }
+  if (typeof node === 'number') {
+    return String(node);
+  }
+  if (Array.isArray(node)) {
+    return node.map(getNodeText).filter(Boolean).join(' ');
+  }
+  if (isValidElement(node)) {
+    const {children} = node.props as {children?: ReactNode};
+    return getNodeText(children);
+  }
+  return '';
+}
+
 export interface ToastViewportProps {
   position?: ToastPosition;
   maxVisible?: number;
@@ -159,21 +185,54 @@ export function ToastViewport({
     [],
   );
 
-  const addToast = useCallback((entry: ToastEntry) => {
-    setToasts(prev => {
+  // Announce toasts through the persistent singleton live regions. Each
+  // <Toast> also renders its own role="status"/"alert" region, but that region
+  // is "born with content" — mounted together with its text — which many
+  // screen readers do not announce (see useAnnounce.ts); the singleton regions
+  // are mounted empty and only mutated afterwards, so they are what actually
+  // guarantees the announcement (the per-toast markup is kept for browse-mode
+  // discoverability). The announcement happens in addToast — the imperative
+  // dispatch path invoked once per useToast() call from an event handler,
+  // never from render — so each toast is announced exactly once by
+  // construction, independent of the React render lifecycle (StrictMode
+  // double-render/double-effect, viewport remounts, and unrelated list
+  // re-renders never re-announce). It is client-only (addToast never runs
+  // during SSR), so it is SSR-safe.
+  const announce = useAnnounce();
+
+  const addToast = useCallback(
+    (entry: ToastEntry) => {
       const {uniqueID, collisionBehavior = 'overwrite'} = entry.options;
-      if (uniqueID) {
-        const existing = prev.find(t => t.options.uniqueID === uniqueID);
-        if (existing) {
-          if (collisionBehavior === 'ignore') {
-            return prev;
+      // Resolve an ignored collision synchronously against the committed list
+      // so a suppressed toast is neither shown nor announced. The remaining
+      // announce + setToasts run outside the setToasts updater, which React may
+      // invoke more than once — keeping the announcement exactly-once.
+      if (
+        uniqueID &&
+        collisionBehavior === 'ignore' &&
+        toastsRef.current.some(t => t.options.uniqueID === uniqueID)
+      ) {
+        return;
+      }
+      const text = getNodeText(entry.options.body);
+      if (text) {
+        // Error toasts map to the assertive region (role="alert"); everything
+        // else to the polite region (role="status") — mirrors Toast.tsx.
+        announce(text, entry.options.type === 'error' ? 'assertive' : 'polite');
+      }
+      setToasts(prev => {
+        if (uniqueID) {
+          const existing = prev.find(t => t.options.uniqueID === uniqueID);
+          if (existing) {
+            // An ignored collision already returned above; overwrite in place.
+            return prev.map(t => (t.options.uniqueID === uniqueID ? entry : t));
           }
-          return prev.map(t => (t.options.uniqueID === uniqueID ? entry : t));
         }
-      }
-      return [...prev, entry];
-    });
-  }, []);
+        return [...prev, entry];
+      });
+    },
+    [announce],
+  );
 
   const removeToast = useCallback((id: string, reason: ToastDismissReason) => {
     // An exiting toast stays in toastsRef until its exit transition ends, so

package/src/Toast/useToast.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: 'useToast',
   displayName: 'useToast',
@@ -31,7 +31,7 @@ export const docs = {
   category: 'interaction',
 };
 
-/** @type {import('../docs-types').HookTranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').HookTranslationDoc} */
 export const docsDense = {
   description: 'Show toast notifications from anywhere in component tree. Returns function accepting toast options + showing notification. Works automatically w/ LayerProvider / self-mounts fallback viewport.',
   returnDescriptions: {

package/src/ToggleButton/ToggleButton.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: 'ToggleButton',
@@ -139,7 +139,7 @@ export const docs = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsZh = {
   usage: {
     description:
@@ -161,7 +161,7 @@ export const docsZh = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description: 'toggle btn w/ pressed/unpressed states, icon swap, group integration for single/multi-select',
   usage: {

package/src/ToggleButton/ToggleButton.test.tsx

@@ -14,6 +14,10 @@ import userEvent from '@testing-library/user-event';
 import {useState, type MouseEvent} from 'react';
 import {ToggleButton} from './ToggleButton';
 import {ToggleButtonGroup} from './ToggleButtonGroup';
+import {
+  getAllInjectedCss,
+  getForcedColorsRules,
+} from '../__tests__/forcedColors';
 
 // =============================================================================
 // ToggleButton — Standalone
@@ -517,3 +521,23 @@ describe('ToggleButtonGroup (multiple)', () => {
     );
   });
 });
+
+// jsdom cannot emulate forced-colors rendering, so these assert that the
+// compiled output includes the forced-colors rules; visual behavior needs
+// manual verification under Windows High Contrast.
+describe('forced colors (WCAG 1.4.11)', () => {
+  it('compiles forced-colors overrides so the pressed state survives Windows High Contrast', () => {
+    render(<ToggleButton label="Bold" isPressed onPressedChange={() => {}} />);
+    const css = getForcedColorsRules();
+    // The painted pressed overlay is stripped; Highlight/HighlightText marks
+    // the pressed toggle (critical for icon-only toggles, which otherwise
+    // lose all pressed indication).
+    expect(css).toContain('background-color: highlight;');
+    expect(css).toContain('color: highlighttext;');
+    // ToggleButton renders a <button>; without opting out of UA remapping it
+    // keeps the native ButtonFace surface and ignores the Highlight fill,
+    // leaving HighlightText text on a white surface. forced-color-adjust: none
+    // makes both render as authored.
+    expect(getAllInjectedCss()).toContain('forced-color-adjust: none;');
+  });
+});

package/src/ToggleButton/ToggleButton.tsx

@@ -17,7 +17,7 @@
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/ToggleButton/index.ts (exports if types change)
  * - /apps/storybook/stories/ToggleButton.stories.tsx
- * - /packages/cli/templates/blocks/components/ToggleButton/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/ToggleButton/ (showcase blocks)
  */
 
 import React, {useOptimistic, type ReactNode} from 'react';
@@ -40,7 +40,25 @@ import {themeProps} from '../utils/themeProps';
  */
 const pressedStyles = stylex.create({
   background: {
-    backgroundColor: colorVars['--color-overlay-pressed'],
+    // forced-color-adjust must be `none` here: ToggleButton renders a <button>,
+    // and the UA keeps native form-control colors (ButtonFace surface) for it
+    // under forced colors, ignoring the authored Highlight fill — the label kept
+    // its HighlightText color, giving white text on a white surface. Opting the
+    // pressed button out of UA remapping makes both the Highlight surface and
+    // the HighlightText label render as authored, restoring figure-ground.
+    forcedColorAdjust: 'none',
+    backgroundColor: {
+      default: colorVars['--color-overlay-pressed'],
+      // Forced colors (Windows High Contrast) strips the painted pressed
+      // overlay, which would leave icon-only toggles with no pressed
+      // indication at all. Highlight/HighlightText is the platform convention
+      // for a selected/pressed control (WCAG 1.4.11).
+      '@media (forced-colors: active)': 'Highlight',
+    },
+    color: {
+      default: null,
+      '@media (forced-colors: active)': 'HighlightText',
+    },
   },
 });
 

package/src/ToggleButton/ToggleButtonGroup.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: 'ToggleButtonGroup',

package/src/ToggleButton/ToggleButtonGroup.tsx

@@ -15,7 +15,7 @@
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/ToggleButton/index.ts
  * - /apps/storybook/stories/ToggleButton.stories.tsx
- * - /packages/cli/templates/blocks/components/ToggleButton/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/ToggleButton/ (showcase blocks)
  */
 
 import {createContext, useCallback, use, useMemo, type ReactNode} from 'react';
@@ -153,8 +153,7 @@ export interface ToggleButtonGroupMultipleProps extends ToggleButtonGroupBasePro
 
 /** Discriminated union of single and multiple group props. */
 export type ToggleButtonGroupProps =
-  | ToggleButtonGroupSingleProps
-  | ToggleButtonGroupMultipleProps;
+  ToggleButtonGroupSingleProps | ToggleButtonGroupMultipleProps;
 
 // =============================================================================
 // Component
@@ -176,9 +175,7 @@ export type ToggleButtonGroupProps =
  * </ToggleButtonGroup>
  * ```
  */
-export function ToggleButtonGroup(
-  props: ToggleButtonGroupProps,
-): ReactNode {
+export function ToggleButtonGroup(props: ToggleButtonGroupProps): ReactNode {
   const {
     children,
     label,

package/src/Token/Token.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: 'Token',
@@ -112,7 +112,7 @@ export const docs = {
   },
 };
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 export const docsZh = {
   name: 'Token',
   displayName: 'Token',
@@ -217,7 +217,7 @@ export const docsZh = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description: 'compact chip/tag for inline metadata, filters, selections. 11 colors, 3 sizes, removable, clickable, linkable.',
   usage: {

package/src/Token/Token.test.tsx

@@ -330,6 +330,151 @@ describe('Token accessibility', () => {
   });
 });
 
+describe('Token link with remove button', () => {
+  it('does not nest the remove button inside the link', () => {
+    render(<Token label="Tag" href="/test" onRemove={() => {}} />);
+    const link = screen.getByRole('link', {name: 'Tag'});
+    const removeButton = screen.getByRole('button', {name: 'Remove Tag'});
+    expect(link.contains(removeButton)).toBe(false);
+  });
+
+  it('keeps the link keyboard-focusable and fires onRemove from the sibling button', async () => {
+    const user = userEvent.setup();
+    const handleRemove = vi.fn();
+    render(<Token label="Tag" href="/test" onRemove={handleRemove} />);
+
+    const link = screen.getByRole('link', {name: 'Tag'});
+    expect(link.tagName).toBe('A');
+    expect(link).toHaveAttribute('href', '/test');
+
+    // Tab reaches the link first, then the remove button
+    await user.tab();
+    expect(link).toHaveFocus();
+    await user.tab();
+    const removeButton = screen.getByRole('button', {name: 'Remove Tag'});
+    expect(removeButton).toHaveFocus();
+
+    // Activating the remove button fires onRemove without involving the link
+    await user.keyboard('{Enter}');
+    expect(handleRemove).toHaveBeenCalledTimes(1);
+  });
+
+  it('wrapper structure matches the onClick branch pattern', () => {
+    render(
+      <Token
+        label="Tag"
+        href="/test"
+        onRemove={() => {}}
+        data-testid="link-token"
+      />,
+    );
+    render(
+      <Token
+        label="Tag"
+        onClick={() => {}}
+        onRemove={() => {}}
+        data-testid="click-token"
+      />,
+    );
+
+    const linkRoot = screen.getByTestId('link-token');
+    const clickRoot = screen.getByTestId('click-token');
+
+    // Both render a <span> container with the same visual classes
+    expect(linkRoot.tagName).toBe('SPAN');
+    expect(linkRoot.className).toBe(clickRoot.className);
+  });
+
+  it('clicking the container activates the link', () => {
+    render(
+      <Token
+        label="Tag"
+        href="/test"
+        onRemove={() => {}}
+        icon={<span data-testid="icon">★</span>}
+        data-testid="link-token"
+      />,
+    );
+    const link = screen.getByRole('link', {name: 'Tag'});
+    const handleLinkClick = vi.fn((e: MouseEvent) => e.preventDefault());
+    link.addEventListener('click', handleLinkClick);
+
+    // Clicking outside the anchor (e.g. the icon) still activates the link
+    fireEvent.click(screen.getByTestId('icon'));
+    expect(handleLinkClick).toHaveBeenCalledTimes(1);
+  });
+
+  it('clicking the remove button does not activate the link', () => {
+    const handleRemove = vi.fn();
+    render(<Token label="Tag" href="/test" onRemove={handleRemove} />);
+    const link = screen.getByRole('link', {name: 'Tag'});
+    const handleLinkClick = vi.fn((e: MouseEvent) => e.preventDefault());
+    link.addEventListener('click', handleLinkClick);
+
+    fireEvent.click(screen.getByRole('button', {name: 'Remove Tag'}));
+    expect(handleRemove).toHaveBeenCalledTimes(1);
+    expect(handleLinkClick).not.toHaveBeenCalled();
+  });
+
+  it('cmd/ctrl+click on the container opens the link in a new tab', () => {
+    const openSpy = vi.spyOn(window, 'open').mockImplementation(() => null);
+    render(
+      <Token
+        label="Tag"
+        href="/test"
+        onRemove={() => {}}
+        icon={<span data-testid="icon">★</span>}
+      />,
+    );
+
+    // Clicking the surface (not the anchor) with a modifier opens a new tab
+    // rather than navigating in place — provided by useClickableContainer.
+    fireEvent.click(screen.getByTestId('icon'), {metaKey: true});
+    expect(openSpy).toHaveBeenCalledWith('/test', '_blank', 'noopener');
+    openSpy.mockRestore();
+  });
+
+  it('middle-click on the container opens the link in a new tab', () => {
+    const openSpy = vi.spyOn(window, 'open').mockImplementation(() => null);
+    render(
+      <Token
+        label="Tag"
+        href="/test"
+        onRemove={() => {}}
+        icon={<span data-testid="icon">★</span>}
+      />,
+    );
+
+    fireEvent.mouseUp(screen.getByTestId('icon'), {button: 1});
+    expect(openSpy).toHaveBeenCalledWith('/test', '_blank', 'noopener');
+    openSpy.mockRestore();
+  });
+
+  it('a modified click that opens a new tab does not fire onRemove', () => {
+    const openSpy = vi.spyOn(window, 'open').mockImplementation(() => null);
+    const handleRemove = vi.fn();
+    render(
+      <Token
+        label="Tag"
+        href="/test"
+        onRemove={handleRemove}
+        icon={<span data-testid="icon">★</span>}
+      />,
+    );
+
+    fireEvent.click(screen.getByTestId('icon'), {metaKey: true});
+    fireEvent.mouseUp(screen.getByTestId('icon'), {button: 1});
+    expect(handleRemove).not.toHaveBeenCalled();
+    expect(openSpy).toHaveBeenCalledTimes(2);
+    openSpy.mockRestore();
+  });
+
+  it('link without onRemove still renders the anchor as the root', () => {
+    const {container} = render(<Token label="Link" href="/test" />);
+    expect(container.firstElementChild?.tagName).toBe('A');
+  });
+});
+
 describe('Token text overflow', () => {
   it('label element has overflow hidden and text-overflow ellipsis styles', () => {
     const {container} = render(<Token label="A very long label text" />);

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,16 @@ 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 {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.
@@ -313,7 +289,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 +328,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}
+      {...stylex.props(styles.removeButton)}>
+      <Icon icon="close" size="xsm" color="inherit" />
+    </button>
+  );
+
   const content = (
     <>
       {icon}
@@ -358,19 +350,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,11 +361,57 @@ 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}),
+            stylex.props(
+              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}),
@@ -394,14 +420,14 @@ export function Token({
             sizeStyles[size],
             colorStyles[color],
             styles.interactive,
+            styles.focusVisibleOutline,
             isDisabled && styles.disabled,
             xstyle,
           ),
           className,
           style,
-        )}>
-        {content}
-      </LinkComponent>
+        )}
+      />
     );
   }
 
@@ -448,19 +474,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>
     );
   }