@stacksjs/stx 0.2.0 → 0.2.3

package/dist/props.d.ts

@@ -0,0 +1,199 @@
+/**
+ * Define component props with type safety and validation.
+ *
+ * @example
+ * ```typescript
+ * // Simple usage with types only
+ * const props = defineProps<{
+ *   title: string
+ *   count: number
+ * }>()
+ *
+ * // With validation and defaults
+ * const props = defineProps<{
+ *   title: string
+ *   count?: number
+ *   status: 'active' | 'inactive'
+ * }>({
+ *   title: { required: true },
+ *   count: { default: 0 },
+ *   status: {
+ *     default: 'active',
+ *     validator: (v) => ['active', 'inactive'].includes(v)
+ *   }
+ * })
+ * ```
+ */
+export declare function defineProps<T extends Record<string, unknown>>(definitions?: PropsDefinition<T>): T;
+/**
+ * Define props with runtime validation.
+ * Use this when you need validation errors at runtime.
+ */
+export declare function definePropsWithValidation<T extends Record<string, unknown>>(definitions: PropsDefinition<T>, options?: {
+    componentName?: string
+    throwOnError?: boolean
+    logWarnings?: boolean
+  }): { props: T; validation: PropValidationResult };
+/**
+ * Define default values for props.
+ *
+ * @example
+ * ```typescript
+ * const props = withDefaults(defineProps<{
+ *   title: string
+ *   count?: number
+ *   items?: string[]
+ * }>(), {
+ *   count: 0,
+ *   items: () => []
+ * })
+ * ```
+ */
+export declare function withDefaults<T extends Record<string, unknown>>(props: T, defaults: Partial<{ [K in keyof T]: T[K] | (() => T[K]) }>): T;
+/**
+ * Create a prop type definition for a specific type.
+ */
+export declare function prop<T>(options: PropOptions<T>): PropOptions<T>;
+/**
+ * Create a required prop.
+ */
+export declare function required<T>(type?: PropType<T>): PropOptions<T>;
+/**
+ * Create an optional prop with default.
+ */
+export declare function optional<T>(defaultValue: T | (() => T), type?: PropType<T>): PropOptions<T>;
+/**
+ * Create a prop with a validator.
+ */
+export declare function validated<T>(validator: (value: T) => boolean, options?: Omit<PropOptions<T>, 'validator'>): PropOptions<T>;
+/**
+ * Create a prop that accepts one of specific values.
+ */
+export declare function oneOf<T extends string | number>(values: readonly T[], options?: Omit<PropOptions<T>, 'validator'>): PropOptions<T>;
+/**
+ * Create a prop for array of specific type.
+ */
+export declare function arrayOf<T>(_itemType: PropType<T>, options?: Omit<PropOptions<T[]>, 'type'>): PropOptions<T[]>;
+/**
+ * Create a prop for object with specific shape.
+ */
+export declare function shape<T extends Record<string, unknown>>(_shape: PropsDefinition<T>, options?: Omit<PropOptions<T>, 'type'>): PropOptions<T>;
+/**
+ * Process props passed to a component.
+ * Called internally during component rendering.
+ */
+export declare function processComponentProps(rawProps: Record<string, unknown>, definitions?: PropsDefinition<Record<string, unknown>>, componentName?: string): Record<string, unknown>;
+/**
+ * Define component events (emits).
+ *
+ * @example
+ * ```typescript
+ * const emit = defineEmits<{
+ *   'update:value': string
+ *   'submit': { data: FormData }
+ *   'close': void
+ * }>()
+ *
+ * // Usage
+ * emit('update:value', 'new value')
+ * emit('submit', { data: formData })
+ * emit('close', undefined)
+ * ```
+ */
+export declare function defineEmits<E extends Record<string, unknown>>(): EmitFn<E>;
+/**
+ * Expose component methods/properties to parent.
+ *
+ * @example
+ * ```typescript
+ * defineExpose({
+ *   focus: () => inputRef.value?.focus(),
+ *   reset: () => { value = '' },
+ *   value: computed(() => internalValue)
+ * })
+ * ```
+ */
+export declare function defineExpose<T extends Record<string, unknown>>(exposed: T): void;
+/**
+ * Generate TypeScript interface from prop definitions.
+ * Useful for documentation and type generation.
+ */
+export declare function generatePropsInterface(componentName: string, definitions: PropsDefinition<Record<string, unknown>>): string;
+/** Prop definition options */
+export declare interface PropOptions<T = unknown> {
+  type?: PropType<T> | PropType<T>[]
+  required?: boolean
+  default?: T | (() => T)
+  validator?: (value: T) => boolean
+  description?: string
+}
+/** Prop validation error */
+export declare interface PropValidationError {
+  prop: string
+  message: string
+  value: unknown
+  expected?: string
+}
+/** Prop validation result */
+export declare interface PropValidationResult {
+  valid: boolean
+  errors: PropValidationError[]
+  warnings: string[]
+}
+/**
+ * STX Props System
+ *
+ * Provides type-safe component props with runtime validation.
+ *
+ * @module props
+ *
+ * @example
+ * ```html
+ * <script>
+ * import { defineProps } from 'stx'
+ *
+ * const props = defineProps<{
+ *   title: string
+ *   count?: number
+ *   items: string[]
+ * }>({
+ *   title: { required: true },
+ *   count: { default: 0 },
+ *   items: { default: () => [] }
+ * })
+ * </script>
+ *
+ * <h1>{{ props.title }}</h1>
+ * <p>Count: {{ props.count }}</p>
+ * ```
+ */
+/** Supported prop types */
+export type PropType<T> = | StringConstructor
+  | NumberConstructor
+  | BooleanConstructor
+  | ArrayConstructor
+  | ObjectConstructor
+  | FunctionConstructor
+  | DateConstructor
+  | SymbolConstructor
+  | { new (...args: unknown[]): T }
+  | PropType<T>[]
+/** Props definition object */
+export type PropsDefinition<T> = {
+  [K in keyof T]?: PropOptions<T[K]> | PropType<T[K]>
+}
+/** Extracted prop types */
+export type ExtractPropTypes<T extends PropsDefinition<unknown>> = {
+  [K in keyof T]: T[K] extends PropOptions<infer V>
+    ? V
+    : T[K] extends PropType<infer V>
+      ? V
+      : unknown
+}
+/** Event handler type */
+export type EventHandler<T = unknown> = (payload: T) => void
+/** Emit function type */
+export type EmitFn<E extends Record<string, unknown>> = <K extends keyof E>(
+  event: K,
+  payload: E[K],
+) => void

package/dist/pwa/audit.d.ts

@@ -0,0 +1,42 @@
+import type { StxOptions } from '../types';
+/**
+ * Run PWA configuration audit
+ */
+export declare function auditConfig(options: StxOptions): AuditCheck[];
+/**
+ * Run PWA build output audit
+ */
+export declare function auditBuildOutput(outputDir: string): AuditCheck[];
+/**
+ * Calculate audit score and summary
+ */
+export declare function calculateAuditResult(checks: AuditCheck[]): AuditResult;
+/**
+ * Run full PWA audit
+ */
+export declare function runPwaAudit(options: StxOptions, outputDir?: string): AuditResult;
+/**
+ * Format audit result for console output
+ */
+export declare function formatAuditResult(result: AuditResult): string;
+/**
+ * Audit check result
+ */
+export declare interface AuditCheck {
+  id: string
+  name: string
+  category: 'required' | 'recommended' | 'optional'
+  passed: boolean
+  message: string
+  details?: string
+}
+/**
+ * Audit result summary
+ */
+export declare interface AuditResult {
+  score: number
+  passed: number
+  failed: number
+  warnings: number
+  checks: AuditCheck[]
+}

package/dist/pwa/directives.d.ts

@@ -0,0 +1,29 @@
+import type { CustomDirective } from '../types';
+/**
+ * Register all PWA directives with the config
+ */
+export declare function registerPwaDirectives(customDirectives: CustomDirective[]): CustomDirective[];
+/**
+ * PWA Install Button Directive
+ * Usage: @pwa.installButton ... @endpwa.installButton
+ */
+export declare const pwaInstallDirective: CustomDirective;
+/**
+ * PWA Update Prompt Directive
+ * Usage: @pwa.updatePrompt ... @endpwa.updatePrompt
+ */
+export declare const pwaUpdateDirective: CustomDirective;
+/**
+ * PWA Offline Indicator Directive
+ * Usage: @pwa.offlineIndicator ... @endpwa.offlineIndicator
+ */
+export declare const pwaOfflineDirective: CustomDirective;
+/**
+ * PWA Push Subscribe Directive
+ * Usage: @pwa.pushSubscribe ... @endpwa.pushSubscribe
+ */
+export declare const pwaPushDirective: CustomDirective;
+/**
+ * All PWA directives
+ */
+export declare const pwaDirectives: CustomDirective[];

package/dist/pwa/icons.d.ts

@@ -0,0 +1,39 @@
+import type { PwaIconConfig, StxOptions } from '../types';
+/**
+ * Generate PWA icons from a source image
+ *
+ * @param options - stx configuration options
+ * @param outputDir - Output directory for generated icons
+ * @returns Result object with success status and file paths
+ */
+export declare function generatePwaIcons(options: StxOptions, outputDir: string): Promise<IconGenerationResult>;
+/**
+ * Get list of icon paths that will be generated
+ * Useful for manifest generation and cache precaching
+ */
+export declare function getExpectedIconPaths(config: PwaIconConfig): string[];
+/**
+ * Check if sharp is available
+ */
+export declare function isSharpAvailable(): Promise<boolean>;
+/**
+ * Default icon sizes for PWA
+ */
+export declare const DEFAULT_ICON_SIZES: readonly [72, 96, 128, 144, 152, 192, 384, 512];
+/**
+ * Apple touch icon sizes
+ */
+export declare const APPLE_TOUCH_ICON_SIZES: readonly [120, 152, 167, 180];
+/**
+ * Favicon sizes
+ */
+export declare const FAVICON_SIZES: readonly [16, 32];
+/**
+ * Icon generation result
+ */
+export declare interface IconGenerationResult {
+  success: boolean
+  generatedFiles: string[]
+  errors: string[]
+  warnings: string[]
+}

package/dist/pwa/index.d.ts

@@ -0,0 +1,59 @@
+export {
+  generateServiceWorker,
+  generateServiceWorkerAuto,
+  getServiceWorkerFileName,
+  isWorkboxEnabled,
+} from './service-worker';
+export {
+  generateWorkboxConfig,
+  generateWorkboxServiceWorker,
+  isWorkboxEnabled as checkWorkboxEnabled,
+  getServiceWorkerGenerator,
+  type WorkboxConfig,
+  type WorkboxModule,
+  type RuntimeCacheRule,
+} from './workbox';
+export {
+  mapStrategyToWorkbox,
+  getWorkboxStrategyName,
+  generateRuntimeCachingCode,
+  generatePatternMatcher,
+  convertRouteToWorkbox,
+  generateRuntimeCaching,
+  createExpirationPlugin,
+  createCacheableResponsePlugin,
+  createBackgroundSyncPlugin,
+  type StxCacheStrategy,
+  type WorkboxStrategy,
+  type WorkboxPlugin,
+  type WorkboxRoute,
+  type RuntimeCachingConfig,
+} from './workbox-strategies';
+export {
+  generateManifest,
+} from './manifest';
+export {
+  generatePwaIcons,
+  type IconGenerationResult,
+} from './icons';
+export {
+  generatePrecacheManifest,
+  generatePrecacheManifestJs,
+  formatSize,
+  type PrecacheEntry,
+} from './precache';
+export {
+  generateOfflinePage,
+} from './offline';
+export {
+  injectPwaTags,
+  generateSwRegistrationScript,
+} from './inject';
+export {
+  runPwaAudit,
+  type AuditResult,
+  type AuditCheck,
+} from './audit';
+export {
+  pwaDirectives,
+} from './directives';

package/dist/pwa/inject.d.ts

@@ -0,0 +1,22 @@
+import type { StxOptions } from '../types';
+/**
+ * Generate PWA HTML tags for injection into <head>
+ */
+export declare function generatePwaTags(options: StxOptions): string;
+/**
+ * Inject PWA tags into HTML document
+ */
+export declare function injectPwaTags(html: string, options: StxOptions): string;
+/**
+ * Generate standalone service worker registration script
+ * Use this if you want to manually add the registration script
+ */
+export declare function generateSwRegistrationScript(options: StxOptions): string;
+/**
+ * Generate manifest link tag
+ */
+export declare function generateManifestLink(): string;
+/**
+ * Generate theme color meta tag
+ */
+export declare function generateThemeColorMeta(color: string): string;

package/dist/pwa/manifest.d.ts

@@ -0,0 +1,104 @@
+import type { PwaManifestConfig, StxOptions } from '../types';
+/**
+ * Generate a Web App Manifest object from configuration
+ */
+export declare function generateManifest(options: StxOptions): WebAppManifest | null;
+/**
+ * Generate manifest.json file content as a string
+ */
+export declare function generateManifestJson(options: StxOptions): string;
+/**
+ * Merge user manifest config with defaults
+ */
+export declare function mergeManifestConfig(userConfig: Partial<PwaManifestConfig>, defaultConfig: PwaManifestConfig): PwaManifestConfig;
+/**
+ * Validate manifest configuration
+ * Returns an array of validation errors
+ */
+export declare function validateManifest(options: StxOptions): string[];
+/**
+ * Manifest icon entry structure
+ */
+export declare interface ManifestIcon {
+  src: string
+  sizes: string
+  type: string
+  purpose?: string
+}
+/**
+ * Share target entry structure
+ */
+export declare interface ManifestShareTarget {
+  action: string
+  method?: 'GET' | 'POST'
+  enctype?: string
+  params: {
+    title?: string
+    text?: string
+    url?: string
+    files?: Array<{
+      name: string
+      accept: string[]
+    }>
+  }
+}
+/**
+ * File handler entry structure
+ */
+export declare interface ManifestFileHandler {
+  action: string
+  accept: Record<string, string[]>
+  icons?: ManifestIcon[]
+  launch_type?: 'single-client' | 'multiple-clients'
+}
+/**
+ * Protocol handler entry structure
+ */
+export declare interface ManifestProtocolHandler {
+  protocol: string
+  url: string
+}
+/**
+ * Complete Web App Manifest structure
+ */
+export declare interface WebAppManifest {
+  name: string
+  short_name?: string
+  description?: string
+  start_url: string
+  display: string
+  display_override?: string[]
+  orientation?: string
+  theme_color?: string
+  background_color?: string
+  scope?: string
+  lang?: string
+  dir?: string
+  id?: string
+  categories?: string[]
+  icons: ManifestIcon[]
+  shortcuts?: Array<{
+    name: string
+    short_name?: string
+    description?: string
+    url: string
+    icons?: ManifestIcon[]
+  }>
+  screenshots?: Array<{
+    src: string
+    sizes: string
+    type?: string
+    label?: string
+    form_factor?: 'wide' | 'narrow'
+  }>
+  share_target?: ManifestShareTarget
+  file_handlers?: ManifestFileHandler[]
+  protocol_handlers?: ManifestProtocolHandler[]
+  launch_handler?: {
+    client_mode: 'auto' | 'focus-existing' | 'navigate-new' | 'navigate-existing'
+  }
+  handle_links?: 'auto' | 'preferred' | 'not-preferred'
+  edge_side_panel?: {
+    preferred_width?: number
+  }
+}

package/dist/pwa/offline.d.ts

@@ -0,0 +1,8 @@
+import type { StxOptions } from '../types';
+/**
+ * Generate offline fallback page HTML
+ *
+ * If a custom offline page is specified in config, it will be processed.
+ * Otherwise, a default styled offline page is generated.
+ */
+export declare function generateOfflinePage(options: StxOptions): Promise<string>;

package/dist/pwa/precache.d.ts

@@ -0,0 +1,29 @@
+import type { StxOptions } from '../types';
+/**
+ * Generate precache manifest from build output directory
+ */
+export declare function generatePrecacheManifest(outputDir: string, options: StxOptions): PrecacheManifest;
+/**
+ * Generate precache manifest as JavaScript array for service worker
+ */
+export declare function generatePrecacheManifestJs(manifest: PrecacheManifest): string;
+/**
+ * Get human-readable size
+ */
+export declare function formatSize(bytes: number): string;
+/**
+ * Precache manifest entry
+ */
+export declare interface PrecacheEntry {
+  url: string
+  revision: string
+  size: number
+}
+/**
+ * Precache manifest result
+ */
+export declare interface PrecacheManifest {
+  entries: PrecacheEntry[]
+  totalSize: number
+  fileCount: number
+}

package/dist/pwa/service-worker.d.ts

@@ -0,0 +1,21 @@
+import type { StxOptions } from '../types';
+/**
+ * Generate the service worker JavaScript code
+ */
+export declare function generateServiceWorker(options: StxOptions, outputDir?: string): string;
+/**
+ * Get the service worker file name from config
+ */
+export declare function getServiceWorkerFileName(options: StxOptions): string;
+/**
+ * Check if Workbox mode is enabled
+ */
+export declare function isWorkboxEnabled(options: StxOptions): boolean;
+/**
+ * Generate service worker code (auto-selects native or Workbox based on config)
+ *
+ * @param options - stx configuration options
+ * @param outputDir - optional output directory for precache manifest
+ * @returns Generated service worker JavaScript code
+ */
+export declare function generateServiceWorkerAuto(options: StxOptions, outputDir?: string): string;

package/dist/pwa/workbox-strategies.d.ts

@@ -0,0 +1,100 @@
+import type { StxOptions } from '../types';
+/**
+ * Map stx strategy name to Workbox strategy
+ */
+export declare function mapStrategyToWorkbox(strategy: StxCacheStrategy): WorkboxStrategy;
+/**
+ * Get Workbox strategy class name
+ */
+export declare function getWorkboxStrategyName(strategy: StxCacheStrategy): string;
+/**
+ * Generate ExpirationPlugin config
+ */
+export declare function createExpirationPlugin(options: {
+  maxEntries?: number
+  maxAgeSeconds?: number
+  purgeOnQuotaError?: boolean
+}): WorkboxPlugin;
+/**
+ * Generate CacheableResponsePlugin config
+ */
+export declare function createCacheableResponsePlugin(options: {
+  statuses?: number[]
+  headers?: Record<string, string>
+}): WorkboxPlugin;
+/**
+ * Generate BackgroundSyncPlugin config
+ */
+export declare function createBackgroundSyncPlugin(options: {
+  name: string
+  maxRetentionTime?: number
+  forceSyncFallback?: boolean
+}): WorkboxPlugin;
+/**
+ * Convert stx route config to Workbox runtime caching config
+ */
+export declare function convertRouteToWorkbox(route: {
+  pattern: string
+  strategy: StxCacheStrategy
+  cacheName?: string
+  maxAgeSeconds?: number
+  maxEntries?: number
+}): RuntimeCachingConfig;
+/**
+ * Generate runtime caching configuration from stx routes
+ */
+export declare function generateRuntimeCaching(routes: Array<{
+    pattern: string
+    strategy: StxCacheStrategy
+    cacheName?: string
+    maxAgeSeconds?: number
+    maxEntries?: number
+  }>): RuntimeCachingConfig[];
+/**
+ * Generate runtime caching JavaScript code
+ */
+export declare function generateRuntimeCachingCode(options: StxOptions): string;
+/**
+ * Generate pattern matcher for Workbox registerRoute
+ */
+export declare function generatePatternMatcher(pattern: string): string;
+export declare interface WorkboxStrategy {
+  className: string
+  importFrom: 'workbox-strategies'
+  defaultPlugins?: WorkboxPlugin[]
+}
+export declare interface WorkboxPlugin {
+  className: string
+  importFrom: string
+  options?: Record<string, unknown>
+}
+export declare interface WorkboxRoute {
+  pattern: string
+  matchType: 'pathname' | 'destination' | 'custom'
+  strategy: WorkboxStrategy
+  plugins?: WorkboxPlugin[]
+  cacheName?: string
+}
+export declare interface RuntimeCachingConfig {
+  urlPattern: string | RegExp
+  handler: string
+  options?: {
+    cacheName?: string
+    plugins?: WorkboxPlugin[]
+    networkTimeoutSeconds?: number
+    matchOptions?: {
+      ignoreSearch?: boolean
+      ignoreMethod?: boolean
+      ignoreVary?: boolean
+    }
+  }
+  method?: string
+}
+// ============================================================================
+// Types
+// ============================================================================
+export type StxCacheStrategy = | 'cache-first'
+  | 'network-first'
+  | 'stale-while-revalidate'
+  | 'network-only'
+  | 'cache-only'