@almadar/ui 5.29.0 → 5.31.0

package/dist/components/core/atoms/Card.d.ts

@@ -23,6 +23,8 @@ export interface CardProps extends React.HTMLAttributes<HTMLDivElement> {
     children?: React.ReactNode;
     /** Declarative event key emitted on click for trait dispatch */
     action?: EventKey;
+    /** Shows a skeleton/spinner overlay while true. */
+    loading?: boolean;
 }
 export declare const Card: React.ForwardRefExoticComponent<CardProps & React.RefAttributes<HTMLDivElement>>;
 export declare const CardHeader: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLDivElement> & React.RefAttributes<HTMLDivElement>>;

package/dist/components/core/atoms/Input.d.ts

@@ -18,6 +18,8 @@ export interface InputProps extends Omit<React.InputHTMLAttributes<HTMLInputElem
     action?: EventKey;
     /** Input type - supports 'select' and 'textarea' in addition to standard types */
     inputType?: "text" | "email" | "password" | "number" | "tel" | "url" | "search" | "date" | "datetime-local" | "time" | "checkbox" | "select" | "textarea";
+    label?: string;
+    helperText?: string;
     error?: string;
     leftIcon?: IconInput;
     rightIcon?: IconInput;

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

@@ -5,20 +5,32 @@ export interface SelectOption {
     label: string;
     disabled?: boolean;
 }
-export interface SelectProps extends Omit<React.SelectHTMLAttributes<HTMLSelectElement>, "children" | "onChange"> {
+export interface SelectOptionGroup {
+    label: string;
+    options: SelectOption[];
+}
+export interface SelectProps extends Omit<React.SelectHTMLAttributes<HTMLSelectElement>, "children" | "onChange" | "multiple"> {
     /** Additional CSS classes applied to the root element. */
     className?: string;
-    /** Select options */
-    options: SelectOption[];
+    /** Select options (flat list) */
+    options?: SelectOption[];
+    /** Grouped options — rendered as <optgroup> in native mode, sections in rich mode. */
+    groups?: SelectOptionGroup[];
     /** Placeholder text */
     placeholder?: string;
-    /** Current value */
-    value?: string;
+    /** Current value (string for single, string[] for multiple) */
+    value?: string | string[];
     /** Declarative event name for trait dispatch */
     action?: EventKey;
     /** Error message */
     error?: string;
+    /** Allow selecting multiple values — activates the rich dropdown. */
+    multiple?: boolean;
+    /** Show a search input inside the dropdown — activates the rich dropdown. */
+    searchable?: boolean;
+    /** Show a clear button when a value is selected. */
+    clearable?: boolean;
     /** onChange handler or declarative event key for trait dispatch */
-    onChange?: React.ChangeEventHandler<HTMLSelectElement> | EventKey;
+    onChange?: ((value: string | string[]) => void) | EventKey;
 }
 export declare const Select: React.ForwardRefExoticComponent<SelectProps & React.RefAttributes<HTMLSelectElement>>;

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

@@ -4,5 +4,7 @@ export interface SpinnerProps extends React.HTMLAttributes<HTMLDivElement> {
     /** Additional CSS classes applied to the root element. */
     className?: string;
     size?: SpinnerSize;
+    /** Renders a centered overlay backdrop instead of inline. */
+    overlay?: boolean;
 }
 export declare const Spinner: React.ForwardRefExoticComponent<SpinnerProps & React.RefAttributes<HTMLDivElement>>;

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

@@ -3,7 +3,7 @@ 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 { Select, type SelectProps, type SelectOption, type SelectOptionGroup } 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";

package/dist/components/core/molecules/DocumentViewer.d.ts

@@ -51,8 +51,6 @@ export interface DocumentViewerProps {
     actions?: readonly DocumentAction[];
     /** Multiple documents (tabbed view) */
     documents?: readonly DocumentItem[];
-    /** Entity name for schema-driven auto-fetch */
-    entity?: string;
     /** Loading state */
     isLoading?: boolean;
     /** Error state */

package/dist/components/core/molecules/Header.d.ts

@@ -109,9 +109,5 @@ export interface HeaderProps {
      * Error state (closed circuit)
      */
     error?: UiError | null;
-    /**
-     * Entity name for schema-driven auto-fetch (closed circuit)
-     */
-    entity?: string;
 }
 export declare const Header: React.FC<HeaderProps>;

package/dist/components/core/molecules/JsonTreeEditor.d.ts

@@ -3,16 +3,11 @@ import type { TraitConfigValue } from '@almadar/core';
 export interface JsonTreeEditorProps {
     /** Current value (object / array / scalar). */
     value: TraitConfigValue;
-    /** Fired with the next value on any edit. */
+    /** Fired with the next value on any edit. Unused in readonly mode. */
     onChange: (next: TraitConfigValue) => void;
     /** Additional CSS classes. */
     className?: string;
+    /** Suppresses all edit controls — renders a read-only viewer. */
+    readonly?: boolean;
 }
-/**
- * JsonTreeEditor — a visual, collapsible tree editor for any `TraitConfigValue`
- * (object / array / nested / scalar). Replaces raw `JSON.stringify` text editing:
- * each node renders a typed inline control, containers collapse, and rows can be
- * added, removed, retyped, and (for objects) re-keyed. Self-contained — styled
- * purely with `@almadar/ui` atoms + design tokens.
- */
 export declare const JsonTreeEditor: React.FC<JsonTreeEditorProps>;

package/dist/components/core/molecules/Menu.d.ts

@@ -36,5 +36,9 @@ export interface MenuProps {
     position?: MenuPosition;
     /** Additional CSS classes */
     className?: string;
+    /** Optional slot rendered above the items. */
+    header?: React.ReactNode;
+    /** Optional slot rendered below the items. */
+    footer?: React.ReactNode;
 }
 export declare const Menu: React.FC<MenuProps>;

package/dist/components/core/molecules/Navigation.d.ts

@@ -63,7 +63,5 @@ export interface NavigationProps {
     isLoading?: boolean;
     /** Error state */
     error?: UiError | null;
-    /** Entity name for schema-driven auto-fetch */
-    entity?: string;
 }
 export declare const Navigation: React.FC<NavigationProps>;

package/dist/components/core/molecules/PageHeader.d.ts

@@ -45,8 +45,6 @@ export interface PageHeaderProps {
     isLoading?: boolean;
     /** Error state */
     error?: UiError | null;
-    /** Entity name for schema-driven auto-fetch */
-    entity?: string;
     /** Tabs for sub-navigation */
     tabs?: ReadonlyArray<{
         label: string;

package/dist/components/core/molecules/PropertyInspector.d.ts

@@ -1,5 +1,5 @@
 import React from 'react';
-import type { DeclaredTraitConfig, TraitConfig, TraitConfigValue, AssetCatalog } from '@almadar/core';
+import type { DeclaredTraitConfig, ConfigFieldDeclaration, TraitConfig, TraitConfigValue, AssetCatalog } from '@almadar/core';
 import type { DisplayStateProps } from '../organisms/types';
 /**
  * PropertyInspector — Storybook-style controls panel for a trait's `config`.
@@ -26,4 +26,11 @@ export interface PropertyInspectorProps extends DisplayStateProps {
     /** Browsable asset catalog supplied to `asset`-typed fields' AssetPicker. */
     assets?: AssetCatalog;
 }
+export declare function FieldControl({ name, decl, value, onChange, assets, }: {
+    name: string;
+    decl: ConfigFieldDeclaration;
+    value: TraitConfigValue | undefined;
+    onChange: (field: string, value: TraitConfigValue) => void;
+    assets?: AssetCatalog;
+}): React.ReactElement;
 export declare const PropertyInspector: React.FC<PropertyInspectorProps>;

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

@@ -15,7 +15,7 @@ export { FilterGroup, type FilterGroupProps, type FilterDefinition } from './Fil
 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 { FloatingActionButton, type FloatingActionButtonProps, type FloatingAction } from './FloatingActionButton';
 export { Grid, type GridProps } from './Grid';
 export { InputGroup, type InputGroupProps } from './InputGroup';
 export { Menu, type MenuProps, type MenuItem } from './Menu';

package/dist/components/core/organisms/index.d.ts

@@ -26,4 +26,3 @@ export { StepFlowOrganism, type StepFlowOrganismProps, } from "../../marketing/o
 export { ShowcaseOrganism, type ShowcaseOrganismProps, } from "../../marketing/organisms/ShowcaseOrganism";
 export { TeamOrganism, type TeamOrganismProps, } from "../../marketing/organisms/TeamOrganism";
 export { CaseStudyOrganism, type CaseStudyOrganismProps, } from "../../marketing/organisms/CaseStudyOrganism";
-export { FeatureRenderer, type FeatureRendererProps } from '../../game/molecules/three/renderers/FeatureRenderer';

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

@@ -12,6 +12,3 @@ export { LandingPageTemplate, type LandingPageTemplateProps, type LandingPageEnt
 export { PricingPageTemplate, type PricingPageTemplateProps, type PricingPageEntity, } from '../../marketing/templates/PricingPageTemplate';
 export { FeatureDetailPageTemplate, type FeatureDetailPageTemplateProps, type FeatureDetailPageEntity, type FeatureDetailSection, } from '../../marketing/templates/FeatureDetailPageTemplate';
 export { AboutPageTemplate, type AboutPageTemplateProps, type AboutPageEntity, } from '../../marketing/templates/AboutPageTemplate';
-export type { GameCanvas3DBattleTemplate, GameCanvas3DBattleTemplateProps } from '../../game/templates/GameCanvas3DBattleTemplate';
-export type { GameCanvas3DCastleTemplate, GameCanvas3DCastleTemplateProps } from '../../game/templates/GameCanvas3DCastleTemplate';
-export type { GameCanvas3DWorldMapTemplate, GameCanvas3DWorldMapTemplateProps } from '../../game/templates/GameCanvas3DWorldMapTemplate';

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

@@ -5,7 +5,6 @@
  *
  * @packageDocumentation
  */
-export type { GameCanvas3D, GameCanvas3DProps, GameCanvas3DHandle, GameEvent, CameraMode, MapOrientation, OverlayControl } from './GameCanvas3D';
 export { DPad, type DPadProps, type DPadDirection } from './DPad';
 export { ActionButtons, type ActionButtonsProps, type ActionButtonConfig } from './ActionButtons';
 export { StatBadge, type StatBadgeProps } from './StatBadge';

package/dist/components/game/molecules/three/index.cjs

@@ -1756,6 +1756,30 @@ function TileRenderer({
       const x = (tile.x - offsetX) * cellSize;
       const z = ((tile.z ?? tile.y ?? 0) - offsetZ) * cellSize;
       const y = (tile.elevation ?? 0) * 0.1;
+      const position = [x, y, z];
+      if (tile.modelUrl) {
+        return /* @__PURE__ */ jsxRuntime.jsx(
+          "group",
+          {
+            userData: { type: "tile", tileId: tile.id, gridX: tile.x, gridZ: tile.z ?? tile.y },
+            onClick: () => onTileClick?.(tile),
+            onPointerEnter: () => onTileHover?.(tile),
+            onPointerLeave: () => onTileHover?.(null),
+            children: /* @__PURE__ */ jsxRuntime.jsx(
+              ModelLoader,
+              {
+                url: tile.modelUrl,
+                position,
+                scale: cellSize * 0.9,
+                fallbackGeometry: "box",
+                castShadow: true,
+                receiveShadow: true
+              }
+            )
+          },
+          tile.id ?? `tile-${tile.x}-${tile.y}`
+        );
+      }
       const colorHex = terrainColors[tile.type || ""] || terrainColors[tile.terrain || ""] || "#808080";
       const isSelected = tile.id ? selectedTileIds.includes(tile.id) : false;
       const isValidMove = validMoves.some(
@@ -1771,7 +1795,7 @@ function TileRenderer({
       return /* @__PURE__ */ jsxRuntime.jsxs(
         "mesh",
         {
-          position: [x, y, z],
+          position,
           userData: { type: "tile", tileId: tile.id, gridX: tile.x, gridZ: tile.z ?? tile.y },
           onClick: () => onTileClick?.(tile),
           onPointerEnter: () => onTileHover?.(tile),
@@ -1793,7 +1817,8 @@ function TileRenderer({
       );
     });
   };
-  if (useInstancing && tiles.length > 0) {
+  const hasModelTiles = tiles.some((t) => t.modelUrl);
+  if (useInstancing && tiles.length > 0 && !hasModelTiles) {
     return /* @__PURE__ */ jsxRuntime.jsx(
       "instancedMesh",
       {

package/dist/components/game/molecules/three/index.js

@@ -1732,6 +1732,30 @@ function TileRenderer({
       const x = (tile.x - offsetX) * cellSize;
       const z = ((tile.z ?? tile.y ?? 0) - offsetZ) * cellSize;
       const y = (tile.elevation ?? 0) * 0.1;
+      const position = [x, y, z];
+      if (tile.modelUrl) {
+        return /* @__PURE__ */ jsx(
+          "group",
+          {
+            userData: { type: "tile", tileId: tile.id, gridX: tile.x, gridZ: tile.z ?? tile.y },
+            onClick: () => onTileClick?.(tile),
+            onPointerEnter: () => onTileHover?.(tile),
+            onPointerLeave: () => onTileHover?.(null),
+            children: /* @__PURE__ */ jsx(
+              ModelLoader,
+              {
+                url: tile.modelUrl,
+                position,
+                scale: cellSize * 0.9,
+                fallbackGeometry: "box",
+                castShadow: true,
+                receiveShadow: true
+              }
+            )
+          },
+          tile.id ?? `tile-${tile.x}-${tile.y}`
+        );
+      }
       const colorHex = terrainColors[tile.type || ""] || terrainColors[tile.terrain || ""] || "#808080";
       const isSelected = tile.id ? selectedTileIds.includes(tile.id) : false;
       const isValidMove = validMoves.some(
@@ -1747,7 +1771,7 @@ function TileRenderer({
       return /* @__PURE__ */ jsxs(
         "mesh",
         {
-          position: [x, y, z],
+          position,
           userData: { type: "tile", tileId: tile.id, gridX: tile.x, gridZ: tile.z ?? tile.y },
           onClick: () => onTileClick?.(tile),
           onPointerEnter: () => onTileHover?.(tile),
@@ -1769,7 +1793,8 @@ function TileRenderer({
       );
     });
   };
-  if (useInstancing && tiles.length > 0) {
+  const hasModelTiles = tiles.some((t) => t.modelUrl);
+  if (useInstancing && tiles.length > 0 && !hasModelTiles) {
     return /* @__PURE__ */ jsx(
       "instancedMesh",
       {

package/dist/components/game/molecules/three/patterns.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Public 3D render-ui pattern components.
+ *
+ * These are the three.js-backed components that authors target from `render-ui`
+ * effects. They are code-split behind the optional
+ * `@almadar/ui/components/molecules/game/three` subpath and are NEVER exported
+ * from the main `@almadar/ui` barrel — that would pull @react-three/fiber into
+ * every app's main bundle.
+ *
+ * The pattern scanner (tools/almadar-pattern-sync/scanner.ts) reads THIS file to
+ * register these as render-ui patterns. It is the curated public surface: 3D
+ * scene internals (Scene3D, Camera3D, Lighting3D, …) live in `./index.ts` for
+ * the lazy loader but are intentionally absent here so they don't become
+ * render-ui targets.
+ */
+export { GameCanvas3D } from '../GameCanvas3D';
+export { GameCanvas3DBattleTemplate } from '../../templates/GameCanvas3DBattleTemplate';
+export { GameCanvas3DCastleTemplate } from '../../templates/GameCanvas3DCastleTemplate';
+export { GameCanvas3DWorldMapTemplate } from '../../templates/GameCanvas3DWorldMapTemplate';
+export { FeatureRenderer } from './renderers/FeatureRenderer';

package/dist/components/game/organisms/TraitSlot.d.ts

@@ -29,7 +29,9 @@ export type SlotItemData = {
     description?: string;
     /** Emoji or text icon */
     iconEmoji?: string;
-    /** Image URL icon (takes precedence over iconEmoji) */
+    /** Image URL icon (takes precedence over iconEmoji)
+     * @default https://almadar-kflow-assets.web.app/shared/platformer/items/platformPack_item001.png
+     */
     iconUrl?: AssetUrl;
     /** Optional state machine for tooltip display */
     stateMachine?: TraitStateMachineDefinition;

package/dist/components/game/organisms/types/isometric.d.ts

@@ -31,6 +31,8 @@ export interface IsometricTile {
     tileType?: string;
     /** Elevation offset for 3D rendering */
     elevation?: number;
+    /** 3D model URL (GLB format) for GameCanvas3D — rendered via ModelLoader with box fallback */
+    modelUrl?: AssetUrl;
 }
 /** A unit positioned on the isometric grid */
 export type IsometricUnit = {