@12-apps/ui 1.5.2 → 1.6.1

package/src/components/layout/ContentToolbar/ContentToolbar.tsx

@@ -98,6 +98,58 @@ function SelectionCluster({
   );
 }
 
+/**
+ * The BROWSING half of the toolbar: search + filters on the left, the page's
+ * own controls on the right. Split out of {@link ContentToolbar} so that
+ * function stays inside the complexity gate — it is layout only, and the
+ * decision of whether to show it at all is made by the caller.
+ */
+function BrowsingClusters({
+  leadingControls,
+  rightControls,
+  hasSelection,
+  edgeAlign,
+}: {
+  leadingControls?: React.ReactNode;
+  rightControls: React.ReactNode;
+  hasSelection: boolean;
+  edgeAlign: boolean;
+}): React.JSX.Element {
+  return (
+    <>
+      {/* minWidth:0 lets this cluster be the one that gives up width as the row
+       * tightens, which is what the filter overflow measures against. */}
+      {leadingControls !== undefined && (
+        <Box sx={{ display: 'flex', alignItems: 'center', flexGrow: 1, minWidth: 0 }}>
+          {leadingControls}
+        </Box>
+      )}
+      {/* ml:auto keeps the controls right-aligned even when the cluster wraps to
+       * its own row (where justify-content:space-between would otherwise snap a
+       * lone item to the left); it's a no-op on a shared row. */}
+      <Box
+        sx={{
+          display: 'flex',
+          alignItems: 'center',
+          // Same single-line rule as the row itself: this cluster wrapping
+          // INTERNALLY buys a second line just as surely as the row wrapping
+          // does. It bit at exactly 900px, the `md` breakpoint where the "N de
+          // N" counter appears and pushes Exibir/Exportar over the edge.
+          flexWrap: leadingControls === undefined ? 'wrap' : 'nowrap',
+          // Tight (5px) when browsing so the controls fit one line beside the
+          // checkbox; roomier (14px) in selection mode where they get their own row.
+          gap: hasSelection ? '14px' : '5px',
+          ml: 'auto',
+          mr: edgeAlign ? -1.5 : 0,
+          '& > *': { flexShrink: 0 },
+        }}
+      >
+        {rightControls}
+      </Box>
+    </>
+  );
+}
+
 /**
  * Shared toolbar for content pages (Favorites, Personal Space, Recents, …). The
  * left cluster owns selection chrome — **Select All**, and once items are
@@ -133,52 +185,56 @@ export function ContentToolbar({
   selectAll,
   clearSelection,
   rightControls,
+  leadingControls,
   actions,
   selectAllTestId,
   clearAllTestId,
   edgeAlign = false,
+  exclusiveSelection = false,
 }: ContentToolbarProps): React.JSX.Element {
+  // Under `exclusiveSelection` the two states are alternatives, not neighbours:
+  // browsing shows the controls and no checkbox, selecting shows the checkbox
+  // and no controls. Anything else double-books the row.
+  const showSelection = !exclusiveSelection || hasSelection;
+  const showControls = !exclusiveSelection || !hasSelection;
   return (
-    // Wrap the two clusters onto separate rows when they can't share one line
-    // (narrow screens / phones) instead of letting the controls collide.
+    // Two clusters on one line. They may wrap onto separate rows ONLY for a
+    // toolbar without `leadingControls` — one carrying search + filters is
+    // driven by a measured collapse ladder (see `useFilterOverflow`), and a
+    // wrap there is the ladder having failed: it would silently buy a second
+    // row instead of shedding a control into "Mais", which is the one outcome
+    // the ladder exists to prevent.
     <Box
       sx={{
         display: 'flex',
         alignItems: 'center',
         justifyContent: 'space-between',
         gap: 2,
-        flexWrap: 'wrap',
+        flexWrap: leadingControls === undefined ? 'wrap' : 'nowrap',
         rowGap: 1,
       }}
     >
-      <SelectionCluster
-        hasSelection={hasSelection}
-        selectedCount={selectedCount}
-        selectAll={selectAll}
-        clearSelection={clearSelection}
-        actions={actions}
-        selectAllTestId={selectAllTestId}
-        clearAllTestId={clearAllTestId}
-        edgeAlign={edgeAlign}
-      />
+      {showSelection && (
+        <SelectionCluster
+          hasSelection={hasSelection}
+          selectedCount={selectedCount}
+          selectAll={selectAll}
+          clearSelection={clearSelection}
+          actions={actions}
+          selectAllTestId={selectAllTestId}
+          clearAllTestId={clearAllTestId}
+          edgeAlign={edgeAlign}
+        />
+      )}
 
-      {/* ml:auto keeps the controls right-aligned even when the cluster wraps to
-       * its own row (where justify-content:space-between would otherwise snap a
-       * lone item to the left); it's a no-op on a shared row. */}
-      <Box
-        sx={{
-          display: 'flex',
-          alignItems: 'center',
-          flexWrap: 'wrap',
-          // Tight (5px) when browsing so the controls fit one line beside the
-          // checkbox; roomier (14px) in selection mode where they get their own row.
-          gap: hasSelection ? '14px' : '5px',
-          ml: 'auto',
-          mr: edgeAlign ? -1.5 : 0,
-        }}
-      >
-        {rightControls}
-      </Box>
+      {showControls && (
+        <BrowsingClusters
+          leadingControls={leadingControls}
+          rightControls={rightControls}
+          hasSelection={hasSelection}
+          edgeAlign={edgeAlign}
+        />
+      )}
     </Box>
   );
 }

package/src/components/layout/ContentToolbar/ContentToolbar.types.ts

@@ -14,6 +14,22 @@ export interface ContentToolbarProps {
   clearSelection: () => void;
   /** Page-specific right-aligned controls (ViewSelector, SortByDropdown, …). */
   rightControls: ReactNode;
+  /**
+   * Controls that share the toolbar's own line, left-aligned after the
+   * selection cluster — the search box and the filter controls, which belong on
+   * the toolbar rather than on a row of their own. Left unset the toolbar keeps
+   * its two-cluster shape.
+   */
+  leadingControls?: ReactNode;
+  /**
+   * Selection OWNS the toolbar line instead of sharing it. Nothing selected ⇒
+   * no Select All at all (the row is search + filters + controls); something
+   * selected ⇒ those give way entirely and only the selection cluster remains.
+   *
+   * Off by default: a toolbar that already shows Select All permanently keeps
+   * doing so, so this cannot move a control on a consumer that did not ask.
+   */
+  exclusiveSelection?: boolean;
   /**
    * Selection actions slot, rendered after the count when items are selected
    * (e.g. a "Delete" / "Send email" control). Kept generic — the consumer owns
@@ -134,6 +150,15 @@ export interface MultiSelectDropdownProps<TValue extends string = string> {
    */
   layout?: 'inline' | 'stacked' | 'pill';
   'data-testid'?: string;
+  /**
+   * Notified when the menu opens and closes.
+   *
+   * For a toolbar whose LAYOUT is measured: applying a filter changes this
+   * control's label and therefore its width, and re-measuring mid-interaction
+   * moves the row under the operator's cursor. A caller that measures uses this
+   * to hold still while the menu is open.
+   */
+  onOpenChange?: (open: boolean) => void;
 }
 
 /* ── FilterTrigger ───────────────────────────────────────────────────────── */

package/src/components/layout/ContentToolbar/MultiSelectDropdown.tsx

@@ -67,6 +67,7 @@ export function MultiSelectDropdown<TValue extends string = string>({
   noResultsLabel = 'No results',
   layout = 'inline',
   'data-testid': testId,
+  onOpenChange,
 }: MultiSelectDropdownProps<TValue>): React.JSX.Element {
   const [anchorEl, setAnchorEl] = useState<HTMLElement | null>(null);
   const [query, setQuery] = useState('');
@@ -76,6 +77,7 @@ export function MultiSelectDropdown<TValue extends string = string>({
   const close = (): void => {
     setAnchorEl(null);
     setQuery('');
+    onOpenChange?.(false);
   };
   const triggerLabel = buildTriggerLabel(selected, options, allLabel);
   // Auto-enable search for long lists (e.g. many categories) unless overridden.
@@ -83,7 +85,10 @@ export function MultiSelectDropdown<TValue extends string = string>({
   const anyExtraChecked = extraOptions?.some((option) => option.checked) ?? false;
   const clearDisabled = selected.size === 0 && !anyExtraChecked;
 
-  const openMenu = (event: React.MouseEvent<HTMLElement>): void => setAnchorEl(event.currentTarget);
+  const openMenu = (event: React.MouseEvent<HTMLElement>): void => {
+    setAnchorEl(event.currentTarget);
+    onOpenChange?.(true);
+  };
   const triggerProps = { triggerLabel, open, onOpen: openMenu, testId };
 
   const renderTrigger = (): React.JSX.Element => {

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

@@ -0,0 +1,117 @@
+import type { BeforeInstallPromptEvent, PwaInstallStash } from './InstallPrompt.types';
+
+/**
+ * Holds `beforeinstallprompt` from before the app exists.
+ *
+ * `usePwaInstall` cannot attach its own listener early enough, and no React
+ * hook can. Chromium fires the event once, during initial page load, the
+ * moment it has a manifest and a registered worker — which in a real app is
+ * before hydration, and often before the chunk containing the component has
+ * even been downloaded. A listener registered in an effect is not late by
+ * milliseconds; it can be late by entire navigations. Nothing calls
+ * `preventDefault()` in time, the browser keeps the event, and the page can
+ * never ask again.
+ *
+ * So the capture has to live outside React, and the host has to install it as
+ * the very first thing the document does. Two supported ways, in order of
+ * reliability:
+ *
+ * 1. An inline `<script>` in `<head>`, which beats a deferred module bundle:
+ *
+ *        <script>
+ *          window.addEventListener('beforeinstallprompt', function (e) {
+ *            e.preventDefault();
+ *            var s = (window.__pwaInstall = window.__pwaInstall || {});
+ *            s.event = e; s.firedAt = Date.now();
+ *            window.dispatchEvent(new Event('pwa-install-available'));
+ *          });
+ *        </script>
+ *
+ * 2. `capturePwaInstallEvent()` as the first statement of the entry module,
+ *    before `createRoot`. Simpler to wire and correct in most apps, but a
+ *    module is still deferred, so a very early event can outrun it.
+ *
+ * Both write the same shape, so the hook does not care which was used.
+ */
+
+/** Property on `window` holding the captured event. Shared with the inline snippet. */
+export const PWA_INSTALL_STASH_KEY = '__pwaInstall';
+
+/** Fired after a capture, so an app already running can adopt the event. */
+export const PWA_INSTALL_AVAILABLE_EVENT = 'pwa-install-available';
+
+type StashHost = Window & { [PWA_INSTALL_STASH_KEY]?: PwaInstallStash };
+
+/** The stash, or `null` when no capture ever ran (SSR, or a host that skipped wiring). */
+export const readPwaInstallStash = (): PwaInstallStash | null => {
+  if (typeof window === 'undefined') return null;
+  return (window as StashHost)[PWA_INSTALL_STASH_KEY] ?? null;
+};
+
+const ensureStash = (): PwaInstallStash => {
+  const host = window as StashHost;
+  host[PWA_INSTALL_STASH_KEY] ??= { event: null, firedAt: null, installedAt: null };
+  return host[PWA_INSTALL_STASH_KEY];
+};
+
+/**
+ * The teardown for the capture currently running, so `resetPwaInstallStash`
+ * can unwind completely. Held here rather than on the stash because it must
+ * survive the stash being deleted, and because it must never be serialised
+ * into the diagnostic payload.
+ */
+let activeTeardown: (() => void) | null = null;
+
+/**
+ * Starts capturing. Returns a teardown, and is safe to call twice — a second
+ * call is a no-op rather than a duplicate listener, so a host that wires both
+ * the inline snippet and this function does not double-handle the event.
+ */
+export const capturePwaInstallEvent = (): (() => void) => {
+  if (typeof window === 'undefined') return () => undefined;
+
+  const stash = ensureStash();
+  if (stash.capturing === true) return () => undefined;
+  stash.capturing = true;
+
+  const onBeforeInstall = (event: Event): void => {
+    // The line the whole component depends on. Without it the browser owns the
+    // event, shows at most its own mini-infobar, and discards the handle.
+    event.preventDefault();
+    stash.event = event as BeforeInstallPromptEvent;
+    stash.firedAt = Date.now();
+    window.dispatchEvent(new Event(PWA_INSTALL_AVAILABLE_EVENT));
+  };
+
+  const onInstalled = (): void => {
+    stash.installedAt = Date.now();
+    stash.event = null;
+  };
+
+  window.addEventListener('beforeinstallprompt', onBeforeInstall);
+  window.addEventListener('appinstalled', onInstalled);
+
+  const teardown = () => {
+    window.removeEventListener('beforeinstallprompt', onBeforeInstall);
+    window.removeEventListener('appinstalled', onInstalled);
+    stash.capturing = false;
+    if (activeTeardown === teardown) activeTeardown = null;
+  };
+
+  activeTeardown = teardown;
+  return teardown;
+};
+
+/**
+ * Returns the page to its pre-capture state: listeners removed, stash gone.
+ *
+ * Exists for tests and stories, which need a clean page per case. It unwinds
+ * the listeners as well as the data, because a leaked capture from a previous
+ * case would go on suppressing events that the next case expects to observe.
+ */
+export const resetPwaInstallStash = (): void => {
+  if (typeof window === 'undefined') return;
+  activeTeardown?.();
+  activeTeardown = null;
+  delete (window as StashHost)[PWA_INSTALL_STASH_KEY];
+};

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

@@ -85,6 +85,54 @@ raised from a timer or an effect.
 All copy defaults to English and every string is a prop — this package is
 locale-neutral and the consuming app supplies its own wording.
 
+## Wiring the capture
+
+**Required on Chromium.** Without it this component can never offer an install,
+and it will fail silently — no error, no warning, just an affordance that never
+appears.
+
+Chromium fires `beforeinstallprompt` once, during page load, as soon as it has a
+manifest and a registered worker. That is before hydration, and in a code-split
+app it can be before the chunk holding this component has been downloaded at
+all. No React hook can attach a listener in time, and the event is not reissued
+on request. So the capture has to run outside React, and first.
+
+Paste this into `<head>`, above the app bundle. A classic inline script is the
+only thing guaranteed to beat a deferred module:
+
+```html
+<script>
+  (function () {
+    var stash = (window.__pwaInstall = { event: null, firedAt: null, installedAt: null });
+    window.addEventListener('beforeinstallprompt', function (event) {
+      event.preventDefault();
+      stash.event = event;
+      stash.firedAt = Date.now();
+      window.dispatchEvent(new Event('pwa-install-available'));
+    });
+    window.addEventListener('appinstalled', function () {
+      stash.installedAt = Date.now();
+      stash.event = null;
+    });
+  })();
+</script>
+```
+
+Or call `capturePwaInstallEvent()` as the first statement of your entry module,
+before `createRoot`. Simpler to wire, but a module is still deferred, so a very
+early event can outrun it. Doing both is safe — the capture is idempotent.
+
+```ts
+import { capturePwaInstallEvent } from '@12-apps/ui/utility/InstallPrompt';
+
+capturePwaInstallEvent();
+```
+
+`readPwaInstallStash()` exposes what was captured (`event`, `firedAt`,
+`installedAt`), which is worth logging when the prompt does not appear:
+`firedAt` set with no visible affordance means something downstream suppressed
+it, whereas an absent stash means the wiring above is missing.
+
 ## Hook API
 
 `usePwaInstall(options)` returns:
@@ -107,7 +155,7 @@ locale-neutral and the consuming app supplies its own wording.
 - **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.
+- **A missed event does NOT recover.** Chromium fires `beforeinstallprompt` once
+  and will not reissue it on request, so a listener that attaches on mount has
+  already lost. This is why "Wiring the capture" above is a requirement rather
+  than an optimisation.

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

@@ -15,6 +15,25 @@ export interface BeforeInstallPromptEvent extends Event {
   prompt: () => Promise<void>;
 }
 
+/**
+ * What the pre-React capture left on `window` for the hook to pick up.
+ *
+ * This is the handoff between code that runs before the app exists and code
+ * that runs inside it. Written either by `capturePwaInstallEvent()` or by the
+ * equivalent inline snippet in the host's HTML, and read on mount — the event
+ * has almost always fired long before any component is alive to hear it.
+ */
+export interface PwaInstallStash {
+  /** The held event, or `null` if none has fired or it was already spent. */
+  event: BeforeInstallPromptEvent | null;
+  /** When it was captured. Diagnostic: proves the capture ran and the browser offered. */
+  firedAt: number | null;
+  /** When `appinstalled` was seen, if it arrived before the app mounted. */
+  installedAt: number | null;
+  /** Guards against a host wiring both the inline snippet and the function. */
+  capturing?: boolean;
+}
+
 /**
  * How — or whether — this browser can install the app.
  *

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

@@ -1,10 +1,18 @@
 export { InstallPrompt } from './InstallPrompt';
 export { usePwaInstall } from './usePwaInstall';
+export {
+  capturePwaInstallEvent,
+  readPwaInstallStash,
+  resetPwaInstallStash,
+  PWA_INSTALL_AVAILABLE_EVENT,
+  PWA_INSTALL_STASH_KEY,
+} from './InstallPrompt.earlyCapture';
 export type {
   BeforeInstallPromptEvent,
   InstallOutcome,
   InstallPlatform,
   InstallPromptProps,
   PwaInstallState,
+  PwaInstallStash,
   UsePwaInstallOptions,
 } from './InstallPrompt.types';

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

@@ -1,5 +1,6 @@
 import { useCallback, useEffect, useRef, useState } from 'react';
 
+import { PWA_INSTALL_AVAILABLE_EVENT, readPwaInstallStash } from './InstallPrompt.earlyCapture';
 import {
   DEFAULT_DISMISS_DAYS,
   DEFAULT_STORAGE_KEY,
@@ -50,7 +51,9 @@ const useInstalledState = (onInstalled?: () => void) => {
   }, [onInstalled]);
 
   useEffect(() => {
-    setIsInstalled(isStandaloneDisplay());
+    // `appinstalled` can also land before the app mounts, so the stash is
+    // consulted for the same reason the deferred event is.
+    setIsInstalled(isStandaloneDisplay() || readPwaInstallStash()?.installedAt != null);
 
     const markInstalled = () => {
       setIsInstalled(true);
@@ -65,29 +68,54 @@ const useInstalledState = (onInstalled?: () => void) => {
 };
 
 /**
- * Captures and holds the deferred `beforeinstallprompt` event.
+ * 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.
+ * The stash written by `capturePwaInstallEvent` is the PRIMARY source, not a
+ * fallback. Chromium fires the event once, during initial page load; a
+ * listener attached in an effect runs after hydration and, when the component
+ * is code-split, after a download that may not happen until a later route. In
+ * a real browser it essentially never catches the event, and the event is not
+ * reissued on request — so a hook that relies on its own listener reports
+ * "cannot install" forever on the one platform that can.
+ *
+ * The live listeners below therefore cover only the narrow case they can
+ * actually serve: a browser re-evaluating installability while the app is
+ * already running, and a host that never wired the capture at all.
  */
 const useDeferredPrompt = () => {
   const deferredRef = useRef<BeforeInstallPromptEvent | null>(null);
   const [promptReady, setPromptReady] = useState(false);
 
   useEffect(() => {
+    const hold = (event: BeforeInstallPromptEvent) => {
+      deferredRef.current = event;
+      setPromptReady(true);
+    };
+
+    // Whatever fired before this component existed.
+    const held = readPwaInstallStash()?.event;
+    if (held) hold(held);
+
+    // The capture rang the bell after mount: adopt what it is holding.
+    const adopt = () => {
+      const fresh = readPwaInstallStash()?.event;
+      if (fresh) hold(fresh);
+    };
+
     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.
+      // with it. The capture has normally done this already; repeating it is
+      // harmless and keeps the hook correct on a host that skipped wiring.
       event.preventDefault();
-      deferredRef.current = event as BeforeInstallPromptEvent;
-      setPromptReady(true);
+      hold(event as BeforeInstallPromptEvent);
     };
 
+    window.addEventListener(PWA_INSTALL_AVAILABLE_EVENT, adopt);
     window.addEventListener('beforeinstallprompt', capture);
-    return () => window.removeEventListener('beforeinstallprompt', capture);
+    return () => {
+      window.removeEventListener(PWA_INSTALL_AVAILABLE_EVENT, adopt);
+      window.removeEventListener('beforeinstallprompt', capture);
+    };
   }, []);
 
   const clearPrompt = useCallback(() => {