@almadar/ui 2.8.1 → 2.9.1

package/dist/runtime/index.js

@@ -0,0 +1,471 @@
+import '../chunk-GTIAVPI5.js';
+import '../chunk-N7MVUW4R.js';
+import '../chunk-3HJHHULT.js';
+import { useFetchedDataContext } from '../chunk-7AKZ7SRV.js';
+import '../chunk-P6NZVIE5.js';
+import '../chunk-DKQN5FVU.js';
+import '../chunk-WGJIL4YR.js';
+import { useEventBus } from '../chunk-YXZM3WCF.js';
+import '../chunk-3JGAROCW.js';
+import '../chunk-6D5QMEUS.js';
+import '../chunk-TSETXL2E.js';
+import '../chunk-K2D5D3WK.js';
+import '../chunk-PKBMQBKP.js';
+import { createContext, useMemo, useContext, useState, useRef, useEffect, useCallback } from 'react';
+import { isCircuitEvent, schemaToIR, getPage, clearSchemaCache as clearSchemaCache$1 } from '@almadar/core';
+import { StateMachineManager, EffectExecutor } from '@almadar/runtime';
+import { isEntityAwarePattern } from '@almadar/patterns';
+import { jsx } from 'react/jsx-runtime';
+
+// runtime/createClientEffectHandlers.ts
+function createClientEffectHandlers(options) {
+  const { eventBus, slotSetter, navigate, notify, enrichPattern } = options;
+  return {
+    emit: (event, payload) => {
+      const prefixedEvent = event.startsWith("UI:") ? event : `UI:${event}`;
+      eventBus.emit(prefixedEvent, { payload });
+    },
+    persist: async () => {
+      console.warn("[ClientEffectHandlers] persist is server-side only, ignored on client");
+    },
+    set: () => {
+      console.warn("[ClientEffectHandlers] set is server-side only, ignored on client");
+    },
+    callService: async () => {
+      console.warn("[ClientEffectHandlers] callService is server-side only, ignored on client");
+      return {};
+    },
+    renderUI: (slot, pattern, props) => {
+      if (pattern === null) {
+        slotSetter.clearSlot(slot);
+        return;
+      }
+      const enriched = enrichPattern ? enrichPattern(pattern) : pattern;
+      slotSetter.addPattern(slot, enriched, props);
+    },
+    navigate: navigate ?? ((path) => {
+      console.warn("[ClientEffectHandlers] No navigate handler, ignoring:", path);
+    }),
+    notify: notify ?? ((msg, type) => {
+      console.log(`[ClientEffectHandlers] notify (${type}):`, msg);
+    })
+  };
+}
+var EntitySchemaContext = createContext(null);
+function EntitySchemaProvider({
+  entities,
+  children
+}) {
+  const entitiesMap = useMemo(() => {
+    const map = /* @__PURE__ */ new Map();
+    for (const entity of entities) {
+      map.set(entity.name, entity);
+    }
+    return map;
+  }, [entities]);
+  const contextValue = useMemo(
+    () => ({
+      entities: entitiesMap
+    }),
+    [entitiesMap]
+  );
+  return /* @__PURE__ */ jsx(EntitySchemaContext.Provider, { value: contextValue, children });
+}
+function useEntitySchema() {
+  const context = useContext(EntitySchemaContext);
+  if (!context) {
+    throw new Error("useEntitySchema must be used within an EntitySchemaProvider");
+  }
+  return context;
+}
+function useEntityDefinition(entityName) {
+  const { entities } = useEntitySchema();
+  return entities.get(entityName);
+}
+
+// runtime/useTraitStateMachine.ts
+function toTraitDefinition(binding) {
+  return {
+    name: binding.trait.name,
+    states: binding.trait.states,
+    transitions: binding.trait.transitions,
+    listens: binding.trait.listens
+  };
+}
+function normalizeEventKey(eventKey) {
+  return eventKey.startsWith("UI:") ? eventKey.slice(3) : eventKey;
+}
+function useTraitStateMachine(traitBindings, slotsActions, options) {
+  const eventBus = useEventBus();
+  const { entities } = useEntitySchema();
+  const fetchedDataContext = useFetchedDataContext();
+  const manager = useMemo(() => {
+    const traitDefs = traitBindings.map(toTraitDefinition);
+    return new StateMachineManager(traitDefs);
+  }, [traitBindings]);
+  const [traitStates, setTraitStates] = useState(() => {
+    return manager.getAllStates();
+  });
+  const traitBindingsRef = useRef(traitBindings);
+  const managerRef = useRef(manager);
+  const slotsActionsRef = useRef(slotsActions);
+  const optionsRef = useRef(options);
+  useEffect(() => {
+    traitBindingsRef.current = traitBindings;
+  }, [traitBindings]);
+  useEffect(() => {
+    managerRef.current = manager;
+    setTraitStates(manager.getAllStates());
+  }, [manager]);
+  useEffect(() => {
+    slotsActionsRef.current = slotsActions;
+  }, [slotsActions]);
+  useEffect(() => {
+    optionsRef.current = options;
+  }, [options]);
+  useEffect(() => {
+    const newManager = managerRef.current;
+    newManager.resetAll();
+    setTraitStates(newManager.getAllStates());
+    console.log(
+      "[TraitStateMachine] Reset states for page navigation:",
+      Array.from(newManager.getAllStates().keys()).join(", ")
+    );
+  }, [traitBindings]);
+  const processEvent = useCallback((eventKey, payload) => {
+    const normalizedEvent = normalizeEventKey(eventKey);
+    const bindings = traitBindingsRef.current;
+    const currentManager = managerRef.current;
+    const actions = slotsActionsRef.current;
+    console.log("[TraitStateMachine] Processing event:", normalizedEvent, "payload:", payload);
+    const bindingMap = new Map(bindings.map((b) => [b.trait.name, b]));
+    const results = currentManager.sendEvent(normalizedEvent, payload);
+    for (const { traitName, result } of results) {
+      const binding = bindingMap.get(traitName);
+      const traitState = currentManager.getState(traitName);
+      if (!binding || !traitState) continue;
+      if (result.executed && result.effects.length > 0) {
+        console.log(
+          "[TraitStateMachine] Executing",
+          result.effects.length,
+          "effects for",
+          traitName,
+          "| linkedEntity:",
+          binding.linkedEntity,
+          "| transition:",
+          `${result.previousState} -> ${result.newState}`,
+          "| effects:",
+          JSON.stringify(result.effects)
+        );
+        const linkedEntity = binding.linkedEntity || "";
+        const entityId = payload?.entityId;
+        const entityData = linkedEntity && entityId && fetchedDataContext ? fetchedDataContext.getById(linkedEntity, entityId) || {} : payload || {};
+        const pendingSlots = /* @__PURE__ */ new Map();
+        const slotSource = {
+          trait: binding.trait.name,
+          state: result.previousState,
+          transition: `${result.previousState}->${result.newState}`,
+          effects: result.effects,
+          traitDefinition: binding.trait
+        };
+        const handlers = createClientEffectHandlers({
+          eventBus,
+          slotSetter: {
+            addPattern: (slot, pattern, props) => {
+              const existing = pendingSlots.get(slot) || [];
+              existing.push({ pattern, props: props || {} });
+              pendingSlots.set(slot, existing);
+            },
+            clearSlot: (slot) => {
+              pendingSlots.set(slot, []);
+            }
+          },
+          navigate: optionsRef.current?.navigate,
+          notify: optionsRef.current?.notify,
+          enrichPattern: (pattern) => {
+            const patternType = pattern?.type;
+            if (linkedEntity && patternType && isEntityAwarePattern(patternType)) {
+              const patternRecord = pattern;
+              if (!patternRecord.entity && fetchedDataContext) {
+                const records = fetchedDataContext.getData(linkedEntity);
+                if (records.length > 0) {
+                  return { type: patternType, ...patternRecord, entity: records };
+                }
+              }
+            }
+            return pattern;
+          }
+        });
+        const bindingCtx = {
+          entity: entityData,
+          payload: payload || {},
+          state: result.previousState
+        };
+        const effectContext = {
+          traitName: binding.trait.name,
+          state: result.previousState,
+          transition: `${result.previousState}->${result.newState}`,
+          linkedEntity,
+          entityId
+        };
+        const executor = new EffectExecutor({ handlers, bindings: bindingCtx, context: effectContext });
+        executor.executeAll(result.effects).then(() => {
+          console.log(
+            "[TraitStateMachine] After executeAll, pendingSlots:",
+            Object.fromEntries(pendingSlots.entries())
+          );
+          for (const [slot, patterns] of pendingSlots) {
+            if (patterns.length === 0) {
+              actions.clearSlot(slot);
+            } else {
+              actions.setSlotPatterns(slot, patterns, slotSource);
+            }
+          }
+        }).catch((error) => {
+          console.error(
+            "[TraitStateMachine] Effect execution error:",
+            error,
+            "| effects:",
+            JSON.stringify(result.effects)
+          );
+        });
+      } else if (!result.executed) {
+        if (result.guardResult === false) {
+          console.log(
+            "[TraitStateMachine] Guard blocked transition:",
+            traitName,
+            result.previousState,
+            "->",
+            result.transition?.to
+          );
+        } else if (!result.transition) {
+          if (isCircuitEvent(normalizedEvent)) {
+            console.warn(
+              `[CLOSED CIRCUIT VIOLATION] Trait "${traitName}" in state "${traitState.currentState}" received event "${normalizedEvent}" but has no transition to handle it.
+   This is likely a schema issue. To fix, add a transition:
+   { from: "${traitState.currentState}", to: "<target_state>", event: "${normalizedEvent}", effects: [...] }
+   Or ensure the previous action (that opened this UI) properly transitions back before emitting this event.`
+            );
+          } else {
+            console.log(
+              "[TraitStateMachine] No transition for",
+              traitName,
+              "from state:",
+              traitState.currentState,
+              "on event:",
+              normalizedEvent
+            );
+          }
+        }
+      }
+    }
+    if (results.length > 0) {
+      setTraitStates(currentManager.getAllStates());
+    }
+    const onEventProcessed = optionsRef.current?.onEventProcessed;
+    if (onEventProcessed) {
+      onEventProcessed(normalizedEvent, payload);
+    }
+  }, [entities, fetchedDataContext, eventBus]);
+  const sendEvent = useCallback((eventKey, payload) => {
+    processEvent(eventKey, payload);
+  }, [processEvent]);
+  const getTraitState = useCallback((traitName) => {
+    return managerRef.current.getState(traitName);
+  }, []);
+  const canHandleEvent = useCallback((traitName, eventKey) => {
+    const normalizedEvent = normalizeEventKey(eventKey);
+    return managerRef.current.canHandleEvent(traitName, normalizedEvent);
+  }, []);
+  useEffect(() => {
+    const allEvents = /* @__PURE__ */ new Set();
+    for (const binding of traitBindings) {
+      for (const event of binding.trait.events) {
+        allEvents.add(event.key);
+      }
+      for (const transition of binding.trait.transitions) {
+        allEvents.add(transition.event);
+      }
+    }
+    console.log("[TraitStateMachine] Subscribing to events:", Array.from(allEvents));
+    const unsubscribes = [];
+    for (const eventKey of allEvents) {
+      if (eventKey === "INIT" || eventKey === "LOAD" || eventKey === "$MOUNT") {
+        continue;
+      }
+      const unsub = eventBus.on(`UI:${eventKey}`, (event) => {
+        console.log("[TraitStateMachine] Received event:", `UI:${eventKey}`, event);
+        processEvent(eventKey, event.payload);
+      });
+      unsubscribes.push(unsub);
+    }
+    return () => {
+      for (const unsub of unsubscribes) {
+        unsub();
+      }
+    };
+  }, [traitBindings, eventBus, processEvent]);
+  return {
+    traitStates,
+    sendEvent,
+    getTraitState,
+    canHandleEvent
+  };
+}
+function useResolvedSchema(schema, pageName) {
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState(null);
+  const ir = useMemo(() => {
+    if (!schema) return null;
+    try {
+      return schemaToIR(schema);
+    } catch (err) {
+      setError(err instanceof Error ? err.message : "Schema resolution failed");
+      return null;
+    }
+  }, [schema]);
+  useEffect(() => {
+    setLoading(false);
+  }, [ir]);
+  const result = useMemo(() => {
+    if (!ir) {
+      return {
+        page: void 0,
+        traits: [],
+        entities: /* @__PURE__ */ new Map(),
+        allEntities: /* @__PURE__ */ new Map(),
+        allTraits: /* @__PURE__ */ new Map(),
+        loading,
+        error: error || (schema ? null : "No schema provided"),
+        ir: null
+      };
+    }
+    const page = getPage(ir, pageName);
+    console.log("[useResolvedSchema] Resolved page:", page?.name, "| path:", page?.path, "| traits:", page?.traits.length);
+    const traits = page?.traits || [];
+    const entities = /* @__PURE__ */ new Map();
+    if (page) {
+      for (const binding of page.entityBindings) {
+        entities.set(binding.entity.name, binding.entity);
+      }
+    }
+    return {
+      page,
+      traits,
+      entities,
+      allEntities: ir.entities,
+      allTraits: ir.traits,
+      loading,
+      error,
+      ir
+    };
+  }, [ir, pageName, loading, error, schema]);
+  return result;
+}
+function clearSchemaCache() {
+  clearSchemaCache$1();
+}
+var TraitContext = createContext(null);
+function TraitProvider({
+  traits: traitBindings,
+  children
+}) {
+  const traitInstances = useMemo(() => {
+    const map = /* @__PURE__ */ new Map();
+    for (const binding of traitBindings) {
+      const trait = binding.trait;
+      const initialState = trait.states.find((s) => s.isInitial);
+      const stateName = initialState?.name || trait.states[0]?.name || "idle";
+      const instance = {
+        name: trait.name,
+        currentState: stateName,
+        availableEvents: trait.transitions.filter((t) => t.from === stateName).map((t) => t.event),
+        dispatch: (eventKey, payload) => {
+          console.log(`[TraitProvider] Dispatch to ${trait.name}: ${eventKey}`, payload);
+        },
+        canDispatch: (eventKey) => {
+          return trait.transitions.some(
+            (t) => t.from === stateName && t.event === eventKey
+          );
+        },
+        trait
+      };
+      map.set(trait.name, instance);
+    }
+    return map;
+  }, [traitBindings]);
+  const contextValue = useMemo(() => {
+    return {
+      traits: traitInstances,
+      getTrait: (name) => traitInstances.get(name),
+      dispatchToTrait: (traitName, eventKey, payload) => {
+        const instance = traitInstances.get(traitName);
+        if (instance) {
+          instance.dispatch(eventKey, payload);
+        }
+      },
+      canDispatch: (traitName, eventKey) => {
+        const instance = traitInstances.get(traitName);
+        return instance?.canDispatch(eventKey) || false;
+      }
+    };
+  }, [traitInstances]);
+  return /* @__PURE__ */ jsx(TraitContext.Provider, { value: contextValue, children });
+}
+function useTraitContext() {
+  const context = useContext(TraitContext);
+  if (!context) {
+    throw new Error("useTraitContext must be used within a TraitProvider");
+  }
+  return context;
+}
+function useTrait(traitName) {
+  const context = useTraitContext();
+  return context.getTrait(traitName);
+}
+var SlotsStateContext = createContext({});
+var SlotsActionsContext = createContext(null);
+function SlotsProvider({ children }) {
+  const [slots, setSlots] = useState({});
+  const setSlotPatterns = useCallback((slot, patterns, source) => {
+    setSlots((prev) => ({
+      ...prev,
+      [slot]: { patterns, source }
+    }));
+  }, []);
+  const clearSlot = useCallback((slot) => {
+    setSlots((prev) => {
+      if (!(slot in prev)) return prev;
+      const next = { ...prev };
+      delete next[slot];
+      return next;
+    });
+  }, []);
+  const clearAllSlots = useCallback(() => {
+    setSlots({});
+  }, []);
+  const actionsRef = useRef({ setSlotPatterns, clearSlot, clearAllSlots });
+  actionsRef.current = { setSlotPatterns, clearSlot, clearAllSlots };
+  const [stableActions] = useState(() => ({
+    setSlotPatterns: (...args) => actionsRef.current.setSlotPatterns(...args),
+    clearSlot: (...args) => actionsRef.current.clearSlot(...args),
+    clearAllSlots: () => actionsRef.current.clearAllSlots()
+  }));
+  return /* @__PURE__ */ jsx(SlotsActionsContext.Provider, { value: stableActions, children: /* @__PURE__ */ jsx(SlotsStateContext.Provider, { value: slots, children }) });
+}
+function useSlots() {
+  return useContext(SlotsStateContext);
+}
+function useSlotContent(slotName) {
+  const slots = useContext(SlotsStateContext);
+  return slots[slotName] || null;
+}
+function useSlotsActions() {
+  const actions = useContext(SlotsActionsContext);
+  if (!actions) {
+    throw new Error("useSlotsActions must be used within a SlotsProvider");
+  }
+  return actions;
+}
+
+export { EntitySchemaProvider, SlotsProvider, TraitContext, TraitProvider, clearSchemaCache, createClientEffectHandlers, useEntityDefinition, useEntitySchema, useResolvedSchema, useSlotContent, useSlots, useSlotsActions, useTrait, useTraitContext, useTraitStateMachine };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@almadar/ui",
-  "version": "2.8.1",
+  "version": "2.9.1",
   "description": "React UI components, hooks, and providers for Almadar",
   "type": "module",
   "main": "./dist/components/index.js",
@@ -31,6 +31,10 @@
       "import": "./dist/renderer/index.js",
       "types": "./dist/renderer/index.d.ts"
     },
+    "./runtime": {
+      "import": "./dist/runtime/index.js",
+      "types": "./dist/runtime/index.d.ts"
+    },
     "./stores": {
       "import": "./dist/stores/index.js",
       "types": "./dist/stores/index.d.ts"
@@ -73,6 +77,7 @@
     "@almadar/core": ">=2.1.0",
     "@almadar/evaluator": ">=2.0.0",
     "@almadar/patterns": ">=2.0.0",
+    "@almadar/runtime": ">=2.0.0",
     "clsx": "^2.1.0",
     "leaflet": "1.9.4",
     "lucide-react": "^0.344.0",

package/dist/{chunk-2QM732NQ.js → chunk-GTIAVPI5.js}

@@ -1,7 +1,7 @@
+import { subscribe, getSnapshot, clearEntities, removeEntity, updateSingleton, updateEntity, spawnEntity, getSingleton, getAllEntities, getByType, getEntity } from './chunk-N7MVUW4R.js';
 import { apiClient } from './chunk-3HJHHULT.js';
 import { SelectionContext, entityDataKeys, useEntityList } from './chunk-WGJIL4YR.js';
 import { useEventBus } from './chunk-YXZM3WCF.js';
-import { subscribe, getSnapshot, clearEntities, removeEntity, updateSingleton, updateEntity, spawnEntity, getSingleton, getAllEntities, getByType, getEntity } from './chunk-N7MVUW4R.js';
 import { useCallback, useState, useEffect, useMemo, useContext, useSyncExternalStore, useRef } from 'react';
 import { useQueryClient, useMutation, useQuery } from '@tanstack/react-query';