@almadar/core 7.10.0 → 7.11.0

package/dist/builders.d.ts

@@ -1,8 +1,156 @@
-import { T as TraitEventContract, E as Entity, a as TraitEventListener, b as TraitConfig, c as EntityField, d as EntityPersistence, e as EntityRow, U as UseDeclaration, f as EntityRef, g as TraitRef, P as PageRef, O as OrbitalDefinition, h as OrbitalSchema, i as Trait, j as Page, k as PageRefObject, l as TraitReference } from './schema-VTi4U3sS.js';
+import { U as UISlot, E as Effect, T as Trait, R as RenderUIEffect, a as TraitEventContract, b as Entity, c as TraitEventListener, d as TraitConfig, e as EntityField, f as EntityPersistence, g as EntityRow, h as UseDeclaration, i as EntityRef, j as TraitRef, P as PageRef, O as OrbitalDefinition, k as OrbitalSchema, l as Page, m as PageRefObject, n as TraitReference } from './schema-CSAEAlE6.js';
 import { S as SExpr } from './expression-eBO9-SQM.js';
-export { C as ComposeBehaviorsInput, a as ComposeBehaviorsResult, E as EventWiringEntry, L as LayoutStrategy, b as applyEventWiring, c as composeBehaviors, d as detectLayoutStrategy } from './compose-behaviors-UN56dMBD.js';
+export { C as ComposeBehaviorsInput, a as ComposeBehaviorsResult, E as EventWiringEntry, L as LayoutStrategy, b as applyEventWiring, c as composeBehaviors, d as detectLayoutStrategy } from './compose-behaviors-B0k9Zoiw.js';
+import { AnyPatternConfig } from '@almadar/patterns';
 import 'zod';
-import '@almadar/patterns';
+
+/**
+ * Layout-Trait Builders
+ *
+ * Helpers for constructing the canonical inline LayoutTrait pattern that
+ * std layout-shell molecules (`std-filtered-list`, `std-master-detail-layout`,
+ * etc.) use to wrap a set of atom trait references in a `(render-ui main)`
+ * effect with `@trait.X` slot embeds.
+ *
+ * The canonical LayoutTrait is stateless: ONE state (`composing`, initial),
+ * ONE transition (`INIT` self-loop) carrying two effects — `(fetch Entity
+ * {emit: {success, failure}})` and `(render-ui "main" <pattern-tree>)`. Atoms
+ * embedded via `@trait.X` slot references react to the bus events the fetch
+ * emits; the LayoutTrait owns no further state.
+ *
+ * Usage from a std layout-shell molecule:
+ *
+ * ```ts
+ * import { makeSlot, makeLayoutTrait } from '@almadar/core/builders';
+ *
+ * const layout = makeLayoutTrait({
+ *   name: 'DashboardLayout',
+ *   linkedEntity: 'Metric',
+ *   fetchEntity: 'Metric',
+ *   loadedEvent: 'MetricLoaded',
+ *   loadFailedEvent: 'MetricLoadFailed',
+ *   renderUI: {
+ *     type: 'stack',
+ *     direction: 'vertical',
+ *     children: [
+ *       makeSlot('StatsRow'),
+ *       makeSlot('ChartsRow'),
+ *       makeSlot('FeedRow'),
+ *     ],
+ *   },
+ * });
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Build a `@trait.<name>` slot reference string. Used as a child entry in a
+ * pattern tree to embed another trait's render-ui at that position. The
+ * runtime resolves `@trait.X` to the matching trait's render-ui inline.
+ *
+ * @example makeSlot('FilteredItemSearch') // "@trait.FilteredItemSearch"
+ */
+declare function makeSlot(traitName: string): string;
+/**
+ * Build a `(render-ui <slot> <root>)` effect tuple. Pattern-typed sugar over
+ * the raw `RenderUIEffect` literal so callers don't have to spell out the
+ * three-element tuple form.
+ *
+ * @param slot - Canonical UI slot name (`'main'`, `'header'`, etc. — see UI_SLOTS).
+ * @param root - The pattern config for this slot's content. Pass `null` to clear.
+ */
+declare function makeRenderUI(slot: UISlot, root: AnyPatternConfig | null): RenderUIEffect;
+/**
+ * Options for {@link makeLayoutTrait}.
+ */
+interface MakeLayoutTraitOpts {
+    /** Trait name, e.g. `"DashboardGridLayout"`. */
+    name: string;
+    /** Entity this layout's emits/listens bind to. */
+    linkedEntity: string;
+    /** Optional human-readable description (carried through to `Trait.description`). */
+    description?: string;
+    /**
+     * Entity name to fetch on INIT. When set, a `(fetch <Entity> {emit:
+     * {success, failure}})` effect is prepended to the INIT transition. Omit
+     * for purely-presentational layouts that don't load data themselves.
+     */
+    fetchEntity?: string;
+    /**
+     * Event name emitted on successful fetch. Required when `fetchEntity` is
+     * set; the LayoutTrait declares this event in its `emits` and uses it as
+     * the `success` emit-name in the fetch effect.
+     * Convention: `"<Entity>Loaded"`.
+     */
+    loadedEvent?: string;
+    /**
+     * Event name emitted on fetch failure. Required when `fetchEntity` is
+     * set. Convention: `"<Entity>LoadFailed"`.
+     */
+    loadFailedEvent?: string;
+    /**
+     * Payload schema for the loaded event. Defaults to `[{ name: "data", type:
+     * "[<Entity>]" }]` when `fetchEntity` is set. Provide explicitly when the
+     * payload should carry additional fields.
+     */
+    loadedPayloadSchema?: Array<{
+        name: string;
+        type: string;
+        required?: boolean;
+    }>;
+    /**
+     * The pattern tree for the layout's main slot. Children may include
+     * `@trait.X` slot strings (built via {@link makeSlot}) interleaved with
+     * inline pattern configs (`{ type: 'stack', ... }`). The shape conforms to
+     * `AnyPatternConfig` from `@almadar/patterns`.
+     */
+    renderUI: AnyPatternConfig;
+    /**
+     * Override the slot the render-ui effect targets. Defaults to `'main'`.
+     * Specify when the layout shell should render into a sub-slot (rare).
+     */
+    slot?: UISlot;
+    /**
+     * Additional effects appended to the INIT transition AFTER the fetch +
+     * render-ui pair. Most layouts don't need this; provided for advanced
+     * cases (analytics emit, persistence seed, etc.).
+     */
+    extraEffects?: Effect[];
+}
+/**
+ * Build the canonical stateless LayoutTrait used by std layout-shell molecules.
+ *
+ * Result shape:
+ * - `category: 'interaction'`, `scope: 'instance'`
+ * - `linkedEntity` set per the option
+ * - `emits` declares the loaded + loadFailed events when `fetchEntity` is set
+ * - One state: `'composing'` (`isInitial: true`)
+ * - One transition: `composing → composing` on `INIT`, with effects:
+ *   - (when `fetchEntity` set) `['fetch', '<Entity>', { emit: { success, failure } }]`
+ *   - `['render-ui', slot, renderUI]`
+ *   - …`extraEffects` if provided
+ *
+ * Atoms whose trait names appear as `@trait.<name>` strings inside `renderUI`
+ * get embedded by the runtime when the orbital instantiates. The LayoutTrait
+ * itself stays stateless — all reactive behaviour lives in the embedded atoms.
+ */
+declare function makeLayoutTrait(opts: MakeLayoutTraitOpts): Trait;
+
+/**
+ * Orbital Builders
+ *
+ * Pure functions for constructing and composing Orbitals.
+ * No new types. Everything uses existing core types:
+ * Entity, Trait, Page, OrbitalDefinition, OrbitalSchema.
+ *
+ * Three categories:
+ * 1. Builders: construct Entity, Page from common params
+ * 2. Utilities: ensureIdField, resolveDefaults
+ * 3. Composition: connect, compose, pipe
+ *
+ * @packageDocumentation
+ */
 
 /**
  * Ensure the fields array has an `id` field. Prepends one if missing.
@@ -67,6 +215,46 @@ interface MakeTraitRefOpts {
     /** Call-site config overrides. Matches {@link TraitReference.config}. */
     config?: TraitConfig;
 }
+/**
+ * Typed-narrowing variant of {@link MakeTraitRefOpts} for callers that know
+ * the imported atom's overridable surfaces — its event-key set, listen-key
+ * set, and config shape. Generated std factories use this variant so an LLM
+ * tool consumer (orbital-agent) sees the closed event-name set and the
+ * config field schema instead of the un-narrowed `Record<string, string>` /
+ * `TraitConfig` defaults.
+ *
+ * Type parameters:
+ * - `EventKey`   — string union of the atom's emit event names. Narrows the
+ *   `events` rename map's keys to legal originals only.
+ * - `ConfigShape` — typed shape of the trait's `config { ... }` block (literal
+ *   unions intact). Narrows the `config` override to the atom's actual fields.
+ * - `ListenKey`  — string union of the atom's listen-key contract. Narrows
+ *   each listens entry's `event` against the atom's real subscription set.
+ *
+ * Runtime behavior is unchanged — {@link makeTraitRef} accepts both the
+ * narrow and wide forms via the standard structural-typing rules. This is
+ * a type-level narrowing only; widening at the call boundary is intentional.
+ */
+interface MakeTraitRefOptsTyped<EventKey extends string = string, ConfigShape extends TraitConfig = Record<string, never>, ListenKey extends string = string> extends Omit<MakeTraitRefOpts, 'events' | 'effects' | 'listens' | 'config'> {
+    /** Per-key rename map, narrowed to the atom's actual event keys. */
+    events?: Partial<Record<EventKey, string>>;
+    /**
+     * Per-event SExpression effect replacement. Keys are POST-rename event
+     * names so they're caller-defined (no narrowing here); values stay typed
+     * as `SExpr[]`.
+     */
+    effects?: Partial<Record<string, SExpr[]>>;
+    /**
+     * Replace the imported trait's `listens` array entirely. Each entry's
+     * `event` field is narrowed to {@link ListenKey} where the atom's
+     * subscription set is fixed; otherwise this widens to plain string.
+     */
+    listens?: Array<TraitEventListener & {
+        event?: ListenKey;
+    }>;
+    /** Typed call-site config overrides — narrowed to {@link ConfigShape}. */
+    config?: ConfigShape;
+}
 /**
  * Build a {@link TraitReference} from options.
  *
@@ -93,6 +281,21 @@ interface MakePageRefOpts {
     /** Replace the page's trait list. */
     traits?: TraitRef[];
 }
+/**
+ * Typed-narrowing variant of {@link MakePageRefOpts}. Narrows the `traits`
+ * override array's entries to the orbital's known trait-name union — so the
+ * agent can't pass a trait name that doesn't exist on the page's owning
+ * orbital. Generated std page-helpers use this variant to surface the
+ * trait set in the tool schema; un-narrowed call sites stay compatible.
+ *
+ * Type parameter:
+ * - `TraitName` — string union of trait names the page may reference.
+ */
+interface MakePageRefOptsTyped<TraitName extends string = string> extends Omit<MakePageRefOpts, 'traits'> {
+    traits?: Array<{
+        ref: TraitName;
+    } | TraitRef>;
+}
 /**
  * Build a {@link PageRefObject} from options. Pass-through factory — omits
  * optional keys that are `undefined`.
@@ -225,4 +428,4 @@ declare function compose(orbitals: (OrbitalDefinition | OrbitalSchema)[], pages:
  */
 declare function pipe(orbitals: (OrbitalDefinition | OrbitalSchema)[], events: TraitEventContract[], appName?: string): OrbitalSchema;
 
-export { type ComposeConnection, type ComposePage, type MakeAtomOrbitalOpts, type MakeAtomOrbitalTraitOverrides, type MakeEntityOpts, type MakeOrbitalWithUsesOpts, type MakePageOpts, type MakePageRefOpts, type MakeTraitRefOpts, compose, connect, ensureIdField, extractTrait, makeAtomOrbital, makeEntity, makeOrbital, makeOrbitalWithUses, makePage, makePageRef, makeSchema, makeTraitRef, mergeOrbitals, pipe, plural, wire };
+export { type ComposeConnection, type ComposePage, type MakeAtomOrbitalOpts, type MakeAtomOrbitalTraitOverrides, type MakeEntityOpts, type MakeLayoutTraitOpts, type MakeOrbitalWithUsesOpts, type MakePageOpts, type MakePageRefOpts, type MakePageRefOptsTyped, type MakeTraitRefOpts, type MakeTraitRefOptsTyped, compose, connect, ensureIdField, extractTrait, makeAtomOrbital, makeEntity, makeLayoutTrait, makeOrbital, makeOrbitalWithUses, makePage, makePageRef, makeRenderUI, makeSchema, makeSlot, makeTraitRef, mergeOrbitals, pipe, plural, wire };

package/dist/builders.js

@@ -1090,6 +1090,83 @@ function composeBehaviors(input) {
   };
 }
 
+// src/builders/layout-trait.ts
+function makeSlot(traitName) {
+  return `@trait.${traitName}`;
+}
+function makeRenderUI(slot, root) {
+  return root === null ? ["render-ui", slot, null] : ["render-ui", slot, root];
+}
+function makeLayoutTrait(opts) {
+  const slot = opts.slot ?? "main";
+  const effects = [];
+  const emits = [];
+  const eventDefs = [
+    { key: "INIT", name: "Initialize" }
+  ];
+  if (opts.fetchEntity) {
+    if (!opts.loadedEvent || !opts.loadFailedEvent) {
+      throw new Error(
+        `makeLayoutTrait: fetchEntity '${opts.fetchEntity}' set but loadedEvent / loadFailedEvent are required`
+      );
+    }
+    const payloadSchema = opts.loadedPayloadSchema ?? [{ name: "data", type: `[${opts.fetchEntity}]` }];
+    emits.push(
+      { event: opts.loadedEvent, scope: "internal", payloadSchema },
+      {
+        event: opts.loadFailedEvent,
+        scope: "internal",
+        payloadSchema: [
+          { name: "error", type: "string" },
+          { name: "code", type: "string" }
+        ]
+      }
+    );
+    eventDefs.push(
+      { key: opts.loadedEvent, name: `${opts.fetchEntity} loaded`, payloadSchema },
+      {
+        key: opts.loadFailedEvent,
+        name: `${opts.fetchEntity} load failed`,
+        payloadSchema: [
+          { name: "error", type: "string" },
+          { name: "code", type: "string" }
+        ]
+      }
+    );
+    const fetchFx = [
+      "fetch",
+      opts.fetchEntity,
+      { emit: { success: opts.loadedEvent, failure: opts.loadFailedEvent } }
+    ];
+    effects.push(fetchFx);
+  }
+  effects.push(makeRenderUI(slot, opts.renderUI));
+  if (opts.extraEffects && opts.extraEffects.length > 0) {
+    effects.push(...opts.extraEffects);
+  }
+  const trait = {
+    name: opts.name,
+    ...opts.description ? { description: opts.description } : {},
+    category: "interaction",
+    linkedEntity: opts.linkedEntity,
+    scope: "instance",
+    ...emits.length > 0 ? { emits } : {},
+    stateMachine: {
+      states: [{ name: "composing", isInitial: true }],
+      events: eventDefs,
+      transitions: [
+        {
+          from: "composing",
+          to: "composing",
+          event: "INIT",
+          effects
+        }
+      ]
+    }
+  };
+  return trait;
+}
+
 // src/builders.ts
 function ensureIdField(fields) {
   if (!fields || fields.length === 0) return [{ name: "id", type: "string", required: true }];
@@ -1336,6 +1413,6 @@ function pipe(orbitals, events, appName) {
   };
 }
 
-export { applyEventWiring, compose, composeBehaviors, connect, detectLayoutStrategy, ensureIdField, extractTrait, makeAtomOrbital, makeEntity, makeOrbital, makeOrbitalWithUses, makePage, makePageRef, makeSchema, makeTraitRef, mergeOrbitals, pipe, plural, wire };
+export { applyEventWiring, compose, composeBehaviors, connect, detectLayoutStrategy, ensureIdField, extractTrait, makeAtomOrbital, makeEntity, makeLayoutTrait, makeOrbital, makeOrbitalWithUses, makePage, makePageRef, makeRenderUI, makeSchema, makeSlot, makeTraitRef, mergeOrbitals, pipe, plural, wire };
 //# sourceMappingURL=builders.js.map
 //# sourceMappingURL=builders.js.map