@pyreon/zero 0.15.0 → 0.18.0

package/lib/types/script.d.ts

@@ -1,4 +1,4 @@
-import { VNodeChild } from "@pyreon/core";
+import { Ref, VNodeChild } from "@pyreon/core";
 
 //#region src/script.d.ts
 interface ScriptProps {
@@ -12,14 +12,86 @@ interface ScriptProps {
   id?: string;
   /** Async attribute. Default: true */
   async?: boolean;
-  /** onLoad callback. */
+  /** onLoad callback — fires when the `<script>` finishes loading. */
   onLoad?: () => void;
-  /** onError callback. */
+  /** onError callback — fires when the `<script>` fails to load. */
   onError?: (error: Error) => void;
 }
 type ScriptStrategy = 'beforeHydration' | 'afterHydration' | 'onIdle' | 'onInteraction' | 'onViewport';
+/** Return type of {@link useScript}. */
+interface UseScriptReturn {
+  /** Ref — attach to the sentinel element for `onViewport` strategy. Undefined for other strategies. */
+  sentinelRef: Ref<HTMLElement> | undefined;
+  /** Whether the script has finished loading (onLoad fired). */
+  loaded: () => boolean;
+  /** Whether the script load failed (onError fired). */
+  errored: () => boolean;
+  /** Whether the script is in the strategy state machine awaiting a trigger (idle/interaction/viewport). */
+  pending: () => boolean;
+  /** Whether the consumer needs to render a sentinel element (only true for `onViewport`). */
+  needsSentinel: boolean;
+  /** Imperatively trigger the script load. Already invoked automatically by the strategy. */
+  load: () => void;
+}
+/** Props passed to a custom component via {@link createScript}. */
+interface ScriptRenderProps {
+  /** Ref — attach to whatever sentinel element you render (only matters for `onViewport`). */
+  sentinelRef: Ref<HTMLElement> | undefined;
+  /** Whether the script is in viewport-wait mode (true → render a sentinel; false → render null). */
+  needsSentinel: boolean;
+  /** Whether the script has finished loading (onLoad fired). */
+  loaded: () => boolean;
+  /** Whether the script load failed (onError fired). */
+  errored: () => boolean;
+  /** Whether the script is in the strategy state machine awaiting a trigger. */
+  pending: () => boolean;
+}
+/**
+ * Composable that provides all script loading behavior — strategy state
+ * machine (afterHydration / onIdle / onInteraction / onViewport),
+ * deduplication, load/error tracking.
+ *
+ * Returns reactive signals (`loaded`, `errored`, `pending`) so consumers
+ * can render loading indicators, retry buttons, or analytics-readiness
+ * gates without re-implementing the strategy machine.
+ *
+ * @example
+ * function MyScript(props: ScriptProps) {
+ *   const s = useScript(props)
+ *   return (
+ *     <>
+ *       {() => s.loaded() ? <Analytics /> : <Skeleton />}
+ *       {() => s.needsSentinel && <div ref={s.sentinelRef} style="width:0;height:0" />}
+ *     </>
+ *   )
+ * }
+ */
+declare function useScript(props: ScriptProps): UseScriptReturn;
+/**
+ * Higher-order component that wraps any component with script load behavior.
+ *
+ * The wrapped component receives {@link ScriptRenderProps} with the sentinel
+ * ref, load-state signals, and a `needsSentinel` flag. Use this when you want
+ * to render a loading indicator, retry button, or custom analytics-readiness
+ * gate around the script load.
+ *
+ * @example
+ * // Script with a loading indicator
+ * const TrackedScript = createScript((props) => (
+ *   <>
+ *     {() => props.pending() && <Spinner />}
+ *     {() => props.errored() && <button onClick={() => location.reload()}>Retry</button>}
+ *     {props.needsSentinel && <div ref={props.sentinelRef} style="width:0;height:0" />}
+ *   </>
+ * ))
+ *
+ * <TrackedScript src="/analytics.js" strategy="onIdle" />
+ */
+declare function createScript(Component: (p: ScriptRenderProps) => any): (props: ScriptProps) => any;
 /**
- * Optimized script loading component.
+ * Default optimized script component. Renders a 0×0 sentinel `<div>` for the
+ * `onViewport` strategy (so IntersectionObserver has an element to observe),
+ * `null` for every other strategy.
  *
  * @example
  * // Load analytics after page is interactive
@@ -33,7 +105,7 @@ type ScriptStrategy = 'beforeHydration' | 'afterHydration' | 'onIdle' | 'onInter
  *   {`console.log("App hydrated!")`}
  * </Script>
  */
-declare function Script(props: ScriptProps): VNodeChild;
+declare const Script: (props: ScriptProps) => VNodeChild;
 //#endregion
-export { Script, ScriptProps, ScriptStrategy };
+export { Script, ScriptProps, ScriptRenderProps, ScriptStrategy, UseScriptReturn, createScript, useScript };
 //# sourceMappingURL=script2.d.ts.map

package/lib/types/seo.d.ts

@@ -1,6 +1,19 @@
 import { Middleware } from "@pyreon/server";
 import { Plugin } from "vite";
-
+//#region src/i18n-routing.d.ts
+interface I18nRoutingConfig {
+  /** Supported locales. e.g. ["en", "de", "cs"] */
+  locales: string[];
+  /** Default locale — served without prefix (/ instead of /en/). */
+  defaultLocale: string;
+  /** Redirect root to detected locale. Default: true */
+  detectLocale?: boolean;
+  /** Cookie name to persist locale preference. Default: "locale" */
+  cookieName?: string;
+  /** URL strategy. Default: "prefix-except-default" */
+  strategy?: 'prefix' | 'prefix-except-default';
+}
+//#endregion
 //#region src/seo.d.ts
 interface SitemapConfig {
   /** Base URL of the site (required). e.g. "https://example.com" */
@@ -13,6 +26,62 @@ interface SitemapConfig {
   priority?: number;
   /** Additional URLs to include (for dynamic routes). */
   additionalPaths?: SitemapEntry[];
+  /**
+   * When `true` AND the build is running in SSG mode, the sitemap reads
+   * the resolved-paths manifest emitted by the SSG plugin
+   * (`dist/_pyreon-ssg-paths.json`) and includes EVERY prerendered URL —
+   * including dynamic routes enumerated via `getStaticPaths` (PR A) and
+   * per-locale variants (PR H, when shipped). Without this flag the
+   * sitemap walks the file-system route tree directly and silently
+   * skips dynamic routes (`[id]` / `[...slug]`) because their concrete
+   * values aren't knowable without running each route's enumerator.
+   *
+   * Sequencing: when `true`, sitemap.xml emission moves from Vite's
+   * `generateBundle` hook (where the SSG plugin's path enumeration
+   * hasn't run yet) to `closeBundle` with `enforce: 'post'` so it
+   * runs AFTER the SSG plugin. The user must ensure `seoPlugin()` is
+   * placed AFTER `zero()` in the Vite plugin array (the canonical
+   * ordering — `closeBundle` hooks fire in plugin-registration order).
+   *
+   * Falls back gracefully: when the manifest doesn't exist (mode is
+   * not `ssg`, or the SSG step was skipped), the sitemap still walks
+   * the file-system routes — same shape as without this flag.
+   *
+   * Default: `false` (preserves prior behaviour). Set `true` for SSG
+   * sites that ship dynamic-route enumerations.
+   */
+  useSsgPaths?: boolean;
+  /**
+   * Emit `<xhtml:link rel="alternate" hreflang="...">` cross-references
+   * inside each `<url>` entry, declaring the locale variants of every
+   * page (PR K — i18n follow-up).
+   *
+   * Accepts:
+   *   - `true` — read the i18n config from the SSG paths manifest
+   *     (which `zero({ i18n: ... })` automatically embeds when SSG runs).
+   *     Zero-config win — declare i18n once, sitemap picks it up.
+   *   - `I18nRoutingConfig` — pass the i18n config explicitly. Use when
+   *     the project doesn't run SSG (file-scan sitemap path) but still
+   *     wants hreflang in the emitted sitemap.
+   *   - `false` / omitted — no hreflang, plain `<url>` entries.
+   *
+   * The emitted shape per page-cluster is the Google-recommended form:
+   *
+   *   <url>
+   *     <loc>https://example.com/about</loc>
+   *     <xhtml:link rel="alternate" hreflang="en" href="https://example.com/about"/>
+   *     <xhtml:link rel="alternate" hreflang="de" href="https://example.com/de/about"/>
+   *     <xhtml:link rel="alternate" hreflang="cs" href="https://example.com/cs/about"/>
+   *     <xhtml:link rel="alternate" hreflang="x-default" href="https://example.com/about"/>
+   *   </url>
+   *
+   * The `x-default` entry points at the default-locale URL so search
+   * engines have a fallback when the user's language doesn't match any
+   * of the configured locales. URLs are clustered by their un-prefixed
+   * (default-locale) form — `/about`, `/de/about`, `/cs/about` collapse
+   * into ONE `<url>` entry with three `xhtml:link` siblings.
+   */
+  hreflang?: boolean | I18nRoutingConfig;
 }
 interface SitemapEntry {
   path: string;
@@ -23,8 +92,60 @@ interface SitemapEntry {
 type ChangeFreq = 'always' | 'hourly' | 'daily' | 'weekly' | 'monthly' | 'yearly' | 'never';
 /**
  * Generate a sitemap.xml string from route file paths.
+ *
+ * When `i18n` is set (PR K — passed by `seoPlugin` after reading the
+ * i18n config from `zero({ i18n: ... })`), URLs are clustered by their
+ * un-prefixed (default-locale) form and each `<url>` carries
+ * `<xhtml:link rel="alternate" hreflang="...">` siblings for every
+ * locale variant + an `x-default` entry pointing at the default locale.
+ */
+declare function generateSitemap(routeFiles: string[], config: SitemapConfig, i18n?: I18nRoutingConfig): string;
+/**
+ * Cluster URL entries by their un-prefixed (default-locale) form.
+ *
+ * Each output cluster has:
+ *   - `canonical`: the SitemapEntry that should be used as the `<url>`
+ *     payload (default-locale variant; falls back to the first variant
+ *     if no default-locale entry exists in the cluster).
+ *   - `variantsByLocale`: Map of locale → SitemapEntry for the cluster.
+ *
+ * Without i18n, every entry becomes its own single-variant cluster.
+ *
+ * @internal — exported for unit testing.
+ */
+declare function clusterPathsByLocale(entries: SitemapEntry[], i18n: I18nRoutingConfig | undefined): Cluster[];
+/** A URL cluster — the canonical entry + per-locale variants. @internal */
+interface Cluster {
+  canonical: SitemapEntry;
+  variantsByLocale: Map<string | null, SitemapEntry>;
+}
+/**
+ * Strip the locale prefix from a path under the i18n strategy.
+ *
+ * Returns `{ unPrefixed, locale }`:
+ *   - `/about` under `prefix-except-default` (default=en) → `{ unPrefixed: '/about', locale: 'en' }`
+ *   - `/de/about` under either strategy → `{ unPrefixed: '/about', locale: 'de' }`
+ *   - `/de` (locale root) → `{ unPrefixed: '/', locale: 'de' }`
+ *   - `/about` under `prefix` → no locale match, returns `{ unPrefixed: '/about', locale: null }`
+ *     (the URL doesn't fit any locale subtree — sitemap treats it as standalone).
+ *
+ * @internal — exported for unit testing.
+ */
+declare function stripLocalePrefix(path: string, locales: readonly string[], defaultLocale: string, strategy: 'prefix' | 'prefix-except-default'): {
+  unPrefixed: string;
+  locale: string | null;
+};
+/**
+ * Resolve the i18n config to feed `generateSitemap` for hreflang
+ * emission. Priority order:
+ *   1. Explicit user config — `hreflang: I18nRoutingConfig` (object)
+ *   2. Auto-detect from SSG manifest — `hreflang: true` + `manifestI18n`
+ *      present (only happens in SSG mode where the manifest exists)
+ *   3. Nothing — emit plain sitemap without xhtml:link siblings
+ *
+ * @internal — exported for unit testing.
  */
-declare function generateSitemap(routeFiles: string[], config: SitemapConfig): string;
+declare function resolveHreflangI18n(hreflang: boolean | I18nRoutingConfig | undefined, manifestI18n: I18nRoutingConfig | undefined): I18nRoutingConfig | undefined;
 interface RobotsConfig {
   /** Rules per user-agent. */
   rules?: RobotsRule[];
@@ -75,7 +196,10 @@ interface SeoPluginConfig {
  *     pyreon(),
  *     zero(),
  *     seoPlugin({
- *       sitemap: { origin: "https://example.com" },
+ *       sitemap: {
+ *         origin: "https://example.com",
+ *         useSsgPaths: true, // include dynamic-route enumerations
+ *       },
  *       robots: { sitemap: "https://example.com/sitemap.xml" },
  *     }),
  *   ],
@@ -88,5 +212,5 @@ declare function seoPlugin(config?: SeoPluginConfig): Plugin;
  */
 declare function seoMiddleware(config?: SeoPluginConfig): Middleware;
 //#endregion
-export { ChangeFreq, JsonLdType, RobotsConfig, RobotsRule, SeoPluginConfig, SitemapConfig, SitemapEntry, generateRobots, generateSitemap, jsonLd, seoMiddleware, seoPlugin };
+export { ChangeFreq, Cluster, JsonLdType, RobotsConfig, RobotsRule, SeoPluginConfig, SitemapConfig, SitemapEntry, clusterPathsByLocale, generateRobots, generateSitemap, jsonLd, resolveHreflangI18n, seoMiddleware, seoPlugin, stripLocalePrefix };
 //# sourceMappingURL=seo2.d.ts.map