@astryxdesign/core 0.4.2 → 0.4.3-canary.5939961

package/dist/utils/characters.js

@@ -0,0 +1,83 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file characters.ts
+ * @input Strings that may contain characters made of several code units
+ *        (emoji, flags, joined emoji sequences, accented letters)
+ * @output Exports characterCount, firstCharacter, truncateCharacters —
+ *         replacements for .length / .charAt(0) / .slice(0, n) that measure
+ *         and cut user-visible strings the way a person reads them
+ * @position Shared utility; consumed by Avatar, TextArea, PowerSearch, Table
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/utils/characters.test.ts
+ * - /packages/core/src/utils/index.ts
+ */
+
+/**
+ * Reuse a single segmenter when the runtime supports Intl.Segmenter.
+ * `grapheme` is the Intl granularity name for a user-perceived character.
+ */
+const characterSegmenter = typeof Intl.Segmenter === 'function' ? new Intl.Segmenter(undefined, {
+  granularity: 'grapheme'
+}) : null;
+
+/**
+ * Split a string into user-perceived characters. The code-point fallback
+ * keeps surrogate pairs intact but may split joined emoji sequences and flag
+ * pairs on runtimes without Intl.Segmenter.
+ */
+function splitCharacters(str) {
+  if (characterSegmenter) {
+    return [...characterSegmenter.segment(str)].map(s => s.segment);
+  }
+  return [...str];
+}
+
+/**
+ * Number of characters in a string — the count a person would give, where one
+ * emoji, flag, or accented letter is one character. Replacement for `.length`
+ * on user-visible strings, which counts internal storage units instead.
+ */
+export function characterCount(str) {
+  if (str === '') {
+    return 0;
+  }
+  return splitCharacters(str).length;
+}
+
+/**
+ * The first character of a string, or '' when empty. Replacement for
+ * `.charAt(0)`, which can return half of an emoji. Reads only the first
+ * character, so cost does not scale with the length of the string.
+ */
+export function firstCharacter(str) {
+  if (characterSegmenter) {
+    const first = characterSegmenter.segment(str)[Symbol.iterator]().next();
+    return first.done ? '' : first.value.segment;
+  }
+  const codePoint = str.codePointAt(0);
+  return codePoint == null ? '' : String.fromCodePoint(codePoint);
+}
+
+/**
+ * Truncate to at most `max` characters, ellipsis included: strings within
+ * `max` characters pass through unchanged; longer strings are cut so the
+ * result — content plus `ellipsis` — is exactly `max` characters (or just the
+ * ellipsis, when `max` is smaller than the ellipsis itself). Replacement for
+ * `str.slice(0, n) + '…'`, which can cut an emoji in half.
+ *
+ * @example
+ * ```
+ * truncateCharacters('abcdefghij', 5) // 'abcd…'
+ * truncateCharacters('abcdefghij', 8, '...') // 'abcde...'
+ * ```
+ */
+export function truncateCharacters(str, max, ellipsis = '…') {
+  const characters = splitCharacters(str);
+  if (characters.length <= max) {
+    return str;
+  }
+  const keep = Math.max(max - characterCount(ellipsis), 0);
+  return characters.slice(0, keep).join('') + ellipsis;
+}

package/dist/utils/index.d.ts

@@ -13,6 +13,7 @@ export { parseISOTime, formatISOTime, formatDisplayTime12h, formatDisplayTime24h
 export type { ISOTimeString, ParsedTime } from './timeParser';
 export { parseStyleKey } from './parseStyleKey';
 export { getKey, type Key, type KeyFallback } from './getKey';
+export { characterCount, firstCharacter, truncateCharacters } from './characters';
 export { mergeProps } from './mergeProps';
 export { mergeRefs } from './mergeRefs';
 export { isFocusDetached } from './focusReturn';

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AAEH,YAAY,EAAC,SAAS,EAAC,MAAM,SAAS,CAAC;AAEvC,YAAY,EAAC,aAAa,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,EAAC,MAAM,aAAa,CAAC;AAEhF,OAAO,EACL,cAAc,EACd,SAAS,EACT,QAAQ,EACR,gBAAgB,GACjB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,cAAc,EACd,eAAe,EACf,iBAAiB,EACjB,cAAc,EACd,cAAc,EACd,kBAAkB,EAClB,kBAAkB,EAClB,gBAAgB,EAChB,kBAAkB,EAClB,oBAAoB,EACpB,iBAAiB,EACjB,gBAAgB,EAChB,gBAAgB,EAChB,YAAY,EACZ,YAAY,EACZ,kBAAkB,EAClB,wBAAwB,EACxB,uBAAuB,EACvB,8BAA8B,EAC9B,sBAAsB,EACtB,eAAe,EACf,gBAAgB,EAChB,wBAAwB,EACxB,8BAA8B,EAC9B,gBAAgB,EAChB,sBAAsB,EACtB,iBAAiB,EACjB,2BAA2B,EAC3B,0BAA0B,GAC3B,MAAM,aAAa,CAAC;AACrB,YAAY,EAAC,gBAAgB,EAAC,MAAM,aAAa,CAAC;AAElD,OAAO,EACL,YAAY,EACZ,aAAa,EACb,oBAAoB,EACpB,oBAAoB,EACpB,cAAc,EACd,WAAW,EACX,aAAa,EACb,SAAS,EACT,UAAU,EACV,mBAAmB,GACpB,MAAM,cAAc,CAAC;AACtB,YAAY,EAAC,aAAa,EAAE,UAAU,EAAC,MAAM,cAAc,CAAC;AAE5D,OAAO,EAAC,aAAa,EAAC,MAAM,iBAAiB,CAAC;AAC9C,OAAO,EAAC,MAAM,EAAE,KAAK,GAAG,EAAE,KAAK,WAAW,EAAC,MAAM,UAAU,CAAC;AAE5D,OAAO,EAAC,UAAU,EAAC,MAAM,cAAc,CAAC;AACxC,OAAO,EAAC,SAAS,EAAC,MAAM,aAAa,CAAC;AACtC,OAAO,EAAC,eAAe,EAAC,MAAM,eAAe,CAAC;AAC9C,OAAO,EAAC,oBAAoB,EAAC,MAAM,wBAAwB,CAAC;AAC5D,OAAO,EAAC,UAAU,EAAE,mBAAmB,EAAC,MAAM,cAAc,CAAC;AAC7D,YAAY,EACV,UAAU,EACV,UAAU,EACV,mBAAmB,EACnB,UAAU,GACX,MAAM,cAAc,CAAC;AACtB,OAAO,EAAC,UAAU,EAAE,YAAY,EAAC,MAAM,cAAc,CAAC;AACtD,YAAY,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAC,aAAa,EAAE,eAAe,EAAC,MAAM,wBAAwB,CAAC;AACtE,OAAO,EAAC,YAAY,EAAC,MAAM,gBAAgB,CAAC;AAC5C,OAAO,EAAC,YAAY,EAAC,MAAM,aAAa,CAAC;AACzC,YAAY,EAAC,SAAS,EAAE,mBAAmB,EAAC,MAAM,aAAa,CAAC;AAEhE,OAAO,EACL,QAAQ,EACR,QAAQ,EACR,UAAU,EACV,SAAS,EACT,WAAW,EACX,UAAU,GACX,MAAM,SAAS,CAAC;AACjB,YAAY,EAAC,IAAI,EAAC,MAAM,SAAS,CAAC;AAElC,OAAO,EAAC,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,gBAAgB,EAAC,MAAM,cAAc,CAAC;AAE3E,OAAO,EAAC,SAAS,EAAC,MAAM,aAAa,CAAC;AAItC,OAAO,EAAC,kBAAkB,EAAE,iBAAiB,EAAC,MAAM,uBAAuB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AAEH,YAAY,EAAC,SAAS,EAAC,MAAM,SAAS,CAAC;AAEvC,YAAY,EAAC,aAAa,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,EAAC,MAAM,aAAa,CAAC;AAEhF,OAAO,EACL,cAAc,EACd,SAAS,EACT,QAAQ,EACR,gBAAgB,GACjB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,cAAc,EACd,eAAe,EACf,iBAAiB,EACjB,cAAc,EACd,cAAc,EACd,kBAAkB,EAClB,kBAAkB,EAClB,gBAAgB,EAChB,kBAAkB,EAClB,oBAAoB,EACpB,iBAAiB,EACjB,gBAAgB,EAChB,gBAAgB,EAChB,YAAY,EACZ,YAAY,EACZ,kBAAkB,EAClB,wBAAwB,EACxB,uBAAuB,EACvB,8BAA8B,EAC9B,sBAAsB,EACtB,eAAe,EACf,gBAAgB,EAChB,wBAAwB,EACxB,8BAA8B,EAC9B,gBAAgB,EAChB,sBAAsB,EACtB,iBAAiB,EACjB,2BAA2B,EAC3B,0BAA0B,GAC3B,MAAM,aAAa,CAAC;AACrB,YAAY,EAAC,gBAAgB,EAAC,MAAM,aAAa,CAAC;AAElD,OAAO,EACL,YAAY,EACZ,aAAa,EACb,oBAAoB,EACpB,oBAAoB,EACpB,cAAc,EACd,WAAW,EACX,aAAa,EACb,SAAS,EACT,UAAU,EACV,mBAAmB,GACpB,MAAM,cAAc,CAAC;AACtB,YAAY,EAAC,aAAa,EAAE,UAAU,EAAC,MAAM,cAAc,CAAC;AAE5D,OAAO,EAAC,aAAa,EAAC,MAAM,iBAAiB,CAAC;AAC9C,OAAO,EAAC,MAAM,EAAE,KAAK,GAAG,EAAE,KAAK,WAAW,EAAC,MAAM,UAAU,CAAC;AAE5D,OAAO,EAAC,cAAc,EAAE,cAAc,EAAE,kBAAkB,EAAC,MAAM,cAAc,CAAC;AAEhF,OAAO,EAAC,UAAU,EAAC,MAAM,cAAc,CAAC;AACxC,OAAO,EAAC,SAAS,EAAC,MAAM,aAAa,CAAC;AACtC,OAAO,EAAC,eAAe,EAAC,MAAM,eAAe,CAAC;AAC9C,OAAO,EAAC,oBAAoB,EAAC,MAAM,wBAAwB,CAAC;AAC5D,OAAO,EAAC,UAAU,EAAE,mBAAmB,EAAC,MAAM,cAAc,CAAC;AAC7D,YAAY,EACV,UAAU,EACV,UAAU,EACV,mBAAmB,EACnB,UAAU,GACX,MAAM,cAAc,CAAC;AACtB,OAAO,EAAC,UAAU,EAAE,YAAY,EAAC,MAAM,cAAc,CAAC;AACtD,YAAY,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAC,aAAa,EAAE,eAAe,EAAC,MAAM,wBAAwB,CAAC;AACtE,OAAO,EAAC,YAAY,EAAC,MAAM,gBAAgB,CAAC;AAC5C,OAAO,EAAC,YAAY,EAAC,MAAM,aAAa,CAAC;AACzC,YAAY,EAAC,SAAS,EAAE,mBAAmB,EAAC,MAAM,aAAa,CAAC;AAEhE,OAAO,EACL,QAAQ,EACR,QAAQ,EACR,UAAU,EACV,SAAS,EACT,WAAW,EACX,UAAU,GACX,MAAM,SAAS,CAAC;AACjB,YAAY,EAAC,IAAI,EAAC,MAAM,SAAS,CAAC;AAElC,OAAO,EAAC,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,gBAAgB,EAAC,MAAM,cAAc,CAAC;AAE3E,OAAO,EAAC,SAAS,EAAC,MAAM,aAAa,CAAC;AAItC,OAAO,EAAC,kBAAkB,EAAE,iBAAiB,EAAC,MAAM,uBAAuB,CAAC"}

package/dist/utils/index.js

@@ -12,6 +12,7 @@ export { plainDateCreate, plainDateFromISO, plainDateToISO, plainDateToDate, pla
 export { parseISOTime, formatISOTime, formatDisplayTime12h, formatDisplayTime24h, parseTimeInput, compareTime, isTimeInRange, clampTime, adjustTime, createISOTimeString } from "./timeParser.js";
 export { parseStyleKey } from "./parseStyleKey.js";
 export { getKey } from "./getKey.js";
+export { characterCount, firstCharacter, truncateCharacters } from "./characters.js";
 export { mergeProps } from "./mergeProps.js";
 export { mergeRefs } from "./mergeRefs.js";
 export { isFocusDetached } from "./focusReturn.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/core",
-  "version": "0.4.2",
+  "version": "0.4.3-canary.5939961",
   "displayName": "Astryx Core",
   "description": "The component library. Accessible, themeable React components with built-in spacing, dark mode, and StyleX styling.",
   "author": "Meta Open Source",
@@ -654,6 +654,7 @@
     "react-dom": ">=19.0.0"
   },
   "devDependencies": {
+    "@astryxdesign/cli": "0.4.3-canary.5939961",
     "@babel/cli": "^8.0.4",
     "@babel/core": "^7.29.7",
     "@babel/preset-react": "^8.0.1",
@@ -662,8 +663,7 @@
     "@testing-library/dom": "^10.0.0",
     "@testing-library/jest-dom": "^6.6.0",
     "@testing-library/react": "^16.3.2",
-    "rimraf": "^6.0.1",
-    "@astryxdesign/cli": "0.4.2"
+    "rimraf": "^6.0.1"
   },
   "dependencies": {
     "intl-messageformat": "^11.2.9"

package/src/Avatar/Avatar.test.tsx

@@ -91,11 +91,16 @@ describe('Avatar', () => {
     expect(screen.getByTestId('avatar')).toHaveTextContent('😀A');
   });
 
-  it('preserves a complete grapheme when generating initials', () => {
+  it('preserves a complete character when generating initials', () => {
     render(<Avatar name="🇬🇧 Ada" data-testid="avatar" />);
     expect(screen.getByTestId('avatar')).toHaveTextContent('🇬🇧A');
   });
 
+  it('keeps a ZWJ family emoji intact when generating initials', () => {
+    render(<Avatar name="👨‍👩‍👧‍👦 Ada" data-testid="avatar" />);
+    expect(screen.getByTestId('avatar')).toHaveTextContent('👨‍👩‍👧‍👦A');
+  });
+
   it('retries a new src after a previous src failed to load', () => {
     const {rerender} = render(
       <Avatar name="Ada" src="https://example.com/broken.jpg" />,

package/src/Avatar/Avatar.tsx

@@ -31,6 +31,7 @@ import {AvatarSizeContext} from './AvatarSizeContext';
 import {useAvatarGroup} from '../AvatarGroup/AvatarGroupContext';
 import {mergeProps, mergeRefs} from '../utils';
 import {themeProps} from '../utils/themeProps';
+import {firstCharacter} from '../utils/characters';
 import {focusOutlineProps} from '../utils/focusOutline.stylex';
 import {useTooltip} from '../Tooltip/useTooltip';
 import {useDevWarning} from '../hooks/useDevWarning';
@@ -317,25 +318,6 @@ export interface AvatarProps extends BaseProps<HTMLDivElement> {
   onClick?: React.MouseEventHandler<HTMLElement>;
 }
 
-/**
- * Reuse a single segmenter when the runtime supports Intl.Segmenter.
- */
-const graphemeSegmenter =
-  typeof Intl.Segmenter === 'function'
-    ? new Intl.Segmenter(undefined, {granularity: 'grapheme'})
-    : null;
-
-/**
- * Return the first user-perceived character, with a code-point fallback.
- */
-function firstGrapheme(word: string): string {
-  if (graphemeSegmenter) {
-    return [...graphemeSegmenter.segment(word)][0]?.segment ?? '';
-  }
-
-  return [...word][0] ?? '';
-}
-
 /**
  * Generates initials from a name string.
  * Takes the first letter of the first two words.
@@ -351,10 +333,10 @@ function getInitials(name: string): string {
     return '';
   }
   if (words.length === 1) {
-    return firstGrapheme(words[0]).toUpperCase();
+    return firstCharacter(words[0]).toUpperCase();
   }
   return (
-    firstGrapheme(words[0]) + firstGrapheme(words[words.length - 1])
+    firstCharacter(words[0]) + firstCharacter(words[words.length - 1])
   ).toUpperCase();
 }
 

package/src/Banner/Banner.doc.mjs

@@ -17,11 +17,13 @@ export const docs = {
       {guidance: true, description: 'Keep titles short and scannable: "Payment failed" not "There was a problem processing your most recent payment."'},
       {guidance: false, description: 'Use Banner for short-lived messages that disappear on their own; use Toast instead.'},
       {guidance: false, description: 'Stack multiple banners with the same status; combine related messages into one banner.'},
+      {guidance: true, description: 'Error and warning banners render as role="alert"; info and success render as role="status". Mount an alert banner in response to an event rather than on first paint, so assistive tech has a change to report.'},
+      {guidance: false, description: 'Rely on the status color or icon alone to carry meaning; say which status it is in the title text, because the icon is decorative to a screen reader.'},
     ],
     anatomy: [
       {name: 'Icon', required: true, description: 'Automatically set based on the status (info, warning, error, success).'},
-      {name: 'Title', required: false, description: 'The main message. Required if no description is provided.'},
-      {name: 'Description', required: false, description: 'Additional detail below the title. Required if no title is provided.'},
+      {name: 'Title', required: true, description: 'The main message. Always required.'},
+      {name: 'Description', required: false, description: 'Additional detail below the title.'},
       {name: 'Action button', required: false, description: 'A button for the user to act on the message, like "Review" or "Retry".'},
       {name: 'Dismiss button', required: false, description: 'Lets the user close the banner. Enabled by setting isDismissable.'},
       {name: 'Collapsible content', required: false, description: 'Extra detail that expands below the banner header, like a list of errors.'},
@@ -123,7 +125,7 @@ export const docs = {
       {className: 'astryx-banner-content', visualProps: ['container', 'status']},
     ],
     vars: [
-      {name: '--_banner-radius', description: 'Border radius (card container only)', default: 'var(--radius-container)', private: true},
+      {name: '--_banner-radius', description: 'Border radius of the card container (header, content area and the elevated root silhouette)', default: 'var(--radius-container)', private: true},
     ],
     derived: [
       {property: 'borderRadius', vars: ['--_banner-radius']},
@@ -148,8 +150,8 @@ export const docsZh = {
     ],
     anatomy: [
       {name: 'Icon', required: true, description: 'Automatically set based on the status (info, warning, error, success).'},
-      {name: 'Title', required: false, description: 'The main message. Required if no description is provided.'},
-      {name: 'Description', required: false, description: 'Additional detail below the title. Required if no title is provided.'},
+      {name: 'Title', required: true, description: 'The main message. Always required.'},
+      {name: 'Description', required: false, description: 'Additional detail below the title.'},
       {name: 'Action button', required: false, description: 'A button for the user to act on the message, like "Review" or "Retry".'},
       {name: 'Dismiss button', required: false, description: 'Lets the user close the banner. Enabled by setting isDismissable.'},
       {name: 'Collapsible content', required: false, description: 'Extra detail that expands below the banner header, like a list of errors.'},
@@ -198,7 +200,7 @@ export const docsZh = {
       },
     ],
     vars: [
-      {name: '--_banner-radius', description: 'Border radius (card container only)', default: 'var(--radius-container)', private: true},
+      {name: '--_banner-radius', description: 'Border radius of the card container (header, content area and the elevated root silhouette)', default: 'var(--radius-container)', private: true},
     ],
     derived: [
       {property: 'borderRadius', vars: ['--_banner-radius']},
@@ -222,7 +224,7 @@ export const docsDense = {
     ],
     anatomy: [
       {name: 'Icon', required: true, description: 'Set automatically from status.'},
-      {name: 'Title', required: false, description: 'Main message text.'},
+      {name: 'Title', required: true, description: 'Main message text.'},
       {name: 'Description', required: false, description: 'Detail below title.'},
       {name: 'Action button', required: false, description: 'CTA like Review or Retry.'},
       {name: 'Dismiss button', required: false, description: 'Close button via isDismissable.'},

package/src/Banner/Banner.test.tsx

@@ -455,4 +455,72 @@ describe('Banner', () => {
       );
     });
   });
+
+  describe('dismiss focus handoff', () => {
+    it('returns focus to where it came from instead of dropping it to body', async () => {
+      const user = userEvent.setup();
+      render(
+        <>
+          <button type="button">Before</button>
+          <Banner status="info" title="Heads up" isDismissable />
+        </>,
+      );
+      const before = screen.getByRole('button', {name: 'Before'});
+      before.focus();
+
+      await user.tab();
+      expect(screen.getByRole('button', {name: 'Dismiss'})).toHaveFocus();
+
+      await user.keyboard('{Enter}');
+
+      expect(screen.queryByRole('status')).not.toBeInTheDocument();
+      expect(before).toHaveFocus();
+      expect(document.activeElement).not.toBe(document.body);
+    });
+
+    it('leaves focus alone when it never entered the banner', async () => {
+      const user = userEvent.setup();
+      render(
+        <>
+          <button type="button">Elsewhere</button>
+          <Banner status="info" title="Heads up" isDismissable />
+        </>,
+      );
+      await user.click(screen.getByRole('button', {name: 'Dismiss'}));
+      expect(screen.queryByRole('status')).not.toBeInTheDocument();
+    });
+  });
+
+  describe('empty slots', () => {
+    it('does not show the expand affordance for children that render nothing', () => {
+      render(
+        <Banner status="info" title="Heads up">
+          {false}
+        </Banner>,
+      );
+      expect(
+        screen.queryByRole('button', {name: 'Expand'}),
+      ).not.toBeInTheDocument();
+    });
+
+    it('still shows the expand affordance for real children', () => {
+      render(
+        <Banner status="info" title="Heads up">
+          <p>Detail</p>
+        </Banner>,
+      );
+      expect(
+        screen.getByRole('button', {name: 'Expand'}),
+      ).toBeInTheDocument();
+    });
+
+    it('renders no description node for a description that renders nothing', () => {
+      const {container} = render(
+        <Banner status="info" title="Heads up" description="" />,
+      );
+      const header = container.firstElementChild!.firstElementChild!;
+      // icon wrapper + text column, and the text column holds the title alone
+      expect(header.children[1].children).toHaveLength(1);
+    });
+  });
 });

package/src/Banner/Banner.tsx

@@ -4,7 +4,7 @@
 
 /**
  * @file Banner.tsx
- * @input Uses React useState, Button, Icon (with registry string names), StyleX
+ * @input Uses React useState/useRef/useId, Button, Icon (with registry string names), StyleX
  * @output Exports Banner component, BannerProps, BannerStatus, BannerContainer types
  * @position Core implementation; consumed by index.ts, tested by Banner.test.tsx
  *
@@ -19,6 +19,10 @@
  * - Each visual area owns its own border-radius (no overflow:clip on the container)
  * - When children are provided, a collapse/expand toggle button appears in the end area
  *
+ * A status added through `BannerStatusMap` augmentation has no entry in the
+ * status lookups, so it renders with no status fill, no default glyph and the
+ * polite `role="status"` rather than losing its ARIA role entirely.
+ *
  * Title and description render as <div> (not <p>): they accept arbitrary
  * ReactNode content, and <p> cannot legally contain block-level children
  * (the HTML parser reparents them, desyncing SSR markup from the hydrated
@@ -34,12 +38,12 @@
  * - /packages/cli/assets/templates/blocks/components/Banner/ (showcase blocks)
  */
 
-import {useId, useState, type ReactNode} from 'react';
+import {useId, useRef, useState, type ReactNode} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import type {BaseProps} from '../BaseProps';
 import {Button} from '../Button';
 import {Icon} from '../Icon';
-import type {IconName} from '../Icon';
+import type {IconName, IconColor} from '../Icon';
 import {
   colorVars,
   spacingVars,
@@ -51,7 +55,7 @@ import {
   easeVars,
   shadowVars,
 } from '../theme/tokens.stylex';
-import {mergeProps} from '../utils';
+import {composeEventHandlers, isRenderable, mergeProps} from '../utils';
 import type {Elevation} from '../utils/types';
 import {edgeCompSlot} from '../Layout/edgeCompensation.stylex';
 import {themeProps} from '../utils/themeProps';
@@ -147,37 +151,38 @@ export interface BannerProps extends BaseProps<HTMLDivElement> {
 }
 
 // =============================================================================
-// Status → Icon mapping
+// Status lookups
 // =============================================================================
 
-const defaultIconNames: Record<BannerStatus, IconName> = {
+// `BannerStatus` is `keyof BannerStatusMap`, and index.ts documents augmenting
+// that interface to add a status. Every lookup below is therefore partial: an
+// augmented status the library has never heard of falls through to the base
+// treatment (no status fill, no glyph, the polite role) instead of resolving to
+// `undefined` and dropping the ARIA role along with it.
+
+const defaultIconNames: Partial<Record<BannerStatus, IconName>> = {
   info: 'info',
   warning: 'warning',
   error: 'error',
   success: 'success',
 };
 
-// =============================================================================
-// Status → ARIA role mapping
-// =============================================================================
-
-const statusRole: Record<BannerStatus, 'alert' | 'status'> = {
+const statusRole: Partial<Record<BannerStatus, 'alert' | 'status'>> = {
   info: 'status',
   warning: 'alert',
   error: 'alert',
   success: 'status',
 };
 
-// =============================================================================
-// Status → Icon color mapping
-// =============================================================================
+/** An unknown status is not urgent by definition, so it announces politely. */
+const FALLBACK_ROLE = 'status';
 
-const statusIconColor = {
+const statusIconColor: Partial<Record<BannerStatus, IconColor>> = {
   info: 'accent',
   warning: 'warning',
   error: 'error',
   success: 'success',
-} as const;
+};
 
 // =============================================================================
 // Styles
@@ -193,7 +198,7 @@ const styles = stylex.create({
   // When elevated, a card-container banner rounds its root so the shadow
   // follows the same silhouette as the header/content border-radius.
   rootElevatedCard: {
-    borderRadius: radiusVars['--radius-container'],
+    borderRadius: `var(--_banner-radius, ${radiusVars['--radius-container']})`,
   },
   // Header area — colored status background with icon, title, description, actions
   // This is the primary theme target ('banner')
@@ -206,11 +211,11 @@ const styles = stylex.create({
   },
   // Border-radius for card container: all corners when standalone, top-only when content is visible
   headerCardStandalone: {
-    borderRadius: radiusVars['--radius-container'],
+    borderRadius: `var(--_banner-radius, ${radiusVars['--radius-container']})`,
   },
   headerCardWithContent: {
-    borderStartStartRadius: radiusVars['--radius-container'],
-    borderStartEndRadius: radiusVars['--radius-container'],
+    borderStartStartRadius: `var(--_banner-radius, ${radiusVars['--radius-container']})`,
+    borderStartEndRadius: `var(--_banner-radius, ${radiusVars['--radius-container']})`,
     borderEndStartRadius: 0,
     borderEndEndRadius: 0,
   },
@@ -233,6 +238,10 @@ const styles = stylex.create({
     fontWeight: fontWeightVars['--font-weight-semibold'],
     lineHeight: typeScaleVars['--text-label-leading'],
     color: colorVars['--color-text-primary'],
+    // A single unbroken token (a URL, an ID, a German compound) otherwise sets
+    // the flex item's min-content width and pushes the page into horizontal
+    // scrolling at 320px, which is a WCAG 1.4.10 reflow failure.
+    overflowWrap: 'anywhere',
   },
   description: {
     margin: 0,
@@ -241,6 +250,7 @@ const styles = stylex.create({
     fontWeight: fontWeightVars['--font-weight-normal'],
     lineHeight: typeScaleVars['--text-supporting-leading'],
     color: colorVars['--color-text-secondary'],
+    overflowWrap: 'anywhere',
   },
   iconWrapper: {
     display: 'flex',
@@ -262,17 +272,17 @@ const styles = stylex.create({
     paddingInline: spacingVars['--spacing-4'],
     borderInlineStartWidth: borderVars['--border-width'],
     borderInlineEndWidth: borderVars['--border-width'],
-    borderBottomWidth: borderVars['--border-width'],
+    borderBlockEndWidth: borderVars['--border-width'],
     borderInlineStartStyle: 'solid',
     borderInlineEndStyle: 'solid',
-    borderBottomStyle: 'solid',
+    borderBlockEndStyle: 'solid',
     borderInlineStartColor: colorVars['--color-border'],
     borderInlineEndColor: colorVars['--color-border'],
-    borderBottomColor: colorVars['--color-border'],
+    borderBlockEndColor: colorVars['--color-border'],
   },
   contentAreaCard: {
-    borderEndStartRadius: radiusVars['--radius-container'],
-    borderEndEndRadius: radiusVars['--radius-container'],
+    borderEndStartRadius: `var(--_banner-radius, ${radiusVars['--radius-container']})`,
+    borderEndEndRadius: `var(--_banner-radius, ${radiusVars['--radius-container']})`,
   },
   // Applied to the chevron <Icon> itself (via `xstyle`) rather than a wrapper,
   // so the element that rotates is the element a theme targets.
@@ -304,6 +314,17 @@ const statusStyles = stylex.create({
   },
 });
 
+/**
+ * Narrows an augmented `BannerStatus` to one the style map actually carries,
+ * so an unknown status renders with no status fill rather than crashing the
+ * lookup. StyleX style maps cannot be declared `Partial`, hence the guard.
+ */
+function hasStatusStyle(
+  status: BannerStatus,
+): status is BannerStatus & keyof typeof statusStyles {
+  return Object.prototype.hasOwnProperty.call(statusStyles, status);
+}
+
 // Resting elevation for the banner. Applied to the root so the shadow wraps
 // the whole banner (header + optional content). 'none' is the default and
 // leaves the layout-only root untouched. For the `card` container the root is
@@ -381,28 +402,63 @@ export function Banner({
   className,
   style,
   ref,
+  onFocusCapture,
+  onPointerDownCapture,
   ...rest
 }: BannerProps) {
   const t = useTranslator();
   const [isDismissed, setIsDismissed] = useState(false);
   const [isExpanded, setIsExpanded] = useState(defaultIsExpanded);
+  // The element focus came from before it entered the banner. Dismissing
+  // unmounts the whole banner, dismiss button included, so without a handoff
+  // the browser drops focus to <body> and a keyboard user loses their place.
+  // ToastViewport makes the same handoff when a focused toast is dismissed.
+  const focusOriginRef = useRef<HTMLElement | null>(null);
   // Links the expand/collapse toggle to the content region it shows/hides so
   // assistive tech can move from the button to its controlled content
   // (disclosure pattern). The region is conditionally rendered, so aria-controls
   // below is set only while it's mounted to avoid a dangling reference.
   const contentId = useId();
   const defaultIconName = defaultIconNames[status];
-  const role = statusRole[status];
+  const role = statusRole[status] ?? FALLBACK_ROLE;
   const iconColor = statusIconColor[status];
-  const hasChildren = children != null;
+  const hasChildren = isRenderable(children);
 
   if (isDismissed) {
     return null;
   }
 
+  // `focusin` reports the element focus came *from* as relatedTarget; on
+  // pointerdown focus has not moved yet, so document.activeElement is it.
+  const rememberFocusOrigin = (candidate: EventTarget | null, root: Node) => {
+    if (
+      candidate instanceof HTMLElement &&
+      candidate !== document.body &&
+      !root.contains(candidate)
+    ) {
+      focusOriginRef.current = candidate;
+    }
+  };
+
+  const handleFocusCapture = (event: React.FocusEvent<HTMLDivElement>) => {
+    rememberFocusOrigin(event.relatedTarget, event.currentTarget);
+  };
+
+  const handlePointerDownCapture = (
+    event: React.PointerEvent<HTMLDivElement>,
+  ) => {
+    rememberFocusOrigin(document.activeElement, event.currentTarget);
+  };
+
   const handleDismiss = () => {
+    const origin = focusOriginRef.current;
     setIsDismissed(true);
     onDismiss?.();
+    // Move focus before React removes the subtree, so the browser never has a
+    // frame where the focused node is gone.
+    if (origin?.isConnected) {
+      origin.focus();
+    }
   };
 
   const handleToggleExpand = () => {
@@ -410,11 +466,11 @@ export function Banner({
   };
 
   // Show the end area if there are actions, dismiss, or a collapsible toggle
-  const showEndArea = endContent != null || isDismissable || hasChildren;
+  const showEndArea = isRenderable(endContent) || isDismissable || hasChildren;
   // Center items vertically when there's only a title (no description)
   // and the banner has action buttons
-  const hasActions = endContent != null || isDismissable;
-  const isSingleLine = description == null && hasActions;
+  const hasActions = isRenderable(endContent) || isDismissable;
+  const isSingleLine = !isRenderable(description) && hasActions;
 
   const showContent = hasChildren && isExpanded;
   const isCard = container === 'card';
@@ -423,6 +479,11 @@ export function Banner({
     <div
       ref={ref}
       role={role}
+      onFocusCapture={composeEventHandlers(onFocusCapture, handleFocusCapture)}
+      onPointerDownCapture={composeEventHandlers(
+        onPointerDownCapture,
+        handlePointerDownCapture,
+      )}
       {...mergeProps(
         stylex.props(
           styles.root,
@@ -441,7 +502,7 @@ export function Banner({
           stylex.props(
             styles.header,
             isSingleLine && styles.headerCentered,
-            statusStyles[status],
+            hasStatusStyle(status) && statusStyles[status],
             isCard &&
               (showContent
                 ? styles.headerCardWithContent
@@ -454,16 +515,16 @@ export function Banner({
             overrides reach it via inheritance). The wrapper itself stays
             layout-only. */}
         <div
-          {...(icon != null
+          {...(isRenderable(icon)
             ? mergeProps(
                 themeProps('banner-icon', {status}),
                 stylex.props(styles.iconWrapper),
               )
             : stylex.props(styles.iconWrapper))}
           aria-hidden="true">
-          {icon != null ? (
+          {isRenderable(icon) ? (
             icon
-          ) : (
+          ) : defaultIconName != null ? (
             // Applied to the status <Icon> itself rather than the wrapper, so
             // the element that paints the glyph is the element a theme
             // targets — a 'banner-icon' 'status:X' color override beats the
@@ -474,11 +535,11 @@ export function Banner({
               color={iconColor}
               {...themeProps('banner-icon', {status})}
             />
-          )}
+          ) : null}
         </div>
         <div {...stylex.props(styles.headerContent)}>
           <div {...stylex.props(styles.title)}>{title}</div>
-          {description != null && (
+          {isRenderable(description) && (
             <div {...stylex.props(styles.description)}>{description}</div>
           )}
         </div>