@nibapp/ui 0.0.0-stage → 0.1.0

package/dist/components/image-sources.d.ts

@@ -0,0 +1,57 @@
+import { type ReactNode } from "react";
+import { type ImageProblem } from "./image-thumbnail.js";
+/** A local image as the surface could get it: a URL `<img>` loads (and its size), or why there is none. */
+export type LocalImage = {
+    readonly kind: "ready";
+    readonly src: string;
+    readonly name?: string | undefined;
+    readonly width?: number | undefined;
+    readonly height?: number | undefined;
+} | {
+    readonly kind: "problem";
+    readonly problem: ImageProblem;
+};
+/** Where a message's images come from on the surface it renders on. */
+export interface ImageSources {
+    /**
+     * The surface's hook for a local image a message names (a path, relative to the conversation's
+     * folder or absolute, or a `file:` URL) as of `scope` (the row that names it, the call that wrote it), read
+     * under the surface's access rules; undefined while it reads. Without one, a path doesn't load.
+     */
+    readonly useLocal?: ((path: string, scope: string) => LocalImage | undefined) | undefined;
+    /**
+     * A remote image (another site's): `ask` loads it when the reader asks, where the page may load
+     * it; `open` names its host and opens it in the browser, where the page may not (a strict CSP).
+     */
+    readonly remote: "ask" | "open";
+}
+export declare function ImageSourcesProvider({ value, children, }: {
+    readonly value: ImageSources;
+    readonly children: ReactNode;
+}): import("react").JSX.Element;
+export declare function useImageSources(): ImageSources;
+/** The local images below are read as of `scope` (the row that names them): a later row reads afresh. */
+export declare function LocalImageScope({ scope, children, }: {
+    readonly scope: string;
+    readonly children: ReactNode;
+}): import("react").JSX.Element;
+/** The scope local images below are read as of (`LocalImageScope`). */
+export declare function useLocalImageScope(): string;
+/** Whether a path names a picture (by its extension), so a surface may read it as one. */
+export declare function isImagePath(path: string): boolean;
+/** A local image's place in its gallery: its path, as of the scope it was read in. */
+export declare function localImageKey(path: string, scope: string): string;
+/** A message's image source as a local path: a `file:` URL's path, or the source decoded. */
+export declare function localImagePath(src: string): string;
+/**
+ * A local image (a path a message names, a file a tool wrote), read by the surface under its
+ * access rules (`ImageSources.useLocal`) as of `scope`, as an image in place. Render it only where
+ * the surface has `useLocal`.
+ */
+export declare function LocalImageThumbnail({ path, alt, scope, useLocal, size, }: {
+    readonly path: string;
+    readonly alt: string;
+    readonly scope: string;
+    readonly useLocal: NonNullable<ImageSources["useLocal"]>;
+    readonly size?: "md" | "sm" | undefined;
+}): import("react").JSX.Element;

package/dist/components/image-sources.js

@@ -0,0 +1,58 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, use } from "react";
+import { ImageThumbnail } from "./image-thumbnail.js";
+const ImageSourcesContext = createContext({ remote: "ask" });
+const ScopeContext = createContext("");
+export function ImageSourcesProvider({ value, children, }) {
+    return _jsx(ImageSourcesContext, { value: value, children: children });
+}
+export function useImageSources() {
+    return use(ImageSourcesContext);
+}
+/** The local images below are read as of `scope` (the row that names them): a later row reads afresh. */
+export function LocalImageScope({ scope, children, }) {
+    return _jsx(ScopeContext, { value: scope, children: children });
+}
+/** The scope local images below are read as of (`LocalImageScope`). */
+export function useLocalImageScope() {
+    return use(ScopeContext);
+}
+/** Paths a message may show as a picture: anything else a message names is never read for one. */
+const IMAGE_FILE = /\.(?:png|jpe?g|gif|webp|svg)$/iu;
+/** Whether a path names a picture (by its extension), so a surface may read it as one. */
+export function isImagePath(path) {
+    return IMAGE_FILE.test(path);
+}
+/** A local image's place in its gallery: its path, as of the scope it was read in. */
+export function localImageKey(path, scope) {
+    return `local:${scope}:${path}`;
+}
+/** A message's image source as a local path: a `file:` URL's path, or the source decoded. */
+export function localImagePath(src) {
+    if (/^file:/iu.test(src)) {
+        try {
+            return decodeURIComponent(new URL(src).pathname);
+        }
+        catch {
+            return src;
+        }
+    }
+    try {
+        return decodeURI(src);
+    }
+    catch {
+        return src;
+    }
+}
+/**
+ * A local image (a path a message names, a file a tool wrote), read by the surface under its
+ * access rules (`ImageSources.useLocal`) as of `scope`, as an image in place. Render it only where
+ * the surface has `useLocal`.
+ */
+export function LocalImageThumbnail({ path, alt, scope, useLocal, size, }) {
+    const image = useLocal(path, scope);
+    const name = path.split(/[\\/]/u).at(-1);
+    const ready = image?.kind === "ready" ? image : undefined;
+    return (_jsx(ImageThumbnail, { src: ready?.src, alt: alt === "" ? (name ?? "") : alt, name: ready?.name ?? name, width: ready?.width, height: ready?.height, problem: image?.kind === "problem" ? image.problem : undefined, galleryKey: localImageKey(path, scope), size: size }));
+}

package/dist/components/image-thumbnail.d.ts

@@ -0,0 +1,34 @@
+import { type ReactNode } from "react";
+/** Why an image shows no picture: it couldn't be had, or it's over what the list shows. */
+export type ImageProblem = {
+    readonly kind: "failed";
+} | {
+    readonly kind: "too-large";
+    readonly bytes?: number | undefined;
+};
+export interface ImageThumbnailProps {
+    /** What `<img>` loads (inline data, a blob or an object URL); undefined while the host fetches it. */
+    readonly src: string | undefined;
+    /** What it shows: the text alternative, and what the viewer is titled. */
+    readonly alt: string;
+    /** The file name Save suggests. */
+    readonly name?: string | undefined;
+    /** A quiet line under the picture (where it came from). */
+    readonly caption?: ReactNode;
+    readonly problem?: ImageProblem | undefined;
+    /** `md`: one image in its place (up to 320 px tall); `sm`: one of a row of them (up to 160 px). */
+    readonly size?: "md" | "sm" | undefined;
+    /** Its own size (`imageSize`, from its header), when known: the place is held at its shape. */
+    readonly width?: number | undefined;
+    readonly height?: number | undefined;
+    /** Which image it is in its gallery (the host's list of a turn's images); default its `src`. */
+    readonly galleryKey?: string | undefined;
+    readonly className?: string | undefined;
+}
+/**
+ * An image in a message list, as an image: proportional, never larger than its own size or the
+ * column, at most 320 px tall (160 in a row of them), so a tall screenshot never takes over the
+ * page. A click opens it full size (the gallery's viewer). While it loads, a placeholder holds the
+ * place; one that can't load, or is too large to show, says so in its place.
+ */
+export declare function ImageThumbnail({ src, alt, name, caption, problem, size, width, height, galleryKey, className, }: ImageThumbnailProps): import("react").JSX.Element;

package/dist/components/image-thumbnail.js

@@ -0,0 +1,58 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { ImageIcon, ImageOff } from "lucide-react";
+import { useMemo, useRef, useState } from "react";
+import { useFormatters, useUiStrings } from "../i18n/provider.js";
+import { cn } from "../lib/cn.js";
+import { useViewerImage } from "./image-viewer.js";
+/** How tall a picture of each size may be, in px (`max-h-80`, `max-h-40`). */
+const MAX_HEIGHT = { md: 320, sm: 160 };
+const frame = "rounded-lg border border-border-subtle bg-bg-subtle";
+/**
+ * Its shape known, the place is held at the size it will show at (its own, or smaller to fit the
+ * height and the column): nothing moves when it arrives.
+ */
+function heldShape(width, height, size) {
+    if (width === undefined || height === undefined || width <= 0 || height <= 0)
+        return undefined;
+    return {
+        aspectRatio: `${width} / ${height}`,
+        // A length, not a percentage: the place sizes itself, and `max-w-full` narrows it in a narrow column.
+        width: `${Math.min(width, (width * MAX_HEIGHT[size]) / height)}px`,
+    };
+}
+/** An image that shows no picture, in its place: it couldn't load, or it's too large to show here. */
+function ProblemCard({ label, problem }) {
+    const t = useUiStrings().imageViewer;
+    const formatters = useFormatters();
+    const failed = problem.kind === "failed";
+    const size = problem.kind === "too-large" && problem.bytes !== undefined ? formatters.bytes(problem.bytes) : undefined;
+    const Icon = failed ? ImageOff : ImageIcon;
+    return (_jsxs("span", { "data-slot": "transcript-image", "data-state": problem.kind, className: cn(frame, "inline-flex max-w-full items-center gap-2 px-3 py-2 text-sm"), children: [_jsx(Icon, { "aria-hidden": true, className: "size-4 shrink-0 text-fg-subtle" }), _jsx("span", { className: "min-w-0 truncate text-fg-muted", children: label }), _jsx("span", { className: "shrink-0 text-xs text-fg-subtle", children: failed ? t.failed : t.tooLarge({ size }) })] }));
+}
+/**
+ * An image in a message list, as an image: proportional, never larger than its own size or the
+ * column, at most 320 px tall (160 in a row of them), so a tall screenshot never takes over the
+ * page. A click opens it full size (the gallery's viewer). While it loads, a placeholder holds the
+ * place; one that can't load, or is too large to show, says so in its place.
+ */
+export function ImageThumbnail({ src, alt, name, caption, problem, size = "md", width, height, galleryKey, className, }) {
+    const t = useUiStrings().imageViewer;
+    const ref = useRef(null);
+    const [loaded, setLoaded] = useState(false);
+    const [broken, setBroken] = useState(false);
+    const label = alt === "" ? t.untitled : alt;
+    const image = useMemo(() => src === undefined || problem !== undefined
+        ? undefined
+        : { key: galleryKey ?? src, src, alt: label, name }, [src, problem, label, name, galleryKey]);
+    const { open, viewer } = useViewerImage(broken ? undefined : image, ref);
+    const shown = broken ? FAILED : problem;
+    const box = size === "md" ? "h-40 w-60" : "h-24 w-32";
+    const shape = heldShape(width, height, size);
+    const body = shown !== undefined ? (_jsx(ProblemCard, { label: label, problem: shown })) : src === undefined ? (_jsx("span", { "data-slot": "transcript-image", "data-state": "loading", role: "img", "aria-label": t.loading, "aria-busy": true, style: shape, className: cn(frame, "block max-w-full animate-pulse-soft", shape === undefined && box) })) : (_jsx("button", { ref: ref, type: "button", "data-slot": "transcript-image", "data-state": loaded ? "loaded" : "loading", "aria-label": t.open({ alt: label }), "aria-haspopup": "dialog", onClick: open, style: shape, className: cn(frame, "block max-w-full cursor-zoom-in overflow-hidden outline-none focus-visible:ring-focus", !loaded &&
+            cn("animate-pulse-soft", shape === undefined && (size === "md" ? "min-h-40 min-w-60" : "min-h-24 min-w-32"))), children: _jsx("img", { src: src, alt: "", loading: "lazy", decoding: "async", draggable: false, onLoad: () => setLoaded(true), onError: () => setBroken(true), className: cn("block object-contain", shape === undefined
+                ? cn("h-auto w-auto max-w-full", size === "md" ? "max-h-80" : "max-h-40")
+                : "size-full") }) }));
+    return (_jsxs("span", { className: cn("inline-flex max-w-full flex-col items-start gap-1 align-top", className), children: [body, caption !== undefined && _jsx("span", { className: "max-w-full truncate text-xs text-fg-subtle", children: caption }), viewer] }));
+}
+const FAILED = { kind: "failed" };

package/dist/components/image-viewer.d.ts

@@ -0,0 +1,60 @@
+import { type ReactNode, type RefObject } from "react";
+/** One image the viewer shows. */
+export interface ViewerImage {
+    /** Which image it is in its gallery: what a thumbnail opens the viewer on. */
+    readonly key: string;
+    /** What `<img>` loads (inline data, a blob, an object URL); or `load` gets it when it's shown. */
+    readonly src?: string | undefined;
+    /** Gets the image when the viewer comes to it (one whose thumbnail isn't on screen). */
+    readonly load?: (() => Promise<string | undefined>) | undefined;
+    /** What it shows: the viewer's title and the image's text alternative. */
+    readonly alt: string;
+    /** The file name Save suggests; without one, a name from its type. */
+    readonly name?: string | undefined;
+}
+export interface ImageViewerProps {
+    /** The images it steps through (a turn's), in reading order. */
+    readonly images: readonly ViewerImage[];
+    /** The one on show. */
+    readonly index: number;
+    readonly onIndexChange: (index: number) => void;
+    readonly onClose: () => void;
+    /** Where the focus goes back to on close (the thumbnail that opened it, while it's still there). */
+    readonly returnFocus?: (() => HTMLElement | null) | undefined;
+}
+/**
+ * An image full size over the page: the whole image in the window at first, then zoom (the wheel, a
+ * pinch, + and −, a double click) and drag to look around; ← and → step through the other images in
+ * reading order (so in a right-to-left language → goes back), Esc closes. Copy puts it on the
+ * clipboard as a PNG and says so on the button; Save downloads it. Zoom and panning move the picture
+ * by `transform` only.
+ */
+export declare function ImageViewer({ images, index, onIndexChange, onClose, returnFocus }: ImageViewerProps): import("react").JSX.Element | null;
+export interface ImageGalleryProps {
+    /**
+     * A group's images (a turn's) in reading order, from the host's own data, so ← → reach the ones
+     * scrolled out of view too; without it (or for an image it doesn't list), the ones on screen.
+     */
+    readonly imagesOf?: ((group: string) => readonly ViewerImage[]) | undefined;
+    readonly children: ReactNode;
+}
+/**
+ * Where images open together: a thumbnail's click opens the viewer on it, and ← → step through the
+ * other images of its group (`ImageGroup`, a turn), in reading order. Without one, an image opens on
+ * its own.
+ */
+export declare function ImageGallery({ imagesOf, children }: ImageGalleryProps): import("react").JSX.Element;
+/** The images below open together in the gallery (a turn's). */
+export declare function ImageGroup({ id, children }: {
+    readonly id: string;
+    readonly children: ReactNode;
+}): import("react").JSX.Element;
+/**
+ * An image that opens in the viewer: in the gallery around it with its group, else on its own.
+ * `element` is what puts it in reading order and gets the focus back. Returns the open action and,
+ * without a gallery, the viewer to render.
+ */
+export declare function useViewerImage(image: ViewerImage | undefined, element: RefObject<HTMLElement | null>): {
+    readonly open: () => void;
+    readonly viewer: ReactNode;
+};