@nikkory/vibe-engine 4.0.0

package/dist/types/granularity-levels/layout.config.d.ts

@@ -0,0 +1,278 @@
+/**
+ * Layout Configuration Types
+ *
+ * Layout-level configuration for page wrappers like AppLayout, AuthLayout.
+ * Layouts define the structural wrapper around pages including headers,
+ * sidebars, and footers that persist across page navigation.
+ *
+ * @packageDocumentation
+ * @module types/granularity-levels
+ * @since 4.0.0
+ *
+ * Powered by Nikkory
+ */
+import type { GranularityLevel, GranularityFactorValues, GranularityStyleOverrides, GranularityLayoutConfig, GranularitySpacingLevel } from '../granularity/base.types';
+import type { GranularityConfig, ChildReference } from '../granularity/config.types';
+import type { GranularitySlotPosition, GranularitySlotConfig } from '../granularity/slot.types';
+import type { DesignSystem, Tier } from '../index';
+/**
+ * Layout slot positions - header, main, sidebar, footer
+ *
+ * @category types
+ * @since 4.0.0
+ *
+ * Powered by Nikkory
+ */
+export type LayoutSlotPosition = GranularitySlotPosition<'layout'>;
+/**
+ * Layout slot configuration
+ *
+ * @category types
+ * @since 4.0.0
+ *
+ * Powered by Nikkory
+ */
+export type LayoutSlotConfig = GranularitySlotConfig<'layout'>;
+/**
+ * Layout type categories - 10+ types organized by purpose
+ *
+ * @category types
+ * @since 4.0.0
+ *
+ * @example
+ * ```typescript
+ * const category: LayoutCategory = 'app';
+ * ```
+ *
+ * Powered by Nikkory
+ */
+export type LayoutCategory = 'app' | 'auth' | 'dashboard' | 'marketing' | 'documentation' | 'minimal' | 'centered' | 'split';
+/**
+ * Layout type identifiers (10+ types)
+ *
+ * @category types
+ * @since 4.0.0
+ *
+ * Powered by Nikkory
+ */
+export type LayoutType = 'app-layout' | 'auth-layout' | 'dashboard-layout' | 'marketing-layout' | 'docs-layout' | 'blog-layout' | 'minimal-layout' | 'centered-layout' | 'split-layout' | 'sidebar-layout';
+/**
+ * Layout structure configuration
+ *
+ * Defines the structural arrangement of the layout including
+ * header, sidebar, main content, and footer positions.
+ *
+ * @category types
+ * @since 4.0.0
+ *
+ * Powered by Nikkory
+ */
+export interface LayoutStructure {
+    /** Header configuration */
+    readonly header: LayoutRegion | null;
+    /** Sidebar configuration */
+    readonly sidebar: LayoutSidebar | null;
+    /** Main content configuration */
+    readonly main: LayoutRegion;
+    /** Footer configuration */
+    readonly footer: LayoutRegion | null;
+}
+/**
+ * Layout region configuration
+ *
+ * @category types
+ * @since 4.0.0
+ *
+ * Powered by Nikkory
+ */
+export interface LayoutRegion {
+    /** Whether region is visible */
+    readonly visible: boolean;
+    /** Whether region is sticky */
+    readonly sticky?: boolean;
+    /** Region height (for header/footer) */
+    readonly height?: 'auto' | 'sm' | 'md' | 'lg';
+    /** Background color */
+    readonly background?: 'transparent' | 'surface' | 'primary' | 'secondary';
+    /** Whether region has border */
+    readonly bordered?: boolean;
+    /** Whether region has shadow */
+    readonly shadow?: boolean;
+}
+/**
+ * Layout sidebar configuration
+ *
+ * @category types
+ * @since 4.0.0
+ *
+ * Powered by Nikkory
+ */
+export interface LayoutSidebar extends LayoutRegion {
+    /** Sidebar position */
+    readonly position: 'left' | 'right';
+    /** Sidebar width */
+    readonly width: 'narrow' | 'medium' | 'wide' | 'custom';
+    /** Custom width value (if width is 'custom') */
+    readonly customWidth?: string;
+    /** Whether sidebar is collapsible */
+    readonly collapsible?: boolean;
+    /** Default collapsed state */
+    readonly defaultCollapsed?: boolean;
+    /** Collapse breakpoint */
+    readonly collapseBreakpoint?: 'sm' | 'md' | 'lg' | 'xl';
+    /** Whether sidebar overlays content when collapsed */
+    readonly overlayMode?: boolean;
+}
+/**
+ * Responsive layout configuration
+ *
+ * @category types
+ * @since 4.0.0
+ *
+ * Powered by Nikkory
+ */
+export interface ResponsiveConfig {
+    /** Mobile breakpoint behavior */
+    readonly mobile?: {
+        readonly hideSidebar?: boolean;
+        readonly hideHeader?: boolean;
+        readonly hideFooter?: boolean;
+        readonly stackLayout?: boolean;
+    };
+    /** Tablet breakpoint behavior */
+    readonly tablet?: {
+        readonly collapseSidebar?: boolean;
+        readonly compactHeader?: boolean;
+    };
+    /** Desktop breakpoint behavior */
+    readonly desktop?: {
+        readonly expandSidebar?: boolean;
+        readonly showBreadcrumb?: boolean;
+    };
+}
+/**
+ * Layout-specific extension fields beyond GranularityConfig
+ *
+ * @category types
+ * @since 4.0.0
+ *
+ * Powered by Nikkory
+ */
+export interface LayoutExtensions {
+    /** Layout type identifier */
+    readonly layoutType: LayoutType;
+    /** Layout category for organization */
+    readonly layoutCategory: LayoutCategory;
+    /** Layout structural configuration */
+    readonly structure: LayoutStructure;
+    /** Responsive behavior configuration */
+    readonly responsive?: ResponsiveConfig;
+    /** Content max width */
+    readonly maxWidth?: 'sm' | 'md' | 'lg' | 'xl' | '2xl' | 'full';
+    /** Content padding */
+    readonly contentPadding?: GranularitySpacingLevel;
+    /** Whether layout uses CSS Grid */
+    readonly useGrid?: boolean;
+    /** Whether layout supports theme switching */
+    readonly themeable?: boolean;
+    /** Whether layout supports RTL */
+    readonly rtlSupport?: boolean;
+    /** Scroll behavior */
+    readonly scrollBehavior?: 'smooth' | 'auto';
+}
+/**
+ * LayoutLevelConfig - Full configuration for layout-level elements
+ *
+ * Extends GranularityConfig<'layout'> with layout-specific fields.
+ * Named LayoutLevelConfig to avoid conflict with LayoutConfig in base.types.ts.
+ *
+ * @category types
+ * @since 4.0.0
+ *
+ * @example
+ * ```typescript
+ * const dashboardLayout: LayoutLevelConfig = {
+ *   id: 'dashboard-layout',
+ *   granularity: 'layout',
+ *   designSystem: 'material-design',
+ *   tier: 'enterprise',
+ *   title: 'Dashboard Layout',
+ *   layoutType: 'dashboard-layout',
+ *   layoutCategory: 'dashboard',
+ *   structure: {
+ *     header: { visible: true, sticky: true, height: 'md' },
+ *     sidebar: {
+ *       visible: true, position: 'left', width: 'medium',
+ *       collapsible: true, defaultCollapsed: false
+ *     },
+ *     main: { visible: true },
+ *     footer: null
+ *   },
+ *   responsive: {
+ *     mobile: { hideSidebar: true },
+ *     tablet: { collapseSidebar: true }
+ *   },
+ *   maxWidth: 'full',
+ *   contentPadding: 'md'
+ * };
+ * ```
+ *
+ * Powered by Nikkory
+ */
+export interface LayoutLevelConfig extends LayoutExtensions {
+    /** Unique identifier */
+    readonly id: string;
+    /** Granularity level - always 'layout' */
+    readonly granularity: 'layout';
+    /** Design system */
+    readonly designSystem: DesignSystem;
+    /** Quality tier */
+    readonly tier: Tier;
+    /** Display title */
+    readonly title: string;
+    /** Optional subtitle/description */
+    readonly subtitle?: string;
+    /** Layout configuration */
+    readonly layout?: GranularityLayoutConfig;
+    /** Slots for layout regions */
+    readonly slots?: readonly LayoutSlotConfig[];
+    /** Factor values */
+    readonly factors?: GranularityFactorValues;
+    /** Children references (pages this layout wraps) */
+    readonly children?: readonly ChildReference<'layout'>[];
+    /** Style overrides */
+    readonly styleOverrides?: GranularityStyleOverrides;
+}
+/**
+ * Default slot configurations for layouts
+ *
+ * @category constants
+ * @since 4.0.0
+ *
+ * Powered by Nikkory
+ */
+export declare const DEFAULT_LAYOUT_SLOTS: readonly LayoutSlotConfig[];
+/**
+ * Type guard to check if a config is a LayoutLevelConfig
+ *
+ * @category utils
+ * @since 4.0.0
+ *
+ * @param config - The config to check
+ * @returns True if config is a LayoutLevelConfig
+ *
+ * Powered by Nikkory
+ */
+export declare function isLayoutLevelConfig(config: GranularityConfig<GranularityLevel>): config is LayoutLevelConfig & GranularityConfig<'layout'>;
+/**
+ * LayoutGranularityConfig - Alias to GranularityConfig<'layout'>
+ *
+ * Use LayoutLevelConfig for the full extended version with layout-specific fields.
+ *
+ * @category types
+ * @since 4.0.0
+ *
+ * Powered by Nikkory
+ */
+export type LayoutGranularityConfig = GranularityConfig<'layout'>;
+//# sourceMappingURL=layout.config.d.ts.map

package/dist/types/granularity-levels/page.config.d.ts

@@ -0,0 +1,210 @@
+/**
+ * Page Configuration Types
+ *
+ * Page-level configuration for full pages like Landing, Dashboard, Profile.
+ * Pages compose multiple sections and define the overall page structure.
+ *
+ * @packageDocumentation
+ * @module types/granularity-levels
+ * @since 4.0.0
+ *
+ * Powered by Nikkory
+ */
+import type { GranularityLevel, GranularityFactorValues, GranularityStyleOverrides, GranularityLayoutConfig, GranularitySpacingLevel } from '../granularity/base.types';
+import type { GranularityConfig, ChildReference } from '../granularity/config.types';
+import type { GranularitySlotPosition, GranularitySlotConfig } from '../granularity/slot.types';
+import type { DesignSystem, Tier } from '../index';
+/**
+ * Page slot positions - header, main, sidebar, footer, overlay, floating
+ *
+ * @category types
+ * @since 4.0.0
+ *
+ * Powered by Nikkory
+ */
+export type PageSlotPosition = GranularitySlotPosition<'page'>;
+/**
+ * Page slot configuration
+ *
+ * @category types
+ * @since 4.0.0
+ *
+ * Powered by Nikkory
+ */
+export type PageSlotConfig = GranularitySlotConfig<'page'>;
+/**
+ * Page type categories - 30+ types organized by purpose
+ *
+ * @category types
+ * @since 4.0.0
+ *
+ * @example
+ * ```typescript
+ * const category: PageCategory = 'marketing';
+ * ```
+ *
+ * Powered by Nikkory
+ */
+export type PageCategory = 'marketing' | 'auth' | 'dashboard' | 'content' | 'ecommerce' | 'account' | 'utility' | 'legal';
+/**
+ * Page type identifiers (30+ types)
+ *
+ * @category types
+ * @since 4.0.0
+ *
+ * Powered by Nikkory
+ */
+export type PageType = 'landing' | 'about' | 'features' | 'pricing' | 'contact' | 'faq' | 'login' | 'register' | 'forgot-password' | 'reset-password' | 'verify-email' | 'two-factor' | 'dashboard-overview' | 'dashboard-analytics' | 'dashboard-reports' | 'dashboard-settings' | 'blog-list' | 'blog-post' | 'documentation' | 'changelog' | 'product-list' | 'product-detail' | 'cart' | 'checkout' | 'order-confirmation' | 'profile' | 'settings' | 'billing' | 'notifications' | 'not-found' | 'error' | 'maintenance' | 'coming-soon' | 'terms' | 'privacy' | 'cookie-policy';
+/**
+ * Page-specific extension fields beyond GranularityConfig
+ *
+ * @category types
+ * @since 4.0.0
+ *
+ * Powered by Nikkory
+ */
+export interface PageExtensions {
+    /** Page type identifier */
+    readonly pageType: PageType;
+    /** Page category for organization */
+    readonly pageCategory: PageCategory;
+    /** Page route path */
+    readonly routePath: string;
+    /** Whether page requires authentication */
+    readonly requiresAuth?: boolean;
+    /** Required user roles (if requiresAuth) */
+    readonly requiredRoles?: readonly string[];
+    /** Page metadata for SEO */
+    readonly metadata?: PageMetadata;
+    /** Whether page has sidebar layout */
+    readonly hasSidebar?: boolean;
+    /** Sidebar position (if hasSidebar) */
+    readonly sidebarPosition?: 'left' | 'right';
+    /** Sidebar width */
+    readonly sidebarWidth?: 'narrow' | 'medium' | 'wide';
+    /** Whether header is sticky */
+    readonly stickyHeader?: boolean;
+    /** Whether footer is visible */
+    readonly showFooter?: boolean;
+    /** Page content max width */
+    readonly maxWidth?: 'sm' | 'md' | 'lg' | 'xl' | '2xl' | 'full';
+    /** Page padding */
+    readonly padding?: GranularitySpacingLevel;
+}
+/**
+ * Page metadata for SEO and social sharing
+ *
+ * @category types
+ * @since 4.0.0
+ *
+ * Powered by Nikkory
+ */
+export interface PageMetadata {
+    /** Page title (for browser tab) */
+    readonly title: string;
+    /** Meta description */
+    readonly description?: string;
+    /** Meta keywords */
+    readonly keywords?: readonly string[];
+    /** Canonical URL */
+    readonly canonical?: string;
+    /** Open Graph image */
+    readonly ogImage?: string;
+    /** Twitter card type */
+    readonly twitterCard?: 'summary' | 'summary_large_image';
+    /** Robots meta */
+    readonly robots?: 'index,follow' | 'noindex,follow' | 'index,nofollow' | 'noindex,nofollow';
+}
+/**
+ * PageLevelConfig - Full configuration for page-level elements
+ *
+ * Extends GranularityConfig<'page'> with page-specific fields.
+ *
+ * @category types
+ * @since 4.0.0
+ *
+ * @example
+ * ```typescript
+ * const landingConfig: PageLevelConfig = {
+ *   id: 'landing-page',
+ *   granularity: 'page',
+ *   designSystem: 'material-design',
+ *   tier: 'enterprise',
+ *   title: 'Landing Page',
+ *   pageType: 'landing',
+ *   pageCategory: 'marketing',
+ *   routePath: '/',
+ *   stickyHeader: true,
+ *   showFooter: true,
+ *   maxWidth: 'xl',
+ *   metadata: {
+ *     title: 'Welcome | Nikkory',
+ *     description: 'Build beautiful UIs faster',
+ *     ogImage: '/og-landing.png'
+ *   },
+ *   children: [
+ *     { childGranularity: 'section', ref: 'hero-section', slot: 'main' },
+ *     { childGranularity: 'section', ref: 'features-section', slot: 'main' }
+ *   ]
+ * };
+ * ```
+ *
+ * Powered by Nikkory
+ */
+export interface PageLevelConfig extends PageExtensions {
+    /** Unique identifier */
+    readonly id: string;
+    /** Granularity level - always 'page' */
+    readonly granularity: 'page';
+    /** Design system */
+    readonly designSystem: DesignSystem;
+    /** Quality tier */
+    readonly tier: Tier;
+    /** Display title */
+    readonly title: string;
+    /** Optional subtitle/description */
+    readonly subtitle?: string;
+    /** Layout configuration */
+    readonly layout?: GranularityLayoutConfig;
+    /** Slots for child sections (6 positions available) */
+    readonly slots?: readonly PageSlotConfig[];
+    /** Factor values */
+    readonly factors?: GranularityFactorValues;
+    /** Children references */
+    readonly children?: readonly ChildReference<'page'>[];
+    /** Style overrides */
+    readonly styleOverrides?: GranularityStyleOverrides;
+}
+/**
+ * Re-export default page slots from slot.types.ts
+ *
+ * @category constants
+ * @since 4.0.0
+ *
+ * Powered by Nikkory
+ */
+export declare const DEFAULT_PAGE_SLOTS: readonly GranularitySlotConfig<"page">[];
+/**
+ * Type guard to check if a config is a PageLevelConfig
+ *
+ * @category utils
+ * @since 4.0.0
+ *
+ * @param config - The config to check
+ * @returns True if config is a PageLevelConfig
+ *
+ * Powered by Nikkory
+ */
+export declare function isPageLevelConfig(config: GranularityConfig<GranularityLevel>): config is PageLevelConfig & GranularityConfig<'page'>;
+/**
+ * PageGranularityConfig - Alias to GranularityConfig<'page'>
+ *
+ * Use PageLevelConfig for the full extended version with page-specific fields.
+ *
+ * @category types
+ * @since 4.0.0
+ *
+ * Powered by Nikkory
+ */
+export type PageGranularityConfig = GranularityConfig<'page'>;
+//# sourceMappingURL=page.config.d.ts.map

package/dist/types/granularity-levels/section.config.d.ts

@@ -0,0 +1,188 @@
+/**
+ * Section Configuration Types
+ *
+ * Section-level configuration for large UI blocks like Hero, Pricing, Testimonials
+ * that compose multiple components and atoms.
+ *
+ * @packageDocumentation
+ * @module types/granularity-levels
+ * @since 4.0.0
+ *
+ * Powered by Nikkory
+ */
+import type { GranularityLevel, GranularityFactorValues, GranularityStyleOverrides, GranularityLayoutConfig, GranularitySpacingLevel, GranularityAlignmentType } from '../granularity/base.types';
+import type { GranularityConfig, ChildReference } from '../granularity/config.types';
+import type { GranularitySlotPosition, GranularitySlotConfig } from '../granularity/slot.types';
+import type { DesignSystem, Tier, SectionCategory } from '../index';
+/**
+ * Section slot positions - header, content, footer, sidebar, overlay
+ *
+ * @category types
+ * @since 4.0.0
+ *
+ * Powered by Nikkory
+ */
+export type SectionSlotPosition = GranularitySlotPosition<'section'>;
+/**
+ * Section slot configuration
+ *
+ * @category types
+ * @since 4.0.0
+ *
+ * Powered by Nikkory
+ */
+export type SectionSlotConfig = GranularitySlotConfig<'section'>;
+/**
+ * Section layout types - how content is arranged
+ *
+ * @category types
+ * @since 4.0.0
+ *
+ * Powered by Nikkory
+ */
+export type SectionLayoutType = 'grid' | 'flex' | 'stack' | 'masonry' | 'carousel' | 'centered' | 'split' | 'fullwidth' | 'alternating' | 'sidebar' | 'asymmetric';
+/**
+ * Section-specific extension fields beyond GranularityConfig
+ *
+ * @category types
+ * @since 4.0.0
+ *
+ * Powered by Nikkory
+ */
+export interface SectionExtensions {
+    /** Section type/category (hero, features, testimonials, etc.) */
+    readonly sectionType: SectionCategory;
+    /** Section layout type */
+    readonly sectionLayout: SectionLayoutType;
+    /** Number of columns (for grid layouts) */
+    readonly columns: 1 | 2 | 3 | 4 | 6;
+    /** Spacing between elements */
+    readonly spacing: GranularitySpacingLevel;
+    /** Section padding */
+    readonly padding?: GranularitySpacingLevel;
+    /** Content alignment */
+    readonly alignment?: GranularityAlignmentType;
+    /** Whether section is full-bleed (edge to edge) */
+    readonly fullBleed?: boolean;
+    /** Background configuration */
+    readonly background?: SectionBackground;
+    /** Whether section is sticky */
+    readonly sticky?: boolean;
+    /** Section anchor ID for navigation */
+    readonly anchorId?: string;
+}
+/**
+ * Section background configuration
+ *
+ * @category types
+ * @since 4.0.0
+ *
+ * Powered by Nikkory
+ */
+export interface SectionBackground {
+    /** Background type */
+    readonly type: 'solid' | 'gradient' | 'image' | 'pattern' | 'video';
+    /** Background color (for solid) */
+    readonly color?: string;
+    /** Gradient definition (for gradient) */
+    readonly gradient?: {
+        readonly direction: 'to-right' | 'to-left' | 'to-bottom' | 'to-top' | 'radial';
+        readonly stops: readonly string[];
+    };
+    /** Image URL (for image/video) */
+    readonly url?: string;
+    /** Pattern name (for pattern) */
+    readonly pattern?: string;
+    /** Overlay opacity */
+    readonly overlay?: number;
+}
+/**
+ * SectionLevelConfig - Full configuration for section-level elements
+ *
+ * Extends GranularityConfig<'section'> with section-specific fields.
+ * Named SectionLevelConfig to avoid conflict with existing SectionConfig.
+ *
+ * @category types
+ * @since 4.0.0
+ *
+ * @example
+ * ```typescript
+ * const heroConfig: SectionLevelConfig = {
+ *   id: 'hero-section',
+ *   granularity: 'section',
+ *   designSystem: 'material-design',
+ *   tier: 'enterprise',
+ *   title: 'Hero Section',
+ *   subtitle: 'Main landing hero with CTA',
+ *   sectionType: 'hero',
+ *   sectionLayout: 'centered',
+ *   columns: 1,
+ *   spacing: 'lg',
+ *   fullBleed: true,
+ *   background: {
+ *     type: 'gradient',
+ *     gradient: { direction: 'to-right', stops: ['#3B82F6', '#8B5CF6'] }
+ *   }
+ * };
+ * ```
+ *
+ * Powered by Nikkory
+ */
+export interface SectionLevelConfig extends SectionExtensions {
+    /** Unique identifier */
+    readonly id: string;
+    /** Granularity level - always 'section' */
+    readonly granularity: 'section';
+    /** Design system */
+    readonly designSystem: DesignSystem;
+    /** Quality tier */
+    readonly tier: Tier;
+    /** Display title */
+    readonly title: string;
+    /** Optional subtitle/description */
+    readonly subtitle?: string;
+    /** Layout configuration */
+    readonly layout?: GranularityLayoutConfig;
+    /** Slots for child components */
+    readonly slots?: readonly SectionSlotConfig[];
+    /** Factor values */
+    readonly factors?: GranularityFactorValues;
+    /** Children references */
+    readonly children?: readonly ChildReference<'section'>[];
+    /** Style overrides */
+    readonly styleOverrides?: GranularityStyleOverrides;
+}
+/**
+ * Re-export default section slots from slot.types.ts
+ *
+ * @category constants
+ * @since 4.0.0
+ *
+ * Powered by Nikkory
+ */
+export declare const DEFAULT_SECTION_SLOTS: readonly GranularitySlotConfig<"section">[];
+/**
+ * Type guard to check if a config is a SectionLevelConfig
+ *
+ * @category utils
+ * @since 4.0.0
+ *
+ * @param config - The config to check
+ * @returns True if config is a SectionLevelConfig
+ *
+ * Powered by Nikkory
+ */
+export declare function isSectionLevelConfig(config: GranularityConfig<GranularityLevel>): config is SectionLevelConfig & GranularityConfig<'section'>;
+/**
+ * SectionGranularityConfig - Alias to GranularityConfig<'section'>
+ *
+ * Use SectionLevelConfig for the full extended version with section-specific fields.
+ * The existing SectionConfig in section.types.ts is preserved for backward compatibility.
+ *
+ * @category types
+ * @since 4.0.0
+ *
+ * Powered by Nikkory
+ */
+export type SectionGranularityConfig = GranularityConfig<'section'>;
+//# sourceMappingURL=section.config.d.ts.map