@rowsncolumns/spreadsheet 10.2.68

package/dist/esm/hooks/use-filter.d.ts

@@ -0,0 +1,46 @@
+import { type CellInterface, type CellPosition, type ScrollCoords } from "@rowsncolumns/grid";
+import type { ReactElement } from "react";
+import type { CanvasGridProps, SpreadsheetTheme } from "../components/canvas-grid/typings";
+import type { FilterBoxBaseProps } from "../components/filter-box";
+import type { CellFormat, FilterView, TableView } from "../types";
+export type UseFilterProps = {
+    scale?: number;
+    sheetId: number;
+    theme: SpreadsheetTheme;
+    getActualCellCoords(coords: CellInterface): CellInterface | undefined;
+    getScrollPosition(): ScrollCoords | undefined;
+    getCellOffsetFromCoords(coords: CellInterface): CellPosition | undefined;
+    getFormattedValue(sheetId: number, rowIndex: number, columnIndex: number): string | undefined;
+    /**
+     * Optional — when provided, the filter box auto-populates its
+     * "Filter by color" picker with distinct cell + font colors present
+     * in the column. Icons come from `conditionalFormatByCell` instead
+     * (CF overlays don't ride along on the effective format).
+     */
+    getEffectiveFormat?(sheetId: number, rowIndex: number, columnIndex: number): CellFormat | undefined | null;
+    /**
+     * Optional — keyed by `cellIdentifier(rowIndex, columnIndex)`. When
+     * provided, distinct CF iconSet/iconId triples present in the column
+     * power the "Filter by icon" picker. Pass the Map returned by
+     * `useConditionalFormatting`.
+     */
+    conditionalFormatByCell?: Map<string, CellFormat | undefined>;
+    getFilterComponent(props: FilterBoxBaseProps): ReactElement | null;
+    isFrozenRow(rowIndex: number): boolean;
+    isFrozenColumn(columnIndex: number): boolean;
+    isHiddenRowByFilter(rowIndex: number): boolean;
+    onSortTable: CanvasGridProps["onSortTable"];
+    onFilterTable: CanvasGridProps["onFilterTable"];
+    onInsertTableColumn: CanvasGridProps["onInsertTableColumn"];
+    onDeleteTableColumn: CanvasGridProps["onDeleteTableColumn"];
+    getFilterValues?: CanvasGridProps["getFilterValues"];
+    getFilterColors?: CanvasGridProps["getFilterColors"];
+    basicFilter?: FilterView | null;
+    tables?: TableView[] | null;
+};
+export declare const useFilter: ({ scale, sheetId, theme, getActualCellCoords, getScrollPosition, getCellOffsetFromCoords, getFormattedValue, getEffectiveFormat, conditionalFormatByCell, getFilterComponent, isFrozenRow, isFrozenColumn, isHiddenRowByFilter, onSortTable, onFilterTable, onInsertTableColumn, onDeleteTableColumn, getFilterValues, getFilterColors, basicFilter, tables, }: UseFilterProps) => {
+    showFilter: (cell: CellInterface, filterOrTable: FilterView | TableView) => void;
+    hideFilter: () => void;
+    filterComponent: ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | null;
+};
+//# sourceMappingURL=use-filter.d.ts.map

package/dist/esm/hooks/use-filter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-filter.d.ts","sourceRoot":"","sources":["../../../hooks/use-filter.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,KAAK,YAAY,EAClB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,OAAO,CAAC;AAG1C,OAAO,KAAK,EACV,eAAe,EACf,gBAAgB,EACjB,MAAM,mCAAmC,CAAC;AAC3C,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAEnE,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAGlE,MAAM,MAAM,cAAc,GAAG;IAC3B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,gBAAgB,CAAC;IACxB,mBAAmB,CAAC,MAAM,EAAE,aAAa,GAAG,aAAa,GAAG,SAAS,CAAC;IACtE,iBAAiB,IAAI,YAAY,GAAG,SAAS,CAAC;IAC9C,uBAAuB,CAAC,MAAM,EAAE,aAAa,GAAG,YAAY,GAAG,SAAS,CAAC;IACzE,iBAAiB,CACf,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,GAClB,MAAM,GAAG,SAAS,CAAC;IACtB;;;;;OAKG;IACH,kBAAkB,CAAC,CACjB,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,GAClB,UAAU,GAAG,SAAS,GAAG,IAAI,CAAC;IACjC;;;;;OAKG;IACH,uBAAuB,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,GAAG,SAAS,CAAC,CAAC;IAC9D,kBAAkB,CAAC,KAAK,EAAE,kBAAkB,GAAG,YAAY,GAAG,IAAI,CAAC;IACnE,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;IACvC,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC;IAC7C,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;IAC/C,WAAW,EAAE,eAAe,CAAC,aAAa,CAAC,CAAC;IAC5C,aAAa,EAAE,eAAe,CAAC,eAAe,CAAC,CAAC;IAChD,mBAAmB,EAAE,eAAe,CAAC,qBAAqB,CAAC,CAAC;IAC5D,mBAAmB,EAAE,eAAe,CAAC,qBAAqB,CAAC,CAAC;IAG5D,eAAe,CAAC,EAAE,eAAe,CAAC,iBAAiB,CAAC,CAAC;IAIrD,eAAe,CAAC,EAAE,eAAe,CAAC,iBAAiB,CAAC,CAAC;IAIrD,WAAW,CAAC,EAAE,UAAU,GAAG,IAAI,CAAC;IAChC,MAAM,CAAC,EAAE,SAAS,EAAE,GAAG,IAAI,CAAC;CAC7B,CAAC;AAQF,eAAO,MAAM,SAAS,GAAI,gWAsBvB,cAAc;uBAyBN,aAAa,iBAAiB,UAAU,GAAG,SAAS;;;CAgN9D,CAAC"}

package/dist/esm/hooks/use-filter.js

@@ -0,0 +1,184 @@
+import { cellIdentifier, } from "@rowsncolumns/grid";
+import { isNil } from "@rowsncolumns/utils";
+import { useCallback, useMemo, useState } from "react";
+import { BLANK_LABEL, FILTER_ICON_WIDTH } from "../config";
+import { useColumnColorIcons } from "./use-column-color-icons";
+// For sorting
+const collator = new Intl.Collator("en", {
+    numeric: true,
+    sensitivity: "base",
+});
+export const useFilter = ({ scale = 1, sheetId, theme, getActualCellCoords, getScrollPosition, getCellOffsetFromCoords, getFormattedValue, getEffectiveFormat, conditionalFormatByCell, getFilterComponent, isFrozenRow, isFrozenColumn, isHiddenRowByFilter, onSortTable, onFilterTable, onInsertTableColumn, onDeleteTableColumn, getFilterValues, getFilterColors, basicFilter, tables, }) => {
+    const [filterCell, setFilterCell] = useState();
+    const [isOpen, setIsOpen] = useState(false);
+    const [cellPosition, setCellPosition] = useState({ x: 0, y: 0 });
+    const [activeFilter, setActiveFilter] = useState();
+    // `activeFilter` is a snapshot from when the popup opened, but Auto apply
+    // rewrites the specs while it stays open — the values scan below must see
+    // the column's just-applied filter or it skips the rows that filter hid
+    // and the checklist collapses to only the displayed values. Re-resolve
+    // the live object by id on every render.
+    const currentFilter = useMemo(() => {
+        if (!activeFilter) {
+            return activeFilter;
+        }
+        if (basicFilter && basicFilter.id === activeFilter.id) {
+            return basicFilter;
+        }
+        return (tables?.find((table) => table.id === activeFilter.id) ?? activeFilter);
+    }, [activeFilter, basicFilter, tables]);
+    // Show filter
+    const showFilter = useCallback((cell, filterOrTable) => {
+        const coords = getActualCellCoords(cell) ?? cell;
+        const scrollPosition = getScrollPosition();
+        const cellPosition = getCellOffsetFromCoords(coords);
+        // Stop if cell is not available
+        if (isNil(cellPosition) || isNil(scrollPosition)) {
+            return;
+        }
+        // Set filter cell
+        setFilterCell(coords);
+        // Set active filter
+        setActiveFilter(filterOrTable);
+        // Update cell position
+        const { x = 0, y = 0, height = 0, width = 0 } = cellPosition;
+        const frozenRow = isFrozenRow(coords.rowIndex);
+        const frozenColumn = isFrozenColumn(coords.columnIndex);
+        const scrollX = frozenColumn ? 0 : scrollPosition.scrollLeft;
+        const scrollY = frozenRow ? 0 : scrollPosition.scrollTop;
+        setCellPosition({
+            x: x + width - FILTER_ICON_WIDTH * scale - scrollX,
+            y: y + height - scrollY,
+        });
+        // Show filter
+        setIsOpen(true);
+    }, [
+        getActualCellCoords,
+        getScrollPosition,
+        getCellOffsetFromCoords,
+        isFrozenRow,
+        isFrozenColumn,
+        scale,
+    ]);
+    // Hide filter
+    const hideFilter = useCallback(() => {
+        setIsOpen(false);
+        setActiveFilter(undefined);
+    }, []);
+    // Update values
+    const values = useMemo(() => {
+        if (!currentFilter || !filterCell) {
+            return [];
+        }
+        // When the host computes the column's distinct
+        // values off-thread (windowed sheets), use them instead of scanning every row via
+        // getFormattedValue — that scan returns blanks for unloaded rows AND notes a
+        // window miss per row, flooding the tile-fetcher until the grid blanks.
+        // `undefined` = host not driving (non-windowed) → fall through.
+        if (getFilterValues) {
+            const hostValues = getFilterValues(sheetId, filterCell.columnIndex, currentFilter.range);
+            if (hostValues !== undefined) {
+                return hostValues;
+            }
+        }
+        const values = [];
+        const { range, filterSpecs } = currentFilter;
+        const dimensionIndex = filterCell.columnIndex - range.startColumnIndex;
+        const startRow = range.startRowIndex + 1;
+        const columnHasActiveFilter = filterSpecs?.find((spec) => spec.columnIndex === dimensionIndex);
+        let hasBlank = false;
+        for (let i = startRow; i <= range.endRowIndex; i++) {
+            if (!columnHasActiveFilter && isHiddenRowByFilter(i)) {
+                continue;
+            }
+            const value = getFormattedValue(sheetId, i, filterCell.columnIndex);
+            if (value)
+                values.push(value);
+            else
+                hasBlank = true;
+        }
+        // Only surface the "(Blanks)" entry when the column actually contains a blank cell.
+        if (hasBlank)
+            values.push(BLANK_LABEL);
+        // Unique
+        return [...new Set(values)].sort(collator.compare);
+    }, [
+        currentFilter,
+        sheetId,
+        filterCell,
+        getFormattedValue,
+        isHiddenRowByFilter,
+        getFilterValues,
+    ]);
+    // CF-painted fills / font colors never ride on the effective format, so
+    // hand the state layer a reader for the rendered CF overlay — the same
+    // Map the "Filter by color" picker sources its swatches from. Without
+    // it, picking a CF-painted swatch matches no row and hides everything.
+    const onFilterTableWithConditionalFormat = useCallback((filterSheetId, filter, columnIndex, conditionType, conditionValue, visibleValues, extras) => {
+        const getCellConditionalFormat = conditionalFormatByCell
+            ? (cfSheetId, rowIndex, cfColumnIndex) => cfSheetId === sheetId
+                ? conditionalFormatByCell.get(cellIdentifier(rowIndex, cfColumnIndex))
+                : undefined
+            : undefined;
+        return onFilterTable?.(filterSheetId, filter, columnIndex, conditionType, conditionValue, visibleValues, getCellConditionalFormat
+            ? { ...extras, getCellConditionalFormat }
+            : extras);
+    }, [onFilterTable, conditionalFormatByCell, sheetId]);
+    // Distinct colors / icons present in the filter column. Powers the
+    // FilterBox's "Filter by color" picker. Only computed when an
+    // effective-format reader is wired in. Shared with the custom Sort
+    // dialog via `useColumnColorIcons`.
+    // Host-computed swatches win when the hook is provided (one engine-side column scan —
+    // the windowed path); the JS per-row scan below stays the default for JS-graph hosts.
+    const hostColorIcons = useMemo(() => {
+        if (!getFilterColors || !currentFilter || !filterCell || !isOpen) {
+            return undefined;
+        }
+        return getFilterColors(sheetId, filterCell.columnIndex, {
+            startRowIndex: (currentFilter.range.startRowIndex ?? 0) + 1,
+            endRowIndex: currentFilter.range.endRowIndex ?? -1,
+        });
+    }, [getFilterColors, currentFilter, filterCell, isOpen, sheetId]);
+    const jsColorIcons = useColumnColorIcons({
+        theme,
+        // The color/icon picker also scans the whole
+        // column via getEffectiveFormat — skip it when the host drives filter values
+        // (windowed) to avoid the same per-row flood, or when the host computes the
+        // swatches itself (getFilterColors).
+        enabled: !!currentFilter && !!filterCell && !getFilterValues && !getFilterColors,
+        sheetId,
+        columnIndex: filterCell?.columnIndex,
+        startRowIndex: (currentFilter?.range.startRowIndex ?? 0) + 1,
+        endRowIndex: currentFilter?.range.endRowIndex ?? -1,
+        getEffectiveFormat,
+        conditionalFormatByCell,
+    });
+    const availableCellColors = hostColorIcons?.availableCellColors ?? jsColorIcons.availableCellColors;
+    const availableFontColors = hostColorIcons?.availableFontColors ?? jsColorIcons.availableFontColors;
+    const availableIcons = hostColorIcons?.availableIcons ?? jsColorIcons.availableIcons;
+    // Final component
+    // Filter is displayed in a popover
+    // Keep it mounted
+    const filterComponent = filterCell && currentFilter
+        ? getFilterComponent({
+            ...cellPosition,
+            isOpen,
+            dimensionIndex: filterCell?.columnIndex - currentFilter.range.startColumnIndex,
+            onOpenChange: setIsOpen,
+            filter: currentFilter,
+            onSort: onSortTable,
+            onFilter: onFilterTableWithConditionalFormat,
+            onInsertTableColumn,
+            onDeleteTableColumn,
+            values,
+            availableCellColors,
+            availableFontColors,
+            availableIcons,
+        })
+        : null;
+    return useMemo(() => ({
+        showFilter,
+        hideFilter,
+        filterComponent,
+    }), [showFilter, hideFilter, filterComponent]);
+};

package/dist/esm/hooks/use-flash.d.ts

@@ -0,0 +1,18 @@
+import type { SpreadsheetTheme } from "../components/canvas-grid/typings";
+import type { Color, SheetRange } from "../types";
+type UseFlashProps = {
+    theme: SpreadsheetTheme;
+};
+export declare const useFlash: ({ theme }: UseFlashProps) => {
+    flash: (range: SheetRange, color?: Color, duration?: number) => void;
+    flashingBorders: (Omit<import("../components/canvas-grid/typings").RangeBorderStyle, "range"> & {
+        range: SheetRange;
+    } & {
+        startTime?: number;
+    })[];
+    onFlashEnd: (id: string) => void;
+    mark: (ranges: SheetRange[], borderColor?: Color, borderWidth?: number) => void;
+    unmark: () => void;
+};
+export {};
+//# sourceMappingURL=use-flash.d.ts.map

package/dist/esm/hooks/use-flash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-flash.d.ts","sourceRoot":"","sources":["../../../hooks/use-flash.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAEV,gBAAgB,EACjB,MAAM,mCAAmC,CAAC;AAE3C,OAAO,KAAK,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAElD,KAAK,aAAa,GAAG;IACnB,KAAK,EAAE,gBAAgB,CAAC;CACzB,CAAC;AAEF,eAAO,MAAM,QAAQ,GAAI,WAAW,aAAa;mBAOrC,UAAU,UAAS,KAAK;;;;oBALO,MAAM;;qBAqCX,MAAM;mBAO9B,UAAU,EAAE,gBACP,KAAK,gBACL,MAAM;;CAiCxB,CAAC"}

package/dist/esm/hooks/use-flash.js

@@ -0,0 +1,68 @@
+import { normalizeColor, uuid } from "@rowsncolumns/utils";
+import { useCallback, useState } from "react";
+import { getStringifiedColor } from "../themes";
+export const useFlash = ({ theme }) => {
+    const [flashingBorders, setFlashingBorders] = useState([]);
+    // Flash a cell range
+    const flash = useCallback((range, color = "#ffcc00", duration = 1500) => {
+        const rgbaStr = getStringifiedColor(color, theme);
+        const rgba = normalizeColor(rgbaStr);
+        if (!rgba) {
+            console.warn("Cannot parse color to a rgba value", color);
+            return;
+        }
+        // Flash should always contain alpha channel
+        if (!rgba?.a || rgba?.a === 0 || rgba?.a === 1) {
+            rgba.a = 0.5;
+        }
+        const rgbaString = `rgba(${rgba.r},${rgba.g},${rgba.b},${rgba.a})`;
+        setFlashingBorders((prev) => {
+            return [
+                ...prev,
+                {
+                    id: uuid(),
+                    range,
+                    type: "flash",
+                    style: {
+                        fill: rgbaString,
+                    },
+                    startTime: new Date().getTime(),
+                    duration,
+                },
+            ];
+        });
+    }, [theme]);
+    // After flash callback
+    const onFlashEnd = useCallback((id) => {
+        setFlashingBorders((prev) => prev.filter((item) => item.id !== id));
+    }, []);
+    // Highlight
+    const mark = useCallback((ranges, borderColor = { theme: 9 }, borderWidth = 2) => {
+        const markedRanges = ranges.map((range) => {
+            return {
+                id: uuid(),
+                range,
+                type: "mark",
+                style: {
+                    stroke: getStringifiedColor(borderColor, theme),
+                    strokeWidth: borderWidth,
+                    strokeStyle: "solid",
+                },
+            };
+        });
+        setFlashingBorders((prev) => {
+            return [...prev, ...markedRanges];
+        });
+    }, [theme]);
+    // Remove highlight
+    const unmark = useCallback(() => {
+        setFlashingBorders((prev) => prev.filter((item) => item.type !== "mark"));
+    }, []);
+    return {
+        flash,
+        flashingBorders,
+        onFlashEnd,
+        mark,
+        unmark,
+    };
+};

package/dist/esm/hooks/use-fonts.d.ts

@@ -0,0 +1,8 @@
+import { FontLoader } from "../api/font-loader";
+export type UseFontResults = {
+    isFontActive: boolean;
+};
+export declare const getWebFont: () => FontLoader | undefined;
+export declare const loadWebFont: (fonts: string[]) => Promise<void | undefined>;
+export declare const useFonts: (fonts?: string) => void;
+//# sourceMappingURL=use-fonts.d.ts.map

package/dist/esm/hooks/use-fonts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-fonts.d.ts","sourceRoot":"","sources":["../../../hooks/use-fonts.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAEhD,MAAM,MAAM,cAAc,GAAG;IAC3B,YAAY,EAAE,OAAO,CAAC;CACvB,CAAC;AAEF,eAAO,MAAM,UAAU,8BAAmD,CAAC;AAE3E,eAAO,MAAM,WAAW,GAAU,OAAO,MAAM,EAAE,8BAEhD,CAAC;AAEF,eAAO,MAAM,QAAQ,GAAI,QAAQ,MAAM,SAMtC,CAAC"}

package/dist/esm/hooks/use-fonts.js

@@ -0,0 +1,14 @@
+import { canUseDOM } from "@rowsncolumns/grid";
+import { useEffect } from "react";
+import { FontLoader } from "../api/font-loader";
+export const getWebFont = () => (canUseDOM ? new FontLoader() : undefined);
+export const loadWebFont = async (fonts) => {
+    return getWebFont()?.loadFonts(fonts);
+};
+export const useFonts = (fonts) => {
+    useEffect(() => {
+        const defaultFonts = ["Inconsolata:400"];
+        const finalFonts = fonts?.split(",").map((value) => String(value).trim());
+        loadWebFont(defaultFonts.concat(finalFonts ? finalFonts : []));
+    }, [fonts]);
+};

package/dist/esm/hooks/use-formula-range-helpers.d.ts

@@ -0,0 +1,21 @@
+import type { SheetRange } from "../types";
+type useFormulaRangeHelpersProps = {
+    sheetId: number;
+};
+export declare const useFormulaRangeHelpers: ({ sheetId, }: useFormulaRangeHelpersProps) => {
+    rangeToFormula: (dataRange?: SheetRange) => string;
+    formulaToRange: (formula: string) => {
+        sheetId: number | undefined;
+        startRowIndex: number;
+        endRowIndex: number;
+        startColumnIndex: number;
+        endColumnIndex: number;
+    } | undefined;
+    rangeToAddress: (dataRange?: SheetRange) => string;
+};
+export declare const useFormulaInputState: (sheetId: number, initialRange?: SheetRange | undefined) => {
+    value: string;
+    onChange: (value: string, onValidRange: (range: SheetRange) => void) => void;
+};
+export {};
+//# sourceMappingURL=use-formula-range-helpers.d.ts.map

package/dist/esm/hooks/use-formula-range-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-formula-range-helpers.d.ts","sourceRoot":"","sources":["../../../hooks/use-formula-range-helpers.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAE3C,KAAK,2BAA2B,GAAG;IACjC,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,eAAO,MAAM,sBAAsB,GAAI,cAEpC,2BAA2B;iCASb,UAAU;8BAwBb,MAAM;;;;;;;iCAZH,UAAU;CA+B1B,CAAC;AAGF,eAAO,MAAM,oBAAoB,GAC/B,SAAS,MAAM,EACf,eAAe,UAAU,GAAG,SAAS;;sBAU3B,MAAM,gBAAgB,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI;CAc5D,CAAC"}

package/dist/esm/hooks/use-formula-range-helpers.js

@@ -0,0 +1,60 @@
+import { useCallback, useState } from "react";
+import { useGetAddressFromSelection, useGetR1C1AddressFromSelection, useGetSelectionsFromFormula, useGetSheetId, useGetSheetName, } from "../atoms";
+export const useFormulaRangeHelpers = ({ sheetId, }) => {
+    const getSelectionsFromFormula = useGetSelectionsFromFormula();
+    const getSheetId = useGetSheetId();
+    const getSheetName = useGetSheetName();
+    const getAddressFromSelection = useGetAddressFromSelection();
+    const getR1C1AddressFromSelection = useGetR1C1AddressFromSelection();
+    // Range to pure formula
+    const rangeToFormula = useCallback((dataRange) => {
+        if (!dataRange) {
+            return `=`;
+        }
+        const sheetName = getSheetName?.(dataRange?.sheetId);
+        return `=` + getAddressFromSelection?.({ range: dataRange }, sheetName);
+    }, [getSheetName, getAddressFromSelection]);
+    // Range to r1c1 address
+    const rangeToAddress = useCallback((dataRange) => {
+        if (!dataRange) {
+            return `=`;
+        }
+        const sheetName = getSheetName?.(dataRange?.sheetId);
+        return getR1C1AddressFromSelection?.(dataRange, sheetName) ?? "=";
+    }, [getSheetName, getR1C1AddressFromSelection]);
+    // Formula to range
+    const formulaToRange = useCallback((formula) => {
+        const selections = getSelectionsFromFormula?.(formula);
+        if (!selections || !selections.length) {
+            return undefined;
+        }
+        const { range, sheetName } = selections[selections.length - 1];
+        return {
+            ...range,
+            sheetId: sheetName ? getSheetId?.(sheetName) : sheetId,
+        };
+    }, [sheetId, getSelectionsFromFormula, getSheetId]);
+    return {
+        rangeToFormula,
+        formulaToRange,
+        rangeToAddress,
+    };
+};
+// Hook to manage formula input state safely
+export const useFormulaInputState = (sheetId, initialRange) => {
+    const { rangeToFormula, formulaToRange } = useFormulaRangeHelpers({
+        sheetId,
+    });
+    const [rawFormula, setRawFormula] = useState(() => rangeToFormula(initialRange));
+    const handleChange = useCallback((value, onValidRange) => {
+        setRawFormula(value);
+        const parsed = formulaToRange(value);
+        if (parsed !== undefined && parsed.sheetId !== undefined) {
+            onValidRange(parsed);
+        }
+    }, [formulaToRange]);
+    return {
+        value: rawFormula,
+        onChange: handleChange,
+    };
+};

package/dist/esm/hooks/use-get-tooltip.d.ts

@@ -0,0 +1,52 @@
+import type { ElementType, ReactNode } from "react";
+import React from "react";
+import type { CellTooltipProps } from "../components/cell-tooltip";
+import type { CellData, ErrorValue } from "../types";
+type UseGetTooltipProps<T extends CellData> = {
+    sheetId: number;
+    /**
+     * Get hyperlink of a cell
+     * @param rowIndex
+     * @param columnIndex
+     */
+    getHyperlink(sheetId: number, rowIndex: number, columnIndex: number): T["hyperlink"] | undefined;
+    /**
+     * Get display value of a cell
+     * @param rowIndex
+     * @param columnIndex
+     */
+    getFormattedValue(sheetId: number, rowIndex: number, columnIndex: number): string | undefined;
+    /**
+     * Get error value of a cell
+     * @param rowIndex
+     * @param columnIndex
+     */
+    getErrorValue(sheetId: number, rowIndex: number, columnIndex: number): ErrorValue | undefined;
+    /**
+     * Get notes
+     */
+    getNote: (sheetId: number, rowIndex: number, columnIndex: number) => string | undefined;
+    /**
+     * Get custom tooltip content for a cell
+     * @param sheetId
+     * @param rowIndex
+     * @param columnIndex
+     * @returns ReactNode (component) or string content for the tooltip
+     */
+    getTooltipContent?: (sheetId: number, rowIndex: number, columnIndex: number) => ReactNode | string | undefined;
+    /**
+     * Optional error resolution component for a cell
+     */
+    errorResolutionComponent?: (sheetId: number, rowIndex: number, columnIndex: number) => ReactNode;
+    /**
+     * Cell tooltip element
+     */
+    CellTooltip?: ElementType<CellTooltipProps>;
+    /**
+     * Show notes as tooltip
+     */
+    showNotes?: boolean;
+};
+export declare const useGetTooltip: <T extends CellData>({ getHyperlink, getErrorValue, getFormattedValue, getNote, getTooltipContent, errorResolutionComponent, sheetId, showNotes, CellTooltip, }: UseGetTooltipProps<T>) => ({ cell, noteEditorCell, x, y, width, height, scrollLeft, scrollTop, onRemoveLink, onSelectLink, onRequestShowNote, onRequestCloseNote, onRequestUpdateNote, onRequestPinTooltip, onRequestUnpinTooltip, }: CellTooltipProps) => React.JSX.Element | null;
+export {};
+//# sourceMappingURL=use-get-tooltip.d.ts.map

package/dist/esm/hooks/use-get-tooltip.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-get-tooltip.d.ts","sourceRoot":"","sources":["../../../hooks/use-get-tooltip.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AACpD,OAAO,KAAsB,MAAM,OAAO,CAAC;AAE3C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAGnE,OAAO,KAAK,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAGrD,KAAK,kBAAkB,CAAC,CAAC,SAAS,QAAQ,IAAI;IAC5C,OAAO,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,YAAY,CACV,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,GAClB,CAAC,CAAC,WAAW,CAAC,GAAG,SAAS,CAAC;IAC9B;;;;OAIG;IACH,iBAAiB,CACf,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,GAClB,MAAM,GAAG,SAAS,CAAC;IACtB;;;;OAIG;IACH,aAAa,CACX,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,GAClB,UAAU,GAAG,SAAS,CAAC;IAC1B;;OAEG;IACH,OAAO,EAAE,CACP,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,KAChB,MAAM,GAAG,SAAS,CAAC;IACxB;;;;;;OAMG;IACH,iBAAiB,CAAC,EAAE,CAClB,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,KAChB,SAAS,GAAG,MAAM,GAAG,SAAS,CAAC;IACpC;;OAEG;IACH,wBAAwB,CAAC,EAAE,CACzB,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,KAChB,SAAS,CAAC;IACf;;OAEG;IACH,WAAW,CAAC,EAAE,WAAW,CAAC,gBAAgB,CAAC,CAAC;IAC5C;;OAEG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB,CAAC;AAEF,eAAO,MAAM,aAAa,GAAI,CAAC,SAAS,QAAQ,EAAE,4IAU/C,kBAAkB,CAAC,CAAC,CAAC,iNAmBf,gBAAgB,6BA4GxB,CAAC"}

package/dist/esm/hooks/use-get-tooltip.js

@@ -0,0 +1,57 @@
+import React, { useCallback } from "react";
+import { CellTooltip as DefaultCellTooltip } from "../components/cell-tooltip";
+import { getTooltipVariant } from "../helpers";
+import { useCallbackRef } from "./use-callback-ref";
+export const useGetTooltip = ({ getHyperlink, getErrorValue, getFormattedValue, getNote, getTooltipContent, errorResolutionComponent, sheetId, showNotes, CellTooltip, }) => {
+    return useCallbackRef(useCallback(({ cell, noteEditorCell, x, y, width, height, scrollLeft, scrollTop, onRemoveLink, onSelectLink, onRequestShowNote, onRequestCloseNote, onRequestUpdateNote, onRequestPinTooltip, onRequestUnpinTooltip, }) => {
+        if (!cell) {
+            return null;
+        }
+        const { rowIndex, columnIndex } = cell;
+        // Hyperlink
+        const hyperlink = getHyperlink(sheetId, rowIndex, columnIndex);
+        // Is Link
+        const isHyperlink = Boolean(hyperlink);
+        // Notes
+        const note = showNotes
+            ? getNote(sheetId, rowIndex, columnIndex)
+            : undefined;
+        // Custom tooltip content
+        const customTooltipContent = getTooltipContent?.(sheetId, rowIndex, columnIndex);
+        // Data validation errors (Invalid icon)
+        const errorValue = getErrorValue(sheetId, rowIndex, columnIndex);
+        const isInvalid = errorValue?.type === "Invalid";
+        // Error from formula calculation (Error icon)
+        const isError = errorValue?.type === "Error";
+        // TooltipElement
+        const TooltipElement = CellTooltip ?? DefaultCellTooltip;
+        if (!isError &&
+            !isInvalid &&
+            !isHyperlink &&
+            !note &&
+            !noteEditorCell &&
+            !customTooltipContent) {
+            return null;
+        }
+        // Check if we are rendering notes
+        // Error has precedence
+        const variant = getTooltipVariant(isError, isInvalid, isHyperlink, noteEditorCell ? true : !!note, customTooltipContent ? true : false);
+        // Content
+        const content = isError || isInvalid ? errorValue.message : undefined;
+        // Title
+        const title = isHyperlink
+            ? getFormattedValue(sheetId, rowIndex, columnIndex)
+            : undefined;
+        return (React.createElement(TooltipElement, { hyperlink: hyperlink, onRemoveLink: onRemoveLink, onSelectLink: onSelectLink, content: content, customContent: customTooltipContent, errorResolutionComponent: errorResolutionComponent, title: title, note: note, variant: variant, position: isHyperlink || customTooltipContent ? "bottom" : undefined, cell: cell, x: x, y: y, sheetId: sheetId, height: height, width: width, scrollLeft: scrollLeft, scrollTop: scrollTop, onRequestShowNote: onRequestShowNote, onRequestCloseNote: onRequestCloseNote, onRequestUpdateNote: onRequestUpdateNote, noteEditorCell: noteEditorCell, onRequestPinTooltip: onRequestPinTooltip, onRequestUnpinTooltip: onRequestUnpinTooltip }));
+    }, [
+        getErrorValue,
+        getFormattedValue,
+        getHyperlink,
+        getNote,
+        getTooltipContent,
+        errorResolutionComponent,
+        sheetId,
+        showNotes,
+        CellTooltip,
+    ]));
+};

package/dist/esm/hooks/use-get-values-from-range.d.ts

@@ -0,0 +1,44 @@
+import type { SelectionArea } from "@rowsncolumns/grid";
+import type { CanvasGridProps, SelectionAttributes } from "../components/canvas-grid/typings";
+import type { CellData, ConditionalFormatRule, ConditionValue, CustomFormulaResult } from "../types";
+type UseGetValuesFromRangeProps<T extends CellData> = {
+    sheetId: number;
+    /**
+     * Get formatted string values. Works for both formulas and cells
+     * @param rowIndex
+     * @param columnIndex
+     */
+    getFormattedValue(sheetId: number, rowIndex: number, columnIndex: number): string | undefined;
+    /**
+     * Get validation effective value from sheet
+     * @param sheetId
+     * @param rowIndex
+     * @param columnIndex
+     * @returns
+     */
+    getValidationValue: (sheetId: number, rowIndex: number, columnIndex: number, rule?: ConditionalFormatRule) => CustomFormulaResult;
+    /**
+     * Get grid selections from an address
+     * @param address
+     */
+    getSelectionsFromFormula(address: string): SelectionArea<SelectionAttributes>[];
+    /**
+     * Get sheet id from a sheet name
+     */
+    getSheetId: CanvasGridProps["getSheetId"];
+    onRequestCalculate?: CanvasGridProps["onRequestCalculate"];
+    /**
+     * Optional full-store per-cell reader for validation source ranges — see
+     * `CanvasGridProps["getValidationSourceValue"]`. Defaults to `getFormattedValue`.
+     */
+    getValidationSourceValue?: CanvasGridProps["getValidationSourceValue"];
+};
+/**
+ * Get all user entered values from a range
+ * used in data validation
+ * @param param0
+ * @returns
+ */
+export declare const useGetValuesFromRange: <T extends CellData>({ sheetId, getFormattedValue, getValidationValue, getSheetId, getSelectionsFromFormula, onRequestCalculate, getValidationSourceValue, }: UseGetValuesFromRangeProps<T>) => readonly [(address: string) => ConditionValue[], (address: string) => ConditionValue[], (address: string, rowIndex: number, columnIndex: number, targetSheetId?: number) => Promise<ConditionValue[]>];
+export {};
+//# sourceMappingURL=use-get-values-from-range.d.ts.map

package/dist/esm/hooks/use-get-values-from-range.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-get-values-from-range.d.ts","sourceRoot":"","sources":["../../../hooks/use-get-values-from-range.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAIxD,OAAO,KAAK,EACV,eAAe,EACf,mBAAmB,EACpB,MAAM,mCAAmC,CAAC;AAC3C,OAAO,KAAK,EACV,QAAQ,EACR,qBAAqB,EACrB,cAAc,EACd,mBAAmB,EACpB,MAAM,UAAU,CAAC;AAGlB,KAAK,0BAA0B,CAAC,CAAC,SAAS,QAAQ,IAAI;IACpD,OAAO,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,iBAAiB,CACf,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,GAClB,MAAM,GAAG,SAAS,CAAC;IACtB;;;;;;OAMG;IACH,kBAAkB,EAAE,CAClB,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,EACnB,IAAI,CAAC,EAAE,qBAAqB,KACzB,mBAAmB,CAAC;IACzB;;;OAGG;IACH,wBAAwB,CACtB,OAAO,EAAE,MAAM,GACd,aAAa,CAAC,mBAAmB,CAAC,EAAE,CAAC;IACxC;;OAEG;IACH,UAAU,EAAE,eAAe,CAAC,YAAY,CAAC,CAAC;IAC1C,kBAAkB,CAAC,EAAE,eAAe,CAAC,oBAAoB,CAAC,CAAC;IAC3D;;;OAGG;IACH,wBAAwB,CAAC,EAAE,eAAe,CAAC,0BAA0B,CAAC,CAAC;CACxE,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,GAAI,CAAC,SAAS,QAAQ,EAAE,yIAQvD,0BAA0B,CAAC,CAAC,CAAC,yBAqDhB,MAAM,KAAG,cAAc,EAAE,YASzB,MAAM,KAAG,cAAc,EAAE,YAUxB,MAAM,YACL,MAAM,eACH,MAAM,kBACJ,MAAM,KACpB,OAAO,CAAC,cAAc,EAAE,CAAC,CA4EjC,CAAC"}