@t09tanaka/stoneage 0.1.0

package/dist/fragment/client.d.ts

@@ -0,0 +1,13 @@
+import type { FragmentTrigger } from "../fragment.js";
+export type FragmentControllerOptions = {
+    root?: ParentNode;
+    trigger?: FragmentTrigger;
+    fetch?: typeof fetch;
+};
+export type FragmentController = {
+    elements: Element[];
+    load: (element: Element) => Promise<void>;
+    disconnect: () => void;
+};
+export declare function fragmentController(selector?: string, options?: FragmentControllerOptions): FragmentController;
+export declare function loadFragment(element: Element, fetcher?: typeof fetch): Promise<void>;

package/dist/fragment/client.js

@@ -0,0 +1,150 @@
+export function fragmentController(selector = "[data-stoneage-fragment]", options = {}) {
+    const root = options.root ?? document;
+    const fetcher = options.fetch ?? fetch;
+    const elements = Array.from(root.querySelectorAll(selector));
+    const cleanups = [];
+    const armedElements = new WeakSet();
+    const controller = {
+        elements,
+        load: async (element) => {
+            await loadFragmentElement(element, fetcher);
+            armNestedFragments(element, selector, armElement);
+        },
+        disconnect: () => {
+            for (const cleanup of cleanups.splice(0)) {
+                cleanup();
+            }
+        },
+    };
+    const armElement = (element) => {
+        if (armedElements.has(element)) {
+            return;
+        }
+        armedElements.add(element);
+        const trigger = options.trigger ?? readFragmentTrigger(element);
+        if (trigger === "manual") {
+            return;
+        }
+        if (trigger === "details-open") {
+            cleanups.push(loadWhenDetailsOpen(element, controller.load));
+            return;
+        }
+        if (trigger === "idle") {
+            cleanups.push(loadWhenIdle(element, controller.load));
+            return;
+        }
+        cleanups.push(loadWhenVisible(element, controller.load));
+    };
+    for (const element of elements) {
+        armElement(element);
+    }
+    return controller;
+}
+export async function loadFragment(element, fetcher = fetch) {
+    await loadFragmentElement(element, fetcher);
+}
+async function loadFragmentElement(element, fetcher) {
+    if (element.hasAttribute("data-fragment-loaded") ||
+        element.hasAttribute("data-fragment-loading")) {
+        return;
+    }
+    const src = element.getAttribute("data-fragment-src");
+    if (!src) {
+        throw new Error("Deferred fragment placeholder is missing data-fragment-src.");
+    }
+    element.setAttribute("data-fragment-loading", "true");
+    element.removeAttribute("data-fragment-error");
+    dispatchFragmentEvent(element, "stoneage:fragmentbeforeload", { src });
+    try {
+        const response = await fetcher(src, {
+            headers: { accept: "text/html" },
+        });
+        if (!response.ok) {
+            throw new Error(`Failed to load deferred fragment ${src}: ${response.status}`);
+        }
+        element.innerHTML = await response.text();
+        element.setAttribute("data-fragment-loaded", "true");
+        element.removeAttribute("data-fragment-error");
+        dispatchFragmentEvent(element, "stoneage:fragmentload", { src });
+    }
+    catch (error) {
+        element.setAttribute("data-fragment-error", "true");
+        dispatchFragmentEvent(element, "stoneage:fragmenterror", { src, error });
+        throw error;
+    }
+    finally {
+        element.removeAttribute("data-fragment-loading");
+    }
+}
+function dispatchFragmentEvent(element, type, detail) {
+    element.dispatchEvent(new CustomEvent(type, {
+        bubbles: true,
+        detail,
+    }));
+}
+function readFragmentTrigger(element) {
+    const trigger = element.getAttribute("data-fragment-trigger");
+    if (trigger === "manual" ||
+        trigger === "details-open" ||
+        trigger === "idle" ||
+        trigger === "visible") {
+        return trigger;
+    }
+    return "visible";
+}
+function armNestedFragments(element, selector, armElement) {
+    for (const nested of Array.from(element.querySelectorAll(selector))) {
+        armElement(nested);
+    }
+}
+function loadWhenDetailsOpen(element, load) {
+    const details = element.closest("details");
+    if (!details) {
+        return loadWhenVisible(element, load);
+    }
+    if (details.open) {
+        loadAutomatically(element, load);
+        return () => { };
+    }
+    const onToggle = () => {
+        if (details.open) {
+            loadAutomatically(element, load);
+            details.removeEventListener("toggle", onToggle);
+        }
+    };
+    details.addEventListener("toggle", onToggle);
+    return () => details.removeEventListener("toggle", onToggle);
+}
+function loadWhenVisible(element, load) {
+    if (typeof IntersectionObserver === "undefined") {
+        loadAutomatically(element, load);
+        return () => { };
+    }
+    const observer = new IntersectionObserver((entries) => {
+        if (entries.some((entry) => entry.isIntersecting)) {
+            loadAutomatically(element, load);
+            observer.disconnect();
+        }
+    });
+    observer.observe(element);
+    return () => observer.disconnect();
+}
+function loadWhenIdle(element, load) {
+    const windowWithIdle = globalThis;
+    const handle = windowWithIdle.requestIdleCallback
+        ? windowWithIdle.requestIdleCallback(() => loadAutomatically(element, load))
+        : setTimeout(() => loadAutomatically(element, load), 0);
+    return () => {
+        if (windowWithIdle.cancelIdleCallback) {
+            windowWithIdle.cancelIdleCallback(handle);
+        }
+        else {
+            clearTimeout(handle);
+        }
+    };
+}
+function loadAutomatically(element, load) {
+    void load(element).catch(() => {
+        // loadFragmentElement marks the placeholder with data-fragment-error.
+    });
+}

package/dist/fragment.d.ts

@@ -0,0 +1,15 @@
+import { type ClassValue, type HtmlMarkup, type HtmlNode } from "./html.js";
+export type FragmentTrigger = "visible" | "details-open" | "idle" | "manual";
+export type DeferredFragmentDefaults = {
+    defaultFallbackText?: string;
+};
+export type DeferredFragmentOptions = {
+    src: string;
+    trigger?: FragmentTrigger;
+    fallback?: HtmlNode;
+    as?: "div" | "span";
+    className?: ClassValue;
+    attrs?: Record<string, unknown>;
+};
+export declare function deferredFragment(options: DeferredFragmentOptions): HtmlMarkup;
+export declare function withDeferredFragmentDefaults<T>(defaults: DeferredFragmentDefaults, render: () => T): T;

package/dist/fragment.js

@@ -0,0 +1,27 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { html } from "./html.js";
+const defaultFallbackText = "Open deferred content";
+const defaultsStorage = new AsyncLocalStorage();
+export function deferredFragment(options) {
+    const fallback = options.fallback === undefined
+        ? html("a", { href: options.src }, currentDefaultFallbackText())
+        : options.fallback;
+    return html(options.as ?? "div", {
+        "data-stoneage-fragment": true,
+        "data-fragment-src": options.src,
+        "data-fragment-trigger": options.trigger ?? "visible",
+        ...fragmentAttrs(options.attrs ?? {}),
+        ...(options.className !== undefined ? { className: options.className } : {}),
+    }, fallback);
+}
+export function withDeferredFragmentDefaults(defaults, render) {
+    return defaultsStorage.run(defaults, render);
+}
+function currentDefaultFallbackText() {
+    return defaultsStorage.getStore()?.defaultFallbackText ?? defaultFallbackText;
+}
+function fragmentAttrs(attrs) {
+    return Object.fromEntries(Object.entries(attrs).filter(([name]) => name !== "data-stoneage-fragment" &&
+        name !== "data-fragment-src" &&
+        name !== "data-fragment-trigger"));
+}

package/dist/html.d.ts

@@ -0,0 +1,57 @@
+declare const markupSymbol: unique symbol;
+export type HtmlNode = HtmlMarkup | string | number | boolean | null | undefined | HtmlNode[];
+export type HtmlComponent<Props = Record<string, unknown>> = (props: Props & {
+    children?: HtmlNode[];
+}) => HtmlNode;
+export type HtmlMarkup = {
+    readonly [markupSymbol]: true;
+    readonly value: string;
+    toString(): string;
+};
+export type ClassValue = string | number | false | null | undefined | ClassValue[] | Record<string, unknown>;
+export type StyleObject = Record<string, string | number | false | null | undefined>;
+type IntrinsicProps = Record<string, unknown> & {
+    children?: HtmlNode[];
+    class?: ClassValue;
+    className?: ClassValue;
+    style?: string | StyleObject;
+    dangerouslySetInnerHTML?: {
+        __html: string;
+    };
+};
+export type IslandMountOptions = {
+    key?: string;
+    props?: unknown;
+    as?: "div" | "span";
+    className?: ClassValue;
+    attrs?: Record<string, unknown>;
+};
+export type SvgImageOptions = {
+    src: string;
+    width: number;
+    height: number;
+    alt: string;
+    loading?: "eager" | "lazy";
+    decoding?: "async" | "sync" | "auto";
+    fetchPriority?: "high" | "low" | "auto";
+    className?: ClassValue;
+    attrs?: Record<string, unknown>;
+};
+export declare function html<Props extends Record<string, unknown>>(tag: string | HtmlComponent<Props>, props: Props | null, ...children: HtmlNode[]): HtmlMarkup;
+export declare function Fragment(props: {
+    children?: HtmlNode[];
+}): HtmlMarkup;
+export declare function raw(value: string): HtmlMarkup;
+export declare function classNames(...values: ClassValue[]): string;
+export declare function islandMount(id: string, options?: IslandMountOptions): HtmlMarkup;
+export declare function svgImage(options: SvgImageOptions): HtmlMarkup;
+export declare function renderToString(node: HtmlNode): string;
+declare global {
+    namespace JSX {
+        type Element = HtmlMarkup;
+        interface IntrinsicElements {
+            [elementName: string]: IntrinsicProps;
+        }
+    }
+}
+export {};

package/dist/html.js

@@ -0,0 +1,208 @@
+const markupSymbol = Symbol("stoneage.html");
+const voidElements = new Set([
+    "area",
+    "base",
+    "br",
+    "col",
+    "embed",
+    "hr",
+    "img",
+    "input",
+    "link",
+    "meta",
+    "source",
+    "track",
+    "wbr",
+]);
+export function html(tag, props, ...children) {
+    if (typeof tag === "function") {
+        return markup(renderNode(tag({ ...(props ?? {}), children })));
+    }
+    const normalizedProps = (props ?? {});
+    const attributes = renderAttributes(normalizedProps);
+    if (voidElements.has(tag)) {
+        return markup(`<${tag}${attributes}>`);
+    }
+    const content = normalizedProps.dangerouslySetInnerHTML
+        ? normalizedProps.dangerouslySetInnerHTML.__html
+        : children.map(renderNode).join("");
+    return markup(`<${tag}${attributes}>${content}</${tag}>`);
+}
+export function Fragment(props) {
+    return markup((props.children ?? []).map(renderNode).join(""));
+}
+export function raw(value) {
+    return markup(value);
+}
+export function classNames(...values) {
+    return renderClassValue(values);
+}
+export function islandMount(id, options = {}) {
+    const tag = options.as ?? "div";
+    const hasKey = options.key !== undefined;
+    const key = options.key ?? id;
+    const root = html(tag, {
+        "data-island": id,
+        ...(hasKey ? { "data-island-key": key } : {}),
+        ...islandAttrs(options.attrs ?? {}),
+        ...(options.className !== undefined ? { className: options.className } : {}),
+    });
+    if (options.props === undefined) {
+        return root;
+    }
+    return markup(`${root.value}<script type="application/json" data-island-props="${escapeAttribute(key)}">${escapeJsonScript(options.props)}</script>`);
+}
+export function svgImage(options) {
+    if (!options.src) {
+        throw new TypeError("svgImage src is required.");
+    }
+    if (options.width === undefined) {
+        throw new TypeError("svgImage width is required.");
+    }
+    if (options.height === undefined) {
+        throw new TypeError("svgImage height is required.");
+    }
+    if (options.alt === undefined) {
+        throw new TypeError("svgImage alt is required.");
+    }
+    return html("img", {
+        src: options.src,
+        width: options.width,
+        height: options.height,
+        alt: options.alt,
+        ...(options.alt === "" ? { "aria-hidden": "true" } : {}),
+        loading: options.loading ?? "lazy",
+        decoding: options.decoding ?? "async",
+        ...(options.fetchPriority ? { fetchPriority: options.fetchPriority } : {}),
+        ...(options.className !== undefined ? { className: options.className } : {}),
+        ...(options.attrs ?? {}),
+    });
+}
+export function renderToString(node) {
+    return renderNode(node);
+}
+function markup(value) {
+    const rendered = value;
+    return {
+        [markupSymbol]: true,
+        value: rendered,
+        toString: () => rendered,
+    };
+}
+function renderNode(node) {
+    if (node === null || node === undefined || typeof node === "boolean") {
+        return "";
+    }
+    if (Array.isArray(node)) {
+        return node.map(renderNode).join("");
+    }
+    if (isMarkup(node)) {
+        return node.value;
+    }
+    if (typeof node === "number") {
+        return String(node);
+    }
+    return escapeHtml(node);
+}
+function renderAttributes(props) {
+    let output = "";
+    for (const [rawName, value] of Object.entries(props)) {
+        if (rawName === "children" || rawName === "dangerouslySetInnerHTML") {
+            continue;
+        }
+        if (value === false || value === null || value === undefined) {
+            continue;
+        }
+        const name = normalizeAttributeName(rawName);
+        const renderedValue = renderAttributeValue(rawName, value);
+        if (renderedValue === undefined) {
+            continue;
+        }
+        if (renderedValue === true) {
+            output += ` ${name}`;
+            continue;
+        }
+        output += ` ${name}="${escapeAttribute(renderedValue)}"`;
+    }
+    return output;
+}
+function renderAttributeValue(name, value) {
+    if (name === "class" || name === "className") {
+        const classValue = renderClassValue(value);
+        return classValue === "" ? undefined : classValue;
+    }
+    if (name === "style" && isStyleObject(value)) {
+        const styleValue = renderStyleObject(value);
+        return styleValue === "" ? undefined : styleValue;
+    }
+    if (value === true) {
+        return true;
+    }
+    return String(value);
+}
+function normalizeAttributeName(name) {
+    if (name === "className") {
+        return "class";
+    }
+    if (name === "htmlFor") {
+        return "for";
+    }
+    return name;
+}
+function renderClassValue(value) {
+    if (value === false || value === null || value === undefined) {
+        return "";
+    }
+    if (Array.isArray(value)) {
+        return value.map(renderClassValue).filter(Boolean).join(" ");
+    }
+    if (typeof value === "object") {
+        return Object.entries(value)
+            .filter(([, enabled]) => Boolean(enabled))
+            .map(([name]) => name)
+            .join(" ");
+    }
+    return String(value);
+}
+function isStyleObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function renderStyleObject(style) {
+    return Object.entries(style)
+        .filter(([, value]) => value !== false && value !== null && value !== undefined)
+        .map(([name, value]) => `${normalizeStyleName(name)}:${String(value)}`)
+        .join(";");
+}
+function normalizeStyleName(name) {
+    if (name.startsWith("--")) {
+        return name;
+    }
+    return name.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`);
+}
+function isMarkup(value) {
+    return typeof value === "object" && value !== null && markupSymbol in value;
+}
+function escapeHtml(value) {
+    return value
+        .replaceAll("&", "&amp;")
+        .replaceAll("<", "&lt;")
+        .replaceAll(">", "&gt;");
+}
+function escapeAttribute(value) {
+    return escapeHtml(value).replaceAll('"', "&quot;");
+}
+function islandAttrs(attrs) {
+    return Object.fromEntries(Object.entries(attrs).filter(([name]) => name !== "data-island" && name !== "data-island-key"));
+}
+function escapeJsonScript(value) {
+    const json = JSON.stringify(value);
+    if (json === undefined) {
+        throw new TypeError("Island props must be JSON-serializable.");
+    }
+    return json
+        .replaceAll("<", "\\u003c")
+        .replaceAll(">", "\\u003e")
+        .replaceAll("&", "\\u0026")
+        .replaceAll("\u2028", "\\u2028")
+        .replaceAll("\u2029", "\\u2029");
+}

package/dist/images.d.ts

@@ -0,0 +1,95 @@
+export type ImageFormat = "webp" | "avif" | "jpeg" | "png";
+export type ImageInput = {
+    source: string;
+    publicPath: string;
+};
+export type GeneratedImage = {
+    source: string;
+    publicPath: string;
+    width: number;
+    format: ImageFormat;
+    bytes: number;
+};
+export type SkippedImage = {
+    source: string;
+    publicPath?: string;
+    width?: number;
+    format?: ImageFormat;
+    bytes?: number;
+    reason: "converter-unavailable" | "unsupported-format" | "existing-current";
+};
+export type ImageConverter = (input: {
+    source: string;
+    outputPath: string;
+    width: number;
+    format: ImageFormat;
+}) => Promise<void>;
+export type OptimizeImagesOptions = {
+    outDir: string;
+    images: ImageInput[];
+    widths: number[];
+    formats: ImageFormat[];
+    skipExisting?: boolean;
+    converter?: ImageConverter;
+    loadConverter?: () => Promise<ImageConverter | undefined>;
+};
+export type OptimizeImagesResult = {
+    generated: GeneratedImage[];
+    skipped: SkippedImage[];
+};
+export type ImageResultOrImages = OptimizeImagesResult | GeneratedImage[];
+/**
+ * Number of distinct source images that could not be optimized because no image
+ * converter (sharp) was available. Lets callers surface an actionable warning
+ * instead of silently shipping unoptimized images.
+ */
+export declare function countConverterUnavailable(result: OptimizeImagesResult): number;
+/**
+ * Resolve whether the optional `sharp` dependency can be loaded in the current
+ * environment. Returns false when sharp is not installed or its native binary
+ * is unavailable for the current platform.
+ */
+export declare function isSharpAvailable(loadConverter?: () => Promise<ImageConverter | undefined>): Promise<boolean>;
+export declare function optimizeImages(options: OptimizeImagesOptions): Promise<OptimizeImagesResult>;
+export declare function imagesForSource(resultOrImages: ImageResultOrImages, sourceOrPublicPath: string): GeneratedImage[];
+export declare function srcsetFor(images: GeneratedImage[]): string;
+export type PictureSource = {
+    format: ImageFormat;
+    type: `image/${ImageFormat}`;
+    srcset: string;
+};
+export declare function pictureSourcesFor(images: GeneratedImage[], formats?: ImageFormat[]): PictureSource[];
+export type PictureImageLoading = "eager" | "lazy";
+export type PictureImageDecoding = "async" | "auto" | "sync";
+export type PictureAttrsFallback = {
+    src: string;
+    width: number;
+    height: number;
+    alt: string;
+    sizes?: string;
+    loading?: PictureImageLoading;
+    decoding?: PictureImageDecoding;
+    fallbackFormat?: ImageFormat;
+    formats?: ImageFormat[];
+};
+export type PictureAttrsSource = PictureSource & {
+    sizes?: string;
+};
+export type PictureImgAttrs = {
+    src: string;
+    srcset?: string;
+    sizes?: string;
+    width: number;
+    height: number;
+    loading?: PictureImageLoading;
+    decoding?: PictureImageDecoding;
+    alt: string;
+};
+export type PictureAttrs = {
+    sources: PictureAttrsSource[];
+    img: PictureImgAttrs;
+};
+export declare function pictureAttrsFor(images: GeneratedImage[], fallback: PictureAttrsFallback): PictureAttrs;
+export declare function pictureHtmlFor(images: GeneratedImage[], fallback: PictureAttrsFallback): string;
+export declare function renderPicture(attrs: PictureAttrs): string;
+export declare function loadSharpConverter(): Promise<ImageConverter | undefined>;