@justeattakeaway/pie-list 0.3.0 → 0.5.0

package/README.md

@@ -21,7 +21,25 @@
   - [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)
+    - [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)
 - [Contributing](#contributing)
@@ -55,8 +73,9 @@ 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"`, `"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` |
+| `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
 
@@ -66,6 +85,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 +136,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, 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"`, 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 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 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 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.
+
+**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
 
-**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 +189,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 +204,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 +218,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 +231,7 @@ import '@justeattakeaway/pie-webc/components/tag.js';
 </pie-list>
 ```
 
-**Bold primary text:**
+### Bold primary text
 
 ```html
 <pie-list>
@@ -190,7 +239,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 +254,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 +280,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,20 +303,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) or a [`pie-checkbox-group`](https://webc.pie.design/?path=/docs/components-checkbox-group--overview) (multi-select), set each item's `selectionType`, and slot the control into the item's `leading` (or `trailing`) slot.
+`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`.
 
-#### The `selectionType` prop
+#### The `interactionType` prop
 
-`selectionType` is what makes a row selectable. Set it to `radio` or `checkbox` and it drives the item to:
+`interactionType` (set to `"radio"`, `"checkbox"` or `"switch"`) is what makes a row selectable. Setting it drives the item to:
 
 - 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, or the group, is disabled).
+- 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).
 
-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); `selectionType` 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.
+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.
 
-Single-select (radios):
+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';
@@ -270,19 +327,19 @@ import '@justeattakeaway/pie-webc/components/list-item.js';
 ```
 
 ```html
-<!-- `selectionType="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 selectionType="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 selectionType="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):
+#### Multi-select (checkboxes)
 
 ```js
 import '@justeattakeaway/pie-webc/components/checkbox-group.js';
@@ -292,15 +349,175 @@ import '@justeattakeaway/pie-webc/components/list-item.js';
 
 ```html
 <pie-checkbox-group>
-  <pie-list-item selectionType="checkbox" primaryText="Cheese" secondaryText="Extra mature" metaText="Free">
+  <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 selectionType="checkbox" primaryText="Pepperoni" secondaryText="Spicy">
+  <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>
+```
+
+#### 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 interactionType="link" primaryText="Overview">
+    <a slot="link" href="/account"></a>
+  </pie-list-item>
+  <pie-list-item 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 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 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.:**
 
 ```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', 'button']"
           },
-          "default": "['none', 'radio', 'checkbox', 'switch']"
+          "default": "['none', 'radio', 'checkbox', 'switch', 'link', 'button']"
         },
         {
           "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,14 +166,22 @@
             },
             {
               "kind": "field",
-              "name": "selectionType",
-              "attribute": "selectionType"
+              "name": "interactionType",
+              "attribute": "interactionType"
             },
             {
               "kind": "field",
               "name": "disabled",
               "attribute": "disabled"
             },
+            {
+              "kind": "field",
+              "name": "aria",
+              "type": {
+                "text": "ListItemProps['aria']"
+              },
+              "attribute": "aria"
+            },
             {
               "kind": "field",
               "name": "_parentDisabled",
@@ -194,7 +206,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 +249,42 @@
               "privacy": "private",
               "readonly": true
             },
+            {
+              "kind": "field",
+              "name": "_isLinkRow",
+              "type": {
+                "text": "boolean"
+              },
+              "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",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "private",
+              "readonly": true
+            },
             {
               "kind": "field",
               "name": "_ownedByGroup",
@@ -246,7 +321,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, 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",
@@ -255,7 +330,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
             },
             {
@@ -264,6 +339,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": "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",
               "name": "_renderSecondaryText"
@@ -271,6 +357,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": [
@@ -308,12 +399,19 @@
               "fieldName": "hasMedia"
             },
             {
-              "name": "selectionType",
-              "fieldName": "selectionType"
+              "name": "interactionType",
+              "fieldName": "interactionType"
             },
             {
               "name": "disabled",
               "fieldName": "disabled"
+            },
+            {
+              "name": "aria",
+              "type": {
+                "text": "ListItemProps['aria']"
+              },
+              "fieldName": "aria"
             }
           ],
           "superclass": {

package/dist/{PieElement-ab_PEQpW.js → PieElement-DQQMEr70.js}

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