first commit

docs/ui/react/react-ui/src/pack/pack-context.md

@@ -0,0 +1,78 @@
+# `pack-context` — React context plumbing for the pack registry
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+  - [pack-registry-provider](./pack-registry-provider/pack-registry-provider.md) — <!-- begin:auto-docs --> _(no submodules)_- [runtime-override](./runtime-override/runtime-override.md) — <!-- begin:auto-docs --> _(no submodules)_  - [runtime-override](./runtime-override/runtime-override.md) — <!-- begin:auto-docs --> _(no submodules)_- [use-pack-component](./use-pack-component/use-pack-component.md) — <!-- begin:auto-docs --> _(no submodules)_  - [use-pack-component](./use-pack-component/use-pack-component.md) — <!-- begin:auto-docs --> _(no submodules)_- [version-check](./version-check/version-check.md) — <!-- begin:auto-docs --> _(no submodules)_  - [version-check](./version-check/version-check.md) — <!-- begin:auto-docs --> _(no submodules)_- [pack-context](./pack-context.md) — <!-- begin:auto-docs --> _(no submodules)_- pack-registry-provider — <!-- begin:auto-docs --> _(…
+- [pack-registry-provider](./pack-registry-provider/pack-registry-provider.md) — <!-- begin:auto-docs --> _(no submodules)_- [runtime-override](./runtime-override/runtime-override.md) — <!-- begin:auto-docs --> _(no submodules)_- [runtime-override](./runtime-override/runtime-override.md) — <!-- begin:auto-docs --> _(no submodules)_- [use-pack-component](./use-pack-component/use-pack-component.md) — <!-- begin:auto-docs --> _(no submodules)_- [use-pack-component](./use-pack-component/use-pack-component.md) — <!-- begin:auto-docs --> _(no submodules)_- [version-check](./version-check/version-check.md) — <!-- begin:auto-docs --> _(no submodules)_- [version-check](./version-check/version-check.md) — <!-- begin:auto-docs --> _(no submodules)_- [pack-context](./pack-context.md) — <!-- begin:auto-docs --> _(no submodules)_- [pack-registry-provider](./pack-registry-provider/pack-registry-provider.md) — <!-- begin:auto-docs --> _(no submodules)_- [runtime-override](./runtime-override/runtime-override.md) — <!-- begin:auto-docs --> _(no submodules)_- [runtime-override](./runtime-override/runtime-override.md) — <!-- begin:auto-docs --> _(no submodules)_- [use-pack-component](./use-pack-component/use-pack-component.md) — <!-- begin:auto-docs --> _(no submodules)_- [use-pack-component](./use-pack-component/use-pack-component.md) — <!-- begin:auto-docs --> _(no submodules)_- [version-check](./version-check/version-check.md) — <!-- begin:auto-docs --> _(no submodules)_- [version-check](./version-check/version-check.md) — <!-- begin:auto-docs --> _(no submodules)_- [pack-context](./pack-context.md) — <!-- begin:auto-docs --> _(no submodules)_- pack-registry-provider — <!-…
+- [pack-registry-provider](./pack-registry-provider/pack-registry-provider.md) — <!-- begin:auto-docs --> _(no submodules)_- [runtime-override](./runtime-override/runtime-override.md) — <!-- begin:auto-docs --> _(no submodules)_- [runtime-override](./runtime-override/runtime-override.md) — <!-- begin:auto-docs --> _(no submodules)_- [use-pack-component](./use-pack-component/use-pack-component.md) — <!-- begin:auto-docs --> _(no submodules)_- [use-pack-component](./use-pack-component/use-pack-component.md) — <!-- begin:auto-docs --> _(no submodules)_- [version-check](./version-check/version-check.md) — <!-- begin:auto-docs --> _(no submodules)_- [version-check](./version-check/version-check.md) — <!-- begin:auto-docs --> _(no submodules)_- [pack-context](./pack-context.md) — <!-- begin:auto-docs --> _(no submodules)_- pack-registry-provider — <!-- begin:auto-docs --> _…
+- [pack-registry-provider](./pack-registry-provider/pack-registry-provider.md) — <!-- begin:auto-docs --> _(no submodules)_- [runtime-override](./runtime-override/runtime-override.md) — <!-- begin:auto-docs --> _(no submodules)_  - [runtime-override](./runtime-override/runtime-override.md) — <!-- begin:auto-docs --> _(no submodules)_- [use-pack-component](./use-pack-component/use-pack-component.md) — <!-- begin:auto-docs --> _(no submodules)_  - [use-pack-component](./use-pack-component/use-pack-component.md) — <!-- begin:auto-docs --> _(no submodules)_- [version-check](./version-check/version-check.md) — <!-- begin:auto-docs --> _(no submodules)_  - [version-check](./version-check/version-check.md) — <!-- begin:auto-docs --> _(no submodules)_- [pack-context](./pack-context.md) — <!-- begin:auto-docs --> _(no submodules)_
+## Purpose
+
+Owns the React `Context` `<PackRegistryProvider>` writes into and the
+`usePackComponent` hook reads from. The context carries two slices: a
+`packs` map (raw `ComponentPack` references keyed by pack name) and a
+`resolved` map (the merged `(packName -> componentName -> Component)`
+view that already accounts for runtime overrides). Splitting raw and
+resolved lets debugging surfaces inspect either layer.
+
+## Features
+
+- Single source-of-truth context for the chassis pack system
+- `null` discriminator drives provider-missing detection in every
+  consumer hook
+- `displayName` set so React DevTools surfaces the context as
+  `ReactUiPackRegistryContext` rather than the generic
+  `Context.Provider`
+- `resolved` map is computed inside the Provider's `useMemo` so a
+  re-render does not rebuild the merged maps unless `packs` or the
+  override prop change
+
+## Usage: Basic example
+
+```ts
+import { useContext } from "react";
+import { PackRegistryContext } from "@suaveplan/react-ui/pack";
+
+function PackInspector() {
+    const ctx = useContext(PackRegistryContext);
+    if (!ctx) return null;
+    return <pre>{[...ctx.packs.keys()].join(", ")}</pre>;
+}
+```
+
+## Usage: Advanced example
+
+```ts
+import { useContext } from "react";
+import { PackRegistryContext } from "@suaveplan/react-ui/pack";
+
+function ResolvedView() {
+    const ctx = useContext(PackRegistryContext);
+    if (!ctx) return null;
+    const rows = [];
+    for (const [pack, components] of ctx.resolved) {
+        for (const componentName of components.keys()) {
+            rows.push(`${pack}/${componentName}`);
+        }
+    }
+    return <ul>{rows.map((r) => <li key={r}>{r}</li>)}</ul>;
+}
+```
+
+## API Reference
+
+- `PackRegistryContext: React.Context<PackRegistryContextValue | null>`
+- `interface PackRegistryContextValue`
+  - `packs: ReadonlyMap<string, ComponentPack>`
+  - `resolved: ReadonlyMap<string, ReadonlyMap<string, ComponentType<unknown>>>`
+
+## Implementation notes
+
+The two-map split allows the consumer-facing `usePackComponent` hook
+to read directly from `resolved` (a flat lookup) without walking the
+raw pack array. Test fixtures and DevTools surfaces that need to see
+the original pack lifecycle hooks consult `packs` instead. The
+context default `null` makes provider-missing failures surface at the
+hook call site rather than producing a confusing read-from-empty-map
+scenario.