@pyreon/zero 0.11.8 → 0.11.9

package/src/meta.tsx

@@ -0,0 +1,210 @@
+import type { VNodeChild } from '@pyreon/core'
+import { useHead } from '@pyreon/head'
+import type { I18nRoutingConfig } from './i18n-routing'
+import { extractLocaleFromPath } from './i18n-routing'
+
+// ─── Meta component ────────────────────────────────────────────────────────
+
+export interface MetaProps {
+  /** Page title. Accepts reactive accessor `() => string`. */
+  title?: string | (() => string)
+  /** Page description. Accepts reactive accessor. */
+  description?: string | (() => string)
+  /** Canonical URL. Also sets og:url. */
+  canonical?: string
+  /** Open Graph image URL. Also sets twitter:image. */
+  image?: string
+  /** Image alt text for accessibility. */
+  imageAlt?: string
+  /** Open Graph type. Default: "website" */
+  type?: 'website' | 'article' | 'product' | 'profile'
+  /** Site name for og:site_name. */
+  siteName?: string
+  /** Twitter card type. Default: "summary_large_image" */
+  twitterCard?: 'summary' | 'summary_large_image' | 'app' | 'player'
+  /** Twitter @handle. */
+  twitterSite?: string
+  /** Twitter creator @handle. */
+  twitterCreator?: string
+  /** Locale. Default: "en_US" */
+  locale?: string
+  /** Alternate locales for hreflang. */
+  alternateLocales?: Array<{ locale: string; url: string }>
+  /** Robots directives. Default: "index, follow" */
+  robots?: string
+  /** Published time (ISO 8601) for article type. */
+  publishedTime?: string
+  /** Modified time (ISO 8601) for article type. */
+  modifiedTime?: string
+  /** Article author. */
+  author?: string
+  /** Article tags. */
+  tags?: string[]
+  /** JSON-LD structured data object. */
+  jsonLd?: Record<string, unknown>
+  /** Additional custom meta tags. */
+  extra?: Array<{ name?: string; property?: string; content: string }>
+  /**
+   * I18n routing config — when provided, auto-generates hreflang alternate
+   * links for all locales based on the current path.
+   * Also sets og:locale and og:locale:alternate.
+   */
+  i18n?: I18nRoutingConfig
+  /** Base URL for building absolute hreflang URLs. e.g. "https://example.com" */
+  origin?: string
+  children?: VNodeChild
+}
+
+const resolveStr = (v: string | (() => string) | undefined): string | undefined =>
+  typeof v === 'function' ? v() : v
+
+/**
+ * Declarative meta component for SSR-compatible page metadata.
+ *
+ * Supports reactive title/description — when passed as `() => string` accessors,
+ * they are forwarded to `useHead()` as a reactive getter so updates propagate
+ * automatically via signal tracking.
+ *
+ * @example
+ * ```tsx
+ * <Meta title="My Page" description="..." image="/og.jpg" canonical="https://..." />
+ * ```
+ *
+ * @example Reactive title
+ * ```tsx
+ * const count = signal(0)
+ * <Meta title={() => `${count()} items`} />
+ * ```
+ */
+export function Meta(props: MetaProps): VNodeChild {
+  const hasReactiveTitle = typeof props.title === 'function'
+  const hasReactiveDescription = typeof props.description === 'function'
+
+  // If title or description are reactive accessors, pass a getter to useHead
+  // so it re-evaluates when the signals change.
+  if (hasReactiveTitle || hasReactiveDescription) {
+    useHead((() => {
+      const title = resolveStr(props.title)
+      const description = resolveStr(props.description)
+      const tags = buildMetaTags({ ...props, title, description } as any)
+      return { title, meta: tags.meta, link: tags.link, script: tags.script }
+    }) as any)
+  } else {
+    const title = resolveStr(props.title)
+    const description = resolveStr(props.description)
+    const tags = buildMetaTags({ ...props, title, description } as any)
+    useHead({ title, meta: tags.meta, link: tags.link, script: tags.script } as any)
+  }
+
+  return props.children ?? null
+}
+
+interface MetaTags {
+  meta: Array<Record<string, string>>
+  link: Array<Record<string, string>>
+  script: Array<{ type: string; children: string }>
+}
+
+export function buildMetaTags(
+  props: Omit<MetaProps, 'title' | 'description' | 'children'> & {
+    title?: string
+    description?: string
+  },
+): MetaTags {
+  const meta: Array<Record<string, string>> = []
+  const link: Array<Record<string, string>> = []
+  const script: Array<{ type: string; children: string }> = []
+
+  const {
+    title, description, canonical, image, imageAlt,
+    type = 'website', siteName,
+    twitterCard = 'summary_large_image', twitterSite, twitterCreator,
+    locale = 'en_US', alternateLocales,
+    robots = 'index, follow',
+    publishedTime, modifiedTime, author, tags, jsonLd, extra,
+  } = props
+
+  if (description) meta.push({ name: 'description', content: description })
+  if (robots) meta.push({ name: 'robots', content: robots })
+  if (author) meta.push({ name: 'author', content: author })
+
+  if (title) meta.push({ property: 'og:title', content: title })
+  if (description) meta.push({ property: 'og:description', content: description })
+  if (canonical) meta.push({ property: 'og:url', content: canonical })
+  if (image) meta.push({ property: 'og:image', content: image })
+  if (imageAlt) meta.push({ property: 'og:image:alt', content: imageAlt })
+  meta.push({ property: 'og:type', content: type })
+  if (siteName) meta.push({ property: 'og:site_name', content: siteName })
+  meta.push({ property: 'og:locale', content: locale })
+
+  if (type === 'article') {
+    if (publishedTime) meta.push({ property: 'article:published_time', content: publishedTime })
+    if (modifiedTime) meta.push({ property: 'article:modified_time', content: modifiedTime })
+    if (author) meta.push({ property: 'article:author', content: author })
+    if (tags) for (const tag of tags) meta.push({ property: 'article:tag', content: tag })
+  }
+
+  meta.push({ name: 'twitter:card', content: twitterCard })
+  if (title) meta.push({ name: 'twitter:title', content: title })
+  if (description) meta.push({ name: 'twitter:description', content: description })
+  if (image) meta.push({ name: 'twitter:image', content: image })
+  if (imageAlt) meta.push({ name: 'twitter:image:alt', content: imageAlt })
+  if (twitterSite) meta.push({ name: 'twitter:site', content: twitterSite })
+  if (twitterCreator) meta.push({ name: 'twitter:creator', content: twitterCreator })
+
+  if (canonical) link.push({ rel: 'canonical', href: canonical })
+  if (alternateLocales) {
+    for (const alt of alternateLocales) {
+      link.push({ rel: 'alternate', hreflang: alt.locale, href: alt.url })
+    }
+  }
+
+  if (jsonLd) {
+    script.push({
+      type: 'application/ld+json',
+      children: JSON.stringify({ '@context': 'https://schema.org', ...jsonLd }),
+    })
+  }
+
+  if (extra) for (const tag of extra) meta.push(tag)
+
+  // I18n: auto-generate hreflang alternates from i18nRouting config
+  if (props.i18n) {
+    const i18nConfig = props.i18n
+    const origin = props.origin ?? ''
+    const currentPath = canonical?.replace(origin, '') ?? '/'
+    const { pathWithoutLocale } = extractLocaleFromPath(
+      currentPath,
+      i18nConfig.locales,
+      i18nConfig.defaultLocale,
+    )
+    const strategy = i18nConfig.strategy ?? 'prefix-except-default'
+
+    for (const loc of i18nConfig.locales) {
+      const localizedPath =
+        strategy === 'prefix-except-default' && loc === i18nConfig.defaultLocale
+          ? pathWithoutLocale
+          : `/${loc}${pathWithoutLocale === '/' ? '' : pathWithoutLocale}`
+
+      link.push({
+        rel: 'alternate',
+        hreflang: loc,
+        href: `${origin}${localizedPath}`,
+      })
+
+      // og:locale:alternate for non-current locales
+      if (loc !== locale) {
+        meta.push({ property: 'og:locale:alternate', content: loc })
+      }
+    }
+
+    // x-default hreflang pointing to default locale
+    link.push({
+      rel: 'alternate',
+      hreflang: 'x-default',
+      href: `${origin}${pathWithoutLocale}`,
+    })
+  }
+
+  return { meta, link, script }
+}

package/src/middleware.ts

@@ -0,0 +1,65 @@
+import type { Middleware, MiddlewareContext } from '@pyreon/server'
+
+// ─── Middleware composition ─────────────────────────────────────────────────
+//
+// Chains multiple middleware functions into a single middleware.
+// Each middleware runs in order. If any returns a Response, the chain
+// short-circuits and that Response is returned. If all return void,
+// the composed middleware returns void (continues to rendering).
+
+/**
+ * Compose multiple middleware into a single middleware function.
+ * Middleware runs sequentially — if any returns a Response, the chain stops.
+ *
+ * @example
+ * import { compose } from "@pyreon/zero/middleware"
+ * import { corsMiddleware } from "@pyreon/zero/cors"
+ * import { rateLimitMiddleware } from "@pyreon/zero/rate-limit"
+ *
+ * const combined = compose(
+ *   corsMiddleware({ origin: "*" }),
+ *   rateLimitMiddleware({ max: 100 }),
+ *   cacheMiddleware(),
+ * )
+ */
+export function compose(...middlewares: Middleware[]): Middleware {
+  return async (ctx: MiddlewareContext) => {
+    for (const mw of middlewares) {
+      const result = await mw(ctx)
+      if (result instanceof Response) return result
+    }
+  }
+}
+
+// ─── Shared request context ─────────────────────────────────────────────────
+//
+// Lightweight context bag attached to MiddlewareContext.locals so middleware
+// can communicate without coupling. Uses a namespaced key to avoid collisions
+// with user-defined locals.
+
+const ZERO_CTX_KEY = '__zeroCtx'
+
+/**
+ * Get the shared Zero context from a middleware context.
+ * Creates one if it doesn't exist. Middleware can use this to
+ * pass data to downstream middleware without polluting `ctx.locals`.
+ *
+ * @example
+ * const authMiddleware: Middleware = (ctx) => {
+ *   const zctx = getContext(ctx)
+ *   zctx.userId = "user_123"
+ * }
+ *
+ * const loggingMiddleware: Middleware = (ctx) => {
+ *   const zctx = getContext(ctx)
+ *   console.log("User:", zctx.userId)
+ * }
+ */
+export function getContext(ctx: MiddlewareContext): Record<string, unknown> {
+  let zctx = ctx.locals[ZERO_CTX_KEY] as Record<string, unknown> | undefined
+  if (!zctx) {
+    zctx = {}
+    ctx.locals[ZERO_CTX_KEY] = zctx
+  }
+  return zctx
+}

package/src/not-found.ts

@@ -0,0 +1,44 @@
+import type { ComponentFn } from "@pyreon/core";
+import { h } from "@pyreon/core";
+import { renderToString } from "@pyreon/runtime-server";
+
+// ─── 404 Not Found rendering ────────────────────────────────────────────────
+//
+// Shared utility for rendering 404 pages in both dev (vite-plugin) and
+// production (entry-server). Renders the notFoundComponent into HTML
+// and wraps it in a minimal document if no template is provided.
+
+const DEFAULT_404_BODY =
+	"<h1>404 — Not Found</h1><p>The page you requested does not exist.</p>";
+
+/**
+ * Render a 404 component to a full HTML string.
+ * If no component is provided, returns a default 404 page.
+ */
+export async function render404Page(
+	component: ComponentFn | undefined,
+	template?: string,
+): Promise<string> {
+	let body: string;
+	if (component) {
+		body = await renderToString(h(component, null));
+	} else {
+		body = DEFAULT_404_BODY;
+	}
+
+	if (template?.includes("<!--pyreon-app-->")) {
+		return template.replace("<!--pyreon-app-->", body);
+	}
+
+	return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>404 — Not Found</title>
+</head>
+<body>
+  ${body}
+</body>
+</html>`;
+}

package/src/types.ts

@@ -105,6 +105,8 @@ export interface FileRoute {
   isError: boolean
   /** Whether this is a loading fallback file. */
   isLoading: boolean
+  /** Whether this is a not-found (404) file. */
+  isNotFound: boolean
   /** Whether this is a catch-all route. */
   isCatchAll: boolean
   /** Resolved rendering mode. */