Skip to content

Latest commit

 

History

History
489 lines (384 loc) · 24.1 KB

declarative-table.md

File metadata and controls

489 lines (384 loc) · 24.1 KB

DeclarativeTable

A data table web component that renders rows and columns from a declarative column definition. Supports pagination, grouped columns, conditional cell styling, value mapping, and multiple cell display modes (plain text, link, boolean icon, secret, tooltip, button, image, tag).

Tags

Usage Tag
Angular component <mfp-declarative-table>
Web Component (framework-agnostic) <mfp-wc-declarative-table>

Usage as a web component

Include the bundle and set properties via JavaScript. Because the component uses Shadow DOM, no extra CSS setup is needed.

<!DOCTYPE html>
<html>
  <head>
    <script type="module" src="declarative-table.js" />
  </head>
  <body>
    <mfp-wc-declarative-table id="table"></mfp-wc-declarative-table>

    <script type="module">
      const table = document.getElementById('table');

      table.columns = [
        { label: 'Name', property: 'metadata.name' },
        { label: 'Status', property: 'status.phase' },
      ];

      table.resources = [
        { metadata: { name: 'pod-1' }, status: { phase: 'Running' } },
        { metadata: { name: 'pod-2' }, status: { phase: 'Pending' } },
      ];

      table.trackByPath = 'metadata.name';
    </script>
  </body>
</html>

columns, resources, and trackBy are JavaScript properties, not HTML attributes. They must be set programmatically after the element is available in the DOM.


Usage as an Angular component

import { DeclarativeTable } from '@openmfp/ngx';
import { TableFieldDefinition } from '@openmfp/ngx';

@Component({
  imports: [DeclarativeTable],
  template: `
    <mfp-declarative-table
      [columns]="columns"
      [resources]="resources"
      [trackByPath]="trackByPath"
      [hasMore]="hasMore"
      [loading]="loading"
      [error]="error"
      [paginationLimit]="pageSize"
      [totalItemsCount]="total"
      (tableRowClicked)="onRowClick($event)"
      (loadMoreResources)="loadMore()"
      (paginationLimitChanged)="onPageSizeChange($event)"
      (retry)="reload()"
    />
  `,
})
export class MyComponent {
  columns: TableFieldDefinition[] = [
    { label: 'Name',   property: 'metadata.name' },
    { label: 'Status', property: 'status.phase' },
  ];
  resources = [...];
  trackByPath = 'metadata.name';
  hasMore = false;
  pageSize = 10;
  total = 0;
}

API

Inputs

Input Type Required Default Description
overflowMode 'Scroll' | 'Popin' no 'Scroll' Horizontal overflow behavior
appearance 'default' | 'card' no 'default' 'card' renders every supplied row as passive, suppresses row click events and hides the pager, page-size selector and load-more controls.
columns TableFieldDefinition[] yes — Column definitions
resources GenericResource[] yes — Data rows
trackByPath string no 'id' JSONPath (dot-notation) into each resource used as the row identity key
totalItemsCount number no — Total count of all items across pages
paginationLimit number no 5 Rows per page shown in the page-size selector
hasMore boolean no false Show the load-more trigger at the bottom
loadMode 'scroll' | 'button' | 'pager' no 'button' Load strategy: 'button' shows a load-more button, 'scroll' triggers on scroll, 'pager' renders numbered pagination controls
loadMoreButtonText string no 'Load More' Label shown on the load-more button (used when loadMode is 'button')
height number no — Fixed height in pixels. Combined with loadMode: 'scroll', enables scroll-based loading. Not needed just to get a scrolling table — see Scrolling and the sticky header.
currentPage number no 1 1-based current page. Only used when loadMode is 'pager'
permissions Record<string, string[]> no — Per-row permission map keyed by resource.id. Passed to every cell's mfp-resource-field to evaluate requirePermission on each column definition.
loading boolean no false Shows the table loading indicator and suppresses the empty state while data is loading.
loadingDelay number no 1000 Delay in milliseconds before the loading indicator is displayed.
error TableErrorConfig | null no null Replaces rows and the empty state with an error illustrated message. When null or absent the table renders normally. See TableErrorConfig.

Outputs / Events

Event Detail payload Description
tableRowClicked row object Fires when a row is clicked
buttonClick { event, field, resource } Fires when a button cell is clicked
loadMoreResources — Fires when the user triggers load more
paginationLimitChanged number Fires when the user changes the page size
pageChange number Fires when the user selects a page (loadMode: 'pager')
retry — Fires when the user selects Retry in the error state

Listening to events from a web component:

table.addEventListener('tableRowClicked', (e) => console.log(e.detail));
table.addEventListener('loadMoreResources', () => fetchNextPage());
table.addEventListener('retry', () => reload());
table.addEventListener('paginationLimitChanged', (e) => {
  table.paginationLimit = e.detail;
});
table.addEventListener('buttonClick', (e) => {
  const { field, resource } = e.detail;
  console.log('Button clicked for', resource);
});

Column definition (TableFieldDefinition)

interface TableFieldDefinition {
  label?: string;
  property?: string; // dot-notation path into the resource object
  jsonPathExpression?: string; // explicit JSONPath expression
  propertyField?: PropertyField; // access a sub-key with optional transforms
  value?: string; // static fallback value
  uiSettings?: UiSettings;
  columnSettings?: TableColumnSettings;
  group?: {
    name: string; // columns sharing the same name are merged into one header
    label?: string; // label for the merged header
    delimiter?: string; // separator between values (default: space)
    multiline?: boolean; // render values on separate lines instead
  };
}

Resolving cell values

Values are resolved in this order:

  1. jsonPathExpression — evaluated as a JSONPath query against the resource (e.g. $.spec.containers[0].image)
  2. property — dot-notation path; a $. prefix is added automatically if missing
  3. propertyField — accesses resource[property][propertyField.key] with optional transforms
  4. value — static string, used as a fallback when the resource yields no value

Examples:

// Simple dot-notation
{ label: 'Name', property: 'metadata.name' }

// Explicit JSONPath
{ label: 'Image', jsonPathExpression: '$.spec.containers[0].image' }

// Sub-key with transform
{ label: 'Created', property: 'metadata', propertyField: { key: 'creationTimestamp', transform: ['uppercase'] } }

// Static fallback when property may be absent
{ label: 'Message', property: 'status.message', value: 'N/A' }

PropertyField transforms

Transforms can be chained and are applied left to right.

Transform Effect
uppercase hello → HELLO
lowercase HELLO → hello
capitalize hello → Hello
encode Base64-encodes the value
decode Base64-decodes the value
{ property: 'metadata', propertyField: { key: 'name', transform: ['capitalize'] } }

Cell display modes (uiSettings.displayAs)

By default a cell renders its value as plain text. Use uiSettings.displayAs to change the rendering:

displayAs Renders as
(unset) Plain text
'secret' Masked value with a toggle-visibility button
'boolIcon' Check / X icon for "true" / "false" string values
'link' Clickable anchor; href from linkSettings.link template or field value; visible text from linkSettings.text or field value
'tooltip' Text with an info icon; the full value appears on hover
'alert' Alert-styled text
'img' <img> element using the value as src
'button' Action button (requires buttonSettings)
'tag' One <ui5-tag> chip per value (split by tagSettings.valueSeparator, default ','); also accepts an array of values

Link href resolution. When linkSettings.link is set, {{path}} placeholders are substituted and then the result is resolved against the current page URL (window.location.href, treated as a directory): absolute URLs (e.g. https://…, mailto:…) are returned unchanged; a leading / resolves from the origin root; no leading slash is appended to the current path. See docs/resource-field.md for full details and examples.

Copy button

Add a copy-to-clipboard icon to any cell:

{ label: 'ID', property: 'metadata.uid', uiSettings: { withCopyButton: true } }

Column width

Set overflowMode to 'Popin' to move columns below each row when space runs out ('Scroll' by default). In columnSettings, use minWidth (default 3rem, applies to automatic/percentage widths), importance (higher stays visible longer, default 0), popinText (defaults to the column/group label), and popinHidden (default false; hides the value on narrow screens). Grouped columns use the first field's settings. For existing configurations, uiSettings.columnWidth remains supported; columnSettings.width takes precedence when provided.

Set an explicit width on a column header cell:

{ label: 'Actions', columnSettings: { width: '10rem' } }

UI5 constraint. The value must be a valid CSS <length> — px, rem, em, %, or calc(). Sizing keywords such as min-content and max-content are rejected by UI5 and fall back to equal-stretch distribution across all columns.

Column alignment

Control the horizontal alignment of cell content using uiSettings.align. The value maps directly to the CSS justify-content property of the cell's flex wrapper.

Value Effect
'start' Left-aligned (default browser behaviour)
'center' Centred
'end' Right-aligned
{
  uiSettings: {
    displayAs: 'button',
    align: 'end',
    buttonSettings: { icon: 'delete', design: 'Transparent', action: 'delete' },
  },
  group: { name: 'actions', label: '' },
}

For group columns the alignment is driven by the first field's uiSettings.align.

Button cells

{
  label: 'Actions',
  property: 'metadata.name',
  uiSettings: {
    displayAs: 'button',
    buttonSettings: {
      text: 'Open',
      icon: 'action',
      design: 'Emphasized', // 'Default' | 'Positive' | 'Negative' | 'Transparent' | 'Emphasized' | 'Attention'
      action: 'navigate',   // 'navigate' | 'openInModal'
    },
  },
}

A buttonClick event fires with { event, field, resource } when clicked.


Grouped columns

Columns that share the same group.name are collapsed into a single table column. Their values are displayed together, separated by group.delimiter or on separate lines when group.multiline is true.

columns = [
  {
    label: 'First name',
    property: 'firstName',
    group: { name: 'fullName', label: 'Full Name', delimiter: ' ' },
  },
  {
    label: 'Last name',
    property: 'lastName',
    group: { name: 'fullName' },
  },
  { label: 'Email', property: 'email' },
];

The above produces two visible columns: Full Name and Email.

Column-level settings via the first field

The first field in a group sets the column-level configuration. columnSettings.width controls the <ui5-table-header-cell> width; uiSettings.align controls justify-content of the cell content wrapper. The column header text comes from group.label (or group.name if omitted) of the first field. These values on subsequent fields in the same group are ignored.

columns = [
  // First field — drives column width and right-alignment for the whole group
  {
    columnSettings: { width: '8rem' },
    uiSettings: {
      displayAs: 'button',
      align: 'end',
      buttonSettings: { icon: 'edit', design: 'Transparent', action: 'edit' },
    },
    group: { name: 'actions', label: '', multiline: false },
  },
  // Second field — columnSettings and uiSettings.align are ignored here
  {
    uiSettings: {
      displayAs: 'button',
      buttonSettings: {
        icon: 'decline',
        design: 'Transparent',
        action: 'delete',
      },
    },
    group: { name: 'actions', label: '', multiline: false },
  },
];

Conditional cell styling (cssRules)

Apply inline styles to a cell when its value meets a condition:

{
  label: 'Status',
  property: 'status.phase',
  uiSettings: {
    cssRules: [
      { if: { condition: 'equals',    value: 'Running' }, styles: { color: 'green' } },
      { if: { condition: 'equals',    value: 'Failed' },  styles: { color: 'red', fontWeight: 'bold' } },
      { if: { condition: 'contains',  value: 'Pending' }, styles: { color: 'orange' } },
    ],
  },
}

Available conditions: equals, notEquals, greaterThan, greaterThanOrEqual, lessThan, lessThanOrEqual, contains.

cssCustomization applies static styles unconditionally:

uiSettings: {
  cssCustomization: {
    fontStyle: 'italic';
  }
}

Value rules (valueRules)

Map a cell's raw value to a display string. The first matching rule wins; when no rule matches the raw value is shown unchanged.

{
  label: 'Activity',
  property: 'metrics.score',
  uiSettings: {
    valueRules: [
      { if: { condition: 'lessThan',           value: '20' }, then: 'Low'    },
      { if: { condition: 'lessThan',           value: '60' }, then: 'Medium' },
      { if: { condition: 'greaterThanOrEqual', value: '60' }, then: 'High'   },
    ],
    cssRules: [
      { if: { condition: 'lessThan',           value: '20' }, styles: { color: 'red'       } },
      { if: { condition: 'greaterThanOrEqual', value: '20' }, styles: { color: 'darkorange' } },
      { if: { condition: 'greaterThanOrEqual', value: '60' }, styles: { color: 'green'     } },
    ],
  },
}

Pagination

When hasMore is true a load-more trigger appears at the bottom of the table. The trigger behaviour is controlled by loadMode:

  • loadMode: 'button' (default) — a button labelled with loadMoreButtonText is shown. Clicking it fires loadMoreResources.
  • loadMode: 'scroll' — loading is triggered automatically as the user scrolls. Set height to constrain the table height and enable scroll detection.
  • loadMode: 'pager' — numbered pagination controls are shown instead of a load-more trigger. Provide totalItemsCount and (optionally) currentPage; the table fires pageChange with the 1-based page number when the user navigates. paginationLimit sets the page size.

A page-size selector is always present.

Scrolling and the sticky header

The component lays itself out as a column: the ui5-table sits above the page-size/count footer. By default it is content-sized — the table grows with its rows, so a load-more click makes it taller and the load-more trigger always sits directly under the last row.

Set height to constrain it instead. The ui5-table then scrolls its data rows inside that height, while the column header row and the footer stay put.

height sizes the ui5-table box alone — the page-size footer sits below it — so a table given height: 200 renders about 260 px tall once the footer is counted. DeclarativeTableCard does that arithmetic for you when it is given a contentHeight, which is how a table card fits a dashboard tile.

The header row is sticky in both cases; where the table does not scroll that has no visible effect. Earlier versions made it sticky only for loadMode: 'scroll' and a set height, which left the column headers scrolling out of view whenever the table scrolled for any other reason.

Resource shape

Any plain object works as a resource. Three optional fields control table behaviour:

Field Type Description
id string Default trackByPath target; used as the row identity key unless overridden
isAvailable boolean When false, the row is rendered as non-interactive
accessibleName string Accessible label attached to the row element

TableErrorConfig

Controls the content of the error illustrated message shown when error is set.

interface TableErrorConfig {
  status?: number; // HTTP status code — 403 switches to the 'UnsuccessfulAuth' illustration
  title?: string; // Heading text rendered above the error illustration
  message?: string; // Subtitle text with additional context
  withRetryButton?: boolean; // When true, a Retry button is shown; clicking it emits the `retry` output
  retryButtonText?: string; // Button label, defaults to 'Retry'
}

Examples:

// Generic error — no retry
error = {};

// Generic error with retry
error = { withRetryButton: true };

// 403 Forbidden — distinct illustration, no retry
error = {
  status: 403,
  title: 'Access Denied',
  message: 'You do not have permission to view this resource.',
};

// Generic error with all fields
error = {
  status: 500,
  title: 'Failed to load data',
  message: 'An unexpected error occurred. Please try again.',
  withRetryButton: true,
};

Test IDs

All interactive elements carry data-testid attributes for reliable E2E targeting. See docs/test-ids.md for the full naming convention.

Element data-testid Notes
Table element generic-table
Header cell generic-table-header-{column} column = group.name or property
Row generic-table-row-{i} i = 0-based index
Cell (simple column) generic-table-cell-{i}-{property}
Cell (grouped column) generic-table-cell-{i}-{group} group = group.name
Group sub-value generic-table-cell-{i}-{group}-{property}
No-data state generic-table-view-nodata Shown when resources is empty
Error state generic-table-view-error Shown when error is set
Error title generic-table-error-title Shown when error.title is set
Retry button generic-table-retry Shown when error.withRetryButton is true
Load-more trigger generic-table-growing Shown when hasMore is true
Page-size select generic-table-pagination-select Always present