@almadar/ui 2.14.0 → 2.15.1

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

@@ -0,0 +1,127 @@
+/**
+ * IsometricCanvas
+ *
+ * Core isometric game renderer. Maps to the `game-canvas` pattern.
+ * Adapted from projects/trait-wars/design-system/organisms/IsometricGameCanvas.tsx
+ * with full closed-circuit pattern compliance (className, isLoading, error).
+ *
+ * Architecture:
+ * - 2:1 diamond isometric projection
+ * - Painter's algorithm (tile → feature → unit depth sort)
+ * - Camera pan/zoom with lerp
+ * - Off-screen culling
+ * - Minimap on separate canvas
+ * - Sprite sheet animation via resolveUnitFrame
+ * - Event bus–friendly handlers (onTileClick, onUnitClick, etc.)
+ *
+ * **State categories (closed-circuit compliant):**
+ * - All game data (tiles, units, features, selection, validMoves) → received via props
+ * - Rendering state (viewportSize, RAF, camera lerp, sprite cache) → local only
+ * - Events → emitted via `useEventBus()` for trait integration
+ *
+ * This component is a **pure renderer** — it holds no game logic state.
+ *
+ * @packageDocumentation
+ */
+import * as React from 'react';
+import type { IsometricTile, IsometricUnit, IsometricFeature } from '../../organisms/game/types/isometric';
+import type { ResolvedFrame } from '../../organisms/game/types/spriteAnimation';
+/** Event Contract:
+ *  Emits: UI:TILE_CLICK
+ *  Emits: UI:UNIT_CLICK
+ *  Emits: UI:TILE_HOVER
+ *  Emits: UI:TILE_LEAVE
+ */
+export interface IsometricCanvasProps {
+    /** Additional CSS classes */
+    className?: string;
+    /** Loading state indicator */
+    isLoading?: boolean;
+    /** Error state */
+    error?: Error | null;
+    /** Array of tiles to render */
+    tiles?: IsometricTile[];
+    /** Array of units on the board */
+    units?: IsometricUnit[];
+    /** Array of features (resources, portals, buildings, etc.) */
+    features?: IsometricFeature[];
+    /** Currently selected unit ID */
+    selectedUnitId?: string | null;
+    /** Valid move positions (shown as pulsing green highlights) */
+    validMoves?: Array<{
+        x: number;
+        y: number;
+    }>;
+    /** Attack target positions (shown as pulsing red highlights) */
+    attackTargets?: Array<{
+        x: number;
+        y: number;
+    }>;
+    /** Hovered tile position */
+    hoveredTile?: {
+        x: number;
+        y: number;
+    } | null;
+    onTileClick?: (x: number, y: number) => void;
+    onUnitClick?: (unitId: string) => void;
+    onTileHover?: (x: number, y: number) => void;
+    onTileLeave?: () => void;
+    /** Declarative event: emits UI:{tileClickEvent} with { x, y } on tile click */
+    tileClickEvent?: string;
+    /** Declarative event: emits UI:{unitClickEvent} with { unitId } on unit click */
+    unitClickEvent?: string;
+    /** Declarative event: emits UI:{tileHoverEvent} with { x, y } on tile hover */
+    tileHoverEvent?: string;
+    /** Declarative event: emits UI:{tileLeaveEvent} with {} on tile leave */
+    tileLeaveEvent?: string;
+    /** Render scale (0.4 = 40% zoom) */
+    scale?: number;
+    /** Show debug grid lines and coordinates */
+    debug?: boolean;
+    /** Background image URL tiled behind the isometric grid */
+    backgroundImage?: string;
+    /** Toggle minimap overlay */
+    showMinimap?: boolean;
+    /** Enable camera pan/zoom controls */
+    enableCamera?: boolean;
+    /** Extra scale multiplier for unit draw size. 1 = default. */
+    unitScale?: number;
+    /** Board width in tiles (overrides tile-derived size) */
+    boardWidth?: number;
+    /** Board height in tiles (overrides tile-derived size) */
+    boardHeight?: number;
+    /** Override for the diamond-top Y offset within the tile sprite (default: 374).
+     *  This controls where the flat diamond face sits vertically inside the tile image. */
+    diamondTopY?: number;
+    /** Resolve terrain sprite URL from terrain key */
+    getTerrainSprite?: (terrain: string) => string | undefined;
+    /** Resolve feature sprite URL from feature type key */
+    getFeatureSprite?: (featureType: string) => string | undefined;
+    /** Resolve unit static sprite URL */
+    getUnitSprite?: (unit: IsometricUnit) => string | undefined;
+    /** Resolve animated sprite sheet frame for a unit */
+    resolveUnitFrame?: (unitId: string) => ResolvedFrame | null;
+    /** Additional sprite URLs to preload (e.g., effect sprites) */
+    effectSpriteUrls?: string[];
+    /** Callback to draw canvas effects after units (canvas-specific: cannot be declarative) */
+    onDrawEffects?: (ctx: CanvasRenderingContext2D, animTime: number, getImage: (url: string) => HTMLImageElement | undefined) => void;
+    /** Whether there are active effects — keeps RAF loop alive */
+    hasActiveEffects?: boolean;
+    /** Base URL for remote asset resolution. When set, manifest paths
+     *  are prefixed with this URL. Example: "https://trait-wars-assets.web.app" */
+    assetBaseUrl?: string;
+    /** Manifest mapping entity keys to relative sprite paths.
+     *  Combined with assetBaseUrl to produce full URLs.
+     *  Used as a fallback when inline URLs and callbacks don't resolve. */
+    assetManifest?: {
+        terrains?: Record<string, string>;
+        units?: Record<string, string>;
+        features?: Record<string, string>;
+        effects?: Record<string, string>;
+    };
+}
+export declare function IsometricCanvas({ className, isLoading, error, tiles: _tilesPropRaw, units: _unitsPropRaw, features: _featuresPropRaw, selectedUnitId, validMoves, attackTargets, hoveredTile, onTileClick, onUnitClick, onTileHover, onTileLeave, tileClickEvent, unitClickEvent, tileHoverEvent, tileLeaveEvent, scale, debug, backgroundImage, showMinimap, enableCamera, unitScale, getTerrainSprite, getFeatureSprite, getUnitSprite, resolveUnitFrame, effectSpriteUrls, onDrawEffects, hasActiveEffects, diamondTopY: diamondTopYProp, assetBaseUrl, assetManifest, }: IsometricCanvasProps): React.JSX.Element;
+export declare namespace IsometricCanvas {
+    var displayName: string;
+}
+export default IsometricCanvas;

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

@@ -0,0 +1,52 @@
+export interface PlatformerPlatform {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    type?: 'ground' | 'platform' | 'hazard' | 'goal';
+}
+export interface PlatformerPlayer {
+    x: number;
+    y: number;
+    width?: number;
+    height?: number;
+    vx?: number;
+    vy?: number;
+    grounded?: boolean;
+    facingRight?: boolean;
+}
+export interface PlatformerCanvasProps {
+    /** Player state data */
+    player?: PlatformerPlayer;
+    /** Static platforms / level geometry */
+    platforms?: readonly PlatformerPlatform[];
+    /** World dimensions */
+    worldWidth?: number;
+    worldHeight?: number;
+    /** Canvas display size */
+    canvasWidth?: number;
+    canvasHeight?: number;
+    /** Camera follows player */
+    followCamera?: boolean;
+    /** Background color */
+    bgColor?: string;
+    /** Player sprite image URL */
+    playerSprite?: string;
+    /** Map of platform type to tile sprite URL */
+    tileSprites?: Record<string, string>;
+    /** Background image URL */
+    backgroundImage?: string;
+    /** Base URL prefix for asset URLs */
+    assetBaseUrl?: string;
+    /** Event names for keyboard controls */
+    leftEvent?: string;
+    rightEvent?: string;
+    jumpEvent?: string;
+    stopEvent?: string;
+    /** Additional CSS classes */
+    className?: string;
+}
+export declare function PlatformerCanvas({ player, platforms, worldWidth, worldHeight, canvasWidth, canvasHeight, followCamera, bgColor, playerSprite, tileSprites, backgroundImage, assetBaseUrl, leftEvent, rightEvent, jumpEvent, stopEvent, className, }: PlatformerCanvasProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace PlatformerCanvas {
+    var displayName: string;
+}

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

@@ -0,0 +1,23 @@
+import * as React from 'react';
+export interface ActivePowerup {
+    /** Unique powerup ID */
+    id: string;
+    /** Icon component or emoji */
+    icon?: React.ReactNode;
+    /** Powerup label */
+    label: string;
+    /** Remaining time in seconds */
+    remainingTime?: number;
+}
+export interface PowerupSlotsProps {
+    /** Array of active powerups */
+    active: ActivePowerup[];
+    /** Maximum number of powerup slots */
+    maxSlots?: number;
+    /** Additional CSS classes */
+    className?: string;
+}
+export declare function PowerupSlots({ active, maxSlots, className, }: PowerupSlotsProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace PowerupSlots {
+    var displayName: string;
+}

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

@@ -0,0 +1,20 @@
+export interface Quest {
+    id: string;
+    title: string;
+    progress: number;
+    maxProgress: number;
+    active?: boolean;
+    completed?: boolean;
+}
+export interface QuestTrackerProps {
+    /** Array of quests to display */
+    quests: Quest[];
+    /** ID of the currently active quest */
+    activeQuestId?: string;
+    /** Additional CSS classes */
+    className?: string;
+}
+export declare function QuestTracker({ quests, activeQuestId, className, }: QuestTrackerProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace QuestTracker {
+    var displayName: string;
+}

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

@@ -0,0 +1,23 @@
+import * as React from 'react';
+export interface ResourceBarResource {
+    /** Icon for the resource */
+    icon?: React.ReactNode;
+    /** Resource name */
+    label: string;
+    /** Current amount */
+    value: number;
+    /** Maximum amount (displays as bar if provided) */
+    max?: number;
+}
+export interface ResourceBarProps {
+    /** Resources to display */
+    resources: ResourceBarResource[];
+    /** Size variant */
+    size?: 'sm' | 'md' | 'lg';
+    /** Additional CSS classes */
+    className?: string;
+}
+export declare function ResourceBar({ resources, size, className, }: ResourceBarProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace ResourceBar {
+    var displayName: string;
+}

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

@@ -0,0 +1,18 @@
+export interface ScoreBoardProps {
+    /** Current score */
+    score: number;
+    /** All-time high score */
+    highScore?: number;
+    /** Current combo count */
+    combo?: number;
+    /** Score multiplier */
+    multiplier?: number;
+    /** Current level */
+    level?: number;
+    /** Additional CSS classes */
+    className?: string;
+}
+export declare function ScoreBoard({ score, highScore, combo, multiplier, level, className, }: ScoreBoardProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace ScoreBoard {
+    var displayName: string;
+}

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

@@ -0,0 +1,27 @@
+import * as React from 'react';
+export interface StatBadgeProps {
+    /** Stat label */
+    label: string;
+    /** Current value (defaults to 0 if not provided) */
+    value?: number | string;
+    /** Maximum value (for bar/hearts format) */
+    max?: number;
+    /** Data source entity name (for schema config) */
+    source?: string;
+    /** Field name in the source (for schema config) */
+    field?: string;
+    /** Display format */
+    format?: 'number' | 'hearts' | 'bar' | 'text' | string;
+    /** Icon component or emoji */
+    icon?: React.ReactNode;
+    /** Size variant */
+    size?: 'sm' | 'md' | 'lg' | string;
+    /** Visual variant */
+    variant?: 'default' | 'primary' | 'success' | 'warning' | 'danger' | string;
+    /** Additional CSS classes */
+    className?: string;
+}
+export declare function StatBadge({ label, value, max, format, icon, size, variant, className, source: _source, field: _field, }: StatBadgeProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace StatBadge {
+    var displayName: string;
+}

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

@@ -0,0 +1,29 @@
+import * as React from 'react';
+export interface TurnPanelAction {
+    /** Action button label */
+    label: string;
+    /** Icon for the button */
+    icon?: React.ReactNode;
+    /** Event name to emit when clicked */
+    event?: string;
+    /** Whether the action is disabled */
+    disabled?: boolean;
+}
+export interface TurnPanelProps {
+    /** Current turn number */
+    currentTurn: number;
+    /** Maximum number of turns */
+    maxTurns?: number;
+    /** Current phase label */
+    phase?: string;
+    /** Active team name */
+    activeTeam?: string;
+    /** Action buttons to display */
+    actions?: TurnPanelAction[];
+    /** Additional CSS classes */
+    className?: string;
+}
+export declare function TurnPanel({ currentTurn, maxTurns, phase, activeTeam, actions, className, }: TurnPanelProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace TurnPanel {
+    var displayName: string;
+}

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

@@ -0,0 +1,25 @@
+import * as React from 'react';
+export interface UnitCommand {
+    /** Command label */
+    label: string;
+    /** Icon for the command button */
+    icon?: React.ReactNode;
+    /** Event name to emit when clicked */
+    event?: string;
+    /** Whether the command is disabled */
+    disabled?: boolean;
+    /** Keyboard shortcut hint */
+    hotkey?: string;
+}
+export interface UnitCommandBarProps {
+    /** Available commands */
+    commands: UnitCommand[];
+    /** ID of the currently selected unit */
+    selectedUnitId?: string;
+    /** Additional CSS classes */
+    className?: string;
+}
+export declare function UnitCommandBar({ commands, selectedUnitId, className, }: UnitCommandBarProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace UnitCommandBar {
+    var displayName: string;
+}

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

@@ -0,0 +1,30 @@
+/**
+ * Game Molecule Components
+ *
+ * Composed components for game UI patterns.
+ *
+ * @packageDocumentation
+ */
+export { DPad, type DPadProps, type DPadDirection } from './DPad';
+export { ActionButtons, type ActionButtonsProps, type ActionButtonConfig } from './ActionButtons';
+export { StatBadge, type StatBadgeProps } from './StatBadge';
+export { InventoryGrid, type InventoryGridProps, type InventoryGridItem } from './InventoryGrid';
+export { QuestTracker, type QuestTrackerProps, type Quest } from './QuestTracker';
+export { CraftingRecipe, type CraftingRecipeProps, type CraftingIngredient } from './CraftingRecipe';
+export { PowerupSlots, type PowerupSlotsProps, type ActivePowerup } from './PowerupSlots';
+export { GameCanvas2D, type GameCanvas2DProps } from './GameCanvas2D';
+export { HealthPanel, type HealthPanelProps } from './HealthPanel';
+export { ScoreBoard, type ScoreBoardProps } from './ScoreBoard';
+export { ResourceBar, type ResourceBarProps, type ResourceBarResource } from './ResourceBar';
+export { TurnPanel, type TurnPanelProps, type TurnPanelAction } from './TurnPanel';
+export { EnemyPlate, type EnemyPlateProps, type EnemyPlateEffect } from './EnemyPlate';
+export { UnitCommandBar, type UnitCommandBarProps, type UnitCommand } from './UnitCommandBar';
+export { GameHud, type GameHudProps, type GameHudStat, type GameHudElement } from './GameHud';
+export { DialogueBox, type DialogueBoxProps, type DialogueNode, type DialogueChoice } from './DialogueBox';
+export { CombatLog, type CombatLogProps, type CombatEvent, type CombatLogEventType } from './CombatLog';
+export { InventoryPanel, type InventoryPanelProps, type InventoryItem } from './InventoryPanel';
+export { GameMenu, type GameMenuProps, type MenuOption } from './GameMenu';
+export { GameOverScreen, type GameOverScreenProps, type GameOverStat, type GameOverAction } from './GameOverScreen';
+export { PlatformerCanvas, type PlatformerCanvasProps, type PlatformerPlatform, type PlatformerPlayer } from './PlatformerCanvas';
+export { IsometricCanvas, type IsometricCanvasProps } from './IsometricCanvas';
+export type { IsometricTile, IsometricUnit, IsometricFeature } from '../../organisms/game/types/isometric';

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

@@ -0,0 +1,59 @@
+export { ErrorBoundary, type ErrorBoundaryProps } from './ErrorBoundary';
+export { FormField, type FormFieldProps } from './FormField';
+export { EmptyState, type EmptyStateProps } from './EmptyState';
+export { LoadingState, type LoadingStateProps } from './LoadingState';
+export { ErrorState, type ErrorStateProps } from './ErrorState';
+export { Skeleton, type SkeletonProps, type SkeletonVariant } from './Skeleton';
+export { Accordion, type AccordionProps, type AccordionItem } from './Accordion';
+export { Alert, type AlertProps, type AlertVariant } from './Alert';
+export { Breadcrumb, type BreadcrumbProps, type BreadcrumbItem } from './Breadcrumb';
+export { ButtonGroup, type ButtonGroupProps } from './ButtonGroup';
+export { FilterGroup, type FilterGroupProps, type FilterDefinition } from './FilterGroup';
+export { Card as ActionCard, type CardProps as ActionCardProps, type CardAction } from './Card';
+export { Container, type ContainerProps } from './Container';
+export { Flex, type FlexProps } from './Flex';
+export { FloatingActionButton, type FloatingActionButtonProps } from './FloatingActionButton';
+export { Grid, type GridProps } from './Grid';
+export { InputGroup, type InputGroupProps } from './InputGroup';
+export { Menu, type MenuProps, type MenuItem } from './Menu';
+export { Modal, type ModalProps, type ModalSize } from './Modal';
+export { Pagination, type PaginationProps } from './Pagination';
+export { Popover, type PopoverProps } from './Popover';
+export { RelationSelect, type RelationSelectProps, type RelationOption } from './RelationSelect';
+export { SearchInput, type SearchInputProps } from './SearchInput';
+export { SidePanel, type SidePanelProps } from './SidePanel';
+export { SimpleGrid, type SimpleGridProps } from './SimpleGrid';
+export { Tabs, type TabsProps, type TabItem } from './Tabs';
+export { Toast, type ToastProps, type ToastVariant } from './Toast';
+export { Tooltip, type TooltipProps } from './Tooltip';
+export { Drawer, type DrawerProps, type DrawerPosition, type DrawerSize } from './Drawer';
+export { WizardProgress, type WizardProgressProps, type WizardProgressStep } from './WizardProgress';
+export { WizardNavigation, type WizardNavigationProps } from './WizardNavigation';
+export { MarkdownContent, type MarkdownContentProps } from './markdown/MarkdownContent';
+export { CodeBlock, type CodeBlockProps } from './markdown/CodeBlock';
+export { QuizBlock, type QuizBlockProps } from './QuizBlock';
+export { ScaledDiagram, type ScaledDiagramProps } from './ScaledDiagram';
+export { CalendarGrid, type CalendarGridProps, type CalendarEvent } from './CalendarGrid';
+export { RepeatableFormSection, type RepeatableFormSectionProps, type RepeatableItem } from './RepeatableFormSection';
+export { ViolationAlert, type ViolationAlertProps, type ViolationRecord } from './ViolationAlert';
+export { FormSectionHeader, type FormSectionHeaderProps } from './FormSectionHeader';
+export { FlipCard, type FlipCardProps } from './FlipCard';
+export { DateRangeSelector, type DateRangeSelectorProps, type DateRangeSelectorOption } from './DateRangeSelector';
+export { ChartLegend, type ChartLegendProps, type ChartLegendItem } from './ChartLegend';
+export { LineChart, type LineChartProps, type ChartDataPoint } from './LineChart';
+export { ProgressDots, type ProgressDotsProps, type DotState, type DotSize } from './ProgressDots';
+export * from './game';
+export { GraphView, type GraphViewProps, type GraphViewNode, type GraphViewEdge } from './GraphView';
+export { MapView, type MapViewProps, type MapMarkerData } from './MapView';
+export { NumberStepper, type NumberStepperProps, type NumberStepperSize } from './NumberStepper';
+export { StarRating, type StarRatingProps, type StarRatingSize, type StarRatingPrecision } from './StarRating';
+export { UploadDropZone, type UploadDropZoneProps } from './UploadDropZone';
+export { Lightbox, type LightboxProps, type LightboxImage } from './Lightbox';
+export { DataGrid, type DataGridProps, type DataGridField, type DataGridItemAction } from './DataGrid';
+export { DataList, type DataListProps, type DataListField, type DataListItemAction } from './DataList';
+export { StatDisplay, type StatDisplayProps } from './StatDisplay';
+export { Meter, type MeterProps, type MeterVariant, type MeterThreshold, type MeterAction } from './Meter';
+export { SwipeableRow, type SwipeableRowProps, type SwipeAction } from './SwipeableRow';
+export { SortableList, type SortableListProps } from './SortableList';
+export { Carousel, type CarouselProps } from './Carousel';
+export { PullToRefresh, type PullToRefreshProps } from './PullToRefresh';

package/dist/components/molecules/markdown/CodeBlock.d.ts

@@ -0,0 +1,25 @@
+/**
+ * CodeBlock Molecule Component
+ *
+ * A syntax-highlighted code block with copy-to-clipboard functionality.
+ * Preserves scroll position during re-renders.
+ *
+ * Event Contract:
+ * - Emits: UI:COPY_CODE { language, success }
+ */
+import React from 'react';
+export interface CodeBlockProps {
+    /** The code content to display */
+    code: string;
+    /** Programming language for syntax highlighting */
+    language?: string;
+    /** Show the copy button */
+    showCopyButton?: boolean;
+    /** Show the language badge */
+    showLanguageBadge?: boolean;
+    /** Maximum height before scrolling */
+    maxHeight?: string;
+    /** Additional CSS classes */
+    className?: string;
+}
+export declare const CodeBlock: React.NamedExoticComponent<CodeBlockProps>;

package/dist/components/molecules/markdown/MarkdownContent.d.ts

@@ -0,0 +1,26 @@
+/**
+ * MarkdownContent Molecule Component
+ *
+ * Renders markdown content with support for GFM (GitHub Flavored Markdown)
+ * and math equations (KaTeX). Handles inline code only — fenced code blocks
+ * should be parsed out and rendered with CodeBlock component.
+ *
+ * Event Contract:
+ * - No events emitted (display-only component)
+ * - entityAware: false
+ *
+ * NOTE: react-markdown's `components` override API requires native HTML
+ * elements — this is the same library-boundary exception as `<iframe>` in
+ * DocumentViewer and `<svg>` in JazariStateMachine/StateMachineView.
+ */
+import React from 'react';
+import 'katex/dist/katex.min.css';
+export interface MarkdownContentProps {
+    /** The markdown content to render */
+    content: string;
+    /** Text direction */
+    direction?: 'rtl' | 'ltr';
+    /** Additional CSS classes */
+    className?: string;
+}
+export declare const MarkdownContent: React.NamedExoticComponent<MarkdownContentProps>;

package/dist/components/molecules/markdown/index.d.ts

@@ -0,0 +1,2 @@
+export { MarkdownContent, type MarkdownContentProps } from './MarkdownContent';
+export { CodeBlock, type CodeBlockProps } from './CodeBlock';

package/dist/components/organisms/CardGrid.d.ts

@@ -0,0 +1,80 @@
+/**
+ * CardGrid Component
+ *
+ * A dumb, responsive grid specifically designed for card layouts.
+ * Uses CSS Grid auto-fit for automatic responsive columns.
+ *
+ * Data comes exclusively from the `entity` prop (injected by the runtime).
+ * All user interactions emit events via useEventBus. Never manages internal state
+ * for pagination, filtering, or search. All state is owned by the trait state machine.
+ */
+import React from 'react';
+import type { EntityDisplayProps } from './types';
+export type CardGridGap = 'none' | 'sm' | 'md' | 'lg' | 'xl';
+/**
+ * Action configuration for card items (schema-driven)
+ */
+export interface CardItemAction {
+    /** Action button label */
+    label: string;
+    /** Event to dispatch on click (schema metadata) */
+    event?: string;
+    /** 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 placement - accepts string for compatibility with generated code */
+    placement?: 'card' | 'footer' | 'row' | string;
+    /** Button variant - accepts string for compatibility with generated code */
+    variant?: 'primary' | 'secondary' | 'ghost' | 'danger' | string;
+}
+/**
+ * Field definition - can be a simple string or object with key/header or name/label
+ */
+export type FieldDef = string | {
+    key?: string;
+    header?: string;
+    name?: string;
+    label?: string;
+};
+export interface CardGridProps extends EntityDisplayProps {
+    /** Minimum width of each card (default: 280px) */
+    minCardWidth?: number;
+    /** Maximum number of columns */
+    maxCols?: 1 | 2 | 3 | 4 | 5 | 6;
+    /** Gap between cards */
+    gap?: CardGridGap;
+    /** Align cards vertically in their cells */
+    alignItems?: 'start' | 'center' | 'end' | 'stretch';
+    /** Children elements (cards) - optional when using entity prop */
+    children?: React.ReactNode;
+    /** Fields to display - required for schema-driven rendering */
+    fields: readonly FieldDef[];
+    /** Alias for fields - backwards compatibility */
+    fieldNames?: readonly string[];
+    /** Alias for fields - backwards compatibility */
+    columns?: readonly FieldDef[];
+    /** Actions for each card item (schema-driven) */
+    itemActions?: readonly CardItemAction[];
+    /** Show total count in pagination */
+    showTotal?: boolean;
+    /** Show avatar/image field on cards */
+    showAvatar?: boolean;
+    /** Visual variant for the card grid */
+    variant?: string;
+    /** Entity field name containing an image URL to display as card thumbnail */
+    imageField?: string;
+}
+/**
+ * CardGrid - Responsive card collection layout
+ *
+ * Can be used in two ways:
+ * 1. With children: <CardGrid><Card>...</Card></CardGrid>
+ * 2. With entity data: <CardGrid entity={tasks} fields={['title', 'status']} />
+ *
+ * All data comes from the `entity` prop. Pagination display hints come from
+ * `page`, `pageSize`, and `totalCount` props (set by the trait via render-ui).
+ */
+export declare const CardGrid: React.FC<CardGridProps>;

package/dist/components/organisms/Chart.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Chart Organism Component
+ *
+ * A data visualization component supporting bar, line, pie, and area chart types.
+ * Composes atoms and molecules for layout, uses CSS variables for theming.
+ *
+ * Orbital Component Interface Compliance:
+ * - Entity binding with auto-fetch when entity is a string
+ * - Event emission via useEventBus (UI:* events)
+ * - isLoading and error state props
+ * - className for external styling
+ */
+import React from "react";
+export type ChartType = "bar" | "line" | "pie" | "area" | "donut";
+export interface ChartDataPoint {
+    label: string;
+    value: number;
+    color?: string;
+}
+export interface ChartSeries {
+    name: string;
+    data: readonly ChartDataPoint[];
+    color?: string;
+}
+export interface ChartAction {
+    label: string;
+    event?: string;
+    navigatesTo?: string;
+    variant?: "primary" | "secondary" | "ghost";
+}
+export interface ChartProps {
+    /** Chart title */
+    title?: string;
+    /** Chart subtitle / description */
+    subtitle?: string;
+    /** Chart type */
+    chartType?: ChartType;
+    /** Data series */
+    series?: readonly ChartSeries[];
+    /** Simple data (single series shorthand) */
+    data?: readonly ChartDataPoint[];
+    /** Chart height in px */
+    height?: number;
+    /** Show legend */
+    showLegend?: boolean;
+    /** Show values on chart */
+    showValues?: boolean;
+    /** Actions for chart interactions */
+    actions?: readonly ChartAction[];
+    /** Entity name for schema-driven auto-fetch */
+    entity?: string;
+    /** Loading state */
+    isLoading?: boolean;
+    /** Error state */
+    error?: Error | null;
+    /** Additional CSS classes */
+    className?: string;
+}
+export declare const Chart: React.FC<ChartProps>;