@almadar/ui 2.58.0 → 2.59.1

package/dist/renderer/trait-binding-resolver.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Trait-binding resolver for the interpreted runtime path.
+ *
+ * When a pattern tree contains a string like `"@trait.ItemSearch"` or
+ * `"@trait.ItemSearch.main"` inside a `children:` array (or a
+ * `node`-typed prop), the `SlotContentRenderer` walker calls this
+ * resolver to transform those string leaves into `<TraitFrame>` React
+ * elements before rendering.
+ *
+ * This module only handles the INTERPRETED path — compiled apps bake
+ * `<TraitFrame>` into JSX at build time via the TypeScript shell
+ * codegen (`orbital-shell-typescript/src/backend.rs`). Both paths land
+ * on the same component.
+ *
+ * Scope:
+ *   - string values `"@trait.X[.slot]"` are replaced with
+ *     `<TraitFrame traitName="X" slot={...} />`.
+ *   - strings that don't match the `@trait.*` shape pass through
+ *     verbatim (they may be `@entity.X` bindings resolved elsewhere,
+ *     or plain text content).
+ *   - recurses into arrays and objects so nested children are covered.
+ *
+ * @see docs/Almadar_Std_Gaps.md §3.8
+ */
+export interface ResolveTraitBindingsContext {
+    /**
+     * Depth cap — the walker refuses to descend deeper than this to
+     * protect against deeply nested patterns (real or adversarial).
+     * Default 8; roughly matches the deepest layout trees seen in the
+     * std catalog plus head-room.
+     */
+    depth?: number;
+}
+/**
+ * Walk a pattern-tree value, returning a structurally-identical tree
+ * with `@trait.*` string leaves replaced by `<TraitFrame>` React
+ * elements.
+ *
+ * The walker preserves insertion order of object keys and array
+ * positions — it only transforms the narrow subset of string values
+ * that match the `@trait.X[.slot]` form. Other strings are copied as-is.
+ *
+ * Call from `SlotContentRenderer` once per render, pointed at
+ * `content.props` with `currentSlot` bound to the slot whose render-ui
+ * is being composed.
+ */
+export declare function resolveTraitBindingsInPattern(value: unknown, ctx: ResolveTraitBindingsContext): unknown;
+/**
+ * Lower-level helper: is this string a `@trait.*` binding the resolver
+ * would handle? Useful for consumers that need to treat the trait case
+ * specially before handing the string back to the walker.
+ */
+export declare function isTraitBinding(value: unknown): value is string;