@instruments/materia-ui 0.1.0

package/dist/components/field/field-label.js

@@ -0,0 +1,29 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Field as FieldPrimitive } from "@base-ui/react/field";
+import { Label } from "@instruments/materia-ui/components/label";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { useFieldContext } from "../field/field-context.js";
+/**
+ * Label for a field (Base UI `Field.Label`). Inside a `<Field>` it is
+ * associated with the field's control automatically, so clicking it focuses
+ * the control and no `htmlFor` is needed. Can wrap interactive elements like
+ * checkboxes/radios for larger click targets. When rendered inside an invalid
+ * `<Field>`, receives `data-invalid` so the label text turns destructive.
+ *
+ * @param props - The field label props
+ * @param props.className - Additional CSS classes to apply.
+ * @param props.children - Label text or interactive elements.
+ * @param props.htmlFor - Optional explicit target; overrides the automatic association.
+ * @param props... - All other Label component props.
+ *
+ * @example
+ * ```tsx
+ * <FieldLabel>Email Address</FieldLabel>
+ * <FieldLabel><Checkbox /> Accept terms</FieldLabel>
+ * ```
+ */
+export const FieldLabel = ({ className, htmlFor, ...props }) => {
+    const field = useFieldContext();
+    return (_jsx(FieldPrimitive.Label, { className: cn("group/field-label peer/field-label flex w-fit gap-2 group-data-[disabled=true]/field:opacity-50", "has-[>[data-slot=field]]:w-full has-[>[data-slot=field]]:flex-col has-[>[data-slot=field]]:rounded-md has-[>[data-slot=field]]:border *:data-[slot=field]:p-4", "has-data-checked:border-primary has-data-checked:bg-primary/5 dark:has-data-checked:bg-primary/10", className), "data-component": "field-label", "data-slot": "field-label", render: _jsx(Label, {}), ...(field?.invalid === true ? { "data-invalid": "true" } : {}), ...(htmlFor === undefined ? {} : { htmlFor }), ...props }));
+};

package/dist/components/field/field-root.d.ts

@@ -0,0 +1,40 @@
+import { Field as FieldPrimitive } from "@base-ui/react/field";
+import type { VariantProps } from "class-variance-authority";
+import { fieldVariants } from "../field/field-variants.js";
+export type FieldProps = Omit<FieldPrimitive.Root.Props, "className" | "invalid"> & VariantProps<typeof fieldVariants> & {
+    /** Additional CSS classes to apply. */
+    className?: string | undefined;
+    /** Marks the field invalid and cascades aria-invalid to its control. */
+    invalid?: boolean | undefined;
+};
+/**
+ * Flexible field container (Base UI `Field.Root`) that arranges label and
+ * content in various orientations. Its parts wire themselves to the control:
+ * `FieldLabel` gets `htmlFor`, and `FieldDescription`/`FieldError` join the
+ * control's `aria-describedby`.
+ *
+ * @param props - The field props
+ * @param props.orientation - Layout orientation. Options: "vertical" (default), "horizontal", "responsive" (vertical on mobile, horizontal on desktop).
+ * @param props.invalid - Marks the field invalid: sets `data-invalid` (turning label/content destructive) and `aria-invalid` on the field's control.
+ * @param props.disabled - Disables the field and its control.
+ * @param props.className - Additional CSS classes to apply.
+ * @param props.children - FieldLabel, FieldContent, and other field components.
+ * @param props... - All other Base UI `Field.Root` props.
+ *
+ * @example
+ * ```tsx
+ * <Field invalid orientation="vertical">
+ *   <FieldLabel>Name</FieldLabel>
+ *   <FieldContent>
+ *     <Input />
+ *     <FieldError errors={[{ message: "Required" }]} />
+ *   </FieldContent>
+ * </Field>
+ * ```
+ *
+ * @bestPractice Set `invalid` on the `Field`, not on each control - it sets `aria-invalid` on the field's `Input`/`InputGroupInput`/`Textarea` and turns the `FieldLabel` destructive.
+ * @bestPractice Compose the documented parts (`FieldLabel`, `FieldContent`, `FieldError`, `FieldDescription`) around one control - the label's `htmlFor` and the control's `aria-describedby` are wired for you, so there are no ids to pass.
+ * @bestPractice Use `orientation="responsive"` for a label-beside-control that collapses to stacked on mobile, rather than duplicating the field per breakpoint.
+ * @category forms
+ */
+export declare const Field: ({ className, orientation, id, invalid, children, ...props }: FieldProps) => import("react").JSX.Element;

package/dist/components/field/field-root.js

@@ -0,0 +1,37 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Field as FieldPrimitive } from "@base-ui/react/field";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { FieldProvider } from "../field/field-context.js";
+import { fieldVariants } from "../field/field-variants.js";
+/**
+ * Flexible field container (Base UI `Field.Root`) that arranges label and
+ * content in various orientations. Its parts wire themselves to the control:
+ * `FieldLabel` gets `htmlFor`, and `FieldDescription`/`FieldError` join the
+ * control's `aria-describedby`.
+ *
+ * @param props - The field props
+ * @param props.orientation - Layout orientation. Options: "vertical" (default), "horizontal", "responsive" (vertical on mobile, horizontal on desktop).
+ * @param props.invalid - Marks the field invalid: sets `data-invalid` (turning label/content destructive) and `aria-invalid` on the field's control.
+ * @param props.disabled - Disables the field and its control.
+ * @param props.className - Additional CSS classes to apply.
+ * @param props.children - FieldLabel, FieldContent, and other field components.
+ * @param props... - All other Base UI `Field.Root` props.
+ *
+ * @example
+ * ```tsx
+ * <Field invalid orientation="vertical">
+ *   <FieldLabel>Name</FieldLabel>
+ *   <FieldContent>
+ *     <Input />
+ *     <FieldError errors={[{ message: "Required" }]} />
+ *   </FieldContent>
+ * </Field>
+ * ```
+ *
+ * @bestPractice Set `invalid` on the `Field`, not on each control - it sets `aria-invalid` on the field's `Input`/`InputGroupInput`/`Textarea` and turns the `FieldLabel` destructive.
+ * @bestPractice Compose the documented parts (`FieldLabel`, `FieldContent`, `FieldError`, `FieldDescription`) around one control - the label's `htmlFor` and the control's `aria-describedby` are wired for you, so there are no ids to pass.
+ * @bestPractice Use `orientation="responsive"` for a label-beside-control that collapses to stacked on mobile, rather than duplicating the field per breakpoint.
+ * @category forms
+ */
+export const Field = ({ className, orientation = "vertical", id, invalid = false, children, ...props }) => (_jsx(FieldProvider, { id: id, invalid: invalid, children: _jsx(FieldPrimitive.Root, { className: cn(fieldVariants({ orientation }), "min-w-0", className), "data-component": "field", "data-orientation": orientation, "data-slot": "field", id: id, invalid: invalid, ...(invalid ? { "data-invalid": "true" } : {}), ...props, children: children }) }));

package/dist/components/field/field-variants.d.ts

@@ -0,0 +1,8 @@
+/**
+ * fieldVariants variant class helper for Field.
+ * Import from "@instruments/materia-ui/components/field".
+ * Uses variant-based styling via class-variance-authority.
+ */
+export declare const fieldVariants: (props?: ({
+    orientation?: "horizontal" | "responsive" | "vertical" | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;

package/dist/components/field/field-variants.js

@@ -0,0 +1,26 @@
+import { cva } from "class-variance-authority";
+/**
+ * fieldVariants variant class helper for Field.
+ * Import from "@instruments/materia-ui/components/field".
+ * Uses variant-based styling via class-variance-authority.
+ */
+export const fieldVariants = cva("group/field data-[invalid=true]:text-destructive flex w-full gap-3", {
+    defaultVariants: {
+        orientation: "vertical",
+    },
+    variants: {
+        orientation: {
+            vertical: ["flex-col *:w-full [&>.sr-only]:w-auto"],
+            horizontal: [
+                "flex-row items-center",
+                "[&>[data-slot=field-label]]:flex-auto",
+                "has-[>[data-slot=field-content]]:items-start has-[>[data-slot=field-content]]:[&>[role=checkbox],[role=radio]]:mt-px",
+            ],
+            responsive: [
+                "flex-col *:w-full @md/field-group:flex-row @md/field-group:items-center @md/field-group:*:w-auto [&>.sr-only]:w-auto",
+                "@md/field-group:[&>[data-slot=field-label]]:flex-auto",
+                "@md/field-group:has-[>[data-slot=field-content]]:items-start @md/field-group:has-[>[data-slot=field-content]]:[&>[role=checkbox],[role=radio]]:mt-px",
+            ],
+        },
+    },
+});

package/dist/components/field.d.ts

@@ -0,0 +1,8 @@
+export { fieldAnatomy, fieldGroupAnatomy } from "./field/field-anatomy.js";
+export { FieldContent } from "./field/field-content.js";
+export { FieldDescription } from "./field/field-description.js";
+export { FieldError } from "./field/field-error.js";
+export { FieldGroup } from "./field/field-group.js";
+export { FieldLabel } from "./field/field-label.js";
+export { Field } from "./field/field-root.js";
+export { fieldVariants } from "./field/field-variants.js";

package/dist/components/field.js

@@ -0,0 +1,8 @@
+export { fieldAnatomy, fieldGroupAnatomy } from "./field/field-anatomy.js";
+export { FieldContent } from "./field/field-content.js";
+export { FieldDescription } from "./field/field-description.js";
+export { FieldError } from "./field/field-error.js";
+export { FieldGroup } from "./field/field-group.js";
+export { FieldLabel } from "./field/field-label.js";
+export { Field } from "./field/field-root.js";
+export { fieldVariants } from "./field/field-variants.js";

package/dist/components/flex/flex-root.d.ts

@@ -0,0 +1,56 @@
+import { useRender } from "@base-ui/react/use-render";
+import type { FlexAlign } from "../../tokens/alignment.js";
+import type { FlexDirection } from "../../tokens/direction.js";
+import type { LayoutElement, LayoutHostAttributes, LayoutHostKey } from "../../tokens/element.js";
+import type { FlexJustify } from "../../tokens/justify.js";
+import type { ResponsiveMode, LayoutResponsiveValue } from "../../tokens/responsive.js";
+import type { GapSize } from "../../tokens/responsive-classes.js";
+import type { FlexWrap } from "../../tokens/wrap.js";
+export interface FlexProps extends Omit<useRender.ComponentProps<"div">, LayoutHostKey>, LayoutHostAttributes {
+    /** Cross-axis alignment. Accepts a per-breakpoint responsive object. @default "stretch" */
+    align?: LayoutResponsiveValue<FlexAlign>;
+    /**
+     * Render as a different host element from the closed layout vocabulary
+     * ({@link LayoutElement}). The set is deliberately closed: `as="button"` is a
+     * type error, because the design-system answer is the Button component. Event handlers
+     * and the ref accept any host element.
+     *
+     * `as` and `render` are mutually exclusive; if both are passed, `render`
+     * wins (a dev-only warning fires).
+     * @example <Flex as="nav">
+     */
+    as?: LayoutElement;
+    /** Main-axis direction. Accepts a per-breakpoint responsive object. @default "row" */
+    direction?: LayoutResponsiveValue<FlexDirection>;
+    /** Gap between items, from the spacing scale. Accepts a per-breakpoint responsive object. */
+    gap?: LayoutResponsiveValue<GapSize>;
+    /** Show dashed outline guidelines during development. @default false */
+    guidelines?: boolean;
+    /** Render as inline-flex instead of flex. @default false */
+    inline?: boolean;
+    /** Main-axis distribution. Accepts a per-breakpoint responsive object. @default "flex-start" */
+    justify?: LayoutResponsiveValue<FlexJustify>;
+    /** Whether responsive values resolve against the viewport ("screen") or nearest container ("container"). @default "screen" */
+    responsiveMode?: ResponsiveMode;
+    /** Wrap behaviour. Accepts a per-breakpoint responsive object. @default "nowrap" */
+    wrap?: LayoutResponsiveValue<FlexWrap>;
+}
+/**
+ * Flexbox container with token-driven direction, alignment, justification, wrapping, and gap.
+ *
+ * Layout props (`direction`, `justify`, `align`, `wrap`, `gap`) accept a single value or a
+ * per-breakpoint responsive object like `{ base: "column", md: "row" }`; set `responsiveMode`
+ * to `"container"` to resolve breakpoints against the nearest container instead of the viewport.
+ *
+ * @example
+ * ```tsx
+ * <Flex direction={{ base: "column", md: "row" }} justify="space-between" gap="base" />
+ * ```
+ *
+ * @bestPractice `Flex` exposes full flexbox (`direction`/`justify`/`align`/`wrap`) and defaults to a row; for a simple gapped column reach for `Stack`, for a wrapping cluster `Group`.
+ * @bestPractice Every layout prop takes a responsive object like `{ base: "column", md: "row" }`; set `responsiveMode="container"` to resolve breakpoints against the nearest container.
+ * @bestPractice `as` and `render` are mutually exclusive (`render` wins, dev-warned); `as` draws from the closed layout vocabulary, so `as="button"` is a type error (use `Button`).
+ * @bestPractice Use `as` to change the element (a tag); use `render` only to swap in a component (e.g. a router Link). Never `render={<Box as=…/>}` - pass `as` directly.
+ * @category layout
+ */
+export declare const Flex: ({ as, className, direction, justify, align, wrap, gap, inline, responsiveMode, guidelines, ref, render, ...props }: FlexProps) => import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;

package/dist/components/flex/flex-root.js

@@ -0,0 +1,48 @@
+import { useRender } from "@base-ui/react/use-render";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { pushResponsiveClasses } from "../../tokens/responsive.js";
+import { ALIGN_CLASS, DIRECTION_CLASS, GAP_CLASS, JUSTIFY_CLASS, WRAP_CLASS, } from "../../tokens/responsive-classes.js";
+import { reportDevIssue } from "../../utils/dev-issue.js";
+/**
+ * Flexbox container with token-driven direction, alignment, justification, wrapping, and gap.
+ *
+ * Layout props (`direction`, `justify`, `align`, `wrap`, `gap`) accept a single value or a
+ * per-breakpoint responsive object like `{ base: "column", md: "row" }`; set `responsiveMode`
+ * to `"container"` to resolve breakpoints against the nearest container instead of the viewport.
+ *
+ * @example
+ * ```tsx
+ * <Flex direction={{ base: "column", md: "row" }} justify="space-between" gap="base" />
+ * ```
+ *
+ * @bestPractice `Flex` exposes full flexbox (`direction`/`justify`/`align`/`wrap`) and defaults to a row; for a simple gapped column reach for `Stack`, for a wrapping cluster `Group`.
+ * @bestPractice Every layout prop takes a responsive object like `{ base: "column", md: "row" }`; set `responsiveMode="container"` to resolve breakpoints against the nearest container.
+ * @bestPractice `as` and `render` are mutually exclusive (`render` wins, dev-warned); `as` draws from the closed layout vocabulary, so `as="button"` is a type error (use `Button`).
+ * @bestPractice Use `as` to change the element (a tag); use `render` only to swap in a component (e.g. a router Link). Never `render={<Box as=…/>}` - pass `as` directly.
+ * @category layout
+ */
+export const Flex = ({ as, className, direction = "row", justify = "flex-start", align = "stretch", wrap = "nowrap", gap, inline = false, responsiveMode = "screen", guidelines = false, ref, render, ...props }) => {
+    if (render !== undefined && as !== undefined) {
+        reportDevIssue("Flex: `as` and `render` are mutually exclusive; `render` wins and `as` is ignored.");
+    }
+    const classes = [inline ? "inline-flex" : "flex"];
+    pushResponsiveClasses(classes, direction, DIRECTION_CLASS, responsiveMode);
+    pushResponsiveClasses(classes, justify, JUSTIFY_CLASS, responsiveMode);
+    pushResponsiveClasses(classes, align, ALIGN_CLASS, responsiveMode);
+    pushResponsiveClasses(classes, wrap, WRAP_CLASS, responsiveMode);
+    pushResponsiveClasses(classes, gap, GAP_CLASS, responsiveMode);
+    if (guidelines) {
+        classes.push("outline", "outline-1", "outline-dashed", "outline-muted-foreground/30");
+    }
+    return useRender({
+        defaultTagName: as ?? "div",
+        props: {
+            className: cn(classes.join(" "), className),
+            "data-component": "flex",
+            "data-slot": "flex",
+            ...props,
+        },
+        ref,
+        render,
+    });
+};

package/dist/components/flex/flex.test-d.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Type-level surface guards for Flex's closed `as` vocabulary (plan M1a).
+ *
+ * Evaluated by `tsc --noEmit` (the `typecheck` gate), not by vitest or the
+ * Playwright story smoke - a `.test-d.ts` name matches neither runner's globs.
+ *
+ * Load-bearing invariant: `as` draws from {@link LayoutElement} only, so
+ * `as="button"` is a type error. If the union widens to `string`, the rejection
+ * guards stop satisfying `extends true` and the typecheck fails.
+ */
+import type { ComponentProps, ReactElement } from "react";
+import type { Flex } from "./flex-root.js";
+/** Passes only when `T` is exactly `true`. */
+type Expect<T extends true> = T;
+/** Boolean negation at the type level. */
+type Not<B extends boolean> = B extends true ? false : true;
+/** `true` iff a value of type `V` is accepted as Flex props. */
+type Accepts<V> = V extends ComponentProps<typeof Flex> ? true : false;
+export type NavAccepted = Expect<Accepts<{
+    as: "nav";
+}>>;
+export type ButtonRejected = Expect<Not<Accepts<{
+    as: "button";
+}>>>;
+export type AnchorRejected = Expect<Not<Accepts<{
+    as: "a";
+}>>>;
+export type InputRejected = Expect<Not<Accepts<{
+    as: "input";
+}>>>;
+export type RenderAccepted = Expect<Accepts<{
+    render: ReactElement;
+}>>;
+export type ArgsNonNever = Expect<Not<[ComponentProps<typeof Flex>] extends [never] ? true : false>>;
+export type BreakpointKeysAccepted = Expect<Accepts<{
+    gap: {
+        base: "sm";
+        md: "lg";
+        "3xl": "xl";
+    };
+}>>;
+export type ContainerKeyRejected = Expect<Not<Accepts<{
+    gap: {
+        "@md": "lg";
+    };
+}>>>;
+export type MixedContainerKeyRejected = Expect<Not<Accepts<{
+    direction: {
+        md: "row";
+        "@md": "column";
+    };
+}>>>;
+export type ListPropsAccepted = Expect<Accepts<ComponentProps<"ul"> & {
+    as: "ul";
+}>>;
+export type ListItemPropsAccepted = Expect<Accepts<ComponentProps<"li"> & {
+    as: "li";
+}>>;
+export type DivPropsAccepted = Expect<Accepts<ComponentProps<"div">>>;
+export {};

package/dist/components/flex/flex.test-d.js

@@ -0,0 +1 @@
+export {};

package/dist/components/flex.d.ts

@@ -0,0 +1 @@
+export { Flex, type FlexProps } from "./flex/flex-root.js";

package/dist/components/flex.js

@@ -0,0 +1 @@
+export { Flex } from "./flex/flex-root.js";

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

@@ -0,0 +1,70 @@
+import type { ReactNode } from "react";
+interface ImageRenderProps {
+    /** Additional className */
+    className?: string | undefined;
+    /** Image source URL */
+    src: string;
+}
+interface GalleryImageProps {
+    /**
+     * Alt text for the built-in `<img>` renderer used when `children` is omitted.
+     * Required in that mode (a dev-only warning fires otherwise); pass `""` to
+     * mark the image decorative. Ignored when `children` is provided.
+     */
+    alt?: string;
+    /**
+     * Render function that receives props to spread onto your image component.
+     * Must pass `src` and `className` to the rendered image surface. When omitted,
+     * GalleryImage renders a plain `<img>` (see `alt`).
+     */
+    children?: (props: ImageRenderProps) => ReactNode;
+    /** Additional className for the image */
+    className?: string;
+    /** Current image source URL; changing it triggers the crossfade transition. */
+    src: string;
+}
+/**
+ * Gallery image that handles variant changes with crossfade.
+ * Shows old image + shimmer while new image loads, then crossfades.
+ *
+ * Framework-agnostic: uses a render prop to let you provide any image component.
+ *
+ * @example
+ * ```tsx
+ * // With next/image
+ * <GalleryImage src={currentImageUrl}>
+ *   {(props) => (
+ *     <Image
+ *       alt="Product"
+ *       className={props.className}
+ *       fill
+ *       sizes="50vw"
+ *       src={props.src}
+ *     />
+ *   )}
+ * </GalleryImage>
+ *
+ * // With a background image surface
+ * <GalleryImage src={currentImageUrl}>
+ *   {(props) => (
+ *     <div
+ *       aria-label="Product"
+ *       className={props.className}
+ *       role="img"
+ *       style={{ backgroundImage: `url(${props.src})` }}
+ *     />
+ *   )}
+ * </GalleryImage>
+ *
+ * // Without a render prop - a plain <img> with the given alt text
+ * <GalleryImage alt="Terracotta tile" src={currentImageUrl} />
+ * ```
+ *
+ * @bestPractice In Next.js pass a `children` render prop wrapping `next/image` and thread its `src`+`className` through - the default renderer is a plain `<img>` that skips Next optimisation.
+ * @bestPractice When you omit `children`, `alt` is required (a dev warning fires otherwise); pass `alt=""` to mark the image decorative. `alt` is ignored once a render prop supplies its own image.
+ * @bestPractice Drive variant switches by changing `src` - that triggers the built-in crossfade + shimmer; don't unmount/remount `GalleryImage` per variant or you lose the transition.
+ * @bestPractice Position `GalleryImage` inside a `relative` container with fixed dimensions - the surfaces are `absolute inset-0`, so an unsized parent collapses to zero height.
+ * @category data
+ */
+export declare const GalleryImage: ({ alt, src, children, className, }: GalleryImageProps) => import("react").JSX.Element;
+export {};

package/dist/components/gallery/gallery-image.js

@@ -0,0 +1,121 @@
+"use client";
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { durations } from "@instruments/materia-ui/tokens/motion";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { AnimatePresence } from "motion/react";
+import * as m from "motion/react-m";
+import { Fragment, useEffect, useState } from "react";
+import { reportDevIssue } from "../../utils/dev-issue.js";
+import { ImageSkeleton } from "../gallery/image-skeleton.js";
+/** How long the crossfade lingers after the new image has loaded. */
+const SETTLE_DELAY_MS = 50;
+/**
+ * Built-in image surface, used as the default `children` when no render prop is
+ * supplied. Returns a render function so each of the three crossfade call sites
+ * threads its own state `className` (z-index/opacity) through the same `<img>`.
+ * Warns (dev-only) when `alt` is missing, since that path is where the built-in
+ * renderer needs it for accessibility.
+ */
+const defaultImageRenderer = (alt) => {
+    if (alt === undefined) {
+        reportDevIssue('GalleryImage: `alt` is required when `children` is omitted; the built-in <img> renderer needs it for accessibility (pass `alt=""` for a decorative image).');
+    }
+    return function DefaultImage({ src, className }) {
+        return (_jsx("img", { alt: alt ?? "", className: cn("absolute inset-0 size-full object-cover", className), src: src }));
+    };
+};
+/**
+ * Gallery image that handles variant changes with crossfade.
+ * Shows old image + shimmer while new image loads, then crossfades.
+ *
+ * Framework-agnostic: uses a render prop to let you provide any image component.
+ *
+ * @example
+ * ```tsx
+ * // With next/image
+ * <GalleryImage src={currentImageUrl}>
+ *   {(props) => (
+ *     <Image
+ *       alt="Product"
+ *       className={props.className}
+ *       fill
+ *       sizes="50vw"
+ *       src={props.src}
+ *     />
+ *   )}
+ * </GalleryImage>
+ *
+ * // With a background image surface
+ * <GalleryImage src={currentImageUrl}>
+ *   {(props) => (
+ *     <div
+ *       aria-label="Product"
+ *       className={props.className}
+ *       role="img"
+ *       style={{ backgroundImage: `url(${props.src})` }}
+ *     />
+ *   )}
+ * </GalleryImage>
+ *
+ * // Without a render prop - a plain <img> with the given alt text
+ * <GalleryImage alt="Terracotta tile" src={currentImageUrl} />
+ * ```
+ *
+ * @bestPractice In Next.js pass a `children` render prop wrapping `next/image` and thread its `src`+`className` through - the default renderer is a plain `<img>` that skips Next optimisation.
+ * @bestPractice When you omit `children`, `alt` is required (a dev warning fires otherwise); pass `alt=""` to mark the image decorative. `alt` is ignored once a render prop supplies its own image.
+ * @bestPractice Drive variant switches by changing `src` - that triggers the built-in crossfade + shimmer; don't unmount/remount `GalleryImage` per variant or you lose the transition.
+ * @bestPractice Position `GalleryImage` inside a `relative` container with fixed dimensions - the surfaces are `absolute inset-0`, so an unsized parent collapses to zero height.
+ * @category data
+ */
+export const GalleryImage = ({ alt, src, 
+// Default to the built-in <img> surface when no render prop is supplied; `alt`
+// is already bound above, so the default (and its dev-only warning) sees it.
+children = defaultImageRenderer(alt), className, }) => {
+    // `settledSrc` is the image on screen once it has loaded (null until the first
+    // load); `loadedSrc` is the latest source whose preload finished. Everything
+    // else (the outgoing image, the transition, the shimmer) is derived from them
+    // and the `src` prop, so a src change flips every field in a single render.
+    const [loadState, setLoadState] = useState({
+        loadedSrc: null,
+        settledSrc: null,
+    });
+    // The preload is an off-DOM HTMLImageElement (new window.Image()) whose "load"
+    // has no React-renderable element to attach an onLoad handler to - the
+    // render-prop surface may be a background div.
+    useEffect(() => {
+        let active = true;
+        let settleTimer;
+        const image = new window.Image();
+        const handleLoad = () => {
+            if (!active) {
+                return;
+            }
+            // The first image has nothing to crossfade from: it settles at once.
+            setLoadState((prev) => prev.settledSrc === null
+                ? { loadedSrc: src, settledSrc: src }
+                : { ...prev, loadedSrc: src });
+            settleTimer = window.setTimeout(() => {
+                setLoadState((prev) => prev.settledSrc === src ? prev : { ...prev, settledSrc: src });
+            }, SETTLE_DELAY_MS);
+        };
+        image.addEventListener("load", handleLoad);
+        image.src = src;
+        return () => {
+            active = false;
+            window.clearTimeout(settleTimer);
+            image.removeEventListener("load", handleLoad);
+        };
+    }, [src]);
+    const { loadedSrc, settledSrc } = loadState;
+    const isInitialLoading = settledSrc === null;
+    const isTransitioning = settledSrc !== null && settledSrc !== src;
+    const newImageLoaded = loadedSrc === src;
+    const showShimmer = isInitialLoading || (isTransitioning && !newImageLoaded);
+    return (_jsxs(_Fragment, { children: [isTransitioning && settledSrc !== "" && (_jsx(Fragment, { children: children({
+                    className: cn(className, "z-0"),
+                    src: settledSrc,
+                }) }, "previous")), _jsx(Fragment, { children: children({
+                    className: cn(className, isTransitioning ? "z-10" : "z-0", isTransitioning && !newImageLoaded && "opacity-0"),
+                    src,
+                }) }, "current"), _jsx(AnimatePresence, { children: showShimmer && (_jsx(m.div, { animate: { opacity: 1 }, className: "absolute inset-0 z-30", exit: { opacity: 0 }, initial: { opacity: 1 }, transition: { duration: durations.normal }, children: _jsx(ImageSkeleton, {}) })) })] }));
+};

package/dist/components/gallery/image-skeleton.d.ts

@@ -0,0 +1,13 @@
+interface ImageSkeletonProps {
+    className?: string;
+}
+/**
+ * Shimmer skeleton for loading state.
+ *
+ * Deliberately no z-index: it renders after its sibling image in every
+ * consumer, so DOM order already paints it on top locally - an explicit z here
+ * escapes the (non-isolated) image container and covers surrounding chrome
+ * (it sat above the quickview sidepanel's controls during load).
+ */
+export declare const ImageSkeleton: ({ className }: ImageSkeletonProps) => import("react").JSX.Element;
+export {};

package/dist/components/gallery/image-skeleton.js

@@ -0,0 +1,12 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { cn } from "@instruments/materia-ui/utils/cn";
+/**
+ * Shimmer skeleton for loading state.
+ *
+ * Deliberately no z-index: it renders after its sibling image in every
+ * consumer, so DOM order already paints it on top locally - an explicit z here
+ * escapes the (non-isolated) image container and covers surrounding chrome
+ * (it sat above the quickview sidepanel's controls during load).
+ */
+export const ImageSkeleton = ({ className }) => (_jsx("div", { className: cn("absolute inset-0 bg-gray-200", className) }));

package/dist/components/gallery/loading-image.d.ts

@@ -0,0 +1,35 @@
+import type { ReactNode } from "react";
+/** What `LoadingImage` hands the image it renders. */
+interface LoadingImageRenderProps {
+    /** The `className` given to `LoadingImage`, for the image to apply. */
+    className: string | undefined;
+    /** Attach to the image so the skeleton fades out once it has loaded. */
+    onLoad: () => void;
+}
+interface LoadingImageProps {
+    /** Render the image (e.g. next/image, native img), applying the given props. */
+    children: (props: LoadingImageRenderProps) => ReactNode;
+    /** Additional className handed to the image. */
+    className?: string;
+}
+/**
+ * Image wrapper with loading state - shows shimmer while loading.
+ *
+ * Framework-agnostic: `children` is a render function, so any image element
+ * works as long as it applies the given `onLoad` and `className`.
+ *
+ * @example
+ * ```tsx
+ * // With next/image
+ * <LoadingImage>
+ *   {(props) => <Image src={url} alt="..." fill sizes="256px" {...props} />}
+ * </LoadingImage>
+ *
+ * // With native img
+ * <LoadingImage className="size-full object-cover">
+ *   {(props) => <img src={url} alt="..." {...props} />}
+ * </LoadingImage>
+ * ```
+ */
+export declare const LoadingImage: ({ children, className }: LoadingImageProps) => import("react").JSX.Element;
+export {};

package/dist/components/gallery/loading-image.js

@@ -0,0 +1,36 @@
+"use client";
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { durations } from "@instruments/materia-ui/tokens/motion";
+import { AnimatePresence } from "motion/react";
+import * as m from "motion/react-m";
+import { useState } from "react";
+import { ImageSkeleton } from "../gallery/image-skeleton.js";
+/**
+ * Image wrapper with loading state - shows shimmer while loading.
+ *
+ * Framework-agnostic: `children` is a render function, so any image element
+ * works as long as it applies the given `onLoad` and `className`.
+ *
+ * @example
+ * ```tsx
+ * // With next/image
+ * <LoadingImage>
+ *   {(props) => <Image src={url} alt="..." fill sizes="256px" {...props} />}
+ * </LoadingImage>
+ *
+ * // With native img
+ * <LoadingImage className="size-full object-cover">
+ *   {(props) => <img src={url} alt="..." {...props} />}
+ * </LoadingImage>
+ * ```
+ */
+export const LoadingImage = ({ children, className }) => {
+    const [isLoaded, setIsLoaded] = useState(false);
+    const image = children({
+        className,
+        onLoad: () => {
+            setIsLoaded(true);
+        },
+    });
+    return (_jsxs(_Fragment, { children: [image, _jsx(AnimatePresence, { children: !isLoaded && (_jsx(m.div, { animate: { opacity: 1 }, className: "absolute inset-0", exit: { opacity: 0 }, initial: { opacity: 1 }, transition: { duration: durations.normal }, children: _jsx(ImageSkeleton, {}) })) })] }));
+};

package/dist/components/gallery.d.ts

@@ -0,0 +1,3 @@
+export { GalleryImage } from "./gallery/gallery-image.js";
+export { ImageSkeleton } from "./gallery/image-skeleton.js";
+export { LoadingImage } from "./gallery/loading-image.js";

package/dist/components/gallery.js

@@ -0,0 +1,3 @@
+export { GalleryImage } from "./gallery/gallery-image.js";
+export { ImageSkeleton } from "./gallery/image-skeleton.js";
+export { LoadingImage } from "./gallery/loading-image.js";