@almadar/ui 2.13.3 → 2.15.0

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

@@ -0,0 +1,31 @@
+import React from "react";
+export type RangeSliderSize = "sm" | "md" | "lg";
+export interface RangeSliderProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "onChange"> {
+    /** Minimum value */
+    min?: number;
+    /** Maximum value */
+    max?: number;
+    /** Current value */
+    value?: number;
+    /** Step increment */
+    step?: number;
+    /** Show tooltip with current value on drag */
+    showTooltip?: boolean;
+    /** Show tick marks at step intervals */
+    showTicks?: boolean;
+    /** Buffered range (0-100), for media seek bars */
+    buffered?: number;
+    /** Slider size */
+    size?: RangeSliderSize;
+    /** Disabled state */
+    disabled?: boolean;
+    /** Declarative event name for value changes */
+    action?: string;
+    /** Payload to include with the action event */
+    actionPayload?: Record<string, unknown>;
+    /** Direct onChange callback */
+    onChange?: (value: number) => void;
+    /** Format function for tooltip display */
+    formatValue?: (value: number) => string;
+}
+export declare const RangeSlider: React.ForwardRefExoticComponent<RangeSliderProps & React.RefAttributes<HTMLDivElement>>;

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

@@ -0,0 +1,12 @@
+import React from "react";
+export interface SelectOption {
+    value: string;
+    label: string;
+    disabled?: boolean;
+}
+export interface SelectProps extends Omit<React.SelectHTMLAttributes<HTMLSelectElement>, "children"> {
+    options: SelectOption[];
+    placeholder?: string;
+    error?: string;
+}
+export declare const Select: React.ForwardRefExoticComponent<SelectProps & React.RefAttributes<HTMLSelectElement>>;

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

@@ -0,0 +1,25 @@
+/**
+ * Spacer Component
+ *
+ * A flexible spacer that expands to fill available space in a flex container.
+ * Useful for pushing elements apart or creating consistent spacing.
+ */
+import React from 'react';
+export type SpacerSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | 'auto';
+export interface SpacerProps {
+    /** Fixed size (auto = flex grow) */
+    size?: SpacerSize;
+    /** Orientation (for fixed sizes) */
+    axis?: 'horizontal' | 'vertical';
+    /** Custom class name */
+    className?: string;
+}
+/**
+ * Spacer - Flexible spacing element for flex layouts
+ *
+ * Usage:
+ * - size="auto" (default): Expands to fill available space (flex: 1)
+ * - size="md": Fixed size spacing
+ */
+export declare const Spacer: React.FC<SpacerProps>;
+export default Spacer;

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

@@ -0,0 +1,6 @@
+import React from "react";
+export type SpinnerSize = "xs" | "sm" | "md" | "lg";
+export interface SpinnerProps extends React.HTMLAttributes<HTMLDivElement> {
+    size?: SpinnerSize;
+}
+export declare const Spinner: React.ForwardRefExoticComponent<SpinnerProps & React.RefAttributes<HTMLDivElement>>;

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

@@ -0,0 +1,66 @@
+/**
+ * Stack Component
+ *
+ * A layout primitive for arranging children in a vertical or horizontal stack with consistent spacing.
+ * Includes convenience exports VStack and HStack for common use cases.
+ */
+import React from "react";
+export type StackDirection = "horizontal" | "vertical";
+export type StackGap = "none" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl";
+export type StackAlign = "start" | "center" | "end" | "stretch" | "baseline";
+export type StackJustify = "start" | "center" | "end" | "between" | "around" | "evenly";
+export interface StackProps {
+    /** Stack direction */
+    direction?: StackDirection;
+    /** Gap between children */
+    gap?: StackGap;
+    /** Align items on the cross axis */
+    align?: StackAlign;
+    /** Justify items on the main axis */
+    justify?: StackJustify;
+    /** Allow items to wrap */
+    wrap?: boolean;
+    /** Reverse the order of children */
+    reverse?: boolean;
+    /** Fill available space (flex: 1) */
+    flex?: boolean;
+    /** Custom class name */
+    className?: string;
+    /** Inline styles */
+    style?: React.CSSProperties;
+    /** Children elements */
+    children?: React.ReactNode;
+    /** HTML element to render as */
+    as?: React.ElementType;
+    /** Click handler */
+    onClick?: (e: React.MouseEvent) => void;
+    /** Keyboard handler */
+    onKeyDown?: (e: React.KeyboardEvent) => void;
+    /** Role for accessibility */
+    role?: string;
+    /** Tab index for focus management */
+    tabIndex?: number;
+    /** Declarative event name — emits UI:{action} via eventBus on click */
+    action?: string;
+    /** Payload to include with the action event */
+    actionPayload?: Record<string, unknown>;
+    /** When true, horizontal stacks flip to vertical below the md breakpoint (768px) */
+    responsive?: boolean;
+}
+/**
+ * Stack - Flexible layout component for arranging children
+ */
+export declare const Stack: React.FC<StackProps>;
+/**
+ * VStack - Vertical stack shorthand
+ */
+export interface VStackProps extends Omit<StackProps, "direction"> {
+}
+export declare const VStack: React.FC<VStackProps>;
+/**
+ * HStack - Horizontal stack shorthand
+ */
+export interface HStackProps extends Omit<StackProps, "direction"> {
+}
+export declare const HStack: React.FC<HStackProps>;
+export default Stack;

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

@@ -0,0 +1,14 @@
+import React from "react";
+export type StatusDotStatus = "online" | "offline" | "away" | "busy" | "warning" | "critical";
+export type StatusDotSize = "sm" | "md" | "lg";
+export interface StatusDotProps extends React.HTMLAttributes<HTMLSpanElement> {
+    /** Status determines the dot color */
+    status?: StatusDotStatus;
+    /** Enable pulse animation for active/critical states */
+    pulse?: boolean;
+    /** Dot size */
+    size?: StatusDotSize;
+    /** Accessible label (rendered as sr-only text) */
+    label?: string;
+}
+export declare const StatusDot: React.ForwardRefExoticComponent<StatusDotProps & React.RefAttributes<HTMLSpanElement>>;

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

@@ -0,0 +1,12 @@
+import * as React from "react";
+export interface SwitchProps {
+    checked?: boolean;
+    defaultChecked?: boolean;
+    onChange?: (checked: boolean) => void;
+    disabled?: boolean;
+    label?: string;
+    id?: string;
+    name?: string;
+    className?: string;
+}
+export declare const Switch: React.ForwardRefExoticComponent<SwitchProps & React.RefAttributes<HTMLButtonElement>>;

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

@@ -0,0 +1,53 @@
+/**
+ * TextHighlight Atom Component
+ *
+ * A styled span component for highlighting text with annotations (questions or notes).
+ * Uses different colors for different annotation types:
+ * - Questions: Blue highlight
+ * - Notes: Yellow highlight
+ */
+import React from "react";
+export type HighlightType = "question" | "note";
+export interface TextHighlightProps {
+    /**
+     * Type of highlight (determines color)
+     */
+    highlightType: HighlightType;
+    /**
+     * Whether the highlight is currently active/focused
+     * @default false
+     */
+    isActive?: boolean;
+    /**
+     * Callback when highlight is clicked
+     */
+    onClick?: () => void;
+    /**
+     * Callback when highlight is hovered
+     */
+    onMouseEnter?: () => void;
+    /**
+     * Callback when hover ends
+     */
+    onMouseLeave?: () => void;
+    /**
+     * Unique ID for the annotation
+     */
+    annotationId?: string;
+    /**
+     * Additional CSS classes
+     */
+    className?: string;
+    /**
+     * Highlighted text content
+     */
+    children: React.ReactNode;
+    /** Declarative event name — emits UI:{action} via eventBus on click */
+    action?: string;
+    /** Declarative hover event — emits UI:{hoverEvent} with { hovered: true/false } */
+    hoverEvent?: string;
+}
+/**
+ * TextHighlight component for rendering highlighted text annotations
+ */
+export declare const TextHighlight: React.FC<TextHighlightProps>;

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

@@ -0,0 +1,5 @@
+import React from "react";
+export interface TextareaProps extends React.TextareaHTMLAttributes<HTMLTextAreaElement> {
+    error?: string;
+}
+export declare const Textarea: React.ForwardRefExoticComponent<TextareaProps & React.RefAttributes<HTMLTextAreaElement>>;

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

@@ -0,0 +1,21 @@
+/**
+ * ThemeSelector - Design theme selector component
+ *
+ * A dropdown/toggle component for switching between design themes.
+ *
+ * @packageDocumentation
+ */
+import React from "react";
+interface ThemeSelectorProps {
+    /** Optional className */
+    className?: string;
+    /** Show as dropdown or buttons */
+    variant?: "dropdown" | "buttons";
+    /** Show labels */
+    showLabels?: boolean;
+}
+/**
+ * ThemeSelector component for switching design themes
+ */
+export declare const ThemeSelector: React.FC<ThemeSelectorProps>;
+export default ThemeSelector;

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

@@ -0,0 +1,33 @@
+/**
+ * ThemeToggle Atom Component
+ *
+ * A button that toggles between light and dark themes.
+ * Uses Sun and Moon icons to indicate current/target theme.
+ *
+ * @packageDocumentation
+ */
+import React from "react";
+export interface ThemeToggleProps {
+    /** Additional CSS classes */
+    className?: string;
+    /** Size variant */
+    size?: "sm" | "md" | "lg";
+    /** Show label text */
+    showLabel?: boolean;
+}
+/**
+ * ThemeToggle component for switching between light and dark modes
+ *
+ * @example
+ * ```tsx
+ * // Basic usage
+ * <ThemeToggle />
+ *
+ * // With label
+ * <ThemeToggle showLabel />
+ *
+ * // Custom size
+ * <ThemeToggle size="lg" />
+ * ```
+ */
+export declare const ThemeToggle: React.FC<ThemeToggleProps>;

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

@@ -0,0 +1,23 @@
+/**
+ * TimeSlotCell
+ *
+ * Calendar time slot atom. Renders a clickable container for a single
+ * time slot that can hold event content via children.
+ */
+import React from "react";
+export interface TimeSlotCellProps {
+    /** Time label for this slot (e.g. "09:00") */
+    time: string;
+    /** Called when the slot is clicked */
+    onClick?: (time: string) => void;
+    /** Additional CSS classes */
+    className?: string;
+    /** Event content placed inside the slot */
+    children?: React.ReactNode;
+    /** Whether this slot contains an event */
+    isOccupied?: boolean;
+}
+export declare function TimeSlotCell({ time, onClick, className, children, isOccupied, }: TimeSlotCellProps): React.JSX.Element;
+export declare namespace TimeSlotCell {
+    var displayName: string;
+}

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

@@ -0,0 +1,18 @@
+import React from "react";
+export type TrendDirection = "up" | "down" | "flat";
+export type TrendIndicatorSize = "sm" | "md" | "lg";
+export interface TrendIndicatorProps extends React.HTMLAttributes<HTMLSpanElement> {
+    /** Numeric value to display (e.g., 12.5 for +12.5%) */
+    value?: number;
+    /** Override automatic direction detection (positive=up, negative=down, zero=flat) */
+    direction?: TrendDirection;
+    /** Show the formatted value text next to the arrow */
+    showValue?: boolean;
+    /** Invert color logic (for metrics where down is good, e.g., error rate, bounce rate) */
+    invert?: boolean;
+    /** Accessible label override */
+    label?: string;
+    /** Size of the indicator */
+    size?: TrendIndicatorSize;
+}
+export declare const TrendIndicator: React.ForwardRefExoticComponent<TrendIndicatorProps & React.RefAttributes<HTMLSpanElement>>;

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

@@ -0,0 +1,20 @@
+/**
+ * TypewriterText Atom Component
+ *
+ * Reveals text character-by-character with a blinking cursor
+ * that disappears after the full text has been typed out.
+ */
+import React from "react";
+export interface TypewriterTextProps {
+    /** The full text to reveal */
+    text: string;
+    /** Milliseconds per character */
+    speed?: number;
+    /** Delay before typing starts (ms) */
+    startDelay?: number;
+    /** Additional class names */
+    className?: string;
+    /** Called when the entire text has been revealed */
+    onComplete?: () => void;
+}
+export declare const TypewriterText: React.FC<TypewriterTextProps>;

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

@@ -0,0 +1,57 @@
+/**
+ * Typography Atom Component
+ *
+ * Text elements following the KFlow design system with theme-aware styling.
+ */
+import React from "react";
+export type TypographyVariant = "h1" | "h2" | "h3" | "h4" | "h5" | "h6" | "heading" | "subheading" | "body1" | "body2" | "body" | "caption" | "overline" | "small" | "large" | "label";
+export type TypographySize = "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | "3xl";
+export interface TypographyProps {
+    /** Typography variant */
+    variant?: TypographyVariant;
+    /** Heading level (1-6) - alternative to variant for headings */
+    level?: 1 | 2 | 3 | 4 | 5 | 6;
+    /** Text color */
+    color?: "primary" | "secondary" | "muted" | "error" | "success" | "warning" | "inherit";
+    /** Text alignment */
+    align?: "left" | "center" | "right";
+    /** Font weight override */
+    weight?: "light" | "normal" | "medium" | "semibold" | "bold";
+    /** Font size override */
+    size?: TypographySize;
+    /** Truncate with ellipsis (single line) */
+    truncate?: boolean;
+    /** Overflow handling mode */
+    overflow?: "visible" | "hidden" | "wrap" | "clamp-2" | "clamp-3";
+    /** Custom HTML element */
+    as?: keyof React.JSX.IntrinsicElements;
+    /** HTML id attribute */
+    id?: string;
+    /** Additional class names */
+    className?: string;
+    /** Inline style */
+    style?: React.CSSProperties;
+    /** Text content (alternative to children) */
+    content?: React.ReactNode;
+    /** Children elements */
+    children?: React.ReactNode;
+}
+export declare const Typography: React.FC<TypographyProps>;
+/**
+ * Heading component - convenience wrapper for Typography heading variants
+ */
+export interface HeadingProps extends Omit<TypographyProps, "variant"> {
+    /** Heading level (1-6) */
+    level?: 1 | 2 | 3 | 4 | 5 | 6;
+    /** Override font size */
+    size?: "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | "3xl";
+}
+export declare const Heading: React.FC<HeadingProps>;
+/**
+ * Text component - convenience wrapper for Typography body/caption variants
+ */
+export interface TextProps extends Omit<TypographyProps, "level"> {
+    /** Text variant */
+    variant?: "body" | "body1" | "body2" | "caption" | "small" | "large" | "label" | "overline";
+}
+export declare const Text: React.FC<TextProps>;

package/dist/components/atoms/game/ActionButton.d.ts

@@ -0,0 +1,25 @@
+import * as React from 'react';
+export interface ActionButtonProps {
+    /** Button label text */
+    label: string;
+    /** Icon displayed before the label */
+    icon?: React.ReactNode;
+    /** Cooldown progress from 0 (ready) to 1 (full cooldown) */
+    cooldown?: number;
+    /** Whether the button is disabled */
+    disabled?: boolean;
+    /** Keyboard hotkey to display as a badge */
+    hotkey?: string;
+    /** Size variant */
+    size?: 'sm' | 'md' | 'lg';
+    /** Visual variant */
+    variant?: 'primary' | 'secondary' | 'danger';
+    /** Click handler */
+    onClick?: () => void;
+    /** Additional CSS classes */
+    className?: string;
+}
+export declare function ActionButton({ label, icon, cooldown, disabled, hotkey, size, variant, onClick, className, }: ActionButtonProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace ActionButton {
+    var displayName: string;
+}

package/dist/components/atoms/game/ChoiceButton.d.ts

@@ -0,0 +1,18 @@
+export interface ChoiceButtonProps {
+    /** Choice text content */
+    text: string;
+    /** Choice index number (displayed as prefix) */
+    index?: number;
+    /** Whether the choice is disabled */
+    disabled?: boolean;
+    /** Whether the choice is currently selected */
+    selected?: boolean;
+    /** Click handler */
+    onClick?: () => void;
+    /** Additional CSS classes */
+    className?: string;
+}
+export declare function ChoiceButton({ text, index, disabled, selected, onClick, className, }: ChoiceButtonProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace ChoiceButton {
+    var displayName: string;
+}

package/dist/components/atoms/game/ComboCounter.d.ts

@@ -0,0 +1,16 @@
+export interface ComboCounterProps {
+    /** Current combo count */
+    combo: number;
+    /** Score multiplier */
+    multiplier?: number;
+    /** Current streak */
+    streak?: number;
+    /** Size variant */
+    size?: 'sm' | 'md' | 'lg';
+    /** Additional CSS classes */
+    className?: string;
+}
+export declare function ComboCounter({ combo, multiplier, streak, size, className, }: ComboCounterProps): import("react/jsx-runtime").JSX.Element | null;
+export declare namespace ComboCounter {
+    var displayName: string;
+}

package/dist/components/atoms/game/ControlButton.d.ts

@@ -0,0 +1,31 @@
+import * as React from 'react';
+export interface ControlButtonProps {
+    /** Button label text */
+    label?: string;
+    /** Icon component or emoji */
+    icon?: React.ReactNode;
+    /** Size variant */
+    size?: 'sm' | 'md' | 'lg' | 'xl' | string;
+    /** Shape variant */
+    shape?: 'circle' | 'rounded' | 'square' | string;
+    /** Visual variant */
+    variant?: 'primary' | 'secondary' | 'ghost' | string;
+    /** Called when button is pressed */
+    onPress?: () => void;
+    /** Called when button is released */
+    onRelease?: () => void;
+    /** Declarative event name emitted on press via useEventBus */
+    pressEvent?: string;
+    /** Declarative event name emitted on release via useEventBus */
+    releaseEvent?: string;
+    /** Whether the button is currently pressed */
+    pressed?: boolean;
+    /** Whether the button is disabled */
+    disabled?: boolean;
+    /** Additional CSS classes */
+    className?: string;
+}
+export declare function ControlButton({ label, icon, size, shape, variant, onPress, onRelease, pressEvent, releaseEvent, pressed, disabled, className, }: ControlButtonProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace ControlButton {
+    var displayName: string;
+}

package/dist/components/atoms/game/DamageNumber.d.ts

@@ -0,0 +1,14 @@
+export interface DamageNumberProps {
+    /** The damage/heal value to display */
+    value: number;
+    /** Type of number display */
+    type?: 'damage' | 'heal' | 'crit' | 'miss';
+    /** Size variant */
+    size?: 'sm' | 'md' | 'lg';
+    /** Additional CSS classes */
+    className?: string;
+}
+export declare function DamageNumber({ value, type, size, className, }: DamageNumberProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace DamageNumber {
+    var displayName: string;
+}

package/dist/components/atoms/game/DialogueBubble.d.ts

@@ -0,0 +1,16 @@
+export interface DialogueBubbleProps {
+    /** Speaker name displayed at the top */
+    speaker?: string;
+    /** Dialogue text content */
+    text: string;
+    /** URL for the speaker portrait image */
+    portrait?: string;
+    /** Position of the bubble on screen */
+    position?: 'top' | 'bottom';
+    /** Additional CSS classes */
+    className?: string;
+}
+export declare function DialogueBubble({ speaker, text, portrait, position, className, }: DialogueBubbleProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace DialogueBubble {
+    var displayName: string;
+}

package/dist/components/atoms/game/HealthBar.d.ts

@@ -0,0 +1,18 @@
+export interface HealthBarProps {
+    /** Current health value */
+    current: number;
+    /** Maximum health value */
+    max: number;
+    /** Display format */
+    format?: 'hearts' | 'bar' | 'numeric';
+    /** Size variant */
+    size?: 'sm' | 'md' | 'lg';
+    /** Additional CSS classes */
+    className?: string;
+    /** Animation on change */
+    animated?: boolean;
+}
+export declare function HealthBar({ current, max, format, size, className, animated, }: HealthBarProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace HealthBar {
+    var displayName: string;
+}

package/dist/components/atoms/game/ItemSlot.d.ts

@@ -0,0 +1,25 @@
+import * as React from 'react';
+export interface ItemSlotProps {
+    /** Icon component or emoji */
+    icon?: React.ReactNode;
+    /** Item label */
+    label?: string;
+    /** Stack quantity */
+    quantity?: number;
+    /** Rarity tier affecting border color */
+    rarity?: 'common' | 'uncommon' | 'rare' | 'epic' | 'legendary';
+    /** Whether the slot is empty */
+    empty?: boolean;
+    /** Size variant */
+    size?: 'sm' | 'md' | 'lg';
+    /** Whether the slot is selected */
+    selected?: boolean;
+    /** Click handler */
+    onClick?: () => void;
+    /** Additional CSS classes */
+    className?: string;
+}
+export declare function ItemSlot({ icon, label, quantity, rarity, empty, size, selected, onClick, className, }: ItemSlotProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace ItemSlot {
+    var displayName: string;
+}

package/dist/components/atoms/game/MiniMap.d.ts

@@ -0,0 +1,36 @@
+export interface MiniMapProps {
+    /** Tile data: each tile renders as a 1px dot at (x,y) with the given color */
+    tiles?: {
+        x: number;
+        y: number;
+        color: string;
+    }[];
+    /** Unit positions: each unit renders as a 2px dot */
+    units?: {
+        x: number;
+        y: number;
+        color: string;
+        isPlayer?: boolean;
+    }[];
+    /** Canvas display width in pixels */
+    width?: number;
+    /** Canvas display height in pixels */
+    height?: number;
+    /** Logical map width (for coordinate scaling) */
+    mapWidth?: number;
+    /** Logical map height (for coordinate scaling) */
+    mapHeight?: number;
+    /** Viewport rectangle outline */
+    viewportRect?: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    };
+    /** Additional CSS classes */
+    className?: string;
+}
+export declare function MiniMap({ tiles, units, width, height, mapWidth, mapHeight, viewportRect, className, }: MiniMapProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace MiniMap {
+    var displayName: string;
+}

package/dist/components/atoms/game/ResourceCounter.d.ts

@@ -0,0 +1,21 @@
+import * as React from 'react';
+export interface ResourceCounterProps {
+    /** Icon component or emoji */
+    icon?: React.ReactNode;
+    /** Resource label */
+    label: string;
+    /** Current value */
+    value: number;
+    /** Maximum value */
+    max?: number;
+    /** Accent color class (e.g. 'text-yellow-400') */
+    color?: string;
+    /** Size variant */
+    size?: 'sm' | 'md' | 'lg';
+    /** Additional CSS classes */
+    className?: string;
+}
+export declare function ResourceCounter({ icon, label, value, max, color, size, className, }: ResourceCounterProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace ResourceCounter {
+    var displayName: string;
+}