Architecture

BC Grid is a BusinessCraft component with a package boundary. The boundary lets ERP screens consume a stable public API while the grid internals keep separate ownership for virtualization, filtering, aggregation, editing, export, and server row models.

Package Layers#

The architecture uses two layers:

core
  -> virtualizer
  -> animations
  -> theming
  -> aggregations
  -> filters
  -> export
  -> server-row-model

react
  -> editors
  -> enterprise

@bc-grid/core owns framework-agnostic types and state contracts. Engine packages depend on core and stay independent of React. @bc-grid/react is the adapter that composes the engines into BcGrid, BcEditGrid, and BcServerGrid.

Why This Matters In BusinessCraft#

BusinessCraft screens need consistent grid behavior across modules: keyboard navigation, row identity, pinned columns, filters, saved views, validation states, and server fetch semantics. Keeping those behaviors in BC Grid prevents every ERP screen from rebuilding them differently.

The public boundary also makes agent work safer. A screen port can select a grid mode and wire domain data without knowing how the virtualizer or aggregation engine is implemented.

Runtime Composition#

Most screens use one of three components:

• BcGrid for read-heavy client-side grids.
• BcEditGrid when cells commit changes in place.
• BcServerGrid when the row set is loaded through a paged, infinite, or tree fetcher.

The packages below those components stay focused:

• @bc-grid/virtualizer calculates visible row and column windows.
• @bc-grid/filters owns filter predicates and serialization.
• @bc-grid/aggregations owns totals, groups, and pivot data.
• @bc-grid/server-row-model owns block caches, request dedupe, retries, and update events.
• @bc-grid/theming maps host tokens and density modes to grid CSS variables.

Host Integration#

BusinessCraft shells provide the surrounding app concerns: navigation, route state, module permissions, theme, and server actions. BC Grid provides the in-screen grid behavior. A screen should keep business rules in the domain package, keep server actions thin, and pass only typed rows, columns, and callbacks into the grid.

import { BcServerGrid, type BcGridColumn } from "@bc-grid/react";

const columns: BcGridColumn<CustomerRow>[] = [
  { field: "account", header: "Account", pinned: "left" },
  { field: "name", header: "Name", filter: { type: "text" } },
  { field: "balance", header: "Balance", align: "right", format: "currency" },
];

export function CustomersGrid() {
  return (
    <BcServerGrid
      columns={columns}
      rowId={(row) => row.account}
      mode="paged"
      loadPage={loadCustomerPage}
      gridId="ar.customers"
    />
  );
}

Design Rules#

Use the grid for behavior that should be consistent everywhere. Use screen code for workflow and business context. If a feature is useful across modules, it belongs in BC Grid or a shared BusinessCraft package, not in one screen.

Keep imports on the public API:

import { BcGrid, BcEditGrid, BcServerGrid } from "@bc-grid/react";
import { textEditor, numberEditor } from "@bc-grid/editors";
import "@bc-grid/theming/styles.css";

Avoid reaching into package src/internal folders. Those internals can change without screen migration support.