@servlyadmin/runtime-core 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,582 @@
+/**
+ * Servly Runtime Core Types
+ * Framework-agnostic type definitions for Layout JSON rendering
+ */
+/**
+ * Configuration options for an element
+ */
+interface ElementConfig {
+    /** HTML tag override */
+    tag?: string;
+    /** Static text content */
+    text?: string;
+    /** Dynamic text with template bindings */
+    dynamicText?: string;
+    /** CSS class name */
+    className?: string;
+    /** Additional CSS class names */
+    classNames?: string;
+    /** Dynamic class name with template bindings */
+    dynamicClassName?: string;
+    /** CSS variables to apply */
+    cssVariables?: Record<string, string>;
+    /** Element ID */
+    id?: string;
+    /** Image source */
+    src?: string;
+    /** Dynamic image source */
+    dynamicSrc?: string;
+    /** Alt text for images */
+    alt?: string;
+    /** Link href */
+    href?: string;
+    /** Link target */
+    target?: string;
+    /** Input placeholder */
+    placeholder?: string;
+    /** Input type */
+    type?: string;
+    /** Input name */
+    name?: string;
+    /** Input value */
+    value?: string;
+    /** Disabled state */
+    disabled?: boolean;
+    /** Required state */
+    required?: boolean;
+    /** Read-only state */
+    readOnly?: boolean;
+    /** Inline styles */
+    style?: Record<string, any>;
+    /** Data attributes */
+    [key: `data-${string}`]: string | undefined;
+    /** Aria attributes */
+    [key: `aria-${string}`]: string | undefined;
+}
+/**
+ * A single element in the Layout JSON tree
+ */
+interface LayoutElement {
+    /** Unique element identifier */
+    i: string;
+    /** Component type (container, text, button, etc.) */
+    componentId: string;
+    /** Parent element ID (null for root elements) */
+    parent?: string | null;
+    /** Element configuration */
+    configuration?: ElementConfig;
+    /** Inline styles */
+    style?: Record<string, any>;
+    /** CSS class name */
+    className?: string;
+    /** Whether this is a group/container */
+    isGroup?: boolean;
+    /** Child element IDs */
+    children?: string[];
+    /** Element name for debugging */
+    name?: string;
+}
+/**
+ * Context for resolving template bindings
+ */
+interface BindingContext {
+    /** Props passed to the component */
+    props: Record<string, any>;
+    /** Component state */
+    state?: Record<string, any>;
+    /** Additional context data */
+    context?: Record<string, any>;
+}
+/**
+ * Options for rendering a component
+ */
+interface RenderOptions {
+    /** Container element to render into */
+    container: HTMLElement;
+    /** Layout elements to render */
+    elements: LayoutElement[];
+    /** Binding context for template resolution */
+    context: BindingContext;
+    /** Event handlers keyed by element ID then event name */
+    eventHandlers?: Record<string, Record<string, (e: Event) => void>>;
+}
+/**
+ * Result of a render operation
+ */
+interface RenderResult {
+    /** Root DOM element created */
+    rootElement: HTMLElement | null;
+    /** Update the rendered component with new context */
+    update: (context: BindingContext) => void;
+    /** Destroy the rendered component and clean up */
+    destroy: () => void;
+}
+/**
+ * Prop definition for a component
+ */
+interface PropDefinition {
+    /** Prop name */
+    name: string;
+    /** Prop type */
+    type: 'string' | 'number' | 'boolean' | 'object' | 'array' | 'function';
+    /** Whether the prop is required */
+    required: boolean;
+    /** Default value if not provided */
+    defaultValue?: any;
+    /** Description for documentation */
+    description?: string;
+}
+/**
+ * Test case assertion
+ */
+interface Assertion$1 {
+    /** CSS selector to find element */
+    selector: string;
+    /** Property to check */
+    property: 'text' | 'attribute' | 'style' | 'exists' | 'class';
+    /** Attribute name (for attribute checks) */
+    attributeName?: string;
+    /** Style property name (for style checks) */
+    styleName?: string;
+    /** Expected value */
+    expected: any;
+}
+/**
+ * Test case for component validation
+ */
+interface TestCase$1 {
+    /** Unique test case ID */
+    id: string;
+    /** Test case name */
+    name: string;
+    /** Props to use for this test */
+    props: Record<string, any>;
+    /** Assertions to validate */
+    assertions?: Assertion$1[];
+}
+/**
+ * Component data from registry
+ */
+interface ComponentData {
+    /** Component ID */
+    id: string;
+    /** Component name */
+    name: string;
+    /** Component description */
+    description?: string;
+    /** Component version */
+    version: string;
+    /** Layout JSON elements */
+    layout: LayoutElement[];
+    /** Props interface definition */
+    propsInterface?: PropDefinition[];
+    /** Test cases for validation */
+    testCases?: TestCase$1[];
+    /** CSS variables used */
+    cssVariables?: Record<string, string>;
+    /** Component tags for search */
+    tags?: string[];
+    /** Created timestamp */
+    createdAt?: string;
+    /** Updated timestamp */
+    updatedAt?: string;
+}
+/**
+ * Cache entry for component data
+ */
+interface CacheEntry {
+    /** Cached component data */
+    data: ComponentData;
+    /** Timestamp when cached */
+    timestamp: number;
+    /** Version of cached component */
+    version: string;
+    /** Number of times accessed */
+    accessCount: number;
+    /** Last access timestamp */
+    lastAccessed: number;
+}
+/**
+ * Cache configuration
+ */
+interface CacheConfig {
+    /** Maximum number of entries in cache */
+    maxEntries?: number;
+    /** Time-to-live in milliseconds */
+    ttl?: number;
+    /** Storage key prefix for localStorage */
+    storageKeyPrefix?: string;
+}
+/**
+ * Cache strategy type
+ */
+type CacheStrategy = 'memory' | 'localStorage' | 'none';
+/**
+ * Retry configuration for failed fetches
+ */
+interface RetryConfig {
+    /** Maximum number of retries */
+    maxRetries?: number;
+    /** Initial delay in ms */
+    initialDelay?: number;
+    /** Maximum delay in ms */
+    maxDelay?: number;
+    /** Backoff multiplier */
+    backoffMultiplier?: number;
+}
+/**
+ * Options for fetching a component
+ */
+interface FetchOptions {
+    /** Version specifier */
+    version?: string;
+    /** API key for authentication */
+    apiKey?: string;
+    /** Cache strategy */
+    cacheStrategy?: CacheStrategy;
+    /** Cache configuration */
+    cacheConfig?: CacheConfig;
+    /** Retry configuration */
+    retryConfig?: Partial<RetryConfig>;
+    /** Skip cache and force fetch */
+    forceRefresh?: boolean;
+    /** Abort signal for cancellation */
+    signal?: AbortSignal;
+}
+/**
+ * Result of a fetch operation
+ */
+interface FetchResult {
+    /** Fetched component data */
+    data: ComponentData;
+    /** Whether data came from cache */
+    fromCache: boolean;
+    /** Resolved version */
+    version: string;
+}
+/**
+ * Result of a single assertion
+ */
+interface AssertionResult$1 {
+    /** Whether assertion passed */
+    passed: boolean;
+    /** The assertion that was checked */
+    assertion: Assertion$1;
+    /** Actual value found */
+    actual?: any;
+    /** Error message if failed */
+    error?: string;
+}
+/**
+ * Result of running a test case
+ */
+interface TestCaseResult {
+    /** Test case ID */
+    id: string;
+    /** Test case name */
+    name: string;
+    /** Whether all assertions passed */
+    passed: boolean;
+    /** Individual assertion results */
+    assertions: AssertionResult$1[];
+    /** Execution time in ms */
+    duration: number;
+}
+/**
+ * Summary of all test results
+ */
+interface TestSummary$1 {
+    /** Total number of tests */
+    total: number;
+    /** Number of passed tests */
+    passed: number;
+    /** Number of failed tests */
+    failed: number;
+    /** Individual test results */
+    results: TestCaseResult[];
+    /** Total execution time in ms */
+    duration: number;
+}
+
+/**
+ * Vanilla DOM Renderer
+ * Renders Layout JSON to native DOM elements
+ */
+
+/**
+ * Render Layout JSON to DOM
+ */
+declare function render(options: RenderOptions): RenderResult;
+
+/**
+ * Template Binding Resolution
+ * Resolves {{path}} syntax in templates using binding context
+ */
+
+/**
+ * Check if a string contains template syntax
+ */
+declare function hasTemplateSyntax(value: unknown): value is string;
+/**
+ * Resolve a binding path to its value from context
+ *
+ * @param path - The path to resolve (e.g., "props.title", "state.count")
+ * @param context - The binding context containing props, state, context
+ * @returns The resolved value or undefined if not found
+ */
+declare function resolveBindingPath(path: string, context: BindingContext): any;
+/**
+ * Resolve a template string with bindings
+ * Replaces all {{path}} occurrences with resolved values
+ *
+ * @param template - The template string containing {{path}} bindings
+ * @param context - The binding context
+ * @returns The resolved string
+ */
+declare function resolveTemplate(template: string, context: BindingContext): string;
+/**
+ * Resolve a template and return the raw value (not stringified)
+ * Useful for non-string values like objects, arrays, booleans
+ */
+declare function resolveTemplateValue(template: string, context: BindingContext): any;
+/**
+ * Recursively resolve all template bindings in an object or array
+ *
+ * @param input - The input value (string, object, array, or primitive)
+ * @param context - The binding context
+ * @returns The input with all templates resolved
+ */
+declare function resolveTemplatesDeep<T>(input: T, context: BindingContext): T;
+/**
+ * Extract all binding keys from a template string
+ *
+ * @param template - The template string
+ * @returns Array of binding keys found
+ */
+declare function extractBindingKeys(template: string): string[];
+
+/**
+ * Style Processing
+ * Handles CSS styles, variables, and class names for DOM elements
+ */
+
+/**
+ * Convert camelCase to kebab-case
+ */
+declare function camelToKebab(str: string): string;
+/**
+ * Format a style value, adding px units if needed
+ */
+declare function formatStyleValue(property: string, value: any): string;
+/**
+ * Process a style object, resolving templates and formatting values
+ */
+declare function processStyles(style: Record<string, any> | undefined, context: BindingContext): Record<string, string>;
+/**
+ * Apply styles to a DOM element
+ */
+declare function applyStyles(element: HTMLElement, styles: Record<string, string>): void;
+/**
+ * Build combined styles from element configuration
+ */
+declare function buildElementStyles(element: LayoutElement, context: BindingContext): Record<string, string>;
+/**
+ * Build class name string from element configuration
+ */
+declare function buildClassName(element: LayoutElement, context: BindingContext): string;
+/**
+ * Clear all inline styles from an element
+ */
+declare function clearStyles(element: HTMLElement): void;
+/**
+ * Update styles on an element (diff and patch)
+ */
+declare function updateStyles(element: HTMLElement, oldStyles: Record<string, string>, newStyles: Record<string, string>): void;
+
+/**
+ * Component Cache System
+ * In-memory and localStorage caching with LRU eviction
+ */
+
+/** Default cache configuration */
+declare const DEFAULT_CACHE_CONFIG: Required<CacheConfig>;
+/**
+ * Generate cache key for component
+ */
+declare function getCacheKey(id: string, version?: string): string;
+/**
+ * Clear memory cache
+ */
+declare function clearMemoryCache(): void;
+/**
+ * Get memory cache size
+ */
+declare function getMemoryCacheSize(): number;
+/**
+ * Clear localStorage cache
+ */
+declare function clearLocalStorageCache(config?: CacheConfig): void;
+/**
+ * Get component from cache (tries memory first, then localStorage)
+ */
+declare function getFromCache(id: string, version?: string, strategy?: CacheStrategy, config?: CacheConfig): ComponentData | null;
+/**
+ * Set component in cache
+ */
+declare function setInCache(id: string, version: string, data: ComponentData, strategy?: CacheStrategy, config?: CacheConfig): void;
+/**
+ * Clear all caches
+ */
+declare function clearAllCaches(config?: CacheConfig): void;
+/**
+ * Invalidate specific component from all caches
+ */
+declare function invalidateCache(id: string, version?: string, config?: CacheConfig): void;
+
+/**
+ * Component Fetcher
+ * Fetches component data from registry with retry logic
+ */
+
+/** Default retry configuration */
+declare const DEFAULT_RETRY_CONFIG: Required<RetryConfig>;
+/**
+ * Configure the registry base URL
+ */
+declare function setRegistryUrl(url: string): void;
+/**
+ * Get the registry base URL
+ */
+declare function getRegistryUrl(): string;
+/**
+ * Fetch component with caching and retry
+ */
+declare function fetchComponent(id: string, options?: FetchOptions): Promise<FetchResult>;
+/**
+ * Prefetch components for faster loading
+ */
+declare function prefetchComponents(ids: Array<{
+    id: string;
+    version?: string;
+}>, options?: Omit<FetchOptions, 'version'>): Promise<void>;
+/**
+ * Check if component is available (in cache or online)
+ */
+declare function isComponentAvailable(id: string, version?: string, options?: Pick<FetchOptions, 'apiKey' | 'cacheStrategy' | 'cacheConfig'>): Promise<{
+    available: boolean;
+    cached: boolean;
+}>;
+
+/**
+ * Semantic Version Utilities
+ * Parsing, comparison, and range resolution for semver
+ */
+/** Parsed semantic version */
+interface ParsedVersion {
+    major: number;
+    minor: number;
+    patch: number;
+}
+/**
+ * Parse a semantic version string
+ * @returns Parsed version or null if invalid
+ */
+declare function parseVersion(version: string): ParsedVersion | null;
+/**
+ * Compare two versions
+ * @returns -1 if a < b, 0 if a == b, 1 if a > b
+ */
+declare function compareVersions(a: string, b: string): number;
+/**
+ * Check if a version satisfies a specifier
+ * Supports: exact (1.2.3), caret (^1.2.3), tilde (~1.2.3), latest, *
+ */
+declare function satisfiesVersion(version: string, specifier: string): boolean;
+/**
+ * Find the best matching version from a list
+ * @param versions - Available versions (sorted newest first recommended)
+ * @param specifier - Version specifier to match
+ * @returns Best matching version or null if none match
+ */
+declare function resolveVersion(versions: string[], specifier?: string): string | null;
+/**
+ * Get next version based on bump type
+ */
+declare function bumpVersion(currentVersion: string, bumpType: 'major' | 'minor' | 'patch'): string;
+/**
+ * Check if a string is a valid version specifier
+ */
+declare function isValidSpecifier(specifier: string): boolean;
+/**
+ * Format a version for display
+ */
+declare function formatVersion(version: string): string;
+
+/**
+ * Test Runner for Servly Components
+ *
+ * Runs test cases against components to validate prop behavior
+ * and DOM output matches expected assertions.
+ */
+
+interface TestCase {
+    id: string;
+    name: string;
+    description?: string;
+    props: Record<string, any>;
+    assertions: Assertion[];
+}
+interface Assertion {
+    type: 'exists' | 'text' | 'attribute' | 'class' | 'style' | 'count' | 'visible';
+    selector: string;
+    expected?: any;
+    attribute?: string;
+    property?: string;
+}
+interface TestResult {
+    testId: string;
+    testName: string;
+    passed: boolean;
+    assertions: AssertionResult[];
+    duration: number;
+    error?: string;
+}
+interface AssertionResult {
+    assertion: Assertion;
+    passed: boolean;
+    actual?: any;
+    expected?: any;
+    message?: string;
+}
+interface TestSummary {
+    total: number;
+    passed: number;
+    failed: number;
+    duration: number;
+    results: TestResult[];
+}
+/**
+ * Run a single test case against a component
+ */
+declare function runTestCase(elements: LayoutElement[], testCase: TestCase, container?: HTMLElement): TestResult;
+/**
+ * Run all test cases for a component
+ */
+declare function runAllTests(elements: LayoutElement[], testCases: TestCase[]): TestSummary;
+/**
+ * Validate a single assertion against the DOM
+ */
+declare function validateAssertion(container: HTMLElement, assertion: Assertion): AssertionResult;
+/**
+ * Validate props against prop definitions
+ */
+declare function validateProps(props: Record<string, any>, definitions: PropDefinition[]): {
+    valid: boolean;
+    errors: string[];
+};
+/**
+ * Generate test cases from prop definitions
+ */
+declare function generateTestCases(definitions: PropDefinition[]): TestCase[];
+
+export { type Assertion$1 as Assertion, type AssertionResult$1 as AssertionResult, type BindingContext, type CacheConfig, type CacheEntry, type CacheStrategy, type ComponentData, DEFAULT_CACHE_CONFIG, DEFAULT_RETRY_CONFIG, type ElementConfig, type FetchOptions, type FetchResult, type LayoutElement, type ParsedVersion, type PropDefinition, type RenderOptions, type RenderResult, type RetryConfig, type AssertionResult as TestAssertionResult, type TestCase$1 as TestCase, type TestCase as TestCaseInput, type TestCaseResult, type TestResult, type TestSummary as TestRunSummary, type TestSummary$1 as TestSummary, applyStyles, buildClassName, buildElementStyles, bumpVersion, camelToKebab, clearAllCaches, clearLocalStorageCache, clearMemoryCache, clearStyles, compareVersions, extractBindingKeys, fetchComponent, formatStyleValue, formatVersion, generateTestCases, getCacheKey, getFromCache, getMemoryCacheSize, getRegistryUrl, hasTemplateSyntax, invalidateCache, isComponentAvailable, isValidSpecifier, parseVersion, prefetchComponents, processStyles, render, resolveBindingPath, resolveTemplate, resolveTemplateValue, resolveTemplatesDeep, resolveVersion, runAllTests, runTestCase, satisfiesVersion, setInCache, setRegistryUrl, updateStyles, validateAssertion, validateProps };