@molecule/app-settings-panel-react 1.0.0

package/LICENSE

@@ -0,0 +1,115 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work.
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship.
+
+      "Contribution" shall mean any work of authorship, including the
+      original version of the Work and any modifications or additions
+      to that Work, that is intentionally submitted to the Licensor for
+      inclusion in the Work by the copyright owner or by an individual or
+      Legal Entity authorized to submit on behalf of the copyright owner.
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by the Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      patent license to make, have made, use, offer to sell, sell, import,
+      and otherwise transfer the Work.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file.
+
+   5. Submission of Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND.
+
+   8. Limitation of Liability. In no event and under no legal theory shall
+      any Contributor be liable to You for damages.
+
+   9. Accepting Warranty or Additional Liability.
+
+   Copyright 2026 Molecule Dev, Inc.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,487 @@
+<!--
+AUTO-GENERATED — DO NOT EDIT THIS FILE.
+Generated by `mlcl sync-docs` from the package's src/index.ts JSDoc + mlcl/registry.json.
+Edits here are overwritten on the next commit (molecule's pre-commit hook regenerates).
+To change this document, edit the module-level JSDoc in src/index.ts.
+Generated: 2026-08-04T00:41:05.064Z
+-->
+
+# @molecule/app-settings-panel-react
+
+> **Auto-generated, AI-first package reference** for the [molecule.dev](https://molecule.dev) ecosystem.
+> It is written to be read by coding agents as much as by people, and is generated from this
+> package's source — edit `src/index.ts` JSDoc, not this file.
+
+`@molecule/app-settings-panel-react` — composable, batteries-included
+settings panel.
+
+`<SettingsContainer onClose={…}>` owns the layout and publishes `onClose`
+via context; each section component is independent and loads its own data
+through hooks:
+
+- `<AccountSection>` — name/email edit (`PATCH /api/users/:id`).
+- `<AppearanceSection>` — dark-mode toggle (`useTheme()`).
+- `<AuthSection>` — password change + TOTP two-factor
+  (`POST /api/users/:id/verify-two-factor`).
+- `<NotificationsSection>` — web-push toggle (see the exported
+  `enablePushOnCurrentDevice` / `disablePushOnCurrentDevice` helpers and
+  their documented device-row contract).
+- `<BillingSection>` — read-only plan display (`GET /api/billing/status`),
+  or `<TiersUpgradeSection>` — full Stripe upgrade/cancel flow
+  (`/api/billing/tiers|checkout|cancel`). Use one or the other, not both.
+- `<DevicesSection>` / `<ThisDeviceSection>` — device list + current
+  device (`GET/DELETE /api/devices`).
+- `<LogOutDeleteSection>` — sign out + delete account
+  (`DELETE /api/users/:id`).
+  Apps compose via JSX children — pick sections, order them, and interleave
+  custom sections.
+
+## Quick Start
+
+```tsx
+import {
+  AccountSection,
+  AppearanceSection,
+  AuthSection,
+  BillingSection,
+  DevicesSection,
+  LogOutDeleteSection,
+  NotificationsSection,
+  SettingsContainer,
+  ThisDeviceSection,
+} from '@molecule/app-settings-panel-react'
+
+function SettingsPanel({ onClose }: { onClose: () => void }) {
+  return (
+    <SettingsContainer onClose={onClose}>
+      <AccountSection />
+      <AppearanceSection />
+      <AuthSection />
+      <NotificationsSection />
+      <BillingSection />
+      <DevicesSection />
+      <ThisDeviceSection />
+      <LogOutDeleteSection />
+    </SettingsContainer>
+  )
+}
+```
+
+## Type
+
+`feature`
+
+## Installation
+
+```bash
+npm install @molecule/app-settings-panel-react @molecule/app-auth @molecule/app-react @molecule/app-ui @molecule/app-ui-react react react-router
+npm install -D @types/react
+```
+
+## API
+
+### Interfaces
+
+#### `Device`
+
+A user's registered device (subset rendered in the settings list).
+
+```typescript
+interface Device {
+  id: string
+  name: string
+  platform: string
+  lastSeen?: string
+  /** `true` for the device making the current request (the API marks it). */
+  isCurrent?: boolean
+}
+```
+
+#### `PushToggleDevice`
+
+Device row slice returned by `GET /api/devices`.
+
+```typescript
+interface PushToggleDevice {
+  id: string
+  isCurrent?: boolean
+  hasPushSubscription?: boolean
+}
+```
+
+#### `PushToggleHttp`
+
+Minimal structural slice of `@molecule/app-http`'s HttpClient used here.
+
+```typescript
+interface PushToggleHttp {
+  get<T = unknown>(url: string): Promise<{ data: T }>
+  patch<T = unknown>(url: string, data?: unknown): Promise<{ data: T }>
+}
+```
+
+#### `PushToggleToken`
+
+Push token slice returned by `@molecule/app-push` `register()`.
+
+```typescript
+interface PushToggleToken {
+  value: string
+  platform: 'web' | 'ios' | 'android'
+}
+```
+
+#### `SettingsPanelContextValue`
+
+Context published by `<SettingsContainer>` to its children.
+
+The container owns the dismiss-the-panel handler; sub-components
+that need to close after an action (logout, delete account, email
+error) read it from context rather than threading the prop down.
+
+```typescript
+interface SettingsPanelContextValue {
+  onClose: () => void
+}
+```
+
+### Types
+
+#### `PushToggleFailureReason`
+
+Why an enable/disable attempt failed (mapped to i18n by the component).
+
+```typescript
+type PushToggleFailureReason =
+  'permission-denied' | 'server-unconfigured' | 'register-failed' | 'persist-failed'
+```
+
+#### `PushToggleResult`
+
+Result of an enable/disable attempt.
+
+```typescript
+type PushToggleResult =
+  { ok: true } | { ok: false; reason: PushToggleFailureReason; message?: string }
+```
+
+### Functions
+
+#### `AccountSection()`
+
+Account section — edits the user's display name + email. Fetches
+`/users/me` on mount to refresh the current user record (and write it
+back to the auth cache so subsequent reloads see the latest data). On
+blur of either field, PATCHes `/api/users/:id` with the changed field;
+reverts + shows an inline error if the request fails.
+
+The user resource's update handler accepts `name`, `username`, and
+`email`; this surfaces `name` + `email` (the universally-present
+profile fields). Apps that use a public `username` handle can extend
+this with a username field the same way.
+
+```typescript
+function AccountSection(): JSX.Element
+```
+
+#### `AppearanceSection()`
+
+Appearance section — dark-mode toggle wired to the theme bond.
+
+Apps that expose other appearance knobs (font size, density, etc.)
+can either add more sub-components to this package or render their
+own section in line with `<AppearanceSection>` via children.
+
+```typescript
+function AppearanceSection(): JSX.Element
+```
+
+#### `AuthSection()`
+
+Authentication section — change password (modal) + two-factor (TOTP) setup.
+
+Two-factor uses the real enrollment flow against the user resource's
+`POST /users/:id/verify-two-factor` endpoint (`@molecule/api-two-factor`):
+
+- Enable → `{action:'setup'}` returns a QR code + secret to scan into an
+  authenticator app → user enters the 6-digit code → `{action:'enable', token}`.
+- Disable → user enters a current code → `{action:'disable', token}`.
+  The current status is read from `/users/me`. (This replaces the previous
+  boolean toggle, which PATCHed `twoFactorEnabled` — a field the update
+  handler deliberately ignores — so it never actually enrolled 2FA.)
+
+Auto-hides for OAuth-only users (`user.oauthServer` truthy) since
+password / 2FA wouldn't apply. If the app's API has no two-factor
+provider bonded, setup fails gracefully with an inline message.
+
+```typescript
+function AuthSection(): JSX.Element | null
+```
+
+#### `BillingSection(props?)`
+
+Billing section — current plan + Upgrade button.
+
+Fetches `/api/billing/status` on mount and uses the returned plan
+name as a more accurate label than the parent-supplied default.
+The `plan` prop remains a fallback (e.g. for offline rendering or
+apps that don't expose `/billing/status`).
+
+The Upgrade button navigates to `upgradeTo` (default `/settings`).
+Pass `upgradeTo="/billing"` or `upgradeTo="/pricing"` if your app
+routes elsewhere. Apps with a multi-tier checkout flow should use
+`<TiersUpgradeSection>` instead.
+
+```typescript
+function BillingSection({
+  plan = 'Free',
+  upgradeTo = '/settings',
+}?: {
+  plan?: string
+  upgradeTo?: string
+}): JSX.Element
+```
+
+#### `DevicesSection(props?)`
+
+Devices section — lists the user's registered devices and lets them
+revoke (sign out) any device other than the one they're currently using.
+
+Revoking deletes the device row (`DELETE /api/devices/:id`). The API's
+authorization layer enforces server-side revocation: it rejects that
+device's session the next time it makes a request (within the
+device-exists cache TTL), so the removed device is actually signed out —
+not just hidden from the list. The current device is labelled
+"This device" and is not revocable here (use Sign out for the current
+session). Recreates molecule v1's device-revocation behaviour.
+
+Apps that want a different trailing element per row can pass a
+`renderRowIcon` callback (which then replaces the built-in revoke
+control); pass `() => null` to suppress it entirely.
+
+```typescript
+function DevicesSection({
+  renderRowIcon,
+}?: {
+  renderRowIcon?: (device: Device) => ReactNode
+}): JSX.Element
+```
+
+#### `disablePushOnCurrentDevice(deps)`
+
+Disables push: unsubscribes the browser (best-effort — a dev build without
+a service worker has nothing to unsubscribe) and ALWAYS clears the server
+state so no further pushes target this device.
+
+```typescript
+function disablePushOnCurrentDevice(deps: {
+  http: PushToggleHttp
+  unregister: () => Promise<void>
+}): Promise<PushToggleResult>
+```
+
+- `deps` — The http client + push action from `usePush()`.
+- `deps.http` — Authenticated http client (`useHttpClient()`).
+- `deps.unregister` — `usePush().unregister`.
+
+**Returns:** `{ ok: true }` or a typed failure (server state not cleared).
+
+#### `enablePushOnCurrentDevice(deps)`
+
+Runs the full enable chain: browser permission → runtime VAPID public key
+(`GET /api/devices/push/public-key`) → `register({ vapidPublicKey })` →
+persist the subscription on the current device row.
+
+Every failure is returned as a typed reason (never thrown) so the UI can
+show an honest, specific message instead of hanging or silently reverting.
+
+```typescript
+function enablePushOnCurrentDevice(deps: {
+  http: PushToggleHttp
+  requestPermission: () => Promise<string>
+  register: (options?: { vapidPublicKey?: string }) => Promise<PushToggleToken>
+}): Promise<PushToggleResult>
+```
+
+- `deps` — The http client + push actions from `usePush()`.
+- `deps.http` — Authenticated http client (`useHttpClient()`).
+- `deps.requestPermission` — `usePush().requestPermission`.
+- `deps.register` — `usePush().register`.
+
+**Returns:** `{ ok: true }` or a typed failure.
+
+#### `findCurrentDevice(devices)`
+
+Picks the caller's own device row: the api flags the session device
+`isCurrent`; fall back to the first row for sessions predating the flag.
+
+```typescript
+function findCurrentDevice(devices: PushToggleDevice[] | undefined): PushToggleDevice | undefined
+```
+
+- `devices` — Rows from `GET /api/devices`.
+
+**Returns:** The current device row, or `undefined` when the user has none.
+
+#### `LogOutDeleteSection()`
+
+Bottom actions section — Log out + Delete account.
+
+Owns the delete-account modal internally (the trigger lives in the
+same section so the modal lives here too). Reads `onClose` from
+the `<SettingsContainer>` context to dismiss the panel after either
+action and navigates to `/login`.
+
+```typescript
+function LogOutDeleteSection(): JSX.Element
+```
+
+#### `NotificationsSection()`
+
+Push-notification toggle section — the full receive-side enable chain:
+browser permission → runtime VAPID public key
+(`GET /api/devices/push/public-key`) → `pushManager.subscribe` with
+`applicationServerKey` → PATCH the subscription onto the current device
+row (`/api/devices/:id { pushSubscription, hasPushSubscription }`), which
+is where the api-side push fan-outs look for it.
+
+Initial state reflects SERVER truth (the current device row's
+`hasPushSubscription`), and every failure surfaces as an honest inline
+message — a dev build without a service worker fails fast instead of
+hanging the switch.
+
+```typescript
+function NotificationsSection(): JSX.Element
+```
+
+#### `readCurrentDevicePushEnabled(http)`
+
+Reads whether push is currently enabled for THIS device (server truth:
+the current device row's `hasPushSubscription`).
+
+```typescript
+function readCurrentDevicePushEnabled(http: PushToggleHttp): Promise<boolean>
+```
+
+- `http` — Authenticated http client (`useHttpClient()`).
+
+**Returns:** `true` when the current device has a stored subscription.
+
+#### `SettingsContainer(props)`
+
+Outer settings-panel layout: padded vertical stack that hosts the
+section sub-components. Publishes `onClose` to descendants via
+context so `<LogOutDeleteSection>` etc. can dismiss the panel
+after an action without explicit prop threading.
+
+```typescript
+function SettingsContainer({
+  onClose,
+  children,
+}: {
+  onClose: () => void
+  children: ReactNode
+}): ReactElement<unknown, string | JSXElementConstructor<any>>
+```
+
+#### `subscriptionFromToken(token)`
+
+Converts an `@molecule/app-push` token into the device resource's
+`pushSubscription` shape (web PushSubscription JSON, FCM registration for
+Android, APNs registration for iOS).
+
+```typescript
+function subscriptionFromToken(token: PushToggleToken): unknown
+```
+
+- `token` — The push token returned by `register()`.
+
+**Returns:** The `pushSubscription` value to PATCH onto the device row.
+
+#### `ThisDeviceSection()`
+
+"This device" detail strip — OS, browser, online/offline.
+
+Reads from `@molecule/app-device` (useDevice hook) + browser
+`navigator.onLine`. No side effects, no app-specific state.
+
+```typescript
+function ThisDeviceSection(): JSX.Element
+```
+
+#### `TiersUpgradeSection()`
+
+Billing section with full multi-tier upgrade flow.
+
+Replaces the simpler `<BillingSection>` for apps backed by
+`@molecule/api-payments-stripe` + `@molecule/api-resource-payment`
+— loads the user's current plan from `/api/billing/status`,
+loads available tiers from `/api/billing/tiers`, and renders an
+Upgrade modal with a Subscribe button per tier price. Subscribe
+POSTs to `/api/billing/checkout` and redirects to the Stripe
+checkout URL; paid users see a Cancel button that POSTs to
+`/api/billing/cancel`.
+
+```typescript
+function TiersUpgradeSection(): JSX.Element
+```
+
+#### `useSettingsPanelContext()`
+
+Reads the `onClose` handler exposed by the parent `<SettingsContainer>`.
+Throws if used outside the container so component misuse is loud.
+
+```typescript
+function useSettingsPanelContext(): SettingsPanelContextValue
+```
+
+### Constants
+
+#### `SettingsPanelContext`
+
+React context object for the settings panel; consume via `useSettingsPanelContext`.
+
+```typescript
+const SettingsPanelContext: Context<SettingsPanelContextValue | null>
+```
+
+## Injection Notes
+
+### Requirements
+
+Peer dependencies:
+
+- `@molecule/app-auth` ^1.0.0
+- `@molecule/app-react` ^1.0.0
+- `@molecule/app-ui` ^1.0.0
+- `@molecule/app-ui-react` ^1.0.0
+- `react` ^18.0.0 || ^19.0.0
+- `react-router` ^7.0.0 || ^8.0.0
+
+### Runtime Dependencies
+
+- `@molecule/app-auth`
+- `@molecule/app-react`
+- `@molecule/app-ui`
+- `@molecule/app-ui-react`
+- `react`
+- `react-router`
+
+- Wiring prereqs: sections need the standard `@molecule/app-react`
+  provider stack — `<I18nProvider>`, `<HttpProvider>` (authenticated
+  client), `<AuthProvider>`, `<ThemeProvider>` (AppearanceSection), push +
+  device providers (NotificationsSection/ThisDeviceSection) — plus a
+  bonded ClassMap. `<BillingSection>` and `<LogOutDeleteSection>` also
+  call react-router's `useNavigate()` and throw outside a `<Router>`.
+- Section components throw if rendered outside `<SettingsContainer>`
+  (they read its context for `onClose`).
+- Server contract: the molecule API surface from
+  `@molecule/api-resource-user`, `@molecule/api-resource-device`,
+  `@molecule/api-two-factor`, and the billing endpoints
+  (`/api/billing/*`) wired by the payments stack. Missing read endpoints
+  degrade gracefully (sections render empty); the mutating actions do not.
+- Translations: `@molecule/app-locales-settings-panel` companion bond.
+
+## Translations
+
+Translation strings are provided by `@molecule/app-locales-settings-panel`.

package/dist/AccountSection.d.ts

@@ -0,0 +1,15 @@
+import { type JSX } from 'react';
+/**
+ * Account section — edits the user's display name + email. Fetches
+ * `/users/me` on mount to refresh the current user record (and write it
+ * back to the auth cache so subsequent reloads see the latest data). On
+ * blur of either field, PATCHes `/api/users/:id` with the changed field;
+ * reverts + shows an inline error if the request fails.
+ *
+ * The user resource's update handler accepts `name`, `username`, and
+ * `email`; this surfaces `name` + `email` (the universally-present
+ * profile fields). Apps that use a public `username` handle can extend
+ * this with a username field the same way.
+ */
+export declare function AccountSection(): JSX.Element;
+//# sourceMappingURL=AccountSection.d.ts.map

package/dist/AccountSection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AccountSection.d.ts","sourceRoot":"","sources":["../src/AccountSection.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,GAAG,EAAuB,MAAM,OAAO,CAAA;AAcrD;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,IAAI,GAAG,CAAC,OAAO,CA6G5C"}