@12-apps/ui 1.0.0 → 1.3.0

package/src/components/utility/InstallPrompt/InstallPrompt.md

@@ -0,0 +1,113 @@
+# InstallPrompt
+
+A dismissible "install this app" invitation, plus the `usePwaInstall` hook behind it.
+
+## The problem this solves
+
+A manifest and a service worker make a site **installable**. They do not make it
+**install**. Chromium signals its willingness by firing `beforeinstallprompt` and
+then does nothing further on its own beyond a small address-bar icon most users
+never notice. If no page code calls `preventDefault()` on that event and keeps a
+reference to it, the handle is gone and the app can never ask.
+
+So a site can pass every installability criterion a browser checks — HTTPS,
+manifest, matching icons, a service worker with a fetch handler — and still never
+offer to install, because nothing in it captures the event. That is the gap this
+component fills.
+
+On iOS Safari the event never fires at all: there is no programmatic install, only
+Share → Add to Home Screen. Collapsing that into "unsupported" hides the affordance
+from the largest slice of a mobile storefront's traffic, so it is handled as its own
+case with instructions in place of a button.
+
+## Usage
+
+```tsx
+import { InstallPrompt } from '@12-apps/ui/utility/InstallPrompt';
+
+export const StorefrontHeader = () => (
+  <InstallPrompt
+    title="Instalar o FutureDrink"
+    description="Peça mais rápido na próxima visita, direto da tela de início."
+    installLabel="Instalar"
+    dismissLabel="Dispensar"
+  />
+);
+```
+
+Mount it unconditionally. It returns `null` unless an install affordance should
+genuinely be shown, so there is nothing to gate at the call site.
+
+### Headless
+
+When the built-in presentation does not fit, use the hook and render your own:
+
+```tsx
+import { usePwaInstall } from '@12-apps/ui/utility/InstallPrompt';
+
+const InstallLink = () => {
+  const { canInstall, platform, promptInstall } = usePwaInstall();
+
+  if (!canInstall) return null;
+  if (platform === 'ios') return <IosHint />;
+
+  return <button onClick={() => void promptInstall()}>Instalar</button>;
+};
+```
+
+`promptInstall()` must be called from a user gesture — browsers reject a prompt
+raised from a timer or an effect.
+
+## When it renders nothing
+
+| Condition | Why |
+|---|---|
+| Already installed | `display-mode: standalone`, or `navigator.standalone` on iOS |
+| Recently dismissed | A stored timestamp inside the `dismissForDays` window |
+| No install route | Not Chromium, and not iOS Safari — e.g. Chrome on iOS, which cannot add to the home screen at all |
+| Event not yet captured | Chromium has not (yet) offered a prompt |
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `title` | `string` | `'Install this app'` | Headline text |
+| `description` | `string` | — | Supporting line |
+| `installLabel` | `string` | `'Install'` | Install button label (Chromium only) |
+| `iosInstructions` | `ReactNode` | Share → Add to Home Screen | Replaces the built-in iOS wording |
+| `dismissLabel` | `string` | `'Dismiss install prompt'` | Accessible label for the close button |
+| `icon` | `ReactNode` | install glyph | Leading icon |
+| `onInstall` | `(outcome: InstallOutcome) => void` | — | Called after the native prompt resolves |
+| `onDismiss` | `() => void` | — | Called when dismissed |
+| `storageKey` | `string` | `'pwa-install-dismissed'` | localStorage key for the dismissal |
+| `dismissForDays` | `number` | `30` | Dismissal lifetime; `0` means permanent |
+
+All copy defaults to English and every string is a prop — this package is
+locale-neutral and the consuming app supplies its own wording.
+
+## Hook API
+
+`usePwaInstall(options)` returns:
+
+- `canInstall` — whether to render an affordance at all
+- `platform` — `'prompt'` (Chromium), `'ios'` (Safari on iOS/iPadOS), or `'unsupported'`
+- `isInstalled` — running as an installed app
+- `promptInstall()` — fires the native prompt; resolves `'accepted' | 'dismissed' | 'unavailable'`
+- `dismiss()` — suppresses the affordance for `dismissForDays`
+
+## Notes
+
+- **SSR-safe.** Every environment probe runs in an effect, never during render, so
+  there is no hydration mismatch. The first paint reports `canInstall: false` and
+  corrects itself on mount.
+- **The deferred event is single-use.** After `prompt()` resolves it is discarded;
+  Chromium emits a fresh one if the app is still installable.
+- **Declining the native dialog counts as a dismissal**, or the affordance would
+  reappear on the next render.
+- **Storage failures are swallowed.** `localStorage` throws rather than returning
+  `null` in Safari private mode and wherever cookies are blocked; an uncaught throw
+  would break the page on exactly the browsers this component serves.
+- **A missed first event recovers on its own.** The listener attaches on mount,
+  which can be after a cold-load event. Chromium re-fires on navigation and on
+  re-evaluation of the criteria. A host that needs the very first one can capture
+  it in its HTML entry point and re-dispatch it once the app has mounted.

package/src/components/utility/InstallPrompt/InstallPrompt.stories.tsx

@@ -0,0 +1,118 @@
+import { Box, Typography } from '@mui/material';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { useEffect } from 'react';
+
+import { InstallPrompt } from './InstallPrompt';
+import type { BeforeInstallPromptEvent } from './InstallPrompt.types';
+
+/**
+ * The component listens for a browser event that Storybook will never fire, so
+ * every story synthesises one. This is also the shape a host can dispatch from
+ * its own early capture script to replay an event that arrived before React
+ * mounted.
+ */
+const useSyntheticInstallEvent = () => {
+  useEffect(() => {
+    const event = new Event('beforeinstallprompt') as BeforeInstallPromptEvent;
+
+    Object.assign(event, {
+      platforms: ['web'],
+      prompt: () => Promise.resolve(),
+      userChoice: Promise.resolve({ outcome: 'accepted' as const, platform: 'web' }),
+    });
+
+    window.dispatchEvent(event);
+  }, []);
+};
+
+/** Storage is shared across stories; clear it so a dismissal in one does not hide the next. */
+const useCleanDismissalState = (storageKey: string) => {
+  useEffect(() => {
+    window.localStorage.removeItem(storageKey);
+  }, [storageKey]);
+};
+
+const meta: Meta<typeof InstallPrompt> = {
+  title: 'Utility/InstallPrompt',
+  component: InstallPrompt,
+  tags: ['autodocs', 'component:InstallPrompt'],
+  parameters: {
+    layout: 'padded',
+    docs: {
+      description: {
+        component:
+          'Dismissible PWA install invitation. Captures the Chromium `beforeinstallprompt` ' +
+          'event so the app can offer installation itself, and falls back to Add to Home ' +
+          'Screen instructions on iOS Safari, where no programmatic install exists. Renders ' +
+          'nothing when the app is already installed, was recently dismissed, or the browser ' +
+          'cannot install it.',
+      },
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof InstallPrompt>;
+
+const DefaultComponent = () => {
+  useCleanDismissalState('sb-install-default');
+  useSyntheticInstallEvent();
+
+  return <InstallPrompt storageKey="sb-install-default" />;
+};
+
+export const Default: Story = {
+  render: () => <DefaultComponent />,
+};
+
+const WithDescriptionComponent = () => {
+  useCleanDismissalState('sb-install-described');
+  useSyntheticInstallEvent();
+
+  return (
+    <InstallPrompt
+      storageKey="sb-install-described"
+      title="Install FutureDrink"
+      description="Order faster next time — the menu opens straight from your home screen."
+      installLabel="Install"
+    />
+  );
+};
+
+export const WithDescription: Story = {
+  render: () => <WithDescriptionComponent />,
+};
+
+const LocalisedComponent = () => {
+  useCleanDismissalState('sb-install-ptbr');
+  useSyntheticInstallEvent();
+
+  return (
+    <InstallPrompt
+      storageKey="sb-install-ptbr"
+      title="Instalar o FutureDrink"
+      description="Peça mais rápido na próxima visita, direto da tela de início."
+      installLabel="Instalar"
+      dismissLabel="Dispensar"
+    />
+  );
+};
+
+/** Every string is a prop; this package ships no locale of its own. */
+export const Localised: Story = {
+  render: () => <LocalisedComponent />,
+};
+
+const NotInstallableComponent = () => (
+  <Box>
+    <Typography variant="body2" sx={{ mb: 2 }}>
+      No install event was dispatched, so the component renders nothing. This is what a browser
+      with no install route, an already-installed app, and a recent dismissal all look like.
+    </Typography>
+    <InstallPrompt storageKey="sb-install-absent" />
+  </Box>
+);
+
+export const NotInstallable: Story = {
+  render: () => <NotInstallableComponent />,
+};

package/src/components/utility/InstallPrompt/InstallPrompt.styles.ts

@@ -0,0 +1,50 @@
+import { alpha } from '@mui/material';
+import type { CSSObject, Theme } from '@mui/material/styles';
+
+export const installPromptStyles = (theme: Theme): CSSObject => ({
+  display: 'flex',
+  alignItems: 'flex-start',
+  gap: theme.spacing(1.5),
+  padding: theme.spacing(1.5, 2),
+  borderRadius: theme.spacing(1),
+  backgroundColor: alpha(theme.palette.primary.main, 0.08),
+  border: `1px solid ${alpha(theme.palette.primary.main, 0.2)}`,
+
+  '.install-prompt-icon': {
+    flexShrink: 0,
+    marginTop: theme.spacing(0.25),
+    display: 'flex',
+    color: theme.palette.primary.main,
+  },
+
+  '.install-prompt-content': {
+    flex: 1,
+    minWidth: 0,
+  },
+
+  '.install-prompt-title': {
+    fontWeight: 600,
+  },
+
+  '.install-prompt-description': {
+    opacity: 0.9,
+  },
+
+  '.install-prompt-actions': {
+    display: 'flex',
+    flexShrink: 0,
+    alignItems: 'center',
+    gap: theme.spacing(1),
+  },
+
+  // The actions drop to their own full-width row on a phone, where this
+  // component does most of its work.
+  [theme.breakpoints.down('sm')]: {
+    flexWrap: 'wrap',
+
+    '.install-prompt-actions': {
+      width: '100%',
+      marginTop: theme.spacing(1),
+    },
+  },
+});

package/src/components/utility/InstallPrompt/InstallPrompt.test.stories.tsx

@@ -0,0 +1,83 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { useEffect } from 'react';
+import { expect, userEvent, waitFor, within } from 'storybook/test';
+
+import { InstallPrompt } from './InstallPrompt';
+import type { BeforeInstallPromptEvent } from './InstallPrompt.types';
+
+const meta: Meta<typeof InstallPrompt> = {
+  title: 'Utility/InstallPrompt/Tests',
+  component: InstallPrompt,
+  parameters: {
+    layout: 'padded',
+    chromatic: { disableSnapshot: false },
+  },
+  tags: ['autodocs', 'test', 'component:InstallPrompt'],
+};
+
+export default meta;
+export type Story = StoryObj<typeof meta>;
+
+const dispatchInstallEvent = () => {
+  const event = new Event('beforeinstallprompt') as BeforeInstallPromptEvent;
+
+  Object.assign(event, {
+    platforms: ['web'],
+    prompt: () => Promise.resolve(),
+    userChoice: Promise.resolve({ outcome: 'accepted' as const, platform: 'web' }),
+  });
+
+  window.dispatchEvent(event);
+};
+
+const Installable = ({ storageKey }: { storageKey: string }) => {
+  useEffect(() => {
+    window.localStorage.removeItem(storageKey);
+    dispatchInstallEvent();
+  }, [storageKey]);
+
+  return <InstallPrompt storageKey={storageKey} title="Install this app" />;
+};
+
+// ================================
+// INTERACTION TESTS
+// ================================
+
+export const AppearsWhenInstallable: Story = {
+  render: () => <Installable storageKey="sb-test-appears" />,
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+
+    await waitFor(async () => {
+      await expect(canvas.getByTestId('install-prompt')).toBeInTheDocument();
+    });
+    await expect(canvas.getByTestId('install-prompt-install')).toBeInTheDocument();
+  },
+};
+
+export const DismissHidesPrompt: Story = {
+  render: () => <Installable storageKey="sb-test-dismiss" />,
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+
+    await waitFor(async () => {
+      await expect(canvas.getByTestId('install-prompt-dismiss')).toBeInTheDocument();
+    });
+    await userEvent.click(canvas.getByTestId('install-prompt-dismiss'));
+
+    await waitFor(async () => {
+      await expect(canvas.queryByTestId('install-prompt')).not.toBeInTheDocument();
+    });
+  },
+};
+
+export const HiddenWithoutInstallEvent: Story = {
+  render: () => <InstallPrompt storageKey="sb-test-hidden" />,
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+
+    await waitFor(async () => {
+      await expect(canvas.queryByTestId('install-prompt')).not.toBeInTheDocument();
+    });
+  },
+};

package/src/components/utility/InstallPrompt/InstallPrompt.tsx

@@ -0,0 +1,192 @@
+import Close from '@mui/icons-material/Close';
+import InstallMobile from '@mui/icons-material/InstallMobile';
+import IosShare from '@mui/icons-material/IosShare';
+import { Box, Button, IconButton, Typography } from '@mui/material';
+import { styled } from '@mui/material/styles';
+import React from 'react';
+
+import { installPromptStyles } from './InstallPrompt.styles';
+import type { InstallPlatform, InstallPromptProps } from './InstallPrompt.types';
+import { usePwaInstall } from './usePwaInstall';
+
+const StyledInstallPrompt = styled(Box)(({ theme }) => installPromptStyles(theme));
+
+const testIdFor = (base: string | undefined, suffix: string) =>
+  base ? `${base}-${suffix}` : `install-prompt-${suffix}`;
+
+/**
+ * The iOS branch renders instructions rather than a button, because Safari
+ * exposes no API to open its own Add to Home Screen sheet. A button here would
+ * be a control that does nothing when pressed.
+ */
+const IosInstructions: React.FC<{
+  instructions?: React.ReactNode;
+  dataTestId?: string;
+}> = ({ instructions, dataTestId }) => (
+  <Typography
+    className="install-prompt-description"
+    variant="body2"
+    component="div"
+    data-testid={testIdFor(dataTestId, 'ios-instructions')}
+    sx={{ display: 'flex', alignItems: 'center', gap: 0.5, flexWrap: 'wrap' }}
+  >
+    {instructions ?? (
+      <>
+        Tap <IosShare fontSize="small" aria-label="Share" /> then &quot;Add to Home Screen&quot;
+      </>
+    )}
+  </Typography>
+);
+
+const InstallPromptBody: React.FC<{
+  icon?: React.ReactNode;
+  title: string;
+  description?: string;
+  iosInstructions?: React.ReactNode;
+  platform: InstallPlatform;
+  dataTestId?: string;
+}> = ({ icon, title, description, iosInstructions, platform, dataTestId }) => (
+  <>
+    <Box className="install-prompt-icon" aria-hidden="true">
+      {icon ?? <InstallMobile />}
+    </Box>
+
+    <Box className="install-prompt-content">
+      <Typography
+        className="install-prompt-title"
+        variant="subtitle2"
+        component="div"
+        data-testid={testIdFor(dataTestId, 'title')}
+      >
+        {title}
+      </Typography>
+
+      {description && (
+        <Typography
+          className="install-prompt-description"
+          variant="body2"
+          component="div"
+          data-testid={testIdFor(dataTestId, 'description')}
+        >
+          {description}
+        </Typography>
+      )}
+
+      {platform === 'ios' && (
+        <IosInstructions instructions={iosInstructions} dataTestId={dataTestId} />
+      )}
+    </Box>
+  </>
+);
+
+const InstallPromptActions: React.FC<{
+  platform: InstallPlatform;
+  installLabel: string;
+  dismissLabel: string;
+  onInstallClick: () => void;
+  onDismissClick: () => void;
+  dataTestId?: string;
+}> = ({ platform, installLabel, dismissLabel, onInstallClick, onDismissClick, dataTestId }) => (
+  <Box className="install-prompt-actions">
+    {platform === 'prompt' && (
+      <Button
+        size="small"
+        variant="contained"
+        onClick={onInstallClick}
+        data-testid={testIdFor(dataTestId, 'install')}
+      >
+        {installLabel}
+      </Button>
+    )}
+
+    <IconButton
+      size="small"
+      onClick={onDismissClick}
+      aria-label={dismissLabel}
+      data-testid={testIdFor(dataTestId, 'dismiss')}
+    >
+      <Close fontSize="small" />
+    </IconButton>
+  </Box>
+);
+
+/**
+ * A dismissible invitation to install the app, rendered only when the browser
+ * is actually able to install it and the user has not recently said no.
+ *
+ * Returns `null` in every other case — already installed, dismissed, or a
+ * browser with no install route at all — so it is safe to mount unconditionally
+ * in a layout rather than gating it at the call site.
+ *
+ * The copy defaults to English and every string is a prop: this package stays
+ * locale-neutral and the consuming app supplies its own wording.
+ */
+export const InstallPrompt = React.forwardRef<HTMLDivElement, InstallPromptProps>(
+  (
+    {
+      title = 'Install this app',
+      description,
+      installLabel = 'Install',
+      iosInstructions,
+      dismissLabel = 'Dismiss install prompt',
+      icon,
+      onInstall,
+      onDismiss,
+      storageKey,
+      dismissForDays,
+      className,
+      'data-testid': dataTestId = 'install-prompt',
+      ...props
+    },
+    ref,
+  ) => {
+    const { canInstall, platform, promptInstall, dismiss } = usePwaInstall({
+      storageKey,
+      dismissForDays,
+    });
+
+    const handleInstall = React.useCallback(() => {
+      void promptInstall().then((outcome) => onInstall?.(outcome));
+    }, [promptInstall, onInstall]);
+
+    const handleDismiss = React.useCallback(() => {
+      dismiss();
+      onDismiss?.();
+    }, [dismiss, onDismiss]);
+
+    if (!canInstall) {
+      return null;
+    }
+
+    return (
+      <StyledInstallPrompt
+        ref={ref}
+        className={className}
+        role="region"
+        aria-label={title}
+        data-testid={dataTestId}
+        {...props}
+      >
+        <InstallPromptBody
+          icon={icon}
+          title={title}
+          description={description}
+          iosInstructions={iosInstructions}
+          platform={platform}
+          dataTestId={dataTestId}
+        />
+
+        <InstallPromptActions
+          platform={platform}
+          installLabel={installLabel}
+          dismissLabel={dismissLabel}
+          onInstallClick={handleInstall}
+          onDismissClick={handleDismiss}
+          dataTestId={dataTestId}
+        />
+      </StyledInstallPrompt>
+    );
+  },
+);
+
+InstallPrompt.displayName = 'InstallPrompt';

package/src/components/utility/InstallPrompt/InstallPrompt.types.ts

@@ -0,0 +1,78 @@
+import type { ReactNode } from 'react';
+
+/**
+ * The Chromium-only event that makes a PWA installable from inside the page.
+ * It is NOT in TypeScript's DOM lib because it is not a standard: Safari and
+ * Firefox never fire it, so the spec never absorbed it.
+ *
+ * The event is a one-shot handle. Once `prompt()` resolves, the browser
+ * discards it; a later install attempt needs the NEXT event the browser emits,
+ * not this one held over.
+ */
+export interface BeforeInstallPromptEvent extends Event {
+  readonly platforms: string[];
+  readonly userChoice: Promise<{ outcome: 'accepted' | 'dismissed'; platform: string }>;
+  prompt: () => Promise<void>;
+}
+
+/**
+ * How — or whether — this browser can install the app.
+ *
+ * `ios` exists as its own case because iOS Safari can install but refuses to be
+ * asked: there is no programmatic route, only Share → Add to Home Screen. A
+ * host that collapses it into `unsupported` shows nothing to the largest slice
+ * of a mobile storefront's traffic.
+ */
+export type InstallPlatform = 'prompt' | 'ios' | 'unsupported';
+
+/** Result of asking the browser to install. `unavailable` = there was no live prompt to fire. */
+export type InstallOutcome = 'accepted' | 'dismissed' | 'unavailable';
+
+export interface UsePwaInstallOptions {
+  /** localStorage key holding the dismissal timestamp. */
+  storageKey?: string;
+  /** Days a dismissal suppresses the prompt for. `0` suppresses it permanently. */
+  dismissForDays?: number;
+  /** Fired once the browser reports the app was installed. */
+  onInstalled?: () => void;
+}
+
+export interface PwaInstallState {
+  /** True only when an install affordance should actually be rendered. */
+  canInstall: boolean;
+  /** Which install route this browser offers. */
+  platform: InstallPlatform;
+  /** True when already running as an installed app. */
+  isInstalled: boolean;
+  /** Fires the native prompt. Must be called from a user gesture. */
+  promptInstall: () => Promise<InstallOutcome>;
+  /** Suppresses the affordance for `dismissForDays`. */
+  dismiss: () => void;
+}
+
+export interface InstallPromptProps {
+  /** Headline text. */
+  title?: string;
+  /** Supporting line under the title. */
+  description?: string;
+  /** Label for the install button (Chromium only). */
+  installLabel?: string;
+  /** Replaces the built-in iOS Share → Add to Home Screen wording. */
+  iosInstructions?: ReactNode;
+  /** Accessible label for the dismiss button. */
+  dismissLabel?: string;
+  /** Leading icon. Defaults to an install glyph. */
+  icon?: ReactNode;
+  /** Called with the outcome after the native prompt resolves. */
+  onInstall?: (outcome: InstallOutcome) => void;
+  /** Called when the user dismisses the prompt. */
+  onDismiss?: () => void;
+  /** localStorage key holding the dismissal timestamp. */
+  storageKey?: string;
+  /** Days a dismissal suppresses the prompt for. `0` suppresses it permanently. */
+  dismissForDays?: number;
+  /** Custom CSS class name. */
+  className?: string;
+  /** Test ID for component testing. */
+  'data-testid'?: string;
+}