@factorialco/f0-react 7.22.0 → 7.24.0

package/dist/f0.d.ts

@@ -3563,6 +3563,7 @@ declare type CollectionVisualizations<Record extends RecordType, Filters extends
     card: VisualizacionTypeDefinition<CardCollectionProps<Record, Filters, Sortings, Summaries, ItemActions, NavigationFilters, Grouping>>;
     kanban: VisualizacionTypeDefinition<KanbanCollectionProps<Record, Filters, Sortings, Summaries, ItemActions, NavigationFilters, Grouping>>;
     graph: VisualizacionTypeDefinition<GraphCollectionProps<Record, Filters, Sortings, Summaries, ItemActions, NavigationFilters, Grouping>, GraphVisualizationSettings>;
+    map: VisualizacionTypeDefinition<MapCollectionProps<Record, Filters, Sortings, Summaries, ItemActions, NavigationFilters, Grouping>>;
 };
 
 declare const collectionVisualizations: CollectionVisualizations<RecordType, FiltersDefinition, SortingsDefinition, SummariesDefinition, ItemActionsDefinition<RecordType>, NavigationFiltersDefinition, GroupingDefinition<RecordType>>;
@@ -5378,6 +5379,7 @@ export declare const defaultTranslations: {
             readonly list: "List";
             readonly kanban: "Kanban";
             readonly graph: "Graph";
+            readonly map: "Map";
             readonly pagination: {
                 readonly of: "of";
             };
@@ -5385,6 +5387,11 @@ export declare const defaultTranslations: {
             readonly reset: "Reset to default";
             readonly viewSelectorLabel: "Select view";
         };
+        readonly map: {
+            readonly notOnMap: "Not on map";
+            readonly onMap: "On map";
+            readonly notOnMapCount: "{{count}} not on map";
+        };
         readonly table: {
             readonly seeMoreChildren: "See more";
             readonly settings: {
@@ -6277,11 +6284,15 @@ export declare const defaultTranslations: {
         readonly loadError: "Couldn't load the map.";
         readonly retry: "Retry";
         readonly currentLocation: "Your location";
+        readonly panel: "Map panel";
+        readonly detailPanel: "Map detail panel";
         readonly controls: {
             readonly zoomIn: "Zoom in";
             readonly zoomOut: "Zoom out";
             readonly fit: "Fit to markers";
             readonly locate: "My location";
+            readonly showPanel: "Show panel";
+            readonly hidePanel: "Hide panel";
         };
     };
     readonly wizard: {
@@ -6675,6 +6686,10 @@ declare type DrawerSize = (typeof drawerSizes)[number];
 
 declare const drawerSizes: readonly ["md"];
 
+declare type DropdownContentVariant = (typeof dropdownContentVariants)[number];
+
+declare const dropdownContentVariants: readonly ["expanded", "reduced"];
+
 export declare type DropdownItem = DropdownItemObject | DropdownItemSeparator | DropdownItemLabel;
 
 declare type DropdownItemLabel = {
@@ -8999,6 +9014,14 @@ declare type F0ButtonDropdownDropdownProps<T = string> = F0ButtonDropdownBasePro
      * @param item The item that was clicked.
      */
     onClick: (value: T, item: ButtonDropdownItem<T>) => void;
+    /**
+     * Caps the width of the dropdown menu.
+     * - "expanded": (default) sizes to content, same as today.
+     * - "reduced": caps the menu at 300px, e.g. when an item's
+     *   `description` is long enough to otherwise stretch the menu.
+     * @default "expanded"
+     */
+    menuVariant?: DropdownContentVariant;
 };
 
 export declare type F0ButtonDropdownProps<T = string> = F0ButtonDropdownSplitProps<T> | F0ButtonDropdownDropdownProps<T>;
@@ -12456,8 +12479,68 @@ declare type F0LocationSuggestion = {
     description?: string;
 };
 
+/**
+ * The data each semantic variant needs. Appearance is fixed by the variant:
+ *  - `default`: a plain pin, no icon or avatar (the generic marker).
+ *  - `workplace`: a building glyph on a fixed brand hue (all sites match).
+ *  - `employee` / `company`: an avatar whose color is its own identity color
+ *    (grey when a photo replaces the colored chip).
+ *  - `stop`: a route stop - a single letter (A, B, C...) on the same fixed
+ *    hue as the route/arc lines it punctuates.
+ */
+declare type F0MapMarkerVariantProps = {
+    variant: "default";
+} | {
+    variant: "workplace";
+} | {
+    variant: "employee";
+    firstName: string;
+    lastName: string;
+    src?: string;
+} | {
+    variant: "company";
+    name: string;
+    src?: string;
+} | {
+    variant: "stop";
+    letter: string;
+};
+
+/**
+ * Map projection. `"globe"` renders the world as a 3D sphere (adaptive: it
+ * eases into a flat mercator view as you zoom in).
+ */
+declare type F0MapProjection = "mercator" | "globe";
+
 declare type F0MapProvider = "maplibre" | "google";
 
+/** Initial camera position for the map. */
+declare interface F0MapViewport {
+    /** `[longitude, latitude]`. */
+    center: [number, number];
+    /** Zoom level (`0` world, higher = closer). Defaults to a city-level view. */
+    zoom?: number;
+}
+
+/**
+ * Region of the map (in screen px) covered by external chrome - typically a
+ * side panel the consumer opens over it. Every camera move (fit, focus, reveal)
+ * shifts its target so the point lands centred in the *free* area beside the
+ * panel instead of behind it. The side is encoded by which key is set: a
+ * right-hand panel sets `right`, a left-hand one or RTL sets `left`.
+ *
+ * The consumer supplies the value - `F0Map` has no notion of the panel. For a
+ * fixed-width drawer pass its width while it is open (e.g. `{ right: 480 }`)
+ * and `undefined` / `{}` while it is closed. Omitted or `0` on every side
+ * behaves exactly as if there were no inset.
+ */
+declare interface F0MapViewportInset {
+    top?: number;
+    right?: number;
+    bottom?: number;
+    left?: number;
+}
+
 export declare type F0Message = {
     id: string;
     role: "user" | "assistant" | "system" | "tool";
@@ -16231,12 +16314,111 @@ export declare type LockedSectionNotice = {
     description: string;
 };
 
+declare type MapCollectionProps<Record extends RecordType, Filters extends FiltersDefinition, Sortings extends SortingsDefinition, Summaries extends SummariesDefinition, ItemActions extends ItemActionsDefinition<Record>, NavigationFilters extends NavigationFiltersDefinition, Grouping extends GroupingDefinition<Record>> = CollectionProps<Record, Filters, Sortings, Summaries, ItemActions, NavigationFilters, Grouping, MapVisualizationOptions<Record, Filters, Sortings>>;
+
 /** A leaf module: the registry and `F0Provider` both need the shape. */
 declare interface MapProviderConfig {
     /** Required by `google`; `maplibre`'s tiles are keyless. */
     apiKey?: string;
 }
 
+/** Selection handles handed to the panels, so their content can drive the map. */
+declare type MapSidebarApi<R extends RecordType> = {
+    /** Select a record (or clear with `null`), flying to its marker if it has one. */
+    select: (record: R | null) => void;
+    selectedRecordId: string | null;
+    /**
+     * What the map did with a record: `"placed"`, `"unplaced"` (no reason
+     * given), or the `MapUnplaced` kind. Per record, so it also answers in the
+     * search's flat list.
+     */
+    placement: (record: R) => "placed" | "unplaced" | MapUnplaced["kind"];
+};
+
+/**
+ * Why a record has no position, returned from `coordinates` instead of one.
+ * `incomplete`: it should have a location and doesn't (an unfilled or
+ * ungeocodable address) - the case somebody can fix.
+ */
+declare type MapUnplaced = {
+    kind: "incomplete";
+};
+
+/**
+ * Options for the map visualization: records projected onto coordinates. Only
+ * reading a record's position is required; how markers look and behave is
+ * `F0Map`'s concern.
+ */
+declare type MapVisualizationOptions<R extends RecordType, _Filters extends FiltersDefinition, _Sortings extends SortingsDefinition> = {
+    /**
+     * A record's `[longitude, latitude]`. `null` or a `MapUnplaced` draws no
+     * marker, and the record is listed under "Not on map" instead. No geocoding
+     * happens here: resolve coordinates server-side.
+     */
+    coordinates: (record: R) => [number, number] | null | MapUnplaced;
+    /** Label beside the marker. Omitted means an unlabelled pin. */
+    label?: (record: R) => string;
+    /** Marker variant per record. Defaults to `default`. */
+    marker?: (record: R) => F0MapMarkerVariantProps;
+    /** A record's id. Defaults to `String(record.id)`, like the graph view. */
+    getRecordId?: (record: R) => string;
+    /**
+     * Controlled selection, `null` for none. Pass it whenever something outside
+     * the map can end the selection, like closing the panel `onSelect` opened.
+     */
+    selectedRecordId?: string | null;
+    /**
+     * Fired when the selection changes: a marker click, a reveal, a panel row,
+     * or `null` when it clears. If it opens your own chrome over the map, report
+     * the region it covers through `viewportInset`.
+     */
+    onSelect?: (record: R | null) => void;
+    /**
+     * Flies to a record and selects it, e.g. from an external search. Pair it
+     * with the collection's `searchSelectionNonce` so a repeat pick flies again.
+     */
+    revealRecordId?: string | null;
+    /** Region covered by your own chrome. The map's own panels are folded in. */
+    viewportInset?: F0MapViewportInset;
+    /** Initial camera. Defaults to framing every marker. */
+    initialViewport?: F0MapViewport;
+    /** Show the navigation controls (locate / fit / zoom). Defaults to `true`. */
+    showControls?: boolean;
+    /** Fired with the side panel's new open state. */
+    onSidebarToggle?: (expanded: boolean) => void;
+    /** Map projection. Defaults to `"mercator"`. */
+    projection?: F0MapProjection;
+    /**
+     * Rendering engine. Defaults to the one the app sets on `F0Provider`, so a
+     * product that configures Google gets it here too; set it only to override
+     * that for this view.
+     */
+    provider?: F0MapProvider;
+    /**
+     * Records to request in the one page the map loads, capped at the map's
+     * recommended marker ceiling.
+     */
+    markerLimit?: number;
+    /** Accessible label for the map region. */
+    ariaLabel?: string;
+    /**
+     * Rows of the side panel, for the records of one section ("Not on map",
+     * then "On map") or for the matches of the panel's search. They are the
+     * records the map is drawing, from the same load. Return rows only: the
+     * panel owns the scrolling. `select` drives the same selection a marker
+     * click does.
+     */
+    sidebar?: (records: R[], api: MapSidebarApi<R>) => ReactNode;
+    /**
+     * Text the panel's search matches a record against. Given it, the panel's
+     * header offers a search over the records the panel holds; the toolbar's
+     * search still narrows the whole view.
+     */
+    sidebarSearchText?: (record: R) => string;
+    /** Detail panel for the selected record, beside the side panel. */
+    detail?: (record: R, api: MapSidebarApi<R>) => ReactNode;
+};
+
 /** Margin tokens (spacing + auto for centering) */
 export declare type MarginToken = SpacingToken | "auto";