@pyreon/zero 0.14.0 → 0.16.0

package/lib/types/image.d.ts

@@ -1,4 +1,4 @@
-import { VNodeChild } from "@pyreon/core";
+import { Ref, VNodeChild } from "@pyreon/core";
 //#region src/image-plugin.d.ts
 /** Per-format source set for <picture> <source> elements. */
 interface FormatSource {
@@ -42,6 +42,9 @@ 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;
 }
@@ -49,9 +52,106 @@ interface ImageSource {
   src: string;
   width: number;
 }
+/** Return type of {@link useImage}. */
+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}. */
+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;
+}
+/**
+ * Composable that provides all image optimization behavior — lazy loading,
+ * srcset/sizes resolution, format selection, blur-placeholder state,
+ * load tracking.
+ *
+ * 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
+ * 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>
+ *   )
+ * }
+ */
+declare function useImage(props: ImageProps): UseImageReturn;
+/**
+ * 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} />
+ */
+declare function createImage(Component: (p: ImageRenderProps) => any): (props: ImageProps) => any;
 /**
- * Optimized image component with lazy loading, responsive images,
- * multi-format <picture> support, and blur-up placeholders.
+ * Default optimized image component with lazy loading, responsive srcset,
+ * `<picture>` multi-format support, and blur-up placeholders.
  *
  * @example
  * // With imagePlugin — spread the import directly
@@ -62,7 +162,7 @@ interface ImageSource {
  * // Manual usage
  * <Image src="/hero.jpg" alt="Hero" width={1200} height={630} />
  */
-declare function Image(props: ImageProps): VNodeChild;
+declare const Image: (props: ImageProps) => any;
 //#endregion
-export { Image, ImageProps, ImageSource };
+export { Image, ImageProps, ImageRenderProps, ImageSource, UseImageReturn, createImage, useImage };
 //# sourceMappingURL=image2.d.ts.map