@almadar/patterns 1.0.15 → 1.1.0

package/LICENSE

@@ -0,0 +1,72 @@
+Business Source License 1.1
+
+Parameters
+
+Licensor:             Almadar FZE
+Licensed Work:        KFlow Builder / Almadar
+                      The Licensed Work is (c) 2025-2026 Almadar FZE.
+Additional Use Grant: You may make production use of the Licensed Work for
+                      non-commercial purposes and for internal evaluation.
+                      Production use for commercial purposes requires a
+                      commercial license from the Licensor.
+Change Date:          2030-02-01
+Change License:       Apache License, Version 2.0
+
+Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative
+works, redistribute, and make non-production use of the Licensed Work. The
+Licensor may make an Additional Use Grant, above, permitting limited
+production use.
+
+Effective on the Change Date, or the fourth anniversary of the first publicly
+available distribution of a specific version of the Licensed Work under this
+License, whichever comes first, the Licensor hereby grants you rights under
+the terms of the Change License, and the rights granted in the paragraph
+above terminate.
+
+If your use of the Licensed Work does not comply with the requirements
+currently in effect as described in this License, you must purchase a
+commercial license from the Licensor, its affiliated entities, or authorized
+resellers, or you must refrain from using the Licensed Work.
+
+All copies of the original and modified Licensed Work, and derivative works
+of the Licensed Work, are subject to this License. This License applies
+separately for each version of the Licensed Work and the Change Date may vary
+for each version of the Licensed Work released by Licensor.
+
+You must conspicuously display this License on each original or modified copy
+of the Licensed Work. If you receive the Licensed Work in original or
+modified form from a third party, the terms and conditions set forth in this
+License apply to your use of that work.
+
+Any use of the Licensed Work in violation of this License will automatically
+terminate your rights under this License for the current and all other
+versions of the Licensed Work.
+
+This License does not grant you any right in any trademark or logo of
+Licensor or its affiliates (provided that you may use a trademark or logo of
+Licensor as expressly required by this License).
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON
+AN "AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS,
+EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND
+TITLE.
+
+---
+
+License text copyright (c) 2017 MariaDB Corporation Ab, All Rights Reserved.
+"Business Source License" is a trademark of MariaDB Corporation Ab.
+
+ADDITIONAL TERMS:
+
+Documentation (builder/packages/website/docs/) is licensed under CC BY 4.0.
+
+TRADEMARKS:
+
+"Orbital", "KFlow", "Almadar", and the Almadar logo are trademarks of
+Almadar FZE. You may not use these trademarks without prior written
+permission from Almadar FZE.
+
+For licensing inquiries: licensing@almadar.io

package/dist/index.d.ts

@@ -14213,6 +14213,96 @@ declare function getAllPatternTypes(): PatternType[];
  */
 declare function getPatternMetadata(patternType: string): any;
 
+/**
+ * Pattern Recommender
+ *
+ * Maps transition context (entity fields, domain category, UI state) to
+ * ranked pattern suggestions using the registry's `suggestedFor` metadata,
+ * category matching, and entity field type heuristics.
+ *
+ * Used by the design-transition tool to include top-N recommendations
+ * in the LLM prompt context.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Context for pattern recommendation.
+ */
+interface RecommendationContext {
+    /** Current state name (e.g., "Browsing", "Creating") */
+    state?: string;
+    /** Triggering event (e.g., "INIT", "CREATE", "VIEW") */
+    event?: string;
+    /** Target UI slot */
+    slot?: 'main' | 'modal' | 'drawer' | 'sidebar' | 'overlay';
+    /** Domain category */
+    domainCategory?: string;
+    /** Entity field types present */
+    entityFieldTypes?: string[];
+    /** Entity has enum fields */
+    hasEnumFields?: boolean;
+    /** Entity has date/timestamp fields */
+    hasDateFields?: boolean;
+    /** Entity has numeric fields */
+    hasNumericFields?: boolean;
+    /** Entity has relation fields */
+    hasRelationFields?: boolean;
+    /** Entity has image/url fields */
+    hasMediaFields?: boolean;
+}
+/**
+ * A pattern recommendation with score and reasoning.
+ */
+interface PatternRecommendation {
+    /** Pattern type name */
+    pattern: PatternType;
+    /** Relevance score (0-100) */
+    score: number;
+    /** Why this pattern was recommended */
+    reason: string;
+    /** Pattern category */
+    category: string;
+    /** Pattern description */
+    description: string;
+    /** Key props to use */
+    keyProps: string[];
+}
+/**
+ * Recommend patterns for a given context.
+ *
+ * Scoring algorithm:
+ * 1. suggestedFor match with domain keywords (+30)
+ * 2. suggestedFor match with event keywords (+25)
+ * 3. Category affinity with slot (+20)
+ * 4. Category affinity with state (+15)
+ * 5. Entity field type bonus (+10 per matching heuristic)
+ * 6. Entity-aware bonus for display patterns (+5)
+ *
+ * @returns Ranked pattern recommendations, highest score first
+ */
+declare function recommendPatterns(context: RecommendationContext, maxResults?: number): PatternRecommendation[];
+/**
+ * Build recommendation context from entity field information.
+ * Analyzes field types to set the boolean flags used by the recommender.
+ */
+declare function buildRecommendationContext(options: {
+    state?: string;
+    event?: string;
+    slot?: 'main' | 'modal' | 'drawer' | 'sidebar' | 'overlay';
+    domainCategory?: string;
+    entityFields?: Array<{
+        name: string;
+        type: string;
+        values?: string[];
+    }>;
+}): RecommendationContext;
+/**
+ * Format recommendations as a concise prompt section.
+ * Used to inject into the design-transition tool's user prompt.
+ */
+declare function formatRecommendationsForPrompt(recommendations: PatternRecommendation[]): string;
+
 declare const registry: {
     version: string;
     exportedAt: string;
@@ -28148,4 +28238,4 @@ declare function getComponentForPattern(patternType: string): any;
  */
 declare function isEntityAwarePattern(patternType: string): boolean;
 
-export { type AnyPatternConfig, COMPONENT_MAPPING, EVENT_CONTRACTS, INTEGRATORS_REGISTRY, PATTERN_REGISTRY, PATTERN_TYPES, type PatternConfig, type PatternProps, type PatternPropsMap, type PatternType, componentMapping, eventContracts, generatePatternDescription, getAllPatternTypes, getComponentForPattern, getPatternActionsRef, getPatternDefinition, getPatternMetadata, getPatternPropsCompact, getPatternsGroupedByCategory, integratorsRegistry, isEntityAwarePattern, isValidPatternType, patternsRegistry, registry };
+export { type AnyPatternConfig, COMPONENT_MAPPING, EVENT_CONTRACTS, INTEGRATORS_REGISTRY, PATTERN_REGISTRY, PATTERN_TYPES, type PatternConfig, type PatternProps, type PatternPropsMap, type PatternRecommendation, type PatternType, type RecommendationContext, buildRecommendationContext, componentMapping, eventContracts, formatRecommendationsForPrompt, generatePatternDescription, getAllPatternTypes, getComponentForPattern, getPatternActionsRef, getPatternDefinition, getPatternMetadata, getPatternPropsCompact, getPatternsGroupedByCategory, integratorsRegistry, isEntityAwarePattern, isValidPatternType, patternsRegistry, recommendPatterns, registry };

package/dist/index.js

@@ -11484,6 +11484,161 @@ function getPatternMetadata(patternType) {
   return patterns[patternType] || null;
 }
 
+// src/helpers/pattern-recommender.ts
+var DOMAIN_KEYWORDS = {
+  business: ["admin panels", "data-dense views", "list pages", "data entry", "comparisons"],
+  dashboard: ["dashboards", "analytics", "overview pages", "overview screens", "data visualization", "reporting", "KPI indicators"],
+  "e-commerce": ["visual items", "images", "previews", "data entry", "list pages"],
+  content: ["visual items", "images", "previews", "media", "pages with multiple views"],
+  social: ["activity logs", "visual items", "previews"],
+  workflow: ["process tracking", "workflow steps", "multi-step forms", "wizards"],
+  form: ["data entry", "create forms", "edit forms", "multi-step forms"],
+  game: ["game", "real-time", "interactive"]
+};
+var EVENT_KEYWORDS = {
+  INIT: ["list pages", "overview pages", "dashboards", "admin panels"],
+  CREATE: ["create forms", "data entry", "multi-step forms"],
+  EDIT: ["edit forms", "data entry"],
+  VIEW: ["detail pages", "entity management", "pages with multiple views"],
+  DELETE: ["destructive actions", "confirmations"],
+  FILTER: ["filterable data", "search functionality", "quick filters"]
+};
+var SLOT_CATEGORY_AFFINITY = {
+  main: ["display", "dashboard", "filter", "header", "layout", "visualization", "navigation", "template"],
+  modal: ["form", "container", "state"],
+  drawer: ["display", "form", "navigation"],
+  sidebar: ["navigation", "filter"],
+  overlay: ["container", "state"]
+};
+var STATE_CATEGORY_AFFINITY = {
+  Browsing: ["display", "filter", "header", "dashboard", "visualization"],
+  Creating: ["form", "navigation"],
+  Editing: ["form", "navigation"],
+  Viewing: ["display", "navigation"],
+  Deleting: ["container", "state"]
+};
+function recommendPatterns(context, maxResults = 10) {
+  const patterns = patterns_registry_default.patterns || {};
+  const scores = /* @__PURE__ */ new Map();
+  const domainKeywords = context.domainCategory ? DOMAIN_KEYWORDS[context.domainCategory] || [] : [];
+  const eventKeywords = context.event ? EVENT_KEYWORDS[context.event] || [] : [];
+  const slotCategories = context.slot ? SLOT_CATEGORY_AFFINITY[context.slot] || [] : [];
+  const stateCategories = context.state ? STATE_CATEGORY_AFFINITY[context.state] || [] : [];
+  for (const [patternName, patternDef] of Object.entries(patterns)) {
+    const suggestedFor = patternDef.suggestedFor || [];
+    const category = patternDef.category || "";
+    let score = 0;
+    const reasons = [];
+    if (category === "game" && context.domainCategory !== "game") continue;
+    if (category === "debug") continue;
+    if (category === "template") continue;
+    for (const keyword of domainKeywords) {
+      if (suggestedFor.some((sf) => sf.toLowerCase().includes(keyword.toLowerCase()))) {
+        score += 30;
+        reasons.push(`domain:${keyword}`);
+        break;
+      }
+    }
+    for (const keyword of eventKeywords) {
+      if (suggestedFor.some((sf) => sf.toLowerCase().includes(keyword.toLowerCase()))) {
+        score += 25;
+        reasons.push(`event:${keyword}`);
+        break;
+      }
+    }
+    if (slotCategories.includes(category)) {
+      score += 20;
+      reasons.push(`slot:${context.slot}`);
+    }
+    if (stateCategories.includes(category)) {
+      score += 15;
+      reasons.push(`state:${context.state}`);
+    }
+    if (context.hasEnumFields && ["filter-group", "tabs", "badge"].includes(patternName)) {
+      score += 10;
+      reasons.push("enum-fields");
+    }
+    if (context.hasDateFields && ["timeline", "chart"].includes(patternName)) {
+      score += 10;
+      reasons.push("date-fields");
+    }
+    if (context.hasNumericFields && ["stats", "chart", "meter", "progress-bar"].includes(patternName)) {
+      score += 10;
+      reasons.push("numeric-fields");
+    }
+    if (context.hasRelationFields && ["tabs", "master-detail"].includes(patternName)) {
+      score += 10;
+      reasons.push("relation-fields");
+    }
+    if (context.hasMediaFields && ["entity-cards", "media-gallery"].includes(patternName)) {
+      score += 10;
+      reasons.push("media-fields");
+    }
+    if (category === "display" || category === "dashboard") {
+      const propsSchema = patternDef.propsSchema || {};
+      if ("entity" in propsSchema) {
+        score += 5;
+        reasons.push("entity-aware");
+      }
+    }
+    if (score > 0) {
+      scores.set(patternName, { score, reasons });
+    }
+  }
+  const ranked = [...scores.entries()].sort((a, b) => b[1].score - a[1].score).slice(0, maxResults);
+  return ranked.map(([patternName, { score, reasons }]) => {
+    const patternDef = patterns[patternName];
+    const propsSchema = patternDef.propsSchema || {};
+    const keyProps = Object.keys(propsSchema).filter((k) => propsSchema[k]?.required === true).slice(0, 5);
+    if (keyProps.length === 0) {
+      const meaningful = Object.keys(propsSchema).filter(
+        (k) => !["className", "isLoading", "error", "entity"].includes(k)
+      );
+      keyProps.push(...meaningful.slice(0, 4));
+    }
+    return {
+      pattern: patternName,
+      score,
+      reason: reasons.join(", "),
+      category: patternDef.category || "unknown",
+      description: patternDef.description || patternName,
+      keyProps
+    };
+  });
+}
+function buildRecommendationContext(options) {
+  const fields = options.entityFields || [];
+  const fieldTypes = fields.map((f) => f.type);
+  return {
+    state: options.state,
+    event: options.event,
+    slot: options.slot,
+    domainCategory: options.domainCategory,
+    entityFieldTypes: fieldTypes,
+    hasEnumFields: fields.some((f) => f.type === "enum" || f.values && f.values.length > 0),
+    hasDateFields: fields.some((f) => ["date", "datetime", "timestamp"].includes(f.type)),
+    hasNumericFields: fields.some((f) => ["number", "integer", "float", "decimal", "currency"].includes(f.type)),
+    hasRelationFields: fields.some((f) => f.type === "relation"),
+    hasMediaFields: fields.some((f) => ["image", "url", "media", "file"].includes(f.type))
+  };
+}
+function formatRecommendationsForPrompt(recommendations) {
+  if (recommendations.length === 0) return "";
+  const lines = [
+    "## Recommended Patterns",
+    "",
+    "| Pattern | Category | Key Props | Why |",
+    "|---------|----------|-----------|-----|"
+  ];
+  for (const rec of recommendations) {
+    const props = rec.keyProps.length > 0 ? rec.keyProps.join(", ") : "\u2014";
+    lines.push(`| ${rec.pattern} | ${rec.category} | ${props} | ${rec.reason} |`);
+  }
+  lines.push("");
+  lines.push("Use these patterns where appropriate. Combine multiple for rich INIT transitions.");
+  return lines.join("\n");
+}
+
 // src/index.ts
 var registry = patterns_registry_default;
 var PATTERN_REGISTRY = patterns_registry_default;
@@ -11507,6 +11662,6 @@ function isEntityAwarePattern(patternType) {
   return hasEntityProp && hasDataProp;
 }
 
-export { COMPONENT_MAPPING, EVENT_CONTRACTS, INTEGRATORS_REGISTRY, PATTERN_REGISTRY, PATTERN_TYPES, component_mapping_default as componentMapping, event_contracts_default as eventContracts, generatePatternDescription, getAllPatternTypes, getComponentForPattern, getPatternActionsRef, getPatternDefinition, getPatternMetadata, getPatternPropsCompact, getPatternsGroupedByCategory, integrators_registry_default as integratorsRegistry, isEntityAwarePattern, isValidPatternType, patterns_registry_default as patternsRegistry, registry };
+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, 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