@justeattakeaway/pie-data-table 0.3.24 → 0.3.25

package/README.md

@@ -1,4 +1,5 @@
 # @justeattakeaway/pie-data-table
+
 [Source Code](https://github.com/justeattakeaway/pie/tree/main/packages/components/pie-data-table) | [Design Documentation](https://pie.design/components/data-table) | [NPM](https://www.npmjs.com/package/@justeattakeaway/pie-data-table)
 
 <p>
@@ -7,16 +8,29 @@
   </a>
 </p>
 
-`@justeattakeaway/pie-data-table` is a Web Component built using the Lit library. It offers a simple and accessible button component for web applications.
+`@justeattakeaway/pie-data-table` is a Web Component built using the Lit library. It offers a simple and accessible data table component for displaying structured tabular data in web applications.
+
+
 
 ## Table of Contents
 
 - [Installation](#installation)
 - [Documentation](#documentation)
-  - [Properties](#properties)
-  - [Slots](#slots)
-  - [CSS Variables](#css-variables)
-  - [Events](#events)
+  - [Usage approaches](#usage-approaches)
+  - [Components](#components)
+  - [pie-data-table](#pie-data-table-1)
+    - [Properties](#properties)
+    - [Slots](#slots)
+    - [CSS Variables](#css-variables)
+    - [Events](#events)
+  - [pie-data-table-header](#pie-data-table-header-1)
+    - [Properties](#properties-1)
+    - [Slots](#slots-1)
+    - [CSS Variables](#css-variables-1)
+  - [pie-data-table-row](#pie-data-table-row-1)
+    - [Properties](#properties-2)
+  - [pie-data-table-cell and pie-data-table-head-cell](#pie-data-table-cell-and-pie-data-table-head-cell)
+    - [Properties](#properties-3)
 - [Usage Examples](#usage-examples)
 - [Questions and Support](#questions-and-support)
 - [Contributing](#contributing)
@@ -29,25 +43,147 @@ Ideally, you should install the component using the **`@justeattakeaway/pie-webc
 
 ## Documentation
 
-### Properties
-| Prop             | Options                                                                                                                                                                  | Description                                                                                                                                                                                                         | Default        |
-|------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------|
-| | | | |
+### Usage approaches
+
+`pie-data-table` supports two rendering approaches:
+
+- **Data-driven:** Pass `columns` and `data` props directly to `pie-data-table` and the component renders the table automatically. This is the simplest approach for straightforward tabular data.
+- **Composable:** Use the individual sub-components to build the table structure yourself. Choose this approach when you need full control over cell content, for example, to render icons, badges, or interactive elements inside cells.
+
+### Components
+
+This package includes the following components:
+
+- `pie-data-table` — the root table component
+- `pie-data-table-header` — optional header above the table with heading, sub-heading, and action buttons
+- `pie-data-table-contents` — wrapper for the underlying `<table>` element
+- `pie-data-table-head` — wrapper for `<thead>`
+- `pie-data-table-body` — wrapper for `<tbody>`
+- `pie-data-table-row` — wrapper for `<tr>`
+- `pie-data-table-head-cell` — wrapper for `<th>`
+- `pie-data-table-cell` — wrapper for `<td>`
+
+---
+
+### Components Specification
+
+### `pie-data-table`
+
+The root component. When `columns` and `data` props are both provided, it automatically renders an HTML table. When either is absent, the default slot is rendered instead, allowing you to display an empty state or compose the table manually using the sub-components.
+
+#### Properties
+
+| Prop             | Options | Description                                                                                                                          | Default |
+|------------------|---------|--------------------------------------------------------------------------------------------------------------------------------------|---------|
+| `columns`        | —       | Array of column definition objects. Each column must have an `id` and `heading`. Optional: `textAlign`, `width`, `accessor`. See [Column definition](#column-definition). | `[]`    |
+| `data`           | —       | Array of data objects to display. Each object's keys are matched against the `accessor` property of each column definition.          | `[]`    |
+| `additionalRows` | —       | Array of additional row objects to render inside a `<tfoot>`. Useful for summary or total rows. See [Additional rows](#additional-rows). | `[]`    |
+
+##### Column definition
+
+Each entry in the `columns` array is an object with the following shape:
+
+| Key         | Type                              | Required | Description                                               |
+|-------------|-----------------------------------|----------|-----------------------------------------------------------|
+| `id`        | `string`                          | Yes      | Unique identifier for the column.                         |
+| `heading`   | `string`                          | Yes      | Display text for the column heading.                      |
+| `textAlign` | `'left'` \| `'right'` \| `'center'` | No    | Text alignment for the column header and body cells.      |
+| `width`     | `string`                          | No       | Inline width applied to the `<th>` element (e.g. `'200px'`). |
+| `accessor`  | `string`                          | No       | Key in each data row object whose value is rendered in this column. If omitted, the cell renders empty. |
+
+##### Additional rows
+
+Each entry in the `additionalRows` array has the following shape:
+
+| Key       | Type      | Description                            |
+|-----------|-----------|----------------------------------------|
+| `cells`   | `AdditionalCell[]` | Array of cell objects for this row. |
+| `hideRow` | `boolean` | When `true`, the row is hidden via CSS. |
+
+Each `AdditionalCell` object:
+
+| Key        | Type                              | Description                                               |
+|------------|-----------------------------------|-----------------------------------------------------------|
+| `content`  | `string` \| `number`             | The content to render in the cell.                        |
+| `textAlign`| `'left'` \| `'right'` \| `'center'` | Text alignment for the cell.                          |
+| `colSpan`  | `number`                          | Number of columns the cell should span. Defaults to `1`. |
+| `hideCell` | `boolean`                         | When `true`, the cell is hidden via CSS.                  |
+
+#### Slots
+
+| Slot           | Description                                                                                                                   |
+|----------------|-------------------------------------------------------------------------------------------------------------------------------|
+| `table-header` | Slot for placing a `pie-data-table-header` or custom header content above the table.                                         |
+| `default`      | Rendered when there is no data to display (i.e. `data` or `columns` is empty). Use this slot to display an empty state view. |
+
+#### CSS Variables
+
+| Variable                               | Description                                          | Default                              |
+|----------------------------------------|------------------------------------------------------|--------------------------------------|
+| `--data-table-background-color`        | Background colour of the table container.            | `var(--dt-color-container-default)`  |
+| `--data-table-background-hover-or-active` | Background colour on row hover.                   | `var(--dt-color-container-subtle)`   |
+| `--data-table-border-color`            | Colour of all table borders.                         | `var(--dt-color-border-default)`     |
+| `--data-table-border-radius`           | Border radius of the table container.                | `var(--dt-radius-rounded-c)`         |
+| `--data-table-text-color`              | Text colour used across the table.                   | `var(--dt-color-content-default)`    |
+
+#### Events
+
+`pie-data-table` does not emit any custom events.
+
+---
+
+### `pie-data-table-header`
+
+An optional header component to be placed in the `table-header` slot of `pie-data-table`. It supports a heading, a sub-heading, and action buttons.
+
+#### Properties
+
+| Prop         | Options                     | Description                                       | Default    |
+|--------------|-----------------------------|---------------------------------------------------|------------|
+| `heading`    | —                           | The heading text displayed in the header.         | —          |
+| `subHeading` | —                           | Optional sub-heading text below the heading.      | —          |
+| `variant`    | `'subtle'`, `'strong'`      | Controls the visual emphasis of the header. `'strong'` applies a brand background colour. | `'subtle'` |
+
+#### Slots
+
+| Slot            | Description                                                                                   |
+|-----------------|-----------------------------------------------------------------------------------------------|
+| `action-button` | Slot for one or more action buttons (e.g. `pie-button`) to display on the right side of the header. The wrapper is hidden when no elements are slotted. |
+
+#### CSS Variables
+
+| Variable                          | Description                                         | Default                                   |
+|-----------------------------------|-----------------------------------------------------|-------------------------------------------|
+| `--data-table-header-background`  | Background colour of the header.                    | `transparent` (`'strong'` variant: `var(--dt-color-support-brand-02)`) |
+| `--data-table-border-color`       | Colour of the bottom border of the header.          | `var(--dt-color-border-default)`          |
+
+---
 
-### Slots
-| Slot     | Description                                                                                                                                                                                                                                                                         |
-|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-|  | |
+### `pie-data-table-row`
 
-### CSS Variables
-| Variable | Description                                                                                                                                                                                                                 | Default |
-|----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------|
-| | | |
+A row component wrapping `<tr>`. Use this when composing the table manually via sub-components.
 
-### Events
-| Event | Type                                                                                                                                                                                                                 | Description |
-|------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------|
-| | | |
+#### Properties
+
+| Prop         | Options         | Description                              | Default |
+|--------------|-----------------|------------------------------------------|---------|
+| `isSelected` | `true`, `false` | Whether the row is in a selected state.  | `false` |
+| `isHidden`   | `true`, `false` | Whether the row is hidden.               | `false` |
+
+---
+
+### `pie-data-table-cell` and `pie-data-table-head-cell`
+
+Cell components wrapping `<td>` and `<th>` respectively. Use these when composing the table manually via sub-components.
+
+#### Properties
+
+| Prop        | Options                               | Description                              | Default  |
+|-------------|---------------------------------------|------------------------------------------|----------|
+| `textAlign` | `'left'`, `'right'`, `'center'`       | Text alignment for the cell content.     | `'left'` |
+| `isHidden`  | `true`, `false`                       | Whether the cell is hidden.              | `false`  |
+
+---
 
 ## Usage Examples
 
@@ -60,16 +196,84 @@ import '@justeattakeaway/pie-webc/components/data-table.js'
 
 ```html
 <!-- pass js file into <script> tag -->
-
+<pie-data-table></pie-data-table>
 <script type="module" src="/main.js"></script>
 ```
 
+**Passing columns and data (automatic rendering):**
+
+```html
+<pie-data-table id="my-table"></pie-data-table>
+
+<script type="module">
+  import '@justeattakeaway/pie-webc/components/data-table.js';
+
+  const table = document.querySelector('#my-table');
+
+  table.columns = [
+    { id: 'name', heading: 'Name', accessor: 'name' },
+    { id: 'amount', heading: 'Amount', accessor: 'amount', textAlign: 'right' },
+  ];
+
+  table.data = [
+    { name: 'Order 1', amount: '£10.00' },
+    { name: 'Order 2', amount: '£25.50' },
+  ];
+</script>
+```
+
+**With a header and additional footer rows:**
+
+```html
+<pie-data-table id="my-table">
+  <pie-data-table-header
+    slot="table-header"
+    heading="Recent Orders"
+    sub-heading="Last 30 days"
+    variant="strong"
+  ></pie-data-table-header>
+</pie-data-table>
+
+<script type="module">
+  import '@justeattakeaway/pie-webc/components/data-table.js';
+  import '@justeattakeaway/pie-webc/components/data-table-header.js';
+
+  const table = document.querySelector('#my-table');
+
+  table.columns = [
+    { id: 'name', heading: 'Name', accessor: 'name' },
+    { id: 'total', heading: 'Total', accessor: 'total', textAlign: 'right' },
+  ];
+
+  table.data = [
+    { name: 'Order 1', total: '£10.00' },
+    { name: 'Order 2', total: '£25.50' },
+  ];
+
+  table.additionalRows = [
+    {
+      cells: [
+        { content: 'Grand Total', textAlign: 'left' },
+        { content: '£35.50', textAlign: 'right' },
+      ],
+    },
+  ];
+</script>
+```
+
+**Displaying an empty state:**
+
+```html
+<pie-data-table>
+  <p>No orders found.</p>
+</pie-data-table>
+```
+
 **For Native JS Applications, Vue, Angular, Svelte etc.:**
 
 ```js
 // Vue templates (using Nuxt 3)
 import '@justeattakeaway/pie-webc/components/data-table.js'
-
 ```
 
 **For React Applications:**
@@ -77,6 +281,54 @@ import '@justeattakeaway/pie-webc/components/data-table.js'
 ```jsx
 import { PieDataTable } from '@justeattakeaway/pie-webc/react/data-table.js';
 
+<PieDataTable
+  columns={[
+    { id: 'name', heading: 'Name', accessor: 'name' },
+    { id: 'amount', heading: 'Amount', accessor: 'amount', textAlign: 'right' },
+  ]}
+  data={[
+    { name: 'Order 1', amount: '£10.00' },
+    { name: 'Order 2', amount: '£25.50' },
+  ]}
+/>
+```
+
+**Manual composition using sub-components (React):**
+
+Use this approach when you need full control over the table structure — for example, to render custom cell content such as icons, badges, or interactive elements.
+
+```jsx
+import { PieDataTable } from '@justeattakeaway/pie-webc/react/data-table.js';
+import { PieDataTableContents } from '@justeattakeaway/pie-webc/react/data-table-contents.js';
+import { PieDataTableHead } from '@justeattakeaway/pie-webc/react/data-table-head.js';
+import { PieDataTableBody } from '@justeattakeaway/pie-webc/react/data-table-body.js';
+import { PieDataTableRow } from '@justeattakeaway/pie-webc/react/data-table-row.js';
+import { PieDataTableHeadCell } from '@justeattakeaway/pie-webc/react/data-table-head-cell.js';
+import { PieDataTableCell } from '@justeattakeaway/pie-webc/react/data-table-cell.js';
+
+const orders = [
+  { id: '001', name: 'Order 1', amount: '£10.00' },
+  { id: '002', name: 'Order 2', amount: '£25.50' },
+];
+
+<PieDataTable>
+  <PieDataTableContents>
+    <PieDataTableHead>
+      <PieDataTableRow>
+        <PieDataTableHeadCell>Order</PieDataTableHeadCell>
+        <PieDataTableHeadCell textAlign="right">Amount</PieDataTableHeadCell>
+      </PieDataTableRow>
+    </PieDataTableHead>
+    <PieDataTableBody>
+      {orders.map((order) => (
+        <PieDataTableRow key={order.id}>
+          <PieDataTableCell>{order.name}</PieDataTableCell>
+          <PieDataTableCell textAlign="right">{order.amount}</PieDataTableCell>
+        </PieDataTableRow>
+      ))}
+    </PieDataTableBody>
+  </PieDataTableContents>
+</PieDataTable>
 ```
 
 ## Questions and Support

package/dist/{PieElement-BxYpXACw.js → PieElement-DtKzrWh3.js}

@@ -4,7 +4,7 @@ const t = class t extends i {
     this.getAttribute("v") || this.setAttribute("v", t.v);
   }
 };
-t.v = "0.3.24";
+t.v = "0.3.25";
 let s = t;
 export {
   s as P

package/dist/index.js

@@ -1,6 +1,6 @@
 import { nothing as c, html as l, unsafeCSS as g } from "lit";
 import { property as h } from "lit/decorators.js";
-import { P as p } from "./PieElement-BxYpXACw.js";
+import { P as p } from "./PieElement-DtKzrWh3.js";
 import { RtlMixin as u, safeCustomElement as f } from "@justeattakeaway/pie-webc-core";
 import { classMap as n } from "lit/directives/class-map.js";
 const v = "*,*:after,*:before{box-sizing:inherit}:host{display:block}.c-data-table{--data-table-background-color: var(--dt-color-container-default);--data-table-background-hover-or-active: var(--dt-color-container-subtle);--data-table-border-color: var(--dt-color-border-default);--data-table-border-radius: var(--dt-radius-rounded-c);--data-table-text-color: var(--dt-color-content-default);background-color:var(--data-table-background-color);border:1px solid var(--data-table-border-color);border-radius:var(--data-table-border-radius);color:var(--data-table-text-color);width:100%;overflow:hidden}.c-data-table table{border-spacing:0;width:100%}.c-data-table tbody{overflow:auto}.c-data-table tbody tr:hover{background-color:var(--data-table-background-hover-or-active)}.c-data-table-head-cell{background-color:transparent;font-size:calc(var(--dt-font-body-strong-l-size) * 1px);line-height:calc(var(--dt-font-body-strong-l-line-height) * 1px);font-weight:var(--dt-font-body-strong-l-weight);color:var(--data-table-text-color);text-align:left}.c-data-table-head-cell-text-align--left,.c-data-table-cell-text-align--left{text-align:left}.c-data-table-head-cell-text-align--right,.c-data-table-cell-text-align--right{text-align:right}.c-data-table-head-cell-text-align--center,.c-data-table-cell-text-align--center{text-align:center}.c-data-table-cell,.c-data-table-head-cell{padding:var(--dt-spacing-d);border-bottom:1px solid var(--data-table-border-color)}.c-data-table-cell--hidden,.c-data-table-row--hidden{display:none}", m = {

package/dist/pie-data-table-body/index.js

@@ -1,5 +1,5 @@
 import { unsafeCSS as p, html as d } from "lit";
-import { P as i } from "../PieElement-BxYpXACw.js";
+import { P as i } from "../PieElement-DtKzrWh3.js";
 import { safeCustomElement as m } from "@justeattakeaway/pie-webc-core";
 const b = ":host{display:table-row-group}:host ::slotted(pie-data-table-row){--pie-data-table-row-background-hover: var(--dt-color-container-subtle)}";
 var u = Object.getOwnPropertyDescriptor, c = (o, a, n, s) => {

package/dist/pie-data-table-cell/index.js

@@ -1,6 +1,6 @@
 import { unsafeCSS as c, nothing as d, html as f } from "lit";
 import { property as p } from "lit/decorators.js";
-import { P as g } from "../PieElement-BxYpXACw.js";
+import { P as g } from "../PieElement-DtKzrWh3.js";
 import { validPropertyValues as b, safeCustomElement as h } from "@justeattakeaway/pie-webc-core";
 const m = ":host{padding:var(--dt-spacing-d);border-bottom:1px solid var(--data-table-border-color);display:table-cell}:host([textAlign=right]){text-align:right}:host([textAlign=center]){text-align:center}:host([textAlign=left]){text-align:left}:host([isHidden]){display:none}", x = ["left", "right", "center"], u = {
   textAlign: "left",

package/dist/pie-data-table-contents/index.js

@@ -1,5 +1,5 @@
 import { unsafeCSS as i, html as c } from "lit";
-import { P as m } from "../PieElement-BxYpXACw.js";
+import { P as m } from "../PieElement-DtKzrWh3.js";
 import { safeCustomElement as p } from "@justeattakeaway/pie-webc-core";
 const b = ":host{inline-size:100%;display:table}";
 var f = Object.getOwnPropertyDescriptor, u = (r, l, o, a) => {

package/dist/pie-data-table-head/index.js

@@ -1,5 +1,5 @@
 import { unsafeCSS as d, html as i } from "lit";
-import { P as c } from "../PieElement-BxYpXACw.js";
+import { P as c } from "../PieElement-DtKzrWh3.js";
 import { safeCustomElement as b } from "@justeattakeaway/pie-webc-core";
 const p = ":host{background-color:transparent;font-size:calc(var(--dt-font-body-strong-l-size) * 1px);line-height:calc(var(--dt-font-body-strong-l-line-height) * 1px);font-weight:var(--dt-font-body-strong-l-weight);color:var(--dt-color-content-default);border-bottom:1px solid var(--data-table-border-color);display:table-header-group}";
 var f = Object.getOwnPropertyDescriptor, h = (o, a, n, l) => {

package/dist/pie-data-table-head-cell/index.js

@@ -1,6 +1,6 @@
 import { unsafeCSS as p, nothing as c, html as f } from "lit";
 import { property as d } from "lit/decorators.js";
-import { P as h } from "../PieElement-BxYpXACw.js";
+import { P as h } from "../PieElement-DtKzrWh3.js";
 import { validPropertyValues as g, safeCustomElement as b } from "@justeattakeaway/pie-webc-core";
 const m = ":host{padding:var(--dt-spacing-d);border-bottom:1px solid var(--data-table-border-color);display:table-cell}:host([textAlign=right]){text-align:right}:host([textAlign=center]){text-align:center}:host([textAlign=left]){text-align:left}:host([isHidden]){display:none}", x = ["left", "right", "center"], u = {
   textAlign: "left",

package/dist/pie-data-table-header/index.js

@@ -1,6 +1,6 @@
 import { unsafeCSS as p, nothing as h, html as d } from "lit";
 import { property as c, queryAssignedElements as g, state as b } from "lit/decorators.js";
-import { P as f } from "../PieElement-BxYpXACw.js";
+import { P as f } from "../PieElement-DtKzrWh3.js";
 import { validPropertyValues as u, safeCustomElement as m } from "@justeattakeaway/pie-webc-core";
 import { classMap as v } from "lit/directives/class-map.js";
 const y = "*,*:after,*:before{box-sizing:inherit}:host{display:block}.c-data-table-header{--data-table-header-background: transparent;--data-table-border-color: var(--dt-color-border-default);padding:var(--dt-spacing-d);background-color:var(--data-table-header-background);border-bottom:1px solid var(--data-table-border-color);display:flex;justify-content:space-between;align-items:flex-end}.c-data-table-header-heading-wrapper{display:flex;flex-direction:column;gap:var(--dt-spacing-b)}.c-data-table-header-heading{font-family:var(--dt-font-heading-m-family);font-weight:var(--dt-font-heading-m-weight);font-size:calc(var(--dt-font-heading-m-size--wide) * 1px);line-height:calc(var(--dt-font-heading-m-line-height--wide) * 1px)}.c-data-table-header-sub-heading{font-family:var(--dt-font-body-l-family);font-weight:var(--dt-font-body-l-weight);font-size:calc(var(--dt-font-body-l-size) * 1px);line-height:calc(var(--dt-font-body-l-line-height) * 1px)}.c-data-table-header--strong{--data-table-header-background: var(--dt-color-support-brand-02)}.c-data-table-action-buttons-wrapper{display:flex;gap:var(--dt-spacing-d)}", w = ["subtle", "strong"], x = {

package/dist/pie-data-table-row/index.js

@@ -1,6 +1,6 @@
 import { unsafeCSS as d, nothing as c, html as f } from "lit";
 import { property as i } from "lit/decorators.js";
-import { P as b } from "../PieElement-BxYpXACw.js";
+import { P as b } from "../PieElement-DtKzrWh3.js";
 import { safeCustomElement as m } from "@justeattakeaway/pie-webc-core";
 const u = ":host{display:table-row;border-bottom:1px solid var(--data-table-border-color)}:host(:hover){background-color:var(--pie-data-table-row-background-hover, transparent)}:host([isSelected]){background-color:var(--dt-color-container-subtle)}", S = {
   isSelected: !1,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@justeattakeaway/pie-data-table",
   "description": "PIE Design System Data Table built using Web Components",
-  "version": "0.3.24",
+  "version": "0.3.25",
   "type": "module",
   "main": "dist/index.js",
   "module": "dist/index.js",