@yahoo/uds-create-config 2.45.0 → 3.0.0

package/dist/framework/projections.d.ts

@@ -0,0 +1,480 @@
+import { Ref } from "./utils/refs.js";
+import { ItemOf } from "./defineEntity.js";
+import { Config } from "./Config.js";
+import { StylePropLeaf, StyleProperty } from "../entities/system/StyleProperty.js";
+
+//#region src/framework/projections.d.ts
+/**
+ * The variable namespace a linked system's entities are declared under, seen from `config`.
+ *
+ * Not the source's own prefix. That is a setting the source chose for itself and the one it gets for
+ * free is `uds`, so two pinned systems that both took the default would declare the same
+ * `--uds-color-brand` and the later `:root` would win — every ref through either pin painting one
+ * value, silently, because an over-declared custom property is not an error.
+ *
+ * The slug is the name that cannot collide: it is a key in the consuming config, unique there by
+ * construction, and already the only name resolution uses. So a borrowed variable lives in the
+ * consumer's namespace, qualified by the pin it came through.
+ */
+declare const sourceVarPrefix: (config: Config, slug: string) => string;
+/**
+ * The CSS custom-property name for an entity — `--<prefix>-<group-kebabed>-<leaf>`.
+ *
+ * The group segment is kebab-cased and the leaf is not, which is not a stylistic choice: it's the
+ * shape the emitted stylesheet declares (`--{prefix}-{kebabCase(namespace)}-{safeTokenName(name)}`).
+ * Deriving it any other way produces a `var()` that resolves to nothing for any camelCase group.
+ */
+declare function cssVar(config: Config, _kind: string, path: string, varPrefix?: string): string;
+/** `var(--…)` — the CSS reference to {@link cssVar}. */
+declare function cssVarRef(config: Config, kind: string, path: string, varPrefix?: string): string;
+/** The utility/class name for an entity — `<prefix>-<path-dashed>`. A class is one identifier, so
+ *  whitespace in the path is written as a hyphen too; a composite or motion preset named with a space
+ *  otherwise declares a rule no element's class list can match. */
+declare function className(config: Config, _kind: string, path: string): string;
+/**
+ * A style prop's allowed values, flattened to concrete strings: literal keywords (`row`)
+ * pass through, and a token group ref (`ref('token', 'color')`) expands to every member
+ * Token's path (`color/brand`, `color/accent`, …) — the utility set the prop offers,
+ * kept in lockstep with the group instead of restated. A ref that names a single token
+ * resolves to just that path. Shared by codegen (utility emit) and the UI value picker so
+ * both offer the same set. Order follows the authored `values`, group members in store
+ * order. Unknown prop → `[]`.
+ */
+declare function stylePropValues(config: Config, path: string): string[];
+/**
+ * One allowed value of a style prop as both halves: the `leaf` a consumer authors (`warning`,
+ * `carbon/2` — the member path with the bound group's prefix stripped) and the `value` it resolves
+ * to for storage/CSS (the qualified token path `color/warning`, or a literal keyword `row`). A group
+ * ref (`token('color')`) expands to one entry per member; a literal keyword is its own leaf+value;
+ * a single-token ref keeps its name as the leaf. This is the leaf↔qualified reverse map the old
+ * Config had (`allowedValues().tokens = token.name` + `accepts(token.name)`) that config-v2 dropped.
+ */
+/** One allowed value of a style prop as both halves, the entity's own {@link StylePropLeaf}. */
+type StylePropEntry = StylePropLeaf;
+/** The leaf value domain a ref offers — for any group-bound prop (composite/variant).
+ *
+ *  Takes the ref itself, not its parts. A caller holding `token:palette@ds` has the whole address; a
+ *  signature that took it apart made every call site split one by hand, and the three that did
+ *  disagreed about whether the `@source` survived the trip — which decides which config the members
+ *  come from. */
+declare function memberLeaves(config: Config, target: string | Ref): string[];
+/** Resolve a group-bound leaf back to its qualified path (`display2` → `textVariant/display2`).
+ *  `undefined` when the leaf isn't a member — what validation rejects. */
+declare function memberFromLeaf(config: Config, target: string | Ref, leaf: string): string | undefined;
+declare function stylePropEntries(config: Config, path: string): StylePropEntry[];
+/**
+ * A style prop's leaf value domain — what a consumer/model actually authors (`warning`, `carbon/2`),
+ * not the qualified storage path (`color/warning`). This is what the catalog, `uds_get_component`,
+ * `uds_validate_props`, and the UI picker should offer, so the model emits `color="warning"`.
+ */
+declare function stylePropValueLeaves(config: Config, path: string): string[];
+/**
+ * Resolve a style-prop leaf value back to its qualified token path (or literal) — the inverse of
+ * {@link stylePropValueLeaves}, for validating + rendering an authored `bg="subtle"`. `undefined`
+ * when the leaf isn't in the prop's domain.
+ */
+declare function stylePropValueFromLeaf(config: Config, path: string, leaf: string): string | undefined;
+/**
+ * The token a style-prop leaf binds, as a qualified path — `('bg', 'brand')` → `color/brand`.
+ * `undefined` when the leaf is a keyword the system declared rather than a token (`row`,
+ * `flex-start`), or isn't in the prop's domain at all.
+ *
+ * The pair below is what lets a bag store the binding as a ref while an author keeps writing the
+ * leaf: this direction mints the ref at parse time, {@link stylePropLeafForToken} reads it back for
+ * the class name. Narrowed to values that actually resolve as tokens, so a keyword is left as the
+ * string it is — a ref to a token that doesn't exist would be a dangling edge, which is worse than
+ * the missing one it replaced.
+ */
+declare function stylePropTokenPath(config: Config, path: string, leaf: string): string | undefined;
+/**
+ * The leaf a style prop calls a token — `('bg', 'color/brand')` → `brand`. The read twin of
+ * {@link stylePropTokenPath}, and the reason storing the ref costs no reader its class name.
+ *
+ * Not `refLeaf`: that strips one path segment, which is right for a variant value
+ * (`value:variant/solid`) and wrong here, because a prop's token group can be several segments deep
+ * (`spectrum/blue/1` under group `spectrum/blue` is the leaf `1`, not `blue/1`). The group is a fact
+ * about the prop's domain, so only the domain can say where the leaf starts.
+ *
+ * First match wins, the same way {@link stylePropValueFromLeaf} resolves the other direction — a
+ * prop binding two groups that share a value already lets authored order decide.
+ */
+declare function stylePropLeafForToken(config: Config, path: string, tokenPath: string): string | undefined;
+/**
+ * The leaf an author wrote for a stored ref in a bag — the read side of the binding
+ * `value-domain.ts` performs on the way in.
+ *
+ * Two cases, because where the leaf starts differs:
+ *
+ *  - a token is reached through a style property, whose domain decides how much of the path is the
+ *    group. `spectrum/blue/1` under the group `spectrum/blue` is the leaf `1`, so the property's own
+ *    domain is the only thing that can say — hence the lookup rather than trimming a segment.
+ *  - anything else (a composite member, a motion preset) is named under the group its prop points at,
+ *    and the authored name is the last segment. This holds for a nested group too: `overlays/elev/1`
+ *    under `overlays/elev` is `1`.
+ *
+ * `undefined` when the ref isn't one a bag value could have been authored as, so the caller leaves it
+ * alone rather than inventing a name for it.
+ */
+declare function authoredValue(config: Config, key: string, value: unknown): unknown;
+/**
+ * A style bag as a surface reads it — every token binding read back to the leaf an author wrote.
+ *
+ * The inverse of the parse-time binding (`bindBagTokens` on `Component`), and the one place that
+ * inverse lives: a bag is stored with refs so the dependency graph sees the edges, while every
+ * consumer that renders, edits, or bakes one wants the leaf. Two implementations of this would be two
+ * chances to disagree about what a value is called — and the panel and the native theme disagreeing
+ * about that is exactly the class of bug the single description is meant to remove.
+ *
+ * Recurses into modifier blocks, since their values are values too. Returns the bag it was given when
+ * nothing was bound, so an untouched bag keeps its identity.
+ */
+declare function authoredBag(config: Config, bag: Record<string, unknown>): Record<string, unknown>;
+/** One resolved style property, as a nameable type — what these lookups hand back. */
+type StylePropertyItem = ItemOf<typeof StyleProperty>;
+/**
+ * The style property a prop on `elementType` writes through.
+ *
+ * Two questions get asked of a config constantly — *what CSS does this prop on this element write?*
+ * and *which prop writes this CSS?* — and both have to be answered from the config rather than from a
+ * prop's name: `spacingX` in one system is `spacingHorizontal` in the next, so CSS is the stable
+ * contract between them.
+ *
+ * One `StyleProperty` read on top of {@link stylePropertyPathFor}, which is where the routing lives:
+ * the component's own table where it declares the prop, the name where it doesn't — which is what an
+ * element styled through a raw tag needs, since a raw tag declares no props at all.
+ *
+ * `elementType` may arrive as a spec element's stored marker (`component:Media`) or as a bare path;
+ * the marker is stripped, because the component lookup keys on the path. Missing that strip is
+ * invisible in a system whose prop names are its style-property paths — the fallback answers
+ * correctly — and wrong the moment a component names a prop something else.
+ */
+declare function stylePropertyFor(config: Config, elementType: string, propName: string): StylePropertyItem | undefined;
+/** Every style property that writes `cssProperty`, in registration order. */
+declare function stylePropertiesWriting(config: Config, cssProperty: string): StylePropertyItem[];
+/** Whether a style property accepts `value` — i.e. the value is one of its leaves. */
+declare function stylePropertyAccepts(config: Config, prop: StylePropertyItem, value: string): boolean;
+/**
+ * Each token-backed value a style prop offers, as `leaf → resolved literal` (`'2' → '0.5rem'`) — what
+ * a token picker shows beside each name. Keyword values are absent: there's no token behind them, so
+ * there's nothing to resolve.
+ */
+declare function stylePropTokenValues(config: Config, propName: string): Record<string, string>;
+/**
+ * The token group a style prop draws its values from (`spacing`) — what an "open this in the system"
+ * link needs. `undefined` when the prop's values are keywords rather than tokens.
+ *
+ * Derived from the values themselves rather than from a declared group list: a token-backed value
+ * resolves to its qualified path, and everything before the leaf is the group it lives in.
+ */
+declare function stylePropTokenGroup(config: Config, propName: string): string | undefined;
+/**
+ * The value of whichever prop in `props` writes `cssProperty`.
+ *
+ * Reads the element's own props rather than the styling the config would apply, because a caller
+ * asking this is asking about a choice someone made on this element (pinning a position, locking an
+ * aspect ratio) — not about what the component's rules paint by default.
+ */
+declare function cssPropValue(config: Config, elementType: string, props: Record<string, unknown>, cssProperty: string): string | undefined;
+/**
+ * One field of one entity, with refs chased to the literal they denote — local and linked alike.
+ *
+ * The whole point is that there is no second walk for a borrow. A ref is a ref: `isRef` is the only
+ * branch, and whether it carries a `@source` decides only which config the next hop reads, never
+ * whether a hop happens. That is what makes "reference something in my system" and "reference
+ * something from a linked system" the same feature rather than two that have to agree.
+ *
+ * A ref stands in for the same field of the entity it names — a token's `value` aliasing another
+ * Token's `value`, a composite's `styles` standing in for another composite's `styles` — so the field
+ * carries through the chase rather than each kind needing to declare a target.
+ *
+ * Answers with whatever the ref denotes rather than narrowing to a scalar — a borrowed gradient or
+ * derived colour is a resolved value too, and a chase that returned `undefined` for one would be
+ * indistinguishable from a chase that failed. A caller wanting a literal narrows.
+ *
+ * `undefined` only when there is no answer: a missing entity, an unreachable linked source, or a cycle.
+ */
+declare function resolveFieldValue(config: Config, kind: string, path: string, field: string, seen?: Set<string>): unknown;
+/** A token's value with alias refs chased to the base literal — {@link resolveFieldValue} for the one
+ *  field every token consumer asks about, narrowed to the scalar a display or a stylesheet can use. */
+declare function resolveTokenValue(config: Config, path: string, seen?: Set<string>): string | number | undefined;
+/**
+ * The literal a token resolves to under an override condition: its own override there when it holds
+ * one, else its base value, with a ref along the way chased under the same condition. That is how the
+ * cascade reads it — under `dark`, an alias of `blue/1` is blue/1's dark value — so a swatch painted
+ * for a dark cell paints what dark will show. `null` is the base, the same as {@link resolveTokenValue}.
+ */
+declare function resolveTokenValueUnder(config: Config, path: string, condition: string | null, seen?: Set<string>): string | number | undefined;
+/** A style-bag value → its CSS string: a token ref (or a bare token path) becomes a
+ *  `var(--…)` reference (so mode/theme overrides still flow), anything else is the literal.
+ *
+ *  `varPrefix` renames the namespace every variable in the result is spelled under, and is how a
+ *  linked source's own values are rendered into the consumer's stylesheet: their token aliasing
+ *  another of theirs has to name the variable as we declared it, not as they would have. Absent — the
+ *  ordinary call — it is `config`'s own prefix. */
+declare function renderStyleValue(config: Config, value: unknown, varPrefix?: string): string;
+/**
+ * The value a negating prop paints — `calc(<value> * -1)`.
+ *
+ * `calc` rather than a computed literal because the value is usually a `var(--…)`: the token it names
+ * has to stay a reference, so a mode override or a theme swap still reaches it. It's applied at the
+ * declaration, not to the token, since the same token feeds the positive prop too.
+ *
+ * Exported because three emitters need the same string — the stylesheet, the runtime's off-scale
+ * branch, and this file's `styleDeclarations` — and a prop that negates from a token but not from a
+ * literal is worse than one that never negates at all.
+ */
+declare function negatedCssValue(value: string): string;
+/**
+ * What one component's own module does with each prop it declares — name → the style property that
+ * prop writes, or `null` for a prop that writes none.
+ *
+ * This is the routing an emitted module performs, and it is a different question from
+ * {@link resolveComponentProps} / `prop-surface`, which answer what a component exposes by chasing
+ * `forwards` and `inherits`. Both are right for their callers — an inspector offers the exposed
+ * surface — but only this one describes what happens at runtime, because a module destructures its
+ * declared props out of the bag and hands the rest to `processStyleProps`:
+ *
+ *     const { className, layerProps, variant, size = "md", children, ...__udsBag } = jsxProps;
+ *     const [classes, rest] = processStyleProps(__udsBag, { gap: "gapY" });
+ *
+ * So a declared prop is answered by its declaration whatever its type, and a prop the component does
+ * not declare falls through by its own name to the root layer — where every prop the config doesn't
+ * model is sent (`rootLayerOf`).
+ *
+ * Three consequences, each a silent miss for a caller that reads the exposed surface instead:
+ *
+ *  - **A rename is the component's own.** `TokenCellShell` forwards `*` from `HStack`, so its exposed
+ *    surface reports `gap` as `gapX` — but its module carries no alias, consumes `gap` under the
+ *    System-wide name, and its baked rule emits `gap:` to match. A forwarded rename is not inherited.
+ *  - **A `variant`, `composite`, `slot`, `forward`, `string`, `number` or `boolean` prop writes no
+ *    style property at all**, even where a style property shares its name. It is destructured out
+ *    before the style-prop table is ever consulted.
+ *  - **A `null` tombstone is a declaration too** — the prop is declared gone, not merely absent, and
+ *    it is destructured out like any other. It writes nothing and does not fall through.
+ */
+declare function declaredPropRouting(config: Config, path: string): Map<string, string | null>;
+/**
+ * The renames out of {@link declaredPropRouting} — the table a component's module is emitted with and
+ * hands to `processStyleProps`.
+ *
+ * Only the renames, because a prop named after its own property is what the runtime assumes when it
+ * finds no entry (`aliases?.[key] ?? key`). So this map is the difference between a prop's
+ * consumer-facing name and what it routes to, and an empty answer means "they are the same".
+ */
+declare function styleAliasesOf(config: Config, path: string): Map<string, string>;
+/** Whether a style prop paints the negation of its value (`offsetX`). */
+declare function stylePropNegates(config: Config, path: string): boolean;
+/**
+ * Flatten a style bag to resolved CSS declarations — each key resolves to its style prop's
+ * CSS `property` (falling back to the key itself as a raw property), each value renders as a
+ * Token ref or a literal. `_`-prefixed keys are modifier blocks the caller nests, so they're
+ * skipped. The single style→CSS resolver shared by codegen (emit CSS text) and the renderer
+ * (inline styles) so a rendered preview matches the emitted stylesheet exactly.
+ */
+/**
+ * The style property one bag key writes — the single answer to "what does this prop mean here",
+ * for every surface that reads a prop bag.
+ *
+ * A bag key is an authored name, and what it writes is settled by the definitions it resolves
+ * against, in `through` order — first one that declares the key wins, and its answer is the whole
+ * answer. A key nothing declares names its own property, which is what a raw tag needs, since a raw
+ * tag declares no props at all.
+ *
+ * `through` is a chain rather than one element because a style rule's bag has two definitions with a
+ * claim on it: the component that authored the rule, and the element whose props the rule sets.
+ * The author comes first — a component's own declaration of `gap` is what `gap` means throughout its
+ * definition, its public API and its style rules alike. So `Row`, which declares `gap` writing
+ * `gapX` over a `VStack` layer that writes `gapY`, means column-gap in both places rather than one
+ * in each.
+ *
+ * A member ref key (`component:layout/HStack#props/gap`) names its element outright, so it answers
+ * for itself and `through` is irrelevant.
+ *
+ * `undefined` means "writes no style property": a `variant`, a `composite`, a tombstone, or a key
+ * that is not a style property at all (`as`, `type`, a data attribute). Every caller already had to
+ * distinguish that from a property, and each one used to decide it differently — the CSS emitter by
+ * `config.resolve('style-property', key)` on the authored name, which both mis-resolved a rename and
+ * silently dropped a key whose only meaning is a rename (`colSpan`, not itself a property, emitted no
+ * declaration at all).
+ */
+declare function stylePropertyPathFor({
+  config,
+  through,
+  key
+}: {
+  readonly config: Config;
+  /** The definitions to resolve `key` against, in precedence order — a path or a stored marker
+   *  (`component:Card`) each, `undefined` entries skipped so a raw-tag layer needs no branch at the
+   *  call site. Empty for a bag no component owns. */
+  readonly through?: readonly (string | undefined)[];
+  readonly key: string;
+}): string | undefined;
+/**
+ * A bag with every key rewritten to the property it writes, resolved through the definitions that
+ * have a claim on it ({@link stylePropertyPathFor}). The one place a bag's authored names become
+ * properties.
+ *
+ * Applied at each boundary rather than per key inside each consumer, so `styleDeclarations`, the CSS
+ * emitter and `splitStyleProps` all stay pure functions of a property-keyed bag and cannot disagree
+ * about what a key meant. A key that writes no style property is left alone, under the name it was
+ * authored with: it is the element's own (`as`, `type`, `onClick`), and the consumer routes it there.
+ *
+ * `_<modifier>` blocks hold an ordinary bag against the same definitions, so they recurse.
+ */
+declare function routedBag({
+  config,
+  through,
+  bag
+}: {
+  readonly config: Config;
+  readonly through?: readonly (string | undefined)[];
+  readonly bag: Record<string, unknown>;
+}): Record<string, unknown>;
+declare function styleDeclarations({
+  config,
+  bag,
+  namespace
+}: {
+  readonly config: Config;
+  readonly bag: Record<string, unknown>;
+  /**
+   * The var-name namespace every value renders in, when it is not this config's own.
+   *
+   * A borrowed entity's bag names the source's vocabulary, so it is resolved against the source — and
+   * then its `var()` names have to be the ones we declare for that source's tokens
+   * (`sourceVarPrefix`), not the source's own prefix. Without it the rule references a custom property
+   * nothing on the page declares, which computes to the inherited value and paints silently wrong.
+   */
+  readonly namespace?: string;
+}): Record<string, string>;
+/**
+ * An opacity value as a `color-mix()` share.
+ *
+ * A system may scale opacity as a fraction (`0.5`) or as a percentage (`50%`), and `color-mix()`
+ * takes only the latter — a bare `0.5` there is not a small share but a syntax error, and the
+ * browser drops the whole declaration.
+ *
+ * A token reference is the common case and cannot be read here: the value is a `var()`, and what it
+ * holds is the theme's answer, which changes per mode. So it is scaled in CSS (`calc(… * 100%)`)
+ * rather than resolved, which commits the config to authoring opacity tokens as fractions — the same
+ * convention CSS's own `opacity` property uses.
+ */
+declare function opacityPercentage(value: string): string | undefined;
+/**
+ * A component's effective props — its own props merged over those it inherits by `extends`ing
+ * another component. A child prop overrides the inherited one of the same name; a `null` child
+ * prop omits an inherited one. A native-tag `extends` (a string, not a ref) inherits nothing,
+ * and a composite doesn't extend, so both resolve to just their own props. Chases the `extends`
+ * chain (transitive inheritance), cycle-guarded.
+ */
+declare function resolveComponentProps(config: Config, path: string, seen?: Set<string>): Record<string, unknown>;
+/**
+ * Which component actually declared one of a component's resolved props — its ultimate owner.
+ *
+ * `resolveComponentProps` answers *what* the props are and deliberately flattens away *where each came
+ * from*. That provenance is a real question with more than one caller: a rename recorded against one
+ * Component has to reach the documents of every component that exposes that prop through `inherits`
+ * (`rewriteSpecRefs`), and telling an author which side of a merge a prop came from needs the same fact.
+ *
+ * Mirrors the merge exactly, so the two can't disagree:
+ *
+ *  - an own non-null declaration means this component owns it — a shadow stops the walk, which is why
+ *    `HStack`'s own `gap` is `HStack`'s and not the `Box` `gap` it shadows;
+ *  - an own `null` is the omit tombstone, so the prop does not exist here and has no owner;
+ *  - otherwise the prop is inherited, and the answer is whatever the inherited component says —
+ *    transitively, so `Button` → `Pressable` → `Box` reports `Box`.
+ *
+ * `undefined` when the component doesn't resolve, doesn't expose that prop, or tombstones it.
+ */
+declare function propOwner(config: Config, path: string, prop: string, seen?: Set<string>): string | undefined;
+/** What deriving a domain needs of a prop declaration: the `type` that says which domain rule
+ *  applies, and the `value` slot every type names its domain under. Structural, so a component's
+ *  own typed prop and a loosely-read stored record both satisfy it without either being cast. */
+type PropDeclaration = {
+  type?: unknown;
+  value?: unknown;
+};
+/** A prop declaration's accepted value domain — the leaves an author may write (`warning`,
+ *  `display2`, a variant name), plus an `accepts` check. Resolved once, relationally, from the prop's
+ *  `type`: a `variant`'s own values; a `styleProperty`'s referenced value-set leaves; a `composite` group's
+ *  member leaves. `null` when there's no enumerable domain (a slot/motion content prop, a free scalar,
+ *  or an unconstrained style prop). The one place prop-value domains are derived — consumed by prop
+ *  validation, the `get_component` prop-domain display, and the Studio value picker, so none re-derive. */
+declare function propValueDomain(config: Config, decl: PropDeclaration): {
+  leaves: string[];
+  accepts: (value: string) => boolean;
+} | null;
+/** Validate a prop bag against a component's declared props — unknown props + per-value domain
+ *  checks. Generic: it resolves each prop's domain via {@link propValueDomain} and checks membership;
+ *  no per-prop-type logic here. Returns the error strings (empty = valid). Lives in config so the
+ *  `component/validate` op's truth is config-defined and the pipeline only renders it. */
+declare function validateComponentProps(config: Config, componentPath: string, props: Record<string, unknown>): string[];
+/**
+ * The props one preview tile starts from: the component's `defaultProps` with its `previewProps`
+ * over the top.
+ *
+ * Preview wins, and that direction is the whole reason this exists once. `previewProps` is the state
+ * a person chose to show a component in — Button's `variant`, an Icon prop's example glyph — so a
+ * surface showing that tile has to agree with it, while `defaultProps` remains the baseline for every
+ * prop the tile doesn't pin. Get the order backwards and the panel reports a value the canvas isn't
+ * rendering, which is invisible until someone edits the wrong one.
+ *
+ * THE PRECEDENCE RULE, stated once: only a RENDER surface — a preview tile, the catalogue card, slot
+ * text seeding — reads this merge. An EDIT surface reads and writes the single field it owns
+ * (`defaultProps` OR `previewProps`, never the merge), and anything that SEEDS committed data — a
+ * prop binding, a forward's re-seed, a stored instance prop, a default-value form — reads raw
+ * `defaultProps`. A preview value that reaches any of those stops being staging and becomes a real
+ * default the moment it is saved, which is exactly the leak UDS-3514 closed. Before adding a caller,
+ * decide which of the three it is.
+ *
+ * Empty is the answer for a component that declares neither, and for a path that names no component
+ * at all — a caller asking about something absent gets "nothing pinned", not a crash.
+ *
+ * A fresh object per call, like every projection here. Callers that feed it to a React dep array
+ * memoize on the config and the path, which is what actually changes.
+ *
+ * Read through `Entity.body` rather than `Component.get`, which would be the typed way to ask: this
+ * module is imported by `entities/system/Component.ts` (for `resolveComponentProps` and
+ * `validateComponentProps`), so importing the class back would close a runtime cycle. `body` is the
+ * accessor that exists for a reader which can't reach its entity class, and it is not `toJSON` —
+ * serialization is for storage and the wire.
+ */
+declare function previewDefaults(config: Config, path: string): Record<string, unknown>;
+/** A preview grid, derived. Rows sweep a prop's declared values; columns are the states the
+ *  Component actually styles for. */
+interface PreviewMatrix {
+  /** Prop → its sweepable values: every value a variant-typed own prop declares (or every member of a
+   *  composite-typed prop's group), in declaration order, then any value the style rules name in
+   *  `when` that the declaration doesn't list. A prop with no declared domain keeps rule order. */
+  readonly props: Record<string, string[]>;
+  /** Modifiers the component's own rules style under (`_hover`) — the columns worth showing. */
+  readonly modifiers: string[];
+}
+/**
+ * The preview grid a component implies.
+ *
+ * Nothing new is being said here: a style rule's `when` names a prop and a value, which is an axis
+ * and a point on it, and a rule's `_hover` block is a state worth a column. Authoring a matrix
+ * restated all of that beside the thing it was derived from, and the two could disagree — a variant
+ * added to `styles` and forgotten in the matrix just never appeared in the grid.
+ *
+ * A composite-typed prop is the same statement made relationally: each member of the group it
+ * references is a whole bag of style declarations, so sweeping the prop sweeps styles exactly the
+ * way a `when` does — the rules just never restate it. Left unchased, a component styled entirely
+ * through composites (a text primitive whose `variant` names a composite group) implies an empty
+ * grid, which reads as "no variants" rather than "fifty of them".
+ *
+ * So a component only authors what a preview can't know: the props one tile starts from.
+ */
+declare function previewMatrix(config: Config, path: string): PreviewMatrix;
+/**
+ * A prop's value as the component declares it, from the string a preview axis spells it as.
+ *
+ * `previewMatrix` names every axis value as a string (`'true'`, `'2'`), and a rule matches on the
+ * string form too, so a surface reading the grid never sees the declared type. Anything that writes
+ * a value back — a default chosen off a cell — restores it here, or a boolean prop's default is
+ * stored as the string `'true'` and never equals the `true` an author writes.
+ */
+declare function propValueFromAxis(config: Config, path: string, prop: string, value: string): unknown;
+//#endregion
+export { PreviewMatrix, PropDeclaration, StylePropEntry, StylePropertyItem, authoredBag, authoredValue, className, cssPropValue, cssVar, cssVarRef, declaredPropRouting, memberFromLeaf, memberLeaves, negatedCssValue, opacityPercentage, previewDefaults, previewMatrix, propOwner, propValueDomain, propValueFromAxis, renderStyleValue, resolveComponentProps, resolveFieldValue, resolveTokenValue, resolveTokenValueUnder, routedBag, sourceVarPrefix, styleAliasesOf, styleDeclarations, stylePropEntries, stylePropLeafForToken, stylePropNegates, stylePropTokenGroup, stylePropTokenPath, stylePropTokenValues, stylePropValueFromLeaf, stylePropValueLeaves, stylePropValues, stylePropertiesWriting, stylePropertyAccepts, stylePropertyFor, stylePropertyPathFor, validateComponentProps };