@almadar/ui 2.13.3 → 2.15.0

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

@@ -0,0 +1,35 @@
+/**
+ * Toast Molecule Component
+ *
+ * A toast notification component with auto-dismiss and action buttons.
+ * Uses theme-aware CSS variables for styling.
+ */
+import React from "react";
+export type ToastVariant = "success" | "error" | "info" | "warning";
+export interface ToastProps {
+    /** Toast variant */
+    variant?: ToastVariant;
+    /** Toast message */
+    message: string;
+    /** Toast title (optional) */
+    title?: string;
+    /** Auto-dismiss duration in milliseconds (0 = no auto-dismiss) */
+    duration?: number;
+    /** Show dismiss button */
+    dismissible?: boolean;
+    /** Callback when toast is dismissed */
+    onDismiss?: () => void;
+    /** Action button label */
+    actionLabel?: string;
+    /** Action button click handler */
+    onAction?: () => void;
+    /** Badge count (optional) */
+    badge?: string | number;
+    /** Additional CSS classes */
+    className?: string;
+    /** Declarative dismiss event — emits UI:{dismissEvent} via eventBus when toast is dismissed */
+    dismissEvent?: string;
+    /** Declarative action event — emits UI:{actionEvent} via eventBus when action button is clicked */
+    actionEvent?: string;
+}
+export declare const Toast: React.FC<ToastProps>;

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

@@ -0,0 +1,25 @@
+/**
+ * Tooltip Molecule Component
+ *
+ * A tooltip component with position variants and delay options.
+ * Uses theme-aware CSS variables for styling.
+ */
+import React from 'react';
+export type TooltipPosition = 'top' | 'bottom' | 'left' | 'right';
+export interface TooltipProps {
+    /** Tooltip content */
+    content: React.ReactNode;
+    /** Tooltip trigger element (ReactElement or ReactNode that will be wrapped in span) */
+    children: React.ReactNode;
+    /** Tooltip position */
+    position?: TooltipPosition;
+    /** Show delay in milliseconds */
+    delay?: number;
+    /** Hide delay in milliseconds */
+    hideDelay?: number;
+    /** Show arrow */
+    showArrow?: boolean;
+    /** Additional CSS classes */
+    className?: string;
+}
+export declare const Tooltip: React.FC<TooltipProps>;

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

@@ -0,0 +1,26 @@
+import React from "react";
+export interface UploadDropZoneProps {
+    /** Accepted MIME types (e.g., "image/*", "application/pdf") */
+    accept?: string;
+    /** Max file size in bytes */
+    maxSize?: number;
+    /** Max number of files */
+    maxFiles?: number;
+    /** Label text */
+    label?: string;
+    /** Description text below label */
+    description?: string;
+    /** Icon name (Lucide string) */
+    icon?: string;
+    /** Disabled state */
+    disabled?: boolean;
+    /** Declarative event name for file selection */
+    action?: string;
+    /** Payload to include with the action event */
+    actionPayload?: Record<string, unknown>;
+    /** Direct onFiles callback */
+    onFiles?: (files: File[]) => void;
+    /** Additional CSS classes */
+    className?: string;
+}
+export declare const UploadDropZone: React.FC<UploadDropZoneProps>;

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

@@ -0,0 +1,49 @@
+/**
+ * ViolationAlert
+ *
+ * Displays inspection violations with law references and action types.
+ * Used in inspection forms to show detected compliance violations.
+ *
+ * Action Types:
+ * - measure: Corrective measure required (warning)
+ * - admin: Administrative action (error)
+ * - penalty: Penalty proceedings (error, severe)
+ */
+import React from "react";
+export interface ViolationRecord {
+    /** Unique violation identifier */
+    id: string;
+    /** Law reference (e.g., "ZVPOT-1") */
+    law: string;
+    /** Article reference (e.g., "14/1") */
+    article: string;
+    /** Violation message */
+    message: string;
+    /** Action type determines severity */
+    actionType: "measure" | "admin" | "penalty";
+    /** Administrative action reference (e.g., "ZVPOT-1 234/1-4") */
+    adminAction?: string;
+    /** Penalty action reference (e.g., "ZVPOT-1 240/1-9") */
+    penaltyAction?: string;
+    /** Field that triggered this violation */
+    fieldId?: string;
+    /** Tab/form where violation occurred */
+    tabId?: string;
+}
+export interface ViolationAlertProps {
+    /** Violation data */
+    violation: ViolationRecord;
+    /** Visual severity (derived from actionType if not specified) */
+    severity?: "warning" | "error";
+    /** Dismissible alert */
+    dismissible?: boolean;
+    /** Dismiss handler */
+    onDismiss?: () => void;
+    /** Navigate to the field that caused violation */
+    onNavigateToField?: (fieldId: string) => void;
+    /** Compact display mode */
+    compact?: boolean;
+    /** Additional CSS classes */
+    className?: string;
+}
+export declare const ViolationAlert: React.FC<ViolationAlertProps>;

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;
+}