@12-apps/ui 1.0.0 → 1.3.1

package/src/components/utility/InstallPrompt/__tests__/InstallPrompt.ios.test.tsx

@@ -0,0 +1,65 @@
+/**
+ * `InstallPrompt` on iOS Safari.
+ *
+ * Its own file because the platform probe has to be replaced at module scope,
+ * and `vi.mock` is hoisted over the whole file — the Chromium cases in
+ * `usePwaInstall.test.tsx` must keep the real probe.
+ *
+ * What matters here is the ABSENCE of the install button. Safari exposes no way
+ * to open its own Add to Home Screen sheet, so a button on iOS would be a
+ * control that does nothing when tapped; the instructions take its place.
+ */
+import { render, screen, waitFor } from '@testing-library/react';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { InstallPrompt } from '../index';
+
+vi.mock('../InstallPrompt.helpers', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('../InstallPrompt.helpers')>();
+
+  return { ...actual, resolveInstallPlatform: () => 'ios' as const };
+});
+
+describe('InstallPrompt on iOS Safari', () => {
+  afterEach(() => {
+    window.localStorage.clear();
+  });
+
+  it('shows without waiting for an event that iOS never fires', async () => {
+    render(<InstallPrompt title="Instalar FutureDrink" />);
+
+    await waitFor(() => {
+      expect(screen.getByTestId('install-prompt')).toBeInTheDocument();
+    });
+    expect(screen.getByTestId('install-prompt-title')).toHaveTextContent('Instalar FutureDrink');
+  });
+
+  it('offers instructions instead of an install button', async () => {
+    render(<InstallPrompt />);
+
+    await waitFor(() => {
+      expect(screen.getByTestId('install-prompt-ios-instructions')).toBeInTheDocument();
+    });
+    await waitFor(() => {
+      expect(screen.queryByTestId('install-prompt-install')).not.toBeInTheDocument();
+    });
+  });
+
+  it('accepts host-supplied instruction copy', async () => {
+    render(<InstallPrompt iosInstructions={<span>Toque em Compartilhar</span>} />);
+
+    await waitFor(() => {
+      expect(screen.getByTestId('install-prompt-ios-instructions')).toHaveTextContent(
+        'Toque em Compartilhar',
+      );
+    });
+  });
+
+  it('can still be dismissed', async () => {
+    render(<InstallPrompt />);
+
+    await waitFor(() => {
+      expect(screen.getByTestId('install-prompt-dismiss')).toBeInTheDocument();
+    });
+  });
+});

package/src/components/utility/InstallPrompt/__tests__/usePwaInstall.test.tsx

@@ -0,0 +1,271 @@
+/**
+ * `usePwaInstall` / `InstallPrompt` — the machinery that turns an installable
+ * site into one that actually asks.
+ *
+ * The regression this file exists for: a manifest and a service worker satisfy
+ * every installability criterion a browser checks, and still produce no prompt
+ * of any kind, because nothing in the page captures `beforeinstallprompt`. The
+ * `preventDefault` case below guards that hole — without that call the browser
+ * reclaims the event and the app can never install itself.
+ *
+ * The iOS branch lives in `InstallPrompt.ios.test.tsx`, which needs a
+ * module-level mock this file must not carry.
+ */
+import { fireEvent, render, screen, waitFor } from '@testing-library/react';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { InstallPrompt } from '../index';
+import {
+  isDismissalActive,
+  isIosSafariAgent,
+  readDismissedAt,
+  writeDismissedAt,
+} from '../InstallPrompt.helpers';
+import type { BeforeInstallPromptEvent } from '../InstallPrompt.types';
+import { usePwaInstall } from '../usePwaInstall';
+
+const STORAGE_KEY = 'pwa-install-dismissed';
+
+// A fixed clock. Deriving expectations from the real `Date.now()` would make
+// them depend on how long the test took to run.
+const NOW = 1_700_000_000_000;
+const DAY = 86_400_000;
+
+type MockPromptEvent = BeforeInstallPromptEvent & { prompt: ReturnType<typeof vi.fn> };
+
+/**
+ * Stands in for the Chromium event: `prompt()` records that it was called and
+ * `userChoice` resolves with whatever answer the test wants the user to give.
+ */
+const createPromptEvent = (outcome: 'accepted' | 'dismissed'): MockPromptEvent => {
+  const event = new Event('beforeinstallprompt') as MockPromptEvent;
+
+  Object.assign(event, {
+    platforms: ['web'],
+    prompt: vi.fn().mockResolvedValue(undefined),
+    userChoice: Promise.resolve({ outcome, platform: 'web' }),
+  });
+
+  return event;
+};
+
+/** Renders the hook's state into the DOM so assertions can read it directly. */
+const HookProbe = ({ dismissForDays }: { dismissForDays?: number }) => {
+  const { canInstall, platform, isInstalled } = usePwaInstall({ dismissForDays });
+
+  return (
+    <div>
+      <span data-testid="can-install">{String(canInstall)}</span>
+      <span data-testid="platform">{platform}</span>
+      <span data-testid="is-installed">{String(isInstalled)}</span>
+    </div>
+  );
+};
+
+const IPHONE_SAFARI =
+  'Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.0 Mobile/15E148 Safari/604.1';
+const IPADOS_SAFARI =
+  'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.0 Safari/605.1.15';
+const CHROME_ON_IOS =
+  'Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) CriOS/120.0 Mobile/15E148 Safari/604.1';
+const DESKTOP_CHROME =
+  'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36';
+
+describe('isIosSafariAgent', () => {
+  it('detects Safari on iPhone', () => {
+    expect(isIosSafariAgent(IPHONE_SAFARI, 5)).toBe(true);
+  });
+
+  it('detects iPadOS, which reports a Macintosh agent with touch points', () => {
+    expect(isIosSafariAgent(IPADOS_SAFARI, 5)).toBe(true);
+  });
+
+  it('rejects desktop Safari, which shares that agent but has no touch points', () => {
+    expect(isIosSafariAgent(IPADOS_SAFARI, 0)).toBe(false);
+  });
+
+  it('rejects Chrome on iOS, which cannot add to the home screen at all', () => {
+    expect(isIosSafariAgent(CHROME_ON_IOS, 5)).toBe(false);
+  });
+
+  it('rejects desktop Chrome', () => {
+    expect(isIosSafariAgent(DESKTOP_CHROME, 0)).toBe(false);
+  });
+});
+
+describe('InstallPrompt dismissal storage', () => {
+  afterEach(() => {
+    window.localStorage.clear();
+  });
+
+  it('reports no dismissal when nothing was ever stored', () => {
+    expect(readDismissedAt(STORAGE_KEY)).toBeNull();
+    expect(isDismissalActive(null, 30, NOW)).toBe(false);
+  });
+
+  it('round-trips a dismissal timestamp', () => {
+    writeDismissedAt(STORAGE_KEY, NOW);
+    expect(readDismissedAt(STORAGE_KEY)).toBe(NOW);
+  });
+
+  it('ignores a corrupted stored value instead of throwing', () => {
+    window.localStorage.setItem(STORAGE_KEY, 'not-a-number');
+    expect(readDismissedAt(STORAGE_KEY)).toBeNull();
+  });
+
+  it('keeps a dismissal active inside the window and expires it after', () => {
+    expect(isDismissalActive(NOW, 30, NOW + 29 * DAY)).toBe(true);
+    expect(isDismissalActive(NOW, 30, NOW + 31 * DAY)).toBe(false);
+  });
+
+  it('treats dismissForDays of 0 as permanent', () => {
+    expect(isDismissalActive(NOW, 0, NOW + 3650 * DAY)).toBe(true);
+  });
+
+  it('treats a future timestamp as active so a wound-back clock cannot re-prompt', () => {
+    expect(isDismissalActive(NOW + DAY, 30, NOW)).toBe(true);
+  });
+});
+
+describe('usePwaInstall', () => {
+  afterEach(() => {
+    window.localStorage.clear();
+  });
+
+  it('cannot install before the browser offers a prompt', async () => {
+    render(<HookProbe />);
+
+    await waitFor(() => {
+      expect(screen.getByTestId('platform')).toHaveTextContent('unsupported');
+    });
+    expect(screen.getByTestId('can-install')).toHaveTextContent('false');
+  });
+
+  it('becomes installable once beforeinstallprompt fires', async () => {
+    render(<HookProbe />);
+    fireEvent(window, createPromptEvent('accepted'));
+
+    await waitFor(() => {
+      expect(screen.getByTestId('can-install')).toHaveTextContent('true');
+    });
+    expect(screen.getByTestId('platform')).toHaveTextContent('prompt');
+  });
+
+  it('calls preventDefault so the deferred handle survives', async () => {
+    render(<HookProbe />);
+
+    const event = createPromptEvent('accepted');
+    const preventDefault = vi.spyOn(event, 'preventDefault');
+    fireEvent(window, event);
+
+    await waitFor(() => {
+      expect(preventDefault).toHaveBeenCalled();
+    });
+  });
+
+  // `dismissForDays: 0` makes the stored dismissal permanent, so this asserts
+  // that the hook consults storage at all without depending on the wall clock.
+  // The expiry arithmetic itself is covered above against a fixed clock.
+  it('stays suppressed while a dismissal is stored', async () => {
+    writeDismissedAt(STORAGE_KEY, NOW);
+
+    render(<HookProbe dismissForDays={0} />);
+    fireEvent(window, createPromptEvent('accepted'));
+
+    await waitFor(() => {
+      expect(screen.getByTestId('platform')).toHaveTextContent('prompt');
+    });
+    expect(screen.getByTestId('can-install')).toHaveTextContent('false');
+  });
+
+  it('reports installed and stays suppressed after appinstalled', async () => {
+    render(<HookProbe />);
+    fireEvent(window, createPromptEvent('accepted'));
+
+    await waitFor(() => {
+      expect(screen.getByTestId('can-install')).toHaveTextContent('true');
+    });
+
+    fireEvent(window, new Event('appinstalled'));
+
+    await waitFor(() => {
+      expect(screen.getByTestId('is-installed')).toHaveTextContent('true');
+    });
+    expect(screen.getByTestId('can-install')).toHaveTextContent('false');
+  });
+});
+
+describe('InstallPrompt', () => {
+  afterEach(() => {
+    window.localStorage.clear();
+  });
+
+  it('renders nothing until the browser offers a prompt', async () => {
+    render(<InstallPrompt />);
+
+    await waitFor(() => {
+      expect(screen.queryByTestId('install-prompt')).not.toBeInTheDocument();
+    });
+  });
+
+  it('appears with an install button once the prompt is captured', async () => {
+    render(<InstallPrompt title="Install FutureDrink" />);
+    fireEvent(window, createPromptEvent('accepted'));
+
+    await waitFor(() => {
+      expect(screen.getByTestId('install-prompt')).toBeInTheDocument();
+    });
+    expect(screen.getByTestId('install-prompt-install')).toBeInTheDocument();
+  });
+
+  it('fires the native prompt and reports the accepted outcome', async () => {
+    const onInstall = vi.fn();
+
+    render(<InstallPrompt onInstall={onInstall} />);
+    const event = createPromptEvent('accepted');
+    fireEvent(window, event);
+
+    await waitFor(() => {
+      expect(screen.getByTestId('install-prompt-install')).toBeInTheDocument();
+    });
+    fireEvent.click(screen.getByTestId('install-prompt-install'));
+
+    await waitFor(() => {
+      expect(onInstall).toHaveBeenCalledWith('accepted');
+    });
+    expect(event.prompt).toHaveBeenCalledTimes(1);
+  });
+
+  it('records a dismissal when the user declines the native dialog', async () => {
+    render(<InstallPrompt onInstall={vi.fn()} />);
+    fireEvent(window, createPromptEvent('dismissed'));
+
+    await waitFor(() => {
+      expect(screen.getByTestId('install-prompt-install')).toBeInTheDocument();
+    });
+    fireEvent.click(screen.getByTestId('install-prompt-install'));
+
+    await waitFor(() => {
+      expect(screen.queryByTestId('install-prompt')).not.toBeInTheDocument();
+    });
+    expect(readDismissedAt(STORAGE_KEY)).not.toBeNull();
+  });
+
+  it('hides and persists the dismissal when the close button is used', async () => {
+    const onDismiss = vi.fn();
+
+    render(<InstallPrompt onDismiss={onDismiss} />);
+    fireEvent(window, createPromptEvent('accepted'));
+
+    await waitFor(() => {
+      expect(screen.getByTestId('install-prompt-dismiss')).toBeInTheDocument();
+    });
+    fireEvent.click(screen.getByTestId('install-prompt-dismiss'));
+
+    await waitFor(() => {
+      expect(screen.queryByTestId('install-prompt')).not.toBeInTheDocument();
+    });
+    expect(onDismiss).toHaveBeenCalledTimes(1);
+    expect(readDismissedAt(STORAGE_KEY)).not.toBeNull();
+  });
+});

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

@@ -0,0 +1,10 @@
+export { InstallPrompt } from './InstallPrompt';
+export { usePwaInstall } from './usePwaInstall';
+export type {
+  BeforeInstallPromptEvent,
+  InstallOutcome,
+  InstallPlatform,
+  InstallPromptProps,
+  PwaInstallState,
+  UsePwaInstallOptions,
+} from './InstallPrompt.types';

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

@@ -0,0 +1,171 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+
+import {
+  DEFAULT_DISMISS_DAYS,
+  DEFAULT_STORAGE_KEY,
+  isDismissalActive,
+  isStandaloneDisplay,
+  readDismissedAt,
+  resolveInstallPlatform,
+  writeDismissedAt,
+} from './InstallPrompt.helpers';
+import type {
+  BeforeInstallPromptEvent,
+  InstallOutcome,
+  InstallPlatform,
+  PwaInstallState,
+  UsePwaInstallOptions,
+} from './InstallPrompt.types';
+
+/**
+ * Headless PWA install machinery.
+ *
+ * A manifest and a service worker make a site installABLE; they do not make it
+ * install. Chromium announces its willingness by firing `beforeinstallprompt`
+ * and then does nothing further on its own beyond a small address-bar icon most
+ * users never notice. Unless a page calls `preventDefault()` on that event and
+ * keeps it, the handle is gone and the app can never ask.
+ *
+ * That is the whole reason this hook exists. It captures the event, tracks the
+ * three states that should suppress an install invitation (already installed,
+ * recently dismissed, browser cannot install), and hands back a
+ * gesture-callable `promptInstall`.
+ *
+ * Every environment probe runs in an effect rather than in a state initialiser:
+ * touching `window` during render breaks SSR and desynchronises hydration, so
+ * the first paint deliberately reports `canInstall: false` and corrects itself
+ * on mount.
+ */
+
+/** Tracks whether the page is running as an installed app. */
+const useInstalledState = (onInstalled?: () => void) => {
+  const [isInstalled, setIsInstalled] = useState(false);
+
+  // Held in a ref, and refreshed in its own effect rather than during render, so
+  // that a caller passing an inline callback does not re-subscribe the listener
+  // on every render.
+  const onInstalledRef = useRef(onInstalled);
+  useEffect(() => {
+    onInstalledRef.current = onInstalled;
+  }, [onInstalled]);
+
+  useEffect(() => {
+    setIsInstalled(isStandaloneDisplay());
+
+    const markInstalled = () => {
+      setIsInstalled(true);
+      onInstalledRef.current?.();
+    };
+
+    window.addEventListener('appinstalled', markInstalled);
+    return () => window.removeEventListener('appinstalled', markInstalled);
+  }, []);
+
+  return isInstalled;
+};
+
+/**
+ * Captures and holds the deferred `beforeinstallprompt` event.
+ *
+ * The listener is attached on mount, which is normally AFTER the browser would
+ * have fired the event on a cold load. Chromium re-fires it on navigation and
+ * on re-evaluation of the install criteria, so a missed first event resolves
+ * itself; a host that needs the very first one can attach an early capture in
+ * its HTML entry point and re-dispatch it.
+ */
+const useDeferredPrompt = () => {
+  const deferredRef = useRef<BeforeInstallPromptEvent | null>(null);
+  const [promptReady, setPromptReady] = useState(false);
+
+  useEffect(() => {
+    const capture = (event: Event) => {
+      // Without preventDefault the browser owns the event and the handle dies
+      // with it — this is the line that makes an in-page install button possible.
+      event.preventDefault();
+      deferredRef.current = event as BeforeInstallPromptEvent;
+      setPromptReady(true);
+    };
+
+    window.addEventListener('beforeinstallprompt', capture);
+    return () => window.removeEventListener('beforeinstallprompt', capture);
+  }, []);
+
+  const clearPrompt = useCallback(() => {
+    deferredRef.current = null;
+    setPromptReady(false);
+  }, []);
+
+  return { deferredRef, promptReady, clearPrompt };
+};
+
+/** Reads and writes the "don't ask again for a while" record. */
+const useDismissal = (storageKey: string, dismissForDays: number) => {
+  const [dismissed, setDismissed] = useState(false);
+
+  useEffect(() => {
+    const dismissedAt = readDismissedAt(storageKey);
+    setDismissed(isDismissalActive(dismissedAt, dismissForDays, Date.now()));
+  }, [storageKey, dismissForDays]);
+
+  const persistDismissal = useCallback(() => {
+    writeDismissedAt(storageKey, Date.now());
+    setDismissed(true);
+  }, [storageKey]);
+
+  return { dismissed, persistDismissal };
+};
+
+/** Resolves the install route once the deferred-prompt state is known. */
+const useInstallPlatform = (promptReady: boolean): InstallPlatform => {
+  const [platform, setPlatform] = useState<InstallPlatform>('unsupported');
+
+  useEffect(() => {
+    setPlatform(resolveInstallPlatform(promptReady));
+  }, [promptReady]);
+
+  return platform;
+};
+
+export const usePwaInstall = (options: UsePwaInstallOptions = {}): PwaInstallState => {
+  const {
+    storageKey = DEFAULT_STORAGE_KEY,
+    dismissForDays = DEFAULT_DISMISS_DAYS,
+    onInstalled,
+  } = options;
+
+  const isInstalled = useInstalledState(onInstalled);
+  const { deferredRef, promptReady, clearPrompt } = useDeferredPrompt();
+  const { dismissed, persistDismissal } = useDismissal(storageKey, dismissForDays);
+  const platform = useInstallPlatform(promptReady);
+
+  const promptInstall = useCallback(async (): Promise<InstallOutcome> => {
+    const deferred = deferredRef.current;
+    if (!deferred) return 'unavailable';
+
+    await deferred.prompt();
+    const { outcome } = await deferred.userChoice;
+
+    // Single-use handle: spent whichever way the user answered. Chromium emits a
+    // fresh event if the app is still installable, so holding this one would
+    // only mean calling prompt() twice on a dead event.
+    clearPrompt();
+
+    // Declining the browser's own dialog is a real "no" — record it, or the
+    // affordance reappears on the next render and badgers the user.
+    if (outcome === 'dismissed') persistDismissal();
+
+    return outcome;
+  }, [deferredRef, clearPrompt, persistDismissal]);
+
+  // iOS has no event to wait for, so its affordance is gated on the platform
+  // probe alone; everywhere else a live captured prompt is the prerequisite.
+  const canInstall = !isInstalled && !dismissed && (platform === 'ios' || promptReady);
+
+  return {
+    canInstall,
+    platform,
+    isInstalled,
+    promptInstall,
+    dismiss: persistDismissal,
+  };
+};

package/src/components/utility/Transition/Transition.helpers.ts

@@ -0,0 +1,40 @@
+import type { Theme } from '@mui/material';
+
+import type { CustomTransitionProps, TransitionVariant } from './Transition.types';
+
+type Duration = NonNullable<CustomTransitionProps['duration']>;
+type Easing = NonNullable<CustomTransitionProps['easing']>;
+
+/** An explicit `duration` wins in either form; otherwise the variant picks one. */
+export const transitionDuration = (
+  theme: Theme,
+  variant: TransitionVariant,
+  duration?: Duration,
+): Duration => {
+  if (typeof duration === 'number' || typeof duration === 'object') return duration;
+
+  switch (variant) {
+    case 'slide':
+      return theme.transitions.duration.enteringScreen;
+    case 'fade':
+    case 'scale':
+    case 'grow':
+    case 'zoom':
+      return theme.transitions.duration.shorter;
+    default:
+      return theme.transitions.duration.standard;
+  }
+};
+
+/** As above: an explicit `easing` wins, otherwise the variant picks one. */
+export const transitionEasing = (
+  theme: Theme,
+  variant: TransitionVariant,
+  easing?: Easing,
+): Easing => {
+  if (typeof easing === 'string' || typeof easing === 'object') return easing;
+
+  return variant === 'slide'
+    ? theme.transitions.easing.easeOut
+    : theme.transitions.easing.easeInOut;
+};