@almadar/patterns 2.8.13 → 2.9.0

package/dist/helpers/pattern-recommender.d.ts

@@ -0,0 +1,89 @@
+/**
+ * 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
+ */
+import type { PatternType } from '../pattern-types.js';
+/**
+ * Context for pattern recommendation.
+ */
+export 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.
+ */
+export 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
+ */
+export 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.
+ */
+export 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.
+ */
+export declare function formatRecommendationsForPrompt(recommendations: PatternRecommendation[]): string;

package/dist/helpers/prompt-helpers.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Prompt Helpers for @almadar/patterns
+ *
+ * Helper functions for generating prompts/documentation from pattern registry.
+ * Used by @almadar/skills package and other tools.
+ *
+ * @packageDocumentation
+ */
+import type { PatternType } from '../pattern-types.js';
+type PatternEntry = {
+    category?: string;
+    description?: string;
+    propsSchema?: Record<string, {
+        types?: string[];
+        required?: boolean;
+    }>;
+    entityAware?: boolean;
+};
+/**
+ * Get patterns grouped by category.
+ * Categories are derived from pattern registry metadata.
+ */
+export declare function getPatternsGroupedByCategory(): Record<string, PatternType[]>;
+/**
+ * Get compact pattern props reference table.
+ * Generates markdown table of pattern names and their key props.
+ */
+export declare function getPatternPropsCompact(): string;
+/**
+ * Get pattern action props reference.
+ * Lists patterns that have action/event props (buttons, forms, etc.).
+ */
+export declare function getPatternActionsRef(): string;
+/**
+ * Generate pattern description from metadata.
+ * Auto-generates human-readable description from pattern props schema.
+ */
+export declare function generatePatternDescription(patternType: string): string;
+/**
+ * Get all pattern types as array.
+ */
+export declare function getAllPatternTypes(): PatternType[];
+/**
+ * Get pattern metadata for a specific pattern.
+ */
+export declare function getPatternMetadata(patternType: string): PatternEntry | null;
+/**
+ * Get patterns allowed in .orb render-ui trees.
+ *
+ * Returns all non-entity patterns (atoms/molecules) plus the allowed
+ * entity-aware exceptions (data-list, data-grid, search-input, form-section, meter).
+ * Excludes game-specific, debug, and template patterns.
+ *
+ * Grouped by registry category with description and key props.
+ */
+export declare function getOrbAllowedPatterns(): Record<string, Array<{
+    name: string;
+    description: string;
+    keyProps: string[];
+}>>;
+/**
+ * Get compact markdown reference of .orb-allowed patterns.
+ * Derives everything from the registry. No hardcoded pattern lists.
+ */
+export declare function getOrbAllowedPatternsCompact(): string;
+/**
+ * Get a slim one-line-per-pattern catalog for Gate 3.5 pattern selection.
+ * Format: "- pattern-name: one-line description"
+ * Much smaller than the full compact reference (~800 tokens vs ~3,500).
+ */
+export declare function getOrbAllowedPatternsSlim(): string;
+/**
+ * Get compact markdown reference for a filtered subset of patterns.
+ * Used by Gate 4 after Gate 3.5 selects the relevant patterns.
+ * Includes all props (not just top 5) since we're showing fewer patterns.
+ */
+export declare function getOrbAllowedPatternsFiltered(patternNames: string[]): string;
+export {};