@almadar/ui 4.24.0 → 4.26.0

package/dist/context/UISlotContext.d.ts

@@ -19,7 +19,7 @@
  * @packageDocumentation
  */
 import React from 'react';
-import { type UISlotManager, type UISlot, type SlotContent, type RenderUIConfig, type SlotAnimation, type SlotChangeCallback } from '../hooks/useUISlots';
+import { type UISlotManager, type UISlot, type SlotContent, type SlotProps, type SlotPropValue, type SlotCallback, type RenderUIConfig, type SlotAnimation, type SlotChangeCallback } from '../hooks/useUISlots';
 /**
  * Context for the UI Slot Manager
  */
@@ -72,4 +72,4 @@ export declare function useSlotContent(slot: UISlot): SlotContent | null;
  * Hook to check if a slot has content.
  */
 export declare function useSlotHasContent(slot: UISlot): boolean;
-export { UISlotContext, type UISlotManager, type UISlot, type SlotContent, type RenderUIConfig, type SlotAnimation, type SlotChangeCallback, };
+export { UISlotContext, type UISlotManager, type UISlot, type SlotContent, type SlotProps, type SlotPropValue, type SlotCallback, type RenderUIConfig, type SlotAnimation, type SlotChangeCallback, };

package/dist/hooks/useUISlots.d.ts

@@ -1,4 +1,36 @@
-import type { EventPayload } from '@almadar/core';
+/**
+ * useUISlots Hook
+ *
+ * Core hook for managing UI slot rendering in the trait-driven architecture.
+ * Traits use render_ui effects to dynamically render content into slots.
+ *
+ * Slots:
+ * - main: Primary content area
+ * - sidebar: Left/right sidebar
+ * - modal: Modal overlay
+ * - drawer: Slide-in drawer
+ * - overlay: Full-screen overlay
+ * - center: Centered popup
+ * - toast: Toast notifications
+ * - hud-top: Game HUD top bar
+ * - hud-bottom: Game HUD bottom bar
+ * - floating: Draggable floating panel
+ *
+ * Multi-source model (2026-04-24):
+ * A slot can receive renders from multiple source traits across independent
+ * batches (e.g. in the playground, ProbeCreate renders "main" on INIT, then
+ * later ProbePersistor cascades a render into "main" too). Prior code stored
+ * a single SlotContent per slot and last-writer-wins silently dropped
+ * earlier traits' frames. Internally the manager now holds a
+ * `Record<UISlot, Record<sourceKey, SlotContent>>` map and consumers see an
+ * aggregated view: a single SlotContent for single-source slots, or a
+ * synthetic `stack` wrapper when 2+ sources are active simultaneously.
+ * This mirrors the compiled-path page layout's VStack-of-trait-views.
+ *
+ * @packageDocumentation
+ */
+import type React from 'react';
+import type { EventPayloadValue, RenderItemLambda } from '@almadar/core';
 /**
  * Valid UI slot names
  */
@@ -8,13 +40,39 @@ export type UISlot = 'main' | 'sidebar' | 'modal' | 'drawer' | 'overlay' | 'cent
  */
 export type SlotAnimation = 'fade' | 'slide' | 'scale' | 'none';
 /**
- * Pattern-specific props carried by a rendered slot. Pattern authors decide
- * the concrete shape; the slot manager treats this as an opaque record of
- * field-like values sourced from the event-bus payload vocabulary so the
- * same types round-trip through render-ui → useUISlots → UISlotRenderer
- * without a private re-coercion boundary.
+ * Render-prop callback after fn-form-lambda conversion or
+ * `wrapCallbackForEvent` wrapping. Pattern components consume these as
+ * `renderItem` / `onTabChange` / `onClick` / etc. The arg list is
+ * contravariant (`never[]` accepts any caller shape — event handlers,
+ * 2-arg `(item, index)` render-props, etc.); the return is the union of
+ * shapes seen at this layer. Pattern-level prop types narrow the
+ * signature for each consumer downstream.
+ */
+export type SlotCallback = (...args: never[]) => void | React.ReactNode | EventPayloadValue;
+/**
+ * Render-ui prop value: any leaf flowing from a `(render-ui slot {...})`
+ * effect into a React pattern component. The union enumerates every
+ * shape the renderer can receive — no `unknown` escape hatch.
+ *
+ * - JSON primitives (`string`, `number`, `boolean`, `Date`, `null`,
+ *   `undefined`) come through `BindingResolver`.
+ * - `RenderItemLambda` is the unconverted tuple form `["fn", arg, body]`;
+ *   `SlotCallback` is the post-conversion callable form.
+ * - `React.ReactNode` covers substituted `<TraitFrame>` elements.
+ * - The recursive array + object branches mirror the `EventPayloadValue`
+ *   shape but with `SlotPropValue` leaves so functions and React nodes
+ *   can appear at any depth (e.g. `tabs[].content: "@trait.X"` surviving
+ *   substitution into a `ReactElement`).
+ */
+export type SlotPropValue = string | number | boolean | Date | null | undefined | RenderItemLambda | SlotCallback | React.ReactElement | ReadonlyArray<SlotPropValue> | {
+    readonly [key: string]: SlotPropValue;
+};
+/**
+ * Pattern-specific props carried by a rendered slot. The slot manager
+ * routes these from `(render-ui slot {...})` effects to React pattern
+ * components without coercion.
  */
-export type SlotProps = Record<string, EventPayload[string] | unknown>;
+export type SlotProps = Record<string, SlotPropValue>;
 /**
  * Content rendered in a slot
  */