An open source design system that's fully customizable and agent ready
TypeScript
fix(ChatComposerDrawer): keep collapsed content unreachable (#6416)
Cindy Zhang20777236fb41
diff --git a/.changeset/chat-composer-drawer-hidden-focus.md b/.changeset/chat-composer-drawer-hidden-focus.mdnew file mode 100644index 0000000000..35fdbe6f2b--- /dev/null+++ b/.changeset/chat-composer-drawer-hidden-focus.md@@ -0,0 +1,7 @@+---+'@astryxdesign/core': patch+---++[fix] Keep collapsed `ChatComposerDrawer` content out of keyboard and assistive-technology navigation, and show the shared focus indicator on its disclosure control.++@cixzhangdiff --git a/apps/storybook/rtl-audit/verified-not-applicable.json b/apps/storybook/rtl-audit/verified-not-applicable.jsonindex 0a955f0a2f..4e5af19f58 100644--- a/apps/storybook/rtl-audit/verified-not-applicable.json+++ b/apps/storybook/rtl-audit/verified-not-applicable.json@@ -189,6 +189,15 @@"component": "core/StatusDot","reason": "StatusDot is a symmetric painted circle with an optional centered caller-owned icon. Its pulse animation is radial, and it has no inline-axis placement, order, scrolling, dragging, overlay, or directional keyboard behavior."},+ {+ "component": "core/ChatComposerDrawer",+ "reason": "ChatComposerDrawer uses normal block and flex flow with logical inline spacing and symmetric top corners. Its collapse handle is horizontal and centered, the disclosure action moves only on the block axis, and its count, attachment, vertical expand/collapse, and caller-owned child content add no component-owned left/right glyph, physical inline positioning, order, horizontal scrolling or dragging, overlay placement, or directional keyboard behavior.",+ "evidence": {+ "apps/storybook/stories/ChatComposerDrawer.stories.tsx": "sha256:115ecc61625c065ffcb02d35c7aeb2a399c8ba1a30a8cd637bdd4adf58185b80",+ "packages/core/src/Chat/ChatComposerDrawer.tsx": "sha256:a8d11adc40decad25688b33a16b562e168c831933ec4387084c00530fcb94600",+ "packages/core/src/Chat/index.ts": "sha256:1e1883f9baa0b9661fefe855a7df6db2a0d0e69118734b3d309543a6c5518b46"+ }+ },{"component": "core/ChatComposer","reason": "ChatComposer arranges caller-owned slots in normal flex and block flow using logical inline properties. Its owned send, stop, status, attachment, microphone, and mention glyphs are direction-neutral; it has no component-owned left/right glyph, physical inline positioning, horizontal scroll or drag behavior, overlay placement, or horizontal keyboard interaction to mirror. Text editing and bidirectional content remain native to the default contenteditable surface or the caller-supplied custom input.",diff --git a/apps/storybook/stories/ChatComposerDrawer.stories.tsx b/apps/storybook/stories/ChatComposerDrawer.stories.tsxnew file mode 100644index 0000000000..962bedb718--- /dev/null+++ b/apps/storybook/stories/ChatComposerDrawer.stories.tsx@@ -0,0 +1,102 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++import type {Meta, StoryObj} from '@storybook/react';+import {expect, userEvent, within} from 'storybook/test';+import {ChatComposerDrawer} from '@astryxdesign/core/Chat';+import {Token} from '@astryxdesign/core/Token';++const meta: Meta<typeof ChatComposerDrawer> = {+ title: 'Core/ChatComposerDrawer',+ component: ChatComposerDrawer,+ tags: ['autodocs'],+ parameters: {layout: 'centered'},+ decorators: [+ Story => (+ <div style={{width: 480}}>+ <Story />+ </div>+ ),+ ],+};++export default meta;+type Story = StoryObj<typeof ChatComposerDrawer>;++const attachments = (+ <>+ <Token label="design-spec.pdf" onRemove={() => {}} />+ <Token label="api-schema.json" onRemove={() => {}} />+ </>+);++export const Expanded: Story = {+ args: {+ count: 2,+ label: 'Attachments',+ children: attachments,+ },+};++export const Collapsed: Story = {+ args: {+ count: 1,+ label: 'Attachment',+ defaultIsCollapsed: true,+ children: (+ <button type="button" data-audit-child="">+ Remove attachment+ </button>+ ),+ },+ render: args => (+ <>+ <ChatComposerDrawer {...args} />+ <button type="button" data-audit-after="">+ After drawer+ </button>+ </>+ ),+ play: async ({canvasElement}) => {+ const canvas = within(canvasElement);+ const toggle = canvas.getByRole('button', {name: /Attachment/});+ const region = document.getElementById(+ toggle.getAttribute('aria-controls') as string,+ );+ const child =+ canvasElement.querySelector<HTMLElement>('[data-audit-child]');+ const after =+ canvasElement.querySelector<HTMLElement>('[data-audit-after]');++ await expect(toggle).toHaveAttribute('aria-expanded', 'false');+ await expect(region).toHaveAttribute('inert');+ await userEvent.tab();+ await expect(toggle).toHaveFocus();+ await userEvent.tab();+ await expect(after).toHaveFocus();++ await userEvent.click(toggle);+ await expect(toggle).toHaveAttribute('aria-expanded', 'true');+ await expect(region).not.toHaveAttribute('inert');+ await userEvent.tab();+ await expect(child).toHaveFocus();+ },+};++export const KeyboardFocus: Story = {+ args: {+ count: 2,+ label: 'Attachments',+ children: attachments,+ },+ play: async ({canvasElement}) => {+ const canvas = within(canvasElement);+ await userEvent.tab();+ const toggle = canvas.getByRole('button', {name: /Attachments/});+ await expect(toggle).toHaveFocus();+ const style = getComputedStyle(toggle);+ await expect(Number.parseFloat(style.outlineWidth)).toBeGreaterThanOrEqual(+ 2,+ );+ await expect(style.outlineStyle).not.toBe('none');+ },+};diff --git a/packages/core/src/Chat/ChatComposerDrawer.doc.mjs b/packages/core/src/Chat/ChatComposerDrawer.doc.mjsindex 7efc5f1c21..b016d097c9 100644--- a/packages/core/src/Chat/ChatComposerDrawer.doc.mjs+++ b/packages/core/src/Chat/ChatComposerDrawer.doc.mjs@@ -7,7 +7,58 @@ export const docs = {subComponentOf: 'Chat',displayName: 'Chat Composer Drawer',isHiddenFromOverview: true,- description: "Collapsible drawer panel that sits above the chat input inside ChatComposer. Pass it to the composer's `drawer` slot to show attachments, context chips, or any supplementary content. When `count` is provided the drawer gains a collapse toggle: collapsed state shows a badge and label, expanded state shows all children.",+ description: "Collapsible drawer panel that sits above the chat input inside ChatComposer. Pass it to the composer's `drawer` slot to show attachments, context chips, or any supplementary content. When `count` is provided the drawer gains a collapse toggle: collapsed state shows a count summary and expanded state shows all children.",+ usage: {+ description:+ 'Use ChatComposerDrawer in the ChatComposer drawer slot for supplementary content such as attachments, context chips, or previews. Provide count only when people should be able to collapse that content.',+ bestPractices: [+ {+ guidance: true,+ description:+ 'Give label a concrete plural noun such as "Attachments" so the expand and collapse actions have a useful accessible name.',+ },+ {+ guidance: true,+ description:+ 'Use controlled isCollapsed with onCollapsedChange when another part of the page owns drawer state; otherwise use defaultIsCollapsed.',+ },+ {+ guidance: false,+ description:+ 'Put primary composer actions in the drawer; use ChatComposer footer or send-action slots so those controls remain available when the drawer is collapsed.',+ },+ ],+ anatomy: [+ {+ name: 'Root surface',+ required: true,+ description: 'The drawer surface that composes above the ChatComposer body.',+ },+ {+ name: 'Disclosure toggle',+ required: false,+ description: 'The keyboard- and pointer-operable collapse control rendered when count is provided.',+ },+ {+ name: 'Collapsed summary',+ required: false,+ description: 'The count and label presented while the drawer is collapsed.',+ },+ {+ name: 'Content area',+ required: true,+ description: 'The caller-provided supplementary content; collapsed descendants are unavailable to keyboard and assistive technology.',+ },+ ],+ },+ theming: {+ targets: [+ {+ className: 'astryx-chat-composer-drawer',+ visualProps: ['collapsed'],+ },+ ],+ },playground: {wrapper: {component: 'Stack', props: {width: 480}},defaults: {@@ -79,7 +130,7 @@ export const docsDense = {description: 'collapsible drawer above chat input; pass to composer `drawer` slot for attachments, context chips, previews. `count` enables collapse toggle',propDescriptions: {children: 'drawer content: tokens, chips, previews, any React elements',- count: 'total count for collapsed badge; enables collapse/expand toggle',+ count: 'total count for collapsed summary; enables collapse/expand toggle',label: 'collapsed label next to count badge',isCollapsed: 'controlled collapsed state',defaultIsCollapsed: 'initial collapsed state (uncontrolled)',diff --git a/packages/core/src/Chat/ChatComposerDrawer.spec.md b/packages/core/src/Chat/ChatComposerDrawer.spec.mdnew file mode 100644index 0000000000..4dd770116f--- /dev/null+++ b/packages/core/src/Chat/ChatComposerDrawer.spec.md@@ -0,0 +1,163 @@+---+schema_version: 3+template_version: 5+kind: component+id: component:ChatComposerDrawer+authority: draft+archive_reason: null+superseded_by: null+approved_by: null+approved_at: null+owners: [cixzhang]+review_triggers: [public-api, behavior, layout, theming, accessibility]+verified_by:+ [+ packages/core/src/Chat/ChatComposerDrawer.test.tsx,+ apps/storybook/stories/ChatComposerDrawer.stories.tsx,+ apps/storybook/rtl-audit/verified-not-applicable.json,+ ]+modules: []+families: []+design_specs: []+architecture:+ [+ architecture:component-theming-surface,+ architecture:interaction-modality,+ architecture:knowledge-contracts,+ ]+contributing: []+system_specs: [spec:AST-002, spec:AST-029]+---++# ChatComposerDrawer component contract++## Contract at a glance++| Area | Contract |+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |+| Public contract | No API or default change. ChatComposerDrawer remains a required-content panel whose optional `count` enables a controlled or uncontrolled disclosure. |+| Behavior | The disclosure reports expanded state and its controlled region, preserves mounted content for animation, and makes collapsed descendants unavailable to keyboard and assistive-technology navigation. |+| End-user impact | Keyboard and screen-reader users do not enter visually hidden drawer actions, and keyboard focus remains visible on the disclosure control. |+| Builder impact | None. Existing props, defaults, exports, child composition, and callback values remain unchanged. |+| Compatibility/readiness | Patch-compatible accessibility correction to released behavior. This observational record remains draft; collapsed-summary representation is not decided here. |+| Review checks | Reject hidden focusable descendants, an invisible disclosure focus state, broken `aria-controls`, changed callback values, or any claim that the collapsed-summary representation is settled. |+| Governing rules | `architecture:interaction-modality/INV1–INV4, INV9`; `architecture:knowledge-contracts/INV11, INV16`; `spec:AST-002/FR14, FR19`; WCAG 2.4.3 and 2.4.7. |++This table is a review projection; the body below is authoritative.++## Intent++ChatComposerDrawer composes supplementary content above ChatComposer input. When+`count` is present, builders may let people collapse that content while keeping a+compact summary available.++## Compatibility and migration++- Released default preserved: yes+- Compatibility class: patch-compatible behavior correction; no public type or default changes+- Controlled/uncontrolled behavior: unchanged+- Migration decision: none++## Ownership boundary++**Owns**++- The drawer surface, optional disclosure state, disclosure association, and availability of collapsed descendants.+- Controlled and uncontrolled collapse requests.++**Does not own / non-goals**++- The meaning or behavior of arbitrary caller children.+- ChatComposer input, submission, status, and action behavior.+- The final visual representation of the collapsed count-and-label summary; this draft records only shipped observation.++## Public concepts++| Concept | Closed values or states | Meaning | Availability by state | Default | Owner | Stability | Invalid-value behavior |+| ---------------- | -------------------------------- | ------------------------------------------------------------------------ | ----------------------------------- | ------------ | ------------------------------ | --------- | ---------------------------------------------------- |+| drawer content | any React node | Supplementary content composed above the chat input. | always | none | `component:ChatComposerDrawer` | stable | Missing content is rejected by the required type. |+| collapse support | unavailable, expanded, collapsed | `count` enables a disclosure and supplies its summary count. | unavailable when `count` is omitted | unavailable | `component:ChatComposerDrawer` | stable | Collapse props have no visible effect without count. |+| collapse control | uncontrolled, controlled | Internal state or `isCollapsed` determines the current disclosure state. | when collapse support is available | uncontrolled | `component:ChatComposerDrawer` | stable | Controlled state wins over the initial default. |+| collapse request | next state | Activation asks for the opposite effective state. | when collapse support is available | none | `component:ChatComposerDrawer` | stable | No request is emitted without a disclosure. |++## Behavioral and layout contract++| ID | Candidate invariant | Basis | Draft review state |+| --- | --------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | ------------------ |+| FR1 | When `count` is present, the component MUST expose one named disclosure control with `aria-expanded` and a resolvable `aria-controls` relationship. | Shipped API and implementation; WAI-ARIA disclosure semantics. | verify |+| FR2 | Pointer activation, Enter, and Space MUST request the opposite effective collapsed state exactly once. | Shipped implementation and public callback contract. | verify |+| FR3 | In controlled mode, `isCollapsed` MUST remain authoritative; in uncontrolled mode, activation MUST update internal state before the next render. | Shipped implementation and consumer docs. | verify |+| FR4 | Collapsed content MAY remain mounted for the grid transition, but its descendants MUST be absent from keyboard and assistive-technology navigation. | WCAG 2.4.3 and 2.4.7; objective restoration of the shipped visually hidden state. | settled |+| FR5 | Keyboard focus on the disclosure MUST remain visibly perceivable through the shared focus-indicator mechanism. | `architecture:interaction-modality/INV1–INV4`; WCAG 2.4.7. | settled |+| FR6 | Omitting `count` MUST render content directly and MUST NOT create a disclosure control. | Shipped implementation and consumer docs. | verify |+| FR7 | The root MUST continue forwarding its ref, BaseProps attributes, and styling seams without moving them to an internal child. | Released public surface and `architecture:knowledge-contracts/INV11`. | verify |++### Allowed variation++- **AV1 — Child composition.** Builders choose the child content and its own semantics.+- **AV2 — Collapsed summary paint.** The current count-and-label presentation is observation, not an approved durable representation.++### Representative states++| State | Required invariant | Allowed variation |+| ----------------------------- | ---------------------------------------------------------------------------------- | ------------------------------------------------- |+| count omitted | Content is visible and no disclosure is rendered. | Child content and root styling. |+| uncontrolled expanded | Disclosure is expanded and descendants are available. | Child content and count value. |+| uncontrolled collapsed | Disclosure is collapsed and mounted descendants are inert. | Current summary presentation. |+| controlled expanded/collapsed | Rendered state follows `isCollapsed`; activation reports the requested next state. | Parent timing and whether it accepts the request. |++### Transformation and precedence order++- **ORD1 — Effective state.** `isCollapsed` when defined → otherwise internal state initialized from `defaultIsCollapsed` → disclosure output only when `count` is present.++### Performance and resources++- **PR1 — Local state only.** The component owns no Effect, observer, listener, timer, or external resource.++## Accessibility contract++- **AR1 — Disclosure relationship.** The toggle exposes a name, expanded state, and a resolvable controlled-content ID.+- **AR2 — Hidden content is unavailable.** A visually collapsed mounted subtree is inert until expansion.+- **AR3 — Focus remains visible.** Keyboard focus on the toggle uses the shared focus indicator.++## Design relationships++| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |+| ----------------- | ------------------ | ------------------------ | -------------- | ------------------ |+| root surface | unsettled | human-selected | supporting | FR7 |+| disclosure toggle | unsettled | human-selected | supporting | FR1, FR5 |+| collapsed summary | unsettled | human-selected | supporting | AV2 |+| content area | unsettled | human-selected | supporting | FR4, FR6 |++The existing `chat-composer-drawer` target remains on the painted root. This+observational draft does not add targets or decide a separate theming boundary for+the disclosure, summary, or content area.++## Family and system relationships++- `architecture:interaction-modality` owns shared focus-visibility mechanics; this component owns the disclosure as its semantic focus owner.+- `architecture:component-theming-surface` owns target and anatomy mapping rules; this component exposes only the existing root target.+- `spec:AST-029` owns the observational audit-backfill boundary.++## Verification map++| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |+| ------------ | --------------------------------------------------------------- | ------------------------------------------------------ | ----------------------------------------------------------------------------------------------- | ---------------------------------------- |+| FR1–FR3, FR6 | `ChatComposerDrawer.test.tsx` | no count; controlled; uncontrolled; Enter; Space | Relationship breaks, state authority changes, or callback reports the wrong next state. | `audit:ChatComposerDrawer/behavior` |+| FR4, AR2 | focused inert-state test plus exact-head accessibility CI | expanded → collapsed → expanded with focusable child | A visually hidden child remains reachable or expansion fails to restore availability. | `audit:ChatComposerDrawer/accessibility` |+| FR5, AR3 | `KeyboardFocus` Storybook play and exact-head visual/a11y gates | keyboard focus in representative light and dark themes | Focus has no shared visible indicator or pointer interaction changes the keyboard-only outcome. | `audit:ChatComposerDrawer/accessibility` |+| FR7 | focused DOM/type tests and package checks | ref, BaseProps, xstyle, className, style | Root ownership or a styling seam moves or disappears. | `audit:ChatComposerDrawer/api` |++## Decision log++No component-local policy decision is created by this observational draft.++## Open questions++- **OQ1 — Collapsed-summary representation.** Should the existing count badge remain, or should the summary use another representation? (`human-design`)++## Content boundary++This file does not duplicate consumer prop tables, examples, current audit scores,+or visual design rationale. It records observed behavior, objective remediation,+and the unresolved representation boundary without deciding it.diff --git a/packages/core/src/Chat/ChatComposerDrawer.test.tsx b/packages/core/src/Chat/ChatComposerDrawer.test.tsxindex 91a90ccb32..488c8b0b35 100644--- a/packages/core/src/Chat/ChatComposerDrawer.test.tsx+++ b/packages/core/src/Chat/ChatComposerDrawer.test.tsx@@ -1,6 +1,6 @@// Copyright (c) Meta Platforms, Inc. and affiliates.-import {describe, it, expect} from 'vitest';+import {describe, it, expect, vi} from 'vitest';import {render, screen, fireEvent} from '@testing-library/react';import {ChatComposerDrawer} from './ChatComposerDrawer';@@ -36,26 +36,49 @@ describe('ChatComposerDrawer', () => {expect(region).toContainElement(screen.getByText('Drawer content'));});- it('toggles aria-expanded when the toggle is activated', () => {+ it('removes collapsed children from the focus order and restores them on expand', () => {render(- <ChatComposerDrawer count={2} label="Attachments">- <span>Drawer content</span>+ <ChatComposerDrawer count={1} label="Attachment">+ <button type="button">Remove attachment</button></ChatComposerDrawer>,);- const toggle = screen.getByRole('button', {name: /Attachments/});- expect(toggle).toHaveAttribute('aria-expanded', 'true');+ const toggle = screen.getByRole('button', {name: /Attachment/});+ const region = document.getElementById(+ toggle.getAttribute('aria-controls') as string,+ )!;+ expect(region).not.toHaveAttribute('inert');fireEvent.click(toggle);- expect(screen.getByRole('button', {name: /Attachments/})).toHaveAttribute(- 'aria-expanded',- 'false',- );+ expect(toggle).toHaveAttribute('aria-expanded', 'false');+ expect(region).toHaveAttribute('inert');+ expect(+ screen+ .getByRole('button', {name: 'Remove attachment'})+ .closest('[inert]'),+ ).toBe(region);- fireEvent.click(screen.getByRole('button', {name: /Attachments/}));- expect(screen.getByRole('button', {name: /Attachments/})).toHaveAttribute(- 'aria-expanded',- 'true',+ fireEvent.click(toggle);+ expect(toggle).toHaveAttribute('aria-expanded', 'true');+ expect(region).not.toHaveAttribute('inert');+ });++ it('supports both disclosure keys and reports the requested state', () => {+ const onCollapsedChange = vi.fn();+ render(+ <ChatComposerDrawer+ count={2}+ label="Attachments"+ onCollapsedChange={onCollapsedChange}>+ <span>Drawer content</span>+ </ChatComposerDrawer>,);++ const toggle = screen.getByRole('button', {name: /Attachments/});+ fireEvent.keyDown(toggle, {key: 'Enter'});+ expect(onCollapsedChange).toHaveBeenLastCalledWith(true);++ fireEvent.keyDown(toggle, {key: ' '});+ expect(onCollapsedChange).toHaveBeenLastCalledWith(false);});});diff --git a/packages/core/src/Chat/ChatComposerDrawer.tsx b/packages/core/src/Chat/ChatComposerDrawer.tsxindex 1988bb06bc..fbc1cd8335 100644--- a/packages/core/src/Chat/ChatComposerDrawer.tsx+++ b/packages/core/src/Chat/ChatComposerDrawer.tsx@@ -13,6 +13,10 @@* the content region (disclosure pattern).** SYNC: When modified, update:+ * - /packages/core/src/Chat/ChatComposerDrawer.test.tsx+ * - /packages/core/src/Chat/ChatComposerDrawer.doc.mjs+ * - /packages/core/src/Chat/ChatComposerDrawer.spec.md+ * - /apps/storybook/stories/ChatComposerDrawer.stories.tsx* - /packages/core/src/Chat/index.ts (exports)* - /packages/cli/assets/templates/blocks/components/ChatComposerDrawer/ (block examples)*/@@ -32,6 +36,7 @@ import {Badge} from '../Badge';import {mergeProps} from '../utils';import type {BaseProps} from '../BaseProps';import {themeProps} from '../utils/themeProps';+import {focusOutlineProps} from '../utils/focusOutline.stylex';import {useTranslator} from '../i18n';export interface ChatComposerDrawerProps extends BaseProps<HTMLDivElement> {@@ -72,7 +77,9 @@ export interface ChatComposerDrawerProps extends BaseProps<HTMLDivElement> {* @example* ```* const styles = stylex.create({ wrapper: { marginTop: 8 } });- * <ChatComposerDrawer xstyle={styles.wrapper} />+ * <ChatComposerDrawer xstyle={styles.wrapper}>+ * <AttachmentThumbnail />+ * </ChatComposerDrawer>* ```*/xstyle?: StyleXStyles;@@ -274,7 +281,7 @@ export function ChatComposerDrawer({{...htmlProps}>{canCollapse && (<div- {...stylex.props(+ {...focusOutlineProps.focusVisible(styles.toggleRow,isCollapsed && styles.toggleCollapsed,stylex.defaultMarker(),@@ -314,6 +321,10 @@ export function ChatComposerDrawer({<divid={contentId}+ // The 0fr row keeps the collapse animation in place. `inert` also+ // removes visually hidden descendants from keyboard and assistive-+ // technology navigation until the drawer expands again.+ inert={canCollapse && isCollapsed ? true : undefined}{...stylex.props(styles.contentGrid,canCollapse && isCollapsed && styles.contentGridCollapsed,