bcell library

A minimal data grid for Flutter with a pluto_grid-shaped API.

Classes

BCellChart
A live chart over a BCellGrid's data — a companion widget in the same calling shape as BCellPagination/BCellSheetTabBar: construct it with the state manager from onLoaded and place it anywhere.
BCellColumn
Describes one column of a BCellGrid: its header title, the key used to look up cells in each row, its data type, and its width.
BCellColumnRendererContext
Passed to BCellColumn.renderer to build a custom cell widget. Mirrors pluto_grid's PlutoColumnRendererContext shape.
BCellColumnType
The data type of a BCellColumn.
BCellColumnTypeDate
BCellColumnTypeNumber
BCellColumnTypeText
BCellConditionalFormat
Conditional-formatting visuals for a numeric column (spec cat 12): color scale, data bar, icon set. Each factory returns a helper whose toRenderer produces a Widget Function(BCellColumnRendererContext) you assign to BCellColumn.renderer — it does not add a new column API or touch the state-manager hot path.
BCellFontController
Holds a font TextStyle and notifies when it changes, so one controller can re-font every BCell widget under a BCellFontScope at once.
BCellFontScope
Broadcasts a font to every descendant BCell widget. Wrap a subtree once and the grids, pagers, and tab bars below all use the controller's font unless they set their own font:. Calling BCellFontController.setFont re-fonts every one of them live — a single place to theme all BCell text.
BCellGrid
A data grid with sortable, resizable columns and tap-to-edit cells. The calling structure mirrors pluto_grid.
BCellGridColumnSizeConfig
Column sizing options for BCellGrid (mirrors pluto_grid's PlutoGridColumnSizeConfig).
BCellGridConfiguration
Visual configuration for BCellGrid.
BCellGridEvent
Marker interface for anything that travels on the grid's event bus (BCellGridEventManager). The user-facing events (BCellGridOnLoadedEvent, BCellGridOnChangedEvent, BCellGridOnSelectedEvent, BCellGridOnSortedEvent) all implement it, so one subscription sees the whole stream — filter with is / whereType for a specific kind.
BCellGridEventManager
A single broadcast stream of every BCellGridEvent the grid emits — the one-place event bus the per-callback API (onChanged/onSelected/… ) does not offer. Mirrors pluto_grid's PlutoGridEventManager calling shape (addEvent / listener / dispose), but is backed by the Dart stdlib StreamController.broadcast() rather than rxdart's PublishSubject — no new dependency.
BCellGridOnChangedEvent
Event passed to BCellGrid.onChanged when a cell value changes.
BCellGridOnLoadedEvent
Event passed to BCellGrid.onLoaded once the grid is ready.
BCellGridOnSelectedEvent
Event passed to BCellGrid.onSelected when the selected cell changes. All fields are null when the selection was cleared.
BCellGridOnSortedEvent
Event passed to BCellGrid.onSorted when a column sort changes.
BCellGridStateManager
Holds the grid's columns, rows, selection, and sort state, and notifies listeners on change.
BCellGridStyleConfig
Style options for BCellGrid.
Renders a URL cell as styled, tappable link text (spec cat 3, hyperlink half). Like BCellConditionalFormat, the factory returns a helper whose toRenderer produces a Widget Function(BCellColumnRendererContext) you assign to BCellColumn.renderer — no new column type, no state-manager hot-path change.
BCellMergeConflict
One cell where both copies changed the same value differently during a BCellWorkbookShare.mergeChanges. The local value won; theirs is what the other copy wanted, so a host app can offer "keep / take theirs".
BCellPagination
Page navigation for a BCellGrid, same calling shape as pluto_grid's PlutoPagination: construct it with the state manager from onLoaded and place it anywhere (typically below the grid).
BCellPivotTable
Result of BCellPivot.pivot: a rows × columns matrix of aggregated values, plus row/column/grand totals. Row and column keys are the distinct values of the pivot's row/column field in first-appearance order.
BCellRichText
Rich text in a cell (spec cat 3): a cell value that is a list of styled BCellTextRuns, rendered as one line of mixed styles (Text.rich).
BCellRichTextColumn
Renderer helper returned by BCellRichText.column; call toRenderer to get the Widget Function(BCellColumnRendererContext) for BCellColumn.renderer. Stateless — the styling lives in each cell's BCellRichText value.
BCellRow
One row of grid data: a map of column field to BCellValue.
BCellSheet
One named sheet in a BCellWorkbook: a title plus the columns and rows that make up a single BCellGrid. A dumb data holder — mutating its contents does not notify anyone; go through the owning BCellWorkbook (or the grid's state manager once the sheet is displayed).
BCellSheetTabBar
A horizontal strip of sheet tabs for a BCellWorkbook: one tab per sheet, the active one highlighted, tapping switches the active sheet. Listens to the workbook, so it rebuilds when sheets are added, removed, renamed, or the active sheet changes.
BCellSheetTabBarStyleConfig
Style options for BCellSheetTabBar. Colors and text styles left null are resolved from the surrounding ThemeData (same convention as BCellGridStyleConfig), so the tab strip follows the app theme and dark mode automatically.
BCellStyle
Per-cell visual override returned by BCellColumn.cellStyle for conditional formatting (e.g. red text for negatives, a highlight band). Null fields fall back to the grid's defaults; selection/range highlight still paints on top, so a formatted cell stays visibly selectable.
BCellTextRun
One styled run of text inside a BCellRichText cell value.
BCellValue
A single cell of a BCellRow, keyed by its column's field.
BCellWorkbook
An ordered collection of named BCellSheets with one active sheet. pluto_grid has no workbook concept, so this is BCell-native: a small ChangeNotifier that a sheet switcher and a grid listen to. It owns no grid state — swapping the active sheet just changes which sheet's columns and rows feed a fresh grid, so the grid state manager's hot path is untouched.
BCellWorkbookVersion
One saved snapshot of a BCellWorkbook (spec: version history).
BCellWorkbookView
Shows the active sheet of a BCellWorkbook as a BCellGrid, rebuilding the grid whenever the active sheet changes.

Enums

BCellAutoSizeMode
How columns adapt to the grid's viewport width (same shape as pluto_grid's PlutoAutoSizeMode).
BCellChartType
Chart kind for BCellChart.
BCellColumnFrozen
Where a column is frozen (pinned). Mirrors pluto_grid's PlutoColumnFrozen: start pins the column to the left, end to the right; both stay put while the middle body scrolls horizontally.
BCellColumnSort
The sort state of a BCellColumn.
BCellGridMode
How the grid behaves for editing/selection. Mirrors pluto_grid's PlutoGridMode, renamed. normal is the default; readOnly blocks all cell edits (used for a protected workbook sheet).
BCellMoveDirection
Direction for BCellGridStateManager.moveCurrentCell (same shape as pluto_grid's PlutoMoveDirection).
BCellPivotAgg
How a pivot cell aggregates the value field's numbers.
BCellResizeMode
How dragging a column's resize handle behaves (same shape as pluto_grid's PlutoResizeMode).

Extensions

BCellAggregate on BCellGridStateManager
Column aggregations (sum / average / min / max / count) over filtered rows.
BCellClipboard on BCellGridStateManager
Clipboard copy for a BCellGridStateManager. Lives in an extension so the flutter/services dependency stays out of the core state manager.
BCellCut on BCellGridStateManager
Clipboard cut for a BCellGridStateManager. Copies the current cell's value then clears it via changeCellValue, which is a no-op on read-only columns — so the copy still happens but the value stays. That is acceptable behaviour until range selection adds multi-cell cut.
BCellFlashFill on BCellGridStateManager
Excel-style flash fill: infers a transform from the seed cell(s) of a column against the other columns of the same row, then applies it to the empty cells below. The classic case is splitting/combining columns — e.g. a "Full name" column and a seed "John" in the next column detects "the part before the first space" and fills the rest.
BCellMarkdownExport on BCellGridStateManager
GitHub-flavored Markdown table export for a BCellGridStateManager. Same selection as other export plugins: visible columns, filtered rows, all pages.
BCellNamedRange on BCellGridStateManager
Named ranges / defined names (spec cat 10): map a name to an A1 ref or range so formulas can say =SUM(SALES) or =PRICE*QTY instead of =SUM(A2:A10).
BCellNotes on BCellGridStateManager
Text notes attached to individual cells (spec: Comment / Comments). Store-only — no popup UI. Read and write notes via the manager extension.
BCellPaste on BCellGridStateManager
Clipboard paste for a BCellGridStateManager (spec: Clipboard / Paste). Pairs with copySelectionToClipboard in bcell_clipboard.dart.
BCellPdfExport on BCellGridStateManager
PDF export for a BCellGridStateManager, mirroring the CSV export: visible columns only, all filtered rows (paging is ignored — an export covers the whole filtered set, not just the current page).
BCellPivot on BCellGridStateManager
Pivot-table aggregation over the grid's filtered rows — a pure read, in the same shape as BCellAggregate. Groups rowsForExport by a row field and a column field and aggregates a value field into each cell.
BCellRowSelection on BCellGridStateManager
Checkbox-style multi-row selection for a BCellGridStateManager (spec: Selection / multi-select). Independent of the cell selection.
BCellSeriesFill on BCellGridStateManager
Excel-style series fill: extends a pattern in the seed cells down a range instead of copying one value (1,2 → 3,4,5; dates step by a day).
BCellStructuredRef on BCellGridStateManager
Structured (table-column) references (spec cat 10): a formula can name a column with [Title] and get that column's data range, e.g. =SUM([Sales]) instead of =SUM(C1:C40). The bracketed name matches a visible column's title (case-insensitive); it resolves live to the column's A1 range over the current displayed rows, so filtering/paging and row add/remove keep it correct.
BCellTableExport on BCellGridStateManager
TSV and HTML-table export for a BCellGridStateManager (spec: Import/Export). Same selection as toCsv/toJson: visible columns, filtered rows, all pages.
BCellTableImport on BCellGridStateManager
TSV, CSV, HTML-table, and Markdown-table import for a BCellGridStateManager (spec: Import/Export). The inverse of toTsv/toCsv/toHtml/toMarkdown: parses a text block and appends it as rows, mapping fields left-to-right onto BCellGridStateManager.visibleColumns (same column set the exports emit, so a round-trip lines up).
BCellWorkbookCrypto on BCellWorkbook
Encrypted file form of a BCellWorkbook (spec: workbook chrome — file encryption). BCellWorkbookCrypto.toEncryptedBytes seals the BCellWorkbook.toJson snapshot with a password; decryptWorkbook / BCellWorkbookCrypto.loadEncryptedBytes open it again. AES-256-GCM (authenticated — a flipped byte or wrong password throws BCellDecryptException, never yields garbage) with the key derived via PBKDF2-HMAC-SHA256 over a random per-file salt.
BCellWorkbookHistory on BCellWorkbook
Version history for a BCellWorkbook (spec: workbook chrome — Excel's "Version History"): named, timestamped snapshots you can restore, built on the existing JSON persistence (BCellWorkbook.toJson to snapshot, BCellWorkbook.loadJson to restore in place).
BCellWorkbookShare on BCellWorkbook
Shared-workbook merge (spec: workbook chrome — Excel's "Compare and Merge Workbooks"): two people edit copies of the same workbook, then one calls mergeChanges with the common-ancestor snapshot and the other copy's snapshot to fold the other copy's edits into this workbook.
BCellXlsxExport on BCellGridStateManager
XLSX (Excel binary) import/export for a BCellGridStateManager (spec: Import/Export), backed by the excel package. Same column/row selection as the text exports: BCellGridStateManager.visibleColumns as the header row, BCellGridStateManager.rowsForExport (filtered, all pages) as data.
BCellXmlExport on BCellGridStateManager
BCellXmlImport on BCellGridStateManager
XML-table import for a BCellGridStateManager: the inverse of toXml in bcell_xml_export.dart. Each <row> maps its child elements BY TAG NAME onto BCellGridStateManager.visibleColumns (self-describing, like importJson — not positional), so a toXml round-trip lines up.

Functions

asBool(Object? value) → bool
Coerces a value to a truth for logical functions. A number is true when non-zero; the strings TRUE/FALSE (any case) map accordingly, empty is false, other text is true.
asDate(Object? value) → DateTime?
Coerces a value to a DateTime for the date functions: a DateTime passes through; an ISO string parses (DateTime.tryParse); a number is read as an Excel date serial (days since the 1899-12-30 epoch). Returns null when none applies — the caller raises #VALUE!.
asNumber(Object? value) → num
Coerces a value to a number for arithmetic. Numbers pass through; a bool is 1/0; a numeric string parses; anything else (text, null) is 0 — matching spreadsheets, where text in an arithmetic context reads as 0.
asText(Object? value) → String
Coerces a value to display/join text: a number drops a trailing .0, a bool is TRUE/FALSE, null is empty.
decryptWorkbook(List<int> bytes, String password) → BCellWorkbook
Decrypts a BCellWorkbookCrypto.toEncryptedBytes blob into a new BCellWorkbook. Throws a FormatException when bytes is not an encrypted-workbook blob (wrong magic/version, truncated) and a BCellDecryptException when the password is wrong or the blob was tampered with.
evaluateFormula(String formula, BCellResolver resolve, {int depth = 0, int maxDepth = 64}) → Object?
Evaluates formula (with or without a leading =) and returns a num, String, bool, or null (a bare reference to an out-of-range or empty cell). resolve reads referenced cells. Throws BCellFormulaError on any problem.
substituteNames(String src, BCellNameResolver resolve) → String
Rewrites named-range tokens in src to their A1 equivalents so the engine resolves them as ordinary refs/ranges — no new parser cases needed.

Typedefs

BCellNameResolver = String? Function(String name)
Resolves a defined name (e.g. TAX, SALES) to its A1 reference or range string (e.g. B2, A2:A10), or null when the name is not defined.
BCellResolver = dynamic Function(int col, int row)
Resolves an A1 reference (0-based col, row) to a raw cell value, or null when out of range. The engine coerces the value itself.

Exceptions / Errors

BCellDecryptException
Thrown by decryptWorkbook / BCellWorkbookCrypto.loadEncryptedBytes when the password is wrong or the blob was tampered with. AES-GCM authenticates the whole ciphertext, so the two cases are indistinguishable by design — either way the bytes cannot be trusted and nothing is returned.
BCellFormulaError
Thrown for any formula error (bad syntax, div-by-zero, circular ref). The caller shows code (e.g. #DIV/0!, #CIRC!, #ERR!) in the cell.