@stacksjs/stx 0.2.154 → 0.2.156

package/dist/types/pwa-types.d.ts

@@ -1,213 +1,338 @@
+/**
+ * Progressive Web App (PWA) Types
+ */
+/**
+ * PWA caching strategy for service worker routes
+ */
+export type PwaCacheStrategy = 'cache-first' | 'network-first' | 'stale-while-revalidate' | 'network-only' | 'cache-only';
 /**
  * PWA route cache configuration
  * Defines how specific routes should be cached by the service worker
  */
-export declare interface PwaRouteCache {
-  pattern: string
-  strategy: PwaCacheStrategy
-  cacheName?: string
-  maxAgeSeconds?: number
-  maxEntries?: number
+export interface PwaRouteCache {
+    /** Route pattern (glob-style, e.g., '/api/*', '*.{js,css}') */
+    pattern: string;
+    /** Caching strategy for this route */
+    strategy: PwaCacheStrategy;
+    /** Custom cache name for this route group */
+    cacheName?: string;
+    /** Cache expiration in seconds */
+    maxAgeSeconds?: number;
+    /** Maximum number of entries in cache */
+    maxEntries?: number;
 }
 /**
  * PWA icon configuration for automatic generation
  */
-export declare interface PwaIconConfig {
-  src: string
-  sizes?: number[]
-  generateWebP?: boolean
-  generateAppleIcons?: boolean
-  outputDir?: string
-  purpose?: ('any' | 'maskable' | 'monochrome')[]
+export interface PwaIconConfig {
+    /** Source icon path (512x512 PNG recommended) */
+    src: string;
+    /** Sizes to generate (default: [72, 96, 128, 144, 152, 192, 384, 512]) */
+    sizes?: number[];
+    /** Generate WebP variants alongside PNG */
+    generateWebP?: boolean;
+    /** Generate Apple touch icon variants */
+    generateAppleIcons?: boolean;
+    /** Output directory for generated icons (relative to output dir) */
+    outputDir?: string;
+    /** Icon purpose for manifest ('any', 'maskable', 'monochrome') */
+    purpose?: ('any' | 'maskable' | 'monochrome')[];
 }
 /**
  * PWA shortcut definition for app shortcuts menu
  */
-export declare interface PwaShortcut {
-  name: string
-  shortName?: string
-  description?: string
-  url: string
-  icons?: Array<{ src: string, sizes: string, type?: string }>
+export interface PwaShortcut {
+    /** Shortcut name */
+    name: string;
+    /** Short name (optional) */
+    shortName?: string;
+    /** Description of the shortcut */
+    description?: string;
+    /** URL to navigate to */
+    url: string;
+    /** Icons for the shortcut */
+    icons?: Array<{
+        src: string;
+        sizes: string;
+        type?: string;
+    }>;
 }
 /**
  * PWA screenshot definition for app store listings
  */
-export declare interface PwaScreenshot {
-  src: string
-  sizes: string
-  type?: string
-  label?: string
-  platform?: 'wide' | 'narrow'
+export interface PwaScreenshot {
+    /** Screenshot image path */
+    src: string;
+    /** Image dimensions (e.g., '1280x720') */
+    sizes: string;
+    /** Image MIME type */
+    type?: string;
+    /** Screenshot label/description */
+    label?: string;
+    /** Platform: 'wide' for desktop, 'narrow' for mobile */
+    platform?: 'wide' | 'narrow';
 }
 /**
  * PWA Web App Manifest configuration
  */
-export declare interface PwaManifestConfig {
-  name: string
-  shortName?: string
-  description?: string
-  startUrl?: string
-  display?: 'fullscreen' | 'standalone' | 'minimal-ui' | 'browser'
-  displayOverride?: string[]
-  orientation?: 'portrait' | 'landscape' | 'any' | 'portrait-primary' | 'portrait-secondary' | 'landscape-primary' | 'landscape-secondary'
-  themeColor?: string
-  backgroundColor?: string
-  scope?: string
-  lang?: string
-  dir?: 'ltr' | 'rtl' | 'auto'
-  id?: string
-  categories?: string[]
-  shortcuts?: PwaShortcut[]
-  screenshots?: PwaScreenshot[]
-  launchHandler?: 'auto' | 'focus-existing' | 'navigate-new' | 'navigate-existing'
-  handleLinks?: 'auto' | 'preferred' | 'not-preferred'
-  edgeSidePanel?: {
-    enabled: boolean
-    preferredWidth?: number
-  }
+export interface PwaManifestConfig {
+    /** Full application name */
+    name: string;
+    /** Short name (displayed on home screen) */
+    shortName?: string;
+    /** Application description */
+    description?: string;
+    /** Start URL when app is launched */
+    startUrl?: string;
+    /** Display mode for the app */
+    display?: 'fullscreen' | 'standalone' | 'minimal-ui' | 'browser';
+    /** Display mode override order */
+    displayOverride?: string[];
+    /** Preferred orientation */
+    orientation?: 'portrait' | 'landscape' | 'any' | 'portrait-primary' | 'portrait-secondary' | 'landscape-primary' | 'landscape-secondary';
+    /** Theme color (affects browser UI) */
+    themeColor?: string;
+    /** Background color (splash screen) */
+    backgroundColor?: string;
+    /** Scope of the PWA */
+    scope?: string;
+    /** Primary language */
+    lang?: string;
+    /** Text direction */
+    dir?: 'ltr' | 'rtl' | 'auto';
+    /** Unique app ID */
+    id?: string;
+    /** App categories for store listings */
+    categories?: string[];
+    /** App shortcuts for quick actions */
+    shortcuts?: PwaShortcut[];
+    /** Screenshots for app store listings */
+    screenshots?: PwaScreenshot[];
+    /** Launch handler behavior */
+    launchHandler?: 'auto' | 'focus-existing' | 'navigate-new' | 'navigate-existing';
+    /** How to handle links */
+    handleLinks?: 'auto' | 'preferred' | 'not-preferred';
+    /** Edge side panel configuration */
+    edgeSidePanel?: {
+        enabled: boolean;
+        preferredWidth?: number;
+    };
 }
 /**
  * PWA offline fallback page configuration
  */
-export declare interface PwaOfflineConfig {
-  enabled: boolean
-  page?: string
-  fallbackTitle?: string
-  fallbackMessage?: string
-  precacheAssets?: string[]
+export interface PwaOfflineConfig {
+    /** Enable offline support */
+    enabled: boolean;
+    /** Path to custom offline page (.stx file) */
+    page?: string;
+    /** Fallback title when offline */
+    fallbackTitle?: string;
+    /** Fallback message when offline */
+    fallbackMessage?: string;
+    /** Additional assets to precache for offline access */
+    precacheAssets?: string[];
 }
 /**
  * Service worker configuration
  */
-export declare interface PwaServiceWorkerConfig {
-  fileName?: string
-  cacheVersion?: string
-  skipWaiting?: boolean
-  clientsClaim?: boolean
-  navigationPreload?: boolean
-  excludeRoutes?: string[]
-  cacheFileTypes?: string[]
-  useWorkbox?: boolean
+export interface PwaServiceWorkerConfig {
+    /** Service worker file name (default: 'sw.js') */
+    fileName?: string;
+    /** Cache version for cache busting */
+    cacheVersion?: string;
+    /** Skip waiting and activate immediately */
+    skipWaiting?: boolean;
+    /** Claim all clients immediately */
+    clientsClaim?: boolean;
+    /** Enable navigation preload */
+    navigationPreload?: boolean;
+    /** Routes to exclude from caching (glob patterns) */
+    excludeRoutes?: string[];
+    /** File types to cache (extensions without dot) */
+    cacheFileTypes?: string[];
+    /** Use Workbox library instead of custom SW (requires workbox-* packages) */
+    useWorkbox?: boolean;
 }
 /**
  * Push notification configuration
  */
-export declare interface PwaPushConfig {
-  enabled: boolean
-  vapidPublicKey?: string
-  subscriptionEndpoint?: string
-  defaultIcon?: string
-  defaultBadge?: string
-  defaultOptions?: {
-    vibrate?: number[]
-    requireInteraction?: boolean
-  }
+export interface PwaPushConfig {
+    /** Enable push notifications */
+    enabled: boolean;
+    /** VAPID public key for push subscriptions */
+    vapidPublicKey?: string;
+    /** Server endpoint for push subscription registration */
+    subscriptionEndpoint?: string;
+    /** Default notification icon path */
+    defaultIcon?: string;
+    /** Default notification badge path */
+    defaultBadge?: string;
+    /** Default notification options */
+    defaultOptions?: {
+        /** Enable vibration */
+        vibrate?: number[];
+        /** Require interaction to dismiss */
+        requireInteraction?: boolean;
+    };
 }
 /**
  * Background sync configuration
  */
-export declare interface PwaBackgroundSyncConfig {
-  enabled: boolean
-  queueName?: string
-  maxRetentionMinutes?: number
-  maxRetries?: number
-  minInterval?: number
-  forms?: string[]
-  endpoints?: string[]
+export interface PwaBackgroundSyncConfig {
+    /** Enable background sync */
+    enabled: boolean;
+    /** Queue name for sync operations */
+    queueName?: string;
+    /** Maximum retention time in minutes */
+    maxRetentionMinutes?: number;
+    /** Maximum retry attempts */
+    maxRetries?: number;
+    /** Minimum interval between retries in ms */
+    minInterval?: number;
+    /** Forms to enable background sync for (CSS selectors) */
+    forms?: string[];
+    /** API endpoints to queue when offline */
+    endpoints?: string[];
 }
 /**
  * Share target configuration for receiving shared content
  */
-export declare interface PwaShareTargetConfig {
-  enabled: boolean
-  action: string
-  method?: 'GET' | 'POST'
-  enctype?: 'application/x-www-form-urlencoded' | 'multipart/form-data'
-  params?: {
-    title?: string
-    text?: string
-    url?: string
-  }
-  acceptFiles?: Array<{
-    name: string
-    accept: string[]
-  }>
+export interface PwaShareTargetConfig {
+    /** Enable share target */
+    enabled: boolean;
+    /** Action URL to handle shared content */
+    action: string;
+    /** HTTP method for share action */
+    method?: 'GET' | 'POST';
+    /** Encoding type for POST */
+    enctype?: 'application/x-www-form-urlencoded' | 'multipart/form-data';
+    /** Parameter configuration */
+    params?: {
+        /** Parameter name for shared title */
+        title?: string;
+        /** Parameter name for shared text */
+        text?: string;
+        /** Parameter name for shared URL */
+        url?: string;
+    };
+    /** Accept file types for sharing */
+    acceptFiles?: Array<{
+        name: string;
+        accept: string[];
+    }>;
 }
 /**
  * File handler configuration for handling specific file types
  */
-export declare interface PwaFileHandlerConfig {
-  enabled: boolean
-  action?: string
-  accept?: Record<string, string[]>
-  launchType?: 'single-client' | 'multiple-clients'
-  icons?: Array<{ src: string, sizes: string, type: string }>
+export interface PwaFileHandlerConfig {
+    /** Enable file handling */
+    enabled: boolean;
+    /** Action URL to handle files */
+    action?: string;
+    /** Accepted MIME types and extensions (e.g., { 'text/markdown': ['.md'] }) */
+    accept?: Record<string, string[]>;
+    /** Launch type */
+    launchType?: 'single-client' | 'multiple-clients';
+    /** Icons for file handler */
+    icons?: Array<{
+        src: string;
+        sizes: string;
+        type: string;
+    }>;
 }
 /**
  * Protocol handler configuration
  */
-export declare interface PwaProtocolHandlerConfig {
-  protocol: string
-  url: string
+export interface PwaProtocolHandlerConfig {
+    /** Protocol scheme (e.g., 'web+myapp') */
+    protocol: string;
+    /** URL to handle the protocol */
+    url: string;
 }
 /**
  * Cache storage limits configuration
  */
-export declare interface PwaCacheStorageConfig {
-  maxSize?: number
-  maxEntries?: number
-  maxAge?: number
-  purgeStrategy?: 'lru' | 'fifo' | 'lfu'
+export interface PwaCacheStorageConfig {
+    /** Maximum cache size in MB */
+    maxSize?: number;
+    /** Maximum number of cached entries */
+    maxEntries?: number;
+    /** Maximum age of cached items in days */
+    maxAge?: number;
+    /** Purge strategy when limits exceeded */
+    purgeStrategy?: 'lru' | 'fifo' | 'lfu';
 }
 /**
  * Update notification configuration
  */
-export declare interface PwaUpdateConfig {
-  enabled: boolean
-  promptUser?: boolean
-  autoReload?: boolean
-  message?: string
-  uiSelector?: string
+export interface PwaUpdateConfig {
+    /** Enable update notifications */
+    enabled: boolean;
+    /** Show prompt when update available */
+    promptUser?: boolean;
+    /** Auto-reload after update */
+    autoReload?: boolean;
+    /** Custom update notification message */
+    message?: string;
+    /** Selector for custom update UI element */
+    uiSelector?: string;
 }
 /**
  * Auto-precaching configuration
  */
-export declare interface PwaPrecacheConfig {
-  enabled: boolean
-  includeHtml?: boolean
-  includeJs?: boolean
-  includeCss?: boolean
-  includeImages?: boolean
-  includeFonts?: boolean
-  include?: string[]
-  exclude?: string[]
-  maxFileSizeKB?: number
+export interface PwaPrecacheConfig {
+    /** Enable auto-precaching of build output */
+    enabled: boolean;
+    /** Include HTML files */
+    includeHtml?: boolean;
+    /** Include JS files */
+    includeJs?: boolean;
+    /** Include CSS files */
+    includeCss?: boolean;
+    /** Include images */
+    includeImages?: boolean;
+    /** Include fonts */
+    includeFonts?: boolean;
+    /** Additional glob patterns to include */
+    include?: string[];
+    /** Glob patterns to exclude */
+    exclude?: string[];
+    /** Maximum file size to precache (in KB) */
+    maxFileSizeKB?: number;
 }
 /**
  * Complete PWA configuration
  */
-export declare interface PwaConfig {
-  enabled: boolean
-  manifest: PwaManifestConfig
-  icons?: PwaIconConfig
-  routes?: PwaRouteCache[]
-  offline?: PwaOfflineConfig
-  serviceWorker?: PwaServiceWorkerConfig
-  autoInject?: boolean
-  push?: PwaPushConfig
-  backgroundSync?: PwaBackgroundSyncConfig
-  shareTarget?: PwaShareTargetConfig
-  fileHandlers?: PwaFileHandlerConfig
-  protocolHandlers?: PwaProtocolHandlerConfig[]
-  cacheStorage?: PwaCacheStorageConfig
-  updates?: PwaUpdateConfig
-  precache?: PwaPrecacheConfig
+export interface PwaConfig {
+    /** Enable PWA features */
+    enabled: boolean;
+    /** Web App Manifest configuration */
+    manifest: PwaManifestConfig;
+    /** Icon generation configuration */
+    icons?: PwaIconConfig;
+    /** Route-based caching strategies */
+    routes?: PwaRouteCache[];
+    /** Offline fallback configuration */
+    offline?: PwaOfflineConfig;
+    /** Service worker configuration */
+    serviceWorker?: PwaServiceWorkerConfig;
+    /** Auto-inject PWA meta tags and service worker registration */
+    autoInject?: boolean;
+    /** Push notification configuration */
+    push?: PwaPushConfig;
+    /** Background sync configuration */
+    backgroundSync?: PwaBackgroundSyncConfig;
+    /** Share target configuration */
+    shareTarget?: PwaShareTargetConfig;
+    /** File handler configuration */
+    fileHandlers?: PwaFileHandlerConfig;
+    /** Protocol handlers */
+    protocolHandlers?: PwaProtocolHandlerConfig[];
+    /** Cache storage limits */
+    cacheStorage?: PwaCacheStorageConfig;
+    /** Update notification configuration */
+    updates?: PwaUpdateConfig;
+    /** Auto-precaching configuration */
+    precache?: PwaPrecacheConfig;
 }
-/**
- * Progressive Web App (PWA) Types
- */
-/**
- * PWA caching strategy for service worker routes
- */
-export type PwaCacheStrategy = 'cache-first' | 'network-first' | 'stale-while-revalidate' | 'network-only' | 'cache-only';

package/dist/types.d.ts

@@ -24,5 +24,4 @@
  * import type { StxConfig, ConditionalDirective } from './types'
  * ```
  */
-// Re-export everything from the modular types
 export * from './types/index';

package/dist/typescript-templates.d.ts

@@ -35,6 +35,17 @@ export declare function inferTypeFromValue(value: unknown): TSType;
 /**
  * Type-check an expression against the type context.
  *
+ * Superseded for `.stx` files by `stx typecheck`, which hands template
+ * expressions to the real compiler (`stx-virtual-ts.ts` builds the buffer,
+ * `typecheck.ts` runs it). #1852 asked for this function to be exported and
+ * given a real checker; it got the real checker instead, and deliberately did
+ * NOT get exported — two template checkers that disagree is the failure mode
+ * this repo keeps hitting.
+ *
+ * This walk only understands a bare identifier and a dotted member chain, and
+ * returns `any` for everything else. Reach for it only where a full compiler
+ * pass is not available.
+ *
  * @returns The inferred type of the expression, or an error
  */
 export declare function typeCheckExpression(expression: string, context: TemplateTypeContext): TSType | TypeCheckError;

package/dist/unresolved-identifiers.d.ts

@@ -1,22 +1,3 @@
-/**
- * Find identifiers a script CALLS that resolve to nothing in the browser.
- *
- * Restricted to names we can name a cause for — exports of `composables/` with
- * no runtime counterpart. A broader "looks like a hook and is not in scope"
- * heuristic would fire on legitimate local helpers and app composables, and a
- * warning people learn to ignore is worse than no warning.
- *
- * @param source the script body, after imports have been transformed
- * @param provided names already in scope (runtime globals, locals, imports)
- */
-export declare function findUnresolvedIdentifiers(source: string, provided: Iterable<string>): UnresolvedIdentifier[];
-/**
- * Report unresolved identifiers against a file, once each.
- *
- * Returns the diagnostics so callers can assert on them without capturing
- * console output.
- */
-export declare function reportUnresolvedIdentifiers(source: string, provided: Iterable<string>, filePath: string): UnresolvedIdentifier[];
 /**
  * Diagnose an identifier a client script calls that will not exist in the browser.
  *
@@ -44,7 +25,28 @@ export declare function reportUnresolvedIdentifiers(source: string, provided: It
  * the auto-import list did (#1804).
  */
 export declare const SERVER_ONLY_COMPOSABLES: readonly string[];
-export declare interface UnresolvedIdentifier {
-  name: string
-  message: string
+export interface UnresolvedIdentifier {
+    /** The identifier as written. */
+    name: string;
+    /** Human-readable explanation, including the fix. */
+    message: string;
 }
+/**
+ * Find identifiers a script CALLS that resolve to nothing in the browser.
+ *
+ * Restricted to names we can name a cause for — exports of `composables/` with
+ * no runtime counterpart. A broader "looks like a hook and is not in scope"
+ * heuristic would fire on legitimate local helpers and app composables, and a
+ * warning people learn to ignore is worse than no warning.
+ *
+ * @param source the script body, after imports have been transformed
+ * @param provided names already in scope (runtime globals, locals, imports)
+ */
+export declare function findUnresolvedIdentifiers(source: string, provided: Iterable<string>): UnresolvedIdentifier[];
+/**
+ * Report unresolved identifiers against a file, once each.
+ *
+ * Returns the diagnostics so callers can assert on them without capturing
+ * console output.
+ */
+export declare function reportUnresolvedIdentifiers(source: string, provided: Iterable<string>, filePath: string): UnresolvedIdentifier[];

package/dist/unresolved-identifiers.js

@@ -7,6 +7,7 @@ export const SERVER_ONLY_COMPOSABLES = [
   "clearStorage",
   "copyToClipboard",
   "createShareableFile",
+  "defineForm",
   "getBatteryLevel",
   "getCookie",
   "getCurrentPosition",
@@ -75,6 +76,7 @@ export const SERVER_ONLY_COMPOSABLES = [
   "useEventSource",
   "useEyeDropper",
   "useFavicon",
+  "useForm",
   "useFullscreen",
   "useGeolocation",
   "useGeolocationWatch",

package/dist/utils.d.ts

@@ -1,8 +1,18 @@
+/**
+ * Utility functions for the stx compiler
+ *
+ * This module provides core utilities for template processing.
+ * Some functionality has been extracted to dedicated modules:
+ *
+ * - validator.ts - Template validation utilities
+ * - variable-extractor.ts - Script variable extraction
+ *
+ * @module utils
+ */
 import type { StxOptions } from './types';
-export type {
-  TemplateValidationError,
-  TemplateValidationResult,
-} from './validator';
+export { extractDirectiveNames, getPositionInfo, hasDirectives, validateDirective, validateTemplate, } from './validator';
+export type { TemplateValidationError, TemplateValidationResult, } from './validator';
+export { convertToCommonJS, extractScriptFromTemplate, extractVariables, hasVariables, } from './variable-extractor';
 /**
  * Check if script should be treated as plain JavaScript (opt-out from TypeScript)
  * By default ALL scripts are TypeScript. Use <script js> or <script lang="js"> to opt-out.
@@ -54,7 +64,7 @@ export declare function slotContentHasExpressions(slotContent: string): boolean;
  * named `title` also exists in the server context.
  */
 export declare function componentClientSignalNames(scripts: string[]): string[];
-export declare function renderComponentWithSlot(componentPath: string, props: Record<string, unknown>, slotContent: string, componentsDir: string, parentContext: Record<string, unknown>, parentFilePath: string, options: StxOptions, processedComponents?: Set<string> | undefined, dependencies: Set<string>): Promise<string>;
+export declare function renderComponentWithSlot(componentPath: string, props: Record<string, unknown>, slotContent: string, componentsDir: string, parentContext: Record<string, unknown>, parentFilePath: string, options: StxOptions, processedComponents: Set<string> | undefined, dependencies: Set<string>): Promise<string>;
 /**
  * Check if a file exists
  */
@@ -71,7 +81,11 @@ export declare function resolveTemplatePath(templatePath: string, currentFilePat
  * @param errorPattern The pattern to locate in the template (fallback if position not available)
  * @returns Line number and context information
  */
-export declare function getSourceLineInfo(template: string, errorPosition?: number, errorPattern?: string): { lineNumber: number, lineContent: string, context: string };
+export declare function getSourceLineInfo(template: string, errorPosition?: number, errorPattern?: string): {
+    lineNumber: number;
+    lineContent: string;
+    context: string;
+};
 /**
  * Create a descriptive error message with line information
  * @param errorType Type of error (e.g., "Expression", "Directive")
@@ -91,18 +105,7 @@ export declare function clearComponentCache(): void;
 /**
  * Get component cache statistics
  */
-export declare function getComponentCacheStats(): { size: number, maxSize: number };
-// Re-export from extracted modules for backward compatibility
-export {
-  extractDirectiveNames,
-  getPositionInfo,
-  hasDirectives,
-  validateDirective,
-  validateTemplate,
-} from './validator';
-export {
-  convertToCommonJS,
-  extractScriptFromTemplate,
-  extractVariables,
-  hasVariables,
-} from './variable-extractor';
+export declare function getComponentCacheStats(): {
+    size: number;
+    maxSize: number;
+};