@almadar/ui 3.3.1 → 3.5.0

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

@@ -1,5 +1,6 @@
+import type { EventKey, EventPayload } from "@almadar/core";
 import { type EventBusContextType } from "../../../hooks/useEventBus";
-export interface MenuOption {
+export type MenuOption = EventPayload & {
     /** Optional ID (generated from index if not provided) */
     id?: string;
     /** Display label */
@@ -15,8 +16,8 @@ export interface MenuOption {
     /** Sub-label or description */
     subLabel?: string;
     /** Action identifier (alternative to event) */
-    action?: string;
-}
+    action?: EventKey;
+};
 export interface GameMenuProps {
     /** Menu title */
     title: string;

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

@@ -1,4 +1,5 @@
 import * as React from "react";
+import type { EventPayload } from "@almadar/core";
 import { type EventBusContextType } from "../../../hooks/useEventBus";
 export interface GameOverStat {
     /** Stat label */
@@ -16,7 +17,7 @@ export interface GameOverStat {
     /** Icon */
     icon?: React.ReactNode;
 }
-export interface GameOverAction {
+export type GameOverAction = EventPayload & {
     /** Display label */
     label: string;
     /** Event to emit on click */
@@ -25,7 +26,7 @@ export interface GameOverAction {
     navigatesTo?: string;
     /** Button variant */
     variant?: "primary" | "secondary" | "ghost";
-}
+};
 export interface GameOverScreenProps {
     /** Screen title (e.g., "Game Over", "Victory!") */
     title: string;

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/CardGrid.d.ts

@@ -9,6 +9,7 @@
  * for pagination, filtering, or search. All state is owned by the trait state machine.
  */
 import React from 'react';
+import type { EventKey } from "@almadar/core";
 import type { EntityDisplayProps } from './types';
 export type CardGridGap = 'none' | 'sm' | 'md' | 'lg' | 'xl';
 /**
@@ -18,13 +19,13 @@ export interface CardItemAction {
     /** Action button label */
     label: string;
     /** Event to dispatch on click (schema metadata) */
-    event?: string;
+    event?: EventKey;
     /** Navigation URL - supports template interpolation like "/products/{{row.id}}" */
     navigatesTo?: string;
     /** Callback on click */
     onClick?: (item: unknown) => void;
     /** Action used by generated code - alternative to event */
-    action?: string;
+    action?: EventKey;
     /** Action placement - accepts string for compatibility with generated code */
     placement?: 'card' | 'footer' | 'row' | string;
     /** Button variant - accepts string for compatibility with generated code */

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

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

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

@@ -1,4 +1,5 @@
 import React from "react";
+import type { EventKey } from "@almadar/core";
 import { LucideIcon } from "lucide-react";
 import { EntityDisplayProps } from "./types";
 import type { EntityRow } from "@almadar/core";
@@ -33,7 +34,7 @@ export interface DataTableProps<T extends EntityRow & {
         label: string;
         event?: string;
         navigatesTo?: string;
-        action?: string;
+        action?: EventKey;
         placement?: "row" | "bulk" | string;
         icon?: LucideIcon;
         variant?: "default" | "primary" | "secondary" | "ghost" | "danger" | string;

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

@@ -12,6 +12,7 @@
  * - Nested sections with collapsible support
  */
 import React from "react";
+import type { EventKey } from "@almadar/core";
 import { type SelectOption } from "../atoms/Select";
 import { type RelationOption } from "../molecules/RelationSelect";
 import type { OrbitalEntity } from "@almadar/core";
@@ -173,9 +174,9 @@ export interface FormProps extends Omit<React.FormHTMLAttributes<HTMLFormElement
     /** Form title (used by ModalSlot to extract title) */
     title?: string;
     /** Event to dispatch on successful submit (defaults to 'SAVE') */
-    submitEvent?: string;
+    submitEvent?: EventKey;
     /** Event to dispatch on cancel (defaults to 'CANCEL') */
-    cancelEvent?: string;
+    cancelEvent?: EventKey;
     /** Entity ID binding for edit mode (triggers initialData from selectedEntity in compiled code) */
     entityId?: string;
     /** Data for relation fields: { fieldName: RelationOption[] } */

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/List.d.ts

@@ -17,6 +17,7 @@
  * - No internal search/filter state — trait provides filtered data
  */
 import React from "react";
+import type { EventKey } from "@almadar/core";
 import type { LucideIcon } from "lucide-react";
 import { type MenuItem } from "../molecules/Menu";
 import type { EntityDisplayProps } from "./types";
@@ -41,11 +42,12 @@ export interface ListItem {
 export interface SchemaItemAction {
     label: string;
     /** Event to dispatch on click */
-    event?: string;
+    event?: EventKey;
     navigatesTo?: string;
     /** Action placement - accepts all common placement values */
     placement?: "row" | "bulk" | "card" | "footer" | string;
-    action?: string;
+    /** Alternate event-dispatch field (same semantics as `event`) — generated code emits `UI:{action}` on click */
+    action?: EventKey;
     variant?: "primary" | "secondary" | "ghost" | "danger" | "default";
     /** Click handler from generated code */
     onClick?: (row: unknown) => void;

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

@@ -11,6 +11,7 @@
  * - className for external styling
  */
 import React from "react";
+import type { EventKey } from "@almadar/core";
 import type { EntityRow } from "@almadar/core";
 import type { LucideIcon } from "lucide-react";
 export type TimelineItemStatus = "complete" | "active" | "pending" | "error";
@@ -32,7 +33,7 @@ export interface TimelineItem {
 }
 export interface TimelineAction {
     label: string;
-    event?: string;
+    event?: EventKey;
     navigatesTo?: string;
     variant?: "primary" | "secondary" | "ghost";
 }

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,4 +1,5 @@
 import React from 'react';
+import { EventKey, EventPayload } from '@almadar/core';
 import { LucideIcon } from 'lucide-react';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 
@@ -48,11 +49,11 @@ 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 */
@@ -106,9 +107,9 @@ 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;
 }
@@ -180,9 +181,9 @@ interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
     /** 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;
 }
@@ -276,7 +277,7 @@ interface InputProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, "
     /** 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;
@@ -295,7 +296,7 @@ interface InputProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, "
     /** onChange handler - accepts events from input, select, or textarea */
     onChange?: React.ChangeEventHandler<HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement>;
 }
-declare const Input: React.ForwardRefExoticComponent<InputProps & React.RefAttributes<HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement>>;
+declare const Input: React.ForwardRefExoticComponent<InputProps & React.RefAttributes<HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement>>;
 
 /**
  * DocSidebar Molecule Component

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,4 +1,5 @@
 import React from 'react';
+import { EventKey, EventPayload } from '@almadar/core';
 import { LucideIcon } from 'lucide-react';
 
 /**
@@ -47,11 +48,11 @@ 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 */
@@ -105,9 +106,9 @@ 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;
 }
@@ -179,9 +180,9 @@ interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
     /** 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/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