@usecarte/components-core

Headless React behaviour, provenance context, and closed-enum formatter/aggregation registries for Carte components.

This package is what @usecarte/components is built on. Use it directly if you're authoring your own styled component package — it gives you the provenance plumbing, the formatter/aggregation registries, and the title-injection hook without prescribing a renderer or a styling system.

Install

pnpm add @usecarte/components-core @usecarte/core

React is an optional peer (>=18). Server-only consumers can import the React-free subpath:

import { FORMATTERS, AGGREGATIONS } from "@usecarte/components-core/registry";

What's in the box

• <ProvenanceProvider> — wraps every panel with the receipt context. Components rendered outside a provider throw CarteProvenanceError (strict-throw, no silent fallback).
• buildReceipt() — assembles an audit receipt from panel + transformations + context.
• FORMATTERS, AGGREGATIONS — closed-enum registries the catalog/registry layers use to ensure receipts are statically auditable.
• useInjectedTitle() — every default-catalog component pulls its title from the entry's titleTemplate rather than from an LLM-authored prop.
• DevHarness — test-only wrapper that satisfies the provenance requirement without a full renderer.

Provenance is mandatory

A component from @usecarte/components rendered outside a <CarteRenderer> (or <ProvenanceProvider>, or <DevHarness> in tests) throws CarteProvenanceError. This is the load-bearing audit story — see the repo root README and the security model.

License

MIT