@almadar/ui 6.15.0 → 6.16.0

package/dist/components/index.cjs

@@ -2117,7 +2117,7 @@ var init_Textarea = __esm({
     init_cn();
     init_useEventBus();
     exports.Textarea = React79__namespace.default.forwardRef(
-      ({ className, error, onChange, ...props }, ref) => {
+      ({ className, error, onChange, action, onKeyDown, ...props }, ref) => {
         const eventBus = useEventBus();
         const handleChange = (e) => {
           if (typeof onChange === "string") {
@@ -2126,11 +2126,18 @@ var init_Textarea = __esm({
             onChange?.(e);
           }
         };
+        const handleKeyDown = (e) => {
+          onKeyDown?.(e);
+          if (!action || e.key !== "Enter" || !(e.metaKey || e.ctrlKey)) return;
+          e.preventDefault();
+          eventBus.emit(`UI:${action}`, { value: e.currentTarget.value });
+        };
         return /* @__PURE__ */ jsxRuntime.jsx(
           "textarea",
           {
             ref,
             onChange: handleChange,
+            onKeyDown: handleKeyDown,
             className: cn(
               "block w-full border-[length:var(--border-width)] shadow-sm",
               "px-3 py-2 text-sm text-foreground",
@@ -20056,6 +20063,29 @@ var init_useCanvasGestures = __esm({
   }
 });
 
+// lib/keyMapEvent.ts
+function isEditableTarget(target) {
+  if (!(target instanceof HTMLElement)) return false;
+  const tag = target.tagName;
+  if (tag === "INPUT" || tag === "TEXTAREA" || tag === "SELECT") return true;
+  return target.isContentEditable || target.contentEditable === "true";
+}
+function keyMapCode(e) {
+  let code = e.code;
+  if (e.altKey) code = `Alt+${code}`;
+  if (e.shiftKey) code = `Shift+${code}`;
+  if (e.metaKey || e.ctrlKey) code = `Mod+${code}`;
+  return code;
+}
+function resolveKeyMapEvent(map, e) {
+  if (!map || isEditableTarget(e.target)) return void 0;
+  return map[keyMapCode(e)] ?? map[e.code];
+}
+var init_keyMapEvent = __esm({
+  "lib/keyMapEvent.ts"() {
+  }
+});
+
 // lib/isometric.ts
 function isoToScreen(tileX, tileY, cellWidth, baseOffsetX, layout = "isometric") {
   const w = cellWidth;
@@ -20774,14 +20804,14 @@ function Canvas2D({
   React79.useEffect(() => {
     if (!keyMap && !keyUpMap) return;
     const onDown = (e) => {
-      const ev = keyMap?.[e.code];
+      const ev = resolveKeyMapEvent(keyMap, e);
       if (ev) {
         eventBus.emit(`UI:${ev}`, {});
         e.preventDefault();
       }
     };
     const onUp = (e) => {
-      const ev = keyUpMap?.[e.code];
+      const ev = resolveKeyMapEvent(keyUpMap, e);
       if (ev) eventBus.emit(`UI:${ev}`, {});
     };
     window.addEventListener("keydown", onDown);
@@ -20905,6 +20935,7 @@ var init_Canvas2D = __esm({
     init_useCamera();
     init_useCanvasGestures();
     init_verificationRegistry();
+    init_keyMapEvent();
     init_webPainter2d();
     init_projector();
     init_paintDispatch();
@@ -25137,6 +25168,40 @@ var init_DashboardLayout = __esm({
     NavLinkBottom.displayName = "NavLinkBottom";
   }
 });
+
+// lib/relationLabel.ts
+function relationLabel(value) {
+  if (value === null || typeof value !== "object" || Array.isArray(value) || value instanceof Date)
+    return null;
+  for (const key of ["name", "title", "label"]) {
+    const candidate = value[key];
+    if (typeof candidate === "string" && candidate !== "") return candidate;
+  }
+  const id = value.id;
+  return id !== void 0 && id !== null ? String(id) : null;
+}
+function relationDisplayLabels(value, options) {
+  if (value === void 0 || value === null || value === "") return [];
+  if (Array.isArray(value)) {
+    return value.flatMap((item) => relationDisplayLabels(item, options));
+  }
+  const hydrated = relationLabel(value);
+  if (hydrated !== null) return [hydrated];
+  const raw = String(value);
+  const match = options?.find((opt) => opt.value === raw);
+  return [match ? match.label : raw];
+}
+function resolveRelationCellDisplay(value, options) {
+  if (value === null || value === void 0 || value === "") return void 0;
+  const isObjectShaped = typeof value === "object" && !(value instanceof Date) || Array.isArray(value) && value.some((v) => v !== null && typeof v === "object" && !(v instanceof Date));
+  if (!isObjectShaped && !options) return void 0;
+  const labels = relationDisplayLabels(value, options);
+  return labels.length > 0 ? labels.join(", ") : void 0;
+}
+var init_relationLabel = __esm({
+  "lib/relationLabel.ts"() {
+  }
+});
 function downloadItemUrl(url, label) {
   const a = document.createElement("a");
   a.href = url;
@@ -25968,7 +26033,8 @@ function DataGrid({
   positionEvent,
   dndItemIdField,
   dndRoot,
-  look = "dense"
+  look = "dense",
+  relationsData
 }) {
   const eventBus = useEventBus();
   const { t } = hooks.useTranslate();
@@ -26158,6 +26224,10 @@ function DataGrid({
               );
             }
             const titleValue = core.getNestedValue(itemData, titleField?.name ?? "");
+            const titleDisplay = resolveRelationCellDisplay(
+              titleValue,
+              titleField ? relationsData?.[titleField.name] : void 0
+            ) ?? (titleValue !== void 0 && titleValue !== null ? String(titleValue) : void 0);
             return wrapDnd(
               /* @__PURE__ */ jsxRuntime.jsxs(
                 exports.Box,
@@ -26182,7 +26252,7 @@ function DataGrid({
                         "img",
                         {
                           src: imgUrl,
-                          alt: titleValue !== void 0 ? String(titleValue) : "",
+                          alt: titleDisplay ?? "",
                           className: "w-full h-full object-cover",
                           loading: "lazy"
                         }
@@ -26197,18 +26267,18 @@ function DataGrid({
                           onChange: () => toggleSelection(id),
                           onClick: (e) => e.stopPropagation(),
                           className: "w-4 h-4 mt-1 flex-shrink-0 accent-primary",
-                          "aria-label": t("card.selectItem", { item: titleValue !== void 0 ? String(titleValue) : t("card.itemFallback") })
+                          "aria-label": t("card.selectItem", { item: titleDisplay ?? t("card.itemFallback") })
                         }
                       ),
                       /* @__PURE__ */ jsxRuntime.jsxs(exports.VStack, { gap: "xs", className: "flex-1 min-w-0", children: [
-                        titleValue !== void 0 && titleValue !== null && /* @__PURE__ */ jsxRuntime.jsxs(exports.HStack, { gap: "xs", className: "items-center min-w-0", children: [
+                        titleDisplay !== void 0 && /* @__PURE__ */ jsxRuntime.jsxs(exports.HStack, { gap: "xs", className: "items-center min-w-0", children: [
                           titleField?.icon && renderIconInput(titleField.icon, { size: "sm", className: "text-primary flex-shrink-0" }),
                           /* @__PURE__ */ jsxRuntime.jsx(
                             exports.Typography,
                             {
                               variant: titleField?.variant === "h3" ? "h3" : "h4",
                               className: "font-semibold truncate min-w-0",
-                              children: String(titleValue)
+                              children: titleDisplay
                             }
                           )
                         ] }),
@@ -26217,7 +26287,7 @@ function DataGrid({
                           if (val === void 0 || val === null || val === "") return null;
                           return /* @__PURE__ */ jsxRuntime.jsxs(exports.HStack, { gap: "xs", className: "items-center", children: [
                             field.icon && renderIconInput(field.icon, { size: "xs" }),
-                            /* @__PURE__ */ jsxRuntime.jsx(exports.Badge, { variant: resolveBadgeVariant(field, String(val)), children: humanizeEnumValue(formatValue(val, field.format)) })
+                            /* @__PURE__ */ jsxRuntime.jsx(exports.Badge, { variant: resolveBadgeVariant(field, String(val)), children: resolveRelationCellDisplay(val, relationsData?.[field.name]) ?? humanizeEnumValue(formatValue(val, field.format)) })
                           ] }, field.name);
                         }) })
                       ] }),
@@ -26256,7 +26326,7 @@ function DataGrid({
                       bodyFields.filter((f3) => f3.variant === "caption" && f3.format !== "boolean").map((field) => {
                         const value = core.getNestedValue(itemData, field.name);
                         if (value === void 0 || value === null || value === "") return null;
-                        return /* @__PURE__ */ jsxRuntime.jsx(exports.Typography, { variant: "small", color: "secondary", className: "line-clamp-2", children: formatValue(value, field.format) }, field.name);
+                        return /* @__PURE__ */ jsxRuntime.jsx(exports.Typography, { variant: "small", color: "secondary", className: "line-clamp-2", children: resolveRelationCellDisplay(value, relationsData?.[field.name]) ?? formatValue(value, field.format) }, field.name);
                       }),
                       /* @__PURE__ */ jsxRuntime.jsx(exports.HStack, { gap: "md", className: "flex-wrap gap-y-1", children: bodyFields.filter((f3) => f3.variant !== "caption" || f3.format === "boolean").map((field) => {
                         const value = core.getNestedValue(itemData, field.name);
@@ -26271,7 +26341,7 @@ function DataGrid({
                         return /* @__PURE__ */ jsxRuntime.jsxs(exports.HStack, { gap: "xs", className: "items-center", children: [
                           field.icon && renderIconInput(field.icon, { size: "xs", className: "text-muted-foreground" }),
                           /* @__PURE__ */ jsxRuntime.jsx(exports.Typography, { variant: "caption", color: "secondary", className: "sr-only", children: (field.label ?? fieldLabel2(field.name)) + ":" }),
-                          /* @__PURE__ */ jsxRuntime.jsx(exports.Typography, { variant: "small", color: "secondary", children: formatValue(value, field.format) })
+                          /* @__PURE__ */ jsxRuntime.jsx(exports.Typography, { variant: "small", color: "secondary", children: resolveRelationCellDisplay(value, relationsData?.[field.name]) ?? formatValue(value, field.format) })
                         ] }, field.name);
                       }) })
                     ] }) })
@@ -26315,6 +26385,7 @@ var init_DataGrid = __esm({
     "use client";
     init_cn();
     init_format();
+    init_relationLabel();
     init_getNestedValue();
     init_useEventBus();
     init_Box();
@@ -26367,7 +26438,9 @@ function statusVariant3(value) {
   if (["new", "created", "scheduled", "queued", "info"].includes(v)) return "info";
   return "default";
 }
-function formatValue2(value, format, boolLabels) {
+function formatValue2(value, format, boolLabels, relationOptions) {
+  const relationDisplay = resolveRelationCellDisplay(value, relationOptions);
+  if (relationDisplay !== void 0) return relationDisplay;
   if (value !== void 0 && value !== null && (format === "boolean" || typeof value === "boolean")) {
     const isNo = value === false || value === 0 || String(value) === "false";
     return isNo ? boolLabels?.no ?? "No" : boolLabels?.yes ?? "Yes";
@@ -26427,7 +26500,8 @@ function DataList({
   positionEvent,
   dndItemIdField,
   dndRoot,
-  look = "dense"
+  look = "dense",
+  relationsData
 }) {
   const eventBus = useEventBus();
   const { t } = hooks.useTranslate();
@@ -26615,13 +26689,13 @@ function DataList({
                       return f3.variant === "badge" ? (
                         // `format` applies here too — a boolean field badged
                         // without it renders the raw "false" instead of "No".
-                        /* @__PURE__ */ jsxRuntime.jsx(exports.Badge, { variant: statusVariant3(String(v)), children: formatValue2(v, f3.format) }, f3.name)
+                        /* @__PURE__ */ jsxRuntime.jsx(exports.Badge, { variant: statusVariant3(String(v)), children: formatValue2(v, f3.format, void 0, relationsData?.[f3.name]) }, f3.name)
                       ) : /* @__PURE__ */ jsxRuntime.jsx(
                         exports.Typography,
                         {
                           variant: "caption",
                           className: cn("text-xs", isSent ? "opacity-70" : "text-muted-foreground"),
-                          children: formatValue2(v, f3.format)
+                          children: formatValue2(v, f3.format, void 0, relationsData?.[f3.name])
                         },
                         f3.name
                       );
@@ -26699,6 +26773,10 @@ function DataList({
     }
     const id = itemData.id || String(index);
     const titleValue = core.getNestedValue(itemData, titleField?.name ?? "");
+    const titleDisplay = resolveRelationCellDisplay(
+      titleValue,
+      titleField ? relationsData?.[titleField.name] : void 0
+    ) ?? (titleValue !== void 0 && titleValue !== null ? String(titleValue) : void 0);
     return wrapDnd(
       /* @__PURE__ */ jsxRuntime.jsxs(exports.Box, { "data-entity-row": true, "data-entity-id": id, onClick: rowClickEvent ? handleRowClick(itemData) : void 0, className: cn(rowClickEvent && "cursor-pointer"), children: [
         /* @__PURE__ */ jsxRuntime.jsxs(
@@ -26723,7 +26801,7 @@ function DataList({
                     {
                       variant: titleField?.variant === "h3" ? "h3" : "h4",
                       className: cn("font-semibold truncate flex-1", isCompact && "text-sm"),
-                      children: String(titleValue)
+                      children: titleDisplay
                     }
                   ),
                   badgeFields.map((field) => {
@@ -26731,7 +26809,7 @@ function DataList({
                     if (val === void 0 || val === null) return null;
                     return /* @__PURE__ */ jsxRuntime.jsxs(exports.HStack, { gap: "xs", className: "items-center flex-shrink-0", children: [
                       field.icon && renderIconInput2(field.icon, { size: "xs" }),
-                      /* @__PURE__ */ jsxRuntime.jsx(exports.Badge, { variant: statusVariant3(String(val)), children: formatValue2(val, field.format) })
+                      /* @__PURE__ */ jsxRuntime.jsx(exports.Badge, { variant: statusVariant3(String(val)), children: formatValue2(val, field.format, void 0, relationsData?.[field.name]) })
                     ] }, field.name);
                   })
                 ] }),
@@ -26752,7 +26830,7 @@ function DataList({
                         ]
                       }
                     ),
-                    /* @__PURE__ */ jsxRuntime.jsx(exports.Typography, { variant: "small", color: "secondary", children: formatValue2(value, field.format, { yes: t("common.yes"), no: t("common.no") }) })
+                    /* @__PURE__ */ jsxRuntime.jsx(exports.Typography, { variant: "small", color: "secondary", children: formatValue2(value, field.format, { yes: t("common.yes"), no: t("common.no") }, relationsData?.[field.name]) })
                   ] }, field.name);
                 }) }),
                 progressFields.map((field) => {
@@ -26832,6 +26910,7 @@ var init_DataList = __esm({
     "use client";
     init_cn();
     init_format();
+    init_relationLabel();
     init_getNestedValue();
     init_useEventBus();
     init_Box();
@@ -34094,6 +34173,7 @@ var init_MathCanvas = __esm({
     "use client";
     init_useEventBus();
     init_perf();
+    init_keyMapEvent();
     init_atoms();
     init_Stack();
     init_gameFonts();
@@ -34147,14 +34227,14 @@ var init_MathCanvas = __esm({
       React79.useEffect(() => {
         if (!stableKeyMap && !stableKeyUpMap) return;
         const onDown = (e) => {
-          const ev = stableKeyMap?.[e.code];
+          const ev = resolveKeyMapEvent(stableKeyMap, e);
           if (ev) {
             eventBus.emit(`UI:${ev}`, {});
             e.preventDefault();
           }
         };
         const onUp = (e) => {
-          const ev = stableKeyUpMap?.[e.code];
+          const ev = resolveKeyMapEvent(stableKeyUpMap, e);
           if (ev) eventBus.emit(`UI:${ev}`, {});
         };
         window.addEventListener("keydown", onDown);
@@ -36570,33 +36650,6 @@ var init_Lightbox = __esm({
     exports.Lightbox.displayName = "Lightbox";
   }
 });
-
-// lib/relationLabel.ts
-function relationLabel(value) {
-  if (value === null || typeof value !== "object" || Array.isArray(value) || value instanceof Date)
-    return null;
-  for (const key of ["name", "title", "label"]) {
-    const candidate = value[key];
-    if (typeof candidate === "string" && candidate !== "") return candidate;
-  }
-  const id = value.id;
-  return id !== void 0 && id !== null ? String(id) : null;
-}
-function relationDisplayLabels(value, options) {
-  if (value === void 0 || value === null || value === "") return [];
-  if (Array.isArray(value)) {
-    return value.flatMap((item) => relationDisplayLabels(item, options));
-  }
-  const hydrated = relationLabel(value);
-  if (hydrated !== null) return [hydrated];
-  const raw = String(value);
-  const match = options?.find((opt) => opt.value === raw);
-  return [match ? match.label : raw];
-}
-var init_relationLabel = __esm({
-  "lib/relationLabel.ts"() {
-  }
-});
 function renderIconInput3(icon, props) {
   return typeof icon === "string" ? /* @__PURE__ */ jsxRuntime.jsx(exports.Icon, { name: icon, ...props }) : /* @__PURE__ */ jsxRuntime.jsx(exports.Icon, { icon, ...props });
 }
@@ -36660,7 +36713,8 @@ function TableView({
   reorderEvent,
   positionEvent,
   dndItemIdField,
-  dndRoot
+  dndRoot,
+  relationsData
 }) {
   const eventBus = useEventBus();
   const { t } = hooks.useTranslate();
@@ -36745,7 +36799,7 @@ function TableView({
   const colFloors = React79__namespace.default.useMemo(
     () => colDefs.map((col) => {
       const longest = data.reduce((widest, row) => {
-        const cell = formatCell(asFieldValue(core.getNestedValue(row, col.field ?? col.key)), col.format);
+        const cell = formatCell(asFieldValue(core.getNestedValue(row, col.field ?? col.key)), col.format, relationsData?.[col.field ?? col.key]);
         return Math.max(widest, cell.length);
       }, columnLabel(col).length);
       const chrome = col.format === "badge" ? BADGE_CHROME_CH : 0;
@@ -36845,9 +36899,11 @@ function TableView({
               col.className
             );
             if (col.format === "badge" && raw != null && raw !== "") {
-              return /* @__PURE__ */ jsxRuntime.jsx(exports.Box, { role: "cell", className: cellBase, children: /* @__PURE__ */ jsxRuntime.jsx(exports.Badge, { variant: statusVariant4(String(raw)), size: "sm", className: "whitespace-nowrap", children: humanizeEnumValue(String(raw)) }) }, col.key);
+              const relationDisplay = resolveRelationCellDisplay(raw, relationsData?.[col.field ?? col.key]);
+              const label = relationDisplay ?? humanizeEnumValue(String(raw));
+              return /* @__PURE__ */ jsxRuntime.jsx(exports.Box, { role: "cell", className: cellBase, children: /* @__PURE__ */ jsxRuntime.jsx(exports.Badge, { variant: statusVariant4(String(raw)), size: "sm", className: "whitespace-nowrap", children: label }) }, col.key);
             }
-            return /* @__PURE__ */ jsxRuntime.jsx(exports.Box, { role: "cell", className: cellBase, children: /* @__PURE__ */ jsxRuntime.jsx("span", { className: "truncate text-foreground", children: formatCell(raw, col.format) }) }, col.key);
+            return /* @__PURE__ */ jsxRuntime.jsx(exports.Box, { role: "cell", className: cellBase, children: /* @__PURE__ */ jsxRuntime.jsx("span", { className: "truncate text-foreground", children: formatCell(raw, col.format, relationsData?.[col.field ?? col.key]) }) }, col.key);
           }),
           hasActions && /* @__PURE__ */ jsxRuntime.jsxs(
             exports.HStack,
@@ -36949,11 +37005,9 @@ var init_TableView = __esm({
     init_Menu();
     init_useDataDnd();
     tableViewLog = logger.createLogger("almadar:ui:table-view");
-    formatCell = (value, format) => {
-      if (value !== null && value !== void 0 && typeof value === "object" && !(value instanceof Date)) {
-        const labels = relationDisplayLabels(value);
-        if (labels.length > 0) return labels.join(", ");
-      }
+    formatCell = (value, format, relationOptions) => {
+      const relationDisplay = resolveRelationCellDisplay(value, relationOptions);
+      if (relationDisplay !== void 0) return relationDisplay;
       return formatValue(value, format);
     };
     MAX_MEASURED_COL_CH = 32;
@@ -45892,7 +45946,8 @@ function DataTable({
   headerActions,
   showTotal = true,
   className,
-  look = "dense"
+  look = "dense",
+  relationsData
 }) {
   const [openActionMenu, setOpenActionMenu] = React79.useState(
     null
@@ -46187,6 +46242,11 @@ function DataTable({
                       "data-column": String(col.key),
                       className: "px-4 py-3 text-sm text-foreground whitespace-nowrap sm:whitespace-normal",
                       children: col.render ? col.render(cellValue, row, rowIndex) : (() => {
+                        const relationDisplay = resolveRelationCellDisplay(
+                          cellValue,
+                          relationsData?.[String(col.key)]
+                        );
+                        if (relationDisplay !== void 0) return relationDisplay;
                         const boolVal = asBooleanValue2(cellValue);
                         if (boolVal !== null) {
                           return boolVal ? /* @__PURE__ */ jsxRuntime.jsx(exports.Badge, { variant: "success", children: t("common.yes") }) : /* @__PURE__ */ jsxRuntime.jsx(exports.Badge, { variant: "neutral", children: t("common.no") });
@@ -46275,6 +46335,7 @@ var init_DataTable = __esm({
     init_cn();
     init_format();
     init_getNestedValue();
+    init_relationLabel();
     init_atoms();
     init_Box();
     init_Stack();

package/dist/components/index.d.cts

@@ -6,8 +6,8 @@ import { LucideIcon } from 'lucide-react';
 import { C as ColorToken, U as UiError, D as DrawableNode, P as Point, a as Projector, F as FxOverlayItem, M as MeshShapeKind, b as MeshMaterial, c as DrawGroupProps, d as DrawTextProps, e as DrawMeshProps, L as LinkAction, I as ImageSource } from '../paintDispatch-Dh1pgljl.cjs';
 export { f as FxOverlayKind, R as Rect } from '../paintDispatch-Dh1pgljl.cjs';
 import { SExpr } from '@almadar/evaluator';
-import { U as UnitAnimationState, F as FacingDirection, S as SpriteSheetUrls, g as SpriteFrameDims, R as ResolvedFrame, h as CanvasLighting, i as CanvasPost, a as IsometricUnit, j as CameraState, k as FieldInfo, l as OrbitalTraitInfo, m as OrbitalPageInfo, T as TraitLevelData, E as ExternalLink } from '../avl-schema-parser-B25PL-a8.cjs';
-export { B as BoardTile, G as GameAction, n as GamePhase, o as GameState, p as GameUnit, b as IsometricFeature, I as IsometricTile, P as Position, q as UnitTrait, r as calculateAttackTargets, s as calculateValidMoves, t as createInitialGameState } from '../avl-schema-parser-B25PL-a8.cjs';
+import { U as UnitAnimationState, F as FacingDirection, S as SpriteSheetUrls, g as SpriteFrameDims, R as ResolvedFrame, h as CanvasLighting, i as CanvasPost, a as IsometricUnit, j as CameraState, k as FieldInfo, l as OrbitalTraitInfo, m as OrbitalPageInfo, T as TraitLevelData, E as ExternalLink } from '../avl-schema-parser-dGHC5jUf.cjs';
+export { B as BoardTile, G as GameAction, n as GamePhase, o as GameState, p as GameUnit, b as IsometricFeature, I as IsometricTile, P as Position, q as UnitTrait, r as calculateAttackTargets, s as calculateValidMoves, t as createInitialGameState } from '../avl-schema-parser-dGHC5jUf.cjs';
 export { G as GameAudioContext, a as GameAudioContextValue, e as GameAudioControls, b as GameAudioProvider, c as GameAudioProviderProps, U as UseGameAudioOptions, f as useGameAudio, u as useGameAudioContext } from '../GameAudioProvider-Cpw_lMPY.cjs';
 import { i as EditorMotion, j as EditorOperator, C as ContentSegment, L as LessonSegment, F as InteractiveOrbitalType, c as DomLayoutData, e as DomStateNode, V as VisualizerConfig, f as DomTransitionLabel } from '../cn-Do5gsPBm.cjs';
 export { G as BloomLevel, H as BloomQuizBlock, J as BloomQuizBlockProps, M as MixedSegment, o as cn, x as parseLessonSegments, K as parseMarkdownWithCodeBlocks } from '../cn-Do5gsPBm.cjs';
@@ -372,7 +372,7 @@ interface TextareaProps extends Omit<React__default.TextareaHTMLAttributes<HTMLT
     placeholder?: string;
     /** Number of visible rows */
     rows?: number;
-    /** Declarative event name for trait dispatch */
+    /** Declarative event: fires on ⌘/Ctrl+Enter with `{ value }`. */
     action?: EventKey;
     /** Error message */
     error?: string;
@@ -2307,9 +2307,9 @@ interface ControlGridProps {
     }>;
     /** Per-direction PRESS → the board's SEMANTIC event (kind="dpad"), e.g. `{ left: "LEFT", right: "RIGHT", up: "JUMP" }`.
      *  Lets the d-pad emit the SAME intent events as the keyboard so the FSM stays device-agnostic. */
-    directionEvents?: Partial<Record<DPadDirection, string>>;
+    directionEvents?: Partial<Record<DPadDirection, EventKey>>;
     /** Per-direction RELEASE → semantic event, e.g. `{ left: "STOP", right: "STOP" }`. Omit a direction to ignore its release. */
-    directionReleaseEvents?: Partial<Record<DPadDirection, string>>;
+    directionReleaseEvents?: Partial<Record<DPadDirection, EventKey>>;
     /** Per-direction sprite assets for kind="dpad" buttons (e.g. Kenny arrow PNGs). Falls back to arrow emoji. */
     directionAssets?: Partial<Record<DPadDirection, Asset>>;
     size?: 'sm' | 'md' | 'lg';
@@ -2593,10 +2593,10 @@ interface Canvas2DProps {
     }>;
     /** Emits UI:{tileLeaveEvent} with {} on pointer leave. */
     tileLeaveEvent?: EventEmit<Record<string, never>>;
-    /** Maps a keydown `e.code` → the board's SEMANTIC event (device-agnostic input). */
-    keyMap?: Record<string, string>;
-    /** Maps a keyup `e.code` → the board's SEMANTIC event. */
-    keyUpMap?: Record<string, string>;
+    /** Maps a keydown `e.code` — optionally prefixed `Mod+` (⌘/Ctrl), `Shift+`, `Alt+` in that order — to the board's SEMANTIC event (device-agnostic input), emitted as `UI:{event}`; keystrokes inside inputs/textareas never route. */
+    keyMap?: Record<string, EventKey>;
+    /** Maps a keyup `e.code` — optionally prefixed `Mod+` (⌘/Ctrl), `Shift+`, `Alt+` in that order — to the board's SEMANTIC event, emitted as `UI:{event}`; keystrokes inside inputs/textareas never route. */
+    keyUpMap?: Record<string, EventKey>;
     /** Enter scene-edit mode: click selects/deselects a drawable, drag moves it. */
     editable?: boolean;
     /** The currently-selected drawable id (controlled); `null`/undefined = none. */
@@ -2754,8 +2754,10 @@ interface CanvasProps {
         type?: string;
         elevation?: number;
     }>;
-    keyMap?: Record<string, string>;
-    keyUpMap?: Record<string, string>;
+    /** Maps a keydown `e.code` — optionally prefixed `Mod+` (⌘/Ctrl), `Shift+`, `Alt+` in that order — to the board's SEMANTIC event (device-agnostic input), emitted as `UI:{event}`; keystrokes inside inputs/textareas never route. */
+    keyMap?: Record<string, EventKey>;
+    /** Maps a keyup `e.code` — optionally prefixed `Mod+` (⌘/Ctrl), `Shift+`, `Alt+` in that order — to the board's SEMANTIC event, emitted as `UI:{event}`; keystrokes inside inputs/textareas never route. */
+    keyUpMap?: Record<string, EventKey>;
     /** Enter scene-edit mode: click selects/deselects a drawable, drag moves it. */
     editable?: boolean;
     /** The currently-selected drawable id (controlled); `null`/undefined = none. */
@@ -6516,10 +6518,10 @@ interface MathCanvasProps {
         type?: string;
         index: number;
     }) => void;
-    /** Maps a keydown `e.code` → the board's SEMANTIC event (device-agnostic input), emitted as `UI:{event}` — same contract as the game canvas keyMap. */
-    keyMap?: Record<string, string>;
-    /** Maps a keyup `e.code` → the board's SEMANTIC event. */
-    keyUpMap?: Record<string, string>;
+    /** Maps a keydown `e.code` — optionally prefixed `Mod+` (⌘/Ctrl), `Shift+`, `Alt+` in that order — to the board's SEMANTIC event (device-agnostic input), emitted as `UI:{event}` — same contract as the game canvas keyMap; keystrokes inside inputs/textareas never route. */
+    keyMap?: Record<string, EventKey>;
+    /** Maps a keyup `e.code` — optionally prefixed `Mod+` (⌘/Ctrl), `Shift+`, `Alt+` in that order — to the board's SEMANTIC event, emitted as `UI:{event}`; keystrokes inside inputs/textareas never route. */
+    keyUpMap?: Record<string, EventKey>;
     isLoading?: boolean;
     error?: UiError | null;
 }
@@ -7869,6 +7871,7 @@ interface DataGridItemAction {
  * with sort, select, and drag-reorder.
  *
  * @capabilities admin table, records grid, user list, CRUD list, manage-records view, spreadsheet-style data grid, sortable columns
+ * @fieldsContract display
  */
 interface DataGridProps extends DataDndProps {
     /**
@@ -7933,8 +7936,13 @@ interface DataGridProps extends DataDndProps {
      * data-grid / data-list / entity-table share one knob name from authors.
      */
     look?: "dense" | "spacious" | "striped" | "borderless" | "card-rows";
+    /** Relation display data: { fieldName: [{value, label}] } — injected
+     *  server-side by the runtime (relation-option injection) or bound by
+     *  compiled codegen; resolves stored foreign ids to display names for a
+     *  field whose type is relation. Same contract DetailPanel takes. */
+    relationsData?: Record<string, readonly RelationOption[]>;
 }
-declare function DataGrid({ entity, fields, columns, itemActions, maxInlineActions, scrollX, cols, gap, minCardWidth, className, isLoading, error, imageField, selectable, selectionEvent, infiniteScroll, loadMoreEvent, hasMore, children, pageSize, renderItem: schemaRenderItem, dragGroup, accepts, sortable, dropEvent, reorderEvent, positionEvent, dndItemIdField, dndRoot, look, }: DataGridProps): string | number | bigint | boolean | React__default.JSX.Element | Iterable<React__default.ReactNode> | Promise<string | number | bigint | boolean | React__default.ReactPortal | React__default.ReactElement<unknown, string | React__default.JSXElementConstructor<any>> | Iterable<React__default.ReactNode> | null | undefined> | null | undefined;
+declare function DataGrid({ entity, fields, columns, itemActions, maxInlineActions, scrollX, cols, gap, minCardWidth, className, isLoading, error, imageField, selectable, selectionEvent, infiniteScroll, loadMoreEvent, hasMore, children, pageSize, renderItem: schemaRenderItem, dragGroup, accepts, sortable, dropEvent, reorderEvent, positionEvent, dndItemIdField, dndRoot, look, relationsData, }: DataGridProps): string | number | bigint | boolean | React__default.JSX.Element | Iterable<React__default.ReactNode> | Promise<string | number | bigint | boolean | React__default.ReactPortal | React__default.ReactElement<unknown, string | React__default.JSXElementConstructor<any>> | Iterable<React__default.ReactNode> | null | undefined> | null | undefined;
 declare namespace DataGrid {
     var displayName: string;
 }
@@ -7985,6 +7993,9 @@ interface DataListSwipeAction {
     /** Button variant */
     variant?: 'primary' | 'secondary' | 'danger' | 'ghost';
 }
+/**
+ * @fieldsContract display
+ */
 interface DataListProps extends DataDndProps {
     /**
      * Schema entity data — the collection of rows to render.
@@ -8087,8 +8098,13 @@ interface DataListProps extends DataDndProps {
      * data-grid / data-list / entity-table share one knob name from authors.
      */
     look?: "dense" | "spacious" | "striped" | "borderless" | "card-rows";
+    /** Relation display data: { fieldName: [{value, label}] } — injected
+     *  server-side by the runtime (relation-option injection) or bound by
+     *  compiled codegen; resolves stored foreign ids to display names for a
+     *  field whose type is relation. Same contract DetailPanel takes. */
+    relationsData?: Record<string, readonly RelationOption[]>;
 }
-declare function DataList({ entity, fields, columns, itemActions, maxInlineActions, itemClickEvent, gap, variant, groupBy, senderField, senderLabelField, currentUser, emptyMessage, className, isLoading, error, reorderable: _reorderable, reorderEvent: _reorderEvent, swipeLeftEvent: _swipeLeftEvent, swipeLeftActions: _swipeLeftActions, swipeRightEvent: _swipeRightEvent, swipeRightActions: _swipeRightActions, longPressEvent: _longPressEvent, infiniteScroll, loadMoreEvent, hasMore, children, pageSize, sortBy, sortDirection, renderItem: schemaRenderItem, dragGroup, accepts, sortable: sortableProp, dropEvent, reorderEvent: dndReorderEvent, positionEvent, dndItemIdField, dndRoot, look, }: DataListProps): string | number | bigint | boolean | React__default.JSX.Element | Iterable<React__default.ReactNode> | Promise<string | number | bigint | boolean | React__default.ReactPortal | React__default.ReactElement<unknown, string | React__default.JSXElementConstructor<any>> | Iterable<React__default.ReactNode> | null | undefined> | null | undefined;
+declare function DataList({ entity, fields, columns, itemActions, maxInlineActions, itemClickEvent, gap, variant, groupBy, senderField, senderLabelField, currentUser, emptyMessage, className, isLoading, error, reorderable: _reorderable, reorderEvent: _reorderEvent, swipeLeftEvent: _swipeLeftEvent, swipeLeftActions: _swipeLeftActions, swipeRightEvent: _swipeRightEvent, swipeRightActions: _swipeRightActions, longPressEvent: _longPressEvent, infiniteScroll, loadMoreEvent, hasMore, children, pageSize, sortBy, sortDirection, renderItem: schemaRenderItem, dragGroup, accepts, sortable: sortableProp, dropEvent, reorderEvent: dndReorderEvent, positionEvent, dndItemIdField, dndRoot, look, relationsData, }: DataListProps): string | number | bigint | boolean | React__default.JSX.Element | Iterable<React__default.ReactNode> | Promise<string | number | bigint | boolean | React__default.ReactPortal | React__default.ReactElement<unknown, string | React__default.JSXElementConstructor<any>> | Iterable<React__default.ReactNode> | null | undefined> | null | undefined;
 declare namespace DataList {
     var displayName: string;
 }
@@ -8148,6 +8164,7 @@ interface TableViewItemAction {
  * columns, with inline row actions and grouping.
  *
  * @capabilities admin console table, records list, CRUD data table, user list, manage-users grid, sortable columns, row selection with bulk actions, grouped list view
+ * @fieldsContract display
  */
 interface TableViewProps extends DataDndProps {
     /** Schema entity data — the collection of rows to render. */
@@ -8212,8 +8229,13 @@ interface TableViewProps extends DataDndProps {
      * so authors share one knob name across row renderers.
      */
     look?: 'dense' | 'spacious' | 'striped' | 'borderless' | 'bordered';
+    /** Relation display data: { fieldName: [{value, label}] } — injected
+     *  server-side by the runtime (relation-option injection) or bound by
+     *  compiled codegen; resolves stored foreign ids to display names for a
+     *  column whose field is relation-typed. Same contract DetailPanel takes. */
+    relationsData?: Record<string, readonly RelationOption[]>;
 }
-declare function TableView({ entity, columns, fields, itemActions, maxInlineActions, itemClickEvent, selectable, selectEvent, selectedIds, sortEvent, sortColumn, sortDirection, className, emptyMessage, isLoading, error, groupBy, pageSize, children, renderItem: _schemaRenderItem, look, dragGroup, accepts, sortable, dropEvent, reorderEvent, positionEvent, dndItemIdField, dndRoot, }: TableViewProps): React__default.JSX.Element;
+declare function TableView({ entity, columns, fields, itemActions, maxInlineActions, itemClickEvent, selectable, selectEvent, selectedIds, sortEvent, sortColumn, sortDirection, className, emptyMessage, isLoading, error, groupBy, pageSize, children, renderItem: _schemaRenderItem, look, dragGroup, accepts, sortable, dropEvent, reorderEvent, positionEvent, dndItemIdField, dndRoot, relationsData, }: TableViewProps): React__default.JSX.Element;
 declare namespace TableView {
     var displayName: string;
 }
@@ -11228,6 +11250,9 @@ interface DataTableEmptyAction {
     label: string;
     event?: EventKey;
 }
+/**
+ * @fieldsContract display
+ */
 interface DataTableProps<T extends EntityRow & {
     id: string | number;
 }> extends DisplayStateProps {
@@ -11268,10 +11293,15 @@ interface DataTableProps<T extends EntityRow & {
     showTotal?: boolean;
     /** Layer 2 visual treatment — orthogonal to the semantic variant. */
     look?: EntityTableLook;
+    /** Relation display data: { fieldName: [{value, label}] } — injected
+     *  server-side by the runtime (relation-option injection) or bound by
+     *  compiled codegen; resolves stored foreign ids to display names for a
+     *  column whose field is relation-typed. Same contract DetailPanel takes. */
+    relationsData?: Record<string, readonly RelationOption[]>;
 }
 declare function DataTable<T extends EntityRow & {
     id: string | number;
-}>({ fields, columns, entity, itemActions, isLoading, error, emptyIcon, emptyTitle, emptyDescription, emptyAction, selectable, selectedIds, sortBy, sortDirection, searchable, searchValue, searchPlaceholder, page, pageSize, totalCount, rowActions: externalRowActions, bulkActions, headerActions, showTotal, className, look, }: DataTableProps<T>): React__default.JSX.Element;
+}>({ fields, columns, entity, itemActions, isLoading, error, emptyIcon, emptyTitle, emptyDescription, emptyAction, selectable, selectedIds, sortBy, sortDirection, searchable, searchValue, searchPlaceholder, page, pageSize, totalCount, rowActions: externalRowActions, bulkActions, headerActions, showTotal, className, look, relationsData, }: DataTableProps<T>): React__default.JSX.Element;
 declare namespace DataTable {
     var displayName: string;
 }