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

package/dist/head.d.ts

@@ -0,0 +1,282 @@
+/**
+ * STX Head Management
+ *
+ * Manage document head (title, meta, links, scripts) with a simple API.
+ *
+ * @example
+ * ```typescript
+ * import { useHead, useSeoMeta, definePageMeta } from 'stx'
+ *
+ * // Full control
+ * useHead({
+ *   title: 'My Page',
+ *   meta: [{ name: 'description', content: '...' }]
+ * })
+ *
+ * // SEO shorthand
+ * useSeoMeta({
+ *   title: 'My Page',
+ *   description: 'Page description',
+ *   ogImage: '/og.png'
+ * })
+ *
+ * // Page configuration
+ * definePageMeta({
+ *   title: 'My Page',
+ *   layout: 'default'
+ * })
+ * ```
+ */
+export interface MetaTag {
+    name?: string;
+    property?: string;
+    content: string;
+    httpEquiv?: string;
+    charset?: string;
+}
+export interface LinkTag {
+    rel: string;
+    href: string;
+    type?: string;
+    sizes?: string;
+    crossorigin?: string;
+    as?: string;
+    media?: string;
+}
+export interface ScriptTag {
+    src?: string;
+    type?: string;
+    async?: boolean;
+    defer?: boolean;
+    content?: string;
+    id?: string;
+}
+export interface HeadConfig {
+    title?: string;
+    titleTemplate?: string | ((title: string) => string);
+    base?: {
+        href?: string;
+        target?: string;
+    };
+    meta?: MetaTag[];
+    link?: LinkTag[];
+    script?: ScriptTag[];
+    style?: {
+        content: string;
+        type?: string;
+    }[];
+    htmlAttrs?: Record<string, string>;
+    bodyAttrs?: Record<string, string>;
+}
+export interface SeoMeta {
+    title?: string;
+    titleTemplate?: string;
+    description?: string;
+    keywords?: string | string[];
+    author?: string;
+    robots?: string;
+    canonical?: string;
+    ogTitle?: string;
+    ogDescription?: string;
+    ogImage?: string;
+    ogUrl?: string;
+    ogType?: string;
+    ogSiteName?: string;
+    ogLocale?: string;
+    twitterCard?: 'summary' | 'summary_large_image' | 'app' | 'player';
+    twitterTitle?: string;
+    twitterDescription?: string;
+    twitterImage?: string;
+    twitterSite?: string;
+    twitterCreator?: string;
+    articleAuthor?: string;
+    articlePublishedTime?: string;
+    articleModifiedTime?: string;
+    articleSection?: string;
+    articleTags?: string[];
+}
+/**
+ * Layouts that exist on disk, augmented by the generated
+ * `<state-dir>/layout-types.d.ts` (stacksjs/stx#1879).
+ *
+ * Empty here on purpose. A project that has not generated the declaration —
+ * or has not added the state directory to its tsconfig — keeps `layout` typed
+ * as `string`, so nothing breaks; a project that has gets a type error for a
+ * name with no layout behind it.
+ */
+export interface KnownLayouts {
+}
+/**
+ * A layout name: the generated union when one is available, otherwise any
+ * string.
+ *
+ * `keyof KnownLayouts` is `never` while the interface is empty, which is what
+ * makes the fallback work.
+ */
+export type LayoutName = keyof KnownLayouts extends never ? string : keyof KnownLayouts;
+export interface PageMeta {
+    title?: string;
+    description?: string;
+    /** Static HTTP response status for this page. */
+    status?: number;
+    /**
+     * Layout for this page, by name (`'app'` → `<layoutsDir>/app.stx`), or
+     * `false` for none — the same as `@nolayout`.
+     *
+     * Precedence: `@extends`/`@layout` in the template wins, then this, then an
+     * auto-discovered `_layout.stx`, then `defaultLayout`.
+     *
+     * Do NOT hand-write `<meta name="stx-layout" content="…">` instead. That tag
+     * is stx *output*: the router reads it to decide between a fragment swap and
+     * a full-document swap, and a page asserting a group it does not belong to
+     * mis-routes rather than mis-styles. This field is the authoring surface; the
+     * meta tag is derived from the layout that actually resolved (#1879).
+     *
+     * Typed as the union of layouts on disk when the generated
+     * `<state-dir>/layout-types.d.ts` is in scope, so a typo is a type error
+     * rather than an unlayouted page.
+     */
+    layout?: LayoutName | false;
+    middleware?: string | string[];
+    transition?: string | {
+        name: string;
+        mode?: string;
+    };
+    keepAlive?: boolean;
+    key?: string | ((route: unknown) => string);
+    validate?: (route: {
+        params: Record<string, string>;
+    }) => boolean | Promise<boolean>;
+    [key: string]: unknown;
+}
+/**
+ * Get the current accumulated head config.
+ */
+export declare function getHead(): HeadConfig;
+/**
+ * Get current page meta.
+ */
+export declare function getPageMeta(): PageMeta;
+/**
+ * Reset head state (for SSR).
+ */
+export declare function resetHead(): void;
+/**
+ * Set document head configuration.
+ *
+ * @example
+ * ```typescript
+ * useHead({
+ *   title: 'My Page',
+ *   meta: [
+ *     { name: 'description', content: 'Page description' },
+ *     { property: 'og:image', content: '/og.png' }
+ *   ],
+ *   link: [
+ *     { rel: 'canonical', href: 'https://example.com/page' }
+ *   ],
+ *   script: [
+ *     { src: 'https://example.com/analytics.js', async: true }
+ *   ]
+ * })
+ * ```
+ */
+export declare function useHead(config: HeadConfig): void;
+/**
+ * Merge two head configs.
+ */
+export declare function mergeHeadConfigs(base: HeadConfig, override: HeadConfig): HeadConfig;
+/**
+ * Set SEO meta tags with a simplified API.
+ *
+ * @example
+ * ```typescript
+ * useSeoMeta({
+ *   title: 'My Page',
+ *   description: 'This is my awesome page',
+ *   ogImage: 'https://example.com/og.png',
+ *   twitterCard: 'summary_large_image'
+ * })
+ * ```
+ */
+export declare function useSeoMeta(config: SeoMeta): void;
+/**
+ * Convert SEO metadata into a head configuration without mutating global state.
+ */
+export declare function seoMetaToHeadConfig(config: SeoMeta): HeadConfig;
+/**
+ * Define page-level metadata.
+ *
+ * @example
+ * ```typescript
+ * definePageMeta({
+ *   title: 'Dashboard',
+ *   layout: 'admin',
+ *   middleware: ['auth', 'admin'],
+ *   keepAlive: true
+ * })
+ * ```
+ */
+export declare function definePageMeta(config: PageMeta): void;
+/**
+ * Set just the page title.
+ *
+ * @example
+ * ```typescript
+ * useTitle('My Page')
+ * useTitle(() => `${productName} - My Store`)
+ * ```
+ */
+export declare function usePageTitle(title: string | (() => string)): void;
+/**
+ * Render head config to HTML string.
+ */
+export declare function renderHead(config?: HeadConfig): string;
+/**
+ * Get HTML attributes string.
+ */
+export declare function renderHtmlAttrs(config?: HeadConfig): string;
+/**
+ * Get body attributes string.
+ */
+export declare function renderBodyAttrs(config?: HeadConfig): string;
+/**
+ * Apply head config to the actual document (client-side).
+ */
+export declare function applyHead(config?: HeadConfig): void;
+/**
+ * Process @head directive.
+ *
+ * @example
+ * ```html
+ * @head
+ *   <title>My Page</title>
+ *   <meta name="description" content="...">
+ * @endhead
+ * ```
+ */
+export declare function processHeadDirective(content: string): {
+    content: string;
+    headContent: string;
+};
+/**
+ * Process @title directive.
+ *
+ * @example
+ * ```html
+ * @title('My Page Title')
+ * @title(pageTitle)
+ * ```
+ */
+export declare function processTitleDirective(content: string, context: Record<string, unknown>): string;
+/**
+ * Process @meta directive.
+ *
+ * @example
+ * ```html
+ * @meta('description', 'Page description')
+ * @meta('og:image', ogImageUrl)
+ * ```
+ */
+export declare function processMetaDirective(content: string, context: Record<string, unknown>): string;
+export { usePageTitle as useTitle };

package/dist/head.js

@@ -0,0 +1,231 @@
+let currentHead = {};
+const headStack = [];
+let currentPageMeta = {};
+export function getHead() {
+  return currentHead;
+}
+export function getPageMeta() {
+  return currentPageMeta;
+}
+export function resetHead() {
+  currentHead = {};
+  headStack.length = 0;
+  currentPageMeta = {};
+}
+export function useHead(config) {
+  currentHead = mergeHeadConfigs(currentHead, config);
+}
+export function mergeHeadConfigs(base, override) {
+  return {
+    title: override.title ?? base.title,
+    titleTemplate: override.titleTemplate ?? base.titleTemplate,
+    base: override.base ?? base.base,
+    meta: [...base.meta || [], ...override.meta || []],
+    link: [...base.link || [], ...override.link || []],
+    script: [...base.script || [], ...override.script || []],
+    style: [...base.style || [], ...override.style || []],
+    htmlAttrs: { ...base.htmlAttrs, ...override.htmlAttrs },
+    bodyAttrs: { ...base.bodyAttrs, ...override.bodyAttrs }
+  };
+}
+export function useSeoMeta(config) {
+  useHead(seoMetaToHeadConfig(config));
+}
+export function seoMetaToHeadConfig(config) {
+  const meta = [];
+  if (config.description)
+    meta.push({ name: "description", content: config.description });
+  if (config.keywords) {
+    const keywords = Array.isArray(config.keywords) ? config.keywords.join(", ") : config.keywords;
+    meta.push({ name: "keywords", content: keywords });
+  }
+  if (config.author)
+    meta.push({ name: "author", content: config.author });
+  if (config.robots)
+    meta.push({ name: "robots", content: config.robots });
+  const ogTitle = config.ogTitle ?? config.title, ogDescription = config.ogDescription ?? config.description;
+  if (ogTitle)
+    meta.push({ property: "og:title", content: ogTitle });
+  if (ogDescription)
+    meta.push({ property: "og:description", content: ogDescription });
+  if (config.ogImage)
+    meta.push({ property: "og:image", content: config.ogImage });
+  if (config.ogUrl)
+    meta.push({ property: "og:url", content: config.ogUrl });
+  if (config.ogType)
+    meta.push({ property: "og:type", content: config.ogType });
+  if (config.ogSiteName)
+    meta.push({ property: "og:site_name", content: config.ogSiteName });
+  if (config.ogLocale)
+    meta.push({ property: "og:locale", content: config.ogLocale });
+  const twitterTitle = config.twitterTitle ?? config.title, twitterDescription = config.twitterDescription ?? config.description, twitterImage = config.twitterImage ?? config.ogImage;
+  if (config.twitterCard)
+    meta.push({ name: "twitter:card", content: config.twitterCard });
+  if (twitterTitle)
+    meta.push({ name: "twitter:title", content: twitterTitle });
+  if (twitterDescription)
+    meta.push({ name: "twitter:description", content: twitterDescription });
+  if (twitterImage)
+    meta.push({ name: "twitter:image", content: twitterImage });
+  if (config.twitterSite)
+    meta.push({ name: "twitter:site", content: config.twitterSite });
+  if (config.twitterCreator)
+    meta.push({ name: "twitter:creator", content: config.twitterCreator });
+  if (config.articleAuthor)
+    meta.push({ property: "article:author", content: config.articleAuthor });
+  if (config.articlePublishedTime)
+    meta.push({ property: "article:published_time", content: config.articlePublishedTime });
+  if (config.articleModifiedTime)
+    meta.push({ property: "article:modified_time", content: config.articleModifiedTime });
+  if (config.articleSection)
+    meta.push({ property: "article:section", content: config.articleSection });
+  if (config.articleTags)
+    for (const tag of config.articleTags)
+      meta.push({ property: "article:tag", content: tag });
+  const link = [];
+  if (config.canonical)
+    link.push({ rel: "canonical", href: config.canonical });
+  return {
+    title: config.title,
+    titleTemplate: config.titleTemplate,
+    meta,
+    link
+  };
+}
+export function definePageMeta(config) {
+  currentPageMeta = { ...currentPageMeta, ...config };
+  if (config.title || config.description)
+    useSeoMeta({
+      title: config.title,
+      description: config.description
+    });
+}
+export function usePageTitle(title) {
+  const resolvedTitle = typeof title === "function" ? title() : title;
+  useHead({ title: resolvedTitle });
+}
+export function renderHead(config = currentHead) {
+  const parts = [];
+  if (config.title) {
+    let title = config.title;
+    if (config.titleTemplate)
+      title = typeof config.titleTemplate === "function" ? config.titleTemplate(title) : config.titleTemplate.replace("%s", title);
+    parts.push(`<title>${escapeHtml(title)}</title>`);
+  }
+  if (config.base) {
+    const attrs = Object.entries(config.base).map(([k, v]) => `${k}="${escapeHtml(v)}"`).join(" ");
+    parts.push(`<base ${attrs}>`);
+  }
+  for (const meta of config.meta || []) {
+    const attrs = Object.entries(meta).filter(([_, v]) => v !== void 0).map(([k, v]) => {
+      return `${k === "httpEquiv" ? "http-equiv" : k}="${escapeHtml(String(v))}"`;
+    }).join(" ");
+    parts.push(`<meta ${attrs}>`);
+  }
+  for (const link of config.link || []) {
+    const attrs = Object.entries(link).filter(([_, v]) => v !== void 0).map(([k, v]) => `${k}="${escapeHtml(String(v))}"`).join(" ");
+    parts.push(`<link ${attrs}>`);
+  }
+  for (const script of config.script || []) {
+    const { content, ...attrs } = script, attrStr = Object.entries(attrs).filter(([_, v]) => v !== void 0).map(([k, v]) => {
+      if (typeof v === "boolean")
+        return v ? k : "";
+      return `${k}="${escapeHtml(String(v))}"`;
+    }).filter(Boolean).join(" ");
+    if (content)
+      parts.push(`<script ${attrStr}>${content}</script>`);
+    else
+      parts.push(`<script ${attrStr}></script>`);
+  }
+  for (const style of config.style || []) {
+    const type = style.type ? ` type="${style.type}"` : "";
+    parts.push(`<style${type}>${style.content}</style>`);
+  }
+  return parts.join(`
+`);
+}
+export function renderHtmlAttrs(config = currentHead) {
+  if (!config.htmlAttrs)
+    return "";
+  return Object.entries(config.htmlAttrs).map(([k, v]) => `${k}="${escapeHtml(v)}"`).join(" ");
+}
+export function renderBodyAttrs(config = currentHead) {
+  if (!config.bodyAttrs)
+    return "";
+  return Object.entries(config.bodyAttrs).map(([k, v]) => `${k}="${escapeHtml(v)}"`).join(" ");
+}
+function escapeHtml(str) {
+  return str.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#039;");
+}
+export function applyHead(config = currentHead) {
+  if (typeof document > "u")
+    return;
+  if (config.title) {
+    let title = config.title;
+    if (config.titleTemplate)
+      title = typeof config.titleTemplate === "function" ? config.titleTemplate(title) : config.titleTemplate.replace("%s", title);
+    document.title = title;
+  }
+  for (const meta of config.meta || []) {
+    const selector = meta.name ? `meta[name="${meta.name}"]` : meta.property ? `meta[property="${meta.property}"]` : null;
+    if (selector) {
+      let el = document.querySelector(selector);
+      if (!el) {
+        el = document.createElement("meta");
+        if (meta.name)
+          el.setAttribute("name", meta.name);
+        if (meta.property)
+          el.setAttribute("property", meta.property);
+        document.head.appendChild(el);
+      }
+      el.setAttribute("content", meta.content);
+    }
+  }
+  for (const link of config.link || []) {
+    const selector = `link[rel="${link.rel}"]${link.href ? `[href="${link.href}"]` : ""}`;
+    let el = document.querySelector(selector);
+    if (!el) {
+      el = document.createElement("link");
+      document.head.appendChild(el);
+    }
+    for (const [key, value] of Object.entries(link))
+      if (value !== void 0)
+        el.setAttribute(key, String(value));
+  }
+  if (config.htmlAttrs)
+    for (const [key, value] of Object.entries(config.htmlAttrs))
+      if (key === "class")
+        for (const cls of String(value).split(/\s+/).filter(Boolean))
+          document.documentElement.classList.add(cls);
+      else
+        document.documentElement.setAttribute(key, value);
+  if (config.bodyAttrs)
+    for (const [key, value] of Object.entries(config.bodyAttrs))
+      document.body.setAttribute(key, value);
+}
+export function processHeadDirective(content) {
+  let headContent = "";
+  return { content: content.replace(/@head\s*([\s\S]*?)@endhead/g, (_, inner) => {
+    headContent += inner.trim() + `
+`;
+    return "";
+  }), headContent: headContent.trim() };
+}
+export function processTitleDirective(content, context) {
+  return content.replace(/@title\s*\(\s*(?:(['"`])(.+?)\1|([^)]+))\s*\)/g, (_, quote, quotedTitle, unquotedTitle) => {
+    const resolvedTitle = quote ? quotedTitle : context[(unquotedTitle || "").trim()] ?? unquotedTitle, existing = context.__stx_runtime_head ?? {};
+    context.__stx_runtime_head = mergeHeadConfigs(existing, { title: resolvedTitle });
+    return "";
+  });
+}
+export function processMetaDirective(content, context) {
+  return content.replace(/@meta\s*\(\s*(['"`])(.+?)\1\s*,\s*(?:(['"`])(.+?)\3|([^)]+))\s*\)/g, (_, _q1, name, q2, quotedValue, unquotedValue) => {
+    const value = q2 ? quotedValue : unquotedValue, resolvedValue = q2 ? value : context[(value || "").trim()] ?? value, meta = name.includes(":") ? { property: name, content: resolvedValue } : { name, content: resolvedValue }, existing = context.__stx_runtime_head ?? {};
+    context.__stx_runtime_head = mergeHeadConfigs(existing, { meta: [meta] });
+    return "";
+  });
+}
+
+export {
+  usePageTitle as useTitle
+};