{"version":3,"file":"useRowPinningUrlState-DSifLlGx.cjs","names":["isDev","proc","globalThis","process","env","NODE_ENV","seen","Set","devWarn","message","has","add","console","warn","resetDevWarnings","clear","devWarn","defaultConfirm","message","onConfirm","native","globalThis","confirm","resolveDisabledReason","reason","undefined","runRowAction","action","row","cancelLabel","onClick","title","confirmLabel","danger","useCallback","useState","bulkActionErrorMessage","error","Error","message","String","JSON","stringify","useBulkActionRunner","confirm","cancelLabel","onComplete","pending","setPending","setError","run","action","ids","context","length","scope","allMatching","total","fire","key","onClick","status","error_","title","confirmLabel","danger","onConfirm","fold","text","normalize","replace","toLowerCase","searchable","item","haystack","label","filterCommands","commands","query","needle","trim","map","filter","includes","tableCommands","options","labels","onPrint","push","key","print","onSelect","onExport","exportCsv","onClearFilters","clearAll","disabled","hasFilters","useEffect","DEFAULT_SHORTCUTS","chord","command","parseChord","parts","toLowerCase","split","key","at","mod","includes","ctrl","meta","alt","shift","matches","event","metaKey","ctrlKey","altKey","shiftKey","inTextEntry","target","HTMLElement","tag","tagName","isContentEditable","useShortcuts","options","$","_c","enabled","onCommand","shortcuts","getTarget","t0","t1","length","parsed","map","_temp","node","document","onKeyDown","KeyboardEvent","bare","preventDefault","addEventListener","removeEventListener","shortcut","getPath","asText","value","String","Date","toISOString","slice","undefined","columnText","column","row","formatValue","rendersOwnCell","Boolean","accessor","Cell","candidates","exportValue","sortValue","key","candidate","text","humanizeKey","key","segment","split","at","words","replaceAll","trim","map","w","charAt","toUpperCase","slice","join","normalizeLocaleTag","locale","trim","replaceAll","toLowerCase","resolveLocaleTag","available","target","tags","exact","find","tag","undefined","primary","split","humanizeKey","resolveLocaleTag","getPath","pathCell","value","String","localizedColumnPath","column","locale","i18n","key","tag","Object","keys","undefined","resolveColumns","columns","map","needsHeader","header","needsAccessor","accessor","Cell","path","row","FILTER_OP_SUFFIX","filterOpKey","key","isFilterOpKey","endsWith","length","TEXT_OPS","NUMBER_OPS","DATE_OPS","TEXT_OP_SET","Set","NUMBER_OP_SET","DATE_OP_SET","isValuelessFilterOp","op","isListFilterOp","isBetweenFilterOp","TEXT_OP_LABEL_KEYS","eq","neq","contains","notContains","startsWith","empty","notEmpty","NUMBER_OP_LABEL_KEYS","gt","gte","lt","lte","between","in","notIn","DATE_OP_LABEL_KEYS","before","after","on","relative","parseTextOp","raw","has","parseNumberOp","undefined","parseDateOp","readFilterOp","extra","isEmptyRowValue","value","trim","Date","Number","isNaN","getTime","parseListOperand","Array","isArray","map","entry","String","filter","Boolean","split","parseNumberList","out","token","n","isFinite","push","formatFilterChip","fieldLabel","opWord","DAY_MS","END_OF_DAY_MS","RELATIVE_NAMED","NAMED","Set","startOfDay","now","Date","getFullYear","getMonth","getDate","endOfDay","day","getTime","addDays","days","startOfIsoWeek","weekday","getDay","mondayOffset","parseRelativeToken","raw","undefined","has","counted","exec","n","Number","isInteger","isRelativeDateToken","namedRange","token","today","startMs","endMs","start","end","resolveRelativeRange","instant","startsWith","slice","countedRelativeToken","kind","count","isFinite","Math","floor","NAMED_LABEL_KEYS","yesterday","tomorrow","thisWeek","thisMonth","previousMonth","RELATIVE_PRESETS","RELATIVE_PRESET_LABEL_KEYS","last","next","splitRelativeToken","preset","joinRelativeToken","relativeTokenLabel","labels","relLastN","replace","relNextN","localizedColumnPath","defaultLabels","devWarn","humanizeKey","getPath","DATE_OP_LABEL_KEYS","DATE_OPS","filterOpKey","formatFilterChip","isEmptyRowValue","NUMBER_OP_LABEL_KEYS","NUMBER_OPS","parseDateOp","parseNumberList","parseNumberOp","parseTextOp","TEXT_OP_LABEL_KEYS","TEXT_OPS","relativeTokenLabel","resolveRelativeRange","FILTER_TYPES","AUTO_OPTIONS_LIMIT","RANGE_SUFFIXES","dateRange","start","end","numberRange","filterStateKeys","def","registry","spec","get","type","stateKeys","key","coerceBooleanValue","value","token","trim","toLowerCase","undefined","Boolean","booleanChoiceOn","resolveFilterDefs","columns","filters","locale","standalone","standaloneKeys","Set","map","d","fromColumns","column","filter","base","has","path","push","label","header","getValue","row","filterLabel","extra","v","Array","isArray","length","valueText","String","DATE_ONLY_RE","END_OF_DAY_MS","dateValueToEpochMs","Date","getTime","Number","NaN","text","test","year","month","day","split","numericRowValue","textMatch","rowValue","term","includes","textRowMatches","op","needle","startsWith","endsWith","dateUpperBoundMs","bound","dateOnMatch","time","dateInclusiveBounds","fromKey","toKey","dateRowMatches","isNaN","range","startMs","endMs","numberRowMatches","n","minKey","maxKey","listKey","min","max","textFilterActive","dateFilterActive","numberFilterActive","asConditionScalar","asConditionList","one","asConditionPair","a","b","rangeConditionToExtra","condition","flavour","opKey","suffixes","lowKey","highKey","list","scalarConditionToExtra","listConditionToExtra","textStateKeys","rangeStateKeys","s","pair","textSpec","widget","ops","defaultOp","match","chips","textChipLabel","emptyOpChip","conditionToExtra","selectSpec","optionLabel","listSpec","urlArray","selected","booleanSpec","boolTrue","boolFalse","rangeSpec","isDate","urlNumberKeys","low","high","flavourName","rangeChipLabel","createBuiltInFilterSpecs","filterPredicate","options","find","o","opWord","labels","field","side","raw","opEmpty","opNotEmpty","buildFilterRuntime","defs","arrayExtraKeys","numberExtraKeys","filterLabels","predicates","Object","assign","filterFn","every","p","clearedFilterExtras","out","materializeAutoOptions","rows","seen","add","size","sort","localeCompare","slice","DATE_OP_LABEL_KEYS","filterOpKey","isListFilterOp","isValuelessFilterOp","NUMBER_OP_LABEL_KEYS","parseDateOp","parseListOperand","parseNumberOp","isRelativeDateToken","RANGE_OPS","text","value","String","asOpValue","raw","undefined","readStoredRangeOp","extra","stored","lowKey","highKey","listKey","op","a","join","b","low","high","inferRangeFromPair","flavour","readRangeWidget","opKey","writeRangeWidget","writeRangeFilter","key","entries","length","pair","active","RANGE_OP_LABEL_KEYS","number","date","eq","useState","filterLabel","RANGE_SUFFIXES","DATE_OP_LABEL_KEYS","DATE_OPS","filterOpKey","isBetweenFilterOp","isListFilterOp","isValuelessFilterOp","NUMBER_OP_LABEL_KEYS","NUMBER_OPS","parseTextOp","TEXT_OP_LABEL_KEYS","TEXT_OPS","readRangeWidget","writeRangeFilter","isRelativeDateToken","scalarFilterText","value","String","listFilterValues","Array","isArray","rangeArity","op","rangeInputType","flavour","arity","useRangeFilterWidget","def","source","$","_c","extra","setExtras","t0","label","type","suffixes","lowKey","key","start","highKey","end","t1","opKey","ops","t2","eq","opLabelKeys","t3","setOp","t4","derived","a","b","t5","inputType","t6","nextOp","nextA","nextB","seededB","seededA","write","t7","useTextFilterWidget","storedOp","localOp","setLocalOp","needsValue","nextValue","valueless","undefined","next","t8","filterOpLabel","labels","parseBooleanChoice","useBooleanFilterWidget","setExtra","choice","useMemo","useState","getPath","listFilterValues","CHECKLIST_VIRTUALIZE_AT","CHECKLIST_ITEM_HEIGHT","CHECKLIST_LIST_HEIGHT","valueText","value","String","optionLabel","options","Array","isArray","list","find","item","label","rowValue","def","row","getValue","key","collectChecklistValues","rows","selected","counts","Map","text","set","get","has","entries","sort","a","b","localeCompare","map","count","selectedList","useChecklistFilter","source","$","_c","fromFacets","facets","allFilteredRows","available","undefined","raw","extra","t0","t1","bb0","t2","items","query","setQuery","trim","toLowerCase","needle","t3","bb1","t4","t5","includes","filter","visible","next","setExtra","length","write","t6","next_0","Set","item_0","add","t7","t8","on","item_1","t9","virtualize","selectAllVisible","clear","toggle","collectChecklistValues","listFilterValues","rowsExcludingFilter","rows","extra","key","filterFn","cleared","undefined","filter","row","computeFilterFacets","defs","registry","out","def","widget","get","type","subset","devWarn","MapRegistry","constructor","specs","get","type","has","types","keys","register","spec","next","Map","set","extend","patch","current","emptyFilterRegistry","createFilterRegistry","map","filterTypeSpec","registry","filterWidgetKind","def","widget","filterTypeOps","ops","filterTypeDefaultOp","defaultOp","renderRegisteredFilter","source","labels","className","render","createBuiltInFilterSpecs","createFilterRegistry","builtInFilterSpecs","defaultFilterRegistry","resolveFilterRegistry","extras","length","reduce","registry","spec","register","resolveFilterMode","mode","headerFilters","toolbarShowsFilters","hasForm","hasFilterTree","showSimpleFilterFields","headerFiltersOn","filterFields","ColumnSpacer","t0","$","_c","width","side","as","t1","undefined","Cell","t2","t3","minWidth","padding","border","t4","useCallback","useEffect","useRef","useEventCallback","callback","$","_c","latest","t0","current","t1","Symbol","for","t2","args","useEffect","useState","useEventCallback","devWarn","EMPTY","useFilterOptions","def","$","_c","source","options","isLoader","loaded","setLoaded","loading","setLoading","t0","key","loader","alive","then","startLoad","t1","t2","isLeftoverAuto","t3","t4","Array","isArray","t5","t6","Symbol","for","ColumnSpacer","defaultFilterRegistry","filterLabel","listFilterValues","useBooleanFilterWidget","useRangeFilterWidget","useTextFilterWidget","renderRegisteredFilter","useFilterOptions","headerFilterStickTop","sticky","base","top","stickyExtras","filterDefForColumn","defs","key","find","def","column","Pad","t0","$","_c","part","style","stickyAttr","className","t1","TextCell","source","labels","slots","widget","Search","value","write","op","t2","search","label","SelectCell","options","extra","selected","t3","values","setExtra","length","undefined","Select","t4","t5","t6","boolAny","t7","map","_temp","t8","t9","option","CompactMultiCell","menuClassName","summary","first","groupCount","Multi","_temp2","checked","filter","item","option_0","BooleanCell","boolTrue","boolFalse","choice","RangeCell","Range","b","a","inputType","arity","value_0","FilterHeaderCell","registry","spec","get","type","custom","FilterHeaderControlChrome","FilterHeaderChrome","enabled","columns","expandable","showReorder","selection","showActions","columnSpacers","cellStyle","pinSide","padStyle","classNames","headerCell","Boolean","join","pad","t10","filterHeaderRow","t11","headerFilters","t12","expandHeader","t13","reorderHeader","t14","selectionHeader","t15","start","t16","filterHeaderCell","filterHeaderInput","filterHeaderMenu","t17","end","t18","actionsHeader","t19","devWarn","isFilterGroup","node","REQUIRES","groupBy","expandedIds","aggregates","filterTree","facets","cursor","REMEDY","grouping","tree","applyQuerySupport","extensions","support","warn","allowed","field","value","Object","entries","undefined","capability","assign","isFilterGroup","defaultFilterRegistry","filterPredicate","isActiveFilterTree","filterOpKey","FILTER_TREE_PARAM","FILTER_TREE_VERSION","parseFilterTree","serializeFilterTree","asScalar","value","undefined","String","conditionToExtra","def","condition","registry","spec","get","type","key","op","matchCondition","row","defs","find","item","evaluateFilterTree","tree","results","conditions","map","node","combinator","every","Boolean","some","isFilterGroup","emptyFilterTree","combinator","conditions","cloneGroup","group","atGroup","tree","path","current","index","child","undefined","replaceChild","next","length","splice","head","rest","updated","setFilterTreeCombinator","parentPath","slice","at","appendFilterTreeChild","root","addFilterTreeCondition","condition","addFilterTreeGroup","replaceFilterTreeNode","removeFilterTreeNode","walkFilterTreeConditions","out","forEach","node","childPath","push","useMemo","filterLabel","filterOpLabel","removeFilterTreeNode","walkFilterTreeConditions","DATE_OP_LABEL_KEYS","formatFilterChip","NUMBER_OP_LABEL_KEYS","TEXT_OP_LABEL_KEYS","relativeTokenLabel","conditionValueText","condition","labels","value","op","Array","isArray","parts","map","item","String","filter","Boolean","length","join","undefined","conditionOpWord","def","type","filterTreeChipLabel","defs","find","key","field","useFilterTreeChips","options","$","_c","tree","setFilterTree","t0","bb0","t1","Symbol","for","t2","path","label","onRemove","columnText","findMatches","options","query","rows","columns","firstRowIndex","needle","trim","toLowerCase","matches","forEach","row","index","column","col","includes","push","matchKey","cell","matchKeySet","Set","map","stepMatch","total","step","clamp","value","max","stepGridFocus","from","move","bounds","lastRow","Math","rowCount","lastCol","colCount","step","pageSize","row","col","moveGridFocus","covered","landed","current","next","sameGridCell","gridFocusMoveForKey","press","dir","toEnd","Boolean","ctrlKey","metaKey","rtl","key","a","b","sameGridCell","cellRangeBounds","range","fromRow","Math","min","anchor","row","head","toRow","max","fromCol","col","toCol","isInCellRange","cell","b","cellRangeSize","singleCellRange","extendCellRange","fallbackAnchor","isSingleCell","cellRangeIndices","rows","cols","r","push","c","useCallback","useEffect","useMemo","useState","singleCellRange","findMatches","matchKeySet","stepMatch","useFindInTable","options","$","_c","enabled","rows","columns","firstRowIndex","t0","undefined","open","setOpen","query","setQuery","index","setIndex","t1","matches","t2","matchKeys","t3","Symbol","for","next","trim","writeQuery","t4","next_0","writeOpen","t5","length","by","current","step","t6","openBar","t7","next_1","t8","previous","safeIndex","Math","min","max","t9","t10","t11","t12","useFindFocus","focusCell","selectRange","batchEditHandler","batch","onCellEdit","undefined","edits","edit","row","columnKey","value","buildExportTable","cellRangeIndices","escapeCell","text","test","replaceAll","cellText","value","String","clipboardRangeText","options","range","rows","columns","firstRowIndex","headers","indices","cols","flatMap","index","column","length","selected","row","undefined","table","lines","map","join","writeClipboardText","clipboard","globalThis","navigator","writeText","readClipboardText","readText","getPath","isCustomEditor","editor","type","isBooleanEditor","isMultiSelectEditor","isSelectEditor","editorInputType","booleanDraft","checked","isDraftChecked","draft","normalizeEditorOptions","options","map","option","value","label","hasEditableColumns","columns","some","column","editable","undefined","isCellEditable","row","flag","resolveCellEditor","readEditableCellValue","seed","readSeed","trimToEditor","editValue","sortValue","stringifyEditSeed","key","slice","at","indexOf","String","Array","isArray","formatMultiDraft","Date","Number","isNaN","getTime","localDateTimeParts","pad","n","padStart","date","getFullYear","getMonth","getDate","getHours","getMinutes","parseCellEditValue","parseNumberDraft","parseMultiDraft","trimmed","trim","isFinite","split","MULTI_SEPARATOR","values","join","readMultiDraft","stepEditableCell","rows","rowKey","from","direction","editableCols","filter","c","length","rowIndex","findIndex","r","rowId","colIndex","columnKey","total","step","flat","nextRow","Math","floor","nextCol","nextEditableCell","resolveCommitValue","find","commit","parseValue","applyCellEditCommit","resolved","onCellEdit","isCellEditable","readEditableCellValue","cellRangeBounds","fillDirection","source","to","bounds","below","row","toRow","above","fromRow","after","col","toCol","before","fromCol","vertical","Math","max","horizontal","fillTargetRange","direction","anchor","head","continueSeries","seed","step","delta","arithmeticStep","length","String","Number","at","numbers","map","value","trim","NaN","every","isFinite","constant","i","previous","undefined","fillAxis","b","forward","along","span","reverse","edgeRow","edgeCol","lanes","edge","distance","abs","lane","position","fillRangeEdits","options","rows","columns","firstRowIndex","axis","edits","flatMap","readCell","n","cell","column","raw","push","columnKey","key","parseValue","from","Array","_","isCellEditable","batchEditHandler","cellRangeBounds","parseClipboardTable","text","rows","row","field","i","length","ch","quoted","readQuotedField","value","next","push","start","pasteRangeEdits","options","range","columns","firstRowIndex","grid","edits","forEach","line","r","fromRow","undefined","raw","c","column","fromCol","columnKey","key","parseValue","cellPasteHandler","onCellPaste","onCellEdit","cellFillHandler","onCellFill","buildExportTable","cellRangeIndices","cellRangeSize","numeric","value","Number","isFinite","trim","parsed","selectionStats","options","enabled","range","rows","columns","firstRowIndex","indices","cols","flatMap","index","column","length","selected","row","undefined","table","numbers","cells","sum","average","min","max","reduce","total","Math","useCallback","useEffect","useMemo","useRef","useState","columnText","useEventCallback","cellRangeBounds","cellRangeSize","extendCellRange","isInCellRange","isSingleCell","singleCellRange","clipboardRangeText","readClipboardText","writeClipboardText","fillRangeEdits","fillTargetRange","gridFocusMoveForKey","moveGridFocus","sameGridCell","pasteRangeEdits","GRID_CELL_ATTR","gridCellAttr","cell","row","col","useGridFocus","options","enabled","headerCheckbox","rowCount","columns","rows","firstRowIndex","pageSize","dir","labels","scrollToRow","onActivate","onRangeChange","onCut","onPaste","onFill","onUndo","onRedo","onFind","matchKeys","currentMatch","isCoveredCell","active","setActive","range","setRange","pending","container","announcement","setAnnouncement","dragging","filling","fillTo","fillPreviewTo","setFillPreviewTo","lastLoadedRow","Math","max","length","bounds","colCount","announce","column","header","key","value","undefined","position","gridCellPosition","defaultPosition","selectRange","next","b","gridRangeSelection","defaultRangeSelection","fromRow","toRow","fromColumn","fromCol","toColumn","toCol","cells","fillPreview","commitFill","to","edits","source","gridRangeFilled","defaultRangeFilled","focusCell","current","target","element","querySelector","focus","copyCells","cut","selection","anchor","head","copySelection","text","then","ok","gridRangeCopied","defaultRangeCopied","gridRangeCopyFailed","fillDown","pasteInto","gridRangePasteFailed","gridRangePasted","defaultRangePasted","handleHistoryKey","event","redo","shiftKey","undo","run","say","editRedone","defaultRedone","editUndone","defaultUndone","editNothingToUndo","handleClipboardKey","from","ctrlKey","metaKey","preventDefault","isSingleRowRange","onKeyDown","move","moved","end","window","addEventListener","removeEventListener","getGridProps","role","ref","node","getCellProps","isActive","firstEver","selected","matched","has","tabIndex","onMouseDown","onMouseEnter","onMouseUp","onFocus","selectColumn","extend","top","bottom","isColumnSelected","toggleColumn","getColumnHeaderProps","onClick","modified","sortable","fillHandleCell","getFillHandleProps","stopPropagation","getRowProps","rowIndex","getCellPropsAt","windowIndex","getRowPropsAt","columnCheckbox","fillHandleLabel","gridFillHandle","total","useCallback","useEffect","useState","canFullscreen","document","fullscreenEnabled","useFullscreen","element","$","_c","active","setActive","t0","Symbol","for","supported","t1","t2","sync","fullscreenElement","addEventListener","removeEventListener","exit","_temp","t3","exitFullscreen","requestFullscreen","catch","_temp2","toggle","t4","undefined","t5","container","useCallback","useSyncExternalStore","mqlCacheByImpl","WeakMap","cachedMatchMedia","query","impl","globalThis","matchMedia","cache","get","Map","set","mql","useMediaQuery","t0","$","_c","defaultValue","undefined","t1","onChange","_temp","addEventListener","removeEventListener","subscribe","t2","mql_0","matches","getSnapshot","t3","getServerSnapshot","useMediaQuery","REDUCED_MOTION_QUERY","usePrefersReducedMotion","stableKey","input","JSON","stringify","normalize","value","undefined","Array","isArray","map","entry","source","keys","Object","sort","a","b","localeCompare","out","key","normalized","MOBILE_BREAKPOINT_PX","DEFAULT_LIMIT","PAGE_SIZE_OPTIONS","pageSizeOptions","limit","sizes","extras","filter","n","i","all","includes","indexOf","length","SEARCH_DEBOUNCE_MS","DEFAULT_ROW_SIZE_PX","DEFAULT_CARD_SIZE_PX","VIRTUAL_OVERSCAN","MOBILE_BREAKPOINT_PX","useMediaQuery","MOBILE_MEDIA_QUERY","mobileMediaQuery","px","String","useIsMobile","t0","$","_c","undefined","t1","resolvePaginationMode","mode","isMobile","useCallback","useEffect","useMemo","useSyncExternalStore","DEFAULT_LIMIT","devWarn","useResolvedAdapter","FILTER_PREFIX","isEmptyFilterValue","MAX_LIMIT","PARAM_GROUP_BY","PARAM_LIMIT","PARAM_PAGE","PARAM_SEARCH","PARAM_SORT_BY","PARAM_SORT_DIR","readExtra","readFilterTreeParam","readLimit","readPage","readSortDir","readSortLevels","writeExtra","writeFilterTreeParam","writeSortLevels","nsRegistry","WeakMap","NO_KEYS","useTableUrlState","t0","$","_c","t1","undefined","options","urlAdapter","urlSync","defaults","t2","numberExtraKeys","t3","arrayExtraKeys","t4","urlKey","t5","ns","backend","syncToUrl","resolved","t6","t7","onChange","subscribe","getSearch","t8","search","t9","URLSearchParams","params","t10","t11","counts","get","Map","set","next","remaining","delete","initialLimit","limit","initialPage","page","t12","t13","t14","t15","trim","searchTerm","t16","sortByRaw","sortBy","sortDirFallback","sortDir","t17","t18","groupByRaw","groupBy","t19","sortLevels","t20","extra","p","urlBag","out","key","value","Object","entries","mergeDefaultExtra","t21","t22","filterTree","t23","mutate","next_0","setSearch","toString","commit","t24","p_0","bag","key_0","keys","writeExtraWithDefaults","t25","p_1","readEffectiveExtra","t26","p_2","resetPage","t27","next_1","p_3","String","setPage","t28","next_2","p_4","clamped","Math","min","max","round","setLimit","t29","next_3","p_5","trimmed","t30","key_1","t31","dir","p_6","setSort","key_2","p_7","setGroupBy","t32","key_3","p_8","levels","index","findIndex","l","push","splice","length","toggleSortLevel","t33","key_4","value_0","p_9","setExtra","t34","updates","p_10","setExtras","t35","tree","p_11","setFilterTree","t36","p_12","clearExtras","t37","p_13","clearAll","t38","defaultLimit","useEffect","useMemo","useRef","useState","useEventCallback","resolvePaginationMode","useIsMobile","useTableUrlState","devWarn","stableKey","applyQuerySupport","useServerData","options","rows","total","nextCursor","loading","error","paginationMode","forceMobile","supports","expandedIds","facetKeys","facets","onQueryChange","urlOptions","mediaMobile","isMobile","resolvedMode","paged","state","page","limit","search","sortBy","sortDir","groupBy","sortLevels","extra","cursorMode","cursor","cursors","setCursors","undefined","query","filters","filterTree","queryKey","generation","setGeneration","controllerRef","emitQuery","current","abort","controller","AbortController","signal","rowsPresent","length","sawLoadingRef","firstLoadDoneRef","isLoading","setPage","lastPage","Math","max","ceil","prev","next","slice","baseKey","stash","setStash","appending","key","appendPending","prevProp","cursorBaseRef","displayRows","moreToLoad","hasNextPage","setPageSafely","fetchNextPage","defaultLimit","isFetching","isFetchingNextPage","setLimit","setSort","setGroupBy","toggleSortLevel","setSearch","setExtra","setExtras","setFilterTree","clearExtras","clearAll","refetch","g","getPath","resolveGroupValue","row","groupBy","column","sortValue","path","key","groupValueKey","value","String","Date","toISOString","JSON","stringify","Object","prototype","toString","call","formatGroupLabel","blankLabel","makeGroupRowKey","keys","valueKeys","k","join","v","groupingKeys","filter","length","partitionGroupedRows","rows","columns","partitionLevel","level","order","buckets","bucketBy","map","valueKey","bucket","get","children","undefined","flattenGroupPartitions","partitions","options","getRowId","collapsedGroupIds","aggregates","footers","sort","groupPageSize","rowPageSize","paging","flat","leafIndex","walk","levelPartitions","nodes","flatMap","part","node","label","leafRows","a","b","compareGroups","groupLimit","pageLimit","groups","shown","slice","hiddenGroups","here","groupKey","collapsed","has","aggregateCells","push","kind","leafIds","emitLeaves","from","limit","moreEntry","buildGroupedFlatModel","localeCompare","index","hidden","Math","max","total","pageSize","revealed","min","find","c","Map","set","scope","remaining","pathKey","aggregate","resolveAggregateValue","toAggregateNumber","createIncrementalAggregate","spec","rows","options","columns","Map","map","column","key","bindings","fn","Object","entries","kind","builtInName","push","acc","sum","numericCount","presentCount","min","undefined","max","dirty","state","row","addAggregateRow","applyValue","valueOf","removeAggregateRow","replaceAggregateRow","prev","next","readIncrementalAggregate","some","binding","rescan","out","format","result","cellOf","get","value","sign","n","Math","groupingKeys","groupValueKey","resolveGroupValue","rowGroupPath","row","keys","columns","map","key","column","find","item","value","valueKey","incrementalGroupTree","partitions","groupBy","roots","toMutable","rootMap","mapOf","snapshotPartitions","tree","toFrozen","addGroupedRow","path","sortedIndex","getRowId","siblings","siblingMap","step","node","get","rows","children","childMap","Map","at","firstSeenInsertAt","splice","set","insertLeaf","rebalance","removeGroupedRow","id","chain","push","i","length","list","removeLeaf","indexOf","delete","moveGroupedRow","prev","next","prevPath","nextPath","samePath","every","replaceAlongPath","sortSiblings","sort","a","b","firstLeafIndex","first","Number","POSITIVE_INFINITY","incoming","findIndex","sibling","existing","part","nodes","insertRow","row","at","type","updateRow","id","changes","upsertRow","removeRow","alreadyApplied","Object","keys","every","key","is","insertIndex","length","undefined","resolved","Math","min","max","indexOfId","list","getRowId","findIndex","PATCH_LOGS","WeakMap","rowPatchLog","rows","get","rememberLog","log","events","set","applyOne","patch","index","splice","push","prev","next","existing","applyRowPatches","patches","applyRowPatchesWithLog","working","event","aggregate","flattenGroupPartitions","groupingKeys","makeGroupRowKey","partitionGroupedRows","compareSortEntries","compareSortLevel","sortedInsertIndex","sortRows","sortRowsMulti","stableKey","addAggregateRow","createIncrementalAggregate","readIncrementalAggregate","removeAggregateRow","replaceAggregateRow","addGroupedRow","incrementalGroupTree","moveGroupedRow","removeGroupedRow","rowGroupPath","snapshotPartitions","applyRowPatchesWithLog","rowPatchLog","STATES","WeakMap","VIEWS","incrementalViewOf","rows","get","attachIncrementalView","view","set","incrementalViewConfig","getState","config","configureIncrementalView","patch","state","Error","merged","definedConfigPatch","queryChanged","queryConfigFingerprint","derivedChanged","derivedConfigFingerprint","createIncrementalView","republishDerived","incrementalSearchText","row","Object","values","map","value","JSON","stringify","String","join","getId","getRowId","filtered","hasFilter","filter","rowMatches","sorted","hasSort","fullSort","keys","groupBy","columns","partitions","length","tree","undefined","groups","groupFlattenOptions","summary","aggregateSpec","aggregateOptions","aggregates","readSummary","searchText","Map","sortValues","filteredSourceIndex","sourceIndices","filteredPos","indexMap","sortedPos","summaryDirty","groupCells","dirtyGroups","Set","warmCaches","cacheGroupCells","publish","applyRowPatchesToView","patches","applyRowPatchLogToView","log","events","needsDerived","slice","source","event","applySourceEvent","delta","applyFilterEvent","applySortEvent","applyGroupEvent","applySummaryEvent","paintGroups","defined","key","assign","search","extra","filterTree","sortBy","sortDir","sortLevels","level","dir","columnKeys","column","hasFilterFn","filterFn","hasFilterTreeFn","filterTreeFn","hasGetSortValue","getSortValue","groupFooters","Boolean","collapsed","collapsedGroupIds","sort","a","b","localeCompare","groupPageSize","rowPageSize","paging","blankLabel","hasGroupAggregates","groupAggregates","hasGroupSort","groupSort","hasGroupFilter","groupFilter","hasSummaryRow","summaryRow","hasAggregateSpec","searchTerm","trim","toLowerCase","cachedText","term","projector","getSearchText","text","includes","levels","resolveSortValue","find","item","sortValue","toSortable","accessor","id","sortKeyOf","type","splice","index","next","_","sourceDelta","filterInsert","filterRemove","filterUpdate","kind","prev","at","firstIndexAtLeast","i","rememberSearch","findIndex","forgetRow","matches","insertAt","insertSorted","removeSorted","replaceSorted","compareCached","delete","_prev","prevKey","nextKey","sameSortKey","target","itemId","targetId","itemIndex","targetIndex","itemKeys","targetKeys","entries","decided","every","is","path","markDirtyPath","prevPath","nextPath","valueKeys","step","valueKey","add","skipAggregates","footers","seen","entry","aggregateCells","cellsForGroup","groupKey","has","clear","cells","groupCellsFrom","leafRows","indices","useCallback","useMemo","useRef","resolvePaginationMode","useIsMobile","applyRowPatchLogToView","attachIncrementalView","createIncrementalView","incrementalSearchText","incrementalViewConfig","incrementalViewOf","rowPatchLog","useTableUrlState","devWarn","stableKey","toSortable","value","warnUnresolvableSort","sortBy","column","rows","getSortValue","first","sortValue","undefined","accessor","defaultSearchText","row","defaultFrontendRowId","id","String","useFrontendData","options","data","getRowId","getSearchText","columns","filterFn","filterTreeFn","paginationMode","error","refetch","isFetching","isLoading","forceMobile","urlOptions","mediaMobile","isMobile","resolvedMode","paged","state","page","limit","search","sortDir","groupBy","sortLevels","getSearchTextRef","current","getRowIdRef","searchCacheRef","Map","projectSearchText","cached","get","text","set","fingerprint","extra","filterTree","hasFilterFn","hasFilterTreeFn","hasGetSortValue","hookConfig","viewRef","dataRef","fingerprintRef","view","syncFrontendView","hookViewFingerprint","searchCache","length","find","key","filtered","sorted","searched","term","trim","toLowerCase","filter","includes","total","lastPage","Math","max","ceil","safePage","min","start","slice","hasNextPage","fetchNextPage","setPage","allFilteredRows","allSearchedRows","isFetchingNextPage","defaultLimit","setLimit","setSort","setGroupBy","toggleSortLevel","setSearch","setExtra","setExtras","setFilterTree","clearExtras","clearAll","map","level","dir","columnKeys","args","latest","previousData","previousFingerprint","configChanged","log","canPatch","logBelongsToPrevious","forgetPatchedSearch","adoptHookRefs","next","dataChanged","clear","created","mergeHookConfig","previous","groupAggregates","groupSort","groupFilter","groupFooters","collapsedGroupIds","blankLabel","groupPageSize","rowPageSize","paging","summaryRow","aggregateSpec","aggregateOptions","cache","event","events","type","delete","working","index","splice","prev","useEffect","useMemo","useRef","useState","resolveColumns","computeFilterFacets","resolveFilterRegistry","buildFilterRuntime","materializeAutoOptions","resolveFilterDefs","evaluateFilterTree","devWarn","stableKey","useFrontendData","useServerData","resolveTier","source","mode","onQueryChange","warnTierMisuse","data","useQueryNotification","handler","page","limit","search","sortBy","sortDir","sortLevels","extra","query","filters","queryKey","handlerRef","current","queryRef","lastKeyRef","controllerRef","notify","abort","controller","AbortController","signal","isDeclarativeFilters","Array","isArray","useTableData","options","total","loading","error","columns","filterTypes","filterFn","paginationMode","getSearchText","getSortValue","locale","supports","facetKeys","facets","serverFacets","urlOptions","declaredFilters","undefined","loaderCacheRef","Map","awaitedRef","Set","loadedOptions","setLoadedOptions","runtime","materialized","withAsync","map","def","loaded","key","cached","get","original","inFlight","set","alive","defs","has","add","then","prev","tier","combinedFilterFn","row","resolvedColumns","frontend","urlSync","filterTreeFn","tree","registry","arrayExtraKeys","numberExtraKeys","isLoading","derivedFacetKeys","filter","type","widget","server","rows","resolved","allSearchedRows","filterTree","sourced","COLUMN_GROUP_STUB_WIDTH","COLUMN_GROUP_ID_SEP","COLUMN_GROUP_STUB_PREFIX","COLUMN_GROUP_RENDER_PREFIX","isColumnGroupStubKey","key","startsWith","isColumnGroupRenderKey","isColumnGroupSummaryKey","groupedHeaderChildRule","hairline","borderBottom","backgroundImage","backgroundPosition","backgroundRepeat","backgroundSize","columnGroupStubStyle","width","minWidth","maxWidth","paddingInline","overflow","boxSizing","groupedHeaderAlign","align","groupedHeaderLabelStyle","display","alignItems","gap","whiteSpace","verticalAlign","groupedHeaderCellStyle","cell","textAlign","rowSpan","hideLabel","columnGroupPath","column","group","undefined","columnGroupId","path","join","toggleCollapsedColumnGroup","collapsedIds","id","includes","filter","one","headerGroupRows","columns","collapsible","groups","paths","map","maxDepth","reduce","max","Math","length","collapsed","Set","rows","depth","push","headerGroupRowAt","cells","index","label","slice","last","at","stub","span","collapsedHere","has","get","headerGroupRow","columnGroupHeaderCaption","htmlGroupedHeaderPlan","groupRows","totalRows","needsChildHeaderRow","plan","Array","from","fillGroupLevels","fillChildHeaderRow","some","level","col","fillGapLeaves","summary","spanIsSummaryOnly","kind","colSpan","start","step","pathLen","columnIndex","COLUMN_GROUP_ID_SEP","COLUMN_GROUP_RENDER_PREFIX","COLUMN_GROUP_STUB_PREFIX","COLUMN_GROUP_STUB_WIDTH","columnGroupId","columnGroupPath","isColumnGroupRenderKey","isColumnGroupStubKey","isColumnGroup","column","Array","isArray","children","flattenColumnTree","columns","leaves","groups","Map","walk","leaf","path","depth","length","id","slice","get","childKeys","push","key","frozen","record","set","applyCollapsedColumnGroups","collapsedIds","collapsed","Set","keep","map","shouldKeepLeaf","inserted","out","index","clear","appendCollapsedChrome","marriedOrderHolds","nextOrder","values","marryChildren","hits","has","first","last","at","nodes","node","nextPath","header","label","collapsedKey","collapsedRender","headerTooltip","align","group","inheritedGroup","pass","collapsedAncestors","groupHasKeptLeaf","add","split","renderColumn","stubColumn","ids","ancestors","show","resolveGroupShow","groupShow","undefined","some","String","width","minWidth","maxWidth","accessor","hideOnMobile","sortable","render","row","FALLBACK_PIN_WIDTH","parsePxWidth","width","test","trim","Number","parseFloat","undefined","resolveColumnWidth","column","widths","override","key","tableMinWidth","columns","options","total","reduce","sum","extra","pinnedColumnWidth","useCallback","useMemo","useRef","useState","applyCollapsedColumnGroups","marriedOrderHolds","FALLBACK_PIN_WIDTH","parsePxWidth","toggleCollapsedColumnGroup","EMPTY_COLUMN_LAYOUT","hidden","order","pinned","widths","PIN_Z","body","rowPinned","rowPinnedColumn","header","headerPinned","insetProp","side","pinnedCellStyle","offset","zIndex","leads","undefined","lead","position","inset","edgePinStyle","active","applyColumnOrder","columns","length","byKey","Map","map","c","key","ordered","col","get","push","delete","has","useColumnLayout","layout","onLayoutChange","defaultColumnLayout","collapsibleColumnGroups","columnGroups","internal","setInternal","state","stateRef","current","commit","next","isHidden","includes","setHidden","nextHidden","filter","k","toggleVisible","setPinned","setWidth","width","visibleColumns","collapsedGroups","toggleColumnGroup","id","nextIds","move","toIndex","latest","from","indexOf","clamped","Math","max","min","splice","reset","pinInsets","resolveWidth","column","override","insets","samePinned","reverse","set","pinOffset","applyColumnOrder","columnMenuLabel","column","header","mobileLabel","key","nextPinSide","current","undefined","pinActionLabel","labels","pinStart","unpin","ACTIONS_COLUMN_KEY","REORDER_COLUMN_KEY","columnMenuRows","allColumns","layout","state","order","map","index","name","hidden","isHidden","pinned","canMove","lockPosition","canHide","lockVisibility","canPin","lockPin","canResize","lockWidth","canSort","sortable","canFilter","filter","filterColumnMenuRows","rows","query","needle","trim","toLowerCase","row","includes","showAllColumns","setHidden","hideAllColumns","unpinAllColumns","setPinned","resetColumnLayout","setWidth","columnMenuActions","ctx","actions","onSortColumn","push","id","label","sortAscending","disabled","sortBy","sortDir","run","sortDescending","pinEnd","showColumn","hideColumn","toggleVisible","onAutoSizeColumn","autoSizeColumn","onFilterColumn","filterColumn","resetColumn","resolveColumnWidth","ASSUMED_COLUMN_WIDTH","budgetWidth","column","widths","dropOrder","columns","map","index","filter","entry","responsivePriority","undefined","sort","a","b","byPriority","responsiveColumns","available","extra","droppable","length","dropped","width","reduce","sum","push","key","gone","Set","has","useMemo","useEventCallback","devWarn","observeEdit","handler","event","error","detail","Error","message","String","useObservedEdit","$","_c","t0","stable","undefined","useEditLifecycle","props","onEditStart","onEditCancel","onEditCommit","onValidationFail","onEditError","useCallback","useMemo","useRef","useState","useEventCallback","parseCellEditValue","readEditableCellValue","resolveCellEditor","observeEdit","useBatchEditing","options","$","_c","enabled","t0","Symbol","for","pending","setPending","t1","pendingRef","t2","next","current","write","t3","columns","onEditStart","row","rowId","columnKey","value","column","find","entry","key","stored","drafts","wasPending","undefined","next_0","Object","keys","length","previousValue","unit","setDraft","t4","current_0","edits","rowId_0","entry_0","entries","row_0","patch","columnKey_0","draft","column_0","one","parseValue","push","onBatchEdit","edit","onEditCommit","saveAll","t5","onEditCancel","rowId_1","entry_1","cancelAll","t6","rowId_2","entry_2","next_1","cancelRow","t7","rowId_3","isPending","t8","rowId_4","columnKey_1","isChanged","t9","row_1","rowId_5","columnKey_2","draft_0","column_1","entry_3","draftFor","t10","map","_temp2","signature","join","t11","count","t12","t13","rowId_6","entry_4","_temp","value_0","useCallback","useMemo","useState","useEventCallback","cellKey","rowId","columnKey","useDirtyCells","t0","$","_c","t1","undefined","options","enabled","dirty","setDirty","_temp","t2","current","key","has","Set","add","mark","t3","Symbol","for","rowId_0","columnKey_0","current_0","key_0","next","delete","confirm","t4","rowId_1","current_1","prefix","next_0","filter","key_1","startsWith","size","confirmRow","t5","_temp2","confirmAll","t6","rowId_2","columnKey_1","isDirty","t7","rowId_3","prefix_0","key_2","isRowDirty","t8","signature","join","t9","count","current_2","useCallback","useMemo","useRef","useState","useEventCallback","devWarn","readEditableCellValue","liveRowChanged","input","rowVersion","undefined","String","opened","current","column","resolveConflictChoice","handler","conflict","policy","choice","error","detail","Error","message","useEditConflict","$","_c","setCurrent","seen","keepLive","_temp","takeLive","_temp2","pending","t0","Symbol","for","clear","t1","row","keep","t2","conflict_0","incomingValue","take","t3","conflict_1","applyChoice","t4","active","openedRow","live","rows","find","rowKey","rowId","columns","item","key","columnKey","previousValue","token","conflict_2","previous","draft","onEditConflict","reconcile","t5","isConflict","t6","useCallback","useMemo","useRef","useState","useEventCallback","parseCellEditValue","readEditableCellValue","resolveCellEditor","observeEdit","editableColumns","columns","row","filter","column","editable","undefined","useRowEditing","options","enabled","activeRowId","setActiveRowId","drafts","setDrafts","draftsRef","opened","begin","rowId","seeds","key","current","onEditStart","columnKey","value","previousValue","unit","setDraft","close","kind","open","onEditCancel","save","patch","draft","parseValue","Object","keys","length","onRowEdit","onEditCommit","isDirty","entries","some","isEditing","draftFor","signature","map","join","cancel","useCallback","useMemo","useRef","useState","useEventCallback","observeEdit","cellKey","rowId","columnKey","defaultFormatError","error","Error","message","isThenable","value","then","useCellSaveState","options","saving","setSaving","Set","failures","setFailures","Map","tokens","markSaving","key","busy","current","has","next","add","delete","setFailure","failure","undefined","set","track","input","previous","attempted","previousValue","result","token","get","formatError","onEditError","row","unit","rollback","onRollback","clear","signature","entries","map","f","join","statusFor","failureFor","canRollback","useCallback","useMemo","useRef","useState","isCellEditable","readEditableCellValue","stepEditableCell","observeEdit","useCellEditing","options","active","setActive","draft","setDraft","activeRef","draftRef","current","openedRef","writeDraft","value","writeActive","next","isActive","rowId","columnKey","fireCancel","opened","row","onEditCancel","previousValue","initial","unit","clearOpened","begin","initialValue","typed","undefined","onEditStart","commit","result","cancel","close","discardIfRowMissing","rows","rowKey","some","openedRow","keepLive","takeLive","handleKeyDown","event","navigation","key","preventDefault","action","advanceTarget","columns","from","direction","shiftKey","beginCellEdit","editing","column","useCallback","useMemo","useRef","useState","useEventCallback","cellKey","rowId","columnKey","useEditValidation","options","cellErrors","setCellErrors","Map","rowErrors","setRowErrors","validating","setValidating","Set","tokens","setCellError","key","message","current","get","undefined","next","delete","set","setRowError","markValidating","busy","has","add","check","input","target","value","row","validateCell","validateRow","applyEdit","shallowApplyEdit","allowed","token","cellMessage","error","edited","rowVerdict","settleRowVerdict","verdict","clear","clearAll","signature","entries","flat","join","errorFor","rowErrorFor","isValidating","rowHasError","prefix","keys","startsWith","hasRowValidator","Object","firstKey","useMemo","mergeFilterChips","filterChips","extraChips","length","resolveActiveFilterCount","override","chipCount","pushChip","chips","key","entry","label","onRemove","push","useActiveFilterChips","t0","$","_c","values","labels","onChange","value","Object","entries","resolve","hasOwn","undefined","Array","isArray","remaining","filter","v","text","String","parseGroupBy","value","undefined","list","split","map","key","trim","filter","length","formatGroupBy","keys","join","useCallback","useMemo","useState","useEventCallback","useGroupCollapse","controlled","$","_c","controlledIds","collapsedGroupIds","isControlled","undefined","uncontrolled","setUncontrolled","_temp","t0","Set","t1","next","onCollapsedGroupIdsChange","commit","t2","groupKey","has","isCollapsed","t3","groupKey_0","next_0","delete","add","toggle","t4","expandAll","t5","groupKeys","collapseAll","t6","depth","groups","filter","group","level","map","_temp2","collapseToDepth","t7","g","key","useCallback","useMemo","useState","useGroupPaging","$","_c","t0","Symbol","for","paging","setPaging","t1","pageSize","groupKey","current","undefined","groups","rows","showMore","t2","reset","t3","useEffect","useRef","useEventCallback","useInfiniteScroll","options","$","_c","hasNextPage","isFetchingNextPage","fetchNextPage","enabled","t0","rootMargin","t1","itemCount","undefined","ref","t2","onSentinelVisible","t3","el","current","IntersectionObserver","observer","entries","isIntersecting","observe","disconnect","t4","useEffect","useRef","useScrollToTableTop","t0","$","_c","ref","deps","enabled","t1","offset","t2","gap","t3","behavior","t4","undefined","t5","map","String","join","depsKey","lastDepsKeyRef","t6","t7","current","queueMicrotask","node","top","getBoundingClientRect","window","scrollBy","useEffect","useState","useElementWidth","ref","$","_c","width","setWidth","undefined","t0","t1","node","current","ResizeObserver","measure","clientWidth","observer","observe","disconnect","resolveRowHeight","rowHeight","row","index","undefined","resolveRowStyle","rowStyle","style","height","rowStyleSignature","JSON","stringify","rowStyleArmed","estimateFromRowHeight","fallback","rowAt","found","PIN_Z","resolveRowStyle","isExtraEntry","entry","kind","extraRowsArmed","extraRows","Boolean","length","toEntry","extra","key","render","insertExtraRows","entries","dataKey","before","Map","append","beforeRowId","undefined","push","bucket","get","set","result","id","waiting","delete","extraRowsForSection","rowIds","appendUntargeted","next","filter","has","insertExtrasBeforeRows","rows","getRowId","ids","Set","map","row","EXTRA_OVER_SPAN_ROW_STYLE","position","zIndex","rowPinned","EXTRA_OVER_SPAN_STYLE","textAlign","paddingBlock","paddingInline","extraHostFillStyle","extraKey","rowStyle","find","item","index","findIndex","visual","fill","backgroundColor","background","Object","keys","EXTRA_ROW_PARTS","separator","cell","fullWidth","extraCountBeforeRowIds","size","count","inflateBodyCellRowSpans","cellsByRow","visualIds","indexOf","cells","origin","changed","updated","rowSpan","extraCount","slice","visualBodySlots","buckets","list","slots","beforeId","visualSlotIndexes","extraIndexes","rowSlotIndex","slot","coverContinuingSpans","leadingCells","covered","start","addSpanCoverage","end","extraIndex","offset","colSpan","add","columnIndex","extraCoveredTableSlots","options","extraUncoveredColSpans","columnSpan","coveredSlots","spans","span","useMemo","useEventCallback","DUPLICATE_ROW_ACTION_KEY","DELETE_ROW_ACTION_KEY","useRowMutations","options","$","_c","onDuplicateRow","onDeleteRow","confirmDeleteRow","labels","t0","onAddRow","addRow","t1","row","duplicate","t2","row_0","remove","canAdd","undefined","canDuplicate","canDelete","confirmDelete","duplicateRow","deleteRow","deleteRowConfirm","built","t3","key","label","onClick","push","title","message","confirmLabel","danger","t4","color","confirm","actions","useCallback","useMemo","useRef","useState","useEventCallback","EMPTY_ROW_PIN_STATE","top","bottom","PIN_TOP_ACTION_KEY","PIN_BOTTOM_ACTION_KEY","UNPIN_ROW_ACTION_KEY","partitionPinnedRows","rows","state","getRowId","topSet","Set","bottomSet","byId","Map","row","set","id","get","undefined","push","scroll","has","rowPinSignature","pinning","rowId","sideOf","withoutId","ids","filter","withId","includes","applyRowPin","side","sameLists","a","b","length","every","index","sameState","useRowPinning","options","enabled","labels","controlledValue","pinnedRowIds","onChange","onPinnedRowIdsChange","internal","setInternal","controlled","modeRef","current","commit","next","live","pin","unpin","actions","key","label","pinToTop","isHidden","onClick","pinToBottom","unpinRow","useCallback","useMemo","useState","useEventCallback","isRtlElement","ROW_DND_MIME","REORDER_COLUMN_KEY","REORDER_COLUMN_WIDTH","rowReorderDropStyle","attrs","undefined","edge","offset","opacity","boxShadow","applyRowReorder","rows","from","to","length","slice","next","item","splice","datasetIndex","localIndex","windowStart","rowReorderSignature","reorder","rowId","lifted","isLifted","targeted","overIndex","isRtl","grip","useRowReorder","options","$","_c","enabled","labels","hostReorder","onRowReorder","t0","row","rowAt","setLifted","setOverIndex","announcement","setAnnouncement","t1","Symbol","for","reset","t2","fromLocal","toLocal","row_0","from_0","to_0","rowMoved","commit","t3","draggable","onDragStart","event","preventDefault","dataTransfer","setData","String","effectAllowed","onDragEnd","dragProps","t4","localIndex_0","row_1","windowStart_0","onDragOver","event_0","dropEffect","onDrop","event_1","payload","getData","sep","lastIndexOf","fromLocal_0","Number","isFinite","dragged","dropProps","t5","event_2","rowId_0","localIndex_1","row_2","windowStart_1","rowCount","key","rowReorderCancelled","to_1","rowLifted","rtl","currentTarget","down","up","Math","min","max","handleKeyDown","t6","localIndex_2","delta","row_3","windowStart_2","rowCount_0","to_2","moveBy","t7","rowId_1","t8","rowId_2","localIndex_3","dragging","from_1","isTarget","dropSide","rowAttrs","t9","t10","useCallback","useMemo","useState","useRowExpansion","defaultExpandedIds","$","_c","t0","Set","expandedIds","setExpandedIds","t1","id","has","isExpanded","t2","Symbol","for","id_0","prev","next","delete","add","toggle","t3","formatGroupLabel","groupValueKey","makeGroupRowKey","serverGroupEntries","options","groups","groupBy","collapsedGroupIds","getRowId","blankLabel","footers","flat","leafIndex","walk","nodes","level","path","key","at","node","here","value","groupKey","slice","collapsed","has","rows","label","push","kind","leafRows","leafIds","map","row","serverCount","count","aggregateCells","renderableAggregates","aggregates","length","index","undefined","cells","Object","entries","JSON","stringify","fillSlot","slot","state","tableErrorState","source","error","undefined","refetch","retry","retrying","isFetching","exportableValue","value","Date","Number","isNaN","getTime","undefined","isFinite","exportableRecord","cells","out","key","Object","entries","next","keys","length","nextIsNestedGroup","index","level","j","kind","skipHiddenLeaf","entry","skipUntilLevel","appendLeaves","rows","row","push","role","groupHeaderEntry","label","labelKey","groupBy","values","aggregateCells","groupFooterEntry","groupTotal","viewFromGroupedEntries","includeHiddenLeaves","dataLevel","i","leafRows","viewFromTreeEntries","map","isStructure","markKeptGroups","view","keep","footerGroupIndex","footerAt","prev","markKeptFooters","groupAt","Boolean","filterExportView","scopedIds","getRowId","has","filter","_","exportViewFromChrome","options","tree","allEntries","grouping","summaryExportValues","ACTIONS_COLUMN_KEY","REORDER_COLUMN_KEY","cellRangeIndices","devWarn","exportViewFromChrome","filterExportView","summaryExportValues","buildExportTable","csvWriter","defaultExportFilename","downloadExportFile","EXPORT_FETCH_ALL_MAX_ROWS","fetchAllExportRows","source","config","limit","pageSize","maxRows","base","exportQueryOf","out","reachedEnd","page","length","batch","fetchPage","push","rows","Math","min","onCapped","slice","resolveExportCsv","value","exportAllFallsBackToPage","exportCsv","options","Boolean","scope","allFilteredRows","undefined","request","fetchAll","exportableColumns","columns","filter","column","key","resolveExportColumns","visible","all","keys","pool","byKey","Map","map","flatMap","get","rowsInRange","range","firstRowIndex","index","row","resolveExportRows","context","selectedIds","getRowId","searchable","has","resolveExport","columnsInRange","columnScope","allColumns","cols","exportTableOptions","includeHiddenLeaves","fullView","grouping","tree","groupTotal","view","Set","getCellSpan","summary","summaryRow","buildTableCsv","build","table","filename","escapeFormulas","text","downloadTableCsv","writer","decision","onBeforeExport","file","onAfterExport","csv","makeExportCsvHandler","format","extension","query","serverAll","paged","search","sortBy","sortDir","filters","extra","groupBy","exportAllFallsBackToPage","collectFeatureNotices","input","labels","notices","virtualize","paginationMode","push","kind","appearance","message","noticeVirtualizePaged","groupByKeys","length","allFilteredRows","undefined","serverGroups","noticeGroupingUnavailable","rowPinningRequested","nestedArmed","noticePinNested","rowReorderRequested","noticeReorderNested","exportCsv","noticeExportAllPage","editMissingWriter","hasEditableColumn","onCellEdit","rowEditing","onRowEdit","batchEditing","onBatchEdit","noticeEditWithoutWriter","DEFAULT_LABEL","nestedTableDefaults","label","parent","urlSync","searchable","density","labels","tableLabel","nestedTableDetail","options","nestedTable","renderRowDetail","renderNestedDetail","row","nested","own","undefined","NestedTableRegion","t0","$","_c","t1","table","t2","buildTreeEntries","options","rows","getRowId","expandedIds","loadingIds","getChildren","getParentId","hasChildren","childrenOf","childrenFromParentIds","roots","filter","row","parent","undefined","some","r","entries","descendantsOf","ids","child","push","walk","list","level","path","key","children","expandable","length","expanded","has","descendantIds","loading","byParent","Map","siblings","get","set","filterTreeRows","withChildren","match","flatMap","kept","treeIndentStyle","paddingInlineStart","treeCardStyle","marginInlineStart","treeColumnKey","columns","declared","bodyRowEntries","tree","map","entry","position","index","treeEntry","sourceIndex","useCallback","useEffect","useRef","useState","useEventCallback","useLazyChildren","options","loadingIds","setLoadingIds","Set","failedIds","setFailedIds","asked","alive","current","settle","id","failed","next","delete","add","loadIfNeeded","row","onLoadChildren","hasLoadedChildren","getRowId","has","Promise","resolve","then","useCallback","useMemo","useState","useEventCallback","useTreeExpansion","controlled","$","_c","controlledIds","expandedIds","isControlled","undefined","uncontrolled","setUncontrolled","_temp","t0","Set","t1","next","onExpandedIdsChange","commit","t2","id","has","isExpanded","t3","id_0","next_0","delete","add","toggle","t4","id_1","expand","t5","ids","expandAll","t6","collapseAll","t7","columnGroupStubStyle","isColumnGroupStubKey","columnFlexShares","options","columns","fitColumns","widths","flexible","filter","column","key","undefined","width","flex","total","reduce","sum","shares","columnSizeStyle","userWidth","share","minWidth","maxWidth","fittedTableStyle","tableLayout","visibleColumns","columns","layout","mobileIdentityColumns","filter","c","hideOnDesktop","alwaysShow","Set","hideOnMobile","slice","Math","max","map","key","has","useCallback","useMemo","useActiveFilterChips","useExtraChips","t0","$","_c","extra","setExtra","labels","out","key","Object","keys","v","Array","isArray","length","values","t1","key_0","next","onChange","t2","computePagination","input","limit","Number","isFinite","Math","max","total","page","totalPages","ceil","safePage","min","fromIndex","toIndex","range","start","end","out","n","push","paginationSlots","siblings","nextSide","paginationItems","map","item","key","String","floor","current","boundaries","maxSlots","left","right","groupSelectionState","leafIds","selectedIds","length","selected","id","has","nextGroupSelection","state","action","ids","applyGroupLeafSelection","next","Set","add","delete","useCallback","useEffect","useMemo","useRef","useState","applyGroupLeafSelection","useSelection","options","rows","getId","resetKey","controlledValue","selectedIds","onChange","onSelectionChange","internal","setInternal","Set","allMatching","setAllMatching","controlled","undefined","modeRef","current","commit","compute","live","prev","selectAllMatching","liveRef","size","lastResetKeyRef","Object","is","visibleIds","map","selectedVisible","reduce","n","id","has","headerState","length","isSelected","toggle","next","delete","add","toggleGroupLeaves","leafIds","toggleAll","allSelected","every","clear","selectedCount","nextSort","current","key","dir","undefined","deriveSortByOptions","columns","options","column","sortable","label","header","mobileLabel","undefined","push","value","key","isEventHandler","key","value","test","mergeProps","base","overrides","out","Object","entries","existing","args","useEffect","useState","useDebounce","value","t0","$","_c","delay","undefined","debounced","setDebounced","t1","t2","id","setTimeout","clearTimeout","useEffect","useRef","useState","useDebounce","useSearchInput","search","setSearch","t0","$","_c","debounceMs","undefined","value","setValue","debounced","committedRef","t1","t2","current","t3","t4","trimmed","trim","t5","createElement","useCallback","useEffect","useMemo","columnFlexShares","columnSizeStyle","resolveColumns","visibleColumns","SEARCH_DEBOUNCE_MS","useExtraChips","resolveLabels","computePagination","useSelection","nextSort","deriveSortByOptions","devWarn","mergeProps","stableKey","useSearchInput","EMPTY_LABELS","textAlign","align","chainLevel","levels","key","find","l","sortIndexAttr","index","findIndex","undefined","ariaSort","column","sortBy","sortDir","sortable","useDataTable","options","$","_c","source","columns","declaredColumns","rowKey","tableLabel","labels","labelOverrides","dir","t0","forceMobile","t1","mobileIdentityColumns","t2","searchDebounceMs","t3","bulkActions","selectionGetId","selectedIds","onSelectedIdsChange","filterLabels","t4","multiSort","t5","locale","fitColumns","t6","columnWidths","isMobile","t7","t8","allColumns","t10","t9","seen","Set","has","add","t11","t12","t13","widths","flexShares","t14","sortByOptions","value","searchValue","setValue","setSearchValue","search","setSearch","t15","extra","setExtra","filterChips","activeFilterCount","length","t16","limit","page","total","pagination","hasBulk","getId","t17","t18","selectionResetKey","groupBy","t19","rows","resetKey","onSelectionChange","selectionState","selection","t20","next","setSort","toggleSort","t21","table","props","role","getTableProps","getHeaderRowProps","_temp","t22","sortLevels","column_0","props_1","style","getHeaderCellProps","t23","column_1","props_2","type","disabled","onClick","event","shiftKey","toggleSortLevel","header","getSortButtonProps","t24","row","props_3","id","selected","isSelected","getRowProps","getCellContent","_temp2","t25","column_3","props_4","getCellProps","t26","searchPlaceholder","props_5","placeholder","onChange","event_0","currentTarget","getSearchInputProps","t27","isLoading","t28","isEmpty","getRowKey","column_2","row_0","rowIndex","Cell","accessor","props_0","defaultLabels","useCallback","useEffect","useMemo","useRef","useRowPairMeasurer","virtualizer","enabled","$","_c","t0","Symbol","for","Map","pairs","observer","t1","owners","t2","index","pair","current","get","row","rowHeight","getBoundingClientRect","height","detailHeight","detail","total","resizeItem","report","t3","t4","ResizeObserver","seen","instance","entries","touched","Set","entry","index_0","target","undefined","add","index_1","element","keys","observe","disconnect","t5","index_2","half","node","pair_0","previous","unobserve","delete","set","attach","t6","index_3","index_4","useVirtualizer","useWindowVirtualizer","useCallback","useEffect","useMemo","useRef","VIRTUAL_OVERSCAN","useRowPairMeasurer","asSizeEstimator","estimateSize","rowSourceIndex","entry","sourceIndex","index","resolveVirtualRows","rows","rowKey","rowEntries","map","row","key","virtualColumnSpan","columnCount","hasSelection","hasActions","hasExpansion","hasReorder","useTableVirtualization","enabled","overscan","scrollMargin","getScrollElement","onEndReached","expandable","elementMode","undefined","rowKeyRef","current","getItemKey","String","windowVirtualizer","count","length","elementVirtualizer","virtualizer","virtualItems","getVirtualItems","active","measureRowPair","materializedRows","flatMap","virtualItem","notifiedAtCount","last","at","atEnd","paddingTop","paddingBottom","first","resolvedScrollMargin","options","start","getTotalSize","end","Math","max","measureElement","useKeyedVirtualization","keys","sizeOf","indices","_","item","windowGroupedEntries","entries","useCallback","useLayoutEffect","useRef","useState","documentOffsetTop","el","Math","max","round","getBoundingClientRect","top","window","scrollY","LIST_SELECTOR","virtualListElement","root","querySelector","measureWindowScrollMargin","list","useMeasuredWindowScrollMargin","enabled","fallbackRoot","scrollMargin","setScrollMargin","nodeRef","read","next","current","prev","observe","node","ResizeObserver","ro","observed","document","documentElement","addEventListener","disconnect","removeEventListener","useCallback","useEffect","useMemo","useRef","defaultConfirm","ACTIONS_COLUMN_KEY","REORDER_COLUMN_KEY","flattenColumnTree","resolveColumns","responsiveColumns","useColumnLayout","DEFAULT_CARD_SIZE_PX","DEFAULT_ROW_SIZE_PX","useBatchEditing","useDirtyCells","useEditConflict","useEditLifecycle","useRowEditing","useCellSaveState","useCellEditing","useEditValidation","mergeFilterChips","resolveActiveFilterCount","useFilterTreeChips","formatGroupBy","parseGroupBy","buildGroupedFlatModel","useGroupCollapse","useGroupPaging","useEventCallback","useInfiniteScroll","useIsMobile","useScrollToTableTop","useElementWidth","insertExtraRows","configureIncrementalView","incrementalViewOf","useRowMutations","partitionPinnedRows","useRowPinning","useRowReorder","estimateFromRowHeight","useRowExpansion","serverGroupEntries","tableErrorState","collectFeatureNotices","nestedTableDetail","buildTreeEntries","treeColumnKey","useLazyChildren","useTreeExpansion","useDataTable","devWarn","useKeyedVirtualization","useTableVirtualization","windowGroupedEntries","useMeasuredWindowScrollMargin","viewControlsToolbar","props","fullscreen","densityChooser","density","onDensityChange","supported","onToggleFullscreen","toggle","isFullscreen","active","undoRedoToolbar","wanted","history","labels","enabled","onUndo","undo","onRedo","redo","canUndo","canRedo","undoLabel","undoEdit","redoLabel","redoEdit","printToolbar","onPrint","undefined","printLabel","print","useTableChrome","$","_c","source","columns","rowKey","tableLabel","dir","forceMobile","mobileBreakpoint","mobileIdentityColumns","onRowsChange","bulkActions","selectionGetId","selectedIds","selectedIdsProp","onSelectionChange","filterLabels","onClearFilters","extraChips","activeFilterCount","activeFilterCountProp","confirm","confirmProp","columnLayout","columnLayoutProp","onColumnLayoutChange","defaultColumnLayout","groupAggregates","groupFooters","groupSort","groupFilter","groupPageSize","groupRowPageSize","onGroupLoadMore","extraRows","autoMobile","isMobile","t0","flattened","t1","leaves","locale","resolvedColumns","rootRef","rootWidth","t2","collapsibleColumnGroups","t3","groups","layout","onLayoutChange","columnGroups","requestedGroupBy","groupBy","t4","groupByKeys","serverGroups","groupingArmed","Boolean","length","allFilteredRows","t5","bb0","all","t6","Math","max","t7","rows","page","limit","total","hasNextPage","isFetchingNextPage","viewSource","state","widths","visibleColumns","available","responsive","fitColumns","multiSort","searchDebounceMs","onSelectedIdsChange","columnWidths","table","t8","t9","controlledSelection","selection","t10","ids","notifySelectionChange","t11","t12","t13","filterDefs","t14","filterTree","setFilterTree","tree","defs","treeChips","t15","filterChips","mergedChips","isPaged","paginationMode","t16","errorState","body","isLoading","isEmpty","emptyVariant","search","isRefreshing","isFetching","t17","clearExtras","clearFilters","expansionState","defaultExpandedRowIds","nestedTable","hostLabels","hostRenderRowDetail","renderRowDetail","t18","parent","t19","render","expansion","detail","t20","onEditCancel","onEditCommit","onEditError","onEditStart","onValidationFail","lifecycle","t21","cellEditingState","conflict","onCellEdit","t22","applyEdit","validateRow","validation","t23","formatEditError","onEditRollback","onRollback","formatError","saving","t24","dirtyIndicators","t25","dirty","rowModeArmed","rowEditing","onRowEdit","t26","batchArmed","batchEditing","onBatchEdit","t27","batch","editingArmed","t28","editConflict","keepMine","takeTheirs","theirsValue","conflictLabels","message","editing","t29","some","_temp","hasEditableColumn","t30","t31","t32","collapsedGroupIds","onCollapsedGroupIdsChange","groupCollapse","t33","t34","onGroupByChange","setGroupBy","sourceSetGroupBy","t35","key","getRowId","groupPaging","t36","confirmDeleteRow","onAddRow","onDeleteRow","onDuplicateRow","rowMutations","mutationActions","actions","hasRowActions","rowActions","actionsHidden","isHidden","hostRowActions","t37","bb1","t38","t39","expandedIds","onExpandedIdsChange","treeExpansion","treeShaped","getChildren","getParentId","row","hasLoadedChildren","t40","onLoadChildren","lazyChildren","t41","loadingIds","hasChildren","treeEntries","t42","Set","flatMap","_temp2","treeExportEntries","t43","bb2","t44","id","entry_0","find","candidate","entry","expanded","loadIfNeeded","t45","t46","t47","failedIds","t48","treeColumn","t49","entries","allEntries","columnKey","bb3","openGroups","incremental","view","rowPageSize","paging","footers","aggregates","sort","filter","_temp3","_temp4","withExtras","entry_3","size","scope","showMore","groupKey","collapseToDepth","depth","collapsed","expandAll","collapseAll","grouping","bb4","entry_4","kind","push","editingRows","requestedReorder","onRowReorder","reorderBlocked","hasRowReorder","reorderHidden","rowReorderEnabled","hostRowReorder","moveRowDown","moveRowUp","reorderRow","rowLifted","rowMoved","rowReorderCancelled","t50","index","t51","rowAt","rowReorderState","rowReorder","t52","pinnedRowIds","onPinnedRowIdsChange","t53","t54","row_0","t55","pinToBottom","pinToTop","unpinRow","t56","requested","blocked","rowPinning","useChromeRowPinning","t57","t58","editConflictPolicy","onEditConflict","rowVersion","discardIfRowMissing","row_1","reconcile","openedRow","draft","policy","keep","row_2","keepLive","take","row_3","value","takeLive","showFooter","error","t59","t60","t61","t62","exportCsv","virtualize","rowPinningRequested","rowReorderRequested","nestedArmed","featureNotices","t63","el","current","value_0","map","_temp5","join","dataset","adapttableNotices","hasAnyActions","t64","bb5","t65","pins","t66","t67","visibleRowActions","dropped","droppedColumns","allColumns","notice","entry_2","entry_1","level","descendantIds","column","editable","useChromeBodyData","chrome","fetchNextPage","fetchNext","scrollBoxRef","inScrollBox","maxHeight","measureWindowOffset","virtualScrollMargin","scrollMargin","measuredScrollMargin","observe","observeWindowList","node","virtualScrollRef","isBodyEligible","bodyEligible","entryKeys","groupKeys","treeArmed","treeKeys","pinState","Symbol","for","top","scroll","bottom","partitioned","estimateBodyItemSize","estimateSize","virtualOverscan","overscan","getScrollElement","onEndReached","scrollOpts","keys","groupVirtualization","treeVirtualization","expandable","virtualization","indices","groupingEntries","resolveBodyVirtualization","resolvedVirtualization","boxVirtual","canLoadMore","bodySentinelCount","itemCount","loadMoreRef","Map","forEach","set","sourceIndexById","sourceIndex","get","pinnedVirtualization","pinnedTopRows","pinnedBottomRows","nested","scrollRows","fallback","estimateCardSize","estimateRowSize","rowHeight","keyed","paddingTop","paddingBottom","measureElement","useChromeScrollReset","ref","pageDep","sortBy","sortDir","scrollToTopOnChange","scrollTopGap","stickyTop","deps","offset","gap","options","useFilterTriggerToggle","open","setOpen","wasOpenAtPointerDown","closedByKit","_temp6","onPointerDown","onClick","humanizeKey","columnHeaderLabel","column","header","key","columnHeaderController","extras","label","sortDir","sortIndex","toggleSort","undefined","resolveColumnHeader","controller","renderHeader","ctx","resolveColumnFooter","value","renderFooter","columnsHaveFooter","columns","some","useCallback","useState","isRtlElement","COLUMN_DND_MIME","columnRowDragProps","key","draggable","onDragStart","event","target","closest","preventDefault","dataTransfer","setData","effectAllowed","isRtl","grip","columnReorderKeyProps","index","move","label","role","tabIndex","onKeyDown","horizontal","vertical","startKey","currentTarget","towardStart","columnDropProps","onDragOver","types","includes","dropEffect","onDrop","getData","useColumnDragState","$","_c","drag","setDrag","overIndex","setOverIndex","t0","Symbol","for","reset","t1","base","defaultPrevented","from","onDragEnd","rowDragProps","t2","index_0","base_0","event_0","event_1","dropProps","t3","key_0","index_1","rowAttrs","t4","t5","draggingKey","useCallback","useRef","useState","useHorizontalOverflow","$","_c","overflowing","setOverflowing","observerRef","t0","Symbol","for","node","current","disconnect","ResizeObserver","measure","scrollWidth","clientWidth","observer","observe","firstElementChild","ref","t1","useCallback","useEffect","useState","PIN_Z","resolveVirtualRows","PINNED_TOP_PART","PINNED_BOTTOM_PART","pinnedRowPart","side","undefined","pinnedRowSticky","sticky","headerOffsetPx","offset","pinnedRowStickyStyle","position","top","zIndex","rowPinned","bottom","pinnedRowCellStyle","columnPinned","edge","rowPinnedColumn","useOffsetHeight","$","_c","node","setNode","height","setHeight","t0","Symbol","for","next","getBoundingClientRect","ref","t1","t2","ResizeObserver","observer","observe","disconnect","t3","orderedCardEntries","rows","getRowId","rowEntries","pinnedTop","pinnedBottom","length","pinnedIds","Set","row","add","indexById","Map","forEach","index","set","asEntry","key","sourceIndex","get","scroll","filter","entry","has","map","isCellEditable","isMultiSelectEditor","isSelectEditor","normalizeEditorOptions","readEditableCellValue","resolveCellEditor","resolveCommitValue","observeEdit","beginCellEdit","beginEdit","editableCellController","options","editing","row","column","rowId","rows","columns","rowKey","idle","mode","validating","isDirty","canRollback","rollback","undefined","dismissFailure","editor","selectOptions","draft","begin","setDraft","commit","cancel","onEditorKeyDown","commitOnBlur","keepConflict","takeConflict","onCellEdit","state","validation","saving","dirty","isEditing","isActive","key","validateCell","asCellValidator","gated","hasRowValidator","sendToHost","resolved","result","value","columnKey","lifecycle","onEditCommit","previousValue","unit","mark","track","previous","attempted","then","saved","confirm","commitNow","commitValidated","verdict","check","target","allowed","error","onValidationFail","close","beginNext","nextRow","find","r","nextCol","c","liveConflict","conflict","isConflict","current","validationError","errorFor","rowErrorFor","conflictLabels","message","isValidating","saveStatus","statusFor","saveFailure","failureFor","clear","pending","event","preventDefault","outcome","handleKeyDown","action","advance","advanceTarget","committed","keep","take","validate","stopCellEditKeyboard","stopPropagation","focusEditorOnMount","node","focus","rowIsDirty","isRowDirty","rowEditingSignature","active","marked","rowHasError","busy","save","signature","rowSave","includes","marks","rowMarks","rowMode","rowEditing","rowDrafts","activeRowId","batchAll","batch","batchRow","split","entry","startsWith","live","conflictMark","incomingValue","base","isCustomEditor","normalizeEditorOptions","resolveCellEditor","focusEditorOnMount","RowEditCell","t0","$","_c","rowEditing","column","display","editLabel","takesFocus","renderEditor","t1","t2","Symbol","for","bb0","editor","focusRef","_temp","t3","key","value","setDraft","t4","event","preventDefault","save","cancel","ctrl","draft","draftFor","onEditorKeyDown","commitOnBlur","_temp2","selectOptions","selectOptionsFor","validating","errorId","render","commit","onKeyDown","onBlur","label","type","options","rowEditControls","row","rowId","labels","editing","isEditing","begin","editRow","saveLabel","saveRow","cancelLabel","dirty","isDirty","RowEditActionsChrome","buttonClassName","className","slots","controls","Button","stopPropagation","gap","event_0","t5","event_1","t6","t7","BatchEditCell","batch","_temp3","_temp4","_temp5","cancelRow","_temp6","isChanged","undefined","BatchEditBarChrome","pending","pendingRows","defaultPendingRows","count","alignItems","saveAll","cancelAll","t8","t9","String","useLayoutEffect","useRef","booleanDraft","formatMultiDraft","isCustomEditor","editableCellController","focusEditorOnMount","stopCellEditKeyboard","BatchEditCell","RowEditCell","isFirstEditableColumn","columns","key","first","find","column","editable","undefined","editorValidationProps","ctrl","error","errorId","validating","conflict","editorBusyProps","describedBy","ConflictNotice","props","errorClassName","slots","Button","conflictLabels","holdFocus","event","preventDefault","message","theirsValue","incomingValue","keepMine","stopPropagation","keepConflict","takeTheirs","takeConflict","commitBooleanDraft","checked","setDraft","commitOnBlur","multiDraftFromSelect","select","selectedOptions","map","option","value","EditableCellGate","activateRef","restoreFocusRef","editing","row","rowId","rows","rowKey","current","mode","focus","batch","display","editLabel","renderEditor","rowEditing","isEditing","onEditorKeyDown","editor","custom","render","draft","commit","cancel","onKeyDown","onBlur","focusRef","label","selectOptions","kitRendersError","Activate","activateClassName","saveStatus","isDirty","node","begin","saveFailure","saveErrorClassName","canRollback","undoLabel","rollbackClassName","rollback","useCallback","useMemo","useRef","useState","getPath","readCellValue","row","column","editValue","sortValue","key","DEFAULT_DEPTH","useEditHistory","options","$","_c","enabled","depth","t0","columns","onCellEdit","undefined","t1","Symbol","for","past","t2","future","t3","counts","setCounts","t4","current","length","sync","t5","find","columnFor","t6","edits","undo","flatMap","edit","column_0","columnKey","value","redo","slice","record","t7","edits_0","edit_0","replay","t8","entry","at","undo_0","t9","entry_0","t10","clear","t11","t12","t13","canUndo","canRedo","useTableEditHistory","props","editHistory","history","nextValue","recording","asGesture","apply","useCallback","useMemo","useState","useSyncExternalStore","EMPTY_ROW_PIN_STATE","useResolvedAdapter","readRowPins","writeRowPins","useRowPinningUrlState","t0","$","_c","t1","undefined","options","urlAdapter","urlSync","urlKey","ns","resolved","t2","t3","onChange","subscribe","getSearch","t4","search","pending","setPending","t5","bb0","t6","URLSearchParams","pinnedRowIds","next","params","setSearch","toString","onPinnedRowIdsChange","t7"],"sources":["../src/utils/devWarn.ts","../src/actions/confirm.ts","../src/actions/useBulkActionRunner.ts","../src/actions/commandRegistry.ts","../src/actions/useShortcuts.ts","../src/columns/columnText.ts","../src/utils/humanizeKey.ts","../src/utils/localeTag.ts","../src/columns/resolveColumns.ts","../src/filters/operators.ts","../src/filters/relativeDates.ts","../src/filters/filterDefs.ts","../src/filters/rangeWidget.ts","../src/filters/filterForm.ts","../src/filters/checklist.ts","../src/filters/facets.ts","../src/filters/filterRegistry.ts","../src/filters/filterBuiltins.ts","../src/filters/filterChrome.ts","../src/virtual/ColumnSpacer.tsx","../src/hooks/useEventCallback.ts","../src/filters/useFilterOptions.ts","../src/filters/FilterHeaderRow.tsx","../src/source/queryContract.ts","../src/filters/filterTree.ts","../src/filters/filterTreeMutations.ts","../src/filters/useFilterTreeChips.ts","../src/find/findMatches.ts","../src/focus/gridFocus.ts","../src/focus/cellRange.ts","../src/find/useFindInTable.ts","../src/focus/cellEdits.ts","../src/focus/clipboardRange.ts","../src/editing/cellEditing.ts","../src/focus/fillRange.ts","../src/focus/pasteRange.ts","../src/focus/selectionStats.ts","../src/focus/useGridFocus.ts","../src/layout/useFullscreen.ts","../src/hooks/useMediaQuery.ts","../src/hooks/usePrefersReducedMotion.ts","../src/utils/stableKey.ts","../src/constants.ts","../src/hooks/useIsMobile.ts","../src/url/useTableUrlState.ts","../src/source/useServerData.ts","../src/grouping/groupRows.ts","../src/rows/incrementalAggregate.ts","../src/rows/incrementalGroup.ts","../src/rows/patch.ts","../src/rows/incremental.ts","../src/source/useFrontendData.ts","../src/source/useTableData.ts","../src/columns/headerGroups.ts","../src/columns/columnTree.ts","../src/columns/columnWidths.ts","../src/columns/useColumnLayout.ts","../src/columns/columnMenuModel.ts","../src/columns/responsiveColumns.ts","../src/editing/editingEvents.ts","../src/editing/batchEditing.ts","../src/editing/dirtyCells.ts","../src/editing/editConflict.ts","../src/editing/rowEditing.ts","../src/editing/saveState.ts","../src/editing/useCellEditing.ts","../src/editing/validation.ts","../src/filters/useActiveFilterChips.ts","../src/grouping/groupKeys.ts","../src/grouping/useGroupCollapse.ts","../src/grouping/useGroupPaging.ts","../src/hooks/useInfiniteScroll.ts","../src/hooks/useScrollToTableTop.ts","../src/layout/useElementWidth.ts","../src/rows/rowStyle.ts","../src/rows/extraRows.ts","../src/rows/rowMutations.ts","../src/rows/rowPinning.ts","../src/rows/rowReorder.ts","../src/rows/useRowExpansion.ts","../src/source/queryGroups.ts","../src/state/errorState.ts","../src/export/exportView.ts","../src/export/tableCsv.ts","../src/state/featureNotices.ts","../src/tree/nestedTable.tsx","../src/tree/treeRows.ts","../src/tree/useLazyChildren.ts","../src/tree/useTreeExpansion.ts","../src/columns/columnSizing.ts","../src/columns/visibleColumns.ts","../src/filters/useExtraChips.ts","../src/pagination/paginationMath.ts","../src/grouping/groupSelection.ts","../src/selection/useSelection.ts","../src/sort/cycleSort.ts","../src/sort/sortByOptions.ts","../src/utils/mergeProps.ts","../src/hooks/useDebounce.ts","../src/useDataTable/useSearchInput.ts","../src/useDataTable/useDataTable.ts","../src/virtual/measureRowPair.ts","../src/virtual/useTableVirtualization.ts","../src/virtual/windowScrollMargin.ts","../src/useTableChrome.ts","../src/columns/columnHeader.ts","../src/columns/columnReorder.ts","../src/layout/useHorizontalOverflow.ts","../src/rows/pinnedRowChrome.ts","../src/editing/editableCellController.ts","../src/editing/RowEditGate.tsx","../src/editing/EditableCellGate.tsx","../src/editing/editHistory.ts","../src/url/useRowPinningUrlState.ts"],"sourcesContent":["/** Minimal shape of a Node-style `process` global, typed locally so the\n * package needs no Node type dependency. */\ninterface ProcessLike {\n env?: Record;\n}\n\n/** True outside production builds. Bundlers inline `NODE_ENV` and drop the\n * dev-only branches; without a bundler (plain browser) this stays on. */\nfunction isDev(): boolean {\n const proc = (globalThis as { process?: ProcessLike }).process;\n return proc?.env?.NODE_ENV !== \"production\";\n}\n\nconst seen = new Set();\n\n/**\n * Log a development-only warning once per unique message. Silent in\n * production builds, never throws — safe to call from render paths via\n * effects. Used for misconfiguration that would otherwise fail silently\n * (a sort that cannot resolve, duplicate column keys, …).\n */\nexport function devWarn(message: string): void {\n if (!isDev() || seen.has(message)) return;\n seen.add(message);\n console.warn(`[adapttable] ${message}`);\n}\n\n/** Test-only seam: forget which warnings have fired. */\nexport function resetDevWarnings(): void {\n seen.clear();\n}\n","import type { RowAction } from \"../types\";\nimport { devWarn } from \"../utils/devWarn\";\n\n/** A confirmation request raised by a row or bulk action. */\nexport interface ConfirmRequest {\n /** Dialog title. */\n title: string;\n /** Dialog message. */\n message: string;\n /** Confirm button label. */\n confirmLabel: string;\n /** Cancel button label. */\n cancelLabel: string;\n /** Marks the action destructive. */\n danger?: boolean;\n /** Runs when the user accepts. */\n onConfirm: () => void;\n}\n\n/** Shows a confirmation, then runs `onConfirm` if accepted. */\nexport type ConfirmHandler = (request: ConfirmRequest) => void;\n\n/**\n * The default confirmation handler — a dependency-free `window.confirm`.\n * Adapters pass a styled handler when they have one.\n *\n * When no dialog exists at all (SSR, jsdom, some embedded webviews) the\n * action is DENIED: an environment that cannot ask must never approve a\n * destructive action on the user's behalf. Integrators in dialogless\n * environments pass their own `confirm` handler.\n */\nexport const defaultConfirm: ConfirmHandler = ({ message, onConfirm }) => {\n const native = (globalThis as { confirm?: (m?: string) => boolean }).confirm;\n if (typeof native !== \"function\") {\n devWarn(\n \"no confirm dialog is available in this environment — the action was NOT run. Pass a `confirm` handler to support dialogless environments.\"\n );\n return;\n }\n if (native(message)) onConfirm();\n};\n\n/**\n * Normalize a `disabledReason` result. Per the action contract only a\n * *non-empty* string disables, so an empty string maps to `undefined` —\n * letting every adapter treat \"disabled\" as simply \"reason is defined\" and\n * fall back to the action label for tooltips. (A plain `|| undefined` would\n * trip `prefer-nullish-coalescing`; this keeps the falsy-empty intent.)\n */\nexport function resolveDisabledReason(\n reason: string | undefined\n): string | undefined {\n return reason !== undefined && reason !== \"\" ? reason : undefined;\n}\n\n/**\n * Run a row action, routing through `confirm` first when the action\n * declares a `confirm` block.\n *\n * @typeParam TRow - The row type.\n * @param action - The action to run.\n * @param row - The row it was triggered on.\n * @param confirm - The confirmation handler.\n * @param cancelLabel - Cancel label for the dialog.\n */\nexport function runRowAction(\n action: RowAction,\n row: TRow,\n confirm: ConfirmHandler,\n cancelLabel: string\n): void {\n if (!action.confirm) {\n action.onClick(row);\n return;\n }\n confirm({\n title: action.confirm.title,\n message: action.confirm.message(row),\n confirmLabel: action.confirm.confirmLabel,\n cancelLabel,\n danger: action.confirm.danger,\n onConfirm: () => action.onClick(row),\n });\n}\n","import { useCallback, useState } from \"react\";\n\nimport type { BulkAction, BulkActionContext } from \"../types\";\nimport type { ConfirmHandler } from \"./confirm\";\n\n/** A bulk-action rejection as display text, or `null` when there is none. */\nexport function bulkActionErrorMessage(error: unknown): string | null {\n if (error == null) return null;\n if (error instanceof Error) return error.message;\n if (typeof error === \"string\") return error;\n if (\n typeof error === \"number\" ||\n typeof error === \"boolean\" ||\n typeof error === \"bigint\"\n ) {\n return String(error);\n }\n try {\n return JSON.stringify(error) ?? \"Unknown error\";\n } catch {\n return \"Unknown error\";\n }\n}\n\n/** How a bulk-action run ended — passed to `onComplete` on every run. */\nexport type BulkActionOutcome =\n | { status: \"success\" }\n | { status: \"error\"; error: unknown };\n\n/** Options for {@link useBulkActionRunner}. */\nexport interface UseBulkActionRunnerOptions {\n /** Confirmation handler for actions that declare a `confirm` block. */\n confirm: ConfirmHandler;\n /** Cancel label for confirm dialogs. */\n cancelLabel: string;\n /**\n * Called after EVERY run with its outcome — success or failure — so a\n * host can clear the selection on success and report failures. (Earlier\n * versions only called this on success, with no argument.)\n */\n onComplete?: (outcome: BulkActionOutcome) => void;\n}\n\n/** The runner returned by {@link useBulkActionRunner}. */\nexport interface BulkActionRunner {\n /** Key of the action currently running, or `null`. */\n pending: string | null;\n /**\n * The value the last run rejected with, or `null`. Cleared when the\n * next run starts.\n */\n error: unknown;\n /**\n * Run a bulk action against the given ids (confirming first if needed).\n * Omit `context` for the plain page-selection scope.\n */\n run: (action: BulkAction, ids: string[], context?: BulkActionContext) => void;\n}\n\n/**\n * Headless runner for bulk actions: tracks the in-flight action key,\n * routes through the confirmation handler, catches rejections (exposed as\n * `error`, never an unhandled rejection), and calls `onComplete` with the\n * outcome of every run. Adapters render the buttons and call `run`.\n *\n * @param options - See {@link UseBulkActionRunnerOptions}.\n * @returns The {@link BulkActionRunner}.\n */\nexport function useBulkActionRunner({\n confirm,\n cancelLabel,\n onComplete,\n}: UseBulkActionRunnerOptions): BulkActionRunner {\n const [pending, setPending] = useState(null);\n const [error, setError] = useState(null);\n\n const run = useCallback(\n (action: BulkAction, ids: string[], context?: BulkActionContext) => {\n if (ids.length === 0) return;\n const scope: BulkActionContext = context ?? {\n allMatching: false,\n total: ids.length,\n };\n const fire = async () => {\n try {\n setPending(action.key);\n setError(null);\n await action.onClick(ids, scope);\n onComplete?.({ status: \"success\" });\n } catch (error_) {\n setError(error_);\n onComplete?.({ status: \"error\", error: error_ });\n } finally {\n setPending(null);\n }\n };\n if (action.confirm) {\n confirm({\n title: action.confirm.title,\n // The confirm count reflects the SCOPE: the whole matching set\n // when \"select all matching\" is active, the page ids otherwise.\n message: action.confirm.message(scope.total),\n confirmLabel: action.confirm.confirmLabel,\n cancelLabel,\n danger: action.confirm.danger,\n onConfirm: () => void fire(),\n });\n } else {\n void fire();\n }\n },\n [confirm, cancelLabel, onComplete]\n );\n\n return { pending, error, run };\n}\n","/**\n * Every action the table can perform, in one list.\n *\n * A command palette that keeps its own list of commands is a second place\n * for an action to exist, and the two drift: an action gains a condition in\n * the menu and not in the palette, or is renamed in one and not the other,\n * and the palette quietly offers something that no longer works. So there\n * is no palette-shaped command type here. A command IS a\n * {@link ContextMenuItem} — the same object the context menus already\n * render — and the palette is another way of showing the same list.\n *\n * What a palette adds is reach. A context menu is scoped to what was\n * right-clicked; a palette is scoped to the table, so it carries the\n * actions that have no particular target — print, export, clear the\n * filters — alongside the ones a menu would offer for the current\n * selection.\n *\n * Filtering is a plain substring match, case- and accent-insensitive.\n * Fuzzy matching is a good default for a file switcher with thousands of\n * paths and a poor one for a list of a dozen actions, where it mostly\n * finds the wrong entry with a high score.\n */\nimport type { ContextMenuItem } from \"./contextMenuModel\";\n\n/** A command, which is exactly a menu entry. */\nexport type Command = ContextMenuItem;\n\n/** One command, with the text a search matches against. */\ninterface Searchable {\n item: Command;\n haystack: string;\n}\n\n/**\n * Fold accents and case so a search for \"resume\" finds \"Résumé\".\n *\n * Someone typing into a palette is typing quickly, from memory, in\n * whatever keyboard layout they have. Making them reproduce diacritics is\n * a way of hiding an action from them.\n */\nfunction fold(text: string): string {\n return text\n .normalize(\"NFD\")\n .replace(/\\p{Diacritic}/gu, \"\")\n .toLowerCase();\n}\n\nfunction searchable(item: Command): Searchable {\n return { item, haystack: fold(item.label) };\n}\n\n/**\n * The commands matching a query, in the order they were registered.\n *\n * Registration order is deliberate: it is the order the host chose, which\n * is more meaningful than alphabetical and does not move under the user as\n * they type. An empty query lists everything.\n *\n * @param commands - Every command available right now.\n * @param query - What the user has typed.\n * @returns The matches.\n */\nexport function filterCommands(\n commands: readonly Command[],\n query: string\n): Command[] {\n const needle = fold(query.trim());\n if (needle === \"\") return [...commands];\n return commands\n .map(searchable)\n .filter(({ haystack }) => haystack.includes(needle))\n .map(({ item }) => item);\n}\n\n/** What {@link tableCommands} needs to build the table-wide actions. */\nexport interface TableCommandOptions {\n /** Labels for the built-in commands. */\n labels: {\n print?: string;\n exportCsv?: string;\n clearAll?: string;\n };\n /** Open the print dialog on the current view. */\n onPrint?: () => void;\n /** Run the export the toolbar button runs. */\n onExport?: () => void;\n /** Clear every active filter. */\n onClearFilters?: () => void;\n /** Whether there is anything to clear, so the entry can say so. */\n hasFilters?: boolean;\n}\n\n/**\n * The commands that belong to the table rather than to a target.\n *\n * Each appears only when its handler is wired, on the same rule the\n * context menus follow: an action the host has not connected is not\n * offered, because a palette entry that does nothing is worse than one\n * that is missing.\n *\n * @param options - The handlers and their labels.\n * @returns The table-wide commands, in display order.\n */\nexport function tableCommands(options: TableCommandOptions): Command[] {\n const { labels } = options;\n const commands: Command[] = [];\n if (options.onPrint) {\n commands.push({\n key: \"print\",\n label: labels.print ?? \"Print\",\n onSelect: options.onPrint,\n });\n }\n if (options.onExport) {\n commands.push({\n key: \"export\",\n label: labels.exportCsv ?? \"Export CSV\",\n onSelect: options.onExport,\n });\n }\n if (options.onClearFilters) {\n commands.push({\n key: \"clear-filters\",\n label: labels.clearAll ?? \"Clear all\",\n disabled: options.hasFilters !== true,\n onSelect: options.onClearFilters,\n });\n }\n return commands;\n}\n","/**\n * Keyboard shortcuts, as a list the host can read and change.\n *\n * A shortcut hard-coded in a key handler is a shortcut nobody can remap,\n * and remapping is not a preference — it is the difference between a table\n * that works inside an application and one that fights it. The host's app\n * may already own Ctrl+K. Its users may be on a layout where the default\n * is awkward, or using software that has claimed the chord.\n *\n * So a shortcut is data: a chord, and the command key it runs. The\n * defaults are the ones people already know, and any of them can be\n * replaced or removed by passing a different list.\n *\n * Matching deliberately ignores the physical key's layout — `event.key` is\n * the character the user's layout produces, which is what they typed and\n * what the shortcut was written as. It is compared case-insensitively,\n * because Shift is part of the chord rather than part of the letter.\n */\nimport { useEffect } from \"react\";\n\n/** One shortcut: the chord, and what it runs. */\nexport interface Shortcut {\n /**\n * The chord, as `\"mod+k\"`. `mod` is Cmd on a Mac and Ctrl elsewhere,\n * which is the only way to write one shortcut that is right on both.\n * Also accepts `ctrl`, `meta`, `alt` and `shift`.\n */\n chord: string;\n /** The key of the command it runs. */\n command: string;\n}\n\n/** The shortcuts a table has unless the host says otherwise. */\nexport const DEFAULT_SHORTCUTS: readonly Shortcut[] = [\n { chord: \"mod+k\", command: \"command-palette\" },\n];\n\ninterface Chord {\n key: string;\n mod: boolean;\n ctrl: boolean;\n meta: boolean;\n alt: boolean;\n shift: boolean;\n}\n\nfunction parseChord(chord: string): Chord {\n const parts = chord.toLowerCase().split(\"+\");\n const key = parts.at(-1) ?? \"\";\n return {\n key,\n mod: parts.includes(\"mod\"),\n ctrl: parts.includes(\"ctrl\"),\n meta: parts.includes(\"meta\"),\n alt: parts.includes(\"alt\"),\n shift: parts.includes(\"shift\"),\n };\n}\n\n/** Whether an event is this chord. */\nfunction matches(chord: Chord, event: KeyboardEvent): boolean {\n if (event.key.toLowerCase() !== chord.key) return false;\n // `mod` is satisfied by either, so one chord is right on every platform\n // without the host writing two.\n const mod = event.metaKey || event.ctrlKey;\n if (chord.mod ? !mod : false) return false;\n if (chord.ctrl && !event.ctrlKey) return false;\n if (chord.meta && !event.metaKey) return false;\n if (chord.alt !== event.altKey) return false;\n if (chord.shift !== event.shiftKey) return false;\n // A chord with no modifier must not fire while a modifier is held, or\n // \"e\" would trigger inside Ctrl+E.\n return chord.mod || chord.ctrl || chord.meta ? true : !mod;\n}\n\n/**\n * True while the event came from somewhere text is being typed.\n *\n * A single-key shortcut must not fire while someone is filling in the\n * search box or a cell editor. Chords with a modifier still work there,\n * because that is what a modifier is for.\n */\nfunction inTextEntry(target: EventTarget | null): boolean {\n if (!(target instanceof HTMLElement)) return false;\n const tag = target.tagName;\n return (\n tag === \"INPUT\" ||\n tag === \"TEXTAREA\" ||\n tag === \"SELECT\" ||\n target.isContentEditable\n );\n}\n\n/** What {@link useShortcuts} needs. */\nexport interface UseShortcutsOptions {\n /** Off unless the host armed it; nothing is bound when false. */\n enabled: boolean;\n /** The shortcuts. Defaults to {@link DEFAULT_SHORTCUTS}. */\n shortcuts?: readonly Shortcut[];\n /** Run a command by key. Returning nothing is fine. */\n onCommand: (command: string) => void;\n /**\n * Where to listen. Defaults to the document, which is what a\n * table-scoped palette wants: the shortcut has to work when focus is on\n * the table, in its toolbar, or nowhere in particular.\n */\n target?: () => EventTarget | null;\n}\n\n/**\n * Bind a table's shortcuts.\n *\n * @param options - The shortcuts and what to do when one fires.\n */\nexport function useShortcuts(options: UseShortcutsOptions): void {\n const { enabled, onCommand } = options;\n const shortcuts = options.shortcuts ?? DEFAULT_SHORTCUTS;\n const getTarget = options.target;\n useEffect(() => {\n if (!enabled || shortcuts.length === 0) return;\n const parsed = shortcuts.map((shortcut) => ({\n chord: parseChord(shortcut.chord),\n command: shortcut.command,\n }));\n const node = getTarget?.() ?? document;\n const onKeyDown = (event: Event) => {\n if (!(event instanceof KeyboardEvent)) return;\n for (const { chord, command } of parsed) {\n const bare = !chord.mod && !chord.ctrl && !chord.meta;\n if (bare && inTextEntry(event.target)) continue;\n if (!matches(chord, event)) continue;\n event.preventDefault();\n onCommand(command);\n return;\n }\n };\n node.addEventListener(\"keydown\", onKeyDown);\n return () => {\n node.removeEventListener(\"keydown\", onKeyDown);\n };\n }, [enabled, shortcuts, onCommand, getTarget]);\n}\n","/**\n * A column's cell as plain text.\n *\n * Everything that is not the rendered cell needs this and cannot use\n * `accessor`, because `accessor` returns a `ReactNode`: a status badge is a\n * React element, an avatar cell is a component, and neither is a word. So a\n * screen-reader announcement, an `aria-label`, a tooltip, or a clipboard copy\n * has nothing to read — which is exactly the hole that showed up the moment\n * the grid focus model had to say a cell out loud.\n *\n * Text is always available here. The order goes from most deliberate to most\n * inferred:\n *\n * 1. `formatValue` — the column stating its own text.\n * 2. `exportValue` — already the underlying value, minus the formatting.\n * 3. `sortValue` — a primitive by definition.\n * 4. `accessor` — used only when it happens to return a primitive.\n * 5. the key's data path — but ONLY for a column that renders no cell of its\n * own, because that is the only case where the path is what is on screen.\n *\n * That last restriction is the whole accessibility point. A column with\n * `accessor: () => null` renders an empty cell; reading its data path would\n * announce a value the user cannot see, which is worse than announcing\n * nothing. Such a column gets `\"\"` — and the fix is to give it a\n * `formatValue`, which is exactly what the field is for.\n */\nimport type { ColumnDef } from \"../types\";\nimport { getPath } from \"../utils/path\";\n\n/** Primitives read as themselves; a date reads as its ISO day. */\nfunction asText(value: unknown): string | undefined {\n if (typeof value === \"string\") return value;\n if (typeof value === \"number\" || typeof value === \"boolean\") {\n return String(value);\n }\n if (value instanceof Date) return value.toISOString().slice(0, 10);\n return undefined;\n}\n\n/**\n * The text for one cell — never `undefined`, so a caller never has to decide\n * what to say when a column declines to answer.\n *\n * @typeParam TRow - The row type.\n * @param column - The column being read.\n * @param row - The row being read.\n * @returns The cell as text, or `\"\"` when the column holds nothing readable.\n */\nexport function columnText(column: ColumnDef, row: TRow): string {\n if (column.formatValue) return column.formatValue(row);\n\n // A column that renders its own cell does not get the data path as a\n // fallback: the path is not what is on screen. `resolveColumns` generates an\n // accessor FROM the path for a bare `{ key }` column, so that case is\n // already covered by the accessor branch.\n const rendersOwnCell = Boolean(column.accessor ?? column.Cell);\n const candidates = [\n column.exportValue?.(row),\n column.sortValue?.(row),\n column.accessor?.(row),\n rendersOwnCell ? undefined : getPath(row, column.key),\n ];\n for (const candidate of candidates) {\n const text = asText(candidate);\n // An empty string is a real answer — a column that says \"nothing here\"\n // must not fall through to a data path that says something else.\n if (text !== undefined) return text;\n }\n return \"\";\n}\n","/**\n * Default column-header text from a key: the last dot-path segment, split on\n * camelCase / snake_case / kebab-case boundaries and title-cased.\n * `\"hiredAt\"` → `\"Hired At\"`, `\"department.name\"` → `\"Name\"`,\n * `\"first_name\"` → `\"First Name\"`. An empty/undefined `key` returns `\"\"` so a\n * transiently-malformed column key can never crash a render.\n */\nexport function humanizeKey(key: string): string {\n if (!key) return \"\";\n // `split` always yields at least one element, so the last one exists.\n const segment = key.split(\".\").at(-1)!;\n const words = segment\n .replaceAll(/([a-z\\d])([A-Z])/g, \"$1 $2\")\n .replaceAll(/[_-]+/g, \" \")\n .trim()\n .split(/\\s+/);\n return words.map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join(\" \");\n}\n","/**\n * ONE locale-tag resolution for everything locale-shaped: label presets\n * (`@adapttable/i18n`) and per-column `i18n` data paths resolve through\n * the same rules, so `locale=\"ar_EG\"` can never pick Arabic labels while\n * missing the Arabic column paths.\n */\n\n/** Normalize a BCP-47-ish tag: trim, `_` → `-`, lower-case. */\nexport function normalizeLocaleTag(locale: string): string {\n return locale.trim().replaceAll(\"_\", \"-\").toLowerCase();\n}\n\n/**\n * Resolve a locale against a set of available tags: the exact tag first\n * (case- and separator-insensitive), then its primary subtag. Returns the\n * ORIGINAL available tag so callers can index their own maps with it.\n */\nexport function resolveLocaleTag(\n available: Iterable,\n locale: string\n): string | undefined {\n const target = normalizeLocaleTag(locale);\n const tags = [...available];\n const exact = tags.find((tag) => normalizeLocaleTag(tag) === target);\n if (exact !== undefined) return exact;\n const primary = target.split(\"-\", 1)[0]!;\n return tags.find((tag) => normalizeLocaleTag(tag) === primary);\n}\n","import type { ColumnDef } from \"../types\";\nimport { humanizeKey } from \"../utils/humanizeKey\";\nimport { resolveLocaleTag } from \"../utils/localeTag\";\nimport { getPath } from \"../utils/path\";\n\n/** Cell content from a dot-path value: primitives render, anything else does not. */\nfunction pathCell(value: unknown): string | null {\n switch (typeof value) {\n case \"string\":\n return value;\n case \"number\":\n case \"boolean\":\n case \"bigint\":\n return String(value);\n default:\n return null;\n }\n}\n\n/**\n * The data path a column reads for the active locale: the exact locale tag\n * first (`\"ar-EG\"`), then its primary subtag (`\"ar\"`), then the key itself.\n * Works for flat per-language fields and nested objects alike — both are\n * just paths.\n */\nexport function localizedColumnPath(\n column: Pick, \"key\" | \"i18n\">,\n locale: string | undefined\n): string {\n if (!column.i18n || !locale) return column.key;\n // The SAME resolution the label presets use (case- and separator-\n // insensitive, exact tag then primary subtag) — `\"ar_EG\"` must not get\n // Arabic labels while missing the Arabic data paths.\n const tag = resolveLocaleTag(Object.keys(column.i18n), locale);\n return (tag !== undefined ? column.i18n[tag] : undefined) ?? column.key;\n}\n\n/**\n * Fill a column's declarative defaults: a missing `header` is humanized from\n * the key, and a column without `accessor`/`Cell` reads the row by its\n * locale-resolved data path (`i18n` map, else `key` — dot paths reach nested\n * values). Client-side sorting follows the generated accessor, so localized\n * columns sort by the localized text. Already-complete columns pass through\n * untouched, so the resolution is idempotent and cheap to repeat.\n */\nexport function resolveColumns(\n columns: readonly ColumnDef[],\n locale?: string\n): ColumnDef[] {\n return columns.map((column) => {\n const needsHeader = column.header === undefined;\n const needsAccessor = !column.accessor && !column.Cell;\n if (!needsHeader && !needsAccessor) return column;\n const path = localizedColumnPath(column, locale);\n return {\n ...column,\n header: needsHeader ? humanizeKey(column.key) : column.header,\n accessor: needsAccessor\n ? (row: TRow) => pathCell(getPath(row, path))\n : column.accessor,\n };\n });\n}\n","/**\n * Filter-operator registry. Each built-in type declares the operators it\n * understands; the token written to `f_Op` is the stable URL / Saved\n * Views / query-contract id. Omitting the param keeps the historical\n * default so existing links keep matching.\n */\nimport type { ExtraFilters, FilterValue, TableLabels } from \"../types\";\n\n/** Suffix on the filter key that stores the operator token (`name` → `nameOp`). */\nexport const FILTER_OP_SUFFIX = \"Op\";\n\n/** The extra-bag / `f_` key that holds one definition's operator. */\nexport function filterOpKey(key: string): string {\n return key + FILTER_OP_SUFFIX;\n}\n\n/** True when `key` is an operator slot (`nameOp`), not a value slot. */\nexport function isFilterOpKey(key: string): boolean {\n return key.endsWith(FILTER_OP_SUFFIX) && key.length > FILTER_OP_SUFFIX.length;\n}\n\n/** Text comparison operators. Default when `f_Op` is absent: `contains`. */\nexport const TEXT_OPS = [\n \"eq\",\n \"neq\",\n \"contains\",\n \"notContains\",\n \"startsWith\",\n \"endsWith\",\n \"empty\",\n \"notEmpty\",\n] as const;\n\n/** Number comparison operators. Absent `Op` infers from the Min/Max pair. */\nexport const NUMBER_OPS = [\n \"eq\",\n \"neq\",\n \"gt\",\n \"gte\",\n \"lt\",\n \"lte\",\n \"between\",\n \"in\",\n \"notIn\",\n] as const;\n\n/**\n * Date comparison operators. `on` / `gte` / `lte` keep the inclusive-day\n * behaviour existing links already encode; `before` / `after` are exclusive.\n */\nexport const DATE_OPS = [\n \"before\",\n \"after\",\n \"on\",\n \"gte\",\n \"lte\",\n \"between\",\n \"relative\",\n \"empty\",\n] as const;\n\n/** One text operator token. */\nexport type TextOp = (typeof TEXT_OPS)[number];\n/** One number operator token. */\nexport type NumberOp = (typeof NUMBER_OPS)[number];\n/** One date operator token. */\nexport type DateOp = (typeof DATE_OPS)[number];\n/** Any built-in operator token. */\nexport type FilterOp = TextOp | NumberOp | DateOp;\n\nconst TEXT_OP_SET = new Set(TEXT_OPS);\nconst NUMBER_OP_SET = new Set(NUMBER_OPS);\nconst DATE_OP_SET = new Set(DATE_OPS);\n\n/** True for operators that take no operand (`empty` / `notEmpty`). */\nexport function isValuelessFilterOp(op: string): boolean {\n return op === \"empty\" || op === \"notEmpty\";\n}\n\n/** True for operators that take a comma-separated list (`in` / `notIn`). */\nexport function isListFilterOp(op: string): boolean {\n return op === \"in\" || op === \"notIn\";\n}\n\n/** True for the two-bound `between` operator. */\nexport function isBetweenFilterOp(op: string): boolean {\n return op === \"between\";\n}\n\n/** `TableLabels` key for each text operator (widget + chip wording). */\nexport const TEXT_OP_LABEL_KEYS = {\n eq: \"opEqual\",\n neq: \"opNotEqual\",\n contains: \"opContains\",\n notContains: \"opNotContains\",\n startsWith: \"opStartsWith\",\n endsWith: \"opEndsWith\",\n empty: \"opEmpty\",\n notEmpty: \"opNotEmpty\",\n} as const satisfies Record;\n\n/** `TableLabels` key for each number operator. */\nexport const NUMBER_OP_LABEL_KEYS = {\n eq: \"opEqual\",\n neq: \"opNotEqual\",\n gt: \"opGreater\",\n gte: \"opAtLeast\",\n lt: \"opLess\",\n lte: \"opAtMost\",\n between: \"opBetween\",\n in: \"opIn\",\n notIn: \"opNotIn\",\n} as const satisfies Record;\n\n/** `TableLabels` key for each date operator. */\nexport const DATE_OP_LABEL_KEYS = {\n before: \"opBefore\",\n after: \"opAfter\",\n on: \"opOn\",\n gte: \"opOnOrAfter\",\n lte: \"opOnOrBefore\",\n between: \"opBetween\",\n relative: \"opRelative\",\n empty: \"opEmpty\",\n} as const satisfies Record;\n\n/** Parse a text operator; unknown / missing → `contains` (historical default). */\nexport function parseTextOp(raw: FilterValue | undefined): TextOp {\n if (typeof raw === \"string\" && TEXT_OP_SET.has(raw)) return raw as TextOp;\n return \"contains\";\n}\n\n/** Parse a number operator, or `undefined` when the token is absent/unknown. */\nexport function parseNumberOp(\n raw: FilterValue | undefined\n): NumberOp | undefined {\n if (typeof raw === \"string\" && NUMBER_OP_SET.has(raw)) {\n return raw as NumberOp;\n }\n return undefined;\n}\n\n/** Parse a date operator, accepting `eq` as the historical spelling of `on`. */\nexport function parseDateOp(raw: FilterValue | undefined): DateOp | undefined {\n if (raw === \"eq\") return \"on\";\n if (typeof raw === \"string\" && DATE_OP_SET.has(raw)) return raw as DateOp;\n return undefined;\n}\n\n/** Read the operator token stored beside a filter key. */\nexport function readFilterOp(\n extra: ExtraFilters,\n key: string\n): FilterValue | undefined {\n return extra[filterOpKey(key)];\n}\n\n/** True when a row value counts as empty for `empty` / `notEmpty`. */\nexport function isEmptyRowValue(value: unknown): boolean {\n if (value == null) return true;\n if (typeof value === \"string\") return value.trim() === \"\";\n if (value instanceof Date) return Number.isNaN(value.getTime());\n return false;\n}\n\n/** Split a list operand (`in` / `notIn`) into trimmed, non-empty tokens. */\nexport function parseListOperand(value: FilterValue | undefined): string[] {\n if (Array.isArray(value)) {\n return value.map((entry) => String(entry).trim()).filter(Boolean);\n }\n if (value == null || value === \"\") return [];\n return String(value)\n .split(\",\")\n .map((entry) => entry.trim())\n .filter(Boolean);\n}\n\n/** Parse a list operand as finite numbers (unknown tokens dropped). */\nexport function parseNumberList(value: FilterValue | undefined): number[] {\n const out: number[] = [];\n for (const token of parseListOperand(value)) {\n const n = Number(token);\n if (Number.isFinite(n)) out.push(n);\n }\n return out;\n}\n\n/**\n * Chip text: `Name contains Ada`, or `Name is empty` when there is no\n * operand. The operator word is already localized by the caller.\n */\nexport function formatFilterChip(\n fieldLabel: string,\n opWord: string,\n value?: string\n): string {\n if (value == null || value === \"\") return `${fieldLabel} ${opWord}`;\n return `${fieldLabel} ${opWord} ${value}`;\n}\n","/**\n * Relative date tokens. The URL and Saved Views store the token, never a\n * resolved calendar day — \"last 7 days\" stays the last 7 days tomorrow.\n * {@link resolveRelativeRange} is the only place a token becomes a window.\n */\n\nconst DAY_MS = 86_400_000;\nconst END_OF_DAY_MS = DAY_MS - 1;\n\n/** Named windows that need no extra number. */\nexport const RELATIVE_NAMED = [\n \"today\",\n \"yesterday\",\n \"tomorrow\",\n \"thisWeek\",\n \"thisMonth\",\n \"previousMonth\",\n] as const;\n\n/** A stored relative-date token (`last:7`, `today`, …). */\nexport type RelativeDateToken =\n | (typeof RELATIVE_NAMED)[number]\n | `last:${number}`\n | `next:${number}`;\n\n/** Inclusive local-time window a token resolves to. */\nexport interface RelativeDateRange {\n startMs: number;\n endMs: number;\n}\n\nconst NAMED = new Set(RELATIVE_NAMED);\n\nfunction startOfDay(now: Date): Date {\n return new Date(now.getFullYear(), now.getMonth(), now.getDate());\n}\n\nfunction endOfDay(day: Date): number {\n return day.getTime() + END_OF_DAY_MS;\n}\n\nfunction addDays(day: Date, days: number): Date {\n return new Date(day.getFullYear(), day.getMonth(), day.getDate() + days);\n}\n\n/** Monday 00:00 of the week that contains `now` (ISO week). */\nfunction startOfIsoWeek(now: Date): Date {\n const day = startOfDay(now);\n const weekday = day.getDay();\n const mondayOffset = weekday === 0 ? -6 : 1 - weekday;\n return addDays(day, mondayOffset);\n}\n\n/**\n * Parse a stored token. Unknown strings (including ISO dates) return\n * `undefined` so a historical absolute bound is never treated as relative.\n */\nexport function parseRelativeToken(\n raw: string | undefined\n): RelativeDateToken | undefined {\n if (raw == null || raw === \"\") return undefined;\n if (NAMED.has(raw)) return raw as RelativeDateToken;\n const counted = /^(last|next):(\\d+)$/.exec(raw);\n if (!counted) return undefined;\n const n = Number(counted[2]);\n if (!Number.isInteger(n) || n < 1) return undefined;\n return `${counted[1] as \"last\" | \"next\"}:${n}`;\n}\n\n/** True when `raw` is a relative token, not an absolute date. */\nexport function isRelativeDateToken(raw: string | undefined): boolean {\n return parseRelativeToken(raw) !== undefined;\n}\n\nfunction namedRange(\n token: (typeof RELATIVE_NAMED)[number],\n now: Date\n): RelativeDateRange {\n const today = startOfDay(now);\n if (token === \"today\") {\n return { startMs: today.getTime(), endMs: endOfDay(today) };\n }\n if (token === \"yesterday\") {\n const day = addDays(today, -1);\n return { startMs: day.getTime(), endMs: endOfDay(day) };\n }\n if (token === \"tomorrow\") {\n const day = addDays(today, 1);\n return { startMs: day.getTime(), endMs: endOfDay(day) };\n }\n if (token === \"thisWeek\") {\n const start = startOfIsoWeek(now);\n return { startMs: start.getTime(), endMs: endOfDay(addDays(start, 6)) };\n }\n if (token === \"thisMonth\") {\n const start = new Date(now.getFullYear(), now.getMonth(), 1);\n const end = new Date(now.getFullYear(), now.getMonth() + 1, 0);\n return { startMs: start.getTime(), endMs: endOfDay(end) };\n }\n const start = new Date(now.getFullYear(), now.getMonth() - 1, 1);\n const end = new Date(now.getFullYear(), now.getMonth(), 0);\n return { startMs: start.getTime(), endMs: endOfDay(end) };\n}\n\n/**\n * Resolve a token against `now` (defaults to the current instant). The\n * frontend predicate and the server query path must both call this so a\n * shared link and a live table agree.\n */\nexport function resolveRelativeRange(\n raw: string | undefined,\n now: number | Date = Date.now()\n): RelativeDateRange | undefined {\n const token = parseRelativeToken(raw);\n if (!token) return undefined;\n const instant = now instanceof Date ? now : new Date(now);\n if (token.startsWith(\"last:\")) {\n const n = Number(token.slice(5));\n const today = startOfDay(instant);\n const start = addDays(today, -(n - 1));\n return { startMs: start.getTime(), endMs: endOfDay(today) };\n }\n if (token.startsWith(\"next:\")) {\n const n = Number(token.slice(5));\n const today = startOfDay(instant);\n const end = addDays(today, n - 1);\n return { startMs: today.getTime(), endMs: endOfDay(end) };\n }\n return namedRange(token as (typeof RELATIVE_NAMED)[number], instant);\n}\n\n/** Build a counted token (`last:7`). `n` below 1 becomes 1. */\nexport function countedRelativeToken(\n kind: \"last\" | \"next\",\n n: number\n): RelativeDateToken {\n const count = Number.isFinite(n) && n >= 1 ? Math.floor(n) : 1;\n return `${kind}:${count}`;\n}\n\nconst NAMED_LABEL_KEYS = {\n today: \"relToday\",\n yesterday: \"relYesterday\",\n tomorrow: \"relTomorrow\",\n thisWeek: \"relThisWeek\",\n thisMonth: \"relThisMonth\",\n previousMonth: \"relPreviousMonth\",\n} as const;\n\n/** Named window or a counted last/next kind (the N lives beside the select). */\nexport type RelativePreset = (typeof RELATIVE_NAMED)[number] | \"last\" | \"next\";\n\n/** Presets offered by the relative-date widget, in display order. */\nexport const RELATIVE_PRESETS: readonly RelativePreset[] = [\n ...RELATIVE_NAMED,\n \"last\",\n \"next\",\n];\n\n/** `TableLabels` key for each relative preset. */\nexport const RELATIVE_PRESET_LABEL_KEYS = {\n today: \"relToday\",\n yesterday: \"relYesterday\",\n tomorrow: \"relTomorrow\",\n thisWeek: \"relThisWeek\",\n thisMonth: \"relThisMonth\",\n previousMonth: \"relPreviousMonth\",\n last: \"relLastN\",\n next: \"relNextN\",\n} as const;\n\n/** Split a stored token into the widget's preset + N (N defaults to 7). */\nexport function splitRelativeToken(raw: string): {\n preset: RelativePreset;\n n: number;\n} {\n const token = parseRelativeToken(raw);\n if (token?.startsWith(\"last:\")) {\n return { preset: \"last\", n: Number(token.slice(5)) };\n }\n if (token?.startsWith(\"next:\")) {\n return { preset: \"next\", n: Number(token.slice(5)) };\n }\n if (token && NAMED.has(token)) {\n return { preset: token as (typeof RELATIVE_NAMED)[number], n: 7 };\n }\n return { preset: \"today\", n: 7 };\n}\n\n/** Join a widget preset + N back into the stored token. */\nexport function joinRelativeToken(\n preset: RelativePreset,\n n: number\n): RelativeDateToken {\n if (preset === \"last\" || preset === \"next\") {\n return countedRelativeToken(preset, n);\n }\n return preset;\n}\n\n/** Chip / select wording for a stored token. */\nexport function relativeTokenLabel(\n raw: string,\n labels: {\n relToday: string;\n relYesterday: string;\n relTomorrow: string;\n relThisWeek: string;\n relThisMonth: string;\n relPreviousMonth: string;\n relLastN: string;\n relNextN: string;\n }\n): string {\n const token = parseRelativeToken(raw);\n if (!token) return raw;\n if (token.startsWith(\"last:\")) {\n return labels.relLastN.replace(/\\bN\\b/, token.slice(5));\n }\n if (token.startsWith(\"next:\")) {\n return labels.relNextN.replace(/\\bN\\b/, token.slice(5));\n }\n return labels[NAMED_LABEL_KEYS[token as keyof typeof NAMED_LABEL_KEYS]];\n}\n","/**\n * Declarative filters. One definition per filter drives everything the four\n * hand-wired pieces used to: the widget an adapter renders, the URL parsing\n * (array/number keys self-register), the chip labels, and the client-side\n * predicate. Definitions come from two places — a column's `filter` shorthand\n * and the table-level `filters` array — merged by {@link resolveFilterDefs}.\n */\nimport { localizedColumnPath } from \"../columns/resolveColumns\";\nimport { defaultLabels } from \"../labels\";\nimport type { QueryCondition } from \"../source/queryContract\";\nimport type {\n ColumnDef,\n ExtraFilters,\n FilterValue,\n TableLabels,\n} from \"../types\";\nimport { devWarn } from \"../utils/devWarn\";\nimport { humanizeKey } from \"../utils/humanizeKey\";\nimport { getPath } from \"../utils/path\";\nimport type { FilterTypeRegistry, FilterTypeSpec } from \"./filterRegistry\";\nimport {\n DATE_OP_LABEL_KEYS,\n DATE_OPS,\n type DateOp,\n filterOpKey,\n formatFilterChip,\n isEmptyRowValue,\n NUMBER_OP_LABEL_KEYS,\n NUMBER_OPS,\n type NumberOp,\n parseDateOp,\n parseNumberList,\n parseNumberOp,\n parseTextOp,\n TEXT_OP_LABEL_KEYS,\n TEXT_OPS,\n} from \"./operators\";\nimport { relativeTokenLabel, resolveRelativeRange } from \"./relativeDates\";\nimport type { ChipLabelResolver } from \"./useActiveFilterChips\";\n\n/** Every built-in filter shape, exported so consumers never hand-type them. */\nexport const FILTER_TYPES = [\n \"text\",\n \"select\",\n \"multiSelect\",\n \"checklist\",\n \"boolean\",\n \"dateRange\",\n \"numberRange\",\n] as const;\n\n/** A built-in filter shape. */\nexport type FilterType = (typeof FILTER_TYPES)[number];\n\n/** One choice in a `select` / `multiSelect` filter. */\nexport interface FilterOption {\n value: string;\n label: string;\n}\n\n/**\n * Where a select/multiSelect gets its choices: a static array, `\"auto\"`\n * (distinct values derived from the data — frontend tier; capped and\n * sorted), or an async loader resolved lazily when the form first renders.\n */\nexport type FilterOptionsSource =\n | readonly FilterOption[]\n | \"auto\"\n | (() => Promise);\n\n/** Most distinct values `\"auto\"` will derive before truncating. */\nexport const AUTO_OPTIONS_LIMIT = 50;\n\n/** A full, standalone filter definition (the `filters` array form). */\nexport interface FilterDef {\n /**\n * State key in the filter bag (and the `f_` URL param). Doubles as\n * the row's data path for the client-side predicate — dot paths reach\n * nested values (`\"department.name\"`) — unless `getValue` overrides it.\n */\n key: string;\n /**\n * Column key the header filter row places this widget under.\n * Defaults to {@link key} when the filter bag and the column share a\n * name; set it when they differ (`key: \"name\"` under `column: \"person\"`).\n */\n column?: string;\n /**\n * The widget shape. Built-ins are {@link FilterType}; any other string\n * is a custom type that must be registered on `filterTypes`.\n */\n type: string;\n /** Widget + chip label. Defaults to a humanized `key` (\"hiredAt\" → \"Hired At\"). */\n label?: string;\n /** Choices for `select` / `multiSelect` — see {@link FilterOptionsSource}. */\n options?: FilterOptionsSource;\n /** Row-value extractor for the client-side predicate; defaults to `key` as a path. */\n getValue?: (row: TRow) => unknown;\n /** Placeholder for text-like inputs. */\n placeholder?: string;\n}\n\n/**\n * The column-level shorthand: a bare type, or a definition without `key` /\n * `label` (both inherited from the column).\n */\nexport type ColumnFilter =\n | FilterType\n | (Omit, \"key\" | \"label\"> & { label?: string });\n\n/** Suffix pair used by the two-field range types. */\nexport const RANGE_SUFFIXES = {\n dateRange: { start: \"From\", end: \"To\" },\n numberRange: { start: \"Min\", end: \"Max\" },\n} as const;\n\n/** The state keys a definition reads/writes in the filter bag. */\nexport function filterStateKeys(\n def: Pick,\n registry?: FilterTypeRegistry\n): string[] {\n const spec = registry?.get(def.type);\n if (spec) return spec.stateKeys(def);\n return [def.key];\n}\n\n/** Coerce a row value to a boolean, or `undefined` when it has no truth. */\nexport function coerceBooleanValue(value: unknown): boolean | undefined {\n if (typeof value === \"boolean\") return value;\n if (value === 1 || value === \"1\") return true;\n if (value === 0 || value === \"0\") return false;\n if (typeof value === \"string\") {\n const token = value.trim().toLowerCase();\n if (token === \"true\" || token === \"yes\") return true;\n if (token === \"false\" || token === \"no\") return false;\n if (token === \"\") return undefined;\n }\n if (value == null) return undefined;\n return Boolean(value);\n}\n\nfunction booleanChoiceOn(value: FilterValue): boolean {\n return value === \"true\" || value === 1;\n}\n\n/**\n * Merge column-declared filters with the standalone `filters` array into the\n * final ordered definition list: column filters first (in column order), then\n * standalone definitions. A standalone definition with the same `key` as a\n * column filter WINS — documented override semantics, with a development\n * warning so accidental duplication is visible.\n */\nexport function resolveFilterDefs(\n columns: readonly ColumnDef[],\n filters: readonly FilterDef[] | undefined,\n locale?: string\n): FilterDef[] {\n const standalone = filters ?? [];\n const standaloneKeys = new Set(standalone.map((d) => d.key));\n const fromColumns: FilterDef[] = [];\n for (const column of columns) {\n if (!column.filter) continue;\n const base =\n typeof column.filter === \"string\"\n ? { type: column.filter }\n : column.filter;\n if (standaloneKeys.has(column.key)) {\n devWarn(\n `column \"${column.key}\" declares a filter but \\`filters\\` also defines that key — using the \\`filters\\` definition. Remove one to silence this.`\n );\n continue;\n }\n // A localized column's filter matches against the same locale-resolved\n // path the cell shows (unless the shorthand brings its own getValue).\n const path = localizedColumnPath(column, locale);\n fromColumns.push({\n key: column.key,\n label:\n base.label ??\n (typeof column.header === \"string\" ? column.header : undefined),\n ...(path === column.key\n ? {}\n : { getValue: (row: TRow) => getPath(row, path) }),\n ...base,\n });\n }\n return [...fromColumns, ...standalone];\n}\n\n/** Resolved label for a definition (explicit, else humanized key). */\nexport function filterLabel(def: Pick): string {\n return def.label ?? humanizeKey(def.key);\n}\n\nconst has = (extra: ExtraFilters, key: string): boolean => {\n const v = extra[key];\n if (v == null || v === \"\") return false;\n return !Array.isArray(v) || v.length > 0;\n};\n\n/** A row value as comparable text; non-primitives never match anything. */\nfunction valueText(value: unknown): string {\n switch (typeof value) {\n case \"string\":\n return value;\n case \"number\":\n case \"boolean\":\n case \"bigint\":\n return String(value);\n default:\n return \"\";\n }\n}\n\nconst DATE_ONLY_RE = /^\\d{4}-\\d{2}-\\d{2}$/;\nconst END_OF_DAY_MS = 86_399_999;\n\n/**\n * One coercion path for everything `dateRange` compares — row values and\n * bounds alike. The timezone rule: a date-only string (`\"2026-01-31\"`,\n * what date pickers and the URL carry) means that day in the USER'S LOCAL\n * timezone; a `Date`, an epoch-milliseconds number, or a datetime string\n * is an absolute instant. Comparing local day windows against absolute\n * row instants keeps boundary days stable in every timezone.\n *\n * @returns Epoch milliseconds, or `NaN` for anything unparseable.\n */\nfunction dateValueToEpochMs(value: unknown): number {\n if (value instanceof Date) return value.getTime();\n if (typeof value === \"number\") return value;\n if (typeof value !== \"string\") return Number.NaN;\n const text = value.trim();\n if (text === \"\") return Number.NaN;\n if (DATE_ONLY_RE.test(text)) {\n const [year = 0, month = 1, day = 1] = text.split(\"-\").map(Number);\n return new Date(year, month - 1, day).getTime();\n }\n return new Date(text).getTime();\n}\n\n/**\n * A row value as a number for range filtering, or `NaN` when the row has\n * no numeric value. `Number(null)` and `Number(\"\")` are `0`, which would\n * silently include no-value rows in any range spanning zero — so only\n * real numbers and non-empty numeric strings qualify.\n */\nfunction numericRowValue(value: unknown): number {\n if (typeof value === \"number\") return value;\n if (typeof value === \"string\" && value.trim() !== \"\") return Number(value);\n return Number.NaN;\n}\n\nfunction textMatch(rowValue: unknown, term: string): boolean {\n const text = valueText(rowValue).toLowerCase();\n return text !== \"\" && text.includes(term.toLowerCase());\n}\n\nfunction textRowMatches(\n op: ReturnType,\n rowValue: unknown,\n term: string\n): boolean {\n if (op === \"empty\") return isEmptyRowValue(rowValue);\n if (op === \"notEmpty\") return !isEmptyRowValue(rowValue);\n const text = valueText(rowValue).toLowerCase();\n const needle = term.toLowerCase();\n switch (op) {\n case \"eq\":\n return text === needle;\n case \"neq\":\n return text !== needle;\n case \"contains\":\n return textMatch(rowValue, term);\n case \"notContains\":\n return !text.includes(needle);\n case \"startsWith\":\n return text !== \"\" && text.startsWith(needle);\n case \"endsWith\":\n return text !== \"\" && text.endsWith(needle);\n }\n}\n\nfunction dateUpperBoundMs(bound: FilterValue): number {\n return (\n dateValueToEpochMs(bound) +\n (typeof bound === \"string\" && DATE_ONLY_RE.test(bound.trim())\n ? END_OF_DAY_MS\n : 0)\n );\n}\n\nfunction dateOnMatch(time: number, day: FilterValue | undefined): boolean {\n if (day == null || day === \"\") return true;\n const start = dateValueToEpochMs(day);\n return time >= start && time <= dateUpperBoundMs(day);\n}\n\nfunction dateInclusiveBounds(\n time: number,\n extra: ExtraFilters,\n fromKey: string,\n toKey: string\n): boolean {\n if (has(extra, fromKey) && time < dateValueToEpochMs(extra[fromKey])) {\n return false;\n }\n if (has(extra, toKey) && time > dateUpperBoundMs(extra[toKey])) {\n return false;\n }\n return true;\n}\n\nfunction dateRowMatches(\n op: DateOp | undefined,\n time: number,\n extra: ExtraFilters,\n fromKey: string,\n toKey: string\n): boolean {\n if (op === \"empty\") return Number.isNaN(time);\n if (op === \"relative\") {\n const range = resolveRelativeRange(String(extra[fromKey] ?? \"\"));\n if (!range) return true;\n return time >= range.startMs && time <= range.endMs;\n }\n if (Number.isNaN(time)) return false;\n if (op === \"before\" && has(extra, toKey)) {\n return time < dateValueToEpochMs(extra[toKey]);\n }\n if (op === \"after\" && has(extra, fromKey)) {\n return time > dateUpperBoundMs(extra[fromKey]);\n }\n if (op === \"on\") {\n const day = has(extra, fromKey) ? extra[fromKey] : extra[toKey];\n return dateOnMatch(time, day);\n }\n return dateInclusiveBounds(time, extra, fromKey, toKey);\n}\n\nfunction numberRowMatches(\n op: NumberOp | undefined,\n n: number,\n extra: ExtraFilters,\n minKey: string,\n maxKey: string,\n listKey: string\n): boolean {\n if (Number.isNaN(n)) return false;\n if (op === \"in\") return parseNumberList(extra[listKey]).includes(n);\n if (op === \"notIn\") return !parseNumberList(extra[listKey]).includes(n);\n const min = has(extra, minKey) ? Number(extra[minKey]) : Number.NaN;\n const max = has(extra, maxKey) ? Number(extra[maxKey]) : Number.NaN;\n switch (op) {\n case \"eq\":\n return !Number.isNaN(min) && n === min;\n case \"neq\":\n return !Number.isNaN(min) && n !== min;\n case \"gt\":\n return !Number.isNaN(min) && n > min;\n case \"gte\":\n return !Number.isNaN(min) && n >= min;\n case \"lt\":\n return !Number.isNaN(max) && n < max;\n case \"lte\":\n return !Number.isNaN(max) && n <= max;\n default:\n if (!Number.isNaN(min) && n < min) return false;\n return Number.isNaN(max) || n <= max;\n }\n}\n\nfunction textFilterActive(extra: ExtraFilters, key: string): boolean {\n const op = parseTextOp(extra[filterOpKey(key)]);\n if (op === \"empty\" || op === \"notEmpty\") return true;\n return has(extra, key);\n}\n\nfunction dateFilterActive(\n extra: ExtraFilters,\n key: string,\n fromKey: string,\n toKey: string\n): boolean {\n const op = parseDateOp(extra[filterOpKey(key)]);\n if (op === \"empty\") return true;\n if (op === \"relative\") return has(extra, fromKey);\n return has(extra, fromKey) || has(extra, toKey);\n}\n\nfunction numberFilterActive(\n extra: ExtraFilters,\n key: string,\n minKey: string,\n maxKey: string\n): boolean {\n const op = parseNumberOp(extra[filterOpKey(key)]);\n if (op === \"in\" || op === \"notIn\") return has(extra, key);\n return has(extra, minKey) || has(extra, maxKey);\n}\n\nfunction rowValue(def: FilterDef, row: TRow): unknown {\n return def.getValue ? def.getValue(row) : getPath(row, def.key);\n}\n\nfunction asConditionScalar(value: unknown): string | undefined {\n if (value == null) return undefined;\n if (typeof value === \"string\") return value;\n if (typeof value === \"number\" || typeof value === \"boolean\") {\n return String(value);\n }\n return undefined;\n}\n\nfunction asConditionList(value: unknown): string[] {\n if (Array.isArray(value)) return value.map(String);\n const one = asConditionScalar(value);\n return one == null ? [] : [one];\n}\n\nfunction asConditionPair(value: unknown): {\n a: string | undefined;\n b: string | undefined;\n} {\n if (Array.isArray(value)) {\n return { a: asConditionScalar(value[0]), b: asConditionScalar(value[1]) };\n }\n return { a: asConditionScalar(value), b: undefined };\n}\n\nfunction rangeConditionToExtra(\n def: FilterDef,\n condition: QueryCondition,\n flavour: \"dateRange\" | \"numberRange\"\n): ExtraFilters {\n const opKey = filterOpKey(def.key);\n const op = condition.op;\n const suffixes = RANGE_SUFFIXES[flavour];\n const lowKey = def.key + suffixes.start;\n const highKey = def.key + suffixes.end;\n if (op === \"empty\" || op === \"notEmpty\") return { [opKey]: op };\n if (op === \"in\" || op === \"notIn\") {\n const list = asConditionList(condition.value);\n return { [def.key]: list.length > 0 ? list : undefined, [opKey]: op };\n }\n if (op === \"between\") {\n const { a, b } = asConditionPair(condition.value);\n return { [lowKey]: a, [highKey]: b, [opKey]: op };\n }\n if (op === \"before\" || op === \"lte\" || op === \"lt\") {\n return { [highKey]: asConditionScalar(condition.value), [opKey]: op };\n }\n return { [lowKey]: asConditionScalar(condition.value), [opKey]: op };\n}\n\nfunction scalarConditionToExtra(\n def: FilterDef,\n condition: QueryCondition\n): ExtraFilters {\n return {\n [def.key]: asConditionScalar(condition.value),\n [filterOpKey(def.key)]: condition.op,\n };\n}\n\nfunction listConditionToExtra(\n def: FilterDef,\n condition: QueryCondition\n): ExtraFilters {\n const list = asConditionList(condition.value);\n return { [def.key]: list.length > 0 ? list : undefined };\n}\n\nfunction textStateKeys(def: Pick): string[] {\n return [def.key, filterOpKey(def.key)];\n}\n\nfunction rangeStateKeys(\n def: Pick,\n flavour: \"dateRange\" | \"numberRange\"\n): string[] {\n const s = RANGE_SUFFIXES[flavour];\n const pair = [def.key + s.start, def.key + s.end, filterOpKey(def.key)];\n return flavour === \"numberRange\" ? [def.key, ...pair] : pair;\n}\n\nfunction textSpec(): FilterTypeSpec {\n return {\n type: \"text\",\n widget: \"text\",\n ops: TEXT_OPS,\n defaultOp: \"contains\",\n stateKeys: textStateKeys,\n match: (def, extra, row) => {\n if (!textFilterActive(extra, def.key)) return true;\n return textRowMatches(\n parseTextOp(extra[filterOpKey(def.key)]),\n rowValue(def, row),\n String(extra[def.key] ?? \"\")\n );\n },\n chips: (def) => {\n const label = filterLabel(def);\n return {\n [def.key]: (v: string, extra?: ExtraFilters) =>\n textChipLabel(label, v, extra, def.key),\n [filterOpKey(def.key)]: (v: string) => emptyOpChip(label, v),\n };\n },\n conditionToExtra: scalarConditionToExtra,\n };\n}\n\nfunction selectSpec(type: \"select\"): FilterTypeSpec {\n return {\n type,\n widget: type,\n ops: [\"eq\"],\n defaultOp: \"eq\",\n stateKeys: (def) => [def.key],\n match: (def, extra, row) =>\n !has(extra, def.key) ||\n valueText(rowValue(def, row)) === String(extra[def.key]),\n chips: (def) => ({\n [def.key]: (v: string) => `${filterLabel(def)}: ${optionLabel(def, v)}`,\n }),\n conditionToExtra: scalarConditionToExtra,\n };\n}\n\nfunction listSpec(type: \"multiSelect\" | \"checklist\"): FilterTypeSpec {\n return {\n type,\n widget: type,\n ops: [\"in\"],\n defaultOp: \"in\",\n urlArray: true,\n stateKeys: (def) => [def.key],\n match: (def, extra, row) => {\n if (!has(extra, def.key)) return true;\n const selected = extra[def.key];\n const list = Array.isArray(selected) ? selected : [String(selected)];\n return list.includes(valueText(rowValue(def, row)));\n },\n chips: (def) => ({\n [def.key]: (v: string) => `${filterLabel(def)}: ${optionLabel(def, v)}`,\n }),\n conditionToExtra: listConditionToExtra,\n };\n}\n\nfunction booleanSpec(): FilterTypeSpec {\n return {\n type: \"boolean\",\n widget: \"boolean\",\n ops: [\"eq\"],\n defaultOp: \"eq\",\n stateKeys: (def) => [def.key],\n match: (def, extra, row) => {\n if (!has(extra, def.key)) return true;\n return (\n coerceBooleanValue(rowValue(def, row)) ===\n booleanChoiceOn(extra[def.key])\n );\n },\n chips: (def) => ({\n [def.key]: (v: string) =>\n `${filterLabel(def)}: ${\n booleanChoiceOn(v) ? defaultLabels.boolTrue : defaultLabels.boolFalse\n }`,\n }),\n conditionToExtra: scalarConditionToExtra,\n };\n}\n\nfunction rangeSpec(flavour: \"dateRange\" | \"numberRange\"): FilterTypeSpec {\n const isDate = flavour === \"dateRange\";\n return {\n type: flavour,\n widget: flavour,\n ops: isDate ? DATE_OPS : NUMBER_OPS,\n defaultOp: isDate ? \"on\" : \"gte\",\n urlArray: !isDate,\n urlNumberKeys: !isDate,\n stateKeys: (def) => rangeStateKeys(def, flavour),\n match: (def, extra, row) => {\n const low = def.key + RANGE_SUFFIXES[flavour].start;\n const high = def.key + RANGE_SUFFIXES[flavour].end;\n if (isDate) {\n if (!dateFilterActive(extra, def.key, low, high)) return true;\n return dateRowMatches(\n parseDateOp(extra[filterOpKey(def.key)]),\n dateValueToEpochMs(rowValue(def, row)),\n extra,\n low,\n high\n );\n }\n if (!numberFilterActive(extra, def.key, low, high)) return true;\n return numberRowMatches(\n parseNumberOp(extra[filterOpKey(def.key)]),\n numericRowValue(rowValue(def, row)),\n extra,\n low,\n high,\n def.key\n );\n },\n chips: (def) => {\n const label = filterLabel(def);\n const low = def.key + RANGE_SUFFIXES[flavour].start;\n const high = def.key + RANGE_SUFFIXES[flavour].end;\n const flavourName = isDate ? \"date\" : \"number\";\n const chips: Record = {\n [low]: (v, extra) =>\n rangeChipLabel(label, v, extra, def.key, \"low\", flavourName),\n [high]: (v, extra) =>\n rangeChipLabel(label, v, extra, def.key, \"high\", flavourName),\n [filterOpKey(def.key)]: (v) => emptyOpChip(label, v),\n };\n if (!isDate) {\n chips[def.key] = (v, extra) =>\n rangeChipLabel(label, v, extra, def.key, \"low\", \"number\");\n }\n return chips;\n },\n conditionToExtra: (def, condition) =>\n rangeConditionToExtra(def, condition, flavour),\n };\n}\n\n/** Built-in types — the registry's first consumers. */\n/** Built-in specs — imported only by {@link defaultFilterRegistry}. */\nexport function createBuiltInFilterSpecs(): FilterTypeSpec[] {\n return [\n textSpec(),\n selectSpec(\"select\"),\n listSpec(\"multiSelect\"),\n listSpec(\"checklist\"),\n booleanSpec(),\n rangeSpec(\"dateRange\"),\n rangeSpec(\"numberRange\"),\n ];\n}\n\n/** Build one definition's client-side predicate (true = row matches). */\nexport function filterPredicate(\n def: FilterDef,\n registry: FilterTypeRegistry\n): (row: TRow, extra: ExtraFilters) => boolean {\n const spec = registry.get(def.type);\n if (!spec) {\n devWarn(`Unknown filter type \"${def.type}\"`);\n return () => true;\n }\n return (row, extra) => spec.match(def, extra, row);\n}\n\n/** Everything the table engine derives from the resolved definitions. */\nexport interface FilterRuntime {\n /** The merged, ordered definitions (drives the auto-built form). */\n defs: readonly FilterDef[];\n /** Keys whose URL values parse as comma-separated arrays. */\n arrayExtraKeys: string[];\n /** Keys whose URL values parse as numbers. */\n numberExtraKeys: string[];\n /** Chip label resolvers, one per state key. */\n filterLabels: Record;\n /** AND-composed client-side predicate across every definition. */\n filterFn: (row: TRow, extra: ExtraFilters) => boolean;\n /** Type registry used to derive this runtime. */\n registry: FilterTypeRegistry;\n}\n\nconst optionLabel = (\n def: Pick,\n value: string\n): string => {\n // Only materialized arrays can map values to labels; `\"auto\"` is\n // materialized before the runtime builds, and async options label their\n // chips with the raw value until loaded.\n if (!Array.isArray(def.options)) return value;\n const options: readonly FilterOption[] = def.options;\n return options.find((o) => o.value === value)?.label ?? value;\n};\n\nfunction opWord(labels: Required, key: keyof TableLabels): string {\n const value = labels[key];\n return typeof value === \"string\" ? value : key;\n}\n\nfunction textChipLabel(\n field: string,\n value: string,\n extra: ExtraFilters | undefined,\n key: string\n): string {\n const op = parseTextOp(extra?.[filterOpKey(key)]);\n return formatFilterChip(\n field,\n opWord(defaultLabels, TEXT_OP_LABEL_KEYS[op]),\n value\n );\n}\n\nfunction rangeChipLabel(\n field: string,\n value: string,\n extra: ExtraFilters | undefined,\n key: string,\n side: \"low\" | \"high\",\n flavour: \"number\" | \"date\"\n): string {\n const raw = extra?.[filterOpKey(key)];\n if (flavour === \"number\") {\n const op = parseNumberOp(raw);\n if (op && op !== \"between\") {\n return formatFilterChip(\n field,\n opWord(defaultLabels, NUMBER_OP_LABEL_KEYS[op]),\n value\n );\n }\n } else {\n const op = parseDateOp(raw);\n if (op === \"relative\") {\n return formatFilterChip(field, relativeTokenLabel(value, defaultLabels));\n }\n if (op && op !== \"between\") {\n return formatFilterChip(\n field,\n opWord(defaultLabels, DATE_OP_LABEL_KEYS[op]),\n value\n );\n }\n }\n return side === \"low\" ? `${field} ≥ ${value}` : `${field} ≤ ${value}`;\n}\n\nfunction emptyOpChip(field: string, token: string): string {\n if (token === \"empty\") {\n return formatFilterChip(field, defaultLabels.opEmpty);\n }\n if (token === \"notEmpty\") {\n return formatFilterChip(field, defaultLabels.opNotEmpty);\n }\n return \"\";\n}\n\n/** Derive the full runtime (URL keys, chips, predicate) from definitions. */\nexport function buildFilterRuntime(\n defs: readonly FilterDef[],\n registry: FilterTypeRegistry\n): FilterRuntime {\n const arrayExtraKeys: string[] = [];\n const numberExtraKeys: string[] = [];\n const filterLabels: Record = {};\n const predicates = defs.map((def) => filterPredicate(def, registry));\n\n for (const def of defs) {\n const spec = registry.get(def.type);\n if (!spec) continue;\n if (spec.urlArray) arrayExtraKeys.push(def.key);\n if (spec.urlNumberKeys) {\n const s = RANGE_SUFFIXES.numberRange;\n numberExtraKeys.push(def.key + s.start, def.key + s.end);\n }\n Object.assign(filterLabels, spec.chips(def));\n }\n\n return {\n defs,\n arrayExtraKeys,\n numberExtraKeys,\n filterLabels,\n filterFn: (row, extra) => predicates.every((p) => p(row, extra)),\n registry,\n };\n}\n\n/** The cleared state for every key a definition list owns. */\nexport function clearedFilterExtras(\n defs: readonly FilterDef[],\n registry?: FilterTypeRegistry\n): ExtraFilters {\n const out: Record = {};\n for (const def of defs) {\n for (const key of filterStateKeys(def, registry)) out[key] = undefined;\n }\n return out;\n}\n\n/**\n * Materialize `\"auto\"` option sources from the data: the distinct values of\n * each such definition's row projection, sorted, capped at\n * {@link AUTO_OPTIONS_LIMIT}. Static arrays and async loaders pass through\n * untouched. Run BEFORE {@link buildFilterRuntime} so chips can label the\n * derived values.\n */\nexport function materializeAutoOptions(\n defs: readonly FilterDef[],\n rows: readonly TRow[]\n): FilterDef[] {\n return defs.map((def) => {\n if (def.options !== \"auto\") return def;\n const seen = new Set();\n for (const row of rows) {\n const text = valueText(\n def.getValue ? def.getValue(row) : getPath(row, def.key)\n );\n if (text !== \"\") seen.add(text);\n if (seen.size > AUTO_OPTIONS_LIMIT) break;\n }\n const options = [...seen]\n .sort((a, b) => a.localeCompare(b))\n .slice(0, AUTO_OPTIONS_LIMIT)\n .map((value) => ({ value, label: value }));\n return { ...def, options };\n });\n}\n","import type { ExtraFilters, FilterValue } from \"../types\";\nimport {\n DATE_OP_LABEL_KEYS,\n type DateOp,\n filterOpKey,\n isListFilterOp,\n isValuelessFilterOp,\n NUMBER_OP_LABEL_KEYS,\n type NumberOp,\n parseDateOp,\n parseListOperand,\n parseNumberOp,\n} from \"./operators\";\nimport { isRelativeDateToken } from \"./relativeDates\";\n\n/**\n * Historical four-operator set. New code should use {@link NUMBER_OPS} /\n * {@link DATE_OPS}; this list stays exported so existing imports keep\n * type-checking while the widgets read the flavour-specific lists.\n */\nexport const RANGE_OPS = [\"eq\", \"gte\", \"lte\", \"between\"] as const;\n\n/** One range-widget comparison operator (number or date). */\nexport type RangeOp = NumberOp | DateOp;\n\n/** The widget's view of a range: an operator plus its bound(s). */\nexport interface RangeWidgetState {\n /** Selected comparison, or `undefined` while nothing is chosen. */\n op: RangeOp | undefined;\n /** The single value, the lower bound (`between`), or the list text. */\n a: string;\n /** The upper bound (`between` only). */\n b: string;\n}\n\nconst text = (value: FilterValue | undefined): string =>\n value == null ? \"\" : String(value);\n\nconst asOpValue = (raw: string): FilterValue => (raw === \"\" ? undefined : raw);\n\nfunction readStoredRangeOp(\n extra: ExtraFilters,\n stored: RangeOp,\n lowKey: string,\n highKey: string,\n listKey?: string\n): RangeWidgetState {\n if (stored === \"in\" || stored === \"notIn\") {\n return {\n op: stored,\n a: parseListOperand(listKey ? extra[listKey] : undefined).join(\", \"),\n b: \"\",\n };\n }\n if (stored === \"empty\") {\n return { op: stored, a: \"\", b: \"\" };\n }\n const low = text(extra[lowKey]);\n const high = text(extra[highKey]);\n if (stored === \"lte\" || stored === \"lt\" || stored === \"before\") {\n return { op: stored, a: high || low, b: \"\" };\n }\n if (stored === \"between\") {\n return { op: stored, a: low, b: high };\n }\n return { op: stored, a: low || high, b: \"\" };\n}\n\nfunction inferRangeFromPair(\n extra: ExtraFilters,\n lowKey: string,\n highKey: string,\n flavour?: \"number\" | \"date\"\n): RangeWidgetState {\n const low = text(extra[lowKey]);\n const high = text(extra[highKey]);\n if (low !== \"\" && high !== \"\") {\n return low === high\n ? { op: flavour === \"date\" ? \"on\" : \"eq\", a: low, b: \"\" }\n : { op: \"between\", a: low, b: high };\n }\n if (low !== \"\" && flavour === \"date\" && isRelativeDateToken(low)) {\n return { op: \"relative\", a: low, b: \"\" };\n }\n if (low !== \"\") return { op: \"gte\", a: low, b: \"\" };\n if (high !== \"\") return { op: \"lte\", a: high, b: \"\" };\n return { op: undefined, a: \"\", b: \"\" };\n}\n\n/**\n * Derive the widget state. A stored `f_Op` wins; without it the\n * inclusive pair still infers `eq` / `gte` / `lte` / `between` so links\n * written before operators were persisted keep opening on the right\n * comparison.\n */\nexport function readRangeWidget(\n extra: ExtraFilters,\n lowKey: string,\n highKey: string,\n opKey?: string,\n listKey?: string,\n flavour?: \"number\" | \"date\"\n): RangeWidgetState {\n const stored = opKey\n ? (parseNumberOp(extra[opKey]) ?? parseDateOp(extra[opKey]))\n : undefined;\n if (stored) {\n return readStoredRangeOp(extra, stored, lowKey, highKey, listKey);\n }\n return inferRangeFromPair(extra, lowKey, highKey, flavour);\n}\n\n/**\n * Convert a widget interaction back to the persisted pair. Empty values\n * clear their keys, so half-filled widgets never leak stale bounds.\n */\nexport function writeRangeWidget(\n op: RangeOp | undefined,\n a: string,\n b: string,\n lowKey: string,\n highKey: string\n): ExtraFilters {\n switch (op) {\n case \"eq\":\n case \"on\":\n return { [lowKey]: asOpValue(a), [highKey]: asOpValue(a) };\n case \"gte\":\n case \"gt\":\n case \"after\":\n case \"neq\":\n case \"relative\":\n return { [lowKey]: asOpValue(a), [highKey]: undefined };\n case \"lte\":\n case \"lt\":\n case \"before\":\n return { [lowKey]: undefined, [highKey]: asOpValue(a) };\n case \"between\":\n return { [lowKey]: asOpValue(a), [highKey]: asOpValue(b) };\n default:\n return { [lowKey]: undefined, [highKey]: undefined };\n }\n}\n\n/**\n * Persist an operator-first range (or list) filter: the inclusive pair,\n * the list key for `in` / `notIn`, and the readable `f_Op` token.\n */\nexport function writeRangeFilter(\n op: RangeOp | undefined,\n a: string,\n b: string,\n lowKey: string,\n highKey: string,\n key: string\n): ExtraFilters {\n const opKey = filterOpKey(key);\n if (!op) {\n return {\n ...writeRangeWidget(undefined, \"\", \"\", lowKey, highKey),\n [opKey]: undefined,\n };\n }\n if (isValuelessFilterOp(op)) {\n return {\n ...writeRangeWidget(undefined, \"\", \"\", lowKey, highKey),\n [key]: undefined,\n [opKey]: op,\n };\n }\n if (isListFilterOp(op)) {\n const entries = parseListOperand(a);\n return {\n ...writeRangeWidget(undefined, \"\", \"\", lowKey, highKey),\n [key]: entries.length > 0 ? entries : undefined,\n [opKey]: entries.length > 0 ? op : undefined,\n };\n }\n const pair = writeRangeWidget(op, a, b, lowKey, highKey);\n const active = a !== \"\" || (op === \"between\" && b !== \"\");\n return {\n ...pair,\n [opKey]: active ? op : undefined,\n };\n}\n\n/** Label keys for each operator, per widget flavour (numbers vs dates). */\nexport const RANGE_OP_LABEL_KEYS = {\n number: NUMBER_OP_LABEL_KEYS,\n /** `eq` stays as the historical spelling of `on` for existing widgets. */\n date: { ...DATE_OP_LABEL_KEYS, eq: \"opOn\" },\n} as const;\n","import { useState } from \"react\";\n\nimport type { TableSource } from \"../source/TableSource\";\nimport type { FilterValue, TableLabels } from \"../types\";\nimport { type FilterDef, filterLabel, RANGE_SUFFIXES } from \"./filterDefs\";\nimport {\n DATE_OP_LABEL_KEYS,\n DATE_OPS,\n filterOpKey,\n isBetweenFilterOp,\n isListFilterOp,\n isValuelessFilterOp,\n NUMBER_OP_LABEL_KEYS,\n NUMBER_OPS,\n parseTextOp,\n TEXT_OP_LABEL_KEYS,\n TEXT_OPS,\n type TextOp,\n} from \"./operators\";\nimport { type RangeOp, readRangeWidget, writeRangeFilter } from \"./rangeWidget\";\nimport { isRelativeDateToken } from \"./relativeDates\";\n\n/** Operand shape for a selected range operator. */\nexport type RangeOpArity = \"none\" | \"one\" | \"two\" | \"list\";\n\n/**\n * The slice of the table source the auto-built filter form reads and writes:\n * the extra-filter bag and its single/bulk setters. Every batteries-included\n * adapter renders its own kit controls over this same contract.\n */\nexport type FilterFormSource = Pick<\n TableSource,\n \"extra\" | \"setExtra\" | \"setExtras\" | \"allFilteredRows\" | \"facets\"\n>;\n\n/** A scalar filter value as input text (\"\" when unset; numbers stringify). */\nexport function scalarFilterText(value: FilterValue): string {\n return value == null ? \"\" : String(value);\n}\n\n/** A multi-select value as a list — tolerating a scalar from the URL. */\nexport function listFilterValues(value: FilterValue): string[] {\n if (Array.isArray(value)) return [...value];\n return value == null || value === \"\" ? [] : [String(value)];\n}\n\nfunction rangeArity(op: RangeOp | undefined): RangeOpArity {\n if (!op) return \"one\";\n if (isValuelessFilterOp(op)) return \"none\";\n if (isListFilterOp(op)) return \"list\";\n if (isBetweenFilterOp(op)) return \"two\";\n return \"one\";\n}\n\nfunction rangeInputType(\n flavour: \"number\" | \"date\",\n arity: RangeOpArity,\n op: RangeOp | undefined\n): \"date\" | \"number\" | \"text\" {\n if (op === \"relative\") return \"text\";\n if (flavour === \"date\") return \"date\";\n if (arity === \"list\") return \"text\";\n return \"number\";\n}\n\n/** Per-operator label keys for one widget flavour (numbers or dates). */\nexport type RangeOpLabelKeys =\n | typeof NUMBER_OP_LABEL_KEYS\n | (typeof DATE_OP_LABEL_KEYS & { readonly eq: \"opOn\" });\n\n/** Computed state + writers driving an operator-first range field. */\nexport interface RangeFieldWidget {\n /** The field's display label. */\n label: string;\n /** Operators offered for this flavour, in display order. */\n ops: readonly RangeOp[];\n /** Per-operator label keys for the current flavour (number vs date). */\n opLabelKeys: RangeOpLabelKeys;\n /** Native input `type` for the bound inputs (`text` for `in` / `notIn`). */\n inputType: \"date\" | \"number\" | \"text\";\n /** Operand shape for the selected operator. */\n arity: RangeOpArity;\n /** The selected operator, or `undefined` until one is chosen. */\n op: RangeOp | undefined;\n /** Set the operator (UI state, re-seeded from the persisted pair). */\n setOp: (op: RangeOp | undefined) => void;\n /** The single / lower bound / list as input text. */\n a: string;\n /** The upper bound as input text (`between` only). */\n b: string;\n /** Persist an operator + bound(s) back to the bag, including `f_Op`. */\n write: (nextOp: RangeOp | undefined, nextA: string, nextB: string) => void;\n}\n\n/**\n * The shared, kit-agnostic logic behind an auto-built range filter\n * (`numberRange` / `dateRange`): it seeds the operator from the persisted\n * `Op` token (or infers it from the Min/Max pair), derives the visible\n * bound(s), and writes interactions back so the operator survives the URL.\n *\n * @typeParam TRow - The row type.\n * @param def - The range filter definition.\n * @param source - The filter-bag slice (extra + setters).\n * @returns The {@link RangeFieldWidget} state and writers.\n */\nexport function useRangeFilterWidget(\n def: FilterDef,\n source: FilterFormSource\n): RangeFieldWidget {\n const { extra, setExtras } = source;\n const label = filterLabel(def);\n const flavour = def.type === \"dateRange\" ? \"date\" : \"number\";\n const suffixes =\n RANGE_SUFFIXES[flavour === \"date\" ? \"dateRange\" : \"numberRange\"];\n const lowKey = def.key + suffixes.start;\n const highKey = def.key + suffixes.end;\n const opKey = filterOpKey(def.key);\n const ops: readonly RangeOp[] = flavour === \"date\" ? DATE_OPS : NUMBER_OPS;\n const opLabelKeys =\n flavour === \"date\"\n ? { ...DATE_OP_LABEL_KEYS, eq: \"opOn\" as const }\n : NUMBER_OP_LABEL_KEYS;\n const [op, setOp] = useState(\n () => readRangeWidget(extra, lowKey, highKey, opKey, def.key, flavour).op\n );\n const derived = readRangeWidget(\n extra,\n lowKey,\n highKey,\n opKey,\n def.key,\n flavour\n );\n const a = derived.a;\n const b = derived.b;\n const arity = rangeArity(op);\n const inputType = rangeInputType(flavour, arity, op);\n const write = (nextOp: RangeOp | undefined, nextA: string, nextB: string) => {\n // Switching into `between` from a single-value comparison copies the\n // current value into both bounds so the pair is never half-empty.\n const seededB =\n nextOp === \"between\" && nextB === \"\" && nextA !== \"\" && op !== \"between\"\n ? nextA\n : nextB;\n // Relative stores a token, never a calendar day. Entering the op seeds\n // `today`; leaving it drops a leftover token so a date input stays empty.\n let seededA = nextA;\n if (nextOp === \"relative\" && !isRelativeDateToken(nextA)) {\n seededA = \"today\";\n } else if (nextOp !== \"relative\" && isRelativeDateToken(nextA)) {\n seededA = \"\";\n }\n setExtras(\n writeRangeFilter(nextOp, seededA, seededB, lowKey, highKey, def.key)\n );\n };\n return {\n label,\n ops,\n opLabelKeys,\n inputType,\n arity,\n op,\n setOp,\n a,\n b,\n write,\n };\n}\n\n/** Computed state + writers driving an operator-first text field. */\nexport interface TextFieldWidget {\n /** The field's display label. */\n label: string;\n /** Operators offered for text filters. */\n ops: readonly TextOp[];\n /** Per-operator `TableLabels` keys. */\n opLabelKeys: typeof TEXT_OP_LABEL_KEYS;\n /** The selected operator (defaults to `contains`). */\n op: TextOp;\n /** Set the operator and persist it. */\n setOp: (op: TextOp) => void;\n /** The comparison term (unused for `empty` / `notEmpty`). */\n value: string;\n /** Whether the operator needs a value input. */\n needsValue: boolean;\n /** Persist the operator + term (clears the term for valueless ops). */\n write: (nextOp: TextOp, nextValue: string) => void;\n}\n\n/**\n * Kit-agnostic logic for a `text` filter: operator-first, persisted as\n * `f_` plus `f_Op` so the comparison survives the URL.\n *\n * @typeParam TRow - The row type.\n * @param def - The text filter definition.\n * @param source - The filter-bag slice (extra + setters).\n * @returns The {@link TextFieldWidget} state and writers.\n */\nexport function useTextFilterWidget(\n def: FilterDef,\n source: FilterFormSource\n): TextFieldWidget {\n const { extra, setExtras } = source;\n const label = filterLabel(def);\n const opKey = filterOpKey(def.key);\n const storedOp = parseTextOp(extra[opKey]);\n const [localOp, setLocalOp] = useState(storedOp);\n const op = extra[opKey] != null ? storedOp : localOp;\n const value = scalarFilterText(extra[def.key]);\n const needsValue = !isValuelessFilterOp(op);\n const write = (nextOp: TextOp, nextValue: string) => {\n const valueless = isValuelessFilterOp(nextOp);\n setLocalOp(nextOp);\n setExtras({\n [def.key]: valueless || nextValue === \"\" ? undefined : nextValue,\n [opKey]: valueless || nextValue !== \"\" ? nextOp : undefined,\n });\n };\n const setOp = (next: TextOp) => write(next, value);\n return {\n label,\n ops: TEXT_OPS,\n opLabelKeys: TEXT_OP_LABEL_KEYS,\n op,\n setOp,\n value,\n needsValue,\n write,\n };\n}\n\n/** Resolve a `TableLabels` key to the string the widget should show. */\nexport function filterOpLabel(\n labels: Required,\n key: keyof TableLabels\n): string {\n const value = labels[key];\n return typeof value === \"string\" ? value : String(key);\n}\n\nexport type { DateOp, NumberOp, TextOp } from \"./operators\";\n\n/** One choice in a tri-state boolean filter (`\"\"` = any). */\nexport type BooleanChoice = \"\" | \"true\" | \"false\";\n\n/** Read a boolean filter slot as a tri-state choice. */\nexport function parseBooleanChoice(value: FilterValue): BooleanChoice {\n if (value === \"true\" || value === 1) return \"true\";\n if (value === \"false\" || value === 0) return \"false\";\n return \"\";\n}\n\n/** Computed state + writer driving a tri-state boolean field. */\nexport interface BooleanFieldWidget {\n /** The field's display label. */\n label: string;\n /** Selected choice (`\"\"` means any / don't care). */\n choice: BooleanChoice;\n /** Persist the choice (`\"\"` clears the key). */\n write: (next: BooleanChoice) => void;\n}\n\n/**\n * Kit-agnostic logic for a `boolean` filter: any / true / false, never a\n * checkbox. The token is stored as `f_=true|false`; omitting it is any.\n */\nexport function useBooleanFilterWidget(\n def: FilterDef,\n source: FilterFormSource\n): BooleanFieldWidget {\n const { extra, setExtra } = source;\n return {\n label: filterLabel(def),\n choice: parseBooleanChoice(extra[def.key]),\n write: (next) => setExtra(def.key, next === \"\" ? undefined : next),\n };\n}\n","/**\n * Excel-style checklist filter — distinct values, counts, search,\n * select-all. Prefers {@link TableSource.facets} (own-filter excluded);\n * falls back to {@link TableSource.allFilteredRows}. A server page that\n * omits both does not offer the widget.\n */\nimport { useMemo, useState } from \"react\";\n\nimport type { TableSource } from \"../source/TableSource\";\nimport type { FilterValue } from \"../types\";\nimport { getPath } from \"../utils/path\";\nimport type { FilterDef, FilterOption } from \"./filterDefs\";\nimport { listFilterValues } from \"./filterForm\";\n\n/** Window the list once it is long enough that a full render would hitch. */\nexport const CHECKLIST_VIRTUALIZE_AT = 40;\n\n/** Fixed row height the virtual window measures against, in px. */\nexport const CHECKLIST_ITEM_HEIGHT = 28;\n\n/** Visible viewport of a virtualized list, in px. */\nexport const CHECKLIST_LIST_HEIGHT = 240;\n\n/** One distinct value in a checklist, with its count in the current set. */\nexport interface ChecklistValue {\n value: string;\n label: string;\n count: number;\n}\n\n/** Kit-agnostic state behind {@link useChecklistFilter}. */\nexport interface ChecklistFilterState {\n /** False when the source has no full filtered set — do not render. */\n available: boolean;\n /** Distinct values, selected-but-missing ones included at count 0. */\n items: readonly ChecklistValue[];\n /** `items` narrowed by the search box. */\n visible: readonly ChecklistValue[];\n /** Current search box text. */\n query: string;\n setQuery: (next: string) => void;\n /** Currently checked values. */\n selected: readonly string[];\n /** True when `visible` is long enough to window. */\n virtualize: boolean;\n selectAllVisible: () => void;\n clear: () => void;\n toggle: (value: string, on: boolean) => void;\n}\n\nfunction valueText(value: unknown): string {\n switch (typeof value) {\n case \"string\":\n return value;\n case \"number\":\n case \"boolean\":\n case \"bigint\":\n return String(value);\n default:\n return \"\";\n }\n}\n\nfunction optionLabel(options: FilterDef[\"options\"], value: string): string {\n if (!Array.isArray(options)) return value;\n const list: readonly FilterOption[] = options;\n return list.find((item) => item.value === value)?.label ?? value;\n}\n\nfunction rowValue(def: FilterDef, row: TRow): string {\n return valueText(def.getValue ? def.getValue(row) : getPath(row, def.key));\n}\n\n/**\n * Distinct values + counts from a row set. Static `options` only supply\n * labels — the values themselves always come from the rows.\n */\nexport function collectChecklistValues(\n def: FilterDef,\n rows: readonly TRow[],\n selected: readonly string[] = []\n): ChecklistValue[] {\n const counts = new Map();\n for (const row of rows) {\n const text = rowValue(def, row);\n if (text === \"\") continue;\n counts.set(text, (counts.get(text) ?? 0) + 1);\n }\n for (const value of selected) {\n if (value !== \"\" && !counts.has(value)) counts.set(value, 0);\n }\n return [...counts.entries()]\n .sort((a, b) => a[0].localeCompare(b[0]))\n .map(([value, count]) => ({\n value,\n label: optionLabel(def.options, value),\n count,\n }));\n}\n\nfunction selectedList(value: FilterValue): string[] {\n return listFilterValues(value);\n}\n\n/**\n * Derive the checklist from `source.facets` or `source.allFilteredRows`.\n * Returns `available: false` when both are missing so a server page\n * never pretends it can count a set it does not hold.\n */\nexport function useChecklistFilter(\n def: FilterDef,\n source: Pick<\n TableSource,\n \"allFilteredRows\" | \"extra\" | \"setExtra\" | \"facets\"\n >\n): ChecklistFilterState {\n const fromFacets = source.facets?.[def.key];\n const rows = source.allFilteredRows;\n const available = fromFacets !== undefined || rows !== undefined;\n const raw = source.extra[def.key];\n const selected = selectedList(raw);\n const items = useMemo(() => {\n if (fromFacets) return [...fromFacets];\n return rows ? collectChecklistValues(def, rows, selectedList(raw)) : [];\n }, [def, rows, raw, fromFacets]);\n const [query, setQuery] = useState(\"\");\n const needle = query.trim().toLowerCase();\n const visible = useMemo(() => {\n if (needle === \"\") return items;\n return items.filter((item) => {\n return (\n item.label.toLowerCase().includes(needle) ||\n item.value.toLowerCase().includes(needle)\n );\n });\n }, [items, needle]);\n\n const write = (next: readonly string[]) => {\n source.setExtra(def.key, next.length > 0 ? [...next] : undefined);\n };\n\n return {\n available,\n items,\n visible,\n query,\n setQuery,\n selected,\n virtualize: visible.length >= CHECKLIST_VIRTUALIZE_AT,\n selectAllVisible: () => {\n const next = new Set(selected);\n for (const item of visible) next.add(item.value);\n write([...next]);\n },\n clear: () => write([]),\n toggle: (value, on) => {\n if (on) {\n write(selected.includes(value) ? selected : [...selected, value]);\n return;\n }\n write(selected.filter((item) => item !== value));\n },\n };\n}\n","/**\n * Facet counts — what selecting a value WOULD give, which is the\n * filtered set with this facet's own filter removed (#281).\n */\nimport type { ExtraFilters } from \"../types\";\nimport { type ChecklistValue, collectChecklistValues } from \"./checklist\";\nimport type { FilterDef } from \"./filterDefs\";\nimport { listFilterValues } from \"./filterForm\";\nimport type { FilterTypeRegistry } from \"./filterRegistry\";\n\n/** Distinct values + counts for one filter key. */\nexport type FacetCounts = readonly ChecklistValue[];\n\n/** Facet counts keyed by filter key. */\nexport type FacetMap = Readonly>;\n\n/**\n * Rows that still match after every filter except `key`. The count on\n * each remaining value is \"how many rows you would keep if you picked\n * it\", not \"how many remain after you already picked it\".\n */\nexport function rowsExcludingFilter(\n rows: readonly TRow[],\n extra: ExtraFilters,\n key: string,\n filterFn: (row: TRow, extra: ExtraFilters) => boolean\n): readonly TRow[] {\n const cleared: ExtraFilters = { ...extra, [key]: undefined };\n return rows.filter((row) => filterFn(row, cleared));\n}\n\n/**\n * Facet counts for every `checklist` definition. Other types are\n * ignored — they do not show per-value counts.\n */\nexport function computeFilterFacets(\n defs: readonly FilterDef[],\n rows: readonly TRow[],\n extra: ExtraFilters,\n filterFn: (row: TRow, extra: ExtraFilters) => boolean,\n registry?: FilterTypeRegistry\n): FacetMap {\n const out: Record = {};\n for (const def of defs) {\n const widget = registry?.get(def.type)?.widget ?? def.type;\n if (widget !== \"checklist\") continue;\n const subset = rowsExcludingFilter(rows, extra, def.key, filterFn);\n out[def.key] = collectChecklistValues(\n def,\n subset,\n listFilterValues(extra[def.key])\n );\n }\n return out;\n}\n","/**\n * Public filter-type registry (#283). A type supplies widget kind, operators,\n * predicate, chips and tree serialization. Built-ins are the first consumers —\n * every former `switch (def.type)` looks up a spec instead.\n */\nimport type { ReactElement } from \"react\";\n\nimport type { QueryCondition } from \"../source/queryContract\";\nimport type { ExtraFilters, TableLabels } from \"../types\";\nimport { devWarn } from \"../utils/devWarn\";\nimport type { FilterDef, FilterType } from \"./filterDefs\";\nimport type { FilterFormSource } from \"./filterForm\";\nimport type { ChipLabelResolver } from \"./useActiveFilterChips\";\n\n/** Built-in widget a kit AutoFilterForm / header row already knows how to draw. */\nexport type FilterWidgetKind = FilterType;\n\n/** Props a custom `render` function receives. */\nexport interface FilterWidgetRenderProps {\n readonly def: FilterDef;\n readonly source: FilterFormSource;\n readonly labels: Required;\n readonly className?: string;\n}\n\n/**\n * One registered filter type: widget + operators + predicate + chips +\n * tree projection. Register a new `type` string, or {@link FilterTypeRegistry.extend}\n * a built-in to add operators without forking the table.\n */\nexport interface FilterTypeSpec {\n readonly type: string;\n /** Which built-in kit widget to draw. Ignored when {@link render} is set. */\n readonly widget: FilterWidgetKind;\n readonly ops: readonly string[];\n readonly defaultOp: string;\n /** Persist this key as a comma-separated array in the URL. */\n readonly urlArray?: boolean;\n /** Persist this type's range bounds as numbers in the URL. */\n readonly urlNumberKeys?: boolean;\n stateKeys(def: Pick): string[];\n match(def: FilterDef, extra: ExtraFilters, row: TRow): boolean;\n chips(def: FilterDef): Record;\n conditionToExtra(\n def: FilterDef,\n condition: QueryCondition\n ): ExtraFilters;\n /** Native renderer — header row and AutoFilterForm use this when set. */\n render?(props: FilterWidgetRenderProps): ReactElement;\n}\n\n/** Immutable registry of {@link FilterTypeSpec}s. */\nexport interface FilterTypeRegistry {\n get(type: string): FilterTypeSpec | undefined;\n has(type: string): boolean;\n types(): readonly string[];\n register(spec: FilterTypeSpec): FilterTypeRegistry;\n extend(type: string, patch: Partial): FilterTypeRegistry;\n}\n\nclass MapRegistry implements FilterTypeRegistry {\n constructor(private readonly specs: ReadonlyMap) {}\n\n get(type: string): FilterTypeSpec | undefined {\n return this.specs.get(type);\n }\n\n has(type: string): boolean {\n return this.specs.has(type);\n }\n\n types(): readonly string[] {\n return [...this.specs.keys()];\n }\n\n register(spec: FilterTypeSpec): FilterTypeRegistry {\n const next = new Map(this.specs);\n next.set(spec.type, spec);\n return new MapRegistry(next);\n }\n\n extend(type: string, patch: Partial): FilterTypeRegistry {\n const current = this.specs.get(type);\n if (!current) {\n devWarn(`extendFilterType: unknown type \"${type}\"`);\n return this;\n }\n return this.register({ ...current, ...patch, type });\n }\n}\n\n/** Empty registry — used to seed {@link createFilterRegistry}. */\nexport function emptyFilterRegistry(): FilterTypeRegistry {\n return new MapRegistry(new Map());\n}\n\n/** Registry from an explicit spec list (last write wins on a repeated type). */\nexport function createFilterRegistry(\n specs: readonly FilterTypeSpec[]\n): FilterTypeRegistry {\n const map = new Map();\n for (const spec of specs) map.set(spec.type, spec);\n return new MapRegistry(map);\n}\n\n/** Look up a spec, or `undefined` for an unknown type. */\nexport function filterTypeSpec(\n type: string,\n registry: FilterTypeRegistry\n): FilterTypeSpec | undefined {\n return registry.get(type);\n}\n\n/** Widget kind a kit should draw for this def. */\nexport function filterWidgetKind(\n def: Pick,\n registry: FilterTypeRegistry\n): FilterWidgetKind | undefined {\n return registry.get(def.type)?.widget;\n}\n\n/** Operators the tree builder offers for this def. */\nexport function filterTypeOps(\n def: Pick,\n registry: FilterTypeRegistry\n): readonly string[] {\n return registry.get(def.type)?.ops ?? [\"eq\"];\n}\n\n/** Default operator when a tree condition is first added. */\nexport function filterTypeDefaultOp(\n def: Pick,\n registry: FilterTypeRegistry\n): string {\n return registry.get(def.type)?.defaultOp ?? \"eq\";\n}\n\n/** Custom `render` for this def, or `undefined` to use the kit widget. */\nexport function renderRegisteredFilter(\n def: FilterDef,\n source: FilterFormSource,\n labels: Required,\n registry: FilterTypeRegistry,\n className?: string\n): ReactElement | undefined {\n return registry.get(def.type)?.render?.({ def, source, labels, className });\n}\n","/**\n * Built-in filter types. Kept off `filterDefs` so a table that only\n * imports `filterLabel` / `useFrontendData` does not pay for every\n * predicate, chip and operator.\n */\nimport { createBuiltInFilterSpecs } from \"./filterDefs\";\nimport {\n createFilterRegistry,\n type FilterTypeRegistry,\n type FilterTypeSpec,\n} from \"./filterRegistry\";\n\n/** Built-in types — the registry's first consumers. */\nexport const builtInFilterSpecs: readonly FilterTypeSpec[] =\n // PURE: a table that never imports the registry must not evaluate this.\n /*#__PURE__*/ createBuiltInFilterSpecs();\n\n/**\n * Default registry: every built-in type, nothing else.\n *\n * It builds its own specs rather than reading {@link builtInFilterSpecs}.\n * Both are pure so a plain table shakes them out, and a pure binding is free\n * to land in a different chunk from the one that reads it — which happened\n * the moment a new entry point changed the chunk layout, and handed this an\n * empty spec list. With no cross-binding there is no order to get wrong.\n */\nexport const defaultFilterRegistry: FilterTypeRegistry =\n /*#__PURE__*/ createFilterRegistry(/*#__PURE__*/ createBuiltInFilterSpecs());\n\n/** Merge host `filterTypes` onto the built-ins (same `type` replaces). */\nexport function resolveFilterRegistry(\n extras?: readonly FilterTypeSpec[]\n): FilterTypeRegistry {\n if (!extras || extras.length === 0) return defaultFilterRegistry;\n return extras.reduce(\n (registry, spec) => registry.register(spec),\n defaultFilterRegistry\n );\n}\n","/** How the table presents filters — one container, never stacked. */\nexport type FilterChromeMode = \"popover\" | \"drawer\" | \"header\";\n\n/**\n * Resolve the single filter chrome. `headerFilters` is an alias for\n * `\"header\"`. Header mode wins when both are passed so a host cannot\n * mount the toolbar overlay and the header row at once.\n */\nexport function resolveFilterMode(\n mode?: FilterChromeMode,\n headerFilters?: boolean\n): FilterChromeMode {\n if (headerFilters === true || mode === \"header\") return \"header\";\n if (mode === \"drawer\") return \"drawer\";\n return \"popover\";\n}\n\n/**\n * Whether the toolbar still shows Filters. Header mode hides that button\n * for the simple form (the icons own those fields) but keeps it when the\n * AND/OR tree is on — the tree has no column of its own.\n */\nexport function toolbarShowsFilters(\n mode: FilterChromeMode,\n hasForm: boolean,\n hasFilterTree: boolean\n): boolean {\n if (!hasForm) return false;\n return mode !== \"header\" || hasFilterTree;\n}\n\n/**\n * Whether the per-field form mounts inside Filters. Header icons own those\n * fields; `filterFields={false}` keeps only the AND/OR tree.\n */\nexport function showSimpleFilterFields(\n headerFiltersOn: boolean,\n filterFields?: boolean\n): boolean {\n if (headerFiltersOn) return false;\n return filterFields !== false;\n}\n","/**\n * The cell that holds open the columns outside the horizontal window.\n *\n * It is one empty cell per side, sized to everything the window skipped, so\n * the table's scroll width matches the columns it claims to have. Aria-hidden\n * because it is scaffolding, not data — a screen reader walking the row would\n * otherwise meet two blank cells whose only job is width.\n */\nimport type { ReactElement } from \"react\";\n\n/** Props for {@link ColumnSpacer}. */\nexport interface ColumnSpacerProps {\n /** Pixel width of the columns this cell stands in for. */\n width: number;\n /** Which side of the window it sits on, for the part name. */\n side: \"start\" | \"end\";\n /** The element to render — a kit's own cell component, or `\"td\"`. */\n as?: \"td\" | \"th\";\n}\n\n/** Renders the spacer, or nothing when there is nothing to hold open. */\nexport function ColumnSpacer({\n width,\n side,\n as = \"td\",\n}: Readonly): ReactElement | null {\n if (width <= 0) return null;\n const Cell = as;\n return (\n \n );\n}\n","import { useCallback, useEffect, useRef } from \"react\";\n\n/**\n * Wrap a callback in a stable identity that always invokes the latest\n * render's version — the ref-latch pattern (a ref updated in an effect,\n * read inside the callback). Effects can call fresh props and state\n * through it without re-running when the caller passes a new closure\n * every render.\n *\n * Works across the full declared React peer range (`^18 || ^19`), unlike\n * `useEffectEvent`, which is only stable from React 19.2. The latch\n * updates in a passive effect, so the returned function is only safe to\n * call from effects that run after it — never during render.\n *\n * @typeParam TArgs - The callback's argument tuple.\n * @typeParam TReturn - The callback's return type.\n * @param callback - The callback to latch; may be a fresh closure each render.\n * @returns A stable function that always calls the latest `callback`.\n */\nexport function useEventCallback(\n callback: (...args: TArgs) => TReturn\n): (...args: TArgs) => TReturn {\n const latest = useRef(callback);\n useEffect(() => {\n latest.current = callback;\n });\n return useCallback((...args: TArgs) => latest.current(...args), []);\n}\n","import { useEffect, useState } from \"react\";\n\nimport { useEventCallback } from \"../hooks/useEventCallback\";\nimport { devWarn } from \"../utils/devWarn\";\nimport type { FilterDef, FilterOption } from \"./filterDefs\";\n\n/** Resolved choices for a select/multiSelect control. */\nexport interface ResolvedFilterOptions {\n /** The choices to render (empty while an async loader is in flight). */\n options: readonly FilterOption[];\n /** True while an async loader is fetching. */\n loading: boolean;\n}\n\nconst EMPTY: readonly FilterOption[] = [];\n\n/**\n * Resolve a definition's option source for the auto-built form: arrays are\n * used as-is, async loaders run once on mount (kit forms show their native\n * loading affordance meanwhile), and a leftover `\"auto\"` — possible only on\n * the server/source tiers, where there is no full dataset to derive from —\n * resolves to no options with a development warning.\n */\nexport function useFilterOptions(\n def: Pick, \"key\" | \"options\">\n): ResolvedFilterOptions {\n const source = def.options;\n const isLoader = typeof source === \"function\";\n const [loaded, setLoaded] = useState(null);\n const [loading, setLoading] = useState(isLoader);\n\n // The load reads the LATEST loader (callers routinely pass it inline, a\n // fresh identity every render) without restarting — only a key change\n // re-runs the effect.\n const startLoad = useEventCallback(() => {\n const loader = source;\n if (typeof loader !== \"function\") return undefined;\n let alive = true;\n setLoading(true);\n void loader().then(\n (options) => {\n if (!alive) return;\n setLoaded(options);\n setLoading(false);\n },\n () => {\n if (!alive) return;\n devWarn(`async options for filter \"${def.key}\" failed to load.`);\n setLoaded(EMPTY);\n setLoading(false);\n }\n );\n return () => {\n alive = false;\n };\n });\n\n useEffect(() => startLoad(), [isLoader, def.key, startLoad]);\n\n // Warn from an effect, not the render path (render stays pure; devWarn\n // already dedupes, this just keeps StrictMode double-renders silent too).\n const isLeftoverAuto = source === \"auto\";\n useEffect(() => {\n if (!isLeftoverAuto) return;\n devWarn(\n `filter \"${def.key}\" uses options: \"auto\" on a tier with no full dataset — provide an options array or loader.`\n );\n }, [isLeftoverAuto, def.key]);\n\n if (Array.isArray(source)) return { options: source, loading: false };\n if (isLoader) return { options: loaded ?? EMPTY, loading };\n return { options: EMPTY, loading: false };\n}\n","/**\n * Compact per-column filter row under the header. Structure only —\n * adapters pass the Search, Select, range inputs and multi menu the\n * end user clicks. Same defs and extra bag the panel uses (#282).\n */\nimport type { CSSProperties, ReactElement, ReactNode } from \"react\";\n\nimport type { ColumnDef, TableLabels } from \"../types\";\nimport { ColumnSpacer } from \"../virtual/ColumnSpacer\";\nimport { defaultFilterRegistry } from \"./filterBuiltins\";\nimport { type FilterDef, filterLabel } from \"./filterDefs\";\nimport {\n type FilterFormSource,\n listFilterValues,\n useBooleanFilterWidget,\n useRangeFilterWidget,\n useTextFilterWidget,\n} from \"./filterForm\";\nimport {\n type FilterTypeRegistry,\n renderRegisteredFilter,\n} from \"./filterRegistry\";\nimport { useFilterOptions } from \"./useFilterOptions\";\n\n/** Class hooks the unstyled adapter maps onto `DataTableClassNames`. */\nexport interface FilterHeaderClassNames {\n filterHeaderRow?: string;\n filterHeaderCell?: string;\n filterHeaderInput?: string;\n filterHeaderMenu?: string;\n headerCell?: string;\n expandHeader?: string;\n reorderHeader?: string;\n selectionHeader?: string;\n actionsHeader?: string;\n}\n\n/** Overlay a sticky `top` on a cell or pad style. */\nexport function headerFilterStickTop(\n sticky: boolean,\n base: CSSProperties | undefined,\n top: number,\n stickyExtras?: CSSProperties\n): CSSProperties | undefined {\n if (!sticky) return base;\n return { ...stickyExtras, ...base, top };\n}\n\n/** Props for an adapter {@link FilterHeaderRow} — no slots on the public API. */\nexport interface FilterHeaderRowProps {\n /** When false the row does not render, even if defs exist. */\n readonly enabled?: boolean;\n readonly columns: readonly ColumnDef[];\n readonly defs: readonly FilterDef[];\n readonly source: FilterFormSource;\n readonly registry?: FilterTypeRegistry;\n readonly labels: Required;\n readonly expandable?: boolean;\n readonly showReorder?: boolean;\n readonly selection?: boolean;\n readonly showActions?: boolean;\n readonly columnSpacers?: { start: number; end: number };\n readonly cellStyle?: (column: ColumnDef) => CSSProperties | undefined;\n readonly pinSide?: (key: string) => \"start\" | \"end\" | undefined;\n readonly padStyle?: CSSProperties;\n readonly stickyAttr?: true;\n readonly classNames?: FilterHeaderClassNames;\n}\n\n/** Props for an adapter {@link FilterHeaderControl} — no slots on the public API. */\nexport interface FilterHeaderControlProps {\n readonly def: FilterDef;\n readonly source: FilterFormSource;\n readonly labels: Required;\n readonly className?: string;\n readonly registry?: FilterTypeRegistry;\n /**\n * Dismiss the overlay after a finished single-control write. Default off.\n * Wired from the table's `closeHeaderFilterOnSelect`.\n */\n readonly closeOnSelect?: boolean;\n}\n\n/** One option in a header Select or multi menu. */\nexport interface FilterHeaderOption {\n readonly value: string;\n readonly label: string;\n}\n\n/** Kit search field a text header cell calls. */\nexport interface FilterHeaderSearchProps {\n readonly label: string;\n readonly placeholder: string;\n readonly value: string;\n readonly className?: string;\n readonly onChange: (value: string) => void;\n}\n\n/** Kit Select a select/boolean header cell calls. */\nexport interface FilterHeaderSelectProps {\n readonly label: string;\n readonly value: string;\n readonly options: readonly FilterHeaderOption[];\n readonly className?: string;\n readonly onChange: (value: string) => void;\n}\n\n/** Kit number/date field a range header cell calls. */\nexport interface FilterHeaderRangeProps {\n readonly label: string;\n readonly type: \"text\" | \"number\" | \"date\";\n readonly value: string;\n readonly onChange: (value: string) => void;\n}\n\n/** Kit compact multi menu a checklist/multiSelect header cell calls. */\nexport interface FilterHeaderMultiProps {\n readonly label: string;\n readonly summary: string;\n readonly options: readonly FilterHeaderOption[];\n readonly selected: readonly string[];\n readonly className?: string;\n readonly menuClassName?: string;\n readonly onToggle: (value: string, checked: boolean) => void;\n}\n\n/** Adapter-supplied controls for {@link FilterHeaderChrome}. */\nexport interface FilterHeaderSlots {\n readonly Search: (props: FilterHeaderSearchProps) => ReactNode;\n readonly Select: (props: FilterHeaderSelectProps) => ReactNode;\n readonly Range: (props: FilterHeaderRangeProps) => ReactNode;\n readonly Multi: (props: FilterHeaderMultiProps) => ReactNode;\n}\n\n/** Props for {@link FilterHeaderChrome}. */\nexport interface FilterHeaderChromeProps<\n TRow,\n> extends FilterHeaderRowProps {\n readonly slots: FilterHeaderSlots;\n}\n\n/** Props for {@link FilterHeaderControlChrome}. */\nexport interface FilterHeaderControlChromeProps<\n TRow,\n> extends FilterHeaderControlProps {\n readonly slots: FilterHeaderSlots;\n}\n\n/** The definition that drives a column's header filter, if any. */\nexport function filterDefForColumn(\n defs: readonly FilterDef[],\n key: string\n): FilterDef | undefined {\n return defs.find((def) => (def.column ?? def.key) === key);\n}\n\nfunction Pad({\n part,\n style,\n stickyAttr,\n className,\n}: Readonly<{\n part: string;\n style?: CSSProperties;\n stickyAttr?: true;\n className?: string;\n}>): ReactElement {\n return (\n \n );\n}\n\nfunction TextCell({\n def,\n source,\n labels,\n className,\n slots,\n}: Readonly<{\n def: FilterDef;\n source: FilterFormSource;\n labels: Required;\n className?: string;\n slots: FilterHeaderSlots;\n}>): ReactElement {\n const widget = useTextFilterWidget(def, source);\n const Search = slots.Search;\n return (\n widget.write(widget.op, value)}\n />\n );\n}\n\nfunction SelectCell({\n def,\n source,\n labels,\n className,\n slots,\n}: Readonly<{\n def: FilterDef;\n source: FilterFormSource;\n labels: Required;\n className?: string;\n slots: FilterHeaderSlots;\n}>): ReactElement {\n const { options } = useFilterOptions(def);\n const selected = listFilterValues(source.extra[def.key]);\n const write = (values: readonly string[]) => {\n source.setExtra(def.key, values.length > 0 ? [...values] : undefined);\n };\n const Select = slots.Select;\n return (\n ({\n value: option.value,\n label: option.label,\n })),\n ]}\n onChange={(value) => {\n write(value === \"\" ? [] : [value]);\n }}\n />\n );\n}\n\nfunction CompactMultiCell({\n def,\n source,\n labels,\n className,\n menuClassName,\n slots,\n}: Readonly<{\n def: FilterDef;\n source: FilterFormSource;\n labels: Required;\n className?: string;\n menuClassName?: string;\n slots: FilterHeaderSlots;\n}>): ReactElement {\n const { options } = useFilterOptions(def);\n const selected = listFilterValues(source.extra[def.key]);\n const write = (values: readonly string[]) => {\n source.setExtra(def.key, values.length > 0 ? [...values] : undefined);\n };\n const first = options.find((option) => option.value === selected[0]);\n let summary = labels.boolAny;\n if (selected.length === 1) summary = first?.label ?? selected[0] ?? summary;\n if (selected.length > 1) summary = labels.groupCount(selected.length);\n const Multi = slots.Multi;\n return (\n ({\n value: option.value,\n label: option.label,\n }))}\n selected={selected}\n className={className}\n menuClassName={menuClassName}\n onToggle={(value, checked) => {\n write(\n checked\n ? [...selected, value]\n : selected.filter((item) => item !== value)\n );\n }}\n />\n );\n}\n\nfunction BooleanCell({\n def,\n source,\n labels,\n className,\n slots,\n}: Readonly<{\n def: FilterDef;\n source: FilterFormSource;\n labels: Required;\n className?: string;\n slots: FilterHeaderSlots;\n}>): ReactElement {\n const widget = useBooleanFilterWidget(def, source);\n const Select = slots.Select;\n return (\n widget.write(value as typeof widget.choice)}\n />\n );\n}\n\nfunction RangeCell({\n def,\n source,\n className,\n slots,\n}: Readonly<{\n def: FilterDef;\n source: FilterFormSource;\n className?: string;\n slots: FilterHeaderSlots;\n}>): ReactElement {\n const widget = useRangeFilterWidget(def, source);\n // Compact header has no operator picker. An unset op would wipe the\n // value on write; `gte` is the same inference a lone lower bound uses.\n const op = widget.op ?? \"gte\";\n const Range = slots.Range;\n return (\n \n widget.write(op, value, widget.b)}\n />\n {widget.arity === \"two\" ? (\n widget.write(op, widget.a, value)}\n />\n ) : null}\n \n );\n}\n\nfunction FilterHeaderCell({\n def,\n source,\n labels,\n className,\n menuClassName,\n registry = defaultFilterRegistry,\n slots,\n}: Readonly<{\n def: FilterDef;\n source: FilterFormSource;\n labels: Required;\n className?: string;\n menuClassName?: string;\n registry?: FilterTypeRegistry;\n slots: FilterHeaderSlots;\n}>): ReactElement | null {\n const spec = registry.get(def.type);\n const custom = renderRegisteredFilter(\n def,\n source,\n labels,\n registry,\n className\n );\n if (custom) return custom;\n switch (spec?.widget ?? def.type) {\n case \"text\":\n return (\n \n );\n case \"select\":\n return (\n \n );\n case \"multiSelect\":\n case \"checklist\":\n return (\n \n );\n case \"boolean\":\n return (\n \n );\n case \"numberRange\":\n case \"dateRange\":\n return (\n \n );\n default:\n return null;\n }\n}\n\n/** Compact control for one filter definition — used in the header row and antd titles. */\nexport function FilterHeaderControlChrome({\n def,\n source,\n labels,\n className,\n registry = defaultFilterRegistry,\n slots,\n}: Readonly>): ReactElement {\n return (\n \n );\n}\n\n/**\n * Second header row of per-column quick filters. Pads and spacers match\n * the leaf header so sticky, pin offsets, and column windowing stay aligned.\n */\nexport function FilterHeaderChrome({\n enabled = true,\n columns,\n defs,\n source,\n labels,\n expandable = false,\n showReorder = false,\n selection = false,\n showActions = false,\n columnSpacers,\n cellStyle,\n pinSide,\n padStyle,\n stickyAttr,\n classNames = {},\n registry = defaultFilterRegistry,\n slots,\n}: Readonly>): ReactElement | null {\n if (!enabled || defs.length === 0) return null;\n const pad = (part: string, extra?: string) => (\n \n );\n return (\n \n {expandable ? pad(\"expand-header\", classNames.expandHeader) : null}\n {showReorder ? pad(\"reorder-header\", classNames.reorderHeader) : null}\n {selection ? pad(\"selection-header\", classNames.selectionHeader) : null}\n {columnSpacers ? (\n \n ) : null}\n {columns.map((column) => {\n const def = filterDefForColumn(defs, column.key);\n return (\n \n {def ? (\n \n ) : null}\n \n );\n })}\n {columnSpacers ? (\n \n ) : null}\n {showActions ? pad(\"actions-header\", classNames.actionsHeader) : null}\n \n );\n}\n","/**\n * The query contract — the shape of everything the table can ask a server for,\n * defined once so the features that arrive later never have to change it.\n *\n * Every field here is optional, on both sides of the wire. A server that\n * ignores all of them behaves exactly as it does today; a table whose source\n * declares no support asks for nothing new. That is the whole design: adding\n * grouping, aggregates, filter trees, facets or cursors to this contract can\n * never break an integration that predates them.\n *\n * A source declares what it can answer through {@link QuerySupport}. The table\n * checks that before it asks, and says so in development when the UI wants\n * something the source did not sign up for — silence there would look like a\n * bug in the table rather than a gap in the integration.\n */\nimport { devWarn } from \"../utils/devWarn\";\n\n/**\n * What a server source can answer, beyond the baseline every source handles\n * (page, limit, search, sort, filters).\n *\n * Omit the whole object — or any field — and the table treats that capability\n * as unavailable: it keeps the work on the frontend where it can, and warns in\n * development where it cannot.\n */\nexport interface QuerySupport {\n /** Grouping keys reach the server, which returns group rows. */\n grouping?: boolean;\n /**\n * The open tree nodes reach the server, which returns the rows of the\n * hierarchy that are visible — the roots, plus the children of every node\n * the reader has opened. The only correct place for a large tree: a browser\n * holding one page cannot know what is under a branch it has never seen.\n */\n tree?: boolean;\n /** Aggregate requests reach the server, which computes the values. */\n aggregates?: boolean;\n /** The nested AND/OR condition tree reaches the server. */\n filterTree?: boolean;\n /** Distinct-value counts per column reach the server. */\n facets?: boolean;\n /** Pagination is by opaque cursor rather than page number. */\n cursor?: boolean;\n}\n\n/** The aggregate functions every implementation is expected to understand. */\nexport type AggregateFn = \"sum\" | \"avg\" | \"count\" | \"min\" | \"max\";\n\n/**\n * One aggregate the table wants computed for a column.\n *\n * `fn` accepts any string so a backend can expose its own aggregations\n * (`\"median\"`, `\"p95\"`) without waiting for this type to name them, while the\n * five standard ones still autocomplete.\n */\nexport interface QueryAggregate {\n /** Column key to aggregate. */\n key: string;\n /** Aggregate function name. */\n fn: AggregateFn | (string & {});\n}\n\n/** A single condition in a filter tree: one column, one operator, one value. */\nexport interface QueryCondition {\n /** Column or filter key. */\n key: string;\n /**\n * Operator id — `\"eq\"`, `\"contains\"`, `\"between\"`, … The operator set is\n * owned by the filtering work; this contract only carries it.\n */\n op: string;\n /** Operand, if the operator takes one. `\"empty\"` and friends do not. */\n value?: unknown;\n}\n\n/**\n * A node in the filter tree: conditions combined with one operator, nestable\n * so `(a AND b) OR c` is expressible.\n */\nexport interface QueryFilterGroup {\n /** How this group's children combine. */\n combinator: \"and\" | \"or\";\n /** Conditions and nested groups, in the order the user built them. */\n conditions: readonly (QueryCondition | QueryFilterGroup)[];\n}\n\n/** Narrows a filter-tree child to a nested group. */\nexport function isFilterGroup(\n node: QueryCondition | QueryFilterGroup\n): node is QueryFilterGroup {\n return \"combinator\" in node;\n}\n\n/**\n * Everything the table can additionally ask for, all optional. These ride on\n * {@link TableQuery} — see that type for the baseline fields.\n */\nexport interface QueryExtensions {\n /**\n * Grouping column keys, outermost first. A single-level grouping sends one\n * key; the field is an array so multi-level grouping needs no new field.\n */\n groupBy?: readonly string[];\n /** Aggregates to compute — per group when grouping, else over the result set. */\n aggregates?: readonly QueryAggregate[];\n /**\n * The nested condition tree, when the UI has built one. The flat `filters`\n * bag stays populated alongside it for servers that only read that.\n */\n filterTree?: QueryFilterGroup;\n /** Column keys needing distinct-value counts for their filter UI. */\n facets?: readonly string[];\n /** Opaque cursor from the previous response, when paginating by cursor. */\n cursor?: string;\n /**\n * The ids of the tree nodes the reader has open, so the server can return\n * their children with the page. Empty means a folded tree — the roots and\n * nothing else.\n */\n expandedIds?: readonly string[];\n}\n\n/** The capability each extension field needs before the table will send it. */\nconst REQUIRES: Record = {\n groupBy: \"grouping\",\n expandedIds: \"tree\",\n aggregates: \"aggregates\",\n filterTree: \"filterTree\",\n facets: \"facets\",\n cursor: \"cursor\",\n};\n\n/** Human-readable reason, so a warning tells the reader what to do next. */\nconst REMEDY: Record = {\n grouping: \"return group rows for `query.groupBy`\",\n tree: \"return the children of every node in `query.expandedIds`\",\n aggregates: \"compute `query.aggregates`\",\n filterTree: \"evaluate `query.filterTree`\",\n facets: \"return counts for `query.facets`\",\n cursor: \"page by `query.cursor` instead of `query.page`\",\n};\n\n/**\n * Keep only the extensions the source declared support for, and say something\n * in development about the ones dropped.\n *\n * The table asks for what the UI is showing; the source decides what it can\n * answer. Where those disagree the field is omitted rather than sent and\n * ignored — a server should never receive a field it never agreed to read.\n */\nexport function applyQuerySupport(\n extensions: QueryExtensions,\n support: QuerySupport | undefined,\n { warn = true }: { warn?: boolean } = {}\n): QueryExtensions {\n const allowed: QueryExtensions = {};\n for (const [field, value] of Object.entries(extensions) as [\n keyof QueryExtensions,\n QueryExtensions[keyof QueryExtensions],\n ][]) {\n if (value === undefined) continue;\n const capability = REQUIRES[field];\n if (support?.[capability]) {\n Object.assign(allowed, { [field]: value });\n } else if (warn) {\n // devWarn dedupes by message, so this fires once per capability per\n // session however often the query changes.\n devWarn(\n `The table wants to send \\`${field}\\`, but this source does not declare ` +\n `\\`supports.${capability}\\`. The field is omitted. Set it once your ` +\n `endpoint can ${REMEDY[capability]}.`\n );\n }\n }\n return allowed;\n}\n","/**\n * AND/OR filter tree — the engine behind advanced filters (#278).\n * The URL and Saved Views store a versioned encoding; the frontend\n * predicate and the server query both read the same {@link QueryFilterGroup}.\n * The builder UI is #279; this file is the evaluator.\n */\nimport type { QueryCondition, QueryFilterGroup } from \"../source/queryContract\";\nimport { isFilterGroup } from \"../source/queryContract\";\nimport type { ExtraFilters } from \"../types\";\nimport { defaultFilterRegistry } from \"./filterBuiltins\";\nimport { type FilterDef, filterPredicate } from \"./filterDefs\";\nimport type { FilterTypeRegistry } from \"./filterRegistry\";\nimport { isActiveFilterTree } from \"./filterTreeCodec\";\nimport { filterOpKey } from \"./operators\";\n\nexport {\n FILTER_TREE_PARAM,\n FILTER_TREE_VERSION,\n isActiveFilterTree,\n parseFilterTree,\n serializeFilterTree,\n} from \"./filterTreeCodec\";\n\nfunction asScalar(value: unknown): string | undefined {\n if (value == null) return undefined;\n if (typeof value === \"string\") return value;\n if (typeof value === \"number\" || typeof value === \"boolean\") {\n return String(value);\n }\n return undefined;\n}\n\n/**\n * Project one tree condition onto the extra-filter bag the existing\n * per-def predicate already understands.\n */\nexport function conditionToExtra(\n def: FilterDef,\n condition: QueryCondition,\n registry: FilterTypeRegistry = defaultFilterRegistry\n): ExtraFilters {\n const spec = registry.get(def.type);\n if (spec) return spec.conditionToExtra(def, condition);\n return {\n [def.key]: asScalar(condition.value),\n [filterOpKey(def.key)]: condition.op,\n };\n}\n\nfunction matchCondition(\n row: TRow,\n condition: QueryCondition,\n defs: readonly FilterDef[],\n registry: FilterTypeRegistry\n): boolean {\n const def = defs.find((item) => item.key === condition.key);\n if (!def) return true;\n return filterPredicate(def, registry)(\n row,\n conditionToExtra(def, condition, registry)\n );\n}\n\n/**\n * Evaluate a tree against one row. An empty / missing tree matches\n * every row. Unknown condition keys match (stale links do not hide data).\n */\nexport function evaluateFilterTree(\n tree: QueryFilterGroup | undefined,\n row: TRow,\n defs: readonly FilterDef[],\n registry: FilterTypeRegistry = defaultFilterRegistry\n): boolean {\n if (!isActiveFilterTree(tree)) return true;\n const results = tree.conditions.map((node) =>\n isFilterGroup(node)\n ? evaluateFilterTree(node, row, defs, registry)\n : matchCondition(row, node, defs, registry)\n );\n return tree.combinator === \"and\"\n ? results.every(Boolean)\n : results.some(Boolean);\n}\n","/**\n * Immutable updates for an AND/OR filter tree. Paths are child indexes\n * from the root (`[]` is the root group).\n */\nimport type { QueryCondition, QueryFilterGroup } from \"../source/queryContract\";\nimport { isFilterGroup } from \"../source/queryContract\";\n\nexport type FilterTreeNode = QueryCondition | QueryFilterGroup;\n\n/** An empty AND group — the tree a first \"Add condition\" starts from. */\nexport function emptyFilterTree(): QueryFilterGroup {\n return { combinator: \"and\", conditions: [] };\n}\n\nfunction cloneGroup(group: QueryFilterGroup): QueryFilterGroup {\n return { combinator: group.combinator, conditions: [...group.conditions] };\n}\n\nfunction atGroup(\n tree: QueryFilterGroup,\n path: readonly number[]\n): QueryFilterGroup | undefined {\n let current = tree;\n for (const index of path) {\n const child = current.conditions[index];\n if (!child || !isFilterGroup(child)) return undefined;\n current = child;\n }\n return current;\n}\n\nfunction replaceChild(\n tree: QueryFilterGroup,\n path: readonly number[],\n index: number,\n next: FilterTreeNode | undefined\n): QueryFilterGroup {\n if (path.length === 0) {\n const group = cloneGroup(tree);\n const conditions = [...group.conditions];\n if (next === undefined) conditions.splice(index, 1);\n else conditions[index] = next;\n return { ...group, conditions };\n }\n const [head, ...rest] = path;\n const child = tree.conditions[head!];\n if (!child || !isFilterGroup(child)) return tree;\n const updated = replaceChild(child, rest, index, next);\n return replaceChild(tree, [], head!, updated);\n}\n\n/** Set the combinator on the group at `path`. */\nexport function setFilterTreeCombinator(\n tree: QueryFilterGroup,\n path: readonly number[],\n combinator: QueryFilterGroup[\"combinator\"]\n): QueryFilterGroup {\n const group = atGroup(tree, path);\n if (!group) return tree;\n if (path.length === 0) return { ...tree, combinator };\n const parentPath = path.slice(0, -1);\n const index = path.at(-1)!;\n return replaceChild(tree, parentPath, index, { ...group, combinator });\n}\n\n/** Append a child to the group at `path`. */\nexport function appendFilterTreeChild(\n tree: QueryFilterGroup | undefined,\n path: readonly number[],\n child: FilterTreeNode\n): QueryFilterGroup {\n const root = tree ?? emptyFilterTree();\n const group = atGroup(root, path);\n if (!group) return root;\n const next: QueryFilterGroup = {\n ...group,\n conditions: [...group.conditions, child],\n };\n if (path.length === 0) return next;\n const parentPath = path.slice(0, -1);\n const index = path.at(-1)!;\n return replaceChild(root, parentPath, index, next);\n}\n\n/** Append a condition to the group at `path`. */\nexport function addFilterTreeCondition(\n tree: QueryFilterGroup | undefined,\n path: readonly number[],\n condition: QueryCondition\n): QueryFilterGroup {\n return appendFilterTreeChild(tree, path, condition);\n}\n\n/** Append a nested AND group to the group at `path`. */\nexport function addFilterTreeGroup(\n tree: QueryFilterGroup | undefined,\n path: readonly number[]\n): QueryFilterGroup {\n return appendFilterTreeChild(tree, path, emptyFilterTree());\n}\n\n/** Replace the node at `path` (path must name a child, not the root). */\nexport function replaceFilterTreeNode(\n tree: QueryFilterGroup,\n path: readonly number[],\n next: FilterTreeNode\n): QueryFilterGroup {\n if (path.length === 0) {\n return isFilterGroup(next) ? next : tree;\n }\n const parentPath = path.slice(0, -1);\n const index = path.at(-1)!;\n return replaceChild(tree, parentPath, index, next);\n}\n\n/**\n * Remove the node at `path`. Removing the last root child returns\n * `undefined` so the URL drops `ft`.\n */\nexport function removeFilterTreeNode(\n tree: QueryFilterGroup,\n path: readonly number[]\n): QueryFilterGroup | undefined {\n if (path.length === 0) return undefined;\n const parentPath = path.slice(0, -1);\n const index = path.at(-1)!;\n const next = replaceChild(tree, parentPath, index, undefined);\n if (next.conditions.length === 0) return undefined;\n return next;\n}\n\n/** Walk every leaf, with the path to that leaf. */\nexport function walkFilterTreeConditions(\n tree: QueryFilterGroup | undefined,\n path: readonly number[] = []\n): { condition: QueryCondition; path: readonly number[] }[] {\n if (!tree) return [];\n const out: { condition: QueryCondition; path: readonly number[] }[] = [];\n tree.conditions.forEach((node, index) => {\n const childPath = [...path, index];\n if (isFilterGroup(node)) {\n out.push(...walkFilterTreeConditions(node, childPath));\n return;\n }\n out.push({ condition: node, path: childPath });\n });\n return out;\n}\n","/**\n * Removable chips for every leaf in the AND/OR filter tree.\n */\nimport { useMemo } from \"react\";\n\nimport type { QueryCondition, QueryFilterGroup } from \"../source/queryContract\";\nimport type { TableLabels } from \"../types\";\nimport { type FilterDef, filterLabel } from \"./filterDefs\";\nimport { filterOpLabel } from \"./filterForm\";\nimport {\n removeFilterTreeNode,\n walkFilterTreeConditions,\n} from \"./filterTreeMutations\";\nimport {\n DATE_OP_LABEL_KEYS,\n type DateOp,\n formatFilterChip,\n NUMBER_OP_LABEL_KEYS,\n type NumberOp,\n TEXT_OP_LABEL_KEYS,\n type TextOp,\n} from \"./operators\";\nimport { relativeTokenLabel } from \"./relativeDates\";\nimport type { ActiveFilterChip } from \"./useActiveFilterChips\";\n\nfunction conditionValueText(\n condition: QueryCondition,\n labels: Required\n): string | undefined {\n const value = condition.value;\n if (condition.op === \"relative\" && typeof value === \"string\") {\n return relativeTokenLabel(value, labels);\n }\n if (Array.isArray(value)) {\n const parts = value\n .map((item) =>\n typeof item === \"string\" ||\n typeof item === \"number\" ||\n typeof item === \"boolean\"\n ? String(item)\n : \"\"\n )\n .filter(Boolean);\n return parts.length > 0 ? parts.join(\", \") : undefined;\n }\n if (value == null || value === \"\") return undefined;\n if (typeof value === \"string\") return value;\n if (typeof value === \"number\" || typeof value === \"boolean\") {\n return String(value);\n }\n return undefined;\n}\n\nfunction conditionOpWord(\n def: FilterDef | undefined,\n op: string,\n labels: Required\n): string {\n if (def?.type === \"text\" && op in TEXT_OP_LABEL_KEYS) {\n return filterOpLabel(labels, TEXT_OP_LABEL_KEYS[op as TextOp]);\n }\n if (def?.type === \"numberRange\" && op in NUMBER_OP_LABEL_KEYS) {\n return filterOpLabel(labels, NUMBER_OP_LABEL_KEYS[op as NumberOp]);\n }\n if (def?.type === \"dateRange\" && op in DATE_OP_LABEL_KEYS) {\n return filterOpLabel(labels, DATE_OP_LABEL_KEYS[op as DateOp]);\n }\n return op;\n}\n\n/** Build one chip label for a tree leaf. */\nexport function filterTreeChipLabel(\n condition: QueryCondition,\n defs: readonly FilterDef[],\n labels: Required\n): string {\n const def = defs.find((item) => item.key === condition.key);\n const field = def ? filterLabel(def) : condition.key;\n return formatFilterChip(\n field,\n conditionOpWord(def, condition.op, labels),\n conditionValueText(condition, labels)\n );\n}\n\n/** Options for {@link useFilterTreeChips}. */\nexport interface UseFilterTreeChipsOptions {\n readonly tree: QueryFilterGroup | undefined;\n readonly defs: readonly FilterDef[];\n readonly labels: Required;\n readonly setFilterTree?: (tree: QueryFilterGroup | undefined) => void;\n}\n\n/** Flatten the tree into removable chips. */\nexport function useFilterTreeChips(\n options: UseFilterTreeChipsOptions\n): readonly ActiveFilterChip[] {\n const { tree, defs, labels, setFilterTree } = options;\n return useMemo(() => {\n if (!tree || !setFilterTree) return [];\n return walkFilterTreeConditions(tree).map(({ condition, path }) => ({\n key: `ft:${path.join(\".\")}:${condition.key}:${condition.op}`,\n label: filterTreeChipLabel(condition, defs, labels),\n onRemove: () => setFilterTree(removeFilterTreeNode(tree, path)),\n }));\n }, [defs, labels, setFilterTree, tree]);\n}\n","/**\n * Find in table — locating text without filtering it away.\n *\n * Search and find are different questions. The search box asks \"show me only\n * the rows that match\", and on a server tier it asks the server. Find asks\n * \"where does this appear in what I am looking at\", leaves every row where it\n * is, and walks the hits — which is what people mean when they press Ctrl+F.\n *\n * Matching reads what the cell SHOWS (`columnText`, the same resolution the\n * screen-reader announcements use), so a column that renders a formatted date\n * is searched by that date rather than by the ISO string underneath. Nothing\n * else would match what a person can see on screen.\n */\nimport { columnText } from \"../columns/columnText\";\nimport type { GridCell } from \"../focus/gridFocus\";\nimport type { ColumnDef } from \"../types\";\n\n/** What a find needs to know. */\nexport interface FindMatchesOptions {\n /** What to look for. An empty or blank query matches nothing. */\n query: string;\n /** The rows the browser holds, in table order. */\n rows: readonly TRow[];\n /** The columns as rendered — matches are addressed by their index. */\n columns: readonly ColumnDef[];\n /** Where the rendered window starts in the dataset. Zero unless paged. */\n firstRowIndex?: number;\n}\n\n/**\n * Every cell whose text contains the query, in reading order.\n *\n * Case-insensitive, because nobody types the case of what they are looking\n * for. Only the LOADED rows are searched: a find cannot honestly claim a hit\n * in a row the browser has never seen, and saying \"3 of 17\" about rows that\n * are not there would be worse than saying nothing.\n *\n * @typeParam TRow - The row type.\n * @param options - See {@link FindMatchesOptions}.\n * @returns The matching cells, in absolute addresses.\n */\nexport function findMatches(\n options: FindMatchesOptions\n): GridCell[] {\n const { query, rows, columns, firstRowIndex = 0 } = options;\n const needle = query.trim().toLowerCase();\n if (needle === \"\") return [];\n\n const matches: GridCell[] = [];\n rows.forEach((row, index) => {\n columns.forEach((column, col) => {\n if (columnText(column, row).toLowerCase().includes(needle)) {\n matches.push({ row: firstRowIndex + index, col });\n }\n });\n });\n return matches;\n}\n\n/** A cell address as a string, for set membership without a nested scan. */\nexport function matchKey(cell: GridCell): string {\n return `${cell.row}:${cell.col}`;\n}\n\n/**\n * The match keys as a set, so a cell can ask \"am I a match\" in constant time.\n *\n * A table of 500 rows × 12 columns asks that question 6,000 times per render;\n * scanning an array each time is the difference between a find that feels\n * instant and one that stutters.\n *\n * @param matches - The matches, from {@link findMatches}.\n * @returns Their keys.\n */\nexport function matchKeySet(matches: readonly GridCell[]): ReadonlySet {\n return new Set(matches.map(matchKey));\n}\n\n/**\n * Step through the matches, wrapping at both ends.\n *\n * Wrapping is what a find does — reaching the last hit and pressing next\n * returns to the first, which is why a browser's find bar says \"1 of 17\"\n * again rather than stopping.\n *\n * @param index - Where the walk is now.\n * @param total - How many matches there are.\n * @param step - `1` for next, `-1` for previous.\n * @returns The next index, or `-1` when there is nothing to step through.\n */\nexport function stepMatch(index: number, total: number, step: number): number {\n if (total === 0) return -1;\n return (((index + step) % total) + total) % total;\n}\n","/**\n * Where the keyboard is, in a grid of cells — the pure part.\n *\n * A table is one tab stop, not hundreds. The focused cell carries\n * `tabIndex=0` and every other cell `-1`, so Tab enters and leaves the table\n * while the arrow keys move inside it. That is the roving-tabindex pattern the\n * ARIA grid practice asks for, and it is the only reason a 10,000-row table is\n * navigable at all.\n *\n * This file is the arithmetic: given where focus is and which key was pressed,\n * where does it go. No React, no DOM — which is what makes every edge testable\n * without rendering anything. {@link useGridFocus} owns the state and the\n * scrolling, and the adapters own none of it.\n */\nimport type { Direction } from \"../types\";\n\n/** A cell address in the grid: both indices absolute, both zero-based. */\nexport interface GridCell {\n /** Row index within the whole dataset, not within the rendered window. */\n row: number;\n /** Column index within the visible column set. */\n col: number;\n}\n\n/** The grid's shape, as the mover needs to see it. */\nexport interface GridBounds {\n /** Total rows the user can reach — the dataset, not the rendered slice. */\n rowCount: number;\n /** Total columns the user can reach. */\n colCount: number;\n /**\n * Rows a PageUp/PageDown travels. The viewport's worth, so paging feels like\n * paging rather than an arbitrary jump.\n */\n pageSize: number;\n}\n\n/**\n * What a key press means. Named rather than passed as raw keys so the mapping\n * is testable on its own and an adapter can bind a kit's own control to the\n * same intent.\n */\nexport type GridFocusMove =\n | \"up\"\n | \"down\"\n | \"left\"\n | \"right\"\n | \"rowStart\"\n | \"rowEnd\"\n | \"gridStart\"\n | \"gridEnd\"\n | \"pageUp\"\n | \"pageDown\";\n\n/** Clamp to the grid; a move that would leave it stops at the edge instead. */\nfunction clamp(value: number, max: number): number {\n if (value < 0) return 0;\n if (value > max) return max;\n return value;\n}\n\n/**\n * Where a move lands, clamped to the grid.\n *\n * Edges stop rather than wrap. Wrapping a right-arrow from the last column to\n * the first cell of the next row is a spreadsheet convention, and in a table\n * it silently moves the user to a different record — so this holds still and\n * lets the screen reader stay quiet.\n *\n * @param from - Where focus is now.\n * @param move - The intent, from {@link gridFocusMoveForKey}.\n * @param bounds - The grid's shape.\n * @returns The new address, which may equal `from` at an edge.\n */\nfunction stepGridFocus(\n from: GridCell,\n move: GridFocusMove,\n bounds: GridBounds\n): GridCell {\n const lastRow = Math.max(0, bounds.rowCount - 1);\n const lastCol = Math.max(0, bounds.colCount - 1);\n const step = Math.max(1, bounds.pageSize);\n\n switch (move) {\n case \"up\":\n return { row: clamp(from.row - 1, lastRow), col: from.col };\n case \"down\":\n return { row: clamp(from.row + 1, lastRow), col: from.col };\n case \"left\":\n return { row: from.row, col: clamp(from.col - 1, lastCol) };\n case \"right\":\n return { row: from.row, col: clamp(from.col + 1, lastCol) };\n case \"rowStart\":\n return { row: from.row, col: 0 };\n case \"rowEnd\":\n return { row: from.row, col: lastCol };\n case \"gridStart\":\n return { row: 0, col: 0 };\n case \"gridEnd\":\n return { row: lastRow, col: lastCol };\n case \"pageUp\":\n return { row: clamp(from.row - step, lastRow), col: from.col };\n case \"pageDown\":\n return { row: clamp(from.row + step, lastRow), col: from.col };\n }\n}\n\n/**\n * Where a move lands, clamped to the grid.\n *\n * Edges stop rather than wrap. Wrapping a right-arrow from the last column to\n * the first cell of the next row is a spreadsheet convention, and in a table\n * it silently moves the user to a different record — so this holds still and\n * lets the screen reader stay quiet.\n *\n * A covered cell (inside someone else's row/col span) is skipped in the\n * same direction; if every remaining cell is covered, focus stays put.\n *\n * @param from - Where focus is now.\n * @param move - The intent, from {@link gridFocusMoveForKey}.\n * @param bounds - The grid's shape.\n * @param covered - True for a cell that must not receive focus.\n * @returns The new address, which may equal `from` at an edge.\n */\nexport function moveGridFocus(\n from: GridCell,\n move: GridFocusMove,\n bounds: GridBounds,\n covered?: (cell: GridCell) => boolean\n): GridCell {\n const landed = stepGridFocus(from, move, bounds);\n if (!covered?.(landed)) return landed;\n let current = landed;\n // Edges stop rather than wrap, so this always hits `sameGridCell` before\n // it could cycle. A trip-count would never run.\n for (;;) {\n const next = stepGridFocus(current, move, bounds);\n if (sameGridCell(next, current)) return from;\n if (!covered(next)) return next;\n current = next;\n }\n}\n\n/** The key press, as much of it as the mapping needs. */\nexport interface GridKeyPress {\n key: string;\n /** Ctrl or Cmd — either one means \"to the end of the grid\". */\n ctrlKey?: boolean;\n metaKey?: boolean;\n}\n\n/**\n * Turn a key press into a move, or `null` when the grid should not react.\n *\n * Left and Right swap under `dir=\"rtl\"`, because the arrow keys describe the\n * screen and not the data: in a mirrored table the visually-next column is the\n * previous one. Nothing else flips — Home is still the start of the row, which\n * in RTL is its right-hand end, and that is what a user pressing Home wants.\n *\n * @param press - The key event, narrowed to what matters.\n * @param dir - The table's text direction.\n * @returns The intended move, or `null` to let the event through untouched.\n */\nexport function gridFocusMoveForKey(\n press: GridKeyPress,\n dir: Direction = \"ltr\"\n): GridFocusMove | null {\n const toEnd =\n Boolean(press.ctrlKey ?? false) || Boolean(press.metaKey ?? false);\n const rtl = dir === \"rtl\";\n\n switch (press.key) {\n case \"ArrowUp\":\n return \"up\";\n case \"ArrowDown\":\n return \"down\";\n case \"ArrowLeft\":\n return rtl ? \"right\" : \"left\";\n case \"ArrowRight\":\n return rtl ? \"left\" : \"right\";\n case \"Home\":\n return toEnd ? \"gridStart\" : \"rowStart\";\n case \"End\":\n return toEnd ? \"gridEnd\" : \"rowEnd\";\n case \"PageUp\":\n return \"pageUp\";\n case \"PageDown\":\n return \"pageDown\";\n default:\n return null;\n }\n}\n\n/** Are two addresses the same cell? */\nexport function sameGridCell(a: GridCell | null, b: GridCell | null): boolean {\n if (!a || !b) return a === b;\n return a.row === b.row && a.col === b.col;\n}\n","/**\n * A rectangle of selected cells — the pure part.\n *\n * Range selection is two addresses, not a list: an **anchor** where the\n * selection started and a **head** where it currently reaches. Every cell\n * between them is selected, which is why extending a range never has to\n * enumerate anything and a 10,000-row selection costs two numbers.\n *\n * Keeping the anchor is the whole reason this is a model rather than a set.\n * Shift+Down twice then Shift+Up must shrink the range back, not start a new\n * one downward — and it only does that if the origin is remembered.\n */\nimport { type GridCell, sameGridCell } from \"./gridFocus\";\n\n/** A rectangle of cells, stored as the two corners that made it. */\nexport interface CellRange {\n /** Where the selection began — fixed while the head moves. */\n anchor: GridCell;\n /** Where it currently reaches — the moving corner. */\n head: GridCell;\n}\n\n/** The rectangle's edges, normalized so `from` is always the top-left. */\nexport interface CellRangeBounds {\n fromRow: number;\n toRow: number;\n fromCol: number;\n toCol: number;\n}\n\n/**\n * The rectangle a range covers, with the corners sorted.\n *\n * A range dragged upward has an anchor below its head, so every consumer would\n * otherwise repeat the same min/max dance and one of them would forget.\n */\nexport function cellRangeBounds(range: CellRange): CellRangeBounds {\n return {\n fromRow: Math.min(range.anchor.row, range.head.row),\n toRow: Math.max(range.anchor.row, range.head.row),\n fromCol: Math.min(range.anchor.col, range.head.col),\n toCol: Math.max(range.anchor.col, range.head.col),\n };\n}\n\n/** Is this cell inside the range? */\nexport function isInCellRange(\n range: CellRange | null,\n cell: GridCell\n): boolean {\n if (!range) return false;\n const b = cellRangeBounds(range);\n return (\n cell.row >= b.fromRow &&\n cell.row <= b.toRow &&\n cell.col >= b.fromCol &&\n cell.col <= b.toCol\n );\n}\n\n/** How many cells the range covers — rows × columns, never enumerated. */\nexport function cellRangeSize(range: CellRange | null): number {\n if (!range) return 0;\n const b = cellRangeBounds(range);\n return (b.toRow - b.fromRow + 1) * (b.toCol - b.fromCol + 1);\n}\n\n/** A single cell selected on its own. */\nexport function singleCellRange(cell: GridCell): CellRange {\n return { anchor: cell, head: cell };\n}\n\n/**\n * Move the head, keeping the anchor — what Shift+arrow and Shift+click do.\n *\n * Starting from nothing anchors at the cell that had focus, so the first\n * Shift+Down selects two cells rather than one.\n */\nexport function extendCellRange(\n range: CellRange | null,\n head: GridCell,\n fallbackAnchor: GridCell\n): CellRange {\n return { anchor: range?.anchor ?? fallbackAnchor, head };\n}\n\n/** Is the range a single cell? Useful for deciding whether to show chrome. */\nexport function isSingleCell(range: CellRange | null): boolean {\n return range !== null && sameGridCell(range.anchor, range.head);\n}\n\n/**\n * The rows and columns a range covers, as index lists.\n *\n * This is the one place that does enumerate, because an exporter has to walk\n * them — and it is a deliberate boundary: the model stays two corners, and\n * anything that needs the cells asks for them explicitly.\n */\nexport function cellRangeIndices(range: CellRange): {\n rows: number[];\n cols: number[];\n} {\n const b = cellRangeBounds(range);\n const rows: number[] = [];\n const cols: number[] = [];\n for (let r = b.fromRow; r <= b.toRow; r++) rows.push(r);\n for (let c = b.fromCol; c <= b.toCol; c++) cols.push(c);\n return { rows, cols };\n}\n","/**\n * The find bar's state: the query, the hits, and which one you are on.\n *\n * It knows nothing about focus. The shell moves focus to the current match\n * through the grid it already has, which keeps this hook pure enough to test\n * without a DOM and stops two pieces of code owning \"where the table is\n * looking\".\n */\nimport { useCallback, useEffect, useMemo, useState } from \"react\";\n\nimport type { CellRange } from \"../focus/cellRange\";\nimport { singleCellRange } from \"../focus/cellRange\";\nimport type { GridCell } from \"../focus/gridFocus\";\nimport type { ColumnDef } from \"../types\";\nimport { findMatches, matchKeySet, stepMatch } from \"./findMatches\";\n\n/** What {@link useFindInTable} needs. */\nexport interface UseFindInTableOptions {\n /** Off unless the host asked for it; when false nothing is searched. */\n enabled: boolean;\n /** The rows the browser holds, in table order. */\n rows: readonly TRow[];\n /** The columns as rendered. */\n columns: readonly ColumnDef[];\n /** Where the rendered window starts in the dataset. Zero unless paged. */\n firstRowIndex?: number;\n}\n\n/** What {@link useFindInTable} returns. */\nexport interface FindInTableState {\n /** Whether the bar is showing. */\n open: boolean;\n /** Show or hide the bar. Hiding clears the query, as a find bar does. */\n setOpen: (open: boolean) => void;\n /** The current query. */\n query: string;\n /** Type into the find bar. Resets the walk to the first hit. */\n setQuery: (query: string) => void;\n /** Every matching cell, in reading order. */\n matches: readonly GridCell[];\n /** Their keys, for marking cells as this render walks them. */\n matchKeys: ReadonlySet;\n /** Which match the walk is on, from zero; `-1` when there are none. */\n index: number;\n /** The cell the walk is on, or `null`. */\n current: GridCell | null;\n /** Step to the next hit, wrapping at the end. */\n next: () => void;\n /** Step to the previous hit, wrapping at the start. */\n previous: () => void;\n /**\n * Open the bar — what Ctrl/Cmd+F and a host's own button call. `undefined`\n * when the feature is off, so the shortcut stays the BROWSER'S rather than\n * being swallowed by a table that has no bar to show.\n */\n openBar?: () => void;\n}\n\n/**\n * Find state over the loaded rows.\n *\n * @typeParam TRow - The row type.\n * @param options - See {@link UseFindInTableOptions}.\n * @returns The state; inert with `enabled` false.\n */\nexport function useFindInTable(\n options: UseFindInTableOptions\n): FindInTableState {\n const { enabled, rows, columns, firstRowIndex = 0 } = options;\n const [open, setOpen] = useState(false);\n const [query, setQuery] = useState(\"\");\n const [index, setIndex] = useState(-1);\n\n const matches = useMemo(\n () =>\n enabled && open\n ? findMatches({ query, rows, columns, firstRowIndex })\n : [],\n [enabled, open, query, rows, columns, firstRowIndex]\n );\n const matchKeys = useMemo(() => matchKeySet(matches), [matches]);\n\n const writeQuery = useCallback((next: string) => {\n setQuery(next);\n // A new query starts the walk again: staying on hit 9 of the last search\n // would land the user somewhere unrelated.\n setIndex(next.trim() === \"\" ? -1 : 0);\n }, []);\n\n const writeOpen = useCallback(\n (next: boolean) => {\n setOpen(next);\n // Closing clears the query, so reopening starts clean and no cell stays\n // marked behind a bar that is no longer on screen.\n if (!next) writeQuery(\"\");\n },\n [writeQuery]\n );\n\n const step = useCallback(\n (by: number) => {\n setIndex((current) => stepMatch(current, matches.length, by));\n },\n [matches.length]\n );\n const openBar = useCallback(() => {\n writeOpen(true);\n }, [writeOpen]);\n const next = useCallback(() => {\n step(1);\n }, [step]);\n const previous = useCallback(() => {\n step(-1);\n }, [step]);\n\n // The walk can outlive its target: typing narrows the hits, and a row can\n // leave the window on the next page. Clamp rather than pointing at nothing.\n const safeIndex =\n matches.length === 0\n ? -1\n : Math.min(Math.max(index, 0), matches.length - 1);\n\n return useMemo(\n () => ({\n open: enabled && open,\n setOpen: writeOpen,\n query,\n setQuery: writeQuery,\n matches,\n matchKeys,\n index: safeIndex,\n current: safeIndex === -1 ? null : (matches[safeIndex] ?? null),\n next,\n previous,\n openBar: enabled ? openBar : undefined,\n }),\n [\n enabled,\n open,\n writeOpen,\n query,\n writeQuery,\n matches,\n matchKeys,\n safeIndex,\n next,\n previous,\n openBar,\n ]\n );\n}\n\n/**\n * Take the table's focus to whichever match the walk is on.\n *\n * Highlighting alone is not finding: with 500 rows rendered, the hit is\n * usually off-screen, so the walk moves focus — which scrolls the cell into\n * view, announces it, and leaves it selected. Both the shell and the antd\n * adapter wire find this way, and this is the one place that rule lives.\n *\n * @param current - The match the walk is on, or `null`.\n * @param focusCell - The grid's `focusCell`.\n * @param selectRange - The grid's `selectRange`.\n */\nexport function useFindFocus(\n current: GridCell | null,\n focusCell: (cell: GridCell) => void,\n selectRange: (range: CellRange | null) => void\n): void {\n useEffect(() => {\n if (!current) return;\n focusCell(current);\n selectRange(singleCellRange(current));\n }, [current, focusCell, selectRange]);\n}\n","/**\n * What a batch gesture commits, and who receives it.\n *\n * Paste and fill both write many cells at once, and both do it as ORDINARY\n * edits: the same shape an inline commit produces, through the same handler.\n * That is deliberate — anything later wrapped around single-cell editing\n * (validation, async saves, conflict handling) covers a batch without the\n * batch knowing it exists, and there is never a second half-maintained\n * editing route to keep in step.\n */\n/** One cell written — exactly what an inline commit writes. */\nexport interface CellEdit {\n /** The row being written. */\n row: TRow;\n /** Which column, by key. */\n columnKey: string;\n /** The value to commit, already through the column's `parseValue`. */\n value: unknown;\n}\n\n/**\n * Resolve who receives a batch of edits.\n *\n * A table that can already be edited can already be pasted into and filled:\n * with no batch handler, each edit goes through `onCellEdit`, the exact call\n * an inline commit makes. The batch handler exists for hosts that want the\n * whole set at once — one server round trip, one undo entry — and takes\n * precedence when given.\n *\n * @typeParam TRow - The row type.\n * @param batch - The host's batch handler, when it has one.\n * @param onCellEdit - The ordinary inline-edit channel.\n * @returns The handler, or `undefined` when the table takes no edits at all —\n * which leaves the gesture's key or drag to the browser.\n */\nexport function batchEditHandler(\n batch: ((edits: CellEdit[]) => void) | undefined,\n onCellEdit: ((row: TRow, key: string, nextValue: unknown) => void) | undefined\n): ((edits: CellEdit[]) => void) | undefined {\n if (batch) return batch;\n if (!onCellEdit) return undefined;\n return (edits) => {\n for (const edit of edits) onCellEdit(edit.row, edit.columnKey, edit.value);\n };\n}\n","/**\n * The selected rectangle, as a spreadsheet reads it.\n *\n * Excel, Google Sheets, Numbers and LibreOffice all put tab-separated text on\n * the clipboard and all parse it back, so TSV — not CSV, not JSON — is what\n * makes copy and paste work between a table and the thing people actually use.\n * A cell containing a tab or a newline is quoted the way those applications\n * quote it, which is RFC-4180's rule applied to a tab delimiter.\n *\n * Values come from the same resolution the exports use, so what lands in a\n * spreadsheet from a copy and from a downloaded file cannot disagree.\n */\nimport { buildExportTable } from \"../export/exportWriter\";\nimport type { ColumnDef } from \"../types\";\nimport { type CellRange, cellRangeIndices } from \"./cellRange\";\n\n/** What a copy needs to know: the rectangle, and the data under it. */\nexport interface ClipboardRangeOptions {\n /** The selected rectangle, in absolute addresses. */\n range: CellRange;\n /** The rows the browser holds, in table order. */\n rows: readonly TRow[];\n /** The columns as rendered — a range's column indices address these. */\n columns: readonly ColumnDef[];\n /** Where the rendered window starts in the dataset. Zero unless paged. */\n firstRowIndex?: number;\n /** Include a header row naming each column. Defaults to `false`. */\n headers?: boolean;\n}\n\n/** A tab or a newline inside a cell would end the field or the row. */\nfunction escapeCell(text: string): string {\n return /[\\t\\n\\r\"]/.test(text) ? `\"${text.replaceAll('\"', '\"\"')}\"` : text;\n}\n\n/** A value as clipboard text — primitives stringify, anything else is empty. */\nfunction cellText(value: unknown): string {\n if (typeof value === \"string\") return value;\n if (typeof value === \"number\" || typeof value === \"boolean\") {\n return String(value);\n }\n return \"\";\n}\n\n/**\n * The selected rectangle as tab-separated text, ready for the clipboard.\n *\n * Rows outside what the browser holds are skipped rather than written blank: a\n * range can only cover loaded rows, and inventing empty ones would paste holes\n * into someone's spreadsheet.\n *\n * @typeParam TRow - The row type.\n * @param options - See {@link ClipboardRangeOptions}.\n * @returns TSV text; an empty string when the range covers nothing loaded.\n */\nexport function clipboardRangeText(\n options: ClipboardRangeOptions\n): string {\n const { range, rows, columns, firstRowIndex = 0, headers = false } = options;\n const indices = cellRangeIndices(range);\n const cols = indices.cols.flatMap((index) => {\n const column = columns[index];\n return column ? [column] : [];\n });\n if (cols.length === 0) return \"\";\n\n const selected = indices.rows.flatMap((index) => {\n const row = rows[index - firstRowIndex];\n return row === undefined ? [] : [row];\n });\n const table = buildExportTable(selected, cols);\n\n const lines = table.rows.map((row) =>\n row.map(cellText).map(escapeCell).join(\"\\t\")\n );\n return headers\n ? [table.headers.map(escapeCell).join(\"\\t\"), ...lines].join(\"\\n\")\n : lines.join(\"\\n\");\n}\n\n/**\n * Write text to the clipboard, reporting whether it landed.\n *\n * The async Clipboard API is unavailable outside a secure context and can be\n * refused by permission, so this answers with a boolean rather than throwing:\n * a copy that silently did nothing is the thing worth avoiding, and the caller\n * needs to know in order to say so.\n *\n * @param text - What to write.\n * @returns Whether the clipboard accepted it.\n */\nexport async function writeClipboardText(text: string): Promise {\n const clipboard = globalThis.navigator?.clipboard;\n if (!clipboard?.writeText) return false;\n try {\n await clipboard.writeText(text);\n return true;\n } catch {\n // A refused permission is not an error to propagate — it is an answer.\n return false;\n }\n}\n\n/**\n * Read text from the clipboard, or `null` when the browser will not give it.\n *\n * Reading is the more restricted half: Safari and Firefox gate `readText`\n * behind a permission or refuse it outside a user gesture. `null` says \"no\n * text\", never \"empty paste\", so a caller can tell the difference and say so.\n *\n * @returns The clipboard's text, or `null` when it is unavailable.\n */\nexport async function readClipboardText(): Promise {\n const clipboard = globalThis.navigator?.clipboard;\n if (!clipboard?.readText) return null;\n try {\n return await clipboard.readText();\n } catch {\n return null;\n }\n}\n","import type { ReactElement } from \"react\";\n\nimport type { SortableValue } from \"../types\";\nimport { getPath } from \"../utils/path\";\n\n/** One choice in a select cell editor. */\nexport interface CellEditorOption {\n value: string;\n label: string;\n}\n\n/**\n * Editor descriptor for an editable column — mirrors the declarative\n * `filter` shorthand: a bare type, or a select with options (objects or\n * plain value strings).\n */\nexport type CellEditor =\n | \"text\"\n | \"number\"\n /** A checkbox. Commits `true` / `false`, never a string. */\n | \"boolean\"\n /** A date. Commits `YYYY-MM-DD`, the value a date input holds. */\n | \"date\"\n /** A date and a time. Commits `YYYY-MM-DDTHH:mm`. */\n | \"datetime\"\n /** A time of day. Commits `HH:mm`. */\n | \"time\"\n | {\n type: \"select\";\n options: readonly CellEditorOption[] | readonly string[];\n }\n | {\n /** Several of a fixed set. Commits an array of the chosen values. */\n type: \"multi-select\";\n options: readonly CellEditorOption[] | readonly string[];\n }\n | {\n /**\n * Your own React editor. The table still owns activation, focus, the\n * keyboard flow, validation and the commit — the component owns what the\n * reader looks at and types into.\n */\n type: \"custom\";\n render: CustomCellEditorRender;\n };\n\n/**\n * A bring-your-own editor.\n *\n * Everything the table already does stays the table's: double-click / Enter /\n * F2 activates, focus returns to the cell afterwards, Enter commits, Escape\n * cancels, Tab moves on, validators gate the commit. What arrives here is the\n * draft and the two calls that change it — so an autocomplete, a rich-text\n * field or a colour picker becomes an editor without reimplementing any of that.\n */\nexport type CustomCellEditorRender = (\n ctrl: CustomCellEditorCtrl\n) => ReactElement;\n\n/** What a custom editor is handed. */\nexport interface CustomCellEditorCtrl {\n /** The draft, as the table holds it. */\n draft: string;\n /** Replace the draft. Does not commit. */\n setDraft: (value: string) => void;\n /**\n * Commit now, without waiting for Enter or a blur — what a picker calls when\n * the reader chooses something, since a choice IS the gesture.\n */\n commit: () => void;\n /** Abandon the draft, exactly as Escape does. */\n cancel: () => void;\n /**\n * Wire to the editor's own `onKeyDown` to keep Enter / Escape / Tab working.\n * An editor that swallows them (a combobox using Enter to choose) simply does\n * not call this for the keys it owns.\n */\n onKeyDown: (event: {\n key: string;\n preventDefault: () => void;\n shiftKey?: boolean;\n }) => void;\n /** Commit on click-away. Wire to `onBlur` unless the editor is a popover. */\n onBlur: () => void;\n /** Attach to the element that should take focus when the cell opens. */\n focusRef: (node: { focus: () => void } | null) => void;\n /** Accessible name for the control — the column's header, resolved. */\n label: string;\n /** A validator's message for this cell, if the last commit was rejected. */\n error?: string;\n /** Whether an async validator is still deciding. */\n validating: boolean;\n /** `id` of the message element, for `aria-describedby`. */\n errorId: string;\n}\n\n/**\n * Minimal column surface the editing helpers need. {@link ColumnDef}\n * satisfies this; using a narrow shape avoids `ColumnDef` variance\n * issues when Tab-navigation crosses generic boundaries.\n *\n * `editable` uses a bivariant callback (same pattern as React's event\n * handlers) so `ColumnDef` is assignable to `EditableColumnLike`.\n */\nexport interface EditableColumnLike {\n key: string;\n editable?: boolean | { bivarianceHack(row: TRow): boolean }[\"bivarianceHack\"];\n editor?: CellEditor;\n editValue?: { bivarianceHack(row: TRow): string }[\"bivarianceHack\"];\n parseValue?: {\n bivarianceHack(draft: string, row: TRow): unknown;\n }[\"bivarianceHack\"];\n validate?: {\n bivarianceHack(\n value: unknown,\n row: TRow\n ): string | undefined | Promise;\n }[\"bivarianceHack\"];\n sortValue?: { bivarianceHack(row: TRow): SortableValue }[\"bivarianceHack\"];\n}\n\n/** The active cell being edited. */\nexport interface CellEditTarget {\n rowId: string;\n columnKey: string;\n}\n\n/** Result of a successful commit (host applies via `onCellEdit`). */\nexport interface CellEditCommit {\n rowId: string;\n columnKey: string;\n /** Raw draft string from the editor. */\n draft: string;\n}\n\n/** Whether this editor is the host's own component. */\nexport function isCustomEditor(\n editor: CellEditor | null\n): editor is { type: \"custom\"; render: CustomCellEditorRender } {\n return (\n editor !== null && typeof editor === \"object\" && editor.type === \"custom\"\n );\n}\n\n/** Whether this editor is a checkbox. */\nexport function isBooleanEditor(editor: CellEditor | null): boolean {\n return editor === \"boolean\";\n}\n\n/** Whether this editor chooses several of a fixed set. */\nexport function isMultiSelectEditor(\n editor: CellEditor | null\n): editor is { type: \"multi-select\"; options: readonly CellEditorOption[] } {\n return (\n editor !== null &&\n typeof editor === \"object\" &&\n editor.type === \"multi-select\"\n );\n}\n\n/** Whether this editor chooses one of a fixed set. */\nexport function isSelectEditor(\n editor: CellEditor | null\n): editor is { type: \"select\"; options: readonly CellEditorOption[] } {\n return (\n editor !== null && typeof editor === \"object\" && editor.type === \"select\"\n );\n}\n\n/**\n * The native `type` an editor's input takes.\n *\n * One mapping for nine kits: every one of them renders a real ``\n * underneath, and the browser's own date and time controls are\n * keyboard-complete and localized by the platform — a better answer than nine\n * hand-built pickers.\n *\n * A checkbox is not among these: a boolean editor renders its own control, and\n * several kits' text fields reject `type=\"checkbox\"` outright.\n *\n * @param editor - The column's editor descriptor.\n * @returns The `type` attribute for the editor's input.\n */\nexport function editorInputType(\n editor: CellEditor | null\n): \"text\" | \"number\" | \"date\" | \"datetime-local\" | \"time\" {\n if (editor === \"number\") return \"number\";\n if (editor === \"date\") return \"date\";\n if (editor === \"datetime\") return \"datetime-local\";\n if (editor === \"time\") return \"time\";\n return \"text\";\n}\n\n/** The draft string a checkbox holds. */\nexport function booleanDraft(checked: boolean): string {\n return checked ? \"true\" : \"false\";\n}\n\n/** Whether a boolean editor's draft is on. */\nexport function isDraftChecked(draft: string): boolean {\n return draft === \"true\";\n}\n\n/** Normalize select options to `{ value, label }` pairs. */\nexport function normalizeEditorOptions(\n options: readonly CellEditorOption[] | readonly string[]\n): CellEditorOption[] {\n return options.map((option) =>\n typeof option === \"string\" ? { value: option, label: option } : option\n );\n}\n\n/** Whether any column opts into editing (ignores per-row predicates). */\nexport function hasEditableColumns(\n columns: readonly EditableColumnLike[]\n): boolean {\n return columns.some(\n (column) => column.editable !== undefined && column.editable !== false\n );\n}\n\n/** Whether a column is editable for a given row. */\nexport function isCellEditable(\n column: EditableColumnLike,\n row: TRow\n): boolean {\n const flag = column.editable;\n if (flag === undefined || flag === false) return false;\n if (flag === true) return true;\n return flag(row);\n}\n\n/**\n * Resolve the editor for a column that opts into editing.\n * Returns `null` when the column is not editable — adapters must not\n * render an editor affordance without a non-null result AND a table-level\n * `onCellEdit` handler.\n */\nexport function resolveCellEditor(\n column: EditableColumnLike\n): CellEditor | null {\n if (column.editable === undefined || column.editable === false) return null;\n return column.editor ?? \"text\";\n}\n\n/**\n * Stringify a cell's current value for the editor draft.\n * Prefers `editValue`, then `sortValue`, then `getPath(row, key)`.\n * Non-primitive path values yield `\"\"` so we never seed `[object Object]`.\n */\nexport function readEditableCellValue(\n row: TRow,\n column: EditableColumnLike\n): string {\n const seed = readSeed(row, column);\n // A date editor holds a day, a time editor holds a time of day: trim the\n // stored value to the part its own input can hold, or the browser rejects it\n // and the editor opens empty.\n return trimToEditor(seed, resolveCellEditor(column));\n}\n\n/** The raw seed, before the editor's own shape is applied. */\nfunction readSeed(row: TRow, column: EditableColumnLike): string {\n if (column.editValue) return column.editValue(row);\n if (column.sortValue) return stringifyEditSeed(column.sortValue(row));\n return stringifyEditSeed(getPath(row, column.key));\n}\n\n/** Cut a `YYYY-MM-DDTHH:mm` seed down to what a date or time input holds. */\nfunction trimToEditor(seed: string, editor: CellEditor | null): string {\n if (editor === \"date\") return seed.slice(0, 10);\n if (editor === \"time\") {\n const at = seed.indexOf(\"T\");\n return at === -1 ? seed.slice(0, 5) : seed.slice(at + 1, at + 6);\n }\n return seed;\n}\n\nfunction stringifyEditSeed(value: unknown): string {\n if (value === null || value === undefined) return \"\";\n if (\n typeof value === \"string\" ||\n typeof value === \"number\" ||\n typeof value === \"boolean\"\n ) {\n return String(value);\n }\n // A multi-select's stored value is the array it commits, so it seeds its own\n // editor without the host writing an `editValue` for the round trip.\n if (Array.isArray(value)) {\n return formatMultiDraft(value.map(String));\n }\n // A Date seeds the date editors in the shape their inputs hold. Local parts,\n // not the ISO string: `toISOString` shifts to UTC, which moves the day for\n // most of the world.\n if (value instanceof Date && !Number.isNaN(value.getTime())) {\n return localDateTimeParts(value);\n }\n return \"\";\n}\n\n/** `YYYY-MM-DDTHH:mm` in local time — a `datetime` input's own format. */\nfunction localDateTimeParts(value: Date): string {\n const pad = (n: number) => String(n).padStart(2, \"0\");\n const date = `${String(value.getFullYear())}-${pad(value.getMonth() + 1)}-${pad(value.getDate())}`;\n return `${date}T${pad(value.getHours())}:${pad(value.getMinutes())}`;\n}\n\n/**\n * Parse a draft string into the value passed to `onCellEdit`.\n * Number editors yield `number | null` (empty / invalid → `null`);\n * select and text stay strings.\n */\nexport function parseCellEditValue(editor: CellEditor, draft: string): unknown {\n if (editor === \"number\") return parseNumberDraft(draft);\n if (editor === \"boolean\") return draft === \"true\";\n if (typeof editor === \"object\" && editor.type === \"multi-select\") {\n return parseMultiDraft(draft);\n }\n // A date, datetime or time editor commits the string its input holds —\n // `YYYY-MM-DD`, `YYYY-MM-DDTHH:mm`, `HH:mm`. A `Date` would be worse: it\n // carries a timezone the reader never chose, and \"the 3rd\" is not an instant.\n return draft;\n}\n\n/** An empty number field is nothing, not zero. */\nfunction parseNumberDraft(draft: string): number | null {\n const trimmed = draft.trim();\n if (trimmed === \"\") return null;\n const n = Number(trimmed);\n return Number.isFinite(n) ? n : null;\n}\n\n/**\n * A multi-select's draft is its chosen values joined by the unit separator.\n *\n * A control character rather than a comma: an option's own label may contain\n * one, and a separator that can appear inside a value is not a separator.\n */\nfunction parseMultiDraft(draft: string): string[] {\n return draft === \"\" ? [] : draft.split(MULTI_SEPARATOR);\n}\n\n/** The separator {@link formatMultiDraft} joins a multi-select's values with. */\nexport const MULTI_SEPARATOR = \"\\u001f\";\n\n/**\n * The draft string for a set of chosen values — the inverse of the parse above.\n *\n * @param values - The chosen values.\n * @returns The draft the editing state holds.\n */\nexport function formatMultiDraft(values: readonly string[]): string {\n return values.join(MULTI_SEPARATOR);\n}\n\n/**\n * The chosen values inside a multi-select draft.\n *\n * @param draft - The draft the editing state holds.\n * @returns The chosen values, in the order they were joined.\n */\nexport function readMultiDraft(draft: string): string[] {\n return parseMultiDraft(draft);\n}\n\n/**\n * Find the next (or previous) editable cell in row-major order (wraps).\n * Returns `null` when no other editable cell exists.\n */\nexport function stepEditableCell(options: {\n rows: readonly TRow[];\n columns: readonly EditableColumnLike[];\n rowKey: (row: TRow) => string;\n from: CellEditTarget;\n /** `1` advances (Tab); `-1` goes previous (Shift+Tab). */\n direction?: 1 | -1;\n}): CellEditTarget | null {\n const { rows, columns, rowKey, from, direction = 1 } = options;\n const editableCols = columns.filter(\n (c) => c.editable !== undefined && c.editable !== false\n );\n if (editableCols.length === 0 || rows.length === 0) return null;\n\n const rowIndex = rows.findIndex((r) => rowKey(r) === from.rowId);\n const colIndex = editableCols.findIndex((c) => c.key === from.columnKey);\n if (rowIndex < 0 || colIndex < 0) return null;\n\n const total = rows.length * editableCols.length;\n for (let step = 1; step < total; step++) {\n const flat =\n (((rowIndex * editableCols.length + colIndex + direction * step) %\n total) +\n total) %\n total;\n const nextRow = Math.floor(flat / editableCols.length);\n const nextCol = flat % editableCols.length;\n const row = rows[nextRow]!;\n const column = editableCols[nextCol]!;\n if (isCellEditable(column, row)) {\n return { rowId: rowKey(row), columnKey: column.key };\n }\n }\n return null;\n}\n\n/** Tab-advance form of {@link stepEditableCell}, fixed to `direction: 1`. */\nexport function nextEditableCell(options: {\n rows: readonly TRow[];\n columns: readonly EditableColumnLike[];\n rowKey: (row: TRow) => string;\n from: CellEditTarget;\n}): CellEditTarget | null {\n return stepEditableCell({ ...options, direction: 1 });\n}\n\n/**\n * The row, the column and the parsed value a commit resolves to.\n *\n * Separate from applying it, because validation has to see the value BEFORE the\n * host does — the whole point of a validator is to stop the call.\n *\n * @typeParam TRow - The row type.\n * @param options - The commit and the page it addresses.\n * @returns The resolved triple, or `null` for a stale commit whose row or\n * column has since left the page.\n */\nexport function resolveCommitValue(options: {\n commit: CellEditCommit;\n rows: readonly TRow[];\n columns: readonly EditableColumnLike[];\n rowKey: (row: TRow) => string;\n}): { row: TRow; column: EditableColumnLike; value: unknown } | null {\n const row = options.rows.find(\n (r) => options.rowKey(r) === options.commit.rowId\n );\n const column = options.columns.find(\n (c) => c.key === options.commit.columnKey\n );\n if (!row || !column) return null;\n const editor = resolveCellEditor(column) ?? \"text\";\n // A column that states how to read its own drafts owns the conversion; the\n // editor's built-in parsing is the fallback, not an extra step on top.\n const value = column.parseValue\n ? column.parseValue(options.commit.draft, row)\n : parseCellEditValue(editor, options.commit.draft);\n return { row, column, value };\n}\n\n/**\n * Apply a commit through the host channel: resolve the row, parse the draft\n * with the column's editor, call `onCellEdit`. Returns `false` when the row\n * or column is missing (stale commit after a filter/page change).\n */\nexport function applyCellEditCommit(options: {\n commit: CellEditCommit;\n rows: readonly TRow[];\n columns: readonly EditableColumnLike[];\n rowKey: (row: TRow) => string;\n onCellEdit: (row: TRow, key: string, nextValue: unknown) => void;\n}): boolean {\n const resolved = resolveCommitValue(options);\n if (!resolved) return false;\n options.onCellEdit(resolved.row, resolved.column.key, resolved.value);\n return true;\n}\n","/**\n * The fill handle — dragging a selection's corner to carry its values on.\n *\n * The gesture is a spreadsheet's, and so is the behaviour people expect from\n * it: two numbers one apart continue counting, anything else repeats. What it\n * produces is not special, though — the same ordinary cell edits a paste or an\n * inline commit produces, so a host wires nothing extra to receive a fill.\n *\n * Values are read the way the EDITOR reads them (`readEditableCellValue`) and\n * written back through the column's `parseValue`, which makes a fill exactly\n * equivalent to retyping the source cell into each target cell — never a\n * separate notion of what a cell contains.\n */\nimport { isCellEditable, readEditableCellValue } from \"../editing/cellEditing\";\nimport type { ColumnDef } from \"../types\";\nimport type { CellEdit } from \"./cellEdits\";\nimport { type CellRange, cellRangeBounds } from \"./cellRange\";\nimport type { GridCell } from \"./gridFocus\";\n\n/** Which way a fill runs. Fills are one-axis, as in every spreadsheet. */\nexport type FillDirection = \"down\" | \"up\" | \"right\" | \"left\";\n\n/**\n * Which way a drag from the selection's corner to `to` is filling.\n *\n * A pointer wanders, so the axis is decided by the LARGER overflow rather than\n * by whichever edge was crossed first — otherwise a drag two rows down and one\n * column across would fill sideways because of a stray pixel.\n *\n * @param source - The selected rectangle the fill starts from.\n * @param to - The cell the pointer has reached.\n * @returns The direction, or `null` when `to` is still inside the selection.\n */\nexport function fillDirection(\n source: CellRange,\n to: GridCell\n): FillDirection | null {\n const bounds = cellRangeBounds(source);\n const below = to.row - bounds.toRow;\n const above = bounds.fromRow - to.row;\n const after = to.col - bounds.toCol;\n const before = bounds.fromCol - to.col;\n const vertical = Math.max(below, above);\n const horizontal = Math.max(after, before);\n if (vertical <= 0 && horizontal <= 0) return null;\n if (vertical >= horizontal) return below > 0 ? \"down\" : \"up\";\n return after > 0 ? \"right\" : \"left\";\n}\n\n/**\n * The rectangle a fill would cover — the selection plus what the drag reached.\n *\n * This is what gets highlighted while dragging, so the preview and the commit\n * can never disagree about which cells are involved.\n *\n * @param source - The selected rectangle.\n * @param to - The cell the pointer has reached.\n * @returns The union rectangle, or the source itself when nothing is added.\n */\nexport function fillTargetRange(source: CellRange, to: GridCell): CellRange {\n const bounds = cellRangeBounds(source);\n const direction = fillDirection(source, to);\n if (direction === null) return source;\n const vertical = direction === \"down\" || direction === \"up\";\n return {\n anchor: {\n row: vertical && direction === \"up\" ? to.row : bounds.fromRow,\n col: !vertical && direction === \"left\" ? to.col : bounds.fromCol,\n },\n head: {\n row: vertical && direction === \"down\" ? to.row : bounds.toRow,\n col: !vertical && direction === \"right\" ? to.col : bounds.toCol,\n },\n };\n}\n\n/** What a fill needs to know to become edits. */\nexport interface FillRangeOptions {\n /** The selected rectangle the values come from. */\n source: CellRange;\n /** The cell the drag reached, or the far end of a keyboard fill. */\n to: GridCell;\n /** The rows the browser holds, in table order. */\n rows: readonly TRow[];\n /** The columns as rendered — a range's column indices address these. */\n columns: readonly ColumnDef[];\n /** Where the rendered window starts in the dataset. Zero unless paged. */\n firstRowIndex?: number;\n}\n\n/**\n * Continue a run of values, the way a spreadsheet continues one.\n *\n * Two or more numbers separated by a constant step are a series and count on\n * (1, 2 → 3, 4); everything else repeats in order (Mon, Tue → Mon, Tue). A\n * single number repeats rather than counting, because one value carries no\n * step — guessing `+1` there is the behaviour spreadsheets are cursed for.\n *\n * @param seed - The source values, in fill order.\n * @param step - How far past the seed this value sits, from 1.\n * @returns The value for that position, as the string an editor would hold.\n */\nfunction continueSeries(seed: readonly string[], step: number): string {\n const delta = arithmeticStep(seed);\n if (delta === null) return seed[(step - 1) % seed.length] ?? \"\";\n return String(Number(seed.at(-1)) + delta * step);\n}\n\n/**\n * The constant step of a run of numbers, or `null` when it is not one.\n *\n * @param seed - The source values.\n * @returns The step between consecutive values, or `null`.\n */\nfunction arithmeticStep(seed: readonly string[]): number | null {\n if (seed.length < 2) return null;\n const numbers = seed.map((value) =>\n value.trim() === \"\" ? Number.NaN : Number(value)\n );\n if (!numbers.every((value) => Number.isFinite(value))) return null;\n const step = numbers[1]! - numbers[0]!;\n const constant = numbers.every((value, i) => {\n const previous = numbers[i - 1];\n return previous === undefined || value - previous === step;\n });\n return constant ? step : null;\n}\n\n/**\n * A fill in one coordinate system, whichever way it actually runs.\n *\n * Down, up, right and left are one operation seen from four angles, and\n * writing it four times is where the bugs live. So a fill is described as\n * LANES (the rows or columns the fill runs along, side by side) and POSITIONS\n * (how far along each lane), with `at` the only place that knows whether a\n * position is a row or a column.\n */\ninterface FillAxis {\n /** The perpendicular indices — one seed run and one output run each. */\n lanes: number[];\n /** Positions of the source cells, in the order the fill reads them. */\n seed: number[];\n /** The position the fill grows from — the selection's leading edge. */\n edge: number;\n /** +1 for a fill that runs forwards, -1 for one that runs back. */\n step: number;\n /** How many cells past the edge the gesture reached. */\n distance: number;\n /** A lane and a position, as a cell address. */\n at: (lane: number, position: number) => GridCell;\n}\n\n/** Describe the fill in lane/position terms, whichever way it runs. */\nfunction fillAxis(\n direction: FillDirection,\n source: CellRange,\n to: GridCell\n): FillAxis {\n const b = cellRangeBounds(source);\n const vertical = direction === \"down\" || direction === \"up\";\n const forward = direction === \"down\" || direction === \"right\";\n const step = forward ? 1 : -1;\n const along = vertical ? span(b.fromRow, b.toRow) : span(b.fromCol, b.toCol);\n // A backwards fill continues from the near edge, so its seed runs the other\n // way: \"1, 2\" dragged upwards continues 0, -1 rather than 3, 4.\n const seed = forward ? along : [...along].reverse();\n const edgeRow = forward ? b.toRow : b.fromRow;\n const edgeCol = forward ? b.toCol : b.fromCol;\n return {\n lanes: vertical ? span(b.fromCol, b.toCol) : span(b.fromRow, b.toRow),\n seed,\n edge: vertical ? edgeRow : edgeCol,\n step,\n distance: Math.abs(vertical ? to.row - edgeRow : to.col - edgeCol),\n at: (lane, position) =>\n vertical ? { row: position, col: lane } : { row: lane, col: position },\n };\n}\n\n/**\n * Turn a fill gesture into the edits it implies.\n *\n * Only cells OUTSIDE the selection are written: the source is what is being\n * carried, not something to overwrite with itself. Cells beyond the loaded rows\n * or the rendered columns are dropped rather than invented, and a column that\n * is not editable is skipped.\n *\n * @typeParam TRow - The row type.\n * @param options - See {@link FillRangeOptions}.\n * @returns The edits, in reading order.\n */\nexport function fillRangeEdits(\n options: FillRangeOptions\n): CellEdit[] {\n const { source, to, rows, columns, firstRowIndex = 0 } = options;\n const direction = fillDirection(source, to);\n if (direction === null) return [];\n const axis = fillAxis(direction, source, to);\n const edits: CellEdit[] = [];\n\n for (const lane of axis.lanes) {\n const seed = axis.seed.flatMap((position) =>\n readCell(axis.at(lane, position), options)\n );\n if (seed.length === 0) continue;\n\n for (let n = 1; n <= axis.distance; n++) {\n const cell = axis.at(lane, axis.edge + n * axis.step);\n const row = rows[cell.row - firstRowIndex];\n const column = columns[cell.col];\n if (row === undefined || !column || !isCellEditable(column, row)) {\n continue;\n }\n const raw = continueSeries(seed, n);\n edits.push({\n row,\n columnKey: column.key,\n // The column's own parser, so a fill commits what retyping would.\n value: column.parseValue ? column.parseValue(raw, row) : raw,\n });\n }\n }\n return edits;\n}\n\n/**\n * One source cell as the editor would read it, or nothing when the cell is not\n * there — an unloaded row or a column the table does not render.\n */\nfunction readCell(\n cell: GridCell,\n options: FillRangeOptions\n): string[] {\n const { rows, columns, firstRowIndex = 0 } = options;\n const row = rows[cell.row - firstRowIndex];\n const column = columns[cell.col];\n if (row === undefined || !column) return [];\n return [readEditableCellValue(row, column)];\n}\n\n/** Inclusive integer span — the indices between two edges. */\nfunction span(from: number, to: number): number[] {\n return Array.from({ length: to - from + 1 }, (_, i) => from + i);\n}\n","/**\n * Clipboard text, turned into ordinary cell edits.\n *\n * Paste is deliberately NOT its own commit path. It parses what a spreadsheet\n * put on the clipboard, maps it onto the selection, and hands back the same\n * edits an inline edit produces — same `parseValue`, same shape, same host\n * handler. Anything later added to that path (validation, async save states,\n * conflict handling) applies to a paste without paste knowing it exists, which\n * is what stops this becoming a second half-maintained editing route.\n *\n * The parsing follows what Excel, Google Sheets, Numbers and LibreOffice write:\n * tab-separated fields, newline-separated rows, and RFC-4180 quoting when a\n * field carries a tab, a newline or a quote.\n */\nimport { isCellEditable } from \"../editing/cellEditing\";\nimport type { ColumnDef } from \"../types\";\nimport { batchEditHandler, type CellEdit } from \"./cellEdits\";\nimport { type CellRange, cellRangeBounds } from \"./cellRange\";\n\n/**\n * Parse clipboard text into a grid of raw strings.\n *\n * Quoted fields keep their tabs and newlines: a spreadsheet writes `\"a\\tb\"` for\n * a cell containing a tab, and splitting naively would turn one cell into two\n * and shift every column after it.\n *\n * @param text - The clipboard's text.\n * @returns Rows of raw cell strings; empty when there is nothing to paste.\n */\nexport function parseClipboardTable(text: string): string[][] {\n if (text === \"\") return [];\n const rows: string[][] = [];\n let row: string[] = [];\n let field = \"\";\n let i = 0;\n\n while (i < text.length) {\n const ch = text[i];\n if (ch === '\"' && field === \"\") {\n const quoted = readQuotedField(text, i + 1);\n field = quoted.value;\n i = quoted.next;\n } else if (ch === \"\\t\") {\n row.push(field);\n field = \"\";\n i++;\n } else if (ch === \"\\n\" || ch === \"\\r\") {\n row.push(field);\n rows.push(row);\n row = [];\n field = \"\";\n // CRLF is one break, not two: counting it twice pastes a blank row.\n i += ch === \"\\r\" && text[i + 1] === \"\\n\" ? 2 : 1;\n } else {\n field += ch;\n i++;\n }\n }\n if (field !== \"\" || row.length > 0) {\n row.push(field);\n rows.push(row);\n }\n return rows;\n}\n\n/**\n * Read one quoted field, starting just past its opening quote.\n *\n * @param text - The whole clipboard text.\n * @param start - Index of the first character inside the quotes.\n * @returns The field's value and the index just past its closing quote.\n */\nfunction readQuotedField(\n text: string,\n start: number\n): { value: string; next: number } {\n let value = \"\";\n let i = start;\n while (i < text.length) {\n if (text[i] !== '\"') {\n value += text[i];\n i++;\n } else if (text[i + 1] === '\"') {\n // A doubled quote is one literal quote; a lone one closes the field.\n value += '\"';\n i += 2;\n } else return { value, next: i + 1 };\n }\n // Unterminated — a truncated clipboard is still worth what it carries.\n return { value, next: i };\n}\n\n/** What a paste needs to know to become edits. */\nexport interface PasteRangeOptions {\n /** The clipboard's text. */\n text: string;\n /** Where the paste starts — its top-left cell is the anchor. */\n range: CellRange;\n /** The rows the browser holds, in table order. */\n rows: readonly TRow[];\n /** The columns as rendered — a range's column indices address these. */\n columns: readonly ColumnDef[];\n /** Where the rendered window starts in the dataset. Zero unless paged. */\n firstRowIndex?: number;\n}\n\n/**\n * Turn clipboard text into the edits it implies, starting at the selection's\n * top-left cell.\n *\n * The clipboard's shape wins over the selection's: pasting a 3×2 block into a\n * single selected cell writes 3×2, which is what every spreadsheet does. Cells\n * falling outside the loaded rows or the rendered columns are dropped rather\n * than invented — a paste must never write into a row the browser has not got.\n *\n * A column that is not editable is skipped: paste is an edit, and an edit into a\n * read-only column is not one.\n *\n * @typeParam TRow - The row type.\n * @param options - See {@link PasteRangeOptions}.\n * @returns The edits, in row-major order.\n */\nexport function pasteRangeEdits(\n options: PasteRangeOptions\n): CellEdit[] {\n const { text, range, rows, columns, firstRowIndex = 0 } = options;\n const grid = parseClipboardTable(text);\n if (grid.length === 0) return [];\n\n const start = cellRangeBounds(range);\n const edits: CellEdit[] = [];\n\n grid.forEach((line, r) => {\n const row = rows[start.fromRow + r - firstRowIndex];\n if (row === undefined) return;\n line.forEach((raw, c) => {\n const column = columns[start.fromCol + c];\n if (!column || !isCellEditable(column, row)) return;\n edits.push({\n row,\n columnKey: column.key,\n // The column's own parser, so a paste commits what typing would.\n value: column.parseValue ? column.parseValue(raw, row) : raw,\n });\n });\n });\n return edits;\n}\n\n/** The two ways a table can receive a paste. */\nexport interface CellPasteHandlerOptions {\n /** Takes the batch whole — one transaction, one undo entry. */\n onCellPaste?: (edits: CellEdit[]) => void;\n /** The ordinary inline-edit channel, used one edit at a time. */\n onCellEdit?: (row: TRow, key: string, nextValue: unknown) => void;\n}\n\n/**\n * Resolve who receives a paste — `onCellPaste`, or `onCellEdit` one cell at a\n * time. See {@link batchEditHandler} for why the default is the edit channel.\n *\n * @typeParam TRow - The row type.\n * @param options - See {@link CellPasteHandlerOptions}.\n * @returns The handler, or `undefined` when the table takes no edits at all —\n * which leaves Ctrl/Cmd+V to the browser.\n */\nexport function cellPasteHandler(\n options: CellPasteHandlerOptions\n): ((edits: CellEdit[]) => void) | undefined {\n return batchEditHandler(options.onCellPaste, options.onCellEdit);\n}\n\n/** The two ways a table can receive a fill. */\nexport interface CellFillHandlerOptions {\n /** Takes the batch whole — one transaction, one undo entry. */\n onCellFill?: (edits: CellEdit[]) => void;\n /** The ordinary inline-edit channel, used one edit at a time. */\n onCellEdit?: (row: TRow, key: string, nextValue: unknown) => void;\n}\n\n/**\n * Resolve who receives a fill — `onCellFill`, or `onCellEdit` one cell at a\n * time. See {@link batchEditHandler} for why the default is the edit channel.\n *\n * @typeParam TRow - The row type.\n * @param options - See {@link CellFillHandlerOptions}.\n * @returns The handler, or `undefined` when the table takes no edits at all —\n * which is also when the fill handle is not rendered.\n */\nexport function cellFillHandler(\n options: CellFillHandlerOptions\n): ((edits: CellEdit[]) => void) | undefined {\n return batchEditHandler(options.onCellFill, options.onCellEdit);\n}\n","/**\n * What the selected cells add up to.\n *\n * Selecting a block of numbers and wanting their sum is the oldest reason\n * anyone selects a block, and a table that can copy a rectangle already knows\n * everything needed to answer it. The values come from the same resolution\n * copy and export use, so the sum shown here and the sum a spreadsheet\n * computes from a paste of the same cells cannot disagree.\n *\n * The count is every selected cell; the arithmetic covers only the numeric\n * ones. A rectangle spanning a name column and a budget column still has a\n * meaningful sum, and refusing to give one because a string is in the way is\n * the behaviour nobody wants.\n */\nimport { buildExportTable } from \"../export/exportWriter\";\nimport type { ColumnDef } from \"../types\";\nimport { type CellRange, cellRangeIndices, cellRangeSize } from \"./cellRange\";\n\n/** The numbers behind a selection. */\nexport interface SelectionStats {\n /** Every selected cell, numeric or not. */\n cells: number;\n /** How many of them held a number. */\n numeric: number;\n /** Total of the numeric cells; `null` when there are none. */\n sum: number | null;\n /** Mean of the numeric cells; `null` when there are none. */\n average: number | null;\n /** Smallest numeric value; `null` when there are none. */\n min: number | null;\n /** Largest numeric value; `null` when there are none. */\n max: number | null;\n}\n\n/** What the statistics need: the rectangle, and the data under it. */\nexport interface SelectionStatsOptions {\n /**\n * Off unless the host asked for it. Passed rather than checked at the call\n * site so the two tables that compute this read identically.\n */\n enabled?: boolean;\n /** The selected rectangle, in absolute addresses. */\n range: CellRange | null;\n /** The rows the browser holds, in table order. */\n rows: readonly TRow[];\n /** The columns as rendered — a range's column indices address these. */\n columns: readonly ColumnDef[];\n /** Where the rendered window starts in the dataset. Zero unless paged. */\n firstRowIndex?: number;\n}\n\n/**\n * A value as a number, or `null` when it is not one.\n *\n * Booleans are not numbers here even though JavaScript will happily add them:\n * summing a column of ticks to 3 says something the table was never asked.\n */\nfunction numeric(value: unknown): number | null {\n if (typeof value === \"number\") return Number.isFinite(value) ? value : null;\n if (typeof value === \"string\" && value.trim() !== \"\") {\n const parsed = Number(value);\n return Number.isFinite(parsed) ? parsed : null;\n }\n return null;\n}\n\n/**\n * Count, sum, average, min and max over the selected cells.\n *\n * Rows outside what the browser holds are skipped rather than counted as\n * empty: a column selection over 500 loaded rows of 100,000 describes the 500,\n * and inventing the rest would put a wrong total on screen.\n *\n * @typeParam TRow - The row type.\n * @param options - See {@link SelectionStatsOptions}.\n * @returns The statistics, or `null` when nothing is selected.\n */\nexport function selectionStats(\n options: SelectionStatsOptions\n): SelectionStats | null {\n const { enabled = true, range, rows, columns, firstRowIndex = 0 } = options;\n if (!enabled || !range) return null;\n const indices = cellRangeIndices(range);\n const cols = indices.cols.flatMap((index) => {\n const column = columns[index];\n return column ? [column] : [];\n });\n if (cols.length === 0) return null;\n\n const selected = indices.rows.flatMap((index) => {\n const row = rows[index - firstRowIndex];\n return row === undefined ? [] : [row];\n });\n const table = buildExportTable(selected, cols);\n\n const numbers = table.rows.flatMap((row) =>\n row.flatMap((value) => {\n const parsed = numeric(value);\n return parsed === null ? [] : [parsed];\n })\n );\n if (numbers.length === 0) {\n return {\n cells: cellRangeSize(range),\n numeric: 0,\n sum: null,\n average: null,\n min: null,\n max: null,\n };\n }\n const sum = numbers.reduce((total, value) => total + value, 0);\n return {\n cells: cellRangeSize(range),\n numeric: numbers.length,\n sum,\n average: sum / numbers.length,\n min: Math.min(...numbers),\n max: Math.max(...numbers),\n };\n}\n","/**\n * Keyboard navigation over table cells — the stateful half.\n *\n * Opt-in: without `cellNavigation` this hook is never called, and the table\n * renders exactly the markup it always did. With it, the table becomes one tab\n * stop whose interior is reachable by arrow keys, which is the difference\n * between a 10,000-row table being usable from a keyboard and being a trap.\n *\n * Three things here are easy to get wrong and are the reason this lives in core\n * rather than in eight adapters:\n *\n * **The ARIA indices are absolute.** `aria-rowindex` counts within the dataset,\n * not within the rendered window. Virtualization mounts 24 rows out of 100,000,\n * so a naive implementation numbers them 1-24 and every assistive technology\n * reports \"row 3 of 24\" while the user is at row 40,000. `aria-rowcount` and\n * `aria-colcount` carry the totals for the same reason.\n *\n * **A cell the virtualizer has not mounted still has to be reachable.**\n * Ctrl+End on a 100,000-row table asks for a cell that does not exist in the\n * DOM. Moving focus there means scrolling it into existence first, then\n * focusing it once it mounts — which is asynchronous, so the hook holds a\n * pending address and focuses on the render that produces the element.\n *\n * **Focus lives in state, but the DOM has to follow it.** Setting\n * `tabIndex` alone moves nothing; something must call `.focus()`. That happens\n * in an effect keyed on the active address, addressing cells by their\n * `data-grid-cell` attribute so the mechanism does not need a ref per cell —\n * with 100,000 rows, a ref map is a leak with extra steps.\n */\nimport { useCallback, useEffect, useMemo, useRef, useState } from \"react\";\n\nimport { columnText } from \"../columns/columnText\";\nimport { useEventCallback } from \"../hooks/useEventCallback\";\nimport type { ColumnDef, Direction, TableLabels } from \"../types\";\nimport type { CellEdit } from \"./cellEdits\";\nimport {\n type CellRange,\n cellRangeBounds,\n cellRangeSize,\n extendCellRange,\n isInCellRange,\n isSingleCell,\n singleCellRange,\n} from \"./cellRange\";\nimport {\n clipboardRangeText,\n readClipboardText,\n writeClipboardText,\n} from \"./clipboardRange\";\nimport { fillRangeEdits, fillTargetRange } from \"./fillRange\";\nimport {\n type GridBounds,\n type GridCell,\n gridFocusMoveForKey,\n moveGridFocus,\n sameGridCell,\n} from \"./gridFocus\";\nimport { pasteRangeEdits } from \"./pasteRange\";\n\n/** The attribute a focusable cell carries, so focus can find it in the DOM. */\nexport const GRID_CELL_ATTR = \"data-grid-cell\";\n\n/** `data-grid-cell` value for one address — `\"row:col\"`, both absolute. */\nexport function gridCellAttr(cell: GridCell): string {\n return `${cell.row}:${cell.col}`;\n}\n\n/** Options for {@link useGridFocus}. */\nexport interface UseGridFocusOptions {\n /** Off unless the host asked for it; when false the hook does nothing. */\n enabled: boolean;\n /**\n * Offer a checkbox in every column header that selects that column.\n *\n * Ctrl/Cmd+click is the gesture for a keyboard and a mouse, and a touch\n * device has neither — there is no Ctrl key to hold. This is the same\n * state reached by a control a finger can hit, and the same state a\n * screen reader can name. Off unless asked for.\n */\n headerCheckbox?: boolean;\n /**\n * Rows in the whole dataset. This is the ARIA number — `aria-rowcount` — and\n * deliberately NOT what movement is clamped to; see the note on navigable\n * bounds below.\n */\n rowCount: number;\n /** Columns in the order they are rendered. */\n columns: readonly ColumnDef[];\n /** The rendered rows, for reading a cell's text when focus lands. */\n rows: readonly TRow[];\n /**\n * Where the rendered window starts in the dataset. Zero without\n * virtualization; with it, `rows[i]` is dataset row `firstRowIndex + i`.\n */\n firstRowIndex?: number;\n /** Rows a PageUp/PageDown travels. Defaults to the rendered row count. */\n pageSize?: number;\n /** Text direction — flips the left/right arrows. */\n dir?: Direction;\n /** Announcement strings; falls back to the built-in English. */\n labels?: TableLabels;\n /**\n * Bring a dataset row into view. Supplied by the virtualizer; without it a\n * move to an unmounted row cannot be completed and is left alone rather than\n * silently dropping focus.\n */\n scrollToRow?: (rowIndex: number) => void;\n /** Enter or F2 on a cell — the editing model's entry point. */\n onActivate?: (cell: GridCell) => void;\n /**\n * True for a cell covered by someone else's span. Arrow keys skip it\n * rather than landing inside a cell that is not in the DOM.\n */\n isCoveredCell?: (cell: GridCell) => boolean;\n /**\n * Fired whenever the selected range changes, including when it collapses to\n * a single cell. `null` means nothing is selected.\n */\n onRangeChange?: (range: CellRange | null) => void;\n /**\n * Ctrl/Cmd+X after the copy succeeded. The table never clears data itself —\n * what \"cut\" removes is the host's decision, and a cut that emptied cells\n * before the clipboard accepted them would lose them outright.\n */\n onCut?: (range: CellRange) => void;\n /**\n * Ctrl/Cmd+V, with the clipboard already parsed into ordinary cell edits.\n *\n * Paste is not a second commit path: these are the same edits an inline edit\n * produces, so validation or async saving added to that path covers a paste\n * without paste knowing. Applying them stays the host's job — the table never\n * writes to data it does not own.\n */\n onPaste?: (edits: CellEdit[]) => void;\n /**\n * A fill — the handle dragged from the selection's corner, or Ctrl/Cmd+D —\n * already turned into ordinary cell edits. Same shape and same contract as\n * {@link UseGridFocusOptions.onPaste}: the table proposes, the host writes.\n */\n onFill?: (edits: CellEdit[]) => void;\n /**\n * Ctrl/Cmd+Z. Returns how many cells came back, so the grid can say — zero\n * means the history was empty, which is worth announcing rather than\n * swallowing.\n */\n onUndo?: () => number;\n /** Ctrl/Cmd+Shift+Z and Ctrl+Y. Returns how many cells were rewritten. */\n onRedo?: () => number;\n /** Ctrl/Cmd+F — open the find bar instead of the browser's own. */\n onFind?: () => void;\n /**\n * Cells the find bar matched, keyed `\"row:col\"`. They carry\n * `data-cell-match`, and the one the walk is on carries\n * `data-cell-match-current`, so each kit paints the hits its own way.\n */\n matchKeys?: ReadonlySet;\n /** The match the walk is on, for the stronger mark. */\n currentMatch?: GridCell | null;\n}\n\n/** What {@link useGridFocus} returns. */\nexport interface GridFocusState {\n /**\n * Whether cell navigation is on. Consumers render the live region only when\n * it is: an `aria-live` region that appears at the same moment as its text is\n * frequently missed by screen readers, so it has to exist beforehand — and\n * must not exist at all when the feature is off.\n */\n enabled: boolean;\n /** The focused cell, or `null` before the grid has been entered. */\n active: GridCell | null;\n /** Props for the grid container: role, dimensions, key handling. */\n getGridProps: () => Record;\n /** Props for one cell — roving `tabIndex`, absolute indices, the hook. */\n getCellProps: (cell: GridCell) => Record;\n /** Props for one row: its absolute `aria-rowindex`. */\n getRowProps: (rowIndex: number) => Record;\n /**\n * Props for a cell addressed by its position in the RENDERED window — which\n * is the index an adapter already has, whether it is mapping `source.rows` or\n * a virtual entry.\n *\n * The conversion to an absolute address lives here rather than in eight\n * adapters, because getting it wrong is invisible: the table looks right and\n * only a screen reader announces the wrong row.\n */\n getCellPropsAt: (windowIndex: number, col: number) => Record;\n /** Props for a row addressed by its position in the rendered window. */\n getRowPropsAt: (windowIndex: number) => Record;\n /** Live-region text naming where focus is. Empty until focus moves. */\n announcement: string;\n /** The selected rectangle, or `null` when nothing is selected. */\n range: CellRange | null;\n /** Select a rectangle programmatically — what a Select-all would call. */\n selectRange: (range: CellRange | null) => void;\n /**\n * Props for a column header that selects its whole column on click, with\n * Ctrl/Cmd+click extending the current selection instead of replacing it.\n */\n getColumnHeaderProps: (\n col: number,\n options?: { sortable?: boolean }\n ) => Record;\n /**\n * Select a whole column by index — the loaded rows of it, since a column of\n * 100,000 rows cannot be selected while 500 are in hand.\n */\n selectColumn: (col: number, extend?: boolean) => void;\n /**\n * Whether an adapter should draw the per-column header checkbox: the host\n * asked for it AND cell navigation is on, resolved here so a header cell\n * renders on one boolean instead of checking two.\n */\n columnCheckbox: boolean;\n /**\n * Whether the selection is exactly this column, over every loaded row.\n *\n * Exactly — a column inside a wider rectangle reads as unchecked, because a\n * checkbox that ticks while its neighbours are also selected says the\n * selection is one column when it is four.\n */\n isColumnSelected: (col: number) => boolean;\n /**\n * What the header checkbox does: select this column alone, or clear the\n * selection when it is already the only thing selected.\n */\n toggleColumn: (col: number) => void;\n /** Move focus programmatically — the fill handle and clipboard will need it. */\n focusCell: (cell: GridCell) => void;\n /**\n * The cell carrying the fill handle — the selection's bottom inline-end\n * corner — or `null` when there is nothing to fill from or no host to\n * receive it.\n */\n fillHandleCell: GridCell | null;\n /** Props for the adapter-owned fill handle element. */\n getFillHandleProps: () => Record;\n /** The handle's accessible name, already localized. */\n fillHandleLabel: string;\n /**\n * What a fill in progress would cover, for a kit that wants to draw the\n * preview its own way. `null` unless a fill is being dragged.\n */\n fillPreview: CellRange | null;\n /**\n * Copy or cut without the keyboard.\n *\n * Ctrl+C always has a focused range. A context menu does not — a\n * right-click on a cell with nothing selected has to copy that cell — so\n * an explicit cell wins and the selection is the fallback.\n */\n copyCells: (cell?: GridCell, cut?: boolean) => void;\n}\n\n/**\n * Keyboard focus over the cell grid.\n *\n * @typeParam TRow - The row type.\n */\nexport function useGridFocus(\n options: UseGridFocusOptions\n): GridFocusState {\n const {\n enabled,\n headerCheckbox = false,\n rowCount,\n columns,\n rows,\n firstRowIndex = 0,\n pageSize,\n dir = \"ltr\",\n labels,\n scrollToRow,\n onActivate,\n onRangeChange,\n onCut,\n onPaste,\n onFill,\n onUndo,\n onRedo,\n onFind,\n matchKeys,\n currentMatch,\n isCoveredCell,\n } = options;\n\n const [active, setActive] = useState(null);\n const [range, setRange] = useState(null);\n // A move can outrun the DOM: the target row may not be mounted yet. This\n // holds the address until a render produces its element.\n const pending = useRef(null);\n const container = useRef(null);\n const [announcement, setAnnouncement] = useState(\"\");\n // A drag in progress. Held in a ref rather than state because it changes on\n // every pointer move and must not re-render the grid to be read.\n const dragging = useRef(false);\n // A fill drag is a different gesture from a selection drag — it carries the\n // selection's values rather than growing it — so it has its own flag. Where\n // it has reached IS state: the preview has to render.\n const filling = useRef(false);\n // Where the fill drag has reached, twice over: a ref the release reads\n // synchronously, and state the preview renders from. The release cannot read\n // it from state — running the commit inside a state updater would run it\n // during render, which React rightly warns about and StrictMode runs twice.\n const fillTo = useRef(null);\n const [fillPreviewTo, setFillPreviewTo] = useState(null);\n\n // Movement is clamped to the LOADED window, not the dataset.\n //\n // `aria-rowcount` says 100,000 because that is true and a screen reader needs\n // it. But Ctrl+End must not move to row 100,000 when only rows 1-25 are\n // loaded: on a paged table that row is on another page, and on a virtualized\n // one it may not be fetched. Moving there announces a cell the user cannot see\n // and strands DOM focus behind — exactly what the Ant Design demo did in a\n // browser before this existed. Virtualization still reaches every loaded row,\n // because `scrollToRow` mounts it and the window grows as more arrives.\n const lastLoadedRow = firstRowIndex + Math.max(0, rows.length - 1);\n const bounds = useMemo(\n () => ({\n rowCount: lastLoadedRow + 1,\n colCount: columns.length,\n pageSize: pageSize ?? Math.max(1, rows.length),\n }),\n [lastLoadedRow, columns.length, pageSize, rows.length]\n );\n\n /** Say where focus landed: the column, then the cell, then the position. */\n const announce = useCallback(\n (cell: GridCell) => {\n const column = columns[cell.col];\n if (!column) return;\n const row = rows[cell.row - firstRowIndex];\n const header =\n typeof column.header === \"string\" ? column.header : column.key;\n const value = row === undefined ? \"\" : columnText(column, row);\n const position = (labels?.gridCellPosition ?? defaultPosition)(\n cell.row + 1,\n rowCount\n );\n setAnnouncement(\n value ? `${header}, ${value}, ${position}` : `${header}, ${position}`\n );\n },\n [columns, rows, firstRowIndex, labels, rowCount]\n );\n\n const selectRange = useCallback(\n (next: CellRange | null) => {\n setRange(next);\n onRangeChange?.(next);\n // Say what was selected, not just where focus is. A single cell says\n // nothing: its own announcement already names it, and repeating \"1 cell\"\n // on every arrow press turns navigation into noise.\n if (!next || isSingleCell(next)) return;\n const b = cellRangeBounds(next);\n setAnnouncement(\n (labels?.gridRangeSelection ?? defaultRangeSelection)({\n fromRow: b.fromRow + 1,\n toRow: b.toRow + 1,\n fromColumn: b.fromCol + 1,\n toColumn: b.toCol + 1,\n cells: cellRangeSize(next),\n })\n );\n },\n [onRangeChange, labels]\n );\n\n // What a fill in progress would cover: the selection plus the cells the drag\n // has reached. Rendering it as selected is the preview — one highlight, one\n // meaning, and it cannot disagree with what gets written because both come\n // from the same rectangle.\n const fillPreview = useMemo(\n () =>\n range && fillPreviewTo ? fillTargetRange(range, fillPreviewTo) : null,\n [range, fillPreviewTo]\n );\n\n const commitFill = useEventCallback((to: GridCell) => {\n if (!range || !onFill) return;\n const edits = fillRangeEdits({\n source: range,\n to,\n rows,\n columns,\n firstRowIndex,\n });\n if (edits.length === 0) return;\n onFill(edits);\n // The filled rectangle stays selected, as it does in a spreadsheet: the\n // next fill continues from what was just written.\n setRange(fillTargetRange(range, to));\n setAnnouncement(\n (labels?.gridRangeFilled ?? defaultRangeFilled)(edits.length)\n );\n });\n\n const focusCell = useCallback(\n (cell: GridCell) => {\n setActive(cell);\n pending.current = cell;\n // Ask the virtualizer for the row before trying to focus it; if it is\n // already mounted this is a no-op and the effect below focuses at once.\n scrollToRow?.(cell.row);\n announce(cell);\n },\n [scrollToRow, announce]\n );\n\n // Move the DOM to wherever state says focus is. Keyed on the address AND on\n // the rendered rows, so a cell that arrives from a scroll gets focused on the\n // render that mounts it rather than being lost.\n useEffect(() => {\n if (!enabled) return;\n const target = pending.current;\n if (!target || !container.current) return;\n const element = container.current.querySelector(\n `[${GRID_CELL_ATTR}=\"${gridCellAttr(target)}\"]`\n );\n if (!element) return;\n pending.current = null;\n element.focus();\n }, [enabled, active, rows, firstRowIndex]);\n\n /**\n * Copy or cut, for a caller that is not the keyboard.\n *\n * The key handler always has a focused range to work from. A context\n * menu does not: a right-click on a cell with nothing selected should\n * copy THAT cell, so an explicit one wins and the selection is the\n * fallback rather than the requirement.\n */\n const copyCells = useEventCallback((cell?: GridCell, cut?: boolean) => {\n const selection: CellRange | null = cell\n ? { anchor: cell, head: cell }\n : range;\n if (!selection) return;\n copySelection(selection, cut === true);\n });\n\n /** Ctrl/Cmd+C and Ctrl/Cmd+X — the rectangle, as a spreadsheet reads it. */\n const copySelection = useEventCallback(\n (selection: CellRange, cut: boolean) => {\n const text = clipboardRangeText({\n range: selection,\n rows,\n columns,\n firstRowIndex,\n });\n void writeClipboardText(text).then((ok) => {\n setAnnouncement(\n ok\n ? (labels?.gridRangeCopied ?? defaultRangeCopied)(\n cellRangeSize(selection)\n )\n : (labels?.gridRangeCopyFailed ?? \"Copy failed\")\n );\n // A cut only tells the host once the clipboard has the data: clearing\n // cells the clipboard never took would lose them outright.\n if (ok && cut) onCut?.(selection);\n });\n }\n );\n\n /** Ctrl/Cmd+D — the selection's top row carries into the rest of it. */\n const fillDown = useEventCallback((selection: CellRange) => {\n const b = cellRangeBounds(selection);\n const edits = fillRangeEdits({\n source: {\n anchor: { row: b.fromRow, col: b.fromCol },\n head: { row: b.fromRow, col: b.toCol },\n },\n to: { row: b.toRow, col: b.toCol },\n rows,\n columns,\n firstRowIndex,\n });\n onFill?.(edits);\n setAnnouncement(\n (labels?.gridRangeFilled ?? defaultRangeFilled)(edits.length)\n );\n });\n\n /** Ctrl/Cmd+V — the clipboard, mapped onto the selection's top-left cell. */\n const pasteInto = useEventCallback((target: CellRange) => {\n void readClipboardText().then((text) => {\n if (text === null) {\n setAnnouncement(labels?.gridRangePasteFailed ?? \"Paste failed\");\n return;\n }\n const edits = pasteRangeEdits({\n text,\n range: target,\n rows,\n columns,\n firstRowIndex,\n });\n onPaste?.(edits);\n setAnnouncement(\n (labels?.gridRangePasted ?? defaultRangePasted)(edits.length)\n );\n });\n });\n\n /**\n * The Ctrl/Cmd gestures: copy, cut, fill down, paste.\n *\n * They live together and run before movement, so a modifier never doubles as\n * a navigation key. Each stays the BROWSER'S own when the table has nothing\n * to do with it — no selection, no host handler — which is what `false` says.\n *\n * @returns Whether the table took the key.\n */\n /** Ctrl/Cmd+Z and its two redo spellings, announced either way. */\n const handleHistoryKey = useEventCallback(\n (event: { key: string; shiftKey?: boolean }): boolean => {\n const redo =\n (event.key === \"z\" && event.shiftKey === true) || event.key === \"y\";\n const undo = event.key === \"z\" && event.shiftKey !== true;\n if (!undo && !redo) return false;\n const run = redo ? onRedo : onUndo;\n if (!run) return false;\n const cells = run();\n const say = redo\n ? (labels?.editRedone ?? defaultRedone)\n : (labels?.editUndone ?? defaultUndone);\n setAnnouncement(\n cells === 0\n ? (labels?.editNothingToUndo ?? \"Nothing to undo\")\n : say(cells)\n );\n return true;\n }\n );\n\n const handleClipboardKey = useEventCallback(\n (\n event: {\n key: string;\n ctrlKey?: boolean;\n metaKey?: boolean;\n shiftKey?: boolean;\n preventDefault: () => void;\n },\n from: GridCell\n ): boolean => {\n if (event.ctrlKey !== true && event.metaKey !== true) return false;\n if (handleHistoryKey(event)) {\n event.preventDefault();\n return true;\n }\n // Ctrl/Cmd+F belongs to the table only when the table has a find bar to\n // open; otherwise the browser's own find is the right answer.\n if (event.key === \"f\" && onFind) {\n event.preventDefault();\n onFind();\n return true;\n }\n if ((event.key === \"c\" || event.key === \"x\") && range) {\n event.preventDefault();\n copySelection(range, event.key === \"x\");\n return true;\n }\n // Nothing to carry into a one-row selection, so the key stays the\n // browser's there.\n if (event.key === \"d\" && onFill && range && !isSingleRowRange(range)) {\n event.preventDefault();\n fillDown(range);\n return true;\n }\n // Paste needs a destination, not a rectangle: a spreadsheet pastes into\n // the focused cell and lets the clipboard's own shape decide the rest, so\n // this takes the same `from` the movement keys take rather than demanding\n // a selection first.\n if (event.key === \"v\" && onPaste) {\n event.preventDefault();\n pasteInto(range ?? singleCellRange(from));\n return true;\n }\n return false;\n }\n );\n\n const onKeyDown = useEventCallback(\n (event: {\n key: string;\n ctrlKey?: boolean;\n metaKey?: boolean;\n shiftKey?: boolean;\n preventDefault: () => void;\n }) => {\n if (!enabled) return;\n const from = active ?? { row: firstRowIndex, col: 0 };\n if (handleClipboardKey(event, from)) return;\n\n // Enter and F2 belong to whatever is inside the cell — `EditableCellGate`\n // handles both on the element focus just landed on. This only fires when\n // a host asked for its own activation, and stays out of the way otherwise\n // so the two never race for one key press.\n if (event.key === \"Enter\" || event.key === \"F2\") {\n if (onActivate) {\n event.preventDefault();\n onActivate(from);\n }\n return;\n }\n\n const move = gridFocusMoveForKey(event, dir);\n if (!move) return;\n const moved = moveGridFocus(from, move, bounds, isCoveredCell);\n // The window may not start at row 0 (page 3 of a paged table) and the\n // mover clamps at zero, so hold that floor here too.\n const next = { row: Math.max(moved.row, firstRowIndex), col: moved.col };\n // An edge move resolves to the same cell: swallow the key so the page\n // does not scroll, but say nothing — nothing changed.\n event.preventDefault();\n if (sameGridCell(next, active)) return;\n\n // Focus first, then the selection: both write the live region, and for a\n // Shift move the RANGE is the news while for a plain move the cell is.\n // Whichever runs last wins, so the order encodes which one matters.\n focusCell(next);\n if (event.shiftKey === true) {\n // Shift extends from wherever the selection began, so pressing\n // Shift+Down twice then Shift+Up shrinks the range rather than starting\n // a new one upward. `from` is the fallback anchor for the first press.\n selectRange(extendCellRange(range, next, from));\n } else {\n // A plain move collapses any selection to the cell landed on, which is\n // what every grid does and what stops a stale rectangle lingering.\n selectRange(singleCellRange(next));\n }\n }\n );\n\n // A pointer released outside the table would otherwise leave the drag armed,\n // so the next hover over any cell would extend a selection nobody started.\n useEffect(() => {\n if (!enabled) return undefined;\n const end = () => {\n dragging.current = false;\n if (!filling.current) return;\n filling.current = false;\n const to = fillTo.current;\n fillTo.current = null;\n setFillPreviewTo(null);\n // A fill that never left the selection writes nothing, which `commitFill`\n // decides.\n if (to) commitFill(to);\n };\n window.addEventListener(\"mouseup\", end);\n return () => window.removeEventListener(\"mouseup\", end);\n }, [enabled, commitFill]);\n\n const getGridProps = useCallback(() => {\n if (!enabled) return {};\n return {\n role: \"grid\",\n \"aria-rowcount\": rowCount,\n \"aria-colcount\": columns.length,\n onKeyDown,\n ref: (node: HTMLElement | null) => {\n container.current = node;\n },\n };\n }, [enabled, rowCount, columns.length, onKeyDown]);\n\n const getCellProps = useCallback(\n (cell: GridCell) => {\n if (!enabled) return {};\n const isActive = sameGridCell(cell, active);\n // Exactly one cell is tabbable. Before the grid has ever been entered\n // that is its first cell, so Tab reaches the table at all.\n const firstEver =\n active === null && cell.row === firstRowIndex && cell.col === 0;\n // While a fill is being dragged the highlight shows what it would write.\n const selected = isInCellRange(fillPreview ?? range, cell);\n const key = gridCellAttr(cell);\n const matched = matchKeys?.has(key) === true;\n return {\n [GRID_CELL_ATTR]: gridCellAttr(cell),\n tabIndex: isActive || firstEver ? 0 : -1,\n \"aria-colindex\": cell.col + 1,\n // Only meaningful once a real rectangle exists: marking every focused\n // cell as selected would tell a screen reader the table is in selection\n // mode when the user has merely arrowed around.\n \"aria-selected\": range && !isSingleCell(range) ? selected : undefined,\n \"data-cell-selected\": selected ? \"\" : undefined,\n \"data-cell-match\": matched ? \"\" : undefined,\n \"data-cell-match-current\":\n matched && sameGridCell(cell, currentMatch ?? null) ? \"\" : undefined,\n onMouseDown: (event: { shiftKey?: boolean }) => {\n if (event.shiftKey === true) {\n selectRange(extendCellRange(range, cell, active ?? cell));\n } else {\n // A press with no modifier starts a drag AND collapses to this\n // cell: dragging away extends from here, releasing without moving\n // leaves the single-cell selection a plain click should give.\n dragging.current = true;\n selectRange(singleCellRange(cell));\n }\n },\n onMouseEnter: () => {\n // Extending on ENTER rather than on move means one update per cell\n // crossed instead of one per pixel.\n if (filling.current) {\n fillTo.current = cell;\n setFillPreviewTo(cell);\n return;\n }\n if (!dragging.current) return;\n selectRange(extendCellRange(range, cell, active ?? cell));\n },\n onMouseUp: () => {\n dragging.current = false;\n },\n onFocus: () => {\n // A mouse click or a screen reader can move focus without a key\n // press; keep state in step rather than fighting it.\n if (!sameGridCell(cell, active)) setActive(cell);\n },\n };\n },\n [\n enabled,\n active,\n firstRowIndex,\n range,\n fillPreview,\n matchKeys,\n currentMatch,\n selectRange,\n ]\n );\n\n /**\n * Select an entire column — what a header click and Ctrl/Cmd+click do.\n *\n * The rectangle spans the LOADED rows, the same bound movement obeys: a column\n * of 100,000 rows cannot be selected when only 500 are in hand, and claiming\n * otherwise would export or copy rows the browser has never seen.\n */\n const selectColumn = useCallback(\n (col: number, extend = false) => {\n const top = { row: firstRowIndex, col };\n const bottom = { row: lastLoadedRow, col };\n selectRange(\n extend && range\n ? extendCellRange(range, bottom, range.anchor)\n : { anchor: top, head: bottom }\n );\n focusCell(top);\n },\n [firstRowIndex, lastLoadedRow, range, selectRange, focusCell]\n );\n\n /**\n * Whether the selection is exactly this column.\n *\n * Both bounds are checked, not just the columns: a rectangle three rows tall\n * inside one column is not that column selected, and a checkbox claiming it\n * is would be wrong in the direction that matters — the reader would think a\n * copy or an export covers rows it does not.\n */\n const isColumnSelected = useCallback(\n (col: number) => {\n if (!enabled || !range) return false;\n const bounds = cellRangeBounds(range);\n return (\n bounds.fromCol === col &&\n bounds.toCol === col &&\n bounds.fromRow === firstRowIndex &&\n bounds.toRow === lastLoadedRow\n );\n },\n [enabled, range, firstRowIndex, lastLoadedRow]\n );\n\n /**\n * What the header checkbox does.\n *\n * Ticking selects the column alone — the same rectangle a plain click makes.\n * Unticking clears, because nothing selected is the only state one checkbox\n * can return to: a rectangle cannot lose a column out of its middle.\n */\n const toggleColumn = useCallback(\n (col: number) => {\n if (isColumnSelected(col)) {\n selectRange(null);\n return;\n }\n selectColumn(col);\n },\n [isColumnSelected, selectRange, selectColumn]\n );\n\n /** Props for a column header that selects its column when clicked. */\n const getColumnHeaderProps = useCallback(\n (col: number, options?: { sortable?: boolean }) => {\n if (!enabled) return {};\n return {\n onClick: (event: { ctrlKey?: boolean; metaKey?: boolean }) => {\n const modified = event.ctrlKey === true || event.metaKey === true;\n // A sortable header's plain click already sorts, and the two cannot\n // share it without one breaking. Ctrl/Cmd+click selects anywhere; a\n // plain click selects only where nothing else claims it.\n if (!modified && options?.sortable === true) return;\n selectColumn(col, modified);\n },\n };\n },\n [enabled, selectColumn]\n );\n\n // The handle sits on the selection's bottom inline-end corner — the last row\n // and last column of the rectangle. Only when a host can receive a fill:\n // an affordance for a gesture nothing listens to is a lie.\n const fillHandleCell = useMemo(() => {\n if (!enabled || !range || !onFill) return null;\n const b = cellRangeBounds(range);\n return { row: b.toRow, col: b.toCol };\n }, [enabled, range, onFill]);\n\n const getFillHandleProps = useCallback(\n () => ({\n onMouseDown: (event: {\n preventDefault: () => void;\n stopPropagation: () => void;\n }) => {\n // Stop the cell's own press: that one collapses the selection to a\n // single cell, which is the opposite of what a fill starts from.\n event.preventDefault();\n event.stopPropagation();\n filling.current = true;\n },\n }),\n []\n );\n\n const getRowProps = useCallback(\n (rowIndex: number) => (enabled ? { \"aria-rowindex\": rowIndex + 1 } : {}),\n [enabled]\n );\n\n const getCellPropsAt = useCallback(\n (windowIndex: number, col: number) =>\n getCellProps({ row: firstRowIndex + windowIndex, col }),\n [getCellProps, firstRowIndex]\n );\n\n const getRowPropsAt = useCallback(\n (windowIndex: number) => getRowProps(firstRowIndex + windowIndex),\n [getRowProps, firstRowIndex]\n );\n\n // Memoized as a whole. A fresh object each render is not a cosmetic problem:\n // an adapter that memoizes on this state — antd derives its `components.table`\n // from it — would rebuild that derivation every render, remount the table, and\n // destroy the focus this hook just placed. Found exactly that way in a browser.\n return useMemo(\n () => ({\n enabled,\n active: enabled ? active : null,\n getGridProps,\n getCellProps,\n getRowProps,\n getCellPropsAt,\n getRowPropsAt,\n announcement: enabled ? announcement : \"\",\n range: enabled ? range : null,\n selectRange,\n selectColumn,\n columnCheckbox: enabled && headerCheckbox,\n isColumnSelected,\n toggleColumn,\n getColumnHeaderProps,\n focusCell,\n fillHandleCell,\n getFillHandleProps,\n fillHandleLabel: labels?.gridFillHandle ?? \"Fill from selection\",\n fillPreview: enabled ? fillPreview : null,\n copyCells,\n }),\n [\n enabled,\n active,\n getGridProps,\n getCellProps,\n getRowProps,\n getCellPropsAt,\n getRowPropsAt,\n announcement,\n range,\n selectRange,\n selectColumn,\n headerCheckbox,\n isColumnSelected,\n toggleColumn,\n getColumnHeaderProps,\n focusCell,\n fillHandleCell,\n getFillHandleProps,\n labels,\n fillPreview,\n copyCells,\n ]\n );\n}\n\n/** \"selected rows 3 to 7, columns 2 to 4, 15 cells\" — replaceable via labels. */\nfunction defaultRangeSelection({\n fromRow,\n toRow,\n fromColumn,\n toColumn,\n cells,\n}: {\n fromRow: number;\n toRow: number;\n fromColumn: number;\n toColumn: number;\n cells: number;\n}): string {\n return `selected rows ${fromRow} to ${toRow}, columns ${fromColumn} to ${toColumn}, ${cells} cells`;\n}\n\n/** Whether a rectangle is one row tall — there is nothing to fill down into. */\nfunction isSingleRowRange(range: CellRange): boolean {\n const bounds = cellRangeBounds(range);\n return bounds.fromRow === bounds.toRow;\n}\n\n/** \"12 cells restored\" — replaceable through `labels.editUndone`. */\nfunction defaultUndone(cells: number): string {\n return `${cells} ${cells === 1 ? \"cell\" : \"cells\"} restored`;\n}\n\n/** \"12 cells redone\" — replaceable through `labels.editRedone`. */\nfunction defaultRedone(cells: number): string {\n return `${cells} ${cells === 1 ? \"cell\" : \"cells\"} redone`;\n}\n\n/** \"12 cells copied\" — replaceable through `labels.gridRangeCopied`. */\nfunction defaultRangeCopied(cells: number): string {\n return `${cells} ${cells === 1 ? \"cell\" : \"cells\"} copied`;\n}\n\n/** \"12 cells filled\" — replaceable through `labels.gridRangeFilled`. */\nfunction defaultRangeFilled(cells: number): string {\n return `${cells} ${cells === 1 ? \"cell\" : \"cells\"} filled`;\n}\n\n/** \"12 cells pasted\" — replaceable through `labels.gridRangePasted`. */\nfunction defaultRangePasted(cells: number): string {\n return `${cells} ${cells === 1 ? \"cell\" : \"cells\"} pasted`;\n}\n\n/** \"row 41 of 10,000\" — replaceable through `labels.gridCellPosition`. */\nfunction defaultPosition(row: number, total: number): string {\n return `row ${row} of ${total}`;\n}\n","/**\n * Fullscreen, and the thing that breaks when you add it.\n *\n * The Fullscreen API promotes one element and hides everything else in the\n * document. That is exactly what a table wants — and it is why every\n * overlay the table owns stops working the moment it is used, because a\n * menu, a popover or a dialog is portalled to `document.body`, and\n * `document.body` is now one of the things being hidden. The overlay is\n * still in the DOM, still focused, still announced, and completely\n * invisible.\n *\n * There is no way to fix that from inside the overlay. The only fix is for\n * the portal to land INSIDE the promoted element, so this hook's real job\n * is not toggling fullscreen — it is telling every kit where to portal\n * while fullscreen is on. `container` is that answer: the fullscreen\n * element, or `undefined` for \"wherever you normally would\".\n *\n * The state is read from the document rather than remembered, because\n * fullscreen can end without going through this hook at all: Escape, the\n * browser's own control, another element being promoted. A remembered flag\n * would say \"on\" while the page had already left.\n */\nimport { useCallback, useEffect, useState } from \"react\";\n\n/** What {@link useFullscreen} returns. */\nexport interface FullscreenState {\n /** Whether the table is the fullscreen element right now. */\n active: boolean;\n /** Whether the browser will allow it at all. */\n supported: boolean;\n /** Go fullscreen, or leave. */\n toggle: () => void;\n /** Leave, if it is on. */\n exit: () => void;\n /**\n * Where overlays must portal while fullscreen is on, and `undefined`\n * otherwise. Hand this to each kit's portal target — Mantine's\n * `portalProps`, MUI's `container`, antd's `getPopupContainer` — or the\n * kit's menus will render into a document nobody can see.\n */\n container: HTMLElement | undefined;\n}\n\n/** Whether this document can do fullscreen at all. */\nfunction canFullscreen(): boolean {\n return typeof document !== \"undefined\" && document.fullscreenEnabled;\n}\n\n/**\n * Promote a table to fullscreen, and say where overlays should go.\n *\n * @param element - The table's root. Nothing happens without one.\n * @returns The state, the toggle, and the portal container.\n */\nexport function useFullscreen(element: HTMLElement | null): FullscreenState {\n const [active, setActive] = useState(false);\n const supported = canFullscreen();\n\n useEffect(() => {\n if (!supported) return;\n // The document is the source of truth. Escape and the browser's own\n // control both leave fullscreen without telling this hook, and a\n // remembered flag would go on claiming the table was promoted.\n const sync = () => {\n setActive(element !== null && document.fullscreenElement === element);\n };\n sync();\n document.addEventListener(\"fullscreenchange\", sync);\n return () => {\n document.removeEventListener(\"fullscreenchange\", sync);\n };\n }, [element, supported]);\n\n const exit = useCallback(() => {\n if (document.fullscreenElement) void document.exitFullscreen();\n }, []);\n\n const toggle = useCallback(() => {\n if (!supported || !element) return;\n if (document.fullscreenElement === element) {\n void document.exitFullscreen();\n return;\n }\n // A rejection here is ordinary: a browser refuses fullscreen that was\n // not asked for by a real gesture, and that is not an error worth\n // throwing at the host.\n void element.requestFullscreen().catch(() => undefined);\n }, [element, supported]);\n\n return {\n active,\n supported,\n toggle,\n exit,\n container: active && element ? element : undefined,\n };\n}\n","import { useCallback, useSyncExternalStore } from \"react\";\n\n/**\n * One `MediaQueryList` per (matchMedia implementation, query) pair.\n * `getSnapshot` runs on EVERY render of every subscriber, and\n * `matchMedia(query)` constructs a fresh list each call — caching turns\n * that hot path into a map lookup. Keyed by the implementation (WeakMap)\n * so tests that stub `matchMedia` never read a stale cache.\n */\nconst mqlCacheByImpl = new WeakMap<\n typeof globalThis.matchMedia,\n Map\n>();\n\nfunction cachedMatchMedia(query: string): MediaQueryList | null {\n const impl = globalThis.matchMedia as\n | typeof globalThis.matchMedia\n | undefined;\n if (typeof impl !== \"function\") return null;\n let cache = mqlCacheByImpl.get(impl);\n if (!cache) {\n cache = new Map();\n mqlCacheByImpl.set(impl, cache);\n }\n let mql = cache.get(query);\n if (!mql) {\n mql = impl(query);\n cache.set(query, mql);\n }\n return mql;\n}\n\n/**\n * SSR-safe `matchMedia` hook built on `useSyncExternalStore`. Returns\n * `false` on the server and before hydration, then the live match.\n *\n * @param query - A CSS media query string, e.g. `\"(max-width: 768px)\"`.\n * @param defaultValue - Value used when `matchMedia` is unavailable (SSR).\n * @returns Whether the query currently matches.\n */\nexport function useMediaQuery(query: string, defaultValue = false): boolean {\n const subscribe = useCallback(\n (onChange: () => void) => {\n const mql = cachedMatchMedia(query);\n if (!mql) return () => undefined;\n mql.addEventListener(\"change\", onChange);\n return () => mql.removeEventListener(\"change\", onChange);\n },\n [query]\n );\n\n const getSnapshot = useCallback(() => {\n const mql = cachedMatchMedia(query);\n return mql ? mql.matches : defaultValue;\n }, [query, defaultValue]);\n\n const getServerSnapshot = useCallback(() => defaultValue, [defaultValue]);\n\n return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);\n}\n","import { useMediaQuery } from \"./useMediaQuery\";\n\n/** The media query that matches when the user prefers reduced motion. */\nexport const REDUCED_MOTION_QUERY = \"(prefers-reduced-motion: reduce)\";\n\n/**\n * Whether the user has requested reduced motion. Animation hooks gate on\n * this so AdaptTable never animates against an accessibility preference.\n *\n * @returns `true` when the user prefers reduced motion.\n */\nexport function usePrefersReducedMotion(): boolean {\n return useMediaQuery(REDUCED_MOTION_QUERY);\n}\n","/**\n * Produce a deterministic string from any JSON-serialisable value so it\n * can be embedded in a query cache key (e.g. TanStack Query) without\n * changing identity on every render.\n *\n * Guarantees:\n * - Object keys are sorted, so `{ a, b }` and `{ b, a }` serialise\n * identically.\n * - Nested objects are normalised recursively.\n * - Array order is preserved (order is meaningful for lists).\n * - `undefined` values are dropped, mirroring how query strings and\n * `JSON.stringify` already treat them.\n *\n * @param input - Any value. Functions/symbols are not supported and will\n * serialise the way `JSON.stringify` handles them.\n * @returns A stable JSON string for the normalised input.\n *\n * @example\n * ```ts\n * stableKey({ b: 1, a: 2 }) === stableKey({ a: 2, b: 1 }); // true\n * ```\n */\nexport function stableKey(input: unknown): string {\n return JSON.stringify(normalize(input));\n}\n\nfunction normalize(value: unknown): unknown {\n if (value === null || typeof value !== \"object\") {\n return value === undefined ? undefined : value;\n }\n\n if (Array.isArray(value)) {\n return value.map((entry) => normalize(entry));\n }\n\n const source = value as Record;\n // Locale-pinned sort keeps the key identical across user locales while\n // staying lexicographic on UTF-16 code units.\n const keys = Object.keys(source).sort((a, b) => a.localeCompare(b, \"en\"));\n const out: Record = {};\n for (const key of keys) {\n const normalized = normalize(source[key]);\n if (normalized !== undefined) {\n out[key] = normalized;\n }\n }\n return out;\n}\n","/**\n * Package-local defaults. Adapters may override per-table via props; these\n * are the headless fallbacks.\n */\n\n/** Viewport width (px) below which `\"auto\"` pagination flips to infinite. */\nexport const MOBILE_BREAKPOINT_PX = 768;\n\n/** Default rows-per-page. */\nexport const DEFAULT_LIMIT = 25;\n\n/** Page-size options offered by adapter pagination controls. */\nexport const PAGE_SIZE_OPTIONS = [10, 25, 50, 100] as const;\n\n/**\n * Page-size options to render in a rows-per-page selector, guaranteeing every\n * given size is present. Pass the active `limit` alone, or `[limit,\n * defaultLimit]` so a host default (scale's 500, a shared-URL 15) stays\n * listed after the user picks 10 / 25 / 50 / 100 — otherwise it vanishes\n * and cannot be selected again.\n *\n * Off-list values are prepended in the order given, de-duplicated.\n *\n * @param limit - The currently-active page size, or several sizes that must\n * stay listed (active + the table's default page size).\n * @param sizes - The standard options to offer (defaults to {@link PAGE_SIZE_OPTIONS}).\n * @returns The options to render, with every given size guaranteed present.\n */\nexport function pageSizeOptions(\n limit: number | readonly number[],\n sizes: readonly number[] = PAGE_SIZE_OPTIONS\n): readonly number[] {\n const extras = (typeof limit === \"number\" ? [limit] : limit).filter(\n (n, i, all) => !sizes.includes(n) && all.indexOf(n) === i\n );\n return extras.length > 0 ? [...extras, ...sizes] : sizes;\n}\n\n/** Default debounce (ms) for the search input before it commits to state. */\nexport const SEARCH_DEBOUNCE_MS = 300;\n\n/** Default row-height estimate (px) for virtualized desktop tables. */\nexport const DEFAULT_ROW_SIZE_PX = 56;\n\n/** Default card-height estimate (px) for virtualized mobile layouts. */\nexport const DEFAULT_CARD_SIZE_PX = 132;\n\n/** Default extra rows/cards rendered above and below the virtual window. */\nexport const VIRTUAL_OVERSCAN = 8;\n","import { MOBILE_BREAKPOINT_PX } from \"../constants\";\nimport type { PaginationMode, ResolvedPaginationMode } from \"../types\";\nimport { useMediaQuery } from \"./useMediaQuery\";\n\n/** The media query that matches the mobile layout at the default width. */\nexport const MOBILE_MEDIA_QUERY = `(max-width: ${MOBILE_BREAKPOINT_PX}px)`;\n\n/**\n * The media query for a given mobile breakpoint.\n *\n * @param px - The width at or below which the card layout takes over.\n * @returns The query string.\n */\nexport function mobileMediaQuery(px: number): string {\n return px === MOBILE_BREAKPOINT_PX\n ? MOBILE_MEDIA_QUERY\n : `(max-width: ${String(px)}px)`;\n}\n\n/**\n * Whether the viewport is at or below the mobile breakpoint.\n *\n * The default is 768px — a phone in portrait. Raise it when the table lives\n * in a sidebar or a split pane, where the viewport says \"desktop\" but the\n * table has a phone's width to work with; lower it when the table is the\n * whole page and the columns are narrow enough to survive.\n *\n * @param px - The breakpoint in pixels. Defaults to 768.\n * @returns `true` on viewports at or below it.\n */\nexport function useIsMobile(px: number = MOBILE_BREAKPOINT_PX): boolean {\n return useMediaQuery(mobileMediaQuery(px));\n}\n\n/**\n * Resolve `\"auto\"` to a concrete pagination mode (mobile → infinite,\n * desktop → paged). A non-auto mode is returned unchanged.\n *\n * @param mode - The requested pagination mode.\n * @param isMobile - Whether the table is in its mobile layout.\n * @returns The resolved mode.\n */\nexport function resolvePaginationMode(\n mode: PaginationMode,\n isMobile: boolean\n): ResolvedPaginationMode {\n if (mode !== \"auto\") return mode;\n return isMobile ? \"infinite\" : \"paged\";\n}\n","import { useCallback, useEffect, useMemo, useSyncExternalStore } from \"react\";\n\nimport { DEFAULT_LIMIT } from \"../constants\";\nimport type { QueryFilterGroup } from \"../source/queryContract\";\nimport type { TableStateMutators } from \"../tableStateMutators\";\nimport type {\n ExtraFilters,\n FilterValue,\n SortDirection,\n TableQueryParams,\n} from \"../types\";\nimport { devWarn } from \"../utils/devWarn\";\nimport { type UrlStateAdapter, useResolvedAdapter } from \"./adapter\";\nimport {\n FILTER_PREFIX,\n isEmptyFilterValue,\n MAX_LIMIT,\n PARAM_GROUP_BY,\n PARAM_LIMIT,\n PARAM_PAGE,\n PARAM_SEARCH,\n PARAM_SORT_BY,\n PARAM_SORT_DIR,\n readExtra,\n readFilterTreeParam,\n readLimit,\n readPage,\n readSortDir,\n readSortLevels,\n writeExtra,\n writeFilterTreeParam,\n writeSortLevels,\n} from \"./serialize\";\n\n/** Options for {@link useTableUrlState}. */\nexport interface UseTableUrlStateOptions {\n /**\n * URL-state backend. Defaults to the browser History API. Supply a\n * router-specific adapter (react-router / Next.js) to integrate with an\n * existing navigation stack.\n */\n urlAdapter?: UrlStateAdapter;\n /**\n * When `false`, state is kept in a component-local memory store instead\n * of the URL — the table still works fully, it just isn't shareable.\n * Defaults to `true`.\n */\n urlSync?: boolean;\n /** Initial values applied when the URL has no value for a key. */\n defaults?: Partial & { extra?: ExtraFilters };\n /** Extra-filter keys whose values are parsed as numbers. */\n numberExtraKeys?: readonly string[];\n /** Extra-filter keys whose values are comma-separated arrays. */\n arrayExtraKeys?: readonly string[];\n /**\n * Namespace for this table's URL params, so multiple tables can share one\n * URL without colliding. With `urlKey=\"left\"` the params become\n * `left.q`, `left.page`, `left.f_status`, … Omit for the bare keys.\n */\n urlKey?: string;\n}\n\n/** State + setters returned by {@link useTableUrlState}. */\nexport interface UseTableUrlStateResult extends TableStateMutators {\n /** Current 1-based page. */\n page: number;\n /** Current page size. */\n limit: number;\n /**\n * Page size applied when the URL has no `limit` param (`defaults.limit`,\n * or 25). Stable across `setLimit` so the rows-per-page list can keep it.\n */\n defaultLimit: number;\n /** Current committed search term. */\n search: string;\n /** Active sort column key, if any. */\n sortBy: string | undefined;\n /** Active sort direction, if any. */\n sortDir: SortDirection | undefined;\n /** Active single-level row-grouping column key, if any. */\n groupBy: string | undefined;\n /** The extra-filter bag. */\n extra: ExtraFilters;\n /** Nested AND/OR filter tree, when one is in the URL. */\n filterTree: QueryFilterGroup | undefined;\n}\n\n/** Mounted namespaces per adapter, for the duplicate-urlKey dev warning. */\nconst nsRegistry = new WeakMap>();\n\n/**\n * Stable default for the key registries. Destructuring defaults (`= []`)\n * would mint a fresh array per render, invalidating the `extra` memo and\n * re-running the host's whole filter/sort pipeline on EVERY re-render.\n */\nconst NO_KEYS: readonly string[] = [];\n\n/**\n * Headless URL-synced table state. Keeps page / limit / search / sort and\n * an arbitrary `extra` filter bag in the query string (or a local store\n * when disabled), so reloads, shared links, and back/forward all restore\n * the exact slice. Decoupled from any router via {@link UrlStateAdapter}.\n *\n * `defaults` apply only while the URL is silent about a key. When the user\n * explicitly clears a defaulted value (clearing the search, removing a\n * filter chip, clear-all), the hook records the clearing as an EMPTY-valued\n * param (`q=`, `sortBy=`, `f_status=`) so the default does not instantly\n * resurrect. Without a default for the key the param is simply deleted, so\n * URLs stay clean in the common case.\n *\n * @param options - See {@link UseTableUrlStateOptions}.\n * @returns The current state and its setters.\n */\nexport function useTableUrlState(\n options: UseTableUrlStateOptions = {}\n): UseTableUrlStateResult {\n const {\n urlAdapter,\n urlSync,\n defaults = {},\n numberExtraKeys = NO_KEYS,\n arrayExtraKeys = NO_KEYS,\n urlKey,\n } = options;\n // Per-table namespace, e.g. \"left.\" → left.q / left.page / left.f_status.\n const ns = urlKey ? `${urlKey}.` : \"\";\n\n const backend = urlAdapter;\n const syncToUrl = urlSync ?? true;\n const resolved = useResolvedAdapter(backend, syncToUrl);\n // Server snapshot: with the default (history) adapter the server rendered\n // from an empty memory store, so hydration must read \"\" too — the real URL\n // applies right after hydration. An EXPLICIT adapter is assumed to be\n // SSR-consistent (e.g. a router adapter that knows the request URL).\n const search = useSyncExternalStore(\n (onChange) => resolved.subscribe(onChange),\n () => resolved.getSearch(),\n () => (backend ? backend.getSearch() : \"\")\n );\n const params = useMemo(() => new URLSearchParams(search), [search]);\n\n // Two tables on one adapter without distinct urlKeys silently clobber each\n // other's params — catch it in development.\n useEffect(() => {\n const counts = nsRegistry.get(resolved) ?? new Map();\n nsRegistry.set(resolved, counts);\n const next = (counts.get(ns) ?? 0) + 1;\n counts.set(ns, next);\n if (next > 1) {\n devWarn(\n `two tables share the URL namespace \"${ns || \"(bare)\"}\" — give each table a distinct \\`urlKey\\` or their state will clobber each other.`\n );\n }\n return () => {\n // The registration above guarantees an entry; drop it at zero so the\n // registry never grows.\n const remaining = counts.get(ns)! - 1;\n if (remaining === 0) counts.delete(ns);\n else counts.set(ns, remaining);\n };\n }, [resolved, ns]);\n\n const initialLimit = defaults.limit ?? DEFAULT_LIMIT;\n const initialPage = defaults.page ?? 1;\n const page = readPage(params, initialPage, ns);\n const limit = readLimit(params, initialLimit, ns);\n // An empty-valued param is an explicit \"cleared\" marker (see the hook\n // docs): the URL overrides the default with nothing.\n const searchTerm = (\n params.get(ns + PARAM_SEARCH) ??\n defaults.search ??\n \"\"\n ).trim();\n const sortByRaw = params.get(ns + PARAM_SORT_BY);\n const sortBy = sortByRaw === null ? defaults.sortBy : sortByRaw || undefined;\n // A defaulted sort adopts the defaulted direction — else ascending, so\n // `defaults: { sortBy }` alone still yields a real sort (data actually\n // ordered, aria-sort truthful, first header click cycles to descending\n // instead of clearing). An explicit URL sort with no direction falls\n // back to ascending too.\n const sortDirFallback =\n sortByRaw === null ? (defaults.sortDir ?? \"asc\") : \"asc\";\n const sortDir =\n sortBy === undefined\n ? undefined\n : (readSortDir(params, ns) ?? sortDirFallback);\n const groupByRaw = params.get(ns + PARAM_GROUP_BY);\n const groupBy =\n groupByRaw === null ? defaults.groupBy : groupByRaw || undefined;\n const sortLevels = useMemo(() => readSortLevels(params, ns), [params, ns]);\n\n /** Merge `defaults.extra` under the URL bag, honouring cleared markers. */\n const mergeDefaultExtra = useCallback(\n (p: URLSearchParams, urlBag: ExtraFilters): ExtraFilters => {\n if (!defaults.extra) return urlBag;\n const out: ExtraFilters = {};\n for (const [key, value] of Object.entries(defaults.extra)) {\n // A present-but-empty param means the user cleared this default.\n if (p.get(ns + FILTER_PREFIX + key) === null) out[key] = value;\n }\n return { ...out, ...urlBag };\n },\n [defaults.extra, ns]\n );\n\n const extra = useMemo(\n () =>\n mergeDefaultExtra(\n params,\n readExtra(params, numberExtraKeys, arrayExtraKeys, ns)\n ),\n [mergeDefaultExtra, params, numberExtraKeys, arrayExtraKeys, ns]\n );\n\n const filterTree = useMemo(\n () => readFilterTreeParam(params, ns),\n [params, ns]\n );\n\n const commit = useCallback(\n (mutate: (next: URLSearchParams) => void) => {\n const next = new URLSearchParams(resolved.getSearch());\n mutate(next);\n resolved.setSearch(next.toString());\n },\n [resolved]\n );\n\n /**\n * Write the full extra bag, then stamp a cleared marker for every\n * defaulted key the bag no longer carries — deleting the param instead\n * would resurrect the default on the next read.\n */\n const writeExtraWithDefaults = useCallback(\n (p: URLSearchParams, bag: ExtraFilters) => {\n writeExtra(p, bag, ns);\n for (const key of Object.keys(defaults.extra ?? {})) {\n if (isEmptyFilterValue(bag[key])) p.set(ns + FILTER_PREFIX + key, \"\");\n }\n },\n [defaults.extra, ns]\n );\n\n /** The current effective extra bag read fresh from a params snapshot. */\n const readEffectiveExtra = useCallback(\n (p: URLSearchParams): ExtraFilters =>\n mergeDefaultExtra(p, readExtra(p, numberExtraKeys, arrayExtraKeys, ns)),\n [mergeDefaultExtra, numberExtraKeys, arrayExtraKeys, ns]\n );\n\n /** Reset to page 1 — as a marker when a non-1 default would resurface. */\n const resetPage = useCallback(\n (p: URLSearchParams) => {\n if (initialPage > 1) p.set(ns + PARAM_PAGE, \"1\");\n else p.delete(ns + PARAM_PAGE);\n },\n [initialPage, ns]\n );\n\n const setPage = useCallback(\n (next: number) =>\n commit((p) => {\n if (next <= 1) resetPage(p);\n else p.set(ns + PARAM_PAGE, String(next));\n }),\n [commit, ns, resetPage]\n );\n\n const setLimit = useCallback(\n (next: number) =>\n commit((p) => {\n // Keep the written value inside the range the read side accepts\n // so URL and table state never diverge.\n const clamped = Math.min(Math.max(1, Math.round(next)), MAX_LIMIT);\n if (clamped === initialLimit) p.delete(ns + PARAM_LIMIT);\n else p.set(ns + PARAM_LIMIT, String(clamped));\n resetPage(p);\n }),\n [commit, initialLimit, ns, resetPage]\n );\n\n const setSearch = useCallback(\n (next: string) =>\n commit((p) => {\n const trimmed = next.trim();\n if (trimmed !== \"\") p.set(ns + PARAM_SEARCH, trimmed);\n else if (defaults.search) p.set(ns + PARAM_SEARCH, \"\");\n else p.delete(ns + PARAM_SEARCH);\n resetPage(p);\n }),\n [commit, defaults.search, ns, resetPage]\n );\n\n const setSort = useCallback(\n (key: string | undefined, dir: SortDirection = \"asc\") =>\n commit((p) => {\n // A plain (single) sort RESETS any multi-sort chain — otherwise the\n // chain keeps superseding it and the click appears dead.\n writeSortLevels(p, [], ns);\n if (key) {\n p.set(ns + PARAM_SORT_BY, key);\n p.set(ns + PARAM_SORT_DIR, dir);\n } else {\n if (defaults.sortBy) p.set(ns + PARAM_SORT_BY, \"\");\n else p.delete(ns + PARAM_SORT_BY);\n p.delete(ns + PARAM_SORT_DIR);\n }\n resetPage(p);\n }),\n [commit, defaults.sortBy, ns, resetPage]\n );\n\n const setGroupBy = useCallback(\n (key: string | undefined) =>\n commit((p) => {\n if (key) p.set(ns + PARAM_GROUP_BY, key);\n else if (defaults.groupBy) p.set(ns + PARAM_GROUP_BY, \"\");\n else p.delete(ns + PARAM_GROUP_BY);\n resetPage(p);\n }),\n [commit, defaults.groupBy, ns, resetPage]\n );\n\n const toggleSortLevel = useCallback(\n (key: string) =>\n commit((p) => {\n const levels = [...readSortLevels(p, ns)];\n const index = levels.findIndex((l) => l.key === key);\n if (index === -1) levels.push({ key, dir: \"asc\" });\n else if (levels[index]!.dir === \"asc\")\n levels[index] = { key, dir: \"desc\" };\n else levels.splice(index, 1);\n writeSortLevels(p, levels, ns);\n // The chain supersedes the single-sort params while present.\n if (levels.length > 0) {\n p.delete(ns + PARAM_SORT_BY);\n p.delete(ns + PARAM_SORT_DIR);\n }\n resetPage(p);\n }),\n [commit, ns, resetPage]\n );\n\n const setExtra = useCallback(\n (key: string, value: FilterValue) =>\n commit((p) => {\n writeExtraWithDefaults(p, { ...readEffectiveExtra(p), [key]: value });\n resetPage(p);\n }),\n [commit, readEffectiveExtra, resetPage, writeExtraWithDefaults]\n );\n\n const setExtras = useCallback(\n (updates: ExtraFilters) =>\n commit((p) => {\n writeExtraWithDefaults(p, { ...readEffectiveExtra(p), ...updates });\n resetPage(p);\n }),\n [commit, readEffectiveExtra, resetPage, writeExtraWithDefaults]\n );\n\n const setFilterTree = useCallback(\n (tree: QueryFilterGroup | undefined) =>\n commit((p) => {\n writeFilterTreeParam(p, tree, ns);\n resetPage(p);\n }),\n [commit, ns, resetPage]\n );\n\n const clearExtras = useCallback(\n () =>\n commit((p) => {\n writeExtraWithDefaults(p, {});\n resetPage(p);\n }),\n [commit, resetPage, writeExtraWithDefaults]\n );\n\n const clearAll = useCallback(\n () =>\n commit((p) => {\n if (defaults.search) p.set(ns + PARAM_SEARCH, \"\");\n else p.delete(ns + PARAM_SEARCH);\n // The multi-sort chain supersedes the single-sort params, so \"clear\n // all\" must drop it too or the rows visibly stay sorted.\n writeSortLevels(p, [], ns);\n if (defaults.sortBy) p.set(ns + PARAM_SORT_BY, \"\");\n else p.delete(ns + PARAM_SORT_BY);\n p.delete(ns + PARAM_SORT_DIR);\n if (defaults.groupBy) p.set(ns + PARAM_GROUP_BY, \"\");\n else p.delete(ns + PARAM_GROUP_BY);\n resetPage(p);\n writeExtraWithDefaults(p, {});\n writeFilterTreeParam(p, undefined, ns);\n }),\n [\n commit,\n defaults.search,\n defaults.sortBy,\n defaults.groupBy,\n ns,\n resetPage,\n writeExtraWithDefaults,\n ]\n );\n\n return {\n page,\n limit,\n defaultLimit: initialLimit,\n search: searchTerm,\n sortBy,\n sortDir,\n groupBy,\n extra,\n filterTree,\n setPage,\n setLimit,\n setSort,\n setGroupBy,\n sortLevels,\n toggleSortLevel,\n setSearch,\n setExtra,\n setExtras,\n setFilterTree,\n clearExtras,\n clearAll,\n };\n}\n","import { useEffect, useMemo, useRef, useState } from \"react\";\n\nimport type { FacetMap } from \"../filters/facets\";\nimport { useEventCallback } from \"../hooks/useEventCallback\";\nimport { resolvePaginationMode, useIsMobile } from \"../hooks/useIsMobile\";\nimport type { SortLevel } from \"../sort/compare\";\nimport type { ExtraFilters, PaginationMode, SortDirection } from \"../types\";\nimport {\n useTableUrlState,\n type UseTableUrlStateOptions,\n} from \"../url/useTableUrlState\";\nimport { devWarn } from \"../utils/devWarn\";\nimport { stableKey } from \"../utils/stableKey\";\nimport {\n applyQuerySupport,\n type QueryExtensions,\n type QuerySupport,\n} from \"./queryContract\";\nimport type { TableSource } from \"./TableSource\";\n\n/**\n * One consolidated snapshot of everything a server query needs.\n *\n * The fields below the baseline come from {@link QueryExtensions} and are all\n * optional: a source receives one only after declaring it can answer it\n * (`supports`), so an endpoint written before a capability existed keeps\n * receiving exactly the query it was written against.\n */\nexport interface TableQuery extends QueryExtensions {\n /** 1-based page. */\n page: number;\n /** Page size. */\n limit: number;\n /** Committed (debounced) search term. */\n search: string;\n /** Active sort column key, if any. */\n sortBy: string | undefined;\n /** Active sort direction, if any. */\n sortDir: SortDirection | undefined;\n /** The multi-sort chain (empty unless multi-sort is in use). */\n sortLevels: readonly SortLevel[];\n /** The active filter values. */\n filters: ExtraFilters;\n}\n\n/** Options for {@link useServerData}. */\nexport interface UseServerDataOptions extends Pick<\n UseTableUrlStateOptions,\n | \"urlAdapter\"\n | \"urlSync\"\n | \"defaults\"\n | \"numberExtraKeys\"\n | \"arrayExtraKeys\"\n | \"urlKey\"\n> {\n /** The current page of rows, exactly as the server returned them. */\n rows: readonly TRow[];\n /** Total row count across all pages (drives the pager). */\n total: number;\n /**\n * Cursor pagination: the token the last response returned for the page\n * after the one on screen, or `null` when that was the last page.\n *\n * Only read when the source declares `supports.cursor`. With it, position\n * comes from the token rather than an offset, so rows that shift while the\n * user reads never duplicate or skip an entry — the failure mode\n * offset-based paging cannot avoid.\n *\n * A cursor is opaque, so the table only ever hands back one the server\n * gave it. That makes \"next\" always possible, \"back\" possible for pages\n * already visited, and a jump to an arbitrary unvisited page impossible —\n * the honest shape of cursor pagination, not a limitation to work around.\n */\n nextCursor?: string | null;\n /** Whether a request is currently in flight. */\n loading?: boolean;\n /** Forwarded error to display. */\n error?: Error | null;\n /** Pagination mode. Defaults to `\"auto\"` (mobile → infinite). */\n paginationMode?: PaginationMode;\n /** Force the resolved mobile state instead of a media query (test/SSR seam). */\n forceMobile?: boolean;\n /**\n * What this endpoint can answer beyond the baseline query. Declare a\n * capability and the matching field starts arriving in `onQueryChange`;\n * leave it out and the field is never sent, with a development warning if\n * the UI wanted it. See {@link QuerySupport}.\n */\n supports?: QuerySupport;\n /**\n * The tree nodes the reader has open, when the hierarchy lives on the server.\n * Sent as `query.expandedIds` only if the source declares\n * `supports: { tree: true }`, so the response can carry the children of every\n * open branch alongside the page. Hold the same array in the table's\n * `expandedIds` and one piece of state drives both.\n */\n expandedIds?: readonly string[];\n /**\n * Filter keys to ask the server for distinct-value counts. Sent as\n * `query.facets` only when `supports.facets` is set.\n */\n facetKeys?: readonly string[];\n /**\n * Distinct-value counts from the last fetch. Surfaces on the source\n * so a checklist can render without holding the full result set.\n */\n facets?: FacetMap;\n /**\n * Fired with the consolidated {@link TableQuery} whenever it changes —\n * including once on mount with the URL-restored values. The previous\n * call's `signal` is aborted when a newer query supersedes it; forward it\n * to `fetch` and out-of-order responses die at the source.\n */\n onQueryChange?: (\n query: TableQuery,\n info: { signal: AbortSignal }\n ) => void | Promise;\n}\n\n/**\n * The hand-rolled-fetch server tier: the table owns the query state (URL,\n * widgets, chips, debounce) and emits ONE consolidated event per real\n * change; the caller's only job is to run the request and hand back\n * `rows` + `total`. No query library required — and the full\n * `useQuerySource` tier remains for callers who want one.\n *\n * Implements the shared source contract: `isLoading` covers the first\n * load only, `isFetching` any in-flight request, and in infinite mode\n * `fetchNextPage` APPENDS the next page's rows to those on screen\n * (accumulating across `onQueryChange` round-trips) instead of replacing\n * them.\n *\n * @typeParam TRow - The row type.\n */\nexport function useServerData(\n options: UseServerDataOptions\n): TableSource {\n const {\n rows,\n total,\n nextCursor = null,\n loading = false,\n error = null,\n paginationMode = \"auto\",\n forceMobile,\n supports,\n expandedIds,\n facetKeys,\n facets,\n onQueryChange,\n ...urlOptions\n } = options;\n const mediaMobile = useIsMobile();\n const isMobile = forceMobile ?? mediaMobile;\n const resolvedMode = resolvePaginationMode(paginationMode, isMobile);\n const paged = resolvedMode === \"paged\";\n\n const state = useTableUrlState(urlOptions);\n const { page, limit, search, sortBy, sortDir, groupBy, sortLevels, extra } =\n state;\n\n // Cursor mode keeps every token the server has handed out, indexed by the\n // page it opens: `cursors[0]` is always `undefined` (page 1 needs no token)\n // and `cursors[n]` is the token for page n+1. Keeping the trail rather than\n // just the latest token is what lets the user page back through what they\n // have already seen, which a single \"next cursor\" cannot do.\n const cursorMode = supports?.cursor === true;\n const [cursors, setCursors] = useState([\n undefined,\n ]);\n const cursor = cursorMode ? cursors[page - 1] : undefined;\n\n const query = useMemo(\n () => ({\n page,\n limit,\n search,\n sortBy,\n sortDir,\n sortLevels,\n filters: extra,\n // Everything past the baseline is gated on what the source declared —\n // an undeclared capability is dropped here, never sent and ignored.\n ...applyQuerySupport(\n {\n groupBy: groupBy ? [groupBy] : undefined,\n cursor,\n expandedIds,\n filterTree: state.filterTree,\n facets: facetKeys,\n },\n supports\n ),\n }),\n [\n page,\n limit,\n search,\n sortBy,\n sortDir,\n sortLevels,\n extra,\n groupBy,\n cursor,\n supports,\n expandedIds,\n state.filterTree,\n facetKeys,\n ]\n );\n // Value-keyed, so re-renders and StrictMode double-mounts never re-fire\n // an identical query; `refetch` bumps the generation to force one.\n const queryKey = stableKey(query);\n const [generation, setGeneration] = useState(0);\n\n const controllerRef = useRef(null);\n\n // Emits the LATEST query / handler when the value-keyed query changes,\n // without re-subscribing on every render.\n const emitQuery = useEventCallback(() => {\n if (!onQueryChange) return undefined;\n controllerRef.current?.abort();\n const controller = new AbortController();\n controllerRef.current = controller;\n void onQueryChange(query, { signal: controller.signal });\n // Abort the in-flight request when the table unmounts.\n return () => controller.abort();\n });\n\n useEffect(() => emitQuery(), [queryKey, generation, emitQuery]);\n\n // `isLoading` covers the FIRST load only — TanStack's reference\n // semantics: fetching with no data yet. Once rows have ever been present\n // or one load has completed (loading transitions true → false), later\n // refreshes never re-raise it — even a refresh that empties `rows`.\n // Latched in an idempotent effect body so StrictMode's simulated remount\n // cannot mark it early.\n const rowsPresent = rows.length > 0;\n const sawLoadingRef = useRef(false);\n const firstLoadDoneRef = useRef(false);\n useEffect(() => {\n if (rowsPresent) firstLoadDoneRef.current = true;\n if (loading) sawLoadingRef.current = true;\n else if (sawLoadingRef.current) firstLoadDoneRef.current = true;\n }, [loading, rowsPresent]);\n const isLoading = loading && !rowsPresent && !firstLoadDoneRef.current;\n\n // Clamp out-of-range pages (hand-edited / stale shared links) once the\n // total is known and nothing is in flight — mirrors useQuerySource, so a\n // ?page=999 deep link self-heals to the last real page (and the URL is\n // rewritten) instead of showing an empty state the pager disagrees with.\n const { setPage } = state;\n useEffect(() => {\n // Cursor mode has no offset arithmetic to clamp against — a page is\n // reachable only if its token is already in hand, which the trail below\n // enforces directly.\n if (cursorMode || loading || total <= 0) return;\n const lastPage = Math.max(1, Math.ceil(total / Math.max(limit, 1)));\n if (page > lastPage) setPage(lastPage);\n }, [cursorMode, loading, total, limit, page, setPage]);\n\n // Record the token for the page after the one on screen, so \"next\" has\n // something to send and a later \"back\" can retrace the trail.\n useEffect(() => {\n if (!cursorMode || loading || nextCursor === null) return;\n setCursors((prev) => {\n if (prev[page] === nextCursor) return prev;\n const next = prev.slice();\n next[page] = nextCursor;\n return next;\n });\n }, [cursorMode, loading, nextCursor, page]);\n\n // Infinite-append accumulation: `fetchNextPage` stashes the rows already\n // on screen (plus the CURRENT `rows` prop identity) and advances the\n // page; the stashed rows alone stay on screen until the caller hands\n // back a NEW `rows` array for the advanced page, which is then appended.\n // Any base-query change (sort/filter/search/limit), a direct page jump,\n // or an error invalidates the stash, falling back to replacement.\n const baseKey = stableKey({\n limit,\n search,\n sortBy,\n sortDir,\n sortLevels,\n filters: extra,\n });\n const [stash, setStash] = useState<{\n key: string;\n page: number;\n rows: readonly TRow[];\n prevProp: readonly TRow[];\n } | null>(null);\n const appending =\n stash !== null && stash.key === baseKey && stash.page === page;\n // The advanced page's response hasn't landed while the caller still\n // passes the identical `rows` array the append started from.\n const appendPending = appending && rows === stash.prevProp;\n useEffect(() => {\n // Memory hygiene + failure recovery: a stash for a superseded base\n // query can never apply, and an errored append stops accumulating.\n if (stash !== null && (stash.key !== baseKey || error !== null)) {\n setStash(null);\n }\n }, [stash, baseKey, error]);\n\n // A new sort, filter, search or page size makes every token the server\n // issued meaningless — they describe a position in a result set that no\n // longer exists. Drop the trail and start again from page 1.\n const cursorBaseRef = useRef(baseKey);\n useEffect(() => {\n if (!cursorMode || cursorBaseRef.current === baseKey) return;\n cursorBaseRef.current = baseKey;\n setCursors([undefined]);\n setPage(1);\n }, [cursorMode, baseKey, setPage]);\n\n const displayRows = useMemo(() => {\n if (!appending) return rows;\n return appendPending ? stash.rows : [...stash.rows, ...rows];\n }, [appending, appendPending, stash, rows]);\n\n // Offset mode knows the end from the count; cursor mode only knows there\n // is more because the server said so by returning another token.\n const moreToLoad = cursorMode\n ? cursors[page] !== undefined\n : page * limit < total;\n const hasNextPage = !paged && moreToLoad;\n // Without a token a page cannot be requested at all, so in cursor mode\n // navigation is limited to pages already visited plus the next one. A pager\n // click beyond that is ignored rather than silently re-serving page 1,\n // which is what sending an absent cursor would do.\n const setPageSafely = useEventCallback((next: number) => {\n if (cursorMode && next > cursors.length) return;\n setPage(next);\n });\n\n const fetchNextPage = useEventCallback(() => {\n if (paged || loading || appendPending || !hasNextPage) return;\n setStash({\n key: baseKey,\n page: page + 1,\n rows: displayRows,\n prevProp: rows,\n });\n setPage(page + 1);\n });\n\n return {\n rows: displayRows,\n total,\n page,\n limit,\n defaultLimit: state.defaultLimit,\n search,\n sortBy,\n sortDir,\n groupBy,\n extra,\n facets,\n filterTree: state.filterTree,\n isLoading,\n isFetching: loading,\n isFetchingNextPage: appendPending,\n hasNextPage,\n error,\n paginationMode: resolvedMode,\n setPage: setPageSafely,\n setLimit: state.setLimit,\n setSort: state.setSort,\n setGroupBy: state.setGroupBy,\n sortLevels: state.sortLevels,\n toggleSortLevel: state.toggleSortLevel,\n setSearch: state.setSearch,\n setExtra: state.setExtra,\n setExtras: state.setExtras,\n setFilterTree: state.setFilterTree,\n clearExtras: state.clearExtras,\n clearAll: state.clearAll,\n fetchNextPage,\n refetch: () => {\n // Re-emitting the query IS this tier's fetch mechanism — the caller\n // runs the request. Without a handler there is nothing to re-run.\n if (!onQueryChange) {\n devWarn(\n \"refetch() has nothing to re-run without an `onQueryChange` handler.\"\n );\n return;\n }\n setGeneration((g) => g + 1);\n },\n };\n}\n","import type { ReactNode } from \"react\";\n\nimport type { ExtraEntry } from \"../rows/extraRows\";\nimport type { ColumnDef } from \"../types\";\nimport { getPath } from \"../utils/path\";\n\n/**\n * One visual row in a single-level grouped body: a group header, or a leaf\n * data row belonging to a group. Adapters switch on `kind`.\n */\nexport type GroupedFlatEntry =\n | {\n kind: \"group\";\n /** Stable id: `group:${keys}:${valueKeys}`, unique down the whole tree. */\n key: string;\n /** Raw group value (from sortValue / path). */\n value: unknown;\n /** Display label for the header (stringified value, or \"(blank)\"). */\n label: string;\n /**\n * Depth from zero. With one grouping key every header is level 0; with\n * `[\"team\", \"status\"]` the status headers are level 1, and adapters\n * indent by it.\n */\n level: number;\n /** Which column this level groups by. */\n groupBy: string;\n /** The value keys from the root down to here — the node's address. */\n path: readonly string[];\n /**\n * EVERY leaf beneath this header, not just its direct children: a\n * parent's count, its aggregates and its selection state all describe\n * the whole subtree, which is what a person reading a nested group\n * expects a number beside it to mean.\n */\n leafRows: readonly TRow[];\n leafIds: readonly string[];\n /**\n * How many leaves the SERVER says are in this group, when the grouping\n * was computed there. A server-grouped table holds a page of a group of\n * 4,000 and must still say 4,000; local grouping leaves this unset and\n * the count comes from `leafIds`.\n */\n serverCount?: number;\n /** Present when the host passed `groupAggregates`. */\n aggregateCells?: Partial>;\n collapsed: boolean;\n }\n | {\n /**\n * The closing row of a group, carrying the same aggregates its header\n * carries. Emitted only when the host asks for footers, and never for a\n * collapsed group — there is nothing between a closed header and its\n * footer to total.\n */\n kind: \"groupFooter\";\n /** Stable id: the group's key with a `:footer` suffix. */\n key: string;\n /** The group this closes. */\n groupKey: string;\n /** Depth of the group it closes. */\n level: number;\n /** Which column that group is grouped by. */\n groupBy: string;\n /** The group's display label, for a \"Core total\" caption. */\n label: string;\n leafRows: readonly TRow[];\n leafIds: readonly string[];\n aggregateCells?: Partial>;\n }\n | {\n /**\n * \"There are more\" — a row offering the rest of a page of groups, or the\n * rest of a group's leaves. Emitted only when the host set a page size,\n * and only while something is still hidden.\n */\n kind: \"groupMore\";\n /** Stable id. */\n key: string;\n /** Which group's leaves are being paged, or absent for top-level groups. */\n groupKey?: string;\n /** Depth the row sits at, so it indents with what it belongs to. */\n level: number;\n /** Whether this offers more groups or more rows inside one. */\n scope: \"groups\" | \"rows\";\n /** How many are still hidden. */\n remaining: number;\n /**\n * Empty, and present so every group-shaped entry has the same fields:\n * one adapter component renders headers, footers and this row, and a\n * missing field there is a conditional in eight kits.\n */\n leafRows: readonly TRow[];\n leafIds: readonly string[];\n label: string;\n }\n | {\n kind: \"row\";\n key: string;\n row: TRow;\n /** Index among leaves in the flat model (stable for selection chrome). */\n index: number;\n groupKey: string;\n }\n | ExtraEntry;\n\n/**\n * One group, as sorting and filtering see it — before it becomes a row.\n *\n * The leaves are here because every aggregate is a function of them: sorting\n * groups \"by their total\" is `sum(b.leafRows) - sum(a.leafRows)`, computed from\n * the same rows the aggregate mapper reads. Comparing rendered aggregate cells\n * instead would mean comparing ReactNodes, which is not an ordering.\n */\nexport interface GroupNode {\n /** The raw bucket value. */\n value: unknown;\n /** Its display label. */\n label: string;\n /** Depth from zero. */\n level: number;\n /** Which column this level groups by. */\n groupBy: string;\n /** Every leaf beneath it, including through nested levels. */\n leafRows: readonly TRow[];\n}\n\n/** How to order groups within their parent. */\nexport type GroupSort =\n | \"label\"\n | \"label-desc\"\n | \"count\"\n | \"count-desc\"\n | ((a: GroupNode, b: GroupNode) => number);\n\n/** Same mapper signature as `summaryRow` — one API for page footer + groups. */\nexport type GroupAggregatesFn = (\n rows: readonly TRow[]\n) => Partial>;\n\nexport interface BuildGroupedFlatModelOptions {\n /** Leaf rows to partition (frontend: prefer `allFilteredRows`). */\n rows: readonly TRow[];\n /**\n * Column key to group by, or an ordered list for nested grouping —\n * `[\"team\", \"status\"]` puts each status inside its team.\n */\n groupBy: string | readonly string[];\n columns: readonly ColumnDef[];\n getRowId: (row: TRow) => string;\n /** Collapsed group keys (from {@link useGroupCollapse}). */\n collapsedGroupIds: ReadonlySet;\n /** Optional per-group cells — same shape as `summaryRow`. */\n aggregates?: GroupAggregatesFn;\n /** Override blank-group label (default `\"(blank)\"`). */\n blankLabel?: string;\n /**\n * Close every group with a footer row carrying its aggregates. Off by\n * default, and pointless without `aggregates` — a footer with nothing to\n * total is a blank row.\n */\n footers?: boolean;\n /**\n * Order groups within their parent. Without it they keep first-seen order,\n * which is the order the source's own sort produced.\n */\n sort?: GroupSort;\n /** Keep only the groups this answers true for, at every level. */\n filter?: (group: GroupNode) => boolean;\n /**\n * Show at most this many top-level groups at a time. A table grouped by\n * customer can have ten thousand groups, and rendering all of them to show\n * the first screen is the same mistake as rendering ten thousand rows.\n */\n groupPageSize?: number;\n /** Show at most this many leaves inside each group. */\n rowPageSize?: number;\n /** How many are currently revealed, from {@link GroupPaging}. */\n paging?: GroupPaging;\n}\n\n/** How much of a paged group model the reader has asked to see. */\nexport interface GroupPaging {\n /** Extra top-level groups revealed beyond the first page. */\n groups?: number;\n /** Extra leaves revealed per group key. */\n rows?: Readonly>;\n}\n\n/**\n * Resolve the value used to bucket a row for `groupBy`. Prefers the column's\n * `sortValue` (same primitive as client sort), then a path lookup on the\n * column key — never the JSX accessor.\n */\nexport function resolveGroupValue(\n row: TRow,\n groupBy: string,\n column: ColumnDef | undefined\n): unknown {\n if (column?.sortValue) return column.sortValue(row);\n const path = column?.key ?? groupBy;\n return getPath(row, path);\n}\n\n/**\n * Stable string key for a group bucket. Type-tagged so distinct values\n * never share a bucket across types — number `5` vs string `\"5\"`, boolean\n * `true` vs string `\"true\"`, a Date vs its own ISO string. Null-ish and\n * empty-string values deliberately share the one blank bucket (they all\n * render the same blank label; splitting them would show several\n * identical \"(blank)\" groups).\n */\nexport function groupValueKey(value: unknown): string {\n if (value == null || value === \"\") return \"\";\n if (typeof value === \"string\") return `s:${value}`;\n if (typeof value === \"number\" || typeof value === \"bigint\") {\n return `n:${String(value)}`;\n }\n if (typeof value === \"boolean\") return `b:${String(value)}`;\n if (value instanceof Date) return `d:${value.toISOString()}`;\n try {\n return `j:${JSON.stringify(value)}`;\n } catch {\n return `o:${Object.prototype.toString.call(value)}`;\n }\n}\n\nexport function formatGroupLabel(\n value: unknown,\n blankLabel = \"(blank)\"\n): string {\n if (value == null || value === \"\") return blankLabel;\n if (typeof value === \"string\") return value;\n if (typeof value === \"number\" || typeof value === \"boolean\") {\n return String(value);\n }\n if (value instanceof Date) return value.toISOString();\n try {\n return JSON.stringify(value);\n } catch {\n return Object.prototype.toString.call(value);\n }\n}\n\n/**\n * A group node's stable id.\n *\n * Both halves carry the whole path, so \"Core > blocked\" and \"Web > blocked\"\n * are different nodes — collapse one and the other stays open, which a key of\n * just the value could never express.\n *\n * @param keys - The grouping keys from the root down to this level.\n * @param valueKeys - The value keys down to this node.\n * @returns The id.\n */\nexport function makeGroupRowKey(\n keys: string | readonly string[],\n valueKeys: string | readonly string[]\n): string {\n const k = typeof keys === \"string\" ? keys : keys.join(\">\");\n const v = typeof valueKeys === \"string\" ? valueKeys : valueKeys.join(\">\");\n return `group:${k}:${v}`;\n}\n\n/**\n * One bucket in a grouped partition tree, before it becomes a rendered row.\n *\n * Incremental re-evaluation keeps this tree up to date and hands it to\n * {@link flattenGroupPartitions} so a patched row does not re-hash every\n * other row's group key.\n */\nexport interface GroupPartition {\n /** The raw bucket value. */\n value: unknown;\n /** {@link groupValueKey} of `value`. */\n valueKey: string;\n /** Every leaf beneath this node, in source (sorted) order. */\n rows: readonly TRow[];\n /** Nested buckets, when another grouping key remains. */\n children?: readonly GroupPartition[];\n}\n\n/**\n * The grouping keys {@link buildGroupedFlatModel} will actually use — blank\n * entries dropped, so `[\"\", \"team\"]` is just `\"team\"`.\n *\n * @param groupBy - A single key or an ordered list.\n * @returns The non-empty keys, outermost first.\n */\nexport function groupingKeys(groupBy: string | readonly string[]): string[] {\n return (typeof groupBy === \"string\" ? [groupBy] : groupBy).filter(\n (key) => key.length > 0\n );\n}\n\n/**\n * Partition rows into the nested bucket tree grouping walks.\n *\n * Order is first-seen at each level, which preserves whatever sort the\n * source already applied.\n *\n * @typeParam TRow - The row type.\n * @param rows - The rows to partition.\n * @param groupBy - Column key, or an ordered list for nested grouping.\n * @param columns - The columns, for each key's `sortValue`.\n * @returns The top-level buckets, or an empty list when there is no key.\n */\nexport function partitionGroupedRows(\n rows: readonly TRow[],\n groupBy: string | readonly string[],\n columns: readonly ColumnDef[]\n): GroupPartition[] {\n const keys = groupingKeys(groupBy);\n if (keys.length === 0) return [];\n return partitionLevel(rows, keys, 0, columns);\n}\n\nfunction partitionLevel(\n rows: readonly TRow[],\n keys: readonly string[],\n level: number,\n columns: readonly ColumnDef[]\n): GroupPartition[] {\n const { order, buckets } = bucketBy(rows, keys[level]!, columns);\n return order.map((valueKey) => {\n const bucket = buckets.get(valueKey)!;\n return {\n value: bucket.value,\n valueKey,\n rows: bucket.rows,\n children:\n level + 1 < keys.length\n ? partitionLevel(bucket.rows, keys, level + 1, columns)\n : undefined,\n };\n });\n}\n\n/**\n * Turn a partition tree into the flat model adapters render.\n *\n * This is the emit half of {@link buildGroupedFlatModel}: filtering, ordering,\n * paging, collapse, footers. Incremental grouping updates the tree, then\n * calls this instead of re-bucketing the world.\n *\n * @typeParam TRow - The row type.\n * @param partitions - The tree {@link partitionGroupedRows} (or an\n * incremental update) produced.\n * @param options - The same options as the full builder, minus `rows`.\n * @returns The entries, in render order.\n */\nexport function flattenGroupPartitions(\n partitions: readonly GroupPartition[],\n options: Omit, \"rows\">\n): GroupedFlatEntry[] {\n const keys = groupingKeys(options.groupBy);\n if (keys.length === 0 || partitions.length === 0) return [];\n\n const {\n getRowId,\n collapsedGroupIds,\n aggregates,\n blankLabel,\n footers = false,\n sort,\n filter,\n groupPageSize,\n rowPageSize,\n paging,\n } = options;\n const flat: GroupedFlatEntry[] = [];\n let leafIndex = 0;\n\n const walk = (\n levelPartitions: readonly GroupPartition[],\n level: number,\n path: readonly string[]\n ): void => {\n const key = keys[level]!;\n\n // Filtering and ordering happen on the whole level at once, before any of\n // it is emitted: a group dropped here takes its leaves with it, and one\n // moved here moves its whole subtree.\n const nodes = levelPartitions.flatMap((part) => {\n const node: GroupNode = {\n value: part.value,\n label: formatGroupLabel(part.value, blankLabel),\n level,\n groupBy: key,\n leafRows: part.rows,\n };\n return filter && !filter(node)\n ? []\n : [{ part, valueKey: part.valueKey, node }];\n });\n if (sort) nodes.sort((a, b) => compareGroups(a.node, b.node, sort));\n\n // Only the top level pages: a nested level is already inside a group the\n // reader chose to open, and hiding part of what they opened would be a\n // second \"more\" to hunt for.\n const groupLimit = pageLimit(\n nodes.length,\n level === 0 ? groupPageSize : undefined,\n paging?.groups\n );\n const shown = nodes.slice(0, groupLimit);\n const hiddenGroups = nodes.length - shown.length;\n\n for (const { part, valueKey, node } of shown) {\n const here = [...path, valueKey];\n const groupKey = makeGroupRowKey(keys.slice(0, level + 1), here);\n const collapsed = collapsedGroupIds.has(groupKey);\n const aggregateCells = aggregates?.(part.rows);\n const label = node.label;\n\n flat.push({\n kind: \"group\",\n key: groupKey,\n value: part.value,\n label,\n level,\n groupBy: key,\n path: here,\n leafRows: part.rows,\n leafIds: part.rows.map((row) => getRowId(row)),\n aggregateCells,\n collapsed,\n });\n if (collapsed) continue;\n\n if (level + 1 < keys.length) {\n walk(part.children ?? [], level + 1, here);\n } else {\n leafIndex = emitLeaves(flat, part.rows, {\n groupKey,\n level,\n getRowId,\n from: leafIndex,\n limit: pageLimit(\n part.rows.length,\n rowPageSize,\n paging?.rows?.[groupKey]\n ),\n });\n }\n\n // The footer closes the group AFTER everything inside it, including any\n // nested groups and their own footers — innermost totals first, exactly\n // as the indentation reads.\n if (footers) {\n flat.push({\n kind: \"groupFooter\",\n key: `${groupKey}:footer`,\n groupKey,\n level,\n groupBy: key,\n label,\n leafRows: part.rows,\n leafIds: part.rows.map((row) => getRowId(row)),\n aggregateCells,\n });\n }\n }\n\n if (hiddenGroups > 0) {\n flat.push(\n moreEntry(\"groups\", hiddenGroups, level, undefined, path.join(\">\"))\n );\n }\n };\n\n walk(partitions, 0, []);\n return flat;\n}\n\n/**\n * Partition leaf rows into the flat model adapters render: a group header,\n * then whatever sits under it — nested headers first when there is more than\n * one grouping key, then the leaves.\n *\n * Flat rather than nested on purpose: a windowing virtualizer can only measure\n * and slice a list, so the tree is expressed as depth on each entry instead of\n * as children. Group order follows first-seen value order within each parent,\n * which keeps the sort the source already applied.\n *\n * A collapsed header emits nothing beneath it — not its child headers and not\n * their leaves — so collapsing a top-level group hides the whole subtree in\n * one step.\n *\n * @typeParam TRow - The row type.\n * @param options - See {@link BuildGroupedFlatModelOptions}.\n * @returns The entries, in render order.\n */\nexport function buildGroupedFlatModel(\n options: BuildGroupedFlatModelOptions\n): GroupedFlatEntry[] {\n return flattenGroupPartitions(\n partitionGroupedRows(options.rows, options.groupBy, options.columns),\n options\n );\n}\n\n/**\n * Order two groups by a {@link GroupSort}.\n *\n * Labels compare with `localeCompare`, so \"Ärger\" lands where a reader expects\n * rather than after \"Zulu\"; counts compare numerically.\n *\n * @typeParam TRow - The row type.\n * @param a - The first group.\n * @param b - The second group.\n * @param sort - The ordering asked for.\n * @returns Negative, zero or positive, as a comparator does.\n */\nfunction compareGroups(\n a: GroupNode,\n b: GroupNode,\n sort: GroupSort\n): number {\n if (typeof sort === \"function\") return sort(a, b);\n if (sort === \"label\") return a.label.localeCompare(b.label);\n if (sort === \"label-desc\") return b.label.localeCompare(a.label);\n if (sort === \"count\") return a.leafRows.length - b.leafRows.length;\n return b.leafRows.length - a.leafRows.length;\n}\n\n/**\n * Emit one group's leaf rows, plus the offer for any it is holding back.\n *\n * @typeParam TRow - The row type.\n * @param flat - The entry list being built, appended to in place.\n * @param rows - The group's leaves.\n * @param options - Where they belong and how many to show.\n * @returns The next leaf index, so numbering continues across groups.\n */\nfunction emitLeaves(\n flat: GroupedFlatEntry[],\n rows: readonly TRow[],\n options: {\n groupKey: string;\n level: number;\n getRowId: (row: TRow) => string;\n from: number;\n limit: number;\n }\n): number {\n const { groupKey, level, getRowId, from, limit } = options;\n let index = from;\n for (const row of rows.slice(0, limit)) {\n flat.push({\n kind: \"row\",\n key: getRowId(row),\n row,\n index: index++,\n groupKey,\n });\n }\n const hidden = Math.max(0, rows.length - limit);\n if (hidden > 0) flat.push(moreEntry(\"rows\", hidden, level + 1, groupKey));\n return index;\n}\n\n/**\n * How many of something to show: everything without a page size, and one page\n * plus whatever has been revealed with one.\n *\n * @param total - How many there are.\n * @param pageSize - The page size, when the host set one.\n * @param revealed - How many extra have been asked for.\n * @returns The count to render.\n */\nfunction pageLimit(\n total: number,\n pageSize: number | undefined,\n revealed: number | undefined\n): number {\n if (!pageSize) return total;\n return Math.min(total, pageSize + (revealed ?? 0));\n}\n\n/**\n * Partition rows into ordered buckets for one grouping key.\n *\n * Order is first-seen, which preserves whatever sort the source applied — the\n * rows arrive sorted and the groups come out in the order those rows named\n * them.\n *\n * @typeParam TRow - The row type.\n * @param rows - The rows to partition.\n * @param key - The grouping key for this level.\n * @param columns - The columns, for the key's `sortValue`.\n * @returns The bucket keys in order, and the buckets themselves.\n */\nfunction bucketBy(\n rows: readonly TRow[],\n key: string,\n columns: readonly ColumnDef[]\n): {\n order: string[];\n buckets: Map;\n} {\n const column = columns.find((c) => c.key === key);\n const order: string[] = [];\n const buckets = new Map();\n for (const row of rows) {\n const value = resolveGroupValue(row, key, column);\n const valueKey = groupValueKey(value);\n let bucket = buckets.get(valueKey);\n if (!bucket) {\n bucket = { value, rows: [] };\n buckets.set(valueKey, bucket);\n order.push(valueKey);\n }\n bucket.rows.push(row);\n }\n return { order, buckets };\n}\n\n/**\n * The \"there are more\" row, for either scope.\n *\n * @typeParam TRow - The row type.\n * @param scope - Whether more groups or more rows are hidden.\n * @param remaining - How many.\n * @param level - The depth the row sits at.\n * @param groupKey - The group whose rows are hidden, for a `\"rows\"` offer.\n * @param pathKey - The path, so a nested level's offer has its own id.\n * @returns The entry.\n */\nfunction moreEntry(\n scope: \"groups\" | \"rows\",\n remaining: number,\n level: number,\n groupKey?: string,\n pathKey = \"\"\n): GroupedFlatEntry {\n return {\n kind: \"groupMore\",\n key: groupKey ? `${groupKey}:more` : `group-more:${level}:${pathKey}`,\n groupKey,\n level,\n scope,\n remaining,\n leafRows: [],\n leafIds: [],\n label: \"\",\n };\n}\n","/**\n * Incremental built-in aggregates — the same numbers {@link aggregate}\n * would compute, updated from the rows a patch touched instead of a full\n * walk of the set.\n *\n * Custom aggregators and a dirty min/max (the old extremum left the set)\n * fall back to a rescan of the rows the total describes. That is still\n * the group or the filtered set, not the unfiltered source.\n */\nimport type { ReactNode } from \"react\";\n\nimport {\n aggregate,\n type AggregateName,\n type AggregateOptions,\n type AggregateSpec,\n resolveAggregateValue,\n toAggregateNumber,\n} from \"../aggregate/aggregate\";\nimport type { ColumnDef, SortableValue } from \"../types\";\n\ninterface ColumnAcc {\n kind: AggregateName | \"custom\";\n sum: number;\n numericCount: number;\n presentCount: number;\n min: number | undefined;\n max: number | undefined;\n /** The old min or max left; `read` must rescan. */\n dirty: boolean;\n}\n\ninterface ColumnBinding {\n key: string;\n acc: ColumnAcc;\n}\n\n/**\n * Running totals for one {@link AggregateSpec} over a changing row set.\n *\n * @typeParam TRow - The row type.\n */\nexport interface IncrementalAggregate {\n spec: AggregateSpec;\n options: AggregateOptions;\n columns: ReadonlyMap>;\n bindings: ColumnBinding[];\n}\n\n/**\n * Start a running total from the rows already in the set.\n *\n * @typeParam TRow - The row type.\n * @param spec - The same declaration {@link aggregate} takes.\n * @param rows - The rows the total currently describes.\n * @param options - Column resolvers and an optional formatter.\n */\nexport function createIncrementalAggregate(\n spec: AggregateSpec,\n rows: readonly TRow[],\n options: AggregateOptions = {}\n): IncrementalAggregate {\n const columns = new Map(\n options.columns?.map((column) => [column.key, column])\n );\n const bindings: ColumnBinding[] = [];\n for (const [key, fn] of Object.entries(spec)) {\n if (!fn) continue;\n const kind = builtInName(fn);\n bindings.push({\n key,\n acc: {\n kind: kind ?? \"custom\",\n sum: 0,\n numericCount: 0,\n presentCount: 0,\n min: undefined,\n max: undefined,\n dirty: kind === undefined,\n },\n });\n }\n const state: IncrementalAggregate = {\n spec,\n options,\n columns,\n bindings,\n };\n for (const row of rows) addAggregateRow(state, row);\n return state;\n}\n\n/**\n * Fold one row into the running total.\n *\n * @typeParam TRow - The row type.\n * @param state - The running total.\n * @param row - The row that entered the set.\n */\nexport function addAggregateRow(\n state: IncrementalAggregate,\n row: TRow\n): void {\n for (const { key, acc } of state.bindings) {\n applyValue(acc, valueOf(state, row, key), 1);\n }\n}\n\n/**\n * Fold one row out of the running total.\n *\n * @typeParam TRow - The row type.\n * @param state - The running total.\n * @param row - The row that left the set.\n */\nexport function removeAggregateRow(\n state: IncrementalAggregate,\n row: TRow\n): void {\n for (const { key, acc } of state.bindings) {\n applyValue(acc, valueOf(state, row, key), -1);\n }\n}\n\n/**\n * Replace one row's contribution with another's.\n *\n * @typeParam TRow - The row type.\n * @param state - The running total.\n * @param prev - The row that left.\n * @param next - The row that entered.\n */\nexport function replaceAggregateRow(\n state: IncrementalAggregate,\n prev: TRow,\n next: TRow\n): void {\n removeAggregateRow(state, prev);\n addAggregateRow(state, next);\n}\n\n/**\n * Read the current cells. When a built-in is dirty or a custom aggregator\n * is in play, rescans `rows` so the answer still matches {@link aggregate}.\n *\n * @typeParam TRow - The row type.\n * @param state - The running total.\n * @param rows - The rows the total describes, for a rescan.\n */\nexport function readIncrementalAggregate(\n state: IncrementalAggregate,\n rows: readonly TRow[]\n): Partial> {\n if (state.bindings.some((binding) => binding.acc.kind === \"custom\")) {\n return aggregate(state.spec, state.options)(rows);\n }\n if (state.bindings.some((binding) => binding.acc.dirty)) {\n rescan(state, rows);\n }\n const out: Partial> = {};\n const format = state.options.format;\n for (const { key, acc } of state.bindings) {\n const result = cellOf(acc);\n out[key] = format ? format(result, key) : result;\n }\n return out;\n}\n\nfunction builtInName(fn: unknown): AggregateName | undefined {\n if (\n fn === \"sum\" ||\n fn === \"avg\" ||\n fn === \"count\" ||\n fn === \"min\" ||\n fn === \"max\"\n ) {\n return fn;\n }\n return undefined;\n}\n\nfunction valueOf(\n state: IncrementalAggregate,\n row: TRow,\n key: string\n): SortableValue {\n return resolveAggregateValue(row, key, state.columns.get(key));\n}\n\nfunction applyValue(acc: ColumnAcc, value: SortableValue, sign: 1 | -1): void {\n if (acc.kind === \"custom\") {\n acc.dirty = true;\n return;\n }\n if (value === undefined || value === null) return;\n acc.presentCount += sign;\n const n = toAggregateNumber(value);\n if (n === undefined) return;\n acc.sum += sign * n;\n acc.numericCount += sign;\n if (sign === 1) {\n acc.min = acc.min === undefined ? n : Math.min(acc.min, n);\n acc.max = acc.max === undefined ? n : Math.max(acc.max, n);\n return;\n }\n if (acc.numericCount <= 0) {\n acc.sum = 0;\n acc.numericCount = 0;\n acc.min = undefined;\n acc.max = undefined;\n acc.dirty = false;\n return;\n }\n if (n === acc.min || n === acc.max) acc.dirty = true;\n}\n\nfunction rescan(\n state: IncrementalAggregate,\n rows: readonly TRow[]\n): void {\n for (const { acc } of state.bindings) {\n acc.sum = 0;\n acc.numericCount = 0;\n acc.presentCount = 0;\n acc.min = undefined;\n acc.max = undefined;\n acc.dirty = false;\n }\n for (const row of rows) addAggregateRow(state, row);\n}\n\nfunction cellOf(acc: ColumnAcc): number | undefined {\n if (acc.kind === \"sum\") return acc.sum;\n if (acc.kind === \"count\") return acc.presentCount;\n if (acc.kind === \"avg\") {\n return acc.numericCount ? acc.sum / acc.numericCount : undefined;\n }\n if (acc.kind === \"min\") return acc.min;\n return acc.max;\n}\n","/**\n * Incremental grouping — keep the partition tree {@link buildGroupedFlatModel}\n * walks, and only re-bucket the rows a patch touched.\n *\n * Flattening still goes through {@link flattenGroupPartitions} so collapse,\n * paging, group sort and group filter stay one implementation.\n */\nimport {\n groupingKeys,\n type GroupPartition,\n groupValueKey,\n resolveGroupValue,\n} from \"../grouping/groupRows\";\nimport type { ColumnDef } from \"../types\";\n\n/** One mutable bucket; `childMap` is the same nodes as `children`. */\nexport interface MutablePartition {\n value: unknown;\n valueKey: string;\n rows: TRow[];\n children?: MutablePartition[];\n childMap: Map>;\n}\n\n/** The grouping keys and the live tree incremental updates mutate. */\nexport interface IncrementalGroupTree {\n keys: readonly string[];\n columns: readonly ColumnDef[];\n roots: MutablePartition[];\n rootMap: Map>;\n}\n\n/**\n * The value-key path a row takes through the grouping keys.\n *\n * @typeParam TRow - The row type.\n * @param row - The row to place.\n * @param keys - Grouping keys, outermost first.\n * @param columns - Columns, for each key's `sortValue`.\n */\nexport function rowGroupPath(\n row: TRow,\n keys: readonly string[],\n columns: readonly ColumnDef[]\n): { value: unknown; valueKey: string }[] {\n return keys.map((key) => {\n const column = columns.find((item) => item.key === key);\n const value = resolveGroupValue(row, key, column);\n return { value, valueKey: groupValueKey(value) };\n });\n}\n\n/**\n * Build a live tree from a frozen partition list (the full-eval path).\n *\n * @typeParam TRow - The row type.\n * @param partitions - The buckets {@link partitionGroupedRows} produced.\n * @param groupBy - The grouping keys those buckets used.\n * @param columns - Columns, kept so later patches resolve the same way.\n */\nexport function incrementalGroupTree(\n partitions: readonly GroupPartition[],\n groupBy: string | readonly string[],\n columns: readonly ColumnDef[]\n): IncrementalGroupTree {\n const roots = partitions.map(toMutable);\n return {\n keys: groupingKeys(groupBy),\n columns,\n roots,\n rootMap: mapOf(roots),\n };\n}\n\n/**\n * A readonly view of the live tree for {@link flattenGroupPartitions}.\n *\n * @typeParam TRow - The row type.\n * @param tree - The live tree.\n */\nexport function snapshotPartitions(\n tree: IncrementalGroupTree\n): GroupPartition[] {\n return tree.roots.map(toFrozen);\n}\n\n/**\n * Insert a row along its group path, creating buckets that do not exist\n * yet. Sibling order is first-seen: a new group lands where its first\n * leaf sits in the sorted list.\n *\n * @typeParam TRow - The row type.\n * @param tree - The live tree.\n * @param row - The row that entered the sorted set.\n * @param path - {@link rowGroupPath} of `row`.\n * @param sortedIndex - Current index of each id in the sorted list.\n * @param getRowId - How a row's id is derived.\n */\nexport function addGroupedRow(\n tree: IncrementalGroupTree,\n row: TRow,\n path: readonly { value: unknown; valueKey: string }[],\n sortedIndex: ReadonlyMap,\n getRowId: (row: TRow) => string\n): void {\n let siblings = tree.roots;\n let siblingMap = tree.rootMap;\n for (const step of path) {\n let node = siblingMap.get(step.valueKey);\n if (!node) {\n node = {\n value: step.value,\n valueKey: step.valueKey,\n rows: [],\n children: [],\n childMap: new Map(),\n };\n const at = firstSeenInsertAt(siblings, row, sortedIndex, getRowId);\n siblings.splice(at, 0, node);\n siblingMap.set(step.valueKey, node);\n }\n insertLeaf(node.rows, row, sortedIndex, getRowId);\n siblings = node.children ?? (node.children = []);\n siblingMap = node.childMap;\n }\n rebalance(tree, path, sortedIndex, getRowId);\n}\n\n/**\n * Remove a row along a path it used to sit on. Empty buckets drop, so a\n * group that just lost its last leaf disappears the way a full rebuild\n * would drop it.\n *\n * @typeParam TRow - The row type.\n * @param tree - The live tree.\n * @param id - The row id to drop.\n * @param path - The path the row was on.\n * @param sortedIndex - Current sorted indices, so remaining groups keep\n * first-seen order.\n * @param getRowId - How a row's id is derived.\n */\nexport function removeGroupedRow(\n tree: IncrementalGroupTree,\n id: string,\n path: readonly { valueKey: string }[],\n sortedIndex: ReadonlyMap,\n getRowId: (row: TRow) => string\n): void {\n const chain: {\n node: MutablePartition;\n siblings: MutablePartition[];\n siblingMap: Map>;\n }[] = [];\n let siblings = tree.roots;\n let siblingMap = tree.rootMap;\n for (const step of path) {\n const node = siblingMap.get(step.valueKey);\n if (!node) return;\n chain.push({ node, siblings, siblingMap });\n siblings = node.children ?? [];\n siblingMap = node.childMap;\n }\n for (let i = chain.length - 1; i >= 0; i--) {\n const { node, siblings: list, siblingMap: map } = chain[i]!;\n removeLeaf(node.rows, id, getRowId);\n if (node.rows.length > 0) continue;\n const at = list.indexOf(node);\n if (at !== -1) list.splice(at, 1);\n map.delete(node.valueKey);\n }\n rebalance(tree, path, sortedIndex, getRowId);\n}\n\n/**\n * Move a row from one path to another, or reposition it inside the same\n * path when only its sort index changed.\n *\n * @typeParam TRow - The row type.\n * @param tree - The live tree.\n * @param prev - The row that left.\n * @param next - The row that entered.\n * @param prevPath - Path of `prev`.\n * @param nextPath - Path of `next`.\n * @param sortedIndex - Current sorted indices.\n * @param getRowId - How a row's id is derived.\n */\nexport function moveGroupedRow(\n tree: IncrementalGroupTree,\n prev: TRow,\n next: TRow,\n prevPath: readonly { value: unknown; valueKey: string }[],\n nextPath: readonly { value: unknown; valueKey: string }[],\n sortedIndex: ReadonlyMap,\n getRowId: (row: TRow) => string\n): void {\n const samePath =\n prevPath.length === nextPath.length &&\n prevPath.every((step, i) => step.valueKey === nextPath[i]?.valueKey);\n if (samePath) {\n replaceAlongPath(tree, next, nextPath, sortedIndex, getRowId);\n return;\n }\n removeGroupedRow(tree, getRowId(prev), prevPath, sortedIndex, getRowId);\n addGroupedRow(tree, next, nextPath, sortedIndex, getRowId);\n}\n\nfunction replaceAlongPath(\n tree: IncrementalGroupTree,\n row: TRow,\n path: readonly { valueKey: string }[],\n sortedIndex: ReadonlyMap,\n getRowId: (row: TRow) => string\n): void {\n let siblingMap = tree.rootMap;\n const id = getRowId(row);\n for (const step of path) {\n const node = siblingMap.get(step.valueKey);\n if (!node) return;\n removeLeaf(node.rows, id, getRowId);\n insertLeaf(node.rows, row, sortedIndex, getRowId);\n siblingMap = node.childMap;\n }\n rebalance(tree, path, sortedIndex, getRowId);\n}\n\nfunction rebalance(\n tree: IncrementalGroupTree,\n path: readonly { valueKey: string }[],\n sortedIndex: ReadonlyMap,\n getRowId: (row: TRow) => string\n): void {\n sortSiblings(tree.roots, sortedIndex, getRowId);\n let map = tree.rootMap;\n for (const step of path) {\n const node = map.get(step.valueKey);\n if (!node?.children) break;\n sortSiblings(node.children, sortedIndex, getRowId);\n map = node.childMap;\n }\n}\n\nfunction sortSiblings(\n siblings: MutablePartition[],\n sortedIndex: ReadonlyMap,\n getRowId: (row: TRow) => string\n): void {\n siblings.sort((a, b) => {\n return (\n firstLeafIndex(a, sortedIndex, getRowId) -\n firstLeafIndex(b, sortedIndex, getRowId)\n );\n });\n}\n\nfunction firstLeafIndex(\n node: MutablePartition,\n sortedIndex: ReadonlyMap,\n getRowId: (row: TRow) => string\n): number {\n const first = node.rows[0];\n if (!first) return Number.POSITIVE_INFINITY;\n return sortedIndex.get(getRowId(first)) ?? Number.POSITIVE_INFINITY;\n}\n\nfunction firstSeenInsertAt(\n siblings: readonly MutablePartition[],\n row: TRow,\n sortedIndex: ReadonlyMap,\n getRowId: (row: TRow) => string\n): number {\n const incoming = sortedIndex.get(getRowId(row)) ?? Number.POSITIVE_INFINITY;\n const at = siblings.findIndex((sibling) => {\n const first = sibling.rows[0];\n if (!first) return true;\n return (\n (sortedIndex.get(getRowId(first)) ?? Number.POSITIVE_INFINITY) > incoming\n );\n });\n return at === -1 ? siblings.length : at;\n}\n\nfunction insertLeaf(\n rows: TRow[],\n row: TRow,\n sortedIndex: ReadonlyMap,\n getRowId: (row: TRow) => string\n): void {\n const incoming = sortedIndex.get(getRowId(row)) ?? Number.POSITIVE_INFINITY;\n const at = rows.findIndex((existing) => {\n return (\n (sortedIndex.get(getRowId(existing)) ?? Number.POSITIVE_INFINITY) >\n incoming\n );\n });\n rows.splice(at === -1 ? rows.length : at, 0, row);\n}\n\nfunction removeLeaf(\n rows: TRow[],\n id: string,\n getRowId: (row: TRow) => string\n): void {\n const at = rows.findIndex((row) => getRowId(row) === id);\n if (at !== -1) rows.splice(at, 1);\n}\n\nfunction toMutable(part: GroupPartition): MutablePartition {\n const children = part.children?.map(toMutable);\n return {\n value: part.value,\n valueKey: part.valueKey,\n rows: [...part.rows],\n children,\n childMap: mapOf(children ?? []),\n };\n}\n\nfunction toFrozen(part: MutablePartition): GroupPartition {\n return {\n value: part.value,\n valueKey: part.valueKey,\n rows: part.rows,\n children: part.children?.map(toFrozen),\n };\n}\n\nfunction mapOf(\n nodes: readonly MutablePartition[]\n): Map> {\n return new Map(nodes.map((node) => [node.valueKey, node]));\n}\n","/**\n * Row patches — changing the data you already have, without refetching it.\n *\n * A save returns the updated record, a socket pushes a new one, a delete\n * succeeds. Refetching the page to reflect that costs a round trip and, worse,\n * throws away everything the user had going: the scroll position, which rows\n * were open, sometimes the selection.\n *\n * ```ts\n * const [rows, setRows] = useState(initial);\n * const onSaved = (row: Person) =>\n * setRows((current) => applyRowPatches(current, [updateRow(row.id, row)], byId));\n * ```\n *\n * Two properties make that safe, and both are tested:\n *\n * - **Untouched rows keep their object identity.** React reconciles them as\n * unchanged, and anything memoized per row — a `computed` column's cache,\n * a `memo`'d cell — stays valid instead of recomputing for the whole page.\n * - **A patch that changes nothing returns the very same array.** Applying an\n * update whose values already match, or removing an id that is not there,\n * hands back the original reference, so a `setState` with it does not\n * re-render.\n *\n * Selection and expansion survive because both are keyed by row id, and a\n * patch never changes the id of a row it did not touch.\n *\n * This is a pure function over an array. The table never owns your data and\n * this does not make it start: you hold the rows, you apply the patch.\n */\n\n/** Insert a row. Without `at`, it goes on the end. */\nexport interface InsertPatch {\n type: \"insert\";\n row: TRow;\n /** Zero-based position. Clamped into range; negative counts from the end. */\n at?: number;\n}\n\n/** Merge changes into the row with this id. Absent id: nothing happens. */\nexport interface UpdatePatch {\n type: \"update\";\n id: string;\n changes: Partial;\n}\n\n/** Replace the row with this id, or append it when it is not there yet. */\nexport interface UpsertPatch {\n type: \"upsert\";\n row: TRow;\n}\n\n/** Drop the row with this id. Absent id: nothing happens. */\nexport interface RemovePatch {\n type: \"remove\";\n id: string;\n}\n\n/** One change to a row set. */\nexport type RowPatch =\n | InsertPatch\n | UpdatePatch\n | UpsertPatch\n | RemovePatch;\n\n/** Insert a row, optionally at a position. */\nexport function insertRow(row: TRow, at?: number): InsertPatch {\n return { type: \"insert\", row, at };\n}\n\n/** Merge changes into one row. */\nexport function updateRow(\n id: string,\n changes: Partial\n): UpdatePatch {\n return { type: \"update\", id, changes };\n}\n\n/** Replace a row, or add it if it is new. */\nexport function upsertRow(row: TRow): UpsertPatch {\n return { type: \"upsert\", row };\n}\n\n/** Remove a row by id. */\nexport function removeRow(id: string): RemovePatch {\n return { type: \"remove\", id };\n}\n\n/** Is every own key of `changes` already equal on `row`? */\nfunction alreadyApplied(row: TRow, changes: Partial): boolean {\n return (Object.keys(changes) as (keyof TRow)[]).every((key) =>\n Object.is(row[key], changes[key])\n );\n}\n\n/** Clamp an insert position, letting a negative index count from the end. */\nfunction insertIndex(at: number | undefined, length: number): number {\n if (at === undefined) return length;\n const resolved = at < 0 ? length + at : at;\n return Math.min(Math.max(resolved, 0), length);\n}\n\n/** Where a row with this id sits, or -1. */\nfunction indexOfId(\n list: readonly TRow[],\n id: string,\n getRowId: (row: TRow) => string\n): number {\n return list.findIndex((row) => getRowId(row) === id);\n}\n\n/**\n * One mutation {@link applyRowPatchesWithLog} actually performed.\n *\n * Incremental re-evaluation walks this list instead of scanning the row set\n * to find what changed. Indices are taken at the moment the event ran, so a\n * later event sees the array the earlier one left behind.\n */\nexport type RowPatchEvent =\n | { type: \"insert\"; id: string; row: TRow; index: number }\n | { type: \"remove\"; id: string; row: TRow; index: number }\n | { type: \"update\"; id: string; prev: TRow; next: TRow; index: number };\n\n/**\n * The result of applying patches, plus the events an incremental view needs\n * so it does not have to diff two 20k-row arrays to find one update.\n */\nexport interface RowPatchLog {\n /** The row set after the patches — same contract as {@link applyRowPatches}. */\n rows: readonly TRow[];\n /** Empty when nothing changed; the original array is then on `rows`. */\n events: readonly RowPatchEvent[];\n}\n\nconst PATCH_LOGS = new WeakMap>();\n\n/**\n * The log {@link applyRowPatches} attached to a result array, when the\n * patches actually changed something. A host that already called\n * `applyRowPatches` (the Scale demo, a socket handler) can hand this to\n * the incremental view instead of applying the same patches twice.\n *\n * Spreading the result (`[...applyRowPatches(...)]`) drops the log — the\n * copy is a different array.\n *\n * @typeParam TRow - The row type.\n * @param rows - An array returned by {@link applyRowPatches}.\n * @returns The log, or `undefined` when this array was not produced by a\n * changing patch (or was copied).\n */\nexport function rowPatchLog(\n rows: readonly TRow[]\n): RowPatchLog | undefined {\n return PATCH_LOGS.get(rows) as RowPatchLog | undefined;\n}\n\nfunction rememberLog(log: RowPatchLog): void {\n if (log.events.length === 0) return;\n PATCH_LOGS.set(log.rows, log);\n}\n\n/** Apply one patch to a working copy. Returns the event when something changed. */\nfunction applyOne(\n list: TRow[],\n patch: RowPatch,\n getRowId: (row: TRow) => string\n): RowPatchEvent | undefined {\n if (patch.type === \"insert\") {\n const index = insertIndex(patch.at, list.length);\n list.splice(index, 0, patch.row);\n return { type: \"insert\", id: getRowId(patch.row), row: patch.row, index };\n }\n\n if (patch.type === \"remove\") {\n const index = indexOfId(list, patch.id, getRowId);\n if (index === -1) return undefined;\n const row = list[index]!;\n list.splice(index, 1);\n return { type: \"remove\", id: patch.id, row, index };\n }\n\n if (patch.type === \"upsert\") {\n const id = getRowId(patch.row);\n const index = indexOfId(list, id, getRowId);\n if (index === -1) {\n list.push(patch.row);\n return { type: \"insert\", id, row: patch.row, index: list.length - 1 };\n }\n // Re-upserting the row already in place is not a change, and replacing it\n // with itself would invalidate every per-row memo for nothing.\n const prev = list[index]!;\n if (prev === patch.row) return undefined;\n list[index] = patch.row;\n return { type: \"update\", id, prev, next: patch.row, index };\n }\n\n const index = indexOfId(list, patch.id, getRowId);\n const existing = list[index];\n if (!existing) return undefined;\n // An update that changes nothing must not replace the row object, or every\n // per-row memo downstream would be invalidated for no reason.\n if (alreadyApplied(existing, patch.changes)) return undefined;\n const next = { ...existing, ...patch.changes };\n list[index] = next;\n return { type: \"update\", id: patch.id, prev: existing, next, index };\n}\n\n/**\n * Apply patches to a row set, in order, and return the result.\n *\n * Returns the original array — the same reference — when no patch changed\n * anything. Rows that no patch touched keep their object identity.\n *\n * @typeParam TRow - The row type.\n * @param rows - The current rows.\n * @param patches - The changes to apply, in order.\n * @param getRowId - How a row's id is derived; the table's own `rowKey`.\n */\nexport function applyRowPatches(\n rows: readonly TRow[],\n patches: readonly RowPatch[],\n getRowId: (row: TRow) => string\n): readonly TRow[] {\n return applyRowPatchesWithLog(rows, patches, getRowId).rows;\n}\n\n/**\n * Apply patches and return the events each real mutation produced.\n *\n * {@link applyRowPatches} is this without the log. Incremental re-evaluation\n * sits on the log so a 200-update burst does not walk 20k rows looking for\n * what changed.\n *\n * @typeParam TRow - The row type.\n * @param rows - The current rows.\n * @param patches - The changes to apply, in order.\n * @param getRowId - How a row's id is derived; the table's own `rowKey`.\n */\nexport function applyRowPatchesWithLog(\n rows: readonly TRow[],\n patches: readonly RowPatch[],\n getRowId: (row: TRow) => string\n): RowPatchLog {\n const working = [...rows];\n const events: RowPatchEvent[] = [];\n for (const patch of patches) {\n // Every patch runs, so a later one acts on what an earlier one did.\n const event = applyOne(working, patch, getRowId);\n if (event) events.push(event);\n }\n const log: RowPatchLog = {\n rows: events.length > 0 ? working : rows,\n events,\n };\n rememberLog(log);\n return log;\n}\n","/**\n * Incremental re-evaluation of a patched row set.\n *\n * {@link applyRowPatches} is the data path — it still owns the rows. This\n * module sits on the patch log and re-runs search, filters, sort, grouping\n * and aggregates for the rows a patch touched, instead of walking the\n * whole set again.\n *\n * Build a snapshot with {@link createIncrementalView}, then feed patches\n * through {@link applyRowPatchesToView}. A host that already called\n * `applyRowPatches` can pass {@link rowPatchLog} into\n * {@link applyRowPatchLogToView} so the same patches are not applied twice.\n */\nimport type { ReactNode } from \"react\";\n\nimport {\n aggregate,\n type AggregateOptions,\n type AggregateSpec,\n} from \"../aggregate/aggregate\";\nimport {\n type BuildGroupedFlatModelOptions,\n flattenGroupPartitions,\n type GroupAggregatesFn,\n type GroupedFlatEntry,\n groupingKeys,\n type GroupNode,\n type GroupPaging,\n type GroupSort,\n makeGroupRowKey,\n partitionGroupedRows,\n} from \"../grouping/groupRows\";\nimport {\n compareSortEntries,\n compareSortLevel,\n sortedInsertIndex,\n type SortLevel,\n sortRows,\n sortRowsMulti,\n} from \"../sort/compare\";\nimport type { QueryFilterGroup } from \"../source/queryContract\";\nimport type {\n ColumnDef,\n ExtraFilters,\n SortableValue,\n SortDirection,\n} from \"../types\";\nimport { stableKey } from \"../utils/stableKey\";\nimport {\n addAggregateRow,\n createIncrementalAggregate,\n type IncrementalAggregate,\n readIncrementalAggregate,\n removeAggregateRow,\n replaceAggregateRow,\n} from \"./incrementalAggregate\";\nimport {\n addGroupedRow,\n type IncrementalGroupTree,\n incrementalGroupTree,\n moveGroupedRow,\n removeGroupedRow,\n rowGroupPath,\n snapshotPartitions,\n} from \"./incrementalGroup\";\nimport {\n applyRowPatchesWithLog,\n type RowPatch,\n type RowPatchEvent,\n type RowPatchLog,\n} from \"./patch\";\n\nexport { rowPatchLog } from \"./patch\";\n\n/** How the table turns a row set into a filtered, sorted, grouped view. */\nexport interface IncrementalViewConfig {\n /** How a row's id is derived; the table's own `rowKey`. */\n getRowId: (row: TRow) => string;\n /**\n * Project a row to its searchable text. Defaults to a flatten of the\n * row's own values — the same default `useFrontendData` uses.\n */\n getSearchText?: (row: TRow) => string;\n /** Active search term. Empty / omitted means no search. */\n search?: string;\n /** Client-side extra-filter predicate. */\n filterFn?: (row: TRow, extra: ExtraFilters) => boolean;\n /** The extra-filter bag `filterFn` reads. */\n extra?: ExtraFilters;\n /**\n * Evaluate the AND/OR filter tree against a row. Omit and the tree is\n * stored but not applied — same seam as `useFrontendData`.\n */\n filterTreeFn?: (row: TRow, tree: QueryFilterGroup) => boolean;\n /** The active filter tree, when there is one. */\n filterTree?: QueryFilterGroup;\n /** Columns — sort and group values resolve through these. */\n columns?: readonly ColumnDef[];\n /** Override a column's sort value. */\n getSortValue?: (row: TRow, columnKey: string) => SortableValue;\n /** Single-column sort. Ignored when `sortLevels` is non-empty. */\n sortBy?: string;\n /** Single-column sort direction. */\n sortDir?: SortDirection;\n /** Multi-column sort chain. Supersedes `sortBy` / `sortDir`. */\n sortLevels?: readonly SortLevel[];\n /** Group by one key, or several for a nested grouping. */\n groupBy?: string | readonly string[];\n /** Per-group cells — same signature as `summaryRow`. */\n groupAggregates?: GroupAggregatesFn;\n /** Order groups within their parent. */\n groupSort?: GroupSort;\n /** Keep only the groups this answers true for. */\n groupFilter?: (group: GroupNode) => boolean;\n /** Close every group with a footer row. */\n groupFooters?: boolean;\n /** Collapsed group keys. */\n collapsedGroupIds?: ReadonlySet;\n /** Override the blank-group label. */\n blankLabel?: string;\n /** Page size for top-level groups. */\n groupPageSize?: number;\n /** Page size for leaves inside a group. */\n rowPageSize?: number;\n /** How many extra groups / rows are currently revealed. */\n paging?: GroupPaging;\n /** Grand-total mapper over the sorted (filtered) set. */\n summaryRow?: (rows: readonly TRow[]) => Partial>;\n /**\n * Built-in aggregate spec for incremental totals. Used for the grand\n * total when `summaryRow` is omitted, and for group cells when\n * `groupAggregates` is omitted.\n */\n aggregateSpec?: AggregateSpec;\n /** Options for {@link IncrementalViewConfig.aggregateSpec}. */\n aggregateOptions?: AggregateOptions;\n}\n\n/**\n * A derived snapshot of a row set. The latest snapshot is the only one\n * {@link applyRowPatchesToView} may be called on — applying to a stale\n * snapshot rebuilds from its `rows` instead of continuing incrementally.\n */\nexport interface IncrementalView {\n /** Source rows after patches — same contract as {@link applyRowPatches}. */\n readonly rows: readonly TRow[];\n /** After search, extra filters and the filter tree. */\n readonly filtered: readonly TRow[];\n /** After sort, or `filtered` when unsorted. */\n readonly sorted: readonly TRow[];\n /** Grouped flat model, when grouping is configured. */\n readonly groups: readonly GroupedFlatEntry[] | undefined;\n /** Grand-total cells over `sorted`. */\n readonly aggregates: Partial> | undefined;\n}\n\ninterface ViewState {\n config: IncrementalViewConfig;\n searchText: Map;\n sortValues: Map;\n filtered: TRow[];\n filteredSourceIndex: number[];\n filteredPos: Map;\n sorted: TRow[];\n sortedPos: Map;\n tree: IncrementalGroupTree | undefined;\n summary: IncrementalAggregate | undefined;\n summaryDirty: boolean;\n groupCells: Map>>;\n dirtyGroups: Set;\n}\n\ntype FilterDelta =\n | { kind: \"none\" }\n | { kind: \"enter\"; id: string; row: TRow }\n | { kind: \"leave\"; id: string; row: TRow }\n | { kind: \"replace\"; id: string; prev: TRow; next: TRow };\n\nconst STATES = new WeakMap, ViewState>();\nconst VIEWS = new WeakMap>();\n\n/**\n * The snapshot {@link createIncrementalView} attached to a derived row\n * array (`rows` / `filtered` / `sorted`, or a page slice the host\n * attached). Spreading that array drops the link, same as\n * {@link rowPatchLog}.\n */\nexport function incrementalViewOf(\n rows: readonly TRow[]\n): IncrementalView | undefined {\n return VIEWS.get(rows) as IncrementalView | undefined;\n}\n\n/**\n * Point a derived array (a page slice) at the snapshot it came from, so\n * {@link incrementalViewOf} can find aggregates / groups without a\n * second argument.\n */\nexport function attachIncrementalView(\n rows: readonly TRow[],\n view: IncrementalView\n): void {\n VIEWS.set(rows, view);\n}\n\n/** The config the snapshot was last built or reconfigured with. */\nexport function incrementalViewConfig(\n view: IncrementalView\n): IncrementalViewConfig | undefined {\n return getState(view)?.config;\n}\n\n/**\n * Merge new settings into a snapshot without walking the row set when\n * only grouping / summary extras changed.\n *\n * Filter, sort and search changes rebuild the derived arrays. Grouping\n * and summary extras rebuild only those stages and keep `filtered` /\n * `sorted` identity. A patch that only replaces a callback or a\n * `columns` array with the same keys returns the same view object —\n * hosts rebuild those every render, and a new view identity must not\n * ripple into the page slice.\n *\n * @typeParam TRow - The row type.\n * @param view - The latest snapshot.\n * @param patch - Fields to merge. `undefined` entries are ignored.\n */\nexport function configureIncrementalView(\n view: IncrementalView,\n patch: Partial>\n): IncrementalView {\n const state = getState(view);\n if (!state) {\n throw new Error(\n \"configureIncrementalView needs a snapshot from createIncrementalView\"\n );\n }\n const merged: IncrementalViewConfig = {\n ...state.config,\n ...definedConfigPatch(patch),\n };\n const queryChanged =\n queryConfigFingerprint(state.config) !== queryConfigFingerprint(merged);\n const derivedChanged =\n derivedConfigFingerprint(state.config) !== derivedConfigFingerprint(merged);\n state.config = merged;\n if (!queryChanged && !derivedChanged) return view;\n if (queryChanged) return createIncrementalView(view.rows, merged);\n return republishDerived(view, state, merged);\n}\n\n/**\n * Default searchable-text projector: flatten a row's own values. Kept\n * here so this module does not import the React hook that publishes the\n * same helper on `useFrontendData`.\n */\nexport function incrementalSearchText(row: TRow): string {\n if (row && typeof row === \"object\") {\n return Object.values(row)\n .map((value) => {\n if (value == null) return \"\";\n if (typeof value === \"object\") return JSON.stringify(value);\n return String(value as string | number | boolean);\n })\n .join(\" \");\n }\n return String(row ?? \"\");\n}\n\n/**\n * Build a snapshot by fully evaluating `rows`. Patches after this go\n * through {@link applyRowPatchesToView} so only touched rows are\n * re-evaluated.\n *\n * @typeParam TRow - The row type.\n * @param rows - The current source rows.\n * @param config - Filter / sort / group / aggregate settings.\n */\nexport function createIncrementalView(\n rows: readonly TRow[],\n config: IncrementalViewConfig\n): IncrementalView {\n const getId = config.getRowId;\n const filtered = hasFilter(config)\n ? rows.filter((row) => rowMatches(row, config))\n : [...rows];\n const sorted = hasSort(config) ? fullSort(filtered, config) : filtered;\n const keys = groupingKeys(config.groupBy ?? []);\n const columns = config.columns ?? [];\n const partitions =\n keys.length > 0 ? partitionGroupedRows(sorted, keys, columns) : [];\n const tree =\n keys.length > 0\n ? incrementalGroupTree(partitions, keys, columns)\n : undefined;\n const groups =\n keys.length > 0\n ? flattenGroupPartitions(partitions, groupFlattenOptions(config))\n : undefined;\n const summary = config.aggregateSpec\n ? createIncrementalAggregate(\n config.aggregateSpec,\n sorted,\n config.aggregateOptions\n )\n : undefined;\n const aggregates = readSummary(sorted, config, summary);\n const state: ViewState = {\n config,\n searchText: new Map(),\n sortValues: new Map(),\n filtered: filtered,\n filteredSourceIndex: sourceIndices(filtered, rows, getId),\n filteredPos: indexMap(filtered, getId),\n sorted: sorted,\n sortedPos: indexMap(sorted, getId),\n tree,\n summary,\n summaryDirty: false,\n groupCells: new Map(),\n dirtyGroups: new Set(),\n };\n warmCaches(state, filtered, config);\n if (groups) cacheGroupCells(state, groups);\n return publish(rows, filtered, sorted, groups, aggregates, state);\n}\n\n/**\n * Apply patches to a snapshot: {@link applyRowPatches} for the rows, then\n * incremental re-evaluation of every derived stage.\n *\n * @typeParam TRow - The row type.\n * @param view - The latest snapshot.\n * @param patches - The changes to apply, in order.\n */\nexport function applyRowPatchesToView(\n view: IncrementalView,\n patches: readonly RowPatch[]\n): IncrementalView {\n const state = getState(view);\n if (!state) {\n throw new Error(\n \"applyRowPatchesToView needs a snapshot from createIncrementalView\"\n );\n }\n return applyRowPatchLogToView(\n view,\n applyRowPatchesWithLog(view.rows, patches, state.config.getRowId)\n );\n}\n\n/**\n * Continue a snapshot from a log {@link applyRowPatches} already produced.\n * Use this when the host applied the patches itself and the incremental\n * view must not apply them a second time.\n *\n * @typeParam TRow - The row type.\n * @param view - The snapshot taken against the pre-patch rows.\n * @param log - The log attached to the post-patch array.\n */\nexport function applyRowPatchLogToView(\n view: IncrementalView,\n log: RowPatchLog\n): IncrementalView {\n const state = getState(view);\n if (!state) {\n throw new Error(\n \"applyRowPatchLogToView needs a snapshot from createIncrementalView\"\n );\n }\n if (log.events.length === 0) return view;\n const config = state.config;\n if (!needsDerived(config)) {\n return publish(log.rows, log.rows, log.rows, undefined, undefined, state);\n }\n\n state.filtered = state.filtered.slice();\n state.filteredSourceIndex = state.filteredSourceIndex.slice();\n state.sorted = state.sorted.slice();\n\n const source = [...view.rows];\n for (const event of log.events) {\n applySourceEvent(source, event);\n const delta = applyFilterEvent(state, event, source, config);\n applySortEvent(state, delta, config);\n applyGroupEvent(state, delta, config);\n applySummaryEvent(state, delta, config);\n }\n\n const filtered = hasFilter(config) ? state.filtered : log.rows;\n const sorted = hasSort(config) ? state.sorted : filtered;\n state.filtered = filtered as TRow[];\n state.sorted = sorted as TRow[];\n state.filteredPos = indexMap(filtered, config.getRowId);\n state.sortedPos = indexMap(sorted, config.getRowId);\n\n const groups = state.tree\n ? paintGroups(\n flattenGroupPartitions(\n snapshotPartitions(state.tree),\n groupFlattenOptions(config, true)\n ),\n state,\n config\n )\n : undefined;\n const aggregates = readSummary(sorted, config, state.summary);\n state.summaryDirty = false;\n return publish(log.rows, filtered, sorted, groups, aggregates, state);\n}\n\nfunction getState(\n view: IncrementalView\n): ViewState | undefined {\n return STATES.get(view) as ViewState | undefined;\n}\n\nfunction publish(\n rows: readonly TRow[],\n filtered: readonly TRow[],\n sorted: readonly TRow[],\n groups: readonly GroupedFlatEntry[] | undefined,\n aggregates: Partial> | undefined,\n state: ViewState\n): IncrementalView {\n const view: IncrementalView = {\n rows,\n filtered,\n sorted,\n groups,\n aggregates,\n };\n STATES.set(view, state as ViewState);\n VIEWS.set(rows, view);\n VIEWS.set(filtered, view);\n VIEWS.set(sorted, view);\n return view;\n}\n\nfunction republishDerived(\n view: IncrementalView,\n state: ViewState,\n config: IncrementalViewConfig\n): IncrementalView {\n const keys = groupingKeys(config.groupBy ?? []);\n const columns = config.columns ?? [];\n const partitions =\n keys.length > 0 ? partitionGroupedRows(state.sorted, keys, columns) : [];\n state.tree =\n keys.length > 0\n ? incrementalGroupTree(partitions, keys, columns)\n : undefined;\n state.groupCells = new Map();\n state.dirtyGroups = new Set();\n const groups =\n keys.length > 0\n ? flattenGroupPartitions(partitions, groupFlattenOptions(config))\n : undefined;\n if (groups) cacheGroupCells(state, groups);\n state.summary = config.aggregateSpec\n ? createIncrementalAggregate(\n config.aggregateSpec,\n state.sorted,\n config.aggregateOptions\n )\n : undefined;\n state.summaryDirty = false;\n return publish(\n view.rows,\n view.filtered,\n view.sorted,\n groups,\n readSummary(state.sorted, config, state.summary),\n state\n );\n}\n\nfunction definedConfigPatch(\n patch: Partial>\n): Partial> {\n const defined: Partial> = {};\n for (const key of Object.keys(\n patch\n ) as (keyof IncrementalViewConfig)[]) {\n const value = patch[key];\n if (value !== undefined) Object.assign(defined, { [key]: value });\n }\n return defined;\n}\n\nfunction queryConfigFingerprint(\n config: IncrementalViewConfig\n): string {\n return stableKey({\n search: config.search ?? \"\",\n extra: config.extra ?? {},\n filterTree: config.filterTree ?? null,\n sortBy: config.sortBy ?? null,\n sortDir: config.sortDir ?? null,\n sortLevels: (config.sortLevels ?? []).map((level) => ({\n key: level.key,\n dir: level.dir,\n })),\n columnKeys: (config.columns ?? []).map((column) => column.key),\n hasFilterFn: config.filterFn !== undefined,\n hasFilterTreeFn: config.filterTreeFn !== undefined,\n hasGetSortValue: config.getSortValue !== undefined,\n });\n}\n\nfunction derivedConfigFingerprint(\n config: IncrementalViewConfig\n): string {\n return stableKey({\n groupBy: groupingKeys(config.groupBy ?? []),\n groupFooters: Boolean(config.groupFooters),\n collapsed: config.collapsedGroupIds\n ? [...config.collapsedGroupIds].sort((a, b) => a.localeCompare(b))\n : [],\n groupPageSize: config.groupPageSize ?? null,\n rowPageSize: config.rowPageSize ?? null,\n paging: config.paging ?? null,\n blankLabel: config.blankLabel ?? null,\n hasGroupAggregates: config.groupAggregates !== undefined,\n hasGroupSort: config.groupSort !== undefined,\n hasGroupFilter: config.groupFilter !== undefined,\n hasSummaryRow: config.summaryRow !== undefined,\n hasAggregateSpec: config.aggregateSpec !== undefined,\n });\n}\n\nfunction needsDerived(config: IncrementalViewConfig): boolean {\n return (\n hasFilter(config) ||\n hasSort(config) ||\n groupingKeys(config.groupBy ?? []).length > 0 ||\n config.summaryRow !== undefined ||\n config.aggregateSpec !== undefined\n );\n}\n\nfunction hasFilter(config: IncrementalViewConfig): boolean {\n return (\n Boolean(searchTerm(config)) ||\n config.filterFn !== undefined ||\n (config.filterTree !== undefined && config.filterTreeFn !== undefined)\n );\n}\n\nfunction hasSort(config: IncrementalViewConfig): boolean {\n if (config.sortLevels && config.sortLevels.length > 0) return true;\n return Boolean(config.sortBy && config.sortDir);\n}\n\nfunction searchTerm(config: IncrementalViewConfig): string {\n return config.search?.trim().toLowerCase() ?? \"\";\n}\n\nfunction rowMatches(\n row: TRow,\n config: IncrementalViewConfig,\n cachedText?: string\n): boolean {\n const term = searchTerm(config);\n if (term) {\n const projector = config.getSearchText ?? incrementalSearchText;\n const text = (cachedText ?? projector(row)).toLowerCase();\n if (!text.includes(term)) return false;\n }\n if (config.filterFn && !config.filterFn(row, config.extra ?? {})) {\n return false;\n }\n if (\n config.filterTree &&\n config.filterTreeFn &&\n !config.filterTreeFn(row, config.filterTree)\n ) {\n return false;\n }\n return true;\n}\n\nfunction fullSort(\n rows: readonly TRow[],\n config: IncrementalViewConfig\n): TRow[] {\n const levels = config.sortLevels;\n if (levels && levels.length > 0) {\n return sortRowsMulti(rows, levels, (row, key) =>\n resolveSortValue(row, key, config)\n );\n }\n return sortRows(\n rows,\n (row) => resolveSortValue(row, config.sortBy!, config),\n config.sortDir!\n );\n}\n\nfunction resolveSortValue(\n row: TRow,\n key: string,\n config: IncrementalViewConfig\n): SortableValue {\n if (config.getSortValue) return config.getSortValue(row, key);\n const column = config.columns?.find((item) => item.key === key);\n // A column that declares `sortValue` owns its whole ordering, including the\n // rows it answers `null` for — that answer means \"this one has no place in\n // the order\", and the comparator groups those at the end. Reading the\n // accessor for those rows instead would order one column by two different\n // extractors at once: some rows by their value, the rest by their rendered\n // text, with nothing on screen to say which row got which.\n if (column?.sortValue) return column.sortValue(row);\n return toSortable(column?.accessor?.(row));\n}\n\nfunction toSortable(value: unknown): SortableValue {\n return typeof value === \"string\" ||\n typeof value === \"number\" ||\n typeof value === \"boolean\"\n ? value\n : null;\n}\n\nfunction warmCaches(\n state: ViewState,\n filtered: readonly TRow[],\n config: IncrementalViewConfig\n): void {\n const getId = config.getRowId;\n const term = searchTerm(config);\n const projector = config.getSearchText ?? incrementalSearchText;\n for (const row of filtered) {\n const id = getId(row);\n if (term) state.searchText.set(id, projector(row));\n if (hasSort(config)) state.sortValues.set(id, sortKeyOf(row, config));\n }\n}\n\nfunction sortKeyOf(\n row: TRow,\n config: IncrementalViewConfig\n): SortableValue[] {\n const levels = config.sortLevels;\n if (levels && levels.length > 0) {\n return levels.map((level) => resolveSortValue(row, level.key, config));\n }\n return [resolveSortValue(row, config.sortBy!, config)];\n}\n\nfunction applySourceEvent(\n source: TRow[],\n event: RowPatchEvent\n): void {\n if (event.type === \"insert\") {\n source.splice(event.index, 0, event.row);\n return;\n }\n if (event.type === \"remove\") {\n source.splice(event.index, 1);\n return;\n }\n source[event.index] = event.next;\n}\n\nfunction applyFilterEvent(\n state: ViewState,\n event: RowPatchEvent,\n source: readonly TRow[],\n config: IncrementalViewConfig\n): FilterDelta {\n if (!hasFilter(config)) {\n state.filtered = source as TRow[];\n state.filteredSourceIndex = source.map((_, index) => index);\n return sourceDelta(event);\n }\n if (event.type === \"insert\") return filterInsert(state, event, config);\n if (event.type === \"remove\") return filterRemove(state, event, config);\n return filterUpdate(state, event, config);\n}\n\nfunction sourceDelta(event: RowPatchEvent): FilterDelta {\n if (event.type === \"insert\") {\n return { kind: \"enter\", id: event.id, row: event.row };\n }\n if (event.type === \"remove\") {\n return { kind: \"leave\", id: event.id, row: event.row };\n }\n return { kind: \"replace\", id: event.id, prev: event.prev, next: event.next };\n}\n\nfunction filterInsert(\n state: ViewState,\n event: Extract, { type: \"insert\" }>,\n config: IncrementalViewConfig\n): FilterDelta {\n const at = firstIndexAtLeast(state.filteredSourceIndex, event.index);\n for (let i = at; i < state.filteredSourceIndex.length; i++) {\n state.filteredSourceIndex[i]! += 1;\n }\n rememberSearch(state, event.id, event.row, config);\n if (!rowMatches(event.row, config, state.searchText.get(event.id))) {\n return { kind: \"none\" };\n }\n state.filtered.splice(at, 0, event.row);\n state.filteredSourceIndex.splice(at, 0, event.index);\n return { kind: \"enter\", id: event.id, row: event.row };\n}\n\nfunction filterRemove(\n state: ViewState,\n event: Extract, { type: \"remove\" }>,\n config: IncrementalViewConfig\n): FilterDelta {\n const at = state.filtered.findIndex(\n (row) => config.getRowId(row) === event.id\n );\n forgetRow(state, event.id);\n for (let i = 0; i < state.filteredSourceIndex.length; i++) {\n if (state.filteredSourceIndex[i]! > event.index) {\n state.filteredSourceIndex[i]! -= 1;\n }\n }\n if (at === -1) return { kind: \"none\" };\n state.filtered.splice(at, 1);\n state.filteredSourceIndex.splice(at, 1);\n return { kind: \"leave\", id: event.id, row: event.row };\n}\n\nfunction filterUpdate(\n state: ViewState,\n event: Extract, { type: \"update\" }>,\n config: IncrementalViewConfig\n): FilterDelta {\n const at = state.filtered.findIndex(\n (row) => config.getRowId(row) === event.id\n );\n rememberSearch(state, event.id, event.next, config);\n const matches = rowMatches(\n event.next,\n config,\n state.searchText.get(event.id)\n );\n if (at !== -1 && matches) {\n state.filtered[at] = event.next;\n return {\n kind: \"replace\",\n id: event.id,\n prev: event.prev,\n next: event.next,\n };\n }\n if (at !== -1 && !matches) {\n state.filtered.splice(at, 1);\n state.filteredSourceIndex.splice(at, 1);\n return { kind: \"leave\", id: event.id, row: event.prev };\n }\n if (at === -1 && matches) {\n const insertAt = firstIndexAtLeast(state.filteredSourceIndex, event.index);\n state.filtered.splice(insertAt, 0, event.next);\n state.filteredSourceIndex.splice(insertAt, 0, event.index);\n return { kind: \"enter\", id: event.id, row: event.next };\n }\n return { kind: \"none\" };\n}\n\nfunction applySortEvent(\n state: ViewState,\n delta: FilterDelta,\n config: IncrementalViewConfig\n): void {\n if (!hasSort(config)) {\n state.sorted = state.filtered;\n state.sortedPos = indexMap(state.filtered, config.getRowId);\n return;\n }\n if (delta.kind === \"none\") return;\n state.filteredPos = indexMap(state.filtered, config.getRowId);\n if (delta.kind === \"enter\") {\n insertSorted(state, delta.row, config);\n } else if (delta.kind === \"leave\") {\n removeSorted(state, delta.id, config);\n } else {\n replaceSorted(state, delta.prev, delta.next, config);\n }\n state.sortedPos = indexMap(state.sorted, config.getRowId);\n}\n\nfunction insertSorted(\n state: ViewState,\n row: TRow,\n config: IncrementalViewConfig\n): void {\n const key = sortKeyOf(row, config);\n state.sortValues.set(config.getRowId(row), key);\n const at = sortedInsertIndex(state.sorted, (item) =>\n compareCached(item, row, state, config)\n );\n state.sorted.splice(at, 0, row);\n}\n\nfunction removeSorted(\n state: ViewState,\n id: string,\n config: IncrementalViewConfig\n): void {\n const at = state.sorted.findIndex((row) => config.getRowId(row) === id);\n if (at !== -1) state.sorted.splice(at, 1);\n state.sortValues.delete(id);\n}\n\nfunction replaceSorted(\n state: ViewState,\n _prev: TRow,\n next: TRow,\n config: IncrementalViewConfig\n): void {\n const id = config.getRowId(next);\n const prevKey = state.sortValues.get(id);\n const nextKey = sortKeyOf(next, config);\n state.sortValues.set(id, nextKey);\n if (sameSortKey(prevKey, nextKey)) {\n const at = state.sorted.findIndex((row) => config.getRowId(row) === id);\n if (at !== -1) state.sorted[at] = next;\n return;\n }\n removeSorted(state, id, config);\n state.sortValues.set(id, nextKey);\n insertSorted(state, next, config);\n}\n\nfunction compareCached(\n item: TRow,\n target: TRow,\n state: ViewState,\n config: IncrementalViewConfig\n): number {\n const getId = config.getRowId;\n const itemId = getId(item);\n const targetId = getId(target);\n const itemIndex = state.filteredPos.get(itemId) ?? 0;\n const targetIndex = state.filteredPos.get(targetId) ?? 0;\n const itemKeys = state.sortValues.get(itemId) ?? sortKeyOf(item, config);\n const targetKeys =\n state.sortValues.get(targetId) ?? sortKeyOf(target, config);\n const levels = config.sortLevels;\n if (levels && levels.length > 0) {\n for (const [i, level] of levels.entries()) {\n const decided = compareSortLevel(itemKeys[i], targetKeys[i], level.dir);\n if (decided !== undefined) return decided;\n }\n return itemIndex - targetIndex;\n }\n return compareSortEntries(\n { value: itemKeys[0], index: itemIndex },\n { value: targetKeys[0], index: targetIndex },\n config.sortDir!\n );\n}\n\nfunction sameSortKey(\n prev: readonly SortableValue[] | undefined,\n next: readonly SortableValue[]\n): boolean {\n return (\n prev?.length === next.length &&\n prev.every((value, i) => Object.is(value, next[i]))\n );\n}\n\nfunction applyGroupEvent(\n state: ViewState,\n delta: FilterDelta,\n config: IncrementalViewConfig\n): void {\n const tree = state.tree;\n if (!tree || delta.kind === \"none\") return;\n const getId = config.getRowId;\n if (delta.kind === \"enter\") {\n const path = rowGroupPath(delta.row, tree.keys, tree.columns);\n addGroupedRow(tree, delta.row, path, state.sortedPos, getId);\n markDirtyPath(state, tree.keys, path);\n return;\n }\n if (delta.kind === \"leave\") {\n const path = rowGroupPath(delta.row, tree.keys, tree.columns);\n removeGroupedRow(tree, delta.id, path, state.sortedPos, getId);\n markDirtyPath(state, tree.keys, path);\n return;\n }\n const prevPath = rowGroupPath(delta.prev, tree.keys, tree.columns);\n const nextPath = rowGroupPath(delta.next, tree.keys, tree.columns);\n moveGroupedRow(\n tree,\n delta.prev,\n delta.next,\n prevPath,\n nextPath,\n state.sortedPos,\n getId\n );\n markDirtyPath(state, tree.keys, prevPath);\n markDirtyPath(state, tree.keys, nextPath);\n}\n\nfunction markDirtyPath(\n state: ViewState,\n keys: readonly string[],\n path: readonly { valueKey: string }[]\n): void {\n const valueKeys = path.map((step) => step.valueKey);\n for (let i = 0; i < path.length; i++) {\n state.dirtyGroups.add(\n makeGroupRowKey(keys.slice(0, i + 1), valueKeys.slice(0, i + 1))\n );\n }\n}\n\nfunction applySummaryEvent(\n state: ViewState,\n delta: FilterDelta,\n config: IncrementalViewConfig\n): void {\n if (delta.kind === \"none\") return;\n if (config.summaryRow && !config.aggregateSpec) {\n state.summaryDirty = true;\n return;\n }\n if (!state.summary) return;\n if (delta.kind === \"enter\") addAggregateRow(state.summary, delta.row);\n else if (delta.kind === \"leave\") removeAggregateRow(state.summary, delta.row);\n else replaceAggregateRow(state.summary, delta.prev, delta.next);\n}\n\nfunction readSummary(\n rows: readonly TRow[],\n config: IncrementalViewConfig,\n summary: IncrementalAggregate | undefined\n): Partial> | undefined {\n if (config.summaryRow) return config.summaryRow(rows);\n if (summary) return readIncrementalAggregate(summary, rows);\n return undefined;\n}\n\nfunction groupFlattenOptions(\n config: IncrementalViewConfig,\n skipAggregates = false\n): Omit, \"rows\"> {\n return {\n groupBy: config.groupBy ?? [],\n columns: config.columns ?? [],\n getRowId: config.getRowId,\n collapsedGroupIds: config.collapsedGroupIds ?? new Set(),\n aggregates: skipAggregates ? undefined : config.groupAggregates,\n blankLabel: config.blankLabel,\n footers: config.groupFooters === true,\n sort: config.groupSort,\n filter: config.groupFilter,\n groupPageSize: config.groupPageSize,\n rowPageSize: config.rowPageSize,\n paging: config.paging,\n };\n}\n\nfunction paintGroups(\n entries: GroupedFlatEntry[],\n state: ViewState,\n config: IncrementalViewConfig\n): GroupedFlatEntry[] {\n const seen = new Set();\n for (const entry of entries) {\n if (entry.kind === \"group\") {\n entry.aggregateCells = cellsForGroup(state, config, entry);\n seen.add(entry.key);\n } else if (entry.kind === \"groupFooter\") {\n entry.aggregateCells = state.groupCells.get(entry.groupKey);\n }\n }\n for (const key of state.groupCells.keys()) {\n if (!seen.has(key)) state.groupCells.delete(key);\n }\n state.dirtyGroups.clear();\n return entries;\n}\n\nfunction cellsForGroup(\n state: ViewState,\n config: IncrementalViewConfig,\n entry: Extract, { kind: \"group\" }>\n): Partial> | undefined {\n if (!state.dirtyGroups.has(entry.key) && state.groupCells.has(entry.key)) {\n return state.groupCells.get(entry.key);\n }\n const cells = groupCellsFrom(config, entry.leafRows);\n if (cells) state.groupCells.set(entry.key, cells);\n return cells;\n}\n\nfunction groupCellsFrom(\n config: IncrementalViewConfig,\n rows: readonly TRow[]\n): Partial> | undefined {\n if (config.groupAggregates) return config.groupAggregates(rows);\n if (config.aggregateSpec) {\n return aggregate(config.aggregateSpec, config.aggregateOptions)(rows);\n }\n return undefined;\n}\n\nfunction cacheGroupCells(\n state: ViewState,\n groups: readonly GroupedFlatEntry[]\n): void {\n for (const entry of groups) {\n if (entry.kind === \"group\" && entry.aggregateCells) {\n state.groupCells.set(entry.key, entry.aggregateCells);\n }\n }\n}\n\nfunction rememberSearch(\n state: ViewState,\n id: string,\n row: TRow,\n config: IncrementalViewConfig\n): void {\n if (!searchTerm(config)) return;\n const projector = config.getSearchText ?? incrementalSearchText;\n state.searchText.set(id, projector(row));\n}\n\nfunction forgetRow(state: ViewState, id: string): void {\n state.searchText.delete(id);\n state.sortValues.delete(id);\n}\n\nfunction sourceIndices(\n filtered: readonly TRow[],\n rows: readonly TRow[],\n getId: (row: TRow) => string\n): number[] {\n const index = new Map(rows.map((row, i) => [getId(row), i]));\n return filtered.map((row) => index.get(getId(row)) ?? -1);\n}\n\nfunction indexMap(\n rows: readonly TRow[],\n getId: (row: TRow) => string\n): Map {\n const map = new Map();\n for (let i = 0; i < rows.length; i++) map.set(getId(rows[i]!), i);\n return map;\n}\n\nfunction firstIndexAtLeast(indices: readonly number[], value: number): number {\n const at = indices.findIndex((index) => index >= value);\n return at === -1 ? indices.length : at;\n}\n","import { useCallback, useMemo, useRef } from \"react\";\n\nimport { resolvePaginationMode, useIsMobile } from \"../hooks/useIsMobile\";\nimport {\n applyRowPatchLogToView,\n attachIncrementalView,\n createIncrementalView,\n incrementalSearchText,\n type IncrementalView,\n type IncrementalViewConfig,\n incrementalViewConfig,\n incrementalViewOf,\n} from \"../rows/incremental\";\nimport { type RowPatchLog, rowPatchLog } from \"../rows/patch\";\nimport type { SortLevel } from \"../sort/compare\";\nimport type {\n ColumnDef,\n ExtraFilters,\n PaginationMode,\n SortableValue,\n SortDirection,\n} from \"../types\";\nimport {\n useTableUrlState,\n type UseTableUrlStateOptions,\n} from \"../url/useTableUrlState\";\nimport { devWarn } from \"../utils/devWarn\";\nimport { stableKey } from \"../utils/stableKey\";\nimport type { QueryFilterGroup } from \"./queryContract\";\nimport type { TableSource } from \"./TableSource\";\n\n/** Narrows an accessor's `ReactNode` to a sortable primitive, else `null`. */\nconst toSortable = (value: unknown): SortableValue =>\n typeof value === \"string\" ||\n typeof value === \"number\" ||\n typeof value === \"boolean\"\n ? value\n : null;\n\n/**\n * Dev-only: surface a sort that cannot resolve values (a silent no-op).\n * The most common cause is forgetting to pass `columns` to the hook.\n */\nfunction warnUnresolvableSort(\n sortBy: string,\n column: ColumnDef | undefined,\n rows: readonly TRow[],\n getSortValue?: (row: TRow, columnKey: string) => SortableValue\n): void {\n if (getSortValue) return;\n if (!column) {\n devWarn(\n `sortBy \"${sortBy}\" matches no column — pass \\`columns\\` (or \\`getSortValue\\`) to useFrontendData so client-side sorting can resolve values.`\n );\n return;\n }\n const first = rows[0];\n if (\n !column.sortValue &&\n first !== undefined &&\n toSortable(column.accessor?.(first)) === null\n ) {\n devWarn(\n `column \"${sortBy}\" has no sortable value — its accessor returns a non-primitive; add a \\`sortValue\\` extractor to the column.`\n );\n }\n}\n\n/** Options for {@link useFrontendData}. */\nexport interface UseFrontendDataOptions extends Pick<\n UseTableUrlStateOptions,\n | \"urlAdapter\"\n | \"urlSync\"\n | \"defaults\"\n | \"numberExtraKeys\"\n | \"arrayExtraKeys\"\n | \"urlKey\"\n> {\n /** The source array. Filtered / sorted / sliced internally by state. */\n data: readonly TRow[];\n /**\n * How a row's id is derived — the same function {@link applyRowPatches}\n * used. Defaults to `String(row.id)` when the row has an `id`.\n */\n getRowId?: (row: TRow) => string;\n /**\n * Project a row to its searchable text. Defaults to a flatten of the\n * row's own values; override to reach nested fields.\n */\n getSearchText?: (row: TRow) => string;\n /**\n * Resolve a row's sort value for a column key. Falls back to the\n * matching column's `sortValue`.\n */\n getSortValue?: (row: TRow, columnKey: string) => SortableValue;\n /** Columns — read for per-column `sortValue` when sorting. */\n columns?: readonly ColumnDef[];\n /**\n * Client-side filter predicate applied after search. Receives the active\n * `extra` filter bag (driven by the filter drawer's `setExtra` calls), so a\n * filter UI filters the rows with no extra wiring. Omit for no filtering.\n */\n filterFn?: (row: TRow, extra: ExtraFilters) => boolean;\n /**\n * Evaluate the URL's AND/OR filter tree against a row. Omit and the\n * tree is stored but not applied (server tiers send it instead).\n */\n filterTreeFn?: (row: TRow, tree: QueryFilterGroup) => boolean;\n /** Pagination mode. Defaults to `\"auto\"` (mobile → infinite). */\n paginationMode?: PaginationMode;\n /** Forwarded error to display (e.g. from a query that produced `data`). */\n error?: Error | null;\n /** Forwarded refetch. */\n refetch?: () => Promise | void;\n /** Forwarded fetching flag. */\n isFetching?: boolean;\n /** Forwarded loading flag. */\n isLoading?: boolean;\n /**\n * Force the resolved mobile state instead of using a media query.\n * Primarily a testing/SSR seam.\n */\n forceMobile?: boolean;\n}\n\n/** Default searchable-text projector: flatten a row's own values. */\nexport function defaultSearchText(row: TRow): string {\n return incrementalSearchText(row);\n}\n\n/** Default row id: `String(row.id)` when the row has a string/number id. */\nexport function defaultFrontendRowId(row: TRow): string {\n if (row && typeof row === \"object\" && \"id\" in row) {\n const id = row.id;\n if (typeof id === \"string\" || typeof id === \"number\") return String(id);\n }\n if (typeof row === \"string\" || typeof row === \"number\") return String(row);\n return \"\";\n}\n\n/**\n * In-memory {@link TableSource}: reads URL/local state and filters, sorts,\n * and slices a caller-supplied array. The mirror of `useQuerySource` —\n * the table cannot tell which produced it.\n *\n * A {@link rowPatchLog} on `data` continues the live {@link IncrementalView}\n * so only touched rows re-run search, filters and sort. Spreading the\n * patched array drops the log and falls back to a full rebuild.\n *\n * @typeParam TRow - The row item type.\n * @param options - See {@link UseFrontendDataOptions}.\n * @returns A {@link TableSource} over the in-memory data.\n */\nexport function useFrontendData(\n options: UseFrontendDataOptions\n): TableSource {\n const {\n data,\n getRowId = defaultFrontendRowId,\n getSearchText = defaultSearchText,\n getSortValue,\n columns,\n filterFn,\n filterTreeFn,\n paginationMode = \"auto\",\n error = null,\n refetch,\n isFetching = false,\n isLoading = false,\n forceMobile,\n ...urlOptions\n } = options;\n\n const mediaMobile = useIsMobile();\n const isMobile = forceMobile ?? mediaMobile;\n const resolvedMode = resolvePaginationMode(paginationMode, isMobile);\n const paged = resolvedMode === \"paged\";\n\n const state = useTableUrlState(urlOptions);\n const { page, limit, search, sortBy, sortDir, groupBy } = state;\n const sortLevels = state.sortLevels;\n\n const getSearchTextRef = useRef(getSearchText);\n getSearchTextRef.current = getSearchText;\n const getRowIdRef = useRef(getRowId);\n getRowIdRef.current = getRowId;\n const searchCacheRef = useRef>(new Map());\n const projectSearchText = useCallback((row: TRow) => {\n const id = getRowIdRef.current(row);\n const cached = searchCacheRef.current.get(id);\n if (cached !== undefined) return cached;\n const text = getSearchTextRef.current(row);\n searchCacheRef.current.set(id, text);\n return text;\n }, []);\n\n const fingerprint: FrontendViewFingerprint = {\n extra: state.extra,\n filterTree: state.filterTree,\n columns,\n search,\n sortBy,\n sortDir,\n sortLevels,\n groupBy,\n hasFilterFn: filterFn !== undefined,\n hasFilterTreeFn: filterTreeFn !== undefined,\n hasGetSortValue: getSortValue !== undefined,\n };\n const hookConfig: IncrementalViewConfig = {\n getRowId,\n getSearchText: projectSearchText,\n filterFn,\n extra: state.extra,\n filterTreeFn,\n filterTree: state.filterTree,\n columns,\n getSortValue,\n sortBy,\n sortDir,\n sortLevels,\n search,\n groupBy,\n };\n\n const viewRef = useRef | undefined>(undefined);\n const dataRef = useRef(data);\n const fingerprintRef = useRef(undefined);\n const view = syncFrontendView({\n data,\n hookConfig,\n fingerprint: hookViewFingerprint(fingerprint),\n viewRef,\n dataRef,\n fingerprintRef,\n searchCache: searchCacheRef.current,\n });\n\n if (sortLevels.length === 0 && sortBy && sortDir) {\n warnUnresolvableSort(\n sortBy,\n columns?.find((column) => column.key === sortBy),\n view.filtered,\n getSortValue\n );\n }\n\n const sorted = view.sorted;\n attachIncrementalView(sorted, view);\n\n // Facets read allSearchedRows: after search, BEFORE extra filters.\n // view.filtered already applied filterFn, so a selected checklist\n // would hide every other value if we published that here.\n const searched = useMemo(() => {\n const term = search.trim().toLowerCase();\n if (!term) return data;\n return data.filter((row) =>\n projectSearchText(row).toLowerCase().includes(term)\n );\n }, [data, search, projectSearchText]);\n const total = sorted.length;\n const lastPage = Math.max(1, Math.ceil(total / Math.max(limit, 1)));\n const safePage = Math.min(Math.max(page, 1), lastPage);\n\n // The view object is NOT a dependency: hosts rebuild extra/columns\n // (and useTableData's filterTreeFn) every render. A new view identity\n // must not mint a new page slice or radix/base-ui findInTable loops.\n const rows = useMemo(() => {\n if (paged) {\n const start = (safePage - 1) * limit;\n return sorted.slice(start, start + limit);\n }\n return sorted.slice(0, safePage * limit);\n }, [sorted, paged, safePage, limit]);\n attachIncrementalView(rows, view);\n\n const hasNextPage = !paged && safePage * limit < total;\n\n const fetchNextPage = useCallback(() => {\n if (paged || safePage * limit >= total) return;\n state.setPage(safePage + 1);\n }, [paged, safePage, limit, total, state]);\n\n return {\n rows,\n allFilteredRows: sorted,\n allSearchedRows: searched,\n total,\n isLoading,\n isFetching,\n isFetchingNextPage: false,\n hasNextPage,\n fetchNextPage,\n error,\n refetch,\n paginationMode: resolvedMode,\n page: safePage,\n limit,\n defaultLimit: state.defaultLimit,\n search,\n sortBy,\n sortDir,\n groupBy,\n extra: state.extra,\n filterTree: state.filterTree,\n setPage: state.setPage,\n setLimit: state.setLimit,\n setSort: state.setSort,\n setGroupBy: state.setGroupBy,\n sortLevels: state.sortLevels,\n toggleSortLevel: state.toggleSortLevel,\n setSearch: state.setSearch,\n setExtra: state.setExtra,\n setExtras: state.setExtras,\n setFilterTree: state.setFilterTree,\n clearExtras: state.clearExtras,\n clearAll: state.clearAll,\n };\n}\n\n/** Value-only hook inputs. Callback / array identity is ignored. */\ninterface FrontendViewFingerprint {\n extra: ExtraFilters;\n filterTree: QueryFilterGroup | undefined;\n columns: readonly ColumnDef[] | undefined;\n search: string;\n sortBy: string | undefined;\n sortDir: SortDirection | undefined;\n sortLevels: readonly SortLevel[];\n groupBy: string | undefined;\n hasFilterFn: boolean;\n hasFilterTreeFn: boolean;\n hasGetSortValue: boolean;\n}\n\nfunction hookViewFingerprint(\n fingerprint: FrontendViewFingerprint\n): string {\n return stableKey({\n extra: fingerprint.extra,\n filterTree: fingerprint.filterTree ?? null,\n search: fingerprint.search,\n sortBy: fingerprint.sortBy ?? null,\n sortDir: fingerprint.sortDir ?? null,\n sortLevels: fingerprint.sortLevels.map((level) => ({\n key: level.key,\n dir: level.dir,\n })),\n groupBy: fingerprint.groupBy ?? null,\n columnKeys: (fingerprint.columns ?? []).map((column) => column.key),\n hasFilterFn: fingerprint.hasFilterFn,\n hasFilterTreeFn: fingerprint.hasFilterTreeFn,\n hasGetSortValue: fingerprint.hasGetSortValue,\n });\n}\n\nfunction syncFrontendView(args: {\n data: readonly TRow[];\n hookConfig: IncrementalViewConfig;\n fingerprint: string;\n viewRef: { current: IncrementalView | undefined };\n dataRef: { current: readonly TRow[] };\n fingerprintRef: { current: string | undefined };\n searchCache: Map;\n}): IncrementalView {\n // Only follow a chrome reconfigure of THIS hook's snapshot. Looking\n // up `data` on first mount would steal another table's view — hosts\n // (and tests) reuse the same source array.\n if (args.viewRef.current) {\n const latest = incrementalViewOf(args.data);\n if (latest) args.viewRef.current = latest;\n }\n\n const previousData = args.dataRef.current;\n const previousFingerprint = args.fingerprintRef.current;\n const configChanged =\n previousFingerprint !== undefined &&\n previousFingerprint !== args.fingerprint;\n\n const log = args.data === previousData ? undefined : rowPatchLog(args.data);\n const canPatch =\n !configChanged &&\n args.viewRef.current !== undefined &&\n log !== undefined &&\n args.viewRef.current.rows === previousData &&\n logBelongsToPrevious(log, previousData);\n\n if (canPatch && log) {\n forgetPatchedSearch(args.searchCache, log);\n adoptHookRefs(args.viewRef.current!, args.hookConfig);\n const next = applyRowPatchLogToView(args.viewRef.current!, log);\n args.viewRef.current = next;\n args.dataRef.current = args.data;\n args.fingerprintRef.current = args.fingerprint;\n return next;\n }\n\n const dataChanged = args.data !== previousData;\n const first = args.viewRef.current === undefined;\n if (!first && !configChanged && !dataChanged) {\n adoptHookRefs(args.viewRef.current!, args.hookConfig);\n return args.viewRef.current!;\n }\n\n if (dataChanged && !canPatch) args.searchCache.clear();\n const created = createIncrementalView(\n args.data,\n mergeHookConfig(args.hookConfig, args.viewRef.current)\n );\n args.viewRef.current = created;\n args.dataRef.current = args.data;\n args.fingerprintRef.current = args.fingerprint;\n return created;\n}\n\nfunction adoptHookRefs(\n view: IncrementalView,\n hookConfig: IncrementalViewConfig\n): void {\n const current = incrementalViewConfig(view);\n if (!current) return;\n current.getRowId = hookConfig.getRowId;\n current.getSearchText = hookConfig.getSearchText;\n current.filterFn = hookConfig.filterFn;\n current.filterTreeFn = hookConfig.filterTreeFn;\n current.columns = hookConfig.columns;\n current.getSortValue = hookConfig.getSortValue;\n}\n\nfunction mergeHookConfig(\n hookConfig: IncrementalViewConfig,\n current: IncrementalView | undefined\n): IncrementalViewConfig {\n const previous = current ? incrementalViewConfig(current) : undefined;\n if (!previous) return hookConfig;\n return {\n ...hookConfig,\n groupAggregates: previous.groupAggregates,\n groupSort: previous.groupSort,\n groupFilter: previous.groupFilter,\n groupFooters: previous.groupFooters,\n collapsedGroupIds: previous.collapsedGroupIds,\n blankLabel: previous.blankLabel,\n groupPageSize: previous.groupPageSize,\n rowPageSize: previous.rowPageSize,\n paging: previous.paging,\n summaryRow: previous.summaryRow,\n aggregateSpec: previous.aggregateSpec,\n aggregateOptions: previous.aggregateOptions,\n groupBy: hookConfig.groupBy ?? previous.groupBy,\n };\n}\n\nfunction forgetPatchedSearch(\n cache: Map,\n log: RowPatchLog\n): void {\n for (const event of log.events) {\n if (event.type !== \"insert\") cache.delete(event.id);\n }\n}\n\n/**\n * Did this log come from applying patches to `previous`? A copied array\n * (`[...applyRowPatches(...)]`) has no log; a log from a different source\n * fails the replay.\n */\nfunction logBelongsToPrevious(\n log: RowPatchLog,\n previous: readonly TRow[]\n): boolean {\n if (log.events.length === 0) return false;\n const working = previous.slice();\n for (const event of log.events) {\n if (event.type === \"insert\") {\n if (event.index < 0 || event.index > working.length) return false;\n working.splice(event.index, 0, event.row);\n } else if (event.type === \"remove\") {\n if (working[event.index] !== event.row) return false;\n working.splice(event.index, 1);\n } else if (working[event.index] !== event.prev) {\n return false;\n } else {\n working[event.index] = event.next;\n }\n }\n return working.length === log.rows.length;\n}\n","import type { ReactNode } from \"react\";\nimport { useEffect, useMemo, useRef, useState } from \"react\";\n\nimport { resolveColumns } from \"../columns/resolveColumns\";\nimport { computeFilterFacets, type FacetMap } from \"../filters/facets\";\nimport { resolveFilterRegistry } from \"../filters/filterBuiltins\";\nimport {\n buildFilterRuntime,\n type FilterDef,\n type FilterOption,\n type FilterRuntime,\n materializeAutoOptions,\n resolveFilterDefs,\n} from \"../filters/filterDefs\";\nimport type { FilterTypeSpec } from \"../filters/filterRegistry\";\nimport { evaluateFilterTree } from \"../filters/filterTree\";\nimport type {\n ColumnDef,\n ExtraFilters,\n PaginationMode,\n SortableValue,\n} from \"../types\";\nimport type { UseTableUrlStateOptions } from \"../url/useTableUrlState\";\nimport { devWarn } from \"../utils/devWarn\";\nimport { stableKey } from \"../utils/stableKey\";\nimport type { QuerySupport } from \"./queryContract\";\nimport type { TableSource } from \"./TableSource\";\nimport { useFrontendData } from \"./useFrontendData\";\nimport {\n type TableQuery,\n useServerData,\n type UseServerDataOptions,\n} from \"./useServerData\";\n\n/** Options for {@link useTableData}. */\nexport interface UseTableDataOptions extends Pick<\n UseTableUrlStateOptions,\n \"urlAdapter\" | \"urlSync\" | \"defaults\" | \"urlKey\"\n> {\n /** Full-control tier: a prebuilt source (e.g. `useQuerySource`). */\n source?: TableSource;\n /** Frontend tier: the raw rows; the table filters/sorts/pages them. */\n data?: readonly TRow[];\n /** Server tier: total row count across all pages. */\n total?: number;\n /** Server tier: request in flight. */\n loading?: boolean;\n /** Forwarded error. */\n error?: Error | null;\n /**\n * Explicit data mode. `\"server\"` makes `onQueryChange` the data\n * contract (the caller fetches); `\"frontend\"` keeps the table's own\n * data processing and turns `onQueryChange` into a pure notification.\n * Absent, the tier is inferred exactly as before: `data` alone →\n * frontend; `data` + `onQueryChange` → server; `source` → source tier.\n */\n mode?: \"frontend\" | \"server\";\n /** Server tier: see {@link UseServerDataOptions.onQueryChange}. */\n onQueryChange?: NonNullable<\n Parameters>[0][\"onQueryChange\"]\n >;\n /** Columns — their `filter` shorthands feed the runtime. */\n columns: readonly ColumnDef[];\n /** Table-level filters: declarative array, or JSX for a hand-drawn form. */\n filters?: readonly FilterDef[] | ReactNode;\n /**\n * Extra or replacement filter types merged onto the built-in registry.\n * A spec whose `type` matches a built-in replaces it.\n */\n filterTypes?: readonly FilterTypeSpec[];\n /** Extra client-side predicate AND-ed with the declarative ones. */\n filterFn?: (row: TRow, extra: ExtraFilters) => boolean;\n /** Frontend tier: pagination mode (defaults to `\"auto\"`). */\n paginationMode?: PaginationMode;\n /** Frontend tier: searchable-text projector. */\n getSearchText?: (row: TRow) => string;\n /** Frontend tier: sort-value resolver. */\n getSortValue?: (row: TRow, columnKey: string) => SortableValue;\n /** Active locale — drives per-column `i18n` path resolution. */\n locale?: string;\n /**\n * Server tier: what this endpoint can answer. `supports.facets`\n * unlocks `query.facets` (checklist keys, or {@link facetKeys}).\n */\n supports?: QuerySupport;\n /**\n * Server tier: keys to send as `query.facets`. Defaults to every\n * `checklist` definition when omitted.\n */\n facetKeys?: readonly string[];\n /** Server tier: distinct-value counts from the last fetch. */\n facets?: FacetMap;\n}\n\n/** Result of {@link useTableData}. */\nexport interface UseTableDataResult {\n /** The resolved source, whichever tier provided it. */\n source: TableSource;\n /** The merged declarative-filter runtime (defs, chips, URL keys, predicate). */\n runtime: FilterRuntime;\n}\n\ntype DataTier = \"source\" | \"server\" | \"frontend\";\n\n/**\n * The public `mode` prop surface, shared by every batteries-included\n * ``: a discriminated union so `mode=\"server\"` REQUIRES\n * `onQueryChange` at compile time, while `mode=\"frontend\"` (or no mode\n * at all) keeps it optional — as a pure notification and as the v1-style\n * inference trigger respectively.\n *\n * @typeParam TRow - The row type.\n */\nexport type DataModeProps =\n | {\n /** The table owns the query state; the CALLER fetches. */\n mode: \"server\";\n /** The data contract: run the request, hand back `data` + `total`. */\n onQueryChange: NonNullable[\"onQueryChange\"]>;\n }\n | {\n /**\n * The table processes `data` itself. Omit `mode` for the inferred\n * tiers (`data` + `onQueryChange` still means server).\n */\n mode?: \"frontend\";\n /**\n * With `mode=\"frontend\"`: a pure notification, fired on every\n * committed sort / filter / page / search change and never on\n * mount. Without `mode`: providing it selects the server tier.\n */\n onQueryChange?: NonNullable[\"onQueryChange\"]>;\n };\n\nfunction resolveTier(\n source: unknown,\n mode: \"frontend\" | \"server\" | undefined,\n onQueryChange: unknown\n): DataTier {\n if (source) return \"source\";\n if (mode) return mode;\n return onQueryChange ? \"server\" : \"frontend\";\n}\n\nfunction warnTierMisuse(\n source: unknown,\n mode: \"frontend\" | \"server\" | undefined,\n data: unknown,\n onQueryChange: unknown\n): void {\n if (source && mode) {\n devWarn(\n \"`mode` is ignored when `source` is provided — the prebuilt source wins. Pass one data tier.\"\n );\n }\n if (source && (data || onQueryChange)) {\n devWarn(\n \"both `source` and `data`/`onQueryChange` were provided — using `source`. Pass one data tier.\"\n );\n }\n if (!source && !data) {\n devWarn(\n \"no data tier provided — pass `data` (frontend), `data` + `onQueryChange` (server) or `source`.\"\n );\n }\n}\n\n/**\n * Notify-only `onQueryChange` for the explicit frontend mode: fires with\n * the consolidated {@link TableQuery} on every COMMITTED state change —\n * sort, filter, page, page size, search — and never on mount. The\n * previous call's signal aborts when a newer notification supersedes it,\n * mirroring the server tier's contract.\n */\nfunction useQueryNotification(\n source: TableSource,\n handler: NonNullable[\"onQueryChange\"]> | undefined\n): void {\n const { page, limit, search, sortBy, sortDir, sortLevels, extra } = source;\n const query = useMemo(\n () => ({\n page,\n limit,\n search,\n sortBy,\n sortDir,\n sortLevels: sortLevels ?? [],\n filters: extra,\n }),\n [page, limit, search, sortBy, sortDir, sortLevels, extra]\n );\n const queryKey = stableKey(query);\n const handlerRef = useRef(handler);\n handlerRef.current = handler;\n const queryRef = useRef(query);\n queryRef.current = query;\n // Primed with the mount key, so the first firing needs a REAL change.\n const lastKeyRef = useRef(queryKey);\n const controllerRef = useRef(null);\n useEffect(() => {\n if (lastKeyRef.current === queryKey) return;\n lastKeyRef.current = queryKey;\n const notify = handlerRef.current;\n if (!notify) return;\n controllerRef.current?.abort();\n const controller = new AbortController();\n controllerRef.current = controller;\n void notify(queryRef.current, { signal: controller.signal });\n return () => controller.abort();\n }, [queryKey]);\n}\n\n/** True when the `filters` prop is the declarative array form. */\nexport function isDeclarativeFilters(\n filters: readonly FilterDef[] | ReactNode\n): filters is readonly FilterDef[] {\n return Array.isArray(filters);\n}\n\n/**\n * Resolve the table's data tier from what the caller passed:\n *\n * - `source` — full control (query-library integration), used as-is;\n * - `data` + `onQueryChange` — server mode: the table owns the query state\n * and emits consolidated change events; the caller fetches;\n * - `data` alone — frontend mode: filtering/sorting/paging are automatic,\n * with the declarative filters' predicate already applied.\n *\n * All three run through the same declarative-filter runtime, so column\n * `filter` shorthands and the `filters` array drive chips and URL parsing\n * regardless of tier.\n *\n * @typeParam TRow - The row type.\n */\nexport function useTableData(\n options: UseTableDataOptions\n): UseTableDataResult {\n const {\n source,\n data,\n total = 0,\n loading,\n error,\n mode,\n onQueryChange,\n columns,\n filters,\n filterTypes,\n filterFn,\n paginationMode,\n getSearchText,\n getSortValue,\n locale,\n supports,\n facetKeys,\n facets: serverFacets,\n ...urlOptions\n } = options;\n\n const declaredFilters = isDeclarativeFilters(filters) ? filters : undefined;\n\n // Async option loaders: ONE cached promise serves both the chip labels\n // (here) and the form's `useFilterOptions` (same function identity), so\n // nothing fetches twice — and once resolved, the defs carry the ARRAY,\n // which re-labels active chips and makes the form instant.\n const loaderCacheRef = useRef(\n new Map Promise>()\n );\n const awaitedRef = useRef(new Set());\n const [loadedOptions, setLoadedOptions] = useState<\n Record\n >({});\n\n const runtime = useMemo(() => {\n const materialized = materializeAutoOptions(\n resolveFilterDefs(columns, declaredFilters, locale),\n // `\"auto\"` derives from the full frontend dataset; other tiers\n // only ever see the current page (useFilterOptions dev-warns).\n data ?? []\n );\n const withAsync = materialized.map((def) => {\n if (typeof def.options !== \"function\") return def;\n const loaded = loadedOptions[def.key];\n if (loaded) return { ...def, options: loaded };\n let cached = loaderCacheRef.current.get(def.key);\n if (!cached) {\n const original = def.options;\n let inFlight: Promise | null = null;\n cached = () => (inFlight ??= original());\n loaderCacheRef.current.set(def.key, cached);\n }\n return { ...def, options: cached };\n });\n return buildFilterRuntime(withAsync, resolveFilterRegistry(filterTypes));\n }, [columns, declaredFilters, locale, data, loadedOptions, filterTypes]);\n\n useEffect(() => {\n let alive = true;\n for (const def of runtime.defs) {\n if (typeof def.options !== \"function\") continue;\n if (awaitedRef.current.has(def.key)) continue;\n awaitedRef.current.add(def.key);\n const key = def.key;\n void def.options().then(\n (options) => {\n if (alive) {\n setLoadedOptions((prev) => ({ ...prev, [key]: options }));\n }\n },\n () => {\n // The form's useFilterOptions surfaces the failure dev warning;\n // chips simply keep labeling with raw values.\n }\n );\n }\n return () => {\n alive = false;\n };\n }, [runtime.defs]);\n\n const tier = resolveTier(source, mode, onQueryChange);\n warnTierMisuse(source, mode, data, onQueryChange);\n\n const combinedFilterFn = useMemo(\n () =>\n filterFn\n ? (row: TRow, extra: ExtraFilters) =>\n runtime.filterFn(row, extra) && filterFn(row, extra)\n : runtime.filterFn,\n [runtime, filterFn]\n );\n\n // Hooks must run unconditionally; the inactive tiers run disabled (memory\n // URL store, empty data, no emitter) and cost nothing.\n const resolvedColumns = useMemo(\n () => resolveColumns(columns, locale),\n [columns, locale]\n );\n const frontend = useFrontendData({\n ...urlOptions,\n urlSync: tier === \"frontend\" ? urlOptions.urlSync : false,\n data: tier === \"frontend\" ? (data ?? []) : [],\n columns: resolvedColumns,\n filterFn: combinedFilterFn,\n filterTreeFn: (row, tree) =>\n evaluateFilterTree(tree, row, runtime.defs, runtime.registry),\n arrayExtraKeys: runtime.arrayExtraKeys,\n numberExtraKeys: runtime.numberExtraKeys,\n paginationMode,\n getSearchText,\n getSortValue,\n error,\n isLoading: mode === \"frontend\" ? loading : undefined,\n });\n const derivedFacetKeys = useMemo(() => {\n if (facetKeys) return facetKeys;\n return runtime.defs\n .filter(\n (def) =>\n (runtime.registry.get(def.type)?.widget ?? def.type) === \"checklist\"\n )\n .map((def) => def.key);\n }, [facetKeys, runtime.defs, runtime.registry]);\n\n const server = useServerData({\n ...urlOptions,\n urlSync: tier === \"server\" ? urlOptions.urlSync : false,\n rows: tier === \"server\" ? (data ?? []) : [],\n total,\n loading,\n error,\n paginationMode,\n onQueryChange: tier === \"server\" ? onQueryChange : undefined,\n arrayExtraKeys: runtime.arrayExtraKeys,\n numberExtraKeys: runtime.numberExtraKeys,\n supports: tier === \"server\" ? supports : undefined,\n facetKeys: tier === \"server\" ? derivedFacetKeys : undefined,\n facets: tier === \"server\" ? serverFacets : undefined,\n });\n\n // Explicit frontend mode turns `onQueryChange` into a pure notification\n // over the frontend source's committed state.\n useQueryNotification(\n frontend,\n tier === \"frontend\" && mode === \"frontend\" ? onQueryChange : undefined\n );\n\n let resolved: TableSource;\n if (source) resolved = source;\n else if (tier === \"server\") resolved = server;\n else resolved = frontend;\n\n const facets = useMemo(() => {\n if (resolved.facets) return resolved.facets;\n const rows = resolved.allSearchedRows;\n if (!rows) return undefined;\n return computeFilterFacets(\n runtime.defs,\n rows,\n resolved.extra,\n (row, extra) => {\n if (!combinedFilterFn(row, extra)) return false;\n if (!resolved.filterTree) return true;\n return evaluateFilterTree(\n resolved.filterTree,\n row,\n runtime.defs,\n runtime.registry\n );\n },\n runtime.registry\n );\n }, [resolved, runtime.defs, runtime.registry, combinedFilterFn]);\n\n const sourced = useMemo(\n () => (facets ? { ...resolved, facets } : resolved),\n [resolved, facets]\n );\n\n return { source: sourced, runtime };\n}\n","import type { CSSProperties } from \"react\";\n\nimport type { ColumnDef } from \"../types\";\n\n/** Pixel lock for a collapsed arrow stub — chevron only, no leftover strip. */\nexport const COLUMN_GROUP_STUB_WIDTH = 36;\n\n/** Path separator inside a column-group id — labels may contain `/`. */\nexport const COLUMN_GROUP_ID_SEP = \"\\u001f\";\n\n/** Synthetic leaf shown when a collapsed group has no summary column. */\nexport const COLUMN_GROUP_STUB_PREFIX = \"__groupStub:\";\n\n/** Synthetic leaf shown when a collapsed group uses `collapsedRender`. */\nexport const COLUMN_GROUP_RENDER_PREFIX = \"__groupRender:\";\n\n/** True when this key is a collapsed-group arrow stub. */\nexport function isColumnGroupStubKey(key: string): boolean {\n return key.startsWith(COLUMN_GROUP_STUB_PREFIX);\n}\n\n/** True when this key is a collapsed-group `collapsedRender` column. */\nexport function isColumnGroupRenderKey(key: string): boolean {\n return key.startsWith(COLUMN_GROUP_RENDER_PREFIX);\n}\n\n/** True when this key is a stub or `collapsedRender` summary leaf. */\nexport function isColumnGroupSummaryKey(key: string): boolean {\n return isColumnGroupStubKey(key) || isColumnGroupRenderKey(key);\n}\n\n/**\n * Inset hairline under a group title that still has child headers below.\n * Stops Assignment and Delivery sharing one stroke across the gap.\n */\nexport function groupedHeaderChildRule(hairline: string): {\n readonly borderBottom: string;\n readonly backgroundImage: string;\n readonly backgroundPosition: string;\n readonly backgroundRepeat: string;\n readonly backgroundSize: string;\n} {\n return {\n borderBottom: \"none\",\n backgroundImage: `linear-gradient(${hairline}, ${hairline})`,\n backgroundPosition: \"center bottom\",\n backgroundRepeat: \"no-repeat\",\n backgroundSize: \"calc(100% - 12px) 1px\",\n };\n}\n\n/** One cell of a group header row. */\nexport interface HeaderGroupCell {\n /** Stable key for React lists. */\n key: string;\n /** Group label, or `null` for the gap over ungrouped columns. */\n label: string | null;\n /** How many leaf columns this cell spans. */\n span: number;\n /**\n * Stable id of this group (`path.join(COLUMN_GROUP_ID_SEP)`).\n * `null` on a gap cell.\n */\n id: string | null;\n /** True when this group is collapsed. */\n collapsed: boolean;\n /** True when the host armed collapse and this cell is a real group. */\n collapsible: boolean;\n /**\n * Hide the visible caption (collapsed arrow stub). The name stays on\n * the toggle's accessible label.\n */\n hideLabel: boolean;\n /**\n * Header alignment. Omit and {@link groupedHeaderAlign} uses `\"center\"`,\n * the previous hardcoded value.\n */\n align?: GroupedHeaderAlign;\n}\n\n/** Alignment of a spanning group header. */\nexport type GroupedHeaderAlign = \"start\" | \"center\" | \"end\";\n\n/**\n * Size lock for a collapsed arrow-stub column. `width` alone is a hint in\n * auto table layout; min + max stop the table from stretching the blank\n * strip to a data-column width.\n */\nexport function columnGroupStubStyle(): CSSProperties {\n return {\n width: COLUMN_GROUP_STUB_WIDTH,\n minWidth: COLUMN_GROUP_STUB_WIDTH,\n maxWidth: COLUMN_GROUP_STUB_WIDTH,\n paddingInline: 0,\n overflow: \"hidden\",\n boxSizing: \"border-box\",\n };\n}\n\n/**\n * Alignment for a group header. Omit / unknown → `\"center\"`, so existing\n * tables keep the hardcoded look; pass `\"start\"` or `\"end\"` to opt out.\n */\nexport function groupedHeaderAlign(\n align?: GroupedHeaderAlign\n): GroupedHeaderAlign {\n if (align === \"start\" || align === \"end\") return align;\n return \"center\";\n}\n\n/**\n * Cluster for the collapse chevron + group title. A one-child group is only\n * as wide as that leaf, so without this the button wraps onto the line above\n * the caption — worst when every neighbor is also collapsed.\n */\nexport function groupedHeaderLabelStyle(): CSSProperties {\n return {\n display: \"inline-flex\",\n alignItems: \"center\",\n gap: \"0.2em\",\n whiteSpace: \"nowrap\",\n verticalAlign: \"middle\",\n maxWidth: \"100%\",\n };\n}\n\n/**\n * Style on one HTML group header cell: inset hairline while children sit\n * below, and the stub lock when the caption is hidden.\n */\nexport function groupedHeaderCellStyle(\n cell: Readonly<{ rowSpan: number; cell: HeaderGroupCell }>,\n hairline: string\n): CSSProperties {\n return {\n textAlign: groupedHeaderAlign(cell.cell.align),\n whiteSpace: \"nowrap\",\n ...(cell.rowSpan > 1 ? {} : groupedHeaderChildRule(hairline)),\n ...(cell.cell.hideLabel\n ? columnGroupStubStyle()\n : { minWidth: \"max-content\" }),\n };\n}\n\n/** `column.group` as a root-to-leaf path. A string is one level. */\nexport function columnGroupPath(\n column: Pick, \"group\">\n): readonly string[] {\n if (column.group === undefined) return [];\n return typeof column.group === \"string\" ? [column.group] : column.group;\n}\n\n/** Stable id for a group path. */\nexport function columnGroupId(path: readonly string[]): string {\n return path.join(COLUMN_GROUP_ID_SEP);\n}\n\n/** Add or drop a group id in the collapsed set. */\nexport function toggleCollapsedColumnGroup(\n collapsedIds: readonly string[],\n id: string\n): string[] {\n return collapsedIds.includes(id)\n ? collapsedIds.filter((one) => one !== id)\n : [...collapsedIds, id];\n}\n\n/**\n * Every group-header row, top level first. Returns `null` when no visible\n * column declares a group. Contiguous same-path cells merge; a reorder that\n * breaks adjacency splits the group rather than teleporting it.\n */\nexport function headerGroupRows(\n columns: readonly ColumnDef[],\n collapsedIds: readonly string[] = [],\n collapsible = false,\n groups?: ReadonlyMap\n): HeaderGroupCell[][] | null {\n const paths = columns.map((column) => columnGroupPath(column));\n const maxDepth = paths.reduce((max, path) => Math.max(max, path.length), 0);\n if (maxDepth === 0) return null;\n const collapsed = new Set(collapsedIds);\n const rows: HeaderGroupCell[][] = [];\n for (let depth = 0; depth < maxDepth; depth += 1) {\n rows.push(\n headerGroupRowAt(columns, paths, collapsed, collapsible, depth, groups)\n );\n }\n return rows;\n}\n\nfunction headerGroupRowAt(\n columns: readonly ColumnDef[],\n paths: readonly (readonly string[])[],\n collapsed: ReadonlySet,\n collapsible: boolean,\n depth: number,\n groups?: ReadonlyMap\n): HeaderGroupCell[] {\n const cells: HeaderGroupCell[] = [];\n for (let index = 0; index < columns.length; index += 1) {\n const path = paths[index] ?? [];\n const label = path[depth] ?? null;\n const id = label === null ? null : columnGroupId(path.slice(0, depth + 1));\n const last = cells.at(-1);\n const stub = isColumnGroupStubKey(columns[index]?.key ?? \"\");\n if (last?.label === label && last.id === id) {\n last.span += 1;\n if (!stub) last.hideLabel = false;\n continue;\n }\n const collapsedHere = id !== null && collapsed.has(id);\n cells.push({\n key: `${id ?? \"gap\"}-${depth}-${cells.length}`,\n label,\n span: 1,\n id,\n collapsed: collapsedHere,\n collapsible: collapsible && id !== null,\n hideLabel: collapsedHere && stub,\n align: id === null ? undefined : groups?.get(id)?.align,\n });\n }\n return cells;\n}\n\n/**\n * The top group-header row. `null` when no visible column declares a group.\n * Groups are adjacency-based — if the user reorders columns apart, the\n * group SPLITS rather than lying about the layout.\n */\nexport function headerGroupRow(\n columns: readonly ColumnDef[]\n): HeaderGroupCell[] | null {\n return headerGroupRows(columns)?.[0] ?? null;\n}\n\n/** Visible group caption; `null` when the collapsed stub hides the name. */\nexport function columnGroupHeaderCaption(cell: HeaderGroupCell): string | null {\n if (cell.hideLabel) return null;\n return cell.label;\n}\n\n/**\n * One cell in {@link htmlGroupedHeaderPlan}. Group cells span children\n * horizontally; leaf cells rowspan through the group band so an ungrouped\n * Person sits beside Delivery and its children — Ant's nested header, on\n * an HTML table. A collapsed `collapsedRender` / stub group rowspans the\n * same way: no second header row, no line under the title. `collapsedKey`\n * keeps the child header, so that group stays two rows.\n */\nexport type HtmlGroupedHeaderCell =\n | {\n readonly kind: \"group\";\n readonly key: string;\n readonly colSpan: number;\n readonly rowSpan: number;\n readonly cell: HeaderGroupCell;\n }\n | {\n readonly kind: \"leaf\";\n readonly key: string;\n readonly columnIndex: number;\n readonly rowSpan: number;\n };\n\n/**\n * Header rows for HTML-table kits. `null` when no column declares a group.\n * Ant folds the same model into native `children`; this plan is that tree\n * flattened into `rowSpan` / `colSpan` so Mantine, MUI, and the rest match.\n */\nexport function htmlGroupedHeaderPlan(\n columns: readonly ColumnDef[],\n collapsedIds: readonly string[] = [],\n collapsible = false,\n groups?: ReadonlyMap\n): HtmlGroupedHeaderCell[][] | null {\n const groupRows = headerGroupRows(columns, collapsedIds, collapsible, groups);\n if (!groupRows) return null;\n const depth = groupRows.length;\n const paths = columns.map((column) => columnGroupPath(column));\n const totalRows =\n depth + (needsChildHeaderRow(columns, paths, depth) ? 1 : 0);\n const plan: HtmlGroupedHeaderCell[][] = Array.from(\n { length: totalRows },\n () => []\n );\n fillGroupLevels(plan, groupRows, columns, paths, totalRows, depth);\n if (totalRows > depth) fillChildHeaderRow(plan, columns, paths, depth);\n return plan;\n}\n\nfunction needsChildHeaderRow(\n columns: readonly ColumnDef[],\n paths: readonly (readonly string[])[],\n depth: number\n): boolean {\n return columns.some((column, index) => {\n if ((paths[index]?.length ?? 0) !== depth) return false;\n return !isColumnGroupSummaryKey(column.key);\n });\n}\n\nfunction fillGroupLevels(\n plan: HtmlGroupedHeaderCell[][],\n groupRows: HeaderGroupCell[][],\n columns: readonly ColumnDef[],\n paths: readonly (readonly string[])[],\n totalRows: number,\n depth: number\n): void {\n for (let level = 0; level < depth; level += 1) {\n let col = 0;\n for (const cell of groupRows[level] ?? []) {\n if (cell.label === null) {\n col = fillGapLeaves(\n plan,\n columns,\n paths,\n col,\n cell.span,\n level,\n totalRows\n );\n continue;\n }\n const summary = spanIsSummaryOnly(columns, col, cell.span);\n plan[level]?.push({\n kind: \"group\",\n key: cell.key,\n colSpan: cell.span,\n rowSpan: summary ? totalRows - level : 1,\n cell,\n });\n col += cell.span;\n }\n }\n}\n\nfunction fillGapLeaves(\n plan: HtmlGroupedHeaderCell[][],\n columns: readonly ColumnDef[],\n paths: readonly (readonly string[])[],\n start: number,\n span: number,\n level: number,\n totalRows: number\n): number {\n let col = start;\n for (let step = 0; step < span; step += 1) {\n const pathLen = paths[col]?.length ?? 0;\n const column = columns[col];\n if (pathLen === level && column) {\n plan[level]?.push({\n kind: \"leaf\",\n key: column.key,\n columnIndex: col,\n rowSpan: totalRows - level,\n });\n }\n col += 1;\n }\n return col;\n}\n\nfunction fillChildHeaderRow(\n plan: HtmlGroupedHeaderCell[][],\n columns: readonly ColumnDef[],\n paths: readonly (readonly string[])[],\n depth: number\n): void {\n for (let index = 0; index < columns.length; index += 1) {\n const column = columns[index];\n if (!column) continue;\n if ((paths[index]?.length ?? 0) !== depth) continue;\n if (isColumnGroupSummaryKey(column.key)) continue;\n plan[depth]?.push({\n kind: \"leaf\",\n key: column.key,\n columnIndex: index,\n rowSpan: 1,\n });\n }\n}\n\nfunction spanIsSummaryOnly(\n columns: readonly ColumnDef[],\n start: number,\n span: number\n): boolean {\n if (span <= 0) return false;\n for (let step = 0; step < span; step += 1) {\n const column = columns[start + step];\n if (!column || !isColumnGroupSummaryKey(column.key)) return false;\n }\n return true;\n}\n","import type { ReactNode } from \"react\";\n\nimport type { ColumnDef, ColumnGroupShow } from \"../types\";\nimport {\n COLUMN_GROUP_ID_SEP,\n COLUMN_GROUP_RENDER_PREFIX,\n COLUMN_GROUP_STUB_PREFIX,\n COLUMN_GROUP_STUB_WIDTH,\n columnGroupId,\n columnGroupPath,\n type GroupedHeaderAlign,\n isColumnGroupRenderKey,\n isColumnGroupStubKey,\n} from \"./headerGroups\";\n\n/**\n * A parent header with its own children. Collapse options live here, not\n * on the table: each group decides whether a collapsed state is an arrow\n * stub, a kept child, or a cell the host draws.\n */\nexport interface ColumnGroupDef {\n /** Caption on the spanning header cell, and the group's id. */\n readonly header: string;\n /** Nested groups or leaf columns. */\n readonly children: readonly ColumnInput[];\n /**\n * Leaf `key` to keep when this group is collapsed. Omit with\n * {@link ColumnGroupDef.collapsedRender} omitted for an arrow stub.\n */\n readonly collapsedKey?: string;\n /**\n * Cell shown for every row while this group is collapsed. Takes\n * precedence over {@link ColumnGroupDef.collapsedKey}.\n */\n readonly collapsedRender?: (row: TRow) => ReactNode;\n /**\n * Keep these children adjacent through reorder. Default `true` for a\n * tree group; the flat `column.group` shortcut still splits on drag.\n */\n readonly marryChildren?: boolean;\n /** Native tooltip on the group header, when set. */\n readonly headerTooltip?: string;\n /**\n * Alignment of this group's spanning header. Default `\"center\"` — the\n * value adapters used when this was hardcoded. Pass `\"start\"` or `\"end\"`\n * to opt out.\n */\n readonly align?: GroupedHeaderAlign;\n}\n\n/** A leaf {@link ColumnDef} or a {@link ColumnGroupDef} parent. */\nexport type ColumnInput = ColumnDef | ColumnGroupDef;\n\n/** Collapse policy recorded for one parent while flattening a tree. */\nexport interface ColumnGroupRecord {\n readonly id: string;\n readonly label: string;\n readonly collapsedKey?: string;\n readonly collapsedRender?: (row: TRow) => ReactNode;\n readonly marryChildren: boolean;\n readonly headerTooltip?: string;\n readonly align?: GroupedHeaderAlign;\n readonly childKeys: readonly string[];\n}\n\n/** True when this column input is a parent with children. */\nexport function isColumnGroup(\n column: ColumnInput\n): column is ColumnGroupDef {\n return \"children\" in column && Array.isArray(column.children);\n}\n\n/**\n * Flatten a mixed column tree into leaves. Tree parents become `group`\n * paths on those leaves; collapse options are in {@link FlattenedColumns.groups}.\n */\nexport function flattenColumnTree(\n columns: readonly ColumnInput[]\n): FlattenedColumns {\n const leaves: ColumnDef[] = [];\n const groups = new Map>();\n walk(columns, [], leaves, groups);\n for (const leaf of leaves) {\n const path = columnGroupPath(leaf);\n for (let depth = 1; depth <= path.length; depth += 1) {\n const id = columnGroupId(path.slice(0, depth));\n groups.get(id)?.childKeys.push(leaf.key);\n }\n }\n const frozen = new Map>();\n for (const [id, record] of groups) {\n frozen.set(id, { ...record, childKeys: [...record.childKeys] });\n }\n return { leaves, groups: frozen };\n}\n\n/** Leaves plus the parent records {@link flattenColumnTree} collected. */\nexport interface FlattenedColumns {\n readonly leaves: ColumnDef[];\n readonly groups: ReadonlyMap>;\n}\n\n/**\n * Hide leaves under collapsed groups according to each parent's options.\n *\n * Default (no `collapsedKey`, no `collapsedRender`, no `groupShow: \"closed\"`\n * child): a thin stub column. `collapsedRender` wins over `collapsedKey`.\n */\nexport function applyCollapsedColumnGroups(\n columns: readonly ColumnDef[],\n collapsedIds: readonly string[],\n groups: ReadonlyMap> = new Map()\n): readonly ColumnDef[] {\n if (collapsedIds.length === 0) return columns;\n const collapsed = new Set(collapsedIds);\n const keep = columns.map((column) =>\n shouldKeepLeaf(column, collapsed, groups)\n );\n const inserted = new Set();\n const out: ColumnDef[] = [];\n for (let index = 0; index < columns.length; index += 1) {\n const column = columns[index]!;\n if (keep[index] === true) {\n out.push(column);\n // A later contiguous run of the same group (flat `group:` split by\n // reorder) gets its own stub rather than vanishing with no chrome.\n inserted.clear();\n continue;\n }\n appendCollapsedChrome(column, index, {\n columns,\n keep,\n collapsed,\n groups,\n inserted,\n out,\n });\n }\n return out;\n}\n\n/**\n * True when `nextOrder` still keeps every married group's children in one\n * contiguous block. Used to reject a reorder that would split a tree group.\n */\nexport function marriedOrderHolds(\n nextOrder: readonly string[],\n groups: ReadonlyMap>\n): boolean {\n for (const record of groups.values()) {\n if (!record.marryChildren) continue;\n const childKeys = new Set(record.childKeys);\n const hits: number[] = [];\n for (let index = 0; index < nextOrder.length; index += 1) {\n if (childKeys.has(nextOrder[index]!)) hits.push(index);\n }\n if (hits.length <= 1) continue;\n const first = hits[0]!;\n const last = hits.at(-1)!;\n if (last - first !== hits.length - 1) return false;\n }\n return true;\n}\n\ninterface MutableGroup {\n id: string;\n label: string;\n collapsedKey?: string;\n collapsedRender?: (row: TRow) => ReactNode;\n marryChildren: boolean;\n headerTooltip?: string;\n align?: GroupedHeaderAlign;\n childKeys: string[];\n}\n\nfunction walk(\n nodes: readonly ColumnInput[],\n path: readonly string[],\n leaves: ColumnDef[],\n groups: Map>\n): void {\n for (const node of nodes) {\n if (isColumnGroup(node)) {\n const nextPath = [...path, node.header];\n const id = columnGroupId(nextPath);\n groups.set(id, {\n id,\n label: node.header,\n collapsedKey: node.collapsedKey,\n collapsedRender: node.collapsedRender,\n marryChildren: node.marryChildren ?? true,\n headerTooltip: node.headerTooltip,\n align: node.align,\n childKeys: [],\n });\n walk(node.children, nextPath, leaves, groups);\n continue;\n }\n leaves.push({\n ...node,\n group: inheritedGroup(node, path),\n });\n }\n}\n\nfunction inheritedGroup(\n node: ColumnDef,\n path: readonly string[]\n): ColumnDef[\"group\"] {\n let group: ColumnDef[\"group\"] = node.group;\n if (path.length === 1) {\n group = path[0];\n } else if (path.length > 1) {\n group = path;\n }\n return group;\n}\n\nfunction appendCollapsedChrome(\n column: ColumnDef,\n index: number,\n pass: {\n columns: readonly ColumnDef[];\n keep: readonly boolean[];\n collapsed: ReadonlySet;\n groups: ReadonlyMap>;\n inserted: Set;\n out: ColumnDef[];\n }\n): void {\n for (const id of collapsedAncestors(column, pass.collapsed)) {\n if (pass.inserted.has(id)) continue;\n if (groupHasKeptLeaf(id, pass.columns, pass.keep)) {\n pass.inserted.add(id);\n continue;\n }\n const record = pass.groups.get(id);\n const path = id.split(COLUMN_GROUP_ID_SEP);\n pass.out.push(\n record?.collapsedRender\n ? renderColumn(id, path, record, index)\n : stubColumn(id, path, record, index)\n );\n pass.inserted.add(id);\n }\n}\n\nfunction collapsedAncestors(\n column: ColumnDef,\n collapsed: ReadonlySet\n): string[] {\n const path = columnGroupPath(column);\n const ids: string[] = [];\n for (let depth = 1; depth <= path.length; depth += 1) {\n const id = columnGroupId(path.slice(0, depth));\n if (collapsed.has(id)) ids.push(id);\n }\n return ids;\n}\n\nfunction shouldKeepLeaf(\n column: ColumnDef,\n collapsed: ReadonlySet,\n groups: ReadonlyMap>\n): boolean {\n if (isColumnGroupStubKey(column.key) || isColumnGroupRenderKey(column.key)) {\n return false;\n }\n const ancestors = collapsedAncestors(column, collapsed);\n if (ancestors.length === 0) return true;\n for (const id of ancestors) {\n const show = resolveGroupShow(column, groups.get(id));\n if (show === \"always\") continue;\n if (show === \"closed\") continue;\n return false;\n }\n return true;\n}\n\nfunction resolveGroupShow(\n column: ColumnDef,\n record: ColumnGroupRecord | undefined\n): ColumnGroupShow {\n if (column.groupShow !== undefined) return column.groupShow;\n if (record?.collapsedRender) return \"open\";\n if (record?.collapsedKey === column.key) return \"closed\";\n return \"open\";\n}\n\nfunction groupHasKeptLeaf(\n id: string,\n columns: readonly ColumnDef[],\n keep: readonly boolean[]\n): boolean {\n return columns.some((column, index) => {\n if (keep[index] !== true) return false;\n return collapsedAncestors(column, new Set([id])).length > 0;\n });\n}\n\nfunction stubColumn(\n id: string,\n path: readonly string[],\n record: ColumnGroupRecord | undefined,\n index: number\n): ColumnDef {\n return {\n key: `${COLUMN_GROUP_STUB_PREFIX}${id}:${String(index)}`,\n header: \"\",\n headerTooltip: record?.headerTooltip,\n width: COLUMN_GROUP_STUB_WIDTH,\n minWidth: COLUMN_GROUP_STUB_WIDTH,\n maxWidth: COLUMN_GROUP_STUB_WIDTH,\n accessor: () => null,\n group: path.length === 1 ? path[0] : path,\n hideOnMobile: true,\n sortable: false,\n };\n}\n\nfunction renderColumn(\n id: string,\n path: readonly string[],\n record: ColumnGroupRecord,\n index: number\n): ColumnDef {\n const render = record.collapsedRender;\n return {\n key: `${COLUMN_GROUP_RENDER_PREFIX}${id}:${String(index)}`,\n header: \"\",\n headerTooltip: record.headerTooltip,\n width: 180,\n accessor: render ? (row) => render(row) : () => null,\n group: path.length === 1 ? path[0] : path,\n sortable: false,\n };\n}\n","import type { ColumnDef } from \"../types\";\n\n/** A column identity for width resolution — just its key and declared width. */\ntype WidthColumn = Pick, \"key\" | \"width\">;\n\n/** Fallback width (px) for a pinned column with no resolvable declared width. */\nexport const FALLBACK_PIN_WIDTH = 150;\n\n/**\n * Parse a declared column width to pixels, or `undefined` when it carries no\n * pixel value (relative units like `%`, `rem`, `fr` have no px here, so\n * `parseInt(\"50%\")` → 50 would silently corrupt a sticky inset / min-width).\n */\nexport function parsePxWidth(\n width: number | string | undefined\n): number | undefined {\n if (typeof width === \"number\") return width;\n if (\n typeof width === \"string\" &&\n /^\\d+(?:\\.\\d+)?(?:px)?$/.test(width.trim())\n ) {\n return Number.parseFloat(width);\n }\n return undefined;\n}\n\n/**\n * A column's effective pixel width: a resize override (from the layout\n * `widths` map) wins over the declared width. `undefined` when neither\n * resolves to pixels.\n */\nexport function resolveColumnWidth(\n column: WidthColumn,\n widths?: Readonly>\n): number | undefined {\n const override = widths?.[column.key];\n if (typeof override === \"number\") return override;\n return parsePxWidth(column.width);\n}\n\n/**\n * Total pixel width of the fixed-width columns, plus any extra leading/trailing\n * fixed columns (selection checkbox, actions). Columns without a px width\n * contribute nothing, so a table with no declared widths returns `0` and is\n * never forced to a min-width. Adapters apply the result as the table's\n * `min-width` so a fixed-width table scrolls horizontally instead of squishing\n * its columns below their declared sizes.\n *\n * @typeParam TRow - The row type.\n * @param columns - The visible columns.\n * @param options - `widths` resize overrides; `extra` px for non-data columns.\n * @returns The min table width in px, or `0` when no column declares a width.\n */\nexport function tableMinWidth(\n columns: readonly ColumnDef[],\n options: { widths?: Readonly>; extra?: number } = {}\n): number {\n const total = columns.reduce(\n (sum, column) => sum + (resolveColumnWidth(column, options.widths) ?? 0),\n 0\n );\n return total > 0 ? total + (options.extra ?? 0) : 0;\n}\n\n/**\n * The pixel width to RENDER a pinned column at: its resolved width, else\n * {@link FALLBACK_PIN_WIDTH}. Pin insets are summed from these same numbers\n * (see `pinOffset`), so applying this width to pinned header cells keeps\n * stacked pins flush — a natural-width pinned column would otherwise render\n * narrower or wider than the inset math assumed.\n *\n * @param column - The pinned column.\n * @param widths - Resize overrides from the column layout.\n */\nexport function pinnedColumnWidth(\n column: WidthColumn,\n widths?: Readonly>\n): number {\n return resolveColumnWidth(column, widths) ?? FALLBACK_PIN_WIDTH;\n}\n","import { useCallback, useMemo, useRef, useState } from \"react\";\n\nimport type { ColumnDef } from \"../types\";\nimport {\n applyCollapsedColumnGroups,\n type ColumnGroupRecord,\n marriedOrderHolds,\n} from \"./columnTree\";\nimport { FALLBACK_PIN_WIDTH, parsePxWidth } from \"./columnWidths\";\nimport { toggleCollapsedColumnGroup } from \"./headerGroups\";\n\n/** Edge a column can be pinned to — logical, so it follows the writing\n * direction (`\"start\"` is the right edge under `dir=\"rtl\"`). */\nexport type PinSide = \"start\" | \"end\";\n\n/**\n * User-driven column layout: which columns are hidden, their order, pinning,\n * and widths. Keyed by column `key`. Empty `order` means \"declared order\".\n */\nexport interface ColumnLayoutState {\n /** Column keys hidden by the user. */\n hidden: readonly string[];\n /** Explicit column order by key; empty falls back to declared order. */\n order: readonly string[];\n /** Per-column edge pinning. */\n pinned: Readonly>;\n /** Per-column pixel widths. */\n widths: Readonly>;\n /** Collapsed column-group ids. Omit or empty — every group is open. */\n collapsedGroups?: readonly string[];\n}\n\n/** An empty layout — declared order, nothing hidden/pinned/resized. */\nexport const EMPTY_COLUMN_LAYOUT: ColumnLayoutState = {\n hidden: [],\n order: [],\n pinned: {},\n widths: {},\n};\n\n/** Options for {@link useColumnLayout}. */\nexport interface UseColumnLayoutOptions {\n /** All declared columns (already filtered for the current device layout). */\n columns: readonly ColumnDef[];\n /** Controlled layout state. Omit for uncontrolled (internal) state. */\n layout?: ColumnLayoutState;\n /** Change handler; required for the controlled mode to update. */\n onLayoutChange?: (next: ColumnLayoutState) => void;\n /** Initial layout for the uncontrolled mode. */\n defaultColumnLayout?: Partial;\n /**\n * When true, `visibleColumns` hides leaves under a collapsed group\n * according to that group's collapse options. Omit and collapse is inert.\n */\n collapsibleColumnGroups?: boolean;\n /** Tree-group collapse options from {@link flattenColumnTree}. */\n columnGroups?: ReadonlyMap>;\n}\n\n/** Result of {@link useColumnLayout}. */\nexport interface UseColumnLayoutResult {\n /** The current layout state (controlled value or internal). */\n state: ColumnLayoutState;\n /** Declared columns reordered then filtered by the user's hidden set. */\n visibleColumns: ColumnDef[];\n /** Whether a column key is currently hidden. */\n isHidden: (key: string) => boolean;\n /** Show/hide a single column. */\n setHidden: (key: string, hidden: boolean) => void;\n /** Toggle a single column's visibility. */\n toggleVisible: (key: string) => void;\n /** Pin a column to an edge, or unpin it with `undefined`. */\n setPinned: (key: string, side: PinSide | undefined) => void;\n /** Move a column to a new index among the visible columns. */\n move: (key: string, toIndex: number) => void;\n /** Set (or clear, with `undefined`) a column's pixel width. */\n setWidth: (key: string, width: number | undefined) => void;\n /** Sticky inset (px) for a pinned column, by side. `undefined` if unpinned. */\n pinOffset: (key: string) => PinOffset | undefined;\n /** Restore the empty layout (all visible, declared order). */\n reset: () => void;\n /** Collapse or expand a column group by id. No-op unless collapse is armed. */\n toggleColumnGroup: (id: string) => void;\n}\n\n/** A pinned column's side plus its sticky inset in px. */\nexport interface PinOffset {\n side: PinSide;\n inset: number;\n}\n\n/**\n * Minimal sticky-positioning style for a pinned cell, from a pin offset.\n * Uses logical inset properties so pinning follows the writing direction:\n * a `\"start\"`-pinned column sticks to the inline START (the right edge under\n * `dir=\"rtl\"`), matching antd's native `fixed` behaviour.\n */\nexport interface PinnedCellStyle {\n position: \"sticky\";\n insetInlineStart?: number;\n insetInlineEnd?: number;\n zIndex: number;\n}\n\n/**\n * Stacking order for sticky table cells, lowest → highest. A pinned body cell\n * must sit above plain scrolled cells; a sticky header above all body cells;\n * and a pinned header (the corner) above everything — otherwise a pinned\n * column's body cells paint over the sticky header on vertical scroll, and\n * later headers paint over a pinned header on horizontal scroll.\n */\nexport const PIN_Z = {\n body: 1,\n /** Sticky pinned rows — above scrolled body, below the header. */\n rowPinned: 2,\n /** A pinned column cell inside a pinned row. */\n rowPinnedColumn: 3,\n header: 4,\n headerPinned: 5,\n} as const;\n\n/**\n * Extra inset (px) the leading selection column / trailing actions column add\n * in front of the pinned data columns, so a start-pinned column sits just after\n * a pinned checkbox and an end-pinned column just before pinned actions.\n */\nexport interface PinLeads {\n start?: number;\n end?: number;\n}\n\n/** Map a pin side to its logical inset property. */\nfunction insetProp(side: PinSide): \"insetInlineStart\" | \"insetInlineEnd\" {\n return side === \"start\" ? \"insetInlineStart\" : \"insetInlineEnd\";\n}\n\n/**\n * Build the sticky style for a pinned header/body cell from its pin offset.\n * Adapters spread this onto the cell and add their own opaque background.\n * `leads` shifts the cell past a pinned selection/actions edge column. Returns\n * undefined for an unpinned cell. The inset is logical (`insetInlineStart` /\n * `insetInlineEnd`), so the same style pins to the correct edge in RTL.\n */\nexport function pinnedCellStyle(\n offset: PinOffset | undefined,\n zIndex = 1,\n leads?: PinLeads\n): PinnedCellStyle | undefined {\n if (!offset) return undefined;\n const lead = leads?.[offset.side] ?? 0;\n return {\n position: \"sticky\",\n [insetProp(offset.side)]: offset.inset + lead,\n zIndex,\n };\n}\n\n/**\n * Sticky style for a leading/trailing non-data column (the selection checkbox\n * at the inline start, row actions at the inline end) so it pins flush to the\n * edge whenever a data column on that side is pinned. `active` is false when\n * nothing on that side is pinned, in which case the column stays in normal\n * flow. Insets are logical, so the edge follows the writing direction.\n */\nexport function edgePinStyle(\n side: PinSide,\n active: boolean,\n zIndex: number = PIN_Z.body\n): PinnedCellStyle | undefined {\n if (!active) return undefined;\n return { position: \"sticky\", [insetProp(side)]: 0, zIndex };\n}\n\n/** Order `columns` by an explicit key order, appending any unlisted columns. */\nexport function applyColumnOrder(\n columns: readonly ColumnDef[],\n order: readonly string[]\n): ColumnDef[] {\n if (order.length === 0) return [...columns];\n const byKey = new Map(columns.map((c) => [c.key, c]));\n const ordered: ColumnDef[] = [];\n for (const key of order) {\n const col = byKey.get(key);\n if (col) {\n ordered.push(col);\n byKey.delete(key);\n }\n }\n // Columns not named in `order` keep their declared order at the end.\n for (const col of columns) if (byKey.has(col.key)) ordered.push(col);\n return ordered;\n}\n\n/**\n * Headless column-layout state. Uncontrolled by default; pass `layout` +\n * `onLayoutChange` to control it (and persist however you like — localStorage,\n * URL, server). Returns the reordered, visibility-filtered columns to render.\n *\n * @typeParam TRow - The row type.\n */\nexport function useColumnLayout({\n columns,\n layout,\n onLayoutChange,\n defaultColumnLayout,\n collapsibleColumnGroups = false,\n columnGroups,\n}: UseColumnLayoutOptions): UseColumnLayoutResult {\n const [internal, setInternal] = useState(() => ({\n ...EMPTY_COLUMN_LAYOUT,\n ...defaultColumnLayout,\n }));\n const state = layout ?? internal;\n\n // Mutators read through this ref so two mutations in ONE event handler\n // compose (the second sees the first's result) instead of the last write\n // silently winning. `commit` advances it optimistically; renders re-sync it.\n const stateRef = useRef(state);\n stateRef.current = state;\n\n const commit = useCallback(\n (next: ColumnLayoutState) => {\n stateRef.current = next;\n if (layout === undefined) setInternal(next);\n onLayoutChange?.(next);\n },\n [layout, onLayoutChange]\n );\n\n const isHidden = useCallback(\n (key: string) => state.hidden.includes(key),\n [state.hidden]\n );\n\n const setHidden = useCallback(\n (key: string, hidden: boolean) => {\n const current = stateRef.current;\n const has = current.hidden.includes(key);\n if (has === hidden) return;\n const nextHidden = hidden\n ? [...current.hidden, key]\n : current.hidden.filter((k) => k !== key);\n commit({ ...current, hidden: nextHidden });\n },\n [commit]\n );\n\n const toggleVisible = useCallback(\n (key: string) => setHidden(key, !stateRef.current.hidden.includes(key)),\n [setHidden]\n );\n\n const setPinned = useCallback(\n (key: string, side: PinSide | undefined) => {\n const current = stateRef.current;\n const next = { ...current.pinned };\n if (side === undefined) delete next[key];\n else next[key] = side;\n commit({ ...current, pinned: next });\n },\n [commit]\n );\n\n const setWidth = useCallback(\n (key: string, width: number | undefined) => {\n const current = stateRef.current;\n const next = { ...current.widths };\n if (width === undefined) delete next[key];\n else next[key] = width;\n commit({ ...current, widths: next });\n },\n [commit]\n );\n\n const visibleColumns = useMemo(() => {\n const ordered = applyColumnOrder(columns, state.order).filter(\n (c) => !state.hidden.includes(c.key)\n );\n if (!collapsibleColumnGroups) return ordered;\n return [\n ...applyCollapsedColumnGroups(\n ordered,\n state.collapsedGroups ?? [],\n columnGroups\n ),\n ];\n }, [\n columns,\n state.order,\n state.hidden,\n state.collapsedGroups,\n collapsibleColumnGroups,\n columnGroups,\n ]);\n\n const toggleColumnGroup = useCallback(\n (id: string) => {\n if (!collapsibleColumnGroups) return;\n const current = stateRef.current;\n const nextIds = toggleCollapsedColumnGroup(\n current.collapsedGroups ?? [],\n id\n );\n commit({\n ...current,\n collapsedGroups: nextIds.length > 0 ? nextIds : undefined,\n });\n },\n [collapsibleColumnGroups, commit]\n );\n\n const move = useCallback(\n (key: string, toIndex: number) => {\n const latest = stateRef.current;\n // Operate on the FULL ordered list (visible + hidden) so hiding a column\n // never reorders the rest and reordering keeps hidden columns in place.\n const current = applyColumnOrder(columns, latest.order).map((c) => c.key);\n const from = current.indexOf(key);\n if (from === -1) return;\n const clamped = Math.max(0, Math.min(toIndex, current.length - 1));\n if (from === clamped) return;\n current.splice(from, 1);\n current.splice(clamped, 0, key);\n if (columnGroups && !marriedOrderHolds(current, columnGroups)) return;\n commit({ ...latest, order: current });\n },\n [commit, columns, columnGroups]\n );\n\n const reset = useCallback(() => commit(EMPTY_COLUMN_LAYOUT), [commit]);\n\n // Precompute every pinned column's inset once per layout change — adapters\n // call `pinOffset` per cell per render, so a lookup beats re-walking the\n // pinned set each time on wide tables.\n const pinInsets = useMemo(() => {\n const resolveWidth = (column: ColumnDef): number => {\n const override = state.widths[column.key];\n if (typeof override === \"number\") return override;\n // Only pixel widths can be summed into a sticky inset; relative units\n // have no px value here, so fall back to a sane default instead.\n return parsePxWidth(column.width) ?? FALLBACK_PIN_WIDTH;\n };\n const insets = new Map();\n for (const side of [\"start\", \"end\"] as const) {\n // Only VISIBLE pinned columns have a rendered cell to stick — a hidden\n // pinned key stays out of the map and reads back as unpinned.\n const samePinned = visibleColumns.filter(\n (c) => state.pinned[c.key] === side\n );\n // Start: sum widths before each column; end: sum widths after it.\n const ordered = side === \"start\" ? samePinned : [...samePinned].reverse();\n let inset = 0;\n for (const column of ordered) {\n insets.set(column.key, { side, inset });\n inset += resolveWidth(column);\n }\n }\n return insets;\n }, [state.pinned, state.widths, visibleColumns]);\n\n const pinOffset = useCallback(\n (key: string) => pinInsets.get(key),\n [pinInsets]\n );\n\n return {\n state,\n visibleColumns,\n isHidden,\n setHidden,\n toggleVisible,\n setPinned,\n move,\n setWidth,\n pinOffset,\n reset,\n toggleColumnGroup,\n };\n}\n","import type { ColumnDef } from \"../types\";\nimport type { PinSide, UseColumnLayoutResult } from \"./useColumnLayout\";\nimport { applyColumnOrder } from \"./useColumnLayout\";\n\n/** Readable label for a column in the menu (header string → mobileLabel → key). */\nexport function columnMenuLabel(column: ColumnDef): string {\n if (typeof column.header === \"string\") return column.header;\n return column.mobileLabel ?? column.key;\n}\n\n/** Edge a column is pinned to, or `undefined` when unpinned. */\nexport type PinnedSide = PinSide | undefined;\n\n/** One row of the column-management menu, with its derived display state. */\nexport interface ColumnMenuRow {\n column: ColumnDef;\n key: string;\n name: string;\n /** Hidden columns keep their position; only the eye toggles. */\n hidden: boolean;\n /** Edge the column is pinned to, or `undefined` when unpinned. */\n pinned: PinnedSide;\n /** Index in the full column order (visible + hidden) — the reorder target. */\n index: number;\n /** False when `column.lockPosition` is set. */\n canMove: boolean;\n /** False when `column.lockVisibility` is set. */\n canHide: boolean;\n /** False when `column.lockPin` is set. */\n canPin: boolean;\n /** False when `column.lockWidth` is set. */\n canResize: boolean;\n /** True when the column declared `sortable`. */\n canSort: boolean;\n /** True when the column declared a `filter`. */\n canFilter: boolean;\n}\n\n/**\n * Toggle a DATA column's start pin: none ↔ start (`\"start\"` = the logical\n * inline-start edge, which is the right edge under `dir=\"rtl\"`). Data columns\n * never pin to the END edge — that is reserved for the trailing actions column,\n * which has its own end-pin toggle. Pinning a leading data column to the\n * trailing edge has no value: it just sticky-travels across the row and\n * collides with the actions column.\n */\nexport function nextPinSide(current: PinnedSide): PinnedSide {\n return current === undefined ? \"start\" : undefined;\n}\n\n/**\n * The label for a data column's pin toggle — \"Pin to start\" when unpinned,\n * \"Unpin\" when pinned — so the accessible name always matches what the click\n * will do. (The actions column uses its own \"Pin to end\" / \"Unpin\" label.)\n */\nexport function pinActionLabel(\n current: PinnedSide,\n labels: { pinStart: string; unpin: string }\n): string {\n return current === undefined ? labels.pinStart : labels.unpin;\n}\n\n/**\n * Build the column-menu rows in the table's real order — visible and hidden\n * columns interleaved exactly as they appear (hiding never reorders the list).\n * Shared so all five adapters render an identical model and only differ in kit\n * markup.\n */\n/**\n * Reserved layout key for the injected row-actions column. It is not a\n * `ColumnDef`, but the layout state treats keys opaquely, so the actions\n * column hides (`hidden: [\"actions\"]`) and end-pins\n * (`pinned: { actions: \"end\" }`) like any data column — adapters list it\n * in the Columns menu with a visibility toggle and an end-pin toggle (no\n * reorder/resize; it always trails).\n */\nexport const ACTIONS_COLUMN_KEY = \"actions\";\n\n/**\n * Reserved layout key for the injected row-reorder column. Same deal as\n * {@link ACTIONS_COLUMN_KEY}: not a `ColumnDef`, but hideable and\n * start-pinnable through the layout because the key is just a string.\n */\nexport const REORDER_COLUMN_KEY = \"reorder\";\n\nexport function columnMenuRows(\n allColumns: readonly ColumnDef[],\n layout: UseColumnLayoutResult\n): ColumnMenuRow[] {\n return applyColumnOrder(allColumns, layout.state.order).map(\n (column, index) => ({\n column,\n key: column.key,\n name: columnMenuLabel(column),\n hidden: layout.isHidden(column.key),\n pinned: layout.state.pinned[column.key],\n index,\n canMove: column.lockPosition !== true,\n canHide: column.lockVisibility !== true,\n canPin: column.lockPin !== true,\n canResize: column.lockWidth !== true,\n canSort: column.sortable === true,\n canFilter: column.filter !== undefined,\n })\n );\n}\n\n/** Keep rows whose name or key contains the query (case-insensitive). */\nexport function filterColumnMenuRows(\n rows: readonly ColumnMenuRow[],\n query: string\n): ColumnMenuRow[] {\n const needle = query.trim().toLowerCase();\n if (needle === \"\") return [...rows];\n return rows.filter(\n (row) =>\n row.name.toLowerCase().includes(needle) ||\n row.key.toLowerCase().includes(needle)\n );\n}\n\n/** Show every unlocked hidden column. */\nexport function showAllColumns(\n rows: readonly ColumnMenuRow[],\n layout: UseColumnLayoutResult\n): void {\n for (const row of rows) {\n if (row.canHide && layout.isHidden(row.key)) {\n layout.setHidden(row.key, false);\n }\n }\n}\n\n/** Hide every unlocked visible column. */\nexport function hideAllColumns(\n rows: readonly ColumnMenuRow[],\n layout: UseColumnLayoutResult\n): void {\n for (const row of rows) {\n if (row.canHide && !layout.isHidden(row.key)) {\n layout.setHidden(row.key, true);\n }\n }\n}\n\n/** Unpin every unlocked pinned column. */\nexport function unpinAllColumns(\n rows: readonly ColumnMenuRow[],\n layout: UseColumnLayoutResult\n): void {\n for (const row of rows) {\n if (row.canPin && layout.state.pinned[row.key] !== undefined) {\n layout.setPinned(row.key, undefined);\n }\n }\n}\n\n/** Restore one column's visibility, pin and width. Locks still apply. */\nexport function resetColumnLayout(\n row: ColumnMenuRow,\n layout: UseColumnLayoutResult\n): void {\n if (row.canHide) layout.setHidden(row.key, false);\n if (row.canPin) layout.setPinned(row.key, undefined);\n if (row.canResize) layout.setWidth(row.key, undefined);\n}\n\n/** One action in a per-column submenu. */\nexport interface ColumnMenuAction {\n id: string;\n label: string;\n disabled: boolean;\n run: () => void;\n}\n\n/** What a submenu needs besides the row itself. */\nexport interface ColumnMenuActionContext {\n labels: ColumnMenuLabels;\n layout: UseColumnLayoutResult;\n sortBy?: string;\n sortDir?: \"asc\" | \"desc\";\n onSortColumn?: (key: string, dir: \"asc\" | \"desc\") => void;\n onAutoSizeColumn?: (key: string) => void;\n onFilterColumn?: (key: string) => void;\n}\n\n/** Sort, pin, hide, autosize, filter, reset — disabled when locked. */\nexport function columnMenuActions(\n row: ColumnMenuRow,\n ctx: ColumnMenuActionContext\n): ColumnMenuAction[] {\n const actions: ColumnMenuAction[] = [];\n if (row.canSort && ctx.onSortColumn) {\n actions.push(\n {\n id: \"sort-asc\",\n label: ctx.labels.sortAscending,\n disabled: ctx.sortBy === row.key && ctx.sortDir === \"asc\",\n run: () => ctx.onSortColumn?.(row.key, \"asc\"),\n },\n {\n id: \"sort-desc\",\n label: ctx.labels.sortDescending,\n disabled: ctx.sortBy === row.key && ctx.sortDir === \"desc\",\n run: () => ctx.onSortColumn?.(row.key, \"desc\"),\n }\n );\n }\n if (row.canPin) {\n actions.push(\n {\n id: \"pin-start\",\n label: ctx.labels.pinStart,\n disabled: row.pinned === \"start\",\n run: () => ctx.layout.setPinned(row.key, \"start\"),\n },\n {\n id: \"pin-end\",\n label: ctx.labels.pinEnd,\n disabled: row.pinned === \"end\",\n run: () => ctx.layout.setPinned(row.key, \"end\"),\n },\n {\n id: \"unpin\",\n label: ctx.labels.unpin,\n disabled: row.pinned === undefined,\n run: () => ctx.layout.setPinned(row.key, undefined),\n }\n );\n }\n if (row.canHide) {\n actions.push({\n id: row.hidden ? \"show\" : \"hide\",\n label: row.hidden ? ctx.labels.showColumn : ctx.labels.hideColumn,\n disabled: false,\n run: () => ctx.layout.toggleVisible(row.key),\n });\n }\n if (row.canResize && ctx.onAutoSizeColumn) {\n actions.push({\n id: \"auto-size\",\n label: ctx.labels.autoSizeColumn,\n disabled: false,\n run: () => ctx.onAutoSizeColumn?.(row.key),\n });\n }\n if (row.canFilter && ctx.onFilterColumn) {\n actions.push({\n id: \"filter\",\n label: ctx.labels.filterColumn,\n disabled: false,\n run: () => ctx.onFilterColumn?.(row.key),\n });\n }\n actions.push({\n id: \"reset\",\n label: ctx.labels.resetColumn,\n disabled: !row.canHide && !row.canPin && !row.canResize,\n run: () => resetColumnLayout(row, ctx.layout),\n });\n return actions;\n}\n\n/**\n * Labels every adapter's column menu needs (pre-translated by the caller).\n * Hoisted here so the five adapters share one contract instead of\n * re-declaring it.\n */\nexport interface ColumnMenuLabels {\n columns: string;\n pinStart: string;\n pinEnd: string;\n unpin: string;\n moveStart: string;\n moveEnd: string;\n resetColumns: string;\n /** \"Size columns to content\" — the menu's auto-size action. */\n autoSizeColumns: string;\n showColumn: string;\n hideColumn: string;\n searchColumns: string;\n showAllColumns: string;\n hideAllColumns: string;\n unpinAllColumns: string;\n resetColumn: string;\n sortAscending: string;\n sortDescending: string;\n filterColumn: string;\n columnActions: string;\n autoSizeColumn: string;\n}\n\n/** The shared prop surface of every adapter's ``. */\nexport interface ColumnMenuChromeProps {\n /** All declared columns (pre layout filtering). */\n allColumns: ColumnDef[];\n /** The user column-layout state + mutators. */\n layout: UseColumnLayoutResult;\n /** Resolved labels. */\n labels: ColumnMenuLabels;\n}\n","/**\n * Progressive column hiding: which columns a narrow container can afford.\n *\n * Between \"wide enough for everything\" and \"narrow enough for cards\" there is\n * a long middle where a table has too many columns and no good answer. The\n * usual outcomes are a horizontal scrollbar the reader never finds, or columns\n * squeezed until nothing is legible. Neither is a decision — they are what\n * happens when nobody made one.\n *\n * `responsivePriority` is that decision, made once by the person who knows\n * the data: number the columns you are willing to lose, and they go in that\n * order as the space runs out.\n *\n * Two rules keep it predictable:\n *\n * A column without a `responsivePriority` is never dropped. That is what\n * makes the feature opt-in — a table that declares none behaves exactly as\n * before — and it means the columns that carry the row's identity stay put by\n * saying nothing.\n *\n * Dropping is by *declared* width, not by measuring the rendered table. A\n * measured version would have to render, observe, drop, re-render and observe\n * again, and that loop is what produces the flicker you see in tables that do\n * it. Arithmetic on the widths the columns already declare settles in one\n * pass, gives the same answer every time, and is the same number the table's\n * own `min-width` is built from.\n */\nimport type { ColumnDef } from \"../types\";\nimport { resolveColumnWidth } from \"./columnWidths\";\n\n/**\n * Width assumed for a column that declares none. Progressive hiding needs a\n * number for every column, and a table whose columns are all auto-width would\n * otherwise budget them at zero and drop nothing.\n */\nexport const ASSUMED_COLUMN_WIDTH = 150;\n\n/** What {@link responsiveColumns} needs to know about the container. */\nexport interface ResponsiveFit {\n /** The columns in render order, after the user's own hiding. */\n columns: ColumnDef[];\n /** The width available, in pixels. `undefined` before the first measure. */\n available: number | undefined;\n /** Resize overrides from the column layout. */\n widths?: Readonly>;\n /** Pixels claimed by non-data columns — selection checkbox, row actions. */\n extra?: number;\n}\n\n/** The result of fitting columns to a container. */\nexport interface ResponsiveColumns {\n /**\n * The columns that fit, in their original order — and the very same array\n * when nothing was dropped, so the rows this feeds keep their memoization.\n */\n columns: ColumnDef[];\n /** Keys dropped to make them fit, in the order they were dropped. */\n dropped: readonly string[];\n}\n\n/** A column's width for budgeting: declared, resized, or assumed. */\nfunction budgetWidth(\n column: ColumnDef,\n widths: Readonly> | undefined\n): number {\n return resolveColumnWidth(column, widths) ?? ASSUMED_COLUMN_WIDTH;\n}\n\n/**\n * The order columns are given up in: highest `responsivePriority` first, and\n * among equals the one furthest right. Numbering follows the ordinary sense\n * of the word — priority 1 is the one you keep longest.\n */\nfunction dropOrder(\n columns: readonly ColumnDef[]\n): readonly ColumnDef[] {\n return columns\n .map((column, index) => ({ column, index }))\n .filter((entry) => entry.column.responsivePriority !== undefined)\n .sort((a, b) => {\n const byPriority =\n (b.column.responsivePriority ?? 0) - (a.column.responsivePriority ?? 0);\n return byPriority === 0 ? b.index - a.index : byPriority;\n })\n .map((entry) => entry.column);\n}\n\n/**\n * Fit columns to the available width, giving up the ones the table was told\n * it could give up.\n *\n * @typeParam TRow - The row type.\n * @param fit - The columns, the width to fit them in, and the widths to use.\n * @returns The columns that fit and the keys dropped to get there.\n */\nexport function responsiveColumns({\n columns,\n available,\n widths,\n extra = 0,\n}: ResponsiveFit): ResponsiveColumns {\n const droppable = dropOrder(columns);\n // Nothing declared, or nothing measured yet: never guess at a narrower\n // table than the one that was asked for.\n if (droppable.length === 0 || available === undefined) {\n return { columns, dropped: [] };\n }\n\n let width =\n columns.reduce((sum, column) => sum + budgetWidth(column, widths), 0) +\n extra;\n const dropped: string[] = [];\n for (const column of droppable) {\n if (width <= available) break;\n width -= budgetWidth(column, widths);\n dropped.push(column.key);\n }\n\n if (dropped.length === 0) return { columns, dropped: [] };\n const gone = new Set(dropped);\n return {\n columns: columns.filter((column) => !gone.has(column.key)),\n dropped,\n };\n}\n","/**\n * Editing lifecycle events — observe a commit, never own it.\n *\n * Integrators hook these for analytics, toasts and side effects. A handler\n * that throws, returns a value, or tries to rewrite the payload must not be\n * able to change whether a commit lands: the table already decided, and the\n * events only report what happened.\n */\nimport { useMemo } from \"react\";\n\nimport { useEventCallback } from \"../hooks/useEventCallback\";\nimport { devWarn } from \"../utils/devWarn\";\n\n/** Which commit unit produced an event. */\nexport type EditUnit = \"cell\" | \"row\" | \"batch\";\n\n/**\n * One lifecycle event. `columnKey` is the edited field for a cell, and empty\n * for a row or batch whose payload is the whole patch (or list of patches).\n */\nexport interface EditEvent {\n /** The row as it was when the gesture started. */\n row: TRow;\n /** Its stable id. */\n rowId: string;\n /** The column, or `\"\"` when the unit is the whole row or a batch. */\n columnKey: string;\n /** What the reader arrived at — the parsed value, the patch, or the edits. */\n value: unknown;\n /** What was there before. */\n previousValue: unknown;\n /** Which commit unit fired this. */\n unit: EditUnit;\n /** Why a commit was refused, or why a save rejected. */\n error?: string;\n}\n\n/** A host callback that observes one kind of event. */\nexport type EditEventHandler = (event: EditEvent) => void;\n\n/** The five observers a host may wire. All optional, all inert when omitted. */\nexport interface EditLifecycle {\n /** An editor opened. */\n onEditStart?: EditEventHandler;\n /** The reader threw the draft away. */\n onEditCancel?: EditEventHandler;\n /** The host received the value. */\n onEditCommit?: EditEventHandler;\n /** A validator refused the value; the editor stayed open. */\n onValidationFail?: EditEventHandler;\n /** A save promise rejected. */\n onEditError?: EditEventHandler;\n}\n\n/**\n * Call an observer without letting it own the outcome. A throw is reported\n * and swallowed: the commit already happened, or the cancel already did, and\n * a side-effect that blows up must not rewind it.\n */\nexport function observeEdit(\n handler: EditEventHandler | undefined,\n event: EditEvent\n): void {\n if (!handler) return;\n try {\n handler(event);\n } catch (error) {\n const detail = error instanceof Error ? error.message : String(error);\n devWarn(\n `an onEdit* handler threw (${detail}) — the table ignored it so the commit could finish`\n );\n }\n}\n\n/**\n * Latch one observer: stable identity, missing stays missing. Calling through\n * a no-op would still look like \"someone is listening\".\n */\nfunction useObservedEdit(\n handler: EditEventHandler | undefined\n): EditEventHandler | undefined {\n const stable = useEventCallback((event: EditEvent) => {\n observeEdit(handler, event);\n });\n return handler ? stable : undefined;\n}\n\n/**\n * Stable identities for the five observers, so a host's inline arrows never\n * repaint rows. The returned object is itself stable while the set of wired\n * handlers does not change — `editing` memoizes on it.\n */\nexport function useEditLifecycle(\n props: EditLifecycle\n): EditLifecycle {\n const onEditStart = useObservedEdit(props.onEditStart);\n const onEditCancel = useObservedEdit(props.onEditCancel);\n const onEditCommit = useObservedEdit(props.onEditCommit);\n const onValidationFail = useObservedEdit(props.onValidationFail);\n const onEditError = useObservedEdit(props.onEditError);\n return useMemo(\n () => ({\n onEditStart,\n onEditCancel,\n onEditCommit,\n onValidationFail,\n onEditError,\n }),\n [onEditStart, onEditCancel, onEditCommit, onValidationFail, onEditError]\n );\n}\n","/**\n * Many rows changed, saved in one go.\n *\n * Row mode holds one row's fields until the reader saves it. Batch mode holds\n * *several rows* until they save all of them — the shape of a review pass, where\n * someone walks a list correcting values and wants one write at the end rather\n * than one per row. Nothing is sent until they say so, and one Cancel puts\n * everything back.\n *\n * The table still owns none of the data: what a save produces is the list of\n * patches, and the host applies them however it applies anything else. That is\n * also what makes the write atomic if the host wants it to be — a single request\n * with every change in it.\n */\nimport { useCallback, useMemo, useRef, useState } from \"react\";\n\nimport { useEventCallback } from \"../hooks/useEventCallback\";\nimport type { EditableColumnLike } from \"./cellEditing\";\nimport {\n parseCellEditValue,\n readEditableCellValue,\n resolveCellEditor,\n} from \"./cellEditing\";\nimport type { EditEventHandler } from \"./editingEvents\";\nimport { observeEdit } from \"./editingEvents\";\n\n/** One row's pending changes. */\nexport interface BatchRowEdit {\n /** The row as it was when the reader started changing it. */\n row: TRow;\n /** Its stable id. */\n rowId: string;\n /** Parsed values by column key — only the fields that actually changed. */\n patch: Readonly>;\n}\n\n/** Headless batch-editing state. */\nexport interface BatchEditingState {\n /** How many rows are waiting — what a \"3 unsaved rows\" line reads. */\n count: number;\n /** Whether anything is waiting at all. */\n pending: boolean;\n /** Whether this row has pending changes. */\n isPending: (rowId: string) => boolean;\n /** This cell's draft, or the row's stored value when it has none. */\n draftFor: (row: TRow, rowId: string, columnKey: string) => string;\n /** Whether this cell has been changed. */\n isChanged: (rowId: string, columnKey: string) => boolean;\n /** Change one cell, without telling the host. */\n setDraft: (\n row: TRow,\n rowId: string,\n columnKey: string,\n value: string\n ) => void;\n /** Hand the host every pending row, as one list, then forget them. */\n saveAll: () => void;\n /** Forget everything, restoring nothing — the drafts were never applied. */\n cancelAll: () => void;\n /** Forget one row's changes. */\n cancelRow: (rowId: string) => void;\n /** A digest of the pending drafts, for a row memo comparator. */\n signature: string;\n}\n\n/** What {@link useBatchEditing} needs. */\nexport interface UseBatchEditingOptions {\n /**\n * Whether batch editing is armed. Off by default: it changes when a commit\n * happens, which is a decision about the data rather than a preference.\n */\n enabled?: boolean;\n /** The columns, for seeding drafts and parsing them back. */\n columns: readonly EditableColumnLike[];\n /**\n * Take every pending row at once. The table never writes to a row, and the\n * whole point of the mode is that this is called once.\n */\n onBatchEdit?: (edits: readonly BatchRowEdit[]) => unknown;\n /** A row became pending. */\n onEditStart?: EditEventHandler;\n /** Pending changes were thrown away. */\n onEditCancel?: EditEventHandler;\n /** The host received the batch. */\n onEditCommit?: EditEventHandler;\n}\n\n/** The drafts of one row, by column key. */\ntype RowDrafts = Readonly>;\n\n/** Every pending row's drafts, by row id. */\ntype PendingDrafts = Readonly<\n Record\n>;\n\n/**\n * Headless state for changing many rows and saving them together.\n *\n * @typeParam TRow - The row type.\n * @param options - See {@link UseBatchEditingOptions}.\n * @returns The state; inert unless `enabled`.\n */\nexport function useBatchEditing(\n options: UseBatchEditingOptions\n): BatchEditingState {\n const enabled = options.enabled ?? false;\n const [pending, setPending] = useState({});\n // A ref beside the state: a save reads the drafts in the same tick a keystroke\n // wrote one, and a control that saves on the click that also edits would\n // otherwise send the values as they were before it.\n const pendingRef = useRef({});\n\n const write = useEventCallback((next: PendingDrafts) => {\n pendingRef.current = next;\n setPending(next);\n });\n\n const setDraft = useEventCallback(\n (row: TRow, rowId: string, columnKey: string, value: string) => {\n if (!enabled) return;\n const column = options.columns.find((entry) => entry.key === columnKey);\n if (!column) return;\n const stored = readEditableCellValue(row, column);\n const current = pendingRef.current[rowId];\n const drafts = { ...current?.drafts, [columnKey]: value };\n // A value typed back to what it was is not a change, and a row left with\n // no changes is not pending — otherwise \"3 unsaved rows\" counts rows the\n // reader has already put back.\n if (value === stored) delete drafts[columnKey];\n const wasPending = current !== undefined;\n const next = { ...pendingRef.current };\n if (Object.keys(drafts).length === 0) delete next[rowId];\n else next[rowId] = { row: current?.row ?? row, drafts };\n write(next);\n if (!wasPending && next[rowId]) {\n observeEdit(options.onEditStart, {\n row,\n rowId,\n columnKey,\n value,\n previousValue: stored,\n unit: \"batch\",\n });\n }\n }\n );\n\n const saveAll = useEventCallback(() => {\n const current = pendingRef.current;\n const edits: BatchRowEdit[] = [];\n for (const [rowId, entry] of Object.entries(current)) {\n const row = entry.row as TRow;\n const patch: Record = {};\n for (const [columnKey, draft] of Object.entries(entry.drafts)) {\n const column = options.columns.find((one) => one.key === columnKey);\n if (!column) continue;\n patch[columnKey] = column.parseValue\n ? column.parseValue(draft, row)\n : parseCellEditValue(resolveCellEditor(column) ?? \"text\", draft);\n }\n edits.push({ row, rowId, patch });\n }\n if (edits.length > 0) {\n options.onBatchEdit?.(edits);\n for (const edit of edits) {\n observeEdit(options.onEditCommit, {\n row: edit.row,\n rowId: edit.rowId,\n columnKey: \"\",\n value: edit.patch,\n previousValue: edit.row,\n unit: \"batch\",\n });\n }\n }\n write({});\n });\n\n const cancelAll = useEventCallback(() => {\n for (const [rowId, entry] of Object.entries(pendingRef.current)) {\n observeEdit(options.onEditCancel, {\n row: entry.row as TRow,\n rowId,\n columnKey: \"\",\n value: entry.drafts,\n previousValue: entry.row,\n unit: \"batch\",\n });\n }\n write({});\n });\n\n const cancelRow = useEventCallback((rowId: string) => {\n const entry = pendingRef.current[rowId];\n if (!entry) return;\n observeEdit(options.onEditCancel, {\n row: entry.row as TRow,\n rowId,\n columnKey: \"\",\n value: entry.drafts,\n previousValue: entry.row,\n unit: \"batch\",\n });\n const next = { ...pendingRef.current };\n delete next[rowId];\n write(next);\n });\n\n const isPending = useCallback((rowId: string) => rowId in pending, [pending]);\n\n const isChanged = useCallback(\n (rowId: string, columnKey: string) =>\n pending[rowId]?.drafts[columnKey] !== undefined,\n [pending]\n );\n\n const draftFor = useCallback(\n (row: TRow, rowId: string, columnKey: string) => {\n const draft = pending[rowId]?.drafts[columnKey];\n if (draft !== undefined) return draft;\n const column = options.columns.find((entry) => entry.key === columnKey);\n return column ? readEditableCellValue(row, column) : \"\";\n },\n [pending, options.columns]\n );\n\n const signature = useMemo(\n () =>\n Object.entries(pending)\n .map(\n ([rowId, entry]) =>\n `${rowId}:${Object.entries(entry.drafts)\n .map(([key, value]) => `${key}=${value}`)\n .join(\"|\")}`\n )\n .join(\";\"),\n [pending]\n );\n\n const count = Object.keys(pending).length;\n\n return useMemo(\n () => ({\n count,\n pending: count > 0,\n isPending,\n isChanged,\n draftFor,\n setDraft,\n saveAll,\n cancelAll,\n cancelRow,\n signature,\n }),\n [\n count,\n isPending,\n isChanged,\n draftFor,\n setDraft,\n saveAll,\n cancelAll,\n cancelRow,\n signature,\n ]\n );\n}\n","/**\n * Which cells have been changed since the reader last saw them agree with the\n * server.\n *\n * A save can be in flight, or it can have landed and not yet be confirmed by\n * anything the reader trusts — an optimistic table shows a value the server has\n * not acknowledged. Both are \"changed but not settled\", and both deserve a mark,\n * because a table that looks identical before and after a save gives the reader\n * no way to tell what is still at risk.\n *\n * The table does not decide when a value is settled: the host does, by handing\n * back a promise that resolves, or by calling `confirm` when a refetch agrees.\n * Marks clear on confirmation and on rollback, and never on their own — a mark\n * that fades on a timer says the change is safe when nobody checked.\n */\nimport { useCallback, useMemo, useState } from \"react\";\n\nimport { useEventCallback } from \"../hooks/useEventCallback\";\n\n/** Dirty state for the whole table. */\nexport interface DirtyCellState {\n /** Whether this cell holds a change nobody has confirmed. */\n isDirty: (rowId: string, columnKey: string) => boolean;\n /** Whether any cell in this row does — what a row marker reads. */\n isRowDirty: (rowId: string) => boolean;\n /** How many cells are waiting, for a \"3 unsaved changes\" line. */\n count: number;\n /** Mark a cell changed. */\n mark: (rowId: string, columnKey: string) => void;\n /** Clear one cell — a save confirmed, or a change undone. */\n confirm: (rowId: string, columnKey: string) => void;\n /** Clear every cell in one row. */\n confirmRow: (rowId: string) => void;\n /** Clear everything — what a successful refetch means. */\n confirmAll: () => void;\n /** A digest of the marks, for a row memo comparator. */\n signature: string;\n}\n\n/** What {@link useDirtyCells} needs. */\nexport interface UseDirtyCellsOptions {\n /**\n * Whether to mark at all. Off by default: a mark is a claim about what the\n * server has agreed to, and a table whose host never says would be guessing.\n */\n enabled?: boolean;\n}\n\n/** `rowId` and `columnKey` as one map key. */\nconst cellKey = (rowId: string, columnKey: string) => `${rowId} ${columnKey}`;\n\n/**\n * Headless dirty-cell state for inline editing.\n *\n * @param options - See {@link UseDirtyCellsOptions}.\n * @returns The state; inert unless `enabled`.\n */\nexport function useDirtyCells(\n options: UseDirtyCellsOptions = {}\n): DirtyCellState {\n const enabled = options.enabled ?? false;\n const [dirty, setDirty] = useState>(() => new Set());\n\n const mark = useEventCallback((rowId: string, columnKey: string) => {\n if (!enabled) return;\n setDirty((current) => {\n const key = cellKey(rowId, columnKey);\n if (current.has(key)) return current;\n return new Set(current).add(key);\n });\n });\n\n const confirm = useEventCallback((rowId: string, columnKey: string) => {\n setDirty((current) => {\n const key = cellKey(rowId, columnKey);\n if (!current.has(key)) return current;\n const next = new Set(current);\n next.delete(key);\n return next;\n });\n });\n\n const confirmRow = useEventCallback((rowId: string) => {\n setDirty((current) => {\n const prefix = `${rowId} `;\n const next = new Set(\n [...current].filter((key) => !key.startsWith(prefix))\n );\n return next.size === current.size ? current : next;\n });\n });\n\n const confirmAll = useEventCallback(() => {\n setDirty((current) => (current.size === 0 ? current : new Set()));\n });\n\n const isDirty = useCallback(\n (rowId: string, columnKey: string) => dirty.has(cellKey(rowId, columnKey)),\n [dirty]\n );\n\n const isRowDirty = useCallback(\n (rowId: string) => {\n const prefix = `${rowId} `;\n for (const key of dirty) {\n if (key.startsWith(prefix)) return true;\n }\n return false;\n },\n [dirty]\n );\n\n const signature = useMemo(() => [...dirty].join(\"\"), [dirty]);\n\n return useMemo(\n () => ({\n isDirty,\n isRowDirty,\n count: dirty.size,\n mark,\n confirm,\n confirmRow,\n confirmAll,\n signature,\n }),\n [\n isDirty,\n isRowDirty,\n dirty.size,\n mark,\n confirm,\n confirmRow,\n confirmAll,\n signature,\n ]\n );\n}\n","/**\n * A row changed underneath an open editor.\n *\n * The table does not own the data, so it cannot merge. It can keep what the\n * reader typed, take the incoming value, or ask. Silently discarding a draft\n * is the one outcome nobody forgives, so the default is to ask.\n */\nimport { useCallback, useMemo, useRef, useState } from \"react\";\n\nimport { useEventCallback } from \"../hooks/useEventCallback\";\nimport { devWarn } from \"../utils/devWarn\";\nimport { type EditableColumnLike, readEditableCellValue } from \"./cellEditing\";\n\n/** How an unhandled conflict is resolved. */\nexport type EditConflictPolicy = \"keep\" | \"take\" | \"ask\";\n\n/** The host's choice, when it makes one. */\nexport type EditConflictChoice = \"keep\" | \"take\";\n\n/**\n * One conflict. `row` is what just arrived; `previous` is the snapshot the\n * editor opened against (or last accepted).\n */\nexport interface EditConflict {\n /** The incoming row. */\n row: TRow;\n /** The row as it was when the editor opened (or last accepted). */\n previous: TRow;\n /** Its stable id. */\n rowId: string;\n /** The column being edited. */\n columnKey: string;\n /** What the reader has typed. */\n draft: string;\n /** The incoming cell value. */\n incomingValue: string;\n /** The cell value the editor opened against. */\n previousValue: string;\n}\n\n/** What a host returns from {@link EditConflictHandler}. `void` defers to policy. */\nexport type EditConflictHandler = (\n conflict: EditConflict\n) => EditConflictChoice | void;\n\n/** Headless conflict state for the active editor. */\nexport interface EditConflictState {\n /** The conflict being asked about, or `null`. */\n current: EditConflict | null;\n /** Whether this cell is the one in conflict. */\n isConflict: (rowId: string, columnKey: string) => boolean;\n /** Keep the draft; accept the incoming row as the new snapshot. */\n keep: () => void;\n /** Replace the draft with the incoming value. */\n take: () => void;\n /**\n * Compare the open editor to the live rows. Call from the same effect that\n * discards a missing row — a conflict is that check one step milder.\n */\n reconcile: (input: ReconcileLiveEdit) => void;\n /** Drop a conflict without choosing — the editor closed. */\n clear: () => void;\n}\n\n/** What {@link EditConflictState.reconcile} needs to judge one live update. */\nexport interface ReconcileLiveEdit {\n /** The active cell, or `null` when idle. */\n active: { rowId: string; columnKey: string } | null;\n /** The row the editor opened against. */\n openedRow: TRow | undefined;\n /** The live draft. */\n draft: string;\n /** The rendered row set. */\n rows: readonly TRow[];\n /** Columns, to read the edited field. */\n columns: readonly EditableColumnLike[];\n rowKey: (row: TRow) => string;\n /** Host version accessor — any change is a conflict, not just this cell. */\n rowVersion?: (row: TRow) => string | number;\n policy: EditConflictPolicy;\n onEditConflict?: EditConflictHandler;\n /** Keep: new snapshot, same draft. */\n keep: (row: TRow) => void;\n /** Take: new snapshot and the incoming value as the draft. */\n take: (row: TRow, incomingValue: string) => void;\n}\n\n/**\n * Whether the live row disagrees with the snapshot the editor opened against.\n *\n * With `rowVersion`, any version change is a conflict — the host said the row\n * moved. Without it, only the edited column's stored value counts, so an\n * unrelated field updating does not steal the draft.\n */\nexport function liveRowChanged(input: {\n opened: TRow;\n current: TRow;\n column: EditableColumnLike;\n rowVersion?: (row: TRow) => string | number;\n}): boolean {\n if (input.rowVersion !== undefined) {\n return (\n String(input.rowVersion(input.opened)) !==\n String(input.rowVersion(input.current))\n );\n }\n return (\n readEditableCellValue(input.opened, input.column) !==\n readEditableCellValue(input.current, input.column)\n );\n}\n\n/** Ask the host; a throw or a void return defers to policy. */\nexport function resolveConflictChoice(\n handler: EditConflictHandler | undefined,\n conflict: EditConflict,\n policy: EditConflictPolicy\n): EditConflictChoice | \"ask\" {\n if (handler) {\n try {\n const choice = handler(conflict);\n if (choice === \"keep\" || choice === \"take\") return choice;\n } catch (error) {\n const detail = error instanceof Error ? error.message : String(error);\n devWarn(\n `onEditConflict threw (${detail}) — the table used editConflictPolicy instead`\n );\n }\n }\n return policy;\n}\n\n/**\n * Headless conflict state. Inert until {@link EditConflictState.reconcile}\n * sees a live row that disagrees with the open editor.\n */\nexport function useEditConflict(): EditConflictState {\n const [current, setCurrent] = useState | null>(null);\n const seen = useRef(\"\");\n const keepLive = useRef[\"keep\"]>(() => undefined);\n const takeLive = useRef[\"take\"]>(() => undefined);\n const pending = useRef | null>(null);\n\n const clear = useCallback(() => {\n seen.current = \"\";\n pending.current = null;\n setCurrent(null);\n }, []);\n\n const keep = useEventCallback(() => {\n const conflict = pending.current ?? current;\n if (!conflict) return;\n keepLive.current(conflict.row);\n clear();\n });\n\n const take = useEventCallback(() => {\n const conflict = pending.current ?? current;\n if (!conflict) return;\n takeLive.current(conflict.row, conflict.incomingValue);\n clear();\n });\n\n const applyChoice = useEventCallback(\n (choice: EditConflictChoice | \"ask\", conflict: EditConflict) => {\n if (choice === \"keep\") {\n keepLive.current(conflict.row);\n setCurrent(null);\n pending.current = null;\n return;\n }\n if (choice === \"take\") {\n takeLive.current(conflict.row, conflict.incomingValue);\n setCurrent(null);\n pending.current = null;\n return;\n }\n pending.current = conflict;\n setCurrent(conflict);\n }\n );\n\n const reconcile = useEventCallback((input: ReconcileLiveEdit) => {\n keepLive.current = input.keep;\n takeLive.current = input.take;\n const { active, openedRow } = input;\n if (!active || openedRow === undefined) {\n if (seen.current !== \"\") clear();\n return;\n }\n const live = input.rows.find((row) => input.rowKey(row) === active.rowId);\n if (!live) {\n // Missing rows are discardIfRowMissing's job.\n if (seen.current !== \"\") clear();\n return;\n }\n const column = input.columns.find((item) => item.key === active.columnKey);\n if (!column) return;\n if (\n !liveRowChanged({\n opened: openedRow,\n current: live,\n column,\n rowVersion: input.rowVersion,\n })\n ) {\n if (seen.current !== \"\") clear();\n return;\n }\n const incomingValue = readEditableCellValue(live, column);\n const previousValue = readEditableCellValue(openedRow, column);\n const token = `${active.rowId}::${active.columnKey}::${incomingValue}`;\n if (token === seen.current) return;\n seen.current = token;\n const conflict: EditConflict = {\n row: live,\n previous: openedRow,\n rowId: active.rowId,\n columnKey: active.columnKey,\n draft: input.draft,\n incomingValue,\n previousValue,\n };\n applyChoice(\n resolveConflictChoice(input.onEditConflict, conflict, input.policy),\n conflict\n );\n });\n\n const isConflict = useCallback(\n (rowId: string, columnKey: string) =>\n current?.rowId === rowId && current.columnKey === columnKey,\n [current]\n );\n\n return useMemo(\n () => ({\n current,\n isConflict,\n keep,\n take,\n reconcile,\n clear,\n }),\n [current, isConflict, keep, take, reconcile, clear]\n );\n}\n","/**\n * Editing a whole row at once.\n *\n * Cell editing commits each field as the reader leaves it, which is right for a\n * spreadsheet and wrong for a form: a row whose fields constrain each other\n * cannot be edited one cell at a time without passing through states that are\n * invalid on the way — a start date after an end date it is about to replace.\n *\n * So a row edit holds every field's draft until the reader saves, then hands the\n * host ONE patch. Cancel throws all of it away. The unit changes; nothing else\n * does — the same editors, the same validators, the same save states.\n */\nimport { useCallback, useMemo, useRef, useState } from \"react\";\n\nimport { useEventCallback } from \"../hooks/useEventCallback\";\nimport type { EditableColumnLike } from \"./cellEditing\";\nimport {\n parseCellEditValue,\n readEditableCellValue,\n resolveCellEditor,\n} from \"./cellEditing\";\nimport type { EditEventHandler } from \"./editingEvents\";\nimport { observeEdit } from \"./editingEvents\";\n\n/** The drafts a row edit holds, by column key. */\nexport type RowEditDrafts = Readonly>;\n\n/** Headless row-editing state. */\nexport interface RowEditingState {\n /** The row being edited, or `null` when none is. */\n activeRowId: string | null;\n /** Whether this row is the one being edited. */\n isEditing: (rowId: string) => boolean;\n /** Every draft in the open row, by column key. */\n drafts: RowEditDrafts;\n /** One column's draft in the open row. */\n draftFor: (columnKey: string) => string;\n /** Open a row, seeding every editable column from its current value. */\n begin: (row: TRow, rowId: string) => void;\n /** Replace one column's draft. */\n setDraft: (columnKey: string, value: string) => void;\n /**\n * Hand the host everything the reader changed, as one patch, then close.\n * A no-op when nothing is open, and it reports nothing when nothing changed —\n * saving an untouched row is a write the host never asked for.\n */\n save: () => void;\n /** Throw every draft away and close. */\n cancel: () => void;\n /** Whether any draft differs from the row's stored value. */\n isDirty: boolean;\n /** A digest of the open row's drafts, for a row memo comparator. */\n signature: string;\n}\n\n/** What {@link useRowEditing} needs. */\nexport interface UseRowEditingOptions {\n /**\n * Whether row editing is armed. Off by default: it changes the commit unit,\n * which is a decision about the data, not a preference.\n */\n enabled?: boolean;\n /** The columns, for seeding drafts and parsing them back. */\n columns: readonly EditableColumnLike[];\n /**\n * Take everything the reader changed, as one patch of parsed values keyed by\n * column. The table never writes to a row.\n */\n onRowEdit?: (row: TRow, patch: Readonly>) => unknown;\n /** An editor opened on this row. */\n onEditStart?: EditEventHandler;\n /** The reader threw the drafts away. */\n onEditCancel?: EditEventHandler;\n /** The host received the patch. */\n onEditCommit?: EditEventHandler;\n}\n\n/** Every column a reader may edit on a given row. */\nfunction editableColumns(\n columns: readonly EditableColumnLike[],\n row: TRow\n): EditableColumnLike[] {\n return columns.filter((column) => {\n const { editable } = column;\n if (editable === undefined || editable === false) return false;\n return editable === true || editable(row);\n });\n}\n\n/**\n * Headless state for editing a row as one unit.\n *\n * @typeParam TRow - The row type.\n * @param options - See {@link UseRowEditingOptions}.\n * @returns The state; inert unless `enabled`.\n */\nexport function useRowEditing(\n options: UseRowEditingOptions\n): RowEditingState {\n const enabled = options.enabled ?? false;\n const [activeRowId, setActiveRowId] = useState(null);\n const [drafts, setDrafts] = useState({});\n // A ref beside the state, written in the same tick: a picker that sets a\n // draft and commits in one gesture — the documented pattern for a custom\n // editor — would otherwise save the drafts as they were before its own click.\n const draftsRef = useRef({});\n // The row and its seeds as they were when the edit opened: what \"changed\"\n // is measured against, and what the patch is built from. A ref because a\n // save reads them in the same tick a keystroke wrote a draft.\n const opened = useRef<{\n row: TRow;\n rowId: string;\n seeds: RowEditDrafts;\n } | null>(null);\n\n const begin = useEventCallback((row: TRow, rowId: string) => {\n if (!enabled) return;\n const seeds: Record = {};\n for (const column of editableColumns(options.columns, row)) {\n seeds[column.key] = readEditableCellValue(row, column);\n }\n opened.current = { row, rowId, seeds };\n draftsRef.current = seeds;\n setActiveRowId(rowId);\n setDrafts(seeds);\n observeEdit(options.onEditStart, {\n row,\n rowId,\n columnKey: \"\",\n value: seeds,\n previousValue: row,\n unit: \"row\",\n });\n });\n\n const setDraft = useEventCallback((columnKey: string, value: string) => {\n if (draftsRef.current[columnKey] === value) return;\n draftsRef.current = { ...draftsRef.current, [columnKey]: value };\n setDrafts(draftsRef.current);\n });\n\n const close = useEventCallback((kind: \"cancel\" | \"silent\" = \"silent\") => {\n const open = opened.current;\n if (kind === \"cancel\" && open) {\n observeEdit(options.onEditCancel, {\n row: open.row,\n rowId: open.rowId,\n columnKey: \"\",\n value: draftsRef.current,\n previousValue: open.seeds,\n unit: \"row\",\n });\n }\n opened.current = null;\n draftsRef.current = {};\n setActiveRowId(null);\n setDrafts({});\n });\n\n const save = useEventCallback(() => {\n const open = opened.current;\n if (!open) return;\n const patch: Record = {};\n const current = draftsRef.current;\n for (const column of editableColumns(options.columns, open.row)) {\n const draft = current[column.key];\n if (draft === undefined || draft === open.seeds[column.key]) continue;\n patch[column.key] = column.parseValue\n ? column.parseValue(draft, open.row)\n : parseCellEditValue(resolveCellEditor(column) ?? \"text\", draft);\n }\n // Saving an untouched row is a write the host never asked for.\n if (Object.keys(patch).length > 0) {\n options.onRowEdit?.(open.row, patch);\n observeEdit(options.onEditCommit, {\n row: open.row,\n rowId: open.rowId,\n columnKey: \"\",\n value: patch,\n previousValue: open.row,\n unit: \"row\",\n });\n }\n close(\"silent\");\n });\n\n const isDirty = useMemo(() => {\n const open = opened.current;\n if (!open) return false;\n return Object.entries(drafts).some(\n ([key, value]) => value !== open.seeds[key]\n );\n }, [drafts]);\n\n const isEditing = useCallback(\n (rowId: string) => activeRowId === rowId,\n [activeRowId]\n );\n\n const draftFor = useCallback(\n (columnKey: string) => drafts[columnKey] ?? \"\",\n [drafts]\n );\n\n const signature = useMemo(\n () =>\n activeRowId === null\n ? \"\"\n : `${activeRowId}:${Object.entries(drafts)\n .map(([key, value]) => `${key}=${value}`)\n .join(\"|\")}`,\n [activeRowId, drafts]\n );\n\n return useMemo(\n () => ({\n activeRowId,\n isEditing,\n drafts,\n draftFor,\n begin,\n setDraft,\n save,\n cancel: () => {\n close(\"cancel\");\n },\n isDirty,\n signature,\n }),\n [\n activeRowId,\n isEditing,\n drafts,\n draftFor,\n begin,\n setDraft,\n save,\n close,\n isDirty,\n signature,\n ]\n );\n}\n","/**\n * What a cell shows while its edit is being saved, and what happens when the\n * save fails.\n *\n * `onCellEdit` may return a promise. If it does, the table knows something the\n * reader cannot see: the value is on its way somewhere. A cell that looks\n * committed while a request is still out is a lie the reader finds out about\n * only when it fails — so the cell is marked saving until the promise settles,\n * and marked failed with the reason if it rejects.\n *\n * The table still does not own the data. An optimistic table has already shown\n * the new value (the host applied it in `onCellEdit`), so a rejection has to put\n * the old one back: `onRollback` hands the host the previous value to restore,\n * because only the host can write to its own rows.\n */\nimport { useCallback, useMemo, useRef, useState } from \"react\";\n\nimport { useEventCallback } from \"../hooks/useEventCallback\";\nimport type { EditEventHandler } from \"./editingEvents\";\nimport { observeEdit } from \"./editingEvents\";\n\n/** What a cell's last save is doing. */\nexport type CellSaveStatus = \"saving\" | \"failed\";\n\n/** One cell's failed save, with what it takes to retry or undo it. */\nexport interface FailedCellSave {\n /** The row as it was before the edit — what a rollback restores. */\n previous: TRow;\n /** The value the reader tried to save. */\n attempted: unknown;\n /** Why it failed, in a sentence a reader can read. */\n message: string;\n}\n\n/** What {@link useCellSaveState} needs. */\nexport interface UseCellSaveStateOptions {\n /**\n * Put the previous row back after a rejected save. Without it the table marks\n * the cell failed and leaves the value where it is — correct for a table that\n * refetches, wrong for one that applied the edit optimistically.\n */\n onRollback?: (previous: TRow, columnKey: string) => void;\n /** Turn a rejection into the sentence the cell shows. */\n formatError?: (error: unknown) => string;\n /** Observe a rejected save — never owns the outcome. */\n onEditError?: EditEventHandler;\n}\n\n/** Per-cell save state for the whole table. */\nexport interface CellSaveState {\n /** What this cell's last save is doing, if anything. */\n statusFor: (rowId: string, columnKey: string) => CellSaveStatus | undefined;\n /** Why this cell's last save failed, if it did. */\n failureFor: (\n rowId: string,\n columnKey: string\n ) => FailedCellSave | undefined;\n /**\n * Watch one commit, and report how it went: `true` when the value reached\n * wherever it was going, `false` when it did not.\n *\n * The outcome comes back from here rather than being read off the state\n * afterwards, because a caller holding a render-old closure would read the\n * state as it was BEFORE the failure and conclude the save succeeded.\n */\n track: (options: {\n rowId: string;\n columnKey: string;\n /** The row before the edit — what a rollback restores. */\n previous: TRow;\n /** The value being saved. */\n attempted: unknown;\n /**\n * The cell's previous value, when the caller has it. The error event\n * reports this as `previousValue`; without it the event uses the row.\n */\n previousValue?: unknown;\n /** Whatever `onCellEdit` returned. */\n result: unknown;\n }) => Promise;\n /** Put a failed cell's previous row back, and forget the failure. */\n rollback: (rowId: string, columnKey: string) => void;\n /** Forget a cell's failure without restoring anything — what a retry does. */\n clear: (rowId: string, columnKey: string) => void;\n /** A digest of the states, for a row memo comparator. */\n signature: string;\n /**\n * Whether the table was told how to put a row back. An undo control offered\n * without one would do nothing when pressed.\n */\n canRollback: boolean;\n}\n\n/** `rowId` and `columnKey` as one map key. */\nconst cellKey = (rowId: string, columnKey: string) => `${rowId} ${columnKey}`;\n\n/** The default sentence for a rejection of any shape. */\nfunction defaultFormatError(error: unknown): string {\n if (error instanceof Error) return error.message;\n if (typeof error === \"string\" && error !== \"\") return error;\n return \"Could not save\";\n}\n\n/** Whether a value is a promise the table should wait on. */\nfunction isThenable(value: unknown): value is Promise {\n return (\n typeof value === \"object\" &&\n value !== null &&\n typeof (value as { then?: unknown }).then === \"function\"\n );\n}\n\n/**\n * Headless save state for inline editing.\n *\n * @typeParam TRow - The row type.\n * @param options - See {@link UseCellSaveStateOptions}.\n * @returns The state; inert until a commit returns a promise that rejects.\n */\nexport function useCellSaveState(\n options: UseCellSaveStateOptions = {}\n): CellSaveState {\n const [saving, setSaving] = useState>(() => new Set());\n const [failures, setFailures] = useState<\n ReadonlyMap>\n >(() => new Map());\n // One token per cell: a save that settles after a newer one started must not\n // mark a cell about a value the reader has already replaced.\n const tokens = useRef(new Map());\n\n const markSaving = useEventCallback((key: string, busy: boolean) => {\n setSaving((current) => {\n if (current.has(key) === busy) return current;\n const next = new Set(current);\n if (busy) next.add(key);\n else next.delete(key);\n return next;\n });\n });\n\n const setFailure = useEventCallback(\n (key: string, failure: FailedCellSave | undefined) => {\n setFailures((current) => {\n if (failure === undefined && !current.has(key)) return current;\n const next = new Map(current);\n if (failure === undefined) next.delete(key);\n else next.set(key, failure);\n return next;\n });\n }\n );\n\n const track = useEventCallback(\n async (input: {\n rowId: string;\n columnKey: string;\n previous: TRow;\n attempted: unknown;\n previousValue?: unknown;\n result: unknown;\n }): Promise => {\n const { rowId, columnKey, previous, attempted, previousValue, result } =\n input;\n // A host that saves synchronously has nothing to wait for, and paying a\n // render for a state that lasts no time would be worse than useless.\n if (!isThenable(result)) return true;\n\n const key = cellKey(rowId, columnKey);\n const token = (tokens.current.get(key) ?? 0) + 1;\n tokens.current.set(key, token);\n const current = () => tokens.current.get(key) === token;\n\n setFailure(key, undefined);\n markSaving(key, true);\n try {\n await result;\n if (current()) setFailure(key, undefined);\n return true;\n } catch (error) {\n // A superseded save says nothing either way: a newer one owns the cell.\n if (!current()) return false;\n const message = (options.formatError ?? defaultFormatError)(error);\n setFailure(key, {\n previous,\n attempted,\n message,\n });\n observeEdit(options.onEditError, {\n row: previous,\n rowId,\n columnKey,\n value: attempted,\n previousValue: previousValue ?? previous,\n unit: \"cell\",\n error: message,\n });\n return false;\n } finally {\n if (current()) markSaving(key, false);\n }\n }\n );\n\n const rollback = useEventCallback((rowId: string, columnKey: string) => {\n const key = cellKey(rowId, columnKey);\n const failure = failures.get(key);\n if (!failure) return;\n setFailure(key, undefined);\n options.onRollback?.(failure.previous, columnKey);\n });\n\n const clear = useEventCallback((rowId: string, columnKey: string) => {\n setFailure(cellKey(rowId, columnKey), undefined);\n });\n\n const signature = useMemo(\n () =>\n [\n ...saving,\n ...[...failures.entries()].map(([key, f]) => key + f.message),\n ].join(\"\"),\n [saving, failures]\n );\n\n const statusFor = useCallback(\n (rowId: string, columnKey: string): CellSaveStatus | undefined => {\n const key = cellKey(rowId, columnKey);\n if (saving.has(key)) return \"saving\";\n return failures.has(key) ? \"failed\" : undefined;\n },\n [saving, failures]\n );\n\n const failureFor = useCallback(\n (rowId: string, columnKey: string) =>\n failures.get(cellKey(rowId, columnKey)),\n [failures]\n );\n\n return useMemo(\n () => ({\n statusFor,\n failureFor,\n track,\n rollback,\n clear,\n signature,\n canRollback: options.onRollback !== undefined,\n }),\n [\n statusFor,\n failureFor,\n track,\n rollback,\n clear,\n signature,\n options.onRollback,\n ]\n );\n}\n","/**\n * Headless editing state machine: one active cell, draft value, and the\n * Enter / Escape / Tab keyboard flow.\n *\n * Opt-in by design — calling this hook alone does nothing visible. Adapters\n * only surface editors when the table passes `onCellEdit` (see\n * {@link TableChrome.editing}) and a column sets `editable`.\n */\nimport { useCallback, useMemo, useRef, useState } from \"react\";\n\nimport {\n type CellEditCommit,\n type CellEditTarget,\n type EditableColumnLike,\n isCellEditable,\n readEditableCellValue,\n stepEditableCell,\n} from \"./cellEditing\";\nimport type { EditEventHandler } from \"./editingEvents\";\nimport { observeEdit } from \"./editingEvents\";\n\n/** Keyboard outcome from {@link CellEditingState.handleKeyDown}. */\nexport type CellEditKeyAction = \"commit\" | \"cancel\" | \"commit-advance\";\n\n/** Row/column context for Tab / Shift+Tab advance. */\nexport interface CellEditNavigation {\n rows: readonly unknown[];\n columns: readonly EditableColumnLike[];\n rowKey: (row: unknown) => string;\n}\n\n/** Outcome of {@link CellEditingState.handleKeyDown}. */\nexport interface CellEditKeyOutcome {\n action: CellEditKeyAction;\n commit: CellEditCommit | null;\n advanceTarget: CellEditTarget | null;\n}\n\n/** Headless cell-editing state returned by {@link useCellEditing}. */\nexport interface CellEditingState {\n /** The cell currently being edited, or `null` when idle. */\n active: CellEditTarget | null;\n /** Live draft string for the active editor. */\n draft: string;\n /** Whether `(rowId, columnKey)` is the active cell. */\n isActive: (rowId: string, columnKey: string) => boolean;\n /**\n * Start editing a cell. Re-beginning the same cell keeps the draft;\n * switching cells abandons the previous draft without committing.\n * Pass the row so lifecycle observers can name what opened.\n */\n begin: (\n rowId: string,\n columnKey: string,\n initialValue: string,\n row?: unknown\n ) => void;\n /** Update the draft without committing. */\n setDraft: (value: string) => void;\n /**\n * Commit the draft. Returns the commit payload, or `null` when idle.\n * Clears the active cell. The table never mutates rows — callers must\n * apply the result through `onCellEdit` (see {@link applyCellEditCommit}).\n */\n commit: () => CellEditCommit | null;\n /**\n * Cancel editing and clear the active cell (Escape). Adapters should\n * restore focus to the cell that was being edited.\n */\n cancel: () => void;\n /**\n * Close the editor without treating it as a cancel — what a successful\n * validation does before handing the value to the host. Observers do not\n * hear about this; the commit event fires from the send instead.\n */\n close: () => void;\n /**\n * Drop the active edit when its row leaves the current page/filter set\n * (no commit). No-op when idle or the row is still present.\n */\n discardIfRowMissing: (\n rows: readonly unknown[],\n rowKey: (row: unknown) => string\n ) => void;\n /**\n * The row the editor opened against, so a live update can be compared to\n * what the reader started from.\n */\n openedRow: () => unknown;\n /**\n * Keep the draft and accept `row` as the new snapshot — the incoming\n * change is acknowledged, the typing is not.\n */\n keepLive: (row: unknown) => void;\n /**\n * Replace the draft with `value` and accept `row` as the new snapshot —\n * the reader takes the incoming cell.\n */\n takeLive: (row: unknown, value: string) => void;\n /**\n * Keyboard flow:\n * - Enter → commit\n * - Escape → cancel (adapters restore focus)\n * - Tab → commit and advance; Shift+Tab → commit and go previous\n *\n * Returns `null` when idle or for unrelated keys (so the input keeps\n * default behaviour).\n */\n handleKeyDown: (\n event: { key: string; preventDefault: () => void; shiftKey?: boolean },\n navigation?: CellEditNavigation\n ) => CellEditKeyOutcome | null;\n}\n\n/** What {@link useCellEditing} observes, when the host wired lifecycle events. */\nexport interface UseCellEditingOptions {\n /** An editor opened. */\n onEditStart?: EditEventHandler;\n /** The reader threw the draft away (Escape, or switching cells). */\n onEditCancel?: EditEventHandler;\n}\n\n/**\n * Headless editing state machine: one active cell, draft value, and the\n * Enter / Escape / Tab keyboard flow.\n *\n * @typeParam TRow - The row type, when lifecycle observers are wired.\n * @param options - Optional start/cancel observers.\n * @returns The state machine.\n */\nexport function useCellEditing(\n options: UseCellEditingOptions = {}\n): CellEditingState {\n const [active, setActive] = useState(null);\n const [draft, setDraft] = useState(\"\");\n // Refs so commit/cancel always see the latest values without stale\n // closures when wired through a keydown listener.\n const activeRef = useRef(active);\n const draftRef = useRef(draft);\n activeRef.current = active;\n draftRef.current = draft;\n const openedRef = useRef<{\n rowId: string;\n columnKey: string;\n initial: string;\n row: TRow | undefined;\n } | null>(null);\n\n /** Update draft state and the sync ref in the same tick. */\n const writeDraft = useCallback((value: string) => {\n draftRef.current = value;\n setDraft(value);\n }, []);\n\n /**\n * Same for the active cell: the ref exists so callers within one tick see\n * what just happened, and a `setActive` that left the ref stale made\n * `begin` right after `commit` a silent no-op — it read the cell it had\n * just closed and treated the reopen as \"same cell, keep the draft\".\n */\n const writeActive = useCallback((next: CellEditTarget | null) => {\n activeRef.current = next;\n setActive(next);\n }, []);\n\n const isActive = useCallback(\n (rowId: string, columnKey: string) =>\n active?.rowId === rowId && active.columnKey === columnKey,\n [active]\n );\n\n const fireCancel = useCallback(() => {\n const opened = openedRef.current;\n if (!opened?.row) return;\n observeEdit(options.onEditCancel, {\n row: opened.row,\n rowId: opened.rowId,\n columnKey: opened.columnKey,\n value: draftRef.current,\n previousValue: opened.initial,\n unit: \"cell\",\n });\n }, [options.onEditCancel]);\n\n const clearOpened = useCallback(() => {\n openedRef.current = null;\n writeActive(null);\n writeDraft(\"\");\n }, [writeActive, writeDraft]);\n\n const begin = useCallback(\n (rowId: string, columnKey: string, initialValue: string, row?: unknown) => {\n const current = activeRef.current;\n if (current?.rowId === rowId && current.columnKey === columnKey) {\n return;\n }\n if (current) fireCancel();\n const typed = row as TRow | undefined;\n openedRef.current = {\n rowId,\n columnKey,\n initial: initialValue,\n row: typed,\n };\n writeActive({ rowId, columnKey });\n writeDraft(initialValue);\n if (typed !== undefined) {\n observeEdit(options.onEditStart, {\n row: typed,\n rowId,\n columnKey,\n value: initialValue,\n previousValue: initialValue,\n unit: \"cell\",\n });\n }\n },\n [fireCancel, options.onEditStart, writeActive, writeDraft]\n );\n\n const commit = useCallback((): CellEditCommit | null => {\n const current = activeRef.current;\n if (!current) return null;\n const result: CellEditCommit = {\n rowId: current.rowId,\n columnKey: current.columnKey,\n draft: draftRef.current,\n };\n openedRef.current = null;\n writeActive(null);\n writeDraft(\"\");\n return result;\n }, [writeActive, writeDraft]);\n\n const cancel = useCallback(() => {\n fireCancel();\n clearOpened();\n }, [clearOpened, fireCancel]);\n\n const close = useCallback(() => {\n clearOpened();\n }, [clearOpened]);\n\n const discardIfRowMissing = useCallback(\n (rows: readonly unknown[], rowKey: (row: unknown) => string) => {\n const current = activeRef.current;\n if (!current) return;\n if (rows.some((row) => rowKey(row) === current.rowId)) return;\n openedRef.current = null;\n writeActive(null);\n writeDraft(\"\");\n },\n [writeActive, writeDraft]\n );\n\n const openedRow = useCallback(() => openedRef.current?.row, []);\n\n const keepLive = useCallback((row: unknown) => {\n const opened = openedRef.current;\n if (!opened) return;\n openedRef.current = { ...opened, row: row as TRow };\n }, []);\n\n const takeLive = useCallback(\n (row: unknown, value: string) => {\n const opened = openedRef.current;\n if (!opened) return;\n openedRef.current = { ...opened, row: row as TRow, initial: value };\n writeDraft(value);\n },\n [writeDraft]\n );\n\n const handleKeyDown = useCallback(\n (\n event: { key: string; preventDefault: () => void; shiftKey?: boolean },\n navigation?: CellEditNavigation\n ): CellEditKeyOutcome | null => {\n if (!activeRef.current) return null;\n\n if (event.key === \"Escape\") {\n event.preventDefault();\n cancel();\n return { action: \"cancel\", commit: null, advanceTarget: null };\n }\n\n if (event.key === \"Enter\") {\n event.preventDefault();\n return {\n action: \"commit\",\n commit: commit(),\n advanceTarget: null,\n };\n }\n\n if (event.key === \"Tab\" && navigation) {\n event.preventDefault();\n const result = commit();\n const advanceTarget = result\n ? stepEditableCell({\n rows: navigation.rows,\n columns: navigation.columns,\n rowKey: navigation.rowKey,\n from: { rowId: result.rowId, columnKey: result.columnKey },\n direction: event.shiftKey ? -1 : 1,\n })\n : null;\n return {\n action: \"commit-advance\",\n commit: result,\n advanceTarget,\n };\n }\n\n return null;\n },\n [cancel, commit]\n );\n\n return useMemo(\n () => ({\n active,\n draft,\n isActive,\n begin,\n setDraft: writeDraft,\n commit,\n cancel,\n close,\n discardIfRowMissing,\n openedRow,\n keepLive,\n takeLive,\n handleKeyDown,\n }),\n [\n active,\n draft,\n isActive,\n begin,\n writeDraft,\n commit,\n cancel,\n close,\n discardIfRowMissing,\n openedRow,\n keepLive,\n takeLive,\n handleKeyDown,\n ]\n );\n}\n\n/**\n * Begin editing when the column is editable for this row; no-op otherwise.\n * Prefer this over raw `begin` so adapters never open an editor the host\n * didn't opt into.\n */\nexport function beginCellEdit(\n editing: CellEditingState,\n row: TRow,\n column: EditableColumnLike,\n rowKey: (row: TRow) => string\n): boolean {\n if (!isCellEditable(column, row)) return false;\n editing.begin(\n rowKey(row),\n column.key,\n readEditableCellValue(row, column),\n row\n );\n return true;\n}\n","/**\n * Validation that gates a commit — and gates nothing else.\n *\n * The host owns persistence. A validator's only power is to stop `onCellEdit`\n * from firing and to put a message on the cell; it never rejects a draft the\n * reader is still typing, never rewrites a value, and never decides what to\n * save. That boundary is what keeps validation composable with a host that\n * validates again on the server, which it will.\n *\n * Two levels, because they answer different questions. A **cell** validator\n * knows one value: is this a number, is it in range, is the SKU real. A **row**\n * validator sees the row the edit would produce and can answer the questions no\n * single cell can — an end date before its start, a total that must match its\n * parts. A cell failure marks that cell; a row failure marks the row and may\n * name cells too.\n *\n * Both may be async, because the interesting checks are: \"is this username\n * taken\" is a request. An async check leaves the editor open and the cell marked\n * busy rather than blocking the keystroke, and a newer draft supersedes an older\n * check — a stale answer must never mark a value the reader has already changed.\n */\nimport { useCallback, useMemo, useRef, useState } from \"react\";\n\nimport { useEventCallback } from \"../hooks/useEventCallback\";\n\n/** Validate one edited value. Return a message to reject it, nothing to allow. */\nexport type CellValidator = (\n value: unknown,\n row: TRow\n) => string | undefined | Promise;\n\n/**\n * Validate the row an edit would produce.\n *\n * Return a message for a row-level problem, a map of column key → message to\n * mark individual cells, or nothing to allow the commit.\n */\nexport type RowValidator = (\n row: TRow\n) =>\n | string\n | Record\n | undefined\n | Promise | undefined>;\n\n/** A cell address, as the editing state spells it. */\nexport interface ValidationTarget {\n rowId: string;\n columnKey: string;\n}\n\n/** What {@link useEditValidation} needs. */\nexport interface UseEditValidationOptions {\n /** The row-level validator, when the host declared one. */\n validateRow?: RowValidator;\n /**\n * Apply an edit to a row without mutating it, so the row validator sees what\n * the commit WOULD produce rather than what is stored. Defaults to a shallow\n * spread keyed by the column key.\n */\n applyEdit?: (row: TRow, columnKey: string, value: unknown) => TRow;\n}\n\n/** Outcome of {@link EditValidationState.check}. */\nexport interface ValidationCheckResult {\n /** Whether the commit may proceed. */\n allowed: boolean;\n /**\n * Why it may not, when it may not. Absent when a newer check superseded\n * this one.\n */\n error?: string;\n}\n\n/** Validation state for the whole table. */\nexport interface EditValidationState {\n /** The message on one cell, if any. */\n errorFor: (rowId: string, columnKey: string) => string | undefined;\n /** The row-level message, if any. */\n rowErrorFor: (rowId: string) => string | undefined;\n /** Whether a cell's validators are still running. */\n isValidating: (rowId: string, columnKey: string) => boolean;\n /** Whether any cell in this row carries a message. */\n rowHasError: (rowId: string) => boolean;\n /**\n * Run the validators for one commit.\n *\n * `allowed` is whether the commit may proceed. A rejection also carries\n * `error` — the sentence the editor shows — so a caller that fires in the\n * same tick as the check does not have to wait for a render to read it.\n */\n check: (options: {\n target: ValidationTarget;\n value: unknown;\n row: TRow;\n validateCell?: CellValidator;\n }) => Promise;\n /** Forget everything about one cell — what cancelling an edit does. */\n clear: (rowId: string, columnKey: string) => void;\n /** Forget every message. */\n clearAll: () => void;\n /** A digest of the messages, for a row memo comparator. */\n signature: string;\n /**\n * Whether a row validator is armed. A cell with no validator of its own still\n * has to run the check when the table has one — a cross-field rule fires on\n * whichever cell was edited.\n */\n hasRowValidator: boolean;\n}\n\n/**\n * `rowId` and `columnKey` as one map key.\n *\n * A control character rather than a printable separator, because a column key\n * is arbitrary data: any separator that can appear inside one makes two\n * different cells share a key. Written as an escape so it is visible in this\n * file rather than invisible in it — a source file carrying a raw NUL is one\n * git treats as binary, with no diff and no blame.\n */\nconst cellKey = (rowId: string, columnKey: string) =>\n `${rowId}\\u0000${columnKey}`;\n\n/**\n * Headless validation state for inline editing.\n *\n * @typeParam TRow - The row type.\n * @param options - See {@link UseEditValidationOptions}.\n * @returns The state; inert until a validator rejects something.\n */\nexport function useEditValidation(\n options: UseEditValidationOptions = {}\n): EditValidationState {\n const [cellErrors, setCellErrors] = useState>(\n () => new Map()\n );\n const [rowErrors, setRowErrors] = useState>(\n () => new Map()\n );\n const [validating, setValidating] = useState>(\n () => new Set()\n );\n // One token per cell, bumped on every check: a check that resolves after a\n // newer one started must not write its verdict over the newer answer.\n const tokens = useRef(new Map());\n\n const setCellError = useEventCallback((key: string, message?: string) => {\n setCellErrors((current) => {\n if ((current.get(key) ?? undefined) === message) return current;\n const next = new Map(current);\n if (message === undefined) next.delete(key);\n else next.set(key, message);\n return next;\n });\n });\n\n const setRowError = useEventCallback((rowId: string, message?: string) => {\n setRowErrors((current) => {\n if ((current.get(rowId) ?? undefined) === message) return current;\n const next = new Map(current);\n if (message === undefined) next.delete(rowId);\n else next.set(rowId, message);\n return next;\n });\n });\n\n const markValidating = useEventCallback((key: string, busy: boolean) => {\n setValidating((current) => {\n if (current.has(key) === busy) return current;\n const next = new Set(current);\n if (busy) next.add(key);\n else next.delete(key);\n return next;\n });\n });\n\n const check = useEventCallback(\n async (input: {\n target: ValidationTarget;\n value: unknown;\n row: TRow;\n validateCell?: CellValidator;\n }): Promise => {\n const { target, value, row, validateCell } = input;\n const { validateRow, applyEdit = shallowApplyEdit } = options;\n if (!validateCell && !validateRow) return { allowed: true };\n\n const key = cellKey(target.rowId, target.columnKey);\n const token = (tokens.current.get(key) ?? 0) + 1;\n tokens.current.set(key, token);\n const current = () => tokens.current.get(key) === token;\n\n markValidating(key, true);\n try {\n const cellMessage = await validateCell?.(value, row);\n if (!current()) return { allowed: false };\n if (cellMessage !== undefined) {\n setCellError(key, cellMessage);\n setRowError(target.rowId, undefined);\n return { allowed: false, error: cellMessage };\n }\n const edited = applyEdit(row, target.columnKey, value);\n const rowVerdict = await validateRow?.(edited);\n if (!current()) return { allowed: false };\n return settleRowVerdict({\n verdict: rowVerdict,\n target,\n setCellError,\n setRowError,\n });\n } finally {\n if (current()) markValidating(key, false);\n }\n }\n );\n\n const clear = useEventCallback((rowId: string, columnKey: string) => {\n const key = cellKey(rowId, columnKey);\n tokens.current.set(key, (tokens.current.get(key) ?? 0) + 1);\n setCellError(key, undefined);\n setRowError(rowId, undefined);\n markValidating(key, false);\n });\n\n const clearAll = useEventCallback(() => {\n tokens.current.clear();\n setCellErrors(new Map());\n setRowErrors(new Map());\n setValidating(new Set());\n });\n\n // A value digest, so a row memo can compare messages without holding maps.\n const signature = useMemo(\n () =>\n [...cellErrors.entries(), ...rowErrors.entries(), ...validating]\n .flat()\n .join(\"\\u0001\"),\n [cellErrors, rowErrors, validating]\n );\n\n const errorFor = useCallback(\n (rowId: string, columnKey: string) =>\n cellErrors.get(cellKey(rowId, columnKey)),\n [cellErrors]\n );\n const rowErrorFor = useCallback(\n (rowId: string) => rowErrors.get(rowId),\n [rowErrors]\n );\n const isValidating = useCallback(\n (rowId: string, columnKey: string) =>\n validating.has(cellKey(rowId, columnKey)),\n [validating]\n );\n const rowHasError = useCallback(\n (rowId: string) => {\n if (rowErrors.has(rowId)) return true;\n const prefix = `${rowId}\\u0000`;\n for (const key of cellErrors.keys()) {\n if (key.startsWith(prefix)) return true;\n }\n return false;\n },\n [cellErrors, rowErrors]\n );\n\n return useMemo(\n () => ({\n errorFor,\n rowErrorFor,\n isValidating,\n rowHasError,\n check,\n clear,\n clearAll,\n signature,\n hasRowValidator: options.validateRow !== undefined,\n }),\n [\n errorFor,\n rowErrorFor,\n isValidating,\n rowHasError,\n check,\n clear,\n clearAll,\n signature,\n options.validateRow,\n ]\n );\n}\n\n/**\n * Record a row validator's verdict.\n *\n * A bare string is the row's own problem; a map names cells, which is how a\n * cross-field rule points at the field the reader should look at.\n */\nfunction settleRowVerdict(input: {\n verdict: string | Record | undefined;\n target: ValidationTarget;\n setCellError: (key: string, message?: string) => void;\n setRowError: (rowId: string, message?: string) => void;\n}): ValidationCheckResult {\n const { verdict, target, setCellError, setRowError } = input;\n const key = cellKey(target.rowId, target.columnKey);\n if (verdict === undefined) {\n setCellError(key, undefined);\n setRowError(target.rowId, undefined);\n return { allowed: true };\n }\n if (typeof verdict === \"string\") {\n setCellError(key, undefined);\n setRowError(target.rowId, verdict);\n return { allowed: false, error: verdict };\n }\n setRowError(target.rowId, undefined);\n for (const [columnKey, message] of Object.entries(verdict)) {\n setCellError(cellKey(target.rowId, columnKey), message);\n }\n // An empty map is a pass: the validator ran and named nothing.\n const keys = Object.keys(verdict);\n const firstKey = keys[0];\n if (firstKey === undefined) return { allowed: true };\n return {\n allowed: false,\n error: verdict[target.columnKey] ?? verdict[firstKey],\n };\n}\n\n/**\n * The row an edit would produce, without touching the stored one.\n *\n * A shallow spread keyed by the column key is right for the common case where a\n * column key IS the field. A host whose columns read nested paths passes its own\n * `applyEdit`.\n */\nfunction shallowApplyEdit(\n row: TRow,\n columnKey: string,\n value: unknown\n): TRow {\n return { ...row, [columnKey]: value };\n}\n","import { useMemo } from \"react\";\n\nimport type { ExtraFilters, FilterValue } from \"../types\";\n\n/** A single removable filter chip. */\nexport interface ActiveFilterChip {\n /** Stable identifier, e.g. `\"status:Active\"`. */\n key: string;\n /** Pre-translated label shown in the chip. */\n label: string;\n /** Remove-this-chip handler. */\n onRemove: () => void;\n}\n\n/** Translate a single raw filter value into a chip label. */\nexport type ChipLabelResolver = (value: string, extra?: ExtraFilters) => string;\n\n/**\n * Merge a table's derived filter chips with caller-supplied `extraChips`,\n * avoiding a new array allocation when either side is empty. Adapters call\n * this (memoised on the inputs) to build the final chip strip.\n *\n * @param filterChips - Chips derived from the table's own filter state.\n * @param extraChips - Optional caller-provided chips to append.\n * @returns The combined chip list (one of the inputs when the other is empty).\n */\nexport function mergeFilterChips(\n filterChips: readonly ActiveFilterChip[],\n extraChips: readonly ActiveFilterChip[] | undefined\n): readonly ActiveFilterChip[] {\n if (!extraChips?.length) return filterChips;\n if (filterChips.length === 0) return extraChips;\n return [...filterChips, ...extraChips];\n}\n\n/**\n * Resolve the active-filter count shown on the filters button: a positive\n * caller `override` wins, otherwise fall back to the number of visible chips.\n *\n * @param override - Caller-supplied count (e.g. for server-driven filters).\n * @param chipCount - Number of currently-visible chips.\n * @returns The count to display.\n */\nexport function resolveActiveFilterCount(\n override: number | undefined,\n chipCount: number\n): number {\n return override && override > 0 ? override : chipCount;\n}\n\n/** Options for {@link useActiveFilterChips}. */\nexport interface UseActiveFilterChipsOptions {\n /** Map of filter key → current value (typically a source's `extra`). */\n readonly values: Readonly>;\n /** Map of filter key → label resolver. Keys without a resolver are skipped. */\n readonly labels: Readonly>;\n /**\n * Called when a chip's ✕ is clicked. Receives the key and the next\n * desired value (the remaining array, or `undefined` when cleared).\n */\n readonly onChange: (key: string, next: FilterValue) => void;\n}\n\n/**\n * Flatten a bag of filter values into removable chips. Array values\n * become one chip per element (removing one keeps the rest); scalars\n * become a single chip. Empty values and keys without a resolver are\n * skipped.\n *\n * @param options - See {@link UseActiveFilterChipsOptions}.\n * @returns The derived chips, memoised on their inputs.\n */\nfunction pushChip(\n chips: ActiveFilterChip[],\n key: string,\n entry: string,\n label: string,\n onRemove: () => void\n): void {\n if (!label) return;\n chips.push({ key: `${key}:${entry}`, label, onRemove });\n}\n\nexport function useActiveFilterChips({\n values,\n labels,\n onChange,\n}: UseActiveFilterChipsOptions): ActiveFilterChip[] {\n return useMemo(() => {\n const chips: ActiveFilterChip[] = [];\n for (const [key, value] of Object.entries(values)) {\n // Own properties only — the keys come from the URL, and a crafted\n // `?f_valueOf=x` would otherwise pull Object.prototype.valueOf out\n // of the record and crash when called as a label resolver.\n const resolve = Object.hasOwn(labels, key) ? labels[key] : undefined;\n if (!resolve || value == null || value === \"\") {\n continue;\n }\n if (Array.isArray(value)) {\n for (const entry of value) {\n pushChip(chips, key, entry, resolve(entry, values), () => {\n const remaining = value.filter((v) => v !== entry);\n onChange(key, remaining.length > 0 ? remaining : undefined);\n });\n }\n } else {\n const text = String(value);\n pushChip(chips, key, text, resolve(text, values), () =>\n onChange(key, undefined)\n );\n }\n }\n return chips;\n }, [values, labels, onChange]);\n}\n","/**\n * The grouping keys, as a prop, as URL text, and as the list the model walks.\n *\n * Grouping travels as a comma-separated STRING — `?groupBy=team,status` — for\n * one reason: the URL and the source contract already carried a single key,\n * and a list that reads the same way keeps every link, saved view and\n * `source.setGroupBy` call ever written working. The array is what the model\n * and the adapters see; the string is what state is stored as.\n */\n\n/** How the grouping keys are written down: one key, a list, or nothing. */\nexport type GroupByInput = string | readonly string[] | null | undefined;\n\n/**\n * The grouping keys as a list, in order.\n *\n * Blank entries are dropped rather than grouped on: `\"team,\"` is a trailing\n * comma, not a request to group by a column with no name.\n *\n * @param value - The prop, the source value, or the URL parameter.\n * @returns The keys, possibly empty.\n */\nexport function parseGroupBy(value: GroupByInput): string[] {\n if (value === null || value === undefined) return [];\n const list = typeof value === \"string\" ? value.split(\",\") : value;\n return list.map((key) => key.trim()).filter((key) => key.length > 0);\n}\n\n/**\n * The grouping keys as the single string state is stored as.\n *\n * @param value - The keys.\n * @returns The joined string, or `undefined` when nothing is grouped.\n */\nexport function formatGroupBy(value: GroupByInput): string | undefined {\n const keys = parseGroupBy(value);\n return keys.length === 0 ? undefined : keys.join(\",\");\n}\n","import { useCallback, useMemo, useState } from \"react\";\n\nimport { useEventCallback } from \"../hooks/useEventCallback\";\n\n/** Collapse state + actions returned by {@link useGroupCollapse}. */\nexport interface GroupCollapseState {\n /** Ids of currently collapsed groups (`group:…` keys). */\n collapsedGroupIds: ReadonlySet;\n /** Whether a group is collapsed. */\n isCollapsed: (groupKey: string) => boolean;\n /** Toggle a group's collapsed state. */\n toggle: (groupKey: string) => void;\n /** Expand every group (clear the collapsed set). */\n expandAll: () => void;\n /** Collapse every group in `groupKeys`. */\n collapseAll: (groupKeys: readonly string[]) => void;\n /**\n * Show the tree down to `depth` and no further: every group at that depth or\n * deeper closes, everything above it opens. Depth 0 collapses the top level,\n * so only the outermost headers show.\n */\n collapseToDepth: (\n depth: number,\n groups: readonly { key: string; level: number }[]\n ) => void;\n}\n\n/**\n * Headless collapse state for single-level row groups. Ephemeral — not\n * URL-synced (punch-list #62). Groups default to expanded (empty set).\n */\nexport function useGroupCollapse(controlled?: {\n collapsedGroupIds?: readonly string[];\n onCollapsedGroupIdsChange?: (ids: string[]) => void;\n}): GroupCollapseState {\n const controlledIds = controlled?.collapsedGroupIds;\n const isControlled = controlledIds !== undefined;\n const [uncontrolled, setUncontrolled] = useState>(\n () => new Set()\n );\n\n const collapsedGroupIds = useMemo(\n () => (isControlled ? new Set(controlledIds ?? []) : uncontrolled),\n [isControlled, controlledIds, uncontrolled]\n );\n\n // Stable across renders on purpose: the options object arrives fresh from\n // the caller every time, and a `commit` that changed with it would change\n // every action here — which rebuilds the whole grouped model on a keystroke\n // that has nothing to do with grouping.\n const commit = useEventCallback((next: Set) => {\n if (isControlled) {\n controlled?.onCollapsedGroupIdsChange?.([...next]);\n } else {\n setUncontrolled(next);\n }\n });\n\n const isCollapsed = useCallback(\n (groupKey: string) => collapsedGroupIds.has(groupKey),\n [collapsedGroupIds]\n );\n\n const toggle = useCallback(\n (groupKey: string) => {\n const next = new Set(collapsedGroupIds);\n if (next.has(groupKey)) next.delete(groupKey);\n else next.add(groupKey);\n commit(next);\n },\n [collapsedGroupIds, commit]\n );\n\n const expandAll = useCallback(() => {\n commit(new Set());\n }, [commit]);\n\n const collapseAll = useCallback(\n (groupKeys: readonly string[]) => {\n commit(new Set(groupKeys));\n },\n [commit]\n );\n\n const collapseToDepth = useCallback(\n (depth: number, groups: readonly { key: string; level: number }[]) => {\n commit(\n new Set(\n groups.filter((group) => group.level >= depth).map((g) => g.key)\n )\n );\n },\n [commit]\n );\n\n return useMemo(\n () => ({\n collapsedGroupIds,\n isCollapsed,\n toggle,\n expandAll,\n collapseAll,\n collapseToDepth,\n }),\n [\n collapsedGroupIds,\n isCollapsed,\n toggle,\n expandAll,\n collapseAll,\n collapseToDepth,\n ]\n );\n}\n","/**\n * How much of a paged group model has been asked for.\n *\n * Revealing more is not a query: the rows are already in hand on the frontend\n * tier, and on a server tier the host fetches them and hands over a longer\n * list. So this holds nothing but counts — how many extra top-level groups,\n * and how many extra leaves per group — which is all the model needs to show\n * one more page of either.\n */\nimport { useCallback, useMemo, useState } from \"react\";\n\nimport type { GroupPaging } from \"./groupRows\";\n\n/** Paging state and the one action that changes it. */\nexport interface GroupPagingState {\n /** What the model reads. */\n paging: GroupPaging;\n /**\n * Reveal one more page. `groupKey` names the group whose leaves to extend;\n * omit it for the top-level groups.\n */\n showMore: (pageSize: number, groupKey?: string) => void;\n /** Back to the first page of everything — what new data calls for. */\n reset: () => void;\n}\n\n/**\n * Track how much of a paged group model is showing.\n *\n * @returns The state; inert until something calls `showMore`.\n */\nexport function useGroupPaging(): GroupPagingState {\n const [paging, setPaging] = useState({});\n\n const showMore = useCallback((pageSize: number, groupKey?: string) => {\n setPaging((current) => {\n if (groupKey === undefined) {\n return { ...current, groups: (current.groups ?? 0) + pageSize };\n }\n const rows = { ...current.rows };\n rows[groupKey] = (rows[groupKey] ?? 0) + pageSize;\n return { ...current, rows };\n });\n }, []);\n\n const reset = useCallback(() => {\n setPaging({});\n }, []);\n\n return useMemo(\n () => ({ paging, showMore, reset }),\n [paging, showMore, reset]\n );\n}\n","import { type RefObject, useEffect, useRef } from \"react\";\n\nimport { useEventCallback } from \"./useEventCallback\";\n\n/** Options for {@link useInfiniteScroll}. */\nexport interface UseInfiniteScrollOptions {\n /** Whether more pages remain to be fetched. */\n hasNextPage: boolean;\n /** Whether a page fetch is currently in flight. */\n isFetchingNextPage: boolean;\n /** Loads the next page; called when the sentinel scrolls into view. */\n fetchNextPage: () => void;\n /**\n * Master switch. When `false` the observer is never attached (e.g. in\n * paged mode, or when the consumer wants explicit \"Load more\" only).\n * @defaultValue true\n */\n enabled?: boolean;\n /**\n * `IntersectionObserver` root margin — how far before the sentinel enters\n * the viewport the next page is prefetched.\n * @defaultValue \"200px\"\n */\n rootMargin?: string;\n /**\n * The current number of rendered rows. Pass `source.rows.length` so the\n * observer re-arms after each page loads: when freshly-loaded content is\n * still shorter than the viewport the sentinel stays in view, and\n * re-observing re-fires the callback to keep loading until the viewport\n * fills or there is no next page. Omit to disable this auto-continue.\n */\n itemCount?: number;\n}\n\n/**\n * Auto-loads the next page when a sentinel element scrolls near the viewport,\n * turning a paginated {@link TableSource} into true infinite scroll. Attach\n * the returned ref to a small element rendered after the last row.\n *\n * SSR- and jsdom-safe: when `IntersectionObserver` is unavailable it no-ops,\n * so an accompanying \"Load more\" button remains the fallback. The latest\n * `fetchNextPage` is read from a ref, so passing a fresh closure each render\n * never re-subscribes the observer.\n *\n * @typeParam TElement - The sentinel element type.\n * @param options - See {@link UseInfiniteScrollOptions}.\n * @returns A ref to attach to the sentinel element.\n */\nexport function useInfiniteScroll<\n TElement extends HTMLElement = HTMLDivElement,\n>(options: UseInfiniteScrollOptions): RefObject {\n const {\n hasNextPage,\n isFetchingNextPage,\n fetchNextPage,\n enabled = true,\n rootMargin = \"200px\",\n itemCount,\n } = options;\n\n const ref = useRef(null);\n // The sentinel handler always sees the latest `fetchNextPage` /\n // `isFetchingNextPage` without re-subscribing the observer, so passing a\n // fresh closure each render never re-arms it.\n const onSentinelVisible = useEventCallback(() => {\n if (!isFetchingNextPage) fetchNextPage();\n });\n\n useEffect(() => {\n const el = ref.current;\n if (!enabled || !hasNextPage || el === null) return undefined;\n if (typeof IntersectionObserver === \"undefined\") return undefined;\n\n const observer = new IntersectionObserver(\n (entries) => {\n if (entries[0]?.isIntersecting) onSentinelVisible();\n },\n { rootMargin }\n );\n observer.observe(el);\n return () => observer.disconnect();\n }, [enabled, hasNextPage, rootMargin, itemCount, onSentinelVisible]);\n\n return ref;\n}\n","import { type RefObject, useEffect, useRef } from \"react\";\n\n/** Options for {@link useScrollToTableTop}. */\nexport interface UseScrollToTableTopOptions {\n /** Table/container element to bring back below sticky chrome. */\n ref: RefObject;\n /** Dependency values that represent table view changes. */\n deps: readonly unknown[];\n /** Master switch. Defaults to true. */\n enabled?: boolean;\n /** Sticky top offset in px. Defaults to 0. */\n offset?: number;\n /** Extra breathing room below the sticky chrome. Defaults to 8px. */\n gap?: number;\n /** Scroll behavior. Defaults to smooth. */\n behavior?: ScrollBehavior;\n}\n\n/**\n * Scroll the table back below sticky chrome after search/filter/page changes.\n * The initial render is skipped so deep links and restored browser positions\n * are not disturbed on first paint.\n */\nexport function useScrollToTableTop({\n ref,\n deps,\n enabled = true,\n offset = 0,\n gap = 8,\n behavior = \"smooth\",\n}: UseScrollToTableTopOptions): void {\n const depsKey = deps.map(String).join(\"|\");\n // Last-seen-value guard, not a boolean first-run flag: refs survive\n // StrictMode's simulated remount, so a boolean guard scrolled on the\n // doubled mount effect and yanked the browser's restored position. Only\n // an actual view change (a new deps key) scrolls.\n const lastDepsKeyRef = useRef(depsKey);\n\n useEffect(() => {\n if (lastDepsKeyRef.current === depsKey) return;\n lastDepsKeyRef.current = depsKey;\n if (!enabled) return;\n queueMicrotask(() => {\n const node = ref.current;\n if (!node) return;\n const top = node.getBoundingClientRect().top;\n if (top < offset) {\n window.scrollBy({\n top: top - offset - gap,\n behavior,\n });\n }\n });\n }, [behavior, depsKey, enabled, gap, offset, ref]);\n}\n","/**\n * An element's width, kept current.\n *\n * `undefined` until the first measurement — which matters, because \"not\n * measured yet\" and \"measured as narrow\" call for opposite behaviour. A\n * table that treated the first as the second would render its narrow layout\n * for one frame on every load, and under SSR (no `ResizeObserver`) it would\n * stay there.\n */\nimport type { RefObject } from \"react\";\nimport { useEffect, useState } from \"react\";\n\n/**\n * Track the content width of an element.\n *\n * @param ref - The element to measure.\n * @returns Its width in pixels, or `undefined` before the first measure.\n */\nexport function useElementWidth(\n ref: RefObject\n): number | undefined {\n const [width, setWidth] = useState(undefined);\n\n useEffect(() => {\n const node = ref.current;\n if (!node || typeof ResizeObserver === \"undefined\") return undefined;\n const measure = () => {\n setWidth(node.clientWidth);\n };\n const observer = new ResizeObserver(measure);\n observer.observe(node);\n measure();\n return () => {\n observer.disconnect();\n };\n }, [ref]);\n\n return width;\n}\n","/**\n * Per-row style and height — host callbacks over the same (row, index)\n * the class hook already uses. Omit both and nothing is applied.\n *\n * A number `rowHeight` is every row; a function is per row. The\n * virtualizer's `estimateSize` reads the same value so a variable-height\n * table windows correctly. `measureElement` stays authoritative for what\n * the browser actually laid out.\n *\n * These are functions of the row, not table state — nothing goes in the URL.\n */\nimport type { CSSProperties } from \"react\";\n\n/** One height, or a height from the row. */\nexport type RowHeight = number | ((row: TRow, index: number) => number);\n\n/** Conditional per-row inline style. */\nexport type RowStyle = (\n row: TRow,\n index: number\n) => CSSProperties | undefined;\n\n/** Resolve `rowHeight` for one row. */\nexport function resolveRowHeight(\n rowHeight: RowHeight | undefined,\n row: TRow,\n index: number\n): number | undefined {\n if (rowHeight === undefined) return undefined;\n return typeof rowHeight === \"number\" ? rowHeight : rowHeight(row, index);\n}\n\n/**\n * Merge `rowStyle` with an explicit height. Height wins when both name it —\n * `rowHeight` is the dedicated override.\n */\nexport function resolveRowStyle(\n rowStyle: RowStyle | undefined,\n rowHeight: RowHeight | undefined,\n row: TRow,\n index: number\n): CSSProperties | undefined {\n const style = rowStyle?.(row, index);\n const height = resolveRowHeight(rowHeight, row, index);\n if (style === undefined && height === undefined) return undefined;\n if (height === undefined) return style;\n return { ...style, height };\n}\n\n/** Stable compare key for a memoized row's resolved style. */\nexport function rowStyleSignature(style: CSSProperties | undefined): string {\n if (style === undefined) return \"\";\n return JSON.stringify(style);\n}\n\n/** True when the host asked for a style or a height. */\nexport function rowStyleArmed(\n rowStyle: RowStyle | undefined,\n rowHeight: RowHeight | undefined\n): boolean {\n return rowStyle !== undefined || rowHeight !== undefined;\n}\n\n/**\n * Virtualizer estimate: a constant, or a per-index read of `rowHeight`.\n * Group/extra slots fall back to `fallback` — they are not data rows.\n */\nexport function estimateFromRowHeight(\n rowHeight: RowHeight | undefined,\n fallback: number,\n rowAt: (index: number) => { row: TRow; index: number } | undefined\n): (index: number) => number {\n if (rowHeight === undefined) return () => fallback;\n if (typeof rowHeight === \"number\") return () => rowHeight;\n return (index: number) => {\n const found = rowAt(index);\n if (!found) return fallback;\n return rowHeight(found.row, found.index);\n };\n}\n","/**\n * Full-width and separator rows — host-injected slots between data rows.\n *\n * Grouping already speaks in `kind`s. These two join that vocabulary so a\n * kit maps one list: a separator is a thin rule, a full-width row is one\n * cell spanning the table. Omit `extraRows` and nothing is inserted.\n *\n * Position is `beforeRowId` (a data-row id). Omit it to append after the\n * last data row. Several extras sharing a target keep the host's order.\n * A named extra stays in front of that person through reorder and pin —\n * pin sections splice extras whose `beforeRowId` is in that section.\n *\n * Extras are content, not table state — nothing goes in the URL. Mobile\n * cards keep the same slots: a rule between cards, or a full-width note.\n */\nimport type { CSSProperties, ReactNode } from \"react\";\n\nimport { PIN_Z } from \"../columns/useColumnLayout\";\nimport { resolveRowStyle, type RowStyle } from \"./rowStyle\";\n\n/** What the host may inject. */\nexport type ExtraRowKind = \"separator\" | \"fullWidth\";\n\n/** One host-injected slot. */\nexport interface ExtraRow {\n /** Stable id — also the React key. */\n key: string;\n kind: ExtraRowKind;\n /**\n * Insert immediately before this data row. Omit to append after the\n * last data row in the list being interleaved.\n */\n beforeRowId?: string;\n /** Full-width body. Ignored on a separator. */\n render?: () => ReactNode;\n}\n\n/** A separator or full-width entry in a `kind`-tagged body list. */\nexport type ExtraEntry =\n | { kind: \"separator\"; key: string }\n | { kind: \"fullWidth\"; key: string; render?: () => ReactNode };\n\n/** Narrow a body slot to a host-injected extra. */\nexport function isExtraEntry(entry: object): entry is ExtraEntry {\n if (!(\"kind\" in entry)) return false;\n const kind = (entry as { kind?: unknown }).kind;\n return kind === \"separator\" || kind === \"fullWidth\";\n}\n\n/** True when the host asked for any extra slot. */\nexport function extraRowsArmed(\n extraRows: readonly ExtraRow[] | undefined\n): boolean {\n return Boolean(extraRows && extraRows.length > 0);\n}\n\nfunction toEntry(extra: ExtraRow): ExtraEntry {\n if (extra.kind === \"separator\") return { kind: \"separator\", key: extra.key };\n return { kind: \"fullWidth\", key: extra.key, render: extra.render };\n}\n\n/**\n * Splice extras into a `kind`-tagged list. `dataKey` names the data row\n * an entry represents — group headers return `undefined` and are never\n * a splice target.\n */\nexport function insertExtraRows(\n entries: readonly T[],\n extraRows: readonly ExtraRow[] | undefined,\n dataKey: (entry: T) => string | undefined\n): readonly (T | ExtraEntry)[] {\n if (!extraRows || extraRows.length === 0) return entries;\n const before = new Map();\n const append: ExtraRow[] = [];\n for (const extra of extraRows) {\n if (extra.beforeRowId === undefined) {\n append.push(extra);\n continue;\n }\n const bucket = before.get(extra.beforeRowId) ?? [];\n bucket.push(extra);\n before.set(extra.beforeRowId, bucket);\n }\n const result: (T | ExtraEntry)[] = [];\n for (const entry of entries) {\n const id = dataKey(entry);\n if (id !== undefined) {\n const waiting = before.get(id);\n if (waiting) {\n for (const extra of waiting) result.push(toEntry(extra));\n before.delete(id);\n }\n }\n result.push(entry);\n }\n for (const extra of append) result.push(toEntry(extra));\n return result;\n}\n\n/**\n * Extras whose `beforeRowId` sits in this section. Untargeted extras\n * (no `beforeRowId`) are included only when `appendUntargeted` is true —\n * those still belong at the end of the scroll body, not in a pin section.\n */\nexport function extraRowsForSection(\n extraRows: readonly ExtraRow[] | undefined,\n rowIds: ReadonlySet,\n appendUntargeted = false\n): readonly ExtraRow[] | undefined {\n if (!extraRows || extraRows.length === 0) return extraRows;\n const next = extraRows.filter((extra) => {\n if (extra.beforeRowId === undefined) return appendUntargeted;\n return rowIds.has(extra.beforeRowId);\n });\n return next.length === 0 ? undefined : next;\n}\n\n/**\n * Splice extras whose `beforeRowId` is in this row list. Use on a pin\n * section so a named extra stays in front of a pinned person.\n */\nexport function insertExtrasBeforeRows(\n rows: readonly TRow[],\n extraRows: readonly ExtraRow[] | undefined,\n getRowId: (row: TRow) => string\n): readonly ({ key: string; row: TRow } | ExtraEntry)[] {\n const ids = new Set(rows.map(getRowId));\n return insertExtraRows(\n rows.map((row) => ({ key: getRowId(row), row })),\n extraRowsForSection(extraRows, ids),\n (entry) => entry.key\n );\n}\n\n/**\n * Lift an extra row above a continuing Team span so the note is not hidden\n * under it. Padding is the extra's own height — it is not folded into the\n * person below. Fill comes from that person's `rowStyle` (see\n * {@link extraHostFillStyle}); AdaptTable does not pick a colour.\n */\nexport const EXTRA_OVER_SPAN_ROW_STYLE: CSSProperties = {\n position: \"relative\",\n zIndex: PIN_Z.rowPinned,\n};\n\n/** Cell paint for an extra: RTL-safe align, and room for a line of text. */\nexport const EXTRA_OVER_SPAN_STYLE: CSSProperties = {\n textAlign: \"start\",\n paddingBlock: \"0.75rem\",\n paddingInline: \"0.75rem\",\n};\n\n/**\n * The fill the host already passed for this extra's person. Height is not\n * copied — extras size from their own padding, not `rowHeight`.\n */\nexport function extraHostFillStyle(\n extraKey: string,\n extraRows: readonly ExtraRow[] | undefined,\n rows: readonly TRow[],\n getRowId: (row: TRow) => string,\n rowStyle: RowStyle | undefined\n): CSSProperties | undefined {\n const extra = extraRows?.find((item) => item.key === extraKey);\n if (!extra?.beforeRowId) return undefined;\n const index = rows.findIndex((row) => getRowId(row) === extra.beforeRowId);\n if (index < 0) return undefined;\n const visual = resolveRowStyle(rowStyle, undefined, rows[index]!, index);\n if (!visual) return undefined;\n const fill: CSSProperties = {};\n if (visual.backgroundColor !== undefined) {\n fill.backgroundColor = visual.backgroundColor;\n }\n if (visual.background !== undefined) fill.background = visual.background;\n return Object.keys(fill).length > 0 ? fill : undefined;\n}\n\n/** Part names every kit stamps on an extra row. */\nexport const EXTRA_ROW_PARTS = {\n separator: { row: \"separator-row\", cell: \"separator-cell\" },\n fullWidth: { row: \"full-width-row\", cell: \"full-width-cell\" },\n} as const;\n\n/** How many extras sit immediately in front of any of these data-row ids. */\nexport function extraCountBeforeRowIds(\n extraRows: readonly ExtraRow[] | undefined,\n ids: ReadonlySet\n): number {\n if (!extraRows || extraRows.length === 0 || ids.size === 0) return 0;\n let count = 0;\n for (const extra of extraRows) {\n if (extra.beforeRowId !== undefined && ids.has(extra.beforeRowId)) {\n count += 1;\n }\n }\n return count;\n}\n\n/**\n * Grow a data-row `rowSpan` so it still reaches the last covered person\n * after extras in front of those people take `` slots.\n */\nexport function inflateBodyCellRowSpans<\n TCell extends { columnIndex: number; colSpan: number; rowSpan: number },\n>(\n cellsByRow: ReadonlyMap,\n visualIds: readonly string[],\n extraRows: readonly ExtraRow[] | undefined\n): ReadonlyMap {\n if (!extraRows?.length) return cellsByRow;\n const indexOf = new Map(visualIds.map((id, index) => [id, index] as const));\n const next = new Map();\n for (const [id, cells] of cellsByRow) {\n const origin = indexOf.get(id);\n if (origin === undefined) {\n next.set(id, cells);\n continue;\n }\n let changed = false;\n const updated = cells.map((cell) => {\n if (cell.rowSpan <= 1) return cell;\n const extraCount = extraCountBeforeRowIds(\n extraRows,\n new Set(visualIds.slice(origin + 1, origin + cell.rowSpan))\n );\n if (extraCount === 0) return cell;\n changed = true;\n return { ...cell, rowSpan: cell.rowSpan + extraCount };\n });\n next.set(id, changed ? updated : cells);\n }\n return next;\n}\n\ntype VisualSlot =\n | { kind: \"extra\"; beforeId: string }\n | { kind: \"row\"; id: string };\n\nfunction visualBodySlots(\n visualIds: readonly string[],\n extraRows: readonly ExtraRow[] | undefined\n): readonly VisualSlot[] {\n const buckets = new Map();\n for (const extra of extraRows ?? []) {\n if (extra.beforeRowId === undefined) continue;\n const list = buckets.get(extra.beforeRowId) ?? [];\n list.push(extra);\n buckets.set(extra.beforeRowId, list);\n }\n const slots: VisualSlot[] = [];\n for (const id of visualIds) {\n for (const extra of buckets.get(id) ?? []) {\n slots.push({ kind: \"extra\", beforeId: extra.beforeRowId ?? id });\n }\n slots.push({ kind: \"row\", id });\n }\n return slots;\n}\n\nfunction visualSlotIndexes(\n slots: readonly VisualSlot[],\n beforeRowId: string\n): { extraIndexes: number[]; rowSlotIndex: Map } {\n const extraIndexes: number[] = [];\n const rowSlotIndex = new Map();\n for (let index = 0; index < slots.length; index += 1) {\n const slot = slots[index]!;\n if (slot.kind === \"extra\" && slot.beforeId === beforeRowId) {\n extraIndexes.push(index);\n }\n if (slot.kind === \"row\") rowSlotIndex.set(slot.id, index);\n }\n return { extraIndexes, rowSlotIndex };\n}\n\nfunction coverContinuingSpans(\n cellsByRow: ReadonlyMap<\n string,\n readonly { columnIndex: number; colSpan: number; rowSpan: number }[]\n >,\n extraIndexes: number[],\n rowSlotIndex: Map,\n leadingCells: number,\n covered: Set\n): void {\n for (const [id, cells] of cellsByRow) {\n const start = rowSlotIndex.get(id);\n if (start === undefined) continue;\n for (const cell of cells) {\n addSpanCoverage(cell, start, extraIndexes, leadingCells, covered);\n }\n }\n}\n\nfunction addSpanCoverage(\n cell: { columnIndex: number; colSpan: number; rowSpan: number },\n start: number,\n extraIndexes: number[],\n leadingCells: number,\n covered: Set\n): void {\n if (cell.rowSpan <= 1) return;\n const end = start + cell.rowSpan;\n for (const extraIndex of extraIndexes) {\n if (extraIndex <= start || extraIndex >= end) continue;\n for (let offset = 0; offset < cell.colSpan; offset += 1) {\n covered.add(leadingCells + cell.columnIndex + offset);\n }\n }\n}\n\n/**\n * Table-slot indexes (leading chrome + data columns) a continuing row span\n * already owns on extras in front of this person — those extras omit a ``\n * there so the merge can keep going.\n */\nexport function extraCoveredTableSlots(\n beforeRowId: string,\n options: {\n visualIds: readonly string[];\n cellsByRow: ReadonlyMap<\n string,\n readonly { columnIndex: number; colSpan: number; rowSpan: number }[]\n >;\n extraRows?: readonly ExtraRow[];\n leadingCells: number;\n }\n): ReadonlySet {\n const { visualIds, cellsByRow, extraRows, leadingCells } = options;\n const covered = new Set();\n const { extraIndexes, rowSlotIndex } = visualSlotIndexes(\n visualBodySlots(visualIds, extraRows),\n beforeRowId\n );\n if (extraIndexes.length === 0) return covered;\n coverContinuingSpans(\n cellsByRow,\n extraIndexes,\n rowSlotIndex,\n leadingCells,\n covered\n );\n return covered;\n}\n\n/** Uncovered colSpans for an extra row that has to leave holes for a row span. */\nexport function extraUncoveredColSpans(\n columnSpan: number,\n coveredSlots: ReadonlySet | undefined\n): readonly number[] {\n if (!coveredSlots || coveredSlots.size === 0) return [columnSpan];\n const spans: number[] = [];\n let index = 0;\n while (index < columnSpan) {\n if (coveredSlots.has(index)) {\n index += 1;\n continue;\n }\n let span = 1;\n while (index + span < columnSpan && !coveredSlots.has(index + span)) {\n span += 1;\n }\n spans.push(span);\n index += span;\n }\n return spans.length === 0 ? [columnSpan] : spans;\n}\n","/**\n * Adding, duplicating and deleting rows — the asking, never the data.\n *\n * These three sit at the boundary between the table and the host: the table\n * knows *when* the reader asked (a toolbar control, a row action) and the host\n * knows what a new row IS, what a copy of one means, and whether it may go. So\n * the table asks and the host does the rest — the same one-way flow every other\n * write already follows, which is what keeps a new row an ordinary row: it\n * arrives through the source like all the others, and editing, validation,\n * grouping, the hierarchy and virtualization need to know nothing about it.\n *\n * Duplicate and delete arrive as ordinary {@link RowAction}s, so every kit\n * already renders them — trailing buttons on desktop, card buttons on mobile,\n * hideable and end-pinnable with the actions column, and confirmable through\n * the same dialog a host's own destructive action uses.\n */\nimport { useMemo } from \"react\";\n\nimport { useEventCallback } from \"../hooks/useEventCallback\";\nimport type { RowAction, TableLabels } from \"../types\";\n\n/** How a table asks for a row to be added, copied or removed. */\nexport interface RowMutationHandlers {\n /**\n * Add a row. Setting this puts an Add control in the toolbar; the host makes\n * the row and stores it, and it reaches the table through the source like\n * every other row — editable, filterable and countable from the moment it\n * lands, with nothing about it special.\n */\n onAddRow?: () => unknown;\n /**\n * Copy a row. Setting this puts a Duplicate action on every row; what a copy\n * means — which fields carry over, which are reset, what id it gets — is the\n * host's, because only the host knows.\n */\n onDuplicateRow?: (row: TRow) => unknown;\n /**\n * Remove a row. Setting this puts a Delete action on every row, behind a\n * confirmation dialog unless {@link RowMutationHandlers.confirmDeleteRow} is\n * `false`.\n */\n onDeleteRow?: (row: TRow) => unknown;\n /**\n * Delete without asking first. Off by default: a delete is destructive and\n * the table cannot undo it. Hosts whose own UI already confirms — or whose\n * delete is reversible — turn it off.\n */\n confirmDeleteRow?: boolean;\n}\n\n/** Row-mutation state: the toolbar's control and the per-row actions. */\nexport interface RowMutationsState {\n /** Whether an Add control should render. */\n canAdd: boolean;\n /** Ask for a new row. Inert without `onAddRow`. */\n addRow: () => void;\n /**\n * Duplicate and Delete, in that order — empty when the host wired neither.\n * Appended to the host's own `rowActions`, so a delete stays last.\n */\n actions: readonly RowAction[];\n}\n\n/** What {@link useRowMutations} needs. */\nexport interface UseRowMutationsOptions<\n TRow,\n> extends RowMutationHandlers {\n /** Resolved labels, for the action names and the delete dialog. */\n labels: Required;\n}\n\n/** The key of the synthesized duplicate action. */\nexport const DUPLICATE_ROW_ACTION_KEY = \"adapttable:duplicate-row\";\n/** The key of the synthesized delete action. */\nexport const DELETE_ROW_ACTION_KEY = \"adapttable:delete-row\";\n\n/**\n * Headless add / duplicate / delete wiring.\n *\n * @typeParam TRow - The row type.\n * @param options - See {@link UseRowMutationsOptions}.\n * @returns The state; every action is absent until its handler is wired.\n */\nexport function useRowMutations(\n options: UseRowMutationsOptions\n): RowMutationsState {\n const { onDuplicateRow, onDeleteRow, confirmDeleteRow, labels } = options;\n\n // Stable identities: a row action list that changes shape every render would\n // defeat the memoized rows the whole body depends on.\n const addRow = useEventCallback(() => {\n options.onAddRow?.();\n });\n const duplicate = useEventCallback((row: TRow) => {\n options.onDuplicateRow?.(row);\n });\n const remove = useEventCallback((row: TRow) => {\n options.onDeleteRow?.(row);\n });\n\n const canAdd = options.onAddRow !== undefined;\n const canDuplicate = onDuplicateRow !== undefined;\n const canDelete = onDeleteRow !== undefined;\n const confirmDelete = confirmDeleteRow !== false;\n const { duplicateRow, deleteRow, deleteRowConfirm } = labels;\n\n const actions = useMemo[]>(() => {\n const built: RowAction[] = [];\n if (canDuplicate) {\n built.push({\n key: DUPLICATE_ROW_ACTION_KEY,\n label: duplicateRow,\n onClick: duplicate,\n });\n }\n if (canDelete) {\n built.push({\n key: DELETE_ROW_ACTION_KEY,\n label: deleteRow,\n // The kits' destructive token — the same one a host's own delete uses.\n color: \"red\",\n onClick: remove,\n confirm: confirmDelete\n ? {\n title: deleteRow,\n message: () => deleteRowConfirm,\n confirmLabel: deleteRow,\n danger: true,\n }\n : undefined,\n });\n }\n return built;\n }, [\n canDuplicate,\n canDelete,\n confirmDelete,\n duplicate,\n remove,\n duplicateRow,\n deleteRow,\n deleteRowConfirm,\n ]);\n\n return useMemo(\n () => ({ canAdd, addRow, actions }),\n [canAdd, addRow, actions]\n );\n}\n","/**\n * Row pinning — the asking, never the data.\n *\n * A pinned row stays put through scroll: it leaves the virtual window and\n * renders in a sticky section above or below it. The host owns the id lists\n * (`pinnedRowIds` / `onPinnedRowIdsChange`); the table never mutates them.\n * Grouping and trees refuse it the same way they refuse reorder — a nested\n * list is not a flat pin stack.\n *\n * Mobile cards are a list, not a grid: the pin actions write the same state,\n * but there is no sticky chrome. The order of the list still puts top pins\n * first and bottom pins last.\n */\nimport { useCallback, useMemo, useRef, useState } from \"react\";\n\nimport { useEventCallback } from \"../hooks/useEventCallback\";\nimport type { RowAction, TableLabels } from \"../types\";\n\n/** Which edge a pinned row sticks to. */\nexport type RowPinSide = \"top\" | \"bottom\";\n\n/** Controlled pin lists — ids in dataset order within each edge. */\nexport interface RowPinState {\n readonly top: readonly string[];\n readonly bottom: readonly string[];\n}\n\n/** Empty pin lists — omit `pinnedRowIds` and this is what the table holds. */\nexport const EMPTY_ROW_PIN_STATE: RowPinState = { top: [], bottom: [] };\n\n/** Synthesized \"Pin to top\" action. */\nexport const PIN_TOP_ACTION_KEY = \"adapttable:pin-row-top\";\n/** Synthesized \"Pin to bottom\" action. */\nexport const PIN_BOTTOM_ACTION_KEY = \"adapttable:pin-row-bottom\";\n/** Synthesized \"Unpin\" action. */\nexport const UNPIN_ROW_ACTION_KEY = \"adapttable:unpin-row\";\n\n/** Labels the pin actions and the live region need. */\nexport interface RowPinLabels {\n pinToTop: string;\n pinToBottom: string;\n unpinRow: string;\n}\n\n/** Headless pin state adapters read. */\nexport interface RowPinningState {\n /** Current lists. */\n state: RowPinState;\n /** Which edge a row is pinned to, if any. */\n sideOf: (rowId: string) => RowPinSide | undefined;\n /** Pin a row to an edge (moves it if it was on the other). */\n pin: (rowId: string, side: RowPinSide) => void;\n /** Remove a row from both edges. */\n unpin: (rowId: string) => void;\n /** Pin actions, hidden per row so a top-pinned row does not offer Pin to top. */\n actions: readonly RowAction[];\n}\n\n/** Split a row list into top pins, the scroll window, and bottom pins. */\nexport function partitionPinnedRows(\n rows: readonly TRow[],\n state: RowPinState,\n getRowId: (row: TRow) => string\n): { top: TRow[]; scroll: TRow[]; bottom: TRow[] } {\n const topSet = new Set(state.top);\n const bottomSet = new Set(state.bottom);\n const byId = new Map();\n for (const row of rows) byId.set(getRowId(row), row);\n const top: TRow[] = [];\n for (const id of state.top) {\n const row = byId.get(id);\n if (row !== undefined) top.push(row);\n }\n const bottom: TRow[] = [];\n for (const id of state.bottom) {\n const row = byId.get(id);\n if (row !== undefined) bottom.push(row);\n }\n const scroll: TRow[] = [];\n for (const row of rows) {\n const id = getRowId(row);\n if (!topSet.has(id) && !bottomSet.has(id)) scroll.push(row);\n }\n return { top, scroll, bottom };\n}\n\n/** Memo digest so a virtualized row repaints when it is pinned or unpinned. */\nexport function rowPinSignature(\n pinning: Pick, \"sideOf\"> | undefined,\n rowId: string\n): string | null {\n if (!pinning) return null;\n return pinning.sideOf(rowId) ?? \"\";\n}\n\nfunction withoutId(ids: readonly string[], rowId: string): string[] {\n return ids.filter((id) => id !== rowId);\n}\n\nfunction withId(ids: readonly string[], rowId: string): string[] {\n return ids.includes(rowId) ? [...ids] : [...ids, rowId];\n}\n\n/** Apply a pin or unpin to a copy of the state. */\nexport function applyRowPin(\n state: RowPinState,\n rowId: string,\n side: RowPinSide | undefined\n): RowPinState {\n const top = withoutId(state.top, rowId);\n const bottom = withoutId(state.bottom, rowId);\n if (side === \"top\") return { top: withId(top, rowId), bottom };\n if (side === \"bottom\") return { top, bottom: withId(bottom, rowId) };\n return { top, bottom };\n}\n\nfunction sameLists(a: readonly string[], b: readonly string[]): boolean {\n if (a.length !== b.length) return false;\n return a.every((id, index) => id === b[index]);\n}\n\nfunction sameState(a: RowPinState, b: RowPinState): boolean {\n return sameLists(a.top, b.top) && sameLists(a.bottom, b.bottom);\n}\n\n/**\n * Headless row pinning. Inert until the host passes {@link UseRowPinningOptions.enabled};\n * omit the prop and this hook still runs (Rules of Hooks) but every action no-ops.\n */\nexport function useRowPinning(options: {\n enabled: boolean;\n pinnedRowIds?: RowPinState;\n onPinnedRowIdsChange?: (next: RowPinState) => void;\n getRowId: (row: TRow) => string;\n labels: RowPinLabels;\n}): RowPinningState {\n const { enabled, labels } = options;\n const controlledValue = options.pinnedRowIds;\n const onChange = options.onPinnedRowIdsChange;\n const [internal, setInternal] = useState(EMPTY_ROW_PIN_STATE);\n const controlled = controlledValue !== undefined;\n const state = controlledValue ?? internal;\n\n const modeRef = useRef({ controlled, onChange, state, enabled });\n modeRef.current = { controlled, onChange, state, enabled };\n\n const commit = useCallback((next: RowPinState) => {\n const live = modeRef.current;\n if (!live.enabled) return;\n if (sameState(live.state, next)) return;\n if (live.controlled) {\n live.onChange?.(next);\n } else {\n setInternal(next);\n }\n }, []);\n\n const pin = useEventCallback((rowId: string, side: RowPinSide) => {\n commit(applyRowPin(modeRef.current.state, rowId, side));\n });\n const unpin = useEventCallback((rowId: string) => {\n commit(applyRowPin(modeRef.current.state, rowId, undefined));\n });\n\n const sideOf = useCallback(\n (rowId: string): RowPinSide | undefined => {\n if (state.top.includes(rowId)) return \"top\";\n if (state.bottom.includes(rowId)) return \"bottom\";\n return undefined;\n },\n [state]\n );\n\n const getRowId = useEventCallback(options.getRowId);\n\n const actions = useMemo[]>(() => {\n if (!enabled) return [];\n return [\n {\n key: PIN_TOP_ACTION_KEY,\n label: labels.pinToTop,\n isHidden: (row) => sideOf(getRowId(row)) === \"top\",\n onClick: (row) => {\n pin(getRowId(row), \"top\");\n },\n },\n {\n key: PIN_BOTTOM_ACTION_KEY,\n label: labels.pinToBottom,\n isHidden: (row) => sideOf(getRowId(row)) === \"bottom\",\n onClick: (row) => {\n pin(getRowId(row), \"bottom\");\n },\n },\n {\n key: UNPIN_ROW_ACTION_KEY,\n label: labels.unpinRow,\n isHidden: (row) => sideOf(getRowId(row)) === undefined,\n onClick: (row) => {\n unpin(getRowId(row));\n },\n },\n ];\n }, [enabled, getRowId, labels, pin, sideOf, unpin]);\n\n return useMemo(\n () => ({ state, sideOf, pin, unpin, actions }),\n [actions, pin, sideOf, state, unpin]\n );\n}\n\n/** Labels a host may override; resolved through {@link TableLabels}. */\nexport type RowPinTableLabels = Pick<\n Required,\n \"pinToTop\" | \"pinToBottom\" | \"unpinRow\"\n>;\n","/**\n * Row reordering — the asking, never the data.\n *\n * Pointer drag follows the column-menu pattern (a MIME type, drop targets,\n * a grip). Keyboard is a grab: Space lifts, arrows move, Space drops,\n * Escape cancels, each step announced. The table never mutates the array;\n * `onRowReorder(from, to, row)` is the same one-way write as `onCellEdit`.\n *\n * `from` / `to` are dataset-relative: the row's index in the current source\n * plus the page offset (`windowStart`), so a virtual window or a paged slice\n * does not lie to the host about where the row sits.\n */\nimport type { CSSProperties, DragEvent, KeyboardEvent } from \"react\";\nimport { useCallback, useMemo, useState } from \"react\";\n\nimport { useEventCallback } from \"../hooks/useEventCallback\";\nimport { isRtlElement } from \"../layout/writingDirection\";\n\n/** MIME type carrying the dragged row id during a reorder drag. */\nexport const ROW_DND_MIME = \"application/x-adapttable-row\";\n\nexport { REORDER_COLUMN_KEY } from \"../columns/columnMenuModel\";\n\n/** Width (px) of the injected reorder column — shared so pin leads agree. */\nexport const REORDER_COLUMN_WIDTH = 40;\n\n/**\n * Dim the lifted row and draw an insertion line on the drop target.\n * Kits apply this so a host without CSS still sees the gesture; unstyled\n * hosts can also target `data-dragging` / `data-drop` from classNames.\n */\nexport function rowReorderDropStyle(\n attrs: { \"data-dragging\"?: \"\"; \"data-drop\"?: \"before\" | \"after\" } | undefined\n): CSSProperties {\n if (attrs === undefined) return {};\n const edge = attrs[\"data-drop\"];\n const offset = edge === \"before\" ? \"2px\" : \"-2px\";\n return {\n opacity: attrs[\"data-dragging\"] === \"\" ? 0.45 : undefined,\n boxShadow: edge ? `inset 0 ${offset} 0 0 currentColor` : undefined,\n };\n}\n\n/** Move `from` to `to` in a copy of `rows`. Out-of-range is a no-op copy. */\nexport function applyRowReorder(\n rows: readonly T[],\n from: number,\n to: number\n): T[] {\n if (\n from === to ||\n from < 0 ||\n to < 0 ||\n from >= rows.length ||\n to >= rows.length\n ) {\n return rows.slice();\n }\n const next = rows.slice();\n const [item] = next.splice(from, 1);\n if (item === undefined) return rows.slice();\n next.splice(to, 0, item);\n return next;\n}\n\n/** Dataset-relative index: the rendered slot plus the page/window offset. */\nexport function datasetIndex(localIndex: number, windowStart: number): number {\n return windowStart + localIndex;\n}\n\n/** What a host receives when the reader drops a row. */\nexport type RowReorderHandler = (\n from: number,\n to: number,\n row: TRow\n) => void;\n\n/** Labels the reorder handle and the live region need. */\nexport interface RowReorderLabels {\n reorderRow: string;\n moveRowUp: string;\n moveRowDown: string;\n rowLifted: (position: number) => string;\n rowMoved: (from: number, to: number) => string;\n rowReorderCancelled: string;\n}\n\n/** Headless reorder state returned by {@link useRowReorder}. */\nexport interface RowReorderState {\n /** The lifted row, or `null` when idle. */\n lifted: { rowId: string; from: number } | null;\n /** Hovered drop index (local), or `null`. */\n overIndex: number | null;\n /** Live-region text. Empty until something happens. */\n announcement: string;\n /** Whether this row is the one being moved. */\n isLifted: (rowId: string) => boolean;\n /** Pointer: start a drag from this row. */\n dragProps: (\n rowId: string,\n localIndex: number\n ) => {\n draggable: true;\n onDragStart: (event: DragEvent) => void;\n onDragEnd: () => void;\n };\n /** Pointer: this row is a drop target. */\n dropProps: (\n localIndex: number,\n row: TRow,\n windowStart: number\n ) => {\n onDragOver: (event: DragEvent) => void;\n onDrop: (event: DragEvent) => void;\n };\n /** Keyboard: Space lifts / drops, arrows move, Escape cancels. */\n handleKeyDown: (\n event: KeyboardEvent,\n rowId: string,\n localIndex: number,\n row: TRow,\n windowStart: number,\n rowCount: number\n ) => void;\n /** Mobile: swap with the neighbour. */\n moveBy: (\n localIndex: number,\n delta: -1 | 1,\n row: TRow,\n windowStart: number,\n rowCount: number\n ) => void;\n /** Indicator attributes for a row. */\n rowAttrs: (\n rowId: string,\n localIndex: number\n ) => {\n \"data-dragging\"?: \"\";\n \"data-drop\"?: \"before\" | \"after\";\n };\n}\n\n/**\n * Per-row digest so a memoized row repaints when IT is lifted or is the drop\n * target, and bails out when the drag is happening to someone else.\n */\nexport function rowReorderSignature(\n reorder: RowReorderState | undefined,\n rowId: string,\n localIndex: number\n): string | null {\n if (!reorder) return null;\n const lifted = reorder.isLifted(rowId) ? \"d\" : \"\";\n const targeted =\n reorder.overIndex === localIndex && reorder.lifted !== null ? \"t\" : \"\";\n return `${lifted}${targeted}`;\n}\n\n/** Whether the grip sits in a right-to-left context. */\nfunction isRtl(grip: HTMLElement | null): boolean {\n return isRtlElement(grip);\n}\n\n/**\n * Headless row reorder. Inert until the host passes {@link RowReorderHandler};\n * omit it and this hook still runs (Rules of Hooks) but every builder no-ops.\n */\nexport function useRowReorder(options: {\n enabled: boolean;\n onRowReorder?: RowReorderHandler;\n labels: RowReorderLabels;\n /** Look up a row in the current source by its rendered index. */\n rowAt: (localIndex: number) => TRow | undefined;\n}): RowReorderState {\n const { enabled, labels } = options;\n const hostReorder = options.onRowReorder;\n const onRowReorder = useEventCallback(\n (from: number, to: number, row: TRow) => {\n hostReorder?.(from, to, row);\n }\n );\n const rowAt = useEventCallback(options.rowAt);\n\n const [lifted, setLifted] = useState<{\n rowId: string;\n from: number;\n } | null>(null);\n const [overIndex, setOverIndex] = useState(null);\n const [announcement, setAnnouncement] = useState(\"\");\n\n const reset = useCallback(() => {\n setLifted(null);\n setOverIndex(null);\n }, []);\n\n const commit = useEventCallback(\n (fromLocal: number, toLocal: number, row: TRow, windowStart: number) => {\n if (!enabled || fromLocal === toLocal) {\n reset();\n return;\n }\n const from = datasetIndex(fromLocal, windowStart);\n const to = datasetIndex(toLocal, windowStart);\n onRowReorder(from, to, row);\n setAnnouncement(labels.rowMoved(from + 1, to + 1));\n reset();\n }\n );\n\n const dragProps = useCallback[\"dragProps\"]>(\n (rowId, localIndex) => ({\n draggable: true,\n onDragStart: (event) => {\n if (!enabled) {\n event.preventDefault();\n return;\n }\n event.dataTransfer.setData(\n ROW_DND_MIME,\n `${rowId}:${String(localIndex)}`\n );\n event.dataTransfer.effectAllowed = \"move\";\n setLifted({ rowId, from: localIndex });\n setOverIndex(localIndex);\n },\n onDragEnd: reset,\n }),\n [enabled, reset]\n );\n\n const dropProps = useCallback[\"dropProps\"]>(\n (localIndex, row, windowStart) => ({\n onDragOver: (event) => {\n // Custom MIME types are often missing from `types` during dragover;\n // the lift flag is the reliable same-table signal.\n if (lifted === null) return;\n event.preventDefault();\n event.dataTransfer.dropEffect = \"move\";\n setOverIndex(localIndex);\n },\n onDrop: (event) => {\n const payload = event.dataTransfer.getData(ROW_DND_MIME);\n if (payload === \"\") return;\n event.preventDefault();\n const sep = payload.lastIndexOf(\":\");\n const fromLocal = Number(payload.slice(sep + 1));\n if (!Number.isFinite(fromLocal)) return;\n const dragged = rowAt(fromLocal);\n commit(fromLocal, localIndex, dragged ?? row, windowStart);\n },\n }),\n [commit, lifted, rowAt]\n );\n\n const handleKeyDown = useEventCallback(\n (\n event: KeyboardEvent,\n rowId: string,\n localIndex: number,\n row: TRow,\n windowStart: number,\n rowCount: number\n ) => {\n if (!enabled) return;\n if (event.key === \"Escape\" && lifted) {\n event.preventDefault();\n setAnnouncement(labels.rowReorderCancelled);\n reset();\n return;\n }\n if (event.key === \" \" || event.key === \"Spacebar\") {\n event.preventDefault();\n if (lifted?.rowId === rowId) {\n const to = overIndex ?? lifted.from;\n commit(lifted.from, to, row, windowStart);\n return;\n }\n setLifted({ rowId, from: localIndex });\n setOverIndex(localIndex);\n setAnnouncement(\n labels.rowLifted(datasetIndex(localIndex, windowStart) + 1)\n );\n return;\n }\n if (lifted?.rowId !== rowId) return;\n const rtl = isRtl(event.currentTarget);\n const down =\n event.key === \"ArrowDown\" ||\n event.key === (rtl ? \"ArrowLeft\" : \"ArrowRight\");\n const up =\n event.key === \"ArrowUp\" ||\n event.key === (rtl ? \"ArrowRight\" : \"ArrowLeft\");\n if (!down && !up) return;\n event.preventDefault();\n const next = Math.min(\n rowCount - 1,\n Math.max(0, (overIndex ?? lifted.from) + (down ? 1 : -1))\n );\n setOverIndex(next);\n }\n );\n\n const moveBy = useEventCallback(\n (\n localIndex: number,\n delta: -1 | 1,\n row: TRow,\n windowStart: number,\n rowCount: number\n ) => {\n const to = localIndex + delta;\n if (to < 0 || to >= rowCount) return;\n commit(localIndex, to, row, windowStart);\n }\n );\n\n const isLifted = useCallback(\n (rowId: string) => lifted?.rowId === rowId,\n [lifted]\n );\n\n const rowAttrs = useCallback[\"rowAttrs\"]>(\n (rowId, localIndex) => {\n const dragging = isLifted(rowId);\n const from = lifted?.from;\n const isTarget =\n overIndex === localIndex &&\n from !== undefined &&\n lifted?.rowId !== rowId;\n const dropSide =\n from !== undefined && localIndex > from ? \"after\" : \"before\";\n return {\n \"data-dragging\": dragging ? \"\" : undefined,\n \"data-drop\": isTarget ? dropSide : undefined,\n };\n },\n [isLifted, lifted, overIndex]\n );\n\n return useMemo(\n () => ({\n lifted,\n overIndex,\n announcement: enabled ? announcement : \"\",\n isLifted,\n dragProps,\n dropProps,\n handleKeyDown,\n moveBy,\n rowAttrs,\n }),\n [\n lifted,\n overIndex,\n enabled,\n announcement,\n isLifted,\n dragProps,\n dropProps,\n handleKeyDown,\n moveBy,\n rowAttrs,\n ]\n );\n}\n","import { useCallback, useMemo, useState } from \"react\";\n\n/** Expansion state + actions returned by {@link useRowExpansion}. */\nexport interface RowExpansionState {\n /** Ids of the currently expanded rows. */\n expandedIds: ReadonlySet;\n /** Whether a row is expanded. */\n isExpanded: (id: string) => boolean;\n /** Toggle a row's detail panel. */\n toggle: (id: string) => void;\n}\n\n/**\n * Headless row-expansion state for `renderRowDetail`: multiple rows may be\n * open at once, keyed by row id so expansion survives sorting and paging\n * (a row that leaves the page simply re-opens when it returns).\n *\n * @param defaultExpandedIds - Row ids whose panel starts open.\n */\nexport function useRowExpansion(\n defaultExpandedIds?: readonly string[]\n): RowExpansionState {\n const [expandedIds, setExpandedIds] = useState>(\n () => new Set(defaultExpandedIds)\n );\n\n const isExpanded = useCallback(\n (id: string) => expandedIds.has(id),\n [expandedIds]\n );\n\n const toggle = useCallback((id: string) => {\n setExpandedIds((prev) => {\n const next = new Set(prev);\n if (next.has(id)) next.delete(id);\n else next.add(id);\n return next;\n });\n }, []);\n\n return useMemo(\n () => ({ expandedIds, isExpanded, toggle }),\n [expandedIds, isExpanded, toggle]\n );\n}\n","/**\n * Groups computed by a server, rendered by the same table as local ones.\n *\n * A backend that can group is usually the only thing that CAN: it has the\n * whole dataset, and the browser has a page of it. So the server answers\n * `query.groupBy` with group rows — a value, a count, its aggregates, and\n * whatever children it chose to include — and this turns that answer into the\n * exact {@link GroupedFlatEntry} list local grouping produces.\n *\n * That reuse is the point. Every adapter already renders those entries, so\n * server-side grouping is not a second rendering path with its own bugs: it is\n * the same rows, filled from a different source of truth.\n */\nimport type { ReactNode } from \"react\";\n\nimport {\n formatGroupLabel,\n type GroupedFlatEntry,\n groupValueKey,\n makeGroupRowKey,\n} from \"../grouping/groupRows\";\n\n/**\n * One group row as a server returns it.\n *\n * Only `value` and `count` are required: a server that can count but not\n * aggregate, or group but not return children, is still useful and should not\n * have to send empty fields to say so.\n */\nexport interface QueryGroupRow {\n /** The grouping value at this level — what the table shows as the label. */\n value: unknown;\n /**\n * How many leaves sit beneath it, per the server. This is the number the\n * header shows, and it is the server's to know: the browser holds a page.\n */\n count: number;\n /** Aggregates the server computed for this group, keyed by column. */\n aggregates?: Readonly>;\n /** Nested groups, when the server grouped by more than one key. */\n groups?: readonly QueryGroupRow[];\n /**\n * The group's leaf rows, when the server included them. A server that sends\n * counts only leaves this out; the table then shows the header with its\n * count and asks for children when the group is opened.\n */\n rows?: readonly TRow[];\n}\n\n/** A page of grouped results. */\nexport interface QueryGroupsPage {\n /** The top-level groups, in the order the server wants them shown. */\n groups: readonly QueryGroupRow[];\n /** Total leaves across every group, when the server knows it. */\n total?: number;\n}\n\n/** What {@link serverGroupEntries} needs to lay a server's answer out. */\nexport interface ServerGroupEntriesOptions {\n /** The groups the server returned. */\n groups: readonly QueryGroupRow[];\n /** The grouping keys that were asked for, outermost first. */\n groupBy: readonly string[];\n /** Which groups are collapsed, by the same keys local grouping uses. */\n collapsedGroupIds: ReadonlySet;\n /** Row identity, for selection and React keys. */\n getRowId: (row: TRow) => string;\n /** Override the blank-group label (default `\"(blank)\"`). */\n blankLabel?: string;\n /** Close every group with a footer carrying its aggregates. */\n footers?: boolean;\n}\n\n/**\n * Turn a server's group rows into the flat entries adapters render.\n *\n * Counts come from the server rather than from the rows in hand — a group of\n * 4,000 says 4,000 even when the response carried 20 of them. The aggregates\n * are the server's too, passed through as they arrived, so a `sum` computed\n * over the whole dataset is the one displayed.\n *\n * @typeParam TRow - The row type.\n * @param options - See {@link ServerGroupEntriesOptions}.\n * @returns The entries, in render order.\n */\nexport function serverGroupEntries(\n options: ServerGroupEntriesOptions\n): GroupedFlatEntry[] {\n const {\n groups,\n groupBy,\n collapsedGroupIds,\n getRowId,\n blankLabel,\n footers = false,\n } = options;\n const flat: GroupedFlatEntry[] = [];\n let leafIndex = 0;\n\n const walk = (\n nodes: readonly QueryGroupRow[],\n level: number,\n path: readonly string[]\n ): void => {\n const key = groupBy[level] ?? groupBy.at(-1) ?? \"\";\n for (const node of nodes) {\n const here = [...path, groupValueKey(node.value)];\n const groupKey = makeGroupRowKey(groupBy.slice(0, level + 1), here);\n const collapsed = collapsedGroupIds.has(groupKey);\n const rows = node.rows ?? [];\n const label = formatGroupLabel(node.value, blankLabel);\n\n flat.push({\n kind: \"group\",\n key: groupKey,\n value: node.value,\n label,\n level,\n groupBy: key,\n path: here,\n // The rows the server sent, which may be none: `count` is what the\n // header reports, and it is the server's number, not this one.\n leafRows: rows,\n leafIds: rows.map((row) => getRowId(row)),\n serverCount: node.count,\n aggregateCells: renderableAggregates(node.aggregates),\n collapsed,\n });\n if (collapsed) continue;\n\n if (node.groups && node.groups.length > 0) {\n walk(node.groups, level + 1, here);\n } else {\n for (const row of rows) {\n flat.push({\n kind: \"row\",\n key: getRowId(row),\n row,\n index: leafIndex++,\n groupKey,\n });\n }\n }\n\n if (footers) {\n flat.push({\n kind: \"groupFooter\",\n key: `${groupKey}:footer`,\n groupKey,\n level,\n groupBy: key,\n label,\n leafRows: rows,\n leafIds: rows.map((row) => getRowId(row)),\n aggregateCells: renderableAggregates(node.aggregates),\n });\n }\n }\n };\n\n walk(groups, 0, []);\n return flat;\n}\n\n/**\n * A server's aggregate values as things React can render.\n *\n * JSON carries numbers, strings, booleans and nulls; a table cell can render\n * the first three. Anything else — an object a backend chose to nest — is\n * stringified rather than thrown at React, which would crash the row.\n *\n * @param aggregates - The values the server sent, if any.\n * @returns Renderable cells, or `undefined` when there were none.\n */\nfunction renderableAggregates(\n aggregates: Readonly> | undefined\n): Partial> | undefined {\n if (!aggregates) return undefined;\n const cells: Partial> = {};\n for (const [key, value] of Object.entries(aggregates)) {\n if (value === null || value === undefined) continue;\n cells[key] =\n typeof value === \"string\" ||\n typeof value === \"number\" ||\n typeof value === \"boolean\"\n ? value\n : JSON.stringify(value);\n }\n return cells;\n}\n","/**\n * The failure state, and what a host needs to replace it.\n *\n * Skeleton and empty are already slots a host can swap out, and they can be\n * plain nodes because there is nothing to say about them: a skeleton is a\n * skeleton. An error is different — it is *about* something, and the built-in\n * one carries a working retry. Handing back a node the host wrote in advance\n * would drop both, which is the same trap the `noResults` slot documents.\n *\n * So a slot here takes a node OR a function. Pass a node when the message is\n * fixed; pass a function when the replacement needs the error it is reporting\n * or the retry it should offer.\n */\nimport type { ReactNode } from \"react\";\n\nimport type { TableSource } from \"../source/TableSource\";\n\n/** What the error chrome is describing, and what it can do about it. */\nexport interface TableErrorState {\n /** The failure to surface. */\n error: Error;\n /**\n * Ask the source to try again, or `undefined` when it cannot — a static\n * `data` array has nothing to re-fetch, so no retry is offered rather than\n * one that does nothing.\n */\n retry?: () => void;\n /** Whether a retry is already in flight. */\n retrying: boolean;\n}\n\n/**\n * A replaceable piece of chrome: a node, or a function that builds one from\n * what the built-in was showing.\n *\n * @typeParam TState - What the built-in had to work with.\n */\nexport type Slot = ReactNode | ((state: TState) => ReactNode);\n\n/**\n * Resolve a slot the host may have replaced.\n *\n * @param slot - The host's replacement, if any.\n * @param state - What the built-in chrome was showing.\n * @returns The host's node, or `undefined` when they left the built-in alone.\n */\nexport function fillSlot(\n slot: Slot | undefined,\n state: TState\n): ReactNode {\n return typeof slot === \"function\" ? slot(state) : slot;\n}\n\n/**\n * The error state a source is in, or `undefined` when it is fine.\n *\n * Every adapter derives this the same way, so it is derived once here — the\n * retry in particular, which is only offered when the source can actually\n * perform one.\n *\n * @param source - The table's source.\n * @returns The state, or `undefined` when there is no failure to report.\n */\nexport function tableErrorState(\n source: TableSource\n): TableErrorState | undefined {\n if (!source.error) return undefined;\n const refetch = source.refetch;\n return {\n error: source.error,\n retry: refetch ? () => void refetch() : undefined,\n retrying: source.isFetching,\n };\n}\n","/**\n * The grouped or tree-shaped view, as an export can write it.\n *\n * Scopes still decide which *data* rows leave the table. This layer then\n * puts those rows back into the structure the reader can see — group\n * headers, outline depth, footers — so a spreadsheet is not a denormalised\n * dump of a grouped table.\n */\nimport type { GroupedFlatEntry } from \"../grouping/groupRows\";\nimport type { TreeEntry } from \"../tree/treeRows\";\nimport type { ExportViewEntry } from \"./exportWriter\";\n\n/**\n * A value a file can carry. JSX is a cell on screen, not a cell in a\n * spreadsheet — skip it rather than write \"[object Object]\".\n */\nexport function exportableValue(value: unknown): unknown {\n if (value instanceof Date) {\n return Number.isNaN(value.getTime()) ? undefined : value;\n }\n if (typeof value === \"number\") {\n return Number.isFinite(value) ? value : undefined;\n }\n if (typeof value === \"boolean\" || typeof value === \"string\") return value;\n return undefined;\n}\n\n/** Drop anything a file cannot type, keeping the keys that remain. */\nexport function exportableRecord(\n cells: Readonly>> | undefined\n): Partial> | undefined {\n if (!cells) return undefined;\n const out: Record = {};\n for (const [key, value] of Object.entries(cells)) {\n const next = exportableValue(value);\n if (next !== undefined) out[key] = next;\n }\n return Object.keys(out).length > 0 ? out : undefined;\n}\n\n/** Whether the next visible child of this group is a nested group. */\nfunction nextIsNestedGroup(\n entries: readonly GroupedFlatEntry[],\n index: number,\n level: number\n): boolean {\n for (let j = index + 1; j < entries.length; j++) {\n const next = entries[j];\n if (!next) return false;\n if (next.kind === \"group\") return next.level > level;\n if (next.kind === \"groupFooter\") return false;\n }\n return false;\n}\n\n/** Rows, \"load more\", and extras hidden because their leaves were dumped. */\nfunction skipHiddenLeaf(\n entry: GroupedFlatEntry,\n skipUntilLevel: number | undefined\n): boolean {\n if (skipUntilLevel === undefined) return false;\n if (entry.kind === \"group\" || entry.kind === \"groupFooter\") {\n return entry.level > skipUntilLevel;\n }\n return true;\n}\n\nfunction appendLeaves(\n out: ExportViewEntry[],\n rows: readonly TRow[],\n level: number\n): void {\n for (const row of rows) {\n out.push({ role: \"data\", row, level });\n }\n}\n\n/** The header row a group contributes, with whatever totals it carries. */\nfunction groupHeaderEntry(\n entry: Extract, { kind: \"group\" }>\n): ExportViewEntry {\n return {\n role: \"group\",\n label: entry.label,\n level: entry.level,\n labelKey: entry.groupBy,\n values: exportableRecord(entry.aggregateCells),\n };\n}\n\n/** The total row a group footer contributes. */\nfunction groupFooterEntry(\n entry: Extract, { kind: \"groupFooter\" }>,\n groupTotal?: (label: string) => string\n): ExportViewEntry {\n return {\n role: \"aggregate\",\n label: groupTotal ? groupTotal(entry.label) : entry.label,\n level: entry.level,\n labelKey: entry.groupBy,\n values: exportableRecord(entry.aggregateCells),\n };\n}\n\n/**\n * Flatten grouping entries into export view rows.\n *\n * Headers and footers keep their outline level. Leaves sit one level\n * deeper than the group they belong to, which is what Excel's outline\n * expects. \"Load more\" and extra rows are render chrome and stay out.\n *\n * @typeParam TRow - The row type.\n * @param entries - The grouping model's flat list.\n * @param groupTotal - Optional caption for a footer (`\"Core total\"`).\n * @param includeHiddenLeaves - When true, a collapsed or paged group\n * contributes every leaf it holds, not only the ones on screen.\n */\nexport function viewFromGroupedEntries(\n entries: readonly GroupedFlatEntry[],\n groupTotal?: (label: string) => string,\n includeHiddenLeaves = false\n): ExportViewEntry[] {\n const out: ExportViewEntry[] = [];\n let dataLevel = 1;\n let skipUntilLevel: number | undefined;\n for (let i = 0; i < entries.length; i++) {\n const entry = entries[i];\n if (!entry || skipHiddenLeaf(entry, skipUntilLevel)) continue;\n if (entry.kind === \"group\" || entry.kind === \"groupFooter\") {\n skipUntilLevel = undefined;\n }\n if (entry.kind === \"group\") {\n dataLevel = entry.level + 1;\n out.push(groupHeaderEntry(entry));\n if (includeHiddenLeaves && !nextIsNestedGroup(entries, i, entry.level)) {\n appendLeaves(out, entry.leafRows, dataLevel);\n skipUntilLevel = entry.level;\n }\n continue;\n }\n if (entry.kind === \"groupFooter\") {\n out.push(groupFooterEntry(entry, groupTotal));\n continue;\n }\n if (entry.kind === \"row\") {\n out.push({ role: \"data\", row: entry.row, level: dataLevel });\n }\n }\n return out;\n}\n\n/**\n * A tree is already a list of data rows with a depth. The outline is that\n * depth; there are no extra header rows to invent.\n *\n * @typeParam TRow - The row type.\n * @param entries - The flattened tree, in render order.\n */\nexport function viewFromTreeEntries(\n entries: readonly TreeEntry[]\n): ExportViewEntry[] {\n return entries.map((entry) => ({\n role: \"data\" as const,\n row: entry.row,\n level: entry.level,\n }));\n}\n\nfunction isStructure(entry: ExportViewEntry): boolean {\n return entry.role === \"group\" || entry.role === \"aggregate\";\n}\n\n/** A group stays if any later leaf before the next peer is kept. */\nfunction markKeptGroups(\n view: readonly ExportViewEntry[],\n keep: boolean[]\n): void {\n for (let i = 0; i < view.length; i++) {\n const entry = view[i];\n if (entry?.role !== \"group\") continue;\n for (let j = i + 1; j < view.length; j++) {\n const next = view[j];\n if (!next || (isStructure(next) && next.level <= entry.level)) break;\n if (keep[j]) {\n keep[i] = true;\n break;\n }\n }\n }\n}\n\n/** Index of the group this footer closes, or -1. */\nfunction footerGroupIndex(\n view: readonly ExportViewEntry[],\n footerAt: number,\n level: number\n): number {\n for (let j = footerAt - 1; j >= 0; j--) {\n const prev = view[j];\n if (!prev) return -1;\n if (prev.role === \"group\" && prev.level === level) return j;\n if (isStructure(prev) && prev.level < level) return -1;\n }\n return -1;\n}\n\n/** A footer stays with the group it closes. */\nfunction markKeptFooters(\n view: readonly ExportViewEntry[],\n keep: boolean[]\n): void {\n for (let i = 0; i < view.length; i++) {\n const entry = view[i];\n if (entry?.role !== \"aggregate\") continue;\n const groupAt = footerGroupIndex(view, i, entry.level);\n if (groupAt >= 0) keep[i] = Boolean(keep[groupAt]);\n }\n}\n\n/**\n * Keep the structure that still has a reason to exist after a scope\n * dropped some leaves: a group header stays if any of its remaining\n * descendants stayed; a footer stays with its header.\n *\n * @typeParam TRow - The row type.\n * @param view - The full grouped or tree view.\n * @param scopedIds - Row ids the scope resolved to.\n * @param getRowId - How a row's id is derived.\n */\nexport function filterExportView(\n view: readonly ExportViewEntry[],\n scopedIds: ReadonlySet,\n getRowId: (row: TRow) => string\n): ExportViewEntry[] {\n const keep = view.map(\n (entry) => entry.role === \"data\" && scopedIds.has(getRowId(entry.row))\n );\n markKeptGroups(view, keep);\n markKeptFooters(view, keep);\n return view.filter((_, index) => keep[index]);\n}\n\n/**\n * Pick the view the current chrome is showing. A tree outranks grouping —\n * the same rule the table uses when both are armed.\n *\n * @typeParam TRow - The row type.\n */\nexport function exportViewFromChrome(options: {\n grouping?: { entries: readonly GroupedFlatEntry[] };\n tree?: {\n entries: readonly TreeEntry[];\n allEntries?: readonly TreeEntry[];\n };\n groupTotal?: (label: string) => string;\n /** Folded or paged-away leaves, for `scope: \"all\"` / `\"selected\"`. */\n includeHiddenLeaves?: boolean;\n}): ExportViewEntry[] | undefined {\n if (options.tree) {\n // A scope that unfolds reads the whole hierarchy; the rendered entries\n // stop at every collapsed node and would drop those subtrees entirely.\n const entries =\n options.includeHiddenLeaves && options.tree.allEntries\n ? options.tree.allEntries\n : options.tree.entries;\n return viewFromTreeEntries(entries);\n }\n if (options.grouping) {\n return viewFromGroupedEntries(\n options.grouping.entries,\n options.groupTotal,\n options.includeHiddenLeaves\n );\n }\n return undefined;\n}\n\n/** `summaryRow` as file values — JSX cells drop out. */\nexport function summaryExportValues(\n cells: Readonly>> | undefined\n): Partial> | undefined {\n return exportableRecord(cells);\n}\n","import type { ReactNode } from \"react\";\n\nimport {\n ACTIONS_COLUMN_KEY,\n REORDER_COLUMN_KEY,\n} from \"../columns/columnMenuModel\";\nimport { type CellRange, cellRangeIndices } from \"../focus/cellRange\";\nimport type { GroupedFlatEntry } from \"../grouping/groupRows\";\nimport type { GetCellSpan } from \"../rows/cellSpan\";\nimport type { TableSource } from \"../source/TableSource\";\nimport type { TreeEntry } from \"../tree/treeRows\";\nimport type { ColumnDef, ExtraFilters, SortDirection } from \"../types\";\nimport { devWarn } from \"../utils/devWarn\";\nimport {\n exportViewFromChrome,\n filterExportView,\n summaryExportValues,\n} from \"./exportView\";\nimport {\n buildExportTable,\n csvWriter,\n defaultExportFilename,\n downloadExportFile,\n type ExportPayload,\n type ExportWriter,\n} from \"./exportWriter\";\n\n/** Which rows an export covers. */\nexport type ExportRowScope = \"page\" | \"all\" | \"selected\" | \"range\";\n\n/**\n * Which columns an export covers: what the user can see, every defined\n * column, or an explicit list of keys in file order.\n */\nexport type ExportColumnScope = \"visible\" | \"all\" | readonly string[];\n\n/** Opt-in CSV export config for the shared DataTable surface. */\nexport interface ExportCsvOptions {\n /** Download filename. Defaults to `\"export.csv\"`. */\n filename?: string;\n /**\n * Which rows the file contains.\n *\n * `\"page\"` (default) — current page / loaded slice.\n * `\"all\"` — full filtered+sorted set when the source exposes\n * {@link TableSource.allFilteredRows}; otherwise falls back to the\n * page with a dev-only warning.\n * `\"selected\"` — the checked rows, in table order. Selection is a set of\n * ids, so this searches the widest set the source can offer: a row selected\n * on page 1 is still exported while page 3 is on screen.\n * `\"range\"` — the highlighted cell rectangle, which needs `cellNavigation`;\n * a rectangle names its own columns, so it decides them and `columns` is not\n * consulted. Without a selection this falls back to the page with a dev-only\n * warning.\n */\n scope?: ExportRowScope;\n /**\n * Which columns the file contains.\n *\n * `\"visible\"` (default) — what the user can see, so the file matches the\n * screen. `\"all\"` — every defined column including those hidden through the\n * column menu, for a complete extract. An explicit array picks columns by\n * key, in the order given, and silently ignores a key that matches no\n * column so a stale saved config cannot break the button.\n *\n * The synthetic actions column is never exported under any of them.\n */\n columns?: ExportColumnScope;\n /**\n * Neutralise spreadsheet formula injection (see\n * {@link RowsToCsvOptions.escapeFormulas}). Disable ONLY for\n * machine-consumed output that is never opened in a spreadsheet.\n * @defaultValue true\n */\n escapeFormulas?: boolean;\n /**\n * Runs after the rows and columns are chosen and before the file is\n * written, which is the only moment where both are known and nothing has\n * happened yet.\n *\n * Return `false` to cancel the export — enough is known here to decide\n * (too many rows, nothing selected, a permission the host enforces).\n * Return `{ filename }` to name the file from the data, which is what most\n * callers want it for. Return nothing to continue unchanged.\n */\n onBeforeExport?: (\n info: ExportInfo\n ) => boolean | void | { filename?: string };\n /**\n * Runs once the file has been handed to the browser, with what was written.\n * For analytics, a toast, or keeping a copy.\n *\n * `csv` is the file's text; a binary format leaves it empty and carries its\n * bytes in `file.parts`.\n */\n onAfterExport?: (\n info: ExportInfo & { csv: string; file: ExportPayload }\n ) => void;\n /**\n * The file format. Defaults to CSV; `@adapttable/core/xlsx` exports\n * {@link ExportWriter | a spreadsheet writer}, and any function of the\n * resolved rows and columns is a valid one.\n *\n * The scope options above are unaffected by this — which rows and columns\n * leave the table is decided before a writer sees them.\n */\n writer?: ExportWriter;\n /**\n * Hand the export to your backend instead of building the file in the\n * browser.\n *\n * Past a certain size the browser is the wrong place to do this: the rows\n * are not all loaded, holding them would cost more memory than the tab has,\n * and the work blocks the main thread. With this set, the button sends the\n * user's current view — filters, search, sort, the chosen scope — to your\n * handler, and building the file (or queueing a job and emailing a link)\n * happens where the data already lives.\n *\n * The table builds no file and downloads nothing when this is present.\n * Return a promise and the button stays busy until it settles, so a second\n * click cannot start the same export twice.\n */\n request?: (info: ExportRequest) => void | Promise;\n /**\n * Let `scope: \"all\"` page a server source itself.\n *\n * A server-backed table holds one page, so \"all\" has nothing to read. The\n * first answer is {@link ExportCsvOptions.request} — the backend already has\n * the data. This is the second: opt in and the table walks the query page by\n * page and builds the file in the browser.\n *\n * It is opt-in because it is a loop of network requests the reader did not\n * ask for, and capped because an unbounded one over a large table is a way\n * to hang a tab. Past {@link FetchAllExport.maxRows} the export stops and\n * says so through {@link FetchAllExport.onCapped} rather than quietly\n * writing a partial file.\n */\n fetchAll?: FetchAllExport;\n}\n\n/** How `scope: \"all\"` pages a server source when the host opts in. */\nexport interface FetchAllExport {\n /**\n * Fetch one page of the current query. Called with 1-based page numbers\n * until it returns fewer rows than `limit`, or the cap is reached.\n */\n fetchPage: (query: ExportQuery) => Promise;\n /** Rows per request. Defaults to the table's current page size. */\n pageSize?: number;\n /**\n * Stop after this many rows. Defaults to 50,000 — high enough that ordinary\n * tables never meet it, low enough that a runaway query cannot exhaust the\n * tab.\n */\n maxRows?: number;\n /**\n * Called when the cap stopped the export short, with what was written and\n * the cap that stopped it. Tell the reader; a silently truncated file is the\n * outcome this whole option exists to avoid.\n */\n onCapped?: (info: { rows: number; maxRows: number }) => void;\n}\n\n/** The default {@link FetchAllExport.maxRows}. */\nexport const EXPORT_FETCH_ALL_MAX_ROWS = 50_000;\n\n/**\n * Walk a server source page by page for `scope: \"all\"`.\n *\n * @typeParam TRow - The row type.\n * @param source - The table's source, for the current query and page size.\n * @param config - See {@link FetchAllExport}.\n * @returns Every row the query matches, up to the cap.\n */\nexport async function fetchAllExportRows(\n source: TableSource,\n config: FetchAllExport\n): Promise {\n const limit = config.pageSize ?? source.limit ?? 100;\n const maxRows = config.maxRows ?? EXPORT_FETCH_ALL_MAX_ROWS;\n const base = exportQueryOf(source, \"page\");\n const out: TRow[] = [];\n let reachedEnd = false;\n let page = 1;\n while (out.length < maxRows && !reachedEnd) {\n const batch = await config.fetchPage({ ...base, page, limit });\n out.push(...batch);\n // A short page is the end of the set; an empty one guards a source that\n // answers the page after the last with an empty array rather than fewer.\n reachedEnd = batch.length < limit;\n page += 1;\n }\n // Stopping ON the cap is still stopping short — a full last page says\n // nothing about whether more exist, so only a short page proves the end.\n if (!reachedEnd) {\n const rows = Math.min(out.length, maxRows);\n config.onCapped?.({ rows, maxRows });\n return out.slice(0, rows);\n }\n return out;\n}\n\n/** The view an export was asked for, as a server needs to hear it. */\nexport interface ExportRequest extends ExportInfo {\n /**\n * The query behind the current view: search, filters, sort and paging,\n * exactly as {@link TableQuery} carries them to a server tier.\n */\n query: ExportQuery;\n /** Which rows were asked for. `rows` holds what the browser has of them. */\n scope: ExportRowScope;\n /**\n * The file extension the button would have produced — `\"csv\"`, `\"xlsx\"`, or\n * whatever a custom writer names itself. A backend building the file needs to\n * know which one, and the filename alone is a guess.\n */\n format: string;\n}\n\n/** The view-defining half of a table query, for an export request. */\nexport interface ExportQuery {\n /**\n * Undefined for `scope: \"all\"`: \"all\" means every row the filters match, so\n * a page number would contradict the ask. Present for every other scope.\n */\n page: number | undefined;\n /** Undefined for `scope: \"all\"` — see {@link ExportQuery.page}. */\n limit: number | undefined;\n search: string;\n sortBy: string | undefined;\n sortDir: SortDirection | undefined;\n filters: ExtraFilters;\n groupBy: string | undefined;\n}\n\n/** What an export lifecycle hook is told about the file being written. */\nexport interface ExportInfo {\n /** The rows the chosen scope resolved to, in table order. */\n rows: readonly TRow[];\n /** The columns the chosen scope resolved to, in file order. */\n columns: readonly ColumnDef[];\n /** The filename as it stands, before any override this hook returns. */\n filename: string;\n}\n\n/** Boolean-or-options CSV export prop (off / on / configured). */\ntype ExportCsvProp =\n | boolean\n | ExportCsvOptions\n | undefined;\n\n/** Resolve a boolean-or-options prop into a concrete config, or `null` when off. */\nexport function resolveExportCsv(\n value: ExportCsvProp\n): ExportCsvOptions | null {\n if (!value) return null;\n if (value === true) return {};\n return value;\n}\n\n/**\n * Whether `scope: \"all\"` will write the current page instead of the\n * full filtered set.\n *\n * A frontend source that exposes `allFilteredRows`, or a host that\n * passed `request` / `fetchAll`, can answer honestly. Everything else\n * is this page — the button should say so.\n */\nexport function exportAllFallsBackToPage(\n exportCsv: ExportCsvProp,\n source: Pick, \"allFilteredRows\">\n): boolean {\n const options = resolveExportCsv(exportCsv);\n return Boolean(\n options?.scope === \"all\" &&\n source.allFilteredRows === undefined &&\n options.request === undefined &&\n options.fetchAll === undefined\n );\n}\n\n/** Columns that belong in a CSV (drop synthetic actions and reorder columns). */\nexport function exportableColumns(\n columns: readonly ColumnDef[]\n): ColumnDef[] {\n return columns.filter(\n (column) =>\n column.key !== ACTIONS_COLUMN_KEY && column.key !== REORDER_COLUMN_KEY\n );\n}\n\n/**\n * Everything an export needs beyond the visible columns: the selection to\n * honour a `\"selected\"` scope, and the full column set to honour `\"all\"`.\n *\n * Every field is optional. A caller that passes none gets exactly the\n * behaviour this function always had.\n */\nexport interface ExportContext {\n /** The checked row ids. */\n selectedIds?: ReadonlySet;\n /** How a row's id is derived — the table's own `getRowId`. */\n getRowId?: (row: TRow) => string;\n /** Every defined column, including any hidden through the column menu. */\n allColumns?: readonly ColumnDef[];\n /** The highlighted cell rectangle, for `scope: \"range\"`. */\n range?: CellRange | null;\n /**\n * Where the rendered window starts in the dataset — the offset that turns a\n * range's absolute row addresses back into rows the browser holds. Zero\n * unless the table is paged.\n */\n firstRowIndex?: number;\n /** Omit covered cells from the file — a span exports its value once. */\n getCellSpan?: GetCellSpan;\n /**\n * The grouping model's entries, when grouping is armed. A spreadsheet\n * writes headers, outline levels and footers from them. A range export\n * ignores this — a rectangle is already its own shape.\n */\n grouping?: { entries: readonly GroupedFlatEntry[] };\n /**\n * The flattened tree, when a tree is armed. Outranks grouping, the same\n * way the table does.\n */\n tree?: {\n entries: readonly TreeEntry[];\n /**\n * The same hierarchy with every node open. A folded folder is display\n * state, so `scope: \"all\"` writes what is inside it — without this, a\n * collapsed subtree is silently missing from the file.\n */\n allEntries?: readonly TreeEntry[];\n };\n /** Caption for a group footer — the table's `labels.groupTotal`. */\n groupTotal?: (label: string) => string;\n /**\n * The table's `summaryRow` mapper. Called on the scoped rows so a grand\n * total in the file matches the rows that actually left.\n */\n summaryRow?: (rows: readonly TRow[]) => Partial>;\n}\n\n/** Pick the column set an export scope asks for, minus the actions column. */\nexport function resolveExportColumns(\n scope: ExportColumnScope | undefined,\n visible: readonly ColumnDef[],\n all: readonly ColumnDef[] | undefined\n): ColumnDef[] {\n const keys: readonly string[] | undefined =\n typeof scope === \"string\" || scope === undefined ? undefined : scope;\n const pool = exportableColumns(\n scope === \"all\" || keys ? (all ?? visible) : visible\n );\n if (!keys) return pool;\n // Order follows the caller's list, not the table's, because an explicit\n // list is a statement about the file's shape.\n const byKey = new Map(pool.map((column) => [column.key, column]));\n return keys.flatMap((key) => {\n const column = byKey.get(key);\n return column ? [column] : [];\n });\n}\n\n/**\n * The rows a highlighted rectangle covers.\n *\n * A range addresses rows by their place in the dataset, because that is what a\n * screen reader is told and what survives scrolling. Turning one back into rows\n * is therefore an offset subtraction — and every row in a range is loaded, since\n * navigation cannot leave the loaded window. A programmatic selection that\n * reaches past it drops those rows rather than exporting blanks.\n */\nfunction rowsInRange(\n range: CellRange,\n source: TableSource,\n firstRowIndex: number\n): readonly TRow[] {\n return cellRangeIndices(range).rows.flatMap((index) => {\n const row = source.rows[index - firstRowIndex];\n return row === undefined ? [] : [row];\n });\n}\n\n/** The rows a scope asks for, in table order. */\nfunction resolveExportRows(\n scope: ExportRowScope,\n source: TableSource,\n context: ExportContext | undefined\n): readonly TRow[] {\n if (scope === \"page\") return source.rows;\n if (scope === \"range\") {\n const { range, firstRowIndex } = context ?? {};\n if (!range) {\n devWarn(\n 'exportCsv scope \"range\" needs a selected cell range, which needs `cellNavigation`. Nothing is selected, so the current page is exported instead.'\n );\n return source.rows;\n }\n return rowsInRange(range, source, firstRowIndex ?? 0);\n }\n if (scope === \"all\") {\n if (!source.allFilteredRows) {\n // Reached only by a hand-built call: the toolbar handler refuses to\n // render an \"all\" button a server source cannot answer.\n devWarn(\n 'exportCsv scope \"all\" needs the full filtered set. This source exposes only the current page, so that is what is exported. Pass `request` or `fetchAll` to export everything from a server tier.'\n );\n }\n return source.allFilteredRows ?? source.rows;\n }\n const { selectedIds, getRowId } = context ?? {};\n if (!selectedIds || !getRowId) {\n devWarn(\n 'exportCsv scope \"selected\" needs the table\\'s selection. Adapters pass it automatically; a hand-built call must supply `selectedIds` and `getRowId`. Exporting the current page instead.'\n );\n return source.rows;\n }\n // Search the widest set available, so a row checked on an earlier page is\n // still in the file when a later page is on screen.\n const searchable = source.allFilteredRows ?? source.rows;\n return searchable.filter((row) => selectedIds.has(getRowId(row)));\n}\n\n/**\n * What an export resolves to: the rows a scope asks for and the columns a\n * scope asks for.\n *\n * Three call sites need exactly this pair — the pure builder, the download\n * path (which brackets it with hooks) and the backend-request path (which\n * sends it instead of writing a file). Resolving it once is what keeps them\n * from drifting apart.\n */\nfunction resolveExport(options: {\n source: TableSource;\n columns: readonly ColumnDef[];\n scope?: ExportRowScope;\n columnScope?: ExportColumnScope;\n context?: ExportContext;\n}): { rows: readonly TRow[]; columns: ColumnDef[] } {\n const scope = options.scope ?? \"page\";\n const range = options.context?.range;\n return {\n rows: resolveExportRows(scope, options.source, options.context),\n // A rectangle names its own columns. Asking for one and then exporting\n // every visible column would ignore half of what the user selected, so the\n // range decides here and `columns` is not consulted.\n columns:\n scope === \"range\" && range\n ? columnsInRange(range, options.columns)\n : resolveExportColumns(\n options.columnScope ?? \"visible\",\n options.columns,\n options.context?.allColumns\n ),\n };\n}\n\n/**\n * The columns a rectangle covers, in table order. Column addresses index the\n * columns as rendered, which is the same list the export is given.\n */\nfunction columnsInRange(\n range: CellRange,\n columns: readonly ColumnDef[]\n): ColumnDef[] {\n return exportableColumns(\n cellRangeIndices(range).cols.flatMap((index) => {\n const column = columns[index];\n return column ? [column] : [];\n })\n );\n}\n\n/** Structure and spans for the resolved rows, when the context has them. */\nfunction exportTableOptions(\n rows: readonly TRow[],\n scope: ExportRowScope | undefined,\n context: ExportContext | undefined\n) {\n const getRowId = context?.getRowId;\n // Page writes the chrome view as it stands — collapsed headers stay,\n // folded leaves stay out. All / selected unfold those leaves first so a\n // ticked row inside a closed group still leaves the table, then prune.\n const includeHiddenLeaves = scope === \"all\" || scope === \"selected\";\n const fullView = exportViewFromChrome({\n grouping: context?.grouping,\n tree: context?.tree,\n groupTotal: context?.groupTotal,\n includeHiddenLeaves,\n });\n let view = fullView;\n if (scope === \"range\" || !fullView) view = undefined;\n else if (includeHiddenLeaves && getRowId) {\n view = filterExportView(\n fullView,\n new Set(rows.map((row) => getRowId(row))),\n getRowId\n );\n }\n return {\n getCellSpan: context?.getCellSpan,\n firstRowIndex: context?.firstRowIndex,\n view,\n summary: summaryExportValues(context?.summaryRow?.(rows)),\n };\n}\n\n/**\n * Build CSV text for the chosen row and column scopes.\n *\n * @typeParam TRow - The row type.\n */\nexport function buildTableCsv(options: {\n source: TableSource;\n columns: readonly ColumnDef[];\n scope?: ExportRowScope;\n columnScope?: ExportColumnScope;\n escapeFormulas?: boolean;\n context?: ExportContext;\n}): string {\n const { rows, columns } = resolveExport(options);\n return csvWriter.build({\n table: buildExportTable(\n rows,\n columns,\n exportTableOptions(rows, options.scope, options.context)\n ),\n filename: \"export.csv\",\n escapeFormulas: options.escapeFormulas,\n }).text;\n}\n\n/**\n * Build + download a file for the current table view. CSV unless a `writer`\n * says otherwise.\n *\n * @typeParam TRow - The row type.\n */\nexport function downloadTableCsv(options: {\n source: TableSource;\n columns: readonly ColumnDef[];\n filename?: string;\n scope?: ExportRowScope;\n columnScope?: ExportColumnScope;\n escapeFormulas?: boolean;\n context?: ExportContext;\n writer?: ExportWriter;\n onBeforeExport?: NonNullable[\"onBeforeExport\"]>;\n onAfterExport?: NonNullable[\"onAfterExport\"]>;\n}): void {\n const { rows, columns } = resolveExport(options);\n const writer = options.writer ?? csvWriter;\n\n let filename = options.filename ?? defaultExportFilename(writer);\n const decision = options.onBeforeExport?.({ rows, columns, filename });\n if (decision === false) return;\n if (decision && decision !== true && decision.filename) {\n filename = decision.filename;\n }\n\n // Built after the hook, so a filename the hook chose reaches a writer that\n // embeds it — and so a cancelled export builds nothing at all.\n const file = writer.build({\n table: buildExportTable(\n rows,\n columns,\n exportTableOptions(rows, options.scope, options.context)\n ),\n filename,\n escapeFormulas: options.escapeFormulas,\n });\n downloadExportFile(filename, file);\n options.onAfterExport?.({ rows, columns, filename, csv: file.text, file });\n}\n\n/**\n * Resolve the `exportCsv` prop into a click handler, or `undefined` when off.\n * Adapters bind this to the toolbar Export button.\n *\n * @typeParam TRow - The row type.\n */\nexport function makeExportCsvHandler(\n exportCsv: boolean | ExportCsvOptions | undefined,\n source: TableSource,\n columns: readonly ColumnDef[],\n context?: ExportContext\n): (() => void | Promise) | undefined {\n const options = resolveExportCsv(exportCsv);\n if (!options) return undefined;\n\n // Handing the export to a backend replaces building it here entirely —\n // the browser neither assembles a file nor downloads one.\n const writer = options.writer ?? csvWriter;\n const { request } = options;\n if (request) {\n return () =>\n request({\n ...resolveExport({\n source,\n columns,\n scope: options.scope,\n columnScope: options.columns,\n context,\n }),\n filename: options.filename ?? defaultExportFilename(writer),\n scope: options.scope ?? \"page\",\n format: writer.extension,\n query: exportQueryOf(source, options.scope ?? \"page\"),\n });\n }\n\n // \"All\" over a server source: the browser holds one page, so it has to be\n // answered by fetching, not by pretending. `fetchAll` is the opt-in.\n const serverAll =\n options.scope === \"all\" && !source.allFilteredRows && options.fetchAll;\n if (serverAll) {\n return async () => {\n const rows = await fetchAllExportRows(source, serverAll);\n downloadTableCsv({\n source: { ...source, allFilteredRows: rows },\n columns,\n filename: options.filename,\n scope: \"all\",\n columnScope: options.columns,\n escapeFormulas: options.escapeFormulas,\n context,\n writer,\n onBeforeExport: options.onBeforeExport,\n onAfterExport: options.onAfterExport,\n });\n };\n }\n\n // Neither a backend handler nor an opt-in fetch, and no rows to read:\n // write this page and name the button that way.\n if (options.scope === \"all\" && !source.allFilteredRows) {\n devWarn(\n 'exportCsv scope \"all\" needs the full filtered set. This source ' +\n \"exposes only the current page, so the Export button writes this \" +\n \"page and names itself that way. Pass `request` or `fetchAll` to \" +\n \"export everything from a server tier.\"\n );\n return () =>\n downloadTableCsv({\n source,\n columns,\n filename: options.filename,\n scope: \"page\",\n columnScope: options.columns,\n escapeFormulas: options.escapeFormulas,\n context,\n writer,\n onBeforeExport: options.onBeforeExport,\n onAfterExport: options.onAfterExport,\n });\n }\n\n return () =>\n downloadTableCsv({\n source,\n columns,\n filename: options.filename,\n scope: options.scope,\n columnScope: options.columns,\n escapeFormulas: options.escapeFormulas,\n context,\n writer,\n onBeforeExport: options.onBeforeExport,\n onAfterExport: options.onAfterExport,\n });\n}\n\n/** The view-defining half of the source's state, for a server export. */\nfunction exportQueryOf(\n source: TableSource,\n scope: ExportRowScope\n): ExportQuery {\n // \"All\" is the whole filtered set, so the window the reader happens to be\n // looking at is not part of the question. Sending it invites a backend to\n // answer with one page and call it everything.\n const paged = scope !== \"all\";\n return {\n page: paged ? source.page : undefined,\n limit: paged ? source.limit : undefined,\n search: source.search,\n sortBy: source.sortBy,\n sortDir: source.sortDir,\n filters: source.extra,\n groupBy: source.groupBy,\n };\n}\n","/**\n * Kit-agnostic notices for opted-in features that cannot run.\n *\n * The host turned something on; the table cannot honour it. Dev consoles\n * already warn. The person at the table should see the same fact — off,\n * disabled, or one page — through existing chrome (status bar, export\n * label, missing pin/reorder, unvirtualized page). Nothing here flips an\n * opt-in or draws a new control.\n */\nimport {\n exportAllFallsBackToPage,\n type ExportCsvOptions,\n} from \"../export/tableCsv\";\nimport type { TableSource } from \"../source/TableSource\";\nimport type { TableLabels } from \"../types\";\n\n/** Which opted-in feature is inert. */\nexport type FeatureNoticeKind =\n | \"virtualize-paged\"\n | \"pin-nested\"\n | \"reorder-nested\"\n | \"grouping-unavailable\"\n | \"export-all-page\"\n | \"edit-without-writer\";\n\n/** How the table already looks to the person sitting at it. */\nexport type FeatureNoticeAppearance = \"off\" | \"disabled\" | \"one-page\";\n\n/** One inert feature, ready for a status slot or a root attribute. */\nexport interface FeatureNotice {\n readonly kind: FeatureNoticeKind;\n readonly appearance: FeatureNoticeAppearance;\n readonly message: string;\n}\n\n/** Inputs {@link collectFeatureNotices} needs. Host props + source facts. */\nexport interface CollectFeatureNoticesInput {\n virtualize?: boolean;\n paginationMode?: TableSource[\"paginationMode\"];\n groupByKeys: readonly string[];\n allFilteredRows?: readonly TRow[];\n serverGroups?: unknown;\n rowPinningRequested: boolean;\n rowReorderRequested: boolean;\n /** Grouping is armed or a tree is on — pin and reorder stay off. */\n nestedArmed: boolean;\n hasEditableColumn: boolean;\n onCellEdit?: unknown;\n rowEditing?: boolean;\n onRowEdit?: unknown;\n batchEditing?: boolean;\n onBatchEdit?: unknown;\n exportCsv?: boolean | ExportCsvOptions;\n labels: TableLabels;\n}\n\n/**\n * Build the notices for features the host asked for that cannot run.\n *\n * @param input - Host flags, source facts, and resolved labels.\n * @returns Notices in a stable order; empty when everything can run.\n */\nexport function collectFeatureNotices(\n input: CollectFeatureNoticesInput\n): readonly FeatureNotice[] {\n const labels = input.labels;\n const notices: FeatureNotice[] = [];\n\n if (input.virtualize === true && input.paginationMode === \"paged\") {\n notices.push({\n kind: \"virtualize-paged\",\n appearance: \"one-page\",\n message:\n labels.noticeVirtualizePaged ??\n \"Virtualization is off — this paged table shows one page at a time.\",\n });\n }\n\n if (\n input.groupByKeys.length > 0 &&\n input.allFilteredRows === undefined &&\n input.serverGroups === undefined\n ) {\n notices.push({\n kind: \"grouping-unavailable\",\n appearance: \"off\",\n message:\n labels.noticeGroupingUnavailable ??\n \"Grouping is off — this source does not provide the full filtered set.\",\n });\n }\n\n if (input.rowPinningRequested && input.nestedArmed) {\n notices.push({\n kind: \"pin-nested\",\n appearance: \"off\",\n message:\n labels.noticePinNested ??\n \"Row pinning is off while grouping or a tree is on.\",\n });\n }\n\n if (input.rowReorderRequested && input.nestedArmed) {\n notices.push({\n kind: \"reorder-nested\",\n appearance: \"off\",\n message:\n labels.noticeReorderNested ??\n \"Row reorder is off while grouping or a tree is on.\",\n });\n }\n\n if (\n exportAllFallsBackToPage(input.exportCsv, {\n allFilteredRows: input.allFilteredRows,\n })\n ) {\n notices.push({\n kind: \"export-all-page\",\n appearance: \"one-page\",\n message:\n labels.noticeExportAllPage ??\n \"Export all is this page — the full filtered set is not available.\",\n });\n }\n\n const editMissingWriter =\n (input.hasEditableColumn && input.onCellEdit === undefined) ||\n (input.rowEditing === true && input.onRowEdit === undefined) ||\n (input.batchEditing === true && input.onBatchEdit === undefined);\n if (editMissingWriter) {\n notices.push({\n kind: \"edit-without-writer\",\n appearance: \"off\",\n message:\n labels.noticeEditWithoutWriter ??\n \"Editing is off — no write handler is wired.\",\n });\n }\n\n return notices;\n}\n","/**\n * A nested table under a row — a real table, not a rendered slot.\n *\n * `renderRowDetail` hands the host a blank panel: whatever goes in it is theirs\n * to build, and a table built by hand in there has none of the sorting,\n * filtering, selection, keyboard navigation or accessibility the outer one has.\n * A nested table is the same component the page uses, so the reader gets the\n * same table twice over rather than a lesser one inside a better one.\n *\n * The host mounts the kit's own `` — core has no components, and the\n * child rows are a different type from the parent's, which no prop on a\n * single-generic component can carry without erasing it. What core owns is the\n * part every nested table gets wrong on its own: the defaults it must have, the\n * region that names it for assistive technology, and the fall back to a\n * hand-built panel for rows that have no nested table.\n */\nimport type { ReactElement, ReactNode } from \"react\";\n\nimport type { TableLabels } from \"../types\";\n\n/** Row density, as the table's own prop spells it. */\ntype Density = \"comfortable\" | \"compact\";\n\n/**\n * The props a nested table must be mounted with, handed to the host's `table`\n * callback to spread onto the kit's own component.\n */\nexport interface NestedTableDefaults {\n /**\n * Never true. Two tables writing `?page=` fight over one URL, and the loser\n * silently resets while the reader is using it.\n */\n urlSync: false;\n /**\n * Off by default: a second search box inside a row reads as chrome rather\n * than as a feature. Spread these first and pass `searchable` after to keep\n * it.\n */\n searchable: boolean;\n /** The parent's density, so the child matches rather than guessing. */\n density: Density | undefined;\n /** The parent's labels, so a nested table is localized like its parent. */\n labels: TableLabels | undefined;\n /** The accessible name, also used on the region around it. */\n tableLabel: string;\n}\n\n/** A row's nested table. */\nexport interface NestedTable {\n /**\n * Accessible name for the nested table and its region — the only thing a\n * screen-reader user has to go on once focus is inside it. Name it after the\n * row it belongs to (\"Orders for Ada Lovelace\"), not after the feature.\n */\n label?: string;\n /**\n * Mount the kit's own table with these defaults:\n * `(defaults) => `.\n * The child rows keep their own type — the closure holds it, so nothing is\n * erased at a prop boundary.\n */\n table: (defaults: NestedTableDefaults) => ReactNode;\n}\n\n/** A host's declaration: the nested table for a row, or nothing. */\nexport type NestedTableFor = (row: TRow) => NestedTable | undefined;\n\n/** What the parent contributes to its nested tables. */\nexport interface NestedTableParent {\n /** The parent's density. */\n density?: Density;\n /** The parent's labels. */\n labels?: TableLabels;\n}\n\n/** The name a nested table takes when the host does not give it one. */\nconst DEFAULT_LABEL = \"Row details\";\n\n/**\n * The defaults a table inside a row is mounted with.\n *\n * @param label - The nested table's accessible name.\n * @param parent - What the parent table contributes.\n * @returns Props to spread onto the kit's own table.\n */\nexport function nestedTableDefaults(\n label: string,\n parent: NestedTableParent = {}\n): NestedTableDefaults {\n return {\n urlSync: false,\n searchable: false,\n density: parent.density,\n labels: parent.labels,\n tableLabel: label,\n };\n}\n\n/**\n * Turn a nested-table declaration into the detail renderer the table already\n * knows how to place under a row.\n *\n * @typeParam TRow - The parent row type.\n * @param options - The declaration, the host's own panel, and the parent chrome.\n * @returns A `renderRowDetail`, or `undefined` when neither is declared.\n */\nexport function nestedTableDetail(options: {\n nestedTable: NestedTableFor | undefined;\n /** The host's own detail panel, used for rows with no nested table. */\n renderRowDetail?: (row: TRow) => ReactNode;\n parent?: NestedTableParent;\n}): ((row: TRow) => ReactNode) | undefined {\n const { nestedTable, renderRowDetail, parent } = options;\n if (!nestedTable) return renderRowDetail;\n // One shape out of here, always an element or null: a union of \"the host's\n // node\" and \"our element\" reads as two functions wearing one name.\n function renderNestedDetail(row: TRow): ReactElement | null {\n const nested = nestedTable?.(row);\n if (nested) return ;\n const own = renderRowDetail?.(row);\n return own === undefined || own === null ? null : <>{own};\n }\n return renderNestedDetail;\n}\n\n/** The region around a nested table, named for assistive technology. */\nfunction NestedTableRegion({\n nested,\n parent,\n}: Readonly<{\n nested: NestedTable;\n parent?: NestedTableParent;\n}>): ReactElement {\n const label = nested.label ?? DEFAULT_LABEL;\n return (\n
\n {nested.table(nestedTableDefaults(label, parent))}\n
\n );\n}\n","/**\n * Hierarchical rows — a tree the DATA declares, not one derived from values.\n *\n * This is deliberately not the grouping model. A group is an answer to a\n * question the reader asked (\"by team\"), computed from values and re-computed\n * when they change the question. A tree is a fact about the rows: a folder\n * contains files, a task has subtasks, an account rolls up to a parent. Sharing\n * one implementation would mean either grouping that cannot express a real\n * hierarchy, or a tree that reshuffles when someone sorts a column.\n *\n * A host declares the shape either way round — `getChildren(row)` for nested\n * data, or `getParentId(row)` for a flat table with a parent column — and the\n * model flattens it to the same list of entries adapters render.\n */\nimport type { ColumnDef } from \"../types\";\n\n/** One visual row of a tree: the row itself, plus where it sits. */\nexport interface TreeEntry {\n /** The row. */\n row: TRow;\n /** Its stable id. */\n key: string;\n /** Depth from zero — what the tree column indents by. */\n level: number;\n /** Whether it has children at all, loaded or not. */\n hasChildren: boolean;\n /** Whether its children are showing. */\n expanded: boolean;\n /** Its ancestors' ids, outermost first — what collapsing a parent hides. */\n path: readonly string[];\n /**\n * Every descendant's id, for selection: ticking a folder ticks what is in\n * it, and a parent shows as partly selected when only some are.\n */\n descendantIds: readonly string[];\n /** Whether children are being fetched for this node right now. */\n loading?: boolean;\n}\n\n/** How a host declares the hierarchy. */\nexport interface TreeShape {\n /** Nested data: the children of a row, if any. */\n getChildren?: (row: TRow) => readonly TRow[] | undefined;\n /** Flat data: the id of a row's parent, if any. */\n getParentId?: (row: TRow) => string | undefined;\n /**\n * Whether a row has children the browser has not fetched yet. Without it a\n * node with no loaded children is a leaf, which is the right default for\n * data that is all in hand.\n */\n hasChildren?: (row: TRow) => boolean;\n}\n\n/** What {@link buildTreeEntries} needs. */\nexport interface BuildTreeEntriesOptions extends TreeShape {\n /** The rows, nested or flat. */\n rows: readonly TRow[];\n /** Row identity. */\n getRowId: (row: TRow) => string;\n /** Which nodes are expanded, by id. */\n expandedIds: ReadonlySet;\n /** Nodes whose children are being fetched. */\n loadingIds?: ReadonlySet;\n}\n\n/**\n * Flatten a hierarchy into the rows a table renders, in reading order.\n *\n * A collapsed node contributes itself and nothing beneath it. `descendantIds`\n * covers the whole subtree whether or not it is showing, because selecting a\n * folder means selecting what is in it — including the part currently folded\n * away.\n *\n * @typeParam TRow - The row type.\n * @param options - See {@link BuildTreeEntriesOptions}.\n * @returns The entries, in render order.\n */\nexport function buildTreeEntries(\n options: BuildTreeEntriesOptions\n): TreeEntry[] {\n const {\n rows,\n getRowId,\n expandedIds,\n loadingIds,\n getChildren,\n getParentId,\n hasChildren,\n } = options;\n const childrenOf =\n getChildren ?? childrenFromParentIds(rows, getParentId, getRowId);\n const roots = getParentId\n ? rows.filter((row) => {\n const parent = getParentId(row);\n return (\n parent === undefined || !rows.some((r) => getRowId(r) === parent)\n );\n })\n : rows;\n\n const entries: TreeEntry[] = [];\n\n /** Collect a subtree's ids, folded or not — selection covers all of it. */\n const descendantsOf = (row: TRow): string[] => {\n const ids: string[] = [];\n for (const child of childrenOf(row) ?? []) {\n ids.push(getRowId(child), ...descendantsOf(child));\n }\n return ids;\n };\n\n const walk = (list: readonly TRow[], level: number, path: string[]): void => {\n for (const row of list) {\n const key = getRowId(row);\n const children = childrenOf(row) ?? [];\n const expandable = children.length > 0 || hasChildren?.(row) === true;\n const expanded = expandable && expandedIds.has(key);\n entries.push({\n row,\n key,\n level,\n hasChildren: expandable,\n expanded,\n path,\n descendantIds: descendantsOf(row),\n loading: loadingIds?.has(key),\n });\n if (expanded && children.length > 0) {\n walk(children, level + 1, [...path, key]);\n }\n }\n };\n\n walk(roots, 0, []);\n return entries;\n}\n\n/**\n * Read children from a flat list keyed by parent id.\n *\n * Built once per call rather than scanned per row: a thousand rows scanned for\n * each of a thousand rows is a million comparisons for a table nobody would\n * call large.\n */\nfunction childrenFromParentIds(\n rows: readonly TRow[],\n getParentId: ((row: TRow) => string | undefined) | undefined,\n getRowId: (row: TRow) => string\n): (row: TRow) => readonly TRow[] {\n if (!getParentId) return () => [];\n const byParent = new Map();\n for (const row of rows) {\n const parent = getParentId(row);\n if (parent === undefined) continue;\n const siblings = byParent.get(parent) ?? [];\n siblings.push(row);\n byParent.set(parent, siblings);\n }\n return (row) => byParent.get(getRowId(row)) ?? [];\n}\n\n/**\n * Keep the rows that match, and every ancestor that leads to one.\n *\n * A filtered tree that dropped the folders would leave matching files with no\n * path to them — the reader would see a flat list and lose the one thing the\n * tree was for. Ancestors are kept even when they do not match themselves.\n *\n * @typeParam TRow - The row type.\n * @param options - The shape, the rows, and the predicate.\n * @returns The rows that survive, nested exactly as they arrived.\n */\nexport function filterTreeRows(options: {\n rows: readonly TRow[];\n getChildren: (row: TRow) => readonly TRow[] | undefined;\n /** Rebuild a row with the children that survived — the host owns its shape. */\n withChildren: (row: TRow, children: readonly TRow[]) => TRow;\n match: (row: TRow) => boolean;\n}): TRow[] {\n const { rows, getChildren, withChildren, match } = options;\n return rows.flatMap((row) => {\n const kept = filterTreeRows({\n rows: getChildren(row) ?? [],\n getChildren,\n withChildren,\n match,\n });\n if (kept.length === 0 && !match(row)) return [];\n return [withChildren(row, kept)];\n });\n}\n\n/**\n * The style a tree column's cell carries at a given depth.\n *\n * Logical padding, so a tree indents from the right in Arabic and Hebrew\n * without a second rule — the same one grouping uses, at the same step, so a\n * table that has both does not step differently between them.\n *\n * @param level - Depth from zero.\n * @returns The style for the tree column's cell.\n */\nexport function treeIndentStyle(level: number): {\n paddingInlineStart?: string;\n} {\n return level > 0 ? { paddingInlineStart: `${level * 1.5}rem` } : {};\n}\n\n/**\n * The style a card carries at a given depth.\n *\n * A card is a block, not a cell, so the whole card steps in rather than its\n * text — on a narrow screen an indented card edge reads as hierarchy where an\n * indented line reads as a typo. Logical margin, so it steps from the right\n * in Arabic and Hebrew.\n *\n * @param level - Depth from zero.\n * @returns The style for the card.\n */\nexport function treeCardStyle(level: number): {\n marginInlineStart?: string;\n} {\n return level > 0 ? { marginInlineStart: `${level * 1.25}rem` } : {};\n}\n\n/** Which column renders the chevron and the indent. */\nexport function treeColumnKey(\n columns: readonly ColumnDef[],\n declared?: string\n): string | undefined {\n if (declared !== undefined) return declared;\n return columns[0]?.key;\n}\n\n/** One body row an adapter renders, tree or flat. */\nexport interface BodyRowEntry {\n /** The row. */\n row: TRow;\n /** Its position for `data-index` and cell navigation. */\n index: number;\n /**\n * Index in the page dataset when pinned rows left the window.\n * Equals `index` when pinning is off.\n */\n sourceIndex?: number;\n /** Its stable key. */\n key: string;\n /** Its place in the tree, when the table is one. */\n treeEntry?: TreeEntry;\n}\n\n/**\n * The rows a body renders: the tree's visible entries when the host declared\n * a hierarchy, the (possibly windowed) rows otherwise.\n *\n * Nine adapters make the same choice, so they make it in one place — and each\n * body keeps a single `.map` over one list rather than a branch that has to\n * stay in step across nine files.\n *\n * @typeParam TRow - The row type.\n * @param rows - The flat rows, already windowed.\n * @param tree - The tree bundle, when one is armed.\n * @returns What to render, in reading order.\n */\nexport function bodyRowEntries(\n rows: readonly {\n row: TRow;\n index: number;\n key: string;\n sourceIndex?: number;\n }[],\n tree?: { entries: readonly TreeEntry[] }\n): BodyRowEntry[] {\n if (tree) {\n return tree.entries.map((entry, position) => ({\n row: entry.row,\n index: position,\n key: entry.key,\n treeEntry: entry,\n }));\n }\n return rows.map((entry) => ({\n row: entry.row,\n index: entry.index,\n sourceIndex: entry.sourceIndex,\n key: entry.key,\n }));\n}\n","/**\n * Children fetched when a node is opened.\n *\n * A tree of any size cannot arrive whole: an org chart of ten thousand people\n * is one request per branch the reader actually opens. What that costs the host\n * is one callback; what it costs the reader is a spinner on the node they\n * clicked — never a table-wide loading state, because the rest of the tree is\n * still perfectly readable while one branch fills.\n *\n * The set of loading ids lives here rather than in the host's state so the\n * chevron can show it without the host wiring anything: opening a node with\n * unfetched children marks it, and it clears when the rows arrive or the fetch\n * rejects. A node whose fetch failed is left closed and clickable, so the\n * reader's retry is the same gesture as the first attempt.\n */\nimport { useCallback, useEffect, useRef, useState } from \"react\";\n\nimport { useEventCallback } from \"../hooks/useEventCallback\";\n\n/** What {@link useLazyChildren} needs. */\nexport interface UseLazyChildrenOptions {\n /**\n * Fetch a node's children. Resolve once they are in the data the table\n * reads — the table re-walks the tree from the rows it is given, so it needs\n * nothing back.\n */\n onLoadChildren?: (row: TRow) => void | Promise;\n /** Whether a row's children are already in hand. */\n hasLoadedChildren: (row: TRow) => boolean;\n /** Row identity. */\n getRowId: (row: TRow) => string;\n}\n\n/** Lazy-loading state for a tree. */\nexport interface LazyChildrenState {\n /** Nodes being fetched right now — what the chevron shows a spinner for. */\n loadingIds: ReadonlySet;\n /**\n * Call before opening a node: fetches its children when they are missing.\n * Returns nothing — expansion is not blocked on the fetch, so the row opens\n * immediately and fills when the rows arrive.\n */\n loadIfNeeded: (row: TRow) => void;\n /** Ids whose last fetch rejected, so a caller can offer a retry. */\n failedIds: ReadonlySet;\n}\n\n/**\n * Track which nodes are fetching their children, and fetch on demand.\n *\n * @typeParam TRow - The row type.\n * @param options - See {@link UseLazyChildrenOptions}.\n * @returns The state; inert when no `onLoadChildren` is given.\n */\nexport function useLazyChildren(\n options: UseLazyChildrenOptions\n): LazyChildrenState {\n const [loadingIds, setLoadingIds] = useState>(\n () => new Set()\n );\n const [failedIds, setFailedIds] = useState>(\n () => new Set()\n );\n // Ids already asked for, so a second click while a fetch is in flight — or\n // after one that returned nothing — does not ask again.\n const asked = useRef(new Set());\n const alive = useRef(true);\n useEffect(() => {\n alive.current = true;\n return () => {\n alive.current = false;\n };\n }, []);\n\n const settle = useEventCallback((id: string, failed: boolean) => {\n if (!alive.current) return;\n setLoadingIds((current) => {\n const next = new Set(current);\n next.delete(id);\n return next;\n });\n if (failed) {\n asked.current.delete(id);\n setFailedIds((current) => new Set(current).add(id));\n }\n });\n\n const loadIfNeeded = useEventCallback((row: TRow) => {\n const { onLoadChildren, hasLoadedChildren, getRowId } = options;\n if (!onLoadChildren) return;\n const id = getRowId(row);\n if (hasLoadedChildren(row) || asked.current.has(id)) return;\n asked.current.add(id);\n setFailedIds((current) => {\n if (!current.has(id)) return current;\n const next = new Set(current);\n next.delete(id);\n return next;\n });\n setLoadingIds((current) => new Set(current).add(id));\n // A synchronous handler that throws must settle the node too, or the\n // spinner outlives the attempt.\n try {\n void Promise.resolve(onLoadChildren(row)).then(\n () => {\n settle(id, false);\n },\n () => {\n settle(id, true);\n }\n );\n } catch {\n settle(id, true);\n }\n });\n\n return {\n loadingIds,\n failedIds,\n loadIfNeeded: useCallback(loadIfNeeded, [loadIfNeeded]),\n };\n}\n","/**\n * Which tree nodes are open.\n *\n * Separate state from row expansion (a detail panel) and from group collapse\n * (a derived bucket), because they answer different questions and a table can\n * have all three at once. The controlled pair mirrors the others: the table\n * performs the change and tells the host, or the host holds the set.\n *\n * Expanded rather than collapsed, unlike groups: a tree starts folded, so the\n * open set is the small one — the opposite default, and the same reasoning.\n */\nimport { useCallback, useMemo, useState } from \"react\";\n\nimport { useEventCallback } from \"../hooks/useEventCallback\";\n\n/** Tree expansion state and the actions that change it. */\nexport interface TreeExpansionState {\n /** Ids of the currently expanded nodes. */\n expandedIds: ReadonlySet;\n /** Whether a node is expanded. */\n isExpanded: (id: string) => boolean;\n /** Open or close one node. */\n toggle: (id: string) => void;\n /** Open a specific node — what \"reveal this row\" needs. */\n expand: (id: string) => void;\n /** Open every node in `ids`. */\n expandAll: (ids: readonly string[]) => void;\n /** Fold everything. */\n collapseAll: () => void;\n}\n\n/**\n * Headless expansion state for a tree.\n *\n * @param controlled - The host's pair, when it holds the state.\n * @returns The state; uncontrolled unless `expandedIds` is given.\n */\nexport function useTreeExpansion(controlled?: {\n expandedIds?: readonly string[];\n onExpandedIdsChange?: (ids: string[]) => void;\n}): TreeExpansionState {\n const controlledIds = controlled?.expandedIds;\n const isControlled = controlledIds !== undefined;\n const [uncontrolled, setUncontrolled] = useState>(\n () => new Set()\n );\n\n const expandedIds = useMemo(\n () => (isControlled ? new Set(controlledIds ?? []) : uncontrolled),\n [isControlled, controlledIds, uncontrolled]\n );\n\n // Stable across renders: the options object arrives fresh every time, and a\n // commit that changed with it would change every action here.\n const commit = useEventCallback((next: Set) => {\n if (isControlled) controlled?.onExpandedIdsChange?.([...next]);\n else setUncontrolled(next);\n });\n\n const isExpanded = useCallback(\n (id: string) => expandedIds.has(id),\n [expandedIds]\n );\n\n const toggle = useCallback(\n (id: string) => {\n const next = new Set(expandedIds);\n if (next.has(id)) next.delete(id);\n else next.add(id);\n commit(next);\n },\n [expandedIds, commit]\n );\n\n const expand = useCallback(\n (id: string) => {\n if (expandedIds.has(id)) return;\n commit(new Set(expandedIds).add(id));\n },\n [expandedIds, commit]\n );\n\n const expandAll = useCallback(\n (ids: readonly string[]) => {\n commit(new Set(ids));\n },\n [commit]\n );\n\n const collapseAll = useCallback(() => {\n commit(new Set());\n }, [commit]);\n\n return useMemo(\n () => ({\n expandedIds,\n isExpanded,\n toggle,\n expand,\n expandAll,\n collapseAll,\n }),\n [expandedIds, isExpanded, toggle, expand, expandAll, collapseAll]\n );\n}\n","/**\n * How wide each column ends up.\n *\n * A table has two honest answers to \"how wide is this column\": as wide as it\n * needs to be, and as wide as its share of the space. The first overflows and\n * scrolls, which is right for a dense table of many columns; the second fits\n * the container, which is right for a table of six. The difference is one prop,\n * and the mechanism underneath is CSS the browser already knows: a fixed table\n * layout with percentage widths shares space proportionally, and `min-width` /\n * `max-width` clamp it.\n */\nimport type { CSSProperties } from \"react\";\n\nimport type { ColumnDef } from \"../types\";\nimport { columnGroupStubStyle, isColumnGroupStubKey } from \"./headerGroups\";\n\n/** What the sizing needs to know about the table as a whole. */\nexport interface ColumnSizingOptions {\n /** The columns as rendered. */\n columns: readonly ColumnDef[];\n /** Whether the table fits its container rather than overflowing it. */\n fitColumns?: boolean;\n /** User widths from the layout state, which always win. */\n widths?: Readonly>;\n}\n\n/**\n * The share of leftover space each flexible column takes.\n *\n * A column with a width — declared or dragged — is not flexible: the user or\n * the author already answered the question for it. Everything else divides\n * what remains, weighted by `flex`, which defaults to 1 in fitting mode so a\n * table of plain columns simply spreads.\n *\n * @typeParam TRow - The row type.\n * @param options - See {@link ColumnSizingOptions}.\n * @returns Total flex weight, and each flexible column's percentage.\n */\nexport function columnFlexShares(\n options: ColumnSizingOptions\n): Readonly> {\n const { columns, fitColumns = false, widths } = options;\n const flexible = columns.filter(\n (column) =>\n widths?.[column.key] === undefined &&\n column.width === undefined &&\n (column.flex !== undefined || fitColumns)\n );\n const total = flexible.reduce((sum, column) => sum + (column.flex ?? 1), 0);\n if (total === 0) return {};\n const shares: Record = {};\n for (const column of flexible) {\n shares[column.key] = ((column.flex ?? 1) / total) * 100;\n }\n return shares;\n}\n\n/**\n * The style one column's cells carry: its width, and the bounds it keeps.\n *\n * The user's dragged width wins over everything — they said what they wanted\n * — then the column's own `width`, then its share of the leftover space.\n *\n * @typeParam TRow - The row type.\n * @param column - The column being sized.\n * @param shares - Percentages from {@link columnFlexShares}.\n * @param userWidth - The width from the layout state, when the user set one.\n * @returns The style, or `undefined` when the column says nothing about size.\n */\nexport function columnSizeStyle(\n column: ColumnDef,\n shares: Readonly> = {},\n userWidth?: number\n): CSSProperties | undefined {\n if (isColumnGroupStubKey(column.key)) {\n return columnGroupStubStyle();\n }\n const share = shares[column.key];\n const width =\n userWidth ??\n column.width ??\n (share === undefined ? undefined : `${share}%`);\n if (\n width === undefined &&\n column.minWidth === undefined &&\n column.maxWidth === undefined\n ) {\n return undefined;\n }\n return {\n width,\n minWidth: column.minWidth,\n maxWidth: column.maxWidth,\n };\n}\n\n/**\n * The style the `` itself carries when it fits its container.\n *\n * `table-layout: fixed` is what makes percentage widths mean anything: without\n * it the browser sizes columns from their content and the percentages are a\n * suggestion it may ignore.\n *\n * @param fitColumns - Whether the table fits its container.\n * @returns The style, or `undefined` when it overflows as usual.\n */\nexport function fittedTableStyle(\n fitColumns?: boolean\n): CSSProperties | undefined {\n return fitColumns === true\n ? { tableLayout: \"fixed\", width: \"100%\" }\n : undefined;\n}\n","import type { ColumnDef } from \"../types\";\n\n/** Which layout a table is rendering in. */\nexport type TableLayout = \"desktop\" | \"mobile\";\n\n/**\n * Resolve the columns visible for a layout.\n *\n * - Desktop: drops `hideOnDesktop` columns.\n * - Mobile: drops `hideOnMobile` columns, but the first three declared\n * desktop-visible columns WITHOUT an explicit `hideOnMobile` surface so\n * every card keeps a minimum identity block — an explicit hide always\n * wins over the identity default. Mobile-only columns (`hideOnDesktop`\n * without `hideOnMobile`) render here — they exist precisely for the\n * card layout.\n *\n * @typeParam TRow - The row type.\n * @param columns - All declared columns.\n * @param layout - The current layout.\n * @returns The columns to render, in declared order.\n */\nexport function visibleColumns(\n columns: readonly ColumnDef[],\n layout: TableLayout,\n mobileIdentityColumns = 3\n): ColumnDef[] {\n if (layout === \"desktop\") return columns.filter((c) => !c.hideOnDesktop);\n // Identity anchors come from the desktop view (the columns a user knows),\n // but mobile filters the FULL declared set so mobile-only columns survive.\n // An explicit `hideOnMobile` is never anchored — the author's hide wins,\n // and the next desktop-visible column takes the identity slot instead.\n const alwaysShow = new Set(\n columns\n .filter((c) => !c.hideOnDesktop && !c.hideOnMobile)\n .slice(0, Math.max(0, mobileIdentityColumns))\n .map((c) => c.key)\n );\n return columns.filter((c) => alwaysShow.has(c.key) || !c.hideOnMobile);\n}\n","import { useCallback, useMemo } from \"react\";\n\nimport type { ExtraFilters, FilterValue } from \"../types\";\nimport {\n type ActiveFilterChip,\n type ChipLabelResolver,\n useActiveFilterChips,\n} from \"./useActiveFilterChips\";\n\n/** Options for {@link useExtraChips}. */\nexport interface UseExtraChipsOptions {\n /** A source's `extra` bag. */\n readonly extra: ExtraFilters;\n /** A source's `setExtra` setter. */\n readonly setExtra: (key: string, value: FilterValue) => void;\n /**\n * Map of filter key → label resolver. Only keys present here become\n * chips. Memoise this on the caller side when the resolver closes over\n * `t`/lookup data so the chip list stays stable across renders.\n */\n readonly labels: Readonly>;\n}\n\n/**\n * Convenience wrapper over {@link useActiveFilterChips} that reads a\n * source's `extra` bag, applies the label resolvers, and wires each\n * chip's removal back to `setExtra`. The caller only declares the labels.\n *\n * @param options - See {@link UseExtraChipsOptions}.\n * @returns The derived chips.\n */\nexport function useExtraChips({\n extra,\n setExtra,\n labels,\n}: UseExtraChipsOptions): ActiveFilterChip[] {\n const values = useMemo>(() => {\n const out: Record = {};\n for (const key of Object.keys(labels)) {\n const v = extra[key];\n if (v == null || v === \"\") continue;\n if (Array.isArray(v) && v.length === 0) continue;\n out[key] = v;\n }\n return out;\n }, [extra, labels]);\n\n const onChange = useCallback(\n (key: string, next: FilterValue) => {\n setExtra(key, next ?? \"\");\n },\n [setExtra]\n );\n\n return useActiveFilterChips({ values, labels, onChange });\n}\n","/** Derived pagination figures for a paged view. */\nexport interface PaginationInfo {\n /** Total number of pages (always ≥ 1). */\n totalPages: number;\n /** The page clamped into `[1, totalPages]`. */\n safePage: number;\n /** 1-based index of the first row on the page (0 when empty). */\n fromIndex: number;\n /** 1-based index of the last row on the page (0 when empty). */\n toIndex: number;\n}\n\n/**\n * Compute page count and the visible \"from–to\" range for a paged view.\n *\n * @param input - Current `page`, `limit`, and `total`.\n * @returns The derived {@link PaginationInfo}.\n */\nexport function computePagination(input: {\n page: number;\n limit: number;\n total: number;\n}): PaginationInfo {\n // Coerce non-finite inputs (NaN/Infinity from hand-built params or bad\n // data) to sane defaults so the derived figures are never NaN.\n const limit = Number.isFinite(input.limit) ? Math.max(input.limit, 1) : 1;\n const total = Number.isFinite(input.total) ? Math.max(input.total, 0) : 0;\n const page = Number.isFinite(input.page) ? input.page : 1;\n const totalPages = Math.max(1, Math.ceil(total / limit));\n const safePage = Math.min(Math.max(page, 1), totalPages);\n const fromIndex = total === 0 ? 0 : (safePage - 1) * limit + 1;\n const toIndex = Math.min(safePage * limit, total);\n return { totalPages, safePage, fromIndex, toIndex };\n}\n\n/** One slot in a numbered pager: a page number, or a gap where pages were elided. */\nexport type PaginationItem = number | \"ellipsis\";\n\nfunction range(start: number, end: number): number[] {\n const out: number[] = [];\n for (let n = start; n <= end; n += 1) out.push(n);\n return out;\n}\n\n/**\n * A pager slot paired with a stable React key — page numbers key on themselves,\n * ellipses on their semantic side (`ellipsis-left` / `ellipsis-right`). Use this\n * instead of indexing into {@link paginationItems} so list keys never depend on\n * the array position.\n */\nexport interface PaginationSlot {\n /** The page number or `\"ellipsis\"` marker. */\n item: PaginationItem;\n /** A stable, position-free React key for this slot. */\n key: string;\n}\n\n/**\n * Build the keyed pager slots (see {@link PaginationSlot}) for a numbered pager.\n * Wraps {@link paginationItems}, assigning each ellipsis a `left`/`right` side\n * key in encounter order — at most two ellipses ever appear, so the side is a\n * stable identity that does not rely on the array index.\n *\n * @param page - The current (1-based) page.\n * @param totalPages - Total page count (coerced to ≥ 1).\n * @param siblings - Pages to show on each side of the current page.\n * @returns Keyed pager slots.\n */\nexport function paginationSlots(\n page: number,\n totalPages: number,\n siblings = 1\n): PaginationSlot[] {\n let nextSide: \"left\" | \"right\" = \"left\";\n return paginationItems(page, totalPages, siblings).map((item) => {\n if (item === \"ellipsis\") {\n const key = `ellipsis-${nextSide}`;\n nextSide = \"right\";\n return { item, key };\n }\n return { item, key: String(item) };\n });\n}\n\n/**\n * Build the page-number sequence for a numbered pager — the first and last\n * (boundary) pages, the current page with `siblings` neighbours on each side,\n * and an `\"ellipsis\"` marker wherever a run of pages is elided. Mirrors the\n * `boundaries: 1` / `siblings: 1` defaults of the kit `` widgets so\n * every adapter — including the hand-rendered unstyled and Chakra pagers — lays\n * pages out identically.\n *\n * @param page - The current (1-based) page.\n * @param totalPages - Total page count (coerced to ≥ 1).\n * @param siblings - Pages to show on each side of the current page.\n * @returns Ordered page numbers interleaved with `\"ellipsis\"` gaps.\n */\nexport function paginationItems(\n page: number,\n totalPages: number,\n siblings = 1\n): PaginationItem[] {\n const total = Number.isFinite(totalPages)\n ? Math.max(1, Math.floor(totalPages))\n : 1;\n const current = Math.min(Math.max(Math.floor(page) || 1, 1), total);\n const boundaries = 1;\n\n // With first/last boundaries, the current page + its siblings, and two\n // ellipses, this many slots fit without eliding anything — so just list all.\n const maxSlots = boundaries * 2 + siblings * 2 + 3;\n if (total <= maxSlots) return range(1, total);\n\n const left = Math.max(\n Math.min(current - siblings, total - boundaries - siblings * 2 - 1),\n boundaries + 2\n );\n const right = Math.min(\n Math.max(current + siblings, boundaries + siblings * 2 + 2),\n total - boundaries - 1\n );\n\n return [\n ...range(1, boundaries),\n // Collapse a single skipped page to that page rather than an ellipsis.\n left > boundaries + 2 ? \"ellipsis\" : boundaries + 1,\n ...range(left, right),\n right < total - boundaries - 1 ? \"ellipsis\" : total - boundaries,\n ...range(total - boundaries + 1, total),\n ];\n}\n","import type { HeaderSelectionState } from \"../selection/useSelection\";\n\n/**\n * Tri-state for a group checkbox over its leaf row ids — same enum as the\n * table header selection state. Leaf ids only; never synthetic group keys.\n */\nexport function groupSelectionState(\n leafIds: readonly string[],\n selectedIds: ReadonlySet\n): HeaderSelectionState {\n if (leafIds.length === 0) return \"none\";\n let selected = 0;\n for (const id of leafIds) {\n if (selectedIds.has(id)) selected += 1;\n }\n if (selected === 0) return \"none\";\n if (selected === leafIds.length) return \"all\";\n return \"some\";\n}\n\n/**\n * Toggle every leaf in the group: if any leaf is unselected, select all;\n * otherwise deselect all (matches typical \"select group\" checkbox UX).\n */\nexport function nextGroupSelection(\n leafIds: readonly string[],\n selectedIds: ReadonlySet\n): { action: \"select\" | \"deselect\"; ids: readonly string[] } {\n const state = groupSelectionState(leafIds, selectedIds);\n if (state === \"all\") return { action: \"deselect\", ids: leafIds };\n return { action: \"select\", ids: leafIds };\n}\n\n/**\n * Apply a group checkbox toggle in one pass — returns the next selected-id\n * set (adapters / {@link useSelection.toggleGroupLeaves} commit this).\n */\nexport function applyGroupLeafSelection(\n leafIds: readonly string[],\n selectedIds: ReadonlySet\n): Set {\n const { action, ids } = nextGroupSelection(leafIds, selectedIds);\n const next = new Set(selectedIds);\n for (const id of ids) {\n if (action === \"select\") next.add(id);\n else next.delete(id);\n }\n return next;\n}\n","import { useCallback, useEffect, useMemo, useRef, useState } from \"react\";\n\nimport { applyGroupLeafSelection } from \"../grouping/groupSelection\";\n\n/** Tri-state of the \"select all visible\" header control. */\nexport type HeaderSelectionState = \"all\" | \"some\" | \"none\";\n\n/** Options for {@link useSelection}. */\nexport interface UseSelectionOptions {\n /** The currently visible rows. */\n rows: readonly TRow[];\n /** Stable id extractor for a row. */\n getId: (row: TRow) => string;\n /**\n * When this value changes, the selection is cleared (the previously\n * selected ids may no longer be visible). Compose it from search /\n * page / active-filter count — e.g. `` `${search}|${page}` ``.\n */\n resetKey?: unknown;\n /**\n * Controlled selection. When provided, the hook reads from this value\n * and reports every change request through `onSelectionChange` instead\n * of mutating its own state — the same controlled/uncontrolled split as\n * `useColumnLayout`.\n */\n selectedIds?: readonly string[];\n /** Change handler; required for the controlled mode to update. */\n onSelectionChange?: (selectedIds: string[]) => void;\n}\n\n/** Selection state + actions returned by {@link useSelection}. */\nexport interface SelectionState {\n /** The set of selected ids. */\n selectedIds: ReadonlySet;\n /** Number of selected ids. */\n selectedCount: number;\n /** Tri-state for the visible rows (`all` / `some` / `none`). */\n headerState: HeaderSelectionState;\n /** Whether a specific id is selected. */\n isSelected: (id: string) => boolean;\n /** Toggle a single id. */\n toggle: (id: string) => void;\n /**\n * Toggle all leaf ids in a group (select missing, or deselect when all\n * selected) — one commit so memoized rows see a single selection change.\n */\n toggleGroupLeaves: (leafIds: readonly string[]) => void;\n /** Toggle every visible id (select all, or clear all if already full). */\n toggleAll: () => void;\n /** Clear the entire selection. */\n clear: () => void;\n /** The visible ids, in row order. */\n visibleIds: string[];\n /** True when the user chose \"select all matching\" across every page. */\n allMatching: boolean;\n /** Extend the selection to every matching row (across all pages). */\n selectAllMatching: () => void;\n}\n\n/**\n * Headless multi-row selection. Tracks a set of ids, derives the header\n * tri-state from the visible rows, and clears itself when `resetKey`\n * changes so stale ids never linger after a filter/page change.\n *\n * @typeParam TRow - The row type.\n * @param options - See {@link UseSelectionOptions}.\n * @returns Selection state and actions.\n */\nexport function useSelection(\n options: UseSelectionOptions\n): SelectionState {\n const { rows, getId, resetKey } = options;\n const controlledValue = options.selectedIds;\n const onChange = options.onSelectionChange;\n const [internal, setInternal] = useState>(() => new Set());\n const [allMatching, setAllMatching] = useState(false);\n const controlled = controlledValue !== undefined;\n const selectedIds = useMemo(\n () => (controlledValue === undefined ? internal : new Set(controlledValue)),\n [controlledValue, internal]\n );\n\n // The mutators below close over `commit`; reading the live mode/state\n // through this ref keeps their identities PERMANENTLY stable — memoized\n // adapter rows can hold `toggle` forever without computing from a stale\n // set in the controlled mode.\n const modeRef = useRef({ controlled, onChange, selectedIds });\n modeRef.current = { controlled, onChange, selectedIds };\n\n /** Route a change to the parent (controlled) or internal state. */\n const commit = useCallback(\n (compute: (prev: ReadonlySet) => Set) => {\n // Any explicit mutation narrows the scope back to concrete ids.\n setAllMatching(false);\n const live = modeRef.current;\n if (live.controlled) {\n live.onChange?.([...compute(live.selectedIds)]);\n } else {\n setInternal((prev) => compute(prev));\n }\n },\n []\n );\n\n const selectAllMatching = useCallback(() => setAllMatching(true), []);\n\n // Clear on reset-key change, but not on first mount. The effect reads the\n // LATEST size through a ref so only `resetKey` retriggers it. The guard\n // is last-seen-value, not a boolean first-run flag: refs survive\n // StrictMode's simulated remount, so a boolean guard saw the doubled\n // mount effect as a \"change\" and wiped a controlled preselection.\n const liveRef = useRef({ commit, size: selectedIds.size });\n liveRef.current = { commit, size: selectedIds.size };\n const lastResetKeyRef = useRef(resetKey);\n useEffect(() => {\n if (Object.is(lastResetKeyRef.current, resetKey)) return;\n lastResetKeyRef.current = resetKey;\n // Identity-preserving no-op when there is nothing to clear.\n if (liveRef.current.size === 0) return;\n liveRef.current.commit(() => new Set());\n }, [resetKey]);\n\n const visibleIds = useMemo(() => rows.map(getId), [rows, getId]);\n\n const selectedVisible = useMemo(\n () => visibleIds.reduce((n, id) => (selectedIds.has(id) ? n + 1 : n), 0),\n [visibleIds, selectedIds]\n );\n\n let headerState: HeaderSelectionState = \"none\";\n if (visibleIds.length > 0 && selectedVisible === visibleIds.length) {\n headerState = \"all\";\n } else if (selectedVisible > 0) {\n headerState = \"some\";\n }\n\n const isSelected = useCallback(\n (id: string) => selectedIds.has(id),\n [selectedIds]\n );\n\n const toggle = useCallback(\n (id: string) => {\n commit((prev) => {\n const next = new Set(prev);\n if (next.has(id)) next.delete(id);\n else next.add(id);\n return next;\n });\n },\n [commit]\n );\n\n const toggleGroupLeaves = useCallback(\n (leafIds: readonly string[]) => {\n commit((prev) => applyGroupLeafSelection(leafIds, prev));\n },\n [commit]\n );\n\n const toggleAll = useCallback(() => {\n commit((prev) => {\n const next = new Set(prev);\n const allSelected =\n visibleIds.length > 0 && visibleIds.every((id) => next.has(id));\n for (const id of visibleIds) {\n if (allSelected) next.delete(id);\n else next.add(id);\n }\n return next;\n });\n }, [commit, visibleIds]);\n\n const clear = useCallback(() => commit(() => new Set()), [commit]);\n\n // Stable identity: row-level React.memo in the adapters depends on the\n // selection object only changing when the selection actually changes.\n return useMemo(\n () => ({\n selectedIds,\n selectedCount: selectedIds.size,\n headerState,\n isSelected,\n toggle,\n toggleGroupLeaves,\n toggleAll,\n clear,\n visibleIds,\n allMatching,\n selectAllMatching,\n }),\n [\n selectedIds,\n headerState,\n isSelected,\n toggle,\n toggleGroupLeaves,\n toggleAll,\n clear,\n visibleIds,\n allMatching,\n selectAllMatching,\n ]\n );\n}\n","import type { SortLevel } from \"./compare\";\n\n/**\n * Advance the three-step sort cycle for a column header click:\n * inactive → ascending → descending → cleared.\n *\n * @param current - The current sort pair (both fields unset when inactive).\n * @param key - The column key that was clicked.\n * @returns The next sort state.\n */\nexport function nextSort(\n current: Partial,\n key: string\n): Partial {\n if (current.key !== key) return { key, dir: \"asc\" };\n if (current.dir === \"asc\") return { key, dir: \"desc\" };\n return { key: undefined, dir: undefined };\n}\n","import type { ColumnDef, SortByOption } from \"../types\";\n\n/**\n * Build sort-by select options from sortable columns. On mobile the card\n * layout has no clickable headers, so a \"Sort by\" select is the only sort\n * affordance — adapters fall back to these when the caller passes no explicit\n * `sortByOptions`.\n *\n * A column contributes an option when it is `sortable` and has a string label\n * (its `header`, else `mobileLabel`). Columns with non-string headers and no\n * `mobileLabel` are skipped — there's nothing to show in the select.\n *\n * @typeParam TRow - The row type.\n * @param columns - The columns to derive from (already layout-filtered).\n * @returns One option per labellable sortable column, in column order.\n */\nexport function deriveSortByOptions(\n columns: readonly ColumnDef[]\n): SortByOption[] {\n const options: SortByOption[] = [];\n for (const column of columns) {\n if (!column.sortable) continue;\n let label: string | undefined;\n if (typeof column.header === \"string\") label = column.header;\n else if (typeof column.mobileLabel === \"string\") label = column.mobileLabel;\n if (label !== undefined) options.push({ value: column.key, label });\n }\n return options;\n}\n","import type { CSSProperties } from \"react\";\n\n/**\n * Any props object a prop-getter can produce or accept for merging.\n *\n * @internal — prop-getter plumbing. Consumers use the prop-getters from\n * `useDataTable`, not this merge helper directly.\n */\nexport type Props = Record;\n\nfunction isEventHandler(\n key: string,\n value: unknown\n): value is (...a: unknown[]) => void {\n return typeof value === \"function\" && /^on[A-Z]/.test(key);\n}\n\n/**\n * Merge a prop-getter's own props with caller overrides (the\n * Downshift/Radix pattern). Event handlers (`onX`) are composed so both\n * run; `className` strings are concatenated; `style` objects are merged.\n * Everything else is overridden by the caller's value.\n *\n * @param base - The prop-getter's own props.\n * @param overrides - Optional caller-supplied props to merge on top.\n * @returns The merged props object.\n *\n * @internal — prop-getter plumbing. Consumers use the prop-getters from\n * `useDataTable`, not this merge helper directly.\n */\nexport function mergeProps(base: T, overrides?: Props): T {\n if (!overrides) return base;\n const out: Props = { ...base };\n\n for (const [key, value] of Object.entries(overrides)) {\n const existing = out[key];\n if (isEventHandler(key, value) && isEventHandler(key, existing)) {\n out[key] = (...args: unknown[]) => {\n existing(...args);\n value(...args);\n };\n } else if (key === \"className\" && existing && value) {\n out[key] = `${existing as string} ${value as string}`;\n } else if (key === \"style\" && existing && value) {\n out[key] = {\n ...(existing as CSSProperties),\n ...(value as CSSProperties),\n };\n } else {\n out[key] = value;\n }\n }\n\n return out as T;\n}\n","import { useEffect, useState } from \"react\";\n\n/**\n * Debounce a rapidly-changing value. The returned value only updates\n * after `delay` ms have elapsed without a new change.\n *\n * @typeParam T - The value type.\n * @param value - The source value.\n * @param delay - Debounce delay in milliseconds. Defaults to 300.\n * @returns The debounced value.\n */\nexport function useDebounce(value: T, delay = 300): T {\n const [debounced, setDebounced] = useState(value);\n\n useEffect(() => {\n const id = setTimeout(() => setDebounced(value), delay);\n return () => clearTimeout(id);\n }, [value, delay]);\n\n return debounced;\n}\n","import { useEffect, useRef, useState } from \"react\";\n\nimport { useDebounce } from \"../hooks/useDebounce\";\n\n/** A controlled, debounced search input bound to a committed value. */\nexport interface SearchInputState {\n /** The live (uncommitted) input value. */\n value: string;\n /** Update the live input value. */\n setValue: (next: string) => void;\n}\n\n/**\n * Bridge a fast-typing search box to a slower committed search value.\n * Local input updates immediately; the trimmed value is flushed to\n * `setSearch` after the debounce, and external `search` changes (back\n * button, deep link, clear-all) mirror back into the input.\n *\n * @param search - The committed search value (from a source).\n * @param setSearch - Commit a new search value.\n * @param debounceMs - Debounce delay; defaults to 300.\n * @returns The controlled input state.\n */\nexport function useSearchInput(\n search: string,\n setSearch: (next: string) => void,\n debounceMs = 300\n): SearchInputState {\n const [value, setValue] = useState(search);\n const debounced = useDebounce(value, debounceMs);\n // The last value we committed, so we can tell our own echo (the committed\n // value coming back as `search`) from a genuine external change.\n const committedRef = useRef(search);\n\n // Mirror only *external* changes (back button, deep link, clear-all) into\n // the input. Skipping our own echo avoids clobbering in-flight typing:\n // a keystroke landing between commit and the committed-value re-render\n // must not be reset to the just-committed string.\n useEffect(() => {\n if (search !== committedRef.current) {\n committedRef.current = search;\n setValue(search);\n }\n }, [search]);\n\n // Debounced input → commit, skipping when already in sync. Compare against\n // the last value WE committed (not the live `search`): when an external\n // change (clear-all, back button) lands while a debounce is still pending,\n // `search` flips but `debounced` is briefly stale — keying off `search` here\n // would re-commit that stale value and resurrect the cleared/old search.\n useEffect(() => {\n const trimmed = debounced.trim();\n if (trimmed !== committedRef.current) {\n committedRef.current = trimmed;\n setSearch(trimmed);\n }\n }, [debounced, setSearch]);\n\n return { value, setValue };\n}\n","import type { CSSProperties, ReactNode } from \"react\";\nimport { createElement, useCallback, useEffect, useMemo } from \"react\";\n\nimport { columnFlexShares, columnSizeStyle } from \"../columns/columnSizing\";\nimport { resolveColumns } from \"../columns/resolveColumns\";\nimport { visibleColumns } from \"../columns/visibleColumns\";\nimport { SEARCH_DEBOUNCE_MS } from \"../constants\";\nimport {\n type ActiveFilterChip,\n type ChipLabelResolver,\n} from \"../filters/useActiveFilterChips\";\nimport { useExtraChips } from \"../filters/useExtraChips\";\nimport { resolveLabels } from \"../labels\";\nimport {\n computePagination,\n type PaginationInfo,\n} from \"../pagination/paginationMath\";\nimport { type SelectionState, useSelection } from \"../selection/useSelection\";\nimport { nextSort } from \"../sort/cycleSort\";\nimport { deriveSortByOptions } from \"../sort/sortByOptions\";\nimport type { TableSource } from \"../source/TableSource\";\nimport type {\n BulkAction,\n ColumnDef,\n Direction,\n SortByOption,\n SortDirection,\n TableLabels,\n} from \"../types\";\nimport { devWarn } from \"../utils/devWarn\";\nimport { mergeProps, type Props } from \"../utils/mergeProps\";\nimport { stableKey } from \"../utils/stableKey\";\nimport { useSearchInput } from \"./useSearchInput\";\n\nconst EMPTY_LABELS: Readonly> = {};\n\n/** Options for {@link useDataTable}. */\nexport interface UseDataTableOptions {\n /** The data + state contract, from `useFrontendData` / `useQuerySource`. */\n source: TableSource;\n /** Column definitions. */\n columns: ColumnDef[];\n /**\n * Make the columns share the container's width instead of overflowing it.\n * Columns with `flex` take that share; columns with a `width` keep it.\n */\n fitColumns?: boolean;\n /** User widths from the column layout, which win over everything else. */\n columnWidths?: Readonly>;\n /** Stable React key extractor for a row. */\n rowKey: (row: TRow) => string;\n /** Accessible label for the table element. */\n tableLabel?: string;\n /** Pre-translated label overrides (merged over English defaults). */\n labels?: TableLabels;\n /** Text direction. Defaults to `\"ltr\"`. */\n dir?: Direction;\n /** Render the mobile (card) layout. Defaults to `false`. */\n forceMobile?: boolean;\n /**\n * Active locale — drives per-column `i18n` data-path resolution for\n * bare-key columns, exactly as it does under ``.\n */\n locale?: string;\n /** Number of leading desktop-visible columns always shown on mobile cards. */\n mobileIdentityColumns?: number;\n /** Search debounce in ms. Defaults to 300. */\n searchDebounceMs?: number;\n /** Bulk actions — enabling these turns on selection. */\n bulkActions?: BulkAction[];\n /** Selection id extractor; defaults to `rowKey` when bulk actions exist. */\n selectionGetId?: (row: TRow) => string;\n /** Controlled selection value (see {@link BaseDataTableProps.selectedIds}). */\n selectedIds?: readonly string[];\n /** Change handler for the controlled selection. */\n onSelectedIdsChange?: (selectedIds: string[]) => void;\n /** Per-filter-key chip label resolvers (drives the chip strip). */\n filterLabels?: Readonly>;\n /** Enable shift-click multi-column sorting (see BaseDataTableProps). */\n multiSort?: boolean;\n}\n\n/** Everything a headless consumer needs to render a table. */\nexport interface UseDataTableResult {\n /** The materialised rows for the current slice. */\n rows: readonly TRow[];\n /** Whether there are no rows and nothing is loading. */\n isEmpty: boolean;\n /** Columns visible for the current layout. */\n columns: ColumnDef[];\n /** Whether the mobile (card) layout is active. */\n isMobile: boolean;\n /**\n * Sort-by select options auto-derived from the sortable columns. Adapters\n * render these as the mobile sort affordance (no clickable headers there)\n * when the caller passes no explicit `sortByOptions`.\n */\n sortByOptions: SortByOption[];\n /** Resolved labels (English defaults + overrides). */\n labels: Required;\n /** Text direction. */\n dir: Direction;\n /** Derived pagination figures. */\n pagination: PaginationInfo;\n /** Active sort column key. */\n sortBy: string | undefined;\n /** Active sort direction. */\n sortDir: SortDirection | undefined;\n /** Advance the sort cycle for a column. */\n toggleSort: (key: string) => void;\n /** The controlled search input value. */\n searchValue: string;\n /** Update the search input value. */\n setSearchValue: (next: string) => void;\n /** Selection state, or `null` when no bulk actions are configured. */\n selection: SelectionState | null;\n /** Removable filter chips derived from `filterLabels` + the source. */\n filterChips: ActiveFilterChip[];\n /** Number of active filter chips (drives the Filters badge). */\n activeFilterCount: number;\n /** The underlying source (for pagination setters, fetchNextPage, etc.). */\n source: TableSource;\n\n /* ── Prop-getters (merge caller overrides) ───────────────────────── */\n getTableProps: (props?: Props) => TableElementProps;\n getHeaderRowProps: (props?: Props) => Props;\n getHeaderCellProps: (\n column: ColumnDef,\n props?: Props\n ) => CellElementProps;\n getSortButtonProps: (\n column: ColumnDef,\n props?: Props\n ) => SortButtonElementProps;\n getRowProps: (row: TRow, index: number, props?: Props) => RowElementProps;\n getCellProps: (column: ColumnDef, props?: Props) => CellElementProps;\n getSearchInputProps: (props?: Props) => SearchInputElementProps;\n /**\n * The row's stable React key. Kept OUT of {@link getRowProps} so its\n * result spreads clean — React forbids spreading a `key`.\n */\n getRowKey: (row: TRow) => string;\n /**\n * A cell's rendered content: the column's `Cell` component when set,\n * else its (resolved) `accessor` value — no optional chaining needed.\n */\n getCellContent: (\n column: ColumnDef,\n row: TRow,\n rowIndex: number\n ) => ReactNode;\n}\n\n/* Precise prop-getter return shapes. Each extends `Props` (keeping the\n index signature so caller overrides still merge and `mergeProps` stays\n compatible) while typing the known keys — so adapters read them without\n casts. */\n\n/** Props from {@link UseDataTableResult.getTableProps}. */\nexport interface TableElementProps extends Props {\n role: string;\n dir?: Direction;\n \"aria-label\": string;\n}\n\n/**\n * Props from {@link UseDataTableResult.getRowProps}. Spread-clean by\n * contract: never contains `key` — read {@link UseDataTableResult.getRowKey}\n * for the React key.\n */\nexport interface RowElementProps extends Props {\n role: string;\n /** The structural part name every kit's body row carries. */\n \"data-adapttable-part\": \"row\";\n /** The row's id, so an event can be traced back to the row it happened in. */\n \"data-row-id\": string;\n \"data-index\": number;\n \"aria-selected\"?: boolean;\n}\n\n/** Props from {@link UseDataTableResult.getSortButtonProps}. */\nexport interface SortButtonElementProps extends Props {\n type: \"button\";\n disabled: boolean;\n onClick: (event?: { shiftKey?: boolean }) => void;\n \"data-sort-index\"?: number;\n \"aria-label\": string;\n}\n\n/** Props from {@link UseDataTableResult.getCellProps} / `getHeaderCellProps`. */\nexport interface CellElementProps extends Props {\n role: string;\n style?: CSSProperties;\n \"data-sort-index\"?: number;\n}\n\n/** Props from {@link UseDataTableResult.getSearchInputProps}. */\nexport interface SearchInputElementProps extends Props {\n type: string;\n role: string;\n value: string;\n placeholder: string;\n \"aria-label\": string;\n onChange: (event: { currentTarget: { value: string } }) => void;\n}\n\nfunction textAlign(\n align: ColumnDef[\"align\"]\n): \"start\" | \"center\" | \"end\" {\n if (align === \"center\") return \"center\";\n if (align === \"end\") return \"end\";\n return \"start\";\n}\n\n/** The chain level for a column, if multi-sort has one. */\nfunction chainLevel(\n levels: readonly { key: string; dir: \"asc\" | \"desc\" }[],\n key: string\n): { key: string; dir: \"asc\" | \"desc\" } | undefined {\n return levels.find((l) => l.key === key);\n}\n\n/** 1-based chain position for the header badge, or undefined. */\nfunction sortIndexAttr(\n levels: readonly { key: string; dir: \"asc\" | \"desc\" }[],\n key: string\n): number | undefined {\n const index = levels.findIndex((l) => l.key === key);\n return index === -1 ? undefined : index + 1;\n}\n\nfunction ariaSort(\n column: ColumnDef,\n sortBy: string | undefined,\n sortDir: SortDirection | undefined\n): \"ascending\" | \"descending\" | \"none\" | undefined {\n if (!column.sortable) return undefined;\n if (sortBy !== column.key) return \"none\";\n return sortDir === \"asc\" ? \"ascending\" : \"descending\";\n}\n\n/** A row type we don't care about here — `align` is independent of it. */\ntype TRowAny = Record;\n\n/**\n * The headless entry point. Combines a {@link TableSource} with columns,\n * sorting, a debounced search input, selection, and filter chips, and\n * returns derived state plus accessible prop-getters so consumers can\n * render any markup with any UI kit.\n *\n * @typeParam TRow - The row type.\n * @param options - See {@link UseDataTableOptions}.\n * @returns Derived state and prop-getters — see {@link UseDataTableResult}.\n */\nexport function useDataTable(\n options: UseDataTableOptions\n): UseDataTableResult {\n const {\n source,\n columns: declaredColumns,\n rowKey,\n tableLabel,\n labels: labelOverrides,\n dir = \"ltr\",\n forceMobile: isMobile = false,\n mobileIdentityColumns = 3,\n searchDebounceMs = SEARCH_DEBOUNCE_MS,\n bulkActions,\n selectionGetId,\n selectedIds,\n onSelectedIdsChange,\n filterLabels = EMPTY_LABELS,\n multiSort = false,\n locale,\n fitColumns = false,\n columnWidths,\n } = options;\n\n const labels = useMemo(() => resolveLabels(labelOverrides), [labelOverrides]);\n\n // Bare-key columns auto-derive their header and accessor here, exactly\n // as they do under `` — headless callers get real headers and\n // cells, not blanks. Idempotent: already-complete columns pass through.\n const allColumns = useMemo(\n () => resolveColumns(declaredColumns, locale),\n [declaredColumns, locale]\n );\n\n // Duplicate keys silently corrupt sorting, selection, and column layout —\n // every feature targets columns by key. Catch it in development.\n useEffect(() => {\n const seen = new Set();\n for (const column of allColumns) {\n if (seen.has(column.key)) {\n devWarn(\n `duplicate column key \"${column.key}\" — column keys must be unique; sorting, selection, and column layout all target keys.`\n );\n }\n seen.add(column.key);\n }\n }, [allColumns]);\n\n const columns = useMemo(\n () =>\n visibleColumns(\n allColumns,\n isMobile ? \"mobile\" : \"desktop\",\n mobileIdentityColumns\n ),\n [allColumns, isMobile, mobileIdentityColumns]\n );\n\n // Each flexible column's share of the leftover width, recomputed only when\n // the column set or the user's widths change.\n const flexShares = useMemo(\n () => columnFlexShares({ columns, fitColumns, widths: columnWidths }),\n [columns, fitColumns, columnWidths]\n );\n\n const sortByOptions = useMemo(() => deriveSortByOptions(columns), [columns]);\n\n const { value: searchValue, setValue: setSearchValue } = useSearchInput(\n source.search,\n source.setSearch,\n searchDebounceMs\n );\n\n const filterChips = useExtraChips({\n extra: source.extra,\n setExtra: source.setExtra,\n labels: filterLabels,\n });\n const activeFilterCount = filterChips.length;\n\n const pagination = useMemo(\n () =>\n computePagination({\n page: source.page,\n limit: source.limit,\n total: source.total,\n }),\n [source.page, source.limit, source.total]\n );\n\n const hasBulk = (bulkActions?.length ?? 0) > 0;\n const getId = selectionGetId ?? rowKey;\n // Selection is keyed by id, so it persists across page / sort / page-size\n // changes (the rows still exist); it only resets when the result *set*\n // changes — i.e. a new search term or a filter change. Keyed on the filter\n // *values* (not just the active count) so swapping one filter value for\n // another — same count, different rows — still clears the stale selection.\n const selectionResetKey = `${source.search}|${stableKey(source.extra)}|${source.groupBy ?? \"\"}`;\n const selectionState = useSelection({\n rows: source.rows,\n getId,\n resetKey: selectionResetKey,\n selectedIds,\n onSelectionChange: onSelectedIdsChange,\n });\n const selection = hasBulk ? selectionState : null;\n\n const toggleSort = useCallback(\n (key: string) => {\n const next = nextSort({ key: source.sortBy, dir: source.sortDir }, key);\n source.setSort(next.key, next.dir);\n },\n [source]\n );\n\n const getTableProps = useCallback(\n (props?: Props) =>\n mergeProps(\n { role: \"table\", dir, \"aria-label\": tableLabel ?? labels.table },\n props\n ),\n [dir, tableLabel, labels.table]\n );\n\n const getHeaderRowProps = useCallback(\n (props?: Props) => mergeProps({ role: \"row\" }, props),\n []\n );\n\n const getHeaderCellProps = useCallback(\n (column: ColumnDef, props?: Props) =>\n mergeProps(\n {\n role: \"columnheader\",\n \"aria-sort\": ariaSort(\n column,\n chainLevel(source.sortLevels, column.key)?.key ?? source.sortBy,\n chainLevel(source.sortLevels, column.key)?.dir ?? source.sortDir\n ),\n \"data-sort-index\": sortIndexAttr(source.sortLevels, column.key),\n \"data-column-key\": column.key,\n style: {\n textAlign: textAlign(column.align),\n ...columnSizeStyle(column, flexShares, columnWidths?.[column.key]),\n },\n },\n props\n ),\n [source.sortBy, source.sortDir, source.sortLevels, flexShares, columnWidths]\n );\n\n const getSortButtonProps = useCallback(\n (column: ColumnDef, props?: Props) =>\n mergeProps(\n {\n type: \"button\",\n disabled: !column.sortable,\n onClick: (event?: { shiftKey?: boolean }) => {\n if (!column.sortable) return;\n if (multiSort && event?.shiftKey) {\n source.toggleSortLevel(column.key);\n return;\n }\n toggleSort(column.key);\n },\n \"data-sort-index\": sortIndexAttr(source.sortLevels, column.key),\n \"aria-label\": `${labels.sortBy}: ${\n typeof column.header === \"string\" ? column.header : column.key\n }`,\n },\n props\n ),\n [toggleSort, labels.sortBy, multiSort, source]\n );\n\n // Spread-clean by contract: no `key` in here — React forbids spreading\n // one, and every consumer had to destructure-and-cast it out. The key\n // lives in `getRowKey` instead.\n const getRowProps = useCallback(\n (row: TRow, index: number, props?: Props) => {\n const id = getId(row);\n const selected = selection?.isSelected(id) ?? false;\n return mergeProps(\n {\n role: \"row\",\n // The part name a host styles and tests against, emitted here so\n // one spread names the row in every kit that renders one.\n \"data-adapttable-part\": \"row\",\n // The id an event can be traced back to. It lives here because\n // this is the row's prop-getter — antd, whose
builds its\n // own , carries both through `onRow` instead.\n \"data-row-id\": id,\n \"data-index\": index,\n \"aria-selected\": hasBulk ? selected : undefined,\n },\n props\n );\n },\n [getId, selection, hasBulk]\n );\n\n const getCellContent = useCallback(\n (column: ColumnDef, row: TRow, rowIndex: number): ReactNode =>\n column.Cell\n ? createElement(column.Cell, { row, rowIndex })\n : (column.accessor?.(row) ?? null),\n []\n );\n\n const getCellProps = useCallback(\n (column: ColumnDef, props?: Props) =>\n mergeProps(\n {\n role: \"cell\",\n // Which column this cell belongs to, so auto-sizing can measure a\n // column's content and CSS can target one column across any kit.\n \"data-column-key\": column.key,\n style: {\n textAlign: textAlign(column.align),\n ...columnSizeStyle(column, flexShares, columnWidths?.[column.key]),\n },\n },\n props\n ),\n [flexShares, columnWidths]\n );\n\n const getSearchInputProps = useCallback(\n (props?: Props) =>\n mergeProps(\n {\n type: \"search\",\n role: \"searchbox\",\n value: searchValue,\n placeholder: labels.searchPlaceholder,\n \"aria-label\": labels.search,\n onChange: (event: { currentTarget: { value: string } }) =>\n setSearchValue(event.currentTarget.value),\n },\n props\n ),\n [searchValue, setSearchValue, labels.searchPlaceholder, labels.search]\n );\n\n return {\n rows: source.rows,\n isEmpty: source.rows.length === 0 && !source.isLoading,\n columns,\n isMobile,\n sortByOptions,\n labels,\n dir,\n pagination,\n sortBy: source.sortBy,\n sortDir: source.sortDir,\n toggleSort,\n searchValue,\n setSearchValue,\n selection,\n filterChips,\n activeFilterCount,\n source,\n getTableProps,\n getHeaderRowProps,\n getHeaderCellProps,\n getSortButtonProps,\n getRowProps,\n getCellProps,\n getSearchInputProps,\n getRowKey: rowKey,\n getCellContent,\n };\n}\n\nexport { defaultLabels } from \"../labels\";\n","/**\n * Measuring a row that carries an expanded detail panel beneath it.\n *\n * A virtualizer sizes one item by measuring one element. A row with an open\n * detail panel is two elements — a table cannot nest the panel inside the row\n * it belongs to, because a `` may only contain cells — so measuring the row\n * alone reports 56px for something 300px tall. Scroll positions then drift as\n * soon as anything is expanded, which is the whole reason row detail carried a\n * \"not recommended with virtualize\" warning.\n *\n * So the pair is measured as a pair: both elements are observed, and their\n * combined height is handed to the virtualizer through `resizeItem`. The\n * virtualizer keeps owning the layout; it is simply told the truth about how\n * tall the item is.\n */\nimport { useCallback, useEffect, useMemo, useRef } from \"react\";\n\n/** What a virtualizer must offer for a pair to be measurable. */\nexport interface ResizableVirtualizer {\n /** Tell the virtualizer an item's real size. */\n resizeItem: (index: number, size: number) => void;\n}\n\n/** Ref callbacks for the two halves of one row. */\nexport interface RowPairMeasurer {\n /** Ref for the row element itself. */\n row: (index: number) => (node: Element | null) => void;\n /** Ref for its detail element, when one is open. */\n detail: (index: number) => (node: Element | null) => void;\n}\n\n/** The two elements of one item, either of which may be absent. */\ninterface Pair {\n row: Element | null;\n detail: Element | null;\n}\n\n/**\n * Measure each row together with its open detail panel.\n *\n * Sizes are reported on every resize of either half, so a detail panel that\n * grows — an image loading, a nested table expanding — corrects the item's\n * height rather than leaving the scrollbar wrong until the next scroll.\n *\n * @param virtualizer - The virtualizer to report sizes to.\n * @param enabled - Off when nothing is virtualized or nothing can expand, in\n * which case the returned refs do nothing at all.\n * @returns Ref callbacks for a row and its detail.\n */\nexport function useRowPairMeasurer(\n virtualizer: ResizableVirtualizer | undefined,\n enabled: boolean\n): RowPairMeasurer {\n const pairs = useRef(new Map());\n const observer = useRef(null);\n const owners = useRef(new Map());\n\n const report = useCallback(\n (index: number) => {\n if (!virtualizer) return;\n const pair = pairs.current.get(index);\n if (!pair?.row) return;\n const rowHeight = pair.row.getBoundingClientRect().height;\n const detailHeight = pair.detail?.getBoundingClientRect().height ?? 0;\n const total = rowHeight + detailHeight;\n if (total > 0) virtualizer.resizeItem(index, total);\n },\n [virtualizer]\n );\n\n useEffect(() => {\n if (!enabled || typeof ResizeObserver === \"undefined\") return undefined;\n const seen = owners.current;\n const instance = new ResizeObserver((entries) => {\n const touched = new Set();\n for (const entry of entries) {\n const index = seen.get(entry.target);\n if (index !== undefined) touched.add(index);\n }\n for (const index of touched) report(index);\n });\n observer.current = instance;\n // Refs run during commit and effects after it, so by the time the observer\n // exists the first rows are already attached. Pick them up rather than\n // waiting for a re-render that may never come.\n for (const element of seen.keys()) instance.observe(element);\n return () => {\n instance.disconnect();\n observer.current = null;\n };\n }, [enabled, report]);\n\n const attach = useCallback(\n (index: number, half: keyof Pair) => (node: Element | null) => {\n if (!enabled) return;\n const pair = pairs.current.get(index) ?? { row: null, detail: null };\n const previous = pair[half];\n if (previous && previous !== node) {\n observer.current?.unobserve(previous);\n owners.current.delete(previous);\n }\n pair[half] = node;\n pairs.current.set(index, pair);\n if (node) {\n owners.current.set(node, index);\n observer.current?.observe(node);\n }\n // Report straight away: the first paint is when a wrong height is most\n // visible, and waiting for a resize would mean waiting for a change that\n // may never come.\n report(index);\n },\n [enabled, report]\n );\n\n return useMemo(\n () => ({\n row: (index: number) => attach(index, \"row\"),\n detail: (index: number) => attach(index, \"detail\"),\n }),\n [attach]\n );\n}\n","import {\n useVirtualizer,\n useWindowVirtualizer,\n type VirtualItem,\n} from \"@tanstack/react-virtual\";\nimport { useCallback, useEffect, useMemo, useRef } from \"react\";\n\nimport { VIRTUAL_OVERSCAN } from \"../constants\";\nimport { type RowPairMeasurer, useRowPairMeasurer } from \"./measureRowPair\";\n\n/** One row/card entry materialized from a virtual window. */\nexport interface VirtualTableRow {\n /** Row data for this visual slot. */\n row: TRow;\n /**\n * Index in the array the virtualizer windows. When pinning is on that is\n * the unpinned scroll list, not the page — use {@link rowSourceIndex}\n * for ARIA, focus and `rowClassName`.\n */\n index: number;\n /**\n * Index in the page's full row list. Equals {@link VirtualTableRow.index}\n * unless pinned rows were pulled out of the window.\n */\n sourceIndex?: number;\n /** Stable key resolved from the caller's rowKey. */\n key: string;\n /** Virtualizer item metadata; absent when virtualization is disabled. */\n virtualItem?: VirtualItem;\n}\n\n/** Wrap a constant estimate so both virtualizer modes share one shape. */\nfunction asSizeEstimator(\n estimateSize: number | ((index: number) => number)\n): (index: number) => number {\n return typeof estimateSize === \"function\" ? estimateSize : () => estimateSize;\n}\n\n/** Dataset index for ARIA / focus — the window index when pinning is off. */\nexport function rowSourceIndex(\n entry: Pick, \"index\" | \"sourceIndex\">\n): number {\n return entry.sourceIndex ?? entry.index;\n}\n\n/** Result consumed by adapters that opt into virtualized rendering. */\nexport interface TableVirtualization {\n /** Whether the returned rows represent a virtual window. */\n enabled: boolean;\n /** Rows to render: either every source row or only the virtual slice. */\n rows: readonly VirtualTableRow[];\n /** Spacer before the rendered slice. */\n paddingTop: number;\n /** Spacer after the rendered slice. */\n paddingBottom: number;\n /** Element measurement callback for virtualized rows/cards. */\n measureElement?: (node: Element | null) => void;\n /**\n * Measure a row TOGETHER with its open detail panel.\n *\n * A table cannot nest a detail panel inside the row it belongs to, so the\n * two are separate elements and the virtualizer would size the item from the\n * row alone. These refs report the pair's real height instead — which is\n * what lets row detail and virtualization be used together at all.\n */\n measureRowPair?: RowPairMeasurer;\n}\n\n/** Options for {@link useTableVirtualization}. */\nexport interface UseTableVirtualizationOptions {\n /** Source rows from the table source. */\n rows: readonly TRow[];\n /** Stable row key resolver. */\n rowKey: (row: TRow) => string;\n /** Master switch; adapters keep this optional. */\n enabled?: boolean;\n /** Estimated row/card size in px, or a per-index reader. */\n estimateSize?: number | ((index: number) => number);\n /** Extra items rendered before/after the visible window. */\n overscan?: number;\n /** Window virtualizer scroll margin, usually sticky header height. */\n scrollMargin?: number;\n /**\n * Scroll container accessor. When provided, the virtual window tracks\n * THIS element's scrolling (a `maxHeight` box) instead of the page —\n * that's how `virtualize` + `maxHeight` compose.\n */\n getScrollElement?: () => Element | null;\n /** Called when the virtual window reaches the last source row. */\n onEndReached?: () => void;\n /**\n * Whether rows can expand. With detail panels in play the window measures\n * each row together with its panel; without them the extra observers would\n * be pure cost.\n */\n expandable?: boolean;\n}\n\n/** Resolve either virtual entries or the full source rows into render entries. */\nexport function resolveVirtualRows(\n rows: readonly TRow[],\n rowKey: (row: TRow) => string,\n rowEntries?: readonly VirtualTableRow[]\n): readonly VirtualTableRow[] {\n return (\n rowEntries ??\n rows.map((row, index) => ({\n row,\n index,\n key: rowKey(row),\n }))\n );\n}\n\n/** Column span for spacer/detail/summary cells in table-based adapters. */\nexport function virtualColumnSpan(\n columnCount: number,\n hasSelection: boolean,\n hasActions: boolean,\n hasExpansion = false,\n hasReorder = false\n): number {\n return (\n columnCount +\n (hasSelection ? 1 : 0) +\n (hasActions ? 1 : 0) +\n (hasExpansion ? 1 : 0) +\n (hasReorder ? 1 : 0)\n );\n}\n\n/**\n * Headless window virtualization for adapter tables. When disabled, it returns\n * every row and no spacer/measurement data, so adapters can use the same render\n * path for virtual and non-virtual tables.\n */\nexport function useTableVirtualization({\n rows,\n rowKey,\n enabled = false,\n estimateSize = 56,\n overscan = VIRTUAL_OVERSCAN,\n scrollMargin = 0,\n getScrollElement,\n onEndReached,\n expandable = false,\n}: UseTableVirtualizationOptions): TableVirtualization {\n const elementMode = getScrollElement !== undefined;\n // Stable identity, re-keyed ONLY when the data changes: the virtualizer\n // memoises its measurements on `getItemKey`, so an inline closure (or the\n // routinely-inline `rowKey` prop) invalidated the cache every render — a\n // full O(n) rebuild with n rowKey calls per keystroke at 10k rows. The\n // extractor reads through a ref (ids for the same row are stable by\n // contract), so only a new `rows` array re-keys.\n const rowKeyRef = useRef(rowKey);\n rowKeyRef.current = rowKey;\n const getItemKey = useCallback(\n (index: number): string => {\n const row = rows[index];\n return row === undefined ? String(index) : rowKeyRef.current(row);\n },\n [rows]\n );\n // Both hooks must run unconditionally (rules of hooks); exactly one is\n // enabled. Window mode tracks the page; element mode tracks the box.\n const windowVirtualizer = useWindowVirtualizer({\n count: rows.length,\n enabled: enabled && !elementMode,\n estimateSize: asSizeEstimator(estimateSize),\n getItemKey,\n overscan,\n scrollMargin,\n });\n const elementVirtualizer = useVirtualizer({\n count: rows.length,\n enabled: enabled && elementMode,\n getScrollElement: getScrollElement ?? (() => null),\n estimateSize: asSizeEstimator(estimateSize),\n getItemKey,\n overscan,\n });\n const virtualizer = elementMode ? elementVirtualizer : windowVirtualizer;\n\n const virtualItems = virtualizer.getVirtualItems();\n const active = enabled && virtualItems.length > 0;\n const measureRowPair = useRowPairMeasurer(virtualizer, enabled && expandable);\n const materializedRows = useMemo[]>(() => {\n if (!active) {\n return rows.map((row, index) => ({\n row,\n index,\n key: rowKey(row),\n }));\n }\n return virtualItems.flatMap((virtualItem) => {\n const row = rows[virtualItem.index];\n if (row === undefined) return [];\n return [\n {\n row,\n index: virtualItem.index,\n key: rowKey(row),\n virtualItem,\n },\n ];\n });\n }, [active, rowKey, rows, virtualItems]);\n\n // `virtualItems` is a fresh array every render, so a naive effect would call\n // `onEndReached` on every render while the last row stays in view. Notify at\n // most once per row count: re-arm only when more rows actually load (the\n // count grows) or the user scrolls back off the end.\n const notifiedAtCount = useRef(-1);\n useEffect(() => {\n if (!active || rows.length === 0) return;\n const last = virtualItems.at(-1);\n const atEnd = last !== undefined && last.index >= rows.length - 1;\n if (!atEnd) {\n notifiedAtCount.current = -1;\n return;\n }\n if (notifiedAtCount.current !== rows.length) {\n notifiedAtCount.current = rows.length;\n onEndReached?.();\n }\n }, [active, onEndReached, rows.length, virtualItems]);\n\n if (!active) {\n return {\n enabled: false,\n rows: materializedRows,\n paddingTop: 0,\n paddingBottom: 0,\n };\n }\n\n // `active` guarantees a non-empty window, so the edges always exist.\n const first = virtualItems[0]!;\n const last = virtualItems.at(-1)!;\n const resolvedScrollMargin = virtualizer.options.scrollMargin ?? 0;\n const paddingTop = first.start - resolvedScrollMargin;\n const paddingBottom =\n virtualizer.getTotalSize() - (last.end - resolvedScrollMargin);\n\n return {\n enabled: true,\n rows: materializedRows,\n paddingTop: Math.max(0, paddingTop),\n paddingBottom: Math.max(0, paddingBottom),\n // A row that can expand is measured as a PAIR; one that cannot keeps the\n // virtualizer's own element measurement, which is cheaper.\n measureElement: expandable ? undefined : virtualizer.measureElement,\n measureRowPair: expandable ? measureRowPair : undefined,\n };\n}\n\n/** Result of {@link useKeyedVirtualization} — index window over a keyed list. */\nexport interface KeyedVirtualization {\n enabled: boolean;\n /** Source indices in the virtual window (or every index when disabled). */\n indices: readonly number[];\n paddingTop: number;\n paddingBottom: number;\n measureElement?: (node: Element | null) => void;\n}\n\n/**\n * Virtualize an opaque keyed list (e.g. grouped flat entries). Same window /\n * element modes as {@link useTableVirtualization}.\n */\nexport function useKeyedVirtualization(options: {\n keys: readonly string[];\n enabled?: boolean;\n estimateSize?: number | ((index: number) => number);\n overscan?: number;\n scrollMargin?: number;\n getScrollElement?: () => Element | null;\n onEndReached?: () => void;\n}): KeyedVirtualization {\n const {\n keys,\n enabled = false,\n estimateSize = 56,\n overscan = VIRTUAL_OVERSCAN,\n scrollMargin = 0,\n getScrollElement,\n onEndReached,\n } = options;\n const elementMode = getScrollElement !== undefined;\n const getItemKey = (index: number): string => keys[index] ?? String(index);\n const sizeOf = asSizeEstimator(estimateSize);\n const windowVirtualizer = useWindowVirtualizer({\n count: keys.length,\n enabled: enabled && !elementMode,\n estimateSize: sizeOf,\n getItemKey,\n overscan,\n scrollMargin,\n });\n const elementVirtualizer = useVirtualizer({\n count: keys.length,\n enabled: enabled && elementMode,\n getScrollElement: getScrollElement ?? (() => null),\n estimateSize: sizeOf,\n getItemKey,\n overscan,\n });\n const virtualizer = elementMode ? elementVirtualizer : windowVirtualizer;\n const virtualItems = virtualizer.getVirtualItems();\n const active = enabled && virtualItems.length > 0;\n\n const indices = useMemo(() => {\n if (!active) return keys.map((_, index) => index);\n return virtualItems.map((item) => item.index);\n }, [active, keys, virtualItems]);\n\n const notifiedAtCount = useRef(-1);\n useEffect(() => {\n if (!active || keys.length === 0) return;\n const last = virtualItems.at(-1);\n const atEnd = last !== undefined && last.index >= keys.length - 1;\n if (!atEnd) {\n notifiedAtCount.current = -1;\n return;\n }\n if (notifiedAtCount.current !== keys.length) {\n notifiedAtCount.current = keys.length;\n onEndReached?.();\n }\n }, [active, onEndReached, keys.length, virtualItems]);\n\n if (!active) {\n return { enabled: false, indices, paddingTop: 0, paddingBottom: 0 };\n }\n\n const first = virtualItems[0]!;\n const last = virtualItems.at(-1)!;\n const resolvedScrollMargin = virtualizer.options.scrollMargin ?? 0;\n const paddingTop = first.start - resolvedScrollMargin;\n const paddingBottom =\n virtualizer.getTotalSize() - (last.end - resolvedScrollMargin);\n\n return {\n enabled: true,\n indices,\n paddingTop: Math.max(0, paddingTop),\n paddingBottom: Math.max(0, paddingBottom),\n measureElement: virtualizer.measureElement,\n };\n}\n\n/** Slice a flat grouped model to the virtual window indices. */\nexport function windowGroupedEntries(\n entries: readonly TEntry[],\n indices: readonly number[]\n): readonly TEntry[] {\n if (indices.length === entries.length) return entries;\n return indices.flatMap((index) => {\n const entry = entries[index];\n return entry === undefined ? [] : [entry];\n });\n}\n","import type { RefObject } from \"react\";\nimport { useCallback, useLayoutEffect, useRef, useState } from \"react\";\n\n/**\n * Document Y of an element — what TanStack's window virtualizer wants as\n * `scrollMargin` so a list that is not at y=0 does not treat the page chrome\n * above it as already-scrolled rows.\n */\nexport function documentOffsetTop(el: Element): number {\n return Math.max(\n 0,\n Math.round(el.getBoundingClientRect().top + window.scrollY)\n );\n}\n\nconst LIST_SELECTOR =\n '[data-adapttable-part=\"tbody\"], [data-adapttable-part=\"cards\"]';\n\n/** The virtualized list node inside a table root, or the root itself. */\nexport function virtualListElement(root: Element | null): Element | null {\n if (!root) return null;\n return root.querySelector(LIST_SELECTOR) ?? root;\n}\n\n/** TanStack window `scrollMargin` for a mounted table root or scroll box. */\nexport function measureWindowScrollMargin(root: Element | null): number {\n const list = virtualListElement(root);\n return list === null ? 0 : documentOffsetTop(list);\n}\n\n/**\n * Keep the window virtualizer's scroll margin equal to the list's document\n * offset. Call {@link UseMeasuredWindowScrollMargin.observe} with the desktop\n * scroll-box (or any ancestor of `tbody` / `cards`); the table root is a\n * fallback so mobile cards, which never attach that box, still measure.\n */\nexport function useMeasuredWindowScrollMargin(\n enabled: boolean,\n fallbackRoot?: RefObject\n): {\n scrollMargin: number;\n observe: (node: HTMLElement | null) => void;\n} {\n const [scrollMargin, setScrollMargin] = useState(0);\n const nodeRef = useRef(null);\n\n const read = useCallback(() => {\n if (!enabled) return;\n const next = measureWindowScrollMargin(\n nodeRef.current ?? fallbackRoot?.current ?? null\n );\n setScrollMargin((prev) => (prev === next ? prev : next));\n }, [enabled, fallbackRoot]);\n\n const observe = useCallback(\n (node: HTMLElement | null) => {\n nodeRef.current = node;\n if (!enabled) return;\n if (node === null) {\n setScrollMargin(0);\n return;\n }\n read();\n },\n [enabled, read]\n );\n\n useLayoutEffect(() => {\n if (!enabled) {\n setScrollMargin(0);\n return;\n }\n read();\n if (typeof ResizeObserver === \"undefined\") return;\n const ro = new ResizeObserver(read);\n const observed = nodeRef.current ?? fallbackRoot?.current;\n if (observed) ro.observe(observed);\n ro.observe(document.documentElement);\n window.addEventListener(\"resize\", read);\n return () => {\n ro.disconnect();\n window.removeEventListener(\"resize\", read);\n };\n }, [enabled, fallbackRoot, read]);\n\n return { scrollMargin, observe };\n}\n","import type { ReactNode, RefCallback, RefObject } from \"react\";\nimport { useCallback, useEffect, useMemo, useRef } from \"react\";\n\nimport { type ConfirmHandler, defaultConfirm } from \"./actions/confirm\";\nimport {\n ACTIONS_COLUMN_KEY,\n REORDER_COLUMN_KEY,\n} from \"./columns/columnMenuModel\";\nimport {\n type ColumnGroupRecord,\n flattenColumnTree,\n} from \"./columns/columnTree\";\nimport { resolveColumns } from \"./columns/resolveColumns\";\nimport { responsiveColumns } from \"./columns/responsiveColumns\";\nimport {\n useColumnLayout,\n type UseColumnLayoutResult,\n} from \"./columns/useColumnLayout\";\nimport { DEFAULT_CARD_SIZE_PX, DEFAULT_ROW_SIZE_PX } from \"./constants\";\nimport { useBatchEditing } from \"./editing/batchEditing\";\nimport { useDirtyCells } from \"./editing/dirtyCells\";\nimport type { EditableCellEditing } from \"./editing/editableCellController\";\nimport { useEditConflict } from \"./editing/editConflict\";\nimport type { EditHistoryState } from \"./editing/editHistory\";\nimport { useEditLifecycle } from \"./editing/editingEvents\";\nimport { useRowEditing } from \"./editing/rowEditing\";\nimport { useCellSaveState } from \"./editing/saveState\";\nimport { useCellEditing } from \"./editing/useCellEditing\";\nimport { useEditValidation } from \"./editing/validation\";\nimport type { ExportStatus } from \"./export/useExportHandler\";\nimport {\n type ActiveFilterChip,\n mergeFilterChips,\n resolveActiveFilterCount,\n} from \"./filters/useActiveFilterChips\";\nimport { useFilterTreeChips } from \"./filters/useFilterTreeChips\";\nimport {\n formatGroupBy,\n type GroupByInput,\n parseGroupBy,\n} from \"./grouping/groupKeys\";\nimport {\n buildGroupedFlatModel,\n type GroupAggregatesFn,\n type GroupedFlatEntry,\n} from \"./grouping/groupRows\";\nimport {\n type GroupCollapseState,\n useGroupCollapse,\n} from \"./grouping/useGroupCollapse\";\nimport { useGroupPaging } from \"./grouping/useGroupPaging\";\nimport { useEventCallback } from \"./hooks/useEventCallback\";\nimport { useInfiniteScroll } from \"./hooks/useInfiniteScroll\";\nimport { useIsMobile } from \"./hooks/useIsMobile\";\nimport { useScrollToTableTop } from \"./hooks/useScrollToTableTop\";\nimport { useElementWidth } from \"./layout/useElementWidth\";\nimport type { BaseDataTableProps, ToolbarSlots } from \"./props\";\nimport { insertExtraRows } from \"./rows/extraRows\";\nimport {\n configureIncrementalView,\n incrementalViewOf,\n} from \"./rows/incremental\";\nimport { type RowMutationsState, useRowMutations } from \"./rows/rowMutations\";\nimport {\n partitionPinnedRows,\n type RowPinLabels,\n type RowPinningState,\n type RowPinState,\n useRowPinning,\n} from \"./rows/rowPinning\";\nimport { type RowReorderState, useRowReorder } from \"./rows/rowReorder\";\nimport { estimateFromRowHeight } from \"./rows/rowStyle\";\nimport {\n type RowExpansionState,\n useRowExpansion,\n} from \"./rows/useRowExpansion\";\nimport type { SelectionState } from \"./selection/useSelection\";\nimport { serverGroupEntries } from \"./source/queryGroups\";\nimport type { TableSource } from \"./source/TableSource\";\nimport { type TableErrorState, tableErrorState } from \"./state/errorState\";\nimport {\n collectFeatureNotices,\n type FeatureNotice,\n} from \"./state/featureNotices\";\n\nexport type { FeatureNotice, FeatureNoticeKind } from \"./state/featureNotices\";\nimport { nestedTableDetail } from \"./tree/nestedTable\";\nimport {\n buildTreeEntries,\n treeColumnKey,\n type TreeEntry,\n} from \"./tree/treeRows\";\nimport { useLazyChildren } from \"./tree/useLazyChildren\";\nimport {\n type TreeExpansionState,\n useTreeExpansion,\n} from \"./tree/useTreeExpansion\";\nimport type {\n BulkAction,\n ColumnDef,\n RowAction,\n SortByOption,\n TableLabels,\n} from \"./types\";\nimport {\n useDataTable,\n type UseDataTableResult,\n} from \"./useDataTable/useDataTable\";\nimport { devWarn } from \"./utils/devWarn\";\nimport {\n type TableVirtualization,\n useKeyedVirtualization,\n useTableVirtualization,\n windowGroupedEntries,\n} from \"./virtual/useTableVirtualization\";\nimport { useMeasuredWindowScrollMargin } from \"./virtual/windowScrollMargin\";\n\n/**\n * The shared prop surface every adapter's toolbar sub-component needs.\n * Adapters render kit-specific markup from this; extracting it keeps the\n * identical shape from being re-declared (and flagged as duplication) in\n * each adapter.\n *\n * @typeParam TRow - The row type.\n */\nexport interface ToolbarChromeProps {\n /** The headless table state + prop-getters. */\n table: UseDataTableResult;\n /** Render the search input (default `true`). */\n searchable?: boolean;\n /** Placeholder for the search input. */\n searchPlaceholder?: string;\n /** Options for an explicit sort-by control. */\n sortByOptions?: SortByOption[];\n /** Extra caller-supplied toolbar content, in the middle region. */\n toolbar?: ReactNode;\n /** Caller-supplied content for the two ends of the toolbar. */\n toolbarSlots?: ToolbarSlots;\n /**\n * Put the last edit back. Set only when the host asked for the buttons\n * (`undoRedoButtons`) AND `editHistory` is armed, so an adapter renders\n * the pair on presence and never has to check two things.\n */\n onUndo?: () => void;\n /** Do the last undone edit again. Present with {@link onUndo}. */\n onRedo?: () => void;\n /**\n * Whether there is anything to undo. The button is disabled, not\n * hidden — a control that vanishes moves the ones beside it, and a\n * toolbar that reflows while someone is working is worse than a button\n * that is briefly unavailable.\n */\n canUndo?: boolean;\n /** Whether there is anything to redo. */\n canRedo?: boolean;\n /** `labels.undoEdit` — the undo button's caption. */\n undoLabel?: string;\n /** `labels.redoEdit` — the redo button's caption. */\n redoLabel?: string;\n /**\n * Open the print dialog. Set only when the host asked for the button\n * (`printButton`) AND wired `onPrint`, so an adapter renders on presence\n * and never has to check two things.\n */\n onPrint?: () => void;\n /** `labels.print` — the print button's caption. */\n printLabel?: string;\n /** The density the table is rendering, when the chooser is shown. */\n density?: \"comfortable\" | \"compact\";\n /** Change it. Present iff the host asked for the chooser. */\n onDensityChange?: (next: \"comfortable\" | \"compact\") => void;\n /** Toggle fullscreen. Present iff asked for AND the browser allows it. */\n onToggleFullscreen?: () => void;\n /** Whether the table is fullscreen right now, for the button's state. */\n isFullscreen?: boolean;\n /** Whether a filters affordance should render. */\n hasFilters: boolean;\n /** Number shown on the filters badge. */\n activeFilterCount: number;\n /** Whether the filter container is open (drives `aria-expanded`). */\n filtersOpen: boolean;\n /** Toggle the filter container (popover and drawer alike). */\n onToggleFilters: () => void;\n /**\n * Bind to the trigger's `onPointerDown` (see\n * {@link useFilterTriggerToggle}) so a click on the open trigger CLOSES\n * the popover instead of racing the kit's outside-close and reopening.\n */\n onFiltersTriggerPointerDown?: () => void;\n /** Whether to show the rows-per-page control (infinite mode). */\n showRowsPerPage: boolean;\n /**\n * Built saved-views menu node, when the `savedViews` prop opts in. Renders\n * ahead of {@link columnMenu} so every adapter's toolbar reads\n * Filters · Saved views · Columns · Export CSV.\n */\n savedViewsMenu?: ReactNode;\n /** Built column-menu node, when `enableColumnMenu` is set. */\n columnMenu?: ReactNode;\n /**\n * When set, render the Export CSV toolbar button and call this on click.\n * Built by {@link makeExportCsvHandler} from the `exportCsv` prop.\n */\n onExportCsv?: () => void;\n /**\n * True while a host-handled export (`exportCsv.request`) is still running.\n *\n * Adapters disable the Export button and mark it busy, so the same export\n * cannot be started twice and the user can see that something is happening.\n * Always false for the built-in browser export, which is synchronous.\n */\n exportBusy?: boolean;\n /**\n * What the last export did — `\"idle\"`, `\"busy\"`, `\"done\"` or `\"failed\"` —\n * for a kit whose button shows more than a spinner.\n */\n exportStatus?: ExportStatus;\n /**\n * Live-region text for the last export's outcome, empty until there is one.\n * Adapters render it through `ExportAnnouncer` beside the button: a download\n * is silent, so without it a screen-reader user cannot tell a finished export\n * from a failed one.\n */\n exportAnnouncement?: string;\n /**\n * The export button's caption, naming the format it produces — CSV by\n * default, the writer's format otherwise, localized either way. Adapters\n * render this rather than `labels.exportCsv`, so a button never names a file\n * the user is not getting.\n */\n exportLabel?: string;\n /**\n * When set, render an Add-row control and call this on click. Present iff\n * the host wired `onAddRow`, so the toolbar needs no second guard.\n */\n onAddRow?: () => void;\n /** The Add control's caption, already localized. */\n addRowLabel?: string;\n /** Text direction, for adapters whose toolbar needs explicit RTL hints. */\n dir?: \"ltr\" | \"rtl\";\n}\n\n/**\n * The shared prop surface every adapter's bulk-action bar needs. Extracted\n * so the identical shape isn't re-declared (and flagged as duplication) in\n * each adapter's chrome.\n */\nexport interface BulkBarChromeProps {\n /** Current selection state. */\n selection: SelectionState;\n /**\n * Total rows in the filtered set — drives the \"select all N matching\"\n * banner when a full page is selected and more rows match elsewhere.\n */\n total: number;\n /** Caller-supplied bulk actions. */\n bulkActions: BulkAction[];\n /** Confirmation handler for actions that declare a `confirm` block. */\n confirm: ConfirmHandler;\n /** Resolved labels. */\n labels: Required;\n}\n\n/**\n * Which body region a `DataTable` should render. Named `TableBodyRegion`\n * (not `TableBody`) so it never collides with MUI's `TableBody` component\n * in consumer imports.\n */\nexport type TableBodyRegion = \"skeleton\" | \"empty\" | \"mobile\" | \"desktop\";\n\n/** The shared, UI-agnostic orchestration result for an adapter table. */\nexport interface TableChrome {\n /**\n * The source as the VIEW sees it. Identical to the caller's source —\n * except with grouping armed, where the table renders the full filtered\n * set and this facade presents that set (full rows, one page, matching\n * total) so footer numbers, select-all scope and page-scope CSV export\n * agree with the screen. Adapters read THIS, never the raw source.\n */\n source: TableSource;\n /** The headless table state + prop-getters. */\n table: UseDataTableResult;\n /** Resolved mobile layout flag. */\n isMobile: boolean;\n /** Resolved confirmation handler. */\n confirm: ConfirmHandler;\n /** Row id extractor (selection id, falling back to rowKey). */\n getRowId: (row: TRow) => string;\n /** Derived chips: label-driven merged with caller `extraChips`. */\n mergedChips: readonly ActiveFilterChip[];\n /** Active filter count (override, or merged chip count). */\n activeFilterCount: number;\n /** Whether the resolved pagination mode is `\"paged\"`. */\n isPaged: boolean;\n /**\n * The table root. Owned here so the width that drives progressive column\n * hiding is measured on the table itself, in both wiring paths.\n */\n rootRef: RefObject;\n /** Column keys progressive hiding gave up at the current width. */\n droppedColumns: readonly string[];\n /** Which body region to render. */\n body: TableBodyRegion;\n /**\n * The load failure to show in place of the body, or `undefined` when the\n * source is fine. Derived here so every adapter offers a retry on exactly\n * the same terms — one the source can actually perform.\n */\n errorState?: TableErrorState;\n /**\n * Why the body is empty: `\"noResults\"` when an active search/filter\n * produced zero rows (offer a clear-filters CTA), `\"noData\"` when the\n * source itself is empty. Only meaningful while `body === \"empty\"`.\n */\n emptyVariant: \"noData\" | \"noResults\";\n /**\n * A background refresh is in flight (`isFetching` without `isLoading`):\n * rows on screen are potentially stale. Adapters show a subtle,\n * non-blocking indicator (thin progress bar / `aria-busy`).\n */\n isRefreshing: boolean;\n /**\n * Clear-filters handler: the caller's `onClearFilters`, falling back to\n * `source.clearExtras` — so chips, the drawer and the no-results CTA can\n * always offer a working \"clear\".\n */\n clearFilters: () => void;\n /**\n * Row-detail bundle — present iff `renderRowDetail` is set, so ONE guard\n * narrows both the renderer and the expansion state (no correlated\n * optionals to re-check).\n */\n detail?: {\n /** The caller's detail-panel renderer. */\n render: (row: TRow) => ReactNode;\n /** Expansion state for the chevrons. */\n expansion: RowExpansionState;\n };\n /**\n * Inline editing bundle — present iff either channel is set (`onCellEdit`\n * for per-cell commits, `rowEditing` + `onRowEdit` for row-level ones), so\n * ONE guard narrows the host channel, the state machine, validation, save\n * state, dirty marks and row mode. Pass neither and editing stays fully\n * dormant: no UI, no keyboard.\n */\n editing?: EditableCellEditing;\n /**\n * Adding, duplicating and deleting rows. Always present: `canAdd` says\n * whether the toolbar's Add control renders, and the duplicate and delete\n * actions are already folded into {@link TableChrome.rowActions}, so an\n * adapter that renders row actions gets both for free.\n */\n rowMutations: RowMutationsState;\n /**\n * The row actions to render — the host's, plus duplicate and delete when\n * those are wired, and `undefined` when the reader hid the actions column.\n * Adapters read THIS rather than the `rowActions` prop.\n */\n rowActions?: RowAction[];\n /**\n * Whether an actions column exists at all, hidden or not — what the column\n * menu offers, and the one figure a hidden column must not change.\n */\n hasRowActions: boolean;\n /**\n * Whether a reorder column exists at all, hidden or not — what the column\n * menu offers. False when grouping or a tree is armed (reorder is refused).\n */\n hasRowReorder: boolean;\n /**\n * Headless row-reorder state. Present iff the host passed `onRowReorder`,\n * grouping/tree are off, and the column is visible. Adapters read THIS.\n */\n rowReorder?: RowReorderState;\n /**\n * Headless row-pin state. Present iff the host passed `pinnedRowIds` or\n * `onPinnedRowIdsChange`, and grouping/tree are off.\n */\n rowPinning?: RowPinningState;\n /**\n * Tree bundle — present iff the host declared a hierarchy (`getChildren` or\n * `getParentId`). A tree and a grouping are different models and can both be\n * dormant; a table that arms both renders the tree, since the rows' own\n * shape outranks a derived one.\n */\n tree?: {\n /** The flattened hierarchy, in render order. */\n entries: readonly TreeEntry[];\n /** Which nodes are open. */\n expansion: TreeExpansionState;\n /** Which column carries the chevron and the indent. */\n columnKey?: string;\n };\n /**\n * Row-grouping bundle — present iff an effective `groupBy` is set AND the\n * source can supply a full filtered set (`allFilteredRows`). Omit\n * `groupBy` and grouping stays fully dormant (package DNA: opt-in).\n */\n grouping?: {\n /** The grouping keys in order — one entry for a flat group, more for nested. */\n groupBy: readonly string[];\n collapsed: GroupCollapseState;\n aggregates?: GroupAggregatesFn;\n /** Flat group-header + leaf entries for adapters to render. */\n entries: readonly GroupedFlatEntry[];\n setGroupBy: (key: GroupByInput) => void;\n /** Open every group. */\n expandAll: () => void;\n /** Close every group, at every level. */\n collapseAll: () => void;\n /**\n * Show the tree down to `depth` and no further — `0` leaves only the\n * outermost headers, `1` opens the first level inside them.\n */\n collapseToDepth: (depth: number) => void;\n /** Reveal the next page of groups, or of one group's rows. */\n showMore: (entry: { scope: \"groups\" | \"rows\"; groupKey?: string }) => void;\n };\n /**\n * The rows the editing layer must treat as present: the grouped leaf set\n * (in render order) while grouping renders the full filtered set, the\n * page slice otherwise. Adapters pass THIS — never `source.rows` — as the\n * `rows` context for editable cells, so an edit on a row outside the\n * current page slice survives and Tab-advance follows the rendered order.\n */\n editingRows: readonly TRow[];\n /** Whether the paged footer should render. */\n showFooter: boolean;\n /** User column-layout state + mutators (visibility, order, …). */\n columnLayout: UseColumnLayoutResult;\n /** Tree groups for the declared columns — collapse options, header align. */\n columnGroups: ReadonlyMap>;\n /** All declared columns (pre layout/device filtering) for the column menu. */\n allColumns: ColumnDef[];\n /**\n * Opted-in features that cannot run. Empty when everything the host\n * asked for can. Adapters show these on the status bar (when it is\n * on) and as `data-adapttable-notices` on the root; the matching\n * control already looks off, disabled, or one-page.\n */\n featureNotices: readonly FeatureNotice[];\n}\n\n/**\n * Run the shared orchestration every adapter `` needs: resolve\n * the layout + confirm handler, build the headless table, merge filter\n * chips, compute the active-filter count, and decide which body region and\n * footer to show. Adapters then render their kit-specific markup from this.\n *\n * @typeParam TRow - The row type.\n * @param props - The adapter's {@link BaseDataTableProps}.\n * @returns The {@link TableChrome} orchestration result.\n */\n/**\n * The undo/redo half of a toolbar's props, or nothing at all.\n *\n * Two conditions have to hold — the host asked for the buttons, and there\n * is a history for them to drive — and resolving both here means an\n * adapter renders the pair on `onUndo` being present and never has to\n * know that `editHistory` exists. Off, the object is empty and the props\n * are absent, which is what keeps an opted-out toolbar identical.\n */\n/**\n * The density chooser and the fullscreen toggle, or nothing.\n *\n * Both resolve to present-or-absent rather than present-and-disabled, so an\n * adapter renders on presence. The fullscreen half folds in whether the\n * browser will allow it at all: a toggle that cannot work is worse than no\n * toggle, and an embedded webview is a real place where it cannot.\n */\nexport interface ViewControlsToolbar {\n density?: \"comfortable\" | \"compact\";\n onDensityChange?: (next: \"comfortable\" | \"compact\") => void;\n onToggleFullscreen?: () => void;\n isFullscreen?: boolean;\n}\n\nexport function viewControlsToolbar(\n props: {\n densityChooser?: boolean;\n density?: \"comfortable\" | \"compact\";\n onDensityChange?: (next: \"comfortable\" | \"compact\") => void;\n fullscreen?: boolean;\n },\n fullscreen: { supported: boolean; active: boolean; toggle: () => void }\n): ViewControlsToolbar {\n return {\n ...(props.densityChooser === true\n ? {\n density: props.density ?? \"comfortable\",\n onDensityChange: props.onDensityChange,\n }\n : {}),\n ...(props.fullscreen === true && fullscreen.supported\n ? {\n onToggleFullscreen: fullscreen.toggle,\n isFullscreen: fullscreen.active,\n }\n : {}),\n };\n}\n\nexport function undoRedoToolbar(\n wanted: boolean | undefined,\n history: EditHistoryState,\n labels: TableLabels\n): Partial> {\n if (wanted !== true || !history.enabled) return {};\n return {\n onUndo: history.undo,\n onRedo: history.redo,\n canUndo: history.canUndo,\n canRedo: history.canRedo,\n undoLabel: labels.undoEdit,\n redoLabel: labels.redoEdit,\n };\n}\n\n/** The print button's half of a toolbar's props. */\nexport interface PrintToolbar {\n onPrint?: () => void;\n printLabel?: string;\n}\n\n/**\n * The print button's half of a toolbar's props, or nothing at all.\n *\n * Two conditions again — the host asked for the button, and there is a handler\n * for it to call — resolved here so an adapter renders on `onPrint` being\n * present. `onPrint` alone stays what it has always been: a palette command.\n *\n * Not generic, unlike {@link undoRedoToolbar}: neither prop mentions the row\n * type, and a `Partial>` return with no `TRow` in the\n * arguments infers `unknown` and widens the whole spread at every call site.\n */\nexport function printToolbar(\n wanted: boolean | undefined,\n onPrint: (() => void) | undefined,\n labels: TableLabels\n): PrintToolbar {\n if (wanted !== true || onPrint === undefined) return {};\n return { onPrint, printLabel: labels.print };\n}\n\nexport function useTableChrome(\n props: BaseDataTableProps\n): TableChrome {\n const {\n source,\n columns,\n rowKey,\n tableLabel,\n labels,\n dir,\n forceMobile,\n mobileBreakpoint,\n mobileIdentityColumns,\n onRowsChange,\n bulkActions,\n selectionGetId,\n selectedIds: selectedIdsProp,\n onSelectionChange,\n filterLabels,\n onClearFilters,\n extraChips,\n activeFilterCount: activeFilterCountProp,\n confirm: confirmProp,\n columnLayout: columnLayoutProp,\n onColumnLayoutChange,\n defaultColumnLayout,\n groupAggregates,\n groupFooters,\n groupSort,\n groupFilter,\n groupPageSize,\n groupRowPageSize,\n onGroupLoadMore,\n extraRows,\n } = props;\n\n const autoMobile = useIsMobile(mobileBreakpoint);\n const isMobile = forceMobile ?? autoMobile;\n const confirm = confirmProp ?? defaultConfirm;\n\n // Declarative defaults (auto headers, dot-path accessors) resolve once\n // here, so the layout, the column menu and the table all see them.\n const flattened = useMemo(() => flattenColumnTree(columns), [columns]);\n const resolvedColumns = useMemo(\n () => resolveColumns(flattened.leaves, props.locale),\n [flattened.leaves, props.locale]\n );\n\n // User column layout (hide/order/…) applied on top of the declared columns,\n // before device filtering inside useDataTable. The menu uses `allColumns`.\n // The chrome owns the root ref so both wiring paths measure the same\n // element: the width that decides progressive hiding has to be the table's\n // own, not the window's.\n const rootRef = useRef(null);\n const rootWidth = useElementWidth(rootRef);\n\n const columnLayout = useColumnLayout({\n columns: resolvedColumns,\n layout: columnLayoutProp,\n onLayoutChange: onColumnLayoutChange,\n defaultColumnLayout,\n collapsibleColumnGroups: props.collapsibleColumnGroups === true,\n columnGroups: flattened.groups,\n });\n\n // Effective groupBy: prop wins when provided (including `null` to force\n // off); otherwise the URL/source value. Empty string is treated as unset.\n //\n // With grouping armed the table is a FULL-SET view: grouped mode renders\n // every filtered row, so the source the chrome reasons about presents\n // that same set — footer numbers, select-all scope and page-scope CSV\n // export all describe exactly what is on screen instead of the page\n // slice. Mutators pass through untouched; the overlay disappears (and\n // real pagination resumes) the moment grouping is cleared.\n const requestedGroupBy =\n props.groupBy === undefined ? source.groupBy : props.groupBy;\n const groupByKeys = useMemo(\n () => parseGroupBy(requestedGroupBy),\n [requestedGroupBy]\n );\n // A server tier that answered `query.groupBy` sends its own groups; a\n // frontend tier hands over the whole filtered set to group locally. Either\n // way the adapters see the same entries.\n const serverGroups = source.groups;\n const groupingArmed = Boolean(\n groupByKeys.length > 0 && (source.allFilteredRows ?? serverGroups)\n );\n const viewSource = useMemo>(() => {\n if (!groupingArmed || !source.allFilteredRows) return source;\n const all = source.allFilteredRows;\n return {\n ...source,\n rows: all,\n page: 1,\n limit: Math.max(all.length, 1),\n total: all.length,\n hasNextPage: false,\n isFetchingNextPage: false,\n };\n }, [groupingArmed, source]);\n\n // Progressive hiding sits between the user's own hidden set and what is\n // rendered: it is a fact about the viewport, not a choice the user made,\n // so it never reaches the layout state, the URL or a saved view.\n const responsive = useMemo(\n () =>\n responsiveColumns({\n columns: columnLayout.visibleColumns,\n available: rootWidth,\n widths: columnLayout.state.widths,\n }),\n [columnLayout.visibleColumns, columnLayout.state.widths, rootWidth]\n );\n\n const table = useDataTable({\n source: viewSource,\n columns: responsive.columns,\n rowKey,\n tableLabel,\n labels,\n dir,\n forceMobile: isMobile,\n mobileIdentityColumns,\n bulkActions,\n selectionGetId,\n selectedIds: selectedIdsProp,\n onSelectedIdsChange: onSelectionChange,\n filterLabels,\n multiSort: props.multiSort,\n searchDebounceMs: props.searchDebounceMs,\n locale: props.locale,\n fitColumns: props.fitColumns,\n // The user's dragged widths win over any share: they said what they wanted.\n columnWidths: columnLayout.state.widths,\n });\n\n useEffect(() => {\n onRowsChange?.(table.rows);\n }, [onRowsChange, table.rows]);\n\n // Selection observer (uncontrolled only): the Set identity only changes\n // when the selection does, so this fires exactly once per user-visible\n // change (including automatic resets and the documented mount fire with\n // the empty selection). The handler is read through a ref-latch — the\n // documented inline-arrow usage is a fresh identity every render, and\n // keying the effect on it loops forever when the handler stores the ids\n // in state. In the CONTROLLED mode the parent already receives change\n // requests synchronously through useSelection's onChange — echoing them\n // here would double-fire (and feed loops).\n const controlledSelection = selectedIdsProp !== undefined;\n const selectedIds = table.selection?.selectedIds;\n const notifySelectionChange = useEventCallback((ids: string[]) => {\n onSelectionChange?.(ids);\n });\n useEffect(() => {\n if (!controlledSelection && selectedIds) {\n notifySelectionChange([...selectedIds]);\n }\n }, [controlledSelection, selectedIds, notifySelectionChange]);\n\n const treeChips = useFilterTreeChips({\n tree: source.filterTree,\n defs: props.filterDefs ?? [],\n labels: table.labels,\n setFilterTree: source.setFilterTree,\n });\n const mergedChips = useMemo(\n () =>\n mergeFilterChips(\n mergeFilterChips(table.filterChips, extraChips),\n treeChips\n ),\n [table.filterChips, extraChips, treeChips]\n );\n\n const activeFilterCount = resolveActiveFilterCount(\n activeFilterCountProp,\n mergedChips.length\n );\n\n const isPaged = source.paginationMode === \"paged\";\n\n const errorState = tableErrorState(viewSource);\n let body: TableBodyRegion;\n if (viewSource.isLoading && viewSource.rows.length === 0) body = \"skeleton\";\n else if (table.isEmpty) body = \"empty\";\n else if (isMobile) body = \"mobile\";\n else body = \"desktop\";\n\n // Zero rows under an active search/filter is \"nothing MATCHED\", not\n // \"nothing exists\" — the empty state should say so and offer a clear.\n const emptyVariant =\n activeFilterCount > 0 || source.search !== \"\" ? \"noResults\" : \"noData\";\n\n // `isFetchingNextPage` is load-more, not a refresh of what's on screen.\n const isRefreshing = Boolean(\n source.isFetching && !source.isLoading && !source.isFetchingNextPage\n );\n\n // `onClearFilters` is a pure NOTIFICATION: the chrome always performs\n // the clear itself, then tells the host. (It used to REPLACE the clear,\n // so a logging handler silently broke the button — take full control\n // via `source.clearExtras` instead.)\n const clearFilters = useCallback(() => {\n source.clearExtras();\n source.setFilterTree?.(undefined);\n onClearFilters?.();\n }, [onClearFilters, source]);\n\n // Hooks run unconditionally; the state is simply unused (and unexposed)\n // when the caller renders no row details.\n const expansionState = useRowExpansion(props.defaultExpandedRowIds);\n // A declared nested table IS the detail panel; a row without one falls back\n // to whatever the host builds itself.\n const { nestedTable, density, labels: hostLabels } = props;\n const hostRenderRowDetail = props.renderRowDetail;\n const renderRowDetail = useMemo(\n () =>\n nestedTableDetail({\n nestedTable,\n renderRowDetail: hostRenderRowDetail,\n parent: { density, labels: hostLabels },\n }),\n [nestedTable, hostRenderRowDetail, density, hostLabels]\n );\n const detail = useMemo(\n () =>\n renderRowDetail\n ? { render: renderRowDetail, expansion: expansionState }\n : undefined,\n [renderRowDetail, expansionState]\n );\n\n // Same opt-in pattern as `detail`: the hook always runs (Rules of Hooks),\n // but `editing` is only exposed when the host passes `onCellEdit`.\n const lifecycle = useEditLifecycle({\n onEditStart: props.onEditStart,\n onEditCancel: props.onEditCancel,\n onEditCommit: props.onEditCommit,\n onValidationFail: props.onValidationFail,\n onEditError: props.onEditError,\n });\n const cellEditingState = useCellEditing({\n onEditStart: lifecycle.onEditStart,\n onEditCancel: lifecycle.onEditCancel,\n });\n const conflict = useEditConflict();\n const onCellEdit = props.onCellEdit;\n // Validation gates the commit and nothing else; it runs whether or not any\n // validator exists, and stays inert until one rejects something.\n const validation = useEditValidation({\n validateRow: props.validateRow,\n applyEdit: props.applyEdit,\n });\n // A host whose `onCellEdit` returns a promise gets a saving cell for free;\n // one that saves synchronously never pays a render for it.\n const saving = useCellSaveState({\n onRollback: props.onEditRollback,\n formatError: props.formatEditError,\n onEditError: lifecycle.onEditError,\n });\n // A mark is a claim about what the server has agreed to, so it is the host's\n // to ask for: `dirtyIndicators` on, and `confirmEdits` to say when a value has\n // settled (a refetch agreed, a websocket echoed it back).\n const dirty = useDirtyCells({ enabled: props.dirtyIndicators === true });\n // Row mode changes the commit unit from a cell to a row, so it takes both the\n // flag and a channel: an Edit control with nowhere to send the patch would be\n // a mode the reader can enter and never leave usefully.\n const rowModeArmed =\n props.rowEditing === true && props.onRowEdit !== undefined;\n const rowEditing = useRowEditing({\n enabled: rowModeArmed,\n columns: resolvedColumns,\n onRowEdit: props.onRowEdit,\n onEditStart: lifecycle.onEditStart,\n onEditCancel: lifecycle.onEditCancel,\n onEditCommit: lifecycle.onEditCommit,\n });\n // Either channel arms the bundle: a host that wants row-level commits only\n // never passes `onCellEdit`, and its cells stay display-only until a reader\n // opens the row.\n // Batch mode is the third commit unit: many rows held, one write at the end.\n const batchArmed =\n props.batchEditing === true && props.onBatchEdit !== undefined;\n const batch = useBatchEditing({\n enabled: batchArmed,\n columns: resolvedColumns,\n onBatchEdit: props.onBatchEdit,\n onEditStart: lifecycle.onEditStart,\n onEditCancel: lifecycle.onEditCancel,\n onEditCommit: lifecycle.onEditCommit,\n });\n const editingArmed = onCellEdit !== undefined || rowModeArmed || batchArmed;\n const editing = useMemo(\n () =>\n editingArmed\n ? {\n onCellEdit,\n state: cellEditingState,\n validation,\n saving,\n dirty,\n // Only when the host armed row mode: carried unconditionally, every\n // table with cell editing would grow an \"Edit row\" control.\n rowEditing: rowModeArmed ? rowEditing : undefined,\n batch: batchArmed ? batch : undefined,\n lifecycle,\n conflict,\n conflictLabels: {\n message: table.labels.editConflict,\n keepMine: table.labels.keepMine,\n takeTheirs: table.labels.takeTheirs,\n theirsValue: table.labels.theirsValue,\n },\n }\n : undefined,\n [\n editingArmed,\n onCellEdit,\n cellEditingState,\n validation,\n saving,\n dirty,\n rowModeArmed,\n rowEditing,\n batchArmed,\n batch,\n lifecycle,\n conflict,\n table.labels.editConflict,\n table.labels.keepMine,\n table.labels.takeTheirs,\n table.labels.theirsValue,\n ]\n );\n // Half-configured editing is a silent trap: `editable: true` on a column\n // does NOTHING without the table-level change channel. Say so in dev.\n const hasEditableColumn = resolvedColumns.some((column) => column.editable);\n useEffect(() => {\n if (!hasEditableColumn || onCellEdit) return;\n devWarn(\n \"columns declare `editable` but no `onCellEdit` handler is set — cell editing stays inert. Pass `onCellEdit` on the table to enable it.\"\n );\n }, [hasEditableColumn, onCellEdit]);\n\n // If the active row leaves the rendered set, drop the draft without\n // committing — the host never receives a stale edit. The check runs\n // against `editingRows` (defined after grouping below): the grouped body\n // renders the FULL filtered leaf set, so validating against the page\n // slice would silently kill edits on every off-page row (each group's\n // rows beyond page 1 froze as display-only).\n\n const groupCollapse = useGroupCollapse({\n collapsedGroupIds: props.collapsedGroupIds,\n onCollapsedGroupIdsChange: props.onCollapsedGroupIdsChange,\n });\n\n useEffect(() => {\n if (groupByKeys.length === 0) return;\n if (source.allFilteredRows || serverGroups) return;\n devWarn(\n \"groupBy is only supported on the frontend data tier (in-memory rows with allFilteredRows). Server-paginated sources cannot regroup a full result set; grouping is ignored.\"\n );\n }, [groupByKeys, source.allFilteredRows, serverGroups]);\n\n // Depend on the two stable members, never the whole props/source objects\n // (both fresh every render) — keying on them rebuilt the grouping bundle,\n // and the O(filtered rows) grouped flat model behind it, on every\n // keystroke.\n const { onGroupByChange } = props;\n const { setGroupBy: sourceSetGroupBy } = source;\n // `onGroupByChange` is a pure NOTIFICATION: the chrome always applies\n // the grouping change itself, then tells the host. (It used to REPLACE\n // the mutator, so a logging handler silently broke grouping — take full\n // control via `source.setGroupBy` instead.)\n const setGroupBy = useCallback(\n (key: GroupByInput) => {\n sourceSetGroupBy(formatGroupBy(key));\n onGroupByChange?.(parseGroupBy(key));\n },\n [onGroupByChange, sourceSetGroupBy]\n );\n\n const getRowId = selectionGetId ?? rowKey;\n const groupPaging = useGroupPaging();\n // Adding, duplicating and deleting: the table asks, the host does. Nothing\n // renders until the handler that performs it is wired.\n const rowMutations = useRowMutations({\n labels: table.labels,\n onAddRow: props.onAddRow,\n onDuplicateRow: props.onDuplicateRow,\n onDeleteRow: props.onDeleteRow,\n confirmDeleteRow: props.confirmDeleteRow,\n });\n // The one row-action list every renderer reads. Duplicate and delete come\n // after the host's own, so a delete stays last where a destructive action\n // belongs — and the whole column hides and end-pins as one, because the\n // layout state cannot tell a synthesized action from a declared one.\n const mutationActions = rowMutations.actions;\n const hasRowActions =\n (props.rowActions?.length ?? 0) + mutationActions.length > 0;\n const actionsHidden = columnLayout.isHidden(ACTIONS_COLUMN_KEY);\n const hostRowActions = props.rowActions;\n const rowActions = useMemo[] | undefined>(() => {\n if (actionsHidden || !hasRowActions) return undefined;\n if (mutationActions.length === 0) return hostRowActions;\n return [...(hostRowActions ?? []), ...mutationActions];\n }, [actionsHidden, hasRowActions, hostRowActions, mutationActions]);\n\n // A declared hierarchy is a fact about the rows, so it is armed by the shape\n // the host gave rather than by a mode flag.\n const treeExpansion = useTreeExpansion({\n expandedIds: props.expandedIds,\n onExpandedIdsChange: props.onExpandedIdsChange,\n });\n const treeShaped =\n props.getChildren !== undefined || props.getParentId !== undefined;\n // A branch the browser has not fetched yet: the host says there is more, the\n // rows are not there, so opening it is a request rather than a reveal.\n const lazyChildren = useLazyChildren({\n onLoadChildren: props.onLoadChildren,\n hasLoadedChildren: (row) => hasLoadedChildren(row, source.rows, props),\n getRowId,\n });\n // The walked hierarchy, before any lazy-loading chrome is layered on it: the\n // entries are what a toggle looks a row up in, since a nested child never\n // appears in `source.rows` at all.\n const treeEntries = useMemo(\n () =>\n treeShaped\n ? buildTreeEntries({\n rows: source.rows,\n getRowId,\n expandedIds: treeExpansion.expandedIds,\n loadingIds: lazyChildren.loadingIds,\n getChildren: props.getChildren,\n getParentId: props.getParentId,\n hasChildren: props.hasChildren,\n })\n : undefined,\n [\n treeShaped,\n source.rows,\n getRowId,\n treeExpansion.expandedIds,\n lazyChildren.loadingIds,\n props.getChildren,\n props.getParentId,\n props.hasChildren,\n ]\n );\n /**\n * The same hierarchy with every node open.\n *\n * An export scoped to \"all\" means all the data, and a folded folder is a\n * display state — the rows inside it matched the filters just the same. The\n * rendered entries stop at every collapsed node, so exporting from them\n * silently drops whole subtrees. This is what the export reads instead.\n */\n const treeExportEntries = useMemo(\n () =>\n treeEntries\n ? buildTreeEntries({\n rows: source.rows,\n getRowId,\n // Every node id: a rendered entry carries its whole subtree in\n // `descendantIds` whether or not it is open, and roots are always\n // rendered — so the walked entries name every node in the tree.\n expandedIds: new Set(\n treeEntries.flatMap((entry) => [\n entry.key,\n ...entry.descendantIds,\n ])\n ),\n getChildren: props.getChildren,\n getParentId: props.getParentId,\n hasChildren: props.hasChildren,\n })\n : undefined,\n [\n treeEntries,\n source.rows,\n getRowId,\n props.getChildren,\n props.getParentId,\n props.hasChildren,\n ]\n );\n const tree = useMemo(() => {\n if (!treeEntries) return undefined;\n return {\n entries: treeEntries,\n /** Every node, folded ones included — what an \"all\" export writes. */\n allEntries: treeExportEntries,\n // Opening a node fetches its children on the way: the row opens at once\n // and fills when they land, so the chevron never feels stuck behind a\n // request.\n expansion: {\n ...treeExpansion,\n toggle: (id: string) => {\n const entry = treeEntries.find((candidate) => candidate.key === id);\n if (entry && !entry.expanded) lazyChildren.loadIfNeeded(entry.row);\n treeExpansion.toggle(id);\n },\n },\n loadingIds: lazyChildren.loadingIds,\n /** Nodes whose last fetch failed — closed, and clickable again. */\n failedIds: lazyChildren.failedIds,\n columnKey: treeColumnKey(columnLayout.visibleColumns, props.treeColumn),\n };\n }, [\n treeEntries,\n treeExportEntries,\n treeExpansion,\n lazyChildren,\n props.treeColumn,\n columnLayout.visibleColumns,\n ]);\n const grouping = useMemo(() => {\n if (groupByKeys.length === 0) return undefined;\n if (!source.allFilteredRows && !serverGroups) return undefined;\n const incremental = incrementalViewOf(source.allFilteredRows ?? []);\n const view = incremental\n ? configureIncrementalView(incremental, {\n groupBy: groupByKeys,\n columns: columnLayout.visibleColumns,\n getRowId,\n groupAggregates,\n groupSort,\n groupFilter,\n groupFooters: groupFooters === true,\n collapsedGroupIds: groupCollapse.collapsedGroupIds,\n groupPageSize,\n rowPageSize: groupRowPageSize,\n paging: groupPaging.paging,\n })\n : undefined;\n const entries = serverGroups\n ? serverGroupEntries({\n groups: serverGroups,\n groupBy: groupByKeys,\n collapsedGroupIds: groupCollapse.collapsedGroupIds,\n getRowId,\n footers: groupFooters === true,\n })\n : (view?.groups ??\n buildGroupedFlatModel({\n rows: source.allFilteredRows ?? [],\n groupBy: groupByKeys,\n columns: columnLayout.visibleColumns,\n getRowId,\n collapsedGroupIds: groupCollapse.collapsedGroupIds,\n aggregates: groupAggregates,\n footers: groupFooters === true,\n sort: groupSort,\n filter: groupFilter,\n groupPageSize,\n rowPageSize: groupRowPageSize,\n paging: groupPaging.paging,\n }));\n // The whole-tree actions need the keys, and the entries are where they\n // are: a collapsed group hides its children, so its own key is still\n // listed while theirs are not — which is exactly what closing everything\n // one level at a time produces.\n const openGroups = entries.flatMap((entry) =>\n entry.kind === \"group\" ? [{ key: entry.key, level: entry.level }] : []\n );\n const withExtras = insertExtraRows(entries, extraRows, (entry) =>\n entry.kind === \"row\" ? entry.key : undefined\n );\n return {\n groupBy: groupByKeys,\n collapsed: groupCollapse,\n aggregates: groupAggregates,\n entries: withExtras,\n setGroupBy,\n /**\n * Reveal the next page of groups, or of one group's rows. The table\n * shows what it already holds; `onGroupLoadMore` is where a server tier\n * fetches the rest.\n */\n showMore: (entry: { scope: \"groups\" | \"rows\"; groupKey?: string }) => {\n const size =\n entry.scope === \"groups\"\n ? (groupPageSize ?? 0)\n : (groupRowPageSize ?? 0);\n groupPaging.showMore(size, entry.groupKey);\n if (entry.scope === \"rows\" && entry.groupKey) {\n onGroupLoadMore?.(entry.groupKey);\n }\n },\n expandAll: groupCollapse.expandAll,\n collapseAll: () => {\n groupCollapse.collapseToDepth(0, openGroups);\n },\n collapseToDepth: (depth: number) => {\n groupCollapse.collapseToDepth(depth, openGroups);\n },\n };\n }, [\n groupByKeys,\n serverGroups,\n source.allFilteredRows,\n columnLayout.visibleColumns,\n getRowId,\n groupCollapse,\n groupAggregates,\n groupFooters,\n groupSort,\n groupFilter,\n groupPageSize,\n groupRowPageSize,\n onGroupLoadMore,\n extraRows,\n groupPaging,\n setGroupBy,\n ]);\n\n // See TableChrome.editingRows — the row universe the editing layer\n // validates against must match what the body renders.\n const editingRows = useMemo(() => {\n if (!grouping) return viewSource.rows;\n const leaves: TRow[] = [];\n for (const entry of grouping.entries) {\n if (entry.kind === \"row\") leaves.push(entry.row);\n }\n return leaves;\n }, [grouping, viewSource.rows]);\n\n // Reorder a flat list, never a nested one: grouping and trees have their\n // own order, and a splice through them would silently lie.\n const requestedReorder = props.onRowReorder !== undefined;\n const reorderBlocked = grouping !== undefined || treeShaped;\n useEffect(() => {\n if (!requestedReorder || !reorderBlocked) return;\n devWarn(\n \"onRowReorder is ignored while grouping or a tree is armed — reorder a flat list, not a nested one.\"\n );\n }, [requestedReorder, reorderBlocked]);\n const hasRowReorder = requestedReorder && !reorderBlocked;\n const reorderHidden = columnLayout.isHidden(REORDER_COLUMN_KEY);\n const rowReorderEnabled = hasRowReorder && !reorderHidden;\n const hostRowReorder = props.onRowReorder;\n const rowReorderState = useRowReorder({\n enabled: rowReorderEnabled,\n onRowReorder: hostRowReorder,\n labels: {\n reorderRow: table.labels.reorderRow,\n moveRowUp: table.labels.moveRowUp,\n moveRowDown: table.labels.moveRowDown,\n rowLifted: table.labels.rowLifted,\n rowMoved: table.labels.rowMoved,\n rowReorderCancelled: table.labels.rowReorderCancelled,\n },\n rowAt: (index) => editingRows[index],\n });\n const rowReorder = rowReorderEnabled ? rowReorderState : undefined;\n\n const rowPinning = useChromeRowPinning({\n requested:\n props.pinnedRowIds !== undefined ||\n props.onPinnedRowIdsChange !== undefined,\n blocked: grouping !== undefined || treeShaped,\n pinnedRowIds: props.pinnedRowIds,\n onPinnedRowIdsChange: props.onPinnedRowIdsChange,\n getRowId: (row) => rowKey(row),\n labels: {\n pinToTop: table.labels.pinToTop,\n pinToBottom: table.labels.pinToBottom,\n unpinRow: table.labels.unpinRow,\n },\n });\n\n useEffect(() => {\n if (!editing) return;\n editing.state.discardIfRowMissing(editingRows, (row) =>\n rowKey(row as TRow)\n );\n conflict.reconcile({\n active: editing.state.active,\n openedRow: editing.state.openedRow() as TRow | undefined,\n draft: editing.state.draft,\n rows: editingRows,\n columns: resolvedColumns,\n rowKey,\n rowVersion: props.rowVersion,\n policy: props.editConflictPolicy ?? \"ask\",\n onEditConflict: props.onEditConflict,\n keep: (row) => {\n editing.state.keepLive(row);\n },\n take: (row, value) => {\n editing.state.takeLive(row, value);\n },\n });\n }, [\n editing,\n editingRows,\n rowKey,\n conflict,\n resolvedColumns,\n props.rowVersion,\n props.editConflictPolicy,\n props.onEditConflict,\n ]);\n\n const showFooter =\n isPaged &&\n !viewSource.error &&\n (viewSource.total > 0 || viewSource.isLoading || viewSource.isFetching);\n\n const featureNotices = useMemo(\n () =>\n collectFeatureNotices({\n virtualize: props.virtualize,\n paginationMode: source.paginationMode,\n groupByKeys,\n allFilteredRows: source.allFilteredRows,\n serverGroups,\n rowPinningRequested:\n props.pinnedRowIds !== undefined ||\n props.onPinnedRowIdsChange !== undefined,\n rowReorderRequested: props.onRowReorder !== undefined,\n nestedArmed: grouping !== undefined || treeShaped,\n hasEditableColumn,\n onCellEdit,\n rowEditing: props.rowEditing,\n onRowEdit: props.onRowEdit,\n batchEditing: props.batchEditing,\n onBatchEdit: props.onBatchEdit,\n exportCsv: props.exportCsv,\n labels: table.labels,\n }),\n [\n props.virtualize,\n source.paginationMode,\n groupByKeys,\n source.allFilteredRows,\n serverGroups,\n props.pinnedRowIds,\n props.onPinnedRowIdsChange,\n props.onRowReorder,\n grouping,\n treeShaped,\n hasEditableColumn,\n onCellEdit,\n props.rowEditing,\n props.onRowEdit,\n props.batchEditing,\n props.onBatchEdit,\n props.exportCsv,\n table.labels,\n ]\n );\n\n useEffect(() => {\n const el = rootRef.current;\n if (!el) return;\n const value = featureNotices.map((notice) => notice.kind).join(\" \");\n if (value) el.dataset.adapttableNotices = value;\n else delete el.dataset.adapttableNotices;\n });\n\n const hasAnyActions = hasRowActions || rowPinning !== undefined;\n const visibleRowActions = useMemo(() => {\n if (actionsHidden || !hasAnyActions) return undefined;\n const pins = rowPinning?.actions ?? [];\n if (pins.length === 0) return rowActions;\n return [...(rowActions ?? []), ...pins];\n }, [actionsHidden, hasAnyActions, rowActions, rowPinning]);\n\n return {\n source: viewSource,\n table,\n isMobile,\n confirm,\n getRowId,\n mergedChips,\n activeFilterCount,\n isPaged,\n rootRef,\n droppedColumns: responsive.dropped,\n body,\n errorState,\n emptyVariant,\n isRefreshing,\n clearFilters,\n detail,\n rowMutations,\n rowActions: visibleRowActions,\n hasRowActions: hasAnyActions,\n hasRowReorder,\n rowReorder,\n rowPinning,\n editing,\n grouping,\n tree,\n editingRows,\n showFooter,\n columnLayout,\n columnGroups: flattened.groups,\n allColumns: resolvedColumns,\n featureNotices,\n };\n}\n\n/** Result of {@link useChromeBodyData}. */\nexport interface ChromeBodyData {\n /** Row/card window virtualization state (disabled unless eligible). */\n virtualization: TableVirtualization;\n /**\n * When grouping is armed, the (possibly virtual-windowed) flat entries\n * adapters should render. `undefined` when grouping is dormant.\n */\n groupingEntries?: readonly GroupedFlatEntry[];\n /**\n * When a tree is armed, the (possibly virtual-windowed) entries adapters\n * should render. `undefined` when the table is flat.\n */\n treeEntries?: readonly TreeEntry[];\n /** Sentinel ref that auto-loads the next page in infinite mode. */\n loadMoreRef: RefObject;\n /** Whether the load-more affordance applies (infinite mode, no error). */\n canLoadMore: boolean;\n /**\n * Attach to the `maxHeight` scroll box (when one renders) so the virtual\n * window tracks the box's scrolling instead of the page's. Harmless to\n * attach when virtualization is off.\n */\n virtualScrollRef: RefCallback;\n /** Top-pinned rows, removed from the virtual window. */\n pinnedTopRows: readonly TRow[];\n /** Bottom-pinned rows, removed from the virtual window. */\n pinnedBottomRows: readonly TRow[];\n}\n\n/**\n * The shared data-flow wiring between {@link useTableChrome} and an\n * adapter's body: window virtualization (eligible only for real rows in\n * infinite mode) and the infinite-scroll sentinel. Extracted because four\n * adapters repeated this block verbatim; antd opts out (it scrolls inside\n * its own `
` container).\n *\n * @typeParam TRow - The row type.\n * @param chrome - The {@link useTableChrome} result.\n * @param props - The adapter's {@link BaseDataTableProps}.\n * @returns Virtualization state + the load-more sentinel.\n */\nexport function useChromeBodyData(\n chrome: TableChrome,\n props: BaseDataTableProps\n): ChromeBodyData {\n const { rowKey, virtualize = false } = props;\n // The chrome's view facade, so grouped full-set state (no next page, all\n // rows present) drives the sentinel and virtualization too.\n const { source } = chrome;\n if (virtualize && source.paginationMode === \"paged\") {\n devWarn(\n 'virtualize only applies in infinite mode — this paged table renders unvirtualized. Pass paginationMode=\"infinite\" to enable it.'\n );\n }\n const fetchNext = useCallback(() => {\n if (source.hasNextPage && !source.isFetchingNextPage) {\n source.fetchNextPage();\n }\n }, [source]);\n const scrollBoxRef = useRef(null);\n const inScrollBox = props.maxHeight != null;\n // Window mode needs the list's document Y as TanStack `scrollMargin`.\n // Without it, page chrome above the table is treated as already-scrolled\n // rows and the body opens with a blank gap. An explicit prop wins.\n const measureWindowOffset =\n virtualize && !inScrollBox && props.virtualScrollMargin == null;\n const { scrollMargin: measuredScrollMargin, observe: observeWindowList } =\n useMeasuredWindowScrollMargin(measureWindowOffset, chrome.rootRef);\n const virtualScrollRef = useCallback(\n (node: HTMLElement | null) => {\n scrollBoxRef.current = node;\n observeWindowList(node);\n },\n [observeWindowList]\n );\n const bodyEligible = isBodyEligible(chrome);\n const groupingArmed = Boolean(chrome.grouping);\n const groupKeys = entryKeys(chrome.grouping?.entries);\n // A tree is a keyed flat list once it has been walked, exactly like a\n // grouped model — so it windows through the same hook rather than a second\n // one. Without this a 50,000-row hierarchy renders 50,000 rows: the row\n // virtualizer counts source rows, and a tree's visible list is its own.\n const treeArmed = Boolean(chrome.tree);\n const treeKeys = entryKeys(chrome.tree?.entries);\n const pinState = chrome.rowPinning?.state;\n const partitioned = useMemo(() => {\n if (!pinState) {\n return { top: [] as TRow[], scroll: source.rows, bottom: [] as TRow[] };\n }\n return partitionPinnedRows(source.rows, pinState, rowKey);\n }, [pinState, rowKey, source.rows]);\n const estimateSize = estimateBodyItemSize(chrome, props, partitioned.scroll);\n const scrollOpts = {\n overscan: props.virtualOverscan,\n scrollMargin: props.virtualScrollMargin ?? measuredScrollMargin,\n getScrollElement: inScrollBox ? () => scrollBoxRef.current : undefined,\n onEndReached: fetchNext,\n estimateSize,\n } as const;\n\n // Both hooks run unconditionally (Rules of Hooks); exactly one is enabled.\n const groupVirtualization = useKeyedVirtualization({\n keys: groupKeys,\n enabled: virtualize && groupingArmed && bodyEligible,\n ...scrollOpts,\n });\n const treeVirtualization = useKeyedVirtualization({\n keys: treeKeys,\n enabled: virtualize && treeArmed && !groupingArmed && bodyEligible,\n ...scrollOpts,\n });\n\n const virtualization = useTableVirtualization({\n rows: partitioned.scroll,\n rowKey,\n enabled: virtualize && !groupingArmed && !treeArmed && bodyEligible,\n // Detail panels are separate elements from their rows, so the window\n // measures the two together rather than sizing an expanded row from its\n // top half.\n expandable: props.renderRowDetail !== undefined,\n ...scrollOpts,\n });\n\n const groupingEntries = chrome.grouping\n ? windowGroupedEntries(chrome.grouping.entries, groupVirtualization.indices)\n : undefined;\n const treeEntries = chrome.tree\n ? windowGroupedEntries(chrome.tree.entries, treeVirtualization.indices)\n : undefined;\n\n const resolvedVirtualization = resolveBodyVirtualization(\n groupingArmed ? groupVirtualization : treeVirtualization,\n virtualization\n );\n\n const boxVirtual = resolvedVirtualization.enabled && inScrollBox;\n const canLoadMore = !chrome.isPaged && !source.error && !boxVirtual;\n const loadMoreRef = useInfiniteScroll({\n hasNextPage: Boolean(source.hasNextPage),\n isFetchingNextPage: Boolean(source.isFetchingNextPage),\n fetchNextPage: fetchNext,\n itemCount: bodySentinelCount(chrome, groupingArmed),\n enabled: canLoadMore,\n });\n const sourceIndexById = useMemo(() => {\n const map = new Map();\n source.rows.forEach((row, index) => map.set(rowKey(row), index));\n return map;\n }, [rowKey, source.rows]);\n\n const pinnedVirtualization = useMemo(() => {\n if (!pinState) return resolvedVirtualization;\n return {\n ...resolvedVirtualization,\n rows: resolvedVirtualization.rows.map((entry) => ({\n ...entry,\n sourceIndex: sourceIndexById.get(entry.key) ?? entry.index,\n })),\n };\n }, [pinState, resolvedVirtualization, sourceIndexById]);\n\n return {\n virtualization: pinnedVirtualization,\n groupingEntries,\n treeEntries,\n loadMoreRef,\n canLoadMore,\n virtualScrollRef,\n pinnedTopRows: partitioned.top,\n pinnedBottomRows: partitioned.bottom,\n };\n}\n\n/**\n * Whether a row's children are already in the data.\n *\n * Both declarations answer it: nested data has them under the row, a flat table\n * has them among the rows keyed by their parent. A node with none is one the\n * host said has children (`hasChildren`) and the browser has not fetched.\n */\nfunction hasLoadedChildren(\n row: TRow,\n rows: readonly TRow[],\n props: BaseDataTableProps\n): boolean {\n const nested = props.getChildren?.(row);\n if (nested !== undefined) return nested.length > 0;\n const { getParentId, rowKey } = props;\n if (!getParentId) return false;\n const id = rowKey(row);\n return rows.some((candidate) => getParentId(candidate) === id);\n}\n\n/** The keys of a walked model's entries — one shape for groups and trees. */\nfunction entryKeys(entries?: readonly { key: string }[]): string[] {\n return entries?.map((entry) => entry.key) ?? [];\n}\n\n/** Whether the body is a real row/card list the window can apply to. */\nfunction isBodyEligible(chrome: TableChrome): boolean {\n return (\n !chrome.isPaged &&\n !chrome.source.error &&\n (chrome.body === \"desktop\" || chrome.body === \"mobile\")\n );\n}\n\n/** A card's height on a phone, a row's on a desktop — or `rowHeight`. */\nfunction estimateBodyItemSize(\n chrome: TableChrome,\n props: BaseDataTableProps,\n scrollRows: readonly TRow[]\n): (index: number) => number {\n const fallback = chrome.isMobile\n ? (props.estimateCardSize ?? DEFAULT_CARD_SIZE_PX)\n : (props.estimateRowSize ?? DEFAULT_ROW_SIZE_PX);\n return estimateFromRowHeight(props.rowHeight, fallback, (index) => {\n if (chrome.grouping) {\n const entry = chrome.grouping.entries[index];\n if (entry?.kind === \"row\") return { row: entry.row, index: entry.index };\n return undefined;\n }\n if (chrome.tree) {\n const entry = chrome.tree.entries[index];\n if (entry) return { row: entry.row, index };\n return undefined;\n }\n const row = scrollRows[index];\n return row === undefined ? undefined : { row, index };\n });\n}\n\n/** How many items the infinite-scroll sentinel counts as already rendered. */\nfunction bodySentinelCount(\n chrome: TableChrome,\n groupingArmed: boolean\n): number {\n if (groupingArmed) return chrome.grouping?.entries.length ?? 0;\n return chrome.source.rows.length;\n}\n\nfunction resolveBodyVirtualization(\n keyed: ReturnType,\n virtualization: TableVirtualization\n): TableVirtualization {\n if (!keyed.enabled) return virtualization;\n return {\n enabled: true,\n rows: [],\n paddingTop: keyed.paddingTop,\n paddingBottom: keyed.paddingBottom,\n measureElement: keyed.measureElement,\n };\n}\n\n/**\n * The shared scroll-restoration wiring every adapter `` needs:\n * when search / sort / page / filters change, scroll the table back below\n * the sticky chrome. Extracted so the identical block isn't repeated (and\n * flagged as duplication) in each adapter.\n *\n * @typeParam TRow - The row type.\n * @param ref - The adapter's root element.\n * @param chrome - The {@link useTableChrome} result.\n * @param props - The adapter's {@link BaseDataTableProps}.\n */\nexport function useChromeScrollReset(\n ref: RefObject,\n chrome: TableChrome,\n props: BaseDataTableProps\n): void {\n const { source } = props;\n // In infinite mode a page increment means \"the window grew at the\n // bottom\" (the sentinel loaded more) — yanking the reader back to the\n // table top would fight the scroll they are mid-way through. Only paged\n // navigation is a real page change worth resetting for.\n const pageDep = source.paginationMode === \"paged\" ? source.page : 0;\n useScrollToTableTop({\n ref,\n deps: [\n source.search,\n source.sortBy ?? \"\",\n source.sortDir ?? \"\",\n pageDep,\n chrome.activeFilterCount,\n ],\n enabled: props.scrollToTopOnChange,\n offset: props.stickyTop,\n gap: props.scrollTopGap,\n });\n}\n\n/** Pointer/click handlers returned by {@link useFilterTriggerToggle}. */\nexport interface FilterTriggerToggle {\n onPointerDown: () => void;\n onClick: () => void;\n}\n\n/**\n * A toggle for the Filters trigger that survives every kit's outside-close\n * behavior. Some kits (Chakra `closeOnBlur`, outside `mousedown` handlers)\n * close the popover on the trigger's own pointer-down — a plain\n * `setOpen(o => !o)` on click then instantly REOPENS it, so the button can\n * never close the popover. This records whether the popover was open at\n * pointer-down: if the kit closed it in between, the click is swallowed;\n * otherwise the click toggles normally (kits that exclude the trigger from\n * outside-close keep working unchanged).\n */\nfunction useChromeRowPinning(options: {\n requested: boolean;\n blocked: boolean;\n pinnedRowIds?: RowPinState;\n onPinnedRowIdsChange?: (next: RowPinState) => void;\n getRowId: (row: TRow) => string;\n labels: RowPinLabels;\n}): RowPinningState | undefined {\n const { requested, blocked, labels } = options;\n useEffect(() => {\n if (!requested || !blocked) return;\n devWarn(\n \"row pinning is ignored while grouping or a tree is armed — pin a flat list, not a nested one.\"\n );\n }, [blocked, requested]);\n const enabled = requested && !blocked;\n const state = useRowPinning({\n enabled,\n pinnedRowIds: options.pinnedRowIds,\n onPinnedRowIdsChange: options.onPinnedRowIdsChange,\n getRowId: options.getRowId,\n labels,\n });\n return enabled ? state : undefined;\n}\n\nexport function useFilterTriggerToggle(\n open: boolean,\n setOpen: (next: boolean | ((current: boolean) => boolean)) => void\n): FilterTriggerToggle {\n const wasOpenAtPointerDown = useRef(false);\n return {\n onPointerDown: useCallback(() => {\n wasOpenAtPointerDown.current = open;\n }, [open]),\n onClick: useCallback(() => {\n const closedByKit = wasOpenAtPointerDown.current && !open;\n wasOpenAtPointerDown.current = false;\n if (closedByKit) return;\n setOpen((current) => !current);\n }, [open, setOpen]),\n };\n}\n","import type { ReactNode } from \"react\";\n\nimport type {\n ColumnDef,\n ColumnHeaderContext,\n ColumnHeaderController,\n} from \"../types\";\nimport { humanizeKey } from \"../utils/humanizeKey\";\n\n/** Default header caption: the explicit header, else a humanized key. */\nexport function columnHeaderLabel(column: ColumnDef): ReactNode {\n return column.header ?? humanizeKey(column.key);\n}\n\n/** Build the controller a custom header receives. */\nexport function columnHeaderController(\n column: ColumnDef,\n extras: {\n sortDir?: \"asc\" | \"desc\";\n sortIndex?: number;\n toggleSort?: (event?: { shiftKey?: boolean }) => void;\n } = {}\n): ColumnHeaderController {\n return {\n label: columnHeaderLabel(column),\n sortDir: extras.sortDir,\n sortIndex: extras.sortIndex,\n toggleSort: extras.toggleSort ?? (() => undefined),\n };\n}\n\n/** Custom `renderHeader`, or the default caption. */\nexport function resolveColumnHeader(\n column: ColumnDef,\n controller: ColumnHeaderController\n): ReactNode {\n if (column.renderHeader === undefined) return controller.label;\n const ctx: ColumnHeaderContext = { column, controller };\n return column.renderHeader(ctx);\n}\n\n/** Custom `renderFooter`, or the summary value as-is. */\nexport function resolveColumnFooter(\n column: ColumnDef,\n value: ReactNode\n): ReactNode {\n if (column.renderFooter === undefined) return value;\n return column.renderFooter({ column, value });\n}\n\n/** True when any column wants a footer cell of its own. */\nexport function columnsHaveFooter(\n columns: readonly ColumnDef[]\n): boolean {\n return columns.some((column) => column.renderFooter !== undefined);\n}\n","import type { DragEvent, KeyboardEvent } from \"react\";\nimport { useCallback, useState } from \"react\";\n\nimport { isRtlElement } from \"../layout/writingDirection\";\n\n/** MIME type carrying the dragged column key during a reorder drag. */\nexport const COLUMN_DND_MIME = \"application/x-adapttable-column\";\n\n/** Props that make a whole menu ROW draggable (so the browser's drag image is\n * the full row — you see the column move). Pair with {@link columnDropProps}. */\nexport interface ColumnRowDragProps {\n draggable: true;\n onDragStart: (event: DragEvent) => void;\n}\n\n/**\n * Build drag props for a column-menu row. The entire row is the drag handle,\n * matching the native drag-image so the reorder feels physical.\n *\n * @param key - Column key being reordered.\n */\nexport function columnRowDragProps(key: string): ColumnRowDragProps {\n return {\n draggable: true,\n onDragStart: (event) => {\n // The whole row is draggable so the drag image is the full row — but a\n // drag starting on an interactive control (the eye/pin buttons) would\n // hijack their click. Cancel those so the buttons stay clickable. The\n // reorder grip is exempt even when a kit renders it as a button\n // (Mantine ActionIcon, MUI IconButton): it carries\n // `data-adapttable-grip` via {@link columnReorderKeyProps}, and\n // dragging from the grip is the strongest affordance of all.\n const target = event.target as HTMLElement | null;\n if (\n target?.closest(\"button,input,select,a\") &&\n !target.closest(\"[data-adapttable-grip]\")\n ) {\n event.preventDefault();\n return;\n }\n event.dataTransfer.setData(COLUMN_DND_MIME, key);\n event.dataTransfer.effectAllowed = \"move\";\n },\n };\n}\n\n/** Props for a small, focusable reorder grip — keyboard a11y for the row drag. */\nexport interface ColumnReorderKeyProps {\n role: \"button\";\n tabIndex: 0;\n \"aria-label\": string;\n \"data-adapttable-grip\": \"\";\n onKeyDown: (event: KeyboardEvent) => void;\n}\n\n/**\n * Whether the grip sits in a right-to-left context. Mirrors the resize\n * handle's detection: an explicit `[dir]` ancestor wins (what the adapters\n * set on the root), falling back to the resolved CSS `direction`.\n */\nfunction isRtl(grip: HTMLElement | null): boolean {\n return isRtlElement(grip);\n}\n\n/**\n * Build keyboard props for the reorder grip. Arrow keys move the column one\n * slot — the accessible equivalent of the pointer drag. Up/Down always mean\n * earlier/later in the order; Left/Right follow the writing direction, so in\n * RTL pressing ArrowRight moves the column toward the start (visually right).\n *\n * @param key - Column key being reordered.\n * @param index - The column's current index in the full order.\n * @param move - Layout mutator that moves a column to a new index.\n * @param label - Accessible label for the grip.\n */\nexport function columnReorderKeyProps(\n key: string,\n index: number,\n move: (key: string, toIndex: number) => void,\n label: string\n): ColumnReorderKeyProps {\n return {\n role: \"button\",\n tabIndex: 0,\n \"aria-label\": label,\n \"data-adapttable-grip\": \"\",\n onKeyDown: (event) => {\n const horizontal =\n event.key === \"ArrowLeft\" || event.key === \"ArrowRight\";\n const vertical = event.key === \"ArrowUp\" || event.key === \"ArrowDown\";\n if (!horizontal && !vertical) return;\n event.preventDefault();\n // The arrow that points toward the inline start: ArrowLeft in LTR,\n // ArrowRight in RTL (where the first column renders on the right).\n const startKey = isRtl(event.currentTarget) ? \"ArrowRight\" : \"ArrowLeft\";\n const towardStart = horizontal\n ? event.key === startKey\n : event.key === \"ArrowUp\";\n move(key, towardStart ? index - 1 : index + 1);\n },\n };\n}\n\n/** Props for a row that accepts a dropped column, moving it to this index. */\nexport interface ColumnDropProps {\n onDragOver: (event: DragEvent) => void;\n onDrop: (event: DragEvent) => void;\n}\n\n/**\n * Build drop props for a reorder target: moves the dragged column to this\n * row's `index` on drop.\n *\n * @param index - Target index the dragged column moves to.\n * @param move - Layout mutator that moves a column to a new index.\n */\nexport function columnDropProps(\n index: number,\n move: (key: string, toIndex: number) => void\n): ColumnDropProps {\n return {\n onDragOver: (event) => {\n if (!event.dataTransfer.types.includes(COLUMN_DND_MIME)) return;\n event.preventDefault();\n event.dataTransfer.dropEffect = \"move\";\n },\n onDrop: (event) => {\n const key = event.dataTransfer.getData(COLUMN_DND_MIME);\n if (key === \"\") return;\n event.preventDefault();\n move(key, index);\n },\n };\n}\n\n/** Indicator attributes for a column-menu row during a reorder drag. */\nexport interface ColumnDragRowAttrs {\n /** Present on the row being dragged (kits dim it). */\n \"data-dragging\"?: \"\";\n /** Present on the hovered drop target, with the insertion edge. */\n \"data-drop\"?: \"before\" | \"after\";\n}\n\n/** Live drag state + composed prop builders from {@link useColumnDragState}. */\nexport interface ColumnDragState {\n /** Key currently being dragged, or `null` outside a drag. */\n draggingKey: string | null;\n /** Hovered drop index, or `null`. */\n overIndex: number | null;\n /** Drag props for a row — {@link columnRowDragProps} + state tracking. */\n rowDragProps: (\n key: string,\n index: number\n ) => ColumnRowDragProps & {\n onDragEnd: () => void;\n };\n /** Drop props for a row — {@link columnDropProps} + hover tracking. */\n dropProps: (\n index: number,\n move: (key: string, toIndex: number) => void\n ) => ColumnDropProps;\n /** Indicator data-attributes for a row; style them with kit CSS. */\n rowAttrs: (key: string, index: number) => ColumnDragRowAttrs;\n}\n\n/**\n * Drop-position feedback for the column-menu reorder. Composes the existing\n * drag/drop prop builders with the tracking they lack, so adapters can show\n * WHERE the dragged column will land instead of leaving the user to guess:\n * the dragged row carries `data-dragging` (dim it) and the hovered target\n * carries `data-drop=\"before\" | \"after\"` (draw an insertion line on that\n * edge). State clears on drop, drag end, and drag cancel alike.\n */\nexport function useColumnDragState(): ColumnDragState {\n const [drag, setDrag] = useState<{ key: string; from: number } | null>(null);\n const [overIndex, setOverIndex] = useState(null);\n\n const reset = useCallback(() => {\n setDrag(null);\n setOverIndex(null);\n }, []);\n\n const rowDragProps = useCallback(\n (key, index) => {\n const base = columnRowDragProps(key);\n return {\n ...base,\n onDragStart: (event) => {\n base.onDragStart(event);\n // The base handler cancels drags that start on interactive\n // controls — only track the ones it allowed.\n if (!event.defaultPrevented) setDrag({ key, from: index });\n },\n onDragEnd: reset,\n };\n },\n [reset]\n );\n\n const dropProps = useCallback(\n (index, move) => {\n const base = columnDropProps(index, move);\n return {\n onDragOver: (event) => {\n base.onDragOver(event);\n // Only a column drag (accepted above) marks a target.\n if (event.defaultPrevented) setOverIndex(index);\n },\n onDrop: (event) => {\n base.onDrop(event);\n reset();\n },\n };\n },\n [reset]\n );\n\n const rowAttrs = useCallback(\n (key, index) => {\n if (!drag) return {};\n // The source row matches by key here, so the hovered-target branch\n // below can never be the dragged row itself.\n if (drag.key === key) return { \"data-dragging\": \"\" };\n if (overIndex !== index) return {};\n // `move` inserts the dragged column AT this index: coming from later\n // in the order it lands before this row, from earlier it lands after.\n return { \"data-drop\": index < drag.from ? \"before\" : \"after\" };\n },\n [drag, overIndex]\n );\n\n return {\n draggingKey: drag?.key ?? null,\n overIndex,\n rowDragProps,\n dropProps,\n rowAttrs,\n };\n}\n","import { useCallback, useRef, useState } from \"react\";\n\n/** Result of {@link useHorizontalOverflow}. */\nexport interface HorizontalOverflow {\n /** Callback ref for the wrapper element to measure. */\n ref: (node: E | null) => void;\n /** True while the wrapper's content is wider than the wrapper. */\n overflowing: boolean;\n}\n\n/**\n * Whether an element's content overflows it horizontally, kept current via\n * `ResizeObserver`. Adapters use it to turn the table wrapper into a\n * horizontal scroller ONLY when the table is actually wider than its\n * container — an unconditional `overflow-x: auto` would make the wrapper a\n * scroll container and trap page-scroll sticky headers even when nothing\n * overflows. Under SSR (no `ResizeObserver`) it stays `false`.\n */\nexport function useHorizontalOverflow<\n E extends HTMLElement,\n>(): HorizontalOverflow {\n const [overflowing, setOverflowing] = useState(false);\n const observerRef = useRef(null);\n const ref = useCallback((node: E | null) => {\n observerRef.current?.disconnect();\n observerRef.current = null;\n if (!node || typeof ResizeObserver === \"undefined\") return;\n const measure = (): void => {\n // +1 absorbs sub-pixel rounding so the scroller never flickers on.\n setOverflowing(node.scrollWidth > node.clientWidth + 1);\n };\n const observer = new ResizeObserver(measure);\n observer.observe(node);\n // The table's width changes (columns shown/hidden/resized) move\n // scrollWidth without resizing the wrapper itself — observe it too.\n if (node.firstElementChild) observer.observe(node.firstElementChild);\n observerRef.current = observer;\n measure();\n }, []);\n return { ref, overflowing };\n}\n","/**\n * Sticky chrome for pinned rows — one style, every kit.\n *\n * A pinned row leaves the virtual window and sticks above or below it.\n * Column pins still apply on those cells, so the z-index has to sit\n * between a scrolled pinned column and the sticky header: otherwise a\n * pinned row slides under the header, or a pinned column paints over it.\n */\nimport { useCallback, useEffect, useState } from \"react\";\n\nimport { PIN_Z } from \"../columns/useColumnLayout\";\nimport type { VirtualTableRow } from \"../virtual/useTableVirtualization\";\nimport { resolveVirtualRows } from \"../virtual/useTableVirtualization\";\nimport type { RowPinSide } from \"./rowPinning\";\n\n/** `data-adapttable-part` on a pinned row in the shared tbody. */\nexport const PINNED_TOP_PART = \"pinned-top\";\n/** Bottom pin marker on that row. */\nexport const PINNED_BOTTOM_PART = \"pinned-bottom\";\n\n/** Part name for a pinned row, or `undefined` when the row is not pinned. */\nexport function pinnedRowPart(\n side: RowPinSide | undefined\n): typeof PINNED_TOP_PART | typeof PINNED_BOTTOM_PART | undefined {\n if (side === \"top\") return PINNED_TOP_PART;\n if (side === \"bottom\") return PINNED_BOTTOM_PART;\n return undefined;\n}\n\n/** Sticky style when the row is pinned and the kit asked for sticky pins. */\nexport function pinnedRowSticky(\n side: RowPinSide | undefined,\n sticky: boolean,\n headerOffsetPx: number\n): ReturnType | undefined {\n if (!sticky || !side) return undefined;\n const offset = side === \"bottom\" ? 0 : headerOffsetPx;\n return pinnedRowStickyStyle(side, offset);\n}\n\n/** Sticky style for a pinned-row section (tbody or the row itself). */\nexport function pinnedRowStickyStyle(\n side: RowPinSide,\n headerOffsetPx: number\n): { position: \"sticky\"; top?: number; bottom?: number; zIndex: number } {\n if (side === \"top\") {\n return {\n position: \"sticky\",\n top: headerOffsetPx,\n zIndex: PIN_Z.rowPinned,\n };\n }\n return {\n position: \"sticky\",\n bottom: 0,\n zIndex: PIN_Z.rowPinned,\n };\n}\n\n/**\n * Extra sticky inset a cell in a pinned row needs, and the z-index when\n * that cell is also a pinned column.\n */\nexport function pinnedRowCellStyle(\n side: RowPinSide | undefined,\n headerOffsetPx: number,\n columnPinned: boolean\n): {\n position?: \"sticky\";\n top?: number;\n bottom?: number;\n zIndex?: number;\n} {\n if (!side) return {};\n const edge = side === \"top\" ? { top: headerOffsetPx } : { bottom: 0 };\n return {\n position: \"sticky\",\n ...edge,\n zIndex: columnPinned ? PIN_Z.rowPinnedColumn : PIN_Z.rowPinned,\n };\n}\n\n/** Measure an element's offset height; used for the sticky header offset. */\nexport function useOffsetHeight(): [\n (node: HTMLElement | null) => void,\n number,\n] {\n const [node, setNode] = useState(null);\n const [height, setHeight] = useState(0);\n const ref = useCallback((next: HTMLElement | null) => {\n setNode(next);\n if (next) setHeight(next.getBoundingClientRect().height);\n }, []);\n useEffect(() => {\n if (!node || typeof ResizeObserver === \"undefined\") return undefined;\n const observer = new ResizeObserver(() => {\n setHeight(node.getBoundingClientRect().height);\n });\n observer.observe(node);\n return () => observer.disconnect();\n }, [node]);\n return [ref, height];\n}\n\n/**\n * Card list order: top pins, then the scroll window, then bottom pins.\n * Desktop sticky sections use the same three lists; cards are a list, so\n * this is the only \"chrome\" they get.\n */\nexport function orderedCardEntries(\n rows: readonly TRow[],\n getRowId: (row: TRow) => string,\n rowEntries: readonly VirtualTableRow[] | undefined,\n pinnedTop: readonly TRow[],\n pinnedBottom: readonly TRow[]\n): readonly VirtualTableRow[] {\n if (pinnedTop.length === 0 && pinnedBottom.length === 0) {\n return resolveVirtualRows(rows, getRowId, rowEntries);\n }\n const pinnedIds = new Set();\n for (const row of pinnedTop) pinnedIds.add(getRowId(row));\n for (const row of pinnedBottom) pinnedIds.add(getRowId(row));\n const indexById = new Map();\n rows.forEach((row, index) => indexById.set(getRowId(row), index));\n const asEntry = (row: TRow): VirtualTableRow => {\n const key = getRowId(row);\n const sourceIndex = indexById.get(key) ?? 0;\n return { row, index: sourceIndex, sourceIndex, key };\n };\n const scroll = resolveVirtualRows(rows, getRowId, rowEntries).filter(\n (entry) => !pinnedIds.has(entry.key)\n );\n return [...pinnedTop.map(asEntry), ...scroll, ...pinnedBottom.map(asEntry)];\n}\n","import type { KeyboardEvent as ReactKeyboardEvent } from \"react\";\n\nimport type { ColumnDef } from \"../types\";\nimport type { BatchEditingState } from \"./batchEditing\";\nimport {\n type CellEditCommit,\n type CellEditor,\n type EditableColumnLike,\n isCellEditable,\n isMultiSelectEditor,\n isSelectEditor,\n normalizeEditorOptions,\n readEditableCellValue,\n resolveCellEditor,\n resolveCommitValue,\n} from \"./cellEditing\";\nimport type { DirtyCellState } from \"./dirtyCells\";\nimport type { EditConflict, EditConflictState } from \"./editConflict\";\nimport type { EditLifecycle } from \"./editingEvents\";\nimport { observeEdit } from \"./editingEvents\";\nimport type { RowEditingState } from \"./rowEditing\";\nimport type {\n CellSaveState,\n CellSaveStatus,\n FailedCellSave,\n} from \"./saveState\";\nimport {\n beginCellEdit as beginEdit,\n type CellEditingState,\n} from \"./useCellEditing\";\nimport type { CellValidator, EditValidationState } from \"./validation\";\n\n/** Opt-in editing bundle from {@link TableChrome.editing}. */\nexport interface EditableCellEditing {\n /**\n * The per-cell change channel. Return a promise and the cell shows it is\n * saving until that promise settles, and shows why if it rejects.\n *\n * Absent when the host wants row-level commits only: the bundle still exists\n * (row mode needs it) and every cell stays display-only until a reader opens\n * the row.\n */\n onCellEdit?: (row: TRow, key: string, nextValue: unknown) => unknown;\n state: CellEditingState;\n /**\n * Validation, when the host declared any. A commit runs the validators first\n * and is dropped if one rejects — the editor stays open with the message on\n * it, so the reader fixes what they typed instead of losing it.\n */\n validation?: EditValidationState;\n /**\n * Save state, when the host's `onCellEdit` returns promises. Inert for a\n * host that saves synchronously.\n */\n saving?: CellSaveState;\n /** Dirty marks, when the host asked for them (`dirtyIndicators`). */\n dirty?: DirtyCellState;\n /**\n * Row-mode state, when the host armed it. While a row is open its cells render\n * row editors instead of the per-cell activate control.\n */\n rowEditing?: RowEditingState;\n /**\n * Batch state, when the host armed it. Every editable cell renders a field\n * and nothing reaches the host until the reader saves them all.\n */\n batch?: BatchEditingState;\n /** Lifecycle observers — fire from the same place the transition happens. */\n lifecycle?: EditLifecycle;\n /** Live-update conflict for the open editor, when one is being asked about. */\n conflict?: EditConflictState;\n /** Labels for the conflict notice — already resolved. */\n conflictLabels?: {\n message: string;\n keepMine: string;\n takeTheirs: string;\n theirsValue: (value: string) => string;\n };\n}\n\n/** Display / edit mode for one cell. */\nexport type EditableCellMode = \"display\" | \"activatable\" | \"editing\";\n\n/** Controller returned by {@link editableCellController}. */\nexport interface EditableCellController {\n mode: EditableCellMode;\n /** The validator's message for this cell, if it rejected the last commit. */\n error?: string;\n /** Whether an async validator is still deciding about this cell. */\n validating: boolean;\n /** What this cell's last save is doing: in flight, or failed. */\n saveStatus?: CellSaveStatus;\n /** Why this cell's last save failed, and what it takes to undo it. */\n saveFailure?: FailedCellSave;\n /** Whether this cell holds a change nobody has confirmed yet. */\n isDirty: boolean;\n /** Whether an undo can be offered — the host said how to perform one. */\n canRollback: boolean;\n /** Put the previous value back after a failed save. */\n rollback: () => void;\n /** Forget a failed save without restoring anything. */\n dismissFailure: () => void;\n /** Resolved editor when the column is editable; always set for activatable/editing. */\n editor: CellEditor | null;\n /** Normalized select options (empty for text/number). */\n selectOptions: ReturnType;\n draft: string;\n begin: () => void;\n setDraft: (value: string) => void;\n /** Commit the draft now, without waiting for Enter or a blur. */\n commit: () => void;\n /** Abandon the draft, exactly as Escape does. */\n cancel: () => void;\n /** Wire to the editor's keydown — Enter/Tab/Escape. */\n onEditorKeyDown: (event: {\n key: string;\n preventDefault: () => void;\n shiftKey?: boolean;\n }) => void;\n /** Commit on blur (click-away). No-op when not editing. */\n commitOnBlur: () => void;\n /**\n * A live row changed under this editor. Present only while the policy is\n * asking; Keep mine / Take theirs resolve it.\n */\n conflict?: EditConflict;\n /** Labels for the conflict notice. */\n conflictLabels?: {\n message: string;\n keepMine: string;\n takeTheirs: string;\n theirsValue: (value: string) => string;\n };\n /** Keep the draft. */\n keepConflict: () => void;\n /** Take the incoming value. */\n takeConflict: () => void;\n}\n\n/**\n * Derive the per-cell editing controller. When `editing` is omitted (host\n * did not pass `onCellEdit`), always returns `mode: \"display\"` — zero UI\n * change for tables that never opted in.\n */\nexport function editableCellController(options: {\n editing: EditableCellEditing | undefined;\n row: TRow;\n column: ColumnDef;\n rowId: string;\n rows: readonly TRow[];\n columns: readonly ColumnDef[];\n rowKey: (row: TRow) => string;\n}): EditableCellController {\n const { editing, row, column, rowId, rows, columns, rowKey } = options;\n\n const idle: EditableCellController = {\n mode: \"display\",\n validating: false,\n isDirty: false,\n canRollback: false,\n rollback: () => undefined,\n dismissFailure: () => undefined,\n editor: null,\n selectOptions: [],\n draft: \"\",\n begin: () => undefined,\n setDraft: () => undefined,\n commit: () => undefined,\n cancel: () => undefined,\n onEditorKeyDown: () => undefined,\n commitOnBlur: () => undefined,\n keepConflict: () => undefined,\n takeConflict: () => undefined,\n };\n\n // No per-cell channel means no per-cell editing, whatever else the bundle\n // carries: a cell that opened an editor with nowhere to send the value would\n // lose whatever the reader typed.\n if (!editing?.onCellEdit) return idle;\n const onCellEdit = editing.onCellEdit;\n\n const editor = resolveCellEditor(column);\n if (!editor || !isCellEditable(column, row)) return idle;\n\n // Both kinds of chooser carry options; only the number chosen differs.\n const selectOptions =\n isSelectEditor(editor) || isMultiSelectEditor(editor)\n ? normalizeEditorOptions(editor.options)\n : [];\n\n const { state, validation, saving, dirty } = editing;\n const isEditing = state.isActive(rowId, column.key);\n\n const validateCell = asCellValidator(column);\n // Nothing validates this cell, so the commit stays exactly as synchronous as\n // it has always been. A microtask on every Tab, paid by every table, to\n // support validators most tables never declare, is not a trade worth making.\n const gated =\n validation !== undefined &&\n (validateCell !== undefined || validation.hasRowValidator);\n\n /**\n * Hand a resolved value to the host, and watch whatever it hands back: a\n * promise means the value is still on its way somewhere, which is something\n * the reader cannot see unless the cell says so.\n */\n const sendToHost = (resolved: {\n row: TRow;\n column: EditableColumnLike;\n value: unknown;\n }) => {\n const result = onCellEdit(\n resolved.row,\n resolved.column.key,\n resolved.value\n );\n const columnKey = resolved.column.key;\n observeEdit(editing.lifecycle?.onEditCommit, {\n row: resolved.row,\n rowId,\n columnKey,\n value: resolved.value,\n previousValue: readEditableCellValue(resolved.row, resolved.column),\n unit: \"cell\",\n });\n // Changed, and not settled by anything the reader trusts yet.\n dirty?.mark(rowId, columnKey);\n if (!saving) return;\n void saving\n .track({\n rowId,\n columnKey,\n previous: resolved.row,\n attempted: resolved.value,\n previousValue: readEditableCellValue(resolved.row, resolved.column),\n result,\n })\n .then((saved) => {\n // The host agreeing is what settles a value, so the mark clears here and\n // nowhere else. A failed save keeps it: the value is still at risk until\n // the reader undoes it or tries again.\n if (saved) dirty?.confirm(rowId, columnKey);\n });\n };\n\n /** Send a commit straight through — the path for an ungated column. */\n const commitNow = (commit: CellEditCommit | null): boolean => {\n if (!commit) return false;\n const resolved = resolveCommitValue({ commit, rows, columns, rowKey });\n if (!resolved) return false;\n sendToHost(resolved);\n return true;\n };\n\n /**\n * Run the validators, then send the value if they allow it.\n *\n * Resolves to whether the host received it, so a Tab that advances can stop\n * short: moving on while this cell is rejected would put the cursor past the\n * message the reader needs to read.\n */\n const commitValidated = async (\n commit: CellEditCommit | null\n ): Promise => {\n if (!commit || !validation) return false;\n const resolved = resolveCommitValue({ commit, rows, columns, rowKey });\n if (!resolved) return false;\n // Hold the reader in the editor while the check runs — a cell that closes\n // and reopens on a rejection loses the caret, and an async check would\n // leave nothing on screen to mark busy.\n beginEdit(state, resolved.row, resolved.column, rowKey);\n state.setDraft(commit.draft);\n const verdict = await validation.check({\n target: { rowId: commit.rowId, columnKey: commit.columnKey },\n value: resolved.value,\n row: resolved.row,\n validateCell,\n });\n // A rejection leaves the editor exactly where it is, message attached.\n // A superseded check (`allowed: false` with no `error`) is silence: a\n // newer draft owns the cell and this one must not speak for it.\n if (!verdict.allowed) {\n if (verdict.error !== undefined) {\n observeEdit(editing.lifecycle?.onValidationFail, {\n row: resolved.row,\n rowId: commit.rowId,\n columnKey: commit.columnKey,\n value: resolved.value,\n previousValue: readEditableCellValue(resolved.row, resolved.column),\n unit: \"cell\",\n error: verdict.error,\n });\n }\n return false;\n }\n // Allowed: close the editor, then hand the value over.\n state.close();\n sendToHost(resolved);\n return true;\n };\n\n const beginNext = (target: { rowId: string; columnKey: string } | null) => {\n if (!target) return;\n const nextRow = rows.find((r) => rowKey(r) === target.rowId);\n const nextCol = columns.find((c) => c.key === target.columnKey);\n if (!nextRow || !nextCol) return;\n beginEdit(state, nextRow, nextCol, rowKey);\n };\n\n const liveConflict = editing.conflict?.isConflict(rowId, column.key)\n ? (editing.conflict.current ?? undefined)\n : undefined;\n let validationError = validation?.errorFor(rowId, column.key);\n if (validationError === undefined && isEditing) {\n validationError = validation?.rowErrorFor(rowId);\n }\n\n return {\n mode: isEditing ? \"editing\" : \"activatable\",\n // A row-level message has no cell of its own, so it shows under the cell\n // the reader just edited — where they are looking. A live conflict uses\n // the same channel: the message is what `aria-describedby` points at.\n error: liveConflict ? editing.conflictLabels?.message : validationError,\n validating: validation?.isValidating(rowId, column.key) ?? false,\n saveStatus: saving?.statusFor(rowId, column.key),\n saveFailure: saving?.failureFor(rowId, column.key),\n isDirty: dirty?.isDirty(rowId, column.key) ?? false,\n canRollback: saving?.canRollback ?? false,\n rollback: () => {\n saving?.rollback(rowId, column.key);\n // The value the reader typed is gone, so nothing is waiting on it.\n dirty?.confirm(rowId, column.key);\n },\n dismissFailure: () => {\n saving?.clear(rowId, column.key);\n },\n editor,\n selectOptions,\n draft: isEditing ? state.draft : \"\",\n begin: () => {\n beginEdit(state, row, column, rowKey);\n },\n setDraft: state.setDraft,\n commit: () => {\n if (!state.isActive(rowId, column.key)) return;\n if (editing.conflict?.isConflict(rowId, column.key)) return;\n const pending = state.commit();\n if (gated) void commitValidated(pending);\n else commitNow(pending);\n },\n cancel: () => {\n validation?.clear(rowId, column.key);\n state.cancel();\n },\n onEditorKeyDown: (event) => {\n // Enter / Tab would commit through the state machine, which does not\n // know about the ask. Hold them until the reader chooses; Escape still\n // throws the draft away.\n if (\n editing.conflict?.isConflict(rowId, column.key) &&\n (event.key === \"Enter\" || event.key === \"Tab\")\n ) {\n event.preventDefault();\n return;\n }\n const outcome = state.handleKeyDown(event, {\n rows,\n columns,\n rowKey: (r) => rowKey(r as TRow),\n });\n if (!outcome) return;\n if (outcome.action === \"cancel\") {\n validation?.clear(rowId, column.key);\n return;\n }\n const advance = () => {\n if (outcome.action === \"commit-advance\")\n beginNext(outcome.advanceTarget);\n };\n if (!gated) {\n if (commitNow(outcome.commit)) advance();\n return;\n }\n void commitValidated(outcome.commit).then((committed) => {\n if (committed) advance();\n });\n },\n commitOnBlur: () => {\n if (!state.isActive(rowId, column.key)) return;\n if (editing.conflict?.isConflict(rowId, column.key)) return;\n const commit = state.commit();\n if (gated) void commitValidated(commit);\n else commitNow(commit);\n },\n conflict: liveConflict,\n conflictLabels: liveConflict ? editing.conflictLabels : undefined,\n keepConflict: () => {\n editing.conflict?.keep();\n },\n takeConflict: () => {\n editing.conflict?.take();\n },\n };\n}\n\n/**\n * A column's own validator, if it declared one.\n *\n * Read off the column rather than passed in, so a validator lives beside the\n * `editor` and `parseValue` that produce the value it judges.\n */\nfunction asCellValidator(column: {\n validate?: (\n value: unknown,\n row: TRow\n ) => string | undefined | Promise;\n}): CellValidator | undefined {\n return column.validate;\n}\n\n/** Convenience: stop React keyboard events from bubbling to row click. */\nexport function stopCellEditKeyboard(\n event: Pick\n): void {\n event.stopPropagation();\n}\n\n/**\n * Attach as a `ref` (or kit `inputRef`) so the editor receives focus when the\n * cell enters edit mode — replaces the `autoFocus` attribute (axe/a11y).\n * Accepts DOM nodes and kit refs that expose `.focus()` (e.g. antd InputRef).\n */\nexport function focusEditorOnMount(node: { focus: () => void } | null): void {\n node?.focus();\n}\n\n/**\n * Whether any cell in a row holds a change nobody has confirmed.\n *\n * Read by every adapter's row so the mark exists at both scales: a reader\n * scanning a long table sees which rows are unsettled without hunting for the\n * cell inside them.\n *\n * @typeParam TRow - The row type.\n * @param editing - The editing bundle from the chrome.\n * @param rowId - The row's stable id.\n * @returns Whether to mark the row.\n */\nexport function rowIsDirty(\n editing: EditableCellEditing | undefined,\n rowId: string\n): boolean {\n return editing?.dirty?.isRowDirty(rowId) ?? false;\n}\n\n/**\n * Memo digest for one desktop/card row: `null` when editing is off (host\n * never passed `onCellEdit`); empty string when this row is idle; otherwise\n * `columnKey:draft` so only the active edit row re-renders on keystrokes.\n */\nexport function rowEditingSignature(\n editing: EditableCellEditing | undefined,\n rowId: string\n): string | null {\n if (!editing) return null;\n const { active, draft } = editing.state;\n // A validation message belongs to a ROW that may not hold the active editor:\n // a cross-field rule marks the cell it points at, and that row has to repaint\n // to show it. Left out, a rejected commit paints nothing.\n const marked = editing.validation?.rowHasError(rowId) ?? false;\n const busy = editing.validation?.isValidating(rowId, active?.columnKey ?? \"\");\n // A save is in flight or has failed on a cell of this row, which may hold no\n // editor at all by then — the reader closed it and moved on.\n const save = editing.saving?.signature ?? \"\";\n const rowSave = save.includes(`${rowId} `) ? save : \"\";\n // A dirty mark belongs to the row too, and outlives the editor that made it.\n const marks = editing.dirty?.signature ?? \"\";\n const rowMarks = marks.includes(`${rowId} `) ? marks : \"\";\n // Row mode replaces every cell in the open row with an editor, so the row it\n // belongs to has to repaint — including on every keystroke in any field.\n const rowMode = editing.rowEditing;\n const rowDrafts =\n rowMode?.activeRowId === rowId ? (rowMode.signature ?? \"\") : \"\";\n // A batch holds drafts for many rows at once, so each row watches its own\n // slice of the digest — without it a typed cell never repaints.\n const batchAll = editing.batch?.signature ?? \"\";\n const batchRow =\n batchAll.split(\";\").find((entry) => entry.startsWith(`${rowId}:`)) ?? \"\";\n // A live conflict is asked on the open editor. Left out, the row memo\n // sees the same draft and never paints Keep mine / Take theirs.\n const live = editing.conflict?.current;\n const conflictMark =\n live?.rowId === rowId\n ? `conflict:${live.columnKey}:${live.incomingValue}`\n : \"\";\n if (active?.rowId !== rowId) {\n const base = `${rowSave}${rowMarks}${rowDrafts}${batchRow}${conflictMark}`;\n return marked ? `invalid${base}` : base;\n }\n const message = editing.validation?.errorFor(rowId, active.columnKey) ?? \"\";\n return `${active.columnKey}:${draft}:${message}:${busy === true ? \"1\" : \"\"}${rowSave}${rowMarks}${rowDrafts}${batchRow}${conflictMark}`;\n}\n","/**\n * A cell inside a row that is being edited as one unit, and the controls that\n * end that edit.\n *\n * Row mode reuses everything cell mode already has — the same editor set, the\n * same validation ARIA, the same custom-editor contract — so the only thing that\n * differs is where the draft lives and when it reaches the host. Both live here\n * rather than in nine adapters, because a second copy of \"which editor does this\n * column want\" is a second place for the answer to drift.\n */\nimport type { ReactElement, ReactNode } from \"react\";\n\nimport type { TableLabels } from \"../types\";\nimport type { BatchEditingState } from \"./batchEditing\";\nimport {\n type CellEditor,\n type EditableColumnLike,\n isCustomEditor,\n normalizeEditorOptions,\n resolveCellEditor,\n} from \"./cellEditing\";\nimport { focusEditorOnMount } from \"./editableCellController\";\nimport type { EditableCellEditorCtrl } from \"./EditableCellGate\";\nimport type { RowEditingState } from \"./rowEditing\";\n\n/** Props for {@link RowEditCell}. */\nexport interface RowEditCellProps {\n /** The row-editing state from the chrome. */\n rowEditing: RowEditingState;\n /** The column this cell belongs to. */\n column: EditableColumnLike;\n /** The cell's display content, for a column that is not editable. */\n display: ReactElement | string | number | null;\n /** Accessible name for the editor (`labels.editCell`). */\n editLabel: string;\n /**\n * Whether this is the first editable column of the row, and so the field the\n * table hands focus to when the row opens. Every field calling focus on mount\n * would leave the reader at the last column of the row they just opened.\n *\n * Not the DOM's `autoFocus`: focus moves because a reader asked to edit this\n * row, which is the case the accessibility guidance carves out.\n */\n takesFocus: boolean;\n /**\n * Render the kit's own editor from a controller — the same callback shape the\n * cell gate uses, so a kit writes one editor and both modes use it.\n */\n renderEditor: (ctrl: EditableCellEditorCtrl) => ReactElement;\n}\n\n/**\n * One cell of a row being edited: the kit's editor bound to the row's draft, or\n * the plain display when the column is not editable.\n *\n * @typeParam TRow - The row type.\n * @param props - See {@link RowEditCellProps}.\n * @returns The editor, or the display content.\n */\nexport function RowEditCell({\n rowEditing,\n column,\n display,\n editLabel,\n takesFocus,\n renderEditor,\n}: Readonly>): ReactElement {\n const editor = resolveCellEditor(column);\n if (!editor) return <>{display};\n const focusRef = takesFocus ? focusEditorOnMount : () => undefined;\n\n const ctrl: EditableCellEditorCtrl = {\n draft: rowEditing.draftFor(column.key),\n setDraft: (value) => {\n rowEditing.setDraft(column.key, value);\n },\n // Enter saves the whole row, Escape cancels it: in row mode the unit is the\n // row, so a per-cell commit would be a different feature wearing this one's\n // keys.\n onEditorKeyDown: (event) => {\n if (event.key === \"Enter\") {\n event.preventDefault();\n rowEditing.save();\n } else if (event.key === \"Escape\") {\n event.preventDefault();\n rowEditing.cancel();\n }\n },\n // Nothing commits on blur: the reader is moving between fields of one form.\n commitOnBlur: () => undefined,\n editor,\n selectOptions: selectOptionsFor(editor),\n validating: false,\n errorId: `adapttable-row-edit-${column.key}`,\n focusRef,\n };\n\n if (isCustomEditor(editor)) {\n return editor.render({\n draft: ctrl.draft,\n setDraft: ctrl.setDraft,\n commit: rowEditing.save,\n cancel: rowEditing.cancel,\n onKeyDown: ctrl.onEditorKeyDown,\n onBlur: ctrl.commitOnBlur,\n focusRef,\n label: editLabel,\n validating: false,\n errorId: ctrl.errorId,\n });\n }\n return renderEditor(ctrl);\n}\n\n/** The options a chooser editor carries, normalized. */\nfunction selectOptionsFor(editor: CellEditor) {\n if (\n typeof editor === \"object\" &&\n (editor.type === \"select\" || editor.type === \"multi-select\")\n ) {\n return normalizeEditorOptions(editor.options);\n }\n return [];\n}\n\n/** Props for {@link rowEditControls}. */\nexport interface RowEditControlsOptions {\n /** The row-editing state from the chrome. */\n rowEditing: RowEditingState;\n /** The row this control set belongs to. */\n row: TRow;\n /** Its stable id. */\n rowId: string;\n /** Labels; falls back to the built-in English. */\n labels?: TableLabels;\n}\n\n/** What a kit needs to render the row's edit / save / cancel controls. */\nexport interface RowEditControls {\n /** Whether this row is the one being edited. */\n editing: boolean;\n /** Open this row for editing. */\n begin: () => void;\n /** Hand the host everything that changed. */\n save: () => void;\n /** Throw the drafts away. */\n cancel: () => void;\n /** Accessible name for the control that opens the row. */\n editLabel: string;\n /** Accessible name for save. */\n saveLabel: string;\n /** Accessible name for cancel. */\n cancelLabel: string;\n /** Whether anything actually changed — a save with nothing to save is inert. */\n dirty: boolean;\n}\n\n/**\n * The row-mode controls, resolved.\n *\n * A helper rather than a component because each kit renders its own buttons —\n * what is shared is which ones exist, what they are called, and what they do.\n *\n * @typeParam TRow - The row type.\n * @param options - See {@link RowEditControlsOptions}.\n * @returns The controls to render.\n */\nexport function rowEditControls({\n rowEditing,\n row,\n rowId,\n labels,\n}: Readonly>): RowEditControls {\n return {\n editing: rowEditing.isEditing(rowId),\n begin: () => {\n rowEditing.begin(row, rowId);\n },\n save: rowEditing.save,\n cancel: rowEditing.cancel,\n editLabel: labels?.editRow ?? \"Edit row\",\n saveLabel: labels?.saveRow ?? \"Save row\",\n cancelLabel: labels?.cancel ?? \"Cancel\",\n dirty: rowEditing.isDirty,\n };\n}\n\n/** Props for an adapter {@link RowEditActions} — no slots on the public API. */\nexport interface RowEditActionsProps<\n TRow,\n> extends RowEditControlsOptions {\n /** Class for the control group. */\n className?: string;\n /** Class for each button. */\n buttonClassName?: string;\n}\n\n/** Kit button the row-edit chrome calls. */\nexport interface RowEditButtonProps {\n readonly label: string;\n readonly part: string;\n readonly className?: string;\n readonly onClick: (event: { stopPropagation: () => void }) => void;\n}\n\n/** Adapter-supplied controls for {@link RowEditActionsChrome}. */\nexport interface RowEditActionsSlots {\n readonly Button: (props: RowEditButtonProps) => ReactNode;\n}\n\n/** Props for {@link RowEditActionsChrome}. */\nexport interface RowEditActionsChromeProps<\n TRow,\n> extends RowEditActionsProps {\n readonly slots: RowEditActionsSlots;\n}\n\n/**\n * The row's edit / save / cancel controls.\n *\n * Layout and the shared {@link rowEditControls} contract — adapters pass the\n * buttons the end user clicks. A kit with a strong opinion about its buttons\n * can still use {@link rowEditControls} directly instead.\n *\n * @typeParam TRow - The row type.\n * @param props - See {@link RowEditActionsChromeProps}.\n * @returns The controls for this row.\n */\nexport function RowEditActionsChrome({\n className,\n buttonClassName,\n slots,\n ...options\n}: Readonly>): ReactElement {\n const controls = rowEditControls(options);\n const Button = slots.Button;\n if (!controls.editing) {\n return (\n {\n event.stopPropagation();\n controls.begin();\n }}\n />\n );\n }\n return (\n \n {\n event.stopPropagation();\n controls.save();\n }}\n />\n {\n event.stopPropagation();\n controls.cancel();\n }}\n />\n \n );\n}\n\n/** Props for {@link BatchEditCell}. */\nexport interface BatchEditCellProps {\n /** The batch state from the chrome. */\n batch: BatchEditingState;\n /** The row this cell belongs to. */\n row: TRow;\n /** Its stable id. */\n rowId: string;\n /** The column this cell belongs to. */\n column: EditableColumnLike;\n /** The cell's display content, for a column that is not editable. */\n display: ReactElement | string | number | null;\n /** Accessible name for the editor (`labels.editCell`). */\n editLabel: string;\n /** Render the kit's own editor from a controller. */\n renderEditor: (ctrl: EditableCellEditorCtrl) => ReactElement;\n}\n\n/**\n * One cell while a batch is being edited: always a field, never an activate\n * control.\n *\n * Batch mode's premise is that the reader is walking a list correcting values,\n * so making them open each cell first would be the friction the mode exists to\n * remove. A changed cell carries `data-changed`, which is how the reader finds\n * their way back to what they touched.\n *\n * @typeParam TRow - The row type.\n * @param props - See {@link BatchEditCellProps}.\n * @returns The field, or the display content.\n */\nexport function BatchEditCell({\n batch,\n row,\n rowId,\n column,\n display,\n editLabel,\n renderEditor,\n}: Readonly>): ReactElement {\n const editor = resolveCellEditor(column);\n if (!editor) return <>{display};\n\n const ctrl: EditableCellEditorCtrl = {\n draft: batch.draftFor(row, rowId, column.key),\n setDraft: (value) => {\n batch.setDraft(row, rowId, column.key, value);\n },\n // No key ends a batch: the reader is moving through a list, and Enter would\n // send everything they have not finished.\n onEditorKeyDown: () => undefined,\n commitOnBlur: () => undefined,\n editor,\n selectOptions: selectOptionsFor(editor),\n validating: false,\n errorId: `adapttable-batch-edit-${rowId}-${column.key}`,\n // Nothing steals focus: every cell is a field, and the reader chose where\n // to start.\n focusRef: () => undefined,\n };\n\n if (isCustomEditor(editor)) {\n return editor.render({\n draft: ctrl.draft,\n setDraft: ctrl.setDraft,\n commit: () => undefined,\n cancel: () => {\n batch.cancelRow(rowId);\n },\n onKeyDown: ctrl.onEditorKeyDown,\n onBlur: ctrl.commitOnBlur,\n focusRef: ctrl.focusRef,\n label: editLabel,\n validating: false,\n errorId: ctrl.errorId,\n });\n }\n return (\n \n {renderEditor(ctrl)}\n \n );\n}\n\n/** Props for an adapter {@link BatchEditBar} — no slots on the public API. */\nexport interface BatchEditBarProps {\n /** The batch state from the chrome. */\n batch: BatchEditingState;\n /** Labels; falls back to the built-in English. */\n labels?: TableLabels;\n /** Class for the bar. */\n className?: string;\n /** Class for each button. */\n buttonClassName?: string;\n}\n\n/** Kit button the batch-edit bar calls. */\nexport interface BatchEditButtonProps {\n readonly label: string;\n readonly part: string;\n readonly className?: string;\n readonly onClick: () => void;\n}\n\n/** Adapter-supplied controls for {@link BatchEditBarChrome}. */\nexport interface BatchEditBarSlots {\n readonly Button: (props: BatchEditButtonProps) => ReactNode;\n}\n\n/** Props for {@link BatchEditBarChrome}. */\nexport interface BatchEditBarChromeProps extends BatchEditBarProps {\n readonly slots: BatchEditBarSlots;\n}\n\n/**\n * The bar that ends a batch: how many rows are waiting, save all, cancel all.\n *\n * Rendered only while something is pending — a bar that is always there says\n * the table is in a mode, when what matters is that there are unsaved changes.\n *\n * @typeParam TRow - The row type.\n * @param props - See {@link BatchEditBarChromeProps}.\n * @returns The bar, or nothing.\n */\nexport function BatchEditBarChrome({\n batch,\n labels,\n className,\n buttonClassName,\n slots,\n}: Readonly>): ReactElement | null {\n if (!batch.pending) return null;\n const count = (labels?.pendingRows ?? defaultPendingRows)(batch.count);\n const Button = slots.Button;\n return (\n \n {count}\n \n \n \n );\n}\n\n/** \"3 unsaved rows\" — replaceable through `labels.pendingRows`. */\nfunction defaultPendingRows(count: number): string {\n return count === 1 ? \"1 unsaved row\" : `${String(count)} unsaved rows`;\n}\n","import {\n type ReactElement,\n type ReactNode,\n useLayoutEffect,\n useRef,\n} from \"react\";\n\nimport type { ColumnDef } from \"../types\";\nimport { booleanDraft, formatMultiDraft, isCustomEditor } from \"./cellEditing\";\nimport {\n editableCellController,\n type EditableCellEditing,\n focusEditorOnMount,\n stopCellEditKeyboard,\n} from \"./editableCellController\";\nimport { BatchEditCell, RowEditCell } from \"./RowEditGate\";\n\n/** Props for a kit-native editor while a cell is active. */\nexport interface EditableCellEditorCtrl {\n draft: string;\n setDraft: (value: string) => void;\n onEditorKeyDown: (event: {\n key: string;\n preventDefault: () => void;\n shiftKey?: boolean;\n }) => void;\n commitOnBlur: () => void;\n editor: NonNullable[\"editor\"]>;\n selectOptions: ReturnType[\"selectOptions\"];\n /**\n * A validator's message for this cell, when the last commit was rejected.\n * Wire it to the kit's own error surface (Mantine's `error`, MUI's\n * `helperText`, …) — and it is on the DOM either way, see `errorId`.\n */\n error?: string;\n /** Whether an async validator is still deciding. */\n validating: boolean;\n /**\n * `id` of the element holding the message. Put it on the editor's\n * `aria-describedby` so the message is announced with the field, and set\n * `aria-invalid` when `error` is set.\n */\n errorId: string;\n /**\n * Attach as the editor's `ref` so the table decides what takes focus.\n *\n * In cell mode that is this editor, every time. In row mode a whole row opens\n * at once, and only the FIRST field should take focus — nine editors each\n * calling focus on mount would leave the reader at the last column of the row\n * they just opened.\n */\n focusRef: (node: { focus: () => void } | null) => void;\n /** A live row changed under this editor. */\n conflict?: boolean;\n}\n\n/**\n * Whether a column is the first editable one — the field a row edit focuses.\n *\n * By column order rather than by which cell renders first, so the answer is the\n * same in a windowed body and in a reordered one.\n */\nfunction isFirstEditableColumn(\n columns: readonly { key: string; editable?: unknown }[],\n key: string\n): boolean {\n const first = columns.find(\n (column) => column.editable !== undefined && column.editable !== false\n );\n return first?.key === key;\n}\n\n/**\n * Opt-in cell wrapper: plain display when editing is off; double-click /\n * Enter / F2 to activate; kit supplies the editor via `renderEditor`.\n *\n * When `editing` is omitted this is a pure pass-through of `display` —\n * zero DOM / behavior change for tables that never opted into cell edit.\n */\nexport interface EditableCellGateProps {\n readonly editing: EditableCellEditing | undefined;\n readonly row: TRow;\n readonly column: ColumnDef;\n readonly rowId: string;\n readonly rows: readonly TRow[];\n readonly columns: readonly ColumnDef[];\n readonly rowKey: (row: TRow) => string;\n /** Accessible name for the activate control. */\n readonly editLabel: string;\n /** Optional class for the activate button (adapters' styling hook). */\n readonly activateClassName?: string;\n /** Optional class for the validation message (adapters' styling hook). */\n readonly errorClassName?: string;\n /** Optional class for a failed save's message. */\n readonly saveErrorClassName?: string;\n /** Optional class for the undo control beside it. */\n readonly rollbackClassName?: string;\n /**\n * Label for the undo control a failed save offers (`labels.undoEdit`). Omit\n * it and the message shows without one — right for a table that refetches\n * rather than rolling back.\n */\n readonly undoLabel?: string;\n /**\n * Set by a kit whose own input renders the message — Mantine's `error`, MUI's\n * `helperText`. Those components own the input's `aria-describedby`, so a\n * second copy of the text would be both duplicated in the DOM and announced\n * twice. The gate then renders no message of its own and leaves the ARIA to\n * the kit.\n */\n readonly kitRendersError?: boolean;\n readonly display: ReactNode;\n /**\n * Kit-native editor. Only called while this cell is the active edit.\n * Wire `value`/`onChange`/`onKeyDown`/`onBlur` from the controller.\n */\n readonly renderEditor: (ctrl: EditableCellEditorCtrl) => ReactElement;\n /** Kit activate control and conflict / undo buttons. */\n readonly slots: EditableCellSlots;\n}\n\n/** Kit activate control the gate calls while the cell is idle. */\nexport interface EditableCellActivateProps {\n readonly title: string;\n readonly className?: string;\n readonly saveStatus: string | undefined;\n readonly dirty: boolean;\n readonly activateRef: (node: HTMLButtonElement | null) => void;\n readonly display: ReactNode;\n readonly onDoubleClick: (event: {\n preventDefault: () => void;\n stopPropagation: () => void;\n }) => void;\n readonly onClick: (event: { stopPropagation: () => void }) => void;\n readonly onKeyDown: (event: {\n key: string;\n preventDefault: () => void;\n stopPropagation: () => void;\n }) => void;\n}\n\n/** Kit button the gate calls for conflict choices and undo. */\nexport interface EditableCellButtonProps {\n readonly label: string;\n readonly part: string;\n readonly className?: string;\n readonly onMouseDown?: (event: { preventDefault: () => void }) => void;\n readonly onClick: (event: { stopPropagation: () => void }) => void;\n}\n\n/** Adapter-supplied controls for {@link EditableCellGate}. */\nexport interface EditableCellSlots {\n readonly Activate: (props: EditableCellActivateProps) => ReactNode;\n readonly Button: (props: EditableCellButtonProps) => ReactNode;\n}\n\n/**\n * The ARIA a kit's editor needs when validation is in play.\n *\n * Spread onto the input or select: invalid marks the field, `describedby`\n * points at the message so it is read WITH the field rather than announced\n * once and lost, and busy says an async check is still deciding.\n *\n * @param ctrl - The editor controller the gate handed the kit.\n * @returns Attributes to spread; empty while the value is fine.\n */\nexport function editorValidationProps(ctrl: EditableCellEditorCtrl): {\n \"aria-invalid\"?: true;\n \"aria-describedby\"?: string;\n \"aria-busy\"?: true;\n \"data-conflict\"?: \"\";\n} {\n return {\n \"aria-invalid\": ctrl.error === undefined ? undefined : true,\n \"aria-describedby\": ctrl.error === undefined ? undefined : ctrl.errorId,\n \"aria-busy\": ctrl.validating ? true : undefined,\n \"data-conflict\": ctrl.conflict === true ? \"\" : undefined,\n };\n}\n\n/**\n * Busy and conflict marks, for a kit whose own input owns `aria-invalid`\n * (Mantine, MUI). `data-conflict` still belongs on the field so the same\n * selector works on every kit; `aria-describedby` points at the notice\n * while one is up.\n *\n * @param ctrl - The editor controller the gate handed the kit.\n * @returns Attributes to spread; empty unless a check is running or a\n * conflict is being asked.\n */\nexport function editorBusyProps(ctrl: EditableCellEditorCtrl): {\n \"aria-busy\"?: true;\n \"aria-describedby\"?: string;\n \"data-conflict\"?: \"\";\n} {\n const describedBy =\n ctrl.conflict === true ? { \"aria-describedby\": ctrl.errorId } : {};\n return {\n \"aria-busy\": ctrl.validating ? true : undefined,\n ...describedBy,\n \"data-conflict\": ctrl.conflict === true ? \"\" : undefined,\n };\n}\n\n/** Keep mine / Take theirs — same channel as a validation message. */\nfunction ConflictNotice(\n props: Readonly<{\n ctrl: ReturnType;\n errorId: string;\n errorClassName?: string;\n slots: EditableCellSlots;\n }>\n): ReactElement | null {\n \"use no memo\";\n const { ctrl, errorId, errorClassName, slots } = props;\n const Button = slots.Button;\n if (ctrl.conflict === undefined || ctrl.conflictLabels === undefined) {\n return null;\n }\n const holdFocus = (event: { preventDefault: () => void }) => {\n event.preventDefault();\n };\n return (\n \n {ctrl.conflictLabels.message}\n \n {ctrl.conflictLabels.theirsValue(ctrl.conflict.incomingValue)}\n \n {\n event.stopPropagation();\n ctrl.keepConflict();\n }}\n />\n {\n event.stopPropagation();\n ctrl.takeConflict();\n }}\n />\n \n );\n}\n\n/**\n * Toggle a checkbox editor and commit in the same gesture.\n *\n * A checkbox has one gesture, so waiting for Enter or a blur would leave the\n * reader looking at a ticked box that has changed nothing. Safe to call\n * synchronously: the editing state writes its draft ref in the same tick, so the\n * commit that follows sees the new value.\n *\n * @param ctrl - The editor controller the gate handed the kit.\n * @param checked - The box's new state.\n */\nexport function commitBooleanDraft(\n ctrl: EditableCellEditorCtrl,\n checked: boolean\n): void {\n ctrl.setDraft(booleanDraft(checked));\n ctrl.commitOnBlur();\n}\n\n/**\n * The draft for a native `