@almadar/ui 3.4.0 → 3.5.1

package/dist/components/molecules/SwipeableRow.d.ts

@@ -6,20 +6,20 @@
  * Uses useSwipeGesture for gesture detection and useEventBus for event emission.
  */
 import React from 'react';
-import type { EventKey } from "@almadar/core";
+import type { EventKey, EventPayload } from "@almadar/core";
 export interface SwipeAction {
     label: string;
     icon?: string;
     variant?: 'primary' | 'secondary' | 'danger' | 'ghost';
     event: EventKey;
-    eventPayload?: Record<string, unknown>;
+    eventPayload?: EventPayload;
 }
 export interface SwipeableRowProps {
     leftActions?: SwipeAction[];
     rightActions?: SwipeAction[];
     threshold?: number;
     children: React.ReactNode;
-    itemData?: Record<string, unknown>;
+    itemData?: EventPayload;
     className?: string;
 }
 export declare const SwipeableRow: React.FC<SwipeableRowProps>;

package/dist/components/molecules/UploadDropZone.d.ts

@@ -1,5 +1,5 @@
 import React from "react";
-import type { EventKey } from "@almadar/core";
+import type { EventKey, EventPayload } from "@almadar/core";
 export interface UploadDropZoneProps {
     /** Accepted MIME types (e.g., "image/*", "application/pdf") */
     accept?: string;
@@ -18,7 +18,7 @@ export interface UploadDropZoneProps {
     /** Declarative event name for file selection */
     action?: EventKey;
     /** Payload to include with the action event */
-    actionPayload?: Record<string, unknown>;
+    actionPayload?: EventPayload;
     /** Direct onFiles callback */
     onFiles?: (files: File[]) => void;
     /** Additional CSS classes */

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

@@ -12,12 +12,13 @@
  * concern analogous to Form's `formData`.
  */
 import React from 'react';
-export interface DialogueChoice {
+import type { EventPayload } from '@almadar/core';
+export type DialogueChoice = EventPayload & {
     text: string;
     action?: string;
     next?: string;
     disabled?: boolean;
-}
+};
 export interface DialogueNode {
     id?: string;
     speaker: string;

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

@@ -1,6 +1,6 @@
-import type { EventKey } from "@almadar/core";
+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 */
@@ -17,7 +17,7 @@ export interface MenuOption {
     subLabel?: string;
     /** Action identifier (alternative to event) */
     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/ComponentPatterns.d.ts

@@ -9,7 +9,8 @@
  * @packageDocumentation
  */
 import React from 'react';
-import { type ButtonVariant, type ButtonSize } from '../atoms/Button';
+import type { EventKey, EventPayload } from '@almadar/core';
+import { type ButtonProps } from '../atoms/Button';
 import { type BadgeVariant } from '../atoms/Badge';
 import { type AlertVariant } from '../molecules/Alert';
 import { type MapViewProps } from '../molecules/MapView';
@@ -22,36 +23,54 @@ interface ClosedCircuitProps {
     error?: Error | null;
     entity?: string;
 }
-export interface ButtonPatternProps extends ClosedCircuitProps {
-    label: string;
-    variant?: ButtonVariant;
-    size?: ButtonSize;
-    disabled?: boolean;
-    onClick?: string;
-    event?: string;
-    icon?: string;
+/**
+ * Props for {@link ButtonPattern}. A thin pass-through over the Button
+ * atom: accepts every Button prop plus wrapper-level aliases for the
+ * `.orb` schema convention (`action`/`event`/`onClick` as string
+ * event names, `iconPosition` for left/right icon placement).
+ *
+ * Anything not explicitly named is forwarded to `<Button>` via rest-spread,
+ * so a future Button prop lands automatically without needing a wrapper
+ * edit. This is the contract that fixes VG17: `action: EventKey` flows
+ * through to Button, which owns both `UI:{action}` emit AND the
+ * `data-testid="action-{NAME}"` attribute the verifier selects on.
+ */
+export interface ButtonPatternProps extends Omit<ButtonProps, 'onClick'>, ClosedCircuitProps {
+    /** Legacy alias for {@link ButtonProps.action} (string event name). */
+    onClick?: EventKey;
+    /** Legacy alias for {@link ButtonProps.action}. */
+    event?: EventKey;
+    /** Icon placement — maps to Button's `icon` (left) or `iconRight` (right). */
     iconPosition?: 'left' | 'right';
-    className?: string;
 }
 /**
- * Button pattern that emits events via the event bus.
+ * Button pattern — thin pass-through to the Button atom.
+ *
+ * Prior to VG17 this wrapper owned a local event-bus emit and
+ * hand-enumerated only a narrow slice of props, silently dropping
+ * every prop outside that list (including the Pre-Phase `action:
+ * EventKey`). The atom already handles emit + data-testid via its
+ * `action` prop, so the wrapper simply forwards everything.
  */
-export declare function ButtonPattern({ label, variant, size, disabled, onClick, event, icon, iconPosition, className, }: ButtonPatternProps): React.ReactElement;
+export declare function ButtonPattern({ action, onClick, event, icon, iconPosition, ...rest }: ButtonPatternProps): React.ReactElement;
 export declare namespace ButtonPattern {
     var displayName: string;
 }
-export interface IconButtonPatternProps extends ClosedCircuitProps {
+export interface IconButtonPatternProps extends Omit<ButtonProps, 'onClick'>, ClosedCircuitProps {
     icon: string;
-    variant?: ButtonVariant;
-    size?: ButtonSize;
-    onClick?: string;
     ariaLabel?: string;
-    className?: string;
+    /** Legacy alias for {@link ButtonProps.action}. */
+    onClick?: EventKey;
+    /** Legacy alias for {@link ButtonProps.action}. */
+    event?: EventKey;
 }
 /**
- * Icon-only button pattern.
+ * Icon-only button pattern — pass-through to the Button atom with a
+ * mandatory icon and optional aria-label. Same VG17 fix as
+ * {@link ButtonPattern}: `action` forwards to the atom, which owns the
+ * emit + data-testid.
  */
-export declare function IconButtonPattern({ icon, variant, size, onClick, ariaLabel, className, }: IconButtonPatternProps): React.ReactElement;
+export declare function IconButtonPattern({ action, onClick, event, icon, ariaLabel, variant, ...rest }: IconButtonPatternProps): React.ReactElement;
 export declare namespace IconButtonPattern {
     var displayName: string;
 }
@@ -59,13 +78,24 @@ export interface LinkPatternProps extends ClosedCircuitProps {
     label: string;
     href?: string;
     external?: boolean;
-    onClick?: string;
+    /** Event key emitted on click (intercepts native navigation when set). */
+    action?: EventKey;
+    /** Legacy alias for action. */
+    onClick?: EventKey;
+    /** Legacy alias for action. */
+    event?: EventKey;
+    /** Payload for the dispatched event. */
+    actionPayload?: EventPayload;
     className?: string;
 }
 /**
- * Link pattern for navigation.
+ * Link pattern for navigation. When an event key is provided via
+ * `action` / `onClick` / `event`, intercepts the native `<a>`
+ * navigation and emits `UI:{action}` with the `href` in the payload.
+ * Sets `data-testid="action-{NAME}"` so the verifier's click-path
+ * gate can select it symmetrically with Button.
  */
-export declare function LinkPattern({ label, href, external, onClick, className, }: LinkPatternProps): React.ReactElement;
+export declare function LinkPattern({ label, href, external, action, onClick, event, actionPayload, className, }: LinkPatternProps): React.ReactElement;
 export declare namespace LinkPattern {
     var displayName: string;
 }

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