@ohos-ports/stacksjs-stx 0.2.287-beta.0

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

@@ -0,0 +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 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 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 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 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 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 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 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 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 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 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 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 interface PwaProtocolHandlerConfig {
+    /** Protocol scheme (e.g., 'web+myapp') */
+    protocol: string;
+    /** URL to handle the protocol */
+    url: string;
+}
+/**
+ * Cache storage limits configuration
+ */
+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 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 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 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;
+}

package/dist/types.d.ts

@@ -0,0 +1,27 @@
+/**
+ * stx Types
+ *
+ * This file re-exports all types from the modular types directory.
+ * The types have been split into domain-specific files for better organization:
+ *
+ * - types/context-types.ts - Template context and authentication types
+ * - types/directive-types.ts - All directive types (discriminated unions)
+ * - types/component-types.ts - Component system and documentation types
+ * - types/config-types.ts - Configuration types for stx options
+ * - types/pwa-types.ts - Progressive Web App configuration types
+ * - types/csp-types.ts - Content Security Policy types
+ *
+ * For new code, prefer importing from specific type files:
+ * @example
+ * ```typescript
+ * import type { StxConfig } from './types/config-types'
+ * import type { ConditionalDirective } from './types/directive-types'
+ * ```
+ *
+ * For backward compatibility, you can still import from this file:
+ * @example
+ * ```typescript
+ * import type { StxConfig, ConditionalDirective } from './types'
+ * ```
+ */
+export * from './types/index';

package/dist/types.js

@@ -0,0 +1 @@
+export * from "./types/index.js";

package/dist/typescript-templates.d.ts

@@ -0,0 +1,156 @@
+/**
+ * Parse a TypeScript type annotation string into a TSType structure.
+ *
+ * @example
+ * parseTypeAnnotation('string') // { kind: 'primitive', value: 'string' }
+ * parseTypeAnnotation('string[]') // { kind: 'array', elementType: { kind: 'primitive', value: 'string' } }
+ * parseTypeAnnotation('{ name: string }') // { kind: 'object', properties: { name: { type: ..., optional: false } } }
+ */
+export declare function parseTypeAnnotation(typeStr: string): TSType;
+/**
+ * Extract type definitions from a template's @types block.
+ *
+ * @example
+ * ```typescript
+ * const result = extractTypesFromTemplate(`
+ *   @types
+ *   interface PageContext {
+ *     title: string
+ *   }
+ *   @endtypes
+ *   <h1>{{ title }}</h1>
+ * `)
+ * // result.interfaces[0].name === 'PageContext'
+ * ```
+ */
+export declare function extractTypesFromTemplate(template: string): TypeExtractionResult;
+/**
+ * Create a type context from extracted types and runtime context.
+ */
+export declare function createTypeContext(extracted: TypeExtractionResult, runtimeContext?: Record<string, unknown>): TemplateTypeContext;
+/**
+ * Infer a TSType from a runtime value.
+ */
+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;
+/**
+ * Validate all expressions in a template.
+ */
+export declare function validateTemplateTypes(template: string, context: TemplateTypeContext): TypeCheckError[];
+/**
+ * Generate TypeScript definition file for a template.
+ *
+ * This creates a .d.ts file that provides type information for IDE support.
+ */
+export declare function generateTypeDefinitions(templatePath: string, extracted: TypeExtractionResult): GeneratedTypes;
+/**
+ * Convert a TSType back to a TypeScript string representation.
+ */
+export declare function typeToString(type: TSType): string;
+/**
+ * Process @types directive - extracts and removes type definitions.
+ */
+export declare function processTypesDirective(template: string): {
+  template: string
+  types: TypeExtractionResult
+};
+/**
+ * Compile-time type check a template.
+ *
+ * @returns Array of errors/warnings, empty if valid
+ */
+export declare function compileTimeTypeCheck(template: string, runtimeContext?: Record<string, unknown>): { errors: TypeCheckError[], warnings: TypeCheckWarning[] };
+/** TypeScript type representation */
+export declare interface TSType {
+  kind: 'primitive' | 'array' | 'object' | 'union' | 'intersection' | 'literal' | 'function' | 'generic' | 'reference'
+  value?: TSPrimitiveType | string
+  elementType?: TSType
+  properties?: Record<string, TSTypeProperty>
+  types?: TSType[]
+  literalValue?: string | number | boolean
+  parameters?: TSFunctionParam[]
+  returnType?: TSType
+  typeArguments?: TSType[]
+  optional?: boolean
+}
+/** Object property with type */
+export declare interface TSTypeProperty {
+  type: TSType
+  optional: boolean
+  readonly: boolean
+  description?: string
+}
+/** Function parameter */
+export declare interface TSFunctionParam {
+  name: string
+  type: TSType
+  optional: boolean
+  rest: boolean
+}
+/** Interface definition */
+export declare interface TSInterface {
+  name: string
+  properties: Record<string, TSTypeProperty>
+  extends?: string[]
+  description?: string
+}
+/** Type alias definition */
+export declare interface TSTypeAlias {
+  name: string
+  type: TSType
+  description?: string
+}
+/** Template type context */
+export declare interface TemplateTypeContext {
+  interfaces: Map<string, TSInterface>
+  typeAliases: Map<string, TSTypeAlias>
+  variables: Map<string, TSType>
+  errors: TypeCheckError[]
+  warnings: TypeCheckWarning[]
+}
+/** Type check error */
+export declare interface TypeCheckError {
+  message: string
+  line?: number
+  column?: number
+  expression?: string
+  expectedType?: string
+  actualType?: string
+}
+/** Type check warning */
+export declare interface TypeCheckWarning {
+  message: string
+  line?: number
+  column?: number
+  suggestion?: string
+}
+/** Type extraction result */
+export declare interface TypeExtractionResult {
+  interfaces: TSInterface[]
+  typeAliases: TSTypeAlias[]
+  contextType?: TSInterface
+  errors: string[]
+}
+/** Generated type definition file content */
+export declare interface GeneratedTypes {
+  content: string
+  filename: string
+}
+/** Supported TypeScript primitive types */
+export type TSPrimitiveType = 'string' | 'number' | 'boolean' | 'null' | 'undefined' | 'any' | 'unknown' | 'never' | 'void';