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

package/dist/notifications/ui/NotificationSettings.d.ts

@@ -0,0 +1,304 @@
+/**
+ * The event x channel notification preferences matrix.
+ *
+ * Issue #126, epic #109. Rendered by `pages/UserNotificationsPage.tsx` at
+ * `/settings/notifications`.
+ *
+ * =============================================================================
+ * THE SPARSE ABSENT-KEY CONTRACT — READ THIS BEFORE CHANGING ANYTHING HERE
+ * =============================================================================
+ *
+ * The stored document is `user_settings.value.notifications`, channel-outer:
+ *
+ *     \{ email: \{ 'user.welcome': false \}, browser: \{ ... \} \}
+ *
+ * A key is present ONLY where the user deliberately chose. Absent — at the
+ * namespace, the channel, or the event level — means "use the registry's
+ * `defaultEnabled`", resolved at read time by the API
+ * (`notifications/notification-preferences.ts`). Three properties depend on
+ * that, and each breaks in a way nobody notices for weeks:
+ *
+ *   1. NO MIGRATION, NO BACKFILL. The feature shipped by reading a key that
+ *      does not exist for anybody.
+ *   2. NOBODY IS MUTED ON ARRIVAL. Every pre-existing account has no
+ *      `notifications` namespace at all; if absent meant "off", the framework
+ *      would ship silent for the entire user base, and the only symptom would
+ *      be mail nobody receives — a failure with no error anywhere.
+ *   3. AN EVENT ADDED LATER IS OPT-OUT, NOT SILENTLY OFF. A user who saved a
+ *      preference today has a stored map that says nothing about an event
+ *      declared next year; absent-means-default gives them that event's
+ *      intended default, where a materialised blob would give them "not in my
+ *      map, therefore off".
+ *
+ * THREE RULES THIS FILE ENFORCES, EACH THE PRECISE OPPOSITE OF THE OBVIOUS
+ * IMPLEMENTATION:
+ *
+ *   A. EVERY CONTROL DERIVES ITS STATE (see `isEventChannelEnabled`) from the
+ *      fetched preferences compared against the registry's `defaultEnabled`.
+ *      There is NO local `Record<event, boolean>` state in this component, and
+ *      there must never be one. The moment a defaulted local object exists, the
+ *      first save serialises it and materialises every key in it.
+ *
+ *   B. NEVER WRITE A FULL PREFERENCES OBJECT — not on mount, not on first
+ *      change. Each toggle emits exactly the one `(channel, event, value)` it
+ *      changed and the page PATCHes that single key; the API deep-merges per
+ *      event, so everything else stays absent.
+ *
+ *   C. RETURNING A CONTROL TO ITS DEFAULT SENDS A NULL-DELETE (see
+ *      `preferenceWriteFor`), never the default value. Writing the default
+ *      explicitly works today, and it opts that user in permanently: the key is
+ *      materialised, the blob grows for no reason, and if the default ever
+ *      changes that user is frozen at the old one with nothing to show why.
+ *
+ * NO SAVE BUTTON, DELIBERATELY. A batched save needs a full local mirror to
+ * diff against, which is exactly the shape that ends up POSTing a materialised
+ * object — rule A and rule B fall together the moment a Save button appears.
+ * Every toggle is its own PATCH and its own snackbar.
+ *
+ * =============================================================================
+ * RESPONSIVE WITHOUT A BREAKPOINT GATE
+ * =============================================================================
+ *
+ * There is no `useMediaQuery` here and no `display: { xs, sm }` switch between
+ * two layouts. `CLAUDE.md` names five coupled breakpoint gates that move
+ * together or not at all (`Layout.tsx`'s `showRail`, `BottomNav`'s self-gate,
+ * `<main>`'s padding, and `isCompactWindow` in both `SettingsHub.tsx` and
+ * `AppBar.tsx`); a sixth gate here would be a sixth thing to keep in lockstep
+ * for no gain.
+ *
+ * Instead each row is ONE flex container that wraps: the event's label and
+ * description take the left, the channel switches the right, and on a narrow
+ * viewport the switches simply flow underneath. Every switch carries its own
+ * visible channel label, so the matrix is self-describing at every width — no
+ * column header row that has to survive being wrapped away, which is precisely
+ * where a table layout breaks down in a 320px drill-down.
+ */
+import type { NotificationChannel, NotificationChannelDescriptor, NotificationEventDef, NotificationPreferences } from '../headless/types.js';
+import type { NotificationCapability } from '../headless/useNotificationCapability.js';
+/**
+ * Is this event enabled on this channel, for this user?
+ *
+ * THE MIRROR OF THE API'S `isChannelEnabled`, function for function, including
+ * the order of its checks — `mandatory` first, then the three-level fallback.
+ * Two implementations of one rule is a drift risk, and it is accepted here for
+ * one reason: the alternative is a per-user "resolved preferences" endpoint,
+ * i.e. the server materialising exactly the defaulted object this whole design
+ * refuses to store. The UI reads the raw sparse document and applies the same
+ * rule; the SERVER's copy remains the only one that decides delivery, so a
+ * drift shows as a wrong checkbox, never as a wrong send.
+ *
+ * `mandatory` is checked BEFORE the stored value, so a preference row that
+ * disables a mandatory event — one written before the event became mandatory,
+ * or by a crafted PATCH — renders as ON, which is what the user will actually
+ * receive. Rendering the stored `false` there would be an honest reading of the
+ * document and a lie about the behaviour.
+ *
+ * @param preferences - the raw stored namespace, or `undefined` when the user has
+ *                    never saved a preference — the single most common case.
+ */
+export declare function isEventChannelEnabled(event: NotificationEventDef, channel: NotificationChannel, preferences: NotificationPreferences | undefined): boolean;
+/**
+ * What to send for a control the user has just moved to `nextEnabled`.
+ *
+ * `null` is a JSON Merge Patch DELETE and is the WHOLE POINT of this function:
+ * when the new state equals the registry default, the correct write is to
+ * remove the key and return the user to "no opinion", not to pin today's
+ * default into their document. See rule C in the file header.
+ *
+ * Both directions matter, which is why this compares against `defaultEnabled`
+ * rather than special-casing "re-enabling":
+ *   * default `true`, user muted it, user un-mutes  -\> next `true`  -\> DELETE
+ *   * default `false`, user opted in, user opts out -\> next `false` -\> DELETE
+ * and a first, non-default change stores the explicit boolean.
+ */
+export declare function preferenceWriteFor(event: NotificationEventDef, nextEnabled: boolean): boolean | null;
+/**
+ * How a gated channel column must behave: whether its control is disabled,
+ * the terse note beside it, and the banner above the whole matrix.
+ *
+ * SHARED BY `browserChannelState` AND `pushChannelState` — originally this
+ * was `BrowserChannelState`, named for its one caller, but `push` needs the
+ * exact same three fields (a control can be live or not, with or without a
+ * one-line reason, with or without a banner explaining why) for a completely
+ * different underlying reason (an unimplemented feature, not a browser
+ * permission). Two interfaces that are structurally identical and diverge
+ * only in field NAMES would be the worse choice here: every caller below —
+ * the channel-state lookup, the render column, the banner block — treats
+ * both the same way, and a shared name says so instead of asking the reader
+ * to notice two shapes happen to line up. `email` never produces one of
+ * these at all: it is never gated, so it simply has no entry wherever these
+ * are collected (see `channelStates` in the component below).
+ *
+ * An app supplies one for its own channel through
+ * `UserNotificationsPage`'s `channelStates` prop.
+ *
+ * @stability experimental
+ */
+export interface ChannelState {
+    /** The channel's controls are disabled (the note says why). */
+    disabled: boolean;
+    /** Terse note beside the control. `null` when there is nothing to add. */
+    note: string | null;
+    /** The banner above the matrix. `null` when the channel is fully working. */
+    alert: ChannelAlert | null;
+}
+/**
+ * The banner above the matrix for a gated channel.
+ *
+ * @stability experimental
+ */
+export interface ChannelAlert {
+    /** `info` for a deliberate configuration, `warning` for something the user can fix. */
+    severity: 'info' | 'warning';
+    /** The banner heading. */
+    title: string;
+    /** The banner text; newlines render as a list. */
+    body: string;
+}
+/**
+ * How the browser column must behave for a given CAPABILITY state.
+ *
+ * SEPARATED FROM THE JSX so the honest answer to "what does `denied` do?" is
+ * one readable table rather than eight ternaries spread through a render, and
+ * so the copy is assertable without a DOM. #126 wrote this over the 4-state
+ * permission; #221 widened it to `NotificationCapability`, and the widening is
+ * the whole point:
+ *
+ *   EVERY ARM MUST NAME A DIFFERENT THING TO DO.
+ *
+ * That is the rule this function exists to keep. Before #221 an iOS Safari tab,
+ * a plain-HTTP origin and a browser from 2011 all rendered the identical "not
+ * supported by this browser" — one of which is a lie, one of which blames the
+ * wrong party, and none of which tells the user the fix. If a new state is
+ * added here and its copy could be swapped with another arm's without anyone
+ * noticing, the state is not pulling its weight and should not exist.
+ *
+ * `disabled` is true only where the app genuinely cannot deliver AND cannot
+ * recover — a control that looks live but can never take effect is worse than
+ * one that explains itself:
+ *   * `admin-disabled`   — the server will not send on this channel at all.
+ *   * `insecure-context` — the API cannot exist over plain HTTP.
+ *   * `unsupported`      — no `Notification` API at all. Nothing to configure.
+ *   * `denied`           — the browser refused; nothing this application does
+ *                          can undo that, only the user in their browser's site
+ *                          settings.
+ *   * `ios-needs-install`— nothing to configure until the app is installed;
+ *                          iOS does not even offer a permission before then.
+ *   * `sw-unavailable`   — NOT disabled. Degraded, not blocked, and reached
+ *                          only with permission ALREADY GRANTED: the page-level
+ *                          `Notification` fallback may still deliver, and a
+ *                          stored preference is still meaningful. A warning
+ *                          explains the risk; a disabled control would overstate
+ *                          it, and copy that told the user to enable something
+ *                          would be addressing a step they have already taken.
+ *   * `default`          — NOT disabled. The permission has not been asked for
+ *                          yet, and the stored preference is still meaningful:
+ *                          it is what takes effect the moment permission is
+ *                          granted. Disabling it would force the user to grant
+ *                          permission before they are allowed to express an
+ *                          opinion, which is backwards.
+ *   * `granted`          — nothing to say.
+ */
+export declare function browserChannelState(capability: NotificationCapability): ChannelState;
+/**
+ * How the push column must behave.
+ *
+ * `pushEnabled` is `GET /api/notifications/config`'s `pushEnabled` — `true`
+ * once an administrator has generated and enabled VAPID keys (#355).
+ *
+ *   * `pushEnabled === false` — disabled, "not available". Phrased as a
+ *                     deployment setting, never as a browser refusal: the
+ *                     user cannot fix it, and blaming their browser would
+ *                     send them looking for a setting that does not exist.
+ *   * `pushEnabled === true`  — never disabled: the preference is per ACCOUNT
+ *                     and applies on every device. When THIS device has not
+ *                     granted permission (`browserCapability` is anything but
+ *                     `granted`/`sw-unavailable`), the row says so in a note;
+ *                     the remedy lives in the browser banner and the app-wide
+ *                     banner, so there is no second alert here.
+ */
+export declare function pushChannelState(pushEnabled: boolean, browserCapability?: NotificationCapability): ChannelState;
+export interface NotificationSettingsProps {
+    /**
+     * The registry, in server order. Rendered as given and NEVER sorted — the
+     * order is meaningful and is the API's to decide.
+     */
+    events: NotificationEventDef[];
+    /**
+     * The raw stored namespace. `undefined` when the user has never saved a
+     * preference, which is the normal case and is NOT a loading state — every
+     * control resolves to its registry default.
+     */
+    preferences: NotificationPreferences | undefined;
+    /**
+     * One toggle happened. `value` is the boolean to store, or `null` to DELETE
+     * the key and restore the registry default (see `preferenceWriteFor`).
+     *
+     * The caller turns this into `{ notifications: { [channel]: { [key]: value } } }`
+     * — one channel, one key, nothing else on the wire.
+     */
+    onToggle: (channel: NotificationChannel, event: NotificationEventDef, value: boolean | null) => void;
+    /**
+     * A save is in flight. EVERY control is disabled, not just the one that was
+     * clicked, and that is on purpose: `useUserSettings` sends `If-Match` with
+     * the settings version it currently holds, so two toggles racing produce two
+     * PATCHes with the same expected version and the second 409s. Serialising
+     * them costs a few hundred milliseconds and removes the conflict entirely.
+     */
+    isSaving?: boolean;
+    /**
+     * What this device can actually do about browser notifications, from
+     * `useNotificationCapability` (#221).
+     *
+     * WIDER THAN `Notification.permission`, and named for that: it folds in the
+     * administrator kill switch, the secure-context requirement, the iOS
+     * install-first rule and the service worker's registration, because each of
+     * those has a remedy the raw permission cannot express. `browserChannelState`
+     * above turns it into the copy.
+     */
+    browserCapability: NotificationCapability;
+    /**
+     * Whether this deployment offers Web Push, from
+     * `GET /api/notifications/config`'s `pushEnabled` (passed by
+     * `UserNotificationsPage` since #365). Optional, defaulting to `false` —
+     * the safe reading while the config is unknown.
+     */
+    pushEnabled?: boolean;
+    /**
+     * Ask the browser for notification permission (#127).
+     *
+     * FILLS THE SEAM #126 LEFT in the `default`-state banner below. The component
+     * does NOT call `Notification.requestPermission()` itself — it raises this
+     * callback from a click, and the page owns the call plus the `refresh()` that
+     * follows it. That split is what keeps the prompt out of this component's
+     * render path entirely: there is no code here that COULD fire it on mount,
+     * because the API call is not in this file.
+     *
+     * Optional, and the button is only rendered when it is supplied. A promptless
+     * host renders the same honest banner #126 shipped.
+     */
+    onRequestPermission?: () => void;
+    /**
+     * The permission prompt is open. Disables the button so a second click cannot
+     * stack a second request behind the browser's modal.
+     */
+    isRequestingPermission?: boolean;
+    /**
+     * The channel descriptors from `GET /api/notifications/channels`
+     * (`useNotificationChannels`), which are where every label comes from. Absent
+     * (not yet read, or the read failed): a channel is labelled with its raw id.
+     */
+    channels?: NotificationChannelDescriptor[];
+    /**
+     * How an app's own channel column behaves, by channel id: disabled with a
+     * terse note and an optional banner above the matrix, exactly as the
+     * built-in browser and push columns are. Optional: a channel with no entry is
+     * never gated and shows nothing extra. An entry for `browser` is ignored (its
+     * state is derived from `browserCapability`), and one for `push` replaces the
+     * built-in push state.
+     */
+    channelStates?: Readonly<Record<string, ChannelState>>;
+}
+export declare function NotificationSettings({ events, preferences, onToggle, isSaving, browserCapability, onRequestPermission, isRequestingPermission, pushEnabled, channels: channelDescriptors, channelStates: extraChannelStates, }: NotificationSettingsProps): import("react").JSX.Element;
+export default NotificationSettings;
+//# sourceMappingURL=NotificationSettings.d.ts.map

package/dist/notifications/ui/NotificationSettings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"NotificationSettings.d.ts","sourceRoot":"","sources":["../../../src/notifications/ui/NotificationSettings.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0EG;AAkBH,OAAO,KAAK,EACV,mBAAmB,EACnB,6BAA6B,EAC7B,oBAAoB,EACpB,uBAAuB,EACxB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,0CAA0C,CAAC;AAQvF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,oBAAoB,EAC3B,OAAO,EAAE,mBAAmB,EAC5B,WAAW,EAAE,uBAAuB,GAAG,SAAS,GAC/C,OAAO,CAqBT;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,oBAAoB,EAC3B,WAAW,EAAE,OAAO,GACnB,OAAO,GAAG,IAAI,CAEhB;AAsBD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,WAAW,YAAY;IAC3B,+DAA+D;IAC/D,QAAQ,EAAE,OAAO,CAAC;IAClB,0EAA0E;IAC1E,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,6EAA6E;IAC7E,KAAK,EAAE,YAAY,GAAG,IAAI,CAAC;CAC5B;AAED;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,uFAAuF;IACvF,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,0BAA0B;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,kDAAkD;IAClD,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,wBAAgB,mBAAmB,CACjC,UAAU,EAAE,sBAAsB,GACjC,YAAY,CA0Id;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,gBAAgB,CAC9B,WAAW,EAAE,OAAO,EACpB,iBAAiB,CAAC,EAAE,sBAAsB,GACzC,YAAY,CAuBd;AAMD,MAAM,WAAW,yBAAyB;IACxC;;;OAGG;IACH,MAAM,EAAE,oBAAoB,EAAE,CAAC;IAC/B;;;;OAIG;IACH,WAAW,EAAE,uBAAuB,GAAG,SAAS,CAAC;IACjD;;;;;;OAMG;IACH,QAAQ,EAAE,CAAC,OAAO,EAAE,mBAAmB,EAAE,KAAK,EAAE,oBAAoB,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,KAAK,IAAI,CAAC;IACrG;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;;;;;;;OASG;IACH,iBAAiB,EAAE,sBAAsB,CAAC;IAC1C;;;;;OAKG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;;;;;;;;;;OAYG;IACH,mBAAmB,CAAC,EAAE,MAAM,IAAI,CAAC;IACjC;;;OAGG;IACH,sBAAsB,CAAC,EAAE,OAAO,CAAC;IACjC;;;;OAIG;IACH,QAAQ,CAAC,EAAE,6BAA6B,EAAE,CAAC;IAC3C;;;;;;;OAOG;IACH,aAAa,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC;CACxD;AAED,wBAAgB,oBAAoB,CAAC,EACnC,MAAM,EACN,WAAW,EACX,QAAQ,EACR,QAAgB,EAChB,iBAAiB,EACjB,mBAAmB,EACnB,sBAA8B,EAC9B,WAAmB,EACnB,QAAQ,EAAE,kBAAkB,EAC5B,aAAa,EAAE,kBAAkB,GAClC,EAAE,yBAAyB,+BAiU3B;AAED,eAAe,oBAAoB,CAAC"}