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

package/dist/page-action.d.ts

@@ -0,0 +1,73 @@
+import { type SetCookieOptions } from './cookie-serialize';
+/**
+ * Parse a form submission body into a plain object.
+ *
+ * Handles both encodings a browser form can send: `multipart/form-data` and
+ * `application/x-www-form-urlencoded`. A repeated field name collapses to an
+ * array, so `<input name="tag">` twice reads as `['a', 'b']` rather than
+ * silently keeping only the last one — checkbox groups are the common case.
+ *
+ * File parts are skipped: the value would be a `File`, and a page action that
+ * wants uploads should read `request.formData()` itself rather than have this
+ * hand it something that cannot round-trip into a re-rendered form field.
+ */
+export declare function parseFormBody(request: Request): Promise<Record<string, string | string[]>>;
+/**
+ * Whether this request should run a page action at all.
+ *
+ * GET and HEAD never do — a page action is for submissions, and running one on
+ * a GET would make every page load a mutation.
+ */
+export declare function isActionableMethod(method: string | undefined): boolean;
+/**
+ * Run a page's own `action`, if it declared one, and merge what it returned.
+ *
+ * The action is picked up off the render context rather than parsed out of the
+ * source: the server block has already run by this point, so a declared
+ * `action` is simply there — and it can close over anything else the block
+ * defined, which a regex-extracted function could not.
+ *
+ * Inert on GET and for any page without an action, so a page that does not opt
+ * in pays one `typeof` check.
+ */
+export declare function runPageAction(context: Record<string, any>, options?: RunPageActionOptions): Promise<PageActionResult>;
+/**
+ * The response a redirecting action should produce.
+ *
+ * 303 rather than 302 deliberately: it is the status that makes a browser
+ * follow up with a GET, so a reload or a Back does not resubmit the form.
+ */
+export declare function actionRedirectResponse(to: string, cookies?: readonly string[], pageHeaders?: Record<string, string>): Response;
+/**
+ * Everything an action is given about the request.
+ *
+ * A plain object rather than the `Request` alone, so an action is a pure
+ * function of its inputs and unit-tests without a server around it.
+ */
+export declare interface PageActionContext {
+  request: Request
+  form: Record<string, string | string[]>
+  params: Record<string, string>
+  query: Record<string, unknown>
+  cookies: Record<string, string>
+}
+/** What running an action produced. */
+export declare interface PageActionResult {
+  redirect?: string
+  cookies?: string[]
+  ran: boolean
+}
+/** Request data a caller has already parsed, if it has. */
+export declare interface RunPageActionOptions {
+  request?: Request
+  method?: string
+  params?: Record<string, string>
+  cookies?: Record<string, string>
+}
+/**
+ * A cookie an action wants set on the response.
+ *
+ * A bare string is the whole cookie for the common case; the object form adds
+ * the attributes a session cookie needs.
+ */
+export type PageActionCookie = string | (SetCookieOptions & { value: string });

package/dist/page-action.js

@@ -0,0 +1,91 @@
+import { serializeSetCookie } from "./cookie-serialize.js";
+export async function parseFormBody(request) {
+  const type = request.headers.get("content-type") || "", form = {}, put = (key, value) => {
+    const existing = form[key];
+    if (existing === void 0)
+      form[key] = value;
+    else if (Array.isArray(existing))
+      existing.push(value);
+    else
+      form[key] = [existing, value];
+  };
+  if (type.includes("multipart/form-data")) {
+    const data = await request.formData();
+    for (const [key, value] of data.entries())
+      if (typeof value === "string")
+        put(key, value);
+    return form;
+  }
+  if (type.includes("application/x-www-form-urlencoded")) {
+    for (const [key, value] of new URLSearchParams(await request.text()).entries())
+      put(key, value);
+    return form;
+  }
+  return form;
+}
+export function isActionableMethod(method) {
+  if (!method)
+    return !1;
+  const verb = method.toUpperCase();
+  return verb !== "GET" && verb !== "HEAD";
+}
+export async function runPageAction(context, options = {}) {
+  const request = options.request, method = options.method ?? request?.method;
+  if (!request || !isActionableMethod(method))
+    return { ran: !1 };
+  if (typeof context.action !== "function")
+    return { ran: !1 };
+  let form = {};
+  try {
+    form = await parseFormBody(request);
+  } catch {}
+  const result = await context.action({
+    request,
+    form,
+    params: options.params ?? {},
+    query: context.query ?? {},
+    cookies: options.cookies ?? {}
+  });
+  if (result && typeof result === "object") {
+    const returned = result, cookies = serializeActionCookies(returned.cookies), to = returned.redirect;
+    if (typeof to === "string" && to)
+      return { redirect: to, ran: !0, ...cookies.length > 0 ? { cookies } : {} };
+    const { cookies: _cookies, redirect: _redirect, ...data } = returned;
+    Object.assign(context, data);
+    if (cookies.length > 0)
+      return { ran: !0, cookies };
+  }
+  return { ran: !0 };
+}
+function serializeActionCookies(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    return [];
+  const headers = [];
+  for (const [name, entry] of Object.entries(value)) {
+    if (!name)
+      continue;
+    if (typeof entry === "string") {
+      headers.push(serializeSetCookie(name, entry));
+      continue;
+    }
+    if (entry && typeof entry === "object") {
+      const options = entry;
+      if (typeof options.value !== "string")
+        continue;
+      headers.push(serializeSetCookie(name, options.value, options));
+    }
+  }
+  return headers;
+}
+export function actionRedirectResponse(to, cookies = [], pageHeaders) {
+  const headers = new Headers({
+    Location: to,
+    "Cache-Control": "no-store"
+  });
+  for (const cookie of cookies)
+    headers.append("Set-Cookie", cookie);
+  for (const [name, value] of Object.entries(pageHeaders ?? {}))
+    if (name.toLowerCase() !== "location")
+      headers.set(name, value);
+  return new Response(null, { status: 303, headers });
+}

package/dist/page-meta.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Reading `definePageMeta({ … })` out of a template's source.
+ *
+ * `PageMeta.layout` was part of the public type and appeared in
+ * `definePageMeta`'s own documentation example, but no code path read it. A
+ * page declaring `definePageMeta({ layout: 'app' })` type-checked, looked like
+ * the idiomatic declaration, and rendered with no layout at all
+ * (stacksjs/stx#1879).
+ *
+ * The cost was not just the missing layout. With no working typed way to say
+ * "this page belongs to the app layout group", pages hand-wrote
+ * `<meta name="stx-layout" content="app">` — a copy of a marker stx emits
+ * itself. The router's full-document-vs-fragment swap decision hinges on that
+ * string, so a page asserting a group it does not belong to is a routing
+ * hazard, not a cosmetic one.
+ *
+ * The extraction lives here because four separate regexes over
+ * `definePageMeta` had accumulated across `ssg.ts`, `page-response.ts` and
+ * `bun-plugin`'s serve path, each recognising a slightly different subset.
+ *
+ * @module page-meta
+ */
+/**
+ * Parse the first `definePageMeta({ … })` call in `source`.
+ *
+ * Object literals only — the call is read statically, before any script has
+ * run, so a computed argument cannot be resolved and returns `null` rather
+ * than half a result.
+ */
+export declare function extractPageMetaFromSource(source: string): Record<string, any> | null;
+/**
+ * The layout a page declares, if any.
+ *
+ * `false` is meaningful and distinct from "not declared" — it means the same
+ * as `@nolayout`, so it must survive as `false` rather than collapsing into
+ * `undefined`.
+ */
+export declare function pageMetaLayout(meta: Record<string, any> | null | undefined): string | false | undefined;

package/dist/page-meta.js

@@ -0,0 +1,16 @@
+export function extractPageMetaFromSource(source) {
+  const match = source.match(/\bdefinePageMeta\s*\(\s*(\{[\s\S]*?\})\s*\)/m);
+  if (!match)
+    return null;
+  try {
+    return Function(`return ${match[1]}`)();
+  } catch {
+    return null;
+  }
+}
+export function pageMetaLayout(meta) {
+  const layout = meta?.layout;
+  if (layout === !1)
+    return !1;
+  return typeof layout === "string" && layout.trim() ? layout.trim() : void 0;
+}

package/dist/page-response.d.ts

@@ -0,0 +1,120 @@
+/**
+ * The HTTP status and headers a page decides for its own response.
+ *
+ * Three shapes reach the same place, so a host reads one key and gets all
+ * three:
+ *
+ *  - `definePageMeta({ status })` — read statically out of the source, before
+ *    anything runs. Right for a page that is *always* an error page.
+ *  - `@status(expr)` — a template directive, evaluated where the rest of the
+ *    template is. It sits inside the branch it belongs to, so a page says
+ *    `@if (!feature) @status(404) @endif` next to the markup that explains it.
+ *  - `setResponseStatus(code)` / `notFound()` / `setResponseHeader(n, v)` —
+ *    callable from `<script server>`, for a decision that needs the lookup's
+ *    result.
+ *
+ * The last two record on the render context under `__stxResponseStatus` and
+ * `__stxResponseHeaders`. Every host that renders a view — the dev/production
+ * serve in `bun-plugin`, `stx`'s own `serve`, the app dev server, the
+ * precompiled production server — reads them back with `readResponseStatus`
+ * and answers with what it finds.
+ *
+ * That read-back is the whole point. Recording without it is the failure this
+ * module exists to prevent: a page that says 404 renders its not-found body
+ * under a 200, which tells a crawler, a cache and an uptime check that the URL
+ * is a real page.
+ *
+ * @module page-response
+ */
+/** Context key holding the status a render asked for. */
+export declare const RESPONSE_STATUS_KEY = "__stxResponseStatus";
+/** Context key holding the headers a render asked for. */
+export declare const RESPONSE_HEADERS_KEY = "__stxResponseHeaders";
+/**
+ * Is this a status a response can actually carry?
+ *
+ * Out of range is ignored rather than thrown everywhere below. A status is not
+ * worth failing an already-rendered page over, and the range check is what
+ * stops a typo becoming a 500 from whichever host reads it back.
+ */
+export declare function isHttpStatus(value: unknown): value is number;
+/**
+ * Read the static HTTP status declared by `definePageMeta`.
+ *
+ * The development server needs this before client scripts execute so error
+ * pages and other non-200 documents carry the correct response semantics.
+ */
+export declare function extractPageResponseStatus(source: string): number | undefined;
+/**
+ * Record a status on the render context, if it is one.
+ *
+ * Last call wins, so a page can look, decide, then change its mind — the
+ * lookup that finds the record after all must be able to take the 404 back.
+ * Returns whether the status was accepted, so a caller can warn about one that
+ * was not.
+ */
+export declare function recordResponseStatus(context: Record<string, any> | undefined, status: unknown): boolean;
+/**
+ * Record a response header on the render context.
+ *
+ * The pair is not optional: a page that works out mid-render that a handle has
+ * moved can say 301 and, without this, cannot say where to — so the response
+ * it produces is a redirect with no destination, which is worse than the 404
+ * it replaced.
+ */
+export declare function recordResponseHeader(context: Record<string, any> | undefined, name: unknown, value: unknown): void;
+/** The status a finished render asked for, or `undefined` if it asked for none. */
+export declare function readResponseStatus(context: Record<string, any> | undefined | null): number | undefined;
+/** The headers a finished render asked for, or `undefined` if it asked for none. */
+export declare function readResponseHeaders(context: Record<string, any> | undefined | null): Record<string, string> | undefined;
+/**
+ * Move a recorded status/headers from one context object onto another.
+ *
+ * Renderers build a fresh internal context from the caller's — so a page that
+ * records a status records it on an object nobody outside can read. This is
+ * how the intent gets back out: call it with the internal context and the
+ * caller's, after the render.
+ *
+ * Only copies what is there. A render that asked for nothing leaves the target
+ * untouched rather than stamping it with a 200, so a caller can tell "the page
+ * said 200" from "the page said nothing" — the second is what lets an outer
+ * status (an error page's `definePageMeta`) survive.
+ */
+export declare function syncRecordedResponse(from: Record<string, any> | undefined | null, to: Record<string, any> | undefined | null): void;
+/**
+ * The `<script server>` bindings for deciding a response, bound to one context.
+ *
+ * Handed to every server script by `extractVariables`, so no host can render a
+ * view and leave them out. A host that wants the calls to go somewhere of its
+ * own — the dev serve puts them straight on its per-request context — overrides
+ * them through the render context, which is appended after these and wins.
+ */
+export declare function responseBindings(context: Record<string, any>): {
+    setResponseStatus: (status: number) => void;
+    setResponseHeader: (name: string, value: string) => void;
+    notFound: (status?: number) => void;
+};
+/**
+ * `@status(expr)` — the template-side spelling.
+ *
+ * Runs after `processConditionals`, so a `@status` in a branch that lost is
+ * already gone from the template and never fires. That ordering is the feature:
+ * it lets the status live beside the markup that justifies it,
+ *
+ *     @if (!feature)
+ *       @status(404)
+ *       <h1>No feature by that name.</h1>
+ *     @endif
+ *
+ * rather than being re-derived from a flag at the top of the server block.
+ *
+ * A literal is taken as written; anything else goes through `safeEvaluate`
+ * against the render context. An argument that evaluates to a non-status is
+ * ignored — see `isHttpStatus` — but *is* warned about, because unlike a
+ * runtime call this one was typed out in the template and a silent no-op there
+ * reads as the feature not existing.
+ */
+export declare function processStatusDirective(template: string, context: Record<string, any>, options?: {
+    filePath?: string;
+    buildMode?: string;
+}): string;

package/dist/page-response.js

@@ -0,0 +1,117 @@
+import { safeEvaluate } from "./safe-evaluator.js";
+const MIN_HTTP_STATUS = 100, MAX_HTTP_STATUS = 599;
+export const RESPONSE_STATUS_KEY = "__stxResponseStatus", RESPONSE_HEADERS_KEY = "__stxResponseHeaders";
+export function isHttpStatus(value) {
+  return typeof value === "number" && Number.isInteger(value) && value >= MIN_HTTP_STATUS && value <= MAX_HTTP_STATUS;
+}
+export function extractPageResponseStatus(source) {
+  for (const call of source.matchAll(/\bdefinePageMeta\s*\(\s*\{([\s\S]*?)\}\s*\)/g)) {
+    const match = call[1].match(/(?:^|,)\s*status\s*:\s*(\d{3})(?=\s*(?:,|$))/);
+    if (!match)
+      continue;
+    const status = Number(match[1]);
+    if (isHttpStatus(status))
+      return status;
+  }
+  return;
+}
+export function recordResponseStatus(context, status) {
+  if (!context || typeof context !== "object")
+    return !1;
+  const code = typeof status === "string" && /^\d+$/.test(status.trim()) ? Number(status.trim()) : status;
+  if (!isHttpStatus(code))
+    return !1;
+  context[RESPONSE_STATUS_KEY] = code;
+  return !0;
+}
+export function recordResponseHeader(context, name, value) {
+  if (!context || typeof context !== "object")
+    return;
+  const header = String(name ?? "").trim();
+  if (!header)
+    return;
+  context[RESPONSE_HEADERS_KEY] = { ...context[RESPONSE_HEADERS_KEY], [header]: String(value) };
+}
+export function readResponseStatus(context) {
+  const status = context?.[RESPONSE_STATUS_KEY];
+  return isHttpStatus(status) ? status : void 0;
+}
+export function readResponseHeaders(context) {
+  const headers = context?.[RESPONSE_HEADERS_KEY];
+  if (!headers || typeof headers !== "object")
+    return;
+  const entries = Object.entries(headers).map(([k, v]) => [k, String(v)]);
+  return entries.length > 0 ? Object.fromEntries(entries) : void 0;
+}
+export function syncRecordedResponse(from, to) {
+  if (!from || !to || from === to || typeof to !== "object")
+    return;
+  const status = readResponseStatus(from);
+  if (status !== void 0)
+    to[RESPONSE_STATUS_KEY] = status;
+  const headers = readResponseHeaders(from);
+  if (headers)
+    to[RESPONSE_HEADERS_KEY] = { ...to[RESPONSE_HEADERS_KEY], ...headers };
+}
+export function responseBindings(context) {
+  return {
+    setResponseStatus: (status) => {
+      recordResponseStatus(context, status);
+    },
+    notFound: (status = 404) => {
+      const code = isHttpStatus(status) && status >= 400 ? status : 404;
+      recordResponseStatus(context, code);
+    },
+    setResponseHeader: (name, value) => {
+      recordResponseHeader(context, name, value);
+    }
+  };
+}
+export function processStatusDirective(template, context, options = {}) {
+  if (!template.includes("@status"))
+    return template;
+  const { filePath, buildMode } = options, precompiling = buildMode === "compile";
+  let result = "", cursor = 0;
+  const pattern = /@status\s*\(/g;
+  let match;
+  while ((match = pattern.exec(template)) !== null) {
+    const close = closingParen(template, match.index + match[0].length - 1);
+    if (close < 0)
+      break;
+    const arg = template.slice(match.index + match[0].length, close).trim(), value = /^\d+$/.test(arg) ? Number(arg) : safeEvaluate(arg, context), where = filePath ? ` in ${filePath}` : "";
+    if (precompiling)
+      console.warn(`[stx] @status(${arg})${where} is skipped when precompiling: the build has no request, so the branch it sits in is not the one a visitor will get. Call notFound() or setResponseStatus(${arg}) from <script server> instead \u2014 that runs per request.`);
+    else if (!recordResponseStatus(context, value))
+      console.warn(`[stx] @status(${arg})${where} is not an HTTP status (100-599) \u2014 ignoring it.`);
+    result += template.slice(cursor, match.index);
+    cursor = close + 1 + (template.slice(close + 1).match(/^[^\S\n]*\n?/)?.[0].length ?? 0);
+    pattern.lastIndex = cursor;
+  }
+  return cursor === 0 ? template : result + template.slice(cursor);
+}
+function closingParen(source, open) {
+  let depth = 1, quote = null, escaped = !1;
+  for (let i = open + 1;i < source.length; i++) {
+    const char = source[i];
+    if (escaped) {
+      escaped = !1;
+      continue;
+    }
+    if (quote) {
+      if (char === "\\")
+        escaped = !0;
+      else if (char === quote)
+        quote = null;
+      continue;
+    }
+    if (char === '"' || char === "'" || char === "`") {
+      quote = char;
+      continue;
+    }
+    if (char === "(")
+      depth++;
+    else if (char === ")" && --depth === 0)
+      return i;
+  }
+  return -1;
+}

package/dist/parser/directive-parser.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Directive Parser
+ *
+ * Provides utilities for parsing directives with proper handling of
+ * nested structures, balanced tags, and expressions.
+ *
+ * @module parser/directive-parser
+ */
+export interface DirectiveMatch {
+    fullMatch: string;
+    name: string;
+    params: string;
+    content: string;
+    start: number;
+    end: number;
+}
+export interface ConditionalBranch {
+    type: 'if' | 'elseif' | 'else';
+    condition?: string;
+    content: string;
+    start: number;
+    end: number;
+}
+export interface ParsedConditional {
+    fullMatch: string;
+    branches: ConditionalBranch[];
+    start: number;
+    end: number;
+}
+/**
+ * Extract a parenthesized expression from a string, handling nested parens
+ * e.g., "func(a, fn(b, c))" -> { expression: "func(a, fn(b, c))", endPos: 17 }
+ *
+ * Returns `null` for the legacy callers; use `extractParenthesizedExpressionDetailed`
+ * when you need to know WHY extraction failed (helpful for directive error
+ * messages pointing at the source location of a malformed `@if(`).
+ */
+export declare function extractParenthesizedExpression(source: string, startPos: number): {
+    expression: string;
+    endPos: number;
+} | null;
+/**
+ * Structured variant of `extractParenthesizedExpression` — returns either a
+ * successful parse or a `{ ok: false, reason, pos }` record explaining the
+ * failure. Use this when emitting user-facing errors ("missing opening
+ * paren", "unclosed paren at column N", etc.).
+ */
+export type ExtractParenResult = {
+    ok: true;
+    expression: string;
+    endPos: number;
+} | {
+    ok: false;
+    reason: 'missing-open-paren' | 'unclosed-paren';
+    pos: number;
+};
+export declare function extractParenthesizedExpressionDetailed(source: string, startPos: number): ExtractParenResult;
+/**
+ * Whether `pos` in `source` falls INSIDE an HTML tag (`<...>`) — i.e. the nearest
+ * angle bracket looking backwards is an unclosed `<`.
+ *
+ * Directive tokens (`@if`/`@elseif`/`@else`/`@endif`) only ever occur in text
+ * content, never inside a tag. The reactive-signal pass, however, rewrites a
+ * NESTED reactive conditional into HTML-attribute markers BEFORE this server pass
+ * runs — e.g. `@if (isPro())A@else B@endif` becomes
+ * `<template @if="isPro()">A</template><template @else>B</template>`. Without this
+ * guard the branch scanner matches that `@else` ATTRIBUTE as the enclosing server
+ * `@if`'s top-level `@else`, mismatching branch/`@endif` boundaries and corrupting
+ * the rest of the template. Skipping tag-interior tokens keeps the two passes from
+ * disagreeing on what is a directive.
+ */
+export declare function isInsideTag(source: string, pos: number): boolean;
+/**
+ * Find the matching end tag for a directive, handling nested instances
+ *
+ * @param source - The source string to search in
+ * @param startName - The opening directive name (e.g., "if", "foreach")
+ * @param endName - The closing directive name (e.g., "endif", "endforeach")
+ * @param startPos - Position to start searching from (after the opening directive)
+ * @returns The position of the matching end tag, or -1 if not found
+ */
+export declare function findMatchingEndTag(source: string, startName: string, endName: string, startPos: number): number;
+/**
+ * Parse a complete conditional block (@if, @elseif, @else, @endif)
+ *
+ * @param source - The source string
+ * @param startPos - Position where @if starts
+ * @returns Parsed conditional with all branches, or null if malformed
+ */
+export declare function parseConditionalBlock(source: string, startPos: number): ParsedConditional | null;
+/**
+ * Find all @if blocks in source (non-nested, outermost only)
+ */
+export declare function findIfBlocks(source: string): ParsedConditional[];
+/**
+ * Find a directive with its content
+ *
+ * @param source - Source string
+ * @param directiveName - Name without @ (e.g., "foreach")
+ * @param endDirectiveName - End name without @ (e.g., "endforeach")
+ * @returns All matches found
+ */
+export declare function findDirectiveBlocks(source: string, directiveName: string, endDirectiveName: string): DirectiveMatch[];
+/**
+ * Parse @switch block with proper handling of nested switches
+ */
+export interface SwitchCase {
+    type: 'case' | 'default';
+    value?: string;
+    content: string;
+}
+export interface ParsedSwitch {
+    fullMatch: string;
+    expression: string;
+    cases: SwitchCase[];
+    start: number;
+    end: number;
+}
+export declare function parseSwitchBlock(source: string, startPos: number): ParsedSwitch | null;