@astryxdesign/core 0.7.0 → 0.7.1-canary.0365e23

package/dist/theme/syntax/defineSyntaxTheme.js

@@ -10,7 +10,7 @@
  *
  * @see https://github.com/facebook/astryx/issues/1148
  */
-import { syntaxTokenDefaults } from "./tokens.js";
+import { syntaxTokenDefaults, DIFF_SYNTAX_TOKEN_NAMES } from "./tokens.js";
 import { devWarn } from "../../utils/devWarning.js";
 
 // =============================================================================
@@ -19,14 +19,25 @@ import { devWarn } from "../../utils/devWarning.js";
 
 /** Human-readable syntax token name (without CSS custom property prefix). */
 
+/** The diff row slots a syntax theme MAY set; unset ones keep their defaults. */
+
 /**
  * Token value — either a single string or a [light, dark] tuple.
  * Tuples are converted to CSS light-dark() at theme creation time.
  */
 
-/** Token map for defineSyntaxTheme input — values can be strings or tuples. */
+/**
+ * Token map for defineSyntaxTheme input — values can be strings or tuples.
+ * The diff row slots are optional: a theme that sets none keeps the defaults
+ * (semantic success/error muted tints and the muted surface).
+ */
 
-/** Resolved token map — all values are CSS strings (tuples resolved to light-dark()). */
+/**
+ * Resolved token map — all values are CSS strings (tuples resolved to
+ * light-dark()). The diff row slots are optional here as in the input, so a
+ * map written before they existed still type-checks; an unset slot renders
+ * its default.
+ */
 
 /** Input to defineSyntaxTheme. */
 
@@ -43,6 +54,13 @@ function toCSSProperty(key) {
 
 /** All valid human-readable token keys, derived from the defaults. */
 export const ALL_SYNTAX_KEYS = Object.keys(syntaxTokenDefaults).map(k => k.replace(CSS_PREFIX, ''));
+const DIFF_KEYS = new Set(DIFF_SYNTAX_TOKEN_NAMES.map(name => name.replace(CSS_PREFIX, '')));
+
+/** The marker slots: unset in a theme, they follow that theme's punctuation. */
+const MARKER_KEYS = new Set(['added-marker', 'removed-marker']);
+
+/** The keys every syntax theme must set: everything but the diff rows. */
+export const REQUIRED_SYNTAX_KEYS = ALL_SYNTAX_KEYS.filter(key => !DIFF_KEYS.has(key));
 
 // =============================================================================
 // Helpers
@@ -96,15 +114,23 @@ export function resolveSyntaxTokenForMode(value, mode) {
  * });
  */
 export function defineSyntaxTheme(input) {
-  const missing = ALL_SYNTAX_KEYS.filter(key => !(key in input.tokens));
+  const missing = REQUIRED_SYNTAX_KEYS.filter(key => !(key in input.tokens));
   if (missing.length > 0) {
-    devWarn('defineSyntaxTheme', `"${input.name}": missing tokens: ${missing.join(', ')}. ` + `All 14 syntax tokens are required.`);
+    devWarn('defineSyntaxTheme', `"${input.name}": missing tokens: ${missing.join(', ')}. ` + `All ${REQUIRED_SYNTAX_KEYS.length} syntax colour tokens are required; ` + `the diff row slots (added, removed, diff-header, added-marker, removed-marker) are optional.`);
   }
 
-  // Resolve tuples to light-dark() CSS strings
+  // Resolve tuples to light-dark() CSS strings. An unset diff row paint keeps
+  // its default so every existing theme renders a readable diff unchanged; an
+  // unset marker slot takes this theme's own line-number colour (its
+  // punctuation token) rather than the page theme's green and red, and an
+  // unset header paint is none at all (the header row sits on this theme's
+  // own background with punctuation text), so number, glyph, and header
+  // text stay legible on this theme's background in every page mode — the
+  // glyph's shape carries the meaning where the colour does not.
   const resolved = {};
   for (const key of ALL_SYNTAX_KEYS) {
-    resolved[key] = resolveTokenValue(input.tokens[key]);
+    const value = input.tokens[key];
+    resolved[key] = value !== undefined ? resolveTokenValue(value) : MARKER_KEYS.has(key) ? 'var(--color-syntax-punctuation)' : key === 'diff-header' ? 'transparent' : syntaxTokenDefaults[toCSSProperty(key)];
   }
   return {
     name: input.name,
@@ -123,12 +149,15 @@ export function defineSyntaxTheme(input) {
 export function syntaxThemeStyle(theme) {
   const vars = {};
   for (const key of ALL_SYNTAX_KEYS) {
-    vars[toCSSProperty(key)] = theme.tokens[key];
+    // An unset diff slot is left to its default rather than written empty.
+    const value = theme.tokens[key];
+    if (value !== undefined) vars[toCSSProperty(key)] = value;
   }
   return vars;
 }
 
 /** Convert a syntax theme to CSS declarations (no selector wrapper). */
 export function syntaxThemeToCSS(theme) {
-  return ALL_SYNTAX_KEYS.map(key => toCSSProperty(key) + ': ' + theme.tokens[key] + ';').join('\n  ');
+  // An unset diff slot is left to its default rather than written `undefined`.
+  return ALL_SYNTAX_KEYS.filter(key => theme.tokens[key] !== undefined).map(key => toCSSProperty(key) + ': ' + theme.tokens[key] + ';').join('\n  ');
 }

package/dist/theme/syntax/index.d.ts

@@ -10,7 +10,7 @@
  */
 export { syntaxTokenDefaults } from './tokens';
 export type { SyntaxTokenName } from './tokens';
-export { defineSyntaxTheme, syntaxThemeStyle, syntaxThemeToCSS } from './defineSyntaxTheme';
+export { defineSyntaxTheme, syntaxThemeStyle, syntaxThemeToCSS, } from './defineSyntaxTheme';
 export type { SyntaxThemeDefinition, SyntaxThemeInput, SyntaxThemeTokenKey, SyntaxThemeTokenMap, SyntaxThemeTokenInput, SyntaxTokenValue, } from './defineSyntaxTheme';
 export { SyntaxTheme, useSyntaxTheme } from './SyntaxTheme';
 export type { UseSyntaxThemeReturn } from './SyntaxTheme';

package/dist/theme/syntax/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/theme/syntax/index.ts"],"names":[],"mappings":"AAEA;;;;;;;;;GASG;AAEH,OAAO,EAAC,mBAAmB,EAAC,MAAM,UAAU,CAAC;AAC7C,YAAY,EAAC,eAAe,EAAC,MAAM,UAAU,CAAC;AAE9C,OAAO,EAAC,iBAAiB,EAAE,gBAAgB,EAAE,gBAAgB,EAAC,MAAM,qBAAqB,CAAC;AAC1F,YAAY,EACV,qBAAqB,EACrB,gBAAgB,EAChB,mBAAmB,EACnB,mBAAmB,EACnB,qBAAqB,EACrB,gBAAgB,GACjB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAAC,WAAW,EAAE,cAAc,EAAC,MAAM,eAAe,CAAC;AAC1D,YAAY,EAAC,oBAAoB,EAAC,MAAM,eAAe,CAAC;AAGxD,OAAO,EACL,UAAU,EACV,OAAO,EACP,OAAO,EACP,IAAI,EACJ,UAAU,EACV,eAAe,EACf,UAAU,EACV,WAAW,EACX,cAAc,EACd,QAAQ,EACR,eAAe,EACf,eAAe,EACf,iBAAiB,EACjB,kBAAkB,EAClB,gBAAgB,GACjB,MAAM,WAAW,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/theme/syntax/index.ts"],"names":[],"mappings":"AAEA;;;;;;;;;GASG;AAEH,OAAO,EAAC,mBAAmB,EAAC,MAAM,UAAU,CAAC;AAC7C,YAAY,EAAC,eAAe,EAAC,MAAM,UAAU,CAAC;AAE9C,OAAO,EACL,iBAAiB,EACjB,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EACV,qBAAqB,EACrB,gBAAgB,EAChB,mBAAmB,EACnB,mBAAmB,EACnB,qBAAqB,EACrB,gBAAgB,GACjB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAAC,WAAW,EAAE,cAAc,EAAC,MAAM,eAAe,CAAC;AAC1D,YAAY,EAAC,oBAAoB,EAAC,MAAM,eAAe,CAAC;AAGxD,OAAO,EACL,UAAU,EACV,OAAO,EACP,OAAO,EACP,IAAI,EACJ,UAAU,EACV,eAAe,EACf,UAAU,EACV,WAAW,EACX,cAAc,EACd,QAAQ,EACR,eAAe,EACf,eAAe,EACf,iBAAiB,EACjB,kBAAkB,EAClB,gBAAgB,GACjB,MAAM,WAAW,CAAC"}

package/dist/theme/syntax/tokens.d.ts

@@ -11,8 +11,11 @@
  * colors automatically adapt to any theme's color system. Themes can also
  * set an explicit syntax theme via defineTheme({ syntax: dracula }).
  *
- * 14-token architecture validated against 11 community code themes.
- * All themes map cleanly to these 14 slots.
+ * 14 token colours and the code background, validated against 11 community
+ * code themes — all of them map cleanly to those slots — plus five diff row
+ * slots (added, removed, header paints; added and removed markers) that default
+ * to semantic tokens, so a syntax theme that does not set them keeps a
+ * readable diff.
  *
  * @see https://github.com/facebook/astryx/issues/1148
  */
@@ -31,6 +34,13 @@ export declare const syntaxTokenDefaults: {
     readonly '--color-syntax-property': "var(--color-text-cyan)";
     readonly '--color-syntax-punctuation': "var(--color-text-secondary)";
     readonly '--color-syntax-background': "var(--color-background-muted)";
+    readonly '--color-syntax-added': "color-mix(in srgb, var(--color-success-muted) 25%, transparent)";
+    readonly '--color-syntax-removed': "color-mix(in srgb, var(--color-error-muted) 25%, transparent)";
+    readonly '--color-syntax-diff-header': "var(--color-background-muted)";
+    readonly '--color-syntax-added-marker': "var(--color-text-green)";
+    readonly '--color-syntax-removed-marker': "var(--color-text-red)";
 };
 export type SyntaxTokenName = keyof typeof syntaxTokenDefaults;
+/** The five diff row slots: optional in a syntax theme, defaulted when unset. */
+export declare const DIFF_SYNTAX_TOKEN_NAMES: readonly ["--color-syntax-added", "--color-syntax-removed", "--color-syntax-diff-header", "--color-syntax-added-marker", "--color-syntax-removed-marker"];
 //# sourceMappingURL=tokens.d.ts.map

package/dist/theme/syntax/tokens.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tokens.d.ts","sourceRoot":"","sources":["../../../src/theme/syntax/tokens.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;GAiBG;AAEH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;CAgCtB,CAAC;AAEX,MAAM,MAAM,eAAe,GAAG,MAAM,OAAO,mBAAmB,CAAC"}
+{"version":3,"file":"tokens.d.ts","sourceRoot":"","sources":["../../../src/theme/syntax/tokens.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;CAkDtB,CAAC;AAEX,MAAM,MAAM,eAAe,GAAG,MAAM,OAAO,mBAAmB,CAAC;AAE/D,iFAAiF;AACjF,eAAO,MAAM,uBAAuB,2JAMe,CAAC"}

package/dist/theme/syntax/tokens.js

@@ -13,8 +13,11 @@
  * colors automatically adapt to any theme's color system. Themes can also
  * set an explicit syntax theme via defineTheme({ syntax: dracula }).
  *
- * 14-token architecture validated against 11 community code themes.
- * All themes map cleanly to these 14 slots.
+ * 14 token colours and the code background, validated against 11 community
+ * code themes — all of them map cleanly to those slots — plus five diff row
+ * slots (added, removed, header paints; added and removed markers) that default
+ * to semantic tokens, so a syntax theme that does not set them keeps a
+ * readable diff.
  *
  * @see https://github.com/facebook/astryx/issues/1148
  */
@@ -50,5 +53,23 @@ export const syntaxTokenDefaults = {
   // text — see #5386.
   '--color-syntax-punctuation': 'var(--color-text-secondary)',
   // background -> muted surface
-  '--color-syntax-background': 'var(--color-background-muted)'
-};
+  '--color-syntax-background': 'var(--color-background-muted)',
+  // Diff rows (CodeBlock isDiff): whole-row tints behind unchanged syntax
+  // colours. Added/removed derive from the semantic success/error muted
+  // tokens at 25% strength: at full strength the secondary-grey syntax
+  // tokens (operator, punctuation, comment) fall under 4.5:1 on the tints
+  // in light; at 25% every default token clears it on both schemes with
+  // margin while the tint still reads against the plain row. Header rows
+  // (@@, and ---/+++ before the first hunk) sit on the muted surface.
+  '--color-syntax-added': 'color-mix(in srgb, var(--color-success-muted) 25%, transparent)',
+  '--color-syntax-removed': 'color-mix(in srgb, var(--color-error-muted) 25%, transparent)',
+  '--color-syntax-diff-header': 'var(--color-background-muted)',
+  // The margin of a changed row — its line number and +/- glyph — in the
+  // default theme's tinted-text tokens, made for tinted surfaces; a defined
+  // syntax theme that leaves them unset follows its own punctuation colour
+  // (see defineSyntaxTheme). Code text keeps the syntax theme's colours.
+  '--color-syntax-added-marker': 'var(--color-text-green)',
+  '--color-syntax-removed-marker': 'var(--color-text-red)'
+};
+/** The five diff row slots: optional in a syntax theme, defaulted when unset. */
+export const DIFF_SYNTAX_TOKEN_NAMES = ['--color-syntax-added', '--color-syntax-removed', '--color-syntax-diff-header', '--color-syntax-added-marker', '--color-syntax-removed-marker'];

package/dist/utils/focusReturn.d.ts

@@ -1,11 +1,3 @@
-/**
- * @file focusReturn.ts
- * @input The document's current active element.
- * @output Whether focus is currently "detached" — on nothing in particular.
- * @position Utility; used by overlay triggers (e.g. DateInput, DateTimeInput)
- *   that return focus to their control when the overlay closes, but only when
- *   the dismiss did not already move focus somewhere the user chose.
- */
 /**
  * True when focus rests on nothing in particular — no active element, or the
  * document body / root element.
@@ -21,4 +13,16 @@
  * when the trigger should reclaim it.
  */
 export declare function isFocusDetached(doc?: Document): boolean;
+/**
+ * Move focus programmatically so its ring follows the last input
+ * (`architecture:interaction-modality` INV1). After pointer input the browser's
+ * focus option keeps the element from matching `:focus-visible`, which is the
+ * one way to reach an element the overlay does not render: the consumer's
+ * autofocus target, the control that opened a Dialog, or a menu trigger the
+ * caller renders. Pass `options` (for example `preventScroll`) as to `focus()`.
+ *
+ * Make sure modality tracking is active (`useInteractionModalityTracking()`)
+ * in the component that calls this.
+ */
+export declare function focusForLastInput(element: HTMLElement, options?: FocusOptions): void;
 //# sourceMappingURL=focusReturn.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"focusReturn.d.ts","sourceRoot":"","sources":["../../src/utils/focusReturn.ts"],"names":[],"mappings":"AAEA;;;;;;;GAOG;AAEH;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,GAAG,GAAE,QAAmB,GAAG,OAAO,CAKjE"}
+{"version":3,"file":"focusReturn.d.ts","sourceRoot":"","sources":["../../src/utils/focusReturn.ts"],"names":[],"mappings":"AAgBA;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,GAAG,GAAE,QAAmB,GAAG,OAAO,CAKjE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,WAAW,EACpB,OAAO,CAAC,EAAE,YAAY,GACrB,IAAI,CAwBN"}

package/dist/utils/focusReturn.js

@@ -2,13 +2,18 @@
 
 /**
  * @file focusReturn.ts
- * @input The document's current active element.
- * @output Whether focus is currently "detached" — on nothing in particular.
+ * @input The document's current active element and the shared interaction
+ *   modality.
+ * @output Whether focus is currently "detached" — on nothing in particular —
+ *   and a focus move whose ring follows the last input.
  * @position Utility; used by overlay triggers (e.g. DateInput, DateTimeInput)
  *   that return focus to their control when the overlay closes, but only when
- *   the dismiss did not already move focus somewhere the user chose.
+ *   the dismiss did not already move focus somewhere the user chose, and by
+ *   overlays (Dialog, DropdownMenu) that move focus programmatically.
  */
 
+import { getInteractionModality } from "./interactionModality.js";
+
 /**
  * True when focus rests on nothing in particular — no active element, or the
  * document body / root element.
@@ -26,4 +31,40 @@
 export function isFocusDetached(doc = document) {
   const active = doc.activeElement;
   return active == null || active === doc.body || active === doc.documentElement;
+}
+
+/**
+ * Move focus programmatically so its ring follows the last input
+ * (`architecture:interaction-modality` INV1). After pointer input the browser's
+ * focus option keeps the element from matching `:focus-visible`, which is the
+ * one way to reach an element the overlay does not render: the consumer's
+ * autofocus target, the control that opened a Dialog, or a menu trigger the
+ * caller renders. Pass `options` (for example `preventScroll`) as to `focus()`.
+ *
+ * Make sure modality tracking is active (`useInteractionModalityTracking()`)
+ * in the component that calls this.
+ */
+export function focusForLastInput(element, options) {
+  // A text-entry field paints its own focus treatment to show where typing
+  // goes, and an extra blur there can run validation or mark it touched.
+  const isTextEntry = element instanceof HTMLInputElement || element instanceof HTMLTextAreaElement || element instanceof HTMLSelectElement || element.isContentEditable;
+  if (isTextEntry || getInteractionModality() !== 'pointer') {
+    if (options === undefined) {
+      element.focus();
+    } else {
+      element.focus(options);
+    }
+    return;
+  }
+  // Focusing the element that already has focus does nothing, so a ring the
+  // browser already drew would stay. WebKit draws one when its own focus
+  // restoration (a dialog's close, a popover's hide) moves focus itself, so
+  // clear that focus first.
+  if (element.matches(':focus-visible')) {
+    element.blur();
+  }
+  element.focus({
+    ...options,
+    focusVisible: false
+  });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/core",
-  "version": "0.7.0",
+  "version": "0.7.1-canary.0365e23",
   "displayName": "Astryx Core",
   "description": "The component library. Accessible, themeable React components with built-in spacing, dark mode, and StyleX styling.",
   "author": "Meta Open Source",
@@ -787,6 +787,8 @@
     "react-dom": ">=19.0.0"
   },
   "devDependencies": {
+    "@astryxdesign/a11y-spec": "0.7.1-canary.0365e23",
+    "@astryxdesign/cli": "0.7.1-canary.0365e23",
     "@babel/cli": "^7.29.7",
     "@babel/core": "^7.29.7",
     "@babel/preset-react": "^7.29.7",
@@ -797,9 +799,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.0"
+    "tailwindcss": "^4.3.2"
   },
   "dependencies": {
     "intl-messageformat": "^11.2.9"

package/src/BottomSheet/BottomSheet.test.tsx

@@ -14,6 +14,7 @@ import {act, render, screen, fireEvent} from '@testing-library/react';
 import {createRef, useState} from 'react';
 import {BottomSheet} from './BottomSheet';
 import {BottomSheetSwitcher} from './BottomSheetSwitcher';
+import {__resetInteractionModalityForTest} from '../utils/interactionModality';
 
 // A sheet has no stops unless its host asks for them, so the tests that
 // exercise detents pass their own. These three — a 14% peek, a half-height
@@ -2351,6 +2352,119 @@ describe('BottomSheet', () => {
 
       expect(document.activeElement).toBe(finalFocusRef.current);
     });
+
+    // The returned focus shows the focus-visible ring only after keyboard
+    // input (`architecture:interaction-modality` INV1). A plain focus() leaves
+    // that to the browser, which rings it after a pointer close: WebKit after
+    // a tap, and Chromium when the sheet was opened from the keyboard.
+    describe('ring on the returned focus', () => {
+      beforeEach(() => {
+        __resetInteractionModalityForTest();
+      });
+
+      afterEach(() => {
+        vi.restoreAllMocks();
+      });
+
+      function openThenClose(closeWith: 'pointer' | 'keyboard') {
+        render(<Harness />);
+        const opener = screen.getByRole('button', {name: 'Open sheet'});
+        opener.focus();
+        fireEvent.click(opener);
+        const done = screen.getByRole('button', {name: 'Done'});
+        if (closeWith === 'pointer') {
+          fireEvent.pointerDown(done);
+        } else {
+          fireEvent.keyDown(done, {key: 'Enter'});
+        }
+        fireEvent.click(done);
+        return opener;
+      }
+
+      it('asks the browser for no ring after a pointer close', () => {
+        const opener = openThenClose('pointer');
+        const focus = vi.spyOn(opener, 'focus');
+        finishSheetExit();
+
+        expect(opener).toHaveFocus();
+        expect(focus.mock.calls).toEqual([[{focusVisible: false}]]);
+      });
+
+      it('leaves the ring to the browser after a keyboard close', () => {
+        const opener = openThenClose('keyboard');
+        const focus = vi.spyOn(opener, 'focus');
+        finishSheetExit();
+
+        expect(opener).toHaveFocus();
+        expect(focus.mock.calls).toEqual([[]]);
+      });
+
+      it('clears a ring the native close already drew before refocusing', () => {
+        const opener = openThenClose('pointer');
+        // The browser's own dialog close restores focus to the opener, with a
+        // ring, before the sheet moves focus, and focusing the focused element
+        // changes nothing.
+        HTMLDialogElement.prototype.close = vi.fn(function (
+          this: HTMLDialogElement,
+        ) {
+          this.removeAttribute('open');
+          opener.focus();
+        });
+        const matches = HTMLElement.prototype.matches;
+        vi.spyOn(HTMLElement.prototype, 'matches').mockImplementation(function (
+          this: HTMLElement,
+          selector: string,
+        ) {
+          return selector === ':focus-visible'
+            ? this === opener
+            : matches.call(this, selector);
+        });
+        const blur = vi.spyOn(opener, 'blur');
+        const focus = vi.spyOn(opener, 'focus');
+        finishSheetExit();
+
+        expect(blur).toHaveBeenCalledTimes(1);
+        expect(focus.mock.calls.at(-1)).toEqual([{focusVisible: false}]);
+        expect(blur.mock.invocationCallOrder[0]).toBeLessThan(
+          focus.mock.invocationCallOrder.at(-1) ?? 0,
+        );
+        expect(opener).toHaveFocus();
+      });
+
+      it('asks for no ring on an explicit final focus target too', () => {
+        const finalFocusRef = createRef<HTMLButtonElement>();
+        function ExplicitFocusHarness() {
+          const [isOpen, setIsOpen] = useState(true);
+          return (
+            <>
+              <button ref={finalFocusRef} type="button">
+                Adaptive trigger
+              </button>
+              <BottomSheet
+                isOpen={isOpen}
+                onOpenChange={setIsOpen}
+                finalFocusRef={finalFocusRef}
+                label="Filters">
+                <button type="button" onClick={() => setIsOpen(false)}>
+                  Done
+                </button>
+              </BottomSheet>
+            </>
+          );
+        }
+
+        render(<ExplicitFocusHarness />);
+        const done = screen.getByRole('button', {name: 'Done'});
+        fireEvent.pointerDown(done);
+        fireEvent.click(done);
+        const target = finalFocusRef.current!;
+        const focus = vi.spyOn(target, 'focus');
+        finishSheetExit();
+
+        expect(target).toHaveFocus();
+        expect(focus.mock.calls).toEqual([[{focusVisible: false}]]);
+      });
+    });
   });
 
   describe('initial focus', () => {

package/src/BottomSheet/BottomSheet.tsx

@@ -4,7 +4,7 @@
 
 /**
  * @file BottomSheet.tsx
- * @input Uses React, StyleX, core hooks, shared layer dismissal, named BottomSheetPanel, BottomSheetSwitcherContext
+ * @input Uses React, StyleX, core hooks, shared layer dismissal, the shared interaction modality, named BottomSheetPanel, BottomSheetSwitcherContext
  * @output Exports BottomSheet component and BottomSheetProps
  * @position Public BottomSheet router plus private standalone/switcher hosts
  *
@@ -46,6 +46,8 @@ import {colorVars, durationVars, easeVars} from '../theme/tokens.stylex';
 import {useDevWarning, useScrollLock} from '../hooks';
 import {LayerDepthProvider} from '../Layer/LayerDepthContext';
 import {useLayerDismissal} from '../Layer/useLayerDismissal';
+import {focusForLastInput} from '../utils/focusReturn';
+import {useInteractionModalityTracking} from '../utils/interactionModality';
 import {
   BottomSheetPanel,
   type BottomSheetPanelMotion,
@@ -320,12 +322,20 @@ function StandaloneBottomSheet({
         dialog.close();
       }
       setIsPresented(false);
-      (finalFocusRef?.current ?? triggerRef.current)?.focus();
+      // The returned focus shows the focus-visible ring only after keyboard
+      // input (`architecture:interaction-modality` INV1). The native close
+      // may already have restored focus to the target with a ring; the helper
+      // clears it first.
+      const returnTarget = finalFocusRef?.current ?? triggerRef.current;
+      if (returnTarget != null) {
+        focusForLastInput(returnTarget);
+      }
       triggerRef.current = null;
     },
     [finalFocusRef, isOpen],
   );
 
+  useInteractionModalityTracking();
   useScrollLock(shouldPresent && hasScrim);
   useDevWarning(
     'BottomSheet',

package/src/BottomSheet/__tests__/BottomSheetFocusReturn.a11y.browser.spec.ts

@@ -0,0 +1,96 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file BottomSheetFocusReturn.a11y.browser.spec.ts
+ * @input The `Core/DropdownMenu` action-sheet story with a trigger the caller
+ *   renders, in a built Storybook, and real Chromium/WebKit pointer and
+ *   keyboard input.
+ * @output Browser evidence that the focus a BottomSheet returns when it closes
+ *   follows the last input (docs/architecture/interaction-modality.md INV1):
+ *   no ring after a pointer close, the ring after a keyboard close.
+ * @position Cross-browser proof; jsdom only proves which focus call the sheet
+ *   makes. The menu's sheet returns focus through BottomSheet's
+ *   `finalFocusRef`, and a control the caller renders carries no style of its
+ *   own that would hide a ring, so the ring shown is the browser's answer.
+ *   Chromium rings it when a keyboard-opened sheet is closed by a pointer;
+ *   WebKit also rings it after a tap open and a tap close.
+ */
+
+import {expect, test, type Locator, type Page} from '@playwright/test';
+import {
+  DEFAULT_STORYBOOK_DIR,
+  serveStorybook,
+  type StaticServer,
+} from '@astryxdesign/a11y-spec/storybook';
+
+let storybook: StaticServer;
+test.beforeAll(async () => {
+  storybook = await serveStorybook(
+    process.env.ASTRYX_STORYBOOK_DIR ?? DEFAULT_STORYBOOK_DIR,
+  );
+});
+test.afterAll(async () => {
+  await storybook?.close();
+});
+
+async function mount(page: Page): Promise<Locator> {
+  await page.goto(
+    `${storybook.origin}/iframe.html?id=core-dropdownmenu--action-sheet-custom-trigger&viewMode=story`,
+  );
+  const trigger = page.getByRole('button', {
+    name: 'Project actions',
+    exact: true,
+  });
+  await expect(trigger).toBeVisible();
+  return trigger;
+}
+
+async function openFromKeyboard(page: Page, trigger: Locator): Promise<void> {
+  await trigger.focus();
+  await page.keyboard.press('Enter');
+  await expect(page.getByRole('dialog')).toBeVisible();
+}
+
+function row(page: Page): Locator {
+  return page.getByRole('dialog').getByRole('button', {name: /Edit project/});
+}
+
+async function expectReturnedFocus(
+  page: Page,
+  trigger: Locator,
+  ring: boolean,
+): Promise<void> {
+  await expect(page.getByRole('dialog')).toBeHidden();
+  await expect(trigger).toBeFocused();
+  expect(
+    await trigger.evaluate(element => element.matches(':focus-visible')),
+  ).toBe(ring);
+}
+
+test('a keyboard-opened sheet closed by a pointer pick returns focus without a ring', async ({
+  page,
+}) => {
+  const trigger = await mount(page);
+  await openFromKeyboard(page, trigger);
+  await row(page).click();
+  await expectReturnedFocus(page, trigger, false);
+});
+
+test('a pointer open and pointer pick return focus without a ring', async ({
+  page,
+}) => {
+  const trigger = await mount(page);
+  await trigger.click();
+  await expect(page.getByRole('dialog')).toBeVisible();
+  await row(page).click();
+  await expectReturnedFocus(page, trigger, false);
+});
+
+test('a keyboard-opened sheet closed by Escape keeps the ring', async ({
+  page,
+}) => {
+  const trigger = await mount(page);
+  await openFromKeyboard(page, trigger);
+  await page.keyboard.press('Escape');
+  await expectReturnedFocus(page, trigger, true);
+});

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

@@ -15,12 +15,11 @@
  * output—not an event wrapper, speculative internal structure, or a node
  * created only for layout plumbing."
  *
- * This is not observable in the unit lane and not observable to the probe-reach
- * gate either. jsdom resolves no cascade, so it cannot say which element paints.
- * The gate's reach check asks whether a target's override lands on the element
- * carrying the class, and it does — that element simply is not the one a reader
- * sees. Only a real engine can be asked the question that matters: does styling
- * the documented target change the pill?
+ * This is not observable in the unit lane: jsdom resolves no cascade, so it
+ * cannot say which element paints. An override can land on the element carrying
+ * the class while that element is not the one a reader sees. Only a real engine
+ * can be asked the question that matters: does styling the documented target
+ * change the pill?
  *
  * The pill is identified structurally, as the button's parent element, so every
  * measurement below is independent of where the class currently sits.

package/src/CodeBlock/CodeBlock.doc.mjs

@@ -56,6 +56,13 @@ export const docs = {
       type: 'number[]',
       description: '1-indexed line numbers to highlight.',
     },
+    {
+      name: 'isDiff',
+      type: 'boolean',
+      default: 'false',
+      description:
+        'Render the code as a unified diff over `language`: lines starting with + are added, - removed, @@ is a hunk header (a `--- `/`+++ ` file-header pair directly before one is a header too), anything else is context. The language label reads `diff` or `<language> diff`. The glyph sits in its own column and the rest of each line keeps syntax highlighting; copy returns the exact source. Markdown ```diff and ```diff-<lang> fences set this.',
+    },
     {
       name: 'hasCopyButton',
       type: 'boolean',