`runtime-override` — pack-component override merger

(no submodules)

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

import { mergePackComponents } from "@suaveplan/react-ui/pack";

const merged = mergePackComponents({
    pack: authPack,
    overrides: {
        auth: { LoginForm: AcmeLoginForm },
    },
});

Usage: Advanced example

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.

2.3 KiB Raw Blame History

runtime-override — pack-component override merger