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

package/dist/settings/ui/SettingsHub.js

@@ -0,0 +1,134 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * The settings hub — ONE component, every settings surface.
+ *
+ * Issue #93, epic #90; moved into `@marinoscar/platform-web/settings/ui` by
+ * #733 WITHOUT behavioural change. A searchable, grouped view of a settings
+ * registry that renders as a card grid from `sm` up and as an iOS-style
+ * drill-down list below it.
+ *
+ * WHY IT TAKES PROPS. The admin hub (`/admin/settings`) and the per-user hub
+ * (`/settings`) are the same page with a different array, and a second hub
+ * COPIED from the first is precisely the failure epic #90 was filed to
+ * remove. Everything surface-specific arrives through `SettingsHubProps`.
+ * Nothing in this file names "admin", and nothing in it may.
+ */
+import { useState } from 'react';
+import { useNavigate } from 'react-router-dom';
+import { Box, Card, CardActionArea, CardContent, Chip, Grid, IconButton, InputAdornment, List, ListItemButton, ListItemIcon, ListItemText, TextField, Typography, useMediaQuery, useTheme, } from '@mui/material';
+import SearchIcon from '@mui/icons-material/Search';
+import ClearIcon from '@mui/icons-material/Clear';
+import ChevronRightIcon from '@mui/icons-material/ChevronRight';
+import { useOptionalPlatformHost } from '../../core/index.js';
+import { visibleSettingsSections } from './registry.js';
+/** Fail closed: without a viewer, no permission-gated card is visible. */
+const NO_PERMISSION = () => false;
+/** The default scroll restoration: none. */
+function noScrollRestoration() { }
+/**
+ * The settings hub: ONE component, every settings surface (the admin Console
+ * at `/admin/settings`, the per-user hub at `/settings`). A searchable,
+ * grouped view of a section registry: a card grid from `sm` up, an iOS-style
+ * drill-down list below it. Nothing in it names a surface; each surface is a
+ * thin binding (`sections`, `hubKey`, `title`, `subtitle`, `features`).
+ *
+ * ⚠ BREAKPOINT GATE 4 OF FIVE: `isCompactWindow` is `down('sm')`, coupled
+ * with the app's `Layout` rail gate, its `BottomNav` self-gate, its `<main>`
+ * bottom padding and its AppBar's compact gate (docs/specs/settings-ui.md,
+ * "Breakpoint gates"). The five move together or not at all.
+ *
+ * @param props - see {@link SettingsHubProps}.
+ * @returns the hub.
+ *
+ * @example
+ * ```tsx
+ * <SettingsHub sections={ADMIN_SECTIONS} hubKey="admin-settings-hub" title="Settings"
+ *   subtitle="…" features={useSettingsFeatures()} useScrollRestoration={useScrollRestoration} />
+ * ```
+ *
+ * @extensionPoint component
+ * @stability stable
+ */
+export function SettingsHub({ sections, hubKey, title, subtitle, features, hasPermission: hasPermissionProp, useScrollRestoration = noScrollRestoration, }) {
+    const navigate = useNavigate();
+    const theme = useTheme();
+    const host = useOptionalPlatformHost();
+    const hasPermission = hasPermissionProp ?? host?.viewer.hasPermission ?? NO_PERMISSION;
+    const [query, setQuery] = useState('');
+    // 600px — `down('sm')`, byte-identical to `BottomNav`'s gate, the exact
+    // complement of `Layout`'s `showRail` (`up('sm')`), and identical to the
+    // compact AppBar gate #95 adds.
+    //
+    // ⚠️ FIVE COUPLED GATES — the full list and the reasoning live in the
+    // app's `components/common/Layout.tsx`. This is member (4). If the hub and the AppBar ever
+    // disagree the user gets one of two broken screens: a back-arrow drill-down
+    // header sitting above a card grid, or a full toolbar above a drill-down list
+    // with no way back up. Below `sm` there is no rail to swap into Console mode
+    // (#94), so the hub IS the navigation, and iOS Settings is the model every
+    // phone user already holds.
+    const isCompactWindow = useMediaQuery(theme.breakpoints.down('sm'));
+    // The make-or-break detail of a drill-down: returning from a settings page
+    // near the bottom of a long hub must land where the user left it, not at the
+    // top. Called UNCONDITIONALLY, before any early return and outside any
+    // branch, per the rules of hooks — `isCompactWindow` flips on a plain resize,
+    // and a hook called only in the compact branch would change the hook order
+    // mid-session and crash the tree.
+    useScrollRestoration(hubKey);
+    // ONE declaration, three consumers — see `./registry.ts`. The
+    // permission gate AND the title search live in that shared helper, so this
+    // page, the Console rail (#94) and the AppBar title resolver (#95) cannot
+    // disagree about what the current user may see. Sections emptied by either
+    // gate are dropped by the helper, so no bare group header ever renders.
+    const visibleSections = visibleSettingsSections(sections, hasPermission, query, features);
+    const trimmedQuery = query.trim();
+    return (_jsxs(Box, { sx: { p: { xs: 2, md: 4 } }, children: [_jsx(Typography, { variant: "h4", gutterBottom: true, sx: { fontWeight: 700 }, children: title }), _jsx(Typography, { variant: "body1", color: "text.secondary", sx: { mb: 3 }, children: subtitle }), _jsx(TextField, { value: query, onChange: (e) => setQuery(e.target.value), size: "small", placeholder: "Search settings", 
+                // NO DEBOUNCE, deliberately. This filters an in-memory array of a few
+                // dozen items; a timer would buy nothing and cost visible input lag —
+                // characters appearing before the list they filter is the single most
+                // common way a "responsive" search feels broken. Search is also the
+                // only navigation aid here that stays constant-effort as the surface
+                // grows, which is why the epic chose it over a tab strip.
+                sx: { mb: 3, width: '100%', maxWidth: { xs: '100%', sm: 420 } }, slotProps: {
+                    // The field has no visible <label> — the placeholder is not one, and
+                    // a placeholder disappears the moment the user types, taking the only
+                    // announced name with it. So the accessible name is explicit.
+                    htmlInput: { 'aria-label': 'Search settings' },
+                    input: {
+                        startAdornment: (_jsx(InputAdornment, { position: "start", children: _jsx(SearchIcon, { fontSize: "small", color: "disabled" }) })),
+                        // Rendered only when there is something to clear. A permanently
+                        // mounted clear button is a dead tab stop on an empty field and
+                        // reads as an affordance that does nothing.
+                        endAdornment: query ? (_jsx(InputAdornment, { position: "end", children: _jsx(IconButton, { size: "small", "aria-label": "Clear settings search", onClick: () => setQuery(''), children: _jsx(ClearIcon, { fontSize: "small" }) }) })) : null,
+                    },
+                } }), visibleSections.length === 0 && trimmedQuery !== '' && (_jsxs(Typography, { variant: "body2", color: "text.secondary", children: ["No settings match \u201C", trimmedQuery, "\u201D."] })), visibleSections.map((section) => (_jsxs(Box, { sx: { mb: 4 }, children: [_jsx(Typography, { variant: "overline", sx: {
+                            display: 'block',
+                            // Tighter above a list than above a grid: list rows carry their
+                            // own dividers and vertical padding, so a grid's gap under the
+                            // header would read as a break in the group rather than a label
+                            // attached to it.
+                            mb: isCompactWindow ? 0.5 : 1.5,
+                            color: 'text.secondary',
+                            fontWeight: 600,
+                            letterSpacing: '0.1em',
+                        }, children: section.label }), isCompactWindow ? (_jsx(List, { disablePadding: true, children: section.cards.map((card) => {
+                            // A card with no `path` is "declared but not yet routed" — as
+                            // inert as an explicitly `disabled` one, and treated
+                            // identically here so it can never render as a focusable row
+                            // whose click does nothing.
+                            const inert = card.disabled || !card.path;
+                            return (_jsxs(ListItemButton, { disabled: inert, onClick: () => card.path && navigate(card.path), sx: {
+                                    borderRadius: 1,
+                                    borderBottom: `1px solid ${theme.palette.divider}`,
+                                    // Matches the disabled CARD's 0.6 rather than taking
+                                    // MUI's default disabled opacity (0.38): the two
+                                    // treatments are the same surface at two widths, and a
+                                    // "Coming soon" row that fades harder than its card reads
+                                    // as a different state instead of the same one.
+                                    '&.Mui-disabled': { opacity: 0.6 },
+                                }, children: [_jsx(ListItemIcon, { sx: { minWidth: 40, color: 'primary.main' }, children: _jsx(card.Icon, { fontSize: "small" }) }), _jsx(ListItemText, { primary: card.title }), inert ? (_jsx(Chip, { label: "Coming soon", size: "small" })) : (_jsx(ChevronRightIcon, { fontSize: "small", color: "disabled" }))] }, card.title));
+                        }) })) : (_jsx(Grid, { container: true, spacing: 2, children: section.cards.map((card) => {
+                            const inert = card.disabled || !card.path;
+                            return (_jsx(Grid, { size: { xs: 12, sm: 6, md: 4 }, children: inert ? (_jsx(Card, { variant: "outlined", sx: { height: '100%', opacity: 0.6, cursor: 'default' }, children: _jsxs(CardContent, { children: [_jsx(card.Icon, { sx: { fontSize: 40 }, color: "primary" }), _jsx(Typography, { variant: "subtitle1", sx: { fontWeight: 600, mt: 1 }, children: card.title }), _jsx(Typography, { variant: "body2", color: "text.secondary", sx: { mt: 0.5 }, children: card.description }), _jsx(Chip, { label: "Coming soon", size: "small", sx: { mt: 1 } })] }) })) : (_jsx(Card, { variant: "outlined", sx: { height: '100%' }, children: _jsx(CardActionArea, { onClick: () => card.path && navigate(card.path), sx: { height: '100%', alignItems: 'flex-start' }, children: _jsxs(CardContent, { children: [_jsx(card.Icon, { sx: { fontSize: 40 }, color: "primary" }), _jsx(Typography, { variant: "subtitle1", sx: { fontWeight: 600, mt: 1 }, children: card.title }), _jsx(Typography, { variant: "body2", color: "text.secondary", sx: { mt: 0.5 }, children: card.description })] }) }) })) }, card.title));
+                        }) }))] }, section.label)))] }));
+}
+//# sourceMappingURL=SettingsHub.js.map

package/dist/settings/ui/SettingsHub.js.map

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

package/dist/settings/ui/ThemeSettings.d.ts

@@ -0,0 +1,65 @@
+import type { ThemeOption, ThemePreferenceId } from '@marinoscar/platform-contract/settings';
+import type { ComponentType } from 'react';
+/**
+ * What the `ExtraFields` slot of {@link ThemeSettings} receives.
+ *
+ * @stability experimental
+ */
+export interface ThemeExtraFieldsProps {
+    /** The stored theme preference. */
+    currentTheme: ThemePreferenceId;
+    /** Reports a chosen preference (the card's own `onThemeChange`). */
+    onThemeChange: (theme: ThemePreferenceId) => void;
+    /** Whether the card is disabled (a save is in flight). */
+    disabled: boolean;
+}
+/**
+ * The replaceable parts of {@link ThemeSettings}. With none, the card is
+ * exactly what it always was.
+ *
+ * @stability experimental
+ */
+export interface ThemeSettingsSlots {
+    /** Rendered under the toggle (nothing by default): an app's own appearance fields, such as a density or an accent. */
+    ExtraFields?: ComponentType<ThemeExtraFieldsProps>;
+}
+/**
+ * Props of {@link ThemeSettings}.
+ *
+ * @extensionPoint slot
+ * @stability experimental
+ */
+export interface ThemeSettingsProps {
+    /** The stored theme preference: light, dark, system, or an id an app registered. */
+    currentTheme: ThemePreferenceId;
+    /**
+     * Called with the chosen preference. Declared as a method so a handler typed
+     * for the three built-in ids (`(theme: 'light' | 'dark' | 'system') => void`)
+     * still fits; an app that registered themes handles the wider id.
+     */
+    onThemeChange(theme: ThemePreferenceId): void;
+    /** Disables the toggle (a save is in flight). */
+    disabled?: boolean;
+    /**
+     * The themes an app registered (`themePreferenceOptions(settings)`), offered
+     * after light, dark and system. Empty or absent: the three built-in choices.
+     */
+    extraOptions?: readonly ThemeOption[];
+    /** Part overrides. */
+    slots?: ThemeSettingsSlots;
+}
+/**
+ * The light, dark or system choice, as a card.
+ *
+ * @param props - see {@link ThemeSettingsProps}.
+ * @returns the card.
+ *
+ * @example
+ * ```tsx
+ * <ThemeSettings currentTheme="system" onThemeChange={(theme) => save({ theme })} />
+ * ```
+ *
+ * @stability experimental
+ */
+export declare function ThemeSettings({ currentTheme, onThemeChange, disabled, extraOptions, slots, }: ThemeSettingsProps): import("react").JSX.Element;
+//# sourceMappingURL=ThemeSettings.d.ts.map

package/dist/settings/ui/ThemeSettings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ThemeSettings.d.ts","sourceRoot":"","sources":["../../../src/settings/ui/ThemeSettings.tsx"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,wCAAwC,CAAC;AAC7F,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,OAAO,CAAC;AAE3C;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IACpC,mCAAmC;IACnC,YAAY,EAAE,iBAAiB,CAAC;IAChC,oEAAoE;IACpE,aAAa,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,CAAC;IAClD,0DAA0D;IAC1D,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC,sHAAsH;IACtH,WAAW,CAAC,EAAE,aAAa,CAAC,qBAAqB,CAAC,CAAC;CACpD;AAED;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC,oFAAoF;IACpF,YAAY,EAAE,iBAAiB,CAAC;IAChC;;;;OAIG;IACH,aAAa,CAAC,KAAK,EAAE,iBAAiB,GAAG,IAAI,CAAC;IAC9C,iDAAiD;IACjD,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;OAGG;IACH,YAAY,CAAC,EAAE,SAAS,WAAW,EAAE,CAAC;IACtC,sBAAsB;IACtB,KAAK,CAAC,EAAE,kBAAkB,CAAC;CAC5B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAAC,EAC5B,YAAY,EACZ,aAAa,EACb,QAAgB,EAChB,YAAY,EACZ,KAAK,GACN,EAAE,kBAAkB,+BA6DpB"}

package/dist/settings/ui/ThemeSettings.js

@@ -0,0 +1,26 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Card, CardContent, Typography, ToggleButtonGroup, ToggleButton, Box, } from '@mui/material';
+import { LightMode as LightIcon, DarkMode as DarkIcon, SettingsBrightness as SystemIcon, } from '@mui/icons-material';
+/**
+ * The light, dark or system choice, as a card.
+ *
+ * @param props - see {@link ThemeSettingsProps}.
+ * @returns the card.
+ *
+ * @example
+ * ```tsx
+ * <ThemeSettings currentTheme="system" onThemeChange={(theme) => save({ theme })} />
+ * ```
+ *
+ * @stability experimental
+ */
+export function ThemeSettings({ currentTheme, onThemeChange, disabled = false, extraOptions, slots, }) {
+    const ExtraFields = slots?.ExtraFields;
+    const handleChange = (_event, newTheme) => {
+        if (newTheme !== null) {
+            onThemeChange(newTheme);
+        }
+    };
+    return (_jsx(Card, { id: "theme", children: _jsxs(CardContent, { children: [_jsx(Typography, { variant: "h6", gutterBottom: true, children: "Appearance" }), _jsx(Typography, { variant: "body2", color: "text.secondary", sx: { mb: 2 }, children: "Choose how the application looks to you" }), _jsxs(ToggleButtonGroup, { value: currentTheme, exclusive: true, onChange: handleChange, "aria-label": "theme selection", disabled: disabled, sx: { mt: 1 }, children: [_jsx(ToggleButton, { value: "light", "aria-label": "light mode", children: _jsxs(Box, { sx: { display: 'flex', alignItems: 'center', gap: 1, px: 1 }, children: [_jsx(LightIcon, {}), _jsx("span", { children: "Light" })] }) }), _jsx(ToggleButton, { value: "dark", "aria-label": "dark mode", children: _jsxs(Box, { sx: { display: 'flex', alignItems: 'center', gap: 1, px: 1 }, children: [_jsx(DarkIcon, {}), _jsx("span", { children: "Dark" })] }) }), _jsx(ToggleButton, { value: "system", "aria-label": "system preference", children: _jsxs(Box, { sx: { display: 'flex', alignItems: 'center', gap: 1, px: 1 }, children: [_jsx(SystemIcon, {}), _jsx("span", { children: "System" })] }) }), extraOptions?.map((option) => (_jsx(ToggleButton, { value: option.id, "aria-label": `${option.label} theme`, children: _jsx(Box, { sx: { display: 'flex', alignItems: 'center', gap: 1, px: 1 }, children: _jsx("span", { children: option.label }) }) }, option.id)))] }), ExtraFields && (_jsx(ExtraFields, { currentTheme: currentTheme, onThemeChange: onThemeChange, disabled: disabled }))] }) }));
+}
+//# sourceMappingURL=ThemeSettings.js.map

package/dist/settings/ui/ThemeSettings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ThemeSettings.js","sourceRoot":"","sources":["../../../src/settings/ui/ThemeSettings.tsx"],"names":[],"mappings":";AAAA,OAAO,EACL,IAAI,EACJ,WAAW,EACX,UAAU,EACV,iBAAiB,EACjB,YAAY,EACZ,GAAG,GACJ,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,SAAS,IAAI,SAAS,EACtB,QAAQ,IAAI,QAAQ,EACpB,kBAAkB,IAAI,UAAU,GACjC,MAAM,qBAAqB,CAAC;AAuD7B;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,aAAa,CAAC,EAC5B,YAAY,EACZ,aAAa,EACb,QAAQ,GAAG,KAAK,EAChB,YAAY,EACZ,KAAK,GACc;IACnB,MAAM,WAAW,GAAG,KAAK,EAAE,WAAW,CAAC;IACvC,MAAM,YAAY,GAAG,CACnB,MAAqC,EACrC,QAAkC,EAClC,EAAE;QACF,IAAI,QAAQ,KAAK,IAAI,EAAE,CAAC;YACtB,aAAa,CAAC,QAAQ,CAAC,CAAC;QAC1B,CAAC;IACH,CAAC,CAAC;IAEF,OAAO,CACL,KAAC,IAAI,IAAC,EAAE,EAAC,OAAO,YACd,MAAC,WAAW,eACV,KAAC,UAAU,IAAC,OAAO,EAAC,IAAI,EAAC,YAAY,iCAExB,EACb,KAAC,UAAU,IAAC,OAAO,EAAC,OAAO,EAAC,KAAK,EAAC,gBAAgB,EAAC,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,EAAE,wDAEnD,EAEb,MAAC,iBAAiB,IAChB,KAAK,EAAE,YAAY,EACnB,SAAS,QACT,QAAQ,EAAE,YAAY,gBACX,iBAAiB,EAC5B,QAAQ,EAAE,QAAQ,EAClB,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,EAAE,aAEb,KAAC,YAAY,IAAC,KAAK,EAAC,OAAO,gBAAY,YAAY,YACjD,MAAC,GAAG,IAAC,EAAE,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,QAAQ,EAAE,GAAG,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,aAC/D,KAAC,SAAS,KAAG,EACb,mCAAkB,IACd,GACO,EACf,KAAC,YAAY,IAAC,KAAK,EAAC,MAAM,gBAAY,WAAW,YAC/C,MAAC,GAAG,IAAC,EAAE,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,QAAQ,EAAE,GAAG,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,aAC/D,KAAC,QAAQ,KAAG,EACZ,kCAAiB,IACb,GACO,EACf,KAAC,YAAY,IAAC,KAAK,EAAC,QAAQ,gBAAY,mBAAmB,YACzD,MAAC,GAAG,IAAC,EAAE,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,QAAQ,EAAE,GAAG,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,aAC/D,KAAC,UAAU,KAAG,EACd,oCAAmB,IACf,GACO,EACd,YAAY,EAAE,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAC7B,KAAC,YAAY,IAAiB,KAAK,EAAE,MAAM,CAAC,EAAE,gBAAc,GAAG,MAAM,CAAC,KAAK,QAAQ,YACjF,KAAC,GAAG,IAAC,EAAE,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,QAAQ,EAAE,GAAG,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,YAC/D,yBAAO,MAAM,CAAC,KAAK,GAAQ,GACvB,IAHW,MAAM,CAAC,EAAE,CAIb,CAChB,CAAC,IACgB,EACnB,WAAW,IAAI,CACd,KAAC,WAAW,IAAC,YAAY,EAAE,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,QAAQ,EAAE,QAAQ,GAAI,CAC9F,IACW,GACT,CACR,CAAC;AACJ,CAAC"}

package/dist/settings/ui/UserAppearancePage.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Settings → Appearance (`/settings/appearance`).
+ *
+ * Issue #96, epic #90. The Theme card of the stacked `UserSettingsPage`, now an
+ * addressable route. THIN BY DESIGN: `ThemeSettings` is not touched, not
+ * copied, and not re-styled. Every line of shared page chrome lives in
+ * `UserSettingsSection`.
+ *
+ * This edits the signed-in user's own theme, never a deployment-wide default —
+ * there is no admin-side equivalent. The `User` filename prefix follows the
+ * same convention as this page's siblings (`UserSettingsPage.tsx`,
+ * `UserNotificationsPage.tsx`, ...), keeping every per-user settings page
+ * distinct from admin pages in `App.tsx`'s lazy imports.
+ *
+ * The title and description mirror the `Appearance` card in
+ * `config/userSettingsSections.tsx` so the hub card, the compact AppBar title
+ * (#95) and the page's own `h1` all name the page identically.
+ */
+import type { PageSlotsBase } from '../../core/index.js';
+import type { ThemeSettingsSlots } from './ThemeSettings.js';
+/**
+ * The slots of {@link UserAppearancePage}: the page-slot contract, and the
+ * theme card's own part overrides ({@link ThemeSettingsSlots}). `Sections` is
+ * where an app adds a section of its own (a density or font-size preference)
+ * above or below the theme card.
+ *
+ * @example
+ * ```tsx
+ * <UserAppearancePage slots={{ Sections: ({ position }) => (position === 'bottom' ? <DensityCard /> : null) }} />
+ * ```
+ *
+ * @extensionPoint slot
+ * @stability experimental
+ */
+export interface UserAppearancePageSlots extends PageSlotsBase, ThemeSettingsSlots {
+}
+/**
+ * Props of {@link UserAppearancePage}.
+ *
+ * @stability experimental
+ */
+export interface UserAppearancePageProps {
+    /** The page-slot contract's slots and the theme card's part overrides. */
+    slots?: UserAppearancePageSlots;
+}
+/**
+ * Settings, Appearance (`/settings/appearance`): light, dark or system, and
+ * any theme an app registered with `registerThemePreference` (listed in the
+ * settings document's `themeOptions`). The stored preference reaches the app's
+ * theme through the host's `applyTheme` (light, dark and system; an app applies
+ * a theme it registered itself).
+ *
+ * @param props - see {@link UserAppearancePageProps}.
+ * @returns the page.
+ *
+ * @example
+ * ```tsx
+ * <Route path="/settings/appearance" element={<UserAppearancePage />} />
+ * ```
+ *
+ * @extensionPoint component
+ * @stability experimental
+ */
+export declare function UserAppearancePage({ slots }?: UserAppearancePageProps): import("react").JSX.Element;
+//# sourceMappingURL=UserAppearancePage.d.ts.map

package/dist/settings/ui/UserAppearancePage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"UserAppearancePage.d.ts","sourceRoot":"","sources":["../../../src/settings/ui/UserAppearancePage.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAGzD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAG7D;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,uBAAwB,SAAQ,aAAa,EAAE,kBAAkB;CAAG;AAErF;;;;GAIG;AACH,MAAM,WAAW,uBAAuB;IACtC,0EAA0E;IAC1E,KAAK,CAAC,EAAE,uBAAuB,CAAC;CACjC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,kBAAkB,CAAC,EAAE,KAAK,EAAE,GAAE,uBAA4B,+BA2BzE"}

package/dist/settings/ui/UserAppearancePage.js

@@ -0,0 +1,33 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { themePreferenceOptions } from '../headless/theme-options.js';
+import { ThemeSettings } from './ThemeSettings.js';
+import { UserSettingsSection } from './UserSettingsSection.js';
+/**
+ * Settings, Appearance (`/settings/appearance`): light, dark or system, and
+ * any theme an app registered with `registerThemePreference` (listed in the
+ * settings document's `themeOptions`). The stored preference reaches the app's
+ * theme through the host's `applyTheme` (light, dark and system; an app applies
+ * a theme it registered itself).
+ *
+ * @param props - see {@link UserAppearancePageProps}.
+ * @returns the page.
+ *
+ * @example
+ * ```tsx
+ * <Route path="/settings/appearance" element={<UserAppearancePage />} />
+ * ```
+ *
+ * @extensionPoint component
+ * @stability experimental
+ */
+export function UserAppearancePage({ slots } = {}) {
+    return (_jsx(UserSettingsSection, { slots: slots, title: "Appearance", description: "Choose a light, dark, or system-matched theme for this account.", children: ({ settings, isSaving, save }) => (_jsx(ThemeSettings, { currentTheme: settings.theme, 
+            // The stacked page's `handleThemeChange`, message for message. The
+            // returned promise is intentionally dropped: `onThemeChange` is typed
+            // `void`, and `save` reports its own failures through the snackbar
+            // rather than rejecting.
+            onThemeChange: (theme) => {
+                void save({ theme }, { success: 'Theme updated', failure: 'Failed to update theme' });
+            }, disabled: isSaving, extraOptions: themePreferenceOptions(settings), slots: slots })) }));
+}
+//# sourceMappingURL=UserAppearancePage.js.map

package/dist/settings/ui/UserAppearancePage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"UserAppearancePage.js","sourceRoot":"","sources":["../../../src/settings/ui/UserAppearancePage.tsx"],"names":[],"mappings":";AAoBA,OAAO,EAAE,sBAAsB,EAAE,MAAM,8BAA8B,CAAC;AACtE,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAEnD,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AA4B/D;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,kBAAkB,CAAC,EAAE,KAAK,KAA8B,EAAE;IACxE,OAAO,CACL,KAAC,mBAAmB,IAClB,KAAK,EAAE,KAAK,EACZ,KAAK,EAAC,YAAY,EAClB,WAAW,EAAC,iEAAiE,YAE5E,CAAC,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC,CACjC,KAAC,aAAa,IACZ,YAAY,EAAE,QAAQ,CAAC,KAAK;YAC5B,mEAAmE;YACnE,sEAAsE;YACtE,mEAAmE;YACnE,yBAAyB;YACzB,aAAa,EAAE,CAAC,KAAK,EAAE,EAAE;gBACvB,KAAK,IAAI,CACP,EAAE,KAAK,EAAE,EACT,EAAE,OAAO,EAAE,eAAe,EAAE,OAAO,EAAE,wBAAwB,EAAE,CAChE,CAAC;YACJ,CAAC,EACD,QAAQ,EAAE,QAAQ,EAClB,YAAY,EAAE,sBAAsB,CAAC,QAAQ,CAAC,EAC9C,KAAK,EAAE,KAAK,GACZ,CACH,GACmB,CACvB,CAAC;AACJ,CAAC"}

package/dist/settings/ui/UserProfilePage.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Settings → Profile (`/settings/profile`).
+ *
+ * Issue #96, epic #90. The Profile card of the stacked `UserSettingsPage`, now
+ * an addressable route. THIN BY DESIGN: `ProfileSettings` is not touched, not
+ * copied, and not re-styled — this issue moves where the component is reached
+ * from, nothing about what it renders. Every line of shared page chrome (the
+ * hook, the spinner, the fetch-error alert, the snackbars) lives in
+ * `UserSettingsSection`.
+ *
+ * The title and description mirror the `Profile` card in
+ * `config/userSettingsSections.tsx` so the hub card, the compact AppBar title
+ * (#95) and the page's own `h1` all name the page identically.
+ */
+import type { PageSlotsBase } from '../../core/index.js';
+import type { ProfileSettingsSlots } from './ProfileSettings.js';
+/**
+ * The slots of {@link UserProfilePage}: the page-slot contract, and the profile
+ * card's own part overrides ({@link ProfileSettingsSlots}: `ExtraFields`, the
+ * fields an app added with `extendUserProfile`). `Sections` is where an app
+ * adds a section of its own (a public handle) above or below the profile card.
+ *
+ * @example
+ * ```tsx
+ * <UserProfilePage slots={{ Sections: ({ position }) => (position === 'bottom' ? <PublicHandleCard /> : null) }} />
+ * ```
+ *
+ * @extensionPoint slot
+ * @stability experimental
+ */
+export interface UserProfilePageSlots extends PageSlotsBase, ProfileSettingsSlots {
+}
+/**
+ * Props of {@link UserProfilePage}.
+ *
+ * @stability experimental
+ */
+export interface UserProfilePageProps {
+    /** The page-slot contract's slots and the profile card's part overrides (`ExtraFields`). */
+    slots?: UserProfilePageSlots;
+}
+/**
+ * Settings, Profile (`/settings/profile`): the display name and the profile
+ * picture, and the fields an app added with `extendUserProfile` when it passes
+ * the `ExtraFields` slot. Every user edits their own; the API grants it to all
+ * roles, so the page carries no permission gate.
+ *
+ * @param props - see {@link UserProfilePageProps}.
+ * @returns the page.
+ *
+ * @example
+ * ```tsx
+ * <Route path="/settings/profile" element={<UserProfilePage />} />
+ * ```
+ *
+ * @extensionPoint component
+ * @stability experimental
+ */
+export declare function UserProfilePage({ slots }?: UserProfilePageProps): import("react").JSX.Element;
+//# sourceMappingURL=UserProfilePage.d.ts.map

package/dist/settings/ui/UserProfilePage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"UserProfilePage.d.ts","sourceRoot":"","sources":["../../../src/settings/ui/UserProfilePage.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAGjE;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,oBAAqB,SAAQ,aAAa,EAAE,oBAAoB;CAAG;AAEpF;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC,4FAA4F;IAC5F,KAAK,CAAC,EAAE,oBAAoB,CAAC;CAC9B;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,eAAe,CAAC,EAAE,KAAK,EAAE,GAAE,oBAAyB,+BA0BnE"}

package/dist/settings/ui/UserProfilePage.js

@@ -0,0 +1,29 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { ProfileSettings } from './ProfileSettings.js';
+import { UserSettingsSection } from './UserSettingsSection.js';
+/**
+ * Settings, Profile (`/settings/profile`): the display name and the profile
+ * picture, and the fields an app added with `extendUserProfile` when it passes
+ * the `ExtraFields` slot. Every user edits their own; the API grants it to all
+ * roles, so the page carries no permission gate.
+ *
+ * @param props - see {@link UserProfilePageProps}.
+ * @returns the page.
+ *
+ * @example
+ * ```tsx
+ * <Route path="/settings/profile" element={<UserProfilePage />} />
+ * ```
+ *
+ * @extensionPoint component
+ * @stability experimental
+ */
+export function UserProfilePage({ slots } = {}) {
+    return (_jsx(UserSettingsSection, { slots: slots, title: "Profile", description: "Your display name and profile image, and the email you signed in with.", children: ({ settings, isSaving, save, replaceSettings }) => (_jsx(ProfileSettings, { profile: settings.profile, 
+            // The stacked page's `handleProfileSave`, message for message.
+            onSave: (profile) => save({ profile }, { success: 'Profile updated', failure: 'Failed to update profile' }), 
+            // Upload/remove return the new settings document (#367); adopting it
+            // keeps the stored `version` current for the next PATCH.
+            onSettingsReplaced: replaceSettings, disabled: isSaving, slots: slots })) }));
+}
+//# sourceMappingURL=UserProfilePage.js.map

package/dist/settings/ui/UserProfilePage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"UserProfilePage.js","sourceRoot":"","sources":["../../../src/settings/ui/UserProfilePage.tsx"],"names":[],"mappings":";AAgBA,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAEvD,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AA4B/D;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,eAAe,CAAC,EAAE,KAAK,KAA2B,EAAE;IAClE,OAAO,CACL,KAAC,mBAAmB,IAClB,KAAK,EAAE,KAAK,EACZ,KAAK,EAAC,SAAS,EACf,WAAW,EAAC,wEAAwE,YAEnF,CAAC,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,eAAe,EAAE,EAAE,EAAE,CAAC,CAClD,KAAC,eAAe,IACd,OAAO,EAAE,QAAQ,CAAC,OAAO;YACzB,+DAA+D;YAC/D,MAAM,EAAE,CAAC,OAAO,EAAE,EAAE,CAClB,IAAI,CACF,EAAE,OAAO,EAAE,EACX,EAAE,OAAO,EAAE,iBAAiB,EAAE,OAAO,EAAE,0BAA0B,EAAE,CACpE;YAEH,qEAAqE;YACrE,yDAAyD;YACzD,kBAAkB,EAAE,eAAe,EACnC,QAAQ,EAAE,QAAQ,EAClB,KAAK,EAAE,KAAK,GACZ,CACH,GACmB,CACvB,CAAC;AACJ,CAAC"}

package/dist/settings/ui/UserSettingsSection.d.ts

@@ -0,0 +1,141 @@
+/**
+ * Shared chrome for every `/settings/*` page that edits the user settings
+ * document.
+ *
+ * Issue #96, epic #90. The exact counterpart of
+ * `pages/Admin/SystemSettingsSection.tsx` (#92), for the same reason and with
+ * the same shape. `UserSettingsPage` used to be one component stacking three
+ * cards, and with it ONE copy of the wiring those cards shared: the
+ * `useUserSettings` hook, the loading spinner, the fetch-error alert, and the
+ * success/failure snackbars. Splitting the stack into routed pages without
+ * extracting that wiring would have produced a copy of it per page — and the
+ * whole point of epic #90 is that near-identical copies drift within a release.
+ * There is still exactly one copy; it just lives here now.
+ *
+ * ONE HOOK CALL PER PAGE, NOT ONE FOR THE SURFACE. Each routed page mounts its
+ * own `UserSettingsSection`, so each owns its own `useUserSettings()` and its
+ * own snackbar state. That is the behavioural change #96 asks for: on the old
+ * stacked page a successful theme save raised a toast that sat visually
+ * alongside the Profile card, because there was one snackbar for three
+ * sections. Two pages that are never mounted together cannot do that. The cost
+ * is one `GET /user-settings` per settings page visit, which is the same cost
+ * the admin split already accepted and is dwarfed by the page's own chunk.
+ *
+ * A RENDER PROP rather than an outlet or a HOC — same argument as the admin
+ * wrapper. `ThemeSettings` and `ProfileSettings` take `settings` fields as
+ * VALUES and are deliberately left untouched by this issue, so the state has to
+ * arrive as arguments. It also lets `settings` be NON-NULLABLE in the callback:
+ * the null case is handled once, here, so neither page repeats a
+ * `settings && …` guard that TypeScript would otherwise demand of both.
+ *
+ * NO `RequirePermission`, NO `hasPermission` CHECK, unlike the admin wrapper —
+ * and that is a deliberate difference, not an omission. These are the user's
+ * own settings; the API grants `user_settings:read` / `user_settings:write` to
+ * all three roles, and `config/userSettingsSections.tsx` declares no
+ * `permission` on any card for the same reason. A gate here would be inventing
+ * an authorization rule the API does not enforce, and would lock users out of
+ * their own profile.
+ *
+ * NO `<Paper>` AROUND THE CHILDREN, unlike the admin wrapper. The admin editors
+ * are bare form controls that need section chrome; `ThemeSettings`,
+ * `ProfileSettings` and `PersonalAccessTokens` each render their own `<Card>`
+ * already, and nesting those in a Paper stacks two elevated surfaces with a
+ * hairline of background between them.
+ */
+import type { ReactNode } from 'react';
+import type { ThemePreferenceId, UserSettingsResponseBase } from '@marinoscar/platform-contract/settings';
+import type { PageSlotsBase } from '../../core/index.js';
+/**
+ * The PATCH body the routed pages send: a theme and/or profile fields.
+ *
+ * @stability experimental
+ */
+export type UserSettingsUpdate = {
+    /** A new theme preference: light, dark, system, or an id an app registered. */
+    theme?: ThemePreferenceId;
+    /** New profile fields, the ones an app added with `extendUserProfile` included (`null` deletes one). */
+    profile?: Partial<UserSettingsResponseBase['profile']> & Record<string, unknown>;
+};
+/**
+ * The strings a save raises, per call site. See `save` below.
+ *
+ * @stability experimental
+ */
+export interface UserSettingsSaveMessages {
+    /** Shown in the success snackbar, e.g. `'Theme updated'`. */
+    success: string;
+    /**
+     * Success-path fallback for the ERROR snackbar when the rejection is not an
+     * `Error` and therefore carries no `.message`, e.g. `'Failed to update theme'`.
+     * Carried per call site rather than hardcoded to one generic string so the
+     * two pages keep the exact copy the stacked page used.
+     */
+    failure: string;
+}
+/**
+ * What a settings page gets handed once the document has loaded.
+ *
+ * @stability experimental
+ */
+export interface UserSettingsSectionState {
+    /** The loaded document. */
+    settings: UserSettingsResponseBase;
+    /** True while a PATCH is in flight. Pages pass it straight to `disabled`. */
+    isSaving: boolean;
+    /**
+     * PATCH a partial settings document and raise the success snackbar.
+     *
+     * SWALLOWS the rejection into the error snackbar rather than rethrowing —
+     * this is `UserSettingsPage`'s `handleThemeChange` / `handleProfileSave`
+     * unchanged, and both callers depend on it. `ProfileSettings.handleSave`
+     * awaits `onSave` and then calls `refreshUser()` outside any try/catch: if
+     * this rethrew, a failed save would skip that refresh and leave the form's
+     * `isSaving` cleared only by its `finally`, with the rejection escaping as an
+     * unhandled promise. `ThemeSettings.onThemeChange` is typed `void` and does
+     * not even receive the promise.
+     */
+    save: (updates: UserSettingsUpdate, messages: UserSettingsSaveMessages) => Promise<void>;
+    /**
+     * Adopt a settings document an endpoint other than `PATCH /user-settings`
+     * already returned (the profile-image upload/delete responses), so the
+     * stored `version` stays current, and optionally raise the success snackbar.
+     */
+    replaceSettings: (settings: UserSettingsResponseBase, successMessage?: string) => void;
+}
+/**
+ * Props of {@link UserSettingsSection}.
+ *
+ * @stability experimental
+ */
+export interface UserSettingsSectionProps {
+    /** `h1` for the page. Mirrors the card title in `userSettingsSections.tsx`. */
+    title: string;
+    /** Secondary line under the title. Mirrors the card description. */
+    description: string;
+    /** Renders the page body once the document has loaded. */
+    children: (state: UserSettingsSectionState) => ReactNode;
+    /**
+     * The page-slot contract's slots, handed to the page chrome. Omitted, the
+     * chrome is exactly what it always was. The loading spinner is not slotted.
+     */
+    slots?: PageSlotsBase;
+}
+/**
+ * The shared chrome of every routed `/settings/*` page that edits the user
+ * settings document (the Profile and Appearance pages): the hook, the
+ * spinner, the fetch-error alert and the success and failure snackbars.
+ *
+ * @param props - see {@link UserSettingsSectionProps}.
+ * @returns the page.
+ *
+ * @example
+ * ```tsx
+ * <UserSettingsSection title="Appearance" description="Pick a theme.">
+ *   {({ settings, save }) => <Theme value={settings.theme} onChange={(theme) => save({ theme }, msgs)} />}
+ * </UserSettingsSection>
+ * ```
+ *
+ * @stability experimental
+ */
+export declare function UserSettingsSection({ title, description, children, slots, }: UserSettingsSectionProps): import("react").JSX.Element;
+//# sourceMappingURL=UserSettingsSection.d.ts.map

package/dist/settings/ui/UserSettingsSection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"UserSettingsSection.d.ts","sourceRoot":"","sources":["../../../src/settings/ui/UserSettingsSection.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAEvC,OAAO,KAAK,EAAE,iBAAiB,EAAE,wBAAwB,EAAE,MAAM,wCAAwC,CAAC;AAE1G,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAIzD;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC/B,+EAA+E;IAC/E,KAAK,CAAC,EAAE,iBAAiB,CAAC;IAC1B,wGAAwG;IACxG,OAAO,CAAC,EAAE,OAAO,CAAC,wBAAwB,CAAC,SAAS,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClF,CAAC;AAEF;;;;GAIG;AACH,MAAM,WAAW,wBAAwB;IACvC,6DAA6D;IAC7D,OAAO,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;GAIG;AACH,MAAM,WAAW,wBAAwB;IACvC,2BAA2B;IAC3B,QAAQ,EAAE,wBAAwB,CAAC;IACnC,6EAA6E;IAC7E,QAAQ,EAAE,OAAO,CAAC;IAClB;;;;;;;;;;;OAWG;IACH,IAAI,EAAE,CAAC,OAAO,EAAE,kBAAkB,EAAE,QAAQ,EAAE,wBAAwB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACzF;;;;OAIG;IACH,eAAe,EAAE,CAAC,QAAQ,EAAE,wBAAwB,EAAE,cAAc,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;CACxF;AAED;;;;GAIG;AACH,MAAM,WAAW,wBAAwB;IACvC,+EAA+E;IAC/E,KAAK,EAAE,MAAM,CAAC;IACd,oEAAoE;IACpE,WAAW,EAAE,MAAM,CAAC;IACpB,0DAA0D;IAC1D,QAAQ,EAAE,CAAC,KAAK,EAAE,wBAAwB,KAAK,SAAS,CAAC;IACzD;;;OAGG;IACH,KAAK,CAAC,EAAE,aAAa,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,mBAAmB,CAAC,EAClC,KAAK,EACL,WAAW,EACX,QAAQ,EACR,KAAK,GACN,EAAE,wBAAwB,+BAyF1B"}