@instruments/materia-ui 0.1.0

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

@@ -0,0 +1,152 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { cva } from "class-variance-authority";
+import { createContext, use } from "react";
+import { getResponsiveSizeClasses } from "../../tokens/responsive.js";
+/**
+ * Context for sharing size across KbdGroup children. Carries the raw
+ * {@link ResponsiveSize} (single token or per-breakpoint object) since each
+ * Kbd resolves it through `getResponsiveSizeClasses`, which accepts both.
+ */
+const KbdGroupContext = createContext(undefined);
+/** Default Kbd size. */
+const DEFAULT_KBD_SIZE = "sm";
+/**
+ * Size classes for kbd - maps component size to dimensions and text.
+ * Applied via `getResponsiveSizeClasses` in the component - NOT as a cva
+ * variant - so `size` can be a single token or a per-breakpoint object.
+ */
+const KBD_SIZE_CLASSES = {
+    "2xl": "h-8 min-w-8 px-2 text-paragraph-sm [&_svg:not([class*='size-'])]:size-4",
+    "2xs": "h-4 min-w-4 px-0.5 text-2xs [&_svg:not([class*='size-'])]:size-2",
+    "3xl": "h-9 min-w-9 px-2 text-paragraph [&_svg:not([class*='size-'])]:size-5",
+    base: "h-5.5 min-w-5.5 px-1 text-caption [&_svg:not([class*='size-'])]:size-3",
+    lg: "h-6 min-w-6 px-1.5 text-caption [&_svg:not([class*='size-'])]:size-3.5",
+    sm: "h-5 min-w-5 px-1 text-caption [&_svg:not([class*='size-'])]:size-3",
+    xl: "h-7 min-w-7 px-1.5 text-paragraph-sm [&_svg:not([class*='size-'])]:size-4",
+    xs: "h-4.5 min-w-4.5 px-0.5 text-2xs [&_svg:not([class*='size-'])]:size-2.5",
+};
+/**
+ * kbdVariants variant class helper for Kbd.
+ * Import from "@instruments/materia-ui/components/kbd".
+ * Uses variant-based styling via class-variance-authority.
+ */
+/**
+ * Kbd tone × emphasis grid. Decomposed from the former single `variant` axis:
+ *   - default     → neutral / solid   (bg-muted text-muted-foreground)
+ *   - secondary   → neutral / soft    (solid grey fill, dark text)
+ *   - outline     → neutral / outline
+ *   - ghost       → neutral / ghost
+ *   - brand       → brand   / solid   (solid brand-yellow chip, dark glyph -
+ *                   restyled from the illegible yellow-on-yellow tint the old
+ *                   `brand` variant carried, per the system-wide brand pairing)
+ *   - destructive → danger  / solid   (tinted danger chip)
+ *   - primary     → COLLAPSED onto neutral / soft (near-duplicate of the former
+ *                   `secondary`; both are dark-text neutral chips, and `primary`
+ *                   was unused outside the Kbd matrix story).
+ *
+ * The `tone`/`emphasis` base variants are empty; every rendered combination is
+ * pinned by an explicit compound so the class output moves verbatim. Undefined
+ * combos (e.g. brand/outline) intentionally fall through to the base string.
+ */
+const kbdVariants = cva("pointer-events-none inline-flex w-fit items-center justify-center gap-1 rounded-sm font-medium select-none", {
+    compoundVariants: [
+        {
+            className: "bg-muted text-muted-foreground",
+            emphasis: "solid",
+            tone: "neutral",
+        },
+        {
+            className: "border-secondary bg-secondary text-secondary-foreground border",
+            emphasis: "soft",
+            tone: "neutral",
+        },
+        {
+            className: "border-border bg-background text-foreground border shadow-xs",
+            emphasis: "outline",
+            tone: "neutral",
+        },
+        {
+            className: "text-muted-foreground border-transparent bg-transparent",
+            emphasis: "ghost",
+            tone: "neutral",
+        },
+        {
+            className: "border-brand-accent/40 bg-brand text-brand-foreground border",
+            emphasis: "solid",
+            tone: "brand",
+        },
+        {
+            className: "border-destructive/20 bg-destructive/10 text-destructive border",
+            emphasis: "solid",
+            tone: "danger",
+        },
+    ],
+    defaultVariants: {
+        emphasis: "solid",
+        tone: "neutral",
+    },
+    variants: {
+        tone: {
+            neutral: "",
+            brand: "",
+            danger: "",
+        },
+        emphasis: {
+            solid: "",
+            soft: "",
+            outline: "",
+            ghost: "",
+        },
+    },
+});
+/**
+ * Keyboard key indicator for displaying keyboard shortcuts.
+ *
+ * @param props - The kbd props
+ * @param props.size - Kbd size. Options: "2xs", "xs", "sm" (default), "base", "lg", "xl", "2xl", "3xl".
+ * @param props.tone - Semantic colour. Options: "neutral" (default), "brand", "danger".
+ * @param props.emphasis - Fill treatment. Options: "solid" (default), "soft", "outline", "ghost".
+ * @param props.className - Additional CSS classes to apply.
+ * @param props.children - Key text or icon (e.g., "⌘", "K", "Enter").
+ * @param props... - All other standard HTML kbd element props.
+ *
+ * @example
+ * ```tsx
+ * <Kbd>⌘</Kbd>
+ * <Kbd size="xs" emphasis="soft">K</Kbd>
+ * <KbdGroup>
+ *   <Kbd>⌘</Kbd>
+ *   <Kbd>K</Kbd>
+ * </KbdGroup>
+ * ```
+ *
+ * @bestPractice Wrap multi-key chords in `KbdGroup` and set `size` on the group - children inherit it via context, so you size the combo once.
+ * @bestPractice It renders a semantic `<kbd>`; reserve it for keyboard keys/shortcuts, not as a generic small-label chip (that's `Badge`).
+ * @category typography
+ */
+const Kbd = ({ className, size, tone, emphasis, ...props }) => {
+    const groupSize = use(KbdGroupContext);
+    const resolvedSize = size ?? groupSize;
+    return (_jsx("kbd", { className: cn(kbdVariants({ emphasis, tone }), getResponsiveSizeClasses(resolvedSize, KBD_SIZE_CLASSES, DEFAULT_KBD_SIZE), "[[data-slot=tooltip-content]_&]:bg-background/20 [[data-slot=tooltip-content]_&]:text-background dark:[[data-slot=tooltip-content]_&]:bg-background/10 [[data-slot=tooltip-content]_&]:border-transparent [[data-slot=tooltip-content]_&]:shadow-none", className), "data-slot": "kbd", ...props }));
+};
+/**
+ * Container for grouping multiple keyboard keys together (e.g., "⌘ + K").
+ *
+ * @param props - The kbd group props
+ * @param props.size - Size to apply to all child Kbd components. Options: "2xs", "xs", "sm", "base", "lg", "xl", "2xl", "3xl".
+ * @param props.className - Additional CSS classes to apply.
+ * @param props.children - Kbd components to group.
+ * @param props... - All other standard HTML div element props.
+ *
+ * @example
+ * ```tsx
+ * <KbdGroup size="xs">
+ *   <Kbd>⌘</Kbd>
+ *   <Kbd>K</Kbd>
+ * </KbdGroup>
+ * ```
+ */
+const KbdGroup = ({ className, size, children, ...props }) => (_jsx(KbdGroupContext.Provider, { value: size, children: _jsx("kbd", { className: cn("inline-flex items-center gap-1", className), "data-slot": "kbd-group", ...props, children: children }) }));
+export { DEFAULT_KBD_SIZE, KBD_SIZE_CLASSES, Kbd, KbdGroup, kbdVariants };

package/dist/components/kbd.d.ts

@@ -0,0 +1,2 @@
+export type { KbdGroupProps, KbdProps } from "./kbd/kbd-root.js";
+export { KBD_SIZE_CLASSES, Kbd, KbdGroup, kbdVariants } from "./kbd/kbd-root.js";

package/dist/components/kbd.js

@@ -0,0 +1 @@
+export { KBD_SIZE_CLASSES, Kbd, KbdGroup, kbdVariants } from "./kbd/kbd-root.js";

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

@@ -0,0 +1,22 @@
+import type * as React from "react";
+/**
+ * Renders an accessible label element that can be associated with form controls.
+ *
+ * @param props - The label props
+ * @param props.htmlFor - ID of the form control this label is for.
+ * @param props.className - Additional CSS classes to apply.
+ * @param props.children - Label text content.
+ * @param props... - All other native `<label>` props.
+ *
+ * @example
+ * ```tsx
+ * <Label htmlFor="email">Email Address</Label>
+ * <Label>Username</Label>
+ * ```
+ *
+ * @bestPractice Point `htmlFor` at the control's `id` so clicking the label focuses/toggles it; a `Label` with no association is just styled text.
+ * @bestPractice For checkbox/radio rows and fields, prefer `CheckboxField`/`FieldLabel`/`RadioGroupItem`, which generate the `id`/`htmlFor` pairing for you.
+ * @category forms
+ */
+declare const Label: ({ className, htmlFor, ...props }: React.ComponentProps<"label">) => React.JSX.Element;
+export { Label };

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

@@ -0,0 +1,24 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { cn } from "@instruments/materia-ui/utils/cn";
+/**
+ * Renders an accessible label element that can be associated with form controls.
+ *
+ * @param props - The label props
+ * @param props.htmlFor - ID of the form control this label is for.
+ * @param props.className - Additional CSS classes to apply.
+ * @param props.children - Label text content.
+ * @param props... - All other native `<label>` props.
+ *
+ * @example
+ * ```tsx
+ * <Label htmlFor="email">Email Address</Label>
+ * <Label>Username</Label>
+ * ```
+ *
+ * @bestPractice Point `htmlFor` at the control's `id` so clicking the label focuses/toggles it; a `Label` with no association is just styled text.
+ * @bestPractice For checkbox/radio rows and fields, prefer `CheckboxField`/`FieldLabel`/`RadioGroupItem`, which generate the `id`/`htmlFor` pairing for you.
+ * @category forms
+ */
+const Label = ({ className, htmlFor, ...props }) => (_jsx("label", { htmlFor: htmlFor, className: cn("text-paragraph-sm flex items-center gap-2 font-medium select-none group-data-[disabled=true]:pointer-events-none group-data-[disabled=true]:opacity-50 peer-disabled:cursor-not-allowed peer-disabled:opacity-50", className), "data-component": "label", "data-slot": "label", ...props }));
+export { Label };

package/dist/components/label.d.ts

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

package/dist/components/label.js

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

package/dist/components/location-input/location-input-root.d.ts

@@ -0,0 +1,88 @@
+import type { ResponsiveValue } from "../../tokens/responsive.js";
+import type { ComponentSize } from "../../tokens/size.js";
+import type { WithTestId } from "../../utils/with-test-id.js";
+import type { Location, LocationMode, LocationResolve, LocationSearch } from "./location-types.js";
+/** Supported LocationInput sizes (control-height subset of the shared scale). */
+type LocationInputSize = Extract<ComponentSize, "sm" | "base" | "lg" | "xl" | "2xl">;
+/**
+ * Per-size wrapper class map. Heights match the shared CONTROL_HEIGHT_CLASSES
+ * (Button/Input canon). Applied via `getResponsiveSizeClasses` so `size` can be
+ * a single token or a per-breakpoint object.
+ */
+export declare const LOCATION_WRAPPER_SIZE_CLASSES: Record<LocationInputSize, string>;
+/** Per-size inner-input class map (resolved responsively in the component). */
+export declare const LOCATION_INPUT_SIZE_CLASSES: Record<LocationInputSize, string>;
+export interface LocationInputProps extends WithTestId<{
+    /** Additional CSS classes for the wrapper */
+    className?: string | undefined;
+    /** Disabled state */
+    disabled?: boolean | undefined;
+    /** Input ID for label association */
+    id?: string | undefined;
+    /** Search mode: "city" (default) or "address". Passed to `search`. */
+    mode?: LocationMode | undefined;
+    /** Called with the chosen location, or `null` when cleared or edited. */
+    onChange: (location: Location | null) => void;
+    /** Input placeholder text */
+    placeholder?: string | undefined;
+    /** Currently selected location (controlled) */
+    value?: Location | null | undefined;
+}> {
+    /**
+     * Input size - a single token or a per-breakpoint object like
+     * `{ base: "sm", md: "lg" }`. Matches `DEFAULT_INPUT_SIZE` so LocationInput
+     * lines up with Input/Button at the same `size`. @default "xl"
+     */
+    size?: ResponsiveValue<LocationInputSize>;
+    /** Show error styling */
+    hasError?: boolean;
+    /**
+     * Geocoder search, supplied by the application. Required: the component
+     * ships no geocoding of its own.
+     */
+    search: LocationSearch;
+    /**
+     * Resolves a chosen suggestion to a full `Location`, supplied by the
+     * application. Required.
+     */
+    resolve: LocationResolve;
+}
+/**
+ * Location autocomplete input with a dropdown of suggestions for city or
+ * address search. The geocoder is injected: pass `search` (query to
+ * suggestions) and `resolve` (suggestion to full `Location`). Queries are
+ * debounced by 300ms and start at two characters.
+ *
+ * @param props - The location input props
+ * @param props.value - Currently selected location object
+ * @param props.onChange - Callback when location is selected or cleared
+ * @param props.mode - Search mode: "city" (default) or "address"
+ * @param props.placeholder - Input placeholder text
+ * @param props.size - Input size: "sm", "base", "lg", "xl" (default), or "2xl"
+ * @param props.hasError - Show error styling
+ * @param props.className - Additional CSS classes
+ * @param props.id - Input ID for label association
+ * @param props.disabled - Disabled state
+ * @param props.testId - Test ID for testing purposes
+ * @param props.search - Geocoder search function (required)
+ * @param props.resolve - Resolves a suggestion's `placeId` to a `Location` (required)
+ *
+ * @example
+ * ```tsx
+ * <LocationInput
+ *   value={location}
+ *   onChange={setLocation}
+ *   mode="city"
+ *   placeholder="Search city…"
+ *   search={(query, { mode }) => geocoder.suggest(query, mode)}
+ *   resolve={(placeId) => geocoder.details(placeId)}
+ * />
+ * ```
+ *
+ * @bestPractice `search` and `resolve` are required - the component has no built-in geocoder. Wrap your provider (Google Places, Mapbox, your own API) in those two functions.
+ * @bestPractice `search` may reject; the dropdown then shows no suggestions. Return `null` from `resolve` to ignore a selection.
+ * @bestPractice Pick `mode="city"` vs `"address"` to scope the geocoding; drive it controlled via the `Location` `value` + `onChange` (which also fires on clear).
+ * @category forms
+ */
+export declare const LocationInput: ({ value, onChange, mode, placeholder, size, hasError, className, id, disabled, testId, search, resolve, }: LocationInputProps) => import("react").JSX.Element;
+export {};

package/dist/components/location-input/location-input-root.js

@@ -0,0 +1,86 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { cva } from "class-variance-authority";
+import { MapPin, X } from "lucide-react";
+import { hasErrorInput } from "../../tokens/has-error-input.js";
+import { INPUT_CONTROL_RESET, INPUT_WRAPPER } from "../../tokens/input-shell.js";
+import { getResponsiveSizeClasses } from "../../tokens/responsive.js";
+import { Button } from "../button.js";
+import { Icon } from "../icon.js";
+import { MenuItem } from "../menu-item.js";
+import { useLocationInput } from "./use-location-input.js";
+/** Default LocationInput size. */
+const DEFAULT_LOCATION_INPUT_SIZE = "xl";
+/**
+ * Per-size wrapper class map. Heights match the shared CONTROL_HEIGHT_CLASSES
+ * (Button/Input canon). Applied via `getResponsiveSizeClasses` so `size` can be
+ * a single token or a per-breakpoint object.
+ */
+export const LOCATION_WRAPPER_SIZE_CLASSES = {
+    "2xl": "h-14 gap-2.5 px-4",
+    base: "h-9 gap-2 px-2.5",
+    lg: "h-10 gap-2 px-3",
+    sm: "h-8 gap-1.5 px-2",
+    xl: "h-12 gap-2.5 px-3.5",
+};
+/** Per-size inner-input class map (resolved responsively in the component). */
+export const LOCATION_INPUT_SIZE_CLASSES = {
+    "2xl": "h-14 py-2.5 text-paragraph",
+    base: "h-9 py-1.5 text-paragraph-sm",
+    lg: "h-10 py-2 text-paragraph-sm",
+    sm: "h-8 py-1 text-paragraph-sm",
+    xl: "h-12 py-2 text-paragraph-sm",
+};
+const inputWrapperVariants = cva(INPUT_WRAPPER);
+const inputVariants = cva(INPUT_CONTROL_RESET);
+/**
+ * Location autocomplete input with a dropdown of suggestions for city or
+ * address search. The geocoder is injected: pass `search` (query to
+ * suggestions) and `resolve` (suggestion to full `Location`). Queries are
+ * debounced by 300ms and start at two characters.
+ *
+ * @param props - The location input props
+ * @param props.value - Currently selected location object
+ * @param props.onChange - Callback when location is selected or cleared
+ * @param props.mode - Search mode: "city" (default) or "address"
+ * @param props.placeholder - Input placeholder text
+ * @param props.size - Input size: "sm", "base", "lg", "xl" (default), or "2xl"
+ * @param props.hasError - Show error styling
+ * @param props.className - Additional CSS classes
+ * @param props.id - Input ID for label association
+ * @param props.disabled - Disabled state
+ * @param props.testId - Test ID for testing purposes
+ * @param props.search - Geocoder search function (required)
+ * @param props.resolve - Resolves a suggestion's `placeId` to a `Location` (required)
+ *
+ * @example
+ * ```tsx
+ * <LocationInput
+ *   value={location}
+ *   onChange={setLocation}
+ *   mode="city"
+ *   placeholder="Search city…"
+ *   search={(query, { mode }) => geocoder.suggest(query, mode)}
+ *   resolve={(placeId) => geocoder.details(placeId)}
+ * />
+ * ```
+ *
+ * @bestPractice `search` and `resolve` are required - the component has no built-in geocoder. Wrap your provider (Google Places, Mapbox, your own API) in those two functions.
+ * @bestPractice `search` may reject; the dropdown then shows no suggestions. Return `null` from `resolve` to ignore a selection.
+ * @bestPractice Pick `mode="city"` vs `"address"` to scope the geocoding; drive it controlled via the `Location` `value` + `onChange` (which also fires on clear).
+ * @category forms
+ */
+export const LocationInput = ({ value, onChange, mode = "city", placeholder, size = "xl", hasError, className, id, disabled, testId, search, resolve, }) => {
+    const { handleClear, handleFocus, handleInputChange, isLoading, isOpen, predictions, query, select, wrapperRef, } = useLocationInput({ disabled, mode, onChange, resolve, search, value });
+    const effectivePlaceholder = placeholder ?? (mode === "address" ? "Search address…" : "Search city…");
+    const hasValue = Boolean(value);
+    return (_jsxs("div", { className: cn("relative", className), ref: wrapperRef, children: [_jsxs("div", { className: cn(inputWrapperVariants(), getResponsiveSizeClasses(size, LOCATION_WRAPPER_SIZE_CLASSES, DEFAULT_LOCATION_INPUT_SIZE), 
+                // Mirrors focusInput() default in focus-within form (see token JSDoc).
+                "focus-within:border-ring overflow-hidden rounded-md focus-within:ring-3 focus-within:ring-gray-500/80", hasError === true && hasErrorInput, disabled === true && "pointer-events-none opacity-50"), "data-component": "location-input", "data-testid": testId, children: [_jsx(Icon, { className: "text-muted-foreground shrink-0", icon: MapPin, size: "xs" }), _jsx("input", { "aria-label": "Search location", className: cn(inputVariants(), getResponsiveSizeClasses(size, LOCATION_INPUT_SIZE_CLASSES, DEFAULT_LOCATION_INPUT_SIZE)), disabled: disabled, id: id, onChange: (event) => {
+                            handleInputChange(event.target.value);
+                        }, onFocus: handleFocus, placeholder: effectivePlaceholder, type: "text", value: query }), hasValue && disabled !== true ? (_jsx(Button, { "aria-label": "Clear location", className: "text-muted-foreground hover:text-foreground", emphasis: "ghost", icon: X, onClick: handleClear, radius: "rounded", size: "icon-2xs", square: true, tone: "neutral", type: "button" })) : null, isLoading ? (_jsx("span", { className: "text-muted-foreground text-caption shrink-0", children: "\u2026" })) : null] }), isOpen && disabled !== true && predictions.length > 0 ? (_jsx("ul", { className: "bg-popover absolute inset-x-0 top-full z-50 m-0 max-h-60 list-none overflow-auto rounded-3xl border p-0 shadow-xs", children: predictions.map((prediction) => (_jsx("li", { children: _jsx(MenuItem, { className: "hover:bg-muted hover:text-accent-foreground focus:bg-muted focus:text-accent-foreground rounded-full px-4 py-2.5", onClick: () => {
+                            void select(prediction.placeId);
+                        }, children: _jsxs("span", { children: [_jsx("span", { className: "font-medium", children: prediction.mainText }), prediction.secondaryText !== undefined &&
+                                    prediction.secondaryText !== "" ? (_jsx("span", { className: "text-muted-foreground ml-1", children: prediction.secondaryText })) : null] }) }) }, prediction.placeId))) })) : null] }));
+};

package/dist/components/location-input/location-types.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Structured location returned by a geocoder once a suggestion is resolved.
+ */
+export interface Location {
+    /** City/locality */
+    city?: string | undefined;
+    /** Country */
+    country?: string | undefined;
+    /** ISO country code (e.g., "US", "GB") */
+    countryCode?: string | undefined;
+    /** Full formatted address */
+    formatted: string;
+    /** Latitude */
+    lat?: number | undefined;
+    /** Longitude */
+    lng?: number | undefined;
+    /** Provider place identifier, passed back to `resolve` */
+    placeId: string;
+    /** Postal/ZIP code */
+    postalCode?: string | undefined;
+    /** State/region/administrative area */
+    state?: string | undefined;
+    /** Street address (number + route) */
+    streetAddress?: string | undefined;
+}
+/**
+ * Search scope: "city" for cities only, "address" for full addresses.
+ */
+export type LocationMode = "city" | "address";
+/**
+ * One row in the suggestion dropdown.
+ */
+export interface LocationSuggestion {
+    /** Full single-line description. */
+    description: string;
+    /** Primary label, rendered in bold. */
+    mainText: string;
+    /** Provider place identifier, passed back to `resolve`. */
+    placeId: string;
+    /** Secondary label, rendered muted beside the primary one. */
+    secondaryText?: string | undefined;
+}
+/**
+ * Returns suggestions for a query. Called after the input debounce, with at
+ * least two characters. Reject to show no suggestions.
+ */
+export type LocationSearch = (query: string, options: {
+    mode: LocationMode;
+}) => Promise<LocationSuggestion[]>;
+/**
+ * Resolves a chosen suggestion's `placeId` to a full `Location`, or `null`
+ * when it cannot be resolved (the selection is then ignored).
+ */
+export type LocationResolve = (placeId: string) => Promise<Location | null>;

package/dist/components/location-input/location-types.js

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

package/dist/components/location-input/use-location-input.d.ts

@@ -0,0 +1,25 @@
+import type { Location, LocationMode, LocationResolve, LocationSearch } from "./location-types.js";
+interface UseLocationInputOptions {
+    disabled: boolean | undefined;
+    mode: LocationMode;
+    onChange: (location: Location | null) => void;
+    resolve: LocationResolve;
+    search: LocationSearch;
+    value: Location | null | undefined;
+}
+/**
+ * Open/close, selection and controlled-value sync for `LocationInput`.
+ * @internal
+ */
+export declare const useLocationInput: ({ disabled, mode, onChange, resolve, search, value, }: UseLocationInputOptions) => {
+    handleClear: () => void;
+    handleFocus: () => void;
+    handleInputChange: (next: string) => void;
+    isLoading: boolean;
+    isOpen: boolean;
+    predictions: import("./location-types.js").LocationSuggestion[];
+    query: string;
+    select: (placeId: string) => Promise<void>;
+    wrapperRef: import("react").RefObject<HTMLDivElement | null>;
+};
+export {};

package/dist/components/location-input/use-location-input.js

@@ -0,0 +1,71 @@
+"use client";
+import { useCallback, useEffect, useRef, useState } from "react";
+import { useLocationSearch } from "./use-location-search.js";
+/**
+ * Open/close, selection and controlled-value sync for `LocationInput`.
+ * @internal
+ */
+export const useLocationInput = ({ disabled, mode, onChange, resolve, search, value, }) => {
+    const [isOpen, setIsOpen] = useState(false);
+    const wrapperRef = useRef(null);
+    const { query, setQuery, predictions, isLoading, selectPlace, clear } = useLocationSearch({ mode, resolve, search });
+    const select = useCallback(async (placeId) => {
+        const location = await selectPlace(placeId);
+        if (location !== null) {
+            onChange(location);
+            clear();
+            setQuery(location.formatted);
+        }
+        setIsOpen(false);
+    }, [clear, onChange, selectPlace, setQuery]);
+    const handleClear = useCallback(() => {
+        clear();
+        setIsOpen(false);
+        onChange(null);
+    }, [clear, onChange]);
+    useEffect(() => {
+        if (value === null || value === undefined) {
+            setQuery("");
+        }
+        else if (value.formatted !== "") {
+            setQuery(value.formatted);
+        }
+    }, [setQuery, value]);
+    useEffect(() => {
+        const handleClickOutside = (event) => {
+            const wrapper = wrapperRef.current;
+            if (wrapper !== null &&
+                event.target instanceof Node &&
+                !wrapper.contains(event.target)) {
+                setIsOpen(false);
+            }
+        };
+        document.addEventListener("mousedown", handleClickOutside);
+        return () => {
+            document.removeEventListener("mousedown", handleClickOutside);
+        };
+    }, []);
+    const handleInputChange = useCallback((next) => {
+        setQuery(next);
+        setIsOpen(true);
+        if (next === "" || (value && next !== value.formatted)) {
+            onChange(null);
+        }
+    }, [onChange, setQuery, value]);
+    const handleFocus = useCallback(() => {
+        if (disabled !== true) {
+            setIsOpen(true);
+        }
+    }, [disabled]);
+    return {
+        handleClear,
+        handleFocus,
+        handleInputChange,
+        isLoading,
+        isOpen,
+        predictions,
+        query,
+        select,
+        wrapperRef,
+    };
+};

package/dist/components/location-input/use-location-search.d.ts

@@ -0,0 +1,19 @@
+import type { Location, LocationMode, LocationResolve, LocationSearch, LocationSuggestion } from "./location-types.js";
+interface UseLocationSearchOptions {
+    mode: LocationMode;
+    resolve: LocationResolve;
+    search: LocationSearch;
+}
+/**
+ * Debounced query-to-suggestions state around an injected geocoder.
+ * @internal
+ */
+export declare const useLocationSearch: ({ mode, resolve, search, }: UseLocationSearchOptions) => {
+    clear: () => void;
+    isLoading: boolean;
+    predictions: LocationSuggestion[];
+    query: string;
+    selectPlace: (placeId: string) => Promise<Location | null>;
+    setQuery: import("react").Dispatch<import("react").SetStateAction<string>>;
+};
+export {};

package/dist/components/location-input/use-location-search.js

@@ -0,0 +1,65 @@
+"use client";
+import { useCallback, useEffect, useRef, useState } from "react";
+const DEBOUNCE_MS = 300;
+const MIN_CHARS = 2;
+/**
+ * Debounced query-to-suggestions state around an injected geocoder.
+ * @internal
+ */
+export const useLocationSearch = ({ mode, resolve, search, }) => {
+    const [query, setQuery] = useState("");
+    const [result, setResult] = useState({ items: [], query: "" });
+    // Callers usually pass inline functions; refs keep them out of effect deps.
+    const searchRef = useRef(search);
+    const resolveRef = useRef(resolve);
+    useEffect(() => {
+        searchRef.current = search;
+        resolveRef.current = resolve;
+    }, [search, resolve]);
+    useEffect(() => {
+        let cancelled = false;
+        const run = async () => {
+            if (query.length < MIN_CHARS) {
+                return;
+            }
+            let items = [];
+            try {
+                items = await searchRef.current(query, { mode });
+            }
+            catch {
+                items = [];
+            }
+            if (!cancelled) {
+                setResult({ items, query });
+            }
+        };
+        const timer = setTimeout(() => {
+            void run();
+        }, DEBOUNCE_MS);
+        return () => {
+            cancelled = true;
+            clearTimeout(timer);
+        };
+    }, [query, mode]);
+    const selectPlace = useCallback(async (placeId) => {
+        try {
+            return await resolveRef.current(placeId);
+        }
+        catch {
+            return null;
+        }
+    }, []);
+    const clear = useCallback(() => {
+        setQuery("");
+        setResult({ items: [], query: "" });
+    }, []);
+    const searchable = query.length >= MIN_CHARS;
+    return {
+        clear,
+        isLoading: searchable && result.query !== query,
+        predictions: searchable ? result.items : [],
+        query,
+        selectPlace,
+        setQuery,
+    };
+};

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

@@ -0,0 +1,2 @@
+export type { Location, LocationMode, LocationResolve, LocationSearch, LocationSuggestion, } from "./location-input/location-types.js";
+export { LocationInput } from "./location-input/location-input-root.js";

package/dist/components/location-input.js

@@ -0,0 +1 @@
+export { LocationInput } from "./location-input/location-input-root.js";