veilkit 0.0.0-stage → 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,209 @@
+import { a as VeilAnimationName, i as VeilDirection, j as VeilRevealTransition, A as AutoMeasureOptions, S as SkeletonProps, e as VeilSpinnerType, b as SpinnerProps, L as LoadingButtonProps, h as LazyImageProps, T as TextLoaderProps } from './types-Ciu5e5xt.cjs';
+export { C as CustomThemeInput, O as OverlayProps, f as PresetProps, P as ProgressProps, g as SkeletonController, c as VeilGlobalConfig, k as VeilPresetName, d as VeilPrimitiveType, V as VeilThemeName, l as VeilThemeTokens } from './types-Ciu5e5xt.cjs';
+export { BUILTIN_THEMES, createTheme, getThemeTokens } from './themes/index.cjs';
+export { L as LoadingManager, O as OverlayController, R as RouteProgressController, T as TrackOptions, V as VeilkitController, a as applyA11yLoading, c as createPreset, b as createPrimitive, d as createProgressElement, e as createSkeletonElement, f as createSkeletonParagraph, v as default, g as getLabel, h as getLocale, l as loadingManager, o as overlayController, p as progressController, r as removeA11yLoading, s as setLabels, i as setLocale, t as track, v as veil, w as wrapFetch } from './controller-5OzP0U8X.cjs';
+
+/**
+ * Veilkit - Animation Engine
+ * 12 GPU-Accelerated Animation Definitions (transform & opacity only)
+ */
+
+interface AnimationConfig {
+    name: VeilAnimationName;
+    duration?: number | string;
+    direction?: VeilDirection;
+    speedMultiplier?: number;
+    intensity?: number;
+}
+declare const ANIMATION_NAMES: VeilAnimationName[];
+/**
+ * Generates the CSS keyframes and utility rules for all 12 animations.
+ * Strictly uses transform and opacity for 60fps GPU execution.
+ */
+declare function getAnimationKeyframesCSS(): string;
+
+/**
+ * Veilkit - Global Synchronized Timeline
+ * Keeps all shimmer animations in lockstep phase via negative animation-delay
+ */
+/**
+ * Initializes or gets the baseline global timeline origin
+ */
+declare function getTimelineOrigin(): number;
+/**
+ * Computes a negative animation-delay string so that an element mounting right now
+ * is in exact phase synchronization with all other animations sharing this duration.
+ *
+ * @param durationMs Duration in milliseconds (default 1500)
+ * @returns CSS animation-delay value, e.g. "-642ms"
+ */
+declare function getSyncDelay(durationMs?: number): string;
+/**
+ * Parses duration string (e.g. "1.5s", "800ms") into milliseconds
+ */
+declare function parseDurationMs(duration?: string | number): number;
+
+/**
+ * Veilkit - Performance & Offscreen Observers
+ * Automatically pauses animations when offscreen or when document is hidden
+ */
+/**
+ * Ensures tab visibility change listener is attached
+ */
+declare function setupVisibilityObserver(): void;
+/**
+ * Registers an element to pause CSS animations when outside the viewport
+ */
+declare function observeOffscreen(element: HTMLElement): () => void;
+/**
+ * Disconnects all observers
+ */
+declare function teardownObservers(): void;
+
+/**
+ * Veilkit - CSS Engine & Style Injector
+ * SSR-safe, adoptedStyleSheets support, CSP nonce, and zero-layout-thrash animations
+ */
+/**
+ * Configure CSP nonce for injected styles
+ */
+declare function setNonce(nonce: string): void;
+/**
+ * Generates the full CSS stylesheet string
+ */
+declare function getStylesCSS(): string;
+/**
+ * Injects CSS into the document head safely (runs only once, SSR safe)
+ */
+declare function injectStyles(nonce?: string): void;
+
+/**
+ * Veilkit - Anti-Flicker Timing Controller
+ * Prevents UI flicker:
+ * 1. delay (default 150ms): suppresses loading state if task completes very quickly
+ * 2. minVisible (default 300ms): guarantees loader stays visible long enough to avoid rapid flashing
+ */
+interface AntiFlickerOptions {
+    delay?: number;
+    minVisible?: number;
+    onShow?: () => void;
+    onHide?: () => void;
+}
+declare class AntiFlickerController {
+    private delay;
+    private minVisible;
+    private onShow?;
+    private onHide?;
+    private delayTimer;
+    private minVisibleTimer;
+    private shownTimestamp;
+    private isVisible;
+    private isPending;
+    constructor(options?: AntiFlickerOptions);
+    /**
+     * Request loader to be shown (subject to delay)
+     */
+    start(): void;
+    private display;
+    /**
+     * Request loader to be hidden (subject to minVisible)
+     */
+    finish(callback?: () => void): void;
+    private hide;
+    active(): boolean;
+    destroy(): void;
+}
+
+/**
+ * Veilkit - Reveal Transitions Engine
+ * Seamless skeleton -> content reveal transitions:
+ * fade, blur-in, slide-up, scale, stagger-children, none
+ */
+
+interface RevealOptions {
+    transition?: VeilRevealTransition;
+    duration?: number;
+    easing?: string;
+    onComplete?: () => void;
+}
+declare function applyReveal(element: HTMLElement, options?: RevealOptions): void;
+
+/**
+ * Veilkit - Auto-Measure Skeleton Engine
+ * Dynamically measures real DOM trees, generates matching skeleton overlays,
+ * updates on resize/mutation, and supports instant layout caching.
+ */
+
+interface LeafBox {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    radius: string;
+    shape: 'circle' | 'rect' | 'line';
+}
+interface CachedLayout {
+    width: number;
+    height: number;
+    boxes: LeafBox[];
+}
+/**
+ * Retrieve cached layout by key
+ */
+declare function getCachedLayout(cacheKey: string): CachedLayout | null;
+/**
+ * Store layout in cache
+ */
+declare function setCachedLayout(cacheKey: string, layout: CachedLayout, persist?: boolean): void;
+/**
+ * Measures the leaf elements of a container DOM tree
+ */
+declare function measureContainer(container: HTMLElement, ignoreSelector?: string): CachedLayout;
+/**
+ * Creates and attaches an auto-measured skeleton overlay to a container
+ */
+declare function createAutoMeasureOverlay(container: HTMLElement, options?: AutoMeasureOptions, skeletonProps?: SkeletonProps): {
+    overlay: HTMLElement;
+    refresh: () => void;
+    destroy: () => void;
+};
+
+/**
+ * Veilkit - 12 Spinner Loaders
+ * Types: ring, dual-ring, dots, bars, pulse, orbit, wave, bounce,
+ *        ios-activity, glass-orb, morph, progress-circle
+ */
+
+declare const SPINNER_TYPES: VeilSpinnerType[];
+/**
+ * Creates a DOM spinner element with specified type, size, and colors
+ */
+declare function createSpinner(props?: SpinnerProps): HTMLElement;
+
+/**
+ * Veilkit - Loading Button Controller
+ * Inline spinner, preserves exact button dimensions to prevent layout shifts,
+ * disables clicks, and applies aria-disabled state.
+ */
+
+declare function wrapLoadingButton(buttonEl: HTMLButtonElement, props?: LoadingButtonProps): {
+    setLoading: (loading: boolean, loadingText?: string) => void;
+    destroy: () => void;
+};
+
+/**
+ * Veilkit - Lazy Image & Media Placeholder
+ * Renders synchronized skeleton placeholder until image loads,
+ * then reveals with smooth blur-up transition and handles error fallback.
+ */
+
+declare function createLazyImage(props: LazyImageProps): HTMLElement;
+
+/**
+ * Veilkit - Text Loader
+ * Animated localized typing text with pulsing ellipsis dots
+ */
+
+declare function createTextLoader(props?: TextLoaderProps): HTMLElement;
+
+export { ANIMATION_NAMES, type AnimationConfig, AntiFlickerController, type AntiFlickerOptions, AutoMeasureOptions, type CachedLayout, LazyImageProps, type LeafBox, LoadingButtonProps, type RevealOptions, SPINNER_TYPES, SkeletonProps, SpinnerProps, TextLoaderProps, VeilAnimationName, VeilDirection, VeilRevealTransition, VeilSpinnerType, applyReveal, createAutoMeasureOverlay, createLazyImage, createSpinner, createTextLoader, getAnimationKeyframesCSS, getCachedLayout, getStylesCSS, getSyncDelay, getTimelineOrigin, injectStyles, measureContainer, observeOffscreen, parseDurationMs, setCachedLayout, setNonce, setupVisibilityObserver, teardownObservers, wrapLoadingButton };

package/dist/index.d.ts

@@ -0,0 +1,209 @@
+import { a as VeilAnimationName, i as VeilDirection, j as VeilRevealTransition, A as AutoMeasureOptions, S as SkeletonProps, e as VeilSpinnerType, b as SpinnerProps, L as LoadingButtonProps, h as LazyImageProps, T as TextLoaderProps } from './types-Ciu5e5xt.js';
+export { C as CustomThemeInput, O as OverlayProps, f as PresetProps, P as ProgressProps, g as SkeletonController, c as VeilGlobalConfig, k as VeilPresetName, d as VeilPrimitiveType, V as VeilThemeName, l as VeilThemeTokens } from './types-Ciu5e5xt.js';
+export { BUILTIN_THEMES, createTheme, getThemeTokens } from './themes/index.js';
+export { L as LoadingManager, O as OverlayController, R as RouteProgressController, T as TrackOptions, V as VeilkitController, a as applyA11yLoading, c as createPreset, b as createPrimitive, d as createProgressElement, e as createSkeletonElement, f as createSkeletonParagraph, v as default, g as getLabel, h as getLocale, l as loadingManager, o as overlayController, p as progressController, r as removeA11yLoading, s as setLabels, i as setLocale, t as track, v as veil, w as wrapFetch } from './controller-Co5bvnaB.js';
+
+/**
+ * Veilkit - Animation Engine
+ * 12 GPU-Accelerated Animation Definitions (transform & opacity only)
+ */
+
+interface AnimationConfig {
+    name: VeilAnimationName;
+    duration?: number | string;
+    direction?: VeilDirection;
+    speedMultiplier?: number;
+    intensity?: number;
+}
+declare const ANIMATION_NAMES: VeilAnimationName[];
+/**
+ * Generates the CSS keyframes and utility rules for all 12 animations.
+ * Strictly uses transform and opacity for 60fps GPU execution.
+ */
+declare function getAnimationKeyframesCSS(): string;
+
+/**
+ * Veilkit - Global Synchronized Timeline
+ * Keeps all shimmer animations in lockstep phase via negative animation-delay
+ */
+/**
+ * Initializes or gets the baseline global timeline origin
+ */
+declare function getTimelineOrigin(): number;
+/**
+ * Computes a negative animation-delay string so that an element mounting right now
+ * is in exact phase synchronization with all other animations sharing this duration.
+ *
+ * @param durationMs Duration in milliseconds (default 1500)
+ * @returns CSS animation-delay value, e.g. "-642ms"
+ */
+declare function getSyncDelay(durationMs?: number): string;
+/**
+ * Parses duration string (e.g. "1.5s", "800ms") into milliseconds
+ */
+declare function parseDurationMs(duration?: string | number): number;
+
+/**
+ * Veilkit - Performance & Offscreen Observers
+ * Automatically pauses animations when offscreen or when document is hidden
+ */
+/**
+ * Ensures tab visibility change listener is attached
+ */
+declare function setupVisibilityObserver(): void;
+/**
+ * Registers an element to pause CSS animations when outside the viewport
+ */
+declare function observeOffscreen(element: HTMLElement): () => void;
+/**
+ * Disconnects all observers
+ */
+declare function teardownObservers(): void;
+
+/**
+ * Veilkit - CSS Engine & Style Injector
+ * SSR-safe, adoptedStyleSheets support, CSP nonce, and zero-layout-thrash animations
+ */
+/**
+ * Configure CSP nonce for injected styles
+ */
+declare function setNonce(nonce: string): void;
+/**
+ * Generates the full CSS stylesheet string
+ */
+declare function getStylesCSS(): string;
+/**
+ * Injects CSS into the document head safely (runs only once, SSR safe)
+ */
+declare function injectStyles(nonce?: string): void;
+
+/**
+ * Veilkit - Anti-Flicker Timing Controller
+ * Prevents UI flicker:
+ * 1. delay (default 150ms): suppresses loading state if task completes very quickly
+ * 2. minVisible (default 300ms): guarantees loader stays visible long enough to avoid rapid flashing
+ */
+interface AntiFlickerOptions {
+    delay?: number;
+    minVisible?: number;
+    onShow?: () => void;
+    onHide?: () => void;
+}
+declare class AntiFlickerController {
+    private delay;
+    private minVisible;
+    private onShow?;
+    private onHide?;
+    private delayTimer;
+    private minVisibleTimer;
+    private shownTimestamp;
+    private isVisible;
+    private isPending;
+    constructor(options?: AntiFlickerOptions);
+    /**
+     * Request loader to be shown (subject to delay)
+     */
+    start(): void;
+    private display;
+    /**
+     * Request loader to be hidden (subject to minVisible)
+     */
+    finish(callback?: () => void): void;
+    private hide;
+    active(): boolean;
+    destroy(): void;
+}
+
+/**
+ * Veilkit - Reveal Transitions Engine
+ * Seamless skeleton -> content reveal transitions:
+ * fade, blur-in, slide-up, scale, stagger-children, none
+ */
+
+interface RevealOptions {
+    transition?: VeilRevealTransition;
+    duration?: number;
+    easing?: string;
+    onComplete?: () => void;
+}
+declare function applyReveal(element: HTMLElement, options?: RevealOptions): void;
+
+/**
+ * Veilkit - Auto-Measure Skeleton Engine
+ * Dynamically measures real DOM trees, generates matching skeleton overlays,
+ * updates on resize/mutation, and supports instant layout caching.
+ */
+
+interface LeafBox {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    radius: string;
+    shape: 'circle' | 'rect' | 'line';
+}
+interface CachedLayout {
+    width: number;
+    height: number;
+    boxes: LeafBox[];
+}
+/**
+ * Retrieve cached layout by key
+ */
+declare function getCachedLayout(cacheKey: string): CachedLayout | null;
+/**
+ * Store layout in cache
+ */
+declare function setCachedLayout(cacheKey: string, layout: CachedLayout, persist?: boolean): void;
+/**
+ * Measures the leaf elements of a container DOM tree
+ */
+declare function measureContainer(container: HTMLElement, ignoreSelector?: string): CachedLayout;
+/**
+ * Creates and attaches an auto-measured skeleton overlay to a container
+ */
+declare function createAutoMeasureOverlay(container: HTMLElement, options?: AutoMeasureOptions, skeletonProps?: SkeletonProps): {
+    overlay: HTMLElement;
+    refresh: () => void;
+    destroy: () => void;
+};
+
+/**
+ * Veilkit - 12 Spinner Loaders
+ * Types: ring, dual-ring, dots, bars, pulse, orbit, wave, bounce,
+ *        ios-activity, glass-orb, morph, progress-circle
+ */
+
+declare const SPINNER_TYPES: VeilSpinnerType[];
+/**
+ * Creates a DOM spinner element with specified type, size, and colors
+ */
+declare function createSpinner(props?: SpinnerProps): HTMLElement;
+
+/**
+ * Veilkit - Loading Button Controller
+ * Inline spinner, preserves exact button dimensions to prevent layout shifts,
+ * disables clicks, and applies aria-disabled state.
+ */
+
+declare function wrapLoadingButton(buttonEl: HTMLButtonElement, props?: LoadingButtonProps): {
+    setLoading: (loading: boolean, loadingText?: string) => void;
+    destroy: () => void;
+};
+
+/**
+ * Veilkit - Lazy Image & Media Placeholder
+ * Renders synchronized skeleton placeholder until image loads,
+ * then reveals with smooth blur-up transition and handles error fallback.
+ */
+
+declare function createLazyImage(props: LazyImageProps): HTMLElement;
+
+/**
+ * Veilkit - Text Loader
+ * Animated localized typing text with pulsing ellipsis dots
+ */
+
+declare function createTextLoader(props?: TextLoaderProps): HTMLElement;
+
+export { ANIMATION_NAMES, type AnimationConfig, AntiFlickerController, type AntiFlickerOptions, AutoMeasureOptions, type CachedLayout, LazyImageProps, type LeafBox, LoadingButtonProps, type RevealOptions, SPINNER_TYPES, SkeletonProps, SpinnerProps, TextLoaderProps, VeilAnimationName, VeilDirection, VeilRevealTransition, VeilSpinnerType, applyReveal, createAutoMeasureOverlay, createLazyImage, createSpinner, createTextLoader, getAnimationKeyframesCSS, getCachedLayout, getStylesCSS, getSyncDelay, getTimelineOrigin, injectStyles, measureContainer, observeOffscreen, parseDurationMs, setCachedLayout, setNonce, setupVisibilityObserver, teardownObservers, wrapLoadingButton };