@12-apps/ui 6.29.1 → 6.30.1

package/dist/types/copy/feedback.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"feedback.d.ts","sourceRoot":"","sources":["../../../src/copy/feedback.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;;;;;GAOG;AACH,6EAA6E;AAC7E,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,8EAA8E;AAC9E,MAAM,WAAW,UAAU;IACzB,oEAAoE;IACpE,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,8CAA8C;IAC9C,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,wEAAwE;IACxE,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,kDAAkD;IAClD,KAAK,EAAE,MAAM,CAAC;CACf"}
+{"version":3,"file":"feedback.d.ts","sourceRoot":"","sources":["../../../src/copy/feedback.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;;;;;GAOG;AACH,6EAA6E;AAC7E,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,8EAA8E;AAC9E,MAAM,WAAW,UAAU;IACzB,oEAAoE;IACpE,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,8CAA8C;IAC9C,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,wEAAwE;IACxE,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,kDAAkD;IAClD,KAAK,EAAE,MAAM,CAAC;CACf;AAED,mEAAmE;AACnE,KAAK,KAAK,GAAG,SAAS,MAAM,EAAE,CAAC;AAE/B;;;;;;;;GAQG;AACH,MAAM,WAAW,uBAAuB;IACtC;;;OAGG;IACH,GAAG,EAAE,KAAK,CAAC;IACX,MAAM,EAAE;QAAE,OAAO,EAAE,KAAK,CAAC;QAAC,OAAO,EAAE,KAAK,CAAA;KAAE,CAAC;IAC3C,IAAI,EAAE;QAAE,OAAO,EAAE,KAAK,CAAC;QAAC,OAAO,EAAE,KAAK,CAAA;KAAE,CAAC;IACzC,OAAO,EAAE;QAAE,OAAO,EAAE,KAAK,CAAC;QAAC,OAAO,EAAE,KAAK,CAAA;KAAE,CAAC;IAC5C,KAAK,EAAE;QAAE,OAAO,EAAE,KAAK,CAAC;QAAC,OAAO,EAAE,KAAK,CAAA;KAAE,CAAC;IAC1C,MAAM,EAAE;QAAE,OAAO,EAAE,KAAK,CAAA;KAAE,CAAC;IAC3B,OAAO,EAAE;QAAE,OAAO,EAAE,KAAK,CAAA;KAAE,CAAC;IAC5B,oEAAoE;IACpE,KAAK,EAAE,KAAK,CAAC;CACd"}

package/dist/types/en-US.feedback.d.ts

@@ -2,7 +2,8 @@
  * The en-US pack for the feedback family. Split the same way
  * `pt-BR.feedback.ts` is — see `en-US.ts` for why.
  */
-import type { ChromeCopy, TutorialCopy } from './copy';
+import type { ChromeCopy, NotificationUnblockCopy, TutorialCopy } from './copy';
 export declare const EN_US_TUTORIAL_COPY: TutorialCopy;
 export declare const EN_US_CHROME_COPY: ChromeCopy;
+export declare const EN_US_NOTIFICATION_UNBLOCK_COPY: NotificationUnblockCopy;
 //# sourceMappingURL=en-US.feedback.d.ts.map

package/dist/types/en-US.feedback.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"en-US.feedback.d.ts","sourceRoot":"","sources":["../../src/en-US.feedback.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,EACV,UAAU,EACV,YAAY,EACb,MAAM,QAAQ,CAAC;AAEhB,eAAO,MAAM,mBAAmB,EAAE,YAKjC,CAAC;AAEF,eAAO,MAAM,iBAAiB,EAAE,UAQ/B,CAAC"}
+{"version":3,"file":"en-US.feedback.d.ts","sourceRoot":"","sources":["../../src/en-US.feedback.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,EACV,UAAU,EACV,uBAAuB,EACvB,YAAY,EACb,MAAM,QAAQ,CAAC;AAEhB,eAAO,MAAM,mBAAmB,EAAE,YAKjC,CAAC;AAEF,eAAO,MAAM,iBAAiB,EAAE,UAQ/B,CAAC;AAgBF,eAAO,MAAM,+BAA+B,EAAE,uBAoD7C,CAAC"}

package/dist/types/pt-BR.feedback.d.ts

@@ -2,7 +2,8 @@
  * The pt-BR pack for the feedback family. Split out of `pt-BR.ts`, which is a
  * barrel over this folder — see that file for why.
  */
-import type { ChromeCopy, TutorialCopy } from './copy';
+import type { ChromeCopy, NotificationUnblockCopy, TutorialCopy } from './copy';
 export declare const PT_BR_TUTORIAL_COPY: TutorialCopy;
 export declare const PT_BR_CHROME_COPY: ChromeCopy;
+export declare const PT_BR_NOTIFICATION_UNBLOCK_COPY: NotificationUnblockCopy;
 //# sourceMappingURL=pt-BR.feedback.d.ts.map

package/dist/types/pt-BR.feedback.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pt-BR.feedback.d.ts","sourceRoot":"","sources":["../../src/pt-BR.feedback.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,EACV,UAAU,EACV,YAAY,EACb,MAAM,QAAQ,CAAC;AAEhB,eAAO,MAAM,mBAAmB,EAAE,YAKjC,CAAC;AAEF,eAAO,MAAM,iBAAiB,EAAE,UAQ/B,CAAC"}
+{"version":3,"file":"pt-BR.feedback.d.ts","sourceRoot":"","sources":["../../src/pt-BR.feedback.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,EACV,UAAU,EACV,uBAAuB,EACvB,YAAY,EACb,MAAM,QAAQ,CAAC;AAEhB,eAAO,MAAM,mBAAmB,EAAE,YAKjC,CAAC;AAEF,eAAO,MAAM,iBAAiB,EAAE,UAQ/B,CAAC;AAgBF,eAAO,MAAM,+BAA+B,EAAE,uBAoD7C,CAAC"}

package/dist/user-avatar.js

@@ -1,13 +1,13 @@
 import {
   UserAvatar,
   UserMenu
-} from "./chunk-ALAJBLBE.js";
+} from "./chunk-554SVTCN.js";
 import "./chunk-UDQSIRAP.js";
-import "./chunk-THOPGHTY.js";
-import "./chunk-3ZVUNSFF.js";
-import "./chunk-HS2OJI6L.js";
-import "./chunk-FAITHWIO.js";
+import "./chunk-HGJHZ5PE.js";
+import "./chunk-35UG2QDB.js";
 import "./chunk-XRMZMBE3.js";
+import "./chunk-FAITHWIO.js";
+import "./chunk-3ZVUNSFF.js";
 import "./chunk-VUHLNYAE.js";
 import "./chunk-2GSIEDGN.js";
 import "./chunk-AVI3XHRQ.js";
@@ -15,11 +15,11 @@ import "./chunk-FKUYRQSP.js";
 import "./chunk-BEBLRL5D.js";
 import "./chunk-6Q6T3FW5.js";
 import "./chunk-BA4RHQ3B.js";
-import "./chunk-GJUIZ5FN.js";
+import "./chunk-73BEVJCS.js";
+import "./chunk-BKAB4KZK.js";
+import "./chunk-TAMIZE4Q.js";
 import "./chunk-TSEWUY4V.js";
 import "./chunk-5LQ7PKMW.js";
-import "./chunk-TAMIZE4Q.js";
-import "./chunk-73BEVJCS.js";
 import "./chunk-YTYROOLY.js";
 import "./chunk-EPRA5QLB.js";
 import "./chunk-TYJR4GOF.js";

package/dist/utility/InstallPrompt.js

@@ -1,12 +1,10 @@
 import "../chunk-3QQVEYOR.js";
 import {
   InstallPrompt
-} from "../chunk-JE6RZ5L6.js";
+} from "../chunk-IABE56TG.js";
 import {
   usePwaInstall
-} from "../chunk-5GMHJ7Y5.js";
-import "../chunk-GY62N32G.js";
-import "../chunk-WXYLH3QZ.js";
+} from "../chunk-S2GDYA6R.js";
 import {
   PWA_INSTALL_AVAILABLE_EVENT,
   PWA_INSTALL_STASH_KEY,
@@ -14,6 +12,8 @@ import {
   readPwaInstallStash,
   resetPwaInstallStash
 } from "../chunk-UUL44SUX.js";
+import "../chunk-GY62N32G.js";
+import "../chunk-WXYLH3QZ.js";
 import "../chunk-PZ5AY32C.js";
 export {
   InstallPrompt,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12-apps/ui",
-  "version": "6.29.1",
+  "version": "6.30.1",
   "license": "MIT",
   "packageManager": "pnpm@10.34.5",
   "type": "module",
@@ -312,6 +312,10 @@
       "types": "./dist/types/components/feedback/Modal/index.d.ts",
       "default": "./dist/feedback/Modal.js"
     },
+    "./feedback/NotificationStatusNotice": {
+      "types": "./dist/types/components/feedback/NotificationStatusNotice/index.d.ts",
+      "default": "./dist/feedback/NotificationStatusNotice.js"
+    },
     "./feedback/Sonner": {
       "types": "./dist/types/components/feedback/Sonner/index.d.ts",
       "default": "./dist/feedback/Sonner.js"

package/src/components/feedback/NotificationStatusNotice/NotificationStatusNotice.helpers.ts

@@ -0,0 +1,80 @@
+import type { NotificationUnblockCopy } from '../../../copy';
+import type { AlertVariant } from '../../data-display/Alert/Alert.types';
+
+import type {
+  NotificationBrowser,
+  NotificationBrowserFamily,
+  NotificationPlatform,
+  NotificationStatus,
+} from './NotificationStatusNotice.types';
+
+/**
+ * How loud each status is.
+ *
+ * `disabled` and `blocked` are warnings because the reader can do something
+ * about them and will miss something if they do not. `unavailable` is only
+ * information: there is nothing to act on, and painting it amber would ask the
+ * reader to fix what they cannot.
+ */
+export const NOTICE_VARIANT: Record<NotificationStatus, AlertVariant> = {
+  enabled: 'success',
+  disabled: 'warning',
+  blocked: 'warning',
+  unavailable: 'info',
+};
+
+const platformOf = (userAgent: string, maxTouchPoints: number): NotificationPlatform => {
+  if (/iphone|ipad|ipod/i.test(userAgent)) return 'ios';
+  // iPadOS asks for the desktop site and reports itself as a Mac; the touch
+  // points are what give it away.
+  if (/macintosh/i.test(userAgent) && maxTouchPoints > 1) return 'ios';
+  if (/android/i.test(userAgent)) return 'android';
+  return 'desktop';
+};
+
+/**
+ * Ordered most-specific first: every Chromium browser also says `Chrome`, and
+ * every browser on iOS also says `Safari`.
+ */
+const FAMILY_PATTERNS: ReadonlyArray<readonly [NotificationBrowserFamily, RegExp]> = [
+  ['samsung', /samsungbrowser/i],
+  ['edge', /edg(e|a|ios)?\//i],
+  ['opera', /opr\/|opera|opt\//i],
+  ['firefox', /firefox\/|fxios\//i],
+  ['chrome', /chrome\/|crios\//i],
+  ['safari', /safari\//i],
+];
+
+const familyOf = (userAgent: string): NotificationBrowserFamily =>
+  FAMILY_PATTERNS.find(([, pattern]) => pattern.test(userAgent))?.[0] ?? 'other';
+
+/**
+ * Which browser, on which platform, the reader is using — enough to pick the
+ * steps that lift a notification block there. Pure: pass
+ * `navigator.userAgent` and `navigator.maxTouchPoints`.
+ */
+export const detectNotificationBrowser = (
+  userAgent: string,
+  maxTouchPoints = 0,
+): NotificationBrowser => ({
+  family: familyOf(userAgent),
+  platform: platformOf(userAgent, maxTouchPoints),
+});
+
+/**
+ * The steps that lift a notification block in `browser`, from a
+ * `NotificationUnblockCopy` pack (`PT_BR_NOTIFICATION_UNBLOCK_COPY`, …).
+ *
+ * Every iOS browser shares one list — the switch is in the device's Settings,
+ * whichever browser installed the app — and a family or platform the pack does
+ * not name falls back to its general `other` steps.
+ */
+export const notificationUnblockSteps = (
+  copy: NotificationUnblockCopy,
+  browser: NotificationBrowser,
+): readonly string[] => {
+  if (browser.platform === 'ios') return copy.ios;
+  if (browser.family === 'other') return copy.other;
+  const byPlatform: Partial<Record<NotificationPlatform, readonly string[]>> = copy[browser.family];
+  return byPlatform[browser.platform] ?? copy.other;
+};

package/src/components/feedback/NotificationStatusNotice/NotificationStatusNotice.md

@@ -0,0 +1,106 @@
+# NotificationStatusNotice
+
+Tells a reader whether **this browser** will notify them, and offers the one
+thing they can do about it.
+
+| `status` | what it means | what it offers |
+|---|---|---|
+| `enabled` | they will be notified here | nothing |
+| `disabled` | they will not, and this page can ask | an action that calls `onEnable` |
+| `blocked` | they will not, and the browser refused once | a "turn back on" disclosure over the steps for **their** browser |
+| `unavailable` | they will not, and nothing here can change it | nothing |
+
+Use it wherever a promise depends on web push — "we will call you when your
+table is ready" — so a reader is never left believing a notification is coming
+that cannot arrive.
+
+## Import
+
+```ts
+import {
+  NotificationStatusNotice,
+  detectNotificationBrowser,
+  notificationUnblockSteps,
+} from '@12-apps/ui/feedback/NotificationStatusNotice';
+import { PT_BR_NOTIFICATION_UNBLOCK_COPY } from '@12-apps/ui/pt-BR';
+```
+
+## Usage
+
+The component owns no words. Map your own permission state onto `status`, and
+pass the sentences:
+
+```tsx
+const browser = detectNotificationBrowser(navigator.userAgent, navigator.maxTouchPoints);
+
+switch (pushState) {
+  case 'offer':
+    return (
+      <NotificationStatusNotice
+        status="disabled"
+        title="Suas notificações estão desligadas."
+        description="Sem elas, a gente não consegue te avisar no celular."
+        enableLabel="Ligar notificações"
+        onEnable={requestPermission} // raise the browser prompt HERE — it needs a gesture
+        pending={asking}
+      />
+    );
+  case 'blocked':
+    return (
+      <NotificationStatusNotice
+        status="blocked"
+        title="As notificações estão bloqueadas neste navegador."
+        stepsToggleLabel="Habilitar novamente"
+        steps={notificationUnblockSteps(PT_BR_NOTIFICATION_UNBLOCK_COPY, browser)}
+      />
+    );
+  // …
+}
+```
+
+## Props
+
+Common to every status:
+
+| prop | type | |
+|---|---|---|
+| `status` | `'enabled' \| 'disabled' \| 'blocked' \| 'unavailable'` | required; picks the shape below |
+| `title` | `string` | required; the reader's situation in one sentence |
+| `description` | `string` | what that means for them |
+| `dataTestId` | `string` | root test id (default `notification-status-notice`); parts append `-enable`, `-steps-toggle`, `-steps` |
+| `className`, `sx` | | forwarded to the root `Alert` |
+
+`disabled` adds `enableLabel`, `onEnable` and `pending` (spinner, and the action
+cannot be pressed twice). `blocked` adds `stepsToggleLabel`, `steps` (ordered)
+and `defaultStepsOpen`.
+
+## The unblock steps
+
+A web page cannot re-ask after a refusal — `Notification.requestPermission()`
+resolves `denied` at once — so the only way back is the browser's own settings,
+and those differ per browser. `NotificationUnblockCopy` holds one ordered list
+per family and platform, shipped in pt-BR and en-US:
+
+- `detectNotificationBrowser(userAgent, maxTouchPoints)` answers
+  `{ family, platform }` — Chrome, Edge, Firefox, Safari, Samsung Internet,
+  Opera, or `other`; on `ios`, `android` or `desktop`. Most specific first:
+  every Chromium browser also says `Chrome`, every iOS browser also says
+  `Safari`, and an iPad asking for the desktop site says `Macintosh`.
+- `notificationUnblockSteps(copy, browser)` picks the list. Every iOS browser
+  shares one list (web push there belongs to a Home Screen app, switched in the
+  device's Settings); a family/platform the pack does not name falls back to
+  `other`.
+
+Menu labels move between browser versions. The packs follow the current ones
+and say where to look; a host that needs different words passes its own
+`NotificationUnblockCopy`.
+
+## Accessibility
+
+- The root is a **polite** live region (`role="status"`): a change of status is
+  announced without interrupting what the screen reader was saying.
+- The steps sit behind a real `button` with `aria-expanded` and `aria-controls`;
+  the list is an `<ol>`, so the order is announced. Enter and Space toggle it.
+- `disabled` and `blocked` are `warning`s — the reader can act, and will miss
+  something if they do not. `unavailable` is only `info`: painting amber what
+  cannot be fixed asks the reader to fix it.

package/src/components/feedback/NotificationStatusNotice/NotificationStatusNotice.metrics.ts

@@ -0,0 +1,8 @@
+/** Theme spacing units between the message and its action. */
+export const NOTICE_ACTION_GAP_UNITS = 1;
+
+/** Theme spacing units the numbered steps are indented by. */
+export const NOTICE_STEPS_INDENT_UNITS = 2.5;
+
+/** Theme spacing units between two steps. */
+export const NOTICE_STEP_GAP_UNITS = 0.5;

package/src/components/feedback/NotificationStatusNotice/NotificationStatusNotice.tsx

@@ -0,0 +1,134 @@
+import Box from '@mui/material/Box/index.js';
+import Typography from '@mui/material/Typography/index.js';
+import React from 'react';
+
+import { Alert } from '../../data-display/Alert/Alert';
+import { Button } from '../../form/Button/Button';
+import { NOTICE_VARIANT } from './NotificationStatusNotice.helpers';
+import {
+  NOTICE_ACTION_GAP_UNITS,
+  NOTICE_STEP_GAP_UNITS,
+  NOTICE_STEPS_INDENT_UNITS,
+} from './NotificationStatusNotice.metrics';
+import type {
+  BlockedNoticeProps,
+  DisabledNoticeProps,
+  NotificationStatusNoticeProps,
+} from './NotificationStatusNotice.types';
+
+const DEFAULT_TEST_ID = 'notification-status-notice';
+
+const EnableAction: React.FC<{ props: DisabledNoticeProps; testId: string }> = ({
+  props,
+  testId,
+}) => (
+  <Box sx={{ mt: NOTICE_ACTION_GAP_UNITS }}>
+    <Button
+      variant="solid"
+      color="primary"
+      size="sm"
+      // `loading` also disables the button, so a second tap cannot ask twice.
+      loading={props.pending}
+      onClick={props.onEnable}
+      dataTestId={`${testId}-enable`}
+    >
+      {props.enableLabel}
+    </Button>
+  </Box>
+);
+
+/**
+ * The way back from a refusal: a disclosure over the steps, because the steps
+ * are long and most readers of a blocked notice will not act on it right now.
+ * A real button with `aria-expanded`, so a screen reader hears that it opens
+ * something and whether it has.
+ */
+const BlockedSteps: React.FC<{ props: BlockedNoticeProps; testId: string }> = ({
+  props,
+  testId,
+}) => {
+  const [open, setOpen] = React.useState(props.defaultStepsOpen ?? false);
+  const listId = React.useId();
+
+  return (
+    <Box sx={{ mt: NOTICE_ACTION_GAP_UNITS }}>
+      <Button
+        variant="text"
+        color="primary"
+        size="sm"
+        aria-expanded={open}
+        aria-controls={listId}
+        onClick={() => setOpen((was) => !was)}
+        dataTestId={`${testId}-steps-toggle`}
+      >
+        {props.stepsToggleLabel}
+      </Button>
+      <Box
+        component="ol"
+        id={listId}
+        hidden={!open}
+        data-testid={`${testId}-steps`}
+        sx={{
+          m: 0,
+          mt: NOTICE_STEP_GAP_UNITS,
+          pl: NOTICE_STEPS_INDENT_UNITS,
+          display: open ? 'flex' : 'none',
+          flexDirection: 'column',
+          gap: NOTICE_STEP_GAP_UNITS,
+        }}
+      >
+        {props.steps.map((step, index) => (
+          <Typography key={`${index}-${step}`} component="li" variant="body2">
+            {step}
+          </Typography>
+        ))}
+      </Box>
+    </Box>
+  );
+};
+
+const NoticeAction: React.FC<{ props: NotificationStatusNoticeProps; testId: string }> = ({
+  props,
+  testId,
+}) => {
+  if (props.status === 'disabled') return <EnableAction props={props} testId={testId} />;
+  if (props.status === 'blocked') return <BlockedSteps props={props} testId={testId} />;
+  return null;
+};
+
+/**
+ * Tells a reader whether this browser will notify them, and gives them the one
+ * thing they can do about it: a tap that asks (`disabled`), the steps that
+ * undo a refusal (`blocked`), or nothing when nothing can change (`enabled`,
+ * `unavailable`).
+ *
+ * Every word is the host's. The component decides only the shape and how loud
+ * each status is — see `NOTICE_VARIANT`.
+ */
+export const NotificationStatusNotice = React.forwardRef<
+  HTMLDivElement,
+  NotificationStatusNoticeProps
+>((props, ref) => {
+  const testId = props.dataTestId ?? DEFAULT_TEST_ID;
+
+  return (
+    <Alert
+      ref={ref}
+      variant={NOTICE_VARIANT[props.status]}
+      title={props.title}
+      description={props.description}
+      // A status line, not an interruption: it must not cut across whatever
+      // the screen reader is saying about the page it sits on.
+      announce="polite"
+      showIcon
+      data-testid={testId}
+      data-status={props.status}
+      className={props.className}
+      sx={props.sx}
+    >
+      <NoticeAction props={props} testId={testId} />
+    </Alert>
+  );
+});
+
+NotificationStatusNotice.displayName = 'NotificationStatusNotice';

package/src/components/feedback/NotificationStatusNotice/NotificationStatusNotice.types.ts

@@ -0,0 +1,83 @@
+import type { SxProps, Theme } from '@mui/material/styles/index.js';
+
+/**
+ * Where a reader stands with this browser's notifications.
+ *
+ * - `enabled` — they will be notified here.
+ * - `disabled` — they are not, and this page CAN ask: one tap raises the
+ *   browser's own permission prompt.
+ * - `blocked` — they are not, and this page can NOT ask: the browser refused
+ *   once and only the reader can undo that, in the browser's own settings.
+ * - `unavailable` — they are not, and nothing will change it here: the browser
+ *   has no web push, or the host cannot send it.
+ */
+export type NotificationStatus = 'enabled' | 'disabled' | 'blocked' | 'unavailable';
+
+interface NotificationStatusNoticeCommon {
+  /** The one sentence that states the reader's situation. */
+  title: string;
+  /** What that situation means for them — e.g. what they will miss. */
+  description?: string;
+  /** Test id of the root; parts derive from it (`-enable`, `-steps`, …). */
+  dataTestId?: string;
+  className?: string;
+  sx?: SxProps<Theme>;
+}
+
+export interface EnabledNoticeProps extends NotificationStatusNoticeCommon {
+  status: 'enabled';
+}
+
+export interface DisabledNoticeProps extends NotificationStatusNoticeCommon {
+  status: 'disabled';
+  /** The action's label, e.g. "Turn on notifications". */
+  enableLabel: string;
+  /**
+   * Ask for the permission. Call the browser's `requestPermission` from HERE:
+   * a browser only shows its prompt inside a user gesture.
+   */
+  onEnable: () => void;
+  /** The request is in flight — the action shows a spinner and cannot be pressed twice. */
+  pending?: boolean;
+}
+
+export interface BlockedNoticeProps extends NotificationStatusNoticeCommon {
+  status: 'blocked';
+  /** The disclosure's label, e.g. "Turn them back on". */
+  stepsToggleLabel: string;
+  /**
+   * How to lift the block in THIS reader's browser, one step per entry, in
+   * order. The host picks them — `detectNotificationBrowser` says which
+   * browser it is looking at — because the words are the host's.
+   */
+  steps: readonly string[];
+  /** Start with the steps showing. Defaults to collapsed. */
+  defaultStepsOpen?: boolean;
+}
+
+export interface UnavailableNoticeProps extends NotificationStatusNoticeCommon {
+  status: 'unavailable';
+}
+
+export type NotificationStatusNoticeProps =
+  | EnabledNoticeProps
+  | DisabledNoticeProps
+  | BlockedNoticeProps
+  | UnavailableNoticeProps;
+
+/** The browser families whose permission settings differ enough to need their own steps. */
+export type NotificationBrowserFamily =
+  | 'chrome'
+  | 'edge'
+  | 'firefox'
+  | 'safari'
+  | 'samsung'
+  | 'opera'
+  | 'other';
+
+export type NotificationPlatform = 'ios' | 'android' | 'desktop';
+
+export interface NotificationBrowser {
+  family: NotificationBrowserFamily;
+  platform: NotificationPlatform;
+}

package/src/components/feedback/NotificationStatusNotice/index.ts

@@ -0,0 +1,16 @@
+export { NotificationStatusNotice } from './NotificationStatusNotice';
+export {
+  detectNotificationBrowser,
+  notificationUnblockSteps,
+} from './NotificationStatusNotice.helpers';
+export type {
+  BlockedNoticeProps,
+  DisabledNoticeProps,
+  EnabledNoticeProps,
+  NotificationBrowser,
+  NotificationBrowserFamily,
+  NotificationPlatform,
+  NotificationStatus,
+  NotificationStatusNoticeProps,
+  UnavailableNoticeProps,
+} from './NotificationStatusNotice.types';

package/src/components/feedback/NotificationStatusNotice/tests.md

@@ -0,0 +1,24 @@
+# NotificationStatusNotice Test Status Tracking
+
+## Test Files Status
+
+- [x] NotificationStatusNotice.test.stories.tsx created
+- [x] Unit tests: `__tests__/notification-status-notice.test.tsx`, `detect-notification-browser.test.ts`, `notification-unblock-steps.test.ts`
+
+## Storybook Tests Status
+
+| Test Name | Status | Pass/Fail | Notes |
+| --- | --- | --- | --- |
+| Disabled: the action asks the host | Written | - | role/status, onEnable called once |
+| Blocked: steps open and close from the keyboard | Written | - | Enter opens, Space closes, aria-expanded, order |
+| Enabled and unavailable: no action | Written | - | no button rendered |
+| Disabled + pending: the action is locked | Written | - | action disabled |
+
+Legend: Pending | Running | PASS | FAIL
+
+## Static Stories Status
+
+- [x] Default story (`Disabled`)
+- [x] All variants covered (`Enabled`, `Disabled`, `Blocked`, `Unavailable`, `AllStatuses`)
+- [x] Loading state story (`Pending`)
+- [x] Edge cases (`LongText`, `BlockedOnIphone`)

package/src/components/feedback/NotificationStatusNotice/track.md

@@ -0,0 +1,34 @@
+# NotificationStatusNotice
+
+Tells a reader whether this browser will notify them — enabled, disabled but
+askable, blocked by the browser, or unavailable — and offers the one action
+each status allows. Composes `Alert` and `Button`; every sentence comes from
+the host, and the browser-specific unblock steps from the pt-BR/en-US
+`NotificationUnblockCopy` packs.
+
+## Props
+
+- `status` — which of the four situations; narrows the props below.
+- `title` / `description` — the host's sentences.
+- `enableLabel` / `onEnable` / `pending` (`disabled`) — the permission request.
+- `stepsToggleLabel` / `steps` / `defaultStepsOpen` (`blocked`) — the disclosure over the unblock steps.
+- `dataTestId`, `className`, `sx` — forwarded to the root.
+
+## Lint
+
+Clean.
+
+## Type Errors
+
+None.
+
+## Testing Scenarios
+
+Each status's shape; `onEnable` once and not while pending; the disclosure by
+click and keyboard; browser detection across Chrome/Edge/Firefox/Safari/Samsung/
+Opera on desktop, Android, iPhone and iPad; the steps fallback; pt-BR and en-US
+packs with the same shape.
+
+## Current
+
+Web only; no React Native port.

package/src/components/feedback/index.ts

@@ -1,6 +1,7 @@
 export * from './ConfirmAction';
 export * from './Dialog';
 export * from './Modal';
+export * from './NotificationStatusNotice';
 export * from './Sonner';
 export * from './StackedModal';
 export * from './Toast';

package/src/components/form/Autocomplete/Autocomplete.helpers.ts

@@ -104,12 +104,30 @@ function escapeRegExp(value: string): string {
   return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
 
+/** One run of a highlighted label: plain text, or text the query matched. */
+export interface HighlightSegment {
+  text: string;
+  match: boolean;
+}
+
 /**
- * Wrap query matches in `<mark>` for the default suggestion renderer. Skipped for
- * fuzzy mode (non-contiguous matches) and empty queries. Returns HTML.
+ * Split `label` into the runs the query matches and the runs between them, in
+ * order, for the default suggestion renderer to wrap the matches in `<mark>`.
+ * Every occurrence of the query matches, case-insensitively and literally (regex
+ * metacharacters are escaped). Fuzzy mode (non-contiguous matches) and an empty
+ * query yield the whole label as one unmatched run.
+ *
+ * Returns TEXT, never markup: a label is caller data (in a consumer, a user's
+ * own display name), so the renderer must hand each run to React as a text
+ * child, which escapes it. Building an HTML string here and injecting it is how
+ * a label of `<img onerror=…>` once ran script in the host page.
  */
-export function highlightLabel(label: string, query: string, matchMode: MatchMode): string {
-  if (!query || matchMode === 'fuzzy') return label;
+export function highlightLabel(label: string, query: string, matchMode: MatchMode): HighlightSegment[] {
+  if (!query || matchMode === 'fuzzy') return [{ text: label, match: false }];
+  // The capturing group makes `split` keep each match, at the odd indices.
   const regex = new RegExp(`(${escapeRegExp(query)})`, 'gi');
-  return label.replace(regex, '<mark>$1</mark>');
+  return label
+    .split(regex)
+    .map((text, index) => ({ text, match: index % 2 === 1 }))
+    .filter((segment) => segment.text !== '');
 }