@almadar/ui 3.3.1 → 3.4.0

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 } 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,7 +52,7 @@ 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>;
 }

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 } 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,7 +45,7 @@ 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>;
     /** Declarative hover event — emits UI:{hoverEvent} with { hovered: true/false } on mouseEnter/mouseLeave */

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

@@ -1,4 +1,5 @@
 import React from "react";
+import type { EventKey } 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,7 +16,7 @@ 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>;
     /** Button label text (alternative to children for schema-driven rendering) */

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 } from "@almadar/core";
 export type RangeSliderSize = "sm" | "md" | "lg";
 export interface RangeSliderProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "onChange"> {
     /** Minimum value */
@@ -20,7 +21,7 @@ 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>;
     /** Direct onChange callback */

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 } 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,7 +42,7 @@ 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>;
     /** When true, horizontal stacks flip to vertical below the md breakpoint (768px) */

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,7 +44,7 @@ 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;
 }

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/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

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

@@ -7,6 +7,7 @@
  * @generated by Orbital Compiler
  */
 import React from "react";
+import type { EventKey } from "@almadar/core";
 export interface CardAction {
     label: string;
     onClick?: () => void;
@@ -32,7 +33,7 @@ export interface CardProps {
     /** Additional CSS classes */
     className?: string;
     /** Declarative event name — emits UI:{action} via eventBus on card click */
-    action?: string;
+    action?: EventKey;
     /** Whether the card is selected (highlighted state) */
     isSelected?: boolean;
     /** Card name (alias for title) */

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

@@ -11,6 +11,7 @@
  * Uses atoms only internally: Box, VStack, HStack, Typography, Badge, Button, Icon.
  */
 import React from 'react';
+import type { EventKey } from '@almadar/core';
 export interface DataGridField {
     /** Entity field name (dot-notation supported) */
     name: string;
@@ -28,7 +29,7 @@ export interface DataGridItemAction {
     /** Button label */
     label: string;
     /** Event name to emit (dispatched as UI:{event} with { row: itemData }) */
-    event: string;
+    event: EventKey;
     /** Lucide icon name */
     icon?: string;
     /** Button variant */

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

@@ -11,6 +11,7 @@
  * Uses atoms only internally: Box, VStack, HStack, Typography, Badge, Button, Icon.
  */
 import React from 'react';
+import type { EventKey } from "@almadar/core";
 export interface DataListField {
     /** Entity field name (dot-notation supported) */
     name: string;
@@ -28,7 +29,7 @@ export interface DataListItemAction {
     /** Button label */
     label: string;
     /** Event name to emit (dispatched as UI:{event} with { id, row: itemData }) */
-    event: string;
+    event: EventKey;
     /** Lucide icon name */
     icon?: string;
     /** Button variant */

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

@@ -1,4 +1,5 @@
 import React from "react";
+import type { EventKey } from "@almadar/core";
 export type NumberStepperSize = "sm" | "md" | "lg";
 export interface NumberStepperProps {
     /** Current value */
@@ -16,7 +17,7 @@ export interface NumberStepperProps {
     /** Direct onChange callback */
     onChange?: (value: number) => void;
     /** Declarative event name for value changes */
-    action?: string;
+    action?: EventKey;
     /** Payload to include with the action event */
     actionPayload?: Record<string, unknown>;
     /** Additional CSS classes */

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

@@ -1,4 +1,5 @@
 import React from "react";
+import type { EventKey } from "@almadar/core";
 export type StarRatingSize = "sm" | "md" | "lg";
 export type StarRatingPrecision = "full" | "half";
 export interface StarRatingProps {
@@ -13,7 +14,7 @@ export interface StarRatingProps {
     /** Star size */
     size?: StarRatingSize;
     /** Declarative event name for rating changes */
-    action?: string;
+    action?: EventKey;
     /** Payload to include with the action event */
     actionPayload?: Record<string, unknown>;
     /** Direct onChange callback */

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

@@ -6,11 +6,12 @@
  * Uses useSwipeGesture for gesture detection and useEventBus for event emission.
  */
 import React from 'react';
+import type { EventKey } from "@almadar/core";
 export interface SwipeAction {
     label: string;
     icon?: string;
     variant?: 'primary' | 'secondary' | 'danger' | 'ghost';
-    event: string;
+    event: EventKey;
     eventPayload?: Record<string, unknown>;
 }
 export interface SwipeableRowProps {

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

@@ -1,4 +1,5 @@
 import React from "react";
+import type { EventKey } from "@almadar/core";
 export interface UploadDropZoneProps {
     /** Accepted MIME types (e.g., "image/*", "application/pdf") */
     accept?: string;
@@ -15,7 +16,7 @@ export interface UploadDropZoneProps {
     /** Disabled state */
     disabled?: boolean;
     /** Declarative event name for file selection */
-    action?: string;
+    action?: EventKey;
     /** Payload to include with the action event */
     actionPayload?: Record<string, unknown>;
     /** Direct onFiles callback */

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

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

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 } from "@almadar/core";
 /**
  * Allowed element types for custom patterns.
  */
@@ -31,7 +32,7 @@ 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>;
     /** Nested children patterns */
@@ -81,7 +82,7 @@ export interface CustomPatternConfig {
     className?: string;
     token?: string | string[];
     content?: string;
-    action?: string;
+    action?: EventKey;
     payload?: Record<string, unknown>;
     children?: CustomPatternConfig[];
     src?: 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/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/docs/index.d.cts

@@ -1,4 +1,5 @@
 import React from 'react';
+import { EventKey } from '@almadar/core';
 import { LucideIcon } from 'lucide-react';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 
@@ -48,7 +49,7 @@ 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>;
     /** Declarative hover event — emits UI:{hoverEvent} with { hovered: true/false } on mouseEnter/mouseLeave */
@@ -106,7 +107,7 @@ 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>;
     /** When true, horizontal stacks flip to vertical below the md breakpoint (768px) */
@@ -180,7 +181,7 @@ 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>;
     /** Button label text (alternative to children for schema-driven rendering) */
@@ -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/marketing/index.d.cts

@@ -1,4 +1,5 @@
 import React from 'react';
+import { EventKey } from '@almadar/core';
 import { LucideIcon } from 'lucide-react';
 
 /**
@@ -47,7 +48,7 @@ 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>;
     /** Declarative hover event — emits UI:{hoverEvent} with { hovered: true/false } on mouseEnter/mouseLeave */
@@ -105,7 +106,7 @@ 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>;
     /** When true, horizontal stacks flip to vertical below the md breakpoint (768px) */
@@ -179,7 +180,7 @@ 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>;
     /** Button label text (alternative to children for schema-driven rendering) */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@almadar/ui",
-  "version": "3.3.1",
+  "version": "3.4.0",
   "description": "React UI components, hooks, and providers for Almadar",
   "type": "module",
   "main": "./dist/components/index.js",
@@ -118,9 +118,9 @@
     "access": "public"
   },
   "dependencies": {
-    "@almadar/core": ">=5.5.0",
+    "@almadar/core": ">=5.6.0",
     "@almadar/evaluator": ">=2.9.2",
-    "@almadar/patterns": ">=2.14.1",
+    "@almadar/patterns": ">=2.16.0",
     "@almadar/runtime": ">=4.3.0",
     "@almadar/std": ">=6.4.1",
     "@almadar/syntax": ">=1.3.1",