@factorialco/f0-react 1.294.0 → 1.295.0

package/dist/f0.d.ts

@@ -1319,7 +1319,7 @@ export declare type DataSourceDefinition<R extends RecordType = RecordType, Filt
     /** Selectable items value under the checkbox column (undefined if not selectable) */
     selectable?: (item: R) => string | number | undefined;
     /** Default selected items */
-    defaultSelectedItems?: SelectedItemsState;
+    defaultSelectedItems?: SelectedItemsState<R>;
     /***** GROUPING ***************************************************/
     /** Grouping configuration */
     grouping?: Grouping;
@@ -1595,6 +1595,7 @@ export declare const defaultTranslations: {
         readonly selected: {
             readonly singular: "Selected";
             readonly plural: "Selected";
+            readonly all: "All selected";
         };
     };
     readonly filters: {
@@ -2394,6 +2395,26 @@ export declare const F0Select: <T extends string = string, R = unknown>(props: F
     ref?: React.Ref<HTMLButtonElement>;
 }) => React.ReactElement;
 
+/**
+ * Base props shared across all F0Select variants
+ */
+declare type F0SelectBaseProps<T extends string, R = unknown> = {
+    onChangeSelectedOption?: (option: F0SelectItemObject<T, ResolvedRecordType<R>> | undefined, checked: boolean) => void;
+    children?: React.ReactNode;
+    open?: boolean;
+    showSearchBox?: boolean;
+    searchBoxPlaceholder?: string;
+    onSearchChange?: (value: string) => void;
+    searchValue?: string;
+    onOpenChange?: (open: boolean) => void;
+    searchEmptyMessage?: string;
+    className?: string;
+    selectContentClassName?: string;
+    actions?: Action_2[];
+    /** Container element to render the portal content into */
+    portalContainer?: HTMLElement | null;
+};
+
 export declare type F0SelectItemObject<T, R = unknown> = {
     type?: "item";
     value: T;
@@ -2413,42 +2434,43 @@ export declare type F0SelectItemProps<T, R = unknown> = F0SelectItemObject<T, R>
 /**
  * Select component for choosing from a list of options.
  *
- * @template T - The type of the emitted  value
+ * @template T - The type of the emitted value
  * @template R - The type of the record/item data (used with data source)
- *
  */
-export declare type F0SelectProps<T extends string, R = unknown> = {
-    onChangeSelectedOption?: (option: F0SelectItemObject<T, ResolvedRecordType<R>> | undefined, checked: boolean) => void;
-    children?: React.ReactNode;
-    open?: boolean;
-    showSearchBox?: boolean;
-    searchBoxPlaceholder?: string;
-    onSearchChange?: (value: string) => void;
-    searchValue?: string;
-    onOpenChange?: (open: boolean) => void;
-    searchEmptyMessage?: string;
-    className?: string;
-    selectContentClassName?: string;
-    actions?: Action_2[];
-    portalContainer?: HTMLElement | null;
-} & ({
+export declare type F0SelectProps<T extends string, R = unknown> = F0SelectBaseProps<T, R> & // Single select not clearable
+({
     clearable?: false;
     multiple?: false;
     value?: T;
     defaultItem?: F0SelectItemObject<T, ResolvedRecordType<R>>;
     onChange?: (value: T, originalItem?: ResolvedRecordType<R> | undefined, option?: F0SelectItemObject<T, ResolvedRecordType<R>>) => void;
+    /** Callback for selection changes - provides full selection state for advanced use cases (e.g., "Select All" with exclusions) */
+    onSelectItems?: never;
 } | {
     clearable: true;
     multiple?: false;
     value?: T;
     defaultItem?: F0SelectItemObject<T, ResolvedRecordType<R>>;
     onChange?: (value: T, originalItem?: ResolvedRecordType<R> | undefined, option?: F0SelectItemObject<T, ResolvedRecordType<R>>) => void;
+    onSelectItems?: never;
 } | {
     multiple: true;
     clearable?: boolean;
     value?: T[];
     defaultItem?: F0SelectItemObject<T, ResolvedRecordType<R>>[];
     onChange?: (value: T[], originalItems: ResolvedRecordType<R>[], options: F0SelectItemObject<T, ResolvedRecordType<R>>[]) => void;
+    /**
+     * Callback for selection changes - provides full selection state including:
+     * - `status.allSelected`: true if "Select All" was used, "indeterminate" if some items deselected after Select All
+     * - `status.items`: Map of all items with their checked state
+     * - `filters`: Current applied filters
+     * - `selectedCount`: Total number of selected items
+     *
+     * Use this for "chunked" selection mode where you need to track:
+     * - When allSelected is true/indeterminate: excluded items are those with checked=false
+     * - When allSelected is false: included items are those with checked=true
+     */
+    onSelectItems?: OnSelectItemsCallback<ResolvedRecordType<R>, FiltersDefinition>;
 }) & ({
     source: DataSourceDefinition<ResolvedRecordType<R>, FiltersDefinition, SortingsDefinition, GroupingDefinition<ResolvedRecordType<R>>>;
     mapOptions: (item: ResolvedRecordType<R>) => F0SelectItemProps<T, ResolvedRecordType<R>>;
@@ -3707,10 +3729,13 @@ export declare type SelectedItems<T> = ReadonlyArray<T>;
 
 export declare type SelectedItemsDetailedStatus<R extends RecordType, Filters extends FiltersDefinition> = {
     allSelected: boolean | "indeterminate";
+    /** Status of items that have been loaded. Items not yet loaded won't appear here. */
     itemsStatus: ReadonlyArray<{
         item: R;
         checked: boolean;
     }>;
+    /** All selected item IDs, including those not yet loaded */
+    selectedIds: ReadonlyArray<SelectionId>;
     groupsStatus: Record<string, boolean>;
     filters: FiltersState<Filters>;
     selectedCount: number;
@@ -3719,16 +3744,45 @@ export declare type SelectedItemsDetailedStatus<R extends RecordType, Filters ex
 /**
  * Represents the selected items by id
  */
-export declare type SelectedItemsState = {
-    allSelected?: boolean | "indeterminate";
-    items?: ReadonlyArray<{
-        id: string;
-        checked: boolean;
-    }>;
-    groups?: ReadonlyArray<{
-        groupId: string;
+export declare type SelectedItemsState<R extends RecordType> = {
+    allSelected: boolean | "indeterminate";
+    items: Map<SelectedItemState<R>["id"], SelectedItemState<R>>;
+    groups: Map<SelectedState["id"], SelectedState>;
+};
+
+export declare type SelectedItemState<R extends RecordType> = SelectedState & {
+    item?: WithGroupId<R>;
+};
+
+export declare type SelectedState = {
+    id: SelectionId;
+    checked: boolean;
+};
+
+export declare type SelectionId = number | string;
+
+export declare type SelectionMeta<R extends RecordType> = {
+    selectedItemsCount: number;
+    totalKnownItemsCount: number;
+    checkedItems: ReadonlyArray<R>;
+    uncheckedItems: ReadonlyArray<R>;
+};
+
+export declare type SelectionStatus<R extends RecordType, Filters extends FiltersDefinition> = {
+    allChecked: boolean | "indeterminate";
+    /** Status of items that have been loaded. Items not yet loaded won't appear here. */
+    itemsStatus: ReadonlyArray<{
+        item: R;
         checked: boolean;
     }>;
+    /** All selected item IDs, including those not yet loaded */
+    selectedIds: ReadonlyArray<SelectionId>;
+    checkedItems: ReadonlyArray<R>;
+    uncheckedItems: ReadonlyArray<R>;
+    groupsStatus: Record<string, boolean>;
+    filters: FiltersState<Filters>;
+    selectedCount: number;
+    totalKnownItemsCount: number;
 };
 
 export declare const selectSizes: readonly ["sm", "md"];
@@ -4399,20 +4453,55 @@ export declare const usePrivacyMode: () => {
 
 export declare const useReducedMotion: () => boolean;
 
-export declare type UseSelectable<R extends RecordType> = {
+export declare function useSelectable<R extends RecordType, Filters extends FiltersDefinition, Sortings extends SortingsDefinition, Grouping extends GroupingDefinition<R>>({ data, paginationInfo, source, selectionMode, selectedState, onSelectItems, }: UseSelectableProps<R, Filters, Sortings, Grouping>): UseSelectableReturn<R, Filters>;
+
+export declare type UseSelectableProps<R extends RecordType, Filters extends FiltersDefinition, Sortings extends SortingsDefinition, Grouping extends GroupingDefinition<R>> = {
+    data: Data<R>;
+    paginationInfo: PaginationInfo | null;
+    source: DataSourceDefinition<R, Filters, Sortings, Grouping>;
+    onSelectItems?: OnSelectItemsCallback<R, Filters>;
+    selectionMode?: "multi" | "single";
+    selectedState?: SelectedItemsState<R>;
+};
+
+export declare type UseSelectableReturn<R extends RecordType, Filters extends FiltersDefinition> = {
     isAllSelected: boolean;
-    selectedItems: Map<number | string, R>;
-    selectedGroups: Map<string, GroupRecord<R>>;
+    selectedItems: Map<SelectionId, R>;
+    selectedGroups: Map<SelectionId, GroupRecord<R>>;
     isPartiallySelected: boolean;
-    handleSelectItemChange: (item: R, checked: boolean) => void;
-    handleSelectAll: (checked: boolean) => void;
-    handleSelectGroupChange: (group: GroupRecord<R>, checked: boolean) => void;
-    groupAllSelectedStatus: Record<string, AllSelectionStatus>;
+    groupAllSelectedStatus: Record<SelectionId, AllSelectionStatus>;
     allSelectedStatus: AllSelectionStatus;
+    selectionStatus: SelectionStatus<R, Filters>;
+    /**
+     * The current selected state
+     */
+    selectedState: SelectedItemsState<R>;
+    /**
+     * The meta data about the selection
+     */
+    selectionMeta: SelectionMeta<R>;
+    /**
+     * Clears the selection
+     */
+    clearSelection: () => void;
+    /**
+     * Handles the change of the selected item.
+     * Accepts either SelectionId(s) or the item itself (R).
+     * When passing an item, the ID will be extracted using source.selectable.
+     */
+    handleSelectItemChange: (itemOrId: R | SelectionId | readonly SelectionId[], checked: boolean) => void;
+    /**
+     * Handles the change of the selected all items
+     */
+    handleSelectAll: (checked: boolean) => void;
+    /**
+     * Handles the change of the selected group.
+     * Accepts either SelectionId(s) or a GroupRecord.
+     * When passing a GroupRecord, the key will be used as the ID.
+     */
+    handleSelectGroupChange: (groupOrId: GroupRecord<R> | SelectionId | readonly SelectionId[], checked: boolean) => void;
 };
 
-export declare function useSelectable<R extends RecordType, Filters extends FiltersDefinition, Sortings extends SortingsDefinition, Grouping extends GroupingDefinition<R>>(data: Data<R>, paginationInfo: PaginationInfo | null, source: DataSourceDefinition<R, Filters, Sortings, Grouping>, onSelectItems: OnSelectItemsCallback<R, Filters> | undefined, defaultSelectedItems?: SelectedItemsState | undefined): UseSelectable<R>;
-
 export declare const useXRay: () => {
     enabled: boolean;
     filter: ComponentTypes[];
@@ -4527,31 +4616,6 @@ declare global {
 }
 
 
-declare module "gridstack" {
-    interface GridStackWidget {
-        id?: string;
-        allowedSizes?: Array<{
-            w: number;
-            h: number;
-        }>;
-        renderFn?: () => React.ReactElement | null;
-        meta?: Record<string, unknown>;
-    }
-    interface GridStackNode {
-        id?: string;
-        w?: number;
-        h?: number;
-        x?: number;
-        y?: number;
-        allowedSizes?: Array<{
-            w: number;
-            h: number;
-        }>;
-        renderFn?: () => React.ReactElement | null;
-    }
-}
-
-
 declare module "@tiptap/core" {
     interface Commands<ReturnType> {
         aiBlock: {
@@ -4579,6 +4643,31 @@ declare module "@tiptap/core" {
 }
 
 
+declare module "gridstack" {
+    interface GridStackWidget {
+        id?: string;
+        allowedSizes?: Array<{
+            w: number;
+            h: number;
+        }>;
+        renderFn?: () => React.ReactElement | null;
+        meta?: Record<string, unknown>;
+    }
+    interface GridStackNode {
+        id?: string;
+        w?: number;
+        h?: number;
+        x?: number;
+        y?: number;
+        allowedSizes?: Array<{
+            w: number;
+            h: number;
+        }>;
+        renderFn?: () => React.ReactElement | null;
+    }
+}
+
+
 declare namespace Calendar {
     var displayName: string;
 }

package/dist/f0.js

@@ -1,5 +1,5 @@
-import { S as Ge, a as Kt, f as Ce, L as J, b as Vt, A as qt, i as ae, c as tt, d as it, E as Xt, g as he, e as Yt, h as Jt, C as Zt, j as Qt, k as V, l as st, u as ei, G as ti, m as ii, n as $e, o as si, p as rt, q as ri, B as nt, X as ot, Y as ze, r as ni, s as at, t as oi, v as ai, w as li, x as hi, y as di, z as ci, D as ui, F as fi, H as Ue, I as gi, J as Z, K as Ne, M as pi, N as mi, O as vi, P as lt, Q as L, R as F, T as yi, U as bi, V as xi, W as _i, Z as wi, _ as Ei, $ as Ci, a0 as ht, a1 as Ni, a2 as de, a3 as dt, a4 as ct, a5 as Ri, a6 as ut, a7 as ft, a8 as gt, a9 as pt, aa as zi, ab as Di, ac as mt, ad as Pi, ae as Si, af as vt, ag as ki, ah as yt, ai as Oi, aj as Ai, ak as Ti, al as Li, am as Mi, an as Hi, ao as Bi, ap as Fi, aq as bt, ar as q, as as xt, at as Ii, au as Wi, av as je, aw as Gi, ax as _t, ay as $i, az as Ui, aA as ji, aB as Ki, aC as Vi, aD as qi, aE as Xi, aF as Yi, aG as Ji, aH as Zi, aI as Qi, aJ as es } from "./hooks-B9lijBjS.js";
-import { bc as Fr, bp as Ir, by as Wr, aK as Gr, aL as $r, aM as Ur, aN as jr, aO as Kr, aP as Vr, aQ as qr, aR as Xr, aT as Yr, aU as Jr, aV as Zr, aW as Qr, aX as en, aY as tn, aZ as sn, bu as rn, a$ as nn, b0 as on, b3 as an, b4 as ln, b5 as hn, b6 as dn, b9 as cn, ba as un, bb as fn, be as gn, b2 as pn, bd as mn, b8 as vn, bv as yn, bo as bn, bj as xn, bm as _n, bi as wn, bz as En, bh as Cn, bg as Nn, aS as Rn, a_ as zn, b1 as Dn, b7 as Pn, bf as Sn, bk as kn, bq as On, br as An, bs as Tn, bA as Ln, bl as Mn, bt as Hn, bx as Bn, bn as Fn, bw as In } from "./hooks-B9lijBjS.js";
+import { S as Ge, a as Kt, f as Ce, L as J, b as Vt, A as qt, i as ae, c as tt, d as it, E as Xt, g as he, e as Yt, h as Jt, C as Zt, j as Qt, k as V, l as st, u as ei, G as ti, m as ii, n as $e, o as si, p as rt, q as ri, B as nt, X as ot, Y as ze, r as ni, s as at, t as oi, v as ai, w as li, x as hi, y as di, z as ci, D as ui, F as fi, H as Ue, I as gi, J as Z, K as Ne, M as pi, N as mi, O as vi, P as lt, Q as L, R as F, T as yi, U as bi, V as xi, W as _i, Z as wi, _ as Ei, $ as Ci, a0 as ht, a1 as Ni, a2 as de, a3 as dt, a4 as ct, a5 as Ri, a6 as ut, a7 as ft, a8 as gt, a9 as pt, aa as zi, ab as Di, ac as mt, ad as Pi, ae as Si, af as vt, ag as ki, ah as yt, ai as Oi, aj as Ai, ak as Ti, al as Li, am as Mi, an as Hi, ao as Bi, ap as Fi, aq as bt, ar as q, as as xt, at as Ii, au as Wi, av as je, aw as Gi, ax as _t, ay as $i, az as Ui, aA as ji, aB as Ki, aC as Vi, aD as qi, aE as Xi, aF as Yi, aG as Ji, aH as Zi, aI as Qi, aJ as es } from "./hooks-BmarskJY.js";
+import { bc as Fr, bp as Ir, by as Wr, aK as Gr, aL as $r, aM as Ur, aN as jr, aO as Kr, aP as Vr, aQ as qr, aR as Xr, aT as Yr, aU as Jr, aV as Zr, aW as Qr, aX as en, aY as tn, aZ as sn, bu as rn, a$ as nn, b0 as on, b3 as an, b4 as ln, b5 as hn, b6 as dn, b9 as cn, ba as un, bb as fn, be as gn, b2 as pn, bd as mn, b8 as vn, bv as yn, bo as bn, bj as xn, bm as _n, bi as wn, bz as En, bh as Cn, bg as Nn, aS as Rn, a_ as zn, b1 as Dn, b7 as Pn, bf as Sn, bk as kn, bq as On, br as An, bs as Tn, bA as Ln, bl as Mn, bt as Hn, bx as Bn, bn as Fn, bw as In } from "./hooks-BmarskJY.js";
 import { jsx as g, jsxs as R, Fragment as xe } from "react/jsx-runtime";
 import * as ke from "react";
 import P, { PureComponent as ts, useState as M, forwardRef as U, createElement as Ke, useRef as Q, useImperativeHandle as wt, Children as is, createContext as _e, useContext as Et, useCallback as K, useEffect as ce, useLayoutEffect as Ve, useMemo as Ct } from "react";