@almadar/core 4.6.0 → 4.7.0

package/dist/builders.d.ts

@@ -1,5 +1,5 @@
-import { T as TraitReference, a as TraitEventContract, E as EntityField, b as EntityPersistence, c as EntityRow, O as OrbitalDefinition, d as OrbitalSchema, e as Trait, f as Entity, P as Page } from './schema-CLFPg1xW.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-Bp32KayC.js';
+import { T as TraitReference, a as TraitEventContract, E as Entity, S as SExpr, b as TraitEventListener, 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 } from './schema-C-6fdZ5P.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-BLEoAOk6.js';
 import 'zod';
 import '@almadar/patterns';
 
@@ -96,6 +96,146 @@ declare function makePage(opts: MakePageOpts): Page;
  * Build an OrbitalDefinition from its three components.
  */
 declare function makeOrbital(name: string, entity: Entity, traits: Trait[], pages: Page[]): OrbitalDefinition;
+/**
+ * Options for {@link makeTraitRef}.
+ */
+interface MakeTraitRefOpts {
+    /**
+     * Optional registry path disambiguator that pairs with {@link ref}
+     * (see {@link TraitReference.from}).
+     */
+    from?: string;
+    /** Trait reference string, e.g. "Browse.traits.BrowseItemBrowse". */
+    ref: string;
+    /** Rename the inlined trait at the call site. */
+    name?: string;
+    /** Rebind the trait to a different linkedEntity. */
+    linkedEntity?: string;
+    /** Per-key rename map, e.g. `{ OPEN: "ADD_ITEM" }`. */
+    events?: Record<string, string>;
+    /**
+     * Per-event SExpression effect replacement. Keys are POST-rename event
+     * names. See {@link TraitReference.effects} for the full contract.
+     */
+    effects?: Record<string, SExpr[]>;
+    /** Replace the imported trait's `listens` array entirely. */
+    listens?: TraitEventListener[];
+    /** Set every emit's scope. */
+    emitsScope?: 'internal' | 'external';
+    /**
+     * Nested config overrides. Matches the real {@link TraitReference.config}
+     * shape: `Record<string, Record<string, unknown>>` (the outer key is the
+     * config field name, the inner record is its value shape).
+     */
+    config?: Record<string, Record<string, unknown>>;
+}
+/**
+ * Build a {@link TraitReference} from options.
+ *
+ * Pass-through factory: copies only the fields that are actually provided,
+ * so optionals stay absent (no `key: undefined` slots) and the emitted
+ * object matches the inliner's expectation that "present = override".
+ */
+declare function makeTraitRef(opts: MakeTraitRefOpts): TraitReference;
+/**
+ * Options for {@link makePageRef}.
+ */
+interface MakePageRefOpts {
+    /**
+     * Optional registry path disambiguator that pairs with {@link ref}
+     * (see {@link PageRefObject.from}).
+     */
+    from?: string;
+    /** Page reference string, e.g. "Browse.pages.BrowseItemPage". */
+    ref: string;
+    /** URL path override. */
+    path?: string;
+    /** Rebind the page's primary entity. */
+    linkedEntity?: string;
+    /** Replace the page's trait list. */
+    traits?: TraitRef[];
+}
+/**
+ * Build a {@link PageRefObject} from options. Pass-through factory — omits
+ * optional keys that are `undefined`.
+ */
+declare function makePageRef(opts: MakePageRefOpts): PageRefObject;
+/**
+ * Options for {@link makeOrbitalWithUses}.
+ */
+interface MakeOrbitalWithUsesOpts {
+    /** Orbital name. */
+    name: string;
+    /**
+     * Per-orbital `uses:` header entries (see CLAUDE.md "uses: lives inside
+     * the orbital").
+     */
+    uses: UseDeclaration[];
+    /** Entity (inline or reference form). */
+    entity: EntityRef;
+    /** Trait references. */
+    traits: TraitRef[];
+    /** Optional page references (omitted entirely when not provided). */
+    pages?: PageRef[];
+}
+/**
+ * Build an {@link OrbitalDefinition} with the `uses:` header set. Follows
+ * the convention that `uses:` lives on the orbital (not the schema).
+ *
+ * When `pages` is omitted, the result has no `pages` property (matches the
+ * existing {@link OrbitalDefinition.pages} optionality in descriptors that
+ * carry trait-only atoms).
+ */
+declare function makeOrbitalWithUses(opts: MakeOrbitalWithUsesOpts): OrbitalDefinition;
+/**
+ * Options for {@link makeAtomOrbital}.
+ *
+ * Overrides for the single trait reference. Mirrors the {@link MakeTraitRefOpts}
+ * subset that is meaningful at the atom-wrapping call site.
+ */
+interface MakeAtomOrbitalTraitOverrides {
+    name?: string;
+    events?: Record<string, string>;
+    effects?: Record<string, SExpr[]>;
+    listens?: TraitEventListener[];
+    emitsScope?: 'internal' | 'external';
+    config?: Record<string, Record<string, unknown>>;
+}
+/**
+ * Options for {@link makeAtomOrbital}.
+ */
+interface MakeAtomOrbitalOpts {
+    /** Orbital name, e.g. `${entityName}Orbital`. */
+    name: string;
+    /** Atom registry path, e.g. `std/behaviors/atoms/std-browse`. */
+    atomPath: string;
+    /** Import alias (PascalCase), e.g. `Browse`. */
+    alias: string;
+    /** Entity definition to attach to the orbital. */
+    entity: Entity;
+    /** Trait reference string, e.g. `Browse.traits.BrowseItemBrowse`. */
+    traitRef: string;
+    /** Optional trait-level overrides applied at the call site. */
+    traitOverrides?: MakeAtomOrbitalTraitOverrides;
+    /** Optional page reference string, e.g. `Browse.pages.BrowseItemPage`. */
+    pageRef?: string;
+    /** Optional page-level overrides applied at the call site. */
+    pageOverrides?: {
+        path?: string;
+    };
+}
+/**
+ * Build a single-atom {@link OrbitalDefinition}.
+ *
+ * The common atom shape: one entity + one trait reference + (optionally) one
+ * page reference, all under a single `uses:` import. Wraps
+ * {@link makeTraitRef}, {@link makePageRef}, and {@link makeOrbitalWithUses}.
+ *
+ * The trait reference is linkedEntity-bound to `entity.name` by default so
+ * that the inliner's entity-substitution pass rewrites every `["ref", X]`
+ * and `@X.path` reference inside the atom.
+ */
+declare function makeAtomOrbital(opts: MakeAtomOrbitalOpts): OrbitalDefinition;
 /**
  * Wrap one or more OrbitalDefinitions into an OrbitalSchema.
  * Every .orb file should be a full OrbitalSchema — this is the builder for that.
@@ -147,4 +287,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 MakeEntityOpts, type MakePageOpts, compose, connect, ensureIdField, explodeBehaviorComposition, extractTrait, makeEntity, makeOrbital, makePage, makeSchema, mergeOrbitals, pipe, plural, wire };
+export { type ComposeConnection, type ComposePage, type MakeAtomOrbitalOpts, type MakeAtomOrbitalTraitOverrides, type MakeEntityOpts, type MakeOrbitalWithUsesOpts, type MakePageOpts, type MakePageRefOpts, type MakeTraitRefOpts, compose, connect, ensureIdField, explodeBehaviorComposition, extractTrait, makeAtomOrbital, makeEntity, makeOrbital, makeOrbitalWithUses, makePage, makePageRef, makeSchema, makeTraitRef, mergeOrbitals, pipe, plural, wire };

package/dist/builders.js

@@ -1181,6 +1181,64 @@ function makePage(opts) {
 function makeOrbital(name, entity, traits, pages) {
   return { name, entity, traits, pages };
 }
+function makeTraitRef(opts) {
+  const ref = { ref: opts.ref };
+  if (opts.from !== void 0) ref.from = opts.from;
+  if (opts.name !== void 0) ref.name = opts.name;
+  if (opts.linkedEntity !== void 0) ref.linkedEntity = opts.linkedEntity;
+  if (opts.events !== void 0) ref.events = opts.events;
+  if (opts.effects !== void 0) ref.effects = opts.effects;
+  if (opts.listens !== void 0) ref.listens = opts.listens;
+  if (opts.emitsScope !== void 0) ref.emitsScope = opts.emitsScope;
+  if (opts.config !== void 0) ref.config = opts.config;
+  return ref;
+}
+function makePageRef(opts) {
+  const ref = { ref: opts.ref };
+  if (opts.from !== void 0) ref.from = opts.from;
+  if (opts.path !== void 0) ref.path = opts.path;
+  if (opts.linkedEntity !== void 0) ref.linkedEntity = opts.linkedEntity;
+  if (opts.traits !== void 0) ref.traits = opts.traits;
+  return ref;
+}
+function makeOrbitalWithUses(opts) {
+  const orbital = {
+    name: opts.name,
+    uses: opts.uses,
+    entity: opts.entity,
+    traits: opts.traits,
+    pages: opts.pages ?? []
+  };
+  return orbital;
+}
+function makeAtomOrbital(opts) {
+  const traitRef = makeTraitRef({
+    from: opts.atomPath,
+    ref: opts.traitRef,
+    linkedEntity: opts.entity.name,
+    ...opts.traitOverrides?.name !== void 0 ? { name: opts.traitOverrides.name } : {},
+    ...opts.traitOverrides?.events !== void 0 ? { events: opts.traitOverrides.events } : {},
+    ...opts.traitOverrides?.effects !== void 0 ? { effects: opts.traitOverrides.effects } : {},
+    ...opts.traitOverrides?.listens !== void 0 ? { listens: opts.traitOverrides.listens } : {},
+    ...opts.traitOverrides?.emitsScope !== void 0 ? { emitsScope: opts.traitOverrides.emitsScope } : {},
+    ...opts.traitOverrides?.config !== void 0 ? { config: opts.traitOverrides.config } : {}
+  });
+  const pages = opts.pageRef ? [
+    makePageRef({
+      from: opts.atomPath,
+      ref: opts.pageRef,
+      linkedEntity: opts.entity.name,
+      ...opts.pageOverrides?.path !== void 0 ? { path: opts.pageOverrides.path } : {}
+    })
+  ] : void 0;
+  return makeOrbitalWithUses({
+    name: opts.name,
+    uses: [{ from: opts.atomPath, as: opts.alias }],
+    entity: opts.entity,
+    traits: [traitRef],
+    ...pages !== void 0 ? { pages } : {}
+  });
+}
 function makeSchema(name, ...definitions) {
   return { name, version: "1.0.0", orbitals: definitions };
 }
@@ -1328,6 +1386,6 @@ function pipe(orbitals, events, appName) {
   };
 }
 
-export { applyEventWiring, compose, composeBehaviors, connect, detectLayoutStrategy, ensureIdField, explodeBehaviorComposition, extractTrait, makeEntity, makeOrbital, makePage, makeSchema, mergeOrbitals, pipe, plural, wire };
+export { applyEventWiring, compose, composeBehaviors, connect, detectLayoutStrategy, ensureIdField, explodeBehaviorComposition, extractTrait, makeAtomOrbital, makeEntity, makeOrbital, makeOrbitalWithUses, makePage, makePageRef, makeSchema, makeTraitRef, mergeOrbitals, pipe, plural, wire };
 //# sourceMappingURL=builders.js.map
 //# sourceMappingURL=builders.js.map