@pyreon/zero 0.15.0 → 0.18.0

package/src/image.tsx

@@ -1,4 +1,4 @@
-import type { VNodeChild } from '@pyreon/core'
+import type { Ref, VNodeChild } from '@pyreon/core'
 import { createRef } from '@pyreon/core'
 import { signal } from '@pyreon/reactivity'
 import type { FormatSource } from './image-plugin'
@@ -13,6 +13,12 @@ import { useIntersectionObserver } from './utils/use-intersection-observer'
 // - Multi-format support via <picture> (WebP/AVIF with fallback)
 // - Blur-up placeholder while loading
 // - Priority loading for above-the-fold images
+//
+// Three levels of API (mirrors @pyreon/zero/link):
+//
+// 1. useImage(props)   — composable returning resolved attributes + signals
+// 2. createImage(Comp) — HOC wrapping any component with image optimization
+// 3. Image             — default <div><img/></div> wrapper (built on createImage)
 
 export interface ImageProps {
   /** Image source URL. */
@@ -47,6 +53,9 @@ export interface ImageProps {
    * Raw mode — renders a plain `<img>` without the container div,
    * aspect-ratio, max-width, or lazy loading wrapper.
    * Use when the Image is inside a custom layout (absolute positioning, etc.).
+   *
+   * Note: `raw` skips the three-layer API entirely. `useImage` / `createImage`
+   * do not apply when `raw: true` — the component returns a bare `<img>`.
    */
   raw?: boolean
 }
@@ -56,37 +65,83 @@ export interface ImageSource {
   width: number
 }
 
+/** Return type of {@link useImage}. */
+export interface UseImageReturn {
+  /** Ref — attach to the container element for IntersectionObserver. */
+  containerRef: Ref<HTMLElement>
+  /** Whether the image has entered the viewport (and started loading). */
+  inView: () => boolean
+  /** Whether the `<img>` onLoad has fired. */
+  loaded: () => boolean
+  /** Resolved `src` accessor — empty string until inView, then `props.src`. */
+  src: () => string
+  /** Resolved srcSet accessor — empty until inView; empty when `formats` is set (srcset moves to `<source>` elements). */
+  srcSet: () => string
+  /** `sizes` attribute or undefined when no srcset. */
+  sizes: string | undefined
+  /** `aspect-ratio` CSS value (`"${width} / ${height}"`). */
+  aspectRatio: string
+  /** Resolved CSS for the container — position + overflow + aspect-ratio + max-width + caller's `style`. */
+  containerStyle: string
+  /** Resolved CSS accessor for the `<img>` — fit + transition + opacity (placeholder fade). */
+  imageStyle: () => string
+  /** Resolved CSS accessor for the placeholder `<img>` (only meaningful when `placeholder` is set). */
+  placeholderStyle: () => string
+  /** `loading` attribute — eager when priority/eager, else lazy. */
+  loading: 'lazy' | 'eager'
+  /** `fetchPriority` — 'high' when priority, else undefined. */
+  fetchPriority: 'high' | undefined
+  /** onLoad handler — sets the loaded signal. Wire into the rendered `<img>`. */
+  handleLoad: () => void
+  /** Resolved per-format <source> descriptors (or undefined when no formats). */
+  formats: FormatSource[] | undefined
+  /** Whether `formats` is non-empty (i.e. consumer should render a `<picture>` wrapper). */
+  hasFormats: boolean
+}
+
+/** Props passed to a custom component via {@link createImage}. */
+export interface ImageRenderProps {
+  /** Container ref. */
+  containerRef: Ref<HTMLElement>
+  /** CSS class for the container. */
+  class: string | undefined
+  /** Resolved container `style` string. */
+  containerStyle: string
+  /** Pre-rendered placeholder `<img>` (or `null` when `placeholder` is unset). */
+  placeholder: VNodeChild
+  /** Pre-rendered image — either a bare `<img>` or a `<picture>` tree when `formats` is set. */
+  image: VNodeChild
+}
+
 /**
- * Optimized image component with lazy loading, responsive images,
- * multi-format <picture> support, and blur-up placeholders.
+ * Composable that provides all image optimization behavior — lazy loading,
+ * srcset/sizes resolution, format selection, blur-placeholder state,
+ * load tracking.
  *
- * @example
- * // With imagePlugin — spread the import directly
- * import hero from "./hero.jpg?optimize"
- * <Image {...hero} alt="Hero" priority />
+ * Use this for full control when `createImage` is too opinionated about
+ * the surrounding markup (e.g. custom container layouts, non-`<div>`
+ * wrappers, additional overlay elements).
  *
  * @example
- * // Manual usage
- * <Image src="/hero.jpg" alt="Hero" width={1200} height={630} />
+ * function MyImage(props: ImageProps) {
+ *   const img = useImage(props)
+ *   return (
+ *     <figure ref={img.containerRef} style={img.containerStyle}>
+ *       <img
+ *         src={img.src}
+ *         srcSet={img.srcSet}
+ *         sizes={img.sizes}
+ *         alt={props.alt}
+ *         loading={img.loading}
+ *         onLoad={img.handleLoad}
+ *         style={img.imageStyle}
+ *       />
+ *       <figcaption>{props.alt}</figcaption>
+ *     </figure>
+ *   )
+ * }
  */
-export function Image(props: ImageProps): VNodeChild {
-  // Raw mode: plain <img> without container, lazy loading, or layout constraints
-  if (props.raw) {
-    return (
-      <img
-        src={props.src}
-        alt={props.alt}
-        width={props.width}
-        height={props.height}
-        class={props.class}
-        style={props.style}
-        decoding={props.decoding ?? 'async'}
-        loading={props.loading ?? 'lazy'}
-        fetchPriority={props.priority ? 'high' : undefined}
-      />
-    ) as any
-  }
-
+export function useImage(props: ImageProps): UseImageReturn {
   const isEager = props.priority || props.loading === 'eager'
   const loaded = signal(isEager)
   const inView = signal(isEager)
@@ -100,7 +155,7 @@ export function Image(props: ImageProps): VNodeChild {
 
   const sizes = props.sizes ?? '100vw'
   const fit = props.fit ?? 'cover'
-  const hasFormats = props.formats && props.formats.length > 0
+  const hasFormats = !!(props.formats && props.formats.length > 0)
   const aspectRatio = `${props.width} / ${props.height}`
 
   if (!isEager) {
@@ -110,7 +165,6 @@ export function Image(props: ImageProps): VNodeChild {
     )
   }
 
-  // Static styles (don't depend on signals)
   const containerStyle = [
     'position: relative',
     'overflow: hidden',
@@ -122,68 +176,165 @@ export function Image(props: ImageProps): VNodeChild {
     .filter(Boolean)
     .join('; ')
 
-  const imgEl = (
-    <img
-      src={() => (inView() ? props.src : '')}
-      srcSet={() => (!hasFormats && inView() && resolvedSrcset ? resolvedSrcset : '')}
-      sizes={resolvedSrcset ? sizes : undefined}
-      alt={props.alt}
-      width={props.width}
-      height={props.height}
-      loading={isEager ? 'eager' : 'lazy'}
-      decoding={props.decoding ?? 'async'}
-      fetchPriority={props.priority ? 'high' : undefined}
-      onLoad={() => loaded.set(true)}
-      style={() =>
-        [
-          'display: block',
-          'width: 100%',
-          'height: 100%',
-          `object-fit: ${fit}`,
-          'transition: opacity 0.3s ease',
-          props.placeholder && !loaded() ? 'opacity: 0' : 'opacity: 1',
-        ].join('; ')
-      }
-    />
-  )
-
-  return (
-    <div ref={containerRef} class={props.class} style={containerStyle}>
-      {props.placeholder && (
+  const imageStyle = () =>
+    [
+      'display: block',
+      'width: 100%',
+      'height: 100%',
+      `object-fit: ${fit}`,
+      'transition: opacity 0.3s ease',
+      props.placeholder && !loaded() ? 'opacity: 0' : 'opacity: 1',
+    ].join('; ')
+
+  const placeholderStyle = () =>
+    [
+      'position: absolute',
+      'inset: 0',
+      'width: 100%',
+      'height: 100%',
+      'object-fit: cover',
+      'filter: blur(20px)',
+      'transform: scale(1.1)',
+      'transition: opacity 0.4s ease',
+      loaded() ? 'opacity: 0; pointer-events: none' : 'opacity: 1',
+    ].join('; ')
+
+  return {
+    containerRef,
+    inView,
+    loaded,
+    src: () => (inView() ? props.src : ''),
+    srcSet: () => (!hasFormats && inView() && resolvedSrcset ? resolvedSrcset : ''),
+    sizes: resolvedSrcset ? sizes : undefined,
+    aspectRatio,
+    containerStyle,
+    imageStyle,
+    placeholderStyle,
+    loading: isEager ? 'eager' : 'lazy',
+    fetchPriority: props.priority ? 'high' : undefined,
+    handleLoad: () => loaded.set(true),
+    formats: props.formats,
+    hasFormats,
+  }
+}
+
+/**
+ * Higher-order component that wraps any component with image optimization.
+ *
+ * The wrapped component receives {@link ImageRenderProps} with the pre-rendered
+ * `image` JSX (bare `<img>` OR `<picture>` tree depending on formats), the
+ * pre-rendered `placeholder` JSX, and the container ref + styles. Consumers
+ * compose those pieces with whatever wrapper element / layout they want.
+ *
+ * @example
+ * // Custom figure-based image with caption
+ * const FigureImage = createImage((props) => (
+ *   <figure ref={props.containerRef} class={props.class} style={props.containerStyle}>
+ *     {props.placeholder}
+ *     {props.image}
+ *     <figcaption>Caption goes here</figcaption>
+ *   </figure>
+ * ))
+ *
+ * // Usage — identical to default <Image>
+ * <FigureImage src="/hero.jpg" alt="Hero" width={1200} height={630} />
+ */
+export function createImage(
+  Component: (p: ImageRenderProps) => any,
+): (props: ImageProps) => any {
+  return function WrappedImage(props: ImageProps) {
+    // `raw` mode short-circuits — returns a bare <img> with no optimization
+    // wrapper, no container, no createImage composition. Documented as the
+    // no-optimization escape hatch.
+    if (props.raw) {
+      return (
         <img
-          src={props.placeholder}
-          alt=""
-          aria-hidden="true"
-          loading="eager"
-          style={() =>
-            [
-              'position: absolute',
-              'inset: 0',
-              'width: 100%',
-              'height: 100%',
-              'object-fit: cover',
-              'filter: blur(20px)',
-              'transform: scale(1.1)',
-              'transition: opacity 0.4s ease',
-              loaded() ? 'opacity: 0; pointer-events: none' : 'opacity: 1',
-            ].join('; ')
-          }
+          src={props.src}
+          alt={props.alt}
+          width={props.width}
+          height={props.height}
+          class={props.class}
+          style={props.style}
+          decoding={props.decoding ?? 'async'}
+          loading={props.loading ?? 'lazy'}
+          fetchPriority={props.priority ? 'high' : undefined}
         />
-      )}
-      {hasFormats ? (
-        <picture>
-          {props.formats?.map((fmt) => (
-            <source
-              type={fmt.type}
-              srcSet={() => (inView() ? (fmt.srcset ?? '') : '')}
-              sizes={sizes}
-            />
-          ))}
-          {imgEl}
-        </picture>
-      ) : (
-        imgEl
-      )}
-    </div>
-  )
+      )
+    }
+
+    const img = useImage(props)
+
+    const imgEl = (
+      <img
+        src={img.src}
+        srcSet={img.srcSet}
+        sizes={img.sizes}
+        alt={props.alt}
+        width={props.width}
+        height={props.height}
+        loading={img.loading}
+        decoding={props.decoding ?? 'async'}
+        fetchPriority={img.fetchPriority}
+        onLoad={img.handleLoad}
+        style={img.imageStyle}
+      />
+    )
+
+    const placeholderEl = props.placeholder
+      ? (
+          <img
+            src={props.placeholder}
+            alt=""
+            aria-hidden="true"
+            loading="eager"
+            style={img.placeholderStyle}
+          />
+        )
+      : null
+
+    const imageEl = img.hasFormats
+      ? (
+          <picture>
+            {img.formats?.map((fmt) => (
+              <source
+                type={fmt.type}
+                srcSet={() => (img.inView() ? (fmt.srcset ?? '') : '')}
+                sizes={img.sizes}
+              />
+            ))}
+            {imgEl}
+          </picture>
+        )
+      : imgEl
+
+    return (
+      <Component
+        containerRef={img.containerRef}
+        class={props.class}
+        containerStyle={img.containerStyle}
+        placeholder={placeholderEl}
+        image={imageEl}
+      />
+    )
+  }
 }
+
+/**
+ * Default optimized image component with lazy loading, responsive srcset,
+ * `<picture>` multi-format support, and blur-up placeholders.
+ *
+ * @example
+ * // With imagePlugin — spread the import directly
+ * import hero from "./hero.jpg?optimize"
+ * <Image {...hero} alt="Hero" priority />
+ *
+ * @example
+ * // Manual usage
+ * <Image src="/hero.jpg" alt="Hero" width={1200} height={630} />
+ */
+export const Image: (props: ImageProps) => any = createImage((props) => (
+  <div ref={props.containerRef} class={props.class} style={props.containerStyle}>
+    {props.placeholder}
+    {props.image}
+  </div>
+))

package/src/index.ts

@@ -13,12 +13,12 @@
 
 // ─── Components (browser-safe) ──────────────────────────────────────────────
 
-export type { ImageProps, ImageSource } from "./image";
-export { Image } from "./image";
+export type { ImageProps, ImageRenderProps, ImageSource, UseImageReturn } from "./image";
+export { createImage, Image, useImage } from "./image";
 export type { LinkProps, LinkRenderProps, UseLinkReturn } from "./link";
 export { createLink, Link, prefetchRoute, useLink } from "./link";
-export type { ScriptProps, ScriptStrategy } from "./script";
-export { Script } from "./script";
+export type { ScriptProps, ScriptRenderProps, ScriptStrategy, UseScriptReturn } from "./script";
+export { createScript, Script, useScript } from "./script";
 export type { MetaProps } from "./meta";
 export { buildMetaTags, Meta } from "./meta";
 

package/src/isr.ts

@@ -29,6 +29,14 @@ export function createISRHandler(
   const revalidating = new Set<string>()
   const revalidateMs = config.revalidate * 1000
   const maxEntries = Math.max(1, config.maxEntries ?? 1000)
+  // M1.1 — cache-key derivation. Default keys by pathname only (the
+  // pre-M1 behaviour). User-supplied `cacheKey` opts in to varying
+  // by cookies / query / headers — required for auth-gated pages.
+  // See `ISRConfig.cacheKey` JSDoc for the auth-incompatibility caveat.
+  const deriveKey: (req: Request, url: URL) => string
+    = typeof config.cacheKey === 'function'
+      ? (req, _url) => (config.cacheKey as (r: Request) => string)(req)
+      : (_req, url) => url.pathname
 
   function set(key: string, entry: CacheEntry): void {
     // LRU: re-inserting moves the key to the newest position. Then if we're
@@ -51,13 +59,23 @@ export function createISRHandler(
     return entry
   }
 
-  async function revalidate(url: URL) {
-    const key = url.pathname
+  async function revalidate(url: URL, originalReq: Request) {
+    // Re-derive key from the ORIGINAL request so cookies / headers /
+    // query that varied the cache entry are preserved across revalidation.
+    // Without this, a user-supplied `cacheKey` that reads cookies would
+    // re-render against a no-cookie request and stomp the cached entry
+    // with the wrong-user content.
+    const key = deriveKey(originalReq, url)
     if (revalidating.has(key)) return
     revalidating.add(key)
 
     try {
-      const req = new Request(url.href, { method: 'GET' })
+      // Forward the original request shape (headers + method) so the
+      // re-render sees the same auth context as the user's read.
+      const req = new Request(url.href, {
+        method: 'GET',
+        headers: originalReq.headers,
+      })
       const res = await handler(req)
       const html = await res.text()
       const headers: Record<string, string> = {}
@@ -80,7 +98,7 @@ export function createISRHandler(
     }
 
     const url = new URL(req.url)
-    const key = url.pathname
+    const key = deriveKey(req, url)
     // `touch` moves the entry to the newest LRU position on read so
     // hot paths survive eviction even when the cap is small. `get`
     // wouldn't update ordering.
@@ -91,7 +109,7 @@ export function createISRHandler(
 
       if (age > revalidateMs) {
         // Stale — serve cached but revalidate in background
-        revalidate(url)
+        revalidate(url, req)
       }
 
       return new Response(entry.html, {
@@ -113,7 +131,7 @@ export function createISRHandler(
       headers[k] = v
     })
 
-    cache.set(key, { html, headers, timestamp: Date.now() })
+    set(key, { html, headers, timestamp: Date.now() })
 
     return new Response(html, {
       status: 200,