@almadar/ui 1.0.34 → 2.0.1

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,64 @@
+/**
+ * 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>;
+}
+/**
+ * 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/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/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" | "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/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/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/ScoreDisplay.d.ts

@@ -0,0 +1,21 @@
+import * as React from 'react';
+export interface ScoreDisplayProps {
+    /** Current score value */
+    value: number;
+    /** Label to display before score */
+    label?: string;
+    /** Icon component or emoji */
+    icon?: React.ReactNode;
+    /** Size variant */
+    size?: 'sm' | 'md' | 'lg' | 'xl';
+    /** Additional CSS classes */
+    className?: string;
+    /** Animation on value change */
+    animated?: boolean;
+    /** Number formatting locale */
+    locale?: string;
+}
+export declare function ScoreDisplay({ value, label, icon, size, className, animated, locale, }: ScoreDisplayProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace ScoreDisplay {
+    var displayName: string;
+}

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

@@ -0,0 +1,63 @@
+/**
+ * Sprite Component
+ *
+ * Renders a single frame from a spritesheet with transform support.
+ */
+import React from 'react';
+export interface SpriteProps {
+    /** Spritesheet image URL */
+    spritesheet: string;
+    /** Width of each frame in pixels */
+    frameWidth: number;
+    /** Height of each frame in pixels */
+    frameHeight: number;
+    /** Frame index to display (0-based, left-to-right, top-to-bottom) */
+    frame: number;
+    /** X position in pixels */
+    x: number;
+    /** Y position in pixels */
+    y: number;
+    /** Scale factor (default: 1) */
+    scale?: number;
+    /** Flip horizontally */
+    flipX?: boolean;
+    /** Flip vertically */
+    flipY?: boolean;
+    /** Rotation in degrees */
+    rotation?: number;
+    /** Opacity (0-1) */
+    opacity?: number;
+    /** Z-index for layering */
+    zIndex?: number;
+    /** Number of columns in spritesheet (for frame calculation) */
+    columns?: number;
+    /** Optional className */
+    className?: string;
+    /** Optional onClick handler */
+    onClick?: () => void;
+    /** Declarative event name emitted on click via useEventBus */
+    action?: string;
+}
+/**
+ * Sprite component for rendering spritesheet frames
+ *
+ * @example
+ * ```tsx
+ * <Sprite
+ *   spritesheet="/sprites/player.png"
+ *   frameWidth={32}
+ *   frameHeight={32}
+ *   frame={currentFrame}
+ *   x={player.x}
+ *   y={player.y}
+ *   flipX={player.facingLeft}
+ *   scale={2}
+ * />
+ * ```
+ */
+export declare function Sprite({ spritesheet, frameWidth, frameHeight, frame, x, y, scale, flipX, flipY, rotation, opacity, zIndex, columns, className, onClick, action, }: SpriteProps): React.JSX.Element;
+/**
+ * Canvas-based sprite renderer for better performance in game loops
+ */
+export declare function drawSprite(ctx: CanvasRenderingContext2D, image: HTMLImageElement, props: Omit<SpriteProps, 'spritesheet' | 'className' | 'onClick'>): void;
+export default Sprite;

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

@@ -0,0 +1,31 @@
+/**
+ * StateIndicator Component
+ *
+ * Displays a visual indicator for a game entity's current state.
+ * Generic — not tied to any specific game. Projects can extend
+ * the state styles via the `stateStyles` prop.
+ */
+import React from 'react';
+export interface StateStyle {
+    icon: string;
+    bgClass: string;
+}
+export interface StateIndicatorProps {
+    /** The current state name */
+    state: string;
+    /** Optional label override (defaults to capitalized state name) */
+    label?: string;
+    /** Size variant */
+    size?: 'sm' | 'md' | 'lg';
+    /** Whether to show pulse animation on non-idle states */
+    animated?: boolean;
+    /** Custom state styles to extend/override defaults */
+    stateStyles?: Record<string, StateStyle>;
+    /** Additional CSS classes */
+    className?: string;
+}
+export declare function StateIndicator({ state, label, size, animated, stateStyles, className, }: StateIndicatorProps): React.JSX.Element;
+export declare namespace StateIndicator {
+    var displayName: string;
+}
+export default StateIndicator;

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

@@ -0,0 +1,12 @@
+/**
+ * Game Atom Components
+ *
+ * Basic building blocks for game UI.
+ *
+ * @packageDocumentation
+ */
+export { HealthBar, type HealthBarProps } from './HealthBar';
+export { ScoreDisplay, type ScoreDisplayProps } from './ScoreDisplay';
+export { ControlButton, type ControlButtonProps } from './ControlButton';
+export { Sprite, drawSprite, type SpriteProps } from './Sprite';
+export { StateIndicator, type StateIndicatorProps, type StateStyle } from './StateIndicator';

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

@@ -0,0 +1,27 @@
+export { Button, type ButtonProps } from "./Button";
+export { Input, type InputProps } from "./Input";
+export { Label, type LabelProps } from "./Label";
+export { Textarea, type TextareaProps } from "./Textarea";
+export { Select, type SelectProps, type SelectOption } from "./Select";
+export { Checkbox, type CheckboxProps } from "./Checkbox";
+export { Card, CardHeader, CardTitle, CardContent, CardBody, CardFooter, type CardProps, } from "./Card";
+export { Badge, type BadgeProps, type BadgeVariant } from "./Badge";
+export { Spinner, type SpinnerProps } from "./Spinner";
+export { Avatar, type AvatarProps, type AvatarSize, type AvatarStatus, } from "./Avatar";
+export { Box, type BoxProps, type BoxPadding, type BoxMargin, type BoxBg, type BoxRounded, type BoxShadow, } from "./Box";
+export { Center, type CenterProps } from "./Center";
+export { Divider, type DividerProps, type DividerOrientation } from "./Divider";
+export { Icon, type IconProps, type IconSize, type IconAnimation, } from "./Icon";
+export { ProgressBar, type ProgressBarProps, type ProgressBarVariant, type ProgressBarColor, } from "./ProgressBar";
+export { Radio, type RadioProps } from "./Radio";
+export { Switch, type SwitchProps } from "./Switch";
+export { Spacer, type SpacerProps, type SpacerSize } from "./Spacer";
+export { Stack, VStack, HStack, type StackProps, type VStackProps, type HStackProps, type StackDirection, type StackGap, type StackAlign, type StackJustify, } from "./Stack";
+export { TextHighlight, type TextHighlightProps, type HighlightType, } from "./TextHighlight";
+export { Typography, Heading, Text, type TypographyProps, type TypographyVariant, type HeadingProps, type TextProps, } from "./Typography";
+export { ThemeToggle, type ThemeToggleProps } from "./ThemeToggle";
+export { ThemeSelector } from "./ThemeSelector";
+export { Overlay, type OverlayProps } from "./Overlay";
+export { ConditionalWrapper, type ConditionalWrapperProps, type ConditionalContext, } from "./ConditionalWrapper";
+export { LawReferenceTooltip, type LawReferenceTooltipProps, type LawReference, } from "./LawReferenceTooltip";
+export * from "./game";

package/dist/components/index.css

@@ -1,4 +1,4 @@
-/* ../../node_modules/.pnpm/katex@0.16.28/node_modules/katex/dist/katex.min.css */
+/* node_modules/.pnpm/katex@0.16.33/node_modules/katex/dist/katex.min.css */
 @font-face {
   font-display: block;
   font-family: KaTeX_AMS;
@@ -213,7 +213,7 @@
   border-color: currentColor;
 }
 .katex .katex-version:after {
-  content: "0.16.28";
+  content: "0.16.33";
 }
 .katex .katex-mathml {
   clip: rect(1px, 1px, 1px, 1px);
@@ -988,6 +988,15 @@
 .katex svg {
   fill: currentColor;
   stroke: currentColor;
+  display: block;
+  height: inherit;
+  position: absolute;
+  width: 100%;
+}
+.katex svg path {
+  stroke: none;
+}
+.katex svg {
   fill-rule: nonzero;
   fill-opacity: 1;
   stroke-width: 1;
@@ -997,13 +1006,6 @@
   stroke-dasharray: none;
   stroke-dashoffset: 0;
   stroke-opacity: 1;
-  display: block;
-  height: inherit;
-  position: absolute;
-  width: 100%;
-}
-.katex svg path {
-  stroke: none;
 }
 .katex img {
   border-style: none;