@astryxdesign/core 0.7.1-canary.b359d5c → 0.7.1-canary.bffff80

package/dist/Calendar/Calendar.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Calendar.d.ts","sourceRoot":"","sources":["../../src/Calendar/Calendar.tsx"],"names":[],"mappings":"AA4BA,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAkD5C,YAAY,EACV,aAAa,EACb,SAAS,EACT,aAAa,EACb,SAAS,GACV,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EACV,aAAa,EACb,SAAS,EACT,aAAa,EACb,SAAS,EACV,MAAM,oBAAoB,CAAC;AAK5B,+CAA+C;AAE/C,MAAM,WAAW,cAAc;IAC7B,wEAAwE;IACxE,UAAU,EAAE,CAAC,IAAI,EAAE,aAAa,KAAK,IAAI,CAAC;CAC3C;AAID,UAAU,iBAAkB,SAAQ,IAAI,CACtC,SAAS,CAAC,cAAc,CAAC,EACzB,UAAU,GAAG,cAAc,CAC5B;IACC,kDAAkD;IAClD,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAChC,qDAAqD;IACrD,SAAS,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IACtC,+CAA+C;IAC/C,cAAc,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC;IAEvB,4CAA4C;IAC5C,GAAG,CAAC,EAAE,aAAa,CAAC;IAEpB,4CAA4C;IAC5C,GAAG,CAAC,EAAE,aAAa,CAAC;IAEpB;;;OAGG;IACH,eAAe,CAAC,EAAE,aAAa,CAAC,CAAC,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,CAAC;IAEzD;;;;;;;OAOG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;;;;;;;OAQG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,aAAa,CAAC;IAE1B,yDAAyD;IACzD,iBAAiB,CAAC,EAAE,CAAC,SAAS,EAAE,aAAa,KAAK,IAAI,CAAC;IAEvD;;;OAGG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IAEzB;;;OAGG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IAEzB;;;OAGG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAE9B;;;;OAIG;IACH,YAAY,CAAC,EAAE,SAAS,GAAG,aAAa,CAAC;CAC1C;AAID,UAAU,mBAAoB,SAAQ,iBAAiB;IACrD,qBAAqB;IACrB,IAAI,CAAC,EAAE,QAAQ,CAAC;IAEhB,mFAAmF;IACnF,KAAK,CAAC,EAAE,aAAa,GAAG,IAAI,CAAC;IAE7B,0CAA0C;IAC1C,YAAY,CAAC,EAAE,aAAa,CAAC;IAE7B,qCAAqC;IACrC,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,aAAa,EAAE,WAAW,EAAE,IAAI,KAAK,IAAI,CAAC;CAC9D;AAED,UAAU,kBAAmB,SAAQ,iBAAiB;IACpD,qBAAqB;IACrB,IAAI,EAAE,OAAO,CAAC;IAEd,8DAA8D;IAC9D,KAAK,CAAC,EAAE,SAAS,GAAG,IAAI,CAAC;IAEzB,0CAA0C;IAC1C,YAAY,CAAC,EAAE,SAAS,CAAC;IAEzB,sCAAsC;IACtC,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,SAAS,KAAK,IAAI,CAAC;CACvC;AAED,MAAM,MAAM,aAAa,GAAG,mBAAmB,GAAG,kBAAkB,CAAC;AAMrE;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CAAC,EAAC,GAAG,EAAE,GAAG,KAAK,EAAC,EAAE,aAAa,+BAsXtD;yBAtXe,QAAQ"}
+{"version":3,"file":"Calendar.d.ts","sourceRoot":"","sources":["../../src/Calendar/Calendar.tsx"],"names":[],"mappings":"AA4BA,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAsD5C,YAAY,EACV,aAAa,EACb,SAAS,EACT,aAAa,EACb,SAAS,GACV,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EACV,aAAa,EACb,SAAS,EACT,aAAa,EACb,SAAS,EACV,MAAM,oBAAoB,CAAC;AAS5B,+CAA+C;AAC/C,MAAM,WAAW,cAAc;IAC7B,wEAAwE;IACxE,UAAU,EAAE,CAAC,IAAI,EAAE,aAAa,KAAK,IAAI,CAAC;CAC3C;AAID,UAAU,iBAAkB,SAAQ,IAAI,CACtC,SAAS,CAAC,cAAc,CAAC,EACzB,UAAU,GAAG,cAAc,CAC5B;IACC,kDAAkD;IAClD,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAChC,qDAAqD;IACrD,SAAS,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IACtC,+CAA+C;IAC/C,cAAc,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC;IAEvB,4CAA4C;IAC5C,GAAG,CAAC,EAAE,aAAa,CAAC;IAEpB,4CAA4C;IAC5C,GAAG,CAAC,EAAE,aAAa,CAAC;IAEpB;;;OAGG;IACH,eAAe,CAAC,EAAE,aAAa,CAAC,CAAC,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,CAAC;IAEzD;;;;;;;OAOG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;;;;;;;OAQG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,aAAa,CAAC;IAE1B,yDAAyD;IACzD,iBAAiB,CAAC,EAAE,CAAC,SAAS,EAAE,aAAa,KAAK,IAAI,CAAC;IAEvD;;;OAGG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IAEzB;;;OAGG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IAEzB;;;OAGG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAE9B;;;;OAIG;IACH,YAAY,CAAC,EAAE,SAAS,GAAG,aAAa,CAAC;CAC1C;AAID,UAAU,mBAAoB,SAAQ,iBAAiB;IACrD,qBAAqB;IACrB,IAAI,CAAC,EAAE,QAAQ,CAAC;IAEhB,mFAAmF;IACnF,KAAK,CAAC,EAAE,aAAa,GAAG,IAAI,CAAC;IAE7B,0CAA0C;IAC1C,YAAY,CAAC,EAAE,aAAa,CAAC;IAE7B,qCAAqC;IACrC,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,aAAa,EAAE,WAAW,EAAE,IAAI,KAAK,IAAI,CAAC;CAC9D;AAED,UAAU,kBAAmB,SAAQ,iBAAiB;IACpD,qBAAqB;IACrB,IAAI,EAAE,OAAO,CAAC;IAEd,8DAA8D;IAC9D,KAAK,CAAC,EAAE,SAAS,GAAG,IAAI,CAAC;IAEzB,0CAA0C;IAC1C,YAAY,CAAC,EAAE,SAAS,CAAC;IAEzB,sCAAsC;IACtC,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,SAAS,KAAK,IAAI,CAAC;CACvC;AAED,MAAM,MAAM,aAAa,GAAG,mBAAmB,GAAG,kBAAkB,CAAC;AAqBrE;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CAAC,EAAC,GAAG,EAAE,GAAG,KAAK,EAAC,EAAE,aAAa,+BAghBtD;yBAhhBe,QAAQ"}

package/dist/Calendar/Calendar.js

@@ -24,7 +24,7 @@ import { Icon } from "../Icon/index.js";
 import { useAnnounce, useGridFocus } from "../hooks/index.js";
 import { useCalendarDays, useCalendarConstraints } from "./hooks/index.js";
 import { calendarStyles, monthGridStyles, dayCellStyles, dayCellTheme } from "./styles.js";
-import { plainDateFromISO, plainDateToISO, plainDateToDate, plainDateToday, plainDateSetFirstOfMonth, plainDateAddMonths, plainDateAddDays, plainDateIsBefore, plainDateIsEqual, plainDateGetWeekNumber, plainDateFormat, DATE_FORMAT_WITH_WEEKDAY, DATE_FORMAT_MONTH_YEAR } from "../utils/plainDate.js";
+import { plainDateFromISO, plainDateToISO, plainDateToDate, plainDateToday, plainDateSetFirstOfMonth, plainDateAddMonths, plainDateAddDays, plainDateDiffDays, getDaysInMonth, plainDateIsAfter, plainDateIsBefore, plainDateIsEqual, plainDateGetWeekNumber, plainDateFormat, plainDateWeekFieldName, DATE_FORMAT_WITH_WEEKDAY, DATE_FORMAT_MONTH_YEAR } from "../utils/plainDate.js";
 import { mergeProps, composeEventHandlers, rtlStyles } from "../utils/index.js";
 import { focusOutlineProps } from "../utils/focusOutline.stylex.js";
 import { interactionOverlayStyles } from "../utils/interactionOverlay.stylex.js";
@@ -39,6 +39,9 @@ import { computeDayCellState, computeRangeRounding, computePreviewRounding, comp
 import { normalizeDayOfWeek } from "../utils/dateTypes.js";
 import { themeProps } from "../utils/themeProps.js";
 import { useLocale, useTranslator } from "../i18n/index.js";
+import { VisuallyHidden } from "../VisuallyHidden/index.js";
+
+/** How a month navigation moves the focused day: by its row offset in days, or by whole months. */
 
 /** Imperative handle for Calendar handleRef */
 
@@ -46,6 +49,22 @@ import { useLocale, useTranslator } from "../i18n/index.js";
 
 // ─── Mode-specific Props (discriminated union) ────────────────
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/** The first day of `month`'s month that `isDisabled` allows, or null. */
+function firstEnabledDayOfMonth(month, isDisabled) {
+  const days = getDaysInMonth(month.year, month.month);
+  for (let day = 1; day <= days; day += 1) {
+    const pd = {
+      year: month.year,
+      month: month.month,
+      day
+    };
+    if (!isDisabled(pd)) {
+      return pd;
+    }
+  }
+  return null;
+}
+
 // =============================================================================
 // Main Component
 // =============================================================================
@@ -157,6 +176,30 @@ export function Calendar({
     });
   }, [baseMonth, numberOfMonths]);
 
+  // A pending target is claimed by the grid that shows its month, or dropped
+  // by the next focus move that is not onto the target day: when a controlled
+  // owner refuses the month change, no grid shows the target's month, and a
+  // stale target would later steal focus (and Enter) when that month does
+  // appear. Only a grid showing the target's month receives it; any other
+  // focus change (an arrow to another day, the month header's buttons, or out
+  // of the calendar) drops it (see onBlur below).
+  const claimablePendingFocus = useMemo(() => {
+    if (pendingFocus == null) {
+      return null;
+    }
+    const target = plainDateFromISO(pendingFocus);
+    return visibleMonths.some(pd => pd.year === target.year && pd.month === target.month) ? pendingFocus : null;
+  }, [pendingFocus, visibleMonths]);
+  const handleRootBlur = useCallback(e => {
+    // Only the move onto the target day itself keeps the target: an arrow
+    // to any other day, a move to the header buttons, or focus leaving the
+    // calendar all drop it.
+    const movesToTarget = e.relatedTarget instanceof Element && e.relatedTarget.getAttribute('data-date') === pendingFocus;
+    if (pendingFocus != null && !movesToTarget) {
+      setPendingFocus(null);
+    }
+  }, [pendingFocus]);
+
   // Format month header
   const monthYearLabel = useMemo(() => {
     if (numberOfMonths === 1) {
@@ -185,6 +228,8 @@ export function Calendar({
   }, [monthYearLabel, announce]);
 
   // Determine if prev/next navigation is possible based on min/max
+  const minDateForKeys = useMemo(() => min ? plainDateFromISO(min) : null, [min]);
+  const maxDateForKeys = useMemo(() => max ? plainDateFromISO(max) : null, [max]);
   const canNavigatePrevious = useMemo(() => {
     if (!min) {
       return true;
@@ -204,23 +249,109 @@ export function Calendar({
   }, [max, baseMonth, numberOfMonths]);
 
   // Navigation handlers
-  const navigateMonth = useCallback((delta, focusedDate, offset) => {
-    const newPd = plainDateAddMonths(baseMonth, delta);
-    const newISO = plainDateToISO(newPd);
+  // The same constraint view the grids use, so a key can resolve its target
+  // before the month changes.
+  const rootRangeAnchor = useMemo(() => mode === 'range' && rangeSelectionStart ? plainDateFromISO(rangeSelectionStart) : null, [mode, rangeSelectionStart]);
+  const {
+    isDateDisabled: isRootDateDisabled
+  } = useCalendarConstraints({
+    min,
+    max,
+    dateConstraints,
+    maxRangeSpan,
+    minRangeSpan,
+    rangeAnchor: rootRangeAnchor
+  });
+  const navigateMonth = useCallback((delta, focusedDate, offset, unit = 'days') => {
+    const monthIndex = pd => pd.year * 12 + pd.month;
+    const firstShown = monthIndex(baseMonth);
+    const lastShown = firstShown + numberOfMonths - 1;
+
+    // The Previous/Next buttons move the month with no focused day.
+    if (!focusedDate) {
+      if (delta < 0 && !canNavigatePrevious || delta > 0 && !canNavigateNext) {
+        return;
+      }
+      const newPd = plainDateAddMonths(baseMonth, delta);
+      if (onFocusDateChange) {
+        onFocusDateChange(plainDateToISO(newPd));
+      } else {
+        setInternalFocusDate(newPd);
+      }
+      return;
+    }
 
-    // Calculate target focus date if a focused date was provided
-    if (focusedDate) {
-      const currentPd = plainDateFromISO(focusedDate);
-      const daysToMove = offset ?? 7;
-      const targetPd = plainDateAddDays(currentPd, delta * daysToMove);
-      setPendingFocus(plainDateToISO(targetPd));
+    // A key resolves its TARGET day first and decides by that, so a
+    // boundary blocks only out-of-range targets, never the month movement
+    // itself (ArrowUp from February 3 reaches January 27 at a January
+    // minimum), and a direction with no enabled day left changes nothing
+    // rather than dropping focus.
+    const currentPd = plainDateFromISO(focusedDate);
+    const inRange = pd => !(minDateForKeys && plainDateIsBefore(pd, minDateForKeys)) && !(maxDateForKeys && plainDateIsAfter(pd, maxDateForKeys));
+    let targetPd;
+    if (unit === 'months') {
+      // A page targets the same day of the month a month away (clamped to
+      // that month's length). Past `min`/`max` nothing moves; a month with
+      // no enabled day is no destination either, the same as an arrow with
+      // no enabled day in its direction; a target disabled by a constraint
+      // lands on that month's first enabled day instead.
+      const candidate = plainDateAddMonths(currentPd, delta);
+      if (!inRange(candidate)) {
+        return;
+      }
+      if (isRootDateDisabled(candidate)) {
+        const firstEnabled = firstEnabledDayOfMonth(candidate, isRootDateDisabled);
+        if (firstEnabled == null) {
+          return;
+        }
+        targetPd = firstEnabled;
+      } else {
+        targetPd = candidate;
+      }
+    } else {
+      // Walk the arrow's direction to the first enabled day, up to a year
+      // away; past `min`/`max` or with every day disabled, nothing moves.
+      const step = delta * (offset ?? 7);
+      let candidate = plainDateAddDays(currentPd, step);
+      let found = null;
+      while (Math.abs(plainDateDiffDays(currentPd, candidate)) <= 366) {
+        if (!inRange(candidate)) {
+          return;
+        }
+        if (!isRootDateDisabled(candidate)) {
+          found = candidate;
+          break;
+        }
+        candidate = plainDateAddDays(candidate, step);
+      }
+      if (found == null) {
+        return;
+      }
+      targetPd = found;
     }
+
+    // Focus moves to the target; the months change only when the target's
+    // month is not already shown. The view shifts the least it can in the
+    // key's direction, so the target month becomes the first (backwards)
+    // or last (forwards) month shown.
+    const resolved = targetPd;
+    const targetMonth = monthIndex(resolved);
+    setPendingFocus(plainDateToISO(resolved));
+    if (targetMonth >= firstShown && targetMonth <= lastShown) {
+      return;
+    }
+    const targetFirst = {
+      year: resolved.year,
+      month: resolved.month,
+      day: 1
+    };
+    const newPd = targetMonth < firstShown ? targetFirst : plainDateAddMonths(targetFirst, -(numberOfMonths - 1));
     if (onFocusDateChange) {
-      onFocusDateChange(newISO);
+      onFocusDateChange(plainDateToISO(newPd));
     } else {
       setInternalFocusDate(newPd);
     }
-  }, [baseMonth, onFocusDateChange]);
+  }, [baseMonth, canNavigateNext, canNavigatePrevious, isRootDateDisabled, maxDateForKeys, minDateForKeys, numberOfMonths, onFocusDateChange]);
 
   // Escape key handler to cancel range selection
   const handleCalendarKeyDown = useCallback(e => {
@@ -294,6 +425,7 @@ export function Calendar({
   return /*#__PURE__*/_jsxs("div", {
     ref: ref,
     ...rest,
+    onBlur: composeEventHandlers(rest.onBlur, handleRootBlur),
     ...mergeProps(themeProps('calendar', {
       mode
     }), stylex.props(calendarStyles.calendar, xstyle), className, style),
@@ -365,9 +497,9 @@ export function Calendar({
         onDayClick: handleDayClick,
         onDayHover: date => setHoveredDate(date ? plainDateToISO(date) : null),
         today: today,
-        onNavigatePrevious: (focusedDate, offset) => navigateMonth(-1, focusedDate, offset),
-        onNavigateNext: (focusedDate, offset) => navigateMonth(1, focusedDate, offset),
-        pendingFocus: pendingFocus,
+        onNavigatePrevious: (focusedDate, offset, unit) => navigateMonth(-1, focusedDate, offset, unit),
+        onNavigateNext: (focusedDate, offset, unit) => navigateMonth(1, focusedDate, offset, unit),
+        pendingFocus: claimablePendingFocus,
         onPendingFocusHandled: () => setPendingFocus(null)
       }, `${month.year}-${month.month}`))
     })]
@@ -501,13 +633,13 @@ function MonthGrid({
   const handlePageUp = useCallback(() => {
     const focusedDate = getFocusedDate();
     if (focusedDate) {
-      onNavigatePrevious?.(focusedDate, 7);
+      onNavigatePrevious?.(focusedDate, 1, 'months');
     }
   }, [getFocusedDate, onNavigatePrevious]);
   const handlePageDown = useCallback(() => {
     const focusedDate = getFocusedDate();
     if (focusedDate) {
-      onNavigateNext?.(focusedDate, 7);
+      onNavigateNext?.(focusedDate, 1, 'months');
     }
   }, [getFocusedDate, onNavigateNext]);
 
@@ -527,7 +659,12 @@ function MonthGrid({
   } = useGridFocus({
     columns: 7,
     cellSelector: '[role="gridcell"]',
-    isCellFocusable: cell => cell.querySelector('button:not([disabled])') !== null,
+    // A borrowed adjacent-month day is exposed aria-disabled (its click does
+    // nothing, but it can still take pointer focus) and may also be natively
+    // disabled by bounds or a constraint; the keyboard skips it either way
+    // and crosses into that month through the grid edge instead, so focus
+    // lands on the real day in the month now shown (FR5).
+    isCellFocusable: cell => cell.querySelector('button:not([disabled]):not([aria-disabled="true"])') !== null,
     getFocusTarget: cell => cell.querySelector('button'),
     hasRovingTabIndex: true,
     onNavigateBefore: handleNavigatePrevious,
@@ -536,27 +673,38 @@ function MonthGrid({
     onPageDown: handlePageDown
   });
 
-  // Handle pending focus after month navigation
+  // Handle pending focus after month navigation. Every mounted month grid
+  // sees the same pending date; only the grid showing that date's month acts,
+  // so a neighbouring grid's fallback never overrides the right target. The
+  // target is the real day in this month, never an outside-day copy; when it
+  // is disabled, the month's first enabled day takes focus instead.
   useEffect(() => {
     if (!pendingFocus || !gridRef.current) {
       return;
     }
-    const buttons = gridRef.current.querySelectorAll('button:not([disabled])');
     const targetPd = plainDateFromISO(pendingFocus);
+    if (targetPd.year !== year || targetPd.month !== month.month) {
+      return;
+    }
     const targetIso = plainDateToISO(targetPd);
-    let targetButton = null;
-    for (const button of buttons) {
-      if (button.getAttribute('data-date') === targetIso) {
-        targetButton = button;
-        break;
+    const buttons = Array.from(gridRef.current.querySelectorAll('button[data-date]:not([disabled]):not([aria-disabled="true"])'));
+
+    // The real target day, else the month's first enabled day, else — in a
+    // month with no enabled day — the first day button that can still take
+    // focus (a borrowed adjacent-month day), so focus stays in the grid
+    // rather than dropping to the page.
+    const targetButton = buttons.find(button => button.getAttribute('data-date') === targetIso) ?? buttons[0] ?? gridRef.current.querySelector('button[data-date]:not([disabled])') ?? null;
+    if (targetButton != null) {
+      // The target becomes this grid's one Tab stop before it takes focus,
+      // the way the hook's own arrow moves do (FR2): a programmatic focus
+      // alone would leave the stop on the day the grid mounted with.
+      for (const button of gridRef.current.querySelectorAll('button[data-date]')) {
+        button.tabIndex = button === targetButton ? 0 : -1;
       }
+      targetButton.focus();
     }
-    if (!targetButton && buttons.length > 0) {
-      targetButton = buttons[0];
-    }
-    targetButton?.focus();
     onPendingFocusHandled?.();
-  }, [pendingFocus, gridRef, onPendingFocusHandled]);
+  }, [pendingFocus, gridRef, month.month, onPendingFocusHandled, year]);
 
   // Parse selection
   let selectedDate = null;
@@ -613,8 +761,19 @@ function MonthGrid({
       children: [/*#__PURE__*/_jsxs("div", {
         role: "row",
         ...stylex.props(monthGridStyles.weekRow),
-        children: [hasWeekNumbers && /*#__PURE__*/_jsx("div", {
-          ...stylex.props(monthGridStyles.dayName, monthGridStyles.weekNumberHeader)
+        children: [hasWeekNumbers &&
+        /*#__PURE__*/
+        // The corner above the week-number column is a header cell like
+        // the weekday names beside it (APG grid: every cell in a row is a
+        // gridcell, columnheader or rowheader). Its name is the locale's
+        // own word for the week field, as visually hidden text so the
+        // column stays blank and the header is not empty to axe.
+        _jsx("div", {
+          role: "columnheader",
+          ...stylex.props(monthGridStyles.dayName, monthGridStyles.weekNumberHeader),
+          children: /*#__PURE__*/_jsx(VisuallyHidden, {
+            children: plainDateWeekFieldName(locale)
+          })
         }), dayNameHeaders.map(({
           dayOfWeek,
           name

package/dist/Chat/ChatMessage.d.ts

@@ -12,6 +12,7 @@
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/Chat/index.ts (exports)
  * - /apps/storybook/stories/Chat.stories.tsx
+ * - /apps/storybook/stories/ChatMessage.stories.tsx
  * - /packages/cli/assets/templates/blocks/components/ChatMessage/ (block examples)
  */
 import { type ReactNode } from 'react';
@@ -28,9 +29,17 @@ export interface ChatMessageProps extends BaseProps<HTMLElement> {
      * should span the full message column.
      */
     children: ReactNode;
+    /**
+     * Avatar content rendered beside a non-system message.
+     * `null`, booleans, and empty strings create no slot; any other content that
+     * renders nothing collapses its slot.
+     */
     avatar?: ReactNode;
     /**
      * Sender name rendered above the message body.
+     * `null`, booleans, and empty strings create no slot, and the message is
+     * labelled by the translated sender fallback; any other content that renders
+     * nothing collapses its slot and falls back to the same label.
      * Use when the first child is raw content (not a bubble).
      * If the first child is a ChatMessageBubble, put the name on the
      * bubble's `name` prop instead — it aligns with the bubble's padding.
@@ -38,6 +47,8 @@ export interface ChatMessageProps extends BaseProps<HTMLElement> {
     name?: ReactNode;
     /**
      * Metadata rendered below the message body.
+     * `null`, booleans, and empty strings create no slot; any other content that
+     * renders nothing collapses its slot.
      * Use when the last child is raw content (not a bubble).
      * If the last child is a ChatMessageBubble, put metadata on the
      * bubble's `metadata` prop instead — it aligns with the bubble's padding.

package/dist/Chat/ChatMessage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ChatMessage.d.ts","sourceRoot":"","sources":["../../src/Chat/ChatMessage.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAC,KAAK,SAAS,EAAiB,MAAM,OAAO,CAAC;AAQrD,OAAO,EAGL,KAAK,iBAAiB,EACtB,KAAK,WAAW,EACjB,MAAM,eAAe,CAAC;AAEvB,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAI5C,MAAM,WAAW,gBAAiB,SAAQ,SAAS,CAAC,WAAW,CAAC;IAC9D,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;IAC7B,MAAM,EAAE,iBAAiB,CAAC;IAC1B;;;;;;OAMG;IACH,QAAQ,EAAE,SAAS,CAAC;IACpB,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB;;;;;OAKG;IACH,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAC;IACrB,OAAO,CAAC,EAAE,WAAW,CAAC;CACvB;AAoFD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,WAAW,CAAC,EAC1B,MAAM,EACN,QAAQ,EACR,MAAM,EACN,IAAI,EACJ,QAAQ,EACR,OAAO,EAAE,WAAW,EACpB,MAAM,EACN,SAAS,EACT,KAAK,EAAE,SAAS,EAChB,aAAa,EAAE,MAAM,EACrB,GAAG,EACH,GAAG,IAAI,EACR,EAAE,gBAAgB,+BA2FlB;yBAxGe,WAAW"}
+{"version":3,"file":"ChatMessage.d.ts","sourceRoot":"","sources":["../../src/Chat/ChatMessage.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAC,KAAK,SAAS,EAAiB,MAAM,OAAO,CAAC;AAQrD,OAAO,EAGL,KAAK,iBAAiB,EACtB,KAAK,WAAW,EACjB,MAAM,eAAe,CAAC;AAEvB,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAI5C,MAAM,WAAW,gBAAiB,SAAQ,SAAS,CAAC,WAAW,CAAC;IAC9D,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;IAC7B,MAAM,EAAE,iBAAiB,CAAC;IAC1B;;;;;;OAMG;IACH,QAAQ,EAAE,SAAS,CAAC;IACpB;;;;OAIG;IACH,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB;;;;;;;;OAQG;IACH,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAC;IACrB,OAAO,CAAC,EAAE,WAAW,CAAC;CACvB;AA4FD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,WAAW,CAAC,EAC1B,MAAM,EACN,QAAQ,EACR,MAAM,EACN,IAAI,EACJ,QAAQ,EACR,OAAO,EAAE,WAAW,EACpB,MAAM,EACN,SAAS,EACT,KAAK,EAAE,SAAS,EAChB,aAAa,EAAE,MAAM,EACrB,GAAG,EACH,GAAG,IAAI,EACR,EAAE,gBAAgB,+BA+FlB;yBA5Ge,WAAW"}

package/dist/Chat/ChatMessage.js

@@ -16,6 +16,7 @@
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/Chat/index.ts (exports)
  * - /apps/storybook/stories/Chat.stories.tsx
+ * - /apps/storybook/stories/ChatMessage.stories.tsx
  * - /packages/cli/assets/templates/blocks/components/ChatMessage/ (block examples)
  */
 import { useMemo, useId } from 'react';
@@ -23,7 +24,7 @@ import * as stylex from '@stylexjs/stylex';
 import "../theme/tokens.stylex.js";
 import { colorVars, spacingVars, typeScaleVars, fontWeightVars } from "../theme/tokens.stylex.js";
 import { ChatMessageContext, useChatListContext } from "./ChatContext.js";
-import { mergeProps } from "../utils/index.js";
+import { isRenderable, mergeProps } from "../utils/index.js";
 import { themeProps } from "../utils/themeProps.js";
 import { useTranslator } from "../i18n/index.js";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
@@ -155,18 +156,23 @@ export function ChatMessage({
   const columnAlignment = sender === 'system' ? styles.contentColumnSystem : sender === 'user' ? styles.contentColumnUser : styles.contentColumnAssistant;
   const childrenAlignment = sender === 'system' ? styles.childrenSystem : sender === 'user' ? styles.childrenUser : styles.childrenAssistant;
   const isSystem = sender === 'system';
-  const hasAvatar = avatar != null && !isSystem;
-  const hasName = name != null && !isSystem;
+  const hasAvatar = !isSystem && isRenderable(avatar);
+  const hasName = !isSystem && isRenderable(name);
+  const hasMetadata = !isSystem && isRenderable(metadata);
   const nameId = useId();
   return /*#__PURE__*/_jsx(ChatMessageContext, {
     value: contextValue,
     children: /*#__PURE__*/_jsxs("article", {
       ...rest,
       ref: ref,
-      "data-testid": testId,
-      "aria-label": !hasName ? t('@astryx.chatMessage.messageFrom', {
+      "data-testid": testId
+      // The visible name labels the article. When it renders no text, the
+      // label reference resolves to nothing and the accessible name falls
+      // back to aria-label (accessible name computation 1.2, step 2B).
+      ,
+      "aria-label": t('@astryx.chatMessage.messageFrom', {
         sender
-      }) : undefined,
+      }),
       "aria-labelledby": hasName ? nameId : undefined,
       ...mergeProps(themeProps('chat-message', {
         sender,
@@ -174,7 +180,7 @@ export function ChatMessage({
       }), stylex.props(styles.root, rootAlignment, hasAvatar && rootGap, xstyle), className, styleProp),
       children: [hasAvatar && /*#__PURE__*/_jsx("div", {
         ...{
-          className: "x2lah0s x5du68j"
+          className: "xjl7jj x2lah0s x5du68j"
         },
         children: avatar
       }), /*#__PURE__*/_jsxs("div", {
@@ -182,13 +188,16 @@ export function ChatMessage({
         children: [hasName && /*#__PURE__*/_jsx("div", {
           id: nameId,
           ...{
-            className: "x141an7d x2mo6ok xv1l7n4 x1ltkj2j x14cgwvg"
+            className: "xjl7jj x141an7d x2mo6ok xv1l7n4 x1ltkj2j x14cgwvg"
           },
           children: name
         }), /*#__PURE__*/_jsx("div", {
           ...stylex.props(styles.childrenWrap, childrenAlignment, childrenGap),
           children: children
-        }), metadata != null && !isSystem && /*#__PURE__*/_jsx("div", {
+        }), hasMetadata && /*#__PURE__*/_jsx("div", {
+          ...{
+            className: "xjl7jj"
+          },
           children: metadata
         })]
       })]

package/dist/CommandPalette/CommandPalette.d.ts

@@ -1,6 +1,7 @@
 /**
  * @file CommandPalette.tsx
- * @input Uses React, Dialog, Layout, CommandPaletteContext, SearchSource, useCombobox, useAnnounce
+ * @input Uses React, Dialog, Layout, CommandPaletteContext, SearchSource,
+ *   useCombobox, useAnnounce, useAnnounceRenderedText
  * @output Exports CommandPalette root component and props
  * @position Core root component; dialog shell with searchSource-driven items
  *
@@ -42,7 +43,9 @@ export interface CommandPaletteProps<T extends SearchableItem = SearchableItem>
     footer?: ReactNode;
     /**
      * Per-item render function. Receives the item and whether it is currently selected.
-     * Auto-grouping by `auxiliaryData.group` is preserved.
+     * Return non-interactive presentation content; buttons and links cannot be
+     * nested inside the rendered option. Auto-grouping by `auxiliaryData.group`
+     * is preserved.
      * When omitted, renders each item's `label` text.
      */
     renderItem?: (item: T, isSelected: boolean) => ReactNode;
@@ -82,9 +85,10 @@ export interface CommandPaletteProps<T extends SearchableItem = SearchableItem>
  * Uses `searchSource` for all search logic — same interface as Typeahead.
  * For static lists, use `createStaticSource` from `@astryxdesign/core/Typeahead`.
  *
- * Keyboard navigation is handled by `useCombobox` from Selector,
- * ensuring consistent arrow key, Home/End, Enter, and Escape behavior
- * across all combobox-pattern components.
+ * Keyboard navigation is handled by `useCombobox` from Selector for arrows,
+ * PageUp/PageDown, and Enter. Home/End remain native caret keys. Modal Escape
+ * dismissal delegates to Dialog's shared layer stack so nested surfaces handle
+ * the first press.
  *
  * Input and footer are rendered by default — only pass them to replace the defaults.
  *

package/dist/CommandPalette/CommandPalette.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"CommandPalette.d.ts","sourceRoot":"","sources":["../../src/CommandPalette/CommandPalette.tsx"],"names":[],"mappings":"AAGA;;;;;;;;;GASG;AAEH,OAAO,EASL,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AAGf,OAAO,KAAK,EAAC,YAAY,EAAE,cAAc,EAAC,MAAM,cAAc,CAAC;AAU/D,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAI5C,MAAM,WAAW,mBAAmB,CAClC,CAAC,SAAS,cAAc,GAAG,cAAc,CACzC,SAAQ,IAAI,CAAC,SAAS,CAAC,iBAAiB,CAAC,EAAE,UAAU,CAAC;IACtD,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC;IACnC,2CAA2C;IAC3C,MAAM,EAAE,OAAO,CAAC;IAEhB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB,0DAA0D;IAC1D,YAAY,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;IAExC;;;;OAIG;IACH,YAAY,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC;IAE9B;;;OAGG;IACH,KAAK,CAAC,EAAE,SAAS,CAAC;IAElB;;;OAGG;IACH,MAAM,CAAC,EAAE,SAAS,CAAC;IAEnB;;;;OAIG;IACH,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,UAAU,EAAE,OAAO,KAAK,SAAS,CAAC;IAEzD;;;OAGG;IACH,eAAe,CAAC,EAAE,SAAS,CAAC;IAE5B;;;OAGG;IACH,kBAAkB,CAAC,EAAE,SAAS,CAAC;IAE/B,mDAAmD;IACnD,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf,8CAA8C;IAC9C,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAExC;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAExB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CAC7B;AAiID;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,cAAc,GAAG,cAAc,EAAE,EACxE,GAAG,EACH,MAAM,EACN,QAAQ,EACR,YAAY,EACZ,YAAY,EACZ,KAAK,EACL,MAAM,EACN,UAAU,EACV,eAAe,EAAE,wBAAwB,EACzC,kBAAkB,EAAE,2BAA2B,EAC/C,KAAK,EAAE,eAAe,EACtB,aAAa,EACb,KAAK,EAAE,cAAc,EACrB,KAAW,EACX,SAAe,EACf,GAAG,IAAI,EACR,EAAE,mBAAmB,CAAC,CAAC,CAAC,+BAsXxB;yBAvYe,cAAc"}
+{"version":3,"file":"CommandPalette.d.ts","sourceRoot":"","sources":["../../src/CommandPalette/CommandPalette.tsx"],"names":[],"mappings":"AAGA;;;;;;;;;;GAUG;AAEH,OAAO,EASL,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AAGf,OAAO,KAAK,EAAC,YAAY,EAAE,cAAc,EAAC,MAAM,cAAc,CAAC;AAU/D,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAK5C,MAAM,WAAW,mBAAmB,CAClC,CAAC,SAAS,cAAc,GAAG,cAAc,CACzC,SAAQ,IAAI,CAAC,SAAS,CAAC,iBAAiB,CAAC,EAAE,UAAU,CAAC;IACtD,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC;IACnC,2CAA2C;IAC3C,MAAM,EAAE,OAAO,CAAC;IAEhB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB,0DAA0D;IAC1D,YAAY,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;IAExC;;;;OAIG;IACH,YAAY,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC;IAE9B;;;OAGG;IACH,KAAK,CAAC,EAAE,SAAS,CAAC;IAElB;;;OAGG;IACH,MAAM,CAAC,EAAE,SAAS,CAAC;IAEnB;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,UAAU,EAAE,OAAO,KAAK,SAAS,CAAC;IAEzD;;;OAGG;IACH,eAAe,CAAC,EAAE,SAAS,CAAC;IAE5B;;;OAGG;IACH,kBAAkB,CAAC,EAAE,SAAS,CAAC;IAE/B,mDAAmD;IACnD,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf,8CAA8C;IAC9C,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAExC;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAExB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CAC7B;AAiID;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,cAAc,GAAG,cAAc,EAAE,EACxE,GAAG,EACH,MAAM,EACN,QAAQ,EACR,YAAY,EACZ,YAAY,EACZ,KAAK,EACL,MAAM,EACN,UAAU,EACV,eAAe,EAAE,wBAAwB,EACzC,kBAAkB,EAAE,2BAA2B,EAC/C,KAAK,EAAE,eAAe,EACtB,aAAa,EACb,KAAK,EAAE,cAAc,EACrB,KAAW,EACX,SAAe,EACf,GAAG,IAAI,EACR,EAAE,mBAAmB,CAAC,CAAC,CAAC,+BA2YxB;yBA5Ze,cAAc"}

package/dist/CommandPalette/CommandPalette.js

@@ -4,7 +4,8 @@
 
 /**
  * @file CommandPalette.tsx
- * @input Uses React, Dialog, Layout, CommandPaletteContext, SearchSource, useCombobox, useAnnounce
+ * @input Uses React, Dialog, Layout, CommandPaletteContext, SearchSource,
+ *   useCombobox, useAnnounce, useAnnounceRenderedText
  * @output Exports CommandPalette root component and props
  * @position Core root component; dialog shell with searchSource-driven items
  *
@@ -24,6 +25,7 @@ import { CommandPaletteInput } from "./CommandPaletteInput.js";
 import { CommandPaletteFooter } from "./CommandPaletteFooter.js";
 import { CommandPaletteEmpty } from "./CommandPaletteEmpty.js";
 import { useAnnounce } from "../hooks/useAnnounce.js";
+import { useAnnounceRenderedText } from "../hooks/useAnnounceRenderedText.js";
 import { useTranslator } from "../i18n/index.js";
 import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
 function getGroup(item) {
@@ -145,9 +147,10 @@ function ItemRenderer({
  * Uses `searchSource` for all search logic — same interface as Typeahead.
  * For static lists, use `createStaticSource` from `@astryxdesign/core/Typeahead`.
  *
- * Keyboard navigation is handled by `useCombobox` from Selector,
- * ensuring consistent arrow key, Home/End, Enter, and Escape behavior
- * across all combobox-pattern components.
+ * Keyboard navigation is handled by `useCombobox` from Selector for arrows,
+ * PageUp/PageDown, and Enter. Home/End remain native caret keys. Modal Escape
+ * dismissal delegates to Dialog's shared layer stack so nested surfaces handle
+ * the first press.
  *
  * Input and footer are rendered by default — only pass them to replace the defaults.
  *
@@ -200,6 +203,7 @@ export function CommandPalette({
   const [optimisticResults, setOptimisticResults] = useOptimistic(searchResults);
   const isBusy = isPending;
   const searchVersionRef = useRef(0);
+  const emptyStateRef = useRef(null);
 
   // Announce search status to screen readers through the shared polite live
   // region (comboboxes-7 announce path, mirroring Selector / BaseTypeahead).
@@ -267,6 +271,10 @@ export function CommandPalette({
   const runSearch = useCallback(query => {
     searchSource.cancel?.();
     const version = ++searchVersionRef.current;
+    // A highlight belongs to the query that created it. Clear it before any
+    // optimistic narrowing so aria-activedescendant never shifts to a
+    // different command at the same index while the next result set loads.
+    combobox.setHighlightedIndex(-1);
     startTransition(async () => {
       const isBootstrap = query === '';
 
@@ -293,18 +301,12 @@ export function CommandPalette({
 
         // Announce the outcome from the search commit (not a reactive
         // effect), matching Selector / BaseTypeahead: exactly one
-        // announcement per committed query, and the version check above
-        // already discards stale keystrokes. Bootstrap stays silent — the
-        // same role PowerSearch's mount guard plays — so opening the
-        // palette announces nothing; clearing the query only clears any
-        // lingering status text.
+        // announcement per committed non-empty query. Empty results are
+        // announced from their rendered content below so a caller-supplied
+        // ReactNode reaches assistive technology as written.
         if (isBootstrap) {
           announce('');
-        } else if (items.length === 0) {
-          announce(t('@astryx.commandPalette.noResultsFor', {
-            query
-          }));
-        } else {
+        } else if (items.length > 0) {
           announce(t('@astryx.commandPalette.resultCount', {
             count: items.length
           }));
@@ -346,13 +348,18 @@ export function CommandPalette({
     }
   }, [isOpen]);
 
-  // Wrap combobox's onKeyDown to intercept Escape (close palette) and
-  // Enter on highlight (select + close), since we're not using combobox's
-  // built-in open/close lifecycle.
+  // Wrap combobox's onKeyDown to preserve inline-preview Escape handling and
+  // select + close on Enter. Modal Escape stays unclaimed here so Dialog's
+  // shared dismissal stack can route it to the topmost surface.
   const handleKeyDown = useCallback(e => {
     if (e.key === 'Escape') {
-      e.preventDefault();
-      handleClose();
+      // Modal CommandPalette delegates Escape to Dialog's shared dismissal
+      // stack so a nested layer handles the first press. Inline previews do
+      // not join that stack, so preserve their local close behavior.
+      if (isInline) {
+        e.preventDefault();
+        handleClose();
+      }
       return;
     }
     if (e.key === 'Enter') {
@@ -366,12 +373,17 @@ export function CommandPalette({
       }
       return;
     }
+    // Home and End remain native caret-movement keys for this editable
+    // combobox. PageUp/PageDown provide first/last result navigation.
+    if (e.key === 'Home' || e.key === 'End') {
+      return;
+    }
     // Space should type in the input, not trigger selection
     if (e.key === ' ') {
       return;
     }
     combobox.onKeyDown(e);
-  }, [combobox, handleClose, selectableItems, selectItem]);
+  }, [combobox, handleClose, isInline, selectableItems, selectItem]);
 
   // Hover highlight is owned here by a single delegated handler on the list
   // container: it routes to useCombobox's hover-aware path, which moves the
@@ -427,13 +439,19 @@ export function CommandPalette({
   // the empty state is never unmounted and re-added mid-search (which flashed).
   const showEmptyBootstrap = search === '' && optimisticResults.length === 0;
   const showEmptySearch = search !== '' && optimisticResults.length === 0;
+  // Announce only once the search settles: while it is pending, optimistic
+  // narrowing can empty the list before the source answers, which would
+  // speak "No results" early or wrongly.
+  useAnnounceRenderedText(emptyStateRef, showEmptySearch && !isPending, search);
   let listContent;
   if (showEmptyBootstrap) {
     listContent = /*#__PURE__*/_jsx(CommandPaletteEmpty, {
+      ref: emptyStateRef,
       children: emptyBootstrapText
     });
   } else if (showEmptySearch) {
     listContent = /*#__PURE__*/_jsx(CommandPaletteEmpty, {
+      ref: emptyStateRef,
       children: emptySearchText
     });
   } else {

package/dist/CommandPalette/CommandPaletteEmpty.d.ts

@@ -12,13 +12,14 @@ export interface CommandPaletteEmptyProps extends BaseProps<HTMLDivElement> {
  * - `emptyBootstrapText`: no search term and bootstrap() returns nothing
  * - `emptySearchText`: a search query returned no results
  *
- * Can also be composed manually inside a custom render function.
+ * Can also be composed as a standalone empty result surface. Render actionable
+ * empty content outside listbox and option semantics.
  *
  * @example
  * ```
  * <CommandPalette
- *   emptyBootstrapText={<CommandPaletteEmpty>Start typing to search</CommandPaletteEmpty>}
- *   emptySearchText={<CommandPaletteEmpty>No results found</CommandPaletteEmpty>}
+ *   emptyBootstrapText="Start typing to search"
+ *   emptySearchText="No results found"
  *   searchSource={source}
  * />
  * ```