@astryxdesign/core 0.7.5-canary.fccd771 → 0.7.5

package/src/CodeBlock/tokenizer.ts

@@ -17,6 +17,24 @@
  */
 declare const scheduler: {yield?: () => Promise<void>} | undefined;
 
+import {
+  BLOCK_COMMENT,
+  CALL,
+  CPP_WORDS,
+  C_WORDS,
+  DIRECTIVE,
+  NUMBER,
+  PUNCTUATION,
+  cLike,
+  codeLanguagePainter,
+} from './grammar';
+import type {CodeLanguage, CodeLanguageTokenize, Grammar} from './grammar';
+
+export type {CodeLanguage} from './grammar';
+
+/** A language identifier string or a language value (FR13). */
+export type CodeLanguageInput = string | CodeLanguage;
+
 export type SyntaxToken = {type: string; start: number; end: number};
 
 /**
@@ -55,22 +73,72 @@ const PHP_KEYWORDS =
 const HACK_KEYWORDS =
   /\b(function|class|if|else|for|foreach|while|return|echo|public|private|protected|static|new|try|catch|throw|namespace|use|require|include|extends|implements|interface|abstract|final|const|shape|vec|dict|keyset|async|await|concurrent|enum|type|newtype|tuple|inout)\b/;
 
-function buildLanguage(lang: string): LangDef | null {
-  const cached = langCache.get(lang);
+/** How each language value paints, compiled once per value. */
+const valueCache = new WeakMap<
+  CodeLanguage,
+  LangDef | {tokenize: CodeLanguageTokenize; name: string} | null
+>();
+
+/**
+ * How `language` paints: a compiled grammar (a built-in identifier, or an
+ * Astryx module), a custom tokenize function, or null (plain code). An
+ * identifier string selects only a built-in grammar (FR12).
+ */
+function resolveLanguage(
+  language: CodeLanguageInput,
+): LangDef | {tokenize: CodeLanguageTokenize; name: string} | null {
+  if (typeof language !== 'string') {
+    const cachedValue = valueCache.get(language);
+    if (cachedValue !== undefined) {
+      return cachedValue;
+    }
+    const painter = codeLanguagePainter(language);
+    const resolved =
+      painter == null
+        ? null
+        : painter.kind === 'grammar'
+          ? compile(painter.grammar)
+          : {tokenize: painter.tokenize, name: language.name};
+    valueCache.set(language, resolved);
+    return resolved;
+  }
+  const cached = langCache.get(language);
   if (cached !== undefined) {
     return cached;
   }
-
-  const def = buildLanguageUncached(lang);
-  langCache.set(lang, def);
+  const def = buildLanguageUncached(language);
+  langCache.set(language, def);
   return def;
 }
 
-function buildLanguageUncached(lang: string): LangDef | null {
-  const raw = buildLanguagePatterns(lang);
-  if (!raw) {
+/** A compiled grammar for `language`, or null for a custom or plain one. */
+function buildLanguage(language: CodeLanguageInput): LangDef | null {
+  const resolved = resolveLanguage(language);
+  return resolved != null && 'patterns' in resolved ? resolved : null;
+}
+
+/** The tokens of a custom language, or null when `language` is not one. */
+function customTokens(
+  code: string,
+  language: CodeLanguageInput,
+): TokenLine[] | null {
+  const resolved = resolveLanguage(language);
+  if (resolved == null || !('tokenize' in resolved)) {
     return null;
   }
+  // A missing function paints nothing rather than throwing, as an absent
+  // `tokenizer` prop does.
+  return typeof resolved.tokenize === 'function'
+    ? flatTokensToLines(resolved.tokenize(code, resolved.name), code)
+    : null;
+}
+
+function buildLanguageUncached(lang: string): LangDef | null {
+  const raw = buildLanguagePatterns(lang);
+  return raw ? compile(raw) : null;
+}
+
+function compile(raw: Grammar): LangDef {
   return {
     defaultType: raw.defaultType,
     patterns: raw.patterns.map(p => {
@@ -80,10 +148,7 @@ function buildLanguageUncached(lang: string): LangDef | null {
   };
 }
 
-function buildLanguagePatterns(lang: string): {
-  patterns: {type: string; regex: RegExp}[];
-  defaultType: string;
-} | null {
+function buildLanguagePatterns(lang: string): Grammar | null {
   switch (lang) {
     case 'typescript':
     case 'javascript':
@@ -308,6 +373,84 @@ function buildLanguagePatterns(lang: string): {
         ],
       };
 
+    case 'c':
+    case 'h':
+      return cLike(C_WORDS, [{type: 'keyword', regex: DIRECTIVE}]);
+
+    case 'cpp':
+    case 'c++':
+    case 'cc':
+    case 'cxx':
+    case 'hpp':
+    case 'hh':
+      return cLike(CPP_WORDS, [
+        {type: 'keyword', regex: DIRECTIVE},
+        {
+          type: 'string',
+          regex: /\b(?:u8|[uUL])?R"([^()\\\s]{0,16})\([\s\S]*?\)\1"/,
+        },
+      ]);
+
+    case 'sql':
+      return {
+        defaultType: 'variable',
+        patterns: [
+          {type: 'comment', regex: /--[^\n]*/},
+          {type: 'comment', regex: BLOCK_COMMENT},
+          {type: 'string', regex: /'(?:[^']|'')*'/},
+          {type: 'property', regex: /"[^"\n]*"|`[^`\n]*`/},
+          {type: 'number', regex: NUMBER},
+          {
+            type: 'keyword',
+            regex:
+              /\b(?:select|from|where|and|or|not|in|is|null|as|join|inner|left|right|full|outer|cross|on|group|by|order|having|limit|offset|union|all|distinct|insert|into|values|update|set|delete|create|table|view|index|drop|alter|add|primary|key|foreign|references|with|case|when|then|else|end|exists|between|like|asc|desc|true|false|default|returning|interval)\b/i,
+          },
+          {type: 'function', regex: CALL},
+          {type: 'operator', regex: /[+\-*/%=<>!|]+/},
+          {type: 'punctuation', regex: PUNCTUATION},
+        ],
+      };
+
+    case 'rust':
+    case 'rs':
+      return cLike(
+        'as async await break const continue crate dyn else enum extern false fn for if impl in let loop match mod move mut pub ref return self Self static struct super trait true type unsafe use where while',
+        [
+          {type: 'constant', regex: /#!?\[[^\]\n]*\]/},
+          {type: 'function', regex: /\b[a-zA-Z_]\w*!(?=\s*[([{])/},
+          {type: 'string', regex: /\bb?r(#*)"[\s\S]*?"\1/},
+          {type: 'type', regex: /'[a-z_]\w*\b(?!')/},
+        ],
+      );
+
+    case 'kotlin':
+    case 'kt':
+    case 'kts':
+      return cLike(
+        'as break class continue do else false for fun if in interface is null object package return super this throw true try typealias val var when while by constructor init companion data sealed enum open override private protected public internal suspend inline lateinit import',
+        [
+          {type: 'constant', regex: /@\w+/},
+          {type: 'string', regex: /"""[\s\S]*?"""/},
+        ],
+      );
+
+    case 'swift':
+      return cLike(
+        'associatedtype class deinit enum extension func import init inout internal let open operator private protocol public static struct subscript typealias var break case continue default defer do else fallthrough for guard if in repeat return switch where while as catch false is nil rethrows super self Self throw throws true try async await actor some any',
+        [
+          {type: 'string', regex: /(#+)"[\s\S]*?"\1/},
+          {type: 'constant', regex: /[@#]\w+/},
+          {type: 'string', regex: /"""[\s\S]*?"""/},
+        ],
+      );
+
+    case 'go':
+    case 'golang':
+      return cLike(
+        'break case chan const continue default defer else fallthrough for func go goto if import interface map package range return select struct switch type var true false nil iota',
+        [{type: 'string', regex: /`[^`]*`/}],
+      );
+
     default:
       return null;
   }
@@ -494,10 +637,17 @@ function tokenizeLine(
  * language's default color type are omitted (~30% reduction).
  *
  * @param code - The source code string to tokenize
- * @param language - Language identifier (e.g. 'typescript', 'python')
+ * @param language - A built-in identifier (e.g. 'typescript') or a language value
  * @returns Array of token arrays, one per line
  */
-export function tokenize(code: string, language: string): TokenLine[] {
+export function tokenize(
+  code: string,
+  language: CodeLanguageInput,
+): TokenLine[] {
+  const custom = customTokens(code, language);
+  if (custom != null) {
+    return custom;
+  }
   const langDef = buildLanguage(language);
   if (!langDef) {
     return [];
@@ -522,9 +672,14 @@ export function tokenize(code: string, language: string): TokenLine[] {
  */
 export async function tokenizeAsync(
   code: string,
-  language: string,
+  language: CodeLanguageInput,
   signal?: AbortSignal,
 ): Promise<TokenLine[]> {
+  // A custom language runs synchronously, as the `tokenizer` prop does.
+  const custom = customTokens(code, language);
+  if (custom != null) {
+    return custom;
+  }
   const langDef = buildLanguage(language);
   if (!langDef) {
     return [];
@@ -560,10 +715,15 @@ export async function tokenizeAsync(
  */
 export async function tokenizeStreaming(
   code: string,
-  language: string,
+  language: CodeLanguageInput,
   onBatch: (lines: TokenLine[], startLine: number) => void,
   signal?: AbortSignal,
 ): Promise<void> {
+  const custom = customTokens(code, language);
+  if (custom != null) {
+    onBatch(custom, 0);
+    return;
+  }
   const langDef = buildLanguage(language);
   if (!langDef) {
     return;

package/src/CodeBlock/tokenizerBudget.test.ts

@@ -0,0 +1,112 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file tokenizerBudget.test.ts
+ * @input tokenizer.ts and each module under languages/, bundled and minified
+ *   by esbuild
+ * @output The CodeBlock language budget (PR4): the built-in tokenizer within
+ *   4,608 bytes and each language module within 512 bytes, minified and gzipped
+ * @position CodeBlock PR4 evidence
+ */
+
+import {execFileSync} from 'node:child_process';
+import {mkdtempSync, rmSync, writeFileSync} from 'node:fs';
+import path from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {afterAll, describe, expect, it} from 'vitest';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const repoRoot = path.resolve(here, '../../../..');
+// Inside the repo so the script resolves `esbuild` by bare specifier, and
+// under node_modules so it is ignored and swept with the install.
+const workspace = mkdtempSync(
+  path.join(repoRoot, 'node_modules', '.astryx-tokenizer-budget-'),
+);
+afterAll(() => {
+  rmSync(workspace, {recursive: true, force: true});
+});
+
+/** Each module's export name and subpath under ./languages. */
+const MODULES = [
+  'graphql:graphql',
+  'java:java',
+  'thrift:thrift',
+  'objectiveC:objective-c',
+  'toml:toml',
+  'powershell:powershell',
+  'ruby:ruby',
+  'lua:lua',
+  'dockerfile:dockerfile',
+];
+
+/**
+ * Gzipped, minified size of each entry. A module is measured as its marginal
+ * cost: the built-in tokenizer plus that module, less the tokenizer alone.
+ */
+const script = path.join(workspace, 'measure.mjs');
+writeFileSync(
+  script,
+  [
+    "import {build} from 'esbuild';",
+    "import {gzipSync} from 'node:zlib';",
+    'const [dir, ...modules] = process.argv.slice(2);',
+    'async function bundle(contents) {',
+    '  const out = await build({',
+    "    stdin: {contents, resolveDir: dir, loader: 'ts'},",
+    "    bundle: true, minify: true, format: 'esm', write: false, logLevel: 'silent',",
+    '  });',
+    '  return out.outputFiles[0].text;',
+    '}',
+    'async function size(contents) {',
+    '  const out = await build({',
+    "    stdin: {contents, resolveDir: dir, loader: 'ts'},",
+    "    bundle: true, minify: true, format: 'esm', write: false, logLevel: 'silent',",
+    '  });',
+    '  return gzipSync(out.outputFiles[0].contents, {level: 9}).length;',
+    '}',
+    'const base = await size("import {tokenize} from \'./tokenizer\'; console.log(tokenize);");',
+    'const core = await bundle("import {CodeBlock, createCodeLanguage, tokenize} from \'./index\'; console.log(CodeBlock, createCodeLanguage, tokenize);");',
+    "const result = {tokenizer: base, modules: {}, leaked: ['cpp_include', 'dynamicparam', 'HEALTHCHECK', 'instancetype', 'subscription'].filter(word => core.includes(word))};",
+    'for (const entry of modules) {',
+    "  const [name, path] = entry.split(':');",
+    "  const both = await size(`import {tokenize} from './tokenizer'; import {${name}} from './languages/${path}'; console.log(tokenize, ${name});`);",
+    '  result.modules[name] = both - base;',
+    '}',
+    'console.log(JSON.stringify(result));',
+  ].join('\n'),
+);
+
+describe('CodeBlock language budget (PR4)', () => {
+  const result = JSON.parse(
+    execFileSync(process.execPath, [script, here, ...MODULES], {
+      encoding: 'utf8',
+      timeout: 120_000,
+    })
+      .trim()
+      .split('\n')
+      .pop() ?? '{}',
+  ) as {
+    tokenizer: number;
+    modules: Record<string, number>;
+    leaked: string[];
+  };
+
+  it('keeps the built-in tokenizer within 4,608 bytes minified and gzipped', () => {
+    expect(result.tokenizer).toBeGreaterThan(0);
+    expect(result.tokenizer).toBeLessThanOrEqual(4608);
+  });
+
+  it('adds no module a bundle does not import', () => {
+    // Words only the Thrift, PowerShell, Dockerfile, Objective-C, and GraphQL
+    // grammars contain never reach a bundle of the CodeBlock entry.
+    expect(result.leaked).toEqual([]);
+  });
+
+  it.each(MODULES.map(entry => entry.split(':')[0]))(
+    'keeps the %s module within 512 bytes',
+    name => {
+      expect(result.modules[name]).toBeGreaterThan(0);
+      expect(result.modules[name]).toBeLessThanOrEqual(512);
+    },
+  );
+});

package/src/Collapsible/Collapsible.doc.mjs

@@ -93,6 +93,12 @@ export const docs = {
       description:
         'Identifier used for group coordination. When set inside a CollapsibleGroup, the group owns open state and its onChange is the notification callback.',
     },
+    {
+      name: 'animatedLayout',
+      type: 'AnimatedLayout',
+      description:
+        'The handle from useAnimatedLayout({containerRef}). With it, opening and closing glides the content after this Collapsible, up to that container, on one shared motion role instead of jumping, and the revealed content and the chevron move on the same motion. Without it, the content after it takes its place at once.',
+    },
     {
       name: 'ref',
       type: 'React.Ref<HTMLDivElement>',

package/src/Collapsible/Collapsible.spec.md

@@ -75,11 +75,12 @@ Consumer migration instructions belong in consumer docs and release notes.
 
 ## Public concepts
 
-| Concept                | Closed values or states | Meaning                                                                      | Availability                     | Default                                   | Owner                                        | Stability | Invalid-value behavior                    |
-| ---------------------- | ----------------------- | ---------------------------------------------------------------------------- | -------------------------------- | ----------------------------------------- | -------------------------------------------- | --------- | ----------------------------------------- |
-| chevron position       | `start`, `end`          | logical side of the trigger label that owns Collapsible's disclosure chevron | Collapsible and CollapsibleGroup | `end`                                     | `component:Collapsible`                      | stable    | rejected by the public type               |
-| disclosure state       | collapsed, expanded     | whether the controlled region is hidden or revealed                          | every Collapsible                | existing state owner                      | `component:Collapsible` or group state owner | stable    | existing controlled/uncontrolled behavior |
-| group position default | absent, `start`, `end`  | common position supplied to direct group items                               | CollapsibleGroup                 | absent, so item default resolves to `end` | `component:Collapsible`                      | stable    | rejected by the public type               |
+| Concept                | Closed values or states              | Meaning                                                                                                            | Availability                     | Default                                          | Owner                                        | Stability | Invalid-value behavior                    |
+| ---------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------ | -------------------------------- | ------------------------------------------------ | -------------------------------------------- | --------- | ----------------------------------------- |
+| chevron position       | `start`, `end`                       | logical side of the trigger label that owns Collapsible's disclosure chevron                                       | Collapsible and CollapsibleGroup | `end`                                            | `component:Collapsible`                      | stable    | rejected by the public type               |
+| disclosure state       | collapsed, expanded                  | whether the controlled region is hidden or revealed                                                                | every Collapsible                | existing state owner                             | `component:Collapsible` or group state owner | stable    | existing controlled/uncontrolled behavior |
+| group position default | absent, `start`, `end`               | common position supplied to direct group items                                                                     | CollapsibleGroup                 | absent, so item default resolves to `end`        | `component:Collapsible`                      | stable    | rejected by the public type               |
+| animated layout        | absent, a `useAnimatedLayout` handle | whether opening and closing glide the content after the Collapsible, up to the handle's container (`spec:AST-105`) | every Collapsible                | absent: content after it takes its place at once | `spec:AST-105`                               | stable    | rejected by the public type               |
 
 The public prop is named `chevronPosition`. The exported value type is
 `CollapsibleChevronPosition`. `placement`, `side`, and rendering terminology are
@@ -87,17 +88,18 @@ not parallel public names for this axis.
 
 ## Behavioral and layout contract
 
-| ID  | Invariant                                                                                                                                                                                                                                         | Basis                                                     |
-| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
-| FR1 | Collapsible MUST expose `chevronPosition?: 'start' \| 'end'`; omission resolves to `end`.                                                                                                                                                         | owner API decision; preserves released default            |
-| FR2 | `end` MUST render Collapsible's chevron after the trigger label in logical order. Collapsed `end` points downward; expanded `end` points upward.                                                                                                  | shipped trailing behavior plus approved position contract |
-| FR3 | `start` MUST render Collapsible's chevron before the trigger label in logical order. Collapsed `start` points inward toward the label/content, so its inline direction mirrors under RTL; expanded `start` points downward.                       | approved leading-disclosure behavior                      |
-| FR4 | Position changes the chevron glyph/direction as well as DOM order. Reusing a vertical down chevron and rotating it sideways MUST NOT make collapsed `start` point away from its content.                                                          | direction and representation decision                     |
-| FR5 | Collapsible owns and renders the chevron for both positions. The position axis MUST NOT accept `none`, arbitrary React content, a cue callback, a renderer, or another replacement escape hatch.                                                  | constrained public-axis decision                          |
-| FR6 | Trigger-label content MUST retain the usable row width needed by composed labels at either position. Moving the chevron to `start` MUST NOT strand the label at the opposite edge or prevent composed label content from using the remaining row. | approved layout rationale and existing grow behavior      |
-| FR7 | CollapsibleGroup MAY provide one `chevronPosition` default to its direct Collapsible items. A direct item's explicit position MUST override the group default.                                                                                    | approved group-coherence behavior                         |
-| FR8 | A Collapsible nested inside another item's revealed content MUST begin a new presentation scope and use its own explicit position or the component default. The outer group's position MUST NOT leak into the nested disclosure.                  | approved nested isolation behavior                        |
-| FR9 | Chevron position MUST NOT change disclosure semantics. The same trigger remains a button, retains `aria-expanded`, identifies the controlled region with `aria-controls`, and follows the existing state owner.                                   | existing accessibility and behavior contract              |
+| ID   | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                            | Basis                                                     |
+| ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------- |
+| FR1  | Collapsible MUST expose `chevronPosition?: 'start' \| 'end'`; omission resolves to `end`.                                                                                                                                                                                                                                                                                                                                            | owner API decision; preserves released default            |
+| FR2  | `end` MUST render Collapsible's chevron after the trigger label in logical order. Collapsed `end` points downward; expanded `end` points upward.                                                                                                                                                                                                                                                                                     | shipped trailing behavior plus approved position contract |
+| FR3  | `start` MUST render Collapsible's chevron before the trigger label in logical order. Collapsed `start` points inward toward the label/content, so its inline direction mirrors under RTL; expanded `start` points downward.                                                                                                                                                                                                          | approved leading-disclosure behavior                      |
+| FR4  | Position changes the chevron glyph/direction as well as DOM order. Reusing a vertical down chevron and rotating it sideways MUST NOT make collapsed `start` point away from its content.                                                                                                                                                                                                                                             | direction and representation decision                     |
+| FR5  | Collapsible owns and renders the chevron for both positions. The position axis MUST NOT accept `none`, arbitrary React content, a cue callback, a renderer, or another replacement escape hatch.                                                                                                                                                                                                                                     | constrained public-axis decision                          |
+| FR6  | Trigger-label content MUST retain the usable row width needed by composed labels at either position. Moving the chevron to `start` MUST NOT strand the label at the opposite edge or prevent composed label content from using the remaining row.                                                                                                                                                                                    | approved layout rationale and existing grow behavior      |
+| FR7  | CollapsibleGroup MAY provide one `chevronPosition` default to its direct Collapsible items. A direct item's explicit position MUST override the group default.                                                                                                                                                                                                                                                                       | approved group-coherence behavior                         |
+| FR8  | A Collapsible nested inside another item's revealed content MUST begin a new presentation scope and use its own explicit position or the component default. The outer group's position MUST NOT leak into the nested disclosure.                                                                                                                                                                                                     | approved nested isolation behavior                        |
+| FR9  | Chevron position MUST NOT change disclosure semantics. The same trigger remains a button, retains `aria-expanded`, identifies the controlled region with `aria-controls`, and follows the existing state owner.                                                                                                                                                                                                                      | existing accessibility and behavior contract              |
+| FR10 | Collapsible MUST accept `animatedLayout?: AnimatedLayout`. With a handle, opening and closing report the content's size change through it, so the content after the Collapsible glides inside the handle's container, and the revealed content and the chevron move on the same motion (`spec:AST-105` FR1–FR4; `spec:AST-108` FR4a). Without one, opening and closing are unchanged. The prop MUST NOT change disclosure semantics. | `spec:AST-105` FR1, FR2                                   |
 
 ### Allowed variation
 
@@ -194,13 +196,14 @@ to the Group container anatomy here.
 
 ## Verification map
 
-| Contract           | Verification                                                                                       | Representative states                                                             | Mutation or failure expectation                                                                                                                                                                    | Audit section                   |
-| ------------------ | -------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- |
-| FR1–FR5            | Collapsible prop/type, DOM-order, glyph/direction, and no-extra-values tests                       | omitted/end/start; collapsed/expanded; LTR/RTL                                    | default changes, `start` follows the label, collapsed leading cue points outward, or an unsupported cue value is admitted                                                                          | audit:Collapsible/public-api    |
-| FR6                | composed trigger layout and geometry tests                                                         | plain text; composed label with trailing content; start/end                       | label becomes shrink-wrapped/stranded or composed content cannot use remaining row                                                                                                                 | audit:Collapsible/layout        |
-| FR7–FR8, ORD1      | group inheritance, item override, and nested reset tests                                           | group start/end; item override; nested omission                                   | group value is ignored, item cannot override, or position leaks into nested content                                                                                                                | audit:Collapsible/behavior      |
-| FR9, AR1–AR3, ORD2 | disclosure semantics via `DISCLOSURE_PATTERN`, plus component-owned chevron and real RTL rendering | collapsed/expanded; controlled/uncontrolled; enabled/disabled; start/end; LTR/RTL | position changes state behavior, the trigger loses its controlled-content relationship, content visibility diverges from state, accessible output duplicates, or leading direction fails to mirror | audit:Collapsible/accessibility |
-| Theming anatomy    | focused target-reflection assertions plus `themingTargets.test.ts`                                 | standalone/grouped; open/closed; enabled/disabled; start/end; divided/density     | a style-driving axis or state disappears from its owning target, a target loses its anatomy owner, or the chevron stops delegating to Icon                                                         | audit:Collapsible/theming       |
+| Contract           | Verification                                                                                                                                                                                                                                                                                                                                                            | Representative states                                                                | Mutation or failure expectation                                                                                                                                                                    | Audit section                   |
+| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- |
+| FR1–FR5            | Collapsible prop/type, DOM-order, glyph/direction, and no-extra-values tests                                                                                                                                                                                                                                                                                            | omitted/end/start; collapsed/expanded; LTR/RTL                                       | default changes, `start` follows the label, collapsed leading cue points outward, or an unsupported cue value is admitted                                                                          | audit:Collapsible/public-api    |
+| FR6                | composed trigger layout and geometry tests                                                                                                                                                                                                                                                                                                                              | plain text; composed label with trailing content; start/end                          | label becomes shrink-wrapped/stranded or composed content cannot use remaining row                                                                                                                 | audit:Collapsible/layout        |
+| FR7–FR8, ORD1      | group inheritance, item override, and nested reset tests                                                                                                                                                                                                                                                                                                                | group start/end; item override; nested omission                                      | group value is ignored, item cannot override, or position leaks into nested content                                                                                                                | audit:Collapsible/behavior      |
+| FR9, AR1–AR3, ORD2 | disclosure semantics via `DISCLOSURE_PATTERN`, plus component-owned chevron and real RTL rendering                                                                                                                                                                                                                                                                      | collapsed/expanded; controlled/uncontrolled; enabled/disabled; start/end; LTR/RTL    | position changes state behavior, the trigger loses its controlled-content relationship, content visibility diverges from state, accessible output duplicates, or leading direction fails to mirror | audit:Collapsible/accessibility |
+| FR10               | `animatedLayoutAdopters.test.tsx` (with and without a handle; an owner-set `isOpen` and a group's controlled value glide; one measurement in StrictMode and none for a refused change; the exit kept inert until it ends) and `animatedLayoutAdopters.interaction.browser.spec.ts` (the `Core/Animated layout` story through a ScrollableArea ref, opening and closing) | no handle; a handle; click, owner-set, and group-driven changes; opening and closing | the content after it jumps with a handle, an owner-set change lands at once, closing content vanishes before its exit or stays reachable during it, or anything changes without a handle           | audit:Collapsible/behavior      |
+| Theming anatomy    | focused target-reflection assertions plus `themingTargets.test.ts`                                                                                                                                                                                                                                                                                                      | standalone/grouped; open/closed; enabled/disabled; start/end; divided/density        | a style-driving axis or state disappears from its owning target, a target loses its anatomy owner, or the chevron stops delegating to Icon                                                         | audit:Collapsible/theming       |
 
 ## Decision log
 

package/src/Collapsible/Collapsible.tsx

@@ -27,7 +27,16 @@
  * - /packages/cli/assets/templates/blocks/components/Collapsible/ (showcase blocks)
  */
 
-import {use, useId, type ReactNode} from 'react';
+import {
+  use,
+  useCallback,
+  useId,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useState,
+  type ReactNode,
+} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import {
   borderVars,
@@ -41,6 +50,15 @@ import {
 } from '../theme/tokens.stylex';
 
 import {useCollapsible} from './useCollapsible';
+import {LayoutChangeSnapshot} from '../motion/LayoutChangeSnapshot';
+import {
+  applyLayoutChangeTransition,
+  holdLayoutExit,
+  playLayoutChange,
+  releaseLayoutExit,
+  reportLayoutChange,
+  type AnimatedLayout,
+} from '../motion/animatedLayout';
 import {CollapsibleGroupPresentationContext} from './CollapsibleGroupContext';
 import type {CollapsibleChevronPosition} from './CollapsibleGroupContext';
 import {Icon} from '../Icon';
@@ -242,6 +260,12 @@ export interface CollapsibleProps extends BaseProps {
    * CollapsibleGroup owns grouped state and calls its `onChange` instead.
    */
   onOpenChange?: (isOpen: boolean) => void;
+  /**
+   * The handle from `useAnimatedLayout({containerRef})`. With it, opening and
+   * closing glides the content after this Collapsible, up to that container,
+   * instead of jumping, and the chevron turns on the same timing.
+   */
+  animatedLayout?: AnimatedLayout;
 
   /**
    * Logical position of the disclosure chevron.
@@ -317,6 +341,7 @@ export function Collapsible({
   onOpenChange,
   chevronPosition,
   value,
+  animatedLayout,
   ref,
   xstyle,
   className,
@@ -335,6 +360,95 @@ export function Collapsible({
     value,
   });
 
+  // With an `animatedLayout` handle, the content's size change animates: the
+  // content after this Collapsible, up to the handle's container, glides, and
+  // the revealed content plays its own entrance on the same timing
+  // (`architecture:react-component-runtime` INV12). Without one, nothing
+  // changes.
+  const contentRef = useRef<HTMLDivElement>(null);
+  const triggerRef = useRef<HTMLButtonElement>(null);
+  const layoutChange = useMemo(
+    () => reportLayoutChange(animatedLayout, contentRef),
+    [animatedLayout],
+  );
+  // Every open-state change, whatever caused it (a click, an owner-set
+  // `isOpen`, a group's value), is measured before it lands (`spec:AST-105`
+  // FR1): LayoutChangeSnapshot calls this in the commit, before the DOM
+  // changes. The chevron (the trigger's Icon, its `icon` theming target)
+  // turns on the glide's motion too.
+  const measureChange = useCallback(() => {
+    applyLayoutChangeTransition(
+      animatedLayout,
+      triggerRef.current?.querySelector<HTMLElement>(':scope > .astryx-icon') ??
+        null,
+    );
+    layoutChange.measureBefore();
+  }, [animatedLayout, layoutChange]);
+  // Without a handle the chevron keeps the theme's own turn: a spring a handle
+  // set stays only while it is passed (`spec:AST-105` FR2).
+  useLayoutEffect(() => {
+    if (animatedLayout == null) {
+      applyLayoutChangeTransition(
+        null,
+        triggerRef.current?.querySelector<HTMLElement>(
+          ':scope > .astryx-icon',
+        ) ?? null,
+      );
+    }
+  }, [animatedLayout]);
+  // A close with a handle keeps the content rendered while it plays its exit
+  // (the exit makes it inert and gives up its space), then hides it
+  // (`spec:AST-105` FR4). Derived from the open state as it changes, during
+  // render, so the closing commit already keeps it.
+  const [renderedIsOpen, setRenderedIsOpen] = useState(isOpen);
+  const [isExiting, setIsExiting] = useState(false);
+  if (renderedIsOpen !== isOpen) {
+    setRenderedIsOpen(isOpen);
+    setIsExiting(!isOpen && animatedLayout != null);
+  }
+  const endExit = useCallback(() => {
+    // eslint-disable-next-line @eslint-react/set-state-in-effect -- holdLayoutExit decides from layout read in the closing commit (the content's place in the area's visible part, Reduce Motion and the pointer, and whether an end margin frees its space); an exit it does not hold hides the content before the frame paints
+    setIsExiting(false);
+  }, []);
+  const wasOpenRef = useRef(isOpen);
+  useLayoutEffect(() => {
+    if (wasOpenRef.current === isOpen) {
+      return;
+    }
+    wasOpenRef.current = isOpen;
+    const content = contentRef.current;
+    if (content == null) {
+      return;
+    }
+    // A change that was not measured (no handle) lands at once, entrance and
+    // exit included, so the content and what follows stay in step.
+    const isMeasured = layoutChange.animate();
+    if (isOpen) {
+      // Opened again mid-exit: the content takes its place in flow.
+      releaseLayoutExit(content);
+      if (isMeasured) {
+        playLayoutChange(animatedLayout, content);
+      }
+      return;
+    }
+    const isHeld =
+      isExiting &&
+      isMeasured &&
+      holdLayoutExit(animatedLayout, content, endExit);
+    if (isExiting && !isHeld) {
+      // An exit holdLayoutExit did not hold (unmeasured, out of view, Reduce
+      // Motion with a fine pointer, or no margin frees its space): hide the
+      // content before this frame paints.
+      endExit();
+    }
+  }, [isOpen, isExiting, layoutChange, animatedLayout, endExit]);
+  useLayoutEffect(() => {
+    if (!isOpen && !isExiting && contentRef.current != null) {
+      // Hidden again after its exit: drop the exit's inline values.
+      releaseLayoutExit(contentRef.current);
+    }
+  }, [isOpen, isExiting]);
+
   // Activation is blocked by this guard rather than the native `disabled`
   // attribute, so the trigger keeps `aria-disabled` semantics and stays
   // discoverable. A native `disabled` button would silently swallow events
@@ -399,6 +513,7 @@ export function Collapsible({
       )}
       {...props}>
       <button
+        ref={triggerRef}
         type="button"
         onClick={handleToggle}
         aria-disabled={isDisabled || undefined}
@@ -432,7 +547,11 @@ export function Collapsible({
         <span {...stylex.props(styles.triggerLabel)}>{trigger}</span>
         {!isChevronAtStart && chevron}
       </button>
+      {animatedLayout != null && (
+        <LayoutChangeSnapshot value={isOpen} onBeforeChange={measureChange} />
+      )}
       <div
+        ref={contentRef}
         id={contentId}
         {...mergeProps(
           themeProps('collapsible-content', {
@@ -442,7 +561,7 @@ export function Collapsible({
           stylex.props(
             styles.content,
             density != null && contentDensity[density],
-            !isOpen && styles.contentHidden,
+            !isOpen && !isExiting && styles.contentHidden,
           ),
         )}>
         {presentation != null ? (