@justeattakeaway/pie-list 0.2.0 → 0.4.0

package/README.md

@@ -21,7 +21,23 @@
   - [CSS Variables](#css-variables)
   - [Events](#events)
 - [Accessibility](#accessibility)
+  - [You never set ARIA on a list item or its slotted content](#you-never-set-aria-on-a-list-item-or-its-slotted-content)
+  - [How the naming is derived](#how-the-naming-is-derived)
 - [Usage Examples](#usage-examples)
+  - [Basic list](#basic-list)
+  - [Leading and trailing content](#leading-and-trailing-content)
+  - [Trailing tag](#trailing-tag)
+  - [Meta text](#meta-text)
+  - [Bold primary text](#bold-primary-text)
+  - [Compact list](#compact-list)
+  - [Media](#media)
+  - [Overriding alignment and padding](#overriding-alignment-and-padding)
+  - [Selectable lists](#selectable-lists)
+    - [Single-select (radios)](#single-select-radios)
+    - [Multi-select (checkboxes)](#multi-select-checkboxes)
+    - [Independent toggles (switches)](#independent-toggles-switches)
+  - [Link items](#link-items)
+  - [Framework variants](#framework-variants)
 - [Usage Notes and Rules](#usage-notes-and-rules)
 - [Questions and Support](#questions-and-support)
 - [Contributing](#contributing)
@@ -55,7 +71,7 @@ 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` |
-| `selectionType` | `"none"`, `"radio"`, `"checkbox"`, `"switch"` | Declares that the item hosts an interactive control in its `leading`/`trailing` slot, making the **whole row** a selectable target. Set it on each selectable row. Inside a `pie-radio-group`, the group lays the rows out as a divided list automatically. See [Selectable lists](#selectable-lists). | `"none"` |
+| `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"` |
 | `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` |
 
 ### Slots
@@ -66,6 +82,7 @@ Slots are provided by `pie-list-item`.
 |---|---|
 | `leading` | Content displayed at the start of the item, before the text. Intended for a small icon or a media element (e.g. `pie-thumbnail`). If slotting `pie-thumbnail`, it MUST use `size="40"`; this is the only size that fits the list-item layout correctly. |
 | `trailing` | Content displayed at the end of the item, after the text. Intended for a small icon, a `pie-tag`, etc. Not rendered when `metaText` is set. |
+| `link` | Only rendered when `interactionType="link"`. Slot a single **empty** anchor (`<a slot="link" href="...">`) here. It is stretched over the whole row so the entire item becomes the navigation target. The item supplies the anchor's accessible name and description from its text, so the anchor must contain no text of its own; apply any native anchor attributes you need (`href`, `target`, `rel`, and so on). See [Link items](#link-items). |
 
 The permitted slotted elements are: a PIE WEBC icon, `pie-tag`, `pie-thumbnail`, `pie-avatar`*, `pie-switch`, and native HTML radio/checkbox inputs.
 Some slotted content is designed with specific properties being used. So please read the entire readme to understand correct slot usage.
@@ -116,9 +133,36 @@ This component does not emit any custom events. To listen for interactions, trea
   </pie-list>
   ```
 
+### You never set ARIA on a list item or its slotted content
+
+> [!IMPORTANT]
+> You do **not** add any ARIA attributes to a `pie-list-item`, nor to the control, anchor, icon or media you slot into it. The item manages all of that for you, driven entirely by the `primaryText`, `secondaryText` and `metaText` props (and the `interactionType`). Just provide the text and slot the element in.
+
+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;
+- **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:
+
+- `primaryText` becomes the control'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.
+
+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.
+
+**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.
+
 ## Usage Examples
 
-**For HTML:**
+The examples below use HTML. For framework-specific syntax, see [Framework variants](#framework-variants).
+
+### Basic list
 
 ```js
 // import as modules into a js file e.g. main.js
@@ -142,7 +186,7 @@ A basic list with primary, secondary and meta text (note the required `aria-labe
 <script type="module" src="/main.js"></script>
 ```
 
-**Leading and trailing content (icons):**
+### Leading and trailing content
 
 ```js
 import '@justeattakeaway/pie-icons-webc/dist/IconChevronRight.js';
@@ -157,7 +201,7 @@ import '@justeattakeaway/pie-icons-webc/dist/IconChevronRight.js';
 </pie-list>
 ```
 
-**Trailing `pie-tag`:**
+### Trailing tag
 
 ```js
 import '@justeattakeaway/pie-webc/components/tag.js';
@@ -171,7 +215,9 @@ import '@justeattakeaway/pie-webc/components/tag.js';
 </pie-list>
 ```
 
-**Meta text** (renders as trailing text; do not combine with the `trailing` slot):
+### Meta text
+
+Renders as trailing text; do not combine with the `trailing` slot:
 
 ```html
 <pie-list>
@@ -182,7 +228,7 @@ import '@justeattakeaway/pie-webc/components/tag.js';
 </pie-list>
 ```
 
-**Bold primary text:**
+### Bold primary text
 
 ```html
 <pie-list>
@@ -190,7 +236,9 @@ import '@justeattakeaway/pie-webc/components/tag.js';
 </pie-list>
 ```
 
-**Compact list** (reduced height, see [rules](#usage-notes-and-rules)):
+### Compact list
+
+Reduced height, see [rules](#usage-notes-and-rules):
 
 ```html
 <pie-list>
@@ -203,7 +251,9 @@ import '@justeattakeaway/pie-webc/components/tag.js';
 </pie-list>
 ```
 
-**Media (`pie-thumbnail`) in the leading slot:**
+### Media
+
+Slot larger media such as `pie-thumbnail` into the `leading` slot:
 
 ```js
 import '@justeattakeaway/pie-webc/components/thumbnail.js';
@@ -227,7 +277,9 @@ import '@justeattakeaway/pie-webc/components/thumbnail.js';
 </pie-list>
 ```
 
-**Overriding alignment and padding** (via CSS variables):
+### Overriding alignment and padding
+
+Via CSS variables:
 
 ```html
 <!-- Vertically centre the content of the items. `--list-item-alignment` must be set on the
@@ -248,18 +300,22 @@ import '@justeattakeaway/pie-webc/components/thumbnail.js';
 
 ### Selectable lists
 
-`pie-list` itself is a static container with no selection or keyboard behaviour. To build a **selectable** list, do **not** put the controls in `pie-list`. Instead, place `pie-list-item`s inside a [`pie-radio-group`](https://webc.pie.design/?path=/docs/components-radio-group--overview) (single-select) with `selection-type="radio"`, and slot the control into each item's `leading` (or `trailing`) slot. The group lays the rows out as a divided list automatically.
+`pie-list` itself is a static container with no selection or keyboard behaviour. To build a **selectable** list, do **not** put the controls in `pie-list`. Instead, place `pie-list-item`s inside a [`pie-radio-group`](https://webc.pie.design/?path=/docs/components-radio-group--overview) (single-select) or a [`pie-checkbox-group`](https://webc.pie.design/?path=/docs/components-checkbox-group--overview) (multi-select), set each item's `interactionType`, and slot the control into the item's `leading` (or `trailing`) slot. Switches have no group, so `interactionType="switch"` rows go directly in a `pie-list`.
 
-`selection-type` on each **item** makes that row selectable:
+#### The `interactionType` prop
 
-- takes the correct **role** — `presentation` for `radio`/`checkbox` (so the group owns the controls directly), `listitem` for `switch` and `none`;
-- provides its `primaryText`, `secondaryText` and `metaText` as the slotted control's **accessible name and description** (and `aria-hidden`s the now-duplicated visible text);
-- **forwards a click** anywhere on the row to the control, so the whole row is a hit target;
-- shows **hover and active** states on the row (suppressed when the item's `disabled` is set, or the group is disabled).
+`interactionType` (set to `"radio"`, `"checkbox"` or `"switch"`) is what makes a row selectable. Setting it drives the item to:
 
-Provide the label through the item's `primaryText` — not as the control's own content. The group still owns the group-level semantics (its own role, shared `name`, selection coordination and group-disable).
+- take the correct **role** — `presentation` for `radio`/`checkbox` (so the group owns the controls directly), `listitem` for `switch` and `none`;
+- provide its `primaryText`, `secondaryText` and `metaText` as the slotted control's **accessible name and description** (and `aria-hidden` the now-duplicated visible text);
+- **forward a click** anywhere on the row to the control, so the whole row is a hit target;
+- show **hover and active** states on the row (suppressed when the control is disabled, or when its group is disabled; switches have no group, so only per-row and per-switch disable applies).
 
-Single-select (radios):
+Provide the label through the item's `primaryText` — not as the control's own content. The group still owns the group-level semantics (its own role, shared `name`, selection coordination and group-disable); `interactionType` only governs the item. See the [`pie-radio-group`](https://webc.pie.design/?path=/docs/components-radio-group--overview) and [`pie-checkbox-group`](https://webc.pie.design/?path=/docs/components-checkbox-group--overview) docs for the group behaviour.
+
+You do not add any ARIA to the item or the slotted control - `pie-list-item` derives the control's accessible name and description from your `primaryText`, `secondaryText` and `metaText`. See [Accessibility](#accessibility).
+
+#### Single-select (radios)
 
 ```js
 import '@justeattakeaway/pie-webc/components/radio-group.js';
@@ -268,18 +324,99 @@ import '@justeattakeaway/pie-webc/components/list-item.js';
 ```
 
 ```html
-<!-- `selection-type="radio"` makes each row selectable and the group lays them out as a divided
+<!-- `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). -->
 <pie-radio-group name="delivery" value="express">
-  <pie-list-item selection-type="radio" primaryText="Standard delivery" secondaryText="3 to 5 working days" metaText="Free">
+  <pie-list-item 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 selection-type="radio" primaryText="Express delivery" secondaryText="Next working day" metaText="£4.99">
+  <pie-list-item interactionType="radio" primaryText="Express delivery" secondaryText="Next working day" metaText="£4.99">
     <pie-radio slot="leading" value="express"></pie-radio>
   </pie-list-item>
 </pie-radio-group>
 ```
 
+#### Multi-select (checkboxes)
+
+```js
+import '@justeattakeaway/pie-webc/components/checkbox-group.js';
+import '@justeattakeaway/pie-webc/components/checkbox.js';
+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-checkbox slot="leading" name="cheese"></pie-checkbox>
+  </pie-list-item>
+  <pie-list-item interactionType="checkbox" primaryText="Pepperoni" secondaryText="Spicy">
+    <pie-checkbox slot="leading" name="pepperoni"></pie-checkbox>
+  </pie-list-item>
+</pie-checkbox-group>
+```
+
+#### Independent toggles (switches)
+
+There is no group, so the rows go in a `pie-list` (which needs its own accessible name), and the switch sits in the `trailing` slot. Set `disabled` on the `pie-list-item` alongside any disabled `pie-switch`:
+
+```js
+import '@justeattakeaway/pie-webc/components/list.js';
+import '@justeattakeaway/pie-webc/components/list-item.js';
+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-switch slot="trailing"></pie-switch>
+  </pie-list-item>
+  <pie-list-item interactionType="switch" primaryText="Push notifications">
+    <pie-switch slot="trailing"></pie-switch>
+  </pie-list-item>
+  <pie-list-item interactionType="switch" primaryText="SMS" disabled>
+    <pie-switch slot="trailing" disabled></pie-switch>
+  </pie-list-item>
+</pie-list>
+```
+
+Each `pie-switch` manages its own state and emits a native `change` event when toggled. Listen on the switch itself, or on the `pie-list` since the event bubbles. Set a switch's initial state with its `checked` prop. There is no group coordinating them, so each switch is independent.
+
+### Link items
+
+Set `interactionType="link"` and slot a single **empty** anchor into the `link` slot to turn the whole row into one navigation link. The anchor is stretched over the entire item (`position: absolute; inset: 0`), so a click or tap anywhere on the row follows the link, and keyboard focus lands on the row as a whole (the focus ring hugs the row).
+
+Because the anchor is empty, `pie-list-item` names it from its own text: `primaryText` becomes the anchor'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)). If you set your own `aria-label`/`aria-labelledby` (or `aria-description`/`aria-describedby`) on the anchor, that wins and the item leaves it untouched. Apply whatever native anchor attributes you need (`href`, `target`, `rel`, `download`, and so on); the only requirement is that the anchor **contains no text** (it must stay empty for the naming to work). Give the `pie-list` its own accessible name (e.g. `aria-label`).
+
+```js
+import '@justeattakeaway/pie-webc/components/list.js';
+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">
+    <a slot="link" href="/orders"></a>
+  </pie-list-item>
+  <pie-list-item interactionType="link" primaryText="Menu" secondaryText="Edit items, prices and photos">
+    <a slot="link" href="/menu"></a>
+  </pie-list-item>
+</pie-list>
+```
+
+You are not limited to a raw `<a>`. Any component that renders an anchor and forwards the `slot` attribute works the same way, so in **Next.js you can slot the `next/link` `<Link>` component** (and in Nuxt, `<NuxtLink>`). Slot it into `link`, keep it empty, and `pie-list-item` names it exactly as it names a raw anchor:
+
+```jsx
+// Next.js
+import Link from 'next/link';
+import { PieListItem } from '@justeattakeaway/pie-webc/react/list-item.js';
+
+<PieListItem interactionType="link" primaryText="Orders" secondaryText="View and manage live orders">
+  <Link slot="link" href="/orders" />
+</PieListItem>
+```
+
+### Framework variants
+
 **For Native JS Applications, Vue, Angular, Svelte etc.:**
 
 ```js

package/custom-elements.json

@@ -68,11 +68,11 @@
       "declarations": [
         {
           "kind": "variable",
-          "name": "selectionTypes",
+          "name": "interactionTypes",
           "type": {
-            "text": "['none', 'radio', 'checkbox', 'switch']"
+            "text": "['none', 'radio', 'checkbox', 'switch', 'link']"
           },
-          "default": "['none', 'radio', 'checkbox', 'switch']"
+          "default": "['none', 'radio', 'checkbox', 'switch', 'link']"
         },
         {
           "kind": "variable",
@@ -80,15 +80,15 @@
           "type": {
             "text": "DefaultProps"
           },
-          "default": "{ isCompact: false, isBold: false, hasMedia: false, selectionType: 'none', disabled: false, }"
+          "default": "{ isCompact: false, isBold: false, hasMedia: false, interactionType: 'none', disabled: false, }"
         }
       ],
       "exports": [
         {
           "kind": "js",
-          "name": "selectionTypes",
+          "name": "interactionTypes",
           "declaration": {
-            "name": "selectionTypes",
+            "name": "interactionTypes",
             "module": "src/pie-list-item/defs.js"
           }
         },
@@ -118,6 +118,10 @@
             {
               "description": "Content shown at the end of the item. Mutually exclusive with `metaText`.",
               "name": "trailing"
+            },
+            {
+              "description": "Rendered only when `interactionType=\"link\"`. Slot one empty anchor (e.g. `<a slot=\"link\" href=\"/x\">`) stretched over the whole row as the link target. Must contain no text.",
+              "name": "link"
             }
           ],
           "members": [
@@ -162,8 +166,8 @@
             },
             {
               "kind": "field",
-              "name": "selectionType",
-              "attribute": "selection-type"
+              "name": "interactionType",
+              "attribute": "interactionType"
             },
             {
               "kind": "field",
@@ -194,7 +198,34 @@
             },
             {
               "kind": "field",
-              "name": "_hasExplicitRole",
+              "name": "_managedRole",
+              "type": {
+                "text": "string | null"
+              },
+              "privacy": "private",
+              "default": "null"
+            },
+            {
+              "kind": "field",
+              "name": "_linkAriaCaptured",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "private",
+              "default": "false"
+            },
+            {
+              "kind": "field",
+              "name": "_consumerNamedLink",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "private",
+              "default": "false"
+            },
+            {
+              "kind": "field",
+              "name": "_consumerDescribedLink",
               "type": {
                 "text": "boolean"
               },
@@ -210,6 +241,24 @@
               "privacy": "private",
               "readonly": true
             },
+            {
+              "kind": "field",
+              "name": "_isLinkRow",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "private",
+              "readonly": true
+            },
+            {
+              "kind": "field",
+              "name": "_providesAria",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "private",
+              "readonly": true
+            },
             {
               "kind": "field",
               "name": "_ownedByGroup",
@@ -246,7 +295,7 @@
                   "text": "void"
                 }
               },
-              "description": "Sets the item's role from `selectionType`: `presentation` for radio/checkbox (so the group\nowns those controls directly), otherwise `listitem` (static items and switches). A role set\nexplicitly by the consumer is left untouched."
+              "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."
             },
             {
               "kind": "field",
@@ -264,6 +313,17 @@
               "privacy": "private",
               "description": "Forwards a click anywhere on the row to the slotted control, so the whole item is a hit\ntarget. Skips clicks that already landed on the control, to avoid a double toggle."
             },
+            {
+              "kind": "method",
+              "name": "_applyLinkAria",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "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."
+            },
             {
               "kind": "method",
               "name": "_renderSecondaryText"
@@ -308,8 +368,8 @@
               "fieldName": "hasMedia"
             },
             {
-              "name": "selection-type",
-              "fieldName": "selectionType"
+              "name": "interactionType",
+              "fieldName": "interactionType"
             },
             {
               "name": "disabled",

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

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