@nikkory/vibe-engine 4.0.0

package/dist/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/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 '../index';
+/**
+ * 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/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

package/dist/types/granularity/slot.types.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Granularity Slot Types
+ *
+ * This file defines the SlotConfig<G> and SlotPosition<G> generic types
+ * for managing component placement within parent granularities.
+ *
+ * @packageDocumentation
+ * @module types/granularity
+ * @since 4.0.0
+ *
+ * Powered by Nikkory
+ */
+import type { GranularityLevel } from './base.types';
+/**
+ * SlotPosition<G> - Level-specific slot positions
+ *
+ * Different granularity levels have different slot positions available.
+ * This conditional type ensures type safety when placing children.
+ *
+ * @category types
+ * @since 4.0.0
+ *
+ * @typeParam G - The granularity level
+ *
+ * @example
+ * ```typescript
+ * // Page has 6 slot positions
+ * type PageSlots = SlotPosition<'page'>;
+ * // = 'header' | 'main' | 'sidebar' | 'footer' | 'overlay' | 'floating'
+ *
+ * // Section has 5 slot positions
+ * type SectionSlots = SlotPosition<'section'>;
+ * // = 'header' | 'content' | 'footer' | 'sidebar' | 'overlay'
+ *
+ * // Layout has 4 slot positions
+ * type LayoutSlots = SlotPosition<'layout'>;
+ * // = 'header' | 'main' | 'sidebar' | 'footer'
+ *
+ * // Template has 3 slot positions
+ * type TemplateSlots = SlotPosition<'template'>;
+ * // = 'pages' | 'shared' | 'assets'
+ * ```
+ *
+ * Powered by Nikkory
+ */
+export type GranularitySlotPosition<G extends GranularityLevel> = G extends 'page' ? 'header' | 'main' | 'sidebar' | 'footer' | 'overlay' | 'floating' : G extends 'section' ? 'header' | 'content' | 'footer' | 'sidebar' | 'overlay' : G extends 'layout' ? 'header' | 'main' | 'sidebar' | 'footer' : G extends 'template' ? 'pages' | 'shared' | 'assets' : G extends 'component' ? 'content' | 'prefix' | 'suffix' : G extends 'atom' ? 'content' : string;
+/**
+ * SlotConfig<G> - Configuration for a slot in a granularity
+ *
+ * Defines how children can be placed in a specific slot position,
+ * including allowed child types, maximum count, and defaults.
+ *
+ * @category types
+ * @since 4.0.0
+ *
+ * @typeParam G - The parent granularity level
+ *
+ * @example
+ * ```typescript
+ * // Page main slot accepting sections
+ * const mainSlot: SlotConfig<'page'> = {
+ *   slotId: 'main-content',
+ *   position: 'main',
+ *   allowedChildren: ['section', 'component'],
+ *   maxChildren: 10,
+ *   defaultChildren: ['hero-section', 'features-section']
+ * };
+ *
+ * // Section content slot accepting components
+ * const contentSlot: SlotConfig<'section'> = {
+ *   slotId: 'section-content',
+ *   position: 'content',
+ *   allowedChildren: ['component', 'atom'],
+ *   maxChildren: 20
+ * };
+ * ```
+ *
+ * Powered by Nikkory
+ */
+export interface GranularitySlotConfig<G extends GranularityLevel> {
+    /** Slot identifier */
+    readonly slotId: string;
+    /** Position within parent (level-specific) */
+    readonly position: GranularitySlotPosition<G>;
+    /** Allowed child granularities */
+    readonly allowedChildren: readonly GranularityLevel[];
+    /** Maximum children in slot (-1 for unlimited) */
+    readonly maxChildren: number;
+    /** Default children to place (IDs or inline configs) */
+    readonly defaultChildren?: readonly string[];
+    /** Whether slot is required (must have at least one child) */
+    readonly required?: boolean;
+    /** Slot display name for UI */
+    readonly displayName?: string;
+    /** Slot description for documentation */
+    readonly description?: string;
+}
+/**
+ * Default slot configurations for each granularity level
+ *
+ * @category constants
+ * @since 4.0.0
+ *
+ * Powered by Nikkory
+ */
+export declare const DEFAULT_PAGE_SLOTS: readonly GranularitySlotConfig<'page'>[];
+/**
+ * Default slot configurations for sections
+ *
+ * @category constants
+ * @since 4.0.0
+ *
+ * Powered by Nikkory
+ */
+export declare const DEFAULT_SECTION_SLOTS: readonly GranularitySlotConfig<'section'>[];
+/**
+ * Get default slots for a granularity level
+ *
+ * @category utils
+ * @since 4.0.0
+ *
+ * @param level - The granularity level
+ * @returns Default slot configurations for the level
+ *
+ * Powered by Nikkory
+ */
+export declare function getDefaultSlots<G extends GranularityLevel>(level: G): readonly GranularitySlotConfig<G>[];
+//# sourceMappingURL=slot.types.d.ts.map