rich-react-component 0.1.0 → 0.3.0

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 suleymangulle
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 suleymangulle
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,118 +1,314 @@
-# rich-react-component
-
-Repository: [github.com/suleymangulle/rich-react-component](https://github.com/suleymangulle/rich-react-component) (private) · [npm](https://www.npmjs.com/package/rich-react-component)
-
-[![npm version](https://img.shields.io/npm/v/rich-react-component.svg)](https://www.npmjs.com/package/rich-react-component)
-
-Enterprise React + TypeScript component library built on **Bootstrap + Metronic** conventions, organized into three capability layers:
-
-```text
-Base    — pure UI behavior, no HTTP, no backend knowledge
-Remote  — adds remote-data fetching to Base components by composing them
-Smart   — metadata-driven configuration layer (Phases 1-5 complete)
-```
-
-Each layer **reuses** the one below it instead of reimplementing it — `RemoteComboBox` composes `ComboBox`, it does not contain a second combobox implementation. See [`react-components-initial.md`](./react-components-initial.md) for the original architecture brief this library follows.
-
-## Install
-
-```bash
-npm install rich-react-component bootstrap react react-dom
-```
-
-`bootstrap`, `react`, and `react-dom` are peer dependencies — the library ships no CSS of its own beyond what Bootstrap classes provide.
-
-```tsx
-import "bootstrap/dist/css/bootstrap.min.css";
-```
-
-## Quick example
-
-```tsx
-import { ComboBox, SmartField } from "rich-react-component";
-import { RemoteComboBox } from "rich-react-component";
-
-// Base — you own the data
-<ComboBox
-  options={[{ value: "tr", label: "Turkey" }]}
-  value={countryId}
-  onChange={setCountryId}
-/>
-
-// Remote — the component owns fetching, cancellation, and stale-response
-// protection; you only describe the endpoint and the field mapping
-<RemoteComboBox
-  url="/api/countries"
-  valueMember="id"
-  displayMember="name"
-  value={countryId}
-  onChange={setCountryId}
-/>
-
-// Smart — the server describes the field, SmartField resolves it onto
-// RemoteComboBox for you; visible/readOnly/required/validation all come
-// from metadata instead of being written by hand at every call site
-<SmartField
-  metadata={{
-    name: "countryId", component: "ComboBox",
-    valueMember: "id", displayMember: "name",
-    dataSource: { id: "Countries" },
-  }}
-  ctx={ctx} // { values, onFieldChange, registry, dataSources, actions }
-/>
-```
-
-## What's in each layer
-
-**Base** (49 components) — form fields (`Input`, `NumberInput`, `PasswordInput`, `FileInput`, `CheckBox`, `Switch`, `RadioGroup`, `Select`, `MultiSelect`, `DatePicker`, `TimePicker`, `DateTimePicker`, `ComboBox`, `AutoComplete`, `FormField`), feedback (`Modal`, `Toast`, `Confirm`, `Alert`, `Spinner`, `Badge`, `Skeleton`), data display (`DataGrid`, `Pagination`, `Avatar`, `Tag`, `Rating`, `ProgressBar`), navigation (`Breadcrumb`, `Menu`, `Stepper`, `Tabs`, `Navbar`, `Sidebar`, `PageHeader`), layout (`Card`, `Divider`, `Stack`, `Container`, `Row`, `Col`), and more (`Button`, `Tooltip`, `Popover`, `Accordion`, `Icon`).
-
-**Remote** — `RemoteComboBox`, `RemoteAutoComplete`, `RemoteSelect`, `RemoteMultiSelect`, `RemoteDataGrid`, backed by a shared `HttpClient` abstraction and a `useRemoteData` hook that handles request cancellation, stale-response protection, and a consistent `idle/loading/success/empty/error` state model.
-
-**Smart** — *Phases 1-5 complete, the full approved plan.* A metadata-driven layer: the server describes a field or action, Smart resolves that description onto the exact Base/Remote component that already exists — it never reimplements one.
-
-- **Metadata contract** — a discriminated union per component type (`InputMetadata | ComboBoxMetadata | DatePickerMetadata | DataGridMetadata`), plus `SmartActionMetadata` for buttons. Declarative only: no expressions, no serialized functions.
-- **Registries** — `SmartComponentRegistry` (keyed by the `component` discriminant, not a switch), `SmartDataSourceRegistry` and `SmartActionRegistry` (id-based indirection — metadata never carries a raw URL or a function).
-- **Built-in resolvers** — Input, ComboBox, DatePicker, and DataGrid, registered via `registerBuiltInResolvers()` through the exact same call a custom application component would use. DataGrid's column metadata (`format: "text" | "date" | "currency" | "boolean"`) maps to a small, Smart-owned set of formatters — the server requests a formatter, never ships one.
-- **Headless engine** — `useSmartField` / `useSmartAction` resolve one field/action's metadata (visibility, validation, localized label, resolved request params); `useSmartDependencies` tracks `dependsOn` and reports which field needs fresh metadata when a value it depends on changes.
-- **Components** — `SmartField` / `SmartAction` resolve one piece of metadata into UI; `SmartForm` / `SmartActions` are thin iteration helpers over a whole `SmartFormMetadata` — no field-value ownership, no business-rule evaluation, no layout decisions.
-
-## Demo pages
-
-Two dev-only pages exercise the library live — not part of the published package:
-
-```bash
-npm run dev
-```
-
-- `/index.html` — every Base/Remote component in one manual-test page
-- `/smart-demo.html` — the full Phase 1-5 Smart engine end to end: a cascading Country/City form and server-driven field visibility/validation rendered through one `<SmartForm>` call, a paginated DataGrid through one `<SmartField>` call, `<SmartActions>` with a real fail-safe-disabled button, a dependency-refresh log, and EN/TR localization (including the DataGrid's boolean formatter) — with in-page documentation popups
-
-## Scripts
-
-| Command | Description |
-| --- | --- |
-| `npm run dev` | Start the demo pages with Vite |
-| `npm run build` | Type-check + build the library to `dist/` (ESM, CJS, `.d.ts`) |
-| `npm test` | Run the test suite once (Vitest) |
-| `npm run test:watch` | Run tests in watch mode |
-| `npm run typecheck` | Type-check the whole project without emitting |
-
-## Project structure
-
-```text
-src/
-├── base/     # Base layer — no dependency on remote/ or smart/
-├── remote/   # Remote layer — may depend on base/, not on smart/
-├── smart/    # Smart layer (Phases 1-5) — may depend on base/ and remote/
-└── index.ts  # public entry point
-
-demo/         # dev-only manual-test pages (not published)
-```
-
-## Testing
-
-Behavioral tests over snapshots. Every capability layer is tested against its own contract — Base components never call `fetch`, Remote components reuse (not duplicate) their Base counterpart's UI, dependency-driven param changes reload correctly without stale-response races, and the Smart registry falls back safely for an unresolved component type instead of rendering the wrong thing.
-
-## License
-
-[MIT](./LICENSE) © suleymangulle
+# rich-react-component
+
+Repository: [github.com/suleymangulle/rich-react-component](https://github.com/suleymangulle/rich-react-component) (private) · [npm](https://www.npmjs.com/package/rich-react-component)
+
+[![npm version](https://img.shields.io/npm/v/rich-react-component.svg)](https://www.npmjs.com/package/rich-react-component)
+
+Enterprise React + TypeScript component library built on **Bootstrap + Metronic** conventions, organized into three capability layers:
+
+```text
+Base    — pure UI behavior, no HTTP, no backend knowledge
+Remote  — adds remote-data fetching to Base components by composing them
+Smart   — metadata-driven configuration layer (Phases 1-5 complete)
+```
+
+Each layer **reuses** the one below it instead of reimplementing it — `RemoteComboBox` composes `ComboBox`, it does not contain a second combobox implementation. See [`react-components-initial.md`](./react-components-initial.md) for the original architecture brief this library follows.
+
+## Install
+
+```bash
+npm install rich-react-component bootstrap react react-dom
+```
+
+`bootstrap`, `react`, and `react-dom` are peer dependencies — the library ships no CSS of its own beyond what Bootstrap classes provide.
+
+```tsx
+import "bootstrap/dist/css/bootstrap.min.css";
+```
+
+The library ships one opt-in stylesheet: a repository-owned **Metronic Bootstrap
+visual skin** covering every public component. It is emitted as a separate
+`dist/style.css` asset, so importing the package entry point stays
+side-effect-free for SSR. Load it after Bootstrap and before your own overrides:
+
+```tsx
+import "bootstrap/dist/css/bootstrap.min.css";
+import "rich-react-component/style.css";
+// ...then your application's own overrides
+```
+
+Every rule in it is anchored on a library-owned `rrc-*` class, so importing it
+cannot repaint your own Bootstrap markup — components emit both their Bootstrap
+class and their `rrc-*` class, and a consumer who skips the import keeps plain
+Bootstrap. It is **not** the official Metronic stylesheet: no licensed Metronic
+or KeenIcons asset is used. Typography prefers Inter but the package never
+fetches a font; supply Inter from your application and it is picked up, or opt
+the whole page in with `body { font-family: var(--rrc-font-sans); }`.
+
+## Quick example
+
+```tsx
+import { ComboBox, SmartField } from "rich-react-component";
+import { RemoteComboBox } from "rich-react-component";
+
+// Base — you own the data
+<ComboBox
+  options={[{ value: "tr", label: "Turkey" }]}
+  value={countryId}
+  onChange={setCountryId}
+/>
+
+// Remote — the component owns fetching, cancellation, and stale-response
+// protection; you only describe the endpoint and the field mapping
+<RemoteComboBox
+  url="/api/countries"
+  valueMember="id"
+  displayMember="name"
+  value={countryId}
+  onChange={setCountryId}
+/>
+
+// Smart — the server describes the field, SmartField resolves it onto
+// RemoteComboBox for you; visible/readOnly/required/validation all come
+// from metadata instead of being written by hand at every call site
+<SmartField
+  metadata={{
+    name: "countryId", component: "ComboBox",
+    valueMember: "id", displayMember: "name",
+    dataSource: { id: "Countries" },
+  }}
+  ctx={ctx} // { values, onFieldChange, registry, dataSources, actions }
+/>
+```
+
+## What's in each layer
+
+**Base** (55 components) — form fields (`Input`, `NumberInput`, `PasswordInput`, `FileInput`, `CheckBox`, `Switch`, `RadioGroup`, `Select`, `MultiSelect`, `DatePicker`, `TimePicker`, `DateTimePicker`, `ComboBox`, `AutoComplete`, `FormField`), feedback (`Modal`, `Toast`, `Confirm`, `Alert`, `Spinner`, `Badge`, `Skeleton`), data display (`DataGrid`, `Pagination`, `Avatar`, `Tag`, `Rating`, `ProgressBar`, `ListItem`, `Sparkline`, `Statistic`), navigation (`Breadcrumb`, `Menu`, `Stepper`, `Tabs`, `Navbar`, `Sidebar`, `PageHeader`), layout (`Card`, `Divider`, `Stack`, `Flex`, `Container`, `Row`, `Col`), typography (`Text`), and more (`Button`, `IconButton`, `Tooltip`, `Popover`, `Accordion`, `Icon`).
+
+`DataGrid` columns are declarative by default (`{ field: "conversion", header: "CONV.", align: "end" }`) — `render` stays available as the escape hatch for genuinely custom cells, and `format`/`formatter` cover the common presentation cases (`dataGridFormatters` exports the built-in `text`/`date`/`currency`/`boolean` set). `Card` accepts `title`/`subtitle`/`icon`/`avatar`/`actions`/`loading` directly, with `header` remaining as the raw escape hatch. `Tabs` supports `variant` (`default`/`underline`/`pill`/`card`/`button`), `orientation`, `size`, `stretch`, and per-item `icon`/`badge`, with roving-tabindex keyboard navigation.
+
+**Remote** — `RemoteComboBox`, `RemoteAutoComplete`, `RemoteSelect`, `RemoteMultiSelect`, `RemoteDataGrid`, backed by a shared `HttpClient` abstraction and a `useRemoteData` hook that handles request cancellation, stale-response protection, and a consistent `idle/loading/success/empty/error` state model.
+
+**Smart** — *Phases 1-5 complete, the full approved plan.* A metadata-driven layer: the server describes a field or action, Smart resolves that description onto the exact Base/Remote component that already exists — it never reimplements one.
+
+- **Metadata contract** — a discriminated union per component type (`InputMetadata | ComboBoxMetadata | DatePickerMetadata | DataGridMetadata`), plus `SmartActionMetadata` for buttons. Declarative only: no expressions, no serialized functions.
+- **Registries** — `SmartComponentRegistry` (keyed by the `component` discriminant, not a switch), `SmartDataSourceRegistry` and `SmartActionRegistry` (id-based indirection — metadata never carries a raw URL or a function).
+- **Built-in resolvers** — Input, ComboBox, DatePicker, and DataGrid, registered via `registerBuiltInResolvers()` through the exact same call a custom application component would use. DataGrid's column metadata (`format: "text" | "date" | "currency" | "boolean"`) maps onto Base DataGrid's own `dataGridFormatters` — Smart requests a formatter, it doesn't maintain a second rendering system for it. The one exception is the boolean formatter's localized text, which Smart still resolves itself (via the `formatter` escape hatch) since that's a translation-catalog concern Base can't own.
+- **Headless engine** — `useSmartField` / `useSmartAction` resolve one field/action's metadata (visibility, validation, localized label, resolved request params); `useSmartDependencies` tracks `dependsOn` and reports which field needs fresh metadata when a value it depends on changes.
+- **Components** — `SmartField` / `SmartAction` resolve one piece of metadata into UI; `SmartForm` / `SmartActions` are thin iteration helpers over a whole `SmartFormMetadata` — no field-value ownership, no business-rule evaluation, no layout decisions.
+
+## Sidebar
+
+One recursive navigation tree with a single authoritative expansion state and a
+single authoritative `activeKey` — no per-group `Accordion` instance, and no
+per-item `active` boolean to keep in sync.
+
+```tsx
+<Sidebar
+  variant="compact"                 // "grouped" (default) | "compact"
+  items={[
+    { type: "link", key: "overview", label: "Overview", href: "/overview" },
+    { type: "divider", key: "sep" },
+    {
+      type: "group", key: "workspace", label: "Workspace",
+      children: [
+        {
+          type: "collapsible", key: "catalog", label: "Catalog",
+          children: [
+            { type: "link", key: "items", label: "Items", href: "/items" },
+            { type: "action", key: "sync", label: "Sync now", onSelect: (item, event) => reload() },
+          ],
+        },
+      ],
+    },
+  ]}
+  activeKey="items"                 // ancestors are derived, never passed in
+  expandActivePath                  // opens the active branch on mount and on
+                                    // every activeKey change — and only then,
+                                    // so the user can close it in between.
+                                    // `activePathExpansion="always"` restores
+                                    // the older force-open behaviour.
+  expandMode="multiple"             // "single" closes the competing branch
+  collapsible
+  header={<Brand />}
+  footer={<OrganizationSelector />} // tenant behavior belongs to the app
+  navLabel="Primary"
+/>
+```
+
+**Item kinds.** `link` (a real `href`), `action` (a command, rendered as a
+native button), `collapsible` (a branch with an explicit toggle), `group` (a
+visual section — never navigable, and expandable only with `collapsible: true`)
+and `divider`. Each supports `key`, `label`, `icon`, `badge`, `disabled`,
+`className` and `ariaLabel`.
+
+**Semantics.** A destination renders as an anchor, or through `renderLink` so
+your router's own link can be swapped in without this package importing a
+router. A command renders as a button; a placeholder `href="#"` is never
+generated. Enabled links keep their default navigation, so modified clicks
+still open a new tab; disabled links are prevented from navigating and disabled
+actions use the native `disabled` attribute. Only the actual active destination
+gets `aria-current="page"` — its ancestors get `data-active-ancestor="true"`.
+
+**State.** `expandedKeys` / `defaultExpandedKeys` / `onExpandedKeysChange`
+(keys are always emitted in tree order), `collapsed` / `defaultCollapsed` /
+`onCollapsedChange`, and `mobileOpen` / `defaultMobileOpen` /
+`onMobileOpenChange` are three separate concerns that never share a value.
+Collapsing the aside leaves the expanded keys intact; opening the mobile drawer
+leaves the desktop collapse choice intact.
+
+**Collapsed and mobile.** A collapsed row keeps its accessible name on the
+control itself and surfaces it through the existing `Tooltip`. A nested branch
+opens as a flyout built from the existing `Popup` primitive, with its own local
+open state, so `expandedKeys` are never touched. The mobile drawer is a modal
+dialog with a backdrop, Escape-to-close, and focus restoration to whatever
+opened it.
+
+**LTR and RTL.** Indentation, flyout placement, the collapse control and the
+drawer all use logical CSS, so `dir="rtl"` mirrors without a second stylesheet.
+
+### Migrating from 0.2.0
+
+`sections`, `SidebarLeafItem`, `SidebarGroup` and `SidebarSection` still work.
+They are normalized onto the recursive model internally, so there is exactly one
+rendering path. Two behavior notes:
+
+- A legacy leaf **without** an `href` used to render as `<a href="#">`. It now
+  renders as a `<button>`; its props are unchanged and `onClick` still fires.
+  This is the one intentional DOM change, and it is what removes the
+  placeholder anchor.
+- A legacy `active: true` flag is folded into the authoritative `activeKey`.
+  When several items are flagged, the first in declaration order wins.
+
+`variant` defaults to `"grouped"`, the presentation this component has always
+rendered. `compact` is opt-in.
+
+## Appearance
+
+An opt-in controller for four strictly independent settings. It is **not** a
+Metronic Layout Builder: there is no demo/template switching, and no
+page-loader, fixed-header or icon-style option.
+
+```tsx
+<AppearanceProvider
+  defaultMode="system"                 // "light" | "dark" | "system"
+  defaultSidebarPresentation="compact" // "compact" | "grouped"
+  defaultSidebarTone="auto"            // "light" | "dark" | "auto"
+  defaultColorSchemeId="blue"
+  storage={window.localStorage}        // persistence is opt-in...
+  storageKey="my-app:appearance"       // ...and needs your own key
+>
+  <App />
+</AppearanceProvider>
+```
+
+`useAppearance()` returns the current settings, the `resolvedTheme`, the live
+`systemTheme`, the setters, and `appearanceProps` to spread onto your own
+layout root. By default the provider mutates **no** global DOM; pass
+`applyTo="documentElement"` if you want it to write the theme attribute and the
+scheme variables for you. A `Sidebar` with no explicit `variant`/`tone` follows
+the provider, and still works with no provider at all.
+
+Importing the package is SSR-safe: `window`, `document`, `localStorage` and
+`matchMedia` are never touched during module evaluation or during render, so
+the server and the first client render agree. To also avoid the first-paint
+theme flash, inline the initialization snippet yourself — it is returned as a
+string and never injected automatically:
+
+```tsx
+<script dangerouslySetInnerHTML={{ __html: createAppearanceInitScript({ storageKey: "my-app:appearance" }) }} />
+```
+
+`AppearanceMenu` is the composable selector — drop it into a `Navbar` slot, a
+`Popover`, or a settings drawer. Every section is individually hideable, and
+every visible string is supplied by the caller, so it ships no copy in any
+language:
+
+```tsx
+<AppearanceMenu labels={{ presentation, mode, tone, colorScheme }} sections={{ tone: false }} />
+```
+
+### Color schemes
+
+A scheme is a complete coordinated token family, never one raw color: changing
+only the primary hue leaves buttons, active components and menu states
+inconsistent, so an incomplete family is rejected at registration.
+
+```tsx
+registerColorScheme(createColorScheme({
+  id: "brand",
+  primary: "#7b1fa2", primaryActive: "#5c1379", primaryLight: "#f0dcf7",
+  primaryInverse: "#ffffff", primaryRgb: "123, 31, 162",
+}));
+```
+
+Applying a scheme emits three groups of CSS custom properties at once:
+
+| Group | Variables | Status |
+| --- | --- | --- |
+| Bootstrap 5.3 | `--bs-primary`, `--bs-primary-rgb` | genuinely exist in the peer dependency, written directly |
+| Metronic-compatible | `--bs-primary-active` / `-light` / `-inverse`, `--bs-component-*`, `--bs-menu-link-color-*` | not in Bootstrap; emitted so a real Metronic build gets a coordinated result instead of a half-recolored theme |
+| Repository-owned | `--rrc-*` | what this library's stylesheet actually consumes; each falls back to the Bootstrap name, then the Metronic name, then a literal — so it works with Metronic, with plain Bootstrap, or with neither |
+
+On dark surfaces the `--rrc-menu-link-color-*` tokens are derived from the
+scheme's primary rather than chained to the `--bs-*` value: neither Bootstrap
+nor Metronic ships a dark variant of those variables, and the light-mode shades
+measure about 2:1 on a dark neutral. An application with its own dark palette
+overrides the `--rrc-*` tokens, which are the documented integration point.
+
+## Component showcase
+
+A dev-only application exercises the library live — not part of the published package:
+
+```bash
+npm run dev
+```
+
+The showcase is a routed single-page application: a persistent shell (categorized
+Sidebar, header, appearance drawer) with one route per public visual component,
+each page showing a live Preview and the source that produced it.
+
+- `/overview/introduction` — the landing route
+- `/components/<category>/<component>` — one route per Base component
+- `/remote/<component>` and `/smart/<component>` — the Remote and Smart layers
+
+The demo consumes the library through its real public specifier
+(`rich-react-component`), never through private source paths, so the package
+boundary is exercised the way a consumer exercises it.
+
+## Scripts
+
+| Command | Description |
+| --- | --- |
+| `npm run dev` | Start the showcase with Vite |
+| `npm run build:demo` | Build the showcase SPA to `demo-dist/` |
+| `npm run preview:demo` | Preview the production showcase build |
+| `npm run build` | Type-check + build the library to `dist/` (ESM, CJS, `.d.ts`) |
+| `npm test` | Run the test suite once (Vitest) |
+| `npm run test:watch` | Run tests in watch mode |
+| `npm run typecheck` | Type-check the whole project without emitting |
+
+## Project structure
+
+```text
+src/
+├── base/     # Base layer — no dependency on remote/ or smart/
+├── remote/   # Remote layer — may depend on base/, not on smart/
+├── smart/    # Smart layer (Phases 1-5) — may depend on base/ and remote/
+└── index.ts  # public entry point
+
+demo/         # dev-only routed showcase application (not published)
+  registry/   #   authoritative route/category metadata + public-export inventory
+  shell/      #   persistent app shell: sidebar, header, drawers, preferences
+  pages/      #   one lazily loaded module per category
+  ui/         #   page standard and the Preview/Code example viewer
+  mocks/      #   deterministic in-memory HttpClient for the Remote demos
+```
+
+## Testing
+
+Behavioral tests over snapshots. Every capability layer is tested against its own contract — Base components never call `fetch`, Remote components reuse (not duplicate) their Base counterpart's UI, dependency-driven param changes reload correctly without stale-response races, and the Smart registry falls back safely for an unresolved component type instead of rendering the wrong thing.
+
+## License
+
+[MIT](./LICENSE) © suleymangulle

package/dist/base/Appearance.d.ts

@@ -0,0 +1,116 @@
+import { CSSProperties, ReactNode } from 'react';
+import { ColorScheme } from './appearanceSchemes';
+/** What the user picked. */
+export type ThemeMode = "light" | "dark" | "system";
+/** What that actually resolves to right now. Never "system". */
+export type ResolvedTheme = "light" | "dark";
+/** Which Sidebar presentation the application uses. Not a Metronic demo/template switch. */
+export type SidebarPresentation = "compact" | "grouped";
+/** The Sidebar's own surface tone, independent of the resolved page theme. */
+export type SidebarTone = "light" | "dark" | "auto";
+export declare const THEME_MODES: readonly ThemeMode[];
+export declare const SIDEBAR_PRESENTATIONS: readonly SidebarPresentation[];
+export declare const SIDEBAR_TONES: readonly SidebarTone[];
+/** The four settings, kept strictly separate so one can never overwrite another. */
+export interface AppearanceSettings {
+    mode: ThemeMode;
+    sidebarPresentation: SidebarPresentation;
+    sidebarTone: SidebarTone;
+    colorSchemeId: string;
+}
+export interface AppearanceContextValue extends AppearanceSettings {
+    /** `mode`, with "system" already resolved through `prefers-color-scheme`. */
+    resolvedTheme: ResolvedTheme;
+    /** The operating-system preference, observed live. */
+    systemTheme: ResolvedTheme;
+    colorScheme: ColorScheme;
+    setMode: (mode: ThemeMode) => void;
+    setSidebarPresentation: (presentation: SidebarPresentation) => void;
+    setSidebarTone: (tone: SidebarTone) => void;
+    setColorSchemeId: (id: string) => void;
+    /**
+     * Spread onto your own layout root when the provider is not configured to
+     * touch the DOM itself (the default). Carries the resolved theme attribute
+     * and the selected scheme's CSS custom properties.
+     */
+    appearanceProps: {
+        "data-bs-theme": ResolvedTheme;
+        style: CSSProperties;
+    };
+}
+/** Minimal `localStorage`-compatible surface — supply your own for SSR or tests. */
+export interface AppearanceStorage {
+    getItem: (key: string) => string | null;
+    setItem: (key: string, value: string) => void;
+}
+export interface AppearanceProviderProps {
+    children: ReactNode;
+    mode?: ThemeMode;
+    defaultMode?: ThemeMode;
+    onModeChange?: (mode: ThemeMode) => void;
+    sidebarPresentation?: SidebarPresentation;
+    defaultSidebarPresentation?: SidebarPresentation;
+    onSidebarPresentationChange?: (presentation: SidebarPresentation) => void;
+    sidebarTone?: SidebarTone;
+    defaultSidebarTone?: SidebarTone;
+    onSidebarToneChange?: (tone: SidebarTone) => void;
+    colorSchemeId?: string;
+    defaultColorSchemeId?: string;
+    onColorSchemeIdChange?: (id: string) => void;
+    /**
+     * Opt-in persistence. Both `storage` and `storageKey` are required before
+     * anything is read or written — this library never invents an application
+     * storage key.
+     */
+    storage?: AppearanceStorage;
+    storageKey?: string;
+    /**
+     * Where to write the resolved theme attribute and the scheme variables.
+     * Defaults to "none": the provider mutates no global DOM unless asked to.
+     */
+    applyTo?: "none" | "documentElement" | "body";
+    /** Attribute used for the resolved theme. Bootstrap 5.3's own mechanism by default. */
+    themeAttribute?: string;
+}
+/**
+ * Opt-in appearance controller. Deliberately NOT a Metronic Layout Builder:
+ * it owns four independent settings and nothing else — no demo/template
+ * switching, no page-loader, header or icon-style options.
+ *
+ * SSR-safe by construction: no `window`, `document`, `localStorage` or
+ * `matchMedia` is touched during module evaluation or during render. The
+ * system preference and any persisted values are read in effects, so the
+ * server and the first client render agree. Use
+ * `createAppearanceInitScript()` if you also need to avoid the initial
+ * theme flash.
+ */
+export declare function AppearanceProvider({ children, mode, defaultMode, onModeChange, sidebarPresentation, defaultSidebarPresentation, onSidebarPresentationChange, sidebarTone, defaultSidebarTone, onSidebarToneChange, colorSchemeId, defaultColorSchemeId, onColorSchemeIdChange, storage, storageKey, applyTo, themeAttribute, }: AppearanceProviderProps): import("react").JSX.Element;
+/** Throws outside an `AppearanceProvider`, so a missing provider fails loudly instead of silently. */
+export declare function useAppearance(): AppearanceContextValue;
+/**
+ * Internal: components that merely *follow* the appearance when a provider
+ * happens to be present (Sidebar) must keep working without one. Not exported
+ * from the package entry point.
+ */
+export declare function useOptionalAppearance(): AppearanceContextValue | undefined;
+export interface AppearanceInitScriptOptions {
+    storageKey: string;
+    themeAttribute?: string;
+    target?: "documentElement" | "body";
+    /** Must match the provider's `defaultMode`. */
+    defaultMode?: ThemeMode;
+}
+/**
+ * Returns the source of a tiny synchronous snippet that applies the persisted
+ * resolved theme before first paint, removing the theme flash.
+ *
+ * It is returned as a string and never injected automatically — the consuming
+ * application decides where and whether to inline it (for example in a
+ * Next.js `<Script strategy="beforeInteractive">` or a raw `<script>` in the
+ * document head).
+ *
+ * The caller-supplied values are embedded as JSON string literals and their
+ * `<` characters are escaped, so a key can neither break out of the literal
+ * nor terminate a surrounding `<script>` element.
+ */
+export declare function createAppearanceInitScript({ storageKey, themeAttribute, target, defaultMode, }: AppearanceInitScriptOptions): string;