@vamos-ui/react 0.0.0-stage → 0.2.0

package/dist/components/activity-timeline.d.ts

@@ -0,0 +1,149 @@
+import * as React from "react";
+import { type LucideIcon } from "lucide-react";
+import type { timelineLabels } from "../lib/data-islands.js";
+export { RelativeTime, type RelativeTimeProps } from "../lib/data-islands.js";
+export type TimelineLabels = Partial<typeof timelineLabels>;
+export type TimelineTone = "neutral" | "accent" | "success" | "warning" | "danger" | "info";
+export type TimelineStatus = "done" | "current" | "upcoming" | "failed";
+/** One event of `ActivityTimeline items`. */
+export interface TimelineEntry {
+    id: string;
+    /** When it happened: a Date, an ISO instant, or `"YYYY-MM-DD"`. */
+    at: Date | string;
+    /** Lucide icon component shown in the indicator. */
+    icon?: LucideIcon;
+    /** Person who did it — shown as an Avatar in the indicator (wins over `icon`). */
+    avatar?: {
+        src?: string | null;
+        name: string;
+    };
+    tone?: TimelineTone;
+    /** What happened. */
+    title: React.ReactNode;
+    /** Note, quoted comment or details under the title. */
+    body?: React.ReactNode;
+    /** Actor name, bolded before the title ("Meltem scheduled a post"). */
+    actor?: string;
+    /** Makes the title a link to the record. */
+    href?: string;
+    /** Steps variant: progress state. */
+    status?: TimelineStatus;
+    /** Trailing actions (Undo, View). */
+    actions?: React.ReactNode;
+}
+export interface TimelineProps extends React.OlHTMLAttributes<HTMLOListElement> {
+    /** `"feed"` (events) or `"steps"` (a process with done / current / upcoming). Default `"feed"`. */
+    variant?: "feed" | "steps";
+    /** `"inherit"` follows the page `data-density`. Default `"inherit"`. */
+    density?: "inherit" | "compact" | "comfortable";
+}
+/**
+ * Composable timeline (`<ol>`). For data use `ActivityTimeline`; compose these parts for
+ * custom rows: `Timeline › TimelineGroup › TimelineItem › TimelineIndicator + TimelineContent`.
+ */
+export declare const Timeline: React.ForwardRefExoticComponent<TimelineProps & React.RefAttributes<HTMLOListElement>>;
+export interface TimelineGroupProps extends Omit<React.LiHTMLAttributes<HTMLLIElement>, "title"> {
+    /** Day as `"YYYY-MM-DD"` — rendered as "Today", "Yesterday" or "Monday, Nov 8" in the current locale. */
+    date?: string;
+    /** Custom heading (wins over `date`). */
+    label?: React.ReactNode;
+    /** Fix the reference time for "Today" (docs, tests). */
+    now?: Date | string | number;
+    labels?: TimelineLabels;
+}
+/** A labelled section (a day). Children are TimelineItems. */
+export declare const TimelineGroup: React.ForwardRefExoticComponent<TimelineGroupProps & React.RefAttributes<HTMLLIElement>>;
+export interface TimelineItemProps extends React.LiHTMLAttributes<HTMLLIElement> {
+    /** Steps variant: drives the indicator, connector and `aria-current="step"`. */
+    status?: TimelineStatus;
+    /** Brief accent highlight for a just-arrived item (none under reduced motion). */
+    highlight?: boolean;
+}
+export declare const TimelineItem: React.ForwardRefExoticComponent<TimelineItemProps & React.RefAttributes<HTMLLIElement>>;
+export interface TimelineIndicatorProps extends React.HTMLAttributes<HTMLSpanElement> {
+    icon?: LucideIcon | React.ReactNode;
+    avatar?: {
+        src?: string | null;
+        name: string;
+    };
+    tone?: TimelineTone;
+    /** Steps: picks the look (check for done, ring for current, hollow for upcoming, × for failed). */
+    status?: TimelineStatus;
+    labels?: TimelineLabels;
+}
+/** The dot / icon / avatar on the connector. Opaque in glass so the line never shows through. */
+export declare function TimelineIndicator({ icon, avatar, tone, status, labels, className, children, ...props }: TimelineIndicatorProps): React.JSX.Element;
+/** Text column: title, time, body, actions. */
+export declare function TimelineContent({ className, ...props }: React.HTMLAttributes<HTMLDivElement>): React.JSX.Element;
+export declare function TimelineTitle({ className, ...props }: React.HTMLAttributes<HTMLDivElement>): React.JSX.Element;
+export interface TimelineBodyProps extends React.HTMLAttributes<HTMLDivElement> {
+    /** `"card"` (default) sets the note on an inset surface; `"plain"` is unstyled text for typographic layouts (CVs, changelogs). */
+    variant?: "card" | "plain";
+}
+/** Note or quoted comment under the title. */
+export declare function TimelineBody({ className, variant, ...props }: TimelineBodyProps): React.JSX.Element;
+export interface TimelineTimeProps {
+    value: Date | string | number;
+    /** Fix the reference time (docs, tests). */
+    now?: Date | string | number;
+    /** `"absolute"` shows the time of day ("9:30 AM") — useful inside day groups. Default `"relative"`. */
+    mode?: "relative" | "absolute";
+    className?: string;
+}
+/** `<time>` with "4 minutes ago" (full date on hover). Server render shows the absolute time. */
+export declare function TimelineTime({ value, now, mode, className }: TimelineTimeProps): React.JSX.Element;
+export declare function TimelineActions({ className, ...props }: React.HTMLAttributes<HTMLDivElement>): React.JSX.Element;
+export interface TimelineNewItemsProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
+    /** Number of waiting items. */
+    count: number;
+    labels?: TimelineLabels;
+}
+/** "3 new updates" pill for live feeds: new items wait above instead of shifting the list. */
+export declare const TimelineNewItems: React.ForwardRefExoticComponent<TimelineNewItemsProps & React.RefAttributes<HTMLButtonElement>>;
+/** Placeholder items while the feed loads. */
+export declare function TimelineSkeleton({ count, className }: {
+    count?: number;
+    className?: string;
+}): React.JSX.Element;
+export interface ActivityTimelineProps extends Omit<TimelineProps, "children"> {
+    items: TimelineEntry[];
+    /** `"day"` groups under "Today / Yesterday / Monday, Nov 8". Default `"none"`. */
+    groupBy?: "day" | "none";
+    /** Default `"desc"` (newest first) for feeds, `"asc"` for steps. */
+    order?: "desc" | "asc";
+    /** Time zone used to split days — pass the same one as your LocaleProvider. Default `"UTC"`. */
+    timeZone?: string;
+    /** Fix the reference time ("4 minutes ago", "Today") — docs, tests, snapshots. */
+    now?: Date | string | number;
+    /** Times as `"relative"` ("4 minutes ago") or `"absolute"` time of day. Default: relative, absolute inside day groups. */
+    timeMode?: "relative" | "absolute";
+    /** Three skeleton items. */
+    loading?: boolean;
+    /** Shown when there are no items. Default: "No activity yet". */
+    empty?: React.ReactNode;
+    /** Show the "Load older activity" button. */
+    hasMore?: boolean;
+    /** Called by the load-more button; return a promise for the busy state. */
+    onLoadMore?: () => void | Promise<void>;
+    /** Waiting live items — shows the "3 new updates" pill. */
+    newCount?: number;
+    onShowNew?: () => void;
+    /** Polite live region text for screen readers (batched by you, e.g. "2 new comments"). */
+    announcement?: string;
+    /** Filter chips above the list. */
+    filter?: React.ReactNode;
+    labels?: TimelineLabels;
+}
+/**
+ * A chronological, human-readable history: dashboard activity, record history, approval steps.
+ * Server-component compatible: relative times and day names are small client islands
+ * (`Intl.RelativeTimeFormat`, one shared ticker).
+ *
+ * ```tsx
+ * <ActivityTimeline groupBy="day" items={[
+ *   { id: "1", at: "2026-11-10T09:12:00Z", icon: Inbox, title: <>New submission on <b>Contact form</b></> },
+ *   { id: "2", at: "2026-11-09T16:40:00Z", avatar: { name: "Ahmet Kaya" }, actor: "Ahmet Kaya", title: "commented on “QR menus guide”" },
+ * ]} />
+ * ```
+ */
+export declare const ActivityTimeline: React.ForwardRefExoticComponent<ActivityTimelineProps & React.RefAttributes<HTMLOListElement>>;

package/dist/components/activity-timeline.js

@@ -0,0 +1,122 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import * as React from "react";
+import { Check, X } from "lucide-react";
+import { cva } from "class-variance-authority";
+import { cn } from "../lib/cn.js";
+import { DataLabel, LoadMoreButton, RelativeTime, TimelineDayLabel } from "../lib/data-islands.js";
+import { dayKey, toIsoInstant } from "../lib/value-format.js";
+import { Avatar } from "./avatar.js";
+import { EmptyState } from "./empty-state.js";
+import { Skeleton } from "./skeleton.js";
+export { RelativeTime } from "../lib/data-islands.js";
+/**
+ * Composable timeline (`<ol>`). For data use `ActivityTimeline`; compose these parts for
+ * custom rows: `Timeline › TimelineGroup › TimelineItem › TimelineIndicator + TimelineContent`.
+ */
+export const Timeline = React.forwardRef(function Timeline({ variant = "feed", density = "inherit", className, ...props }, ref) {
+    return (_jsx("ol", { ref: ref, "data-slot": "timeline", "data-variant": variant, "data-density": density === "inherit" ? undefined : density, className: cn("group/timeline m-0 grid list-none gap-(--tl-gap) p-0 [--tl-gap:calc(var(--row-h)*0.3)] [--tl-ind:1.75rem]", "data-[density=compact]:[--tl-ind:1.5rem] [[data-density=compact]_&]:[--tl-ind:1.5rem]", className), ...props }));
+});
+/** A labelled section (a day). Children are TimelineItems. */
+export const TimelineGroup = React.forwardRef(function TimelineGroup({ date, label, now, labels, className, children, ...props }, ref) {
+    const id = React.useId();
+    return (_jsxs("li", { ref: ref, "data-slot": "timeline-group", "aria-labelledby": id, className: cn("grid gap-(--tl-gap)", className), ...props, children: [_jsxs("div", { id: id, className: "flex items-center gap-3 font-mono text-[11px] font-medium tracking-[0.06em] text-fg-subtle", children: [_jsx("span", { className: "shrink-0", children: label ?? (date ? _jsx(TimelineDayLabel, { date: date, now: now, labels: labels }) : null) }), _jsx("span", { "aria-hidden": true, className: "h-px flex-1 bg-line" })] }), _jsx("ol", { className: "m-0 grid list-none gap-(--tl-gap) p-0", children: children })] }));
+});
+export const TimelineItem = React.forwardRef(function TimelineItem({ status, highlight, className, ...props }, ref) {
+    return (_jsx("li", { ref: ref, "data-slot": "timeline-item", "data-status": status, "data-highlight": highlight ? "" : undefined, "aria-current": status === "current" ? "step" : undefined, className: cn("relative grid grid-cols-[var(--tl-ind)_minmax(0,1fr)] gap-x-3", 
+        // connector from below this indicator to the next one (start side, RTL-aware)
+        "before:absolute before:start-[calc(var(--tl-ind)/2-0.5px)] before:top-[calc(var(--tl-ind)+0.25rem)] before:-bottom-[calc(var(--tl-gap)-0.25rem)] before:w-px before:bg-line last:before:hidden", "data-[status=upcoming]:before:w-0 data-[status=upcoming]:before:border-s data-[status=upcoming]:before:border-dashed data-[status=upcoming]:before:border-line data-[status=upcoming]:before:bg-transparent", "data-[status=current]:before:w-0 data-[status=current]:before:border-s data-[status=current]:before:border-dashed data-[status=current]:before:border-line data-[status=current]:before:bg-transparent", className), ...props }));
+});
+const indicatorVariants = cva("relative z-[1] grid size-(--tl-ind) shrink-0 place-items-center rounded-full border text-fg-muted [&_svg]:size-[calc(var(--tl-ind)*0.5)] [&_svg]:shrink-0", {
+    variants: {
+        tone: {
+            neutral: "border-line bg-[color-mix(in_oklch,var(--surface)_90%,var(--scene))]",
+            accent: "tone-accent border-[color-mix(in_srgb,var(--tone)_35%,var(--line))] bg-[color-mix(in_oklch,var(--tone)_14%,color-mix(in_oklch,var(--surface)_92%,var(--scene)))] text-(--tone)",
+            success: "tone-success border-[color-mix(in_srgb,var(--tone)_35%,var(--line))] bg-[color-mix(in_oklch,var(--tone)_14%,color-mix(in_oklch,var(--surface)_92%,var(--scene)))] text-(--tone)",
+            warning: "tone-warning border-[color-mix(in_srgb,var(--tone)_35%,var(--line))] bg-[color-mix(in_oklch,var(--tone)_14%,color-mix(in_oklch,var(--surface)_92%,var(--scene)))] text-(--tone)",
+            danger: "tone-danger border-[color-mix(in_srgb,var(--tone)_35%,var(--line))] bg-[color-mix(in_oklch,var(--tone)_14%,color-mix(in_oklch,var(--surface)_92%,var(--scene)))] text-(--tone)",
+            info: "tone-info border-[color-mix(in_srgb,var(--tone)_35%,var(--line))] bg-[color-mix(in_oklch,var(--tone)_14%,color-mix(in_oklch,var(--surface)_92%,var(--scene)))] text-(--tone)",
+        },
+    },
+    defaultVariants: { tone: "neutral" },
+});
+/** The dot / icon / avatar on the connector. Opaque in glass so the line never shows through. */
+export function TimelineIndicator({ icon, avatar, tone, status, labels, className, children, ...props }) {
+    const statusText = status ? (_jsx("span", { className: "sr-only", children: _jsx(DataLabel, { ns: "timeline", id: status, override: labels }) })) : null;
+    if (avatar && !status) {
+        return (_jsx("span", { "data-slot": "timeline-indicator", className: cn("relative z-[1] grid size-(--tl-ind) place-items-center", className), ...props, children: _jsx(Avatar, { name: avatar.name, src: avatar.src, size: "sm", className: "size-(--tl-ind)! ring-2 ring-[color-mix(in_oklch,var(--surface)_90%,var(--scene))]" }) }));
+    }
+    if (status) {
+        return (_jsxs("span", { "data-slot": "timeline-indicator", "data-status": status, className: cn(indicatorVariants({ tone: status === "done" ? "success" : status === "failed" ? "danger" : "neutral" }), status === "current" && "border-accent-ink border-[1.5px] text-accent-ink", status === "upcoming" && "border-dashed text-fg-subtle", className), ...props, children: [status === "done" ? _jsx(Check, { "aria-hidden": true, strokeWidth: 2.5 }) : status === "failed" ? _jsx(X, { "aria-hidden": true, strokeWidth: 2.5 }) : status === "current" ? _jsx("span", { "aria-hidden": true, className: "size-2 rounded-full bg-accent-ink" }) : _jsx("span", { "aria-hidden": true, className: "size-1.5 rounded-full bg-current" }), statusText, children] }));
+    }
+    const Icon = typeof icon === "function" || (typeof icon === "object" && icon !== null && !React.isValidElement(icon) && "render" in icon) ? icon : undefined;
+    return (_jsx("span", { "data-slot": "timeline-indicator", className: cn(indicatorVariants({ tone }), className), ...props, children: Icon ? _jsx(Icon, { "aria-hidden": true }) : icon ? icon : children ?? _jsx("span", { "aria-hidden": true, className: "size-1.5 rounded-full bg-current opacity-70" }) }));
+}
+/** Text column: title, time, body, actions. */
+export function TimelineContent({ className, ...props }) {
+    return _jsx("div", { "data-slot": "timeline-content", className: cn("min-w-0 pt-[calc((var(--tl-ind)-1.25rem)/2)] text-[13px] leading-5 text-fg-muted", className), ...props });
+}
+export function TimelineTitle({ className, ...props }) {
+    return _jsx("div", { "data-slot": "timeline-title", className: cn("text-pretty [&_b]:font-medium [&_b]:text-fg [&_strong]:font-medium [&_strong]:text-fg", className), ...props });
+}
+/** Note or quoted comment under the title. */
+export function TimelineBody({ className, variant = "card", ...props }) {
+    return (_jsx("div", { "data-slot": "timeline-body", "data-variant": variant, className: cn(variant === "card" ? "surface-2 mt-2 rounded-ui-sm px-3 py-2 text-[13px] leading-relaxed text-fg" : "mt-1 leading-relaxed text-fg", className), ...props }));
+}
+/** `<time>` with "4 minutes ago" (full date on hover). Server render shows the absolute time. */
+export function TimelineTime({ value, now, mode = "relative", className }) {
+    return _jsx(RelativeTime, { value: value, now: now, display: mode === "absolute" ? "time" : "relative", className: cn("mt-0.5 block text-[11.5px] text-fg-subtle", className) });
+}
+export function TimelineActions({ className, ...props }) {
+    return _jsx("div", { "data-slot": "timeline-actions", className: cn("mt-2 flex flex-wrap items-center gap-1.5", className), ...props });
+}
+/** "3 new updates" pill for live feeds: new items wait above instead of shifting the list. */
+export const TimelineNewItems = React.forwardRef(function TimelineNewItems({ count, labels, className, children, ...props }, ref) {
+    if (count <= 0)
+        return null;
+    return (_jsxs("button", { ref: ref, type: "button", "data-slot": "timeline-new-items", className: cn("mx-auto inline-flex h-7 items-center gap-1.5 rounded-full bg-accent-soft px-3 text-xs font-medium text-accent-ink transition-[filter] hover:brightness-95 focus-ring motion-safe:ui-fade", className), ...props, children: [_jsx("span", { "aria-hidden": true, className: "size-1.5 rounded-full bg-current" }), children ?? _jsx(DataLabel, { ns: "timeline", id: "newItems", vars: { count }, override: labels })] }));
+});
+/** Placeholder items while the feed loads. */
+export function TimelineSkeleton({ count = 3, className }) {
+    return (_jsx("div", { "data-slot": "timeline-skeleton", "aria-busy": "true", className: cn("grid gap-4 [--tl-ind:1.75rem]", className), children: Array.from({ length: count }, (_, i) => (_jsxs("div", { className: "grid grid-cols-[var(--tl-ind)_1fr] gap-x-3", children: [_jsx(Skeleton, { shape: "circle", className: "size-(--tl-ind)" }), _jsxs("div", { className: "grid gap-2 pt-1", children: [_jsx(Skeleton, { shape: "text", className: "h-3", style: { width: `${78 - ((i * 19) % 30)}%` } }), _jsx(Skeleton, { shape: "text", className: "h-2.5 w-16" })] })] }, i))) }));
+}
+/**
+ * A chronological, human-readable history: dashboard activity, record history, approval steps.
+ * Server-component compatible: relative times and day names are small client islands
+ * (`Intl.RelativeTimeFormat`, one shared ticker).
+ *
+ * ```tsx
+ * <ActivityTimeline groupBy="day" items={[
+ *   { id: "1", at: "2026-11-10T09:12:00Z", icon: Inbox, title: <>New submission on <b>Contact form</b></> },
+ *   { id: "2", at: "2026-11-09T16:40:00Z", avatar: { name: "Ahmet Kaya" }, actor: "Ahmet Kaya", title: "commented on “QR menus guide”" },
+ * ]} />
+ * ```
+ */
+export const ActivityTimeline = React.forwardRef(function ActivityTimeline({ items, variant = "feed", groupBy = "none", order, timeZone = "UTC", now, timeMode, loading, empty, hasMore, onLoadMore, newCount = 0, onShowNew, announcement, filter, labels, className, density, ...props }, ref) {
+    const dir = order ?? (variant === "steps" ? "asc" : "desc");
+    const sorted = variant === "steps" && order === undefined ? items : [...items].sort((a, b) => cmp(a.at, b.at) * (dir === "asc" ? 1 : -1));
+    const renderItem = (it, inGroup) => (_jsxs(TimelineItem, { status: it.status, children: [_jsx(TimelineIndicator, { icon: it.icon, avatar: it.avatar, tone: it.tone, status: variant === "steps" ? (it.status ?? "upcoming") : undefined, labels: labels }), _jsxs(TimelineContent, { children: [_jsxs(TimelineTitle, { className: it.status === "upcoming" ? "text-fg-subtle" : undefined, children: [it.actor ? _jsxs("b", { children: [it.actor, " "] }) : null, it.href ? (_jsx("a", { href: it.href, className: "rounded-[2px] underline-offset-2 hover:text-fg hover:underline focus-ring", children: it.title })) : (it.title)] }), variant === "steps" && it.status === "upcoming" ? null : _jsx(TimelineTime, { value: toIsoInstant(it.at), now: now, mode: timeMode ?? (inGroup ? "absolute" : "relative") }), it.body ? _jsx(TimelineBody, { children: it.body }) : null, it.actions ? _jsx(TimelineActions, { children: it.actions }) : null] })] }, it.id));
+    let list;
+    if (loading)
+        list = _jsx(TimelineSkeleton, {});
+    else if (sorted.length === 0)
+        list = empty ?? _jsx(EmptyState, { size: "sm", title: _jsx(DataLabel, { ns: "timeline", id: "empty", override: labels }) });
+    else if (groupBy === "day") {
+        const groups = new Map();
+        for (const it of sorted) {
+            const k = dayKey(it.at, timeZone);
+            groups.set(k, [...(groups.get(k) ?? []), it]);
+        }
+        list = (_jsx(Timeline, { ref: ref, variant: variant, density: density, className: className, ...props, children: [...groups].map(([day, entries]) => (_jsx(TimelineGroup, { date: day, now: now, labels: labels, children: entries.map((e) => renderItem(e, true)) }, day))) }));
+    }
+    else {
+        list = (_jsx(Timeline, { ref: ref, variant: variant, density: density, className: className, ...props, children: sorted.map((e) => renderItem(e, false)) }));
+    }
+    const wrapped = Boolean(filter || newCount > 0 || announcement !== undefined || (hasMore && onLoadMore) || loading || sorted.length === 0);
+    if (!wrapped)
+        return list;
+    return (_jsxs("div", { "data-slot": "activity-timeline", className: "grid gap-4", children: [filter ? _jsx("div", { className: "flex flex-wrap items-center gap-1.5", children: filter }) : null, newCount > 0 ? _jsx(TimelineNewItems, { count: newCount, onClick: onShowNew, labels: labels }) : null, list, hasMore && onLoadMore && !loading ? (_jsx("div", { className: "flex justify-center", children: _jsx(LoadMoreButton, { onLoadMore: onLoadMore, labels: labels }) })) : null, announcement !== undefined ? (_jsx("div", { "aria-live": "polite", role: "status", className: "sr-only", children: announcement })) : null] }));
+});
+function cmp(a, b) {
+    const t = (v) => (v instanceof Date ? v.getTime() : Date.parse(v.length === 10 ? `${v}T00:00:00Z` : v));
+    return t(a) - t(b);
+}

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

@@ -0,0 +1,116 @@
+import * as React from "react";
+import { type ControlA11yProps } from "../lib/field-context.js";
+import type { AddressDataSource } from "../locale-data/core/types.js";
+/**
+ * A structured postal address. Region names are stored as text (official spelling), because
+ * invoices (UBL-TR `CityName` / `CitySubdivisionName`) and labels need names, not codes.
+ */
+export interface Address {
+    /** ISO 3166-1 alpha-2. */
+    country: string;
+    /** Province / state ("İstanbul", "California"). */
+    region1?: string;
+    /** District / city ("Kadıköy", "San Francisco"). */
+    region2?: string;
+    /** Neighbourhood (from an app endpoint; not bundled). */
+    region3?: string;
+    line1?: string;
+    line2?: string;
+    postalCode?: string;
+}
+export type AddressPart = keyof Address;
+declare const addressLabels: {
+    country: string;
+    province: string;
+    district: string;
+    state: string;
+    city: string;
+    line1: string;
+    line2: string;
+    postalCode: string;
+    zip: string;
+    select: string;
+    selectProvince: string;
+    selectDistrict: string;
+    provinceFirst: string;
+    loading: string;
+    districtCleared: string;
+    postalMismatch: string;
+};
+export type AddressFieldLabels = typeof addressLabels;
+/**
+ * Formats an address as lines in the country's convention.
+ *
+ * ```ts
+ * formatAddress({ country: "TR", region1: "İstanbul", region2: "Kadıköy", line1: "Caferağa Mah. Moda Cad. No: 12", postalCode: "34710" }, { locale: "en-US" });
+ * // ["Caferağa Mah. Moda Cad. No: 12", "34710 Kadıköy/İstanbul", "Türkiye"]
+ * ```
+ */
+export declare function formatAddress(a: Address, opts?: {
+    locale?: string;
+    includeCountry?: boolean;
+}): string[];
+interface NativeSelectProps extends Omit<React.SelectHTMLAttributes<HTMLSelectElement>, "size">, ControlA11yProps {
+    size?: "sm" | "md" | "lg";
+    invalid?: boolean;
+}
+export interface RegionSelectProps extends Omit<NativeSelectProps, "value" | "defaultValue" | "onChange"> {
+    /** Region data (e.g. `trAddress` from `@vamos-ui/react/locale-data`). */
+    source: AddressDataSource;
+    level: "province" | "district";
+    /** Parent province name, for `level="district"`. */
+    province?: string;
+    value?: string;
+    defaultValue?: string;
+    onValueChange?: (name: string) => void;
+    /** First option text. */
+    placeholder?: string;
+    labels?: Partial<AddressFieldLabels>;
+}
+/**
+ * Province or district picker over an address data source, loaded lazily. Values are official
+ * names. Use alone in filter bars ("Branches in İzmir") or inside AddressField.
+ *
+ * ```tsx
+ * <Field label="Province"><RegionSelect source={trAddress} level="province" /></Field>
+ * ```
+ */
+export declare const RegionSelect: React.ForwardRefExoticComponent<RegionSelectProps & React.RefAttributes<HTMLSelectElement>>;
+export interface AddressFieldProps extends Omit<React.FieldsetHTMLAttributes<HTMLFieldSetElement>, "defaultValue" | "onChange" | "required"> {
+    value?: Address | null;
+    defaultValue?: Address | null;
+    onValueChange?: (address: Address) => void;
+    /** Region data per country. Default `{ TR: trAddress }` (81 provinces, 973 districts, lazy). */
+    sources?: Record<string, AddressDataSource>;
+    /** Country list. Default: every country. */
+    countries?: string[];
+    /** Initial country when there is no value. Default `"TR"` for Turkish locales, else the locale's region. */
+    defaultCountry?: string;
+    /** Parts to show, in any order of preference. Default: all except `region3`. */
+    fields?: AddressPart[];
+    /** Parts that are required. */
+    required?: AddressPart[];
+    /** `"grid"` (two columns from `sm`, default) or `"stack"`. */
+    layout?: "grid" | "stack";
+    /** Prefix for form names: `billing` → `billing[country]`, `billing[region1]`… */
+    name?: string;
+    legend?: React.ReactNode;
+    hint?: React.ReactNode;
+    /** Per-part errors from your validation. */
+    errors?: Partial<Record<AddressPart, React.ReactNode>>;
+    readOnly?: boolean;
+    size?: "sm" | "md" | "lg";
+    labels?: Partial<AddressFieldLabels>;
+}
+/**
+ * Structured postal address in a fieldset: country → province → district cascading pickers for
+ * countries with a data source (Türkiye ships built in, loaded lazily), free text elsewhere.
+ * Changing a parent clears its children (and says so to screen readers). Read-only shows the
+ * address formatted the way the country writes it.
+ *
+ * ```tsx
+ * <AddressField legend="Billing address" name="billing" defaultValue={{ country: "TR" }} required={["line1", "region1", "region2"]} />
+ * ```
+ */
+export declare const AddressField: React.ForwardRefExoticComponent<AddressFieldProps & React.RefAttributes<HTMLFieldSetElement>>;
+export {};

package/dist/components/address-field.js

@@ -0,0 +1,219 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import * as React from "react";
+import { ChevronDown } from "lucide-react";
+import { cn } from "../lib/cn.js";
+import { useFieldControl } from "../lib/field-context.js";
+import { useLabels } from "../lib/labels.js";
+import { useLocale } from "../lib/locale.js";
+import { compareText } from "../lib/text.js";
+import { useControllableState, useLatest } from "../lib/use-controllable-state.js";
+import { controlVariants } from "../lib/variants.js";
+import { checkTrPostalCode, trAddress } from "../locale-data/tr/address.js";
+import { Field, Fieldset, Input } from "./input.js";
+/** ISO 3166-1 alpha-2 codes (names come from `Intl.DisplayNames`). */
+const COUNTRY_CODES = "AD AE AF AG AI AL AM AO AR AS AT AU AW AX AZ BA BB BD BE BF BG BH BI BJ BL BM BN BO BQ BR BS BT BW BY BZ CA CC CD CF CG CH CI CK CL CM CN CO CR CU CV CW CX CY CZ DE DJ DK DM DO DZ EC EE EG EH ER ES ET FI FJ FK FM FO FR GA GB GD GE GF GG GH GI GL GM GN GP GQ GR GT GU GW GY HK HN HR HT HU ID IE IL IM IN IO IQ IR IS IT JE JM JO JP KE KG KH KI KM KN KP KR KW KY KZ LA LB LC LI LK LR LS LT LU LV LY MA MC MD ME MF MG MH MK ML MM MN MO MP MQ MR MS MT MU MV MW MX MY MZ NA NC NE NF NG NI NL NO NP NR NU NZ OM PA PE PF PG PH PK PL PM PN PR PS PT PW PY QA RE RO RS RU RW SA SB SC SD SE SG SH SI SK SL SM SN SO SR SS ST SV SX SY SZ TC TD TG TH TJ TK TL TM TN TO TR TT TV TW TZ UA UG US UY UZ VA VC VE VG VI VN VU WF WS XK YE YT ZA ZM ZW".split(" ");
+const addressLabels = {
+    country: "Country",
+    province: "Province",
+    district: "District",
+    state: "State / Province",
+    city: "City",
+    line1: "Street address",
+    line2: "Apartment, suite, building",
+    postalCode: "Postal code",
+    zip: "ZIP code",
+    select: "Select…",
+    selectProvince: "Select a province",
+    selectDistrict: "Select a district",
+    provinceFirst: "Choose a province first",
+    loading: "Loading…",
+    districtCleared: "District cleared",
+    postalMismatch: "Postal codes in {province} start with {prefix}",
+};
+const US_LIKE = new Set(["US", "CA", "AU"]);
+function displayNames(locale) {
+    try {
+        return new Intl.DisplayNames([locale], { type: "region" });
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Formats an address as lines in the country's convention.
+ *
+ * ```ts
+ * formatAddress({ country: "TR", region1: "İstanbul", region2: "Kadıköy", line1: "Caferağa Mah. Moda Cad. No: 12", postalCode: "34710" }, { locale: "en-US" });
+ * // ["Caferağa Mah. Moda Cad. No: 12", "34710 Kadıköy/İstanbul", "Türkiye"]
+ * ```
+ */
+export function formatAddress(a, opts = {}) {
+    const { locale = "en-US", includeCountry = true } = opts;
+    const c = a.country?.toUpperCase();
+    const join = (...xs) => xs.filter(Boolean).join(" ");
+    let lines;
+    if (c === "TR")
+        lines = [a.line1, a.line2, a.region3, join(a.postalCode, [a.region2, a.region1].filter(Boolean).join("/"))];
+    else if (US_LIKE.has(c))
+        lines = [a.line1, a.line2, [a.region2, join(a.region1, a.postalCode)].filter(Boolean).join(", ")];
+    else if (c === "GB" || c === "IE")
+        lines = [a.line1, a.line2, a.region2, a.region1, a.postalCode];
+    else
+        lines = [a.line1, a.line2, join(a.postalCode, a.region2), a.region1];
+    if (includeCountry && c)
+        lines.push(displayNames(locale)?.of(c) ?? c);
+    return lines.map((l) => l?.trim()).filter((l) => !!l);
+}
+const NativeSelect = React.forwardRef(function NativeSelect({ className, size = "md", invalid, children, ...rest }, ref) {
+    const props = useFieldControl({ ...rest, "aria-invalid": invalid ? true : rest["aria-invalid"] });
+    return (_jsxs("div", { "data-slot": "address-select", className: cn(controlVariants({ size }), "px-0", className), children: [_jsx("select", { ref: ref, ...props, className: cn("h-full w-full min-w-0 cursor-pointer appearance-none rounded-[inherit] bg-transparent ps-3 pe-9 text-[length:inherit] text-fg outline-none disabled:cursor-not-allowed", props.value === "" && "text-fg-subtle"), children: children }), _jsx(ChevronDown, { "aria-hidden": true, className: "pointer-events-none absolute end-3 size-4 text-fg-subtle" })] }));
+});
+/* ------------------------------------------------------------------ */
+/* RegionSelect                                                        */
+/* ------------------------------------------------------------------ */
+function useRegions(source, level, province) {
+    const [state, setState] = React.useState({ key: "", items: null });
+    const [provinces, setProvinces] = React.useState(null);
+    const key = `${source?.id ?? ""}|${level}|${level === "district" ? province ?? "" : ""}`;
+    const cmp = React.useMemo(() => compareText(source?.id ?? "en"), [source?.id]);
+    React.useEffect(() => {
+        if (!source)
+            return;
+        let alive = true;
+        source.provinces().then((p) => {
+            if (alive)
+                setProvinces(p);
+        });
+        return () => {
+            alive = false;
+        };
+    }, [source]);
+    React.useEffect(() => {
+        if (!source || !provinces)
+            return;
+        let alive = true;
+        if (level === "province") {
+            setState({ key, items: [...provinces].sort((a, b) => cmp(a.name, b.name)) });
+        }
+        else {
+            const p = provinces.find((x) => x.name === province);
+            if (!p)
+                setState({ key, items: [] });
+            else
+                source.districts(p.code).then((d) => {
+                    if (alive)
+                        setState({ key, items: d });
+                });
+        }
+        return () => {
+            alive = false;
+        };
+    }, [source, provinces, level, province, key, cmp]);
+    return { items: state.key === key ? state.items : null, provinces };
+}
+/**
+ * Province or district picker over an address data source, loaded lazily. Values are official
+ * names. Use alone in filter bars ("Branches in İzmir") or inside AddressField.
+ *
+ * ```tsx
+ * <Field label="Province"><RegionSelect source={trAddress} level="province" /></Field>
+ * ```
+ */
+export const RegionSelect = React.forwardRef(function RegionSelect({ source, level, province, value, defaultValue, onValueChange, placeholder, labels, disabled, ...rest }, ref) {
+    const t = useLabels("address", addressLabels, labels);
+    const [current, setCurrent] = useControllableState({ value, defaultValue: defaultValue ?? "", onChange: onValueChange, name: "RegionSelect" });
+    const { items } = useRegions(source, level, province);
+    const needsParent = level === "district" && !province;
+    const loading = !needsParent && items === null;
+    const known = items?.some((x) => x.name === current);
+    return (_jsxs(NativeSelect, { ref: ref, ...rest, value: current, disabled: disabled || needsParent || loading, "aria-busy": loading || undefined, "data-level": level, onChange: (e) => setCurrent(e.currentTarget.value), children: [_jsx("option", { value: "", children: loading ? t("loading") : needsParent ? t("provinceFirst") : placeholder ?? (level === "province" ? t("selectProvince") : t("selectDistrict")) }), current && !known && !loading ? _jsx("option", { value: current, children: current }) : null, items?.map((x) => (_jsx("option", { value: x.name, children: x.name }, x.code)))] }));
+});
+const DEFAULT_FIELDS = ["country", "region1", "region2", "line1", "line2", "postalCode"];
+/**
+ * Structured postal address in a fieldset: country → province → district cascading pickers for
+ * countries with a data source (Türkiye ships built in, loaded lazily), free text elsewhere.
+ * Changing a parent clears its children (and says so to screen readers). Read-only shows the
+ * address formatted the way the country writes it.
+ *
+ * ```tsx
+ * <AddressField legend="Billing address" name="billing" defaultValue={{ country: "TR" }} required={["line1", "region1", "region2"]} />
+ * ```
+ */
+export const AddressField = React.forwardRef(function AddressField(props, ref) {
+    const { value, defaultValue, onValueChange, sources = { TR: trAddress }, countries, defaultCountry, fields = DEFAULT_FIELDS, required = [], layout = "grid", name, legend, hint, errors, readOnly, disabled, size, labels, className, ...rest } = props;
+    const { locale } = useLocale();
+    const t = useLabels("address", addressLabels, labels);
+    const fallbackCountry = (defaultCountry ?? (locale.toLowerCase().startsWith("tr") ? "TR" : regionOfLocale(locale)) ?? "US").toUpperCase();
+    const [address, setAddress] = useControllableState({
+        value,
+        defaultValue: defaultValue ?? { country: fallbackCountry },
+        onChange: (a) => a && onValueChange?.(a),
+        name: "AddressField",
+    });
+    const a = { ...address, country: (address?.country || fallbackCountry).toUpperCase() };
+    const source = sources[a.country];
+    const [announce, setAnnounce] = React.useState("");
+    const [postalWarning, setPostalWarning] = React.useState(null);
+    const { provinces } = useRegions(source, "province", undefined);
+    const latest = useLatest(a);
+    const set = (patch) => setAddress({ ...latest.current, ...patch });
+    const names = React.useMemo(() => displayNames(locale), [locale]);
+    const countryList = React.useMemo(() => {
+        const cmp = compareText(locale);
+        const list = (countries ?? COUNTRY_CODES).map((c) => c.toUpperCase());
+        if (!list.includes(a.country))
+            list.push(a.country);
+        return list.map((code) => ({ code, name: names?.of(code) ?? code })).sort((x, y) => cmp(x.name, y.name));
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [countries, locale, names]);
+    const show = (p) => fields.includes(p);
+    const req = (p) => required.includes(p);
+    const fname = (p) => (name ? `${name}[${p}]` : undefined);
+    const usLike = US_LIKE.has(a.country);
+    if (readOnly) {
+        const lines = formatAddress(a, { locale });
+        return (_jsxs("fieldset", { ref: ref, ...rest, "data-slot": "address-field", "data-readonly": "", className: cn("grid min-w-0 gap-1.5 border-0 p-0", className), children: [legend ? _jsx("legend", { className: "mb-1.5 p-0 text-sm font-semibold text-fg", children: legend }) : null, _jsx("address", { className: "text-sm leading-relaxed text-fg not-italic", children: lines.map((l, i) => (_jsx("span", { className: cn("block", i === lines.length - 1 && lines.length > 1 && "text-fg-muted"), children: l }, i))) }), name ? Object.keys(a).map((k) => (a[k] ? _jsx("input", { type: "hidden", name: fname(k), value: a[k] }, k) : null)) : null] }));
+    }
+    const checkPostal = (code) => {
+        if (a.country !== "TR" || !code)
+            return setPostalWarning(null);
+        const plate = provinces?.find((p) => p.name === a.region1)?.code;
+        const r = checkTrPostalCode(code, plate);
+        setPostalWarning(r === "province" && plate ? t("postalMismatch", { province: a.region1, prefix: String(plate).padStart(2, "0") }) : null);
+    };
+    const parts = {
+        country: show("country") ? (_jsx(Field, { label: t("country"), name: fname("country"), required: req("country"), error: errors?.country, children: _jsx(NativeSelect, { size: size, value: a.country, autoComplete: "country", onChange: (e) => {
+                    const country = e.currentTarget.value;
+                    setPostalWarning(null);
+                    set({ country, region1: undefined, region2: undefined, region3: undefined });
+                }, children: countryList.map((c) => (
+                // Country names come from Intl.DisplayNames, whose data differs between the server's
+                // and the browser's ICU ("Falkland Islands" vs "Falkland Islands (Islas Malvinas)").
+                _jsx("option", { value: c.code, suppressHydrationWarning: true, children: c.name }, c.code))) }) }, "country")) : null,
+        region1: show("region1") ? (_jsx(Field, { label: source ? t("province") : usLike ? t("state") : t("state"), name: fname("region1"), required: req("region1"), error: errors?.region1, children: source ? (_jsx(RegionSelect, { size: size, source: source, level: "province", value: a.region1 ?? "", labels: labels, autoComplete: "address-level1", onValueChange: (region1) => {
+                    const hadChild = !!latest.current.region2;
+                    set({ region1: region1 || undefined, region2: undefined, region3: undefined });
+                    if (hadChild)
+                        setAnnounce(t("districtCleared"));
+                } })) : (_jsx(Input, { size: size, value: a.region1 ?? "", autoComplete: "address-level1", onChange: (e) => set({ region1: e.currentTarget.value || undefined }) })) }, "region1")) : null,
+        region2: show("region2") ? (_jsx(Field, { label: source ? t("district") : t("city"), name: fname("region2"), required: req("region2"), error: errors?.region2, children: source ? (_jsx(RegionSelect, { size: size, source: source, level: "district", province: a.region1, value: a.region2 ?? "", labels: labels, autoComplete: "address-level2", onValueChange: (region2) => {
+                    set({ region2: region2 || undefined, region3: undefined });
+                    setAnnounce("");
+                } })) : (_jsx(Input, { size: size, value: a.region2 ?? "", autoComplete: "address-level2", onChange: (e) => set({ region2: e.currentTarget.value || undefined }) })) }, "region2")) : null,
+        region3: show("region3") ? (_jsx(Field, { label: t("city"), name: fname("region3"), required: req("region3"), error: errors?.region3, children: _jsx(Input, { size: size, value: a.region3 ?? "", autoComplete: "address-level3", onChange: (e) => set({ region3: e.currentTarget.value || undefined }) }) }, "region3")) : null,
+        line1: show("line1") ? (_jsx(Field, { label: t("line1"), name: fname("line1"), required: req("line1"), error: errors?.line1, className: layout === "grid" ? "sm:col-span-2" : undefined, children: _jsx(Input, { size: size, value: a.line1 ?? "", autoComplete: "address-line1", onChange: (e) => set({ line1: e.currentTarget.value || undefined }) }) }, "line1")) : null,
+        line2: show("line2") ? (_jsx(Field, { label: t("line2"), optional: !req("line2"), name: fname("line2"), required: req("line2"), error: errors?.line2, className: layout === "grid" ? "sm:col-span-2" : undefined, children: _jsx(Input, { size: size, value: a.line2 ?? "", autoComplete: "address-line2", onChange: (e) => set({ line2: e.currentTarget.value || undefined }) }) }, "line2")) : null,
+        postalCode: show("postalCode") ? (_jsx(Field, { label: usLike && a.country === "US" ? t("zip") : t("postalCode"), name: fname("postalCode"), required: req("postalCode"), error: errors?.postalCode, hint: postalWarning ?? undefined, children: _jsx(Input, { size: size, value: a.postalCode ?? "", autoComplete: "postal-code", inputMode: a.country === "TR" || a.country === "US" || a.country === "DE" ? "numeric" : undefined, dir: "ltr", className: "tabular", onChange: (e) => set({ postalCode: e.currentTarget.value || undefined }), onBlur: (e) => checkPostal(e.currentTarget.value.trim()) }) }, "postalCode")) : null,
+    };
+    const order = ["country", "postalCode", "region1", "region2", "region3", "line1", "line2"];
+    return (_jsxs(Fieldset, { ref: ref, ...rest, legend: legend, hint: hint, disabled: disabled, "data-slot": "address-field", "data-country": a.country, className: className, children: [_jsx("div", { className: cn("grid min-w-0 gap-x-4 gap-y-3.5", layout === "grid" && "sm:grid-cols-2"), children: order.map((p) => parts[p]) }), _jsx("span", { className: "sr-only", "aria-live": "polite", children: announce })] }));
+});
+function regionOfLocale(locale) {
+    try {
+        return new Intl.Locale(locale).maximize().region;
+    }
+    catch {
+        return undefined;
+    }
+}