@astryxdesign/core 0.7.2 → 0.7.3-canary.0bf23bd

package/dist/hooks/useMenuPress.js

@@ -36,7 +36,9 @@
  *
  * The menu root is marked `data-astryx-menu-press` so a nested flyout (a DOM
  * descendant of its parent menu) can tell which level owns a press, and so a
- * surface can be recognised as carrying this model.
+ * surface can be recognised as carrying this model. A menu the root renders
+ * beside itself names the root with `data-astryx-menu-press-surface` and counts
+ * as nested in it.
  *
  * SYNC: When modified, update:
  * - /packages/core/src/hooks/index.ts
@@ -52,6 +54,14 @@ import { useLongPress } from "./useLongPress.js";
 /** Marks a menu root that carries this press model. */
 export const MENU_PRESS_MARKER = 'data-astryx-menu-press';
 const MENU_PRESS_ROOT_SELECTOR = `[${MENU_PRESS_MARKER}]`;
+/**
+ * Carried by a menu root that another root renders beside itself rather than
+ * inside it, naming that root's `id`: the menu of a sub-menu with a header or
+ * footer, in a dialog beside the root's menu, is nested in that root for the
+ * press model, as a flyout inside the root's DOM is. Nothing else beside the
+ * root carries it, so a picker placed in a header or footer stays its own root.
+ */
+export const MENU_PRESS_SURFACE_ATTR = 'data-astryx-menu-press-surface';
 
 /** How long after a tracked release the browser's click is still swallowed. */
 export const MENU_PRESS_STRAY_CLICK_MS = 400;
@@ -153,13 +163,41 @@ function isRowFocusable(row) {
 function getOutermostRoot(menu) {
   let root = menu;
   for (;;) {
-    const parent = root.parentElement?.closest(MENU_PRESS_ROOT_SELECTOR);
-    if (parent == null) {
+    const parent = root.parentElement?.closest(MENU_PRESS_ROOT_SELECTOR) ?? getSurfaceOwner(root);
+    if (parent == null || parent === root) {
       return root;
     }
     root = parent;
   }
 }
+
+/**
+ * The menu root that renders `menu` beside itself, if any (see
+ * `MENU_PRESS_SURFACE_ATTR`). Read off the menu itself, never an ancestor, so
+ * a root placed in a region of that surface is not adopted.
+ */
+function getSurfaceOwner(menu) {
+  const ownerId = menu.getAttribute(MENU_PRESS_SURFACE_ATTR);
+  if (!ownerId) {
+    return null;
+  }
+  const owner = menu.ownerDocument.getElementById(ownerId);
+  return owner?.matches(MENU_PRESS_ROOT_SELECTOR) === true ? owner : null;
+}
+
+/**
+ * Whether `element` is inside the menu tree whose outermost root is `root`:
+ * inside the root itself, or inside a menu nested in it through a surface
+ * the root renders beside itself. Anything else in such a surface (a header
+ * field, say) is outside the menu, as the root's own regions are.
+ */
+function isInMenuTree(element, root) {
+  if (root.contains(element)) {
+    return true;
+  }
+  const owner = element.closest(MENU_PRESS_ROOT_SELECTOR);
+  return owner != null && getOutermostRoot(owner) === root;
+}
 // =============================================================================
 // Hook
 // =============================================================================
@@ -223,13 +261,13 @@ export function useMenuPress(options) {
       element = event.target instanceof Element ? event.target : null;
     }
     const root = menu == null ? null : getOutermostRoot(menu);
-    const isInMenu = root != null && element != null && root.contains(element);
+    const isInMenu = root != null && element != null && isInMenuTree(element, root);
     const trigger = triggerRef?.current ?? null;
     const isOnTrigger = trigger != null && element != null && trigger.contains(element);
     let row = null;
     if (isInMenu && element != null) {
       row = element.closest(itemSelector);
-      if (row != null && !root.contains(row)) {
+      if (row != null && !isInMenuTree(row, root)) {
         row = null;
       }
     }

package/dist/utils/disabledInteraction.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @file disabledInteraction.ts
+ * @input An optional caller keydown handler
+ * @output Event props that keep a focusable, aria-disabled control inert
+ * @position Shared by controls that replace native `disabled` with
+ *   `aria-disabled` under spec:AST-085 (FR1, FR2)
+ */
+import type { KeyboardEvent, KeyboardEventHandler, MouseEvent } from 'react';
+/**
+ * Event props for a disabled control that stays focusable. Native `disabled`
+ * dispatched no click at all; without it, Enter and Space still synthesize a
+ * click that native listeners on the element (a wrapping Popover's trigger)
+ * receive. Cancelling those keys keeps the click from existing, and the click
+ * handler cancels pointer clicks and keeps them from reaching ancestors. Other
+ * keys still reach the caller's handler.
+ */
+export declare function disabledInteractionProps<T extends HTMLElement>(onKeyDown?: KeyboardEventHandler<T>): {
+    onClick: (event: MouseEvent<T>) => void;
+    onKeyDown: (event: KeyboardEvent<T>) => void;
+};
+//# sourceMappingURL=disabledInteraction.d.ts.map

package/dist/utils/disabledInteraction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"disabledInteraction.d.ts","sourceRoot":"","sources":["../../src/utils/disabledInteraction.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAC,aAAa,EAAE,oBAAoB,EAAE,UAAU,EAAC,MAAM,OAAO,CAAC;AAE3E;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CAAC,CAAC,SAAS,WAAW,EAC5D,SAAS,CAAC,EAAE,oBAAoB,CAAC,CAAC,CAAC,GAClC;IACD,OAAO,EAAE,CAAC,KAAK,EAAE,UAAU,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC;IACxC,SAAS,EAAE,CAAC,KAAK,EAAE,aAAa,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC;CAC9C,CAcA"}

package/dist/utils/disabledInteraction.js

@@ -0,0 +1,33 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file disabledInteraction.ts
+ * @input An optional caller keydown handler
+ * @output Event props that keep a focusable, aria-disabled control inert
+ * @position Shared by controls that replace native `disabled` with
+ *   `aria-disabled` under spec:AST-085 (FR1, FR2)
+ */
+
+/**
+ * Event props for a disabled control that stays focusable. Native `disabled`
+ * dispatched no click at all; without it, Enter and Space still synthesize a
+ * click that native listeners on the element (a wrapping Popover's trigger)
+ * receive. Cancelling those keys keeps the click from existing, and the click
+ * handler cancels pointer clicks and keeps them from reaching ancestors. Other
+ * keys still reach the caller's handler.
+ */
+export function disabledInteractionProps(onKeyDown) {
+  return {
+    onClick: event => {
+      event.preventDefault();
+      event.stopPropagation();
+    },
+    onKeyDown: event => {
+      if (event.key === 'Enter' || event.key === ' ') {
+        event.preventDefault();
+      } else {
+        onKeyDown?.(event);
+      }
+    }
+  };
+}

package/dist/utils/timeParser.d.ts

@@ -70,6 +70,10 @@ export declare function isTimeInRange(time: ISOTimeString, min?: ISOTimeString,
 export declare function clampTime(time: ISOTimeString, min?: ISOTimeString, max?: ISOTimeString, includeSeconds?: boolean): ISOTimeString;
 /**
  * Adjusts a time by adding/subtracting minutes.
+ *
+ * `deltaMinutes` is a whole number of minutes. A fractional delta leaves the
+ * time unchanged rather than returning a value that is no longer a time —
+ * `HH:MM` has no place for a fraction of a minute.
  */
 export declare function adjustTime(time: ISOTimeString, deltaMinutes: number, includeSeconds?: boolean): ISOTimeString;
 //# sourceMappingURL=timeParser.d.ts.map

package/dist/utils/timeParser.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"timeParser.d.ts","sourceRoot":"","sources":["../../src/utils/timeParser.ts"],"names":[],"mappings":"AAEA;;;;;;;GAOG;AAEH;;;GAGG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG;IAAC,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAA;CAAC,CAAC;AAEzE;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI,CAMvE;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CA6B5D;AAED;;GAEG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,UAAU,EAChB,cAAc,GAAE,OAAe,GAC9B,aAAa,CAUf;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,aAAa,GAAG,SAAS,EAC/B,cAAc,GAAE,OAAe,GAC9B,MAAM,CAqBR;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,aAAa,GAAG,SAAS,EAC/B,cAAc,GAAE,OAAe,GAC9B,MAAM,CAmBR;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,MAAM,EACb,cAAc,GAAE,OAAe,GAC9B,aAAa,GAAG,IAAI,CA6HtB;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CACzB,CAAC,EAAE,aAAa,GAAG,SAAS,EAC5B,CAAC,EAAE,aAAa,GAAG,SAAS,GAC3B,MAAM,CA4BR;AAED;;GAEG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,aAAa,EACnB,GAAG,CAAC,EAAE,aAAa,EACnB,GAAG,CAAC,EAAE,aAAa,GAClB,OAAO,CAQT;AAED;;GAEG;AACH,wBAAgB,SAAS,CACvB,IAAI,EAAE,aAAa,EACnB,GAAG,CAAC,EAAE,aAAa,EACnB,GAAG,CAAC,EAAE,aAAa,EACnB,cAAc,GAAE,OAAe,GAC9B,aAAa,CAoBf;AAED;;GAEG;AACH,wBAAgB,UAAU,CACxB,IAAI,EAAE,aAAa,EACnB,YAAY,EAAE,MAAM,EACpB,cAAc,GAAE,OAAe,GAC9B,aAAa,CAwBf"}
+{"version":3,"file":"timeParser.d.ts","sourceRoot":"","sources":["../../src/utils/timeParser.ts"],"names":[],"mappings":"AAEA;;;;;;;GAOG;AAEH;;;GAGG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG;IAAC,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAA;CAAC,CAAC;AAEzE;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI,CAMvE;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CA6B5D;AAED;;GAEG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,UAAU,EAChB,cAAc,GAAE,OAAe,GAC9B,aAAa,CAUf;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,aAAa,GAAG,SAAS,EAC/B,cAAc,GAAE,OAAe,GAC9B,MAAM,CAqBR;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,aAAa,GAAG,SAAS,EAC/B,cAAc,GAAE,OAAe,GAC9B,MAAM,CAmBR;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,MAAM,EACb,cAAc,GAAE,OAAe,GAC9B,aAAa,GAAG,IAAI,CA6HtB;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CACzB,CAAC,EAAE,aAAa,GAAG,SAAS,EAC5B,CAAC,EAAE,aAAa,GAAG,SAAS,GAC3B,MAAM,CA4BR;AAED;;GAEG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,aAAa,EACnB,GAAG,CAAC,EAAE,aAAa,EACnB,GAAG,CAAC,EAAE,aAAa,GAClB,OAAO,CAQT;AAED;;GAEG;AACH,wBAAgB,SAAS,CACvB,IAAI,EAAE,aAAa,EACnB,GAAG,CAAC,EAAE,aAAa,EACnB,GAAG,CAAC,EAAE,aAAa,EACnB,cAAc,GAAE,OAAe,GAC9B,aAAa,CAoBf;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CACxB,IAAI,EAAE,aAAa,EACnB,YAAY,EAAE,MAAM,EACpB,cAAc,GAAE,OAAe,GAC9B,aAAa,CA2Bf"}

package/dist/utils/timeParser.js

@@ -313,6 +313,10 @@ export function clampTime(time, min, max, includeSeconds = false) {
 
 /**
  * Adjusts a time by adding/subtracting minutes.
+ *
+ * `deltaMinutes` is a whole number of minutes. A fractional delta leaves the
+ * time unchanged rather than returning a value that is no longer a time —
+ * `HH:MM` has no place for a fraction of a minute.
  */
 export function adjustTime(time, deltaMinutes, includeSeconds = false) {
   const parsed = parseISOTime(time);
@@ -321,8 +325,11 @@ export function adjustTime(time, deltaMinutes, includeSeconds = false) {
   }
 
   // A non-finite delta would spin the wrap-around forever (-Infinity) or
-  // produce "NaN:NaN" (NaN) — return the input unchanged instead.
-  if (!Number.isFinite(deltaMinutes)) {
+  // produce "NaN:NaN" (NaN), and a fractional one is never rounded on the way
+  // out — formatISOTime pads "30.5" to two characters and leaves it, so the
+  // caller gets back a value that is no longer a time. Steps are whole
+  // minutes: return the input unchanged instead.
+  if (!Number.isInteger(deltaMinutes)) {
     return time;
   }
   let totalMinutes = parsed.hour * 60 + parsed.minute + deltaMinutes;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/core",
-  "version": "0.7.2",
+  "version": "0.7.3-canary.0bf23bd",
   "displayName": "Astryx Core",
   "description": "The component library. Accessible, themeable React components with built-in spacing, dark mode, and StyleX styling.",
   "author": "Meta Open Source",
@@ -792,6 +792,8 @@
     "react-dom": ">=19.0.0"
   },
   "devDependencies": {
+    "@astryxdesign/a11y-spec": "0.7.3-canary.0bf23bd",
+    "@astryxdesign/cli": "0.7.3-canary.0bf23bd",
     "@babel/cli": "^7.29.7",
     "@babel/core": "^7.29.7",
     "@babel/preset-react": "^7.29.7",
@@ -802,9 +804,7 @@
     "@testing-library/jest-dom": "^6.6.0",
     "@testing-library/react": "^16.3.2",
     "@types/babel__core": "^7.20.5",
-    "tailwindcss": "^4.3.2",
-    "@astryxdesign/a11y-spec": "0.0.0",
-    "@astryxdesign/cli": "0.7.2"
+    "tailwindcss": "^4.3.2"
   },
   "dependencies": {
     "intl-messageformat": "^11.2.9"

package/scripts/agent-doc-state.mjs

@@ -39,6 +39,7 @@ import * as path from 'node:path';
 export const AGENTS_MD = 'AGENTS.md';
 export const CLAUDE_MD = 'CLAUDE.md';
 export const CLAUDE_DIR_MD = '.claude/CLAUDE.md'; // cross-platform literal
+export const GEMINI_MD = 'GEMINI.md';
 export const CURSOR_RULES = '.cursorrules';
 export const HERMES_DOT_MD = '.hermes.md';
 export const HERMES_MD = 'HERMES.md';
@@ -51,15 +52,18 @@ export const LEGACY_MARKER_END = '<!-- XDS:END -->';
 
 /**
  * The canonical set of EVERY location an --agent preset (or the default) can
- * write the Astryx block. SINGLE SOURCE OF TRUTH: discovery, removal, and the
- * `isAstryxInitialized` predicate all derive from this list, so "where init
- * writes" and "where we look" can never drift. (Explicit --agent-docs-path
- * targets are user-chosen and not enumerable here.)
+ * write a managed Astryx block — the full block, or the one-line import of
+ * AGENTS.md that the default writes to GEMINI.md. SINGLE
+ * SOURCE OF TRUTH: discovery, removal, and the `isAstryxInitialized` predicate
+ * all derive from this list, so "where init writes" and "where we look" can
+ * never drift. (Explicit --agent-docs-path targets are user-chosen and not
+ * enumerable here.)
  */
 export const AGENT_DOC_PATHS = [
   AGENTS_MD, // Codex / ChatGPT / Muse / generic
   CLAUDE_MD, // Claude Code (root)
   CLAUDE_DIR_MD, // Claude Code (.claude/CLAUDE.md)
+  GEMINI_MD, // Gemini CLI
   CURSOR_RULES, // Cursor
   HERMES_DOT_MD, // Hermes
   HERMES_MD, // Hermes
@@ -74,7 +78,7 @@ export const INIT_MARKERS = [MARKER_START, LEGACY_MARKER_START];
 /**
  * Find all existing agent doc files in a directory, across EVERY location any
  * preset can write (see {@link AGENT_DOC_PATHS}: AGENTS.md, CLAUDE.md,
- * .claude/CLAUDE.md, .cursorrules, .hermes.md, HERMES.md).
+ * .claude/CLAUDE.md, GEMINI.md, .cursorrules, .hermes.md, HERMES.md).
  * @param {string} targetDir
  * @returns {string[]} Relative paths of existing agent doc files
  */
@@ -82,10 +86,33 @@ export function discoverAgentDocs(targetDir) {
   return AGENT_DOC_PATHS.filter(p => fs.existsSync(path.join(targetDir, p)));
 }
 
+/**
+ * Whether `content` holds an Astryx block. A managed block that only imports
+ * another file (the one-line `@./AGENTS.md` that init writes to GEMINI.md) does
+ * not count: it holds nothing once that file has lost its block. A malformed
+ * block still counts, so a half-written file reads as set up.
+ *
+ * @param {string} content
+ * @returns {boolean}
+ */
+export function holdsAstryxBlock(content) {
+  for (const marker of INIT_MARKERS) {
+    let at = content.indexOf(marker);
+    while (at !== -1) {
+      const from = at + marker.length;
+      const end = content.indexOf('<!--', from);
+      const inner = (end === -1 ? content.slice(from) : content.slice(from, end)).trim();
+      if (!/^@\S+$/.test(inner)) return true;
+      at = content.indexOf(marker, from);
+    }
+  }
+  return false;
+}
+
 /**
  * Single source of truth for "is Astryx set up in this project?" — true when any
- * agent-doc file already carries the Astryx marker, i.e. `init` / `agent-docs`
- * has run. Reused by the init & upgrade commands, the per-command setup nudge
+ * agent-doc file already holds an Astryx block, i.e. `init` / `agent-docs` has
+ * run. Reused by the init & upgrade commands, the per-command setup nudge
  * (enforcement layer 3), and the cli postinstall nudge (layer 2). Core's
  * postinstall (separate package, layer 1) mirrors the same marker contract.
  *
@@ -96,7 +123,7 @@ export function isAstryxInitialized(targetDir = process.cwd()) {
   for (const rel of discoverAgentDocs(targetDir)) {
     try {
       const content = fs.readFileSync(path.join(targetDir, rel), 'utf-8');
-      if (INIT_MARKERS.some(m => content.includes(m))) {
+      if (holdsAstryxBlock(content)) {
         return true;
       }
     } catch {

package/src/Banner/Banner.spec.md

@@ -42,29 +42,29 @@ separately targetable surface. The status and content targets remain unchanged.
 - Released default preserved: `no` — Banner no longer derives a live-region role from visual status
 - Compatibility class: breaking accessibility-semantic correction; visual output, DOM structure, props, theming targets, and interaction behavior are unchanged
 - Controlled/uncontrolled behavior: unchanged
-- Migration decision: announce async outcomes in their transition handler with `useAnnounce`; add an explicit `role="status"` only for a persistent semantic mirror, and reserve `role="alert"` for genuinely urgent interruption
+- Migration decision: announce async outcomes in their transition handler with `useAnnounce`; add an explicit `role="status"` only for a persistent semantic mirror, and reserve `role="alert"` for genuinely urgent interruption. Inside a mounted live container, `spec:AST-086` FR4 applies instead.
 
 Consumer migration instructions belong in consumer docs and release notes.
 
 ### DEP-0007 — Deprecate live-region roles derived from `status`
 
-| Field            | Value                                                                                                                                                                                                                                                                              |
-| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| id               | `DEP-0007`                                                                                                                                                                                                                                                                         |
-| cleanup          | `CLN-0015`                                                                                                                                                                                                                                                                         |
-| package          | `@astryxdesign/core`                                                                                                                                                                                                                                                               |
-| surface          | Default ARIA role of `Banner`: `role="alert"` for `warning` and `error`, `role="status"` for `info` and `success`, derived from `status` when the caller passes no `role`                                                                                                          |
-| old contract     | Visual `status` selects the live-region role of the Banner root                                                                                                                                                                                                                    |
-| replacement      | A caller that announces an async outcome calls `useAnnounce` from the transition that produced it. A caller whose Banner is a persistent semantic mirror passes `role="status"`; genuinely urgent content passes `role="alert"`. Both explicit roles already reach the Banner root |
-| direct authority | `component:Banner`. Owners: `cixzhang`, `imdreamrunner`                                                                                                                                                                                                                            |
-| warning          | Consumer docs and the release notes name `DEP-0007` and the explicit `role` that keeps the released semantics. No runtime warning (`spec:AST-017` FR29)                                                                                                                            |
-| migration        | Non-mechanical: a caller that announces an async outcome calls `useAnnounce` from the transition that produced it; a caller whose Banner is a persistent mirror or urgent content passes `role="status"` or `role="alert"`                                                         |
-| codemod          | None: whether a Banner needs an announcement, and when, depends on the transition that renders it, which only the caller knows; adding the released role everywhere would restore the coupling this cleanup removes                                                                |
-| downstream       | Maintained docs teach `useAnnounce` for async outcomes and explicit `role` for persistent mirrors                                                                                                                                                                                  |
-| transition       | no prior transition                                                                                                                                                                                                                                                                |
-| state            | `proposed`                                                                                                                                                                                                                                                                         |
-| open decision    | Banner FR and DEC entries that make `status` visual-only                                                                                                                                                                                                                           |
-| target plan      | `CLN-0015` in the next minor release                                                                                                                                                                                                                                               |
+| Field            | Value                                                                                                                                                                                                                                                                                                                                                    |
+| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| id               | `DEP-0007`                                                                                                                                                                                                                                                                                                                                               |
+| cleanup          | `CLN-0015`                                                                                                                                                                                                                                                                                                                                               |
+| package          | `@astryxdesign/core`                                                                                                                                                                                                                                                                                                                                     |
+| surface          | Default ARIA role of `Banner`: `role="alert"` for `warning` and `error`, `role="status"` for `info` and `success`, derived from `status` when the caller passes no `role`                                                                                                                                                                                |
+| old contract     | Visual `status` selects the live-region role of the Banner root                                                                                                                                                                                                                                                                                          |
+| replacement      | A caller that announces an async outcome calls `useAnnounce` from the transition that produced it. A caller whose Banner is a persistent semantic mirror passes `role="status"`; genuinely urgent content passes `role="alert"`. Both explicit roles already reach the Banner root. Inside a mounted live container, `spec:AST-086` FR4 applies instead. |
+| direct authority | `component:Banner`. Owners: `cixzhang`, `imdreamrunner`                                                                                                                                                                                                                                                                                                  |
+| warning          | Consumer docs and the release notes name `DEP-0007` and the explicit `role` that keeps the released semantics. No runtime warning (`spec:AST-017` FR29)                                                                                                                                                                                                  |
+| migration        | Non-mechanical: a caller that announces an async outcome calls `useAnnounce` from the transition that produced it; a caller whose Banner is a persistent mirror or urgent content passes `role="status"` or `role="alert"`. Inside a mounted live container, `spec:AST-086` FR4 applies instead.                                                         |
+| codemod          | None: whether a Banner needs an announcement, and when, depends on the transition that renders it, which only the caller knows; adding the released role everywhere would restore the coupling this cleanup removes                                                                                                                                      |
+| downstream       | Maintained docs teach `useAnnounce` for async outcomes and explicit `role` for persistent mirrors. Inside a mounted live container, `spec:AST-086` FR4 applies instead.                                                                                                                                                                                  |
+| transition       | no prior transition                                                                                                                                                                                                                                                                                                                                      |
+| state            | `proposed`                                                                                                                                                                                                                                                                                                                                               |
+| open decision    | Banner FR and DEC entries that make `status` visual-only                                                                                                                                                                                                                                                                                                 |
+| target plan      | `CLN-0015` in the next minor release                                                                                                                                                                                                                                                                                                                     |
 
 ### CLN-0015 — Banner renders no live-region role by default
 
@@ -105,16 +105,16 @@ prop vocabulary or extensibility rule changes.
 The requirements below describe the current implementation and its additive
 frame target contract.
 
-| ID  | Invariant                                                                                                                                                                                                                                                                                                            | Basis                                                  | Contract state           |
-| --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | ------------------------ |
-| FR1 | The current render places `banner` on the colored status surface, which is Banner's primary painted surface and reflects `container` and `status`.                                                                                                                                                                   | Current source, public docs, and tests                 | Current behavior         |
-| FR2 | The Banner frame receives the public ref, role, supported DOM props, `xstyle`, `className`, and `style`; it also paints the selected `boxShadow`.                                                                                                                                                                    | Current source and tests                               | Current behavior         |
-| FR3 | An elevated `card` frame also paints the whole-banner radius. A `section` frame remains square. A non-elevated frame does not receive the frame-radius style.                                                                                                                                                        | Current source and elevation tests                     | Current behavior         |
-| FR4 | Card shape is split across surface owners: the status surface owns all corners without visible content or the top corners with visible content; the content surface owns the bottom corners.                                                                                                                         | Current source                                         | Current behavior         |
-| FR5 | Theme-authored `borderRadius` on `banner` currently writes the private `--_banner-radius` variable on the Status surface only. CSS inheritance does not carry that value upward to the frame or sideways to the Content surface, so both keep their fallback radius.                                                 | Current compiler output and CSS inheritance            | Current reachability gap |
-| FR6 | The Banner frame exposes `banner-frame` and reflects `container` and `elevation`. The existing `banner` target remains on the Status surface rather than moving to the outermost DOM element.                                                                                                                        | Owner decision; current source and tests               | Current behavior         |
-| FR7 | `banner-frame` is additive. The existing `banner`, `banner-icon`, `banner-description`, and `banner-content` targets and their current axes remain unchanged.                                                                                                                                                        | Current target inventory; compatibility policy         | Current behavior         |
-| FR8 | `status` controls visual meaning only and MUST NOT derive `role`, `aria-live`, or an announcement. Standard DOM props MAY provide an explicit persistent role. Async outcomes MUST announce from the transition handler through `useAnnounce`; `role="alert"` is reserved for genuinely urgent interruptive content. | Accessibility Checklist §Announcements; owner decision | Current behavior         |
+| ID  | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | Basis                                                  | Contract state           |
+| --- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | ------------------------ |
+| FR1 | The current render places `banner` on the colored status surface, which is Banner's primary painted surface and reflects `container` and `status`.                                                                                                                                                                                                                                                                                                                            | Current source, public docs, and tests                 | Current behavior         |
+| FR2 | The Banner frame receives the public ref, role, supported DOM props, `xstyle`, `className`, and `style`; it also paints the selected `boxShadow`.                                                                                                                                                                                                                                                                                                                             | Current source and tests                               | Current behavior         |
+| FR3 | An elevated `card` frame also paints the whole-banner radius. A `section` frame remains square. A non-elevated frame does not receive the frame-radius style.                                                                                                                                                                                                                                                                                                                 | Current source and elevation tests                     | Current behavior         |
+| FR4 | Card shape is split across surface owners: the status surface owns all corners without visible content or the top corners with visible content; the content surface owns the bottom corners.                                                                                                                                                                                                                                                                                  | Current source                                         | Current behavior         |
+| FR5 | Theme-authored `borderRadius` on `banner` currently writes the private `--_banner-radius` variable on the Status surface only. CSS inheritance does not carry that value upward to the frame or sideways to the Content surface, so both keep their fallback radius.                                                                                                                                                                                                          | Current compiler output and CSS inheritance            | Current reachability gap |
+| FR6 | The Banner frame exposes `banner-frame` and reflects `container` and `elevation`. The existing `banner` target remains on the Status surface rather than moving to the outermost DOM element.                                                                                                                                                                                                                                                                                 | Owner decision; current source and tests               | Current behavior         |
+| FR7 | `banner-frame` is additive. The existing `banner`, `banner-icon`, `banner-description`, and `banner-content` targets and their current axes remain unchanged.                                                                                                                                                                                                                                                                                                                 | Current target inventory; compatibility policy         | Current behavior         |
+| FR8 | `status` controls visual meaning only and MUST NOT derive `role`, `aria-live`, or an announcement. Standard DOM props MAY provide an explicit persistent role, except on a Banner added inside a mounted live container (`spec:AST-086` FR4). Async outcomes MUST announce from the transition handler through `useAnnounce`, except inside a mounted live container, where `spec:AST-086` FR4 applies; `role="alert"` is reserved for genuinely urgent interruptive content. | Accessibility Checklist §Announcements; owner decision | Current behavior         |
 
 ### Allowed variation
 
@@ -154,11 +154,15 @@ runtime work.
 `status` communicates visual category through color and icon; it does not choose
 announcement urgency. Banner renders no live-region role by default. A caller may
 provide `role="status"` through the standard DOM surface when the visible banner
-is intentionally a persistent semantic mirror. Async outcomes use `useAnnounce`
+is intentionally a persistent semantic mirror, except on a Banner added inside a
+mounted live container. Async outcomes use `useAnnounce`
 from the transition handler, which writes into a previously mounted live region;
+inside a mounted live container, that container delivers them
+(`spec:AST-086` FR4);
 a Banner mounted together with its message is not a reliable announcement.
 `role="alert"` remains available as an explicit native role, but is reserved for
-genuinely urgent content that should interrupt current speech.
+genuinely urgent content that should interrupt current speech; it is not used on
+a Banner added inside a mounted live container.
 
 Dismissal focus handoff, disclosure controls, and accessible control names remain
 unchanged.
@@ -247,8 +251,9 @@ placement and would imply that the target must remain on the outermost element.
 Banner status selects color and icon only. It does not assign `role="status"` or
 `role="alert"`. Async outcomes announce through `useAnnounce` from the transition
 handler so the message reaches a persistent live region rather than one mounted
-with its content. An explicit native role remains available through BaseProps for
-a persistent semantic mirror or the rare genuinely urgent alert.
+with its content; inside a mounted live container, `spec:AST-086` FR4 applies. An explicit native role remains available through BaseProps for
+a persistent semantic mirror or the rare genuinely urgent alert, except on a
+Banner added inside a mounted live container.
 
 Rejected: deriving alert urgency from `warning` or `error`. Severity and urgency
 are independent, and a static error present on first paint is not an event that

package/src/BottomSheet/BottomSheet.spec.md

@@ -15,6 +15,7 @@ verified_by:
     packages/core/src/BottomSheet/BottomSheet.test.tsx,
     packages/core/src/BottomSheet/BottomSheetPanel.test.tsx,
     packages/core/src/BottomSheet/BottomSheetKeyboard.test.tsx,
+    packages/core/src/BottomSheet/__tests__/BottomSheetNativeModal.a11y.browser.spec.ts,
     packages/core/src/BottomSheet/__tests__/BottomSheetKeyboard.a11y.browser.spec.ts,
     apps/storybook/stories/BottomSheet.stories.tsx,
     scripts/check-knowledge.mjs,
@@ -93,14 +94,17 @@ Consumer migration instructions belong in consumer docs and release notes.
 - The Content area's container padding, published per
   `architecture:container-padding`.
 - Standalone sheet presentation, including its optional native-dialog Scrim.
+- The native dialog every sheet renders, standalone or switcher-managed
+  (`component:BottomSheetSwitcher` DEC-1's decided structure).
 
 **Does not own / non-goals**
 
 - Caller-provided content rendered inside the Content area.
 - A separate target for Content area, Handle, or Scrim; none exists on current
   `main`.
-- A shared switcher dialog or scrim — owned by BottomSheetSwitcher when the sheet
-  participates in that host.
+- The presentation lifecycle of its dialog and the flow's scrim ownership when
+  the sheet participates in a BottomSheetSwitcher — owned by BottomSheetSwitcher
+  (`component:BottomSheetSwitcher` DEC-1's decided structure).
 - Shared layer hosting or dismissal policy.
 
 ## Public concepts
@@ -128,8 +132,10 @@ in `BottomSheet.doc.mjs`.
 - A standalone modal sheet renders Sheet panel, Content area, Handle, and Scrim.
 - A standalone non-modal sheet renders Sheet panel, Content area, and Handle
   without a Scrim.
-- A switcher-managed sheet renders the same panel anatomy while
-  BottomSheetSwitcher owns the shared dialog and optional Scrim.
+- A switcher-managed sheet renders the same panel anatomy in its own dialog while
+  BottomSheetSwitcher coordinates that dialog's lifecycle and the flow's one Scrim
+  (`component:BottomSheetSwitcher` DEC-1's decided structure, not shipped
+  anatomy).
 
 ### Transformation and precedence order
 
@@ -184,7 +190,7 @@ a decision that they must remain unthemeable.
   },
   "Scrim": {
     "none": {
-      "reason": "reachability-gap: No BottomSheet public target reaches the native dialog backdrop or switcher-owned scrim."
+      "reason": "reachability-gap: No BottomSheet public target reaches the native dialog backdrop, standalone or switcher-coordinated."
     }
   }
 }
@@ -210,7 +216,8 @@ a decision that they must remain unthemeable.
 | ------------------- | -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------- | --------------------------------- |
 | FR1                 | `BottomSheet.test.tsx` render, content, Handle, and scrim behavior suites                          | Modal, non-modal, and switcher presentations                             | Removing a documented part fails existing content, structure, or dismissal assertions.                  | `audit:BottomSheet/anatomy`       |
 | FR2                 | Panel target assertion, source inspection, and theming target inventories                          | Sheet panel, Content area, Handle, and Scrim                             | Removing the panel target or documenting an unshipped child target fails evidence or inventory.         | `audit:BottomSheet/theming`       |
-| FR3, AR1–AR2        | `BottomSheetKeyboard.test.tsx`; `BottomSheetKeyboard.a11y.browser.spec.ts`; open Storybook stories | fitting/overflow, plain text, usable/unusable/dynamic descendants, focus | Missing/duplicate keyboard access, stale ownership, focus movement, or broken content-box layout fails. | `audit:BottomSheet/accessibility` |     | Layout evidence | `BottomSheetPanel.test.tsx` | Floating Handle and scrolling Content area | Reordering or merging the stable parts fails existing panel structure and style assertions. | `audit:BottomSheet/anatomy` |
+| FR3, AR1–AR2        | `BottomSheetKeyboard.test.tsx`; `BottomSheetKeyboard.a11y.browser.spec.ts`; open Storybook stories | fitting/overflow, plain text, usable/unusable/dynamic descendants, focus | Missing/duplicate keyboard access, stale ownership, focus movement, or broken content-box layout fails. | `audit:BottomSheet/accessibility` |
+| Layout evidence     | `BottomSheetPanel.test.tsx`                                                                        | Floating Handle and scrolling Content area                               | Reordering or merging the stable parts fails existing panel structure and style assertions.             | `audit:BottomSheet/anatomy`       |
 | FR4                 | `BottomSheetPanel.test.tsx` container padding tests; `derivedVarRegistry.test.ts`                  | default, `padding` prop, theme `padding`, lone padded Section child      | The published inset differs from the applied padding, or a lone padded Section changes geometry.        | `audit:BottomSheet/anatomy`       |
 | Theming anatomy map | `scripts/check-knowledge.mjs`                                                                      | Canonical anatomy and current target inventory                           | Missing, extra, prefixed, stale, or multiply assigned mappings fail repository validation.              | `audit:BottomSheet/theming`       |
 

package/src/BottomSheet/BottomSheet.test.tsx

@@ -498,6 +498,35 @@ describe('BottomSheet', () => {
     expect(dialog).toHaveStyle({'--_sheet-scrim-opacity': '1'});
   });
 
+  it('stays open when a file picker inside it is dismissed, and still closes on its own close request', () => {
+    // A file input fires a bubbling `cancel` at itself when its picker is
+    // dismissed. It reaches the <dialog> like a close request but is not one.
+    const onOpenChange = vi.fn();
+    render(
+      <BottomSheet
+        isOpen
+        purpose="form"
+        onOpenChange={onOpenChange}
+        label="Upload">
+        <input type="file" aria-label="Picture" />
+      </BottomSheet>,
+    );
+
+    const fromPicker = new Event('cancel', {bubbles: true, cancelable: true});
+    fireEvent(screen.getByLabelText('Picture'), fromPicker);
+
+    expect(onOpenChange).not.toHaveBeenCalled();
+    expect(fromPicker.defaultPrevented).toBe(false);
+
+    fireEvent(
+      screen.getByRole('dialog'),
+      new Event('cancel', {cancelable: true}),
+    );
+
+    expect(onOpenChange).toHaveBeenCalledTimes(1);
+    expect(onOpenChange).toHaveBeenCalledWith(false);
+  });
+
   it('keeps a standalone modal sheet presented through its exit animation', () => {
     render(<ExitHarness />);
     const dialog = screen.getByRole('dialog', {name: 'Filters'});

package/src/BottomSheet/BottomSheet.tsx

@@ -361,12 +361,16 @@ function StandaloneBottomSheet({
   });
 
   // The native `cancel` event is a close request the stack never saw a press
-  // for (Android back, the platform close watcher). Always preventDefault so
-  // the browser cannot close the controlled <dialog>, then answer with the
-  // stack's rules: only the top-most layer dismisses, and nothing dismisses
-  // during an IME composition.
+  // for (Android back, the platform close watcher). One that bubbles up from
+  // inside is not: a file input fires it when its picker is dismissed, so it is
+  // left alone. Otherwise always preventDefault so the browser cannot close the
+  // controlled <dialog>, then answer with the stack's rules: only the top-most
+  // layer dismisses, and nothing dismisses during an IME composition.
   const handleCancel = useCallback(
     (event: React.SyntheticEvent<HTMLDialogElement>) => {
+      if (event.target !== event.currentTarget) {
+        return;
+      }
       event.preventDefault();
       if (shouldDismissOnCloseRequest()) {
         dismissOnEscape();