@vamos-ui/react 0.0.0-stage → 0.2.0

package/dist/components/hover-card.d.ts

@@ -0,0 +1,21 @@
+import * as React from "react";
+import { HoverCard as HoverCardPrimitive } from "radix-ui";
+import { type VariantProps } from "class-variance-authority";
+export interface HoverCardProps extends React.ComponentProps<typeof HoverCardPrimitive.Root> {
+}
+/**
+ * Root. Opens after 500 ms of hover and closes 150 ms after the pointer leaves.
+ * Hover cards are *extra* information for pointer users: they don't open from the keyboard or on
+ * touch, so the same details must be reachable on the link target.
+ */
+export declare function HoverCard({ openDelay, closeDelay, ...props }: HoverCardProps): React.JSX.Element;
+export declare const HoverCardTrigger: React.ForwardRefExoticComponent<HoverCardPrimitive.HoverCardTriggerProps & React.RefAttributes<HTMLAnchorElement>>;
+export declare const hoverCardContentVariants: (props?: ({
+    size?: "sm" | "md" | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;
+export interface HoverCardContentProps extends React.ComponentPropsWithoutRef<typeof HoverCardPrimitive.Content>, VariantProps<typeof hoverCardContentVariants> {
+    /** Show the pointer arrow. Default `false`. */
+    arrow?: boolean;
+}
+/** The preview panel. Portals into the nearest `ThemeScope` and follows the layer-depth glass rules. */
+export declare const HoverCardContent: React.ForwardRefExoticComponent<HoverCardContentProps & React.RefAttributes<HTMLDivElement>>;

package/dist/components/hover-card.js

@@ -0,0 +1,32 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import * as React from "react";
+import { HoverCard as HoverCardPrimitive } from "radix-ui";
+import { cva } from "class-variance-authority";
+import { cn } from "../lib/cn.js";
+import { usePortalContainer } from "../lib/theme-scope.js";
+import { Layer } from "../lib/layer.js";
+import { FloatingArrow } from "../lib/floating-arrow.js";
+/**
+ * Root. Opens after 500 ms of hover and closes 150 ms after the pointer leaves.
+ * Hover cards are *extra* information for pointer users: they don't open from the keyboard or on
+ * touch, so the same details must be reachable on the link target.
+ */
+export function HoverCard({ openDelay = 500, closeDelay = 150, ...props }) {
+    return _jsx(HoverCardPrimitive.Root, { openDelay: openDelay, closeDelay: closeDelay, ...props });
+}
+export const HoverCardTrigger = HoverCardPrimitive.Trigger;
+export const hoverCardContentVariants = cva("surface-popover ui-pop z-(--z-popover) rounded-ui-lg p-[calc(var(--gap)*0.85)] outline-none max-w-[calc(100vw-1.5rem)]", {
+    variants: {
+        size: {
+            sm: "w-64",
+            md: "w-80",
+        },
+    },
+    defaultVariants: { size: "md" },
+});
+/** The preview panel. Portals into the nearest `ThemeScope` and follows the layer-depth glass rules. */
+export const HoverCardContent = React.forwardRef(function HoverCardContent({ className, size, arrow = false, sideOffset = 8, collisionPadding = 12, children, ...props }, ref) {
+    const container = usePortalContainer();
+    return (_jsx(HoverCardPrimitive.Portal, { container: container, children: _jsx(Layer, { asChild: true, children: _jsxs(HoverCardPrimitive.Content, { ref: ref, "data-slot": "hover-card-content", sideOffset: sideOffset, collisionPadding: collisionPadding, className: cn(hoverCardContentVariants({ size }), className), ...props, children: [children, arrow ? (_jsx(HoverCardPrimitive.Arrow, { asChild: true, width: 14, height: 7, children: _jsx(FloatingArrow, {}) })) : null] }) }) }));
+});

package/dist/components/iban-input.d.ts

@@ -0,0 +1,38 @@
+import * as React from "react";
+import type { IbanCountryRule } from "../locale-data/core/types.js";
+import { type BaseFormattedProps } from "./formatted-input.js";
+declare const ibanInputLabels: {
+    length: string;
+    lengthGeneric: string;
+    chars: string;
+    checksum: string;
+    pattern: string;
+    country: string;
+    bank: string;
+};
+export type IbanInputLabels = typeof ibanInputLabels;
+export interface IbanInputProps extends BaseFormattedProps<string | null> {
+    /** Allowed country codes (`["TR"]`). Default: any. */
+    countries?: string[];
+    /** Per-country rules with BBAN patterns and bank lookups (locale packs). Default: the `tr` rule. */
+    rules?: IbanCountryRule[];
+    /**
+     * Bank name next to the number once the bank code is typed. `true` (default) uses the rules'
+     * `bankName`; pass a function for your own lookup, or `false` to hide it.
+     */
+    showBank?: boolean | ((iban: string) => string | undefined);
+    labels?: Partial<IbanInputLabels>;
+}
+/**
+ * IBAN entry: typed in groups of four (`TR33 0006 1005 1978 6457 8413 26`) with the caret kept in
+ * place, checked against the country length, BBAN pattern and ISO 13616 mod-97 checksum. The value
+ * is the electronic format (no spaces, uppercase). Turkish IBANs show the bank name.
+ *
+ * ```tsx
+ * <Field label="IBAN" error={error}>
+ *   <IbanInput countries={["TR"]} onValidate={(r) => setError(r.message)} />
+ * </Field>
+ * ```
+ */
+export declare const IbanInput: React.ForwardRefExoticComponent<IbanInputProps & React.RefAttributes<HTMLInputElement>>;
+export {};

package/dist/components/iban-input.js

@@ -0,0 +1,112 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import * as React from "react";
+import { Landmark } from "lucide-react";
+import { cn } from "../lib/cn.js";
+import { mergeIds, useComposedRefs } from "../lib/compose-refs.js";
+import { useLabels } from "../lib/labels.js";
+import { useLocale } from "../lib/locale.js";
+import { useFormattedInput } from "../lib/use-formatted-input.js";
+import { IBAN_LENGTHS, formatIban, normalizeIban, validateIban } from "../locale-data/core/iban.js";
+import { trIbanRule } from "../locale-data/tr/iban.js";
+import { Input } from "./input.js";
+import { WithoutFieldName, useFormattedValidity, useSubmitName } from "./formatted-input.js";
+const ibanInputLabels = {
+    length: "An IBAN from {country} has {length} characters",
+    lengthGeneric: "An IBAN has 15 to 34 characters",
+    chars: "An IBAN starts with a two-letter country code and two check digits",
+    checksum: "Invalid IBAN checksum. Check it for typos.",
+    pattern: "This isn't a valid IBAN for {country}",
+    country: "IBANs from {country} aren't accepted here",
+    bank: "Bank: {bank}",
+};
+function regionName(locale, code) {
+    try {
+        return new Intl.DisplayNames([locale], { type: "region" }).of(code) ?? code;
+    }
+    catch {
+        return code;
+    }
+}
+const accept = (ch) => /^[0-9A-Za-z]$/.test(ch);
+/**
+ * IBAN entry: typed in groups of four (`TR33 0006 1005 1978 6457 8413 26`) with the caret kept in
+ * place, checked against the country length, BBAN pattern and ISO 13616 mod-97 checksum. The value
+ * is the electronic format (no spaces, uppercase). Turkish IBANs show the bank name.
+ *
+ * ```tsx
+ * <Field label="IBAN" error={error}>
+ *   <IbanInput countries={["TR"]} onValidate={(r) => setError(r.message)} />
+ * </Field>
+ * ```
+ */
+export const IbanInput = React.forwardRef(function IbanInput({ countries, rules = [trIbanRule], showBank = true, value, defaultValue, onValueChange, validateOn = "blur", onValidate, mono = true, labels, name, invalid, trailing, inputClassName, onBlur, onKeyDown, disabled, placeholder, ...rest }, forwardedRef) {
+    const { locale } = useLocale();
+    const t = useLabels("ibanInput", ibanInputLabels, labels);
+    const v = useFormattedValidity(validateOn, onValidate);
+    const bankId = React.useId();
+    const maxFor = (compact) => {
+        const cc = compact.slice(0, 2).toUpperCase();
+        return rules.find((r) => r.country === cc)?.length ?? IBAN_LENGTHS[cc] ?? 34;
+    };
+    const format = (typed) => {
+        const compact = [...typed].filter(accept).join("").toUpperCase();
+        return formatIban(compact.slice(0, maxFor(compact)));
+    };
+    const check = (raw) => {
+        if (!raw)
+            return { valid: true };
+        const cc = raw.slice(0, 2);
+        const country = /^[A-Z]{2}$/.test(cc) ? regionName(locale, cc) : cc;
+        if (countries && /^[A-Z]{2}$/.test(cc) && !countries.includes(cc))
+            return { valid: false, reason: "country", message: t("country", { country }) };
+        const r = validateIban(raw, rules);
+        if (r.valid)
+            return { valid: true, kind: r.kind };
+        const length = rules.find((x) => x.country === cc)?.length ?? IBAN_LENGTHS[cc];
+        const message = r.reason === "length"
+            ? length
+                ? t("length", { country, length })
+                : t("lengthGeneric")
+            : r.reason === "chars"
+                ? t("chars")
+                : r.reason === "pattern"
+                    ? t("pattern", { country })
+                    : t("checksum");
+        return { valid: false, reason: r.reason, message, kind: r.kind };
+    };
+    const engine = useFormattedInput({
+        value,
+        defaultValue,
+        accept,
+        format,
+        parse: (d) => normalizeIban(d) || null,
+        toDisplay: (raw) => (raw ? format(raw) : ""),
+        onValueChange: (raw, formatted) => {
+            const c = check(raw);
+            v.report({ valid: c.valid, reason: c.reason, message: c.message }, "change");
+            onValueChange?.(raw, { valid: c.valid, reason: c.reason, kind: c.kind, formatted });
+        },
+    });
+    const ref = useComposedRefs(forwardedRef, engine.ref);
+    const submitName = useSubmitName(name);
+    const raw = engine.raw ?? "";
+    let bank;
+    if (showBank && raw.length >= 9) {
+        if (typeof showBank === "function")
+            bank = showBank(raw);
+        else
+            bank = rules.find((r) => r.country === raw.slice(0, 2))?.bankName?.(raw.slice(4, 9));
+    }
+    const firstCountry = countries?.[0] ?? "TR";
+    const sample = firstCountry === "TR" ? "TR00 0000 0000 0000 0000 0000 00" : `${firstCountry}00 0000 0000 0000 0000`;
+    return (_jsxs(_Fragment, { children: [_jsx(WithoutFieldName, { children: _jsx(Input, { ref: ref, ...rest, ...engine.inputProps, disabled: disabled, autoComplete: "off", autoCapitalize: "characters", spellCheck: false, dir: "ltr", placeholder: placeholder ?? sample, invalid: invalid || v.invalid, "aria-describedby": mergeIds(bank ? bankId : undefined, rest["aria-describedby"]), inputClassName: cn(mono && "font-mono tabular tracking-[0.02em]", inputClassName), "data-slot": "iban-input", trailing: bank || trailing ? (_jsxs(_Fragment, { children: [bank ? (_jsxs("span", { id: bankId, "data-slot": "iban-input-bank", className: "ui-fade me-1.5 flex max-w-[11rem] items-center gap-1.5 truncate text-xs font-medium text-fg-muted", children: [_jsx(Landmark, { "aria-hidden": true, className: "size-3.5 shrink-0 text-fg-subtle" }), _jsx("span", { className: "sr-only", children: t("bank", { bank }) }), _jsx("span", { "aria-hidden": true, className: "truncate", children: bank })] })) : null, trailing] })) : undefined, onKeyDown: (e) => {
+                        onKeyDown?.(e);
+                        engine.inputProps.onKeyDown(e);
+                    }, onBlur: (e) => {
+                        engine.inputProps.onBlur(e);
+                        const c = check(normalizeIban(e.currentTarget.value) || null);
+                        v.report({ valid: c.valid, reason: c.reason, message: c.message }, "blur");
+                        onBlur?.(e);
+                    } }) }), submitName ? _jsx("input", { type: "hidden", name: submitName, value: raw, disabled: disabled }) : null] }));
+});

package/dist/components/id-input.d.ts

@@ -0,0 +1,65 @@
+import * as React from "react";
+import type { IdRule } from "../locale-data/core/types.js";
+import { type BaseFormattedProps } from "./formatted-input.js";
+/** An ID rule as the input uses it: a locale-data `IdRule` plus how it is typed. */
+export interface IdInputRule extends IdRule {
+    /** Characters a user can type. Default `"digits"`. */
+    charset?: "digits" | "alphanumeric";
+}
+/** Built-in kinds (the `tr` pack) plus anything registered with `registerIdRule`. */
+export type IdKind = "tr-tckn" | "tr-vkn" | "tr-tax-id" | (string & {});
+/**
+ * Adds (or replaces) an ID rule. Locale packs call this with their `idRules`; apps can add
+ * their own (employee numbers, membership codes).
+ *
+ * ```ts
+ * import { trPack } from "@vamos-ui/react/locale-data";
+ * trPack.idRules?.forEach(registerIdRule);
+ * registerIdRule({ id: "de-steuer-id", label: "German tax ID", lengths: [11], normalize, validate });
+ * ```
+ */
+export declare function registerIdRule(rule: IdInputRule): void;
+/** A registered rule, or `undefined`. */
+export declare function getIdRule(kind: IdKind): IdInputRule | undefined;
+/** Every registered kind. */
+export declare function listIdRules(): IdInputRule[];
+declare const idInputLabels: {
+    length: string;
+    lengthChars: string;
+    chars: string;
+    checksum: string;
+    pattern: string;
+    or: string;
+};
+export type IdInputLabels = typeof idInputLabels;
+export interface IdInputProps extends BaseFormattedProps<string | null> {
+    /** A registered rule id (`"tr-tckn"`, `"tr-vkn"`, `"tr-tax-id"`) or a rule object. */
+    kind: IdKind | IdInputRule;
+    /**
+     * Privacy mask (KVKK / GDPR): when the field is not focused, a valid value shows as
+     * `123******01`. Focus reveals it. Default false.
+     */
+    masked?: boolean;
+    labels?: Partial<IdInputLabels>;
+}
+/**
+ * National and tax ID entry with checksum validation from pluggable rules: TCKN (and foreign
+ * resident YKN, reported as `kind: "tr-ykn"`), VKN, and the combined invoice tax id. The value is
+ * the normalized number.
+ *
+ * ```tsx
+ * <Field label="Turkish ID number" error={error}>
+ *   <IdInput kind="tr-tckn" onValidate={(r) => setError(r.message)} />
+ * </Field>
+ * ```
+ */
+export declare const IdInput: React.ForwardRefExoticComponent<IdInputProps & React.RefAttributes<HTMLInputElement>>;
+export interface NationalIdInputProps extends Omit<IdInputProps, "kind"> {
+    /** Default `"tr-tckn"` (accepts YKN too). */
+    kind?: IdKind | IdInputRule;
+}
+/** `IdInput` preset for personal IDs. Default kind `tr-tckn`. */
+export declare const NationalIdInput: React.ForwardRefExoticComponent<NationalIdInputProps & React.RefAttributes<HTMLInputElement>>;
+/** `IdInput` preset for tax numbers. Default kind `tr-tax-id` (VKN or a sole proprietor's TCKN). */
+export declare const TaxIdInput: React.ForwardRefExoticComponent<NationalIdInputProps & React.RefAttributes<HTMLInputElement>>;
+export {};

package/dist/components/id-input.js

@@ -0,0 +1,130 @@
+"use client";
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import * as React from "react";
+import { cn } from "../lib/cn.js";
+import { useComposedRefs } from "../lib/compose-refs.js";
+import { useLabels } from "../lib/labels.js";
+import { useFormattedInput } from "../lib/use-formatted-input.js";
+import { trTaxIdRule, trTcknRule, trVknRule } from "../locale-data/tr/id.js";
+import { Input } from "./input.js";
+import { WithoutFieldName, useFormattedValidity, useSubmitName } from "./formatted-input.js";
+const registry = new Map([
+    [trTcknRule.id, trTcknRule],
+    [trVknRule.id, trVknRule],
+    [trTaxIdRule.id, trTaxIdRule],
+]);
+/**
+ * Adds (or replaces) an ID rule. Locale packs call this with their `idRules`; apps can add
+ * their own (employee numbers, membership codes).
+ *
+ * ```ts
+ * import { trPack } from "@vamos-ui/react/locale-data";
+ * trPack.idRules?.forEach(registerIdRule);
+ * registerIdRule({ id: "de-steuer-id", label: "German tax ID", lengths: [11], normalize, validate });
+ * ```
+ */
+export function registerIdRule(rule) {
+    registry.set(rule.id, rule);
+}
+/** A registered rule, or `undefined`. */
+export function getIdRule(kind) {
+    return registry.get(kind);
+}
+/** Every registered kind. */
+export function listIdRules() {
+    return [...registry.values()];
+}
+/* ------------------------------------------------------------------ */
+/* IdInput                                                             */
+/* ------------------------------------------------------------------ */
+const idInputLabels = {
+    length: "Must be {lengths} digits",
+    lengthChars: "Must be {lengths} characters",
+    chars: "Only digits are allowed",
+    checksum: "This number isn't valid. Check it for typos.",
+    pattern: "This number isn't valid. Check it for typos.",
+    or: "{a} or {b}",
+};
+/**
+ * National and tax ID entry with checksum validation from pluggable rules: TCKN (and foreign
+ * resident YKN, reported as `kind: "tr-ykn"`), VKN, and the combined invoice tax id. The value is
+ * the normalized number.
+ *
+ * ```tsx
+ * <Field label="Turkish ID number" error={error}>
+ *   <IdInput kind="tr-tckn" onValidate={(r) => setError(r.message)} />
+ * </Field>
+ * ```
+ */
+export const IdInput = React.forwardRef(function IdInput({ kind, masked = false, value, defaultValue, onValueChange, validateOn = "blur", onValidate, mono = true, labels, name, invalid, inputClassName, onBlur, onFocus, onKeyDown, disabled, placeholder, ...rest }, forwardedRef) {
+    const rule = typeof kind === "string" ? registry.get(kind) : kind;
+    if (!rule && process.env.NODE_ENV !== "production")
+        console.warn(`IdInput: no rule registered for "${String(kind)}".`);
+    const t = useLabels("idInput", idInputLabels, labels);
+    const digits = (rule?.charset ?? "digits") === "digits";
+    const maxLength = rule ? Math.max(...rule.lengths) : 64;
+    const accept = React.useCallback((ch) => (digits ? ch >= "0" && ch <= "9" : /^[0-9A-Za-z]$/.test(ch)), [digits]);
+    const v = useFormattedValidity(validateOn, onValidate);
+    const [focused, setFocused] = React.useState(false);
+    const normalize = (s) => {
+        const out = [...s].filter(accept).join("").slice(0, maxLength);
+        return digits ? out : out.toUpperCase();
+    };
+    const display = (s) => {
+        const n = normalize(s);
+        return n && rule?.format && rule.lengths.includes(n.length) ? rule.format(n) : n;
+    };
+    const lengthText = () => {
+        const ls = rule?.lengths ?? [];
+        const joined = ls.length > 1 ? t("or", { a: ls.slice(0, -1).join(", "), b: ls[ls.length - 1] }) : String(ls[0] ?? "");
+        return t(digits ? "length" : "lengthChars", { lengths: joined });
+    };
+    const check = (raw) => {
+        if (!raw || !rule)
+            return { valid: true };
+        const r = rule.validate(raw);
+        if (r.valid)
+            return { valid: true, kind: r.kind };
+        const reason = r.reason ?? "checksum";
+        const message = reason === "length" ? lengthText() : reason === "chars" ? t("chars") : t(reason === "pattern" ? "pattern" : "checksum");
+        return { valid: false, reason, message, kind: r.kind };
+    };
+    const engine = useFormattedInput({
+        value,
+        defaultValue,
+        accept,
+        format: display,
+        parse: (d) => normalize(d) || null,
+        toDisplay: (raw) => (raw ? display(raw) : ""),
+        onValueChange: (raw, formatted) => {
+            const c = check(raw);
+            v.report({ valid: c.valid, reason: c.reason, message: c.message }, "change");
+            onValueChange?.(raw, { valid: c.valid, reason: c.reason, kind: c.kind, formatted });
+        },
+    });
+    const ref = useComposedRefs(forwardedRef, engine.ref);
+    const submitName = useSubmitName(name);
+    const showMask = masked && !focused && engine.raw && rule?.mask && check(engine.raw).valid;
+    const shown = showMask ? rule.mask(engine.raw) : engine.display;
+    return (_jsxs(_Fragment, { children: [_jsx(WithoutFieldName, { children: _jsx(Input, { ref: ref, ...rest, ...engine.inputProps, value: shown, disabled: disabled, inputMode: digits ? "numeric" : "text", autoComplete: "off", spellCheck: false, dir: "ltr", placeholder: placeholder, invalid: invalid || v.invalid, inputClassName: cn(mono && "font-mono tabular tracking-[0.02em]", inputClassName), "data-slot": "id-input", "data-kind": rule?.id, "data-masked": showMask ? "" : undefined, onFocus: (e) => {
+                        setFocused(true);
+                        onFocus?.(e);
+                    }, onKeyDown: (e) => {
+                        onKeyDown?.(e);
+                        engine.inputProps.onKeyDown(e);
+                    }, onBlur: (e) => {
+                        setFocused(false);
+                        engine.inputProps.onBlur(e);
+                        const c = check(normalize(e.currentTarget.value) || null);
+                        v.report({ valid: c.valid, reason: c.reason, message: c.message }, "blur");
+                        onBlur?.(e);
+                    } }) }), submitName ? _jsx("input", { type: "hidden", name: submitName, value: engine.raw ?? "", disabled: disabled }) : null] }));
+});
+/** `IdInput` preset for personal IDs. Default kind `tr-tckn`. */
+export const NationalIdInput = React.forwardRef(function NationalIdInput({ kind = "tr-tckn", ...props }, ref) {
+    return _jsx(IdInput, { ref: ref, kind: kind, ...props });
+});
+/** `IdInput` preset for tax numbers. Default kind `tr-tax-id` (VKN or a sole proprietor's TCKN). */
+export const TaxIdInput = React.forwardRef(function TaxIdInput({ kind = "tr-tax-id", ...props }, ref) {
+    return _jsx(IdInput, { ref: ref, kind: kind, ...props });
+});

package/dist/components/image.d.ts

@@ -0,0 +1,130 @@
+import * as React from "react";
+import { type VariantProps } from "class-variance-authority";
+import type { CropRect, ImageLoader, MediaAsset } from "../media/types.js";
+export type ImageAspect = "auto" | "1/1" | "4/3" | "3/2" | "16/9" | "21/9" | "4/5" | "1.91/1" | number;
+/** Default `srcset` steps. */
+export declare const IMAGE_WIDTHS: number[];
+/** `"16/9"` → 1.777…, `1.5` → 1.5, `"auto"` → the intrinsic ratio (or `undefined`). */
+export declare function aspectRatioOf(aspect: ImageAspect | undefined, width?: number, height?: number): number | undefined;
+/** Focal point (0..1) → CSS `object-position`. Image space: never mirrored in RTL. */
+export declare function focalToObjectPosition(focal?: {
+    x: number;
+    y: number;
+} | null): string | undefined;
+export interface ImageSourcesOptions {
+    /** `sizes` attribute, e.g. `"(min-width: 1024px) 50vw, 100vw"`. */
+    sizes?: string;
+    widths?: number[];
+    loader?: ImageLoader;
+    quality?: number;
+    focal?: {
+        x: number;
+        y: number;
+    };
+    crop?: string | CropRect;
+    format?: "auto" | "webp" | "avif";
+}
+export interface ImageSources {
+    src: string;
+    srcSet?: string;
+    sizes?: string;
+}
+/** Builds `src` / `srcSet` / `sizes` for an asset or URL (pure; usable on the server). */
+export declare function getImageSources(source: string | MediaAsset, options?: ImageSourcesOptions): ImageSources;
+/**
+ * Sets the image loader for every kit `Image` below (CDN URL builder). Same signature as the
+ * Next.js loader. The media adapter's `loader` is used when no provider sets one.
+ *
+ * ```tsx
+ * <ImageLoaderProvider loader={({ src, width, quality }) => `https://cdn.example.com/cdn-cgi/image/width=${width},quality=${quality ?? 75},format=auto/${src}`}>
+ * ```
+ */
+export declare function ImageLoaderProvider({ loader, children }: {
+    loader: ImageLoader | undefined;
+    children: React.ReactNode;
+}): React.JSX.Element;
+/** The active loader: `ImageLoaderProvider` → media adapter `loader` → none. */
+export declare function useImageLoader(): ImageLoader | undefined;
+/** `getImageSources` with the provider's loader. */
+export declare function useImageSources(source: string | MediaAsset, options?: ImageSourcesOptions): ImageSources;
+export declare const imageVariants: (props?: ({
+    rounded?: "ui" | "ui-lg" | "full" | "none" | null | undefined;
+    fit?: "contain" | "cover" | null | undefined;
+    frame?: "none" | "surface" | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;
+declare const imageLabels: {
+    processing: string;
+    error: string;
+};
+export type ImageLabels = typeof imageLabels;
+export type ImagePlaceholder = "blur" | "color" | "skeleton" | "none";
+export interface ImageBaseProps extends Omit<React.ImgHTMLAttributes<HTMLImageElement>, "src" | "placeholder" | "width" | "height" | "alt">, Omit<VariantProps<typeof imageVariants>, "fit"> {
+    width?: number;
+    height?: number;
+    /** Box ratio. `"auto"` (default) uses the intrinsic width/height. */
+    aspect?: ImageAspect;
+    fit?: "cover" | "contain";
+    /** 0..1 → `object-position`. Defaults to the asset's `focalPoint`. */
+    focal?: {
+        x: number;
+        y: number;
+    };
+    /** Named crop from `asset.crops`, or a rect. Applied by the loader. */
+    crop?: string | CropRect;
+    sizes?: string;
+    /** `srcset` steps (with a loader). */
+    widths?: number[];
+    quality?: number;
+    /** Above the fold: eager loading + `fetchpriority="high"`. */
+    priority?: boolean;
+    /** While loading. Default: `blur` with a blur source, `color` with a dominant colour, else `skeleton`. */
+    placeholder?: ImagePlaceholder;
+    /** Tiny blurred preview (LQIP data URL or a small URL). Defaults to `asset.placeholder`. */
+    blurDataURL?: string;
+    /** Placeholder colour. Defaults to `asset.dominantColor`. */
+    color?: string;
+    /** Overrides the provider loader. */
+    loader?: ImageLoader;
+    /** Rendered instead of the broken-image icon. */
+    fallback?: React.ReactNode;
+    /** Show the "Processing" badge (defaults to `asset.status === "processing"`). */
+    processing?: boolean;
+    /** Class of the wrapper; `className` goes to the wrapper too, `imgClassName` to the `<img>`. */
+    imgClassName?: string;
+    labels?: Partial<ImageLabels>;
+}
+/**
+ * `src` is a URL (then `alt` is required; `""` marks the image decorative) or a `MediaAsset`
+ * (supplies alt, size, focal point, placeholder and variants; `alt` overrides per use).
+ */
+export type ImageProps = ImageBaseProps & ({
+    src: string | MediaAsset;
+    alt: string;
+} | {
+    src: MediaAsset;
+    alt?: string;
+});
+/**
+ * The image primitive: no layout shift (width/height + `aspect-ratio`), focal point →
+ * `object-position`, LQIP / colour / skeleton placeholder that cross-fades out, `srcset` from the
+ * loader or asset variants. Framework-agnostic: a plain `<img>`, or the app's `Image` from
+ * `VamosProvider` (e.g. `next/image`).
+ *
+ * ```tsx
+ * <Image src={asset} alt="Lobby of the Kadıköy office" aspect="16/9" sizes="(min-width: 1024px) 50vw, 100vw" rounded="ui" />
+ * ```
+ */
+export declare const Image: React.ForwardRefExoticComponent<ImageProps & React.RefAttributes<HTMLImageElement>>;
+export interface FigureProps extends React.HTMLAttributes<HTMLElement> {
+    /** Spacing between media and caption. */
+    gap?: "sm" | "md";
+}
+/** `<figure>` for a captioned image (blocks, galleries, articles). */
+export declare const Figure: React.ForwardRefExoticComponent<FigureProps & React.RefAttributes<HTMLElement>>;
+export interface FigureCaptionProps extends React.HTMLAttributes<HTMLElement> {
+    /** Small print line, e.g. photo credit. */
+    credit?: React.ReactNode;
+}
+/** `<figcaption>`: caption text plus an optional credit. */
+export declare const FigureCaption: React.ForwardRefExoticComponent<FigureCaptionProps & React.RefAttributes<HTMLElement>>;
+export {};