@astryxdesign/core 0.6.1 → 0.6.2-canary.0faf070

package/src/Markdown/utils.ts

@@ -16,9 +16,15 @@ export {
 
 export type {
   InlineNode,
+  InlineNodeWithMath,
+  MathInlineNode,
   BlockNode,
+  BlockNodeWithMath,
+  MathBlockNode,
   ListItemNode,
   TableCellNode,
   TableAlignment,
+  ParseOptions,
+  MathParseOptions,
   IncrementalState,
 } from './parser';

package/src/Outline/Outline.spec.md

@@ -12,7 +12,7 @@ owners: [cixzhang]
 review_triggers: [theming]
 verified_by:
   [packages/core/src/Outline/Outline.test.tsx, scripts/check-knowledge.mjs]
-modules: []
+modules: [module:Outline/parseOutlineFromMarkdown]
 families: []
 design_specs: []
 architecture: [architecture:component-theming-surface]

package/src/Outline/modules/parseOutlineFromMarkdown.spec.md

@@ -0,0 +1,142 @@
+---
+schema_version: 3
+template_version: 1
+kind: module
+id: module:Outline/parseOutlineFromMarkdown
+authority: current
+archive_reason: null
+superseded_by: null
+approved_by: cixzhang
+approved_at: 2026-09-15
+owners: [cixzhang]
+review_triggers: [public-api, behavior]
+verified_by: [packages/core/src/Outline/parseOutlineFromMarkdown.test.ts]
+parent_component: component:Outline
+references:
+  [architecture:public-component-api, component:Markdown, spec:AST-036]
+---
+
+# parseOutlineFromMarkdown module contract
+
+## Intent
+
+`parseOutlineFromMarkdown` and `useOutlineFromMarkdown` derive same-document
+heading navigation from the same Markdown parse configuration, ordered immutable
+transforms, text projection, and collision allocator used by the rendered document.
+This focused module owns that utility behavior without deciding the draft Outline
+component's anatomy or theming.
+
+## Compatibility and migration
+
+- Released default preserved: `yes`
+- Compatibility class: additive parser options; calls without plugins preserve
+  released labels, levels, IDs, and return types
+- Migration decision: `spec:AST-036`
+
+## Ownership boundary
+
+**Owns**
+
+- Deriving ordered `OutlineItem` values from Markdown headings.
+- Accepting the same parser-affecting options and ordered plugin list as Markdown.
+- Applying the same validated immutable transforms before selecting headings.
+- Using the same extension text projection and collision-safe slug allocation as
+  Markdown heading rendering.
+
+**Does not own / non-goals**
+
+- Outline component structure, active state, targets, layout, or theming.
+- Plugin rendering, block-extension navigation entries, or renderer-derived text.
+- A second parser, plugin registry, or independent heading-ID policy.
+
+## Public API and concepts
+
+`parseOutlineFromMarkdown(source, options?)` performs direct derivation.
+`useOutlineFromMarkdown(source, options?)` memoizes the same derivation for React
+callers. `options.plugins` uses the canonical opaque Markdown plugin entries. The
+same ordered transforms run before heading selection; inline extension-node `toText`
+projections then contribute to heading labels and IDs.
+
+## Behavioral contract
+
+| ID  | Invariant                                                                                                                                                                                                                                                                                                                                                                             | Basis                           | Acceptance and implementation state |
+| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- | ----------------------------------- |
+| FR1 | Both utilities accept the same Markdown parser options and ordered plugin list as the rendered Markdown document.                                                                                                                                                                                                                                                                     | `spec:AST-036` FR13, FR16       | pending implementation              |
+| FR2 | Both utilities apply the same validated immutable transforms before selecting headings, without allowing renderer output to affect identity.                                                                                                                                                                                                                                          | `spec:AST-036` FR13, FR16       | pending implementation              |
+| FR3 | Plugin-enabled labels and IDs use the same extension `toText` projection, slugger, and cross-base collision allocator as Markdown, producing unique matching targets.                                                                                                                                                                                                                 | `spec:AST-036` FR16             | pending implementation              |
+| FR4 | An extension node never creates an Outline entry of its own, and extension containers do not change heading traversal: entries come from the same blocks Markdown assigns heading IDs to, so a heading nested in a container is omitted exactly as one nested in a blockquote or list item is. A container never restarts, extends, or re-scopes heading identity or slug allocation. | `spec:AST-036` FR16, FR25       | pending implementation              |
+| FR5 | Omitting plugins and passing an empty list preserve released heading selection, labels, levels, IDs, return type, and memoization behavior.                                                                                                                                                                                                                                           | `spec:AST-036` FR2              | pending implementation              |
+| FR6 | The hook memoizes against source and every parse-affecting or transform-affecting option so changed configuration cannot return stale headings.                                                                                                                                                                                                                                       | `component:Markdown` FR15–FR16  | pending implementation              |
+| FR7 | A transform that removes a heading removes its Outline entry, and a transform that inserts a synthetic heading adds one, in both surfaces identically. Source-backed heading depth cannot change, so an entry's level always matches the rendered heading.                                                                                                                            | `spec:AST-036` FR26             | pending implementation              |
+| FR8 | When a plugin fails, derivation uses the same last valid root the rendered document uses, so labels, levels, and IDs still agree. Failures are reported through the shared diagnostic channel; this module adds no failure mode, fallback, or throw of its own.                                                                                                                       | `spec:AST-036` FR12, FR29       | pending implementation              |
+| FR9 | Derivation runs on the canonical tree through the shared parse path and requires no DOM, renderer, client boundary, or second parser. Because transforms are idempotent under streaming, an outline derived from a growing source prefix converges rather than oscillates.                                                                                                            | `spec:AST-036` FR32, FR33, FR36 | pending implementation              |
+
+### Transformation and precedence order
+
+Markdown parse configuration → ordered immutable transforms → heading nodes →
+shared perceivable-text projection → shared slug normalization → document-order
+collision allocation → Outline items.
+
+### Performance and resources
+
+- The hook recomputes only when source or parser/transform configuration changes.
+- Renderer output does not enter heading identity.
+- No DOM, renderer mount, registry, Remark runtime, or optional plugin resource is
+  required.
+
+## Accessibility contract
+
+Each derived label is the same perceivable heading text used for Markdown identity,
+and each derived ID targets the matching rendered heading. This module adds no
+interaction or ARIA behavior; the Outline component owns navigation presentation.
+
+## Design relationships
+
+No visual representation is owned by this parser utility.
+
+## Parent and system relationships
+
+- `component:Markdown` owns aggregate parsing, heading rendering, and the shared
+  projection/collision rules.
+- `spec:AST-036` owns the canonical plugin protocol and cross-surface parity.
+- Draft `component:Outline` owns presentation only after its separate anatomy and
+  theming decisions become current.
+
+## Verification map
+
+| Contract | Verification                                                            | Representative states                                                                                                                                                       | Mutation or failure expectation                                                                                                         |
+| -------- | ----------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| FR1–FR6  | Outline parser tests, plugin transform parity tests, and Core typecheck | transformed, formatted, and extension headings; headings nested in extension containers, blockquotes, and list items; duplicate and cross-base slugs; omitted/empty plugins | A transform is skipped, a label/ID diverges from Markdown, a container changes which headings have identity, or default output changes. |
+| FR7–FR9  | Heading insert/remove parity, failure parity, and streaming derivation  | headings removed with/without sections; inserted synthetic headings; failing transform; growing source prefix; server derivation                                            | Outline/document disagreement, divergent fallback, a throw, stale IDs, or streamed oscillation.                                         |
+
+## Decision log
+
+### DEC-1 — Markdown owns heading identity; Outline projects it
+
+**Reference:** `module:Outline/parseOutlineFromMarkdown/DEC-1`
+**Decider:** cixzhang, 2026-09-15
+
+Outline utilities consume Markdown's parse configuration, ordered transforms, text
+projection, and collision allocator rather than defining a second heading-identity
+system. This keeps labels and link targets aligned without coupling plugin renderer
+output to navigation identity.
+
+### DEC-2 — One traversal survives containers and heading edits
+
+**Reference:** `module:Outline/parseOutlineFromMarkdown/DEC-2`
+**Decider:** cixzhang, 2026-09-16
+
+Extension containers hold ordinary Markdown but do not change which headings have identity. Markdown assigns IDs by one traversal and this module reads the same one, so Outline never links to a heading Markdown did not identify. A heading inside a container remains omitted like one inside a blockquote or list item, and the extension node is never an Outline entry. Widening traversal is a separate decision.
+
+Transforms may remove and insert headings, so Outline follows the rendered document rather than source: a dropped heading disappears, an inserted heading appears, and immutable source-backed depth keeps levels aligned. Both surfaces run the same pipeline rather than independent rules.
+
+Rejected: a container-only traversal exception; extension nodes as Outline entries; source-only derivation; module-local plugin failure fallback.
+
+## Open questions
+
+None.
+
+## Content boundary
+
+This file does not duplicate plugin protocol details, Markdown parser mechanics,
+consumer examples, or the draft Outline component's anatomy and theming contract.

package/src/PowerSearch/PowerSearchEditPopover.test.tsx

@@ -10,7 +10,14 @@ import {
   afterAll,
   afterEach,
 } from 'vitest';
-import {render, screen, fireEvent, act} from '@testing-library/react';
+import {
+  render,
+  screen,
+  fireEvent,
+  act,
+  waitFor,
+  within,
+} from '@testing-library/react';
 import React, {useState} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import {spacingVars} from '../theme/tokens.stylex';
@@ -170,6 +177,148 @@ describe('PowerSearch', () => {
     expect(popoverText).toContain('equals');
   });
 
+  describe('value editor identity follows the field and operator', () => {
+    // Two fields with the same value type, so an unkeyed editor would be
+    // reused across the switch and keep the first field's menu contents.
+    const sameTypeConfig: PowerSearchConfig = {
+      name: 'test-same-type',
+      fields: [
+        {
+          key: 'creator',
+          label: 'Creator',
+          operators: [
+            {
+              key: 'is_any_of',
+              label: 'is any of',
+              value: {
+                type: 'enum_list',
+                values: [{value: 'creator-1', label: 'Creator Person'}],
+              },
+            },
+          ],
+        },
+        {
+          key: 'owner',
+          label: 'Owner',
+          operators: [
+            {
+              key: 'is_any_of',
+              label: 'is any of',
+              value: {
+                type: 'enum_list',
+                values: [{value: 'owner-1', label: 'Owner Person'}],
+              },
+            },
+          ],
+        },
+      ],
+    };
+
+    const creatorOption = () =>
+      screen.queryByRole('option', {name: 'Creator Person', hidden: true});
+    const ownerOption = () =>
+      screen.queryByRole('option', {name: 'Owner Person', hidden: true});
+
+    it('replaces an open value menu when the field changes', async () => {
+      function Harness() {
+        const internalConfig = useInternalConfig(sameTypeConfig);
+        return (
+          <PowerSearchEditPopover
+            config={internalConfig}
+            filter={{
+              field: 'creator',
+              operator: 'is_any_of',
+              value: {type: 'enum_list', value: []},
+            }}
+            mode="edit"
+            onSave={() => {}}
+            onCancel={() => {}}
+          />
+        );
+      }
+
+      render(<Harness />);
+
+      // Open the Creator value menu and leave it open.
+      fireEvent.focus(screen.getByRole('combobox', {name: 'Values'}));
+      await waitFor(() => expect(creatorOption()).toBeInTheDocument());
+
+      // Switch the field underneath the open menu.
+      fireEvent.click(screen.getByRole('combobox', {name: 'Field'}));
+      fireEvent.click(
+        screen.getByRole('option', {name: 'Owner', hidden: true}),
+      );
+      act(() => flushRAF());
+
+      // The old field's options are gone, the new field's are shown.
+      expect(creatorOption()).not.toBeInTheDocument();
+      await waitFor(() => expect(ownerOption()).toBeInTheDocument());
+    });
+
+    it('replaces an open value menu on a nested sub-filter row', async () => {
+      const nestedConfig: PowerSearchConfig = {
+        name: 'test-nested-same-type',
+        fields: [
+          {
+            key: 'group',
+            label: 'Group',
+            operators: [
+              {key: 'all_of', label: 'all of', value: {type: 'nested'}},
+            ],
+          },
+          ...sameTypeConfig.fields,
+        ],
+      };
+
+      function Harness() {
+        const internalConfig = useInternalConfig(nestedConfig);
+        return (
+          <PowerSearchEditPopover
+            config={internalConfig}
+            filter={{
+              field: 'group',
+              operator: 'all_of',
+              value: {
+                type: 'nested',
+                value: [
+                  {
+                    field: 'creator',
+                    operator: 'is_any_of',
+                    value: {type: 'enum_list', value: []},
+                  },
+                ],
+              },
+            }}
+            mode="edit"
+            onSave={() => {}}
+            onCancel={() => {}}
+          />
+        );
+      }
+
+      render(<Harness />);
+
+      fireEvent.focus(screen.getByRole('combobox', {name: 'Values'}));
+      await waitFor(() => expect(creatorOption()).toBeInTheDocument());
+
+      // The nested row's own field selector is the one currently on
+      // "Creator"; the root selector stays on "Group".
+      const rowField = screen
+        .getAllByRole('combobox', {name: 'Field'})
+        .find(el => el.textContent === 'Creator');
+      expect(rowField).toBeDefined();
+      fireEvent.click(rowField!);
+      const rowListbox = document.getElementById(
+        rowField!.getAttribute('aria-controls')!,
+      )!;
+      fireEvent.click(
+        within(rowListbox).getByRole('option', {name: 'Owner', hidden: true}),
+      );
+
+      expect(creatorOption()).not.toBeInTheDocument();
+    });
+  });
+
   it('edit popover shows correct filter after removing a preceding filter', () => {
     const filters: PowerSearchFilter[] = [
       {field: 'status', operator: 'is', value: {type: 'string', value: 'open'}},

package/src/PowerSearch/PowerSearchEditPopover.tsx

@@ -22,7 +22,10 @@ import {TreeList, type TreeListItemData} from '../TreeList';
 import {useTranslator} from '../i18n';
 import {isImeKeyEvent} from '../utils/ime';
 import {spacingVars, typeScaleVars} from '../theme/tokens.stylex';
-import {PowerSearchValueEditor} from './PowerSearchValueEditor';
+import {
+  PowerSearchValueEditor,
+  type PowerSearchValueEditorProps,
+} from './PowerSearchValueEditor';
 import {resolveOperatorLabel} from './resolveOperatorLabel';
 import type {InternalConfig} from './useInternalConfig';
 import type {
@@ -356,6 +359,7 @@ function NestedSubFilterRow({
       {operatorValue && !isEmptyType && !isNestedType && (
         <div {...stylex.props(styles.nestedRowValueEditor)}>
           <PowerSearchValueEditor
+            key={valueEditorKey(subFilter)}
             operatorValue={operatorValue}
             filterValue={subFilter.value}
             onChange={handleValueChange}
@@ -606,6 +610,42 @@ function NestedEditor({
   return <TreeList items={items} density="balanced" />;
 }
 
+// =============================================================================
+// Value editor cell
+// =============================================================================
+
+// A field switch must replace the editor, not update it in place: a reused
+// editor keeps its open menu and old results.
+function valueEditorKey(filter: {field: string; operator?: string}): string {
+  return `${filter.field}\u0000${filter.operator ?? ''}`;
+}
+
+// Keyed on field + operator, so this also mounts on a field switch, not just
+// when the popover opens; the focus handoff below runs for both.
+function ValueEditorCell(props: PowerSearchValueEditorProps) {
+  const ref = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    const frame = requestAnimationFrame(() => {
+      const container = ref.current;
+      if (!container) {
+        return;
+      }
+      const focusable = container.querySelector<HTMLElement>(
+        'input:not([disabled]), button:not([disabled]), textarea:not([disabled]), select:not([disabled]), [tabindex]:not([tabindex="-1"])',
+      );
+      focusable?.focus();
+    });
+    return () => cancelAnimationFrame(frame);
+  }, []);
+
+  return (
+    <div ref={ref} {...stylex.props(styles.valueEditor)}>
+      <PowerSearchValueEditor {...props} />
+    </div>
+  );
+}
+
 // =============================================================================
 // Main popover
 // =============================================================================
@@ -625,22 +665,6 @@ export function PowerSearchEditPopover({
     saveButtonLabelFromProps ?? t('@astryx.powersearch.editor.apply');
   const [partialFilter, setPartialFilter] =
     useState<PartialFilter>(initialFilter);
-  const valueEditorRef = useRef<HTMLDivElement>(null);
-
-  // Focus the first focusable element inside the value editor after mount
-  useEffect(() => {
-    const frame = requestAnimationFrame(() => {
-      const container = valueEditorRef.current;
-      if (!container) {
-        return;
-      }
-      const focusable = container.querySelector<HTMLElement>(
-        'input:not([disabled]), button:not([disabled]), textarea:not([disabled]), select:not([disabled]), [tabindex]:not([tabindex="-1"])',
-      );
-      focusable?.focus();
-    });
-    return () => cancelAnimationFrame(frame);
-  }, []);
 
   const currentOperator = partialFilter.operator
     ? config.getOperator(partialFilter.field, partialFilter.operator)
@@ -854,17 +878,16 @@ export function PowerSearchEditPopover({
             </div>
           )}
           {operatorValue && !isEmptyType && (
-            <div ref={valueEditorRef} {...stylex.props(styles.valueEditor)}>
-              <PowerSearchValueEditor
-                operatorValue={operatorValue}
-                filterValue={partialFilter.value}
-                onChange={handleValueChange}
-                onEnter={handleSave}
-                config={config}
-                maxMenuItems={maxMenuItems}
-                isDisabled={isReadOnly}
-              />
-            </div>
+            <ValueEditorCell
+              key={valueEditorKey(partialFilter)}
+              operatorValue={operatorValue}
+              filterValue={partialFilter.value}
+              onChange={handleValueChange}
+              onEnter={handleSave}
+              config={config}
+              maxMenuItems={maxMenuItems}
+              isDisabled={isReadOnly}
+            />
           )}
         </HStack>
       </div>

package/src/RadioList/RadioList.doc.mjs

@@ -132,6 +132,17 @@ export const docs = {
     {name: 'RadioListItem'},
   ],
   usage: {
+    accessibility: [
+      {
+        name: 'Radio circle',
+        category: 'Color contrast',
+        criterion: '1.4.11 Non-text Contrast',
+        requirement: '3:1',
+        states: ['Rest', 'Hover', 'Pointer down', 'Selected'],
+        description:
+          'The circle edge (unselected) and fill (selected) 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:
       'A group of options where only one can be selected at a time. All options are visible at once, making it easy to compare choices. Use it when users need to pick one option from a small set.',
     bestPractices: [

package/src/RadioList/RadioList.test.tsx

@@ -15,6 +15,7 @@
 import {describe, it, expect, vi, beforeEach} from 'vitest';
 import {render, screen, fireEvent, waitFor} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
+import {hasPressedArm} from '../__tests__/pressState';
 import {RadioList} from './RadioList';
 import {RadioListItem} from './RadioListItem';
 import {getForcedColorsRules} from '../__tests__/forcedColors';
@@ -856,3 +857,34 @@ describe('forced colors (WCAG 1.4.11)', () => {
     expect(getForcedColorsRules()).toContain('background-color: canvastext;');
   });
 });
+
+describe('pressed state', () => {
+  it('paints the pressed overlay over the radio indicator while the row is pressed', () => {
+    const {container} = render(
+      <RadioList label="Plan" value="a" onChange={() => {}}>
+        <RadioListItem label="Option A" value="a" />
+        <RadioListItem label="Option B" value="b" />
+      </RadioList>,
+    );
+    const circle = container.querySelector('.astryx-radio-indicator');
+    const wrapper = circle?.parentElement?.parentElement;
+    if (wrapper == null) {
+      throw new Error('the radio has no indicator wrapper to press');
+    }
+    expect(hasPressedArm(wrapper)).toBe(true);
+  });
+
+  it('does not expose a pressed arm on a disabled radio', () => {
+    const {container} = render(
+      <RadioList label="Plan" value="a" onChange={() => {}}>
+        <RadioListItem label="Unavailable" value="b" isDisabled />
+      </RadioList>,
+    );
+    const circle = container.querySelector('.astryx-radio-indicator');
+    const wrapper = circle?.parentElement?.parentElement;
+    if (wrapper == null) {
+      throw new Error('the radio has no indicator wrapper');
+    }
+    expect(hasPressedArm(wrapper)).toBe(false);
+  });
+});

package/src/RadioList/RadioListItem.tsx

@@ -23,6 +23,7 @@ import * as stylex from '@stylexjs/stylex';
 import type {StyleXStyles} from '@stylexjs/stylex';
 import type {BaseProps} from '../BaseProps';
 import {RadioListContext} from './RadioList';
+import {colorVars, radiusVars} from '../theme/tokens.stylex';
 import {mergeProps, isRenderable, rtlStyles} from '../utils';
 import {indicatorScope} from '../Indicator/indicator.markers.stylex';
 import {useIndicatorFocusRing} from '../hooks/useIndicatorFocusRing';
@@ -39,6 +40,25 @@ const styles = stylex.create({
     flexShrink: 0,
     isolation: 'isolate',
   },
+  // The row remains the large press target, but nested links and buttons keep
+  // their independent action and do not make the radio appear pressed. This
+  // owner-drawn layer also survives a theme replacing the indicator component.
+  indicatorPressOverlay: {
+    '::after': {
+      content: '""',
+      position: 'absolute',
+      inset: 0,
+      borderRadius: radiusVars['--radius-full'],
+      pointerEvents: 'none',
+      backgroundColor: {
+        default: 'transparent',
+        [stylex.when.ancestor(
+          ':active:not(:has(a:active,button:active,[role="button"]:active,[role="link"]:active))',
+          indicatorScope,
+        )]: colorVars['--color-overlay-pressed'],
+      },
+    },
+  },
   input: {
     position: 'absolute',
     top: '50%',
@@ -222,7 +242,11 @@ export function RadioListItem({
 
   const radioCircle = (
     <div
-      {...stylex.props(styles.radioWrapper, wrapperSizeStyles[size])}
+      {...stylex.props(
+        styles.radioWrapper,
+        wrapperSizeStyles[size],
+        !isDisabled && styles.indicatorPressOverlay,
+      )}
       {...focusProps}>
       <input
         ref={radioRef}