ag-grid-cljs.core — io.github.unisoma/ag-grid-cljs 0.1.0-SNAPSHOT

Public API — walking-skeleton first cut. Namespace layout and naming are provisional until the namespace-layout decision lands.

create-grid! cljs

(create-grid! el opts)

Convert the EDN options map and mount AG Grid on el, returning a GridHandle — {:api <GridApi> :opts <last-applied-EDN>} — that every runtime channel takes (ADR 0008). el is a DOM element; opts is the EDN options map (build it with the with-* builders or plain assoc). The map crosses the conversion boundary (kebab->camel, ADR 0005) before it reaches AG Grid.

The stashed :opts is the unconverted EDN, so later update-grid! diffs compare EDN to EDN; reach the raw GridApi with grid-api for anything the wrapper does not cover. (The handle also carries an internal per-handle set of keys already dev-warned by update-grid! — not part of the public shape.)

Example:

(create-grid! el (-> (options)
                     (with-columns [{:field :name}])
                     (with-row-data rows)))

destroy! cljs

(destroy! handle)

Tear down the grid behind handle (releases its DOM and listeners). Takes a GridHandle from create-grid!.

Example: (destroy! handle).

enable-dev-validations! cljs

(enable-dev-validations!)

Turn on the wrapper's dev-mode option validation: unknown top-level and ColDef keys warn once with a kebab did-you-mean, and deprecated keys warn with their replacement (ADR 0007 §4-5). Warn-only — validation never rejects or alters what AG Grid receives. No-op in production builds (goog.DEBUG false), where both the validation code and the key registry are dead-code-eliminated.

Call once at app startup in dev. This covers only the kebab-native layer; for type, option-dependency, and row-model checks register AG Grid's own ValidationModule (dev bundle) alongside it:

(:require ["ag-grid-community" :refer [ValidationModule]])
(ag/register! ValidationModule)
(ag/enable-dev-validations!)

grid-api cljs

(grid-api handle)

Return the raw AG Grid GridApi held by handle — the escape hatch (ADR 0004) for any imperative capability the wrapper does not wrap.

Example: (.getDisplayedRowCount (grid-api handle)).

options cljs

(options)

(options base)

Start an options map, optionally from an existing EDN map.

raw cljs

Escape hatch: (raw x) passes x to AG Grid untouched — no key renaming, no recursion, no function wrapping.

register! cljs

(register! & modules)

Thin optional sugar over ModuleRegistry.registerModules. The consumer owns module registration; must run before the first grid is created.

set-rows! cljs

(set-rows! handle rows)

Replace the full row set on the grid behind handle. Rows are JS by contract: a JS array of JS objects (ADR 0003). With :get-row-id set, AG Grid diffs by id and preserves grid state (scroll/selection/focus) across the swap. Writes AG Grid's rowData grid option.

Example: (set-rows! handle (into-array (map person->row people))).

transact! cljs

(transact! handle tx)

Apply a fine-grained row transaction to the grid behind handle: {:add [...] :update [...] :remove [...] :add-index n}. Rows are JS by contract (ADR 0003); :update/:remove match existing rows via :get-row-id. The tx map is forward-converted (ADR 0005) and handed to AG Grid's applyTransaction; its RowNodeTransaction result is returned untouched.

Example: (transact! handle {:update [(person->row p)]}).

update-grid! cljs

(update-grid! handle new-opts)

PATCH the grid behind handle with new-opts, an EDN options map holding only the keys to change (ADR 0008). A MERGE differ, not full-state: keys ABSENT from new-opts are left as-is; present keys are compared by = against the handle's stashed last-applied EDN and only CHANGED keys do anything. Returns the handle with its stash merged forward, so successive updates diff against the true applied state — thread the returned handle.

Per changed key (registry :initial? is the sole updatable-vs-initial-only classifier):

• updatable -> one setGridOption (key camelized, value forward-converted via the conversion boundary, ADR 0005). :column-defs is an ordinary updatable key: the WHOLE new value ships and AG Grid owns column-level diffing (pin :col-id to preserve column state).
• initial-only -> ignored with a once-per-key dev warning (an initial-only option cannot change after creation; recreating the grid would destroy scroll/selection/focus state).
• :row-data -> ignored with a dev warning; the data channel owns it (use set-rows! / transact!, ADR 0004).
• unclassified -> applied optimistically via setGridOption with a once-per-key dev warning (newer than the registry pin, or a typo already flagged by conversion-time validation).

All dev warnings are no-ops in production builds (goog.DEBUG false).

Example:

(-> handle
    (update-grid! {:pagination true})
    (update-grid! {:quick-filter-text "ada"}))

with-cell-selection cljs

(with-cell-selection opts cell-selection)

Enable cell (range) selection — Enterprise. Pass true for defaults, or the v32.2+ cellSelection object form for finer control, e.g. {:handle {:mode "fill"}} to turn on the fill handle. Requires an Enterprise module bundle registered (CellSelectionModule) and a license.

with-columns cljs

(with-columns opts col-defs)

with-infinite-datasource cljs

(with-infinite-datasource opts get-rows)

(with-infinite-datasource opts
                          get-rows
                          {:keys [cache-block-size max-blocks-in-cache]})

Behavioral bundle (Community, Infinite Row Model): assoc :row-model-type "infinite" plus a :datasource wrapping get-rows, and optional cache sizing. Bundles the row-model wiring — it does NOT marshal the callbacks (ADR 0010 §5).

get-rows is your fetch function. It receives one argument, the kebab-bean request params: :start-row, :end-row, :sort-model, :filter-model, and the raw AG Grid callbacks :success/:fail. Rows are JS by contract, so reply with a JS object:

(fn [params]
  (let [page (fetch (:start-row params) (:end-row params))]
    ((:success params) #js {:rowData (into-array page) :rowCount total})))

Second arg (optional) is cache sizing: {:cache-block-size 100 :max-blocks-in-cache 10}. Writes rowModelType, datasource, and any of cacheBlockSize/maxBlocksInCache supplied. Community; requires the InfiniteRowModelModule registered (register!).

Example:

(-> (options)
    (with-columns [{:field :name}])
    (with-infinite-datasource get-rows {:cache-block-size 50}))

with-pagination cljs

(with-pagination opts)

(with-pagination opts {:keys [page-size page-size-selector auto-page-size]})

Option-bundle: turn on pagination and configure page sizing, encoding the paginationAutoPageSize x paginationPageSize mutual exclusion (AG Grid ignores a fixed page size when auto-sizing is on).

EDN shape (config optional; (with-pagination opts) just enables it):

{:page-size          25            ; rows per page (ignored if :auto-page-size)
 :page-size-selector [25 50 100]   ; or true/false to show/hide the selector
 :auto-page-size     true}         ; size each page to fill the viewport

When :auto-page-size is true, :page-size is dropped (dev-warns if both were given). Writes pagination, plus paginationPageSize, paginationPageSizeSelector, paginationAutoPageSize as supplied. Community; all supported versions.

Example:

(-> (options)
    (with-columns [{:field :name}])
    (with-pagination {:page-size 25 :page-size-selector [25 50 100]}))

with-row-data cljs

(with-row-data opts rows)

Rows are JS by contract: pass a JS array of JS objects. (A JS array passes the converter untouched; CLJS rows trigger the dev-mode JS-by-contract warning.)

with-row-id cljs

(with-row-id opts id)

Coercion: assoc :get-row-id, the row-identity callback AG Grid uses to diff row data. Give it a keyword naming an id field, or a function computing an id from the row; either way the result is string-coerced, since AG Grid requires getRowId to return a string.

Load-bearing: with a stable row id, set-rows! and transact! diff by id and preserve grid state (scroll/selection/focus) across updates (ADR 0008).

EDN shape:

• a keyword — (with-row-id opts :id) reads that field from each JS row (:first-name reads firstName, kebab->camel like every other key) and calls str on it. Compiles to a raw callback over the JS row, so the per-row hot path allocates no bean.
• a function — (with-row-id opts (fn [p] (:id (:data p)))) receives the kebab-bean params (ADR 0010; (:data p) is the row) and its return is string-coerced. Wrap your own fn with raw to receive raw JS params.

Writes AG Grid's getRowId grid option (initial-only). Community; all supported versions.

Example:

(-> (options)
    (with-columns [{:field :id} {:field :name}])
    (with-row-id :id))

with-selection cljs

(with-selection opts selection)

Option-bundle: assoc :row-selection as the v32.2+ rowSelection OBJECT, shielding callers from the pre-v32.2 string form ("single"/"multiple") and its scattered deprecated flags (suppressRowClickSelection, etc.).

Coerces the friendly :mode value — :single/:multiple (or the raw "singleRow"/"multiRow") — and passes the remaining friendly keys through the conversion boundary unchanged (:header-checkbox -> headerCheckbox, etc.).

EDN shape (all keys optional; :mode defaults to :multiple):

{:mode                   :single | :multiple
 :checkboxes             true | false
 :header-checkbox        true | false     ; multiRow only
 :enable-click-selection true | false}

Writes AG Grid's rowSelection grid option (an object). Community; requires AG Grid v32.2+ (the object form of rowSelection).

Example:

(-> (options)
    (with-columns [{:field :name}])
    (with-selection {:mode :multiple :header-checkbox true}))