@almadar/ui 5.12.1 → 5.13.3

package/dist/components/index.js

@@ -6260,7 +6260,7 @@ var init_Modal = __esm({
           document.body.style.overflow = "";
         };
       }, [isOpen]);
-      if (!isOpen) return null;
+      if (!isOpen || typeof document === "undefined") return null;
       const handleClose = () => {
         if (closeEvent) eventBus.emit(`UI:${closeEvent}`, {});
         onClose();
@@ -6270,124 +6270,127 @@ var init_Modal = __esm({
           handleClose();
         }
       };
-      return /* @__PURE__ */ jsxs(Fragment, { children: [
-        /* @__PURE__ */ jsx(
-          Overlay,
-          {
-            isVisible: isOpen,
-            onClick: handleOverlayClick,
-            className: "z-40"
-          }
-        ),
-        /* @__PURE__ */ jsx(
-          Box,
-          {
-            className: cn(
-              "fixed inset-0 z-50 pointer-events-none",
-              "flex items-start justify-center px-4 pb-4 pt-[10vh]",
-              "max-sm:items-stretch max-sm:p-0 max-sm:pt-0"
-            ),
-            children: /* @__PURE__ */ jsxs(
-              Dialog,
-              {
-                ref: modalRef,
-                open: true,
-                className: cn(
-                  // Reset browser-default dialog chrome — we own styling. `static`
-                  // overrides the user-agent `position: absolute` so the parent
-                  // flex container's `justify-center` actually centers the dialog
-                  // (without this, the dialog drops out of flex flow and `m-0`
-                  // kills the user-agent's `margin: auto` centering, pinning the
-                  // dialog to top-left).
-                  "static m-0 p-0 border-0 bg-transparent",
-                  // Pre-existing dialog frame
-                  "pointer-events-auto w-full flex flex-col bg-surface border shadow-elevation-dialog rounded-container",
-                  // Desktop sizing + viewport-aware floor.
-                  sizeClasses5[size],
-                  minWidthClasses[size],
-                  "max-h-[80vh]",
-                  // Mobile: take the entire screen. Override desktop max-w cap,
-                  // full height, no rounded corners, no min-width.
-                  "max-sm:max-w-none max-sm:max-h-none max-sm:w-full max-sm:h-full max-sm:rounded-none",
-                  lookStyles2[look],
-                  className
-                ),
-                style: dragY > 0 ? {
-                  transform: `translateY(${dragY}px)`,
-                  transition: isDragging.current ? "none" : "transform 200ms ease-out"
-                } : void 0,
-                ...title && { "aria-labelledby": "modal-title" },
-                children: [
-                  /* @__PURE__ */ jsx(
-                    Box,
-                    {
-                      className: "hidden max-sm:flex justify-center py-2 cursor-grab active:cursor-grabbing touch-none",
-                      onPointerDown: (e) => {
-                        if (!swipeDownToClose) return;
-                        dragStartY.current = e.clientY;
-                        isDragging.current = true;
-                        e.target.setPointerCapture(e.pointerId);
-                      },
-                      onPointerMove: (e) => {
-                        if (!isDragging.current) return;
-                        const dy = Math.max(0, e.clientY - dragStartY.current);
-                        setDragY(dy);
-                      },
-                      onPointerUp: () => {
-                        if (!isDragging.current) return;
-                        isDragging.current = false;
-                        if (dragY > 100) {
-                          handleClose();
-                        }
-                        setDragY(0);
-                      },
-                      onPointerCancel: () => {
-                        isDragging.current = false;
-                        setDragY(0);
-                      },
-                      children: /* @__PURE__ */ jsx(Box, { className: "w-10 h-1 rounded-full bg-border" })
-                    }
+      return createPortal(
+        /* @__PURE__ */ jsxs(Fragment, { children: [
+          /* @__PURE__ */ jsx(
+            Overlay,
+            {
+              isVisible: isOpen,
+              onClick: handleOverlayClick,
+              className: "z-[1000]"
+            }
+          ),
+          /* @__PURE__ */ jsx(
+            Box,
+            {
+              className: cn(
+                "fixed inset-0 z-[1001] pointer-events-none",
+                "flex items-start justify-center px-4 pb-4 pt-[10vh]",
+                "max-sm:items-stretch max-sm:p-0 max-sm:pt-0"
+              ),
+              children: /* @__PURE__ */ jsxs(
+                Dialog,
+                {
+                  ref: modalRef,
+                  open: true,
+                  className: cn(
+                    // Reset browser-default dialog chrome — we own styling. `static`
+                    // overrides the user-agent `position: absolute` so the parent
+                    // flex container's `justify-center` actually centers the dialog
+                    // (without this, the dialog drops out of flex flow and `m-0`
+                    // kills the user-agent's `margin: auto` centering, pinning the
+                    // dialog to top-left).
+                    "static m-0 p-0 border-0 bg-transparent",
+                    // Pre-existing dialog frame
+                    "pointer-events-auto w-full flex flex-col bg-surface border shadow-elevation-dialog rounded-container",
+                    // Desktop sizing + viewport-aware floor.
+                    sizeClasses5[size],
+                    minWidthClasses[size],
+                    "max-h-[80vh]",
+                    // Mobile: take the entire screen. Override desktop max-w cap,
+                    // full height, no rounded corners, no min-width.
+                    "max-sm:max-w-none max-sm:max-h-none max-sm:w-full max-sm:h-full max-sm:rounded-none",
+                    lookStyles2[look],
+                    className
                   ),
-                  (title || showCloseButton) && /* @__PURE__ */ jsxs(
-                    Box,
-                    {
-                      className: cn(
-                        "px-6 py-4 flex items-center justify-between",
-                        "border-b-[length:var(--border-width)] border-border"
-                      ),
-                      children: [
-                        title && /* @__PURE__ */ jsx(Typography, { variant: "h4", as: "h2", id: "modal-title", children: title }),
-                        showCloseButton && /* @__PURE__ */ jsx(
-                          Button,
-                          {
-                            variant: "ghost",
-                            size: "sm",
-                            icon: "x",
-                            onClick: handleClose,
-                            "data-event": "CLOSE",
-                            "aria-label": "Close modal"
+                  style: dragY > 0 ? {
+                    transform: `translateY(${dragY}px)`,
+                    transition: isDragging.current ? "none" : "transform 200ms ease-out"
+                  } : void 0,
+                  ...title && { "aria-labelledby": "modal-title" },
+                  children: [
+                    /* @__PURE__ */ jsx(
+                      Box,
+                      {
+                        className: "hidden max-sm:flex justify-center py-2 cursor-grab active:cursor-grabbing touch-none",
+                        onPointerDown: (e) => {
+                          if (!swipeDownToClose) return;
+                          dragStartY.current = e.clientY;
+                          isDragging.current = true;
+                          e.target.setPointerCapture(e.pointerId);
+                        },
+                        onPointerMove: (e) => {
+                          if (!isDragging.current) return;
+                          const dy = Math.max(0, e.clientY - dragStartY.current);
+                          setDragY(dy);
+                        },
+                        onPointerUp: () => {
+                          if (!isDragging.current) return;
+                          isDragging.current = false;
+                          if (dragY > 100) {
+                            handleClose();
                           }
-                        )
-                      ]
-                    }
-                  ),
-                  /* @__PURE__ */ jsx(Box, { className: "flex-1 overflow-y-auto p-6", children }),
-                  footer && /* @__PURE__ */ jsx(
-                    Box,
-                    {
-                      className: cn(
-                        "px-6 py-4 bg-muted",
-                        "border-t-[length:var(--border-width)] border-border"
-                      ),
-                      children: footer
-                    }
-                  )
-                ]
-              }
-            )
-          }
-        )
-      ] });
+                          setDragY(0);
+                        },
+                        onPointerCancel: () => {
+                          isDragging.current = false;
+                          setDragY(0);
+                        },
+                        children: /* @__PURE__ */ jsx(Box, { className: "w-10 h-1 rounded-full bg-border" })
+                      }
+                    ),
+                    (title || showCloseButton) && /* @__PURE__ */ jsxs(
+                      Box,
+                      {
+                        className: cn(
+                          "px-6 py-4 flex items-center justify-between",
+                          "border-b-[length:var(--border-width)] border-border"
+                        ),
+                        children: [
+                          title && /* @__PURE__ */ jsx(Typography, { variant: "h4", as: "h2", id: "modal-title", children: title }),
+                          showCloseButton && /* @__PURE__ */ jsx(
+                            Button,
+                            {
+                              variant: "ghost",
+                              size: "sm",
+                              icon: "x",
+                              onClick: handleClose,
+                              "data-event": "CLOSE",
+                              "aria-label": "Close modal"
+                            }
+                          )
+                        ]
+                      }
+                    ),
+                    /* @__PURE__ */ jsx(Box, { className: "flex-1 overflow-y-auto p-6", children }),
+                    footer && /* @__PURE__ */ jsx(
+                      Box,
+                      {
+                        className: cn(
+                          "px-6 py-4 bg-muted",
+                          "border-t-[length:var(--border-width)] border-border"
+                        ),
+                        children: footer
+                      }
+                    )
+                  ]
+                }
+              )
+            }
+          )
+        ] }),
+        document.body
+      );
     };
     Modal.displayName = "Modal";
   }
@@ -12439,7 +12442,7 @@ var init_CodeBlock = __esm({
             };
           };
         }, [errorLines]);
-        const isFoldable = foldableProp ?? (language === "orb" || language === "json");
+        const isFoldable = foldableProp ?? true;
         const [collapsed, setCollapsed] = useState(() => /* @__PURE__ */ new Set());
         const foldRegions = useMemo(
           () => isFoldable ? computeFoldRegions(code) : [],
@@ -16378,6 +16381,7 @@ function CalendarGrid({
   swipeRightEvent,
   dayWindow = "auto"
 }) {
+  const evs = Array.isArray(events2) ? events2 : events2 ? [events2] : [];
   const eventBus = useEventBus();
   const longPressTimer = useRef(null);
   const resolvedWeekStart = useMemo(
@@ -16426,7 +16430,7 @@ function CalendarGrid({
     [onEventClick]
   );
   const eventsForDayCount = useCallback(
-    (day) => events2.filter(
+    (day) => evs.filter(
       (ev) => new Date(ev.startTime).toDateString() === day.toDateString()
     ).length,
     [events2]
@@ -16541,7 +16545,7 @@ function CalendarGrid({
                   }
                 ) }),
                 visibleDays.map((day) => {
-                  const slotEvents = events2.filter(
+                  const slotEvents = evs.filter(
                     (ev) => eventInSlot(ev, day, time)
                   );
                   const isToday = day.toDateString() === (/* @__PURE__ */ new Date()).toDateString();
@@ -29289,7 +29293,7 @@ function useSafeEventBus10() {
   }
 }
 function SortableListInner({
-  items: initialItems = EMPTY_ITEMS,
+  items: initialItemsProp = EMPTY_ITEMS,
   renderItem,
   reorderEvent,
   reorderPayload,
@@ -29297,6 +29301,7 @@ function SortableListInner({
   className
 }) {
   const eventBus = useSafeEventBus10();
+  const initialItems = Array.isArray(initialItemsProp) ? initialItemsProp : initialItemsProp ? [initialItemsProp] : [];
   const handleReorder = useCallback(
     (fromIndex, toIndex, item) => {
       eventBus.emit(`UI:${reorderEvent}`, {
@@ -32793,9 +32798,10 @@ var init_ReplyTree = __esm({
       showActions = true,
       className
     }) => {
+      const nodeList = Array.isArray(nodes) ? nodes : nodes ? [nodes] : [];
       const [collapsedSet, setCollapsedSet] = useState(() => {
         const acc = /* @__PURE__ */ new Set();
-        collectInitiallyCollapsed(nodes, acc);
+        collectInitiallyCollapsed(nodeList, acc);
         return acc;
       });
       const toggleCollapse = useCallback((id) => {
@@ -32809,10 +32815,10 @@ var init_ReplyTree = __esm({
           return next;
         });
       }, []);
-      if (nodes.length === 0) {
+      if (nodeList.length === 0) {
         return /* @__PURE__ */ jsx(Box, { className: cn("text-sm text-muted-foreground", className), children: "No replies yet." });
       }
-      return /* @__PURE__ */ jsx(Box, { className: cn("flex flex-col gap-2 min-w-0", className), children: nodes.map((node) => /* @__PURE__ */ jsx(
+      return /* @__PURE__ */ jsx(Box, { className: cn("flex flex-col gap-2 min-w-0", className), children: nodeList.map((node) => /* @__PURE__ */ jsx(
         ReplyTreeNode,
         {
           node,

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

@@ -6,7 +6,7 @@
  * Composes DayCell and TimeSlotCell atoms into a 7-day grid.
  */
 import React from "react";
-import type { EventEmit, EventPayload } from "@almadar/core";
+import type { EventEmit, EventPayload, EntityCollection } from "@almadar/core";
 export interface CalendarEvent {
     id: string;
     title: string;
@@ -26,7 +26,7 @@ export interface CalendarGridProps {
     /** Time slot labels (defaults to 09:00-17:00) */
     timeSlots?: string[];
     /** Events to display on the grid */
-    events?: CalendarEvent[];
+    events?: EntityCollection<CalendarEvent>;
     /** Called when a time slot is clicked */
     onSlotClick?: (day: Date, time: string) => void;
     /** Called when a day header is clicked */

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

@@ -11,7 +11,7 @@
  * Uses atoms only internally: Box, VStack, HStack, Typography, Badge, Button, Icon.
  */
 import React from 'react';
-import type { EntityRow, EventKey } from '@almadar/core';
+import type { EntityRow, EventKey, EntityCollection } from '@almadar/core';
 import { type DataDndProps } from './useDataDnd';
 export interface DataGridField {
     /** Entity field name (dot-notation supported) */
@@ -54,8 +54,14 @@ export interface DataGridProps<T extends EntityRow = EntityRow> extends DataDndP
      * without widening. The generic `T` lets consumers pass a narrower
      * entity (e.g. `CartItem`) and have the `children` render function
      * receive cards typed to that exact shape.
+     *
+     * Declared as the pattern's data INLET via `EntityCollection<T>` (the inlet
+     * half of the circuit, symmetric with the `EventKey` outlet props below):
+     * pattern-sync tags it `kind:"entity", cardinality:"collection"` so consumers
+     * bind the domain entity without name-matching the prop. Structurally still
+     * `T | readonly T[]` — see the brand's doc.
      */
-    entity: T | readonly T[];
+    entity: EntityCollection<T>;
     /**
      * Field definitions for rendering each card. The pattern contract in
      * `@almadar/patterns` documents `columns` as the wire-format alias the

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

@@ -11,7 +11,7 @@
  * Uses atoms only internally: Box, VStack, HStack, Typography, Badge, Button, Icon.
  */
 import React from 'react';
-import type { EntityRow, EventKey } from "@almadar/core";
+import type { EntityRow, EntityCollection, EventKey } from "@almadar/core";
 import { type DataDndProps } from './useDataDnd';
 export interface DataListField {
     /** Entity field name (dot-notation supported) */
@@ -45,7 +45,7 @@ export interface DataListProps<T extends EntityRow = EntityRow> extends DataDndP
      * entity (e.g. `CartItem`) and have the `children` render function
      * receive items of that exact shape.
      */
-    entity: T | readonly T[];
+    entity: EntityCollection<T>;
     /**
      * Field definitions for rendering each row. The pattern contract in
      * `@almadar/patterns` documents `columns` as the wire-format alias the

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

@@ -1,5 +1,5 @@
 import React from "react";
-import type { EventEmit, EventPayloadValue } from "@almadar/core";
+import type { EventEmit, EntityCollection } from "@almadar/core";
 export type CanvasItemStatus = 'empty' | 'seated' | 'ordered' | 'awaiting-bill' | 'cleaning';
 export type CanvasItemShape = 'round' | 'rectangle' | 'square';
 export interface CanvasItem {
@@ -20,7 +20,7 @@ export interface PositionedCanvasProps {
      * molecule narrows non-array values to `[]` and validates element shape at
      * render time via the `id` / `x` / `y` guards.
      */
-    items: readonly CanvasItem[] | EventPayloadValue;
+    items: EntityCollection<CanvasItem>;
     width?: number;
     height?: number;
     selectedId?: string | null;

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

@@ -5,7 +5,7 @@
  * Composes the VoteStack molecule + Avatar/Typography/Button atoms.
  */
 import React from "react";
-import type { EventEmit } from "@almadar/core";
+import type { EventEmit, EntityCollection } from "@almadar/core";
 import { type VoteValue } from "../molecules/VoteStack";
 export interface ReplyNode {
     id: string;
@@ -19,7 +19,7 @@ export interface ReplyNode {
     collapsed?: boolean;
 }
 export interface ReplyTreeProps {
-    nodes: ReplyNode[];
+    nodes: EntityCollection<ReplyNode>;
     maxDepth?: number;
     onVote?: (nodeId: string, vote: VoteValue) => void;
     onReply?: (parentNodeId: string) => void;

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

@@ -6,9 +6,9 @@
  * Shows a drop indicator line at the target position during drag.
  */
 import React from 'react';
-import type { EventKey, EventPayload, EventPayloadValue } from "@almadar/core";
+import type { EntityCollection, EventKey, EventPayload, EventPayloadValue } from "@almadar/core";
 export interface SortableListProps<T extends EventPayloadValue = EventPayload> {
-    items: T[];
+    items: EntityCollection<T>;
     renderItem: (item: T, index: number) => React.ReactNode;
     reorderEvent: EventKey;
     reorderPayload?: EventPayload;

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

@@ -12,7 +12,7 @@
  * Icon, Checkbox, Divider.
  */
 import React from 'react';
-import type { EntityRow, EventKey } from '@almadar/core';
+import type { EntityRow, EventKey, EntityCollection } from '@almadar/core';
 import { type DataDndProps } from './useDataDnd';
 export interface TableViewColumn {
     /** Stable column key (React key + default value lookup). */
@@ -52,7 +52,7 @@ export interface TableViewItemAction {
 }
 export interface TableViewProps<T extends EntityRow = EntityRow> extends DataDndProps {
     /** Schema entity data — single record or collection. */
-    entity: T | readonly T[];
+    entity: EntityCollection<T>;
     /** Column definitions. The compiler emits `columns`; `fields` is the alias. */
     columns?: readonly TableViewColumn[];
     /** Alias for `columns`. */

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

@@ -19,7 +19,7 @@ export interface CodeBlockProps {
     showLanguageBadge?: boolean;
     /** Maximum height before scrolling */
     maxHeight?: string;
-    /** Enable JSON-style code folding (default: true for json/orb) */
+    /** Enable brace-based code folding of multi-line `{}`/`[]` blocks (default: true). */
     foldable?: boolean;
     /** Additional CSS classes */
     className?: string;

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

@@ -7,6 +7,7 @@
  * See EntityDisplayProps in ./types.ts for base prop contract.
  */
 import React from "react";
+import type { EntityRecord, EntityRow } from "@almadar/core";
 import type { LucideIcon } from "lucide-react";
 import type { EntityDisplayProps } from "./types";
 export interface DetailField {
@@ -44,6 +45,8 @@ export type FieldDef = string | {
     type: string;
 };
 export interface DetailPanelProps extends EntityDisplayProps {
+    /** RECORD-cardinality override: renders ONE record (see body collapse below). */
+    entity?: EntityRecord<EntityRow>;
     title?: string;
     subtitle?: string;
     status?: {

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

@@ -10,9 +10,11 @@
  * - Never listens to events
  */
 import React from 'react';
+import type { EntityRecord } from '@almadar/core';
 import type { EntityDisplayProps } from './types';
 import type { HeroEntity } from './marketing-types';
 export interface HeroOrganismProps extends EntityDisplayProps<HeroEntity> {
+    entity?: EntityRecord<HeroEntity>;
     children?: React.ReactNode;
 }
 export declare const HeroOrganism: React.FC<HeroOrganismProps>;

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

@@ -12,7 +12,7 @@
  */
 import React from "react";
 import type { EventKey } from "@almadar/core";
-import type { EntityRow } from "@almadar/core";
+import type { EntityCollection, EntityRow } from "@almadar/core";
 import type { LucideIcon } from "lucide-react";
 export type TimelineItemStatus = "complete" | "active" | "pending" | "error";
 /**
@@ -55,7 +55,7 @@ export interface TimelineProps {
      * TimelineItem fields (`icon`, callbacks) cannot round-trip through the
      * event bus, so decorative stories that need them pass `items` directly.
      */
-    entity?: EntityRow | readonly EntityRow[];
+    entity?: EntityCollection<EntityRow>;
     /** Timeline title */
     title?: string;
     /** Timeline items */

package/dist/components/organisms/book/BookViewer.d.ts

@@ -17,9 +17,12 @@
  * - Listens: UI:BOOK_START, UI:BOOK_NAVIGATE, UI:BOOK_PAGE_PREV/NEXT, UI:BOOK_PRINT, UI:BOOK_SHOW_TOC
  */
 import React from 'react';
+import type { EntityRecord, EntityRow } from '@almadar/core';
 import type { EntityDisplayProps } from '../types';
 import type { BookFieldMap } from './types';
 export interface BookViewerProps extends EntityDisplayProps {
+    /** Renders ONE record (the book), not a collection */
+    entity?: EntityRecord<EntityRow>;
     /** Initial page index (default: 0 = cover) */
     initialPage?: number;
     /** Field name translation map — a BookFieldMap object or locale key ("ar") */

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

@@ -7,7 +7,7 @@
  * Exception: Form manages local `formData` state for field input tracking.
  * This is the ONE allowed exception — documented here.
  */
-import type { EntityRow } from '@almadar/core';
+import type { EntityRow, EntityInlet } from '@almadar/core';
 export declare const EntityDisplayEvents: {
     readonly SORT: "SORT";
     readonly PAGINATE: "PAGINATE";
@@ -61,7 +61,7 @@ export interface EntityDisplayProps<T extends EntityRow = EntityRow> {
      * extend `EntityRow`. They surface `EntityDisplayProps<T>` constraint errors.
      * Tracked as a Phase 7 follow-up in `docs/Almadar_Entity_V2_Plan.md` §10.
      */
-    entity?: T | readonly T[];
+    entity?: EntityInlet<T>;
     /** Additional CSS classes */
     className?: string;
     /** Loading state indicator */

package/dist/docs/index.d.cts

@@ -318,7 +318,7 @@ interface InputProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, "
     /** onChange handler - accepts events from input, select, or textarea */
     onChange?: React.ChangeEventHandler<HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement>;
 }
-declare const Input: React.ForwardRefExoticComponent<InputProps & React.RefAttributes<HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement>>;
+declare const Input: React.ForwardRefExoticComponent<InputProps & React.RefAttributes<HTMLSelectElement | HTMLInputElement | HTMLTextAreaElement>>;
 
 /**
  * DocSidebar Molecule Component