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

package/dist/site-builder/seo.js

@@ -0,0 +1,67 @@
+function absoluteImage(image, origin) {
+  if (!image)
+    return image;
+  if (/^[a-z][a-z0-9+.-]*:/i.test(image) || image.startsWith("//"))
+    return image;
+  return `${origin}${image.startsWith("/") ? "" : "/"}${image}`;
+}
+export function injectSeo(html, site, page = {}, pagePath = "/") {
+  const seo = site.seo ?? {}, title = page.title ?? seo.title ?? site.name, description = page.description ?? seo.description ?? site.description ?? "", origin = site.url.replace(/\/$/, ""), url = `${origin}${pagePath}`, image = absoluteImage(page.image ?? seo.image, origin), siteName = seo.siteName ?? site.name, ogType = seo.type ?? "website", locale = seo.locale ?? "en_US", tags = [];
+  if (seo.favicon) {
+    const ext = seo.favicon.toLowerCase().split(".").pop(), mime = ext === "svg" ? "image/svg+xml" : ext === "ico" ? "image/x-icon" : ext === "png" ? "image/png" : ext === "jpg" || ext === "jpeg" ? "image/jpeg" : "";
+    tags.push(`<link rel="icon"${mime ? ` type="${mime}"` : ""} href="${escapeAttr(seo.favicon)}">`);
+  }
+  tags.push(`<title>${escapeText(title)}</title>`, `<link rel="canonical" href="${escapeAttr(url)}">`, `<meta name="description" content="${escapeAttr(description)}">`, `<meta property="og:title" content="${escapeAttr(title)}">`, `<meta property="og:description" content="${escapeAttr(description)}">`, `<meta property="og:type" content="${escapeAttr(ogType)}">`, `<meta property="og:url" content="${escapeAttr(url)}">`, `<meta property="og:site_name" content="${escapeAttr(siteName)}">`, `<meta property="og:locale" content="${escapeAttr(locale)}">`, `<meta name="twitter:card" content="${image ? "summary_large_image" : "summary"}">`, `<meta name="twitter:title" content="${escapeAttr(title)}">`, `<meta name="twitter:description" content="${escapeAttr(description)}">`);
+  if (image) {
+    tags.push(`<meta property="og:image" content="${escapeAttr(image)}">`);
+    tags.push(`<meta name="twitter:image" content="${escapeAttr(image)}">`);
+  }
+  if (seo.twitter) {
+    tags.push(`<meta name="twitter:site" content="@${escapeAttr(seo.twitter.replace(/^@/, ""))}">`);
+    tags.push(`<meta name="twitter:creator" content="@${escapeAttr(seo.twitter.replace(/^@/, ""))}">`);
+  }
+  const stxAutoBlockRe = /<!--\s*stx SEO Tags\s*-->[\s\S]*?<meta\s+name="twitter:description"[^>]*>\s*/i;
+  if (stxAutoBlockRe.test(html))
+    html = html.replace(stxAutoBlockRe, "");
+  html = html.replace(/<!--\s*SEO\s*-->[\s\S]*?<!--\s*\/SEO\s*-->\s*/g, "");
+  html = html.replace(/<meta\s+name="title"\s+content="stx Project"[^>]*>\s*/g, "").replace(/<meta\s+name="description"\s+content="A website built with stx[^"]*"[^>]*>\s*/g, "").replace(/<meta\s+property="og:title"\s+content="stx Project"[^>]*>\s*/g, "").replace(/<meta\s+property="og:description"\s+content="A website built with stx[^"]*"[^>]*>\s*/g, "").replace(/<meta\s+name="twitter:title"\s+content="stx Project"[^>]*>\s*/g, "").replace(/<meta\s+name="twitter:description"\s+content="A website built with stx[^"]*"[^>]*>\s*/g, "");
+  const headEnd = html.search(/<\/head>/i), head = headEnd === -1 ? html : html.slice(0, headEnd), PLACEHOLDER_TITLES = /^(?:stx App|stx Project|Document|Untitled)$/i, existingTitle = /<title[^>]*>([\s\S]*?)<\/title>/i.exec(head)?.[1]?.trim(), titleIsPlaceholder = existingTitle === void 0 || existingTitle === "" || PLACEHOLDER_TITLES.test(existingTitle), declared = (tag) => {
+    if (/^<title[\s>]/i.test(tag))
+      return /<title[\s>]/i.test(head) && !titleIsPlaceholder;
+    if (/rel="canonical"/i.test(tag))
+      return /<link[^>]+rel=["']canonical["']/i.test(head);
+    const key = /(?:property|name)="([^"]+)"/i.exec(tag)?.[1];
+    if (!key)
+      return !1;
+    return new RegExp(`<meta[^>]+(?:property|name)=["']${key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}["']`, "i").test(head);
+  };
+  let missing = tags.filter((tag) => !declared(tag));
+  if (missing.length === 0)
+    return html;
+  let output = html;
+  const titleTag = missing.find((tag) => /^<title[\s>]/i.test(tag));
+  if (titleTag && titleIsPlaceholder && /<title[^>]*>[\s\S]*?<\/title>/i.test(output)) {
+    output = output.replace(/<title[^>]*>[\s\S]*?<\/title>/i, () => titleTag);
+    missing = missing.filter((tag) => tag !== titleTag);
+    if (missing.length === 0)
+      return output;
+  }
+  const block = `<!-- SEO -->
+${missing.join(`
+`)}
+<!-- /SEO -->`, outEnd = output.search(/<\/head>/i);
+  if (outEnd !== -1)
+    return `${output.slice(0, outEnd)}${block}
+${output.slice(outEnd)}`;
+  if (/<head[^>]*>/i.test(output))
+    return output.replace(/<head([^>]*)>/i, `<head$1>
+${block}`);
+  return `${block}
+${output}`;
+}
+function escapeAttr(s) {
+  return s.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+function escapeText(s) {
+  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}

package/dist/site-builder/sitemap.d.ts

@@ -0,0 +1,10 @@
+import type { PageMeta, SiteConfig } from './types';
+/**
+ * Generate sitemap.xml content from a list of built pages.
+ * Pages with `sitemap: false` in their config are excluded.
+ */
+export declare function generateSitemap(site: SiteConfig, entries: SitemapEntry[]): string;
+export declare interface SitemapEntry {
+  path: string
+  page?: PageMeta
+}

package/dist/site-builder/sitemap.js

@@ -0,0 +1,26 @@
+export function generateSitemap(site, entries) {
+  const baseUrl = site.url.replace(/\/$/, ""), now = new Date().toISOString().slice(0, 10);
+  return [
+    '<?xml version="1.0" encoding="UTF-8"?>',
+    '<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">',
+    entries.filter((e) => e.page?.sitemap !== !1).map((e) => {
+      const url = `${baseUrl}${e.path}`, priority = e.page?.priority ?? (e.path === "/" ? 1 : 0.8), changefreq = e.page?.changefreq ?? "monthly";
+      return [
+        "  <url>",
+        `    <loc>${escape(url)}</loc>`,
+        `    <lastmod>${now}</lastmod>`,
+        `    <changefreq>${changefreq}</changefreq>`,
+        `    <priority>${priority.toFixed(1)}</priority>`,
+        "  </url>"
+      ].join(`
+`);
+    }).join(`
+`),
+    "</urlset>",
+    ""
+  ].join(`
+`);
+}
+function escape(s) {
+  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}

package/dist/site-builder/theme.d.ts

@@ -0,0 +1,12 @@
+import type { SiteConfig } from './types';
+/**
+ * Inject the theme bootstrap (FOUC guard + class) and the toggle
+ * handler. Skips no-op if the markers are already present so rebuilds
+ * stay idempotent.
+ */
+export declare function injectThemeBootstrap(html: string, site: SiteConfig): string;
+export declare interface ThemeOptions {
+  default?: 'dark' | 'light' | 'auto'
+  storageKey?: string
+  colors?: { light?: string, dark?: string }
+}

package/dist/site-builder/theme.js

@@ -0,0 +1,38 @@
+import { COLOR_MODE_BOOT_MARKER } from "../color-mode-boot.js";
+const FAVICON_FN = `window.__stxThemeIcon=function(isDark){try{var want=isDark?'dark':'light';var pick=document.querySelector('link[rel~="icon"][media*="prefers-color-scheme: '+want+'"]');if(!pick)return;var live=document.querySelector('link[rel~="icon"]:not([media])');if(!live){live=document.createElement('link');live.setAttribute('rel','icon');document.head.appendChild(live)}if(pick.type)live.setAttribute('type',pick.type);var href=pick.getAttribute('href');if(live.getAttribute('href')!==href)live.setAttribute('href',href)}catch(e){}};`, FOUC_SCRIPT = (defaultTheme, storageKey, lightColor, darkColor) => `(function(){${FAVICON_FN}function read(){try{var k=${JSON.stringify(storageKey)};var t=localStorage.getItem(k);return t===null?(${JSON.stringify(defaultTheme)}==='dark'||(${JSON.stringify(defaultTheme)}==='auto'&&window.matchMedia('(prefers-color-scheme: dark)').matches)):t==='dark'}catch(e){return ${JSON.stringify(defaultTheme)}==='dark'}}function apply(){var isDark=read();var html=document.documentElement;html.classList[isDark?'add':'remove']('dark');var color=isDark?${JSON.stringify(darkColor)}:${JSON.stringify(lightColor)};if(!document.head)return;var tc=document.querySelector('meta[name="theme-color"]:not([media])');if(!tc){tc=document.createElement('meta');tc.setAttribute('name','theme-color');tc.setAttribute('data-stx-theme-meta','1')}tc.setAttribute('content',color);if(tc!==document.head.firstChild){document.head.insertBefore(tc,document.head.firstChild)}if(window.__stxThemeIcon)window.__stxThemeIcon(isDark)}apply();window.addEventListener('stx:navigate',apply);window.addEventListener('popstate',apply)})();`, TOGGLE_HANDLER = (storageKey, lightColor, darkColor) => `document.addEventListener('click',function(e){var t=e.target&&e.target.closest&&e.target.closest('#theme-toggle');if(!t)return;var html=document.documentElement;var isDark=html.classList.toggle('dark');try{localStorage.setItem(${JSON.stringify(storageKey)},isDark?'dark':'light')}catch(e){}var tc=document.querySelector('meta[name="theme-color"]:not([media])');if(tc)tc.setAttribute('content',isDark?${JSON.stringify(darkColor)}:${JSON.stringify(lightColor)});if(window.__stxThemeIcon)window.__stxThemeIcon(isDark)});`;
+export function injectThemeBootstrap(html, site) {
+  if (site.theme === !1)
+    return html;
+  const colorModeOwnsTheme = html.includes(COLOR_MODE_BOOT_MARKER), opts = typeof site.theme === "object" && site.theme !== null ? site.theme : {}, defaultTheme = opts.default ?? "dark", storageKey = opts.storageKey ?? "theme", lightColor = opts.colors?.light ?? "#ffffff", darkColor = opts.colors?.dark ?? "#000000";
+  if (defaultTheme === "dark" && !colorModeOwnsTheme) {
+    if (!/<html\b[^>]*\bclass=/.test(html))
+      html = html.replace(/<html\b([^>]*)>/i, '<html$1 class="dark">');
+    else if (!/<html\b[^>]*\bclass="[^"]*\bdark\b/.test(html))
+      html = html.replace(/<html\b([^>]*\bclass=")([^"]*)(")/i, "<html$1$2 dark$3");
+  }
+  if (!html.includes("data-stx-theme-meta") && /<head\b[^>]*>/i.test(html)) {
+    const metas = [
+      '<meta name="color-scheme" content="dark light" data-stx-theme-meta="1">',
+      `<meta name="theme-color" media="(prefers-color-scheme: light)" content="${lightColor}" data-stx-theme-meta="1">`,
+      `<meta name="theme-color" media="(prefers-color-scheme: dark)" content="${darkColor}" data-stx-theme-meta="1">`
+    ].join(`
+  `);
+    html = html.replace(/<head\b([^>]*)>/i, `<head$1>
+  ${metas}`);
+  }
+  if (!colorModeOwnsTheme && !html.includes("__stxThemeGuard") && /<head\b[^>]*>/i.test(html)) {
+    const guard = `<script data-stx-theme-guard="1">${`window.__STX_COLOR_MODE__=window.__STX_COLOR_MODE__||${JSON.stringify({
+      storageKey,
+      initialMode: defaultTheme,
+      darkClass: "dark"
+    })};`}${FOUC_SCRIPT(defaultTheme, storageKey, lightColor, darkColor)};window.__stxThemeGuard=1;</script>`;
+    html = html.replace(/<head\b([^>]*)>/i, `<head$1>
+  ${guard}`);
+  }
+  if (!colorModeOwnsTheme && !html.includes("__stxThemeToggle") && /<\/body>/i.test(html)) {
+    const handler = `<script data-stx-theme-toggle="1">${TOGGLE_HANDLER(storageKey, lightColor, darkColor)};window.__stxThemeToggle=1;</script>`;
+    html = html.replace(/<\/body>/i, `${handler}
+</body>`);
+  }
+  return html;
+}

package/dist/site-builder/types.d.ts

@@ -0,0 +1,74 @@
+export declare interface SiteSeo {
+  title?: string
+  description?: string
+  siteName?: string
+  image?: string
+  twitter?: string
+  locale?: string
+  type?: string
+  favicon?: string
+}
+export declare interface SiteSocial {
+  twitter?: string
+  instagram?: string
+  youtube?: string
+  github?: string
+  linkedin?: string
+  [k: string]: string | undefined
+}
+export declare interface SiteConfig {
+  name: string
+  url: string
+  description?: string
+  social?: SiteSocial
+  seo?: SiteSeo
+  pagesDir?: string
+  excludeDirs?: string[]
+  publicDir?: string
+  outDir?: string
+  sitemap?: boolean
+  robots?: boolean | 'allow' | 'disallow' | string
+  pages?: Record<string, PageMeta>
+  spa?: boolean
+  router?: SiteRouterOptions
+  theme?: false | SiteThemeOptions
+  i18n?: SiteI18nOptions
+}
+export declare interface SiteI18nOptions {
+  locales: string[]
+  labels?: Record<string, string>
+  defaultLocale?: string
+  translations?: Record<string, Record<string, string>>
+  translationsDir?: string | false
+  format?: 'json' | 'yaml' | 'yml'
+  pickerSelector?: string
+}
+export declare interface SiteThemeOptions {
+  default?: 'dark' | 'light' | 'auto'
+  storageKey?: string
+}
+export declare interface PageMeta {
+  title?: string
+  description?: string
+  image?: string
+  sitemap?: boolean
+  priority?: number
+  changefreq?: 'always' | 'hourly' | 'daily' | 'weekly' | 'monthly' | 'yearly' | 'never'
+}
+export declare interface BuildOptions extends SiteConfig {
+  noClean?: boolean
+}
+/**
+ * SPA router options (subset — see RouterOptions in router.ts).
+ * Inlined to avoid a circular import in this types file.
+ */
+export declare interface SiteRouterOptions {
+  color?: string
+  progressColor?: string
+  progressHeight?: string
+  progress?: boolean
+  prefetch?: boolean
+  cache?: boolean
+  container?: string
+  interceptAllLinks?: boolean
+}

package/dist/site-url.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Where the canonical site URL comes from.
+ *
+ * The SSG defaulted `domain` to `http://localhost` and read no config at all,
+ * so an app that declared `url: 'https://example.org'` still shipped a
+ * sitemap.xml in which every entry was `http://localhost/…` — valid XML,
+ * accepted by the build, and useless to a crawler. Nothing warned, because
+ * from the build's point of view nothing failed (stacksjs/stx#1866).
+ *
+ * The URL is looked for in the places apps actually declare it, because there
+ * is more than one: `stx.config.ts` for stx-native apps, `site.config.ts` for
+ * the site-builder path (which has had `site.url` all along — that generator
+ * was never wired to this one), and the deploy-platform env vars, which are the
+ * only source available in CI where neither file knows the preview domain.
+ *
+ * @module site-url
+ */
+/** Where a resolved URL came from, for diagnostics. */
+export type SiteUrlSource = 'option' | 'stx.config' | 'site.config' | 'env' | 'fallback';
+export interface ResolvedSiteUrl {
+    url: string;
+    source: SiteUrlSource;
+    /** The env var or config key it came from, when there is one. */
+    via?: string;
+}
+/** Last resort. Deliberately not a real domain, so it is obvious in output. */
+export declare const SITE_URL_FALLBACK = "http://localhost";
+/**
+ * Resolve the canonical site URL, reporting where it came from so the caller
+ * can warn when it had to fall back.
+ *
+ * Order is explicit-option, then app config, then deploy env, then localhost.
+ */
+export declare function resolveSiteUrl(options?: {
+    explicit?: string;
+    stxConfig?: unknown;
+    cwd?: string;
+    env?: Record<string, string | undefined>;
+}): Promise<ResolvedSiteUrl>;
+/**
+ * The warning shown when a build produced localhost URLs.
+ *
+ * Loud, and it names the fix — a sitemap full of `http://localhost` is not
+ * something anyone notices by reading build output.
+ */
+export declare function siteUrlFallbackWarning(): string;

package/dist/site-url.js

@@ -0,0 +1,70 @@
+export const SITE_URL_FALLBACK = "http://localhost";
+const ENV_KEYS = ["STX_SITE_URL", "SITE_URL", "URL", "VERCEL_URL", "CF_PAGES_URL"];
+function normalize(raw) {
+  const trimmed = raw.trim();
+  if (!trimmed)
+    return null;
+  const withScheme = /^https?:\/\//i.test(trimmed) ? trimmed : `https://${trimmed}`;
+  try {
+    return new URL(withScheme).origin + new URL(withScheme).pathname.replace(/\/$/, "");
+  } catch {
+    return null;
+  }
+}
+function fromEnv(env) {
+  for (const key of ENV_KEYS) {
+    const value = env[key];
+    if (!value)
+      continue;
+    const url = normalize(value);
+    if (url)
+      return { url, source: "env", via: key };
+  }
+  return null;
+}
+function fromConfigObject(config) {
+  if (!config || typeof config !== "object")
+    return null;
+  const record = config, candidate = record.site?.url ?? record.url ?? record.app?.url;
+  return typeof candidate === "string" ? normalize(candidate) : null;
+}
+async function loadSiteConfigFile(cwd) {
+  const { existsSync } = await import("node:fs"), path = await import("node:path");
+  for (const name of ["site.config.ts", "site.config.js", ".config/site.config.ts"]) {
+    const file = path.resolve(cwd, name);
+    if (!existsSync(file))
+      continue;
+    try {
+      const module = await import(file), url = fromConfigObject(module.default ?? module);
+      if (url)
+        return url;
+    } catch {}
+  }
+  return null;
+}
+export async function resolveSiteUrl(options = {}) {
+  const cwd = options.cwd ?? process.cwd(), env = options.env ?? process.env;
+  if (options.explicit) {
+    const url = normalize(options.explicit);
+    if (url)
+      return { url, source: "option" };
+  }
+  const fromStx = fromConfigObject(options.stxConfig);
+  if (fromStx)
+    return { url: fromStx, source: "stx.config", via: "site.url" };
+  const fromSiteFile = await loadSiteConfigFile(cwd);
+  if (fromSiteFile)
+    return { url: fromSiteFile, source: "site.config", via: "url" };
+  const env_ = fromEnv(env);
+  if (env_)
+    return env_;
+  return { url: SITE_URL_FALLBACK, source: "fallback" };
+}
+export function siteUrlFallbackWarning() {
+  return [
+    "No site URL configured \u2014 sitemap.xml and robots.txt will point at http://localhost.",
+    "  Set one in stx.config.ts (site: { url: 'https://example.com' }), in site.config.ts,",
+    "  via --domain, or with SITE_URL in the build environment."
+  ].join(`
+`);
+}

package/dist/slots.d.ts

@@ -0,0 +1,129 @@
+/**
+ * STX Slots Module
+ *
+ * Provides Vue-style named slots and scoped slots support.
+ *
+ * @module slots
+ *
+ * ## Named Slots
+ *
+ * Parent component:
+ * ```html
+ * <Card>
+ *   <template #header>
+ *     <h1>Title</h1>
+ *   </template>
+ *
+ *   <p>Default slot content</p>
+ *
+ *   <template #footer>
+ *     <button>Submit</button>
+ *   </template>
+ * </Card>
+ * ```
+ *
+ * Child component (Card.stx):
+ * ```html
+ * <div class="card">
+ *   <header>
+ *     <slot name="header">Default Header</slot>
+ *   </header>
+ *   <main>
+ *     <slot />
+ *   </main>
+ *   <footer>
+ *     <slot name="footer" />
+ *   </footer>
+ * </div>
+ * ```
+ *
+ * ## Scoped Slots
+ *
+ * Parent component:
+ * ```html
+ * <DataTable :items="users">
+ *   <template #row="{ item, index }">
+ *     <td>{{ index + 1 }}</td>
+ *     <td>{{ item.name }}</td>
+ *   </template>
+ * </DataTable>
+ * ```
+ *
+ * Child component (DataTable.stx):
+ * ```html
+ * <table>
+ *   @foreach (items as item, index)
+ *     <tr>
+ *       <slot name="row" :item="item" :index="index">
+ *         <td>{{ item }}</td>
+ *       </slot>
+ *     </tr>
+ *   @endforeach
+ * </table>
+ * ```
+ */
+export interface SlotDefinition {
+    /** Slot name (empty string for default slot) */
+    name: string;
+    /** Slot content (the template) */
+    content: string;
+    /** Scoped slot props binding (e.g., "{ item, index }") */
+    propsBinding?: string;
+}
+export interface SlotProps {
+    [key: string]: unknown;
+}
+export interface ParsedSlots {
+    /** Default slot content */
+    default: string;
+    /** Named slots */
+    named: Map<string, SlotDefinition>;
+}
+/**
+ * Parse slot content from component children.
+ *
+ * Extracts:
+ * - Default slot content (anything not in a template#name)
+ * - Named slots from <template #name> or <template v-slot:name>
+ * - Scoped slot bindings from <template #name="{ props }">
+ */
+export declare function parseSlots(childContent: string): ParsedSlots;
+/**
+ * Parse slot props from a slot element.
+ *
+ * Parses: <slot name="row" :item="item" :index="index" />
+ * Returns: { name: 'row', props: { item: 'item', index: 'index' } }
+ */
+export declare function parseSlotElement(slotTag: string): {
+    name: string;
+    props: Record<string, string>;
+    defaultContent: string;
+};
+/**
+ * Render a slot with its content and props.
+ *
+ * @param slotDef - The slot definition from the parent
+ * @param slotProps - Props passed from the child's <slot :prop="value">
+ * @param defaultContent - Default content if no slot provided
+ * @param context - The current template context
+ */
+export declare function renderSlot(slotDef: SlotDefinition | undefined, slotProps: SlotProps, defaultContent: string, context: Record<string, unknown>): Promise<string>;
+/**
+ * Process all slots in a component template.
+ *
+ * Replaces <slot> elements with the appropriate content from parsed slots.
+ */
+export declare function processSlots(template: string, parsedSlots: ParsedSlots, context: Record<string, unknown>): Promise<string>;
+/**
+ * Extract named slots from component children content.
+ * This is called when processing a component to separate slot content.
+ */
+export declare function extractSlotContent(childContent: string): {
+    defaultSlot: string;
+    namedSlots: Map<string, SlotDefinition>;
+};
+/**
+ * Apply slots to a component template.
+ * This replaces <slot> elements with the provided slot content.
+ */
+export declare function applySlots(componentTemplate: string, defaultSlotContent: string, namedSlots: Map<string, SlotDefinition>, context: Record<string, unknown>): Promise<string>;