@almadar/ui 5.121.3 → 5.122.0

package/dist/providers/index.d.cts

@@ -257,6 +257,18 @@ declare namespace OrbitalProvider {
  * path's codegen wraps each trait view with the same provider so both
  * paths share the qualification contract.
  *
+ * ## Embedded-trait emit bubbling (R-EMBEDDED-EMIT-BUBBLE)
+ *
+ * Providers NEST: when a trait's `render-ui` embeds another trait
+ * (`@trait.X` / inline `<External.Trait …/>`), the embedded view is
+ * rendered inside the host's subtree AND wraps itself in its own
+ * provider. The context therefore carries the full scope CHAIN
+ * (innermost-first), not a single scope. `useEventBus` fans every
+ * `UI:*` emit out to each scope on the chain so the host trait's
+ * subscribers hear emits from the embedded trait — a button authored
+ * as `<UiButton.traits.ButtonRender action={CREATE}/>` inside a host
+ * dispatches on the host's qualified key, not only the hoisted atom's.
+ *
  * @packageDocumentation
  */
 
@@ -266,6 +278,13 @@ interface TraitScope {
     /** Trait name within the orbital (e.g. `"ContactBrowse"`). */
     trait: string;
 }
+/**
+ * Scope chain, innermost-first. `chain[0]` is the trait whose subtree
+ * the caller renders inside; `chain[1..]` are its host ancestors (the
+ * traits whose `render-ui` embedded it, outermost last). An empty
+ * chain means the caller is outside any `TraitScopeProvider`.
+ */
+type TraitScopeChain = readonly TraitScope[];
 interface TraitScopeProviderProps {
     orbital: string;
     trait: string;
@@ -275,12 +294,22 @@ interface TraitScopeProviderProps {
  * Wrap a trait's rendered subtree to qualify bare `UI:*` emits with the
  * trait's scope. Mount this at the slot-content boundary in runtime
  * mode (UISlotRenderer) and at each generated trait view's outermost
- * element in compiled mode (orbital-shell-typescript codegen).
+ * element in compiled mode (orbital-shell-typescript codegen). Nesting
+ * is preserved: a provider prepends itself to the parent chain so
+ * embedded-trait emits can bubble to their host.
  */
 declare function TraitScopeProvider({ orbital, trait, children, }: TraitScopeProviderProps): React__default.ReactElement;
 /**
- * Read the current trait scope. Returns `null` when called outside
- * any `TraitScopeProvider` (e.g. Storybook, design-system catalog).
+ * Read the full trait-scope chain, innermost-first. Empty when called
+ * outside any `TraitScopeProvider` (e.g. Storybook, design-system
+ * catalog). `useEventBus` uses this to fan embedded-trait emits out to
+ * every host ancestor.
+ */
+declare function useTraitScopeChain(): TraitScopeChain;
+/**
+ * Read the innermost (nearest) trait scope. Returns `null` when called
+ * outside any `TraitScopeProvider`. Kept for callers that only need the
+ * immediate scope.
  */
 declare function useTraitScope(): TraitScope | null;
 
@@ -425,4 +454,4 @@ declare function useOfflineMode(): OfflineModeContextValue;
  */
 declare function useOptionalOfflineMode(): OfflineModeContextValue | null;
 
-export { EventBusContext, EventBusProvider, type OfflineModeContextValue, OfflineModeProvider, type OfflineModeProviderProps, OrbitalProvider, type OrbitalProviderProps, SelectionContext, type SelectionContextType, SelectionProvider, type TraitScope, TraitScopeProvider, type TraitScopeProviderProps, UIThemeDefinition, VerificationProvider, type VerificationProviderProps, useOfflineMode, useOptionalOfflineMode, useSelection, useSelectionOptional, useTraitScope };
+export { EventBusContext, EventBusProvider, type OfflineModeContextValue, OfflineModeProvider, type OfflineModeProviderProps, OrbitalProvider, type OrbitalProviderProps, SelectionContext, type SelectionContextType, SelectionProvider, type TraitScope, TraitScopeProvider, type TraitScopeProviderProps, UIThemeDefinition, VerificationProvider, type VerificationProviderProps, useOfflineMode, useOptionalOfflineMode, useSelection, useSelectionOptional, useTraitScope, useTraitScopeChain };

package/dist/providers/index.d.ts

@@ -257,6 +257,18 @@ declare namespace OrbitalProvider {
  * path's codegen wraps each trait view with the same provider so both
  * paths share the qualification contract.
  *
+ * ## Embedded-trait emit bubbling (R-EMBEDDED-EMIT-BUBBLE)
+ *
+ * Providers NEST: when a trait's `render-ui` embeds another trait
+ * (`@trait.X` / inline `<External.Trait …/>`), the embedded view is
+ * rendered inside the host's subtree AND wraps itself in its own
+ * provider. The context therefore carries the full scope CHAIN
+ * (innermost-first), not a single scope. `useEventBus` fans every
+ * `UI:*` emit out to each scope on the chain so the host trait's
+ * subscribers hear emits from the embedded trait — a button authored
+ * as `<UiButton.traits.ButtonRender action={CREATE}/>` inside a host
+ * dispatches on the host's qualified key, not only the hoisted atom's.
+ *
  * @packageDocumentation
  */
 
@@ -266,6 +278,13 @@ interface TraitScope {
     /** Trait name within the orbital (e.g. `"ContactBrowse"`). */
     trait: string;
 }
+/**
+ * Scope chain, innermost-first. `chain[0]` is the trait whose subtree
+ * the caller renders inside; `chain[1..]` are its host ancestors (the
+ * traits whose `render-ui` embedded it, outermost last). An empty
+ * chain means the caller is outside any `TraitScopeProvider`.
+ */
+type TraitScopeChain = readonly TraitScope[];
 interface TraitScopeProviderProps {
     orbital: string;
     trait: string;
@@ -275,12 +294,22 @@ interface TraitScopeProviderProps {
  * Wrap a trait's rendered subtree to qualify bare `UI:*` emits with the
  * trait's scope. Mount this at the slot-content boundary in runtime
  * mode (UISlotRenderer) and at each generated trait view's outermost
- * element in compiled mode (orbital-shell-typescript codegen).
+ * element in compiled mode (orbital-shell-typescript codegen). Nesting
+ * is preserved: a provider prepends itself to the parent chain so
+ * embedded-trait emits can bubble to their host.
  */
 declare function TraitScopeProvider({ orbital, trait, children, }: TraitScopeProviderProps): React__default.ReactElement;
 /**
- * Read the current trait scope. Returns `null` when called outside
- * any `TraitScopeProvider` (e.g. Storybook, design-system catalog).
+ * Read the full trait-scope chain, innermost-first. Empty when called
+ * outside any `TraitScopeProvider` (e.g. Storybook, design-system
+ * catalog). `useEventBus` uses this to fan embedded-trait emits out to
+ * every host ancestor.
+ */
+declare function useTraitScopeChain(): TraitScopeChain;
+/**
+ * Read the innermost (nearest) trait scope. Returns `null` when called
+ * outside any `TraitScopeProvider`. Kept for callers that only need the
+ * immediate scope.
  */
 declare function useTraitScope(): TraitScope | null;
 
@@ -425,4 +454,4 @@ declare function useOfflineMode(): OfflineModeContextValue;
  */
 declare function useOptionalOfflineMode(): OfflineModeContextValue | null;
 
-export { EventBusContext, EventBusProvider, type OfflineModeContextValue, OfflineModeProvider, type OfflineModeProviderProps, OrbitalProvider, type OrbitalProviderProps, SelectionContext, type SelectionContextType, SelectionProvider, type TraitScope, TraitScopeProvider, type TraitScopeProviderProps, UIThemeDefinition, VerificationProvider, type VerificationProviderProps, useOfflineMode, useOptionalOfflineMode, useSelection, useSelectionOptional, useTraitScope };
+export { EventBusContext, EventBusProvider, type OfflineModeContextValue, OfflineModeProvider, type OfflineModeProviderProps, OrbitalProvider, type OrbitalProviderProps, SelectionContext, type SelectionContextType, SelectionProvider, type TraitScope, TraitScopeProvider, type TraitScopeProviderProps, UIThemeDefinition, VerificationProvider, type VerificationProviderProps, useOfflineMode, useOptionalOfflineMode, useSelection, useSelectionOptional, useTraitScope, useTraitScopeChain };