@almadar/ui 3.4.0 → 3.5.0

package/dist/components/molecules/game/InventoryPanel.d.ts

@@ -11,14 +11,15 @@
  * Local state is hover/tooltip only — rendering-only concerns.
  */
 import React from 'react';
-export interface InventoryItem {
+import type { EventPayload } from "@almadar/core";
+export type InventoryItem = EventPayload & {
     id: string;
     type: string;
     quantity: number;
     sprite?: string;
     name?: string;
     description?: string;
-}
+};
 export interface InventoryPanelProps {
     /** Array of items in inventory */
     items: InventoryItem[];

package/dist/components/organisms/CustomPattern.d.ts

@@ -8,7 +8,7 @@
  * @packageDocumentation
  */
 import React from "react";
-import type { EventKey } from "@almadar/core";
+import type { EventKey, EventPayload } from "@almadar/core";
 /**
  * Allowed element types for custom patterns.
  */
@@ -34,7 +34,7 @@ export interface CustomPatternProps {
     /** Event to emit on click (REQUIRED for interactive elements) */
     action?: EventKey;
     /** Event payload */
-    payload?: Record<string, unknown>;
+    payload?: EventPayload;
     /** Nested children patterns */
     children?: React.ReactNode;
     /** Image source (for img elements) */
@@ -83,7 +83,7 @@ export interface CustomPatternConfig {
     token?: string | string[];
     content?: string;
     action?: EventKey;
-    payload?: Record<string, unknown>;
+    payload?: EventPayload;
     children?: CustomPatternConfig[];
     src?: string;
     alt?: string;

package/dist/components/organisms/GraphCanvas.d.ts

@@ -11,7 +11,8 @@
  * - className for external styling
  */
 import React from "react";
-export interface GraphNode {
+import type { EventPayload } from "@almadar/core";
+export type GraphNode = EventPayload & {
     id: string;
     label?: string;
     group?: string;
@@ -20,7 +21,7 @@ export interface GraphNode {
     /** Position (optional, computed if missing) */
     x?: number;
     y?: number;
-}
+};
 export interface GraphEdge {
     source: string;
     target: string;

package/dist/components/organisms/game/three/index.cjs

@@ -1439,9 +1439,6 @@ var fallbackEventBus = {
   emit: (type, payload, source) => {
     const event = {
       type,
-      // Narrow at the bus boundary: public emit accepts an opaque object so
-      // generic UI emit sites don't require casts; the envelope stores the
-      // payload as EventPayload which listeners consume directly.
       payload,
       timestamp: Date.now(),
       source

package/dist/components/organisms/game/three/index.js

@@ -1415,9 +1415,6 @@ var fallbackEventBus = {
   emit: (type, payload, source) => {
     const event = {
       type,
-      // Narrow at the bus boundary: public emit accepts an opaque object so
-      // generic UI emit sites don't require casts; the envelope stores the
-      // payload as EventPayload which listeners consume directly.
       payload,
       timestamp: Date.now(),
       source

package/dist/docs/index.cjs

@@ -2573,9 +2573,6 @@ var fallbackEventBus = {
   emit: (type, payload, source) => {
     const event = {
       type,
-      // Narrow at the bus boundary: public emit accepts an opaque object so
-      // generic UI emit sites don't require casts; the envelope stores the
-      // payload as EventPayload which listeners consume directly.
       payload,
       timestamp: Date.now(),
       source

package/dist/docs/index.d.cts

@@ -1,5 +1,5 @@
 import React from 'react';
-import { EventKey } from '@almadar/core';
+import { EventKey, EventPayload } from '@almadar/core';
 import { LucideIcon } from 'lucide-react';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 
@@ -51,9 +51,9 @@ interface BoxProps extends React.HTMLAttributes<HTMLDivElement> {
     /** Declarative event name — emits UI:{action} via eventBus on click */
     action?: EventKey;
     /** Payload to include with the action event */
-    actionPayload?: Record<string, unknown>;
+    actionPayload?: EventPayload;
     /** Declarative hover event — emits UI:{hoverEvent} with { hovered: true/false } on mouseEnter/mouseLeave */
-    hoverEvent?: string;
+    hoverEvent?: EventKey;
     /** Maximum width (CSS value, e.g., "550px", "80rem") */
     maxWidth?: string;
     /** Children elements */
@@ -109,7 +109,7 @@ interface StackProps {
     /** Declarative event name — emits UI:{action} via eventBus on click */
     action?: EventKey;
     /** Payload to include with the action event */
-    actionPayload?: Record<string, unknown>;
+    actionPayload?: EventPayload;
     /** When true, horizontal stacks flip to vertical below the md breakpoint (768px) */
     responsive?: boolean;
 }
@@ -183,7 +183,7 @@ interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
     /** Declarative event name — emits UI:{action} via eventBus on click */
     action?: EventKey;
     /** Payload to include with the action event */
-    actionPayload?: Record<string, unknown>;
+    actionPayload?: EventPayload;
     /** Button label text (alternative to children for schema-driven rendering) */
     label?: string;
 }

package/dist/docs/index.js

@@ -2549,9 +2549,6 @@ var fallbackEventBus = {
   emit: (type, payload, source) => {
     const event = {
       type,
-      // Narrow at the bus boundary: public emit accepts an opaque object so
-      // generic UI emit sites don't require casts; the envelope stores the
-      // payload as EventPayload which listeners consume directly.
       payload,
       timestamp: Date.now(),
       source

package/dist/hooks/event-bus-types.d.ts

@@ -7,28 +7,28 @@
  *
  * @packageDocumentation
  */
-import type { BusEvent, BusEventSource, BusEventListener, Unsubscribe } from "@almadar/core";
-export type { BusEvent, BusEventSource, Unsubscribe };
+import type { BusEvent, BusEventSource, BusEventListener, EventPayload, Unsubscribe } from "@almadar/core";
+export type { BusEvent, BusEventSource, EventPayload, Unsubscribe };
 export type EventListener = BusEventListener;
 /**
  * Event bus context type.
  *
- * `emit` accepts `Record<string, unknown>` on its public surface so
- * generic UI components (DataGrid, SortableList, ...) can pass
- * consumer-defined row data without a cast at every emit site. The
- * envelope stored in `BusEvent.payload` is narrowed to `EventPayload`
- * inside the bus implementation — listeners always receive the typed
- * shape.
+ * `emit` accepts `EventPayload` from `@almadar/core` — the canonical
+ * object shape (index signature over `EventPayloadValue`) that the bus
+ * envelope stores and listeners consume. Pattern-specific payload types
+ * from `@almadar/patterns` (`ItemActionPayload`, `SelectionChangePayload`,
+ * `FormSubmitPayload`, ...) are structural subtypes of `EventPayload`,
+ * so components can pass them in without casts.
  */
 export interface EventBusContextType {
     /**
      * Emit an event to all listeners.
      *
      * @param type - Event type identifier
-     * @param payload - Optional payload data (object-shaped)
+     * @param payload - Optional payload data (shape matches {@link EventPayload})
      * @param source - Optional origin info (orbital/trait/...)
      */
-    emit: (type: string, payload?: Record<string, unknown>, source?: BusEventSource) => void;
+    emit: (type: string, payload?: EventPayload, source?: BusEventSource) => void;
     /**
      * Subscribe to an event type.
      *

package/dist/hooks/index.cjs

@@ -938,9 +938,6 @@ var fallbackEventBus = {
   emit: (type, payload, source) => {
     const event = {
       type,
-      // Narrow at the bus boundary: public emit accepts an opaque object so
-      // generic UI emit sites don't require casts; the envelope stores the
-      // payload as EventPayload which listeners consume directly.
       payload,
       timestamp: Date.now(),
       source

package/dist/hooks/index.js

@@ -932,9 +932,6 @@ var fallbackEventBus = {
   emit: (type, payload, source) => {
     const event = {
       type,
-      // Narrow at the bus boundary: public emit accepts an opaque object so
-      // generic UI emit sites don't require casts; the envelope stores the
-      // payload as EventPayload which listeners consume directly.
       payload,
       timestamp: Date.now(),
       source

package/dist/hooks/useDraggable.d.ts

@@ -1,7 +1,8 @@
+import type { EventPayload } from '@almadar/core';
 /** Discriminated payload carried by every drag operation. */
 export interface DraggablePayload {
     kind: 'pattern' | 'behavior' | 'tree-node' | 'event-wire';
-    data: Record<string, unknown>;
+    data: EventPayload;
 }
 export interface UseDraggableOptions {
     /** The payload that will be serialised into dataTransfer. */

package/dist/hooks/useEventBus.d.ts

@@ -1,4 +1,5 @@
 import type { BusEvent, BusEventSource, EventListener, Unsubscribe, EventBusContextType } from './event-bus-types';
+import type { EventPayload } from '@almadar/core';
 export type { BusEvent, BusEventSource, EventListener, Unsubscribe, EventBusContextType };
 declare global {
     interface Window {
@@ -92,5 +93,5 @@ export declare const useEventSubscription: typeof useEventListener;
  * };
  * ```
  */
-export declare function useEmitEvent(): (type: string, payload?: Record<string, unknown>, source?: BusEventSource) => void;
+export declare function useEmitEvent(): (type: string, payload?: EventPayload, source?: BusEventSource) => void;
 export default useEventBus;

package/dist/lib/verificationRegistry.d.ts

@@ -9,7 +9,7 @@
  *
  * @packageDocumentation
  */
-import type { AssetLoadStatus, BridgeHealth, BusEvent, CheckStatus, EffectTrace, EventLogEntry, OrbitalVerificationAPI, ServerResponseTrace, TraitStateSnapshot, TransitionTrace, VerificationCheck, VerificationSnapshot, VerificationSummary } from '@almadar/core';
+import type { AssetLoadStatus, BridgeHealth, BusEvent, CheckStatus, EffectTrace, EventLogEntry, EventPayload, OrbitalVerificationAPI, ServerResponseTrace, TraitStateSnapshot, TransitionTrace, VerificationCheck, VerificationSnapshot, VerificationSummary } from '@almadar/core';
 export type { AssetLoadStatus, BridgeHealth, CheckStatus, EffectTrace, EventLogEntry, OrbitalVerificationAPI, ServerResponseTrace, TraitStateSnapshot, TransitionTrace, VerificationCheck, VerificationSnapshot, VerificationSummary, };
 type ChangeListener = () => void;
 /**
@@ -59,7 +59,7 @@ export declare function waitForTransition(event: string, timeoutMs?: number): Pr
  * Call this during app initialization.
  */
 export declare function bindEventBus(eventBus: {
-    emit: (type: string, payload?: Record<string, unknown>) => void;
+    emit: (type: string, payload?: EventPayload) => void;
     onAny?: (listener: (event: BusEvent) => void) => () => void;
 }): void;
 /**

package/dist/marketing/index.cjs

@@ -2573,9 +2573,6 @@ var fallbackEventBus = {
   emit: (type, payload, source) => {
     const event = {
       type,
-      // Narrow at the bus boundary: public emit accepts an opaque object so
-      // generic UI emit sites don't require casts; the envelope stores the
-      // payload as EventPayload which listeners consume directly.
       payload,
       timestamp: Date.now(),
       source

package/dist/marketing/index.d.cts

@@ -1,5 +1,5 @@
 import React from 'react';
-import { EventKey } from '@almadar/core';
+import { EventKey, EventPayload } from '@almadar/core';
 import { LucideIcon } from 'lucide-react';
 
 /**
@@ -50,9 +50,9 @@ interface BoxProps extends React.HTMLAttributes<HTMLDivElement> {
     /** Declarative event name — emits UI:{action} via eventBus on click */
     action?: EventKey;
     /** Payload to include with the action event */
-    actionPayload?: Record<string, unknown>;
+    actionPayload?: EventPayload;
     /** Declarative hover event — emits UI:{hoverEvent} with { hovered: true/false } on mouseEnter/mouseLeave */
-    hoverEvent?: string;
+    hoverEvent?: EventKey;
     /** Maximum width (CSS value, e.g., "550px", "80rem") */
     maxWidth?: string;
     /** Children elements */
@@ -108,7 +108,7 @@ interface StackProps {
     /** Declarative event name — emits UI:{action} via eventBus on click */
     action?: EventKey;
     /** Payload to include with the action event */
-    actionPayload?: Record<string, unknown>;
+    actionPayload?: EventPayload;
     /** When true, horizontal stacks flip to vertical below the md breakpoint (768px) */
     responsive?: boolean;
 }
@@ -182,7 +182,7 @@ interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
     /** Declarative event name — emits UI:{action} via eventBus on click */
     action?: EventKey;
     /** Payload to include with the action event */
-    actionPayload?: Record<string, unknown>;
+    actionPayload?: EventPayload;
     /** Button label text (alternative to children for schema-driven rendering) */
     label?: string;
 }

package/dist/marketing/index.js

@@ -2549,9 +2549,6 @@ var fallbackEventBus = {
   emit: (type, payload, source) => {
     const event = {
       type,
-      // Narrow at the bus boundary: public emit accepts an opaque object so
-      // generic UI emit sites don't require casts; the envelope stores the
-      // payload as EventPayload which listeners consume directly.
       payload,
       timestamp: Date.now(),
       source

package/dist/providers/index.cjs

@@ -474,9 +474,6 @@ var init_useEventBus = __esm({
       emit: (type, payload, source) => {
         const event = {
           type,
-          // Narrow at the bus boundary: public emit accepts an opaque object so
-          // generic UI emit sites don't require casts; the envelope stores the
-          // payload as EventPayload which listeners consume directly.
           payload,
           timestamp: Date.now(),
           source
@@ -15994,7 +15991,11 @@ var init_CardGrid = __esm({
           return;
         }
         if (action.event) {
-          eventBus.emit(`UI:${action.event}`, { id: itemData.id, row: itemData });
+          const payload = {
+            id: itemData.id,
+            row: itemData
+          };
+          eventBus.emit(`UI:${action.event}`, payload);
         }
         if (action.onClick) {
           action.onClick(itemData);
@@ -18678,7 +18679,8 @@ var init_DataGrid = __esm({
           if (next.has(id)) next.delete(id);
           else next.add(id);
           if (selectionEvent) {
-            eventBus.emit(`UI:${selectionEvent}`, { selectedIds: Array.from(next) });
+            const payload = { selectedIds: Array.from(next) };
+            eventBus.emit(`UI:${selectionEvent}`, payload);
           }
           return next;
         });
@@ -18689,7 +18691,8 @@ var init_DataGrid = __esm({
           const allSelected2 = allIds2.length > 0 && allIds2.every((id) => prev.has(id));
           const next = allSelected2 ? /* @__PURE__ */ new Set() : new Set(allIds2);
           if (selectionEvent) {
-            eventBus.emit(`UI:${selectionEvent}`, { selectedIds: Array.from(next) });
+            const payload = { selectedIds: Array.from(next) };
+            eventBus.emit(`UI:${selectionEvent}`, payload);
           }
           return next;
         });
@@ -18701,7 +18704,11 @@ var init_DataGrid = __esm({
       const dangerActions = itemActions?.filter((a) => a.variant === "danger") ?? [];
       const handleActionClick = (action, itemData) => (e) => {
         e.stopPropagation();
-        eventBus.emit(`UI:${action.event}`, { id: itemData.id, row: itemData });
+        const payload = {
+          id: itemData.id,
+          row: itemData
+        };
+        eventBus.emit(`UI:${action.event}`, payload);
       };
       const gridTemplateColumns = cols ? void 0 : `repeat(auto-fit, minmax(min(${minCardWidth}px, 100%), 1fr))`;
       const colsClass = cols ? {
@@ -19029,7 +19036,11 @@ var init_DataList = __esm({
       );
       const handleActionClick = (action, itemData) => (e) => {
         e.stopPropagation();
-        eventBus.emit(`UI:${action.event}`, { id: itemData.id, row: itemData });
+        const payload = {
+          id: itemData.id,
+          row: itemData
+        };
+        eventBus.emit(`UI:${action.event}`, payload);
       };
       if (isLoading) {
         return /* @__PURE__ */ jsxRuntime.jsx(Box, { className: "text-center py-8", children: /* @__PURE__ */ jsxRuntime.jsx(Typography, { variant: "body", color: "secondary", children: t("loading.items") || "Loading..." }) });
@@ -27413,7 +27424,8 @@ var init_DetailPanel = __esm({
             return;
           }
           if (action.event) {
-            eventBus.emit(`UI:${action.event}`, { id: data2?.id, row: data2 });
+            const payload = data2 ? { id: data2.id, row: data2 } : {};
+            eventBus.emit(`UI:${action.event}`, payload);
           }
           if (action.onClick) {
             action.onClick();
@@ -28855,9 +28867,10 @@ var init_Form = __esm({
       };
       const handleSubmit = (e) => {
         e.preventDefault();
-        eventBus.emit(`UI:${submitEvent}`, { data: formData });
+        const payload = { data: formData };
+        eventBus.emit(`UI:${submitEvent}`, payload);
         if (onSubmit) {
-          eventBus.emit(`UI:${onSubmit}`, { data: formData });
+          eventBus.emit(`UI:${onSubmit}`, payload);
         }
       };
       const handleCancel = () => {
@@ -30225,6 +30238,31 @@ function normalizeFields2(fields) {
   if (!fields) return [];
   return fields.map((f3) => typeof f3 === "string" ? f3 : f3.key ?? f3.name ?? "");
 }
+function entityFieldsFromListItem(item) {
+  const {
+    icon: _icon,
+    metadata: _metadata,
+    onClick: _onClick,
+    avatar: _avatar,
+    _fields,
+    ...rest
+  } = item;
+  const result = {};
+  for (const [key, value] of Object.entries(rest)) {
+    if (typeof value === "function" || value !== null && typeof value === "object" && "$$typeof" in value) {
+      continue;
+    }
+    result[key] = value;
+  }
+  if (_fields && typeof _fields === "object") {
+    for (const [k, v] of Object.entries(_fields)) {
+      if (typeof v !== "function") {
+        result[k] = v;
+      }
+    }
+  }
+  return result;
+}
 function getStatusStyle(fieldName, value) {
   const val = String(value).toLowerCase();
   if (val.includes("complete") || val.includes("done"))
@@ -30428,18 +30466,17 @@ var init_List = __esm({
             label: action.label,
             event: action.event,
             onClick: () => {
+              const row = entityFieldsFromListItem(item);
               if (action.navigatesTo) {
                 const url = action.navigatesTo.replace(
                   /\{\{(\w+)\}\}/g,
-                  (_, key) => String(item[key] || item.id || "")
+                  (_, key) => String(row[key] ?? item.id ?? "")
                 );
-                eventBus.emit("UI:NAVIGATE", { url, row: item });
+                eventBus.emit("UI:NAVIGATE", { url, row });
                 return;
               }
               if (action.event) {
-                eventBus.emit(`UI:${action.event}`, {
-                  row: item
-                });
+                eventBus.emit(`UI:${action.event}`, { row });
               }
             }
           }));
@@ -30519,7 +30556,7 @@ var init_List = __esm({
         );
         const hasExplicitClick = !!(viewAction?.event || item.onClick);
         const rowAction = viewAction?.event ?? "VIEW";
-        const rowActionPayload = { row: item };
+        const rowActionPayload = { row: entityFieldsFromListItem(item) };
         const primaryField = effectiveFieldNames?.[0];
         const statusField = effectiveFieldNames?.find(
           (f3) => f3.toLowerCase().includes("status")
@@ -36354,16 +36391,19 @@ var init_Timeline = __esm({
               ] }),
               item.description && /* @__PURE__ */ jsxRuntime.jsx(Typography, { variant: "small", color: "secondary", children: item.description }),
               item.tags && item.tags.length > 0 && /* @__PURE__ */ jsxRuntime.jsx(HStack, { gap: "xs", wrap: true, children: item.tags.map((tag, tagIdx) => /* @__PURE__ */ jsxRuntime.jsx(Badge, { variant: "default", children: tag }, tagIdx)) }),
-              itemActions && itemActions.length > 0 && /* @__PURE__ */ jsxRuntime.jsx(HStack, { gap: "xs", className: "mt-1", children: itemActions.map((action, actionIdx) => /* @__PURE__ */ jsxRuntime.jsx(
-                Box,
-                {
-                  action: action.event,
-                  actionPayload: { row: item },
-                  className: "cursor-pointer hover:opacity-80 transition-opacity",
-                  children: /* @__PURE__ */ jsxRuntime.jsx(Badge, { variant: "default", children: action.label })
-                },
-                actionIdx
-              )) })
+              itemActions && itemActions.length > 0 && /* @__PURE__ */ jsxRuntime.jsx(HStack, { gap: "xs", className: "mt-1", children: itemActions.map((action, actionIdx) => {
+                const { icon: _icon, ...rowSafe } = item;
+                return /* @__PURE__ */ jsxRuntime.jsx(
+                  Box,
+                  {
+                    action: action.event,
+                    actionPayload: { row: rowSafe },
+                    className: "cursor-pointer hover:opacity-80 transition-opacity",
+                    children: /* @__PURE__ */ jsxRuntime.jsx(Badge, { variant: "default", children: action.label })
+                  },
+                  actionIdx
+                );
+              }) })
             ] })
           ] }, item.id);
         }) })
@@ -38258,9 +38298,6 @@ function EventBusProvider({ children, debug: debug2 = false }) {
   const emit = React115.useCallback((type, payload, source) => {
     const event = {
       type,
-      // Narrow at the bus boundary: public emit takes Record for ergonomics
-      // (generic UI components pass consumer-defined rows) while the envelope
-      // stores the payload as EventPayload for listeners.
       payload,
       timestamp: Date.now(),
       source