@kong-ui-public/table-data-grid 0.5.4 → 0.5.5-pr.3854.739ace440.0

package/README.md

@@ -2,8 +2,9 @@
 
 Reusable Vue wrapper around AG Grid for Kong table data grids.
 
-This package currently supports AG Grid infinite row loading with a cursor-first
-fetcher contract, basic column definitions, single-column sorting, empty/error
+This package supports AG Grid infinite row loading with a cursor-first fetcher
+contract and host-supplied complete results through its client-side row model. It also
+provides basic column definitions, single-column sorting, empty/error
 presentation states, and state lifecycle emits.
 
 ## Peer Dependencies
@@ -113,11 +114,13 @@ const handleState = (payload: TableDataGridStatePayload) => {
 | Prop | Type | Required | Default | Notes |
 | --- | --- | --- | --- | --- |
 | `headers` | `Array<TableDataGridHeader<Row>>` | Yes | - | Basic column definitions mapped to AG Grid columns. |
-| `fetcher` | `TableDataGridFetcher<Row>` | Yes | - | Async row loader called by the AG Grid infinite datasource. |
+| `fetcher` | `TableDataGridFetcher<Row>` | Infinite mode | - | Async row loader called by the AG Grid infinite datasource. |
+| `rows` | `Row[]` | Unpaginated mode | - | Complete host-owned result. The grid does not fetch in this mode. |
+| `mode` | `'infinite' \| 'unpaginated'` | No | `'infinite'` | Selects `fetcher` or `rows` and the AG Grid row model when mounted. Remount to change modes. |
 | `error` | `boolean` | No | `false` | Host-controlled visible error state. Internal fetch failures emit state but do not render error UI unless this prop is true. |
-| `pageSize` | `number` | No | `25` | AG Grid cache block size and fetcher request size. `tableConfig.pageSize` wins when present. |
-| `refreshKey` | `string \| number \| boolean` | No | - | Parent invalidation signal that rebuilds the datasource from the beginning. |
-| `tableConfig` | `TableDataGridConfig` | No | - | Host-controlled current sort and page size. Restores a previously-chosen sort on mount, or moves it after mount, without a click. Uncontrolled (internal state) when omitted. |
+| `pageSize` | `number` | No | `25` | Infinite mode only. AG Grid cache block size and fetcher request size. `tableConfig.pageSize` wins when present. |
+| `refreshKey` | `string \| number \| boolean` | No | - | Infinite mode only. Parent invalidation signal that rebuilds the datasource from the beginning. |
+| `tableConfig` | `TableDataGridConfig` | No | - | Host-controlled current sort, page size, and optional content-height sizing. Restores a previously-chosen sort on mount, or moves it after mount, without a click. Uncontrolled (internal state) when omitted. |
 
 ## Fetcher Contract
 
@@ -161,11 +164,38 @@ the public fetcher contract.
 is omitted, `hasMore: false` or a response shorter than `pageSize` marks the last
 loaded row as the end of the dataset.
 
+## Complete Results
+
+For a complete result that the host already loaded, set `mode="unpaginated"`
+and pass `rows`. The rows go to AG Grid's client-side row model. The grid does
+not fetch, show a loading overlay, or emit `state` events in this mode. The host
+owns loading, refresh, and error handling, and replaces `rows` when its result
+changes. An empty `rows` array shows the empty state.
+
+The row model is selected when `TableDataGrid` mounts. To switch between
+`infinite` and `unpaginated`, key the component by mode so Vue remounts it.
+
+For compact, content-sized tables, set `tableConfig.fitToContent` to `true` and
+leave the host height unconstrained. The grid fits its header and all returned
+rows, retains horizontal scrolling, and resizes when the result changes. This
+option defaults to `false` and is ignored in infinite mode. Otherwise, give the
+host a height and the grid scrolls within it.
+
+```vue
+<TableDataGrid
+  mode="unpaginated"
+  :headers="headers"
+  :rows="rows"
+/>
+```
+
 ## Refresh Behavior
 
 `refreshKey` is a parent-owned invalidation signal. Changing it rebuilds the
 infinite datasource, clears stored cursors, and starts again from the first
-block with `cursor: undefined`.
+block with `cursor: undefined`. Replacing `fetcher` triggers the same reset;
+subsequent requests use the new function and superseded responses cannot update
+current rows or error state.
 
 This reset is required for cursor APIs because cursor values are only valid
 relative to the response and query chain that produced them. Reusing a later
@@ -223,6 +253,23 @@ should opt out of the default flexible fill behavior.
 | `disableRowClick` | `boolean` | No | Suppresses `row:click` for clicks landing in this column's cells, e.g. an actions column. `cell:click` still fires. |
 | `sortable` | `boolean` | No | Enables sorting on this column via AG Grid's built-in header sort control. Only one column can be sorted at a time. |
 | `showSortIcon` | `boolean` | No | Shows the unsorted sort icon on this column even when it isn't the active sort, instead of only on hover or once sorted. Only relevant when `sortable` is true. |
+| `dataType` | `'number'` | No | Enables numeric presentation options for this column. Aggregate options are applied only in unpaginated mode. |
+| `valueFormatter` | `(value, row) => string` | No | Formats a raw value for display. A custom cell slot still receives the original `rowValue`. |
+| `showPercentage` | `boolean` | No | In unpaginated numeric columns, shows the row's percentage of the complete returned column sum. |
+| `percentageFormatter` | `(percentage) => string` | No | Optional formatter for the percentage points (50 means 50%) shown by `showPercentage`. The default uses the grid locale, up to two decimal places, and `< 0.01 %` for small positive values. |
+| `bar` | `'relative' \| 'absolute'` | No | In unpaginated numeric columns, renders a bar. `relative` uses `value / sum`; `absolute` uses `value / maximum`, matching the TopN scales. |
+| `thresholds` | `Array<{ value: number, type: 'warning' \| 'error' }>` | No | Applies threshold text/bar colors at or above the highest crossed threshold. Numeric finite values only. |
+
+Numeric presentation is intentionally derived from the complete `rows` result
+in unpaginated mode. Infinite mode does not calculate aggregate values; supplying
+numeric presentation options there, or on a header without `dataType: 'number'`,
+emits a console warning and omits those adornments. Nonnumeric or non-finite
+values also warn once per column and keep their ordinary content without numeric
+adornments. Missing values retain an empty bar track when a bar is configured.
+Bars clamp to 0–100%; percentage labels are omitted when the column total is not positive.
+
+Hosts render optional icons through the `cell-icon` slot. The grid places slot
+content beside the cell value without replacing its default or custom content.
 
 ## Sorting
 
@@ -255,7 +302,13 @@ under one sort order is not valid under another.
 ## Custom Cell Content
 
 Columns render custom cell content through a slot named after `header.key`.
-Columns without a matching slot render their raw `rowValue`.
+Columns without a matching slot render `valueFormatter(rowValue, row)` when
+configured, otherwise their raw `rowValue`. The `cell-icon` slot, percentages,
+and bars decorate both default values and slot content.
+When a named slot renders no content, the grid falls back to the formatted
+default value with ellipsis and an overflow tooltip; non-empty slot content
+remains host-owned.
+`cell-icon` is reserved for icon content and cannot name a column content slot.
 
 ```vue
 <TableDataGrid
@@ -267,6 +320,9 @@ Columns without a matching slot render their raw `rowValue`.
       {{ rowValue }}
     </KBadge>
   </template>
+  <template #cell-icon="{ column, rowValue }">
+    <ProviderIcon v-if="column.key === 'provider' && rowValue === 'openai'" />
+  </template>
 </TableDataGrid>
 ```
 
@@ -275,7 +331,7 @@ Columns without a matching slot render their raw `rowValue`.
 | `row` | `Row` | The full row record backing this cell. |
 | `rowValue` | `unknown` | `row[header.key]`. |
 | `column` | `TableDataGridHeader<Row>` | The header definition for this column. |
-| `rowIndex` | `number` | The row's index in the currently loaded block. |
+| `rowIndex` | `number` | The row's index in the currently loaded result. |
 | `selected` | `boolean` | Whether the row is currently selected. |
 | `refreshCell` | `() => void` | Forces AG Grid to re-render this cell. |
 
@@ -284,7 +340,7 @@ Columns without a matching slot render their raw `rowValue`.
 | Event | Payload | When it fires |
 | --- | --- | --- |
 | `grid:ready` | `GridApi<Row>` | AG Grid is ready. |
-| `state` | `{ state: 'loading' \| 'success' \| 'error', hasData: boolean }` | Internal fetch lifecycle changes after the datasource starts requesting rows. |
+| `state` | `{ state: 'loading' \| 'success' \| 'error', hasData: boolean }` | Internal fetch lifecycle changes after the datasource starts requesting rows. Not emitted in `unpaginated` mode. |
 | `row:click` | `(row: TableDataGridRowClickPayload<Row>, event: RowClickedEvent<Row>)` | A row is clicked, unless the click landed in a `disableRowClick` column. |
 | `cell:click` | `TableDataGridCellClickPayload<Row>` | Any cell is clicked, including cells in `disableRowClick` columns. |
 | `sort` | `TableDataGridSort` | The current single-column sort changes. Fires before `update:tableConfig`. |
@@ -294,8 +350,9 @@ Columns without a matching slot render their raw `rowValue`.
 
 | Slot | Purpose |
 | --- | --- |
-| `empty-state` | Replaces the default empty state after a successful empty first block. |
+| `empty-state` | Replaces the default empty state after a successful empty result. |
 | `error-state` | Replaces the default visible error state when `error` is true. |
+| `cell-icon` | Adds optional host-rendered content before each cell's default value or column slot. Uses the same cell slot props; render nothing for cells without an icon. |
 | `[columnKey]` | Renders custom cell content for the column matching `header.key`. See [Custom Cell Content](#custom-cell-content). |
 
 ## Exports
@@ -308,6 +365,7 @@ Columns without a matching slot render their raw `rowValue`.
 - `TableDataGridCellClickPayload`
 - `TableDataGridCellSlotProps`
 - `TableDataGridHeader`
+- `TableDataGridProps`
 - `TableDataGridInfiniteFetcherParams`
 - `TableDataGridFetcherResult`
 - `TableDataGridFetcher`

package/dist/style.css

@@ -1 +1 @@
-.table-data-grid-cell-renderer,.table-data-grid-cell-tooltip,.table-data-grid-cell-content{display:block;min-width:0;width:100%}.table-data-grid-cell-content{max-width:100%;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}.kong-ui-public-table-data-grid[data-v-d8328fe5]{border:none;border-radius:4px;border-radius:var(--kui-border-radius-20, 4px);box-sizing:border-box;display:flex;flex-direction:column;height:100%;min-height:0;overflow:hidden;width:100%}.table-data-grid-grid[data-v-d8328fe5]{--ag-background-color: var(--kui-color-background, #ffffff);--ag-border-color: var(--kui-color-border, #e0e4ea);--ag-foreground-color: var(--kui-color-text, #0d0e14);--ag-header-background-color: var(--kui-color-background, #ffffff);--ag-header-column-border: 1px solid var(--kui-color-border, #e0e4ea);--ag-header-column-border-height: 30%;--ag-header-column-resize-handle-color: transparent;--ag-header-font-weight: var(--kui-font-weight-semibold, 600);--ag-header-text-color: var(--kui-color-text-neutral, #6c7489);--ag-wrapper-border: none;--ag-wrapper-border-radius: 0;flex:1 1 auto;min-height:0;width:100%}.ag-cell{align-items:center;display:flex;min-width:0}.ag-cell-wrapper,.ag-cell-value{min-width:0;width:100%}
+.table-data-grid-cell-renderer,.table-data-grid-cell-tooltip,.table-data-grid-cell-content,.table-data-grid-cell-slot-content{display:block;min-width:0;width:100%}.table-data-grid-cell-renderer{align-items:center;display:flex;font-feature-settings:"case";font-variant-numeric:tabular-nums;gap:4px;gap:var(--kui-space-20, 4px);min-width:0;width:100%}.table-data-grid-cell-content,.table-data-grid-cell-slot-content,.table-data-grid-cell-relative{white-space:nowrap}.table-data-grid-cell-relative{font-size:12px;font-size:var(--kui-font-size-20, 12px);font-weight:400;font-weight:var(--kui-font-weight-regular, 400)}.table-data-grid-cell-renderer--bar .table-data-grid-cell-content,.table-data-grid-cell-renderer--bar .table-data-grid-cell-slot-content,.table-data-grid-cell-renderer--text-warning .table-data-grid-cell-content,.table-data-grid-cell-renderer--text-warning .table-data-grid-cell-slot-content,.table-data-grid-cell-renderer--text-error .table-data-grid-cell-content,.table-data-grid-cell-renderer--text-error .table-data-grid-cell-slot-content{font-weight:600;font-weight:var(--kui-font-weight-semibold, 600)}.table-data-grid-cell-renderer--text-warning{color:#995c00;color:var(--kui-color-text-warning, #995c00)}.table-data-grid-cell-renderer--text-error{color:#d60027;color:var(--kui-color-text-danger, #d60027)}.table-data-grid-cell-renderer--bar .table-data-grid-cell-content,.table-data-grid-cell-renderer--bar .table-data-grid-cell-slot-content,.table-data-grid-cell-renderer--bar .table-data-grid-cell-tooltip,.table-data-grid-cell-renderer--percentage .table-data-grid-cell-slot-content,.table-data-grid-cell-renderer--percentage .table-data-grid-cell-tooltip,.table-data-grid-cell-renderer--percentage .table-data-grid-cell-content{flex:0 1 auto;width:auto}.table-data-grid-cell-bar{background-color:#e0e4ea;background-color:var(--kui-color-background-neutral-weaker, #e0e4ea);border-radius:100px;border-radius:var(--kui-border-radius-round, 100px);display:block;flex:1 1 80px;height:8px;min-width:80px;overflow:hidden;width:100%}.table-data-grid-cell-bar-fill{background-color:#6a86d2;border-radius:inherit;display:block;height:100%}.table-data-grid-cell-bar[data-threshold=warning] .table-data-grid-cell-bar-fill{background-color:#995c00;background-color:var(--kui-color-background-warning, #995c00)}.table-data-grid-cell-bar[data-threshold=error] .table-data-grid-cell-bar-fill{background-color:#d60027;background-color:var(--kui-color-background-danger, #d60027)}.table-data-grid-cell-content{max-width:100%;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}.kong-ui-public-table-data-grid[data-v-70223444]{border:none;border-radius:4px;border-radius:var(--kui-border-radius-20, 4px);box-sizing:border-box;display:flex;flex-direction:column;height:100%;min-height:0;overflow:hidden;width:100%}.kong-ui-public-table-data-grid.fit-to-content[data-v-70223444]{height:auto}.kong-ui-public-table-data-grid.fit-to-content[data-v-70223444] .ag-grid-scrolling-rows{min-height:0}.table-data-grid-grid[data-v-70223444]{--ag-background-color: var(--kui-color-background, #ffffff);--ag-border-color: var(--kui-color-border, #e0e4ea);--ag-foreground-color: var(--kui-color-text, #0d0e14);--ag-header-background-color: var(--kui-color-background, #ffffff);--ag-header-column-border: 1px solid var(--kui-color-border, #e0e4ea);--ag-header-column-border-height: 30%;--ag-header-column-resize-handle-color: transparent;--ag-header-font-weight: var(--kui-font-weight-semibold, 600);--ag-header-text-color: var(--kui-color-text-neutral, #6c7489);--ag-wrapper-border: none;--ag-wrapper-border-radius: 0;flex:1 1 auto;min-height:0;width:100%}.ag-cell{align-items:center;display:flex;min-width:0}.ag-cell-wrapper,.ag-cell-value{min-width:0;width:100%}