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

package/dist/props.js

@@ -0,0 +1,224 @@
+function getTypeName(type) {
+  if (type === String)
+    return "string";
+  if (type === Number)
+    return "number";
+  if (type === Boolean)
+    return "boolean";
+  if (type === Array)
+    return "array";
+  if (type === Object)
+    return "object";
+  if (type === Function)
+    return "function";
+  if (type === Date)
+    return "date";
+  if (type === Symbol)
+    return "symbol";
+  if (typeof type === "function" && type.name)
+    return type.name;
+  return "unknown";
+}
+function checkType(value, type) {
+  if (value === null || value === void 0)
+    return !0;
+  if (type === String)
+    return typeof value === "string";
+  if (type === Number)
+    return typeof value === "number" && !Number.isNaN(value);
+  if (type === Boolean)
+    return typeof value === "boolean";
+  if (type === Array)
+    return Array.isArray(value);
+  if (type === Object)
+    return typeof value === "object" && !Array.isArray(value);
+  if (type === Function)
+    return typeof value === "function";
+  if (type === Date)
+    return value instanceof Date;
+  if (type === Symbol)
+    return typeof value === "symbol";
+  if (typeof type === "function")
+    return value instanceof type;
+  return !0;
+}
+function validateProp(name, value, options, componentName) {
+  const prefix = componentName ? `[${componentName}]` : "";
+  if (options.required && (value === void 0 || value === null))
+    return {
+      prop: name,
+      message: `${prefix} Missing required prop: "${name}"`,
+      value,
+      expected: options.type ? getTypeName(options.type) : void 0
+    };
+  if (value === void 0 || value === null)
+    return null;
+  if (options.type) {
+    const types = Array.isArray(options.type) ? options.type : [options.type];
+    if (!types.some((t) => checkType(value, t))) {
+      const expectedTypes = types.map((t) => getTypeName(t)).join(" | ");
+      return {
+        prop: name,
+        message: `${prefix} Invalid prop type for "${name}": expected ${expectedTypes}, got ${typeof value}`,
+        value,
+        expected: expectedTypes
+      };
+    }
+  }
+  if (options.validator) {
+    if (!options.validator(value))
+      return {
+        prop: name,
+        message: `${prefix} Custom validation failed for prop "${name}"`,
+        value
+      };
+  }
+  return null;
+}
+export function defineProps(definitions) {
+  const props = globalThis.__STX_CURRENT_PROPS__ || {};
+  if (!definitions)
+    return props;
+  const result = { ...props };
+  for (const [key, def] of Object.entries(definitions)) {
+    const options = typeof def === "function" || Array.isArray(def) ? { type: def } : def || {};
+    if (result[key] === void 0 && options.default !== void 0)
+      result[key] = typeof options.default === "function" ? options.default() : options.default;
+  }
+  return result;
+}
+export function definePropsWithValidation(definitions, options = {}) {
+  const {
+    componentName,
+    throwOnError = !1,
+    logWarnings = !0
+  } = options, rawProps = globalThis.__STX_CURRENT_PROPS__ || {}, result = { ...rawProps }, validation = {
+    valid: !0,
+    errors: [],
+    warnings: []
+  };
+  for (const [key, def] of Object.entries(definitions)) {
+    const propOptions = typeof def === "function" || Array.isArray(def) ? { type: def } : def || {};
+    if (result[key] === void 0 && propOptions.default !== void 0)
+      result[key] = typeof propOptions.default === "function" ? propOptions.default() : propOptions.default;
+    const error = validateProp(key, result[key], propOptions, componentName);
+    if (error) {
+      validation.valid = !1;
+      validation.errors.push(error);
+      if (logWarnings)
+        console.warn(error.message);
+    }
+  }
+  for (const key of Object.keys(rawProps))
+    if (!(key in definitions)) {
+      const warning = `${componentName ? `[${componentName}]` : ""} Unknown prop: "${key}"`;
+      validation.warnings.push(warning);
+      if (logWarnings)
+        console.warn(warning);
+    }
+  if (throwOnError && !validation.valid) {
+    const errorMessages = validation.errors.map((e) => e.message).join(`
+`);
+    throw Error(`Prop validation failed:
+${errorMessages}`);
+  }
+  return {
+    props: result,
+    validation
+  };
+}
+export function withDefaults(props, defaults) {
+  const result = { ...props };
+  for (const [key, defaultValue] of Object.entries(defaults))
+    if (result[key] === void 0)
+      result[key] = typeof defaultValue === "function" ? defaultValue() : defaultValue;
+  return result;
+}
+export function prop(options) {
+  return options;
+}
+export function required(type) {
+  return { type, required: !0 };
+}
+export function optional(defaultValue, type) {
+  return { type, default: defaultValue };
+}
+export function validated(validator, options = {}) {
+  return { ...options, validator };
+}
+export function oneOf(values, options = {}) {
+  return {
+    ...options,
+    validator: (value) => values.includes(value)
+  };
+}
+export function arrayOf(_itemType, options = {}) {
+  return {
+    ...options,
+    type: Array,
+    validator: (value) => {
+      if (!Array.isArray(value))
+        return !1;
+      return !0;
+    }
+  };
+}
+export function shape(_shape, options = {}) {
+  return {
+    ...options,
+    type: Object
+  };
+}
+export function processComponentProps(rawProps, definitions, componentName) {
+  if (!definitions)
+    return rawProps;
+  const result = {};
+  for (const [key, def] of Object.entries(definitions)) {
+    const options = typeof def === "function" || Array.isArray(def) ? { type: def } : def || {};
+    let value = rawProps[key];
+    if (value === void 0 && options.default !== void 0)
+      value = typeof options.default === "function" ? options.default() : options.default;
+    {
+      const error = validateProp(key, value, options, componentName);
+      if (error)
+        console.warn(error.message);
+    }
+    result[key] = value;
+  }
+  for (const [key, value] of Object.entries(rawProps))
+    if (!(key in result))
+      result[key] = value;
+  return result;
+}
+export function defineEmits() {
+  const element = globalThis.__STX_CURRENT_ELEMENT__;
+  return (event, payload) => {
+    if (element) {
+      const customEvent = new CustomEvent(String(event), {
+        detail: payload,
+        bubbles: !0,
+        cancelable: !0
+      });
+      element.dispatchEvent(customEvent);
+    } else
+      console.warn(`Cannot emit event "${String(event)}" - no element context`);
+  };
+}
+export function defineExpose(exposed) {
+  const element = globalThis.__STX_CURRENT_ELEMENT__;
+  if (element) {
+    element.__stx_exposed__ = exposed;
+    element.setAttribute("data-stx-exposed", Object.keys(exposed).join(","));
+  }
+}
+export function generatePropsInterface(componentName, definitions) {
+  const lines = [`interface ${componentName}Props {`];
+  for (const [key, def] of Object.entries(definitions)) {
+    const options = typeof def === "function" || Array.isArray(def) ? { type: def } : def || {}, typeName = options.type ? getTypeName(options.type) : "unknown", optional = options.required ? "" : "?", description = options.description ? `  /** ${options.description} */
+` : "";
+    lines.push(`${description}  ${key}${optional}: ${typeName}`);
+  }
+  lines.push("}");
+  return lines.join(`
+`);
+}

package/dist/public-env.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Public env exposure for client bundles
+ *
+ * Mirrors the server-side `$env` template context (process.ts:762) onto the
+ * client side via build-time substitution. Any env var matching `envPrefix`
+ * (default `STX_PUBLIC_`) gets inlined as `import.meta.env.STX_PUBLIC_*` in
+ * scripts bundled for the browser.
+ *
+ *   .env:    STX_PUBLIC_API_URL=https://api.example.com
+ *   store:   const api = import.meta.env.STX_PUBLIC_API_URL
+ *   built:   const api = "https://api.example.com"
+ *
+ * Vite-style. Build-time, zero runtime cost.
+ */
+/**
+ * Build the `define` map every client bundler/transpiler should pass to
+ * Bun.build / new Bun.Transpiler({ define }).
+ *
+ * Returns substitutions for both `import.meta.env.<KEY>` (preferred, Vite-
+ * compatible) and a single `import.meta.env` literal that maps to the full
+ * object so consumers can do `if (import.meta.env.X)` and similar idiomatic
+ * patterns.
+ */
+export declare function getPublicEnvDefine(envPrefix?: string): Record<string, string>;
+/**
+ * Get the public env values as a plain object. Useful for places that want
+ * the raw map (e.g. tests, debugging) rather than the define-shaped strings.
+ */
+export declare function getPublicEnv(envPrefix?: string): Record<string, string>;

package/dist/public-env.js

@@ -0,0 +1,19 @@
+import process from "node:process";
+export function getPublicEnvDefine(envPrefix = "STX_PUBLIC_") {
+  const define = {}, envObject = {};
+  for (const [key, value] of Object.entries(process.env)) {
+    if (!key.startsWith(envPrefix) || value === void 0)
+      continue;
+    define[`import.meta.env.${key}`] = JSON.stringify(value);
+    envObject[key] = value;
+  }
+  define["import.meta.env"] = JSON.stringify(envObject);
+  return define;
+}
+export function getPublicEnv(envPrefix = "STX_PUBLIC_") {
+  const out = {};
+  for (const [key, value] of Object.entries(process.env))
+    if (key.startsWith(envPrefix) && value !== void 0)
+      out[key] = value;
+  return out;
+}

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/audit.js

@@ -0,0 +1,255 @@
+import fs from "node:fs";
+import path from "node:path";
+export function auditConfig(options) {
+  const checks = [], pwa = options.pwa;
+  checks.push({
+    id: "pwa-enabled",
+    name: "PWA Enabled",
+    category: "required",
+    passed: pwa?.enabled === !0,
+    message: pwa?.enabled ? "PWA is enabled" : "PWA is not enabled in config"
+  });
+  if (!pwa?.enabled)
+    return checks;
+  checks.push({
+    id: "manifest-name",
+    name: "App Name",
+    category: "required",
+    passed: Boolean(pwa.manifest?.name),
+    message: pwa.manifest?.name ? `App name: "${pwa.manifest.name}"` : "Missing required manifest name"
+  });
+  checks.push({
+    id: "manifest-short-name",
+    name: "Short Name",
+    category: "recommended",
+    passed: Boolean(pwa.manifest?.shortName),
+    message: pwa.manifest?.shortName ? `Short name: "${pwa.manifest.shortName}"` : "Short name not set (will use full name)"
+  });
+  checks.push({
+    id: "manifest-description",
+    name: "App Description",
+    category: "recommended",
+    passed: Boolean(pwa.manifest?.description),
+    message: pwa.manifest?.description ? "Description is set" : "App description not provided"
+  });
+  checks.push({
+    id: "manifest-theme-color",
+    name: "Theme Color",
+    category: "required",
+    passed: Boolean(pwa.manifest?.themeColor),
+    message: pwa.manifest?.themeColor ? `Theme color: ${pwa.manifest.themeColor}` : "Theme color not set"
+  });
+  checks.push({
+    id: "manifest-background-color",
+    name: "Background Color",
+    category: "required",
+    passed: Boolean(pwa.manifest?.backgroundColor),
+    message: pwa.manifest?.backgroundColor ? `Background color: ${pwa.manifest.backgroundColor}` : "Background color not set"
+  });
+  checks.push({
+    id: "manifest-display",
+    name: "Display Mode",
+    category: "required",
+    passed: ["standalone", "fullscreen", "minimal-ui"].includes(pwa.manifest?.display || ""),
+    message: pwa.manifest?.display ? `Display mode: ${pwa.manifest.display}` : "Display mode should be standalone, fullscreen, or minimal-ui"
+  });
+  checks.push({
+    id: "manifest-start-url",
+    name: "Start URL",
+    category: "required",
+    passed: Boolean(pwa.manifest?.startUrl),
+    message: pwa.manifest?.startUrl ? `Start URL: ${pwa.manifest.startUrl}` : "Start URL not set"
+  });
+  checks.push({
+    id: "icons-source",
+    name: "Icon Source",
+    category: "required",
+    passed: Boolean(pwa.icons?.src),
+    message: pwa.icons?.src ? `Icon source: ${pwa.icons.src}` : "No icon source configured"
+  });
+  const iconSizes = pwa.icons?.sizes || [];
+  checks.push({
+    id: "icons-192",
+    name: "192x192 Icon",
+    category: "required",
+    passed: iconSizes.includes(192),
+    message: iconSizes.includes(192) ? "192x192 icon will be generated" : "Missing 192x192 icon (required for Android)"
+  });
+  checks.push({
+    id: "icons-512",
+    name: "512x512 Icon",
+    category: "required",
+    passed: iconSizes.includes(512),
+    message: iconSizes.includes(512) ? "512x512 icon will be generated" : "Missing 512x512 icon (required for splash screen)"
+  });
+  checks.push({
+    id: "icons-maskable",
+    name: "Maskable Icon",
+    category: "recommended",
+    passed: pwa.icons?.purpose?.includes("maskable") || !1,
+    message: pwa.icons?.purpose?.includes("maskable") ? "Maskable icon purpose is set" : "Consider adding maskable icon purpose for adaptive icons"
+  });
+  checks.push({
+    id: "sw-configured",
+    name: "Service Worker",
+    category: "required",
+    passed: Boolean(pwa.serviceWorker),
+    message: pwa.serviceWorker ? "Service worker is configured" : "Service worker configuration missing"
+  });
+  checks.push({
+    id: "sw-cache-version",
+    name: "Cache Version",
+    category: "recommended",
+    passed: Boolean(pwa.serviceWorker?.cacheVersion),
+    message: pwa.serviceWorker?.cacheVersion ? `Cache version: ${pwa.serviceWorker.cacheVersion}` : "Set cache version for proper cache busting"
+  });
+  checks.push({
+    id: "offline-enabled",
+    name: "Offline Support",
+    category: "required",
+    passed: pwa.offline?.enabled === !0,
+    message: pwa.offline?.enabled ? "Offline support is enabled" : "Offline support is disabled"
+  });
+  const routes = pwa.routes || [];
+  checks.push({
+    id: "caching-strategies",
+    name: "Caching Strategies",
+    category: "recommended",
+    passed: routes.length > 0,
+    message: routes.length > 0 ? `${routes.length} route caching strategies configured` : "No custom caching strategies defined"
+  });
+  checks.push({
+    id: "push-config",
+    name: "Push Notifications",
+    category: "optional",
+    passed: !pwa.push?.enabled || Boolean(pwa.push?.vapidPublicKey),
+    message: pwa.push?.enabled ? pwa.push?.vapidPublicKey ? "Push notifications configured with VAPID key" : "Push enabled but missing VAPID key" : "Push notifications not enabled"
+  });
+  checks.push({
+    id: "share-target",
+    name: "Share Target",
+    category: "optional",
+    passed: !0,
+    message: pwa.shareTarget?.enabled ? `Share target enabled at ${pwa.shareTarget.action}` : "Share target not enabled"
+  });
+  checks.push({
+    id: "auto-inject",
+    name: "Auto-injection",
+    category: "recommended",
+    passed: pwa.autoInject !== !1,
+    message: pwa.autoInject !== !1 ? "PWA tags will be auto-injected" : "Auto-injection disabled - manual tag insertion required"
+  });
+  return checks;
+}
+export function auditBuildOutput(outputDir) {
+  const checks = [], manifestPath = path.join(outputDir, "manifest.json"), manifestExists = fs.existsSync(manifestPath);
+  checks.push({
+    id: "build-manifest",
+    name: "Manifest File",
+    category: "required",
+    passed: manifestExists,
+    message: manifestExists ? "manifest.json exists" : "manifest.json not found in build output"
+  });
+  if (manifestExists)
+    try {
+      const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf-8"));
+      checks.push({
+        id: "build-manifest-valid",
+        name: "Valid Manifest JSON",
+        category: "required",
+        passed: !0,
+        message: "Manifest is valid JSON"
+      });
+      checks.push({
+        id: "build-manifest-icons",
+        name: "Manifest Icons",
+        category: "required",
+        passed: Array.isArray(manifest.icons) && manifest.icons.length > 0,
+        message: manifest.icons?.length ? `${manifest.icons.length} icons defined in manifest` : "No icons defined in manifest"
+      });
+    } catch {
+      checks.push({
+        id: "build-manifest-valid",
+        name: "Valid Manifest JSON",
+        category: "required",
+        passed: !1,
+        message: "Manifest is not valid JSON"
+      });
+    }
+  const swPath = path.join(outputDir, "sw.js"), swExists = fs.existsSync(swPath);
+  checks.push({
+    id: "build-sw",
+    name: "Service Worker File",
+    category: "required",
+    passed: swExists,
+    message: swExists ? "Service worker (sw.js) exists" : "Service worker not found in build output"
+  });
+  const offlinePath = path.join(outputDir, "offline.html"), offlineExists = fs.existsSync(offlinePath);
+  checks.push({
+    id: "build-offline",
+    name: "Offline Page",
+    category: "recommended",
+    passed: offlineExists,
+    message: offlineExists ? "Offline page exists" : "No offline.html found"
+  });
+  const iconsDir = path.join(outputDir, "pwa-icons");
+  if (fs.existsSync(iconsDir)) {
+    const iconFiles = fs.readdirSync(iconsDir).filter((f) => f.endsWith(".png") || f.endsWith(".webp"));
+    checks.push({
+      id: "build-icons",
+      name: "Generated Icons",
+      category: "required",
+      passed: iconFiles.length > 0,
+      message: iconFiles.length > 0 ? `${iconFiles.length} icon files generated` : "No icon files found"
+    });
+  } else
+    checks.push({
+      id: "build-icons",
+      name: "Generated Icons",
+      category: "required",
+      passed: !1,
+      message: "Icons directory not found"
+    });
+  return checks;
+}
+export function calculateAuditResult(checks) {
+  const requiredChecks = checks.filter((c) => c.category === "required"), recommendedChecks = checks.filter((c) => c.category === "recommended"), requiredPassed = requiredChecks.filter((c) => c.passed).length, recommendedPassed = recommendedChecks.filter((c) => c.passed).length, requiredScore = requiredChecks.length > 0 ? requiredPassed / requiredChecks.length * 70 : 70, recommendedScore = recommendedChecks.length > 0 ? recommendedPassed / recommendedChecks.length * 30 : 30;
+  return {
+    score: Math.round(requiredScore + recommendedScore),
+    passed: checks.filter((c) => c.passed).length,
+    failed: checks.filter((c) => !c.passed && c.category === "required").length,
+    warnings: checks.filter((c) => !c.passed && c.category !== "required").length,
+    checks
+  };
+}
+export function runPwaAudit(options, outputDir) {
+  const configChecks = auditConfig(options), buildChecks = outputDir && fs.existsSync(outputDir) ? auditBuildOutput(outputDir) : [];
+  return calculateAuditResult([...configChecks, ...buildChecks]);
+}
+export function formatAuditResult(result) {
+  const lines = [];
+  lines.push(`
+=== PWA Audit Report ===
+`);
+  const scoreColor = result.score >= 90 ? "32" : result.score >= 70 ? "33" : "31";
+  lines.push(`Score: \x1B[${scoreColor}m${result.score}/100\x1B[0m`);
+  lines.push(`Passed: ${result.passed} | Failed: ${result.failed} | Warnings: ${result.warnings}
+`);
+  const categories = ["required", "recommended", "optional"];
+  for (const category of categories) {
+    const categoryChecks = result.checks.filter((c) => c.category === category);
+    if (categoryChecks.length === 0)
+      continue;
+    lines.push(`
+${category.toUpperCase()}:`);
+    for (const check of categoryChecks) {
+      const icon = check.passed ? "\x1B[32m\u2713\x1B[0m" : "\x1B[31m\u2717\x1B[0m";
+      lines.push(`  ${icon} ${check.name}: ${check.message}`);
+      if (check.details)
+        lines.push(`      ${check.details}`);
+    }
+  }
+  lines.push("");
+  return lines.join(`
+`);
+}

package/dist/pwa/directives.d.ts

@@ -0,0 +1,38 @@
+/**
+ * PWA Template Directives
+ *
+ * Provides template directives for PWA functionality:
+ * - @pwa.installButton - Install prompt button
+ * - @pwa.updatePrompt - Update notification UI
+ * - @pwa.offlineIndicator - Offline status indicator
+ * - @pwa.pushSubscribe - Push notification subscription button
+ */
+import type { CustomDirective } from '../types';
+/**
+ * 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[];
+/**
+ * Register all PWA directives with the config
+ */
+export declare function registerPwaDirectives(customDirectives: CustomDirective[]): CustomDirective[];