@marinoscar/platform-web 0.1.0-next.3 → 0.1.0-next.4

package/dist/host/ui/install-prompt.d.ts

@@ -0,0 +1,57 @@
+import type { ReactNode } from 'react';
+/**
+ * Props of {@link InstallPrompt}.
+ *
+ * @stability experimental
+ */
+export interface InstallPromptProps {
+    /** The product name the offer's message uses. */
+    appName: string;
+    /**
+     * An icon drawn before the message (the app's mark). Omitted, the offer is
+     * the plain text message it always was.
+     */
+    icon?: ReactNode;
+    /**
+     * The offer's words. Every member is optional and falls back to the platform
+     * wording: `body` to "Install <appName> for faster access and notifications",
+     * `install` to "Install", `dismiss` (the dismiss button's accessible name) to
+     * "Dismiss install prompt". `title` has no default; when set, it is drawn as
+     * a bold line above the body.
+     */
+    copy?: InstallPromptCopy;
+}
+/**
+ * The words of an {@link InstallPrompt}, each optional.
+ *
+ * @stability experimental
+ */
+export interface InstallPromptCopy {
+    /** A bold line above the body. No default. */
+    title?: ReactNode;
+    /** The offer. Default: "Install <appName> for faster access and notifications". */
+    body?: ReactNode;
+    /** The install button's label. Default "Install". */
+    install?: string;
+    /** The dismiss button's accessible name. Default "Dismiss install prompt". */
+    dismiss?: string;
+}
+/**
+ * The "install this app" offer: captures `beforeinstallprompt`, shows a
+ * bottom-left snackbar, remembers a dismissal in `localStorage`, and renders
+ * `null` when installed, dismissed or not offered. Mount it once, outside
+ * the routes.
+ *
+ * @param props - see {@link InstallPromptProps}.
+ * @returns the snackbar, or `null`.
+ *
+ * @example
+ * ```tsx
+ * <InstallPrompt appName={APP_NAME} />
+ * ```
+ *
+ * @extensionPoint component
+ * @stability experimental
+ */
+export declare function InstallPrompt({ appName, icon, copy }: InstallPromptProps): import("react").JSX.Element | null;
+//# sourceMappingURL=install-prompt.d.ts.map

package/dist/host/ui/install-prompt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"install-prompt.d.ts","sourceRoot":"","sources":["../../../src/host/ui/install-prompt.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAgHvC;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,iDAAiD;IACjD,OAAO,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,iBAAiB,CAAC;CAC1B;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,8CAA8C;IAC9C,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,mFAAmF;IACnF,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,qDAAqD;IACrD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,8EAA8E;IAC9E,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,aAAa,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,kBAAkB,sCAqHxE"}

package/dist/host/ui/install-prompt.js

@@ -0,0 +1,156 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { useCallback, useEffect, useState } from 'react';
+import { Box, Button, IconButton, Snackbar, Stack, Typography } from '@mui/material';
+import { Close as CloseIcon } from '@mui/icons-material';
+/**
+ * Follows `ThemeContext`'s `theme_mode` naming for the same reason: these keys
+ * share one origin-wide namespace, so they read as one set or they read as
+ * accidents.
+ */
+const INSTALL_DISMISSED_KEY = 'pwa_install_dismissed';
+/**
+ * EVERY `localStorage` ACCESS IN THIS FILE IS WRAPPED, and that is not
+ * defensive padding. `localStorage` is not merely empty in Safari's private
+ * mode and under a "block third-party cookies" policy in an iframe — the
+ * getter itself THROWS (`SecurityError`) on property access. An unguarded read
+ * during render would take the whole app down with a white screen, for a
+ * feature whose entire job is a dismissible suggestion.
+ *
+ * The failure mode of the fallback is that the offer reappears on the next
+ * visit, which is the correct thing to be wrong about.
+ */
+function readDismissed() {
+    try {
+        return window.localStorage.getItem(INSTALL_DISMISSED_KEY) === 'true';
+    }
+    catch {
+        return false;
+    }
+}
+function writeDismissed() {
+    try {
+        window.localStorage.setItem(INSTALL_DISMISSED_KEY, 'true');
+    }
+    catch {
+        // Nothing to recover: the dismissal still holds for this page's lifetime
+        // through React state, it just will not survive a reload.
+    }
+}
+/**
+ * Whether the app is already running as an installed app.
+ *
+ * Both checks are needed and neither is redundant: `display-mode: standalone`
+ * is the standard signal every Chromium browser answers, and
+ * `navigator.standalone` is the pre-standard one iOS Safari answers instead.
+ * `matchMedia` is called defensively — some embedded webviews do not implement
+ * it, and a `TypeError` here would be a crash rather than a missing suggestion.
+ */
+function isRunningInstalled() {
+    try {
+        if (window.matchMedia?.('(display-mode: standalone)').matches) {
+            return true;
+        }
+    }
+    catch {
+        // Fall through to the iOS flag.
+    }
+    return window.navigator.standalone === true;
+}
+/**
+ * The "install this app" offer: captures `beforeinstallprompt`, shows a
+ * bottom-left snackbar, remembers a dismissal in `localStorage`, and renders
+ * `null` when installed, dismissed or not offered. Mount it once, outside
+ * the routes.
+ *
+ * @param props - see {@link InstallPromptProps}.
+ * @returns the snackbar, or `null`.
+ *
+ * @example
+ * ```tsx
+ * <InstallPrompt appName={APP_NAME} />
+ * ```
+ *
+ * @extensionPoint component
+ * @stability experimental
+ */
+export function InstallPrompt({ appName, icon, copy }) {
+    /**
+     * The captured event. Holding it is the whole trick: the browser only offers
+     * it once, and `prompt()` may only be called on it in response to the user's
+     * gesture — which has not happened yet at capture time.
+     */
+    const [installEvent, setInstallEvent] = useState(null);
+    const [dismissed, setDismissed] = useState(readDismissed);
+    const [installed, setInstalled] = useState(isRunningInstalled);
+    useEffect(() => {
+        const handleBeforeInstallPrompt = (event) => {
+            // Suppresses Chromium's own mini-infobar, which appears at a moment of
+            // the browser's choosing, over the app's content, with no relationship
+            // to what the user is doing. Preventing it is what earns the right to
+            // show the offer below instead — and it is required before the event can
+            // be deferred at all.
+            event.preventDefault();
+            setInstallEvent(event);
+        };
+        const handleAppInstalled = () => {
+            // Fires when the install completes THROUGH ANY ROUTE — including the
+            // browser's own omnibox affordance, which this component knows nothing
+            // about. Without this, an app installed from the address bar leaves the
+            // "install" offer sitting on screen in the tab that is still open.
+            setInstallEvent(null);
+            setInstalled(true);
+        };
+        window.addEventListener('beforeinstallprompt', handleBeforeInstallPrompt);
+        window.addEventListener('appinstalled', handleAppInstalled);
+        return () => {
+            window.removeEventListener('beforeinstallprompt', handleBeforeInstallPrompt);
+            window.removeEventListener('appinstalled', handleAppInstalled);
+        };
+    }, []);
+    const install = useCallback(() => {
+        if (!installEvent)
+            return;
+        // Cleared FIRST, unconditionally: the deferred event is single-use, so a
+        // second `prompt()` on it rejects. Dropping the reference here also closes
+        // this snackbar the moment the browser's own dialog takes over, which is
+        // the only sensible thing for it to do while a native modal is up.
+        setInstallEvent(null);
+        void installEvent.prompt().catch(() => {
+            // The browser declined to show the dialog (already installed in another
+            // window, gesture no longer trusted). There is nothing to tell the user
+            // that they can act on, and the offer is gone from this page either way.
+        });
+    }, [installEvent]);
+    const dismiss = useCallback(() => {
+        setDismissed(true);
+        setInstallEvent(null);
+        // Persisted, and permanently. Re-asking on every visit is how an install
+        // prompt becomes the thing users learn to dismiss without reading. The user
+        // is not stranded by this: the browser keeps its own install affordance in
+        // the omnibox / menu, which is where someone who changes their mind looks.
+        writeDismissed();
+    }, []);
+    if (installed || dismissed || !installEvent) {
+        return null;
+    }
+    const defaultBody = `Install ${appName} for faster access and notifications`;
+    return (_jsx(Snackbar, { open: true, 
+        // No auto-hide. This is an offer, not a status message: it should be
+        // answered, not outwaited. `clickaway` is ignored below for the same
+        // reason — typing in the page behind it is not an answer.
+        onClose: (_event, reason) => {
+            if (reason === 'clickaway')
+                return;
+            dismiss();
+        }, message: icon !== undefined || copy?.title !== undefined ? (_jsxs(Stack, { direction: "row", spacing: 1.5, sx: { alignItems: 'center' }, children: [icon, _jsxs(Box, { children: [copy?.title !== undefined && _jsx(Typography, { sx: { fontWeight: 600 }, children: copy.title }), copy?.body ?? defaultBody] })] })) : ((copy?.body ?? defaultBody)), 
+        // Matches `UpdatePrompt`'s offset for the same reason — it clears the
+        // fixed `BottomNav`, which exists only below `sm`. A static responsive
+        // style, not a `useMediaQuery` mount gate.
+        //
+        // Both prompts anchor bottom-left, so in the rare moment they are both
+        // open they overlap. Left alone deliberately: staggering them would mean
+        // one component knowing about the other's state, and the overlap needs a
+        // deploy to land in the same seconds as a first-time install offer.
+        sx: { bottom: { xs: 72, sm: 24 } }, action: _jsxs(_Fragment, { children: [_jsx(Button, { color: "secondary", size: "small", onClick: install, children: copy?.install ?? 'Install' }), _jsx(IconButton, { size: "small", "aria-label": copy?.dismiss ?? 'Dismiss install prompt', color: "inherit", onClick: dismiss, children: _jsx(CloseIcon, { fontSize: "small" }) })] }) }));
+}
+//# sourceMappingURL=install-prompt.js.map

package/dist/host/ui/install-prompt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"install-prompt.js","sourceRoot":"","sources":["../../../src/host/ui/install-prompt.tsx"],"names":[],"mappings":"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"}

package/dist/host/ui/loading-spinner.d.ts

@@ -0,0 +1,2 @@
+export declare function LoadingSpinner(): import("react").JSX.Element;
+//# sourceMappingURL=loading-spinner.d.ts.map

package/dist/host/ui/loading-spinner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loading-spinner.d.ts","sourceRoot":"","sources":["../../../src/host/ui/loading-spinner.tsx"],"names":[],"mappings":"AAMA,wBAAgB,cAAc,gCAM7B"}

package/dist/host/ui/loading-spinner.js

@@ -0,0 +1,9 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+// The page's loading state: the same DOM and sx as the reference app's
+// `LoadingSpinner` (non-fullscreen), so a packaged page looks identical.
+// Private to the slice; not exported.
+import { Box, CircularProgress } from '@mui/material';
+export function LoadingSpinner() {
+    return (_jsx(Box, { sx: { display: 'flex', justifyContent: 'center', p: 3 }, children: _jsx(CircularProgress, { size: 40 }) }));
+}
+//# sourceMappingURL=loading-spinner.js.map

package/dist/host/ui/loading-spinner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loading-spinner.js","sourceRoot":"","sources":["../../../src/host/ui/loading-spinner.tsx"],"names":[],"mappings":";AAAA,uEAAuE;AACvE,yEAAyE;AACzE,sCAAsC;AAEtC,OAAO,EAAE,GAAG,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAEtD,MAAM,UAAU,cAAc;IAC5B,OAAO,CACL,KAAC,GAAG,IAAC,EAAE,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,cAAc,EAAE,QAAQ,EAAE,CAAC,EAAE,CAAC,EAAE,YAC1D,KAAC,gBAAgB,IAAC,IAAI,EAAE,EAAE,GAAI,GAC1B,CACP,CAAC;AACJ,CAAC"}

package/dist/host/ui/maintenance-banner.d.ts

@@ -0,0 +1,84 @@
+/**
+ * The bypassing administrator's reminder — issue #258, epic #254.
+ *
+ * =============================================================================
+ * WHY THIS IS NECESSARY AT ALL
+ * =============================================================================
+ *
+ * Everybody else finds out about a maintenance window by being refused. An
+ * administrator covered by `allowAdmins` is refused nothing: the application
+ * looks completely normal to them, which is exactly the person who then forgets
+ * it is on and leaves a deployment out of service overnight. Nothing in the
+ * ordinary UI would ever tell them otherwise, so this does.
+ *
+ * =============================================================================
+ * "BYPASSING" IS STRUCTURAL, NOT A CONDITION THIS COMPONENT EVALUATES
+ * =============================================================================
+ *
+ * It renders inside `Layout` — i.e. inside `MaintenanceGate`'s children. A
+ * viewer who is being BLOCKED never gets here at all; the gate has replaced the
+ * whole subtree with the maintenance screen. So "the window is open AND this
+ * component is rendering" already means "and this viewer is getting through",
+ * and there is no second predicate to write, invert, or get wrong.
+ *
+ * What is left to check is only whether the window is open, which takes the
+ * admin endpoint — the one thing an administrator who is being let through can
+ * still call.
+ *
+ * =============================================================================
+ * IT ASKS NOTHING OF THE API FOR ANYONE WHO COULD NOT READ THE ANSWER
+ * =============================================================================
+ *
+ * `GET /api/admin/maintenance` is `system_settings:read`. This component mounts
+ * in the shell for EVERY signed-in user, most of whom hold no such permission,
+ * so the permission is checked from the session already in memory and the hook
+ * is told not to fetch. Firing anyway would buy one predictable 403 per minute
+ * per viewer, on every deployment, forever.
+ *
+ * RENDERS `null` IN EVERY OTHER STATE — loading, error, no permission, window
+ * closed. It occupies no space until there is something true to say, which is
+ * also what keeps it out of the app's pixel baselines (`tests/visual/`).
+ */
+import type { ReactNode } from 'react';
+/**
+ * What {@link MaintenanceBanner} takes, both optional.
+ *
+ * @stability experimental
+ */
+export interface MaintenanceBannerProps {
+    /**
+     * Replaces the sentence under the title ("Everyone except administrators is
+     * being turned away." and the layer note). Omitted, the platform wording.
+     */
+    copy?: {
+        /** The message. */
+        message?: ReactNode;
+    };
+    /**
+     * Extra controls beside "Manage" (a status page link). Drawn before it.
+     * Omitted, "Manage" is the only action.
+     */
+    actions?: ReactNode;
+}
+/**
+ * The bypassing administrator's reminder: an `Alert` in the shell while a
+ * maintenance window is open. Renders `null` for everyone else (no
+ * `system_settings:read`, window closed, status not loaded, or the maintenance
+ * page itself), and never asks the API for a viewer who could not read the
+ * answer. Mount it inside {@link MaintenanceGate}'s children.
+ *
+ * @returns the banner element, or `null`.
+ *
+ * @example
+ * ```tsx
+ * <MaintenanceGate appName={APP_NAME}>
+ *   <MaintenanceBanner />
+ *   <Outlet />
+ * </MaintenanceGate>
+ * ```
+ *
+ * @extensionPoint component
+ * @stability experimental
+ */
+export declare function MaintenanceBanner({ copy, actions }?: MaintenanceBannerProps): import("react").JSX.Element | null;
+//# sourceMappingURL=maintenance-banner.d.ts.map

package/dist/host/ui/maintenance-banner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"maintenance-banner.d.ts","sourceRoot":"","sources":["../../../src/host/ui/maintenance-banner.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAOvC;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACrC;;;OAGG;IACH,IAAI,CAAC,EAAE;QACL,mBAAmB;QACnB,OAAO,CAAC,EAAE,SAAS,CAAC;KACrB,CAAC;IACF;;;OAGG;IACH,OAAO,CAAC,EAAE,SAAS,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,iBAAiB,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,GAAE,sBAA2B,sCA2E/E"}

package/dist/host/ui/maintenance-banner.js

@@ -0,0 +1,54 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { Alert, AlertTitle, Box, Button } from '@mui/material';
+import { Link as RouterLink, useLocation } from 'react-router-dom';
+import { usePermissions } from '../../identity/index.js';
+import { MAINTENANCE_ADMIN_PATH } from '../headless/maintenance-block.js';
+import { MAINTENANCE_POLL_INTERVAL_MS, useMaintenance } from '../headless/use-maintenance.js';
+/**
+ * The bypassing administrator's reminder: an `Alert` in the shell while a
+ * maintenance window is open. Renders `null` for everyone else (no
+ * `system_settings:read`, window closed, status not loaded, or the maintenance
+ * page itself), and never asks the API for a viewer who could not read the
+ * answer. Mount it inside {@link MaintenanceGate}'s children.
+ *
+ * @returns the banner element, or `null`.
+ *
+ * @example
+ * ```tsx
+ * <MaintenanceGate appName={APP_NAME}>
+ *   <MaintenanceBanner />
+ *   <Outlet />
+ * </MaintenanceGate>
+ * ```
+ *
+ * @extensionPoint component
+ * @stability experimental
+ */
+export function MaintenanceBanner({ copy, actions } = {}) {
+    const { hasPermission } = usePermissions();
+    const canRead = hasPermission('system_settings:read');
+    const { pathname } = useLocation();
+    const { status } = useMaintenance({
+        enabled: canRead,
+        // Polled rather than fetched once: the window may be opened from another
+        // tab, another instance, or by a colleague, and an administrator whose shell
+        // mounted before any of that happened would otherwise never be told.
+        pollIntervalMs: MAINTENANCE_POLL_INTERVAL_MS,
+    });
+    if (!canRead || !status?.enabled) {
+        return null;
+    }
+    // Suppressed on the maintenance page itself. That page's entire body is a
+    // fuller, editable statement of what this banner summarises, and repeating it
+    // directly above would read as two disagreeing controls for one switch.
+    const onMaintenancePage = pathname === MAINTENANCE_ADMIN_PATH || pathname.startsWith(`${MAINTENANCE_ADMIN_PATH}/`);
+    if (onMaintenancePage) {
+        return null;
+    }
+    return (_jsx(Box, { sx: { mb: 3 }, children: _jsxs(Alert, { severity: "warning", action: actions === undefined ? (_jsx(Button, { component: RouterLink, to: MAINTENANCE_ADMIN_PATH, color: "inherit", size: "small", children: "Manage" })) : (_jsxs(_Fragment, { children: [actions, _jsx(Button, { component: RouterLink, to: MAINTENANCE_ADMIN_PATH, color: "inherit", size: "small", children: "Manage" })] })), children: [_jsx(AlertTitle, { children: "Maintenance mode is on" }), copy?.message ??
+                    (_jsxs(_Fragment, { children: [status.allowAdmins
+                                ? 'Everyone except administrators is being turned away.'
+                                : 'Administrators are not exempt from this window, so the next request you make will be turned away too.', status.source === 'env' && ' It is being forced on by this deployment’s environment.', status.source === 'memory' &&
+                                ' It is being held open by a maintenance task running on the server.'] }))] }) }));
+}
+//# sourceMappingURL=maintenance-banner.js.map

package/dist/host/ui/maintenance-banner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"maintenance-banner.js","sourceRoot":"","sources":["../../../src/host/ui/maintenance-banner.tsx"],"names":[],"mappings":";AA2CA,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAC/D,OAAO,EAAE,IAAI,IAAI,UAAU,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACnE,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AACzD,OAAO,EAAE,sBAAsB,EAAE,MAAM,kCAAkC,CAAC;AAC1E,OAAO,EAAE,4BAA4B,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AAuB9F;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,iBAAiB,CAAC,EAAE,IAAI,EAAE,OAAO,KAA6B,EAAE;IAC9E,MAAM,EAAE,aAAa,EAAE,GAAG,cAAc,EAAE,CAAC;IAC3C,MAAM,OAAO,GAAG,aAAa,CAAC,sBAAsB,CAAC,CAAC;IACtD,MAAM,EAAE,QAAQ,EAAE,GAAG,WAAW,EAAE,CAAC;IAEnC,MAAM,EAAE,MAAM,EAAE,GAAG,cAAc,CAAC;QAChC,OAAO,EAAE,OAAO;QAChB,yEAAyE;QACzE,6EAA6E;QAC7E,qEAAqE;QACrE,cAAc,EAAE,4BAA4B;KAC7C,CAAC,CAAC;IAEH,IAAI,CAAC,OAAO,IAAI,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC;QACjC,OAAO,IAAI,CAAC;IACd,CAAC;IAED,0EAA0E;IAC1E,8EAA8E;IAC9E,wEAAwE;IACxE,MAAM,iBAAiB,GACrB,QAAQ,KAAK,sBAAsB,IAAI,QAAQ,CAAC,UAAU,CAAC,GAAG,sBAAsB,GAAG,CAAC,CAAC;IAC3F,IAAI,iBAAiB,EAAE,CAAC;QACtB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,OAAO,CACL,KAAC,GAAG,IAAC,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,EAAE,YAChB,MAAC,KAAK,IACJ,QAAQ,EAAC,SAAS,EAClB,MAAM,EACJ,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,CACtB,KAAC,MAAM,IACL,SAAS,EAAE,UAAU,EACrB,EAAE,EAAE,sBAAsB,EAC1B,KAAK,EAAC,SAAS,EACf,IAAI,EAAC,OAAO,uBAGL,CACV,CAAC,CAAC,CAAC,CACF,8BACG,OAAO,EACR,KAAC,MAAM,IACL,SAAS,EAAE,UAAU,EACrB,EAAE,EAAE,sBAAsB,EAC1B,KAAK,EAAC,SAAS,EACf,IAAI,EAAC,OAAO,uBAGL,IACR,CACJ,aAGH,KAAC,UAAU,yCAAoC,EAM9C,IAAI,EAAE,OAAO;oBACZ,CACE,8BACG,MAAM,CAAC,WAAW;gCACjB,CAAC,CAAC,sDAAsD;gCACxD,CAAC,CAAC,uGAAuG,EAC1G,MAAM,CAAC,MAAM,KAAK,KAAK,IAAI,0DAA0D,EACrF,MAAM,CAAC,MAAM,KAAK,QAAQ;gCACzB,qEAAqE,IACtE,CACJ,IACG,GACJ,CACP,CAAC;AACJ,CAAC"}

package/dist/host/ui/maintenance-gate.d.ts

@@ -0,0 +1,76 @@
+/**
+ * The client gate — issue #258, epic #254.
+ *
+ * =============================================================================
+ * THE ONE DISTINCTION THIS COMPONENT EXISTS TO MAKE
+ * =============================================================================
+ *
+ * A `503` with `details.reason === 'MAINTENANCE_MODE'` is a planned window, and
+ * this renders the operator's message and a retry. A `503` WITHOUT that marker
+ * is a crashed API, an exhausted pool, or a proxy with no backend — and it
+ * keeps its existing behaviour exactly: the `ApiError` propagates to whichever
+ * call site threw it, and that page shows the error it always showed. Nothing
+ * here is reached.
+ *
+ * The decision is not made in this file. `services/api.ts` recognises the
+ * marker centrally, on the single error path every request in the application
+ * shares, and records a block; this component only renders what was recorded.
+ * That separation is why adding an endpoint cannot forget to handle a window.
+ *
+ * =============================================================================
+ * WHY IT SWAPS THE SUBTREE RATHER THAN OVERLAYING IT
+ * =============================================================================
+ *
+ * Because unmounting is what makes the retry work. While the maintenance screen
+ * is up the application's pages are gone; clearing the block remounts them, so
+ * their effects re-run and re-issue the very requests that failed. The
+ * alternative — a modal over a live page — would leave the user looking at half
+ * a screen of stale data behind a dialog, and would need every page to grow its
+ * own "now refetch" path.
+ *
+ * =============================================================================
+ * WHY ONE ROUTE IS NEVER GATED
+ * =============================================================================
+ *
+ * `MAINTENANCE_ADMIN_PATH` is the client mirror of `@AllowDuringMaintenance()`
+ * on `maintenance.controller.ts` of the host slice. The API
+ * exempts its own maintenance endpoints for the obvious reason — the switch
+ * that ends a window has to be reachable while the window is open — and both
+ * halves of that argument have to hold, or an administrator caught by an
+ * `allowAdmins: false` window can reach the endpoint and not the page in front
+ * of it. Exemption here is about REACHABILITY only: the page still gates itself
+ * on `system_settings:read`, and the API still enforces it.
+ */
+import type { ReactNode } from 'react';
+/**
+ * Props of {@link MaintenanceGate}.
+ *
+ * @stability experimental
+ */
+export interface MaintenanceGateProps {
+    /** The product name the maintenance screen's heading uses. */
+    appName: string;
+    /** The application, rendered whenever no window is blocking this viewer. */
+    children: ReactNode;
+}
+/**
+ * Swaps the application for the maintenance screen while the API is refusing
+ * this viewer with a maintenance `503` (the block the app's HTTP client
+ * recorded), except on `MAINTENANCE_ADMIN_PATH`. Renders its children
+ * otherwise.
+ *
+ * @param props - see {@link MaintenanceGateProps}.
+ * @returns the maintenance screen or the children.
+ *
+ * @example
+ * ```tsx
+ * <MaintenanceGate appName={APP_NAME}>
+ *   <Routes>...</Routes>
+ * </MaintenanceGate>
+ * ```
+ *
+ * @extensionPoint component
+ * @stability experimental
+ */
+export declare function MaintenanceGate({ appName, children }: MaintenanceGateProps): import("react").JSX.Element;
+//# sourceMappingURL=maintenance-gate.d.ts.map

package/dist/host/ui/maintenance-gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"maintenance-gate.d.ts","sourceRoot":"","sources":["../../../src/host/ui/maintenance-gate.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAMvC;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC,8DAA8D;IAC9D,OAAO,EAAE,MAAM,CAAC;IAChB,4EAA4E;IAC5E,QAAQ,EAAE,SAAS,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,eAAe,CAAC,EAAE,OAAO,EAAE,QAAQ,EAAE,EAAE,oBAAoB,+BAgB1E"}

package/dist/host/ui/maintenance-gate.js

@@ -0,0 +1,38 @@
+import { jsx as _jsx, Fragment as _Fragment } from "react/jsx-runtime";
+import { useLocation } from 'react-router-dom';
+import { MAINTENANCE_ADMIN_PATH } from '../headless/maintenance-block.js';
+import { useMaintenanceBlock } from '../headless/use-maintenance.js';
+import { MaintenanceScreen } from './maintenance-screen.js';
+/**
+ * Swaps the application for the maintenance screen while the API is refusing
+ * this viewer with a maintenance `503` (the block the app's HTTP client
+ * recorded), except on `MAINTENANCE_ADMIN_PATH`. Renders its children
+ * otherwise.
+ *
+ * @param props - see {@link MaintenanceGateProps}.
+ * @returns the maintenance screen or the children.
+ *
+ * @example
+ * ```tsx
+ * <MaintenanceGate appName={APP_NAME}>
+ *   <Routes>...</Routes>
+ * </MaintenanceGate>
+ * ```
+ *
+ * @extensionPoint component
+ * @stability experimental
+ */
+export function MaintenanceGate({ appName, children }) {
+    const { block, clear } = useMaintenanceBlock();
+    const { pathname } = useLocation();
+    // `startsWith` with the separator, not a bare prefix match: the exemption is
+    // for that page and anything nested under it, and `…/maintenance-history`
+    // must not inherit it. Same segment-boundary rule `config/destinations.ts`
+    // and `settingsPageTitle` already apply.
+    const isExemptRoute = pathname === MAINTENANCE_ADMIN_PATH || pathname.startsWith(`${MAINTENANCE_ADMIN_PATH}/`);
+    if (block && !isExemptRoute) {
+        return _jsx(MaintenanceScreen, { appName: appName, block: block, onRetry: clear });
+    }
+    return _jsx(_Fragment, { children: children });
+}
+//# sourceMappingURL=maintenance-gate.js.map

package/dist/host/ui/maintenance-gate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"maintenance-gate.js","sourceRoot":"","sources":["../../../src/host/ui/maintenance-gate.tsx"],"names":[],"mappings":";AA6CA,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,sBAAsB,EAAE,MAAM,kCAAkC,CAAC;AAC1E,OAAO,EAAE,mBAAmB,EAAE,MAAM,gCAAgC,CAAC;AACrE,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAc5D;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,eAAe,CAAC,EAAE,OAAO,EAAE,QAAQ,EAAwB;IACzE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,mBAAmB,EAAE,CAAC;IAC/C,MAAM,EAAE,QAAQ,EAAE,GAAG,WAAW,EAAE,CAAC;IAEnC,6EAA6E;IAC7E,0EAA0E;IAC1E,2EAA2E;IAC3E,yCAAyC;IACzC,MAAM,aAAa,GACjB,QAAQ,KAAK,sBAAsB,IAAI,QAAQ,CAAC,UAAU,CAAC,GAAG,sBAAsB,GAAG,CAAC,CAAC;IAE3F,IAAI,KAAK,IAAI,CAAC,aAAa,EAAE,CAAC;QAC5B,OAAO,KAAC,iBAAiB,IAAC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,GAAI,CAAC;IAC/E,CAAC;IAED,OAAO,4BAAG,QAAQ,GAAI,CAAC;AACzB,CAAC"}

package/dist/host/ui/maintenance-page.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Admin → Settings → Maintenance (`/admin/settings/maintenance`).
+ *
+ * Issue #258, epic #254. A REGISTRY CARD and nothing else, per `CLAUDE.md`'s
+ * MANDATORY Settings UI Pattern: one entry in `ADMIN_SECTIONS`
+ * (`config/adminSections.tsx`), one route in `App.tsx` gated on the same
+ * permission string, and no tab anywhere. The hub, the Console rail and the
+ * compact AppBar title all pick this page up from that single declaration.
+ *
+ * It is deliberately NOT a section or a tab on another settings page: a tab
+ * gate is about CONTENT within one destination, and this is a destination of
+ * its own — the one screen an operator navigates straight to during an
+ * incident.
+ *
+ * WHY IT DOES NOT USE `SystemSettingsSection` (the render-prop wrapper
+ * `NotificationSettingsPage` uses). That component is bound to
+ * `useSystemSettings`: it loads the whole system settings document and PATCHes
+ * one branch of it. The maintenance window is a different controller with a response this page exists
+ * to render — `source` and `layers`, which the settings document does not carry
+ * — and a write that must be a `PUT` of `{ enabled, … }` so the API can stamp
+ * the window's provenance. `EmailSettingsPage` (#124) made the same departure
+ * for the same reason, and what is shared is the CHROME, reproduced here field
+ * for field: container, `h4` title, mirrored card description, "(read-only)"
+ * suffix, `Paper` body, save snackbar.
+ *
+ * =============================================================================
+ * THE LAYERS ARE THE POINT OF THIS PAGE, NOT DECORATION
+ * =============================================================================
+ *
+ * A switch would have been three lines. "I turned it off and it is still on" is
+ * the question an operator asks at the worst possible moment, and its honest
+ * answer — "because `MAINTENANCE_MODE=true` is still in this deployment's
+ * environment, and it outranks the row you just wrote" — is invisible unless
+ * every contributing layer is on screen next to the effective state. The API
+ * publishes all three for exactly this reason; a page that rendered only
+ * `enabled` would throw that away and send the operator to a shell.
+ *
+ * =============================================================================
+ * WHAT AN ENVIRONMENT OVERRIDE DISABLES, AND WHAT IT DOES NOT
+ * =============================================================================
+ *
+ * `MAINTENANCE_MODE` carries a BOOLEAN AND NOTHING ELSE. In
+ * `MaintenanceModeService.resolve` the env layer decides `enabled`, while
+ * `message` and `allowAdmins` are resolved independently from the highest layer
+ * that actually supplies them — which, with no in-memory override, is the
+ * persisted row this page writes.
+ *
+ * So an env override disables the ON/OFF SWITCH ONLY. Greying the whole form
+ * out would be the easy gesture and the wrong one: it would stop an operator
+ * preparing the message and the `allowAdmins` value that take effect the moment
+ * the variable is removed — and those are the settings that a window forced
+ * open from the environment is *still using right now*.
+ */
+import type { PageSlotsBase } from '../../core/index.js';
+/**
+ * The slots of {@link MaintenancePage}: the page-slot contract. `BeforeContent`
+ * is where an app puts its runbook link or on-call contact above the controls;
+ * `Sections` is drawn at both ends of the body, around the effective state, the
+ * form and the layers.
+ *
+ * @example
+ * ```tsx
+ * <MaintenancePage slots={{ BeforeContent: () => <Alert severity="info">Announce in #ops before switching it on.</Alert> }} />
+ * ```
+ *
+ * @extensionPoint slot
+ * @stability experimental
+ */
+export type MaintenancePageSlots = PageSlotsBase;
+/**
+ * The props of {@link MaintenancePage}.
+ *
+ * @stability experimental
+ */
+export interface MaintenancePageProps {
+    /** Optional extension slots; omitted, the page renders exactly as it always did. */
+    slots?: MaintenancePageSlots;
+}
+/**
+ * Admin → Settings → Maintenance: open or close the maintenance window, with
+ * every contributing layer (environment, server task, saved setting) shown
+ * beside the effective state. Redirects to `/` without `system_settings:read`;
+ * the controls are disabled without `system_settings:write`.
+ *
+ * @returns the page element.
+ *
+ * @example
+ * ```tsx
+ * <Route path="/admin/settings/maintenance" element={<RequirePermission permission="system_settings:read"><MaintenancePage /></RequirePermission>} />
+ * ```
+ *
+ * @extensionPoint component
+ * @stability experimental
+ */
+export declare function MaintenancePage(props?: MaintenancePageProps): import("react").JSX.Element;
+//# sourceMappingURL=maintenance-page.d.ts.map

package/dist/host/ui/maintenance-page.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"maintenance-page.d.ts","sourceRoot":"","sources":["../../../src/host/ui/maintenance-page.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AAsBH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAmEzD;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,oBAAoB,GAAG,aAAa,CAAC;AAEjD;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC,oFAAoF;IACpF,KAAK,CAAC,EAAE,oBAAoB,CAAC;CAC9B;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,eAAe,CAAC,KAAK,GAAE,oBAAyB,+BAyR/D"}