232 lines
15 KiB
Plaintext
232 lines
15 KiB
Plaintext
page wrnexusimage {
|
|
seo {
|
|
title = "@wrnexus/image"
|
|
description = "Responsive image optimization, loaders, placeholders, and components."
|
|
}
|
|
|
|
view {
|
|
<div class="docs-shell">
|
|
<a href="#main" class="skip-link">Skip to content</a>
|
|
<header class="topbar">
|
|
<a class="brand" href="/"><span>W</span> WRNexusJS</a>
|
|
<nav aria-label="Primary"><a href="/getting-started">Get started</a><a href="/packages">Packages</a><a href="https://component.wrnexusjs.dev/">Components</a><a href="/language">Language</a><a href="/architecture">Architecture</a></nav>
|
|
<div class="topbar-actions"><a class="preview-pill" href="/access">Private preview · v0.8.8</a><button data-wire-theme-toggle class="theme-button" aria-label="Toggle color theme" title="Toggle color theme">◐</button></div>
|
|
</header>
|
|
<div class="mobile-doc-nav"><details><summary>Browse documentation</summary><nav><a href="/getting-started">Get started</a><a href="/packages">Packages</a><a href="https://component.wrnexusjs.dev/">Components</a><a href="/language">Language</a><a href="/architecture">Architecture</a><a href="/tutorial">Tutorial</a><a href="/guides/project-structure">Guides</a><a href="/examples">Examples</a><a href="/search">Search</a></nav></details></div>
|
|
<main id="main" class="portal-main docs-layout docs-layout--navigation"><aside class="docs-section-menu" aria-label="Documentation sections"><nav>
|
|
<section><strong>Get started</strong><a href="/getting-started">Quick start</a><a href="/tutorial">Tutorial</a><a href="/guides/full-stack-auth-demo">Auth dashboard demo</a><a href="/guides/configuration-and-profiles">Configuration</a></section>
|
|
<section><strong>Build</strong><a href="/guides/pages-and-components">Pages and components</a><a href="/guides/routing">Routing</a><a href="/guides/server-data">Server data</a><a href="/guides/forms-and-validation">Forms and validation</a><a href="/guides/database">Database</a></section>
|
|
<section><strong>Auth and security</strong><a href="/guides/authentication">Authentication</a><a href="/guides/authorization">Authorization</a><a href="/guides/security">Application security</a><a href="/security">Security policy</a></section>
|
|
<section><strong>Reference</strong><a href="/packages">Packages overview</a><a href="/packages/cli">CLI</a><a href="/language">.wrn language</a><a href="https://component.wrnexusjs.dev/">Components</a><a href="/examples">Examples</a></section>
|
|
<section class="package-menu"><strong>Packages</strong><a href="/packages/ai">@wrnexus/ai</a><a href="/packages/auth">@wrnexus/auth</a><a href="/packages/authz">@wrnexus/authz</a><a href="/packages/benchmark">@wrnexus/benchmark</a><a href="/packages/cache">@wrnexus/cache</a><a href="/packages/captcha">@wrnexus/captcha</a><a href="/packages/cli">@wrnexus/cli</a><a href="/packages/compiler">@wrnexus/compiler</a><a href="/packages/content">@wrnexus/content</a><a href="/packages/core">@wrnexus/core</a><a href="/packages/csr">@wrnexus/csr</a><a href="/packages/db">@wrnexus/db</a><a href="/packages/dev-server">@wrnexus/dev-server</a><a href="/packages/dev-toolbar">@wrnexus/dev-toolbar</a><a href="/packages/encryption">@wrnexus/encryption</a><a href="/packages/graphql">@wrnexus/graphql</a><a href="/packages/helpers">@wrnexus/helpers</a><a href="/packages/i18n">@wrnexus/i18n</a><a href="/packages/identity">@wrnexus/identity</a><a href="/packages/image">@wrnexus/image</a><a href="/packages/jwt">@wrnexus/jwt</a><a href="/packages/language-server">@wrnexus/language-server</a><a href="/packages/mcp">@wrnexus/mcp</a><a href="/packages/mobile">@wrnexus/mobile</a><a href="/packages/native">@wrnexus/native</a><a href="/packages/oauth">@wrnexus/oauth</a><a href="/packages/observability">@wrnexus/observability</a><a href="/packages/playground">@wrnexus/playground</a><a href="/packages/plugin">@wrnexus/plugin</a><a href="/packages/pubsub">@wrnexus/pubsub</a><a href="/packages/pwa">@wrnexus/pwa</a><a href="/packages/queue">@wrnexus/queue</a><a href="/packages/reactive">@wrnexus/reactive</a><a href="/packages/realtime">@wrnexus/realtime</a><a href="/packages/router">@wrnexus/router</a><a href="/packages/security">@wrnexus/security</a><a href="/packages/ssr">@wrnexus/ssr</a><a href="/packages/store">@wrnexus/store</a><a href="/packages/styles">@wrnexus/styles</a><a href="/packages/syntax">@wrnexus/syntax</a><a href="/packages/test">@wrnexus/test</a><a href="/packages/tracking">@wrnexus/tracking</a><a href="/packages/typecheck">@wrnexus/typecheck</a><a href="/packages/ui">@wrnexus/ui</a><a href="/packages/uploader">@wrnexus/uploader</a><a href="/packages/validation">@wrnexus/validation</a></section>
|
|
</nav></aside><div class="docs-reading-column">
|
|
<article class="documentation prose standalone package-document"><nav class="breadcrumbs" aria-label="Breadcrumb"><a href="/">Home</a><span>/</span><a href="/packages">Packages</a><span>/</span><span aria-current="page">@wrnexus/image</span></nav><section class="doc-intro"><span class="eyebrow">Frontend · Package reference</span><h1>@wrnexus/image</h1><p>Responsive image optimization, loaders, placeholders, and components.</p><div class="doc-meta"><span>v0.8.8</span><span>Private registry</span><span>Frontend</span></div><section id="access" class="access-callout"><h2>Install the package</h2><p>After WorkRoot approves private registry access, install the release-aligned package:</p><pre><code>bun add @wrnexus/image@0.8.8</code><button type="button" class="copy-button" aria-label="Copy installation command">Copy</button></pre><p><a href="/access">Request preview access</a>. Never put registry tokens in source control.</p></section></section><section id="guide"><p>Secure responsive-image planning, loader adapters, picture sources, preload hints, placeholders, and performance auditing for WRNexusJS.</p>
|
|
<p>Build-time conversion is available through <code>optimizeImage</code>. It normalizes and bounds width/format variants, prevents variant explosions, writes deterministic filenames, and returns a manifest with dimensions and byte sizes:</p>
|
|
<pre data-language="ts"><code>import { optimizeImage } from "@wrnexus/image";
|
|
|
|
const manifest = await optimizeImage("public/hero.jpg", {
|
|
outputDir: "public/generated/images",
|
|
widths: [480, 960, 1440],
|
|
formats: ["avif", "webp"],
|
|
quality: 80,
|
|
});</code></pre>
|
|
<p>Install the optional <code>sharp</code> peer (<code>bun add sharp</code>) for the default AVIF/WebP processor. Build systems can instead supply an <code>ImageProcessor</code> adapter, which also makes transformation pipelines deterministic in tests.</p>
|
|
<h3 id="helper-api">Helper API</h3>
|
|
<pre data-language="ts"><code>import {
|
|
createResponsiveImage,
|
|
createPicture,
|
|
createCdnImageLoader,
|
|
createPathImageLoader,
|
|
createBlurPlaceholder,
|
|
imagePreload,
|
|
auditImage,
|
|
} from "@wrnexus/image";
|
|
|
|
const loader = createCdnImageLoader("https://images.example.com/transform");
|
|
const picture = createPicture({
|
|
src: "/hero.jpg",
|
|
alt: "Product dashboard",
|
|
width: 1600,
|
|
height: 900,
|
|
widths: [480, 768, 1200, 1600],
|
|
formats: ["avif", "webp"],
|
|
sizes: "(max-width: 768px) 100vw, 1200px",
|
|
fetchPriority: "high",
|
|
loader,
|
|
});</code></pre>
|
|
<p>Remote loaders require HTTPS. Source URLs are validated, dimensions and quality are bounded, placeholder colors are restricted to safe CSS colors, and preload attributes are escaped.</p>
|
|
<h3 id="components">Components</h3>
|
|
<p>Enable <code>imagePlugin()</code> and use:</p>
|
|
<ul>
|
|
<li><code><OptimizedImage /></code></li>
|
|
<li><code><Picture /></code></li>
|
|
<li><code><ImageCard /></code></li>
|
|
</ul>
|
|
<p>The package-owned blocks compose <code>@wrnexus/ui</code> where a complete UI block is appropriate while keeping the low-level image element lightweight.</p></section><section id="api" class="api"><h2>Complete TypeScript API</h2><p>Generated from the exact installed package declarations.</p><pre data-language="typescript"><code>export { ImagePluginOptions, imageComponentsDir, default as imagePlugin } from './plugin.js';
|
|
import '@wrnexus/plugin';
|
|
|
|
interface ImageProcessorResult {
|
|
data: Uint8Array;
|
|
width: number;
|
|
height: number;
|
|
}
|
|
interface ImageProcessor {
|
|
transform(input: string, options: {
|
|
width: number;
|
|
format: Exclude<ImageFormat, "original">;
|
|
quality: number;
|
|
}): Promise<ImageProcessorResult>;
|
|
}
|
|
interface OptimizeImageOptions {
|
|
outputDir: string;
|
|
widths: number[];
|
|
formats?: Array<Exclude<ImageFormat, "original">>;
|
|
quality?: number;
|
|
maxVariants?: number;
|
|
processor?: ImageProcessor;
|
|
}
|
|
interface OptimizedImageVariant {
|
|
path: string;
|
|
width: number;
|
|
height: number;
|
|
format: Exclude<ImageFormat, "original">;
|
|
bytes: number;
|
|
}
|
|
interface OptimizedImageManifest {
|
|
source: string;
|
|
variants: OptimizedImageVariant[];
|
|
}
|
|
declare function optimizeImage(input: string, options: OptimizeImageOptions): Promise<OptimizedImageManifest>;
|
|
|
|
type ImageFormat = "avif" | "webp" | "jpeg" | "png" | "original";
|
|
interface ImageLoaderInput {
|
|
src: string;
|
|
width: number;
|
|
quality?: number;
|
|
format?: ImageFormat;
|
|
}
|
|
type ImageLoader = (input: ImageLoaderInput) => string;
|
|
interface ImagePolicy {
|
|
remoteHosts?: string[];
|
|
allowedProtocols?: string[];
|
|
maxWidth?: number;
|
|
maxQuality?: number;
|
|
}
|
|
interface ResponsiveImageOptions extends ImagePolicy {
|
|
src: string;
|
|
alt: string;
|
|
width: number;
|
|
height: number;
|
|
widths?: number[];
|
|
sizes?: string;
|
|
quality?: number;
|
|
format?: ImageFormat;
|
|
loading?: "eager" | "lazy";
|
|
fetchPriority?: "high" | "low" | "auto";
|
|
decoding?: "async" | "sync" | "auto";
|
|
loader?: ImageLoader;
|
|
class?: string;
|
|
}
|
|
interface ResponsiveImageAttributes {
|
|
src: string;
|
|
srcset?: string;
|
|
sizes?: string;
|
|
alt: string;
|
|
width: string;
|
|
height: string;
|
|
loading: "eager" | "lazy";
|
|
decoding: "async" | "sync" | "auto";
|
|
fetchpriority?: "high" | "low" | "auto";
|
|
class?: string;
|
|
}
|
|
interface ImageAuditInput {
|
|
src: string;
|
|
width?: number;
|
|
height?: number;
|
|
renderedWidth?: number;
|
|
bytes?: number;
|
|
loading?: string;
|
|
fetchPriority?: string;
|
|
isLcp?: boolean;
|
|
}
|
|
interface ImageAuditIssue {
|
|
code: string;
|
|
severity: "error" | "warning" | "info";
|
|
message: string;
|
|
}
|
|
declare const defaultImageLoader: ImageLoader;
|
|
declare function createResponsiveImage(options: ResponsiveImageOptions): ResponsiveImageAttributes;
|
|
declare function auditImage(input: ImageAuditInput): ImageAuditIssue[];
|
|
interface PictureSource {
|
|
type: string;
|
|
srcset: string;
|
|
sizes?: string;
|
|
}
|
|
interface PicturePlan {
|
|
image: ResponsiveImageAttributes;
|
|
sources: PictureSource[];
|
|
}
|
|
declare function normalizeImageWidths(widths: readonly number[], options?: {
|
|
min?: number;
|
|
max?: number;
|
|
}): number[];
|
|
declare function createCdnImageLoader(baseUrl: string, options?: {
|
|
sourceParam?: string;
|
|
widthParam?: string;
|
|
qualityParam?: string;
|
|
formatParam?: string;
|
|
}): ImageLoader;
|
|
declare function createPathImageLoader(prefix?: string): ImageLoader;
|
|
declare function createPicture(options: ResponsiveImageOptions & {
|
|
formats?: ImageFormat[];
|
|
}): PicturePlan;
|
|
declare function createBlurPlaceholder(options?: {
|
|
width?: number;
|
|
height?: number;
|
|
color?: string;
|
|
accent?: string;
|
|
}): string;
|
|
declare function imagePreload(image: ResponsiveImageAttributes, options?: {
|
|
as?: string;
|
|
type?: string;
|
|
crossOrigin?: "anonymous" | "use-credentials";
|
|
}): string;
|
|
declare function imageCacheKey(input: ImageLoaderInput): string;
|
|
|
|
export { type ImageAuditInput, type ImageAuditIssue, type ImageFormat, type ImageLoader, type ImageLoaderInput, type ImagePolicy, type ImageProcessor, type ImageProcessorResult, type OptimizeImageOptions, type OptimizedImageManifest, type OptimizedImageVariant, type PicturePlan, type PictureSource, type ResponsiveImageAttributes, type ResponsiveImageOptions, auditImage, createBlurPlaceholder, createCdnImageLoader, createPathImageLoader, createPicture, createResponsiveImage, defaultImageLoader, imageCacheKey, imagePreload, normalizeImageWidths, optimizeImage };
|
|
</code></pre></section><section id="examples" class="examples"><h2>Examples</h2><p>Copy-ready examples from the installed package documentation.</p><div class="example-grid"><article class="example-card"><h3>filenames, and returns a manifest with dimensions and byte sizes</h3><pre data-language="ts"><code>import { optimizeImage } from "@wrnexus/image";
|
|
|
|
const manifest = await optimizeImage("public/hero.jpg", {
|
|
outputDir: "public/generated/images",
|
|
widths: [480, 960, 1440],
|
|
formats: ["avif", "webp"],
|
|
quality: 80,
|
|
});</code></pre></article><article class="example-card"><h3>## Helper API</h3><pre data-language="ts"><code>import {
|
|
createResponsiveImage,
|
|
createPicture,
|
|
createCdnImageLoader,
|
|
createPathImageLoader,
|
|
createBlurPlaceholder,
|
|
imagePreload,
|
|
auditImage,
|
|
} from "@wrnexus/image";
|
|
|
|
const loader = createCdnImageLoader("https://images.example.com/transform");
|
|
const picture = createPicture({
|
|
src: "/hero.jpg",
|
|
alt: "Product dashboard",
|
|
width: 1600,
|
|
height: 900,
|
|
widths: [480, 768, 1200, 1600],
|
|
formats: ["avif", "webp"],
|
|
sizes: "(max-width: 768px) 100vw, 1200px",
|
|
fetchPriority: "high",
|
|
loader,
|
|
});</code></pre></article></div></section></article></div>
|
|
<aside class="on-this-page"><h2>On this page</h2><nav><a class="toc-level-2" href="#guide">Guide</a><a class="toc-level-3" href="#helper-api">Helper API</a><a class="toc-level-3" href="#components">Components</a><a class="toc-level-2" href="#api">Complete API</a><a class="toc-level-2" href="#examples">Examples</a></nav></aside>
|
|
</main>
|
|
<footer><div class="footer-brand"><span class="footer-mark" aria-hidden="true">W</span><p><strong>WRNexusJS 0.8.8</strong><span>Complete API documentation generated from installed package declarations.</span></p></div><nav aria-label="Footer"><a href="/packages">All packages</a><a href="/getting-started">Get started</a><a href="/security">Security</a><a href="/support">Support</a><a href="/llms.txt">AI guide</a></nav><p class="footer-meta">Private Developer Preview · Bun-native</p></footer>
|
|
</div>
|
|
}
|
|
}
|