@rowsncolumns/spreadsheet 10.2.68

package/dist/esm/api/validation.d.ts

@@ -0,0 +1,98 @@
+import type { CellInterface, GridRange } from "@rowsncolumns/grid";
+import type { CellData, ConditionType, ConditionValue, CustomFormulaResult, DataValidationRule, DataValidationRuleAlert, FilterCriteria, Maybe, ProtectedRange, SheetProtection, TimePeriodTypes } from "../types";
+export type CheckBooleanRuleOptions = {
+    locale?: string;
+};
+/**
+ * Conditional Validation
+ * @param condition
+ * @param value
+ * @returns
+ */
+export declare const checkBooleanRule: <T extends CellData>(rule?: DataValidationRule | undefined, value?: CustomFormulaResult, previousValue?: CustomFormulaResult, getRangeValues?: (address: string) => ConditionValue[], options?: CheckBooleanRuleOptions) => boolean | undefined;
+export declare const checkFilterRule: (filterCriteria: FilterCriteria, value?: CustomFormulaResult) => boolean | undefined;
+export declare const validationValueToDate: (value: string | TimePeriodTypes) => Date;
+/**
+ * A small helper function for list validation
+ * @param type
+ * @returns
+ */
+export declare const showValidationDropdownArrow: (rule?: DataValidationRule | null | undefined) => boolean;
+/**
+ * Check if a cell is within a protected range
+ * @param cell
+ * @param protectedRanges
+ * @returns
+ */
+export declare const isProtectedCell: (sheetId: number, cell: CellInterface, protectedRanges: ProtectedRange[]) => boolean;
+/**
+ * Check if the entire sheet is protected
+ * @param sheetId
+ * @param protectedRanges
+ * @returns
+ */
+export declare const isProtectedSheet: (sheetId: number, protectedRanges?: ProtectedRange[]) => boolean;
+/**
+ * Structural operations that worksheet protection (`<sheetProtection>`) can
+ * prohibit. Every member except `mergeCells` maps 1:1 to the OOXML flag of
+ * the same name; `mergeCells` has no allow flag in Excel — merging/unmerging
+ * is always refused while the sheet is protected.
+ */
+export type SheetProtectionAction = "formatCells" | "formatColumns" | "formatRows" | "insertColumns" | "insertRows" | "insertHyperlinks" | "deleteColumns" | "deleteRows" | "sort" | "autoFilter" | "pivotTables" | "mergeCells";
+/**
+ * Whether worksheet protection is turned on at all (`<sheetProtection
+ * sheet="1">`). All other flags are inert until this master switch is set.
+ */
+export declare const isSheetProtectionActive: (sheetProtection?: Maybe<SheetProtection>) => boolean;
+/**
+ * Whether an active worksheet protection prohibits a structural action.
+ * `false` when protection is inactive. For an active protection, a flag set
+ * `true` prohibits, `false` allows, and an ABSENT flag falls back to the
+ * OOXML schema default — prohibited for every action here (the schema only
+ * defaults `selectLockedCells`/`selectUnlockedCells` to allowed, and those
+ * are not structural actions). `mergeCells` is always prohibited while the
+ * sheet is protected (Excel has no allow flag for it).
+ */
+export declare const isActionBlockedBySheetProtection: (sheetProtection: Maybe<SheetProtection> | undefined, action: SheetProtectionAction) => boolean;
+/**
+ * Whether a cell refuses edits under an active worksheet protection. Excel's
+ * per-cell default is LOCKED, so a cell is locked unless its
+ * `protection.locked` is explicitly `false`. Always `false` when the sheet's
+ * protection is inactive.
+ */
+export declare const isCellLockedUnderProtection: (sheetProtection: Maybe<SheetProtection> | undefined, cellProtection: Maybe<Pick<NonNullable<CellData["protection"]>, "locked">>) => boolean;
+/**
+ * Check if a range is protected
+ * @param sheetId
+ * @param range
+ * @param protectedRanges
+ * @returns
+ */
+export declare const isProtectedRange: (sheetId: number, range: GridRange, protectedRanges: ProtectedRange[] | undefined | null) => boolean | undefined;
+/**
+ * Get protect range
+ * @param sheetId
+ * @param range
+ * @param protectedRanges
+ * @returns
+ */
+export declare const getProtectedRange: (sheetId: number, range: GridRange, protectedRanges: ProtectedRange[] | undefined) => ProtectedRange | undefined;
+export declare const shouldUsePreviousValue: (_type: Maybe<ConditionType>) => boolean;
+/**
+ * How a freshly-entered cell value should be committed, given its data
+ * validation alert. Mirrors Excel's `errorStyle` semantics.
+ */
+export type ValidationCommitDecision = "proceed" | "block" | "confirm";
+/**
+ * Decide how to commit an entered value against a data validation alert:
+ * - valid value, or no alert configured -> "proceed" (write normally)
+ * - invalid + style "stop"               -> "block"   (reject, keep the cell)
+ * - invalid + "warning" / "information"  -> "confirm" (allow override)
+ *
+ * Excel only blocks on `stop`; `warning`/`information` let the user keep the
+ * value. When no alert is configured the cell is still flagged with the red
+ * "Invalid" marker (handled by `SheetCell.validate`), matching today's
+ * Google-Sheets-style behaviour.
+ */
+export declare const decideValidationCommit: (alert: Maybe<DataValidationRuleAlert>, isValid: boolean) => ValidationCommitDecision;
+//# sourceMappingURL=validation.d.ts.map

package/dist/esm/api/validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../../api/validation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AASnE,OAAO,KAAK,EACV,QAAQ,EACR,aAAa,EACb,cAAc,EACd,mBAAmB,EACnB,kBAAkB,EAClB,uBAAuB,EAEvB,cAAc,EACd,KAAK,EACL,cAAc,EACd,eAAe,EACf,eAAe,EAChB,MAAM,UAAU,CAAC;AAElB,MAAM,MAAM,uBAAuB,GAAG;IACpC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AA6CF;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,GAAI,CAAC,SAAS,QAAQ,EACjD,OAAO,kBAAkB,GAAG,SAAS,EACrC,QAAQ,mBAAmB,EAC3B,gBAAgB,mBAAmB,EACnC,iBAAiB,CAAC,OAAO,EAAE,MAAM,KAAK,cAAc,EAAE,EACtD,UAAU,uBAAuB,wBAgVlC,CAAC;AAEF,eAAO,MAAM,eAAe,GAC1B,gBAAgB,cAAc,EAC9B,QAAQ,mBAAmB,wBAM5B,CAAC;AAEF,eAAO,MAAM,qBAAqB,GAAI,OAAO,MAAM,GAAG,eAAe,SA+BpE,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,2BAA2B,GACtC,OAAO,kBAAkB,GAAG,IAAI,GAAG,SAAS,YAO7C,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,eAAe,GAC1B,SAAS,MAAM,EACf,MAAM,aAAa,EACnB,iBAAiB,cAAc,EAAE,YA2BlC,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,GAC3B,SAAS,MAAM,EACf,kBAAkB,cAAc,EAAE,YAcnC,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,qBAAqB,GAC7B,aAAa,GACb,eAAe,GACf,YAAY,GACZ,eAAe,GACf,YAAY,GACZ,kBAAkB,GAClB,eAAe,GACf,YAAY,GACZ,MAAM,GACN,YAAY,GACZ,aAAa,GACb,YAAY,CAAC;AAEjB;;;GAGG;AACH,eAAO,MAAM,uBAAuB,GAClC,kBAAkB,KAAK,CAAC,eAAe,CAAC,KACvC,OAA0C,CAAC;AAE9C;;;;;;;;GAQG;AACH,eAAO,MAAM,gCAAgC,GAC3C,iBAAiB,KAAK,CAAC,eAAe,CAAC,GAAG,SAAS,EACnD,QAAQ,qBAAqB,KAC5B,OAQF,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,2BAA2B,GACtC,iBAAiB,KAAK,CAAC,eAAe,CAAC,GAAG,SAAS,EACnD,gBAAgB,KAAK,CAAC,IAAI,CAAC,WAAW,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC,KACzE,OAC2E,CAAC;AAE/E;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,GAC3B,SAAS,MAAM,EACf,OAAO,SAAS,EAChB,iBAAiB,cAAc,EAAE,GAAG,SAAS,GAAG,IAAI,wBAWrD,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,GAC5B,SAAS,MAAM,EACf,OAAO,SAAS,EAChB,iBAAiB,cAAc,EAAE,GAAG,SAAS,+BAW9C,CAAC;AAEF,eAAO,MAAM,sBAAsB,GAAI,OAAO,KAAK,CAAC,aAAa,CAAC,YAGjE,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,wBAAwB,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS,CAAC;AAEvE;;;;;;;;;;GAUG;AACH,eAAO,MAAM,sBAAsB,GACjC,OAAO,KAAK,CAAC,uBAAuB,CAAC,EACrC,SAAS,OAAO,KACf,wBAKF,CAAC"}

package/dist/esm/api/validation.js

@@ -0,0 +1,470 @@
+import { isCellWithinBounds } from "@rowsncolumns/grid";
+import { escapeCharacters, isNil, toDate, toSerial } from "@rowsncolumns/utils";
+import { EMAIL_REGEX, URL_REGEX } from "../config";
+import { checkIfStringIsReference, splitDataValidationListValues, } from "../helpers";
+/**
+ * Parse a number value with locale awareness
+ * Handles common decimal separators like comma (e.g., "6,5" in German)
+ */
+const parseLocaleNumber = (value, locale) => {
+    if (typeof value === "number")
+        return value;
+    if (value === undefined || value === null || value === "")
+        return NaN;
+    if (typeof value === "boolean")
+        return value ? 1 : 0;
+    if (value instanceof Date)
+        return value.getTime();
+    if (typeof value === "object")
+        return NaN; // Error objects
+    const trimmed = String(value).trim();
+    if (!trimmed)
+        return NaN;
+    // Try standard Number parsing first
+    const standardParsed = Number(trimmed);
+    if (!isNaN(standardParsed))
+        return standardParsed;
+    // Handle locale-specific decimal separator (comma -> period)
+    // This handles cases like "6,5" in German locale
+    if (locale) {
+        try {
+            const parts = new Intl.NumberFormat(locale).formatToParts(1.1);
+            const decimalSep = parts.find((p) => p.type === "decimal")?.value ?? ".";
+            if (decimalSep !== ".") {
+                const normalized = trimmed.replace(new RegExp(`\\${decimalSep}`, "g"), ".");
+                const parsed = Number(normalized);
+                if (!isNaN(parsed))
+                    return parsed;
+            }
+        }
+        catch {
+            // Fallback if Intl fails
+        }
+    }
+    return NaN;
+};
+/**
+ * Conditional Validation
+ * @param condition
+ * @param value
+ * @returns
+ */
+export const checkBooleanRule = (rule, value, previousValue, getRangeValues, options) => {
+    const { locale } = options ?? {};
+    const parseNumber = (val) => parseLocaleNumber(val, locale);
+    const isErrorValue = (entry) => Boolean(entry &&
+        typeof entry === "object" &&
+        "type" in entry &&
+        "message" in entry);
+    const normalizeDate = (date) => new Date(date.getFullYear(), date.getMonth(), date.getDate());
+    const toComparableDate = (entry) => {
+        if (entry instanceof Date) {
+            return entry;
+        }
+        if (typeof entry === "number" && Number.isFinite(entry)) {
+            return toDate(entry);
+        }
+        if (typeof entry === "string") {
+            const trimmed = entry.trim();
+            if (!trimmed)
+                return undefined;
+            const asNumber = Number(trimmed);
+            if (Number.isFinite(asNumber)) {
+                return toDate(asNumber);
+            }
+            const parsed = new Date(trimmed);
+            if (!isNaN(parsed.getTime())) {
+                return parsed;
+            }
+        }
+        return undefined;
+    };
+    const getWeekStart = (date) => {
+        const day = date.getDay();
+        const diff = day === 0 ? -6 : 1 - day;
+        return new Date(date.getFullYear(), date.getMonth(), date.getDate() + diff);
+    };
+    const getTimePeriodRange = (type) => {
+        const today = normalizeDate(new Date());
+        const startOfDay = (date) => normalizeDate(date);
+        const endOfDay = (date) => new Date(date.getFullYear(), date.getMonth(), date.getDate(), 23, 59, 59, 999);
+        switch (type) {
+            case "DATE_TODAY": {
+                return { start: startOfDay(today), end: endOfDay(today) };
+            }
+            case "DATE_YESTERDAY": {
+                const target = new Date(today);
+                target.setDate(target.getDate() - 1);
+                return { start: startOfDay(target), end: endOfDay(target) };
+            }
+            case "DATE_TOMORROW": {
+                const target = new Date(today);
+                target.setDate(target.getDate() + 1);
+                return { start: startOfDay(target), end: endOfDay(target) };
+            }
+            case "DATE_LAST_7_DAYS": {
+                const start = new Date(today);
+                start.setDate(start.getDate() - 6);
+                return { start: startOfDay(start), end: endOfDay(today) };
+            }
+            case "DATE_THIS_WEEK": {
+                const start = getWeekStart(today);
+                const end = new Date(start);
+                end.setDate(end.getDate() + 6);
+                return { start: startOfDay(start), end: endOfDay(end) };
+            }
+            case "DATE_LAST_WEEK": {
+                const thisWeekStart = getWeekStart(today);
+                const start = new Date(thisWeekStart);
+                start.setDate(start.getDate() - 7);
+                const end = new Date(thisWeekStart);
+                end.setDate(end.getDate() - 1);
+                return { start: startOfDay(start), end: endOfDay(end) };
+            }
+            case "DATE_NEXT_WEEK": {
+                const thisWeekStart = getWeekStart(today);
+                const start = new Date(thisWeekStart);
+                start.setDate(start.getDate() + 7);
+                const end = new Date(thisWeekStart);
+                end.setDate(end.getDate() + 13);
+                return { start: startOfDay(start), end: endOfDay(end) };
+            }
+            case "DATE_THIS_MONTH": {
+                const start = new Date(today.getFullYear(), today.getMonth(), 1);
+                const end = new Date(today.getFullYear(), today.getMonth() + 1, 0);
+                return { start: startOfDay(start), end: endOfDay(end) };
+            }
+            case "DATE_LAST_MONTH": {
+                const start = new Date(today.getFullYear(), today.getMonth() - 1, 1);
+                const end = new Date(today.getFullYear(), today.getMonth(), 0);
+                return { start: startOfDay(start), end: endOfDay(end) };
+            }
+            case "DATE_NEXT_MONTH": {
+                const start = new Date(today.getFullYear(), today.getMonth() + 1, 1);
+                const end = new Date(today.getFullYear(), today.getMonth() + 2, 0);
+                return { start: startOfDay(start), end: endOfDay(end) };
+            }
+            default:
+                return undefined;
+        }
+    };
+    const condition = rule?.condition;
+    // Exit early
+    if (!condition || !condition.type) {
+        // Set as valid
+        return true;
+    }
+    // Exit early
+    const allowBlank = rule?.allowBlank;
+    if (allowBlank && (value === "" || isNil(value))) {
+        return true;
+    }
+    const { type, values } = condition;
+    const valuesArray = values ?? [];
+    const firstValue = valuesArray[0] ?? { userEnteredValue: "" };
+    switch (type) {
+        case "TEXT_EQ":
+            return new RegExp("^" + escapeCharacters(firstValue.userEnteredValue) + "$", "gi").test(String(value));
+        case "BLANK":
+            return value === "" || isNil(value);
+        case "BOOLEAN":
+            // A blank cell under a checkbox rule is an unchecked checkbox, not a
+            // violation (Google Sheets semantics) — flagging it Invalid would also
+            // suppress the checkbox render for freshly inserted checkboxes.
+            return typeof value === "boolean" || value === "" || isNil(value);
+        case "CUSTOM_FORMULA":
+            return value === true;
+        case "NUMBER_BETWEEN": {
+            const num = parseNumber(value);
+            const bound1 = parseNumber(firstValue.userEnteredValue);
+            const bound2 = parseNumber(valuesArray[1]?.userEnteredValue);
+            const min = Math.min(bound1, bound2);
+            const max = Math.max(bound1, bound2);
+            return num >= min && num <= max;
+        }
+        case "NUMBER_NOT_BETWEEN": {
+            const num = parseNumber(value);
+            const bound1 = parseNumber(firstValue.userEnteredValue);
+            const bound2 = parseNumber(valuesArray[1]?.userEnteredValue);
+            const min = Math.min(bound1, bound2);
+            const max = Math.max(bound1, bound2);
+            return !(num >= min && num <= max);
+        }
+        case "NUMBER_EQ":
+            return parseNumber(value) === parseNumber(firstValue.userEnteredValue);
+        case "NUMBER_GREATER":
+            return parseNumber(value) > parseNumber(firstValue.userEnteredValue);
+        case "NUMBER_GREATER_THAN_EQ":
+            return parseNumber(value) >= parseNumber(firstValue.userEnteredValue);
+        case "NUMBER_LESS":
+            return parseNumber(value) < parseNumber(firstValue.userEnteredValue);
+        case "NUMBER_LESS_THAN_EQ":
+            return parseNumber(value) <= parseNumber(firstValue.userEnteredValue);
+        case "NUMBER_GREATER_THAN_PREVIOUS":
+        case "NUMBER_GREATER_THAN_EQ_PREVIOUS":
+        case "NUMBER_LESS_THAN_PREVIOUS":
+        case "NUMBER_LESS_THAN_EQ_PREVIOUS":
+            // Deprecated: previous-value conditions aren't supported in Excel exports.
+            return false;
+        case "NUMBER_NOT_EQ":
+            return parseNumber(value) !== parseNumber(firstValue.userEnteredValue);
+        case "TEXT_CONTAINS":
+            return new RegExp(escapeCharacters(firstValue.userEnteredValue), "gi").test(String(value));
+        case "TEXT_ENDS_WITH":
+            return new RegExp(escapeCharacters(firstValue.userEnteredValue) + "$", "gi").test(String(value));
+        case "TEXT_NOT_CONTAINS":
+            return !new RegExp(escapeCharacters(firstValue.userEnteredValue), "gi").test(String(value));
+        case "NOT_BLANK":
+            return !(isNil(value) || value === "");
+        case "TEXT_NOT_EQ":
+            return !new RegExp(escapeCharacters(firstValue.userEnteredValue), "gi").test(String(value));
+        case "TEXT_STARTS_WITH":
+            return new RegExp("^" + escapeCharacters(firstValue.userEnteredValue), "gi").test(String(value));
+        case "ONE_OF_RANGE":
+        case "ONE_OF_LIST": {
+            // Validate allowBlank
+            if (allowBlank && !value) {
+                return true;
+            }
+            const firstValue = valuesArray[0].userEnteredValue;
+            const isAddress = type === "ONE_OF_RANGE" ? true : checkIfStringIsReference(firstValue);
+            const finalValues = isAddress
+                ? getRangeValues?.(firstValue)
+                : splitDataValidationListValues(firstValue);
+            // A cell storing the lone text-prefix apostrophe (`'`) is Excel's
+            // "empty text" — it satisfies the list exactly like a blank cell does,
+            // and both match the list's empty entry (a stripped bare `'`).
+            const candidate = value === "'" || isNil(value) ? "" : String(value);
+            return finalValues?.some(({ userEnteredValue }) => new RegExp("^" + escapeCharacters(userEnteredValue) + "$", "gi").test(candidate));
+        }
+        case "TEXT_IS_EMAIL":
+            return new RegExp(EMAIL_REGEX, "gi").test(String(value));
+        case "TEXT_IS_URL":
+            return new RegExp(URL_REGEX, "gi").test(String(value));
+        case "DATE_EQ":
+            return (value === toSerial(validationValueToDate(firstValue.userEnteredValue)));
+        case "DATE_AFTER":
+            return (value >
+                toSerial(validationValueToDate(firstValue.userEnteredValue)));
+        case "DATE_BEFORE":
+            return (value <
+                toSerial(validationValueToDate(firstValue.userEnteredValue)));
+        case "DATE_IS_VALID": {
+            const dateValue = toDate(value);
+            return dateValue instanceof Date && !isNaN(dateValue?.getTime());
+        }
+        case "DATE_TODAY":
+        case "DATE_YESTERDAY":
+        case "DATE_TOMORROW":
+        case "DATE_LAST_7_DAYS":
+        case "DATE_LAST_WEEK":
+        case "DATE_THIS_WEEK":
+        case "DATE_NEXT_WEEK":
+        case "DATE_LAST_MONTH":
+        case "DATE_THIS_MONTH":
+        case "DATE_NEXT_MONTH": {
+            const dateValue = toComparableDate(value);
+            if (!dateValue)
+                return false;
+            const range = getTimePeriodRange(type);
+            if (!range)
+                return false;
+            const normalized = normalizeDate(dateValue);
+            return normalized >= range.start && normalized <= range.end;
+        }
+        case "ERROR":
+            return isErrorValue(value);
+        case "NOT_ERROR":
+            return !isErrorValue(value);
+        case "DATE_NOT_EQ":
+            return (value !== toSerial(validationValueToDate(firstValue.userEnteredValue)));
+        case "DATE_ON_OR_AFTER":
+            return (value >=
+                toSerial(validationValueToDate(firstValue.userEnteredValue)));
+        case "DATE_ON_OR_BEFORE":
+            return (value <=
+                toSerial(validationValueToDate(firstValue.userEnteredValue)));
+        case "DATE_BETWEEN":
+            return (value >=
+                toSerial(validationValueToDate(firstValue.userEnteredValue)) &&
+                value <=
+                    toSerial(validationValueToDate(valuesArray[1].userEnteredValue)));
+        case "DATE_NOT_BETWEEN":
+            return !(value >=
+                toSerial(validationValueToDate(firstValue.userEnteredValue)) &&
+                value <=
+                    toSerial(validationValueToDate(valuesArray[1].userEnteredValue)));
+        default:
+            return true;
+    }
+};
+export const checkFilterRule = (filterCriteria, value) => {
+    if (filterCriteria.condition) {
+        return checkBooleanRule({ condition: filterCriteria.condition }, value);
+    }
+    return false;
+};
+export const validationValueToDate = (value) => {
+    switch (value) {
+        case "today":
+            return new Date();
+        case "yesterday":
+            return new Date(new Date().getTime() - 24 * 60 * 60 * 1000);
+        case "last7Days":
+            return new Date(new Date().getTime() - 7 * 24 * 60 * 60 * 1000);
+        case "lastMonth":
+            return new Date(new Date().getFullYear(), new Date().getMonth() - 1, 1);
+        case "lastWeek":
+            return new Date(new Date().getTime() - 7 * 24 * 60 * 60 * 1000);
+        case "nextMonth":
+            return new Date(new Date().getFullYear(), new Date().getMonth() + 1, 1);
+        case "nextWeek":
+            return new Date(new Date().setDate(new Date().getDate() + 7 - new Date().getDay() + 1));
+        case "thisMonth":
+            return new Date(new Date().getFullYear(), new Date().getMonth(), 1);
+        case "thisWeek":
+            return new Date(new Date().setDate(new Date().getDate() - new Date().getDay() + 1));
+        case "tomorrow":
+            return new Date(new Date().getTime() + 24 * 60 * 60 * 1000);
+        default:
+            return new Date(value);
+    }
+};
+/**
+ * A small helper function for list validation
+ * @param type
+ * @returns
+ */
+export const showValidationDropdownArrow = (rule) => {
+    const isList = rule?.condition?.type === "ONE_OF_LIST" ||
+        rule?.condition?.type === "ONE_OF_RANGE";
+    const displayStyle = rule?.displayStyle ?? "arrow";
+    return isList && displayStyle === "arrow";
+};
+/**
+ * Check if a cell is within a protected range
+ * @param cell
+ * @param protectedRanges
+ * @returns
+ */
+export const isProtectedCell = (sheetId, cell, protectedRanges) => {
+    return protectedRanges.some(({ range, unprotectedRanges }) => {
+        const rangeExists = range.startRowIndex &&
+            range.endRowIndex &&
+            range.startColumnIndex &&
+            range.endColumnIndex;
+        // For sheet protection, we have to look in unprotected ranges
+        const isSheetProtectionEnabled = !rangeExists && range.sheetId;
+        // Entire sheet is protected, so look in unprotected ranges exclusion
+        if (isSheetProtectionEnabled) {
+            return unprotectedRanges
+                ? !unprotectedRanges?.some((range) => isCellWithinBounds(cell, range) && range.sheetId === sheetId)
+                : range.sheetId === sheetId;
+        }
+        else {
+            return (range.sheetId === sheetId &&
+                isCellWithinBounds(cell, range));
+        }
+    });
+};
+/**
+ * Check if the entire sheet is protected
+ * @param sheetId
+ * @param protectedRanges
+ * @returns
+ */
+export const isProtectedSheet = (sheetId, protectedRanges) => {
+    if (!protectedRanges) {
+        return false;
+    }
+    return protectedRanges.some(({ range }) => {
+        const rangeExists = range.startRowIndex &&
+            range.endRowIndex &&
+            range.startColumnIndex &&
+            range.endColumnIndex;
+        return range.sheetId === sheetId && !rangeExists;
+    });
+};
+/**
+ * Whether worksheet protection is turned on at all (`<sheetProtection
+ * sheet="1">`). All other flags are inert until this master switch is set.
+ */
+export const isSheetProtectionActive = (sheetProtection) => sheetProtection?.sheet === true;
+/**
+ * Whether an active worksheet protection prohibits a structural action.
+ * `false` when protection is inactive. For an active protection, a flag set
+ * `true` prohibits, `false` allows, and an ABSENT flag falls back to the
+ * OOXML schema default — prohibited for every action here (the schema only
+ * defaults `selectLockedCells`/`selectUnlockedCells` to allowed, and those
+ * are not structural actions). `mergeCells` is always prohibited while the
+ * sheet is protected (Excel has no allow flag for it).
+ */
+export const isActionBlockedBySheetProtection = (sheetProtection, action) => {
+    if (!isSheetProtectionActive(sheetProtection)) {
+        return false;
+    }
+    if (action === "mergeCells") {
+        return true;
+    }
+    return sheetProtection?.[action] !== false;
+};
+/**
+ * Whether a cell refuses edits under an active worksheet protection. Excel's
+ * per-cell default is LOCKED, so a cell is locked unless its
+ * `protection.locked` is explicitly `false`. Always `false` when the sheet's
+ * protection is inactive.
+ */
+export const isCellLockedUnderProtection = (sheetProtection, cellProtection) => isSheetProtectionActive(sheetProtection) && cellProtection?.locked !== false;
+/**
+ * Check if a range is protected
+ * @param sheetId
+ * @param range
+ * @param protectedRanges
+ * @returns
+ */
+export const isProtectedRange = (sheetId, range, protectedRanges) => {
+    return protectedRanges?.some((protectedRange) => {
+        return (protectedRange.range.sheetId === sheetId &&
+            protectedRange.range.startRowIndex === range.startRowIndex &&
+            protectedRange.range.startColumnIndex === range.startColumnIndex &&
+            protectedRange.range.endRowIndex === range.endRowIndex &&
+            protectedRange.range.endColumnIndex === range.endColumnIndex);
+    });
+};
+/**
+ * Get protect range
+ * @param sheetId
+ * @param range
+ * @param protectedRanges
+ * @returns
+ */
+export const getProtectedRange = (sheetId, range, protectedRanges) => {
+    return protectedRanges?.find((protectedRange) => {
+        return (protectedRange.range.sheetId === sheetId &&
+            protectedRange.range.startRowIndex === range.startRowIndex &&
+            protectedRange.range.startColumnIndex === range.startColumnIndex &&
+            protectedRange.range.endRowIndex === range.endRowIndex &&
+            protectedRange.range.endColumnIndex === range.endColumnIndex);
+    });
+};
+export const shouldUsePreviousValue = (_type) => {
+    // Deprecated: previous-value conditions aren't supported in Excel exports.
+    return false;
+};
+/**
+ * Decide how to commit an entered value against a data validation alert:
+ * - valid value, or no alert configured -> "proceed" (write normally)
+ * - invalid + style "stop"               -> "block"   (reject, keep the cell)
+ * - invalid + "warning" / "information"  -> "confirm" (allow override)
+ *
+ * Excel only blocks on `stop`; `warning`/`information` let the user keep the
+ * value. When no alert is configured the cell is still flagged with the red
+ * "Invalid" marker (handled by `SheetCell.validate`), matching today's
+ * Google-Sheets-style behaviour.
+ */
+export const decideValidationCommit = (alert, isValid) => {
+    if (isValid || !alert) {
+        return "proceed";
+    }
+    return alert.style === "stop" ? "block" : "confirm";
+};

package/dist/esm/atoms/active-editor.atom.d.ts

@@ -0,0 +1,8 @@
+import type { TextEditorRef } from "@rowsncolumns/ui";
+export declare const activeEditorAtom: import("jotai").PrimitiveAtom<TextEditorRef | undefined> & {
+    init: TextEditorRef | undefined;
+};
+export declare const useActiveEditor: () => TextEditorRef | undefined;
+export declare const useSetActiveEditor: () => (args_0: TextEditorRef | ((prev: TextEditorRef | undefined) => TextEditorRef | undefined) | undefined) => void;
+export declare const useEditorVisibility: () => [boolean, (args_0: boolean | ((prev: boolean) => boolean)) => void];
+//# sourceMappingURL=active-editor.atom.d.ts.map

package/dist/esm/atoms/active-editor.atom.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"active-editor.atom.d.ts","sourceRoot":"","sources":["../../../atoms/active-editor.atom.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAGtD,eAAO,MAAM,gBAAgB;;CAA6C,CAAC;AAE3E,eAAO,MAAM,eAAe,iCAAuC,CAAC;AACpE,eAAO,MAAM,kBAAkB,sHAAqC,CAAC;AAIrE,eAAO,MAAM,mBAAmB,2EAAgC,CAAC"}

package/dist/esm/atoms/active-editor.atom.js

@@ -0,0 +1,6 @@
+import { atom, useAtom, useAtomValue, useSetAtom } from "jotai";
+export const activeEditorAtom = atom(undefined);
+export const useActiveEditor = () => useAtomValue(activeEditorAtom);
+export const useSetActiveEditor = () => useSetAtom(activeEditorAtom);
+const showEditorAtom = atom(false);
+export const useEditorVisibility = () => useAtom(showEditorAtom);

package/dist/esm/atoms/cell-input-context.atom.d.ts

@@ -0,0 +1,15 @@
+export declare const useCellInputContext: () => {
+    makeEditable: ((sheetId: number, cell: import("@rowsncolumns/grid").CellInterface, initialValue?: string, options?: import("../hooks/use-editable").MakeEditableOptions) => void) | undefined;
+    getNextFocusableCell: ((sheetId: number, currentCell: import("@rowsncolumns/grid").CellInterface, direction?: import("@rowsncolumns/grid").Direction, restrictWithinSelection?: boolean) => import("@rowsncolumns/grid").CellInterface | null) | undefined;
+    submitEditor: ((value: string, textFormatRuns: import("@rowsncolumns/common-types").TextFormatRun[] | undefined, sheetId: number, activeCell: import("@rowsncolumns/grid").CellInterface, nextActiveCell?: import("@rowsncolumns/grid").CellInterface | null | undefined) => void) | undefined;
+    cancelEditor: ((e?: React.KeyboardEvent<HTMLDivElement>) => void) | undefined;
+    onEditorKeyDown: ((e: React.KeyboardEvent<HTMLDivElement>) => void) | undefined;
+    canEditCell: ((sheetId: number, cell: import("@rowsncolumns/grid").CellInterface) => boolean) | undefined;
+    setEditorValue: ((value: string, textFormatRuns: import("..").Maybe<import("@rowsncolumns/common-types").TextFormatRun[]>, sheetId: number, cell: import("@rowsncolumns/grid").CellInterface) => void) | undefined;
+    getTableNames: (() => import("@rowsncolumns/ui").OptionItem[] | undefined) | undefined;
+    getTableColumnNames: ((tableName: string) => import("@rowsncolumns/ui").OptionItem[] | undefined) | undefined;
+    getNamedRanges: (() => import("@rowsncolumns/ui").OptionItem[] | undefined) | undefined;
+    getMentions: ((query: import("..").Maybe<string>) => Promise<import("..").Maybe<any[]>>) | undefined;
+    getStructuredProperties: ((sheetName: string | undefined, rowIndex: number, columnIndex: number) => import("@rowsncolumns/ui").OptionItem[] | undefined) | undefined;
+};
+//# sourceMappingURL=cell-input-context.atom.d.ts.map

package/dist/esm/atoms/cell-input-context.atom.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cell-input-context.atom.d.ts","sourceRoot":"","sources":["../../../atoms/cell-input-context.atom.ts"],"names":[],"mappings":"AAoCA,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;CAA+C,CAAC"}

package/dist/esm/atoms/cell-input-context.atom.js

@@ -0,0 +1,20 @@
+import { atom, useAtomValue } from "jotai";
+import { spreadsheetContextAtom } from "./sheet-context.atom";
+const cellInputContextSelector = atom((get) => {
+    const { makeEditable, getNextFocusableCell, submitEditor, cancelEditor, onEditorKeyDown, canEditCell, setEditorValue, getTableNames, getTableColumnNames, getNamedRanges, getMentions, getStructuredProperties, } = get(spreadsheetContextAtom);
+    return {
+        makeEditable,
+        getNextFocusableCell,
+        submitEditor,
+        cancelEditor,
+        onEditorKeyDown,
+        canEditCell,
+        setEditorValue,
+        getTableNames,
+        getTableColumnNames,
+        getNamedRanges,
+        getMentions,
+        getStructuredProperties,
+    };
+});
+export const useCellInputContext = () => useAtomValue(cellInputContextSelector);

package/dist/esm/atoms/editing-cell.atom.d.ts

@@ -0,0 +1,7 @@
+import type { SheetCoordinate } from "../types";
+export declare const editingCellAtom: import("jotai").PrimitiveAtom<SheetCoordinate | undefined> & {
+    init: SheetCoordinate | undefined;
+};
+export declare const useEditingCellCoordinate: () => SheetCoordinate | undefined;
+export declare const useEditingCell: () => [SheetCoordinate | undefined, (args_0: SheetCoordinate | ((prev: SheetCoordinate | undefined) => SheetCoordinate | undefined) | undefined) => void];
+//# sourceMappingURL=editing-cell.atom.d.ts.map

package/dist/esm/atoms/editing-cell.atom.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"editing-cell.atom.d.ts","sourceRoot":"","sources":["../../../atoms/editing-cell.atom.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAEhD,eAAO,MAAM,eAAe;;CAA+C,CAAC;AAE5E,eAAO,MAAM,wBAAwB,mCAAsC,CAAC;AAC5E,eAAO,MAAM,cAAc,2JAAiC,CAAC"}

package/dist/esm/atoms/editing-cell.atom.js

@@ -0,0 +1,4 @@
+import { atom, useAtom, useAtomValue } from "jotai";
+export const editingCellAtom = atom(undefined);
+export const useEditingCellCoordinate = () => useAtomValue(editingCellAtom);
+export const useEditingCell = () => useAtom(editingCellAtom);