@nikkory/vibe-engine 4.0.0

package/dist/ui-studio/types/granularity/base.types.d.ts

@@ -0,0 +1,268 @@
+/**
+ * Base Types for Unified Granularity Architecture
+ *
+ * This file defines the core types for the 6-level granularity system,
+ * replacing duplicate Section/Page/Layout/Template patterns with a
+ * unified generic approach.
+ *
+ * @packageDocumentation
+ * @module types/granularity
+ * @since 4.0.0
+ *
+ * Powered by Nikkory
+ */
+import type { DesignSystem, Tier } from '../../../types';
+/**
+ * 6 Granularity Levels - Component hierarchy from smallest to largest
+ *
+ * @category types
+ * @since 4.0.0
+ *
+ * @example
+ * ```typescript
+ * const level: GranularityLevel = 'section';
+ * const config: GranularityConfig<'page'> = { ... };
+ * ```
+ *
+ * Powered by Nikkory
+ */
+export type GranularityLevel = 'atom' | 'component' | 'section' | 'page' | 'layout' | 'template';
+/**
+ * Granularity hierarchy for cascade - ordered from highest to lowest
+ *
+ * Higher levels cascade factors DOWN to lower levels.
+ * Template is the highest level (6), Atom is the lowest (1).
+ *
+ * @category constants
+ * @since 4.0.0
+ *
+ * @example
+ * ```typescript
+ * // Iterate from highest to lowest
+ * for (const level of GRANULARITY_HIERARCHY) {
+ *   console.log(level); // template, layout, page, section, component, atom
+ * }
+ * ```
+ *
+ * Powered by Nikkory
+ */
+export declare const GRANULARITY_HIERARCHY: readonly GranularityLevel[];
+/**
+ * Get numeric rank for a granularity level
+ *
+ * Returns a number where:
+ * - template = 6 (highest)
+ * - layout = 5
+ * - page = 4
+ * - section = 3
+ * - component = 2
+ * - atom = 1 (lowest)
+ *
+ * @category utils
+ * @since 4.0.0
+ *
+ * @param level - The granularity level to get rank for
+ * @returns Numeric rank (1-6)
+ *
+ * @example
+ * ```typescript
+ * getGranularityRank('template'); // 6
+ * getGranularityRank('atom');     // 1
+ * getGranularityRank('section');  // 3
+ *
+ * // Use for comparison
+ * if (getGranularityRank(a) > getGranularityRank(b)) {
+ *   // a is higher level than b
+ * }
+ * ```
+ *
+ * Powered by Nikkory
+ */
+export declare function getGranularityRank(level: GranularityLevel): number;
+/**
+ * Factor categories for grouping related factors
+ *
+ * @category types
+ * @since 4.0.0
+ *
+ * @example
+ * ```typescript
+ * const category: FactorCategory = 'visual';
+ * ```
+ *
+ * Powered by Nikkory
+ */
+export type GranularityFactorCategory = 'visual' | 'layout' | 'behavior' | 'responsive' | 'a11y';
+/**
+ * Factor definition with level and cascade behavior
+ *
+ * This REPLACES hardcoded 8/13/24 factor arrays with a dynamic
+ * registry-based approach where each factor specifies its minimum
+ * level and whether it cascades down to child granularities.
+ *
+ * @category types
+ * @since 4.0.0
+ *
+ * @example
+ * ```typescript
+ * const spacingFactor: GranularityFactorDefinition = {
+ *   id: 'spacing',
+ *   name: 'Spacing',
+ *   category: 'layout',
+ *   level: 'template',
+ *   cascadeDown: true,
+ *   defaults: {
+ *     'material-design': 'md',
+ *     'ios-hig': 'sm'
+ *   },
+ *   options: ['xs', 'sm', 'md', 'lg', 'xl'],
+ *   description: 'Controls spacing between elements'
+ * };
+ * ```
+ *
+ * Powered by Nikkory
+ */
+export interface GranularityFactorDefinition {
+    /** Factor unique identifier */
+    readonly id: string;
+    /** Human-readable name */
+    readonly name: string;
+    /** Factor category */
+    readonly category: GranularityFactorCategory;
+    /** Minimum granularity level where this factor applies */
+    readonly level: GranularityLevel;
+    /** Whether factor cascades DOWN to child granularities */
+    readonly cascadeDown: boolean;
+    /** Default value per design system */
+    readonly defaults: Partial<Record<DesignSystem, unknown>>;
+    /** Possible values */
+    readonly options?: readonly unknown[];
+    /** Description for documentation */
+    readonly description: string;
+}
+/**
+ * Template visibility levels for sharing
+ *
+ * @category types
+ * @since 4.0.0
+ *
+ * Powered by Nikkory
+ */
+export type GranularityTemplateVisibility = 'private' | 'team' | 'public';
+/**
+ * Layout configuration for slot arrangements
+ *
+ * @category types
+ * @since 4.0.0
+ *
+ * @example
+ * ```typescript
+ * const layout: LayoutConfig = {
+ *   type: 'grid',
+ *   columns: 3,
+ *   gap: 'md',
+ *   alignment: 'center'
+ * };
+ * ```
+ *
+ * Powered by Nikkory
+ */
+export interface GranularityLayoutConfig {
+    readonly type: 'grid' | 'flex' | 'stack' | 'masonry' | 'carousel';
+    readonly columns?: 1 | 2 | 3 | 4 | 6;
+    readonly gap?: GranularitySpacingLevel;
+    readonly alignment?: GranularityAlignmentType;
+}
+/**
+ * Spacing levels for consistent spacing scale
+ *
+ * @category types
+ * @since 4.0.0
+ *
+ * Powered by Nikkory
+ */
+export type GranularitySpacingLevel = 'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl';
+/**
+ * Alignment types for layout positioning
+ *
+ * @category types
+ * @since 4.0.0
+ *
+ * Powered by Nikkory
+ */
+export type GranularityAlignmentType = 'start' | 'center' | 'end' | 'stretch' | 'between';
+/**
+ * Style overrides for customization
+ *
+ * @category types
+ * @since 4.0.0
+ *
+ * @example
+ * ```typescript
+ * const styles: StyleOverrides = {
+ *   className: 'custom-section',
+ *   tailwindClasses: 'bg-gray-100 p-4 rounded-lg'
+ * };
+ * ```
+ *
+ * Powered by Nikkory
+ */
+export interface GranularityStyleOverrides {
+    readonly className?: string;
+    readonly style?: Record<string, string>;
+    readonly tailwindClasses?: string;
+}
+/**
+ * Factor values map - key-value pairs for resolved factors
+ *
+ * @category types
+ * @since 4.0.0
+ *
+ * @example
+ * ```typescript
+ * const factors: FactorValues = {
+ *   spacing: 'md',
+ *   colorPrimary: '#3B82F6',
+ *   borderRadius: 'lg'
+ * };
+ * ```
+ *
+ * Powered by Nikkory
+ */
+export type GranularityFactorValues = Record<string, unknown>;
+/**
+ * Base fields shared by ALL granularity levels
+ *
+ * This interface defines the common fields that every granularity
+ * config must have, regardless of whether it's an atom, component,
+ * section, page, layout, or template.
+ *
+ * @category types
+ * @since 4.0.0
+ *
+ * @typeParam G - The granularity level this config is for
+ *
+ * @example
+ * ```typescript
+ * interface MySectionConfig extends GranularityBaseFields<'section'> {
+ *   customField: string;
+ * }
+ * ```
+ *
+ * Powered by Nikkory
+ */
+export interface GranularityBaseFields<G extends GranularityLevel> {
+    /** Unique identifier */
+    readonly id: string;
+    /** Granularity level */
+    readonly granularity: G;
+    /** Design system */
+    readonly designSystem: DesignSystem;
+    /** Quality tier */
+    readonly tier: Tier;
+    /** Display title */
+    readonly title: string;
+    /** Optional subtitle/description */
+    readonly subtitle?: string;
+}
+//# sourceMappingURL=base.types.d.ts.map

package/dist/ui-studio/types/granularity/config.types.d.ts

@@ -0,0 +1,177 @@
+/**
+ * Granularity Configuration Types
+ *
+ * This file defines the GranularityConfig<G> generic interface that replaces
+ * separate SectionConfig, PageConfig, LayoutConfig, and TemplateConfig types.
+ *
+ * @packageDocumentation
+ * @module types/granularity
+ * @since 4.0.0
+ *
+ * Powered by Nikkory
+ */
+import type { GranularityLevel, GranularityBaseFields, GranularityLayoutConfig, GranularityStyleOverrides, GranularityFactorValues } from './base.types';
+import type { GranularitySlotConfig } from './slot.types';
+/**
+ * Child reference for recursive generation
+ *
+ * Allows a parent granularity to reference child granularities,
+ * enabling recursive generation: Page → Sections → Components.
+ *
+ * @category types
+ * @since 4.0.0
+ *
+ * @typeParam _G - The parent granularity level (prefixed with _ as intentionally unused)
+ *
+ * @example
+ * ```typescript
+ * // Page referencing sections
+ * const child: ChildReference<'page'> = {
+ *   childGranularity: 'section',
+ *   ref: 'hero-section-id',
+ *   slot: 'main',
+ *   factorOverrides: { spacing: 'lg' }
+ * };
+ *
+ * // Inline config instead of reference
+ * const inlineChild: ChildReference<'page'> = {
+ *   childGranularity: 'section',
+ *   ref: {
+ *     id: 'inline-section',
+ *     granularity: 'section',
+ *     designSystem: 'material-design',
+ *     tier: 'standard',
+ *     title: 'Inline Section'
+ *   },
+ *   slot: 'main'
+ * };
+ * ```
+ *
+ * Powered by Nikkory
+ */
+export interface ChildReference<_G extends GranularityLevel> {
+    /** Child granularity level */
+    readonly childGranularity: GranularityLevel;
+    /** Child ID (string) or inline config */
+    readonly ref: string | GranularityConfig<GranularityLevel>;
+    /** Slot to place child in */
+    readonly slot: string;
+    /** Factor overrides for this child (highest priority) */
+    readonly factorOverrides?: GranularityFactorValues;
+}
+/**
+ * GranularityConfig<G> - THE unified generic config interface
+ *
+ * This interface replaces separate SectionConfig, PageConfig, LayoutConfig,
+ * and TemplateConfig types with a single generic that works for all 6
+ * granularity levels.
+ *
+ * @category types
+ * @since 4.0.0
+ *
+ * @typeParam G - The granularity level this config is for
+ *
+ * @example
+ * ```typescript
+ * // Section configuration
+ * const sectionConfig: GranularityConfig<'section'> = {
+ *   id: 'hero-section',
+ *   granularity: 'section',
+ *   designSystem: 'material-design',
+ *   tier: 'enterprise',
+ *   title: 'Hero Section',
+ *   subtitle: 'Main landing hero with CTA',
+ *   layout: { type: 'flex', alignment: 'center' },
+ *   factors: { spacing: 'lg', colorPrimary: '#3B82F6' }
+ * };
+ *
+ * // Page configuration with children
+ * const pageConfig: GranularityConfig<'page'> = {
+ *   id: 'landing-page',
+ *   granularity: 'page',
+ *   designSystem: 'material-design',
+ *   tier: 'enterprise',
+ *   title: 'Landing Page',
+ *   children: [
+ *     { childGranularity: 'section', ref: 'hero-section', slot: 'main' },
+ *     { childGranularity: 'section', ref: 'features-section', slot: 'main' }
+ *   ]
+ * };
+ * ```
+ *
+ * Powered by Nikkory
+ */
+export interface GranularityConfig<G extends GranularityLevel> extends GranularityBaseFields<G> {
+    /** Layout configuration for arranging children */
+    readonly layout?: GranularityLayoutConfig;
+    /** Slots for child granularities (level-specific positions) */
+    readonly slots?: readonly GranularitySlotConfig<G>[];
+    /** Factors applicable at this level (resolved dynamically) */
+    readonly factors?: GranularityFactorValues;
+    /** Children references (for recursive generation) */
+    readonly children?: readonly ChildReference<G>[];
+    /** Style overrides for customization */
+    readonly styleOverrides?: GranularityStyleOverrides;
+}
+/**
+ * AtomConfig - Configuration for atom-level components
+ *
+ * @category types
+ * @since 4.0.0
+ *
+ * Powered by Nikkory
+ */
+export type AtomConfig = GranularityConfig<'atom'>;
+/**
+ * ComponentConfig - Configuration for component-level elements
+ *
+ * @category types
+ * @since 4.0.0
+ *
+ * Powered by Nikkory
+ */
+export type ComponentConfig = GranularityConfig<'component'>;
+/**
+ * SectionGranularityConfig - Configuration for section-level elements
+ *
+ * Note: Named SectionGranularityConfig to avoid conflict with
+ * existing SectionConfig in section.types.ts. Use GranularityConfig<'section'>
+ * for the unified approach.
+ *
+ * @category types
+ * @since 4.0.0
+ *
+ * Powered by Nikkory
+ */
+export type SectionGranularityConfig = GranularityConfig<'section'>;
+/**
+ * PageConfig - Configuration for page-level elements
+ *
+ * @category types
+ * @since 4.0.0
+ *
+ * Powered by Nikkory
+ */
+export type PageConfig = GranularityConfig<'page'>;
+/**
+ * LayoutGranularityConfig - Configuration for layout-level elements
+ *
+ * Note: Named LayoutGranularityConfig to avoid conflict with
+ * existing LayoutConfig in base.types.ts.
+ *
+ * @category types
+ * @since 4.0.0
+ *
+ * Powered by Nikkory
+ */
+export type LayoutGranularityConfig = GranularityConfig<'layout'>;
+/**
+ * TemplateConfig - Configuration for template-level elements
+ *
+ * @category types
+ * @since 4.0.0
+ *
+ * Powered by Nikkory
+ */
+export type TemplateConfig = GranularityConfig<'template'>;
+//# sourceMappingURL=config.types.d.ts.map

package/dist/ui-studio/types/granularity/factors.types.d.ts

@@ -0,0 +1,194 @@
+/**
+ * Factor Types for Unified Granularity Architecture
+ *
+ * This file defines additional factor-related types that support
+ * the dynamic factor resolution and cascade system.
+ *
+ * @packageDocumentation
+ * @module types/granularity
+ * @since 4.0.0
+ *
+ * Powered by Nikkory
+ */
+import type { GranularityLevel, GranularityFactorCategory, GranularityFactorDefinition } from './base.types';
+import type { DesignSystem } from '../../../types';
+/**
+ * Factor resolution result from getFactorsForLevel()
+ *
+ * Contains both the factor definitions and resolved values
+ * for a specific granularity level.
+ *
+ * @category types
+ * @since 4.0.0
+ *
+ * @example
+ * ```typescript
+ * const result: FactorResolutionResult = {
+ *   level: 'section',
+ *   factors: [spacingFactor, colorFactor, ...],
+ *   resolvedValues: {
+ *     spacing: 'md',
+ *     colorPrimary: '#3B82F6'
+ *   },
+ *   cascadedFrom: ['template', 'page']
+ * };
+ * ```
+ *
+ * Powered by Nikkory
+ */
+export interface GranularityFactorResolutionResult {
+    /** The granularity level these factors are for */
+    readonly level: GranularityLevel;
+    /** All applicable factor definitions */
+    readonly factors: readonly GranularityFactorDefinition[];
+    /** Resolved factor values */
+    readonly resolvedValues: Record<string, unknown>;
+    /** Levels from which factors were cascaded */
+    readonly cascadedFrom: readonly GranularityLevel[];
+}
+/**
+ * Factor override configuration
+ *
+ * Allows specifying overrides that take priority over
+ * cascaded or default factor values.
+ *
+ * @category types
+ * @since 4.0.0
+ *
+ * @example
+ * ```typescript
+ * const override: FactorOverride = {
+ *   factorId: 'spacing',
+ *   value: 'xl',
+ *   priority: 100,
+ *   source: 'user'
+ * };
+ * ```
+ *
+ * Powered by Nikkory
+ */
+export interface GranularityFactorOverride {
+    /** Factor identifier */
+    readonly factorId: string;
+    /** Override value */
+    readonly value: unknown;
+    /** Priority (higher wins) */
+    readonly priority: number;
+    /** Source of override */
+    readonly source: 'default' | 'cascade' | 'config' | 'user';
+}
+/**
+ * Options for querying factors
+ *
+ * @category types
+ * @since 4.0.0
+ *
+ * @example
+ * ```typescript
+ * const options: FactorQueryOptions = {
+ *   level: 'section',
+ *   designSystem: 'material-design',
+ *   includeInherited: true,
+ *   categories: ['visual', 'layout']
+ * };
+ * ```
+ *
+ * Powered by Nikkory
+ */
+export interface GranularityFactorQueryOptions {
+    /** Target granularity level */
+    readonly level: GranularityLevel;
+    /** Design system for default values */
+    readonly designSystem?: DesignSystem;
+    /** Whether to include inherited factors from higher levels */
+    readonly includeInherited?: boolean;
+    /** Filter by specific categories */
+    readonly categories?: readonly GranularityFactorCategory[];
+    /** Filter by specific factor IDs */
+    readonly factorIds?: readonly string[];
+}
+/**
+ * Factor cascade configuration
+ *
+ * Controls how factors cascade from parent to child levels.
+ *
+ * @category types
+ * @since 4.0.0
+ *
+ * @example
+ * ```typescript
+ * const cascade: FactorCascadeConfig = {
+ *   parentLevel: 'page',
+ *   childLevel: 'section',
+ *   parentFactors: { spacing: 'lg', theme: 'dark' },
+ *   overrides: { spacing: 'md' }
+ * };
+ * ```
+ *
+ * Powered by Nikkory
+ */
+export interface GranularityFactorCascadeConfig {
+    /** Parent granularity level */
+    readonly parentLevel: GranularityLevel;
+    /** Child granularity level */
+    readonly childLevel: GranularityLevel;
+    /** Factor values from parent */
+    readonly parentFactors: Record<string, unknown>;
+    /** Child-specific overrides (highest priority) */
+    readonly overrides?: Record<string, unknown>;
+}
+/**
+ * Create a factor definition with type safety
+ *
+ * @category utils
+ * @since 4.0.0
+ *
+ * @param definition - Partial factor definition
+ * @returns Complete factor definition with defaults
+ *
+ * @example
+ * ```typescript
+ * const factor = createFactorDefinition({
+ *   id: 'spacing',
+ *   name: 'Spacing',
+ *   category: 'layout',
+ *   level: 'template',
+ *   cascadeDown: true,
+ *   options: ['xs', 'sm', 'md', 'lg', 'xl'],
+ *   description: 'Controls spacing between elements'
+ * });
+ * ```
+ *
+ * Powered by Nikkory
+ */
+export declare function createGranularityFactorDefinition(definition: Omit<GranularityFactorDefinition, 'defaults'> & {
+    defaults?: Partial<Record<DesignSystem, unknown>>;
+}): GranularityFactorDefinition;
+/**
+ * Standard priority levels for factor resolution
+ *
+ * @category constants
+ * @since 4.0.0
+ *
+ * Powered by Nikkory
+ */
+export declare const FACTOR_PRIORITY: {
+    /** Default values from design system */
+    readonly DEFAULT: 0;
+    /** Values cascaded from parent levels */
+    readonly CASCADE: 25;
+    /** Values from config/template */
+    readonly CONFIG: 50;
+    /** Values explicitly set by user */
+    readonly USER: 100;
+};
+/**
+ * Factor priority type
+ *
+ * @category types
+ * @since 4.0.0
+ *
+ * Powered by Nikkory
+ */
+export type GranularityFactorPriority = (typeof FACTOR_PRIORITY)[keyof typeof FACTOR_PRIORITY];
+//# sourceMappingURL=factors.types.d.ts.map

package/dist/ui-studio/types/granularity/index.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Unified Granularity Architecture Types
+ *
+ * This module exports all types for the 6-level granularity system:
+ * - GranularityLevel: atom, component, section, page, layout, template
+ * - GranularityConfig<G>: Generic config for any level
+ * - GranularityTemplate<G>: Config + 8 metadata fields
+ * - GranularitySlotConfig<G>: Child placement configuration
+ * - GranularityFactorDefinition: Factor with level and cascadeDown
+ *
+ * @packageDocumentation
+ * @module types/granularity
+ * @since 4.0.0
+ *
+ * @example
+ * ```typescript
+ * import type {
+ *   GranularityLevel,
+ *   GranularityConfig,
+ *   GranularityTemplate,
+ *   GranularitySlotConfig,
+ *   GranularityFactorDefinition
+ * } from '@nikkory/engine';
+ *
+ * // Create a section config
+ * const section: GranularityConfig<'section'> = {
+ *   id: 'hero',
+ *   granularity: 'section',
+ *   designSystem: 'material-design',
+ *   tier: 'enterprise',
+ *   title: 'Hero Section'
+ * };
+ *
+ * // Create a page template
+ * const template: GranularityTemplate<'page'> = {
+ *   ...pageConfig,
+ *   templateId: 'landing-v1',
+ *   templateName: 'Landing Page',
+ *   description: 'Modern landing page template',
+ *   author: 'Nikkory',
+ *   version: '1.0.0',
+ *   tags: ['landing', 'marketing'],
+ *   visibility: 'public'
+ * };
+ * ```
+ *
+ * Powered by Nikkory
+ */
+export type { GranularityLevel, GranularityFactorCategory, GranularityFactorDefinition, GranularityBaseFields, GranularityTemplateVisibility, GranularityLayoutConfig, GranularitySpacingLevel, GranularityAlignmentType, GranularityStyleOverrides, GranularityFactorValues, } from './base.types';
+export { GRANULARITY_HIERARCHY, getGranularityRank } from './base.types';
+export type { ChildReference, GranularityConfig, AtomConfig, ComponentConfig, SectionGranularityConfig, PageConfig, LayoutGranularityConfig, TemplateConfig, } from './config.types';
+export type { GranularityTemplateMetadata, GranularityTemplate, AtomTemplate, ComponentTemplate, SectionGranularityTemplate, PageTemplate, LayoutTemplate, TemplateGranularityTemplate, } from './template.types';
+export type { GranularitySlotPosition, GranularitySlotConfig } from './slot.types';
+export { DEFAULT_PAGE_SLOTS, DEFAULT_SECTION_SLOTS, getDefaultSlots } from './slot.types';
+export type { GranularityFactorResolutionResult, GranularityFactorOverride, GranularityFactorQueryOptions, GranularityFactorCascadeConfig, GranularityFactorPriority, } from './factors.types';
+export { FACTOR_PRIORITY, createGranularityFactorDefinition } from './factors.types';
+//# sourceMappingURL=index.d.ts.map