@almadar/patterns 2.34.1 → 2.36.0

package/dist/index.js

@@ -1,7 +1,7 @@
 // src/patterns-registry.json
 var patterns_registry_default = {
   version: "1.0.0",
-  exportedAt: "2026-05-30T10:04:19.715Z",
+  exportedAt: "2026-06-04T18:07:03.548Z",
   patterns: {
     "entity-table": {
       type: "entity-table",
@@ -20,6 +20,8 @@ var patterns_registry_default = {
             "array"
           ],
           description: "Entity record or array of records \u2014 pre-resolved by the trait via render-ui after a fetch emit",
+          kind: "entity",
+          cardinality: "collection",
           items: {
             types: [
               "object"
@@ -270,7 +272,9 @@ var patterns_registry_default = {
             "object",
             "array"
           ],
-          description: "Entity record or array of records \u2014 pre-resolved by the trait via render-ui after a fetch emit"
+          description: "Entity record or array of records \u2014 pre-resolved by the trait via render-ui after a fetch emit",
+          kind: "entity",
+          cardinality: "collection"
         },
         className: {
           types: [
@@ -447,7 +451,9 @@ var patterns_registry_default = {
             "object",
             "array"
           ],
-          description: "Entity record or array of records \u2014 pre-resolved by the trait via render-ui after a fetch emit"
+          description: "Entity record or array of records \u2014 pre-resolved by the trait via render-ui after a fetch emit",
+          kind: "entity",
+          cardinality: "collection"
         },
         className: {
           types: [
@@ -692,10 +698,11 @@ var patterns_registry_default = {
       propsSchema: {
         entity: {
           types: [
-            "object",
-            "array"
+            "object"
           ],
-          description: "Entity record or array of records \u2014 pre-resolved by the trait via render-ui after a fetch emit"
+          description: "RECORD-cardinality override: renders ONE record (see body collapse below).",
+          kind: "entity",
+          cardinality: "record"
         },
         className: {
           types: [
@@ -4054,6 +4061,8 @@ var patterns_registry_default = {
             "array"
           ],
           description: "Entity record or array of records \u2014 pre-resolved by the trait via render-ui after a fetch emit",
+          kind: "entity",
+          cardinality: "collection",
           items: {
             types: [
               "object"
@@ -9184,6 +9193,8 @@ var patterns_registry_default = {
             "array"
           ],
           description: "Entity record or array of records \u2014 pre-resolved by the trait via render-ui after a fetch emit",
+          kind: "entity",
+          cardinality: "collection",
           items: {
             types: [
               "object"
@@ -10514,7 +10525,14 @@ var patterns_registry_default = {
             "object",
             "array"
           ],
-          description: "Schema entity data typed against @almadar/core's EntityRow. Items from `entity` are normalised into `items` when `items` is omitted. UI-specific TimelineItem fields (`icon`, callbacks) cannot round-trip through the event bus, so decorative stories that need them pass `items` directly."
+          description: "Schema entity data typed against @almadar/core's EntityRow. Items from `entity` are normalised into `items` when `items` is omitted. UI-specific TimelineItem fields (`icon`, callbacks) cannot round-trip through the event bus, so decorative stories that need them pass `items` directly.",
+          kind: "entity",
+          cardinality: "collection",
+          items: {
+            types: [
+              "object"
+            ]
+          }
         },
         title: {
           types: [
@@ -10673,6 +10691,8 @@ var patterns_registry_default = {
             "array"
           ],
           description: "Entity record or array of records \u2014 pre-resolved by the trait via render-ui after a fetch emit",
+          kind: "entity",
+          cardinality: "collection",
           items: {
             types: [
               "object"
@@ -11960,7 +11980,9 @@ var patterns_registry_default = {
             "object",
             "array"
           ],
-          description: "Entity record or array of records \u2014 pre-resolved by the trait via render-ui after a fetch emit"
+          description: "Entity record or array of records \u2014 pre-resolved by the trait via render-ui after a fetch emit",
+          kind: "entity",
+          cardinality: "collection"
         },
         className: {
           types: [
@@ -12385,9 +12407,12 @@ var patterns_registry_default = {
         },
         events: {
           types: [
+            "object",
             "array"
           ],
           description: "Events to display on the grid",
+          kind: "entity",
+          cardinality: "collection",
           items: {
             types: [
               "object"
@@ -13097,8 +13122,15 @@ var patterns_registry_default = {
             "object",
             "array"
           ],
-          description: "Schema entity data \u2014 single record or collection, typed against `@almadar/core`'s `EntityRow` so the narrow type declared on the emitting trait's `Event { data : [X] }` flows through to the prop 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.",
-          required: true
+          description: "Schema entity data \u2014 single record or collection, typed against `@almadar/core`'s `EntityRow` so the narrow type declared on the emitting trait's `Event { data : [X] }` flows through to the prop 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[]` \u2014 see the brand's doc.",
+          required: true,
+          kind: "entity",
+          cardinality: "collection",
+          items: {
+            types: [
+              "object"
+            ]
+          }
         },
         fields: {
           types: [
@@ -13491,7 +13523,14 @@ var patterns_registry_default = {
             "array"
           ],
           description: "Schema entity data \u2014 single record or collection, typed against `@almadar/core`'s `EntityRow` so the narrow type declared on the emitting trait's `Event { data : [X] }` flows through to the prop without widening. The generic `T` lets consumers pass a narrower entity (e.g. `CartItem`) and have the `children` render function receive items of that exact shape.",
-          required: true
+          required: true,
+          kind: "entity",
+          cardinality: "collection",
+          items: {
+            types: [
+              "object"
+            ]
+          }
         },
         fields: {
           types: [
@@ -15114,10 +15153,13 @@ var patterns_registry_default = {
       propsSchema: {
         items: {
           types: [
+            "object",
             "array"
           ],
           description: "items prop",
           required: true,
+          kind: "entity",
+          cardinality: "collection",
           items: {
             types: [
               "object"
@@ -16760,6 +16802,8 @@ var patterns_registry_default = {
             "array"
           ],
           description: "Entity record or array of records \u2014 pre-resolved by the trait via render-ui after a fetch emit",
+          kind: "entity",
+          cardinality: "collection",
           items: {
             types: [
               "object"
@@ -16909,6 +16953,8 @@ var patterns_registry_default = {
             "array"
           ],
           description: "Entity record or array of records \u2014 pre-resolved by the trait via render-ui after a fetch emit",
+          kind: "entity",
+          cardinality: "collection",
           items: {
             types: [
               "object"
@@ -17053,155 +17099,151 @@ var patterns_registry_default = {
       propsSchema: {
         entity: {
           types: [
-            "object",
-            "array"
+            "object"
           ],
-          description: "Entity record or array of records \u2014 pre-resolved by the trait via render-ui after a fetch emit",
-          items: {
-            types: [
-              "object"
-            ],
-            properties: {
-              id: {
-                types: [
-                  "string"
-                ]
-              },
-              tag: {
-                types: [
-                  "string"
-                ]
-              },
-              title: {
-                types: [
-                  "string"
-                ]
-              },
-              titleAccent: {
-                types: [
-                  "string"
-                ]
-              },
-              subtitle: {
-                types: [
-                  "string"
-                ]
-              },
-              primaryAction: {
-                types: [
-                  "object"
-                ],
-                properties: {
-                  label: {
-                    types: [
-                      "string"
-                    ]
-                  },
-                  href: {
-                    types: [
-                      "string"
-                    ]
-                  },
-                  variant: {
-                    types: [
-                      "string"
-                    ],
-                    enumValues: [
-                      "primary",
-                      "secondary",
-                      "ghost"
-                    ]
-                  }
+          description: "entity prop",
+          kind: "entity",
+          cardinality: "record",
+          properties: {
+            id: {
+              types: [
+                "string"
+              ]
+            },
+            tag: {
+              types: [
+                "string"
+              ]
+            },
+            title: {
+              types: [
+                "string"
+              ]
+            },
+            titleAccent: {
+              types: [
+                "string"
+              ]
+            },
+            subtitle: {
+              types: [
+                "string"
+              ]
+            },
+            primaryAction: {
+              types: [
+                "object"
+              ],
+              properties: {
+                label: {
+                  types: [
+                    "string"
+                  ]
                 },
-                required: [
-                  "label",
-                  "href"
-                ]
-              },
-              secondaryAction: {
-                types: [
-                  "object"
-                ],
-                properties: {
-                  label: {
-                    types: [
-                      "string"
-                    ]
-                  },
-                  href: {
-                    types: [
-                      "string"
-                    ]
-                  },
-                  variant: {
-                    types: [
-                      "string"
-                    ],
-                    enumValues: [
-                      "primary",
-                      "secondary",
-                      "ghost"
-                    ]
-                  }
+                href: {
+                  types: [
+                    "string"
+                  ]
                 },
-                required: [
-                  "label",
-                  "href"
-                ]
-              },
-              installCommand: {
-                types: [
-                  "string"
-                ]
+                variant: {
+                  types: [
+                    "string"
+                  ],
+                  enumValues: [
+                    "primary",
+                    "secondary",
+                    "ghost"
+                  ]
+                }
               },
-              image: {
-                types: [
-                  "object"
-                ],
-                properties: {
-                  src: {
-                    types: [
-                      "string"
-                    ]
-                  },
-                  alt: {
-                    types: [
-                      "string"
-                    ]
-                  }
+              required: [
+                "label",
+                "href"
+              ]
+            },
+            secondaryAction: {
+              types: [
+                "object"
+              ],
+              properties: {
+                label: {
+                  types: [
+                    "string"
+                  ]
                 },
-                required: [
-                  "src",
-                  "alt"
-                ]
+                href: {
+                  types: [
+                    "string"
+                  ]
+                },
+                variant: {
+                  types: [
+                    "string"
+                  ],
+                  enumValues: [
+                    "primary",
+                    "secondary",
+                    "ghost"
+                  ]
+                }
               },
-              imagePosition: {
-                types: [
-                  "string"
-                ],
-                enumValues: [
-                  "below",
-                  "right",
-                  "background"
-                ]
+              required: [
+                "label",
+                "href"
+              ]
+            },
+            installCommand: {
+              types: [
+                "string"
+              ]
+            },
+            image: {
+              types: [
+                "object"
+              ],
+              properties: {
+                src: {
+                  types: [
+                    "string"
+                  ]
+                },
+                alt: {
+                  types: [
+                    "string"
+                  ]
+                }
               },
-              background: {
-                types: [
-                  "string"
-                ],
-                enumValues: [
-                  "dark",
-                  "gradient",
-                  "subtle"
-                ]
-              }
+              required: [
+                "src",
+                "alt"
+              ]
             },
-            required: [
-              "id",
-              "title",
-              "subtitle"
-            ]
-          }
+            imagePosition: {
+              types: [
+                "string"
+              ],
+              enumValues: [
+                "below",
+                "right",
+                "background"
+              ]
+            },
+            background: {
+              types: [
+                "string"
+              ],
+              enumValues: [
+                "dark",
+                "gradient",
+                "subtle"
+              ]
+            }
+          },
+          propertyRequired: [
+            "id",
+            "title",
+            "subtitle"
+          ]
         },
         className: {
           types: [
@@ -17295,6 +17337,8 @@ var patterns_registry_default = {
             "array"
           ],
           description: "Entity record or array of records \u2014 pre-resolved by the trait via render-ui after a fetch emit",
+          kind: "entity",
+          cardinality: "collection",
           items: {
             types: [
               "object"
@@ -17459,6 +17503,8 @@ var patterns_registry_default = {
             "array"
           ],
           description: "Entity record or array of records \u2014 pre-resolved by the trait via render-ui after a fetch emit",
+          kind: "entity",
+          cardinality: "collection",
           items: {
             types: [
               "object"
@@ -17628,6 +17674,8 @@ var patterns_registry_default = {
             "array"
           ],
           description: "Entity record or array of records \u2014 pre-resolved by the trait via render-ui after a fetch emit",
+          kind: "entity",
+          cardinality: "collection",
           items: {
             types: [
               "object"
@@ -17750,6 +17798,8 @@ var patterns_registry_default = {
             "array"
           ],
           description: "Entity record or array of records \u2014 pre-resolved by the trait via render-ui after a fetch emit",
+          kind: "entity",
+          cardinality: "collection",
           items: {
             types: [
               "object"
@@ -17904,6 +17954,8 @@ var patterns_registry_default = {
             "array"
           ],
           description: "Entity record or array of records \u2014 pre-resolved by the trait via render-ui after a fetch emit",
+          kind: "entity",
+          cardinality: "collection",
           items: {
             types: [
               "object"
@@ -19509,10 +19561,13 @@ var patterns_registry_default = {
       propsSchema: {
         nodes: {
           types: [
+            "object",
             "array"
           ],
           description: "nodes prop",
           required: true,
+          kind: "entity",
+          cardinality: "collection",
           items: {
             types: [
               "object"
@@ -20089,11 +20144,84 @@ var patterns_registry_default = {
       propsSchema: {
         items: {
           types: [
-            "array",
-            "object"
+            "object",
+            "array"
           ],
           description: "Items to render. Accepts either a typed array (direct consumers) or the runtime payload shape from a render-ui binding (`@payload.data`). The molecule narrows non-array values to `[]` and validates element shape at render time via the `id` / `x` / `y` guards.",
-          required: true
+          required: true,
+          kind: "entity",
+          cardinality: "collection",
+          items: {
+            types: [
+              "object"
+            ],
+            properties: {
+              id: {
+                types: [
+                  "string"
+                ]
+              },
+              label: {
+                types: [
+                  "string"
+                ]
+              },
+              x: {
+                types: [
+                  "number"
+                ]
+              },
+              y: {
+                types: [
+                  "number"
+                ]
+              },
+              shape: {
+                types: [
+                  "string"
+                ],
+                enumValues: [
+                  "round",
+                  "rectangle",
+                  "square"
+                ]
+              },
+              capacity: {
+                types: [
+                  "number"
+                ]
+              },
+              status: {
+                types: [
+                  "string"
+                ],
+                enumValues: [
+                  "empty",
+                  "seated",
+                  "ordered",
+                  "awaiting-bill",
+                  "cleaning"
+                ]
+              },
+              partySize: {
+                types: [
+                  "number"
+                ]
+              },
+              serverName: {
+                types: [
+                  "string"
+                ]
+              }
+            },
+            required: [
+              "id",
+              "label",
+              "x",
+              "y",
+              "capacity"
+            ]
+          }
         },
         width: {
           types: [
@@ -26154,10 +26282,11 @@ var patterns_registry_default = {
       propsSchema: {
         entity: {
           types: [
-            "object",
-            "array"
+            "object"
           ],
-          description: "Entity record or array of records \u2014 pre-resolved by the trait via render-ui after a fetch emit"
+          description: "Renders ONE record (the book), not a collection",
+          kind: "entity",
+          cardinality: "record"
         },
         className: {
           types: [
@@ -31467,7 +31596,9 @@ var patterns_registry_default = {
             "object",
             "array"
           ],
-          description: "Entity record or array of records \u2014 pre-resolved by the trait via render-ui after a fetch emit"
+          description: "Entity record or array of records \u2014 pre-resolved by the trait via render-ui after a fetch emit",
+          kind: "entity",
+          cardinality: "collection"
         },
         className: {
           types: [
@@ -32313,7 +32444,14 @@ var patterns_registry_default = {
             "array"
           ],
           description: "Schema entity data \u2014 single record or collection.",
-          required: true
+          required: true,
+          kind: "entity",
+          cardinality: "collection",
+          items: {
+            types: [
+              "object"
+            ]
+          }
         },
         columns: {
           types: [
@@ -33615,7 +33753,7 @@ var integrators_registry_default = {
 // src/component-mapping.json
 var component_mapping_default = {
   version: "1.0.0",
-  exportedAt: "2026-05-30T10:04:19.715Z",
+  exportedAt: "2026-06-04T18:07:03.548Z",
   mappings: {
     "page-header": {
       component: "PageHeader",
@@ -35155,7 +35293,7 @@ var component_mapping_default = {
 // src/event-contracts.json
 var event_contracts_default = {
   version: "1.0.0",
-  exportedAt: "2026-05-30T10:04:19.715Z",
+  exportedAt: "2026-06-04T18:07:03.548Z",
   contracts: {
     form: {
       emits: [
@@ -37045,6 +37183,44 @@ function formatRecommendationsForPrompt(recommendations) {
   return lines.join("\n");
 }
 
+// src/helpers/pattern-swap.ts
+var PATTERNS = patterns_registry_default;
+var CONTRACTS = event_contracts_default;
+function entityInlet(patternType) {
+  const propsSchema = PATTERNS.patterns?.[patternType]?.propsSchema;
+  if (!propsSchema) return null;
+  for (const prop of Object.values(propsSchema)) {
+    if (prop.kind === "entity") return prop;
+  }
+  return propsSchema["entity"] ?? null;
+}
+function getEntityCardinality(patternType) {
+  return entityInlet(patternType)?.cardinality ?? null;
+}
+function getEmittedEvents(patternType) {
+  const emits = CONTRACTS.contracts?.[patternType]?.emits ?? [];
+  const out = [];
+  for (const e of emits) {
+    if (typeof e.event === "string") out.push(e.event);
+  }
+  return out;
+}
+function findCompatiblePatterns(currentType, gate = {}) {
+  const cardinality = getEntityCardinality(currentType);
+  const required = gate.requiredEmits ?? [];
+  const result = [];
+  for (const type of Object.keys(PATTERNS.patterns ?? {})) {
+    if (type === currentType) continue;
+    if (getEntityCardinality(type) !== cardinality) continue;
+    if (required.length > 0) {
+      const emits = new Set(getEmittedEvents(type));
+      if (!required.every((ev) => emits.has(ev))) continue;
+    }
+    result.push(type);
+  }
+  return result;
+}
+
 // src/index.ts
 var registry = patterns_registry_default;
 var PATTERN_REGISTRY = patterns_registry_default;
@@ -37067,6 +37243,6 @@ function isEntityAwarePattern(patternType) {
   return "entity" in propsSchema;
 }
 
-export { COMPONENT_MAPPING, EVENT_CONTRACTS, INTEGRATORS_REGISTRY, PATTERN_REGISTRY, PATTERN_TYPES, buildRecommendationContext, component_mapping_default as componentMapping, event_contracts_default as eventContracts, formatRecommendationsForPrompt, generatePatternDescription, getAllPatternTypes, getComponentForPattern, getOrbAllowedPatterns, getOrbAllowedPatternsCompact, getOrbAllowedPatternsFiltered, getOrbAllowedPatternsSlim, getPatternActionsRef, getPatternDefinition, getPatternMetadata, getPatternPropsCompact, getPatternsGroupedByCategory, integrators_registry_default as integratorsRegistry, isEntityAwarePattern, isValidPatternType, patterns_registry_default as patternsRegistry, recommendPatterns, registry };
+export { COMPONENT_MAPPING, EVENT_CONTRACTS, INTEGRATORS_REGISTRY, PATTERN_REGISTRY, PATTERN_TYPES, buildRecommendationContext, component_mapping_default as componentMapping, event_contracts_default as eventContracts, findCompatiblePatterns, formatRecommendationsForPrompt, generatePatternDescription, getAllPatternTypes, getComponentForPattern, getEmittedEvents, getEntityCardinality, getOrbAllowedPatterns, getOrbAllowedPatternsCompact, getOrbAllowedPatternsFiltered, getOrbAllowedPatternsSlim, getPatternActionsRef, getPatternDefinition, getPatternMetadata, getPatternPropsCompact, getPatternsGroupedByCategory, integrators_registry_default as integratorsRegistry, isEntityAwarePattern, isValidPatternType, patterns_registry_default as patternsRegistry, recommendPatterns, registry };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map