themelia-ui 2.0.0 → 3.0.0

package/dist/components/features/global-search/global-search.types.d.ts

@@ -19,7 +19,10 @@ export interface GlobalSearchResult<TGroup extends string = string> {
     /** The only line guaranteed to render. */
     title: string;
     subtitle?: string;
-    /** The bucket this lands in. Also a tab, unless `tabs` says otherwise. */
+    /**
+     * The bucket this lands in. Tabs and group headings are both generated from the groups that
+     * actually returned something, unless `tabs` says otherwise.
+     */
     group: TGroup;
     avatar?: {
         src?: string;
@@ -76,22 +79,49 @@ export interface GlobalSearchSlots<TGroup extends string = string> {
     renderResult?: (result: GlobalSearchResult<TGroup>, context: GlobalSearchRenderResultContext) => ReactNode;
 }
 export interface GlobalSearchProps<TGroup extends string = string> {
+    /**
+     * One shape for every kind, with optional parts: avatar OR thumbnail, a badge, meta, tags, a
+     * timestamp, a trailing figure. A union per kind would be honest about the data and useless
+     * for a list that renders them all the same way.
+     */
     results?: readonly GlobalSearchResult<TGroup>[];
-    /** Controlled. The palette never searches; it renders what it is given. */
+    /** Controlled, always. The palette never searches; it renders what it is given. */
     query: string;
+    /** Receives every edit to `query`. */
     onQueryChange: (query: string) => void;
+    /** Fires on click and on Enter, with the whole result including its free-form `data`. */
     onResultSelect?: (result: GlobalSearchResult<TGroup>) => void;
-    /** Fires on Escape. The dialog presentation wires this to closing itself. */
+    /**
+     * Fires on Escape. The dialog presentation wires this to closing itself; a panel embedded in
+     * a page usually wants it too.
+     */
     onClose?: () => void;
-    /** Swaps the input's clear button for a spinner and shows the loading region. */
+    /**
+     * Swaps the input's clear control for a spinner and shows the loading region. Hidden results
+     * cannot be selected while the loading region is visible.
+     */
     loading?: boolean;
+    /**
+     * Recent queries and curated suggestions. The palette has no memory of its own — whose
+     * recents these are is a question only the app can answer.
+     */
     idleSections?: readonly GlobalSearchIdleSection[];
-    /** Names a group in the tab strip and above its results. Otherwise the key shows. */
+    /**
+     * Names a group in the tab strip and above its results. Without it the raw key shows, which
+     * is a useful default only while you are wiring it up.
+     */
     groupLabels?: Partial<Record<TGroup, ReactNode>>;
     autoFocus?: boolean;
     strings?: Partial<GlobalSearchStrings>;
+    /**
+     * `input`, `tabs`, `idle`, `empty`, `loading`, `footer`, and `renderResult` — every region,
+     * replaceable one at a time.
+     */
     slots?: GlobalSearchSlots<TGroup>;
-    /** Replaces the auto-generated "All + one per group" strip. */
+    /**
+     * Replaces the auto-generated "All + one per group" strip, for a fixed set of tabs that
+     * should not appear and disappear with the results.
+     */
     tabs?: readonly GlobalSearchTab<TGroup>[];
     className?: string;
 }

package/dist/components/features/global-search/use-global-search.d.ts

@@ -25,4 +25,9 @@ export interface UseGlobalSearchResult<TGroup extends string = string> {
     onKeyDown: (event: KeyboardEvent) => void;
     selectActive: () => void;
 }
+/**
+ * The palette's active row, active tab and key handling — `grouped`, `tabCounts`, `activeTab`,
+ * `flat`, `activeIndex` and `onKeyDown` — for a palette whose markup is entirely yours. `flat`
+ * is both what the rows render and what the keys walk, so the highlight and Enter always agree.
+ */
 export declare function useGlobalSearch<TGroup extends string = string>({ results, query, onResultSelect, onClose, }: UseGlobalSearchOptions<TGroup>): UseGlobalSearchResult<TGroup>;

package/dist/components/features/kanban/kanban-context.d.ts

@@ -1,5 +1,6 @@
 import { KanbanContextValue } from './kanban.types.js';
 export declare const KanbanContextProvider: import('react').Provider<KanbanContextValue<unknown> | null>;
+/** The board's state, for a custom card or column rendered inside it. */
 export declare function useKanbanContext<T = unknown>(): KanbanContextValue<T>;
 /**
  * What one card publishes to its parts. `registerHandle`: a mounted handle registers
@@ -15,4 +16,5 @@ export interface KanbanItemContextValue<T = unknown> {
     item: T | null;
 }
 export declare const KanbanItemContextProvider: import('react').Provider<KanbanItemContextValue<unknown> | null>;
+/** One card's drag state, for a custom card that still needs to know it is being dragged. */
 export declare function useKanbanItemContext<T = unknown>(): KanbanItemContextValue<T>;

package/dist/components/features/kanban/kanban.d.ts

@@ -1,12 +1,34 @@
 import { Ref } from 'react';
 import { KanbanBoardProps, KanbanColumnContentProps, KanbanColumnProps, KanbanItemActionsProps, KanbanItemHandleProps, KanbanItemProps, KanbanOverlayProps, KanbanProps } from './kanban.types.js';
+/**
+ * A drag-and-drop board. It never persists: `onValueChange` is the truth, and `onItemMove` the
+ * seam for saving it.
+ */
 export declare function Kanban<T>({ value, onValueChange, getItemValue, onItemMove, itemActions, onItemClick, strings, className, children, }: KanbanProps<T>): import("react").JSX.Element;
 export declare function KanbanBoard({ className, style, children }: KanbanBoardProps): import("react").JSX.Element;
 export declare function KanbanColumn({ value, className, children }: KanbanColumnProps): import("react").JSX.Element;
+/**
+ * A column's droppable region, for a board that wants its own column chrome but the same drag
+ * behaviour.
+ */
 export declare function KanbanColumnContent({ value, className, children }: KanbanColumnContentProps): import("react").JSX.Element;
+/**
+ * One draggable card, for a board that wants its own column chrome but the same drag
+ * behaviour.
+ */
 export declare function KanbanItem({ value, className, disabled, onClick, children, }: KanbanItemProps): import("react").JSX.Element;
+/**
+ * The grip. Optional: present, it becomes the only grip; absent, the whole card is. A handle
+ * rather than a draggable card body, because a card carrying a menu and a link has no way to
+ * tell a drag from a press otherwise — and text inside the card stays selectable.
+ */
 export declare function KanbanItemHandle({ className, children, ref, }: KanbanItemHandleProps & {
     ref?: Ref<HTMLButtonElement>;
 }): import("react").JSX.Element;
+/** The card's verbs: its `itemActions`, in a menu. */
 export declare function KanbanItemActions<T = unknown>({ className, icon, label, }: KanbanItemActionsProps): import("react").JSX.Element | null;
+/**
+ * What follows the pointer during a drag — rendered outside the column so it is not clipped by
+ * the scroll container it started in.
+ */
 export declare function KanbanOverlay<T = unknown>({ className, render }: KanbanOverlayProps<T>): import("react").JSX.Element;

package/dist/components/features/kanban/kanban.types.d.ts

@@ -39,14 +39,32 @@ export interface KanbanContextValue<T = unknown> {
     strings: KanbanStrings;
 }
 export interface KanbanProps<T = unknown> {
+    /**
+     * The board, as `Record<columnId, T[]>`: a plain object because that is what a board is,
+     * and it serialises without a thought. Column titles and limits are the consumer's — only
+     * the ORDER lives here.
+     */
     value: KanbanValue<T>;
+    /** Receives the whole next board after every move. */
     onValueChange: (next: KanbanValue<T>) => void;
     /** A stable id per item. Everything else is keyed off this. */
     getItemValue: (item: T) => string;
-    /** Fires after a move lands, with both ends of it, for persistence or analytics. */
+    /**
+     * Fires after a move lands, with both ends of it — from column and index, to column and
+     * index. The seam for persistence or analytics. Idempotent: a move that changes nothing
+     * fires nothing.
+     */
     onItemMove?: (event: KanbanItemMoveEvent<T>) => void;
+    /**
+     * Each card's actions, or a function of the card. The factory form is what a real board
+     * needs: “Reopen” belongs on a card in Done and nowhere else, and a fixed list would render
+     * it everywhere and disable it.
+     */
     itemActions?: KanbanItemActions<T>;
-    /** Fires on a card click that was not the handle or the menu. */
+    /**
+     * Fires on a card click that was not the handle or the menu — both mark themselves, so a
+     * click on an icon inside either is caught too.
+     */
     onItemClick?: (item: T) => void;
     strings?: Partial<KanbanStrings>;
     className?: string;
@@ -88,7 +106,10 @@ export interface KanbanItemActionsProps {
 }
 export interface KanbanOverlayProps<T = unknown> {
     className?: string;
-    /** Replaces the default outline with the consumer's own card. */
+    /**
+     * Replaces the default outline with the consumer's own card. The default is a placeholder
+     * rather than a copy of the card, because the card's markup lives at the call site.
+     */
     render?: (context: {
         item: T | null;
         columnId: string | null;

package/dist/components/features/kanban/use-kanban.d.ts

@@ -18,4 +18,9 @@ export interface UseKanbanResult<T> {
         toIndex?: number;
     }) => void;
 }
+/**
+ * The move without the drag: `findItem` and `move` over the same `value`, `onValueChange` and
+ * `getItemValue` the board takes — for a keyboard board, a "move to column" menu, or a test
+ * that moves items without simulating a pointer.
+ */
 export declare function useKanban<T>({ value, onValueChange, getItemValue, onItemMove, }: UseKanbanOptions<T>): UseKanbanResult<T>;

package/dist/components/features/map/map-runtime.d.ts

@@ -22,7 +22,14 @@ export declare const ReactLeafletHooksProvider: (props: {
 }) => import("react").JSX.Element | null;
 export declare function useLeafletMap(): LeafletNamespace.Map;
 export declare function useLeafletMapEvents(handlers: Parameters<ReactLeafletModule["useMapEvents"]>[0]): LeafletNamespace.Map;
-/** Leaflet plus draw and fullscreen once loaded; `null` until then, so callers must check. */
+/**
+ * Leaflet itself, with its draw and fullscreen plugins, once it has loaded — and `null` until
+ * then, so callers must check. For a consumer reaching for the imperative API. Everything here
+ * is lazy: Leaflet and its plugins are ~200KB, they touch `window` at import time, and most pages
+ * that ship this kit never render a map. Inside a Map, react-leaflet's hooks reach the controls
+ * through a provider that has already resolved the module, so a control calls `useMap` normally
+ * instead of managing its own load state.
+ */
 export declare function useLeaflet(): {
     L: typeof LeafletNamespace | null;
     LeafletDraw: typeof LeafletDrawNamespace | null;

package/dist/components/features/map/map.d.ts

@@ -7,59 +7,106 @@ import { PlaceAutocompleteProps } from './place-autocomplete.js';
 /** Corner the control anchors to. */
 export type MapControlPosition = "top-left" | "top-right" | "bottom-left" | "bottom-right";
 export type MapProps = Omit<MapContainerProps, "zoomControl"> & {
+    /** Where the map opens, with `zoom`. */
     center: LatLngExpression;
     /**
-     * Minimum height: a named step or any CSS length. The map still grows to fill a flex
-     * parent that gives it room.
+     * Minimum height: `sm`, `md` and `lg` are 16, 24 and 36rem, or any CSS length. A MINIMUM, not
+     * a fixed height — the map still grows to fill a flex parent that gives it room, which is what
+     * a map docked beside a list needs.
      */
     height?: "sm" | "md" | "lg" | (string & {});
     /**
-     * `framed` draws a border and radius; `flush` removes both, for a map that is the panel
-     * itself (a sheet body, a full-bleed hero).
+     * `framed` draws the border and radius the tiles need against a page of the same colour.
+     * `flush` removes both, for a map that IS the panel rather than one sitting inside it — a
+     * sheet's body, a full-bleed hero.
      */
     surface?: "framed" | "flush";
     ref?: Ref<LeafletMapInstance>;
     strings?: Partial<MapStrings>;
 };
+/**
+ * A Leaflet map in the kit's vocabulary. Everything else from react-leaflet's MapContainer
+ * passes through, except `zoomControl` — MapZoomControl replaces it.
+ */
 export declare function Map({ zoom, maxZoom, height, surface, className, children, strings, style, ...props }: MapProps): import("react").JSX.Element;
 interface MapLayerGroupOption {
+    /** Names the group in the layers control, and registers it with the enclosing MapLayers. */
     name: string;
+    /** Disables the group's checkbox in the layers control. */
     disabled?: boolean;
 }
-export type MapTileLayerProps = Partial<TileLayerProps> & {
-    /** Names the layer in the layer control. */
+export type MapTileLayerProps = Partial<TileLayerProps> & Partial<Pick<TileLayerProps, "url" | "attribution">> & {
+    /**
+     * Names the layer in the layer control, and registers it with the enclosing MapLayers under
+     * that name.
+     */
     name?: string;
-    /** Swapped in when the dark theme is active. */
+    /**
+     * Swapped in when the dark theme is active. The default tiles are inverted in dark mode,
+     * since there is no key-less dark basemap; passing `darkUrl` removes the filter.
+     */
     darkUrl?: string;
     darkAttribution?: string;
     ref?: Ref<TileLayer>;
 };
+/**
+ * A base map. Give it a `name` and it registers itself with the enclosing MapLayers, which is
+ * how the layers control knows what to offer without being told twice. Without a `url` it draws
+ * OpenStreetMap's own tiles — the only basemap that renders with no key.
+ */
 export declare function MapTileLayer({ name: nameProp, url, attribution, darkUrl, darkAttribution, ...props }: MapTileLayerProps): import("react").JSX.Element | null;
 export type MapLayerGroupProps = LayerGroupProps & MapLayerGroupOption & {
     ref?: Ref<LayerGroup>;
 };
+/** A toggleable group of overlays, registered with the enclosing MapLayers by `name`. */
 export declare function MapLayerGroup({ name, disabled, ...props }: MapLayerGroupProps): import("react").JSX.Element | null;
 export type MapFeatureGroupProps = LayerGroupProps & MapLayerGroupOption & {
     ref?: Ref<FeatureGroup>;
 };
+/**
+ * A toggleable group of overlays that also answers as one shape for events and bounds, which is
+ * what the drawing tools edit against.
+ */
 export declare function MapFeatureGroup({ name, disabled, ...props }: MapFeatureGroupProps): import("react").JSX.Element | null;
 export interface MapLayersProps {
     children?: ReactNode;
-    /** Must name a MapTileLayer. The first registered one wins when it does not. */
+    /**
+     * Names a MapTileLayer. Naming nothing REPORTS through `onError` and shows the first
+     * registered layer, rather than throwing — a typo should not take down the page.
+     */
     defaultTileLayer?: string;
+    /** The layer groups switched on at first, by name. */
     defaultLayerGroups?: string[];
-    /** Hears about a `defaultTileLayer` or `defaultLayerGroups` naming nothing. */
+    /**
+     * Hears about a `defaultTileLayer` or `defaultLayerGroups` naming nothing — a typo that would
+     * otherwise show an empty map and no reason for it.
+     */
     onError?: (error: Error) => void;
 }
+/**
+ * Holds the registry every named layer reports into. Tile layers become a radio group and
+ * layer groups a checkbox list in MapLayersControl — no array to keep in step with the
+ * children.
+ */
 export declare function MapLayers({ defaultTileLayer, defaultLayerGroups, onError, children, }: MapLayersProps): import("react").JSX.Element;
 export interface MapLayersControlProps extends ComponentProps<"button"> {
+    /** Heads the tile layers' radio group. */
     tileLayersLabel?: string;
+    /** Heads the layer groups' checkboxes. */
     layerGroupsLabel?: string;
+    /** The corner it anchors to. */
     position?: MapControlPosition;
 }
+/**
+ * The layer picker. It throws when mounted outside MapLayers rather than rendering an empty
+ * menu, because a control with nothing to control is a wiring mistake, not a state.
+ */
 export declare function MapLayersControl({ tileLayersLabel, layerGroupsLabel, position, className, ...props }: MapLayersControlProps): import("react").JSX.Element | null;
 export type MapMarkerProps = Omit<MarkerProps, "icon"> & Pick<DivIconOptions, "iconAnchor" | "bgPos" | "popupAnchor" | "tooltipAnchor"> & {
-    /** Rendered to a string and handed to Leaflet as a div icon. */
+    /**
+     * Rendered to a string and handed to Leaflet as a div icon. The accessible name is written
+     * onto the element after Leaflet builds it, because Leaflet builds it outside React.
+     */
     icon?: ReactNode;
     ariaLabel?: string;
     ref?: Ref<Marker>;
@@ -70,33 +117,67 @@ export type MapMarkerClusterGroupProps = Omit<MarkerClusterGroupProps, "iconCrea
     /** Receives how many markers the cluster holds. */
     icon?: (markerCount: number) => ReactNode;
 };
+/**
+ * Collapses markers into counted clusters as the map zooms out. Above a few hundred pins the map
+ * stops being readable and starts being a texture.
+ */
 export declare function MapMarkerClusterGroup({ polygonOptions, spiderLegPolylineOptions, icon, ...props }: MapMarkerClusterGroupProps): import("react").JSX.Element | null;
+/**
+ * A circle sized in metres, so it grows as the map zooms in — MapCircleMarker is sized in
+ * pixels, and the difference matters the moment someone zooms. Like every shape primitive it
+ * takes the kit's tokens for stroke and fill, so a drawn area matches the surface it sits on.
+ */
 export declare function MapCircle({ className, ...props }: CircleProps & {
     ref?: Ref<Circle>;
 }): import("react").JSX.Element;
+/**
+ * A circle sized in pixels, so it keeps its size at every zoom — MapCircle is sized in metres.
+ * Like every shape primitive it takes the kit's tokens for stroke and fill, so a drawn area
+ * matches the surface it sits on.
+ */
 export declare function MapCircleMarker({ className, ...props }: CircleMarkerProps & {
     ref?: Ref<CircleMarker>;
 }): import("react").JSX.Element;
+/** A line, taking the kit's tokens for stroke so it matches the surface it sits on. */
 export declare function MapPolyline({ className, ...props }: PolylineProps & {
     ref?: Ref<Polyline>;
 }): import("react").JSX.Element;
+/**
+ * A polygon, taking the kit's tokens for stroke and fill so a drawn area matches the surface it
+ * sits on.
+ */
 export declare function MapPolygon({ className, ...props }: PolygonProps & {
     ref?: Ref<Polygon>;
 }): import("react").JSX.Element;
+/**
+ * A rectangle, taking the kit's tokens for stroke and fill so a drawn area matches the surface
+ * it sits on.
+ */
 export declare function MapRectangle({ className, ...props }: RectangleProps & {
     ref?: Ref<Rectangle>;
 }): import("react").JSX.Element;
+/**
+ * Attached to a marker or a shape, a popup is clicked open and stays. A popup is where an
+ * action belongs; a tooltip cannot hold one.
+ */
 export declare function MapPopup({ className, ...props }: Omit<PopupProps, "content"> & {
     ref?: Ref<Popup>;
 }): import("react").JSX.Element;
 export type MapTooltipProps = Omit<TooltipProps, "offset"> & {
+    /** The side of its anchor it sits on. */
     side?: "top" | "right" | "bottom" | "left";
     /** Distance from the anchor, in pixels. */
     sideOffset?: number;
     ref?: Ref<Tooltip>;
 };
+/**
+ * Attached to a marker or a shape, a tooltip comes and goes with the pointer, so it cannot hold
+ * an action; that is what a popup is for. It takes a `side` and an offset, and Leaflet's own tip
+ * is removed, because a single built-in tip cannot sit on a side this component chose.
+ */
 export declare function MapTooltip({ className, children, side, sideOffset, ...props }: MapTooltipProps): import("react").JSX.Element;
 export interface MapControlContainerProps extends ComponentProps<"div"> {
+    /** The corner it anchors to. */
     position?: MapControlPosition;
 }
 /**
@@ -111,28 +192,69 @@ export declare function MapZoomControl({ position, className, ...props }: MapZoo
 export interface MapFullscreenControlProps extends ComponentProps<"button"> {
     position?: MapControlPosition;
 }
+/** Toggles the map in and out of full screen. */
 export declare function MapFullscreenControl({ position, className, ...props }: MapFullscreenControlProps): import("react").JSX.Element;
 export interface MapLocateControlProps extends ComponentProps<"button">, Pick<LocateOptions, "watch"> {
     onLocationFound?: (location: LocationEvent) => void;
     onLocationError?: (error: ErrorEvent) => void;
     position?: MapControlPosition;
 }
+/**
+ * Find-me. It draws a pulse at the fix rather than only recentring, because a map that jumps
+ * with no mark leaves the reader hunting for what moved. `watch` follows the device; the watch
+ * is stopped on unmount, since one left running keeps the radio awake.
+ */
 export declare function MapLocateControl({ watch, onLocationFound, onLocationError, position, className, ...props }: MapLocateControlProps): import("react").JSX.Element;
 export interface MapSearchControlProps extends PlaceAutocompleteProps {
     position?: MapControlPosition;
 }
+/** Place search over the map: a PlaceAutocomplete in one of the control corners. */
 export declare function MapSearchControl({ position, className, ...props }: MapSearchControlProps): import("react").JSX.Element;
 export interface MapDrawControlProps extends ComponentProps<"div"> {
+    /**
+     * Fires on create, edit, and delete, with the FeatureGroup — call `toGeoJSON()` on it to
+     * persist.
+     */
     onLayersChange?: (layers: FeatureGroup) => void;
     position?: MapControlPosition;
 }
+/**
+ * The drawing toolbar. It composes the tool buttons, so a caller who wants only two of them
+ * mounts those two instead of configuring the toolbar out.
+ */
 export declare function MapDrawControl({ onLayersChange, position, className, children, ...props }: MapDrawControlProps): import("react").JSX.Element;
+/**
+ * The drawing button for a marker. Each shape's button takes Leaflet's own draw options for that
+ * shape, so nothing is re-declared here.
+ */
 export declare function MapDrawMarker(props: DrawOptions.MarkerOptions): import("react").JSX.Element;
+/**
+ * The drawing button for a line. Each shape's button takes Leaflet's own draw options for that
+ * shape, so nothing is re-declared here.
+ */
 export declare function MapDrawPolyline({ showLength, drawError, shapeOptions, ...props }: DrawOptions.PolylineOptions): import("react").JSX.Element;
+/**
+ * The drawing button for a circle. Each shape's button takes Leaflet's own draw options for that
+ * shape, so nothing is re-declared here.
+ */
 export declare function MapDrawCircle({ showRadius, shapeOptions, ...props }: DrawOptions.CircleOptions): import("react").JSX.Element;
+/**
+ * The drawing button for a rectangle. Each shape's button takes Leaflet's own draw options for that
+ * shape, so nothing is re-declared here.
+ */
 export declare function MapDrawRectangle({ showArea, shapeOptions, ...props }: DrawOptions.RectangleOptions): import("react").JSX.Element;
+/**
+ * The drawing button for a polygon. Each shape's button takes Leaflet's own draw options for that
+ * shape, so nothing is re-declared here.
+ */
 export declare function MapDrawPolygon({ drawError, shapeOptions, ...props }: DrawOptions.PolygonOptions): import("react").JSX.Element;
+/** Edits the shapes in the drawing's feature group. */
 export declare function MapDrawEdit({ selectedPathOptions, ...props }: Omit<EditToolbar.EditHandlerOptions, "featureGroup">): import("react").JSX.Element;
+/** Deletes shapes from the drawing's feature group. */
 export declare function MapDrawDelete(): import("react").JSX.Element;
+/**
+ * Undo for the current edit or delete: it steps back what that mode has staged, rather than the
+ * whole session. Outside one there is nothing to undo — leaflet-draw has already committed it.
+ */
 export declare function MapDrawUndo({ className, ...props }: ComponentProps<"button">): import("react").JSX.Element;
 export {};

package/dist/components/features/map/place-autocomplete.d.ts

@@ -66,4 +66,8 @@ export interface PlaceAutocompleteProps extends Omit<PlaceSearchOptions, "query"
     onResultsChange?: (results: PlaceFeature[]) => void;
     strings?: Partial<PlaceAutocompleteStrings>;
 }
+/**
+ * A text field that turns typing into places. It defaults to the free, key-less, rate-limited
+ * Photon geocoder; set `searchUrl` for production.
+ */
 export declare function PlaceAutocomplete({ debounceMs, searchUrl, lang, limit, bbox, lat, lon, zoom, locationBiasScale, className, value, defaultValue, onValueChange, onPlaceSelect, onResultsChange, strings, onFocus, ...props }: PlaceAutocompleteProps): import("react").JSX.Element;

package/dist/components/features/map/place-search.d.ts

@@ -1,7 +1,11 @@
 import { PlaceFeature, PlaceFeatureProperties, UsePlaceSearchOptions } from './place-autocomplete.js';
 /** The address as a person would write it, deduplicated (a town is often its own city and state). */
 export declare function formatAddress(properties: PlaceFeatureProperties): string;
-/** The lookup on its own, for a consumer building their own field. */
+/**
+ * The geocoding search behind PlaceAutocomplete, without the field: debounced and abort-safe —
+ * every keystroke cancels the request before it. For a caller building their own field against
+ * the same debounce, abort and result shape.
+ */
 export declare function usePlaceSearch({ debounceMs, searchUrl, query, lang, limit, bbox, lat, lon, zoom, locationBiasScale, }: UsePlaceSearchOptions): {
     results: PlaceFeature[];
     isLoading: boolean;

package/dist/components/features/media-library/media-library-detail.d.ts

@@ -10,4 +10,8 @@ export interface MediaLibraryDetailPanelProps<TItem> {
     onRemove: () => Promise<boolean>;
     renderDetail?: MediaLibrarySlots<TItem>["renderDetail"];
 }
+/**
+ * The panel for the selected asset. The detail is a COLUMN rather than an overlay: an overlay
+ * would cover the grid the reader is comparing against.
+ */
 export declare function MediaLibraryDetailPanel<TItem>({ item, collections, accessors, strings, onClose, onUpdate, onRemove, renderDetail }: MediaLibraryDetailPanelProps<TItem>): import("react").JSX.Element | null;

package/dist/components/features/media-library/media-library-parts.d.ts

@@ -9,7 +9,7 @@ export interface MediaLibraryEmptyStateProps {
     action?: ReactNode;
     className?: string;
 }
-/** The browser's empty state: bordered and inset, since it stands in for a grid. */
+/** The state with no assets: bordered and inset, since it stands in for a grid. */
 export declare function MediaLibraryEmptyState({ title, description, icon, action, className, }: MediaLibraryEmptyStateProps): import("react").JSX.Element;
 export interface MediaLibraryToolbarProps {
     query: string;
@@ -30,6 +30,7 @@ export interface MediaLibraryToolbarProps {
     end?: ReactNode;
     className?: string;
 }
+/** Search, filter and view controls. A single type filter draws no control. */
 export declare function MediaLibraryToolbar({ query, onQueryChange, type, onTypeChange, typeFilters, collection, onCollectionChange, collections, sort, onSortChange, view, onViewChange, hasFilters, onClearFilters, strings, end, className, }: MediaLibraryToolbarProps): import("react").JSX.Element;
 export interface MediaLibraryCardProps<TItem> {
     item: TItem;
@@ -43,6 +44,7 @@ export interface MediaLibraryCardProps<TItem> {
     onDetails?: () => void;
     className?: string;
 }
+/** One asset in the grid, with its preview, name and selection control. */
 export declare function MediaLibraryCard<TItem>({ item, selected, density, showMeta, accessors, strings, onToggle, onDetails, className, }: MediaLibraryCardProps<TItem>): import("react").JSX.Element;
 export interface MediaLibraryListProps<TItem> {
     items: readonly TItem[];
@@ -53,6 +55,10 @@ export interface MediaLibraryListProps<TItem> {
     onToggle: (id: string) => void;
     onDetails: (id: string) => void;
 }
+/**
+ * The composable compact rows. Like the grid and the table, it uses the same accessors and
+ * selection callbacks.
+ */
 export declare function MediaLibraryList<TItem>({ items, selectedSet, accessors, strings, onToggle, onDetails, }: MediaLibraryListProps<TItem>): import("react").JSX.Element;
 export { MediaLibraryDetailPanel, type MediaLibraryDetailPanelProps } from './media-library-detail.js';
 export interface MediaLibraryUploadPanelProps {
@@ -71,6 +77,10 @@ export interface MediaLibraryUploadPanelProps {
     onCancel: () => void;
     empty?: ReactNode;
 }
+/**
+ * The drop target and queue inside the library, so uploading happens where the assets are
+ * rather than behind a second dialog.
+ */
 export declare function MediaLibraryUploadPanel({ stagedFiles, uploading, uploadOptions, collections, strings, onAddFiles, onRemoveFile, onClear, onOptionsChange, onStart, onCancel, empty, showActions, }: MediaLibraryUploadPanelProps): import("react").JSX.Element;
 export interface MediaLibraryFooterSummaryProps {
     tab: MediaLibraryTab;
@@ -85,8 +95,9 @@ export interface MediaLibraryFooterSummaryProps {
     className?: string;
 }
 /**
- * The footer line: a selection count while browsing, a staged-file tally while uploading.
- * A live region, so keyboard picks inside the grid are announced.
+ * The footer line: what is chosen — a selection count while browsing, a staged-file tally while
+ * uploading. A live region, so keyboard picks inside the grid are announced. Split from the
+ * actions, so a consumer can keep the count and supply their own verbs.
  */
 export declare function MediaLibraryFooterSummary({ tab, selectedIds, selectionMode, stagedFiles, strings, visibleCount, totalCount, onClearSelection, className, }: MediaLibraryFooterSummaryProps): import("react").JSX.Element;
 export interface MediaLibraryFooterActionsProps<TItem> {
@@ -104,9 +115,17 @@ export interface MediaLibraryFooterActionsProps<TItem> {
     onCancelUpload?: () => void;
     className?: string;
 }
+/**
+ * The footer's verbs: what can be done with the selection, or with the staged files. Split from
+ * the summary, so a consumer can keep the count and supply their own verbs.
+ */
 export declare function MediaLibraryFooterActions<TItem>({ tab, selectedIds, selectedItems, stagedFiles, uploading, strings, confirmLabel, cancelLabel, onCancel, onConfirm, onUpload, onCancelUpload, className, }: MediaLibraryFooterActionsProps<TItem>): import("react").JSX.Element;
 export interface MediaLibraryFooterProps<TItem> extends MediaLibraryFooterSummaryProps, Omit<MediaLibraryFooterActionsProps<TItem>, "className"> {
     /** `section` draws the rule and the inset; `bare` leaves both to a surrounding shell. */
     chrome?: "section" | "bare";
 }
+/**
+ * The selection bar: what is chosen, and what can be done with it — the summary and the actions
+ * together.
+ */
 export declare function MediaLibraryFooter<TItem>({ tab, selectedItems, selectedIds, selectionMode, stagedFiles, uploading, strings, visibleCount, totalCount, confirmLabel, cancelLabel, onCancel, onConfirm, onClearSelection, onUpload, onCancelUpload, chrome, className, }: MediaLibraryFooterProps<TItem>): import("react").JSX.Element;

package/dist/components/features/media-library/media-library-table.d.ts

@@ -4,5 +4,8 @@ export interface MediaLibraryTableProps<TItem> extends MediaLibraryListProps<TIt
     className?: string;
     collections?: readonly MediaLibraryCollectionOption[];
 }
-/** A metadata table for inspecting assets; selection and details remain separate controls. */
+/**
+ * The composable metadata table for inspecting assets; selection and details remain separate
+ * controls. Like the grid and the list, it uses the same accessors and selection callbacks.
+ */
 export declare function MediaLibraryTable<TItem>({ items, selectedSet, accessors, strings, onToggle, onDetails, className, collections }: MediaLibraryTableProps<TItem>): import("react").JSX.Element;

package/dist/components/features/media-library/media-library-views.d.ts

@@ -8,6 +8,10 @@ export interface MediaLibraryGridProps<TItem> extends MediaLibraryListProps<TIte
     renderItem?: MediaLibrarySlots<TItem>["renderItem"];
     className?: string;
 }
+/**
+ * The composable visual grid. Like the list and the table, it uses the same accessors and
+ * selection callbacks.
+ */
 export declare function MediaLibraryGrid<TItem>({ items, selectedSet, accessors, strings, onToggle, onDetails, density, selectionMode, showMeta, renderItem, className }: MediaLibraryGridProps<TItem>): import("react").JSX.Element;
 export interface MediaLibrarySelectionBarProps {
     visibleCount: number;
@@ -20,4 +24,8 @@ export interface MediaLibrarySelectionBarProps {
     strings?: Partial<MediaLibraryStrings>;
     className?: string;
 }
+/**
+ * Result counts, pending announcements, and selection of the visible results. Selections the
+ * current filters hide are preserved.
+ */
 export declare function MediaLibrarySelectionBar({ visibleCount, totalCount, selectedVisibleCount, onSelectVisible, onDeselectVisible, status, disabled, strings, className }: MediaLibrarySelectionBarProps): import("react").JSX.Element;

package/dist/components/features/media-library/media-library.d.ts

@@ -1,4 +1,8 @@
 import { MediaLibraryDialogProps, MediaLibraryItem, MediaLibraryProps } from './media-library.types.js';
+/**
+ * The asset browser, as a panel. The detail panel is a column beside the grid, not an overlay,
+ * so several assets can be edited in a row.
+ */
 export declare function MediaLibrary<TItem = MediaLibraryItem>({ title, description, confirmLabel, cancelLabel, density, showMeta, allowUpload, typeFilters, confirmOnSelect, onConfirm, onCancel, onClose, bulkActions, strings, slots, className, collections, selectionMode, ...options }: MediaLibraryProps<TItem>): import("react").JSX.Element;
 /** The same library in a modal, for picking assets from elsewhere on a page. */
 export declare function MediaLibraryDialog<TItem = MediaLibraryItem>({ open, onOpenChange, trigger, dialogTitle, dialogDescription, dialogClassName, contentClassName, closeOnEscape, closeOnBackdropClick, onClose, strings, ...props }: MediaLibraryDialogProps<TItem>): import("react").JSX.Element;