@12-apps/ui 6.29.1 → 6.30.0

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/copy/feedback.ts

@@ -37,3 +37,31 @@ export interface ChromeCopy {
   /** The share affordance in the install prompt. */
   share: string;
 }
+
+/** One ordered list of steps a reader follows in their browser. */
+type Steps = readonly string[];
+
+/**
+ * How to lift a notification block, per browser — the steps
+ * `NotificationStatusNotice` shows in its `blocked` state.
+ *
+ * Keyed the way `detectNotificationBrowser` answers, and read through
+ * `notificationUnblockSteps`, which falls back to `other` for anything a pack
+ * does not name. Menu labels move between browser versions; these follow the
+ * current ones and say where to look rather than promising an exact word.
+ */
+export interface NotificationUnblockCopy {
+  /**
+   * Every browser on iOS. Web push there belongs to a Home Screen app, so the
+   * switch lives in the device's Settings rather than in any browser.
+   */
+  ios: Steps;
+  chrome: { desktop: Steps; android: Steps };
+  edge: { desktop: Steps; android: Steps };
+  firefox: { desktop: Steps; android: Steps };
+  opera: { desktop: Steps; android: Steps };
+  safari: { desktop: Steps };
+  samsung: { android: Steps };
+  /** Anything unrecognised — general enough to be true everywhere. */
+  other: Steps;
+}

package/src/en-US.feedback.ts

@@ -4,6 +4,7 @@
  */
 import type {
   ChromeCopy,
+  NotificationUnblockCopy,
   TutorialCopy,
 } from './copy';
 
@@ -23,3 +24,71 @@ export const EN_US_CHROME_COPY: ChromeCopy = {
   scrollToTop: "Back to top",
   share: "Share",
 };
+
+const EN_US_CHROMIUM_DESKTOP = [
+  "Click the icon to the left of the site's address.",
+  "Open \"Site settings\".",
+  "Under \"Notifications\", choose \"Allow\".",
+  "Come back to this page and reload it.",
+] as const;
+
+const EN_US_CHROMIUM_ANDROID = [
+  "Tap the icon to the left of the site's address.",
+  "Tap \"Permissions\".",
+  "Tap \"Notifications\" and choose \"Allow\".",
+  "Come back to this page and reload it.",
+] as const;
+
+export const EN_US_NOTIFICATION_UNBLOCK_COPY: NotificationUnblockCopy = {
+  ios: [
+    "Open the iPhone's Settings.",
+    "Tap \"Notifications\".",
+    "Find this app in the list and turn on \"Allow Notifications\".",
+  ],
+  chrome: { desktop: EN_US_CHROMIUM_DESKTOP, android: EN_US_CHROMIUM_ANDROID },
+  edge: {
+    desktop: [
+      "Click the lock to the left of the site's address.",
+      "Open \"Permissions for this site\".",
+      "Under \"Notifications\", choose \"Allow\".",
+      "Come back to this page and reload it.",
+    ],
+    android: EN_US_CHROMIUM_ANDROID,
+  },
+  firefox: {
+    desktop: [
+      "Click the permissions icon to the left of the site's address.",
+      "Next to \"Send notifications\", click the X to clear the block.",
+      "Reload the page and turn notifications on again.",
+    ],
+    android: [
+      "Open the browser menu and tap \"Settings\".",
+      "Tap \"Site permissions\", then \"Notifications\".",
+      "Find this site and choose \"Allow\".",
+      "Come back to this page and reload it.",
+    ],
+  },
+  opera: { desktop: EN_US_CHROMIUM_DESKTOP, android: EN_US_CHROMIUM_ANDROID },
+  safari: {
+    desktop: [
+      "In the Safari menu, open \"Settings\".",
+      "Go to the \"Websites\" tab and pick \"Notifications\" in the sidebar.",
+      "Find this site and choose \"Allow\".",
+      "Come back to this page and reload it.",
+    ],
+  },
+  samsung: {
+    android: [
+      "Open the browser menu and tap \"Settings\".",
+      "Tap \"Sites and downloads\", then \"Notifications\".",
+      "Find this site and allow notifications.",
+      "Come back to this page and reload it.",
+    ],
+  },
+  other: [
+    "Open the browser's settings.",
+    "Look for site permissions, then \"Notifications\".",
+    "Allow notifications for this site.",
+    "Come back to this page and reload it.",
+  ],
+};

package/src/pt-BR.feedback.ts

@@ -4,6 +4,7 @@
  */
 import type {
   ChromeCopy,
+  NotificationUnblockCopy,
   TutorialCopy,
 } from './copy';
 
@@ -23,3 +24,71 @@ export const PT_BR_CHROME_COPY: ChromeCopy = {
   scrollToTop: "Voltar ao topo",
   share: "Compartilhar",
 };
+
+const PT_BR_CHROMIUM_DESKTOP = [
+  "Clique no ícone à esquerda do endereço do site.",
+  "Abra \"Configurações do site\".",
+  "Em \"Notificações\", escolha \"Permitir\".",
+  "Volte a esta página e recarregue.",
+] as const;
+
+const PT_BR_CHROMIUM_ANDROID = [
+  "Toque no ícone à esquerda do endereço do site.",
+  "Toque em \"Permissões\".",
+  "Toque em \"Notificações\" e escolha \"Permitir\".",
+  "Volte a esta página e recarregue.",
+] as const;
+
+export const PT_BR_NOTIFICATION_UNBLOCK_COPY: NotificationUnblockCopy = {
+  ios: [
+    "Abra os Ajustes do iPhone.",
+    "Toque em \"Notificações\".",
+    "Encontre este app na lista e ative \"Permitir Notificações\".",
+  ],
+  chrome: { desktop: PT_BR_CHROMIUM_DESKTOP, android: PT_BR_CHROMIUM_ANDROID },
+  edge: {
+    desktop: [
+      "Clique no cadeado à esquerda do endereço do site.",
+      "Abra \"Permissões para este site\".",
+      "Em \"Notificações\", escolha \"Permitir\".",
+      "Volte a esta página e recarregue.",
+    ],
+    android: PT_BR_CHROMIUM_ANDROID,
+  },
+  firefox: {
+    desktop: [
+      "Clique no ícone de permissões à esquerda do endereço do site.",
+      "Ao lado de \"Enviar notificações\", clique no X para tirar o bloqueio.",
+      "Recarregue a página e ative as notificações de novo.",
+    ],
+    android: [
+      "Abra o menu do navegador e toque em \"Configurações\".",
+      "Toque em \"Permissões de sites\" e depois em \"Notificações\".",
+      "Encontre este site e escolha \"Permitir\".",
+      "Volte a esta página e recarregue.",
+    ],
+  },
+  opera: { desktop: PT_BR_CHROMIUM_DESKTOP, android: PT_BR_CHROMIUM_ANDROID },
+  safari: {
+    desktop: [
+      "No menu Safari, abra \"Ajustes\".",
+      "Vá na aba \"Sites\" e, na lateral, em \"Notificações\".",
+      "Encontre este site e escolha \"Permitir\".",
+      "Volte a esta página e recarregue.",
+    ],
+  },
+  samsung: {
+    android: [
+      "Abra o menu do navegador e toque em \"Configurações\".",
+      "Toque em \"Sites e downloads\" e depois em \"Notificações\".",
+      "Encontre este site e permita as notificações.",
+      "Volte a esta página e recarregue.",
+    ],
+  },
+  other: [
+    "Abra as configurações do navegador.",
+    "Procure as permissões dos sites e depois \"Notificações\".",
+    "Permita as notificações para este site.",
+    "Volte a esta página e recarregue.",
+  ],
+};

package/dist/chunk-E5ACI7EA.js

@@ -1,22 +0,0 @@
-// src/en-US.feedback.ts
-var EN_US_TUTORIAL_COPY = {
-  skip: "Skip",
-  previous: "Back",
-  next: "Next",
-  restart: "Start over"
-};
-var EN_US_CHROME_COPY = {
-  dismissToast: "Dismiss",
-  goBack: "Back",
-  closePanel: "Close",
-  closeTab: "Close tab",
-  scrollRegion: "Scrollable content",
-  scrollToTop: "Back to top",
-  share: "Share"
-};
-
-export {
-  EN_US_TUTORIAL_COPY,
-  EN_US_CHROME_COPY
-};
-//# sourceMappingURL=chunk-E5ACI7EA.js.map

package/dist/chunk-E5ACI7EA.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/en-US.feedback.ts"],"sourcesContent":["/**\n * The en-US pack for the feedback family. Split the same way\n * `pt-BR.feedback.ts` is — see `en-US.ts` for why.\n */\nimport type {\n  ChromeCopy,\n  TutorialCopy,\n} from './copy';\n\nexport const EN_US_TUTORIAL_COPY: TutorialCopy = {\n  skip: \"Skip\",\n  previous: \"Back\",\n  next: \"Next\",\n  restart: \"Start over\",\n};\n\nexport const EN_US_CHROME_COPY: ChromeCopy = {\n  dismissToast: \"Dismiss\",\n  goBack: \"Back\",\n  closePanel: \"Close\",\n  closeTab: \"Close tab\",\n  scrollRegion: \"Scrollable content\",\n  scrollToTop: \"Back to top\",\n  share: \"Share\",\n};\n"],"mappings":";AASO,IAAM,sBAAoC;AAAA,EAC/C,MAAM;AAAA,EACN,UAAU;AAAA,EACV,MAAM;AAAA,EACN,SAAS;AACX;AAEO,IAAM,oBAAgC;AAAA,EAC3C,cAAc;AAAA,EACd,QAAQ;AAAA,EACR,YAAY;AAAA,EACZ,UAAU;AAAA,EACV,cAAc;AAAA,EACd,aAAa;AAAA,EACb,OAAO;AACT;","names":[]}

package/dist/chunk-IFLZNCAI.js

@@ -1,22 +0,0 @@
-// src/pt-BR.feedback.ts
-var PT_BR_TUTORIAL_COPY = {
-  skip: "Pular",
-  previous: "Anterior",
-  next: "Pr\xF3ximo",
-  restart: "Recome\xE7ar"
-};
-var PT_BR_CHROME_COPY = {
-  dismissToast: "Fechar o aviso",
-  goBack: "Voltar",
-  closePanel: "Fechar",
-  closeTab: "Fechar a aba",
-  scrollRegion: "Conte\xFAdo rol\xE1vel",
-  scrollToTop: "Voltar ao topo",
-  share: "Compartilhar"
-};
-
-export {
-  PT_BR_TUTORIAL_COPY,
-  PT_BR_CHROME_COPY
-};
-//# sourceMappingURL=chunk-IFLZNCAI.js.map

package/dist/chunk-IFLZNCAI.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/pt-BR.feedback.ts"],"sourcesContent":["/**\n * The pt-BR pack for the feedback family. Split out of `pt-BR.ts`, which is a\n * barrel over this folder — see that file for why.\n */\nimport type {\n  ChromeCopy,\n  TutorialCopy,\n} from './copy';\n\nexport const PT_BR_TUTORIAL_COPY: TutorialCopy = {\n  skip: \"Pular\",\n  previous: \"Anterior\",\n  next: \"Próximo\",\n  restart: \"Recomeçar\",\n};\n\nexport const PT_BR_CHROME_COPY: ChromeCopy = {\n  dismissToast: \"Fechar o aviso\",\n  goBack: \"Voltar\",\n  closePanel: \"Fechar\",\n  closeTab: \"Fechar a aba\",\n  scrollRegion: \"Conteúdo rolável\",\n  scrollToTop: \"Voltar ao topo\",\n  share: \"Compartilhar\",\n};\n"],"mappings":";AASO,IAAM,sBAAoC;AAAA,EAC/C,MAAM;AAAA,EACN,UAAU;AAAA,EACV,MAAM;AAAA,EACN,SAAS;AACX;AAEO,IAAM,oBAAgC;AAAA,EAC3C,cAAc;AAAA,EACd,QAAQ;AAAA,EACR,YAAY;AAAA,EACZ,UAAU;AAAA,EACV,cAAc;AAAA,EACd,aAAa;AAAA,EACb,OAAO;AACT;","names":[]}

package/dist/chunk-SO2J7ULY.js

@@ -1 +0,0 @@
-//# sourceMappingURL=chunk-SO2J7ULY.js.map