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

package/dist/menubar.d.ts

@@ -0,0 +1,65 @@
+/// <reference path="./stx.d.ts" />
+import type { Preferences, WindowOptions } from '@stacksjs/desktop';
+/**
+ * Normalize a route key to `"<METHOD> <path>"`. A key without a method is a
+ * `GET`, so `'/api/status'` and `'GET /api/status'` are the same route.
+ */
+export declare function normalizeRouteKey(key: string): string;
+/**
+ * Coerce a handler's return value into a `Response`. Handlers that return
+ * nothing get `204 No Content`; a handler that built its own `Response` keeps it.
+ */
+export declare function toResponse(result: RouteResult): Response;
+/**
+ * Apply an untrusted patch to a preference store, keeping only keys that exist
+ * in the defaults so a stray request cannot write arbitrary fields into the
+ * preferences file.
+ */
+export declare function applyPreferencePatch<T extends Record<string, unknown>>(preferences: Preferences<T>, patch: Record<string, unknown>): T;
+export declare function createMenuBarApp<T extends Record<string, unknown>>(options: MenuBarAppOptions<T>): MenuBarApp<T>;
+/** A tray menu entry. Actions are plain strings the app interprets itself. */
+export declare interface MenuBarMenuItem {
+  label?: string
+  type?: 'normal' | 'separator' | 'checkbox' | 'radio' | 'submenu'
+  checked?: boolean
+  enabled?: boolean
+  icon?: string
+  shortcut?: string
+  action?: string
+  submenu?: MenuBarMenuItem[]
+}
+export declare interface MenuBarAppOptions<T extends Record<string, unknown>> {
+  name: string
+  template: string
+  templateSource?: string
+  preferences?: T
+  context?: (preferences: Preferences<T>) => Record<string, unknown> | Promise<Record<string, unknown>>
+  routes?: Routes<T>
+  menu?: (preferences: Preferences<T>) => MenuBarMenuItem[]
+  launchAtLogin?: keyof T
+  window?: WindowOptions
+  port?: number
+}
+export declare interface MenuBarApp<T extends Record<string, unknown>> {
+  readonly preferences: Preferences<T>
+  readonly url: string | null
+  start: () => Promise<MenuBarApp<T>>
+  stop: () => void
+}
+/**
+ * What a route may hand back: a `Response` to take over the reply entirely,
+ * `undefined` for a `204`, or any JSON-serializable value to send as JSON.
+ * Typed as `unknown` so a handler can return a plain interface without the
+ * value needing an index signature.
+ */
+export type RouteResult = Response | unknown;
+/** A route handler receives the request and the app's preference store. */
+export type RouteHandler<T extends Record<string, unknown>> = (
+  request: Request,
+  preferences: Preferences<T>,
+) => RouteResult | Promise<RouteResult>;
+/**
+ * Routes keyed by `"<METHOD> <path>"`, e.g. `'POST /api/caffeinate/toggle'`.
+ * The method may be omitted, in which case `GET` is assumed.
+ */
+export type Routes<T extends Record<string, unknown>> = Record<string, RouteHandler<T>>;

package/dist/menubar.js

@@ -0,0 +1,99 @@
+import { createPreferences, createWindow, setAutoLaunch } from "@stacksjs/desktop";
+import { renderTemplate, renderTemplateString } from "./render.js";
+const MENU_BAR_WINDOW = {
+  width: 320,
+  height: 640,
+  systemTray: !0,
+  hideDockIcon: !0,
+  titlebarHidden: !0,
+  resizable: !1,
+  alwaysOnTop: !0,
+  darkMode: !0
+}, JSON_HEADERS = { "Content-Type": "application/json; charset=utf-8" };
+export function normalizeRouteKey(key) {
+  const [first, ...rest] = key.trim().split(/\s+/);
+  return rest.length ? `${first.toUpperCase()} ${rest.join(" ")}` : `GET ${first}`;
+}
+export function toResponse(result) {
+  if (result instanceof Response)
+    return result;
+  if (result === void 0)
+    return new Response(null, { status: 204 });
+  return new Response(JSON.stringify(result), { headers: JSON_HEADERS });
+}
+export function applyPreferencePatch(preferences, patch) {
+  const known = preferences.getAll();
+  for (const [key, value] of Object.entries(patch))
+    if (key in known)
+      preferences.set(key, value);
+  return preferences.getAll();
+}
+export function createMenuBarApp(options) {
+  const preferences = createPreferences({
+    name: options.name.toLowerCase(),
+    defaults: options.preferences ?? {}
+  }), routes = new Map(Object.entries(options.routes ?? {}).map(([key, handler]) => [normalizeRouteKey(key), handler])), builtins = {
+    "GET /api/preferences": () => preferences.getAll(),
+    "POST /api/preferences": async (request) => applyPreferencePatch(preferences, await request.json()),
+    "GET /api/menu": () => options.menu?.(preferences) ?? []
+  };
+  for (const [key, handler] of Object.entries(builtins))
+    if (!routes.has(key))
+      routes.set(key, handler);
+  let server = null, window = null, url = null;
+  async function renderPopup() {
+    const renderOptions = { context: await options.context?.(preferences) ?? {}, wrapInDocument: !0, title: options.name }, html = options.templateSource ? await renderTemplateString(options.templateSource, options.template, renderOptions) : await renderTemplate(options.template, renderOptions);
+    return new Response(html, { headers: { "Content-Type": "text/html; charset=utf-8" } });
+  }
+  function serve() {
+    server = Bun.serve({
+      port: options.port ?? 0,
+      hostname: "127.0.0.1",
+      async fetch(request) {
+        const { pathname } = new URL(request.url);
+        if (request.method === "GET" && (pathname === "/" || pathname === "/index.html"))
+          return renderPopup();
+        const handler = routes.get(`${request.method} ${pathname}`);
+        if (!handler)
+          return new Response("Not Found", { status: 404 });
+        return toResponse(await handler(request, preferences));
+      }
+    });
+    url = `http://127.0.0.1:${server.port}`;
+  }
+  function bindLaunchAtLogin() {
+    const key = options.launchAtLogin;
+    if (!key)
+      return;
+    const sync = (enabled) => {
+      setAutoLaunch(Boolean(enabled), { appName: options.name, isHidden: !0 }).catch(() => {});
+    };
+    sync(preferences.get(key));
+    preferences.onChange(key, sync);
+  }
+  return {
+    preferences,
+    get url() {
+      return url;
+    },
+    async start() {
+      if (!server)
+        serve();
+      bindLaunchAtLogin();
+      window = await createWindow(url, {
+        ...MENU_BAR_WINDOW,
+        title: options.name,
+        ...options.window
+      });
+      return this;
+    },
+    stop() {
+      window?.close();
+      window = null;
+      server?.stop();
+      server = null;
+      url = null;
+      preferences.close();
+    }
+  };
+}

package/dist/method-spoofing.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Form Method Spoofing for stx templates
+ *
+ * Similar to Laravel's @method directive, this allows specifying
+ * HTTP methods like PUT, PATCH, DELETE in HTML forms which only
+ * support GET and POST.
+ */
+/**
+ * Generate a method spoofing input field
+ */
+export declare function methodField(method: string, fieldName?: string): string;
+/**
+ * Process @method directives in templates
+ */
+export declare function processMethodDirectives(template: string): string;
+/**
+ * Helper to get the original method from a request
+ * For middleware implementations
+ */
+export declare function getOriginalMethod(body: Record<string, any>, methodField?: string): string | null;

package/dist/method-spoofing.js

@@ -0,0 +1,17 @@
+const METHOD_FIELD_NAME = "_method";
+export function methodField(method, fieldName = METHOD_FIELD_NAME) {
+  const upperMethod = method.toUpperCase();
+  if (upperMethod === "GET" || upperMethod === "POST")
+    return "";
+  return `<input type="hidden" name="${fieldName}" value="${upperMethod}">`;
+}
+export function processMethodDirectives(template) {
+  return template.replace(/@method\(\s*(['"])([^'"]+)\1\s*(?:,\s*(['"])([^'"]+)\3\s*)?\)/g, (_, outerQuote, method, innerQuote, fieldName) => {
+    return methodField(method, fieldName || METHOD_FIELD_NAME);
+  });
+}
+export function getOriginalMethod(body, methodField = METHOD_FIELD_NAME) {
+  if (body && typeof body[methodField] === "string")
+    return body[methodField].toUpperCase();
+  return null;
+}

package/dist/middleware.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Middleware Module
+ *
+ * Provides a middleware system for pre/post-processing templates.
+ * Middleware can transform template content before or after directive processing.
+ *
+ * ## Middleware Lifecycle
+ *
+ * 1. **Before (pre-processing)**: Runs before any directives are processed.
+ *    Use for raw template transformation, content injection, or validation.
+ *
+ * 2. **After (post-processing)**: Runs after all directives are processed.
+ *    Use for output transformation, minification, or final validation.
+ *
+ * ## Middleware Definition
+ *
+ * ```typescript
+ * interface Middleware {
+ *   name: string                              // Unique identifier
+ *   timing: 'before' | 'after'                // When to run
+ *   handler: (
+ *     template: string,                       // Current template content
+ *     context: Record<string, any>,           // Template context
+ *     filePath: string,                       // Path to template file
+ *     options: StxOptions                     // Processing options
+ *   ) => string | Promise<string>             // Modified template
+ * }
+ * ```
+ *
+ * ## Configuration Example
+ *
+ * ```typescript
+ * // stx.config.ts
+ * export default {
+ *   middleware: [
+ *     {
+ *       name: 'minify-html',
+ *       timing: 'after',
+ *       handler: (template) => template.replace(/\\s+/g, ' ')
+ *     },
+ *     {
+ *       name: 'inject-timestamp',
+ *       timing: 'before',
+ *       handler: (template, ctx) => {
+ *         ctx.buildTime = new Date().toISOString()
+ *         return template
+ *       }
+ *     }
+ *   ]
+ * }
+ * ```
+ *
+ * ## Error Handling
+ *
+ * - Middleware errors are caught and logged (in debug mode)
+ * - A visual error message is injected into the output when debug is enabled
+ * - Processing continues with remaining middleware even if one fails
+ *
+ * @module middleware
+ */
+import type { StxOptions } from './types';
+/**
+ * Process middleware registered in the application.
+ *
+ * Executes all middleware handlers that match the specified timing in sequence.
+ * Each middleware receives the current template and can modify it.
+ *
+ * @param template - The template string to process
+ * @param context - Template context with variables (can be modified by middleware)
+ * @param filePath - Path to the template file (for error messages)
+ * @param options - STX processing options containing middleware configuration
+ * @param timing - When to run: 'before' or 'after' directive processing
+ * @returns The processed template string
+ *
+ * @example
+ * ```typescript
+ * const processed = await processMiddleware(
+ *   '<div>{{ content }}</div>',
+ *   { content: 'Hello' },
+ *   '/path/to/template.stx',
+ *   { middleware: myMiddleware },
+ *   'before'
+ * )
+ * ```
+ */
+export declare function processMiddleware(template: string, context: Record<string, any>, filePath: string, options: StxOptions, timing: 'before' | 'after'): Promise<string>;
+/**
+ * Run pre-processing middleware (timing: 'before').
+ *
+ * This is a convenience wrapper for `processMiddleware` with timing='before'.
+ * Pre-processing middleware runs before any directives are processed.
+ *
+ * @param template - The raw template string
+ * @param context - Template context with variables
+ * @param filePath - Path to the template file
+ * @param options - STX processing options
+ * @returns The pre-processed template string
+ */
+export declare function runPreProcessingMiddleware(template: string, context: Record<string, any>, filePath: string, options: StxOptions): Promise<string>;
+/**
+ * Run post-processing middleware (timing: 'after').
+ *
+ * This is a convenience wrapper for `processMiddleware` with timing='after'.
+ * Post-processing middleware runs after all directives have been processed.
+ *
+ * @param template - The processed template string
+ * @param context - Template context with variables
+ * @param filePath - Path to the template file
+ * @param options - STX processing options
+ * @returns The post-processed template string
+ */
+export declare function runPostProcessingMiddleware(template: string, context: Record<string, any>, filePath: string, options: StxOptions): Promise<string>;

package/dist/middleware.js

@@ -0,0 +1,40 @@
+import { escapeHtml } from "./expressions.js";
+import { createDetailedErrorMessage } from "./utils.js";
+export async function processMiddleware(template, context, filePath, options, timing) {
+  if (!options.middleware || options.middleware.length === 0)
+    return template;
+  let output = template;
+  const middlewareToRun = options.middleware.filter((m) => m.timing === timing);
+  if (middlewareToRun.length === 0)
+    return output;
+  for (const middleware of middlewareToRun) {
+    if (!middleware.name || typeof middleware.handler !== "function") {
+      if (options.debug)
+        console.warn("Invalid middleware:", middleware);
+      continue;
+    }
+    try {
+      const result = await middleware.handler(output, context, filePath, options);
+      if (typeof result === "string")
+        output = result;
+      else if (options.debug)
+        console.warn(`Middleware ${middleware.name} did not return a string`);
+    } catch (error) {
+      if (options.debug)
+        console.error(`Error in middleware ${middleware.name}:`, error);
+      if (options.debug) {
+        const errorMessage = createDetailedErrorMessage("Middleware", `Error in middleware '${middleware.name}': ${error instanceof Error ? error.message : String(error)}`, filePath, template);
+        output = output.replace(/<body[^>]*>/, `$&
+<div style="color:red;background:#ffeeee;padding:10px;border:1px solid #ff0000;margin:10px 0;font-family:monospace;white-space:pre-wrap;">${escapeHtml(errorMessage)}</div>
+`);
+      }
+    }
+  }
+  return output;
+}
+export async function runPreProcessingMiddleware(template, context, filePath, options) {
+  return processMiddleware(template, context, filePath, options, "before");
+}
+export async function runPostProcessingMiddleware(template, context, filePath, options) {
+  return processMiddleware(template, context, filePath, options, "after");
+}

package/dist/misc-directives.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Process @json directive to output JSON
+ */
+export declare function processJsonDirective(template: string, context: Record<string, any>): string;
+/**
+ * Process @once directive blocks.
+ * Primary deduplication is handled by processIncludes (context.__onceStore).
+ * This function only strips remaining @once/@endonce tags, keeping content.
+ */
+export declare function processOnceDirective(template: string): string;
+/**
+ * Process @memo directive — memoize template subtrees.
+ *
+ * Two shapes are supported:
+ *
+ * 1. Attribute form on an element:
+ *      <div @memo="[count(), name()]">Expensive content</div>
+ *    Transforms to `data-stx-memo="[count(), name()]"`. The signals runtime
+ *    skips re-processing elements whose deps haven't changed.
+ *
+ * 2. Blade-style block form wrapping arbitrary markup:
+ *      @memo([])
+ *        <section>...marketing content...</section>
+ *      @endmemo
+ *    The block is transformed by injecting `data-stx-memo` onto the first
+ *    opening tag inside the block (or wrapping in a <div> if the contents
+ *    don't start with a single element). Both `@memo(...)` and `@endmemo`
+ *    are stripped from the output.
+ */
+export declare function processMemoDirective(template: string): string;
+/**
+ * Process ref attributes for DOM element references (Vue-style).
+ *
+ * Transforms:
+ *   <input ref="inputRef" />
+ *   <input @ref="inputRef" />
+ *
+ * Into:
+ *   <input data-stx-ref="inputRef" />
+ *
+ * The client-side runtime will automatically bind these to ref objects.
+ */
+export declare function processRefAttributes(template: string): string;
+/**
+ * Add x-cloak to HTML elements whose own text contains an unresolved {{ }}
+ * expression. Those were preserved for client-side evaluation (signals, loop
+ * vars, etc.), and x-cloak hides them until the runtime binds and reveals them,
+ * so the raw mustache never flashes.
+ *
+ * Only the element that actually holds the expression is stamped — see
+ * `ownTextContainsMustache` for why that scoping is the fix rather than a refinement. An
+ * element carrying `x-no-cloak` is left visible regardless.
+ */
+export declare function addCloakToUnresolvedExpressions(html: string): string;
+export declare function addCloakToConditionalDirectives(html: string): string;