@almadar/ui 3.3.1 → 3.5.0

package/dist/avl/index.cjs

@@ -2956,9 +2956,6 @@ function EventBusProvider({ children, debug: debug2 = false }) {
   const emit = React126.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
@@ -3131,9 +3128,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
@@ -19039,7 +19033,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);
@@ -21723,7 +21721,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;
         });
@@ -21734,7 +21733,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;
         });
@@ -21746,7 +21746,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 ? {
@@ -22074,7 +22078,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..." }) });
@@ -30458,7 +30466,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();
@@ -31900,9 +31909,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 = () => {
@@ -33270,6 +33280,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"))
@@ -33473,18 +33508,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 });
               }
             }
           }));
@@ -33564,7 +33598,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")
@@ -39418,16 +39452,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);
         }) })

package/dist/avl/index.js

@@ -2910,9 +2910,6 @@ function EventBusProvider({ children, debug: debug2 = false }) {
   const emit = 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
@@ -3085,9 +3082,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
@@ -18993,7 +18987,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);
@@ -21677,7 +21675,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;
         });
@@ -21688,7 +21687,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;
         });
@@ -21700,7 +21700,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 ? {
@@ -22028,7 +22032,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__ */ jsx(Box, { className: "text-center py-8", children: /* @__PURE__ */ jsx(Typography, { variant: "body", color: "secondary", children: t("loading.items") || "Loading..." }) });
@@ -30412,7 +30420,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();
@@ -31854,9 +31863,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 = () => {
@@ -33224,6 +33234,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"))
@@ -33427,18 +33462,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 });
               }
             }
           }));
@@ -33518,7 +33552,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")
@@ -39372,16 +39406,19 @@ var init_Timeline = __esm({
               ] }),
               item.description && /* @__PURE__ */ jsx(Typography, { variant: "small", color: "secondary", children: item.description }),
               item.tags && item.tags.length > 0 && /* @__PURE__ */ jsx(HStack, { gap: "xs", wrap: true, children: item.tags.map((tag, tagIdx) => /* @__PURE__ */ jsx(Badge, { variant: "default", children: tag }, tagIdx)) }),
-              itemActions && itemActions.length > 0 && /* @__PURE__ */ jsx(HStack, { gap: "xs", className: "mt-1", children: itemActions.map((action, actionIdx) => /* @__PURE__ */ jsx(
-                Box,
-                {
-                  action: action.event,
-                  actionPayload: { row: item },
-                  className: "cursor-pointer hover:opacity-80 transition-opacity",
-                  children: /* @__PURE__ */ jsx(Badge, { variant: "default", children: action.label })
-                },
-                actionIdx
-              )) })
+              itemActions && itemActions.length > 0 && /* @__PURE__ */ jsx(HStack, { gap: "xs", className: "mt-1", children: itemActions.map((action, actionIdx) => {
+                const { icon: _icon, ...rowSafe } = item;
+                return /* @__PURE__ */ jsx(
+                  Box,
+                  {
+                    action: action.event,
+                    actionPayload: { row: rowSafe },
+                    className: "cursor-pointer hover:opacity-80 transition-opacity",
+                    children: /* @__PURE__ */ jsx(Badge, { variant: "default", children: action.label })
+                  },
+                  actionIdx
+                );
+              }) })
             ] })
           ] }, item.id);
         }) })

package/dist/components/atoms/Avatar.d.ts

@@ -4,6 +4,7 @@
  * A versatile avatar component supporting images, initials, icons, and status indicators.
  */
 import React from "react";
+import type { EventKey, EventPayload } from "@almadar/core";
 import type { LucideIcon } from "lucide-react";
 export type AvatarSize = "xs" | "sm" | "md" | "lg" | "xl";
 export type AvatarStatus = "online" | "offline" | "away" | "busy";
@@ -51,8 +52,8 @@ export interface AvatarProps {
      */
     onClick?: () => void;
     /** Declarative event name — emits UI:{action} via eventBus on click */
-    action?: string;
+    action?: EventKey;
     /** Payload to include with the action event */
-    actionPayload?: Record<string, unknown>;
+    actionPayload?: EventPayload;
 }
 export declare const Avatar: React.FC<AvatarProps>;

package/dist/components/atoms/Box.d.ts

@@ -5,6 +5,7 @@
  * Think of it as a styled div with consistent design tokens.
  */
 import React from "react";
+import type { EventKey, EventPayload } from "@almadar/core";
 export type BoxPadding = "none" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl";
 export type BoxMargin = "none" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | "auto";
 export type BoxBg = "transparent" | "primary" | "secondary" | "muted" | "accent" | "surface" | "overlay";
@@ -44,11 +45,11 @@ export interface BoxProps extends React.HTMLAttributes<HTMLDivElement> {
     /** HTML element to render as */
     as?: React.ElementType;
     /** Declarative event name — emits UI:{action} via eventBus on click */
-    action?: string;
+    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 */

package/dist/components/atoms/Button.d.ts

@@ -1,4 +1,5 @@
 import React from "react";
+import type { EventKey, EventPayload } from "@almadar/core";
 import { type LucideIcon } from "lucide-react";
 export type ButtonVariant = "primary" | "secondary" | "ghost" | "danger" | "success" | "warning" | "default";
 export type ButtonSize = "sm" | "md" | "lg";
@@ -15,9 +16,9 @@ export interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElemen
     /** Alias for rightIcon */
     iconRight?: React.ReactNode | LucideIcon | string;
     /** Declarative event name — emits UI:{action} via eventBus on click */
-    action?: string;
+    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/components/atoms/InfiniteScrollSentinel.d.ts

@@ -6,11 +6,12 @@
  * then fires a load-more event through the event bus.
  */
 import React from "react";
+import type { EventKey, EventPayload } from "@almadar/core";
 export interface InfiniteScrollSentinelProps {
     /** Event name to emit when load-more is triggered (emitted as UI:{loadMoreEvent}) */
-    loadMoreEvent: string;
+    loadMoreEvent: EventKey;
     /** Optional payload to include with the load-more event */
-    loadMorePayload?: Record<string, unknown>;
+    loadMorePayload?: EventPayload;
     /** Whether a load operation is currently in progress */
     isLoading?: boolean;
     /** Whether there are more items to load */

package/dist/components/atoms/Input.d.ts

@@ -1,4 +1,5 @@
 import React from "react";
+import type { EventKey } from "@almadar/core";
 import { type LucideIcon } from "lucide-react";
 export interface SelectOption {
     value: string;
@@ -12,7 +13,7 @@ export interface InputProps extends Omit<React.InputHTMLAttributes<HTMLInputElem
     /** Whether input is disabled */
     disabled?: boolean;
     /** Declarative event name for trait dispatch */
-    action?: string;
+    action?: EventKey;
     /** Input type - supports 'select' and 'textarea' in addition to standard types */
     inputType?: "text" | "email" | "password" | "number" | "tel" | "url" | "search" | "date" | "datetime-local" | "time" | "checkbox" | "select" | "textarea";
     error?: string;
@@ -31,4 +32,4 @@ export interface InputProps extends Omit<React.InputHTMLAttributes<HTMLInputElem
     /** onChange handler - accepts events from input, select, or textarea */
     onChange?: React.ChangeEventHandler<HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement>;
 }
-export declare const Input: React.ForwardRefExoticComponent<InputProps & React.RefAttributes<HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement>>;
+export declare const Input: React.ForwardRefExoticComponent<InputProps & React.RefAttributes<HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement>>;

package/dist/components/atoms/Overlay.d.ts

@@ -4,13 +4,14 @@
  * A fixed backdrop for modals and drawers.
  */
 import React from "react";
+import type { EventKey } from "@almadar/core";
 export interface OverlayProps {
     isVisible?: boolean;
     onClick?: (e: React.MouseEvent) => void;
     className?: string;
     blur?: boolean;
     /** Declarative event name — emits UI:{action} via eventBus on click */
-    action?: string;
+    action?: EventKey;
 }
 export declare const Overlay: React.FC<OverlayProps>;
 export default Overlay;

package/dist/components/atoms/Radio.d.ts

@@ -4,13 +4,14 @@
  * A radio button component with label support and accessibility.
  */
 import React from "react";
+import type { EventKey } from "@almadar/core";
 export interface RadioProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, "type" | "size"> {
     /** Radio options (string array or SelectOption array) */
     options?: string[];
     /** Current selected value */
     value?: string;
     /** Declarative event name for trait dispatch */
-    action?: string;
+    action?: EventKey;
     /**
      * Label text displayed next to the radio button
      */

package/dist/components/atoms/RangeSlider.d.ts

@@ -1,4 +1,5 @@
 import React from "react";
+import type { EventKey, EventPayload } from "@almadar/core";
 export type RangeSliderSize = "sm" | "md" | "lg";
 export interface RangeSliderProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "onChange"> {
     /** Minimum value */
@@ -20,9 +21,9 @@ export interface RangeSliderProps extends Omit<React.HTMLAttributes<HTMLDivEleme
     /** Disabled state */
     disabled?: boolean;
     /** Declarative event name for value changes */
-    action?: string;
+    action?: EventKey;
     /** Payload to include with the action event */
-    actionPayload?: Record<string, unknown>;
+    actionPayload?: EventPayload;
     /** Direct onChange callback */
     onChange?: (value: number) => void;
     /** Format function for tooltip display */

package/dist/components/atoms/Select.d.ts

@@ -1,4 +1,5 @@
 import React from "react";
+import type { EventKey } from "@almadar/core";
 export interface SelectOption {
     value: string;
     label: string;
@@ -12,7 +13,7 @@ export interface SelectProps extends Omit<React.SelectHTMLAttributes<HTMLSelectE
     /** Current value */
     value?: string;
     /** Declarative event name for trait dispatch */
-    action?: string;
+    action?: EventKey;
     /** Error message */
     error?: string;
 }

package/dist/components/atoms/Stack.d.ts

@@ -5,6 +5,7 @@
  * Includes convenience exports VStack and HStack for common use cases.
  */
 import React from "react";
+import type { EventKey, EventPayload } from "@almadar/core";
 export type StackDirection = "horizontal" | "vertical";
 export type StackGap = "none" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl";
 export type StackAlign = "start" | "center" | "end" | "stretch" | "baseline";
@@ -41,9 +42,9 @@ export interface StackProps {
     /** Tab index for focus management */
     tabIndex?: number;
     /** Declarative event name — emits UI:{action} via eventBus on click */
-    action?: string;
+    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;
 }

package/dist/components/atoms/TextHighlight.d.ts

@@ -7,6 +7,7 @@
  * - Notes: Yellow highlight
  */
 import React from "react";
+import type { EventKey } from "@almadar/core";
 export type HighlightType = "question" | "note";
 export interface TextHighlightProps {
     /**
@@ -43,9 +44,9 @@ export interface TextHighlightProps {
      */
     children: React.ReactNode;
     /** Declarative event name — emits UI:{action} via eventBus on click */
-    action?: string;
+    action?: EventKey;
     /** Declarative hover event — emits UI:{hoverEvent} with { hovered: true/false } */
-    hoverEvent?: string;
+    hoverEvent?: EventKey;
 }
 /**
  * TextHighlight component for rendering highlighted text annotations

package/dist/components/atoms/Textarea.d.ts

@@ -1,11 +1,12 @@
 import React from "react";
+import type { EventKey } from "@almadar/core";
 export interface TextareaProps extends React.TextareaHTMLAttributes<HTMLTextAreaElement> {
     /** Placeholder text */
     placeholder?: string;
     /** Number of visible rows */
     rows?: number;
     /** Declarative event name for trait dispatch */
-    action?: string;
+    action?: EventKey;
     /** Error message */
     error?: string;
 }

package/dist/components/atoms/game/ControlButton.d.ts

@@ -1,4 +1,5 @@
 import * as React from 'react';
+import type { EventKey } from "@almadar/core";
 export interface ControlButtonProps {
     /** Button label text */
     label?: string;
@@ -15,9 +16,9 @@ export interface ControlButtonProps {
     /** Called when button is released */
     onRelease?: () => void;
     /** Declarative event name emitted on press via useEventBus */
-    pressEvent?: string;
+    pressEvent?: EventKey;
     /** Declarative event name emitted on release via useEventBus */
-    releaseEvent?: string;
+    releaseEvent?: EventKey;
     /** Whether the button is currently pressed */
     pressed?: boolean;
     /** Whether the button is disabled */

package/dist/components/atoms/game/Sprite.d.ts

@@ -4,6 +4,7 @@
  * Renders a single frame from a spritesheet with transform support.
  */
 import React from 'react';
+import type { EventKey } from "@almadar/core";
 export interface SpriteProps {
     /** Spritesheet image URL */
     spritesheet: string;
@@ -36,7 +37,7 @@ export interface SpriteProps {
     /** Optional onClick handler */
     onClick?: () => void;
     /** Declarative event name emitted on click via useEventBus */
-    action?: string;
+    action?: EventKey;
 }
 /**
  * Sprite component for rendering spritesheet frames