/**
 * Provides metadata related to column groups in LyteNyte Grid.
 *
 * This metadata is auto-generated by the grid based on the configured column definitions.
 * It is used internally to manage layout and grouping behavior, but is also exposed for
 * advanced use cases where programmatic interaction with group structures is needed.
 *
 * @group Column Groups
 */
export interface ColumnGroupMeta {
    /**
     * A map linking each column id to its associated group id hierarchy.
     *
     * Only populated for columns that belong to at least one group. The group ids reflect the
     * nesting structure and are ordered from outermost to innermost group.
     */
    readonly colIdToGroupIds: Map<string, string[]>;
    /**
     * A map linking each column id to its associated occurrence-qualified group id hierarchy.
     *
     * Occurrence ids distinguish separate runs of the same group name (e.g. two non-adjacent
     * blocks of columns sharing the same groupPath). The format appends the run index to the
     * plain group id using the configured group delimiter, matching the `idOccurrence` format
     * produced by the path table (e.g. `"Sports/0"`, `"Sports/1"`).
     */
    readonly colIdToOccurrenceGroupIds: Map<string, string[]>;
    /**
     * A set of all valid group ids found in the grid.
     *
     * Group ids are derived by joining nested group names using the configured group delimiter.
     * Used for validation, lookup, and rendering logic.
     */
    readonly validGroupIds: Set<string>;
    /**
     * Indicates whether a given column group occurrence is collapsible.
     *
     * For a group occurrence to be collapsible:
     * - It must contain at least one column visible when the group is **collapsed**
     * - It must also contain at least one column visible only when the group is **expanded**
     *
     * The map uses occurrence-qualified group ids as keys (e.g. `"Sports/0"`).
     */
    readonly groupIsCollapsible: Map<string, boolean>;
}
/**
 * Controls the visibility behavior of a column within a column group.
 *   - `"always"`: The column is always visible regardless of the group's state.
 *   - `"close"`: The column is visible only when the group is **collapsed**.
 *   - `"open"`: The column is visible only when the group is **expanded**.
 *
 * Used to build dynamic, collapsible column group layouts in LyteNyte Grid.
 *
 * @group Column Groups
 */
export type ColumnGroupVisibility = "always" | "close" | "open";
/**
 * Represents the possible pinned positions a column can occupy in LyteNyte Grid.
 *
 * The actual position is determined by the document's reading direction:
 * - In left-to-right (LTR) mode, `"start"` pins to the left and `"end"` to the right.
 * - In right-to-left (RTL) mode, this behavior is reversed.
 *
 * This approach aligns with CSS logical properties for layout direction.
 *
 * @group Column
 */
export type ColumnPin = "start" | "end" | null;
/**
 * The internal row data store used by LyteNyte Grid to manage row metadata, counts, and access functions.
 *
 * @group Row Data Source
 */
export interface RowDataStore<T> {
    /**
     * Total number of rows present in the grid.
     */
    readonly rowCount: GridAtomReadonly<number>;
    /**
     * Number of rows pinned to the top section.
     */
    readonly rowTopCount: GridAtom<number>;
    /**
     * Number of scrollable rows in the center section.
     */
    readonly rowCenterCount: GridAtom<number>;
    /**
     * Number of rows pinned to the bottom section.
     */
    readonly rowBottomCount: GridAtom<number>;
    /**
     * Retrieves the row node for the given row index.
     */
    readonly rowForIndex: (row: number) => GridAtomReadonlyUnwatchable<RowNode<T> | null>;
    /**
     * Clears the cached row node data in the store.
     */
    readonly rowClearCache: () => void;
    /**
     * Invalidates the row node for the given index, forcing a refresh.
     */
    readonly rowInvalidateIndex: (row: number) => void;
}
/**
 * Represents a mutable piece of reactive grid state. This atom allows reading,
 *   updating, watching, and consuming its value reactively within React components.
 *
 *   @group Grid Atom
 */
export interface GridAtom<T> {
    /**
     * Retrieves the current value stored in the atom. This method provides read access
     *   to the state managed by the atom.
     *
     *   @group Grid Atom
     */
    readonly get: () => T;
    /**
     * Updates the atom's value. Accepts either a new value or a function that receives
     *   the current value and returns the updated value.
     *
     *   @group Grid Atom
     */
    readonly set: (v: T | ((p: T) => T)) => void;
    /**
     * Registers a listener function to be invoked whenever the atom's value changes.
     *   Returns a cleanup function to remove the listener.
     *
     *   @group Grid Atom
     */
    readonly watch: (fn: () => void) => () => void;
    /**
     * A React hook that subscribes to the atom's value and causes the component to re-render
     *   whenever the atom changes.
     *
     *   @group Grid Atom
     */
    readonly useValue: () => T;
    /**
     * Reactive retrieve actual signal
     */
    readonly $: () => T;
}
/**
 * Represents an immutable version of a grid atom that supports read, watch, and reactive
 *   usage but does not allow updates.
 *
 *   @group Grid Atom
 */
export interface GridAtomReadonly<T> {
    /**
     * Retrieves the current value stored in the atom. This method provides read access
     *   to the state managed by the atom.
     *
     *   @group Grid Atom
     */
    readonly get: () => T;
    /**
     * Registers a listener function to be invoked whenever the atom's value changes.
     *   Returns a cleanup function to remove the listener.
     *
     *   @group Grid Atom
     */
    readonly watch: (fn: () => void) => () => void;
    /**
     * A React hook that subscribes to the atom's value and causes the component to re-render
     *   whenever the atom changes.
     *
     *   @group Grid Atom
     */
    readonly useValue: () => T;
    /**
     * Reactive retrieve actual signal
     */
    readonly $: () => T;
}
/**
 * Represents the most minimal read-only version of a grid atom. It supports value
 *   retrieval and reactive consumption, but not watching or updates.
 *
 *   @group Grid Atom
 */
export interface GridAtomReadonlyUnwatchable<T> {
    /**
     * Retrieves the current value stored in the atom. This method provides read access
     *   to the state managed by the atom.
     *
     *   @group Grid Atom
     */
    readonly get: () => T;
    /**
     * A React hook that subscribes to the atom's value and causes the component to re-render
     *   whenever the atom changes.
     *
     *   @group Grid Atom
     */
    readonly useValue: () => T;
    /**
     * Reactive retrieve actual signal
     */
    readonly $: () => T;
}
/**
 * A union of {@link RowLeaf} and {@link RowGroup}. Represents any row that may appear in the grid view.
 * Used generically when the row type is not known ahead of time.
 *
 * @group Row
 */
export type RowNode<T> = RowLeaf<T> | RowGroup;
/**
 * Represents a leaf row in the grid. A leaf row is a terminal node that has no children.
 * These rows typically represent the raw dataset and are used for aggregations and visual representation.
 *
 * @group Row
 */
export interface RowLeaf<T = any> {
    /**
     * A unique `id` for a given row. The `id` is generated by a given {@link RowDataSource}.
     * Every row must have a unique `id`.
     */
    readonly id: string;
    /**
     * An optional flag indicating whether the row is currently loading data.
     * Useful for asynchronous data loading scenarios.
     */
    readonly loading?: boolean;
    /**
     * An error object associated with this row. The type is intentionally flexible,
     * and should be interpreted by the consumer based on context.
     */
    readonly error?: unknown;
    /**
     * Discriminant used to identify this row as a `RowLeaf`.
     */
    readonly kind: "leaf";
    /**
     * The data payload associated with this row. Usually a plain object or array,
     * this is passed to column field logic to extract cell values.
     */
    readonly data: T | null;
}
/**
 * Represents a group (branch) row which may contain children rows (leaf or other groups).
 * Group rows are used in hierarchical views and support expansion/collapse behavior.
 *
 * @group Row
 */
export interface RowGroup {
    /**
     * A unique `id` for a given row. The `id` is generated by a given {@link RowDataSource}.
     * Every row must have a unique `id`.
     */
    readonly id: string;
    /**
     * An optional flag indicating whether the row is currently loading data.
     * Useful for asynchronous data loading scenarios.
     */
    readonly loading?: boolean;
    /**
     * An error object associated with this row. The type is intentionally flexible,
     * and should be interpreted by the consumer based on context.
     */
    readonly error?: unknown;
    /**
     * Discriminant used to identify this row as a `RowGroup`.
     */
    readonly kind: "branch";
    /**
     * The group key used to organize this branch in the hierarchy. Acts as part of the grouping path.
     */
    readonly key: string | null;
    /**
     * Group-level aggregated or summarized data. Must be an object with string keys;
     * values may be any type depending on aggregation strategy.
     */
    readonly data: Record<string, unknown>;
    /**
     * Depth level from the root; used to determine visual indenting and structure.
     */
    readonly depth: number;
    /**
     * An error that applies to the group row. This is usually set when the group fails to load
     * its children rows.
     */
    readonly errorGroup?: unknown;
    /**
     * A boolean indicating if the group expansion is loading. This is normally used for server
     * data loading, which expansions occur only after the group's children data has been fetched.
     */
    readonly loadingGroup?: boolean;
}
/**
 * Indicates the pinning position of a row:
 * - "top": pinned to top,
 * - "bottom": pinned to bottom,
 * - null: not pinned.
 * Pinned rows remain visible during scrolling.
 *
 * @group Row
 */
export type RowPin = "top" | "bottom" | null;
/**
 * Options used for date-based sorting.
 *
 * @group Sort
 */
export interface SortDateComparatorOptions {
    /**
     * A boolean indicating if null values should appear first in the sort order.
     *
     * @group Sort
     */
    readonly nullsFirst?: boolean;
    /**
     * A function to convert a value to an ISO date string.
     */
    readonly toIsoDateString?: (v: unknown) => string;
    /**
     * Whether to include the time portion of the date during comparison.
     */
    readonly includeTime?: boolean;
}
/**
 * Options for number-based sorting.
 *
 * @group Sort
 */
export interface SortNumberComparatorOptions {
    /**
     * A boolean indicating if null values should appear first in the sort order.
     *
     * @group Sort
     */
    readonly nullsFirst?: boolean;
    /**
     * Whether to compare absolute values instead of raw numbers.
     */
    readonly absoluteValue?: boolean;
}
/**
 * Options used when sorting string values.
 *
 * @group Sort
 */
export interface SortStringComparatorOptions {
    /**
     * Whether string sorting should ignore case.
     */
    readonly caseInsensitive?: boolean;
    /**
     * Whether leading/trailing whitespace should be trimmed before sorting.
     */
    readonly trimWhitespace?: boolean;
    /**
     * Whether punctuation should be ignored during sorting.
     */
    readonly ignorePunctuation?: boolean;
    /**
     * The locale used for collation-based sorting.
     */
    readonly locale?: string;
    /**
     * An optional Intl.Collator instance to use for string comparison.
     */
    readonly collator?: Intl.Collator;
    /**
     * A boolean indicating if null values should appear first in the sort order.
     *
     * @group Sort
     */
    readonly nullsFirst?: boolean;
}
/**
 * A filter type for evaluating date fields in a grid dataset.
 *
 * Date filters enable both exact and relative comparisons of date values and are essential
 * for time-series or event-driven data. LyteNyte Grid expects date values to follow a standard
 * ISO string format like `"2025-02-01 12:00:11-02:00"`.
 *
 * If filtering on timestamps or partial dates, be mindful of timezone offsets and whether
 * time components are relevant to your comparison.
 *
 * @group Filters
 */
export interface FilterDate {
    /**
     * Type discriminator used to identify this filter as a date-based filter.
     *
     * Helps distinguish between multiple filter types when working with compound filters.
     */
    readonly kind: "date";
    /**
     * The comparison operator to apply. Determines how the field value is matched
     * against the provided filter `value`.
     *
     * Refer to {@link FilterDateOperator} for the complete set of options.
     */
    readonly operator: FilterDateOperator;
    /**
     * The comparison value used by the filter.
     *
     * This may be:
     * - A date string (e.g., "2025-01-01") for direct comparisons
     * - A number (e.g., 7) for relative filters like "n_days_ago"
     * - Null, for special null-matching semantics
     *
     * The exact type depends on the operator in use.
     */
    readonly value: string | number | null;
    /**
     * Optional configuration to control how the date is parsed and compared.
     *
     * For example, setting `includeTime` enables precise comparisons down to milliseconds.
     */
    readonly options?: FilterDateOptions;
}
/**
 * Set of valid comparison operators for evaluating date-based filters.
 *
 * These operators support both fixed comparisons (e.g., "equals", "before") and dynamic
 * relative date expressions (e.g., "n_days_ago", "last_week", "is_weekend").
 *
 * The required type of the `value` field depends on the selected operator.
 *
 * @group Filters
 */
export type FilterDateOperator = "equals" | "not_equals" | "before" | "before_or_equals" | "after" | "after_or_equals" | "year_to_date" | "this_week" | "this_month" | "this_year" | "last_week" | "last_month" | "last_year" | "next_week" | "next_month" | "next_year" | "today" | "tomorrow" | "yesterday" | "week_of_year" | "quarter_of_year" | "is_weekend" | "is_weekday" | "n_days_ago" | "n_days_ahead" | "n_weeks_ago" | "n_weeks_ahead" | "n_months_ago" | "n_months_ahead" | "n_years_ago" | "n_years_ahead";
/**
 * Optional modifiers to customize date filter evaluation behavior.
 *
 * Includes options like null handling and whether time values should be considered
 * during comparisons.
 *
 * @group Filters
 */
export interface FilterDateOptions {
    /**
     * Controls how `null` values are treated when applying the filter.
     *
     * - `"ignore"`: Excludes rows where the value is `null`
     * - `"include"`: Retains rows with `null` values
     *
     * **Note:** Actual behavior depends on the row data source. Properly implemented sources will
     * respect this setting, but others may not. Additionally, this setting may be ignored by some
     * filter operators. For instance, equality checks may treat `null` as a valid match if it's
     * explicitly passed as the filter value.
     */
    readonly nullHandling?: "ignore" | "include";
    /**
     * If true, includes time components (hours, minutes, seconds) when comparing date values.
     *
     * By default, only the calendar date is compared. Enabling this flag allows for high-precision
     * filtering, which is useful for timestamp-based data (e.g., log entries or event schedules).
     */
    readonly includeTime?: boolean;
}
/**
 * Defines a filter for numeric columns.
 *
 * Applies common comparison logic to include or exclude rows based on numerical values in a specified column.
 *
 * @group Filters
 */
export interface FilterNumber {
    /**
     * Discriminant property used for type narrowing and filter dispatching.
     * Identifies this object as a number-based filter.
     */
    readonly kind: "number";
    /**
     * Operator to apply in the filter condition (e.g., `greater_than`, `equals`).
     *
     * Determines how the row value is compared to the provided `value`.
     */
    readonly operator: FilterNumberOperator;
    /**
     * Target value for the filter.
     *
     * This will be used as the right-hand operand when applying the operator to each row's value. May be `null` if specifically filtering for nulls.
     */
    readonly value: number | null;
    /**
     * Optional behavior modifiers for the filter such as absolute value comparison and null handling.
     *
     * These settings enhance precision and flexibility when filtering numerical data.
     */
    readonly options?: FilterNumberOptions;
}
/**
 * Logical operators available for number-based filtering.
 * These correspond to the traditional comparison operators, `>, <=`, etc.
 *
 *
 * @group Filters
 */
export type FilterNumberOperator = "greater_than" | "greater_than_or_equals" | "less_than" | "less_than_or_equals" | "equals" | "not_equals";
/**
 * Optional configuration values for number filters. These options allow fine-tuning of filter behavior,
 * especially in cases involving precision or null handling.
 *
 * @group Filters
 */
export interface FilterNumberOptions {
    /**
     * If set to `true`, the filter will compare absolute values instead of signed numbers.
     *
     * Useful for scenarios where magnitude is more relevant than direction (e.g., distance, deviation).
     */
    readonly absolute?: boolean;
    /**
     * Floating-point precision buffer when evaluating comparisons.
     *
     * For example, a comparison using `epsilon = 0.0001` allows for minor rounding differences
     * when dealing with decimal values.
     */
    readonly epsilon?: number;
    /**
     * Controls how `null` values are treated when applying the filter.
     *
     * - `"ignore"`: Excludes rows where the value is `null`
     * - `"include"`: Retains rows with `null` values
     *
     * **Note:** Actual behavior depends on the row data source. Properly implemented sources will
     * respect this setting, but others may not. Additionally, this setting may be ignored by some
     * filter operators. For instance, equality checks may treat `null` as a valid match if it's
     * explicitly passed as the filter value.
     */
    readonly nullHandling?: "ignore" | "include";
}
/**
 * Filter configuration for string-based column data.
 *
 * Supports a wide range of operators such as exact match, substring containment, regex matching, and string length comparisons.
 *
 * @group Filters
 */
export interface FilterString {
    /**
     * Type discriminant used internally to identify this as a string filter.
     * Useful when filters are stored in a mixed array.
     */
    readonly kind: "string";
    /**
     * The filtering operator (e.g., "contains", "equals", "length_greater_than").
     */
    readonly operator: FilterStringOperator;
    /**
     * The value to compare against.
     *
     * May be:
     * - `string`: for most text comparisons
     * - `number`: for length-based operators
     * - `null`: when matching absence of value
     */
    readonly value: string | number | null;
    /**
     * Optional modifiers to control filter behavior including case sensitivity, whitespace, punctuation,
     * and locale-sensitive matching.
     */
    readonly options?: FilterStringOptions;
}
/**
 * Collation configuration for locale-sensitive string comparisons.
 *
 * Used to construct an `Intl.Collator` instance, which enables proper handling of language and region-specific rules.
 *
 * @group Filters
 */
export interface FilterStringCollation {
    /**
     * The locale string to apply during comparisons (e.g., "en", "de", "zh-CN").
     * This determines how values are interpreted for culturally appropriate sorting.
     */
    readonly locale: Locale;
    /**
     * Specifies the sensitivity of character comparisons (e.g., case vs. accent differences).
     *
     * See the [Intl.Collator documentation](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Collator)
     * for details on supported sensitivity levels.
     */
    readonly sensitivity?: Intl.CollatorOptions["sensitivity"];
}
/**
 * List of operators available for string filtering.
 *
 * These include comparison operators (e.g., "equals"), substring checks (e.g., "contains"), and
 * length-based checks (e.g., "length_less_than"). Some operators require a numeric `value`
 * (e.g., those dealing with string length).
 *
 * @group Filters
 */
export type FilterStringOperator = "equals" | "not_equals" | "less_than" | "less_than_or_equals" | "greater_than" | "greater_than_or_equals" | "begins_with" | "not_begins_with" | "ends_with" | "not_ends_with" | "contains" | "not_contains" | "length" | "not_length" | "matches" | "length_less_than" | "length_less_than_or_equals" | "length_greater_than" | "length_greater_than_or_equals";
/**
 * Optional settings to modify the behavior of string filter evaluation.
 *
 * These provide control over how string values are matched, such as case sensitivity, whitespace trimming,
 * regular expression flags, and locale-based collation.
 *
 * @group Filters
 */
export interface FilterStringOptions {
    /**
     * Flags to apply when using the `matches` operator (e.g., "i" for case-insensitive, "g" for global).
     *
     * See the [MDN RegExp flags guide](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_expressions#advanced_searching_with_flags)
     * for details.
     */
    readonly regexOpts?: string;
    /**
     * If true, trims leading and trailing whitespace from both the value and target before comparing.
     */
    readonly trimWhitespace?: boolean;
    /**
     * If true, string comparisons are case-insensitive.
     *
     * Note: Some locales may implicitly perform case-insensitive comparisons depending on `sensitivity`.
     */
    readonly caseInsensitive?: boolean;
    /**
     * If true, removes punctuation from strings before evaluating the comparison.
     */
    readonly ignorePunctuation?: boolean;
    /**
     * Controls how `null` values are treated when applying the filter.
     *
     * - `"ignore"`: Excludes rows where the value is `null`
     * - `"include"`: Retains rows with `null` values
     *
     * **Note:** Actual behavior depends on the row data source. Properly implemented sources will
     * respect this setting, but others may not. Additionally, this setting may be ignored by some
     * filter operators. For instance, equality checks may treat `null` as a valid match if it's
     * explicitly passed as the filter value.
     */
    readonly nullHandling?: "ignore" | "include";
    /**
     * Collation options to apply locale-sensitive sorting and comparison behavior using `Intl.Collator`.
     */
    readonly collation?: FilterStringCollation;
}
/**
 * The supported locale identifiers for string filtering and collation.
 *
 * Used to configure internationalized string comparison behavior.
 *
 * @group Filters
 */
export type Locale = "en-US" | "en-GB" | "en-CA" | "en-AU" | "en-IN" | "fr-FR" | "fr-CA" | "fr-BE" | "fr-CH" | "es-ES" | "es-MX" | "es-AR" | "es-CO" | "zh-CN" | "zh-TW" | "zh-HK" | "zh-Hant" | "zh-Hans" | "ar-SA" | "ar-EG" | "ar-AE" | "de-DE" | "de-AT" | "de-CH" | "ja-JP" | "ko-KR" | "hi-IN" | "pt-BR" | "pt-PT" | "ru-RU" | "uk-UA" | "pl-PL" | "it-IT" | "nl-NL" | "sv-SE" | "tr-TR" | "th-TH" | "vi-VN" | "he-IL" | "fa-IR" | "el-GR";
/**
 * The position value type when the current focus position of the grid is within a detail cell.
 *
 *   @group Navigation
 */
export interface PositionDetailCell {
    /**
     * Discriminant indicating this position refers to a detail cell.
     */
    readonly kind: "detail";
    /**
     * The zero-based index of the row.
     */
    readonly rowIndex: number;
    /**
     * The zero-based index of the column.
     */
    readonly colIndex: number;
}
/**
 * Describes the focus position of a floating header cell.
 *
 *   @group Navigation
 */
export interface PositionFloatingCell {
    /**
     * Discriminant for identifying this as a floating header cell.
     */
    readonly kind: "floating-cell";
    /**
     * The zero-based index of the column.
     */
    readonly colIndex: number;
}
/**
 * Describes the focus position when a full width row is active.
 *
 *   @group Navigation
 */
export interface PositionFullWidthRow {
    /**
     * Discriminant indicating this position refers to a full width row.
     */
    readonly kind: "full-width";
    /**
     * The zero-based index of the row.
     */
    readonly rowIndex: number;
    /**
     * The zero-based index of the column.
     */
    readonly colIndex: number;
}
/**
 * Represents the current focus position of a regular cell in the grid.
 *
 *   @group Navigation
 */
export interface PositionGridCell {
    /**
     * Discriminant for identifying this as a regular grid cell position.
     */
    readonly kind: "cell";
    /**
     * The zero-based index of the row.
     */
    readonly rowIndex: number;
    /**
     * The zero-based index of the column.
     */
    readonly colIndex: number;
    /**
     * Reference to the root cell. If `null`, this cell is not hidden by spanning and is its own root.
     */
    readonly root: PositionGridCellRoot | null;
}
/**
 * The root reference of a grid cell. If a cell is obscured by a rowspan
 *   or colspan, it points to the actual root cell containing the data.
 *
 *   @group Navigation
 */
export interface PositionGridCellRoot {
    /**
     * The zero-based index of the column.
     */
    readonly colIndex: number;
    /**
     * The zero-based index of the row.
     */
    readonly rowIndex: number;
    /**
     * The number of rows spanned by the root cell.
     */
    readonly rowSpan: number;
    /**
     * The number of columns spanned by the root cell.
     */
    readonly colSpan: number;
}
/**
 * Describes the focus position of a standard header cell.
 *
 *   @group Navigation
 */
export interface PositionHeaderCell {
    /**
     * Discriminant for identifying this as a header cell position.
     */
    readonly kind: "header-cell";
    /**
     * The zero-based index of the column.
     */
    readonly colIndex: number;
}
/**
 * Describes the focus position of a header group cell in the column hierarchy.
 *
 *   @group Navigation
 */
export interface PositionHeaderGroupCell {
    /**
     * Discriminant indicating this is a header group cell.
     */
    readonly kind: "header-group-cell";
    /**
     * The inclusive start index of the group column range.
     */
    readonly columnStartIndex: number;
    /**
     * The exclusive end index of the group column range.
     */
    readonly columnEndIndex: number;
    /**
     * The header hierarchy row index of the group.
     */
    readonly hierarchyRowIndex: number;
    /**
     * The zero-based index of the column.
     */
    readonly colIndex: number;
}
/**
 * Union of all valid focusable positions in the grid: cells, headers, full width rows, etc.
 *
 *   @group Navigation
 */
export type PositionUnion = PositionGridCell | PositionFloatingCell | PositionHeaderCell | PositionDetailCell | PositionFullWidthRow | PositionHeaderGroupCell;