@almadar/ui 2.14.0 → 2.15.1

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

@@ -0,0 +1,51 @@
+/**
+ * WizardNavigation Component
+ *
+ * Navigation buttons for multi-step wizards.
+ * Includes Back, Next, and Complete buttons with proper state handling.
+ *
+ * Emits events via useEventBus for trait integration.
+ * Uses wireframe theme styling (high contrast, sharp edges).
+ */
+import React from "react";
+export interface WizardNavigationProps {
+    /** Current step index (0-based) */
+    currentStep: number;
+    /** Total number of steps */
+    totalSteps: number;
+    /** Whether the current step is valid (enables Next/Complete) */
+    isValid?: boolean;
+    /** Show the Back button */
+    showBack?: boolean;
+    /** Show the Next button */
+    showNext?: boolean;
+    /** Show the Complete button (on last step) */
+    showComplete?: boolean;
+    /** Custom label for Back button */
+    backLabel?: string;
+    /** Custom label for Next button */
+    nextLabel?: string;
+    /** Custom label for Complete button */
+    completeLabel?: string;
+    /** Event to emit on Back click */
+    onBack?: string;
+    /** Event to emit on Next click */
+    onNext?: string;
+    /** Event to emit on Complete click */
+    onComplete?: string;
+    /** Direct callback for Back (alternative to event) */
+    onBackClick?: () => void;
+    /** Direct callback for Next (alternative to event) */
+    onNextClick?: () => void;
+    /** Direct callback for Complete (alternative to event) */
+    onCompleteClick?: () => void;
+    /** Compact mode (smaller padding) */
+    compact?: boolean;
+    /** Additional CSS classes */
+    className?: string;
+}
+/**
+ * WizardNavigation - Wizard navigation buttons
+ */
+export declare const WizardNavigation: React.FC<WizardNavigationProps>;
+export default WizardNavigation;

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

@@ -0,0 +1,42 @@
+/**
+ * WizardProgress Component
+ *
+ * Step progress indicator for multi-step wizards.
+ * Shows current step, completed steps, and allows navigation to completed steps.
+ *
+ * Uses wireframe theme styling (high contrast, sharp edges).
+ */
+import React from "react";
+/**
+ * Step info needed by WizardProgress.
+ * Compatible with WizardContainer's WizardStep (subset of fields).
+ */
+export interface WizardProgressStep {
+    /** Step identifier */
+    id: string;
+    /** Step title */
+    title: string;
+    /** Step description (optional) */
+    description?: string;
+}
+export interface WizardProgressProps {
+    /** Step definitions (compatible with WizardContainer's WizardStep) */
+    steps: WizardProgressStep[];
+    /** Current step index (0-based) */
+    currentStep: number;
+    /** Callback when a completed step is clicked */
+    onStepClick?: (stepIndex: number) => void;
+    /** Allow clicking on completed steps to navigate back */
+    allowNavigation?: boolean;
+    /** Compact mode (smaller, no titles) */
+    compact?: boolean;
+    /** Additional CSS classes */
+    className?: string;
+    /** Declarative step click event — emits UI:{stepClickEvent} with { stepIndex } */
+    stepClickEvent?: string;
+}
+/**
+ * WizardProgress - Step progress indicator
+ */
+export declare const WizardProgress: React.FC<WizardProgressProps>;
+export default WizardProgress;

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

@@ -0,0 +1,34 @@
+import * as React from 'react';
+export interface ActionButtonConfig {
+    /** Unique identifier */
+    id: string;
+    /** Display label */
+    label?: string;
+    /** Icon component or emoji */
+    icon?: React.ReactNode;
+    /** Button variant */
+    variant?: 'primary' | 'secondary' | 'ghost' | string;
+}
+/** Event Contract:
+ *  Emits: UI:ACTION
+ */
+export interface ActionButtonsProps {
+    /** Button configurations */
+    buttons: ActionButtonConfig[];
+    /** Called when a button is pressed/released */
+    onAction?: (id: string, pressed: boolean) => void;
+    /** Declarative event name emitted on action via useEventBus */
+    actionEvent?: string;
+    /** Layout variant */
+    layout?: 'horizontal' | 'vertical' | 'diamond';
+    /** Size variant */
+    size?: 'sm' | 'md' | 'lg';
+    /** Additional CSS classes */
+    className?: string;
+    /** Disabled state */
+    disabled?: boolean;
+}
+export declare function ActionButtons({ buttons, onAction, actionEvent, layout, size, className, disabled, }: ActionButtonsProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace ActionButtons {
+    var displayName: string;
+}

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

@@ -0,0 +1,30 @@
+/**
+ * CombatLog Component
+ *
+ * Scrollable log of combat events with icons and colors.
+ * Generalized from Trait Wars — removed asset manifest coupling.
+ */
+import React from 'react';
+export type CombatLogEventType = 'attack' | 'defend' | 'heal' | 'move' | 'special' | 'death' | 'spawn';
+export interface CombatEvent {
+    id: string;
+    type: CombatLogEventType;
+    message: string;
+    timestamp: number;
+    actorName?: string;
+    targetName?: string;
+    value?: number;
+    turn?: number;
+}
+export interface CombatLogProps {
+    events: CombatEvent[];
+    maxVisible?: number;
+    autoScroll?: boolean;
+    showTimestamps?: boolean;
+    title?: string;
+    className?: string;
+}
+export declare function CombatLog({ events, maxVisible, autoScroll, showTimestamps, className, title, }: CombatLogProps): React.JSX.Element;
+export declare namespace CombatLog {
+    var displayName: string;
+}

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

@@ -0,0 +1,33 @@
+import * as React from 'react';
+export interface CraftingIngredient {
+    /** Icon component or emoji */
+    icon?: React.ReactNode;
+    /** Ingredient label */
+    label: string;
+    /** Number required for the recipe */
+    required: number;
+    /** Number currently available */
+    available: number;
+}
+export interface CraftingRecipeProps {
+    /** Input ingredients for the recipe */
+    inputs: CraftingIngredient[];
+    /** Output item produced by the recipe */
+    output: {
+        icon?: React.ReactNode;
+        label: string;
+        rarity?: string;
+    };
+    /** Whether the player has enough ingredients to craft */
+    canCraft?: boolean;
+    /** Callback when the craft button is clicked */
+    onCraft?: () => void;
+    /** Event bus event name for crafting */
+    craftEvent?: string;
+    /** Additional CSS classes */
+    className?: string;
+}
+export declare function CraftingRecipe({ inputs, output, canCraft, onCraft, craftEvent, className, }: CraftingRecipeProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace CraftingRecipe {
+    var displayName: string;
+}

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

@@ -0,0 +1,22 @@
+export type DPadDirection = 'up' | 'down' | 'left' | 'right';
+/** Event Contract:
+ *  Emits: UI:DIRECTION
+ */
+export interface DPadProps {
+    /** Called when a direction is pressed/released */
+    onDirection?: (direction: DPadDirection, pressed: boolean) => void;
+    /** Declarative event name emitted on direction press/release via useEventBus */
+    directionEvent?: string;
+    /** Size variant */
+    size?: 'sm' | 'md' | 'lg';
+    /** Whether to include diagonal buttons */
+    includeDiagonals?: boolean;
+    /** Additional CSS classes */
+    className?: string;
+    /** Disabled state */
+    disabled?: boolean;
+}
+export declare function DPad({ onDirection, directionEvent, size, includeDiagonals, className, disabled, }: DPadProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace DPad {
+    var displayName: string;
+}

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

@@ -0,0 +1,78 @@
+/**
+ * DialogueBox Component
+ *
+ * NPC dialogue display with typewriter effect and choices.
+ *
+ * **State categories (closed-circuit compliant):**
+ * - Content (dialogue node, speaker, text, choices) → received via props
+ * - UI-transient animation (displayedText, isTyping, charIndex, selectedChoice) → local only
+ * - Events → emitted via `useEventBus()` (complete, choice, advance)
+ *
+ * Local state is typewriter animation only — an inherently rendering-only
+ * concern analogous to Form's `formData`.
+ */
+import React from 'react';
+export interface DialogueChoice {
+    text: string;
+    action?: string;
+    next?: string;
+    disabled?: boolean;
+}
+export interface DialogueNode {
+    id?: string;
+    speaker: string;
+    text: string;
+    portrait?: string;
+    choices?: DialogueChoice[];
+    autoAdvance?: number;
+}
+/** Event Contract:
+ *  Emits: UI:COMPLETE
+ *  Emits: UI:CHOICE
+ *  Emits: UI:ADVANCE
+ */
+export interface DialogueBoxProps {
+    /** Current dialogue node to display */
+    dialogue: DialogueNode;
+    /** Typewriter speed in ms per character (0 = instant) */
+    typewriterSpeed?: number;
+    /** Position of dialogue box */
+    position?: 'top' | 'bottom';
+    /** Called when text animation completes */
+    onComplete?: () => void;
+    /** Called when a choice is selected */
+    onChoice?: (choice: DialogueChoice) => void;
+    /** Called when dialogue is advanced (no choices) */
+    onAdvance?: () => void;
+    /** Declarative event: emits UI:{completeEvent} when text animation completes */
+    completeEvent?: string;
+    /** Declarative event: emits UI:{choiceEvent} with { choice } when a choice is selected */
+    choiceEvent?: string;
+    /** Declarative event: emits UI:{advanceEvent} when dialogue is advanced */
+    advanceEvent?: string;
+    /** Optional className */
+    className?: string;
+}
+/**
+ * Dialogue box component with typewriter effect
+ *
+ * @example
+ * ```tsx
+ * <DialogueBox
+ *   dialogue={{
+ *     speaker: "Old Man",
+ *     text: "It's dangerous to go alone! Take this.",
+ *     portrait: "/portraits/oldman.png",
+ *     choices: [
+ *       { text: "Thank you!", action: "ACCEPT_ITEM" },
+ *       { text: "No thanks", next: "decline_node" }
+ *     ]
+ *   }}
+ *   typewriterSpeed={30}
+ *   onChoice={(choice) => handleChoice(choice)}
+ *   position="bottom"
+ * />
+ * ```
+ */
+export declare function DialogueBox({ dialogue, typewriterSpeed, position, onComplete, onChoice, onAdvance, completeEvent, choiceEvent, advanceEvent, className, }: DialogueBoxProps): React.JSX.Element;
+export default DialogueBox;

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

@@ -0,0 +1,27 @@
+import * as React from 'react';
+export interface EnemyPlateEffect {
+    /** Effect icon */
+    icon: React.ReactNode;
+    /** Effect label */
+    label?: string;
+    /** Effect type */
+    variant?: 'buff' | 'debuff' | 'neutral';
+}
+export interface EnemyPlateProps {
+    /** Enemy name */
+    name: string;
+    /** Current health */
+    health: number;
+    /** Maximum health */
+    maxHealth: number;
+    /** Enemy level */
+    level?: number;
+    /** Active status effects */
+    effects?: EnemyPlateEffect[];
+    /** Additional CSS classes */
+    className?: string;
+}
+export declare function EnemyPlate({ name, health, maxHealth, level, effects, className, }: EnemyPlateProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace EnemyPlate {
+    var displayName: string;
+}

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

@@ -0,0 +1,18 @@
+export interface GameCanvas2DProps {
+    /** Canvas width in pixels */
+    width?: number;
+    /** Canvas height in pixels */
+    height?: number;
+    /** Called each frame with the 2D context and current frame count */
+    onDraw?: (ctx: CanvasRenderingContext2D, frame: number) => void;
+    /** Called each tick with delta time in seconds */
+    onTick?: (dt: number) => void;
+    /** Target frames per second */
+    fps?: number;
+    /** Additional CSS classes */
+    className?: string;
+}
+export declare function GameCanvas2D({ width, height, onDraw, onTick, fps, className, }: GameCanvas2DProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace GameCanvas2D {
+    var displayName: string;
+}

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

@@ -0,0 +1,49 @@
+import * as React from "react";
+import { type StatBadgeProps } from "./StatBadge";
+export interface GameHudStat extends Omit<StatBadgeProps, "size"> {
+    /** Data source entity name */
+    source?: string;
+    /** Field name in the source */
+    field?: string;
+}
+/**
+ * Schema-style HUD element definition.
+ * Used when elements are passed from schema render_ui effects.
+ */
+export interface GameHudElement {
+    type?: string;
+    bind?: string;
+    position?: string;
+    label?: string;
+    /** Direct value (from compiled render-ui effects) */
+    value?: number | string;
+    /** Icon name or node */
+    icon?: React.ReactNode;
+    /** Display format */
+    format?: string;
+    /** Max value (for bars/hearts) */
+    max?: number;
+}
+export interface GameHudProps {
+    /** Position of the HUD */
+    position?: "top" | "bottom" | "corners" | string;
+    /** Stats to display - accepts readonly for compatibility with generated const arrays */
+    stats?: readonly GameHudStat[];
+    /** Alias for stats (schema compatibility) */
+    items?: readonly GameHudStat[];
+    /**
+     * Schema-style elements array (alternative to stats).
+     * Converted to stats internally for backwards compatibility.
+     */
+    elements?: readonly GameHudElement[];
+    /** Size variant */
+    size?: "sm" | "md" | "lg";
+    /** Additional CSS classes */
+    className?: string;
+    /** Whether to use a semi-transparent background */
+    transparent?: boolean;
+}
+export declare function GameHud({ position: propPosition, stats: propStats, items, elements, size, className, transparent, }: GameHudProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace GameHud {
+    var displayName: string;
+}

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

@@ -0,0 +1,43 @@
+import { type EventBusContextType } from "../../../hooks/useEventBus";
+export interface MenuOption {
+    /** Optional ID (generated from index if not provided) */
+    id?: string;
+    /** Display label */
+    label: string;
+    /** Event to emit on click */
+    event?: string;
+    /** Page to navigate to */
+    navigatesTo?: string;
+    /** Button variant */
+    variant?: "primary" | "secondary" | "ghost" | string;
+    /** Whether the option is disabled */
+    disabled?: boolean;
+    /** Sub-label or description */
+    subLabel?: string;
+    /** Action identifier (alternative to event) */
+    action?: string;
+}
+export interface GameMenuProps {
+    /** Menu title */
+    title: string;
+    /** Optional subtitle or version */
+    subtitle?: string;
+    /** Menu options - accepts readonly for compatibility with generated const arrays */
+    options?: readonly MenuOption[];
+    /** Alias for options (schema compatibility) */
+    menuItems?: readonly MenuOption[];
+    /** Called when an option is selected (legacy callback, prefer event bus) */
+    onSelect?: (option: MenuOption) => void;
+    /** Event bus for emitting UI events (optional, uses hook if not provided) */
+    eventBus?: EventBusContextType;
+    /** Background image or gradient */
+    background?: string;
+    /** Logo image URL */
+    logo?: string;
+    /** Additional CSS classes */
+    className?: string;
+}
+export declare function GameMenu({ title, subtitle, options, menuItems, onSelect, eventBus: eventBusProp, background, logo, className, }: GameMenuProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace GameMenu {
+    var displayName: string;
+}

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

@@ -0,0 +1,56 @@
+import * as React from "react";
+import { type EventBusContextType } from "../../../hooks/useEventBus";
+export interface GameOverStat {
+    /** Stat label */
+    label: string;
+    /** Stat value (required if bind is not provided) */
+    value?: number | string;
+    /**
+     * Schema-style data binding (e.g., "player.score").
+     * Alternative to value - used when stats come from schema render_ui effects.
+     * Component will display 0 as placeholder since runtime binding is not implemented.
+     */
+    bind?: string;
+    /** Display format */
+    format?: "number" | "time" | "text";
+    /** Icon */
+    icon?: React.ReactNode;
+}
+export interface GameOverAction {
+    /** Display label */
+    label: string;
+    /** Event to emit on click */
+    event?: string;
+    /** Page to navigate to */
+    navigatesTo?: string;
+    /** Button variant */
+    variant?: "primary" | "secondary" | "ghost";
+}
+export interface GameOverScreenProps {
+    /** Screen title (e.g., "Game Over", "Victory!") */
+    title: string;
+    /** Optional message */
+    message?: string;
+    /** Stats to display */
+    stats?: GameOverStat[];
+    /** Action buttons */
+    actions?: GameOverAction[];
+    /** Alias for actions (schema compatibility) */
+    menuItems?: GameOverAction[];
+    /** Called when an action is selected (legacy callback, prefer event bus) */
+    onAction?: (action: GameOverAction) => void;
+    /** Event bus for emitting UI events (optional, uses hook if not provided) */
+    eventBus?: EventBusContextType;
+    /** Victory or defeat variant */
+    variant?: "victory" | "defeat" | "neutral";
+    /** High score (optional, shows "NEW HIGH SCORE!" if exceeded) */
+    highScore?: number | string;
+    /** Current score for high score comparison (accepts string for schema bindings) */
+    currentScore?: number | string;
+    /** Additional CSS classes */
+    className?: string;
+}
+export declare function GameOverScreen({ title, message, stats, actions, menuItems, onAction, eventBus: eventBusProp, variant, highScore, currentScore, className, }: GameOverScreenProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace GameOverScreen {
+    var displayName: string;
+}

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

@@ -0,0 +1,27 @@
+import * as React from 'react';
+export interface HealthPanelProps {
+    /** Current health value */
+    current: number;
+    /** Maximum health value */
+    max: number;
+    /** Shield/armor points */
+    shield?: number;
+    /** Label shown above the bar */
+    label?: string;
+    /** Active status effects displayed as small badges */
+    effects?: {
+        icon: React.ReactNode;
+        label?: string;
+        variant?: 'buff' | 'debuff' | 'neutral';
+    }[];
+    /** Whether to display numeric HP values */
+    showNumbers?: boolean;
+    /** Size variant */
+    size?: 'sm' | 'md' | 'lg';
+    /** Additional CSS classes */
+    className?: string;
+}
+export declare function HealthPanel({ current, max, shield, label, effects, showNumbers, size, className, }: HealthPanelProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace HealthPanel {
+    var displayName: string;
+}

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

@@ -0,0 +1,30 @@
+import * as React from 'react';
+export interface InventoryGridItem {
+    id: string;
+    icon?: React.ReactNode;
+    label?: string;
+    quantity?: number;
+    rarity?: 'common' | 'uncommon' | 'rare' | 'epic' | 'legendary';
+}
+export interface InventoryGridProps {
+    /** Array of items to display in the grid */
+    items: InventoryGridItem[];
+    /** Number of columns in the grid */
+    columns?: number;
+    /** Total number of slots (empty slots fill remaining space) */
+    totalSlots?: number;
+    /** Currently selected item ID */
+    selectedId?: string;
+    /** Callback when an item is selected */
+    onSelect?: (id: string) => void;
+    /** Event bus event name for selection */
+    selectEvent?: string;
+    /** Size variant for all item slots */
+    size?: 'sm' | 'md' | 'lg';
+    /** Additional CSS classes */
+    className?: string;
+}
+export declare function InventoryGrid({ items, columns, totalSlots, selectedId, onSelect, selectEvent, size, className, }: InventoryGridProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace InventoryGrid {
+    var displayName: string;
+}

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

@@ -0,0 +1,67 @@
+/**
+ * InventoryPanel Component
+ *
+ * Grid-based inventory UI with item selection and tooltips.
+ *
+ * **State categories (closed-circuit compliant):**
+ * - Data (items, slots, selectedSlot) → received via props
+ * - UI-transient (hoveredSlot, tooltipPosition) → local only
+ * - Events → emitted via `useEventBus()` (selectSlot, useItem, dropItem)
+ *
+ * Local state is hover/tooltip only — rendering-only concerns.
+ */
+import React from 'react';
+export interface InventoryItem {
+    id: string;
+    type: string;
+    quantity: number;
+    sprite?: string;
+    name?: string;
+    description?: string;
+}
+export interface InventoryPanelProps {
+    /** Array of items in inventory */
+    items: InventoryItem[];
+    /** Total number of slots */
+    slots: number;
+    /** Number of columns in grid */
+    columns: number;
+    /** Currently selected slot index */
+    selectedSlot?: number;
+    /** Called when a slot is selected */
+    onSelectSlot?: (index: number) => void;
+    /** Called when an item is used (double-click or Enter) */
+    onUseItem?: (item: InventoryItem) => void;
+    /** Called when an item is dropped */
+    onDropItem?: (item: InventoryItem) => void;
+    /** Declarative event: emits UI:{selectSlotEvent} with { index } when a slot is selected */
+    selectSlotEvent?: string;
+    /** Declarative event: emits UI:{useItemEvent} with { item } when an item is used */
+    useItemEvent?: string;
+    /** Declarative event: emits UI:{dropItemEvent} with { item } when an item is dropped */
+    dropItemEvent?: string;
+    /** Show item tooltips on hover */
+    showTooltips?: boolean;
+    /** Optional className */
+    className?: string;
+    /** Slot size in pixels */
+    slotSize?: number;
+}
+/**
+ * Inventory panel component with grid layout
+ *
+ * @example
+ * ```tsx
+ * <InventoryPanel
+ *   items={playerInventory}
+ *   slots={20}
+ *   columns={5}
+ *   selectedSlot={selectedSlot}
+ *   onSelectSlot={setSelectedSlot}
+ *   onUseItem={(item) => console.log('Used:', item.name)}
+ *   showTooltips
+ * />
+ * ```
+ */
+export declare function InventoryPanel({ items, slots, columns, selectedSlot, onSelectSlot, onUseItem, onDropItem, selectSlotEvent, useItemEvent, dropItemEvent, showTooltips, className, slotSize, }: InventoryPanelProps): React.JSX.Element;
+export default InventoryPanel;