bcell library

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

Classes

BCellAutoFilter

Shared per-column filter state for a set of BCellColumnFilterButtons, so multiple column filters compose (AND together, Excel style). One controller per grid; hand it to every filter button.

BCellAutoSum

Excel-style status-bar aggregate for a BCellGrid: shows Count / Sum / Average of the currently selected cells, updating live as the selection changes. Same calling shape as BCellPagination — construct with the state manager from onLoaded and place it anywhere (typically below the grid).

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.

BCellColumnFilterButton

Excel-style AutoFilter button for one column header: a funnel icon that opens a checklist of the column's distinct values. Place it in a column header (e.g. via a custom header) and give every button the same BCellAutoFilter controller so filters compose.

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

BCellColumnTypeSelect

A single-select column. Editing shows a dropdown of items; the cell holds the chosen item. Display is the item's toString (unformatted).

BCellColumnTypeText

BCellConditionalFormat

Conditional-formatting visuals and rules for a column (spec cat 12): color scale, data bar, icon set, plus Excel "highlight cells rules" lite — duplicates, topN, and formulaRule. 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.

BCellHyperlink

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.

BCellImportTransform

A small, chainable transform pipeline for row maps before they reach the grid via BCellTableImport.importJson (spec cat 22: Power-Query-style import transforms). Each step returns a new BCellImportTransform over a fresh row list, so the source is never mutated and steps compose:

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(s) in first-appearance order (or sorted by the pivot's keyComparator).

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.

BCellRowGroup

One Excel-outline-style row group made by BCellGridStateManager.groupRows: a captured run of rows whose first row is the always-visible header (it carries the grid's +/− toggle) and whose remaining rows hide while not expanded.

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.

BCellSlicer

Excel-style slicer for a BCellGrid: a labelled chip bar of one column's distinct values. Tapping chips toggles a multi-select filter on that column. Same calling shape as BCellPagination — construct with the state manager from onLoaded and place it anywhere (typically above the grid).

BCellSparkline

A mini in-cell chart (Excel's Sparklines): a tiny line or bar chart drawn from a List<num> cell value, sized to the cell — no axes, labels, or legend (that's BCellChart). Like BCellHyperlink, the factory returns a helper whose toRenderer produces a Widget Function(BCellColumnRendererContext) you assign to BCellColumn.renderer.

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.

BCellTable

The grid's table definition (spec cat 10): a name plus per-column totals aggregates. One table per grid — the grid body IS the table, so the table carries no row/column data of its own.

BCellTextRun

One styled run of text inside a BCellRichText cell value.

BCellValidation

Factory namespace for prebuilt BCellColumn.validator functions.

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.

BCellColumnTextAlign

Horizontal text alignment for a column's cells and header. Modeled on pluto_grid's PlutoColumnTextAlign (start/left/center/right/end), plus auto — a bcell extension and the default — which keeps bcell's legacy behavior (numbers right, everything else left).

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.

BCellPivotValueMode

How aggregated values are shown: as-is, or each cell/total as a percentage of the grand total (Excel's "% of Grand Total"; the grand total becomes 100).

BCellResizeMode

How dragging a column's resize handle behaves (same shape as pluto_grid's PlutoResizeMode).

BCellWrapText

Per-cell / per-row text-wrap choice. inherit (the default) falls through the cascade BCellValue.wrapText -> BCellRow.wrapText -> BCellColumn.wrapText (the column bool is the cascade root, so a column with wrapText: true wraps every cell that doesn't override). wrap and noWrap force this level's answer regardless of the levels above.

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.

BCellGoalSeek on BCellGridStateManager

Goal Seek (spec: What-If Analysis) for a BCellGridStateManager — Excel's Data → What-If Analysis → Goal Seek: find the input value for one cell that makes a formula cell evaluate to a target number.

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). The grid renders a noted cell with a corner marker + hover tooltip; read and write notes via this 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.

BCellScenario on BCellGridStateManager

Scenario Manager (spec: What-If Analysis) for a BCellGridStateManager — Excel's Data → What-If Analysis → Scenario Manager: named snapshots of a set of INPUT cells' values that can be re-applied later. The cell-scoped sibling of bcell_workbook_history's whole-workbook save/restore.

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).

BCellSolver on BCellGridStateManager

Solver (spec: What-If Analysis) for a BCellGridStateManager — Excel's Data → Solver, target-value mode: find inputs for SEVERAL cells that make a formula cell evaluate to a target number. The multi-variable sibling of goalSeek in bcell_goal_seek.dart.

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.

BCellTableExt on BCellGridStateManager

Table object: unlocks the [#Headers] / [#Totals] structured-reference item specifiers that enableStructuredRefs alone can't provide.

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

BCellColumnValueFormatter = String Function(dynamic value)

Formats a cell's raw value into its display string. Mirrors pluto_grid's PlutoColumnValueFormatter. Display-only: the editor edits the raw value.

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.