@justeattakeaway/pie-list 0.4.0 → 0.6.0

package/README.md

@@ -9,9 +9,6 @@
 
 `@justeattakeaway/pie-list` is a Web Component built using the Lit library. It provides a simple, accessible list built from two elements: a `pie-list` container and one or more `pie-list-item` children.
 
-> [!NOTE]
-> This component is still growing. More properties, slots and sub-components will be added over time. This documentation covers what is currently supported.
-
 ## Table of Contents
 
 - [Installation](#installation)
@@ -37,6 +34,8 @@
     - [Multi-select (checkboxes)](#multi-select-checkboxes)
     - [Independent toggles (switches)](#independent-toggles-switches)
   - [Link items](#link-items)
+    - [Indicating the current page](#indicating-the-current-page)
+  - [Button items](#button-items)
   - [Framework variants](#framework-variants)
 - [Usage Notes and Rules](#usage-notes-and-rules)
 - [Questions and Support](#questions-and-support)
@@ -50,7 +49,7 @@ Ideally, you should install the component using the **`@justeattakeaway/pie-webc
 
 ## Documentation
 
-`pie-list` is a compound component. The `pie-list` element is the container (it applies the `list` role and renders the dividers between items), and each row is a `pie-list-item` (which applies the `listitem` role).
+`pie-list` is a compound component. The `pie-list` element is the container (it applies the `list` role), and each row is a `pie-list-item` (which applies the `listitem` role). Set `hasDivider` on each item that needs a divider except for the last one.
 
 > [!IMPORTANT]
 > Because `pie-list` uses the `list` role, you **must always give it an accessible name** using either `aria-label` or `aria-labelledby`. Without one, screen reader users get no context for what the list contains. See [Accessibility](#accessibility).
@@ -71,8 +70,10 @@ Ideally, you should install the component using the **`@justeattakeaway/pie-webc
 | `isCompact` | `true`, `false` | Decreases the item height to save vertical space. See the [rules](#usage-notes-and-rules) below. | `false` |
 | `isBold` | `true`, `false` | Sets the primary text to a bold font-weight. | `false` |
 | `hasMedia` | `true`, `false` | **Required whenever you slot a media element (e.g. `pie-thumbnail`) into the item.** Reduces the block padding so single-line media sits correctly (this padding adjustment has no effect when `secondaryText` is set, but you should still set `hasMedia`). | `false` |
-| `interactionType` | `"none"`, `"radio"`, `"checkbox"`, `"switch"`, `"link"` | Declares how the **whole row** behaves, and drives its role, accessible naming, click forwarding and interactive states from this one prop. `"none"` is a static item; `"radio"`/`"checkbox"`/`"switch"` host the matching control in the `leading`/`trailing` slot; `"link"` turns the row into a single navigation link (slot an empty `<a slot="link" href="...">`). See [Selectable lists](#selectable-lists) and [Link items](#link-items). | `"none"` |
+| `interactionType` | `"none"`, `"radio"`, `"checkbox"`, `"switch"`, `"link"`, `"button"` | Declares how the **whole row** behaves, and drives its role, accessible naming, click forwarding and interactive states from this one prop. `"none"` is a static item; `"radio"`/`"checkbox"`/`"switch"` host the matching control in the `leading`/`trailing` slot; `"link"` turns the row into a single navigation link (slot an empty `<a slot="link" href="...">`); `"button"` turns the row into a single button for an in-page action (the item renders the button for you - listen for `click`). See [Selectable lists](#selectable-lists), [Link items](#link-items) and [Button items](#button-items). | `"none"` |
 | `disabled` | `true`, `false` | Marks the row as disabled: it takes the disabled styling and stops forwarding row clicks to its control. Set it alongside the slotted control's own `disabled` (the control still governs its own interactivity). No visible effect on a non-selectable (static) item. | `false` |
+| `hasDivider` | `true`, `false` | Renders a bottom divider line on the item. Do not set this to `true` on the last item in a list. | `false` |
+| `aria` | `{ button?: { haspopup?: "menu" \| "listbox" \| "tree" \| "grid" \| "dialog" \| "true" } }` | Additional ARIA properties that the item cannot derive from its text props. `button.haspopup` only applies when `interactionType="button"` and is forwarded to the internal `<button>` element. Set it when the button row triggers a popup such as a dialog or menu. | `undefined` |
 
 ### Slots
 
@@ -118,7 +119,7 @@ This component does not emit any custom events. To listen for interactions, trea
 
   ```html
   <pie-list aria-label="Payment methods">
-    <pie-list-item primaryText="Credit card"></pie-list-item>
+    <pie-list-item hasDivider primaryText="Credit card"></pie-list-item>
     <pie-list-item primaryText="PayPal"></pie-list-item>
   </pie-list>
   ```
@@ -128,7 +129,7 @@ This component does not emit any custom events. To listen for interactions, trea
   ```html
   <h2 id="payment-methods-heading">Payment methods</h2>
   <pie-list aria-labelledby="payment-methods-heading">
-    <pie-list-item primaryText="Credit card"></pie-list-item>
+    <pie-list-item hasDivider primaryText="Credit card"></pie-list-item>
     <pie-list-item primaryText="PayPal"></pie-list-item>
   </pie-list>
   ```
@@ -141,22 +142,22 @@ This component does not emit any custom events. To listen for interactions, trea
 Specifically, for **every** interaction type the item takes care of:
 
 - the **role** on the item itself (`listitem`, or `presentation` for radio/checkbox rows so the group owns the control directly) - you never write `role="..."`;
-- the **accessible name and description** of whatever it hosts - you never write `aria-label`, `aria-labelledby`, `aria-description` or `aria-describedby` on the control or anchor;
+- the **accessible name and description** of whatever it hosts - you never write `aria-label`, `aria-labelledby`, `aria-description` or `aria-describedby` on the control, anchor or button;
 - **hiding the duplicated visible text** from assistive technology (the item `aria-hidden`s its own text once the name/description have been mirrored onto the interactive element), so nothing is announced twice.
 
 The one accessibility attribute you **do** own is the accessible name of the `pie-list` container itself (`aria-label` / `aria-labelledby`), because only you know what the list represents. See the note above.
 
 ### How the naming is derived
 
-When a `pie-list-item` hosts an interactive element (a slotted control set via `interactionType="radio" | "checkbox" | "switch"`, or a slotted link anchor via `interactionType="link"`) it generates that element's accessibility naming from its own text:
+When a `pie-list-item` hosts an interactive element (a slotted control set via `interactionType="radio" | "checkbox" | "switch"`, a slotted link anchor via `interactionType="link"`, or the button it renders for `interactionType="button"`) it generates that element's accessibility naming from its own text:
 
-- `primaryText` becomes the control's **accessible name**;
+- `primaryText` becomes the element's **accessible name**;
 - `secondaryText` and `metaText` become its **accessible description** (combined with a full stop when both are present);
-- the visible text rendered inside the item is `aria-hidden`, so a screen reader announces the name and description once (via the control) rather than twice.
+- the visible text rendered inside the item is `aria-hidden`, so a screen reader announces the name and description once (via the interactive element) rather than twice.
 
-How the naming reaches the element differs by type, but this is entirely internal - you never do it yourself. Selection controls receive it through a shared context and each applies it to the element that carries its role: `pie-radio` names its host, while `pie-checkbox` and `pie-switch` name their internal `input` (their host is role-less). A link anchor is a plain light-DOM element (not a PIE control), so `pie-list-item` sets `aria-label` and `aria-description` on it directly.
+How the naming reaches the element differs by type, but this is entirely internal - you never do it yourself. Selection controls receive it through a shared context and each applies it to the element that carries its role: `pie-radio` names its host, while `pie-checkbox` and `pie-switch` name their internal `input` (their host is role-less). A link anchor is a plain light-DOM element you slot (not a PIE control), so `pie-list-item` sets `aria-label` and `aria-description` on it directly. A `button` row's button is one the item renders itself, so it is named the same way from within the item.
 
-**If you do set something yourself, it always wins.** If a slotted control already has its own name (its `label` or `aria` prop), or the slotted anchor already has an `aria-label`/`aria-labelledby` (or `aria-description`/`aria-describedby`), the item leaves it untouched and does not overwrite it. This is an escape hatch for the rare case that needs it, not something you normally reach for.
+**For slotted elements, anything you set yourself wins.** If a slotted control already has its own name (its `label` or `aria` prop), or the slotted link anchor already has an `aria-label`/`aria-labelledby` (or `aria-description`/`aria-describedby`), the item leaves it untouched and does not overwrite it. This is an escape hatch for the rare case that needs it, not something you normally reach for. (A `button` row's button is rendered and named by the item, so there is nothing for you to set.)
 
 ## Usage Examples
 
@@ -175,10 +176,12 @@ A basic list with primary, secondary and meta text (note the required `aria-labe
 ```html
 <pie-list aria-label="Recent orders">
   <pie-list-item
+    hasDivider
     primaryText="Primary text"
     secondaryText="Secondary text"
     metaText="Meta text"></pie-list-item>
   <pie-list-item
+    hasDivider
     primaryText="Primary text"
     secondaryText="Secondary text"></pie-list-item>
   <pie-list-item primaryText="Primary text"></pie-list-item>
@@ -242,7 +245,7 @@ Reduced height, see [rules](#usage-notes-and-rules):
 
 ```html
 <pie-list>
-  <pie-list-item isCompact primaryText="Primary text">
+  <pie-list-item hasDivider isCompact primaryText="Primary text">
     <icon-chevron-right slot="trailing"></icon-chevron-right>
   </pie-list-item>
   <pie-list-item isCompact primaryText="Primary text">
@@ -324,10 +327,10 @@ import '@justeattakeaway/pie-webc/components/list-item.js';
 ```
 
 ```html
-<!-- `interactionType="radio"` makes each row selectable and the group lays them out as a divided
-     list. `value` on the group selects the matching radio (here, Express). -->
+<!-- `interactionType="radio"` makes each row selectable. `value` on the group selects
+     the matching radio (here, Express). -->
 <pie-radio-group name="delivery" value="express">
-  <pie-list-item interactionType="radio" primaryText="Standard delivery" secondaryText="3 to 5 working days" metaText="Free">
+  <pie-list-item hasDivider interactionType="radio" primaryText="Standard delivery" secondaryText="3 to 5 working days" metaText="Free">
     <pie-radio slot="leading" value="standard"></pie-radio>
   </pie-list-item>
   <pie-list-item interactionType="radio" primaryText="Express delivery" secondaryText="Next working day" metaText="£4.99">
@@ -346,7 +349,7 @@ import '@justeattakeaway/pie-webc/components/list-item.js';
 
 ```html
 <pie-checkbox-group>
-  <pie-list-item interactionType="checkbox" primaryText="Cheese" secondaryText="Extra mature" metaText="Free">
+  <pie-list-item hasDivider interactionType="checkbox" primaryText="Cheese" secondaryText="Extra mature" metaText="Free">
     <pie-checkbox slot="leading" name="cheese"></pie-checkbox>
   </pie-list-item>
   <pie-list-item interactionType="checkbox" primaryText="Pepperoni" secondaryText="Spicy">
@@ -367,10 +370,10 @@ import '@justeattakeaway/pie-webc/components/switch.js';
 
 ```html
 <pie-list aria-label="Notification settings">
-  <pie-list-item interactionType="switch" primaryText="Email" secondaryText="Order updates and receipts">
+  <pie-list-item hasDivider interactionType="switch" primaryText="Email" secondaryText="Order updates and receipts">
     <pie-switch slot="trailing"></pie-switch>
   </pie-list-item>
-  <pie-list-item interactionType="switch" primaryText="Push notifications">
+  <pie-list-item hasDivider interactionType="switch" primaryText="Push notifications">
     <pie-switch slot="trailing"></pie-switch>
   </pie-list-item>
   <pie-list-item interactionType="switch" primaryText="SMS" disabled>
@@ -394,7 +397,7 @@ import '@justeattakeaway/pie-webc/components/list-item.js';
 
 ```html
 <pie-list aria-label="Manage your restaurant">
-  <pie-list-item interactionType="link" primaryText="Orders" secondaryText="View and manage live orders" metaText="12 active">
+  <pie-list-item hasDivider interactionType="link" primaryText="Orders" secondaryText="View and manage live orders" metaText="12 active">
     <a slot="link" href="/orders"></a>
   </pie-list-item>
   <pie-list-item interactionType="link" primaryText="Menu" secondaryText="Edit items, prices and photos">
@@ -415,6 +418,104 @@ import { PieListItem } from '@justeattakeaway/pie-webc/react/list-item.js';
 </PieListItem>
 ```
 
+#### Indicating the current page
+
+To highlight the active link in a navigation list, combine `isBold` on the `pie-list-item` with `aria-current="page"` on the slotted anchor. `isBold` gives the active item a heavier weight visually; `aria-current="page"` communicates the current page to assistive technology. `pie-list-item` only manages the anchor's `aria-label` and `aria-description`, so `aria-current` does not conflict with the item's naming logic and is safe to set yourself.
+
+You can also slot a tick icon into the `trailing` slot of the active item as an additional visual indicator. PIE icons render with `role="presentation"` on their SVG, so they are already hidden from assistive technology and no extra `aria-hidden` is needed.
+
+```js
+import '@justeattakeaway/pie-icons-webc/dist/IconCheck.js';
+```
+
+```html
+<pie-list aria-label="Account navigation">
+  <pie-list-item hasDivider interactionType="link" primaryText="Overview">
+    <a slot="link" href="/account"></a>
+  </pie-list-item>
+  <pie-list-item hasDivider interactionType="link" isBold primaryText="Orders">
+    <a slot="link" href="/account/orders" aria-current="page"></a>
+    <icon-check slot="trailing"></icon-check>
+  </pie-list-item>
+  <pie-list-item hasDivider interactionType="link" primaryText="Payment methods">
+    <a slot="link" href="/account/payment"></a>
+  </pie-list-item>
+  <pie-list-item interactionType="link" primaryText="Addresses">
+    <a slot="link" href="/account/addresses"></a>
+  </pie-list-item>
+</pie-list>
+```
+
+In React, pass `isBold` as a prop and `aria-current="page"` directly to the `<Link>` component (or raw anchor):
+
+```jsx
+import { IconCheck } from '@justeattakeaway/pie-icons-webc/dist/IconCheck.js';
+
+<PieListItem interactionType="link" isBold primaryText="Orders">
+  <Link slot="link" href="/account/orders" aria-current="page" />
+  <IconCheck slot="trailing" />
+</PieListItem>
+```
+
+### Button items
+
+Set `interactionType="button"` to turn the whole row into one button. Use this for an **in-page action** (opening a dialog, running a command); use [`link`](#link-items) when the row navigates to another page. Unlike a link, **you do not slot anything** - the item renders the interactive element for you: an invisible, row-sized native `<button type="button">` stretched over the row. A click or tap anywhere on the row activates it, and keyboard focus lands on the row as a whole (the focus ring hugs the row). It is just an action trigger, **not a form control** - it is `type="button"`, so it never submits a form, and it carries no value.
+
+The item names the button from its own text: `primaryText` becomes the button's `aria-label` and `secondaryText`/`metaText` its `aria-description`, and the visible text is hidden from assistive technology so nothing is announced twice (see [You never set ARIA on a list item or its slotted content](#you-never-set-aria-on-a-list-item-or-its-slotted-content)).
+
+**Handle activation by listening for `click`** on the `pie-list-item` (or on the `pie-list`, since the event bubbles). Because it is a real `<button>`, activation is native: both pointer taps and keyboard (Enter, and Space) fire a `click`, so a single `click` listener covers every input. The row shows a pressed tint while it is pressed - by pointer, or while Space is held on the focused row - and the focus ring on keyboard focus. Give the `pie-list` its own accessible name (e.g. `aria-label`).
+
+**When the button opens a popup (dialog, menu, etc.)**, pass the `aria` prop with `button.haspopup` set to the popup type. This is forwarded to the internal `<button>` so assistive technology announces it correctly:
+
+```html
+<!-- A row that opens a dialog -->
+<pie-list-item
+  interactionType="button"
+  primaryText="Delete account"
+  secondaryText="Permanently remove your account"
+  .aria=${{ button: { haspopup: 'dialog' } }}>
+</pie-list-item>
+```
+
+In React:
+
+```jsx
+<PieListItem
+  interactionType="button"
+  primaryText="Delete account"
+  secondaryText="Permanently remove your account"
+  aria={{ button: { haspopup: 'dialog' } }}
+  onClick={openConfirmDialog}
+/>
+```
+
+```js
+import '@justeattakeaway/pie-webc/components/list.js';
+import '@justeattakeaway/pie-webc/components/list-item.js';
+```
+
+```html
+<pie-list aria-label="Account actions">
+  <pie-list-item hasDivider interactionType="button" primaryText="Edit profile" secondaryText="Update your name and photo"></pie-list-item>
+  <pie-list-item interactionType="button" primaryText="Sign out" secondaryText="End your session on this device"></pie-list-item>
+</pie-list>
+
+<script type="module">
+  document.querySelector('pie-list').addEventListener('click', (event) => {
+    const item = event.target.closest('pie-list-item');
+    if (item) runActionFor(item.primaryText);
+  });
+</script>
+```
+
+In React, attach an `onClick` to the item:
+
+```jsx
+import { PieListItem } from '@justeattakeaway/pie-webc/react/list-item.js';
+
+<PieListItem interactionType="button" primaryText="Edit profile" secondaryText="Update your name and photo" onClick={openProfileEditor} />
+```
+
 ### Framework variants
 
 **For Native JS Applications, Vue, Angular, Svelte etc.:**
@@ -448,6 +549,7 @@ To keep lists consistent and correct, follow these rules:
 
 - **Always give `pie-list` an accessible name** with `aria-label` or `aria-labelledby` (use `aria-labelledby` when a visible heading exists). This is required for screen reader users to understand the list. See [Accessibility](#accessibility).
 - **Provide `primaryText`** on every `pie-list-item`; it is the item's main line of content.
+- **Do not set `hasDivider` to `true` on the last item in a list.** Setting it on the last item adds a bottom border beneath the list, which breaks the design. Set `hasDivider` on every item except the last.
 - **For selectable lists, use `pie-list-item` inside `pie-radio-group` or `pie-checkbox-group`, not `pie-list`.** `pie-list` is a static container with no selection or keyboard behaviour. See [Selectable lists](#selectable-lists).
 - **`metaText` and the `trailing` slot are mutually exclusive.** If `metaText` is set, any `trailing` slot content is ignored. Choose one.
 - **Slotted `pie-thumbnail` must use `size="40"`.** This is the only size that fits the list-item layout correctly.

package/custom-elements.json

@@ -70,9 +70,9 @@
           "kind": "variable",
           "name": "interactionTypes",
           "type": {
-            "text": "['none', 'radio', 'checkbox', 'switch', 'link']"
+            "text": "['none', 'radio', 'checkbox', 'switch', 'link', 'button']"
           },
-          "default": "['none', 'radio', 'checkbox', 'switch', 'link']"
+          "default": "['none', 'radio', 'checkbox', 'switch', 'link', 'button']"
         },
         {
           "kind": "variable",
@@ -80,7 +80,7 @@
           "type": {
             "text": "DefaultProps"
           },
-          "default": "{ isCompact: false, isBold: false, hasMedia: false, interactionType: 'none', disabled: false, }"
+          "default": "{ isCompact: false, isBold: false, hasMedia: false, interactionType: 'none', disabled: false, hasDivider: false, }"
         }
       ],
       "exports": [
@@ -174,6 +174,19 @@
               "name": "disabled",
               "attribute": "disabled"
             },
+            {
+              "kind": "field",
+              "name": "hasDivider",
+              "attribute": "hasDivider"
+            },
+            {
+              "kind": "field",
+              "name": "aria",
+              "type": {
+                "text": "ListItemProps['aria']"
+              },
+              "attribute": "aria"
+            },
             {
               "kind": "field",
               "name": "_parentDisabled",
@@ -250,6 +263,24 @@
               "privacy": "private",
               "readonly": true
             },
+            {
+              "kind": "field",
+              "name": "_isButtonRow",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "private",
+              "readonly": true
+            },
+            {
+              "kind": "field",
+              "name": "_isOverlayRow",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "private",
+              "readonly": true
+            },
             {
               "kind": "field",
               "name": "_providesAria",
@@ -295,7 +326,7 @@
                   "text": "void"
                 }
               },
-              "description": "Sets the item's role from `interactionType`: `presentation` for radio/checkbox (so the group\nowns those controls directly), otherwise `listitem` (static items, switches and links). A role\nset explicitly by the consumer is left untouched, even if it is added or removed dynamically\nafter the element connects."
+              "description": "Sets the item's role from `interactionType`: `presentation` for radio/checkbox (so the group\nowns those controls directly), otherwise `listitem` (static items, switches, links and\nbuttons). A role set explicitly by the consumer is left untouched, even if it is added or\nremoved dynamically after the element connects."
             },
             {
               "kind": "field",
@@ -304,7 +335,7 @@
                 "text": "ContextualAria | undefined"
               },
               "privacy": "private",
-              "description": "The accessible name and description this item provides to its slotted control, stitched from\nits text. Only provided in a selectable list. Each control consumes this via `ariaContext`\nand decides how to apply it: `pie-radio` names its host (which carries `role=\"radio\"`),\nwhile `pie-checkbox` / `pie-switch` name their internal input (their host is role-less, so\n`aria-label` there would be invalid). Context reaches across the shadow boundary that\n`aria-labelledby` cannot.",
+              "description": "The accessible name and description this item provides to its interactive element, stitched\nfrom its text. Selection controls consume it via `ariaContext` (each applying it to the\nelement that carries its role); the action button of a `button` row takes it directly as\n`aria-label`/`aria-description` in the template; a link anchor takes it via `_applyLinkAria`.",
               "readonly": true
             },
             {
@@ -322,7 +353,7 @@
                   "text": "void"
                 }
               },
-              "description": "When the item is a link, names the slotted (empty) anchor from the item's own text: the parent\nowns the child's aria. The anchor is plain light-DOM, so it cannot reference the shadow-DOM text\nvia `aria-labelledby`; and it is not a PIE control that consumes `ariaContext`, so we set the\nattributes imperatively. The visible text is `aria-hidden` in the template, so nothing is\nannounced twice.\n\nA consumer-provided name/description always wins: we capture (once) whether the anchor already\ncarries `aria-label`/`aria-labelledby` or `aria-description`/`aria-describedby` and, if so,\nleave that attribute untouched. Otherwise we keep our generated value in sync with the text."
+              "description": "On a link row, names the slotted (empty) anchor from the item's own text: the parent owns the\nchild's aria. The anchor is plain light-DOM, so it cannot reference the shadow-DOM text via\n`aria-labelledby`; and it is not a PIE control that consumes `ariaContext`, so we set the\nattributes imperatively. The visible text is `aria-hidden` in the template, so nothing is\nannounced twice. (A `button` row names its own rendered element in the template instead.)\n\nA consumer-provided name/description always wins: we capture (once) whether the anchor already\ncarries `aria-label`/`aria-labelledby` or `aria-description`/`aria-describedby` and, if so,\nleave that attribute untouched. Otherwise we keep our generated value in sync with the text."
             },
             {
               "kind": "method",
@@ -331,6 +362,11 @@
             {
               "kind": "method",
               "name": "_renderTrailingContent"
+            },
+            {
+              "kind": "method",
+              "name": "_renderActionButton",
+              "description": "The interactive target for a `button` row: an empty, native `<button>` stretched invisibly\nover the whole row (see the SCSS). The item renders and owns it - rather than the consumer\nslotting one - so it can name it from its own text and keep its attributes private (it is just\nan action box, not a configurable control). Being a real button, activation is native: pointer\nclicks and keyboard (Enter/Space) both fire a `click` that bubbles out, so consumers listen for\n`click` on the `pie-list-item`. It is `type=\"button\"`, so it never submits a form."
             }
           ],
           "attributes": [
@@ -374,6 +410,17 @@
             {
               "name": "disabled",
               "fieldName": "disabled"
+            },
+            {
+              "name": "hasDivider",
+              "fieldName": "hasDivider"
+            },
+            {
+              "name": "aria",
+              "type": {
+                "text": "ListItemProps['aria']"
+              },
+              "fieldName": "aria"
             }
           ],
           "superclass": {

package/dist/{PieElement-CGtUo9tK.js → PieElement-wRsAkkYC.js}

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