@astryxdesign/core 0.6.2 → 0.6.3-canary.0899f21

package/src/Chat/__tests__/ChatMessageMetadata.a11y.chromium.spec.ts

@@ -0,0 +1,413 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file ChatMessageMetadata.a11y.chromium.spec.ts
+ * @input Exact-head Storybook build and component-owned metadata fixtures
+ * @output Chromium PNGs, semantic/paint sensor receipts, and a fail-closed manifest
+ * @position Browser evidence for the ChatMessageMetadata component audit
+ */
+
+import {createHash} from 'node:crypto';
+import {execFileSync} from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {expect, test, type Page} from '@playwright/test';
+import {holdMotionStill} from '@astryxdesign/a11y-spec/chromium';
+import {
+  DEFAULT_STORYBOOK_DIR,
+  serveStorybook,
+  type StaticServer,
+} from '@astryxdesign/a11y-spec/storybook';
+
+const OUTPUT = path.resolve(
+  'test-results/chat-message-metadata-audit-evidence',
+);
+const STATES = 'core-chatmessagemetadata--states';
+const NARROW = 'core-chatmessagemetadata--narrow-overflow';
+const LABELS = {
+  sending: 'Sending',
+  sent: 'Sent',
+  delivered: 'Delivered',
+  read: 'Read',
+  error: 'Failed',
+} as const;
+
+interface Case {
+  name: string;
+  storyId: string;
+  rootCount: number;
+  text: string;
+  status?: keyof typeof LABELS;
+  button?: boolean;
+  sender?: 'user' | 'assistant';
+}
+
+// These expectations are fixture/source facts, never values copied from a page.
+const CASES: Case[] = [
+  ...Object.entries(LABELS).map(([status, label]) => ({
+    name: `status-${status}`,
+    storyId: STATES,
+    rootCount: 1,
+    text: `10:30·${label}`,
+    status: status as keyof typeof LABELS,
+    sender: 'user' as const,
+  })),
+  {
+    name: 'assistant-footer',
+    storyId: STATES,
+    rootCount: 1,
+    text: '10:31·Copy reply',
+    button: true,
+    sender: 'assistant',
+  },
+  {
+    name: 'empty-footer',
+    storyId: STATES,
+    rootCount: 1,
+    text: '10:32',
+    sender: 'assistant',
+  },
+  {
+    name: 'empty-timestamp',
+    storyId: STATES,
+    rootCount: 1,
+    text: 'Model info',
+    sender: 'assistant',
+  },
+  {
+    name: 'empty-row',
+    storyId: STATES,
+    rootCount: 0,
+    text: '',
+    sender: 'assistant',
+  },
+  {
+    name: 'numeric-slots',
+    storyId: STATES,
+    rootCount: 1,
+    text: '0·0',
+    sender: 'user',
+  },
+  {
+    name: 'standalone',
+    storyId: STATES,
+    rootCount: 1,
+    text: '11:00·Read',
+    status: 'read',
+  },
+  {
+    name: 'narrow-overflow',
+    storyId: NARROW,
+    rootCount: 1,
+    text: '10:32·A longer metadata description that can grow when translated into a different language·Delivered',
+    status: 'delivered',
+    sender: 'assistant',
+  },
+];
+
+let server: StaticServer;
+let head: string;
+let build: string;
+const frames: Record<string, unknown>[] = [];
+
+test.beforeAll(async () => {
+  head = execFileSync('git', ['rev-parse', 'HEAD'], {encoding: 'utf8'}).trim();
+  if (process.env.ASTRYX_HEAD_SHA && process.env.ASTRYX_HEAD_SHA !== head) {
+    throw new Error('PR head differs from the checked out source');
+  }
+  server = await serveStorybook(
+    process.env.ASTRYX_STORYBOOK_DIR ?? DEFAULT_STORYBOOK_DIR,
+  );
+  const stamp = await fetch(`${server.origin}/astryx-build-sha.txt`);
+  if (!stamp.ok) {
+    throw new Error('Storybook build is missing its source stamp');
+  }
+  build = (await stamp.text()).trim();
+  if (build !== head) {
+    throw new Error('Storybook bytes differ from the PR head');
+  }
+  fs.mkdirSync(OUTPUT, {recursive: true});
+});
+
+test.afterAll(async () => {
+  const previous = fs.existsSync(path.join(OUTPUT, 'manifest.json'))
+    ? (JSON.parse(fs.readFileSync(path.join(OUTPUT, 'manifest.json'), 'utf8'))
+        .frames ?? [])
+    : [];
+  if (head && build) {
+    fs.writeFileSync(
+      path.join(OUTPUT, 'manifest.json'),
+      `${JSON.stringify(
+        {
+          version: 1,
+          component: 'core/ChatMessageMetadata',
+          headSha: head,
+          storybookSha: build,
+          frames: [...previous, ...frames].filter(
+            (frame, index, all) =>
+              all.findIndex(
+                other =>
+                  other.state === frame.state &&
+                  other.mode === frame.mode &&
+                  other.direction === frame.direction,
+              ) === index,
+          ),
+        },
+        null,
+        2,
+      )}\n`,
+    );
+  }
+  await server?.close();
+});
+
+async function capture(
+  page: Page,
+  scenario: Case,
+  mode: 'light' | 'dark',
+  direction: 'ltr' | 'rtl',
+  options: {
+    viewport?: {width: number; height: number};
+    coarsePointer?: boolean;
+    state?: string;
+  } = {},
+) {
+  const viewport = options.viewport ?? {width: 1024, height: 768};
+  const state = options.state ?? scenario.name;
+  const errors: string[] = [];
+  const onError = (error: Error) => errors.push(String(error));
+  page.on('pageerror', onError);
+  await page.setViewportSize(viewport);
+  await page.goto(
+    `${server.origin}/iframe.html?id=${scenario.storyId}&viewMode=story&globals=colorMode:${mode};astryxTheme:neutral;direction:${direction}`,
+  );
+  const panel = page.locator(`[data-metadata-case="${scenario.name}"]`);
+  await panel.waitFor();
+  await page.waitForFunction(
+    expected =>
+      document.documentElement.getAttribute('data-theme') === expected,
+    mode,
+  );
+  await holdMotionStill(page);
+  await page.evaluate(async () => document.fonts.ready);
+  const roots = panel.locator('.astryx-chat-message-metadata');
+  const actual = await panel.evaluate((element, expected) => {
+    const root = element.querySelector('.astryx-chat-message-metadata');
+    const status = root?.querySelector('[title]');
+    const rect = element.getBoundingClientRect();
+    const rootStyle = root ? getComputedStyle(root) : null;
+    return {
+      rootCount: element.querySelectorAll('.astryx-chat-message-metadata')
+        .length,
+      text: (root?.textContent ?? '').replace(/\s+/g, ' ').trim(),
+      direction: rootStyle?.direction ?? getComputedStyle(element).direction,
+      color: rootStyle?.color ?? null,
+      fontSize: rootStyle?.fontSize ?? null,
+      statusColor: status ? getComputedStyle(status).color : null,
+      statusTitle: status?.getAttribute('title') ?? null,
+      statusLabel: status?.getAttribute('aria-label') ?? null,
+      buttonCount: element.querySelectorAll('button').length,
+      sender:
+        element.querySelector('article')?.getAttribute('data-sender') ?? null,
+      overflowFree: element.scrollWidth <= element.clientWidth + 1,
+      rootWidth: root?.getBoundingClientRect().width ?? null,
+      childX: root
+        ? [...root.children].map(child => child.getBoundingClientRect().x)
+        : [],
+      geometry: {x: rect.x, y: rect.y, width: rect.width, height: rect.height},
+      rootVisible: root
+        ? root.getBoundingClientRect().width > 0 &&
+          root.getBoundingClientRect().height > 0
+        : false,
+      storyError: [
+        ...document.querySelectorAll(
+          '.sb-errordisplay, [data-testid="story-error"]',
+        ),
+      ].some(node => {
+        const box = node.getBoundingClientRect();
+        const style = getComputedStyle(node);
+        return (
+          box.width > 0 &&
+          box.height > 0 &&
+          box.bottom > 0 &&
+          box.right > 0 &&
+          box.top < innerHeight &&
+          box.left < innerWidth &&
+          style.display !== 'none' &&
+          style.visibility !== 'hidden' &&
+          style.opacity !== '0'
+        );
+      }),
+      mode: document.documentElement.getAttribute('data-theme'),
+      theme: document
+        .querySelector('[data-astryx-theme]')
+        ?.getAttribute('data-astryx-theme'),
+      colorScheme: getComputedStyle(document.documentElement).colorScheme,
+      fonts: document.fonts.status,
+      viewport: {width: innerWidth, height: innerHeight},
+      dpr: devicePixelRatio,
+      reducedMotion: matchMedia('(prefers-reduced-motion: reduce)').matches,
+      coarsePointer: matchMedia('(pointer: coarse)').matches,
+      horizontalOverflow: document.documentElement.scrollWidth > innerWidth + 1,
+      expectedSubject: expected,
+    };
+  }, scenario.name);
+  const expected = {
+    build: head,
+    storyId: scenario.storyId,
+    theme: 'neutral',
+    mode,
+    direction,
+    viewport,
+    coarsePointer: options.coarsePointer ?? false,
+    reducedMotion: true,
+    rootCount: scenario.rootCount,
+    text: scenario.text,
+    statusTitle: scenario.status ? LABELS[scenario.status] : null,
+    buttonCount: scenario.button ? 1 : 0,
+    sender: scenario.sender ?? null,
+  };
+  const failures: string[] = [];
+  const check = (ok: boolean, detail: string) => {
+    if (!ok) {
+      failures.push(detail);
+    }
+  };
+  check(actual.rootCount === expected.rootCount, 'metadata root count');
+  check(actual.text === expected.text, 'visible content and separators');
+  check(actual.direction === direction, 'computed direction');
+  if (scenario.name === 'status-read' || scenario.name === 'assistant-footer') {
+    const first = actual.childX[0];
+    const last = actual.childX[actual.childX.length - 1];
+    const goesRight =
+      scenario.sender === 'user' ? direction === 'rtl' : direction === 'ltr';
+    check(
+      first != null &&
+        last != null &&
+        (goesRight ? first < last : first > last),
+      'sender-relative visual order',
+    );
+  }
+  check(actual.statusTitle === expected.statusTitle, 'translated status title');
+  check(actual.buttonCount === expected.buttonCount, 'footer button');
+  check(actual.sender === expected.sender, 'message sender');
+  check(
+    actual.theme === 'neutral' &&
+      actual.mode === mode &&
+      actual.colorScheme === mode,
+    'resolved theme',
+  );
+  check(
+    actual.fonts === 'loaded' && actual.reducedMotion,
+    'settled fonts and reduced motion',
+  );
+  check(
+    actual.viewport.width === viewport.width &&
+      actual.viewport.height === viewport.height &&
+      actual.coarsePointer === expected.coarsePointer,
+    'viewport and pointer',
+  );
+  check(
+    actual.geometry.width > 0 &&
+      actual.geometry.height > 0 &&
+      !actual.storyError,
+    'visible fixture with no Storybook error',
+  );
+  check(
+    actual.rootCount === 0 || actual.rootVisible,
+    'visible metadata subject',
+  );
+  check(
+    actual.overflowFree && !actual.horizontalOverflow,
+    'no horizontal overflow',
+  );
+  check(errors.length === 0, 'no page errors');
+  const file = `ChatMessageMetadata__${state}__neutral-${mode}__${direction}.png`;
+  const png = await panel.screenshot({animations: 'disabled'});
+  const image = {
+    file,
+    sha256: createHash('sha256').update(png).digest('hex'),
+    width: png.readUInt32BE(16),
+    height: png.readUInt32BE(20),
+  };
+  fs.writeFileSync(path.join(OUTPUT, file), png);
+  const receipt = {
+    expected,
+    observed: {...actual, build, storyId: scenario.storyId, pageErrors: errors},
+    browser: page.context().browser()?.version() ?? 'unknown',
+    image,
+    passed: failures.length === 0,
+    failures,
+  };
+  fs.writeFileSync(
+    path.join(OUTPUT, `${file}.sensors.json`),
+    `${JSON.stringify(receipt, null, 2)}\n`,
+  );
+  frames.push({
+    state,
+    mode,
+    direction,
+    receipt: `${file}.sensors.json`,
+    image,
+    passed: receipt.passed,
+    failures,
+  });
+  expect(await roots.count()).toBe(actual.rootCount);
+  page.off('pageerror', onError);
+  return failures.map(detail => `${state}/${mode}/${direction}: ${detail}`);
+}
+
+test('captures light and dark status, composition, empty, and overflow states', async ({
+  page,
+}) => {
+  const failures: string[] = [];
+  await page.emulateMedia({reducedMotion: 'reduce'});
+  for (const mode of ['light', 'dark'] as const) {
+    for (const scenario of CASES) {
+      failures.push(...(await capture(page, scenario, mode, 'ltr')));
+    }
+  }
+  expect(failures).toEqual([]);
+});
+
+test('captures sender ordering in RTL', async ({page}) => {
+  const failures: string[] = [];
+  await page.emulateMedia({reducedMotion: 'reduce'});
+  for (const mode of ['light', 'dark'] as const) {
+    for (const scenario of CASES.filter(
+      item => item.name === 'status-read' || item.name === 'assistant-footer',
+    )) {
+      failures.push(...(await capture(page, scenario, mode, 'rtl')));
+    }
+  }
+  expect(failures).toEqual([]);
+});
+
+test('captures narrow touch reflow in both modes', async ({browser}) => {
+  const viewport = {width: 320, height: 640};
+  const context = await browser.newContext({
+    viewport,
+    deviceScaleFactor: 1,
+    hasTouch: true,
+    isMobile: true,
+    reducedMotion: 'reduce',
+  });
+  try {
+    const page = await context.newPage();
+    const scenario = CASES.find(item => item.name === 'narrow-overflow');
+    if (!scenario) {throw new Error('Narrow metadata fixture is missing');}
+    const failures: string[] = [];
+    for (const mode of ['light', 'dark'] as const) {
+      failures.push(
+        ...(await capture(page, scenario, mode, 'ltr', {
+          viewport,
+          coarsePointer: true,
+          state: 'narrow-touch',
+        })),
+      );
+    }
+    expect(failures).toEqual([]);
+  } finally {
+    await context.close();
+  }
+});

package/src/Chat/index.ts

@@ -25,6 +25,7 @@ export {ChatComposerInput, ChatComposerTokenElement} from './ChatComposerInput';
 export type {
   ChatComposerInputProps,
   ChatComposerInputHandle,
+  ChatComposerTokenElementProps,
   ChatComposerToken,
   ChatComposerTrigger,
   ChatComposerTriggerItem,

package/src/CheckboxInput/CheckboxInput.doc.mjs

@@ -137,6 +137,17 @@ export const docs = {
     ],
   },
   usage: {
+    accessibility: [
+      {
+        name: 'Checkbox box',
+        category: 'Color contrast',
+        criterion: '1.4.11 Non-text Contrast',
+        requirement: '3:1',
+        states: ['Rest', 'Hover', 'Pointer down', 'Checked'],
+        description:
+          'The box edge (unchecked) and fill (checked) must have at least 3:1 contrast with the surface behind them. For Hover and Pointer down, measure the final colors after the tint and the pressed overlay are applied.',
+      },
+    ],
     description: 'CheckboxInput toggles a single on/off value. Use it for settings like "Enable notifications", terms acceptance, or opt-in choices. For multiple checkboxes in a group, use CheckboxList instead.',
     bestPractices: [
       { guidance: true, description: 'Always provide a visible label so the user knows what they are toggling. Use isLabelHidden only when surrounding context makes it obvious.' },

package/src/CheckboxInput/CheckboxInput.test.tsx

@@ -15,6 +15,7 @@
 import {describe, it, expect, vi, beforeEach, afterEach} from 'vitest';
 import {render, screen, fireEvent, waitFor} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
+import {hasPressedArm} from '../__tests__/pressState';
 import {CheckboxInput} from './CheckboxInput';
 import {Theme} from '../theme/Theme';
 import {defineTheme} from '../theme/defineTheme';
@@ -763,3 +764,36 @@ describe('label theme target', () => {
     expect(label).toHaveClass('astryx-checkbox-label');
   });
 });
+
+describe('pressed state', () => {
+  it('paints the pressed overlay over the indicator while the row is pressed', () => {
+    const {container} = render(
+      <CheckboxInput label="Accept terms" value={false} onChange={() => {}} />,
+    );
+    const box = container.querySelector('.astryx-checkbox-indicator');
+    const wrapper = box?.parentElement?.parentElement;
+    if (wrapper == null) {
+      throw new Error('the checkbox has no indicator wrapper to press');
+    }
+    // The owner paints over the resolved indicator, so the treatment survives a
+    // theme replacement that does not forward style props.
+    expect(hasPressedArm(wrapper)).toBe(true);
+  });
+
+  it('does not expose a pressed arm on a disabled checkbox', () => {
+    const {container} = render(
+      <CheckboxInput
+        label="Unavailable"
+        value={false}
+        onChange={() => {}}
+        isDisabled
+      />,
+    );
+    const box = container.querySelector('.astryx-checkbox-indicator');
+    const wrapper = box?.parentElement?.parentElement;
+    if (wrapper == null) {
+      throw new Error('the checkbox has no indicator wrapper');
+    }
+    expect(hasPressedArm(wrapper)).toBe(false);
+  });
+});

package/src/CheckboxInput/CheckboxInput.tsx

@@ -70,6 +70,22 @@ const styles = stylex.create({
     flexShrink: 0,
     isolation: 'isolate',
   },
+  // The owner paints this layer over the resolved indicator, so a theme
+  // replacement cannot accidentally drop the component's pressed contract.
+  indicatorPressOverlay: {
+    '::after': {
+      content: '""',
+      position: 'absolute',
+      inset: 0,
+      borderRadius: radiusVars['--radius-inner'],
+      pointerEvents: 'none',
+      backgroundColor: {
+        default: 'transparent',
+        [stylex.when.ancestor(':active', indicatorScope)]:
+          colorVars['--color-overlay-pressed'],
+      },
+    },
+  },
   // Holds only the indicator, so the focus ring has one unambiguous target.
   // `display: contents` adds no box of its own — the indicator keeps whatever
   // layout relationship it already had with the wrapper.
@@ -399,7 +415,11 @@ export function CheckboxInput({
           !isDisabled && indicatorScope,
         )}>
         <div
-          {...stylex.props(styles.checkboxWrapper, wrapperSizeStyles[size])}
+          {...stylex.props(
+            styles.checkboxWrapper,
+            wrapperSizeStyles[size],
+            !isDisabled && styles.indicatorPressOverlay,
+          )}
           {...focusProps}>
           <input
             {...rest}

package/src/Citation/Citation.doc.mjs

@@ -71,7 +71,7 @@ export const docs = {
       name: 'source',
       type: 'CitationSource',
       description:
-        'The citation source object containing title, url, an optional image src, and an optional icon node.',
+        'The citation source object containing title, url, an optional image src, and an optional icon node. The url follows the shared navigation rule described on the Link `href` prop; rejected destinations leave the citation visible without navigation. Image src uses separate resource handling.',
       required: true,
     },
     {
@@ -122,7 +122,7 @@ export const docsDense = {
   },
   propDescriptions: {
     source:
-      'citation source object with title, url, optional image src, and optional icon node.',
+      'citation source with title, url, optional image src, and optional icon. url follows the Link href navigation rule; rejected destinations stay visible without navigation. Image src handling is separate.',
     number: 'display index for this citation.',
     variant: 'display style: label chip with source title or compact numbered badge.',
   },

package/src/Citation/Citation.test.tsx

@@ -36,6 +36,23 @@ function atomicClasses(style: (typeof probe)[keyof typeof probe]): string[] {
 describe('Citation', () => {
   const source = {title: 'Example Source', url: 'https://example.com'};
 
+  it.each([
+    'javascript:alert(1)',
+    'vbscript:MsgBox(1)',
+    'data:text/html,<b>x</b>',
+    'java\nscript:alert(1)',
+  ])('renders rejected citation URL %s without navigation', url => {
+    const {container} = render(
+      <>
+        <Citation source={{title: 'Source', url}} number={1} />
+        <Citation source={{title: 'Source', url}} number={1} variant="number" />
+      </>,
+    );
+    expect(container.querySelector('a')).toBeNull();
+    expect(container.querySelector('[href]')).toBeNull();
+    expect(container.textContent).toBe('Source1');
+  });
+
   it('renders the source title as a link in the label variant', () => {
     render(<Citation source={source} number={1} data-testid="citation" />);
     const el = screen.getByTestId('citation');

package/src/Citation/Citation.tsx

@@ -4,7 +4,7 @@
 
 /**
  * @file Citation.tsx
- * @input Uses React, StyleX, theme tokens
+ * @input Uses React, StyleX, theme tokens, and the shared navigation policy
  * @output Exports Citation component for inline citation references
  * @position Core implementation; consumed by index.ts
  *
@@ -30,6 +30,7 @@ import {
   easeVars,
 } from '../theme/tokens.stylex';
 import {mergeProps} from '../utils';
+import {isSafeUrl} from '../utils/safeUrl';
 import type {BaseProps} from '../BaseProps';
 import {themeProps} from '../utils/themeProps';
 import {useTranslator} from '../i18n';
@@ -189,7 +190,8 @@ export function Citation({
 }: CitationProps): React.ReactElement {
   const t = useTranslator();
   const title = source.title ?? String(number);
-  const href = source.url;
+  const href =
+    source.url != null && isSafeUrl(source.url) ? source.url : undefined;
 
   // Resolve the source icon. A non-string `icon` node renders as-is (an Astryx
   // <Icon>, SVG, avatar, etc.). Otherwise fall back to an image URL: `src`, or

package/src/ClickableCard/ClickableCard.doc.mjs

@@ -22,7 +22,7 @@ export const docs = {
   props: [
     {name: 'label', type: 'string', description: 'Accessibility label.', required: true},
     {name: 'onClick', type: '(event: MouseEvent) => void', description: 'Click handler: fires on card surface only.'},
-    {name: 'href', type: 'string', description: 'Navigation URL.'},
+    {name: 'href', type: 'string', description: 'Navigation URL. Plain, new-tab, Cmd/Ctrl-click, and middle-click activation all follow the shared navigation rule described on the Link `href` prop.'},
     {name: 'target', type: 'string', description: 'Link target.', default: "'_self'"},
     {name: 'isDisabled', type: 'boolean', description: 'Disables the card.', default: 'false'},
     {name: 'children', type: 'ReactNode', description: 'Card content.'},
@@ -69,7 +69,7 @@ export const docsDense = {
   propDescriptions: {
     label: 'accessibility label',
     onClick: 'click handler: fires on card surface only',
-    href: 'navigation URL',
+    href: 'navigation URL; every activation follows the shared navigation rule (see Link href)',
     target: 'link target',
     isDisabled: 'disables card',
     padding: 'inner padding',