@almadar/ui 2.13.3 → 2.15.0

package/dist/components/templates/GameCanvas3DWorldMapTemplate.d.ts

@@ -0,0 +1,96 @@
+/**
+ * GameCanvas3DWorldMapTemplate
+ *
+ * Pure declarative template wrapper for 3D world map.
+ * No hooks, no callbacks, no local state -- just entity data and config props.
+ *
+ * Page: WorldMap3DPage
+ * Entity: WorldMap3D
+ * ViewType: detail
+ *
+ * Events Emitted:
+ * - TILE_SELECTED - When a tile is clicked ({ tileId, x, z, type })
+ * - UNIT_SELECTED - When a unit is clicked ({ unitId, x, z, name })
+ * - FEATURE_SELECTED - When a feature is clicked ({ featureId, x, z, type })
+ * - TILE_HOVERED - When hovering over a tile ({ tileId, x, z })
+ * - TILE_LEAVE - When leaving a tile ({})
+ * - CAMERA_CHANGED - When camera position changes ({ position })
+ *
+ * @packageDocumentation
+ */
+import React from 'react';
+import type { IsometricTile, IsometricUnit, IsometricFeature } from '../organisms/game/types/isometric';
+import type { TemplateProps } from './types';
+export interface WorldMap3DEntity {
+    /** Map tiles */
+    tiles: IsometricTile[];
+    /** Units on the map */
+    units: IsometricUnit[];
+    /** Map features (castles, resources, etc.) */
+    features: IsometricFeature[];
+    /** Entity ID */
+    id: string;
+    /** Entity name */
+    name?: string;
+}
+export interface GameCanvas3DWorldMapTemplateProps extends TemplateProps<WorldMap3DEntity> {
+    /** 3D camera mode */
+    cameraMode?: 'isometric' | 'perspective' | 'top-down';
+    /** Show grid helper */
+    showGrid?: boolean;
+    /** Show coordinate overlay */
+    showCoordinates?: boolean;
+    /** Show tile info on hover */
+    showTileInfo?: boolean;
+    /** Enable shadows */
+    shadows?: boolean;
+    /** Background color */
+    backgroundColor?: string;
+    /** Event name for tile clicks */
+    tileClickEvent?: string;
+    /** Event name for unit clicks */
+    unitClickEvent?: string;
+    /** Event name for feature clicks */
+    featureClickEvent?: string;
+    /** Event name for tile hover */
+    tileHoverEvent?: string;
+    /** Event name for tile leave */
+    tileLeaveEvent?: string;
+    /** Event name for camera changes */
+    cameraChangeEvent?: string;
+    /** Exit/back event name */
+    exitEvent?: string;
+    /** Currently selected unit ID */
+    selectedUnitId?: string | null;
+    /** Valid move positions for selected unit */
+    validMoves?: Array<{
+        x: number;
+        z: number;
+    }>;
+    /** Attack target positions */
+    attackTargets?: Array<{
+        x: number;
+        z: number;
+    }>;
+}
+/**
+ * GameCanvas3DWorldMapTemplate Component
+ *
+ * Template for 3D world map view.
+ *
+ * @example
+ * ```tsx
+ * <GameCanvas3DWorldMapTemplate
+ *     entity={worldMapEntity}
+ *     cameraMode="isometric"
+ *     tileClickEvent="SELECT_TILE"
+ *     unitClickEvent="SELECT_UNIT"
+ *     showCoordinates={true}
+ * />
+ * ```
+ */
+export declare function GameCanvas3DWorldMapTemplate({ entity, cameraMode, showGrid, showCoordinates, showTileInfo, shadows, backgroundColor, tileClickEvent, unitClickEvent, featureClickEvent, tileHoverEvent, tileLeaveEvent, cameraChangeEvent, selectedUnitId, validMoves, attackTargets, className, }: GameCanvas3DWorldMapTemplateProps): React.JSX.Element | null;
+export declare namespace GameCanvas3DWorldMapTemplate {
+    var displayName: string;
+}
+export default GameCanvas3DWorldMapTemplate;

package/dist/components/templates/GameShell.d.ts

@@ -0,0 +1,34 @@
+/**
+ * GameShell
+ *
+ * A full-screen layout wrapper for game applications.
+ * Replaces DashboardLayout for game clients — no sidebar nav, just full-viewport
+ * rendering with an optional HUD overlay bar.
+ *
+ * Wrap game page content directly as children:
+ *   <GameShell appName="TraitWars">
+ *     <WorldMapPage />
+ *   </GameShell>
+ *
+ * @generated pattern — can be customised per-game via props
+ */
+import React from "react";
+export interface GameShellProps {
+    /** Application / game title shown in the HUD bar */
+    appName?: string;
+    /** Optional HUD content rendered above the main area */
+    hud?: React.ReactNode;
+    /** Extra class name on the root container */
+    className?: string;
+    /** Whether to show the minimal top bar (default: true) */
+    showTopBar?: boolean;
+    /** Game content rendered inside the full-screen area */
+    children?: React.ReactNode;
+}
+/**
+ * Full-viewport game shell layout.
+ *
+ * Renders children inside a full-height flex container.
+ * An optional top bar shows the game title and can host HUD widgets.
+ */
+export declare const GameShell: React.FC<GameShellProps>;

package/dist/components/templates/GameTemplate.d.ts

@@ -0,0 +1,36 @@
+/**
+ * GameTemplate
+ *
+ * A presentational template for game applications.
+ * Includes a main game canvas/area, HUD overlay, and an optional debug sidebar.
+ * **Atomic Design**: Composed using Box, Typography, and Layout molecules/atoms.
+ */
+import React from "react";
+import type { TemplateProps } from "./types";
+interface GameEntity {
+    id: string;
+    title?: string;
+}
+export interface GameTemplateProps extends TemplateProps<GameEntity> {
+    /** Title of the game */
+    title?: string;
+    /** The main game canvas or content */
+    children: React.ReactNode;
+    /** HUD overlay content (scores, health, etc.) */
+    hud?: React.ReactNode;
+    /** Debug panel content */
+    debugPanel?: React.ReactNode;
+    /** Whether the debug panel is visible */
+    showDebugPanel?: boolean;
+    /** Game controls */
+    controls?: {
+        onPlay?: () => void;
+        onPause?: () => void;
+        onReset?: () => void;
+        isPlaying?: boolean;
+    };
+    /** Additional class name */
+    className?: string;
+}
+export declare const GameTemplate: React.FC<GameTemplateProps>;
+export {};

package/dist/components/templates/GenericAppTemplate.d.ts

@@ -0,0 +1,30 @@
+/**
+ * GenericAppTemplate
+ *
+ * A simple, generic template for any application.
+ * Includes a header with title and actions, and a main content area.
+ * **Atomic Design**: Composed using Box, Typography, and Button atoms.
+ */
+import React from "react";
+import type { TemplateProps } from "./types";
+interface GenericAppEntity {
+    id: string;
+    title?: string;
+    subtitle?: string;
+}
+export interface GenericAppTemplateProps extends TemplateProps<GenericAppEntity> {
+    /** Page title */
+    title: string;
+    /** Subtitle or description */
+    subtitle?: string;
+    /** Main content */
+    children: React.ReactNode;
+    /** Header actions (buttons, links) */
+    headerActions?: React.ReactNode;
+    /** Footer content */
+    footer?: React.ReactNode;
+    /** Additional class name */
+    className?: string;
+}
+export declare const GenericAppTemplate: React.FC<GenericAppTemplateProps>;
+export {};

package/dist/components/templates/WorldMapTemplate.d.ts

@@ -0,0 +1,29 @@
+/**
+ * WorldMapTemplate
+ *
+ * Thin declarative wrapper around WorldMapBoard organism.
+ * All game logic (hero movement, encounters, hex conversion, etc.) lives in WorldMapBoard.
+ *
+ * Compliant with Almadar_Templates.md: no hooks, no callbacks, entity-only data flow.
+ *
+ * @packageDocumentation
+ */
+import React from 'react';
+import type { TemplateProps } from './types';
+import type { WorldMapEntity } from '../organisms/game/WorldMapBoard';
+export type { WorldMapEntity, MapHero, MapHex, WorldMapSlotContext, } from '../organisms/game/WorldMapBoard';
+export interface WorldMapTemplateProps extends TemplateProps<WorldMapEntity> {
+    /** Canvas render scale */
+    scale?: number;
+    /** Unit draw-size multiplier */
+    unitScale?: number;
+    /** Override for the diamond-top Y offset within tile sprites (default: 374). */
+    diamondTopY?: number;
+    /** Allow selecting / moving ALL heroes (including enemy). For testing. */
+    allowMoveAllHeroes?: boolean;
+}
+export declare function WorldMapTemplate({ entity, scale, unitScale, diamondTopY, allowMoveAllHeroes, className, }: WorldMapTemplateProps): React.JSX.Element;
+export declare namespace WorldMapTemplate {
+    var displayName: string;
+}
+export default WorldMapTemplate;

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

@@ -0,0 +1,10 @@
+export type { TemplateProps } from './types';
+export { DashboardLayout, type DashboardLayoutProps, type NavItem } from './DashboardLayout';
+export { AuthLayout, type AuthLayoutProps } from './AuthLayout';
+export { CounterTemplate, type CounterTemplateProps, type CounterSize, type CounterVariant } from './CounterTemplate';
+export { GameTemplate, type GameTemplateProps } from './GameTemplate';
+export { GenericAppTemplate, type GenericAppTemplateProps } from './GenericAppTemplate';
+export { GameShell, type GameShellProps } from './GameShell';
+export { BattleTemplate, type BattleTemplateProps, type BattleEntity, type BattlePhase, type BattleUnit, type BattleTile, type BattleSlotContext, } from './BattleTemplate';
+export { CastleTemplate, type CastleTemplateProps, type CastleEntity, type CastleSlotContext, } from './CastleTemplate';
+export { WorldMapTemplate, type WorldMapTemplateProps, type WorldMapEntity, type MapHero, type MapHex, type WorldMapSlotContext, } from './WorldMapTemplate';

package/dist/components/templates/types.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Base template types for Almadar UI.
+ *
+ * All templates MUST extend `TemplateProps<E>` to enforce entity-only data flow
+ * and JSON round-trip compatibility with the flattener pipeline.
+ *
+ * The compiler passes `entity` as `E[]` (array from data store), so
+ * TemplateProps accepts the same union as EntityDisplayProps.
+ *
+ * @see docs/Almadar_Templates.md
+ */
+/** Base props for all templates — enforces entity-only data flow. */
+export interface TemplateProps<E extends {
+    id: string;
+} = {
+    id: string;
+}> {
+    /** Entity data — single object, array from compiler, or string entity name */
+    entity?: string | E | readonly E[];
+    /** External styling override */
+    className?: string;
+}

package/dist/context/DesignThemeContext.d.ts

@@ -0,0 +1,21 @@
+/** @deprecated Use ThemeDefinition from ThemeContext */
+export type DesignTheme = string;
+/**
+ * @deprecated Use ThemeProvider from ThemeContext instead
+ */
+export declare const DesignThemeProvider: import("react").FC<import("./ThemeContext").ThemeProviderProps>;
+/**
+ * @deprecated Use useTheme from ThemeContext instead
+ *
+ * This wrapper provides backward compatibility with the old API.
+ */
+export declare function useDesignTheme(): {
+    designTheme: string;
+    setDesignTheme: (theme: string) => void;
+    availableThemes: string[];
+};
+declare const _default: {
+    DesignThemeProvider: import("react").FC<import("./ThemeContext").ThemeProviderProps>;
+    useDesignTheme: typeof useDesignTheme;
+};
+export default _default;

package/dist/{ThemeContext-D9xUORq5.d.ts → context/ThemeContext.d.ts}

@@ -1,5 +1,3 @@
-import React__default from 'react';
-
 /**
  * Unified ThemeContext - Single provider for theme and color mode
  *
@@ -10,13 +8,13 @@ import React__default from 'react';
  *
  * @packageDocumentation
  */
-
+import React from "react";
 /** Color mode preference */
-type ColorMode = "light" | "dark" | "system";
+export type ColorMode = "light" | "dark" | "system";
 /** Resolved color mode (what's actually applied) */
-type ResolvedMode = "light" | "dark";
+export type ResolvedMode = "light" | "dark";
 /** Theme definition */
-interface ThemeDefinition {
+export interface ThemeDefinition {
     /** Theme identifier (e.g., "ocean", "wireframe") */
     name: string;
     /** Display name for UI (e.g., "Ocean Blue") */
@@ -27,7 +25,7 @@ interface ThemeDefinition {
     hasDarkMode?: boolean;
 }
 /** Built-in themes available in the design system */
-declare const BUILT_IN_THEMES: ThemeDefinition[];
+export declare const BUILT_IN_THEMES: ThemeDefinition[];
 /** Theme context value */
 interface ThemeContextValue {
     /** Current theme name */
@@ -47,9 +45,9 @@ interface ThemeContextValue {
     /** The full theme string applied to data-theme (e.g., "ocean-light") */
     appliedTheme: string;
 }
-declare const ThemeContext: React__default.Context<ThemeContextValue | undefined>;
-interface ThemeProviderProps {
-    children: React__default.ReactNode;
+declare const ThemeContext: React.Context<ThemeContextValue | undefined>;
+export interface ThemeProviderProps {
+    children: React.ReactNode;
     /** Available themes (will be merged with built-in themes) */
     themes?: readonly ThemeDefinition[] | ThemeDefinition[];
     /** Default theme name */
@@ -57,7 +55,7 @@ interface ThemeProviderProps {
     /** Default color mode */
     defaultMode?: ColorMode;
     /** Optional target element ref — when provided, theme attributes are applied to this element instead of document.documentElement */
-    targetRef?: React__default.RefObject<HTMLElement>;
+    targetRef?: React.RefObject<HTMLElement>;
 }
 /**
  * Unified ThemeProvider component
@@ -76,7 +74,7 @@ interface ThemeProviderProps {
  * </ThemeProvider>
  * ```
  */
-declare const ThemeProvider: React__default.FC<ThemeProviderProps>;
+export declare const ThemeProvider: React.FC<ThemeProviderProps>;
 /**
  * Hook for accessing theme context
  *
@@ -99,7 +97,8 @@ declare const ThemeProvider: React__default.FC<ThemeProviderProps>;
  * </select>
  * ```
  */
-declare function useTheme(): ThemeContextValue;
-type DesignTheme = ThemeDefinition;
-
-export { BUILT_IN_THEMES as B, type ColorMode as C, type DesignTheme as D, type ResolvedMode as R, type ThemeProviderProps as T, ThemeContext as a, type ThemeDefinition as b, ThemeProvider as c, useTheme as u };
+export declare function useTheme(): ThemeContextValue;
+export type Theme = ColorMode;
+export type ResolvedTheme = ResolvedMode;
+export type DesignTheme = ThemeDefinition;
+export default ThemeContext;

package/dist/context/UISlotContext.d.ts

@@ -0,0 +1,75 @@
+/**
+ * UISlotContext
+ *
+ * React context for providing the UI Slot Manager throughout the application.
+ * Traits use this context to render content into slots via render_ui effects.
+ *
+ * Usage:
+ * ```tsx
+ * // In App.tsx or layout
+ * <UISlotProvider>
+ *   <App />
+ * </UISlotProvider>
+ *
+ * // In trait hooks or components
+ * const { render, clear } = useUISlots();
+ * render({ target: 'modal', pattern: 'form-section', props: {...} });
+ * ```
+ *
+ * @packageDocumentation
+ */
+import React from 'react';
+import { type UISlotManager, type UISlot, type SlotContent, type RenderUIConfig, type SlotAnimation, type SlotChangeCallback } from '../hooks/useUISlots';
+/**
+ * Context for the UI Slot Manager
+ */
+declare const UISlotContext: React.Context<UISlotManager | null>;
+export interface UISlotProviderProps {
+    children: React.ReactNode;
+}
+/**
+ * Provider component that creates and provides the UI Slot Manager.
+ *
+ * Must wrap any components that use traits with render_ui effects.
+ */
+export declare function UISlotProvider({ children }: UISlotProviderProps): React.ReactElement;
+/**
+ * Hook to access the UI Slot Manager.
+ *
+ * Must be used within a UISlotProvider.
+ *
+ * @throws Error if used outside of UISlotProvider
+ *
+ * @example
+ * ```tsx
+ * function MyTraitHook() {
+ *   const { render, clear } = useUISlots();
+ *
+ *   const showModal = () => {
+ *     render({
+ *       target: 'modal',
+ *       pattern: 'form-section',
+ *       props: { title: 'Create Item' },
+ *     });
+ *   };
+ *
+ *   const closeModal = () => {
+ *     clear('modal');
+ *   };
+ *
+ *   return { showModal, closeModal };
+ * }
+ * ```
+ */
+export declare function useUISlots(): UISlotManager;
+/**
+ * Hook to get content for a specific slot.
+ *
+ * Useful for components that only need to read slot state.
+ */
+export declare function useSlotContent(slot: UISlot): SlotContent | null;
+/**
+ * Hook to check if a slot has content.
+ */
+export declare function useSlotHasContent(slot: UISlot): boolean;
+export { UISlotContext, type UISlotManager, type UISlot, type SlotContent, type RenderUIConfig, type SlotAnimation, type SlotChangeCallback, };

package/dist/context/UserContext.d.ts

@@ -0,0 +1,111 @@
+/**
+ * UserContext
+ *
+ * React context for providing user data throughout the application.
+ * Enables @user bindings in S-expressions for role-based UI and permissions.
+ *
+ * Usage:
+ * ```tsx
+ * // In App.tsx or layout
+ * <UserProvider user={{ id: '123', role: 'admin', permissions: ['read', 'write'] }}>
+ *   <App />
+ * </UserProvider>
+ *
+ * // In components - access via hook
+ * const { user, hasRole, hasPermission } = useUser();
+ * if (hasRole('admin')) { ... }
+ * if (hasPermission('delete')) { ... }
+ * ```
+ *
+ * @packageDocumentation
+ */
+import React from 'react';
+/**
+ * User data for @user bindings.
+ * Matches UserContext type from evaluator/context.ts
+ */
+export interface UserData {
+    /** User's unique ID */
+    id: string;
+    /** User's email */
+    email?: string;
+    /** User's display name */
+    name?: string;
+    /** User's role (for RBAC) */
+    role?: string;
+    /** User's permissions */
+    permissions?: string[];
+    /** Additional custom profile fields */
+    [key: string]: unknown;
+}
+/**
+ * User context value.
+ */
+export interface UserContextValue {
+    /** Current user data (null if not logged in) */
+    user: UserData | null;
+    /** Check if user is logged in */
+    isLoggedIn: boolean;
+    /** Check if user has a specific role */
+    hasRole: (role: string) => boolean;
+    /** Check if user has a specific permission */
+    hasPermission: (permission: string) => boolean;
+    /** Check if user has any of the specified roles */
+    hasAnyRole: (roles: string[]) => boolean;
+    /** Check if user has all of the specified permissions */
+    hasAllPermissions: (permissions: string[]) => boolean;
+    /** Get a user field by path (for @user.field bindings) */
+    getUserField: (path: string) => unknown;
+}
+/**
+ * Anonymous user for when no user is logged in.
+ */
+declare const ANONYMOUS_USER: UserData;
+declare const UserContext: React.Context<UserContextValue | null>;
+export interface UserProviderProps {
+    /** User data (null if not logged in) */
+    user?: UserData | null;
+    /** Children to render */
+    children: React.ReactNode;
+}
+/**
+ * Provider component that provides user context to the application.
+ *
+ * Provides RBAC helpers and field access for @user bindings.
+ */
+export declare function UserProvider({ user, children, }: UserProviderProps): React.ReactElement;
+/**
+ * Hook to access the user context.
+ *
+ * Returns default values if used outside of UserProvider (for resilience).
+ *
+ * @example
+ * ```tsx
+ * function AdminPanel() {
+ *   const { user, hasRole, hasPermission } = useUser();
+ *
+ *   if (!hasRole('admin') && !hasPermission('admin:access')) {
+ *     return <AccessDenied />;
+ *   }
+ *
+ *   return <div>Welcome, {user?.name}</div>;
+ * }
+ * ```
+ */
+export declare function useUser(): UserContextValue;
+/**
+ * Hook to check if user has a specific role.
+ * Convenience wrapper around useUser().hasRole().
+ */
+export declare function useHasRole(role: string): boolean;
+/**
+ * Hook to check if user has a specific permission.
+ * Convenience wrapper around useUser().hasPermission().
+ */
+export declare function useHasPermission(permission: string): boolean;
+/**
+ * Hook to get user data for @user bindings in S-expressions.
+ * Returns the user data object compatible with EvaluationContext.user
+ */
+export declare function useUserForEvaluation(): UserData | undefined;
+export { UserContext, ANONYMOUS_USER };