Description

The <k-card-grid> component renders data as a grid of <k-card> tiles instead of table rows — for anything that reads better as a card than a cell: thumbnails, media, profiles. Its data model, pagination and selection all match <k-table> on purpose, so a control built against Table's contract (getSelectedRecords(), selectAllOnPage(), deselectAllOnPage(), the selectionChange event) works against a CardGrid unmodified — including kempo-ui's own kc-tc-* controls.

Basic Usage

In HTML create a <k-card-grid>, and then in JavaScript call setData with your records and a cardTemplate function — one render function for the whole card, in place of Table's per-column fields.

<k-card-grid id="basicUsageExample"></k-card-grid>
<script type="module">
  await window.customElements.whenDefined('k-card-grid');
  document.getElementById('basicUsageExample').setData({
    records: [{
      name: 'Dustin',
      role: 'Engineer'
    }, {
      name: 'Kayla',
      role: 'Designer'
    }, {
      name: 'Alexander',
      role: 'Manager'
    }],
    cardTemplate: record => `<strong>${record.name}</strong><br>${record.role}`
  });
</script>

Selection and Table Controls

Set enable-selection and every card gets a checkbox in its corner, plus a "select all" checkbox above the grid — the same mechanism <k-table> uses. Because CardGrid sets controlled on itself and implements getSelectedRecords()/deselectAllOnPage()/the selectionChange event identically to Table, any kc-tc-* control (or a custom control built the same way, extending Control/ButtonControl) works in its slot="top" exactly as it would inside a <k-table>.

<k-card-grid id="selectionExample" enable-selection>
  <kc-tc-delete-selected slot="top"></kc-tc-delete-selected>
</k-card-grid>
<script type="module">
  await window.customElements.whenDefined('k-card-grid');
  document.getElementById('selectionExample').setData({
    records: [{
      id: 1,
      name: 'Dustin'
    }, {
      id: 2,
      name: 'Kayla'
    }, {
      id: 3,
      name: 'Alexander'
    }],
    cardTemplate: record => record.name
  });
</script>

kc-tc-delete-selected's own handleAction() just calls host.deleteSelected() — it has no idea whether host is a Table or a CardGrid, and doesn't need to.

Differences from Table

CardGrid is deliberately not a 1:1 port. Table's columns give it a natural place to hang sorting, filtering, per-cell search and inline editing — a card has no columns, just one opaque block of content per record, so none of that carries over:

• No fields, no per-column calculator/formatter/editor — one cardTemplate(record, host) renders the whole card instead.
• No sorting (sortBy), filtering (addFilter/removeFilter), or built-in search().
• No inline editing (editRecord/saveEditedRecord).
• No field visibility (hideField/showField) or CSV/JSON export, both of which assume tabular columns.
• No fetch-on-scroll (setupFetchRecords).

Everything else — pagination, record CRUD, record-level hide/show, selection, requestDelete confirmation — matches Table's method names, argument shapes and event names exactly.

JavaScript Reference

Constructor

Extends Component

new CardGrid()
new CardGrid(<Array>object options)

Parameters

object options

An object containing the initial configuration for the grid. The options object can contain the following properties:

• records: An array of objects representing the records to be shown in the grid.
• cardTemplate: A function (record, host) => TemplateResult that renders the contents of each card.

Properties

records: <Array>object

An array of objects containing the data that will be the records of the grid.

cardTemplate: function

A function (record, host) => TemplateResult called once per record to render the contents of its card. host is the CardGrid instance itself, mirroring the (record, table) signature Table passes to a field's calculator.

enable-selection: boolean

Shows a checkbox on every card and a "select all" checkbox above the grid.

min-card-width: string

The minimum width of a card before the grid wraps to another column, passed straight into a repeat(auto-fill, minmax(min-card-width, 1fr)) grid-template-columns. Defaults to "11rem".

pageSize: number

The number of records to display per page.

pageSizeOptions: <Array>number

An array of numbers representing the available page size options.

request-delete: boolean

When set, deleteRecord/deleteSelected dispatch a requestDelete event and wait for approve() instead of deleting immediately.

placeholder: string

Text shown when the grid has no records. Defaults to "No Records".

filtered-placeholder: string

Text shown when records exist but every one is currently hidden (via hideRecord). Defaults to "" (nothing shown).

Methods

setData(object options): undefined

Sets the records and the card template and renders the grid. The options object can contain records, cardTemplate, pageSize, pageSizeOptions, currentPage, and enableSelection.

setRecords(Array records, function cardTemplate): undefined

Sets the records for the grid and re-renders. cardTemplate is optional — omit it to keep whatever's already set.

addRecord(object record): undefined

Adds a new record to the grid.

updateRecord(object record, object newData): undefined

Updates an existing record with new data.

deleteRecord(object record): undefined

Deletes a record from the grid, or — with request-delete set — dispatches requestDelete and waits for approval first.

setPageSize(number pageSize): undefined

Sets the number of records to display per page.

setPage(number page): undefined

Sets the current page to display.

nextPage(): undefined

Moves to the next page.

prevPage(): undefined

Moves to the previous page.

firstPage(): undefined

Moves to the first page.

lastPage(): undefined

Moves to the last page.

getCurrentPage(): number

Returns the current page number.

getTotalPages(): number

Returns the total number of pages.

getSelectedRecords(): Array

Returns an array of the currently selected records.

deleteSelected(): undefined

Deletes all currently selected records from the grid — or, with request-delete set, dispatches requestDelete for the selection.

selectAllOnPage(): undefined

Selects all the records on the current page.

deselectAllOnPage(): undefined

Deselects all the records on the current page.

allOnPageSelected(): boolean

Returns true if all the records on the current page are selected.

hideRecord(object record): undefined

Hides a record from the grid.

showRecord(object record): undefined

Shows a hidden record.

showAllRecords(): undefined

Shows every hidden record.

getDisplayedRecords(): Array

Returns the records currently displayed (i.e. not hidden).

getHiddenRecords(): Array

Returns the currently hidden records.