first commit

docs/ui/react/react-ui/src/pack/runtime-override/runtime-override.md

@@ -0,0 +1,76 @@
+# `runtime-override` — pack-component override merger
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## Purpose
+
+Pure helper that merges a `ComponentPack`'s default components with the
+`<ReactUiProvider components={...}>` runtime override map. The result
+is a flat `Map<componentName, ComponentType<unknown>>` the chassis
+stores in the `PackRegistryContext`'s `resolved` slot. White-label and
+runtime-swap scenarios drive the override mechanism — consumers swap a
+pack's `LoginForm` for their bespoke implementation without forking the
+pack package.
+
+## Features
+
+- Pure / synchronous merge of pack defaults with overrides
+- Skips `undefined` override entries so consumers can spread a partial
+  override map without wiping a pack default
+- Skips overrides for unrelated packs so multiple packs share a single
+  override map without cross-talk
+- Returns a frozen-style `ReadonlyMap` so consumers cannot mutate
+  the registry post-construction
+
+## Usage: Basic example
+
+```ts
+import { mergePackComponents } from "@suaveplan/react-ui/pack";
+
+const merged = mergePackComponents({
+    pack: authPack,
+    overrides: {
+        auth: { LoginForm: AcmeLoginForm },
+    },
+});
+```
+
+## Usage: Advanced example
+
+```ts
+import {
+    mergePackComponents,
+    type RuntimeComponentOverride,
+} from "@suaveplan/react-ui/pack";
+
+const overrides: RuntimeComponentOverride = {
+    auth: {
+        LoginForm: AcmeLoginForm,
+        RegisterForm: AcmeRegisterForm,
+    },
+    social: {
+        ShareButton: AcmeShareButton,
+    },
+};
+
+const merged = mergePackComponents({ pack: authPack, overrides });
+const Login = merged.get("LoginForm"); // → AcmeLoginForm
+```
+
+## API Reference
+
+- `mergePackComponents({ pack, overrides? })` →
+  `ReadonlyMap<string, ComponentType<unknown>>`
+- `type RuntimeComponentOverride = Partial<Record<string,
+  Partial<Record<string, ComponentType<unknown>>>>>`
+
+## Implementation notes
+
+The override semantics are intentionally simple: the override entry,
+if present and not `undefined`, replaces the pack's default for that
+component name. There is no deep-merge or composition step because
+React components are atomic units — swapping `LoginForm` is the
+intent, not "augment the existing component with override props". A
+consumer that wants compositional swapping wraps their override
+component around the imported pack default explicitly.