@justeattakeaway/pie-radio-group 0.3.0 → 0.4.0

package/README.md

@@ -8,15 +8,6 @@
   </a>
 </p>
 
-# Table of Contents
-
-1. [Introduction](#pie-radio-group)
-2. [Installation](#installation)
-3. [Importing the component](#importing-the-component)
-4. [Peer Dependencies](#peer-dependencies)
-5. [Props](#props)
-6. [Contributing](#contributing)
-
 ## pie-radio-group
 
 `pie-radio-group` is a Web Component built using the Lit library.
@@ -29,63 +20,22 @@ This component can be easily integrated into various frontend frameworks and cus
 To install `pie-radio-group` in your application, run the following on your command line:
 
 ```bash
-# npm
-$ npm i @justeattakeaway/pie-radio-group
-
-# yarn
-$ yarn add @justeattakeaway/pie-radio-group
-```
-
-For full information on using PIE components as part of an application, check out the [Getting Started Guide](https://github.com/justeattakeaway/pie/wiki/Getting-started-with-PIE-Web-Components).
-
-
-### Importing the component
-
-#### JavaScript
-```js
-// Default – for Native JS Applications, Vue, Angular, Svelte, etc.
-import { PieRadioGroup } from '@justeattakeaway/pie-radio-group';
-
-// If you don't need to reference the imported object, you can simply
-// import the module which registers the component as a custom element.
-import '@justeattakeaway/pie-radio-group';
+npm i @justeattakeaway/pie-radio-group
 ```
-
-#### React
-```js
-// React
-// For React, you will need to import our React-specific component build
-// which wraps the web component using ​@lit/react
-import { PieRadioGroup } from '@justeattakeaway/pie-radio-group/dist/react';
+```bash
+yarn add @justeattakeaway/pie-radio-group
 ```
 
-> [!NOTE]
-> When using the React version of the component, please make sure to also
-> include React as a [peer dependency](#peer-dependencies) in your project.
-
-
-## Peer Dependencies
-
-> [!IMPORTANT]
-> When using `pie-radio-group`, you will also need to include a couple of dependencies to ensure the component renders as expected. See [the PIE Wiki](https://github.com/justeattakeaway/pie/wiki/Getting-started-with-PIE-Web-Components#expected-dependencies) for more information and how to include these in your application.
-
-
-## Props
+For full information on using PIE components as part of an application, check out the [Getting Started Guide](https://github.com/justeattakeaway/pie/wiki/Getting-started-with-PIE-Web-Components).
 
-| Property | Type | Default | Description |
-|---|---|---|---|
-| - | - | - | - |
+## Documentation
 
-In your markup or JSX, you can then use these to set the properties for the `pie-radio-group` component:
+Visit  [Radio Group | PIE Design System](https://pie.design/components/radio-group/code) to view more information on this component.
 
-```html
-<!-- Native HTML -->
-<pie-radio-group></pie-radio-group>
+## Questions
 
-<!-- JSX -->
-<PieRadioGroup></PieRadioGroup>
-```
+Please head to [FAQs | PIE Design System](https://pie.design/support/contact-us/) to see our FAQs and get in touch.
 
 ## Contributing
 
-Check out our [contributing guide](https://github.com/justeattakeaway/pie/wiki/Contributing-Guide) for more information on [local development](https://github.com/justeattakeaway/pie/wiki/Contributing-Guide#local-development) and how to run specific [component tests](https://github.com/justeattakeaway/pie/wiki/Contributing-Guide#testing).
+Check out our [contributing guide](https://github.com/justeattakeaway/pie/wiki/Contributing-Guide) for more information on [local development](https://github.com/justeattakeaway/pie/wiki/Contributing-Guide#local-development) and how to run specific [component tests](https://github.com/justeattakeaway/pie/wiki/Contributing-Guide#testing).

package/custom-elements.json

@@ -143,6 +143,14 @@
                 "text": "Array<HTMLInputElement>"
               }
             },
+            {
+              "kind": "field",
+              "name": "_fieldset",
+              "type": {
+                "text": "HTMLInputElement"
+              },
+              "privacy": "private"
+            },
             {
               "kind": "field",
               "name": "_abortController",
@@ -151,6 +159,17 @@
               },
               "privacy": "private"
             },
+            {
+              "kind": "field",
+              "name": "_wasShiftTabPressed",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "private",
+              "static": true,
+              "default": "false",
+              "description": "Tracks whether the `Shift` key was held during the last `Tab` key press.\n\nThe property is static because it needs to be shared across all instances of the\n`PieRadioGroup` component on the same page, ensuring consistent behavior."
+            },
             {
               "kind": "method",
               "name": "_handleDisabled",
@@ -243,6 +262,172 @@
                 }
               },
               "description": "Renders the label element inside a legend, wrapping the slot content."
+            },
+            {
+              "kind": "method",
+              "name": "_updateShiftTabState",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "event",
+                  "type": {
+                    "text": "KeyboardEvent"
+                  }
+                }
+              ],
+              "description": "Updates the state of `_wasShiftTabPressed` based on the last `Tab` key press."
+            },
+            {
+              "kind": "method",
+              "name": "_handleFocusIn",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "event",
+                  "type": {
+                    "text": "FocusEvent"
+                  }
+                }
+              ],
+              "description": "Handles the `focusin` event to manage focus within the radio group.\n\nThis method determines the appropriate element to focus when the radio group\ngains focus. It considers the last navigation action (whether `Shift+Tab` was used)\nand focuses the checked option, the first option, or the last option as needed."
+            },
+            {
+              "kind": "method",
+              "name": "_handleFocusOut",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "description": "Handles the `focusout` event to restore the `tabindex` on the radio group's `fieldset`.\n\nWhen focus leaves the radio group, this method enables the `tabindex` attribute\non the `fieldset` element. This ensures the radio group remains accessible for\nkeyboard navigation and can be re-focused when tabbing back into the group."
+            },
+            {
+              "kind": "method",
+              "name": "_toggleFieldsetTabindex",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "enable",
+                  "type": {
+                    "text": "boolean"
+                  }
+                }
+              ]
+            },
+            {
+              "kind": "method",
+              "name": "_moveFocus",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "currentIndex",
+                  "type": {
+                    "text": "number"
+                  }
+                },
+                {
+                  "name": "step",
+                  "type": {
+                    "text": "number"
+                  }
+                }
+              ]
+            },
+            {
+              "kind": "method",
+              "name": "_isForwardKey",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "boolean"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "event",
+                  "type": {
+                    "text": "KeyboardEvent"
+                  }
+                }
+              ],
+              "description": "Determines if a key press indicates forward navigation within the radio group.\n\nThis method evaluates a keyboard event to check if the pressed key corresponds\nto forward navigation based on the current text direction (LTR or RTL).\n\n**Behaviour:**\n- For LTR (Left-to-Right) layouts:\n  - `ArrowRight` and `ArrowDown` indicate forward navigation.\n- For RTL (Right-to-Left) layouts:\n  - `ArrowLeft` and `ArrowDown` indicate forward navigation."
+            },
+            {
+              "kind": "method",
+              "name": "_isBackwardKey",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "boolean"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "event",
+                  "type": {
+                    "text": "KeyboardEvent"
+                  }
+                }
+              ],
+              "description": "Determines if a key press indicates backward navigation within the radio group.\n\nThis method evaluates a keyboard event to check if the pressed key corresponds\nto backward navigation based on the current text direction (LTR or RTL).\n\n**Behaviour:**\n- For LTR (Left-to-Right) layouts:\n  - `ArrowLeft` and `ArrowUp` indicate backward navigation.\n- For RTL (Right-to-Left) layouts:\n  - `ArrowRight` and `ArrowUp` indicate backward navigation."
+            },
+            {
+              "kind": "method",
+              "name": "_handleKeyDown",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "event",
+                  "type": {
+                    "text": "KeyboardEvent"
+                  }
+                }
+              ],
+              "description": "Handles keyboard navigation within the radio group using arrow keys.\n\nThis method responds to `keydown` events and determines the appropriate navigation\naction (forward or backward) based on the pressed key and the current focus. It prevents\nthe default browser behaviour (e.g., scrolling) when arrow keys are used for navigation."
+            },
+            {
+              "kind": "method",
+              "name": "_focusAndClickOption",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "option",
+                  "type": {
+                    "text": "HTMLInputElement"
+                  }
+                }
+              ]
             }
           ],
           "events": [

package/dist/index.d.ts

@@ -33,7 +33,15 @@ export declare class PieRadioGroup extends PieRadioGroup_base implements RadioGr
     assistiveText?: RadioGroupProps['assistiveText'];
     status: "default" | "error" | "success";
     _slottedChildren: Array<HTMLInputElement>;
+    private _fieldset;
     private _abortController;
+    /**
+     * Tracks whether the `Shift` key was held during the last `Tab` key press.
+     *
+     * The property is static because it needs to be shared across all instances of the
+     * `PieRadioGroup` component on the same page, ensuring consistent behavior.
+     */
+    private static _wasShiftTabPressed;
     /**
      * Dispatches a custom event to notify each slotted child radio element
      * when the radio group is disabled.
@@ -71,7 +79,65 @@ export declare class PieRadioGroup extends PieRadioGroup_base implements RadioGr
      */
     private _renderWrappedLabel;
     protected updated(_changedProperties: PropertyValues<this>): void;
+    protected firstUpdated(): void;
     connectedCallback(): void;
+    /**
+     * Updates the state of `_wasShiftTabPressed` based on the last `Tab` key press.
+     */
+    private _updateShiftTabState;
+    /**
+     * Handles the `focusin` event to manage focus within the radio group.
+     *
+     * This method determines the appropriate element to focus when the radio group
+     * gains focus. It considers the last navigation action (whether `Shift+Tab` was used)
+     * and focuses the checked option, the first option, or the last option as needed.
+     */
+    private _handleFocusIn;
+    /**
+     * Handles the `focusout` event to restore the `tabindex` on the radio group's `fieldset`.
+     *
+     * When focus leaves the radio group, this method enables the `tabindex` attribute
+     * on the `fieldset` element. This ensures the radio group remains accessible for
+     * keyboard navigation and can be re-focused when tabbing back into the group.
+     */
+    private _handleFocusOut;
+    private _toggleFieldsetTabindex;
+    private _moveFocus;
+    /**
+     * Determines if a key press indicates forward navigation within the radio group.
+     *
+     * This method evaluates a keyboard event to check if the pressed key corresponds
+     * to forward navigation based on the current text direction (LTR or RTL).
+     *
+     * **Behaviour:**
+     * - For LTR (Left-to-Right) layouts:
+     *   - `ArrowRight` and `ArrowDown` indicate forward navigation.
+     * - For RTL (Right-to-Left) layouts:
+     *   - `ArrowLeft` and `ArrowDown` indicate forward navigation.
+     */
+    private _isForwardKey;
+    /**
+     * Determines if a key press indicates backward navigation within the radio group.
+     *
+     * This method evaluates a keyboard event to check if the pressed key corresponds
+     * to backward navigation based on the current text direction (LTR or RTL).
+     *
+     * **Behaviour:**
+     * - For LTR (Left-to-Right) layouts:
+     *   - `ArrowLeft` and `ArrowUp` indicate backward navigation.
+     * - For RTL (Right-to-Left) layouts:
+     *   - `ArrowRight` and `ArrowUp` indicate backward navigation.
+     */
+    private _isBackwardKey;
+    /**
+     * Handles keyboard navigation within the radio group using arrow keys.
+     *
+     * This method responds to `keydown` events and determines the appropriate navigation
+     * action (forward or backward) based on the pressed key and the current focus. It prevents
+     * the default browser behaviour (e.g., scrolling) when arrow keys are used for navigation.
+     */
+    private _handleKeyDown;
+    private _focusAndClickOption;
     disconnectedCallback(): void;
     render(): TemplateResult<1>;
     static styles: CSSResult;

package/dist/index.js

@@ -1,23 +1,25 @@
-import { LitElement as v, html as p, nothing as u, unsafeCSS as m } from "lit";
-import { state as _, property as l, queryAssignedElements as y } from "lit/decorators.js";
-import { FormControlMixin as C, RtlMixin as x, wrapNativeEvent as S, validPropertyValues as E, defineCustomElement as $ } from "@justeattakeaway/pie-webc-core";
-import { ifDefined as w } from "lit/directives/if-defined.js";
-import { classMap as L } from "lit/directives/class-map.js";
+import { LitElement as g, html as c, nothing as p, unsafeCSS as m } from "lit";
+import { state as v, property as l, queryAssignedElements as y, query as w } from "lit/decorators.js";
+import { FormControlMixin as C, RtlMixin as x, wrapNativeEvent as S, validPropertyValues as A, defineCustomElement as T } from "@justeattakeaway/pie-webc-core";
+import { ifDefined as L } from "lit/directives/if-defined.js";
+import { classMap as E } from "lit/directives/class-map.js";
 import "@justeattakeaway/pie-assistive-text";
-const A = "*,*:after,*:before{box-sizing:inherit}.c-radioGroup{--radio-group-gap: var(--dt-spacing-c);--radio-group-gap--inline: var(--dt-spacing-c) var(--dt-spacing-e);margin:0;padding:0;border:0;min-width:0;display:flex;flex-flow:column wrap;gap:var(--radio-group-gap)}.c-radioGroup.c-radioGroup--inline{flex-flow:row wrap;gap:var(--radio-group-gap--inline)}.c-radioGroup.c-radioGroup--hasAssistiveText{margin-block-end:var(--dt-spacing-a)}", I = ["default", "success", "error"], G = "pie-radio-group-disabled", n = {
+const R = "*,*:after,*:before{box-sizing:inherit}.c-radioGroup{--radio-group-gap: var(--dt-spacing-c);--radio-group-gap--inline: var(--dt-spacing-c) var(--dt-spacing-e);margin:0;padding:0;border:0;min-width:0;display:flex;flex-flow:column wrap;gap:var(--radio-group-gap)}.c-radioGroup.c-radioGroup--inline{flex-flow:row wrap;gap:var(--radio-group-gap--inline)}.c-radioGroup.c-radioGroup--hasAssistiveText{margin-block-end:var(--dt-spacing-a)}", k = ["default", "success", "error"], F = "pie-radio-group-disabled", h = {
   status: "default",
   disabled: !1,
   isInline: !1,
   value: ""
 };
-var R = Object.defineProperty, o = (c, e, t, d) => {
-  for (var a = void 0, i = c.length - 1, r; i >= 0; i--)
-    (r = c[i]) && (a = r(e, t, a) || a);
-  return a && R(e, t, a), a;
+var I = Object.defineProperty, d = (u, t, e, s) => {
+  for (var i = void 0, a = u.length - 1, n; a >= 0; a--)
+    (n = u[a]) && (i = n(t, e, i) || i);
+  return i && I(t, e, i), i;
 };
-const b = "pie-radio-group", g = "assistive-text", h = class h extends C(x(v)) {
+const _ = "pie-radio-group", f = "assistive-text";
+var r;
+const o = (r = class extends C(x(g)) {
   constructor() {
-    super(...arguments), this._hasLabel = !1, this.value = n.value, this.isInline = n.isInline, this.disabled = n.disabled, this.status = n.status;
+    super(...arguments), this._hasLabel = !1, this.value = h.value, this.isInline = h.isInline, this.disabled = h.disabled, this.status = h.status;
   }
   /**
    * Dispatches a custom event to notify each slotted child radio element
@@ -25,7 +27,7 @@ const b = "pie-radio-group", g = "assistive-text", h = class h extends C(x(v)) {
    * @private
    */
   _handleDisabled() {
-    this._slottedChildren.forEach((e) => e.dispatchEvent(new CustomEvent(G, {
+    this._slottedChildren.forEach((t) => t.dispatchEvent(new CustomEvent(F, {
       bubbles: !1,
       composed: !1,
       detail: { disabled: this.disabled }
@@ -37,16 +39,16 @@ const b = "pie-radio-group", g = "assistive-text", h = class h extends C(x(v)) {
    * @returns {void}
    */
   _handleStatus() {
-    this._slottedChildren.forEach((e) => e.setAttribute("status", this.status === "error" ? "error" : "default"));
+    this._slottedChildren.forEach((t) => t.setAttribute("status", this.status === "error" ? "error" : "default"));
   }
   /**
    * Unselects all radios that are not the selected value.
    * @param {string} selectedValue - The value of the currently selected radio.
    * @private
    */
-  _handleRadioSelection(e) {
-    this.value = e, this._slottedChildren.forEach((t) => {
-      t.disabled || (t.checked = t.value === e);
+  _handleRadioSelection(t) {
+    this.value = t, this._slottedChildren.forEach((e) => {
+      e.disabled || (e.checked = e.value === t);
     });
   }
   /**
@@ -54,21 +56,21 @@ const b = "pie-radio-group", g = "assistive-text", h = class h extends C(x(v)) {
    * @param {Event} event - The change event from a radio element.
    * @private
    */
-  _handleRadioChange(e) {
-    e.stopPropagation();
-    const t = e.target;
-    this._handleRadioSelection(t.value);
-    const d = S(e);
-    this.dispatchEvent(d);
+  _handleRadioChange(t) {
+    t.stopPropagation();
+    const e = t.target;
+    this._handleRadioSelection(e.value);
+    const s = S(t);
+    this.dispatchEvent(s);
   }
   /**
    * Updates the `_hasLabel` state when content is added to the label slot.
    * @param {Event} e - The slotchange event.
    * @private
    */
-  _handleSlotChange(e) {
-    const t = e.target.assignedNodes({ flatten: !0 });
-    this._hasLabel = t.length > 0;
+  _handleSlotChange(t) {
+    const e = t.target.assignedNodes({ flatten: !0 });
+    this._hasLabel = e.length > 0;
   }
   /**
    * Renders the label element inside a legend, wrapping the slot content.
@@ -76,83 +78,173 @@ const b = "pie-radio-group", g = "assistive-text", h = class h extends C(x(v)) {
    * @private
    */
   _renderWrappedLabel() {
-    return this._hasLabel ? p`<legend><slot name='label' @slotchange=${this._handleSlotChange}></slot></legend>` : p`<slot name='label' @slotchange=${this._handleSlotChange}></slot>`;
+    return this._hasLabel ? c`<legend><slot name='label' @slotchange=${this._handleSlotChange}></slot></legend>` : c`<slot name='label' @slotchange=${this._handleSlotChange}></slot>`;
   }
-  updated(e) {
-    e.has("disabled") && this._handleDisabled(), e.has("value") && this._handleRadioSelection(this.value), e.has("status") && this._handleStatus();
+  updated(t) {
+    t.has("disabled") && this._handleDisabled(), t.has("value") && this._handleRadioSelection(this.value), t.has("status") && this._handleStatus();
+  }
+  firstUpdated() {
+    this._slottedChildren.forEach((t) => t.setAttribute("tabindex", "-1"));
   }
   connectedCallback() {
-    var t;
+    var e;
     super.connectedCallback(), this._abortController = new AbortController();
-    const { signal: e } = this._abortController;
-    (t = this.shadowRoot) == null || t.addEventListener("change", this._handleRadioChange.bind(this), { signal: e });
+    const { signal: t } = this._abortController;
+    (e = this.shadowRoot) == null || e.addEventListener("change", this._handleRadioChange.bind(this), { signal: t }), this.addEventListener("focusin", this._handleFocusIn, { signal: t }), this.addEventListener("focusout", this._handleFocusOut, { signal: t }), this.addEventListener("keydown", this._handleKeyDown, { signal: t }), document.addEventListener("keydown", this._updateShiftTabState.bind(this), { signal: t });
+  }
+  /**
+   * Updates the state of `_wasShiftTabPressed` based on the last `Tab` key press.
+   */
+  _updateShiftTabState(t) {
+    t.key === "Tab" && (r._wasShiftTabPressed = t.shiftKey);
+  }
+  /**
+   * Handles the `focusin` event to manage focus within the radio group.
+   *
+   * This method determines the appropriate element to focus when the radio group
+   * gains focus. It considers the last navigation action (whether `Shift+Tab` was used)
+   * and focuses the checked option, the first option, or the last option as needed.
+   */
+  _handleFocusIn(t) {
+    var i;
+    if (this !== t.target) return;
+    const e = r._wasShiftTabPressed, s = ((i = this._slottedChildren) == null ? void 0 : i.find((a) => a.checked)) || (e ? this._slottedChildren.at(-1) : this._slottedChildren[0]);
+    s && (s.focus(), this._toggleFieldsetTabindex(!1));
+  }
+  /**
+   * Handles the `focusout` event to restore the `tabindex` on the radio group's `fieldset`.
+   *
+   * When focus leaves the radio group, this method enables the `tabindex` attribute
+   * on the `fieldset` element. This ensures the radio group remains accessible for
+   * keyboard navigation and can be re-focused when tabbing back into the group.
+   */
+  _handleFocusOut() {
+    this._toggleFieldsetTabindex(!0);
+  }
+  _toggleFieldsetTabindex(t) {
+    t ? this._fieldset.setAttribute("tabindex", "0") : this._fieldset.removeAttribute("tabindex");
+  }
+  _moveFocus(t, e) {
+    const s = (t + e + this._slottedChildren.length) % this._slottedChildren.length;
+    this._focusAndClickOption(this._slottedChildren[s]);
+  }
+  /**
+   * Determines if a key press indicates forward navigation within the radio group.
+   *
+   * This method evaluates a keyboard event to check if the pressed key corresponds
+   * to forward navigation based on the current text direction (LTR or RTL).
+   *
+   * **Behaviour:**
+   * - For LTR (Left-to-Right) layouts:
+   *   - `ArrowRight` and `ArrowDown` indicate forward navigation.
+   * - For RTL (Right-to-Left) layouts:
+   *   - `ArrowLeft` and `ArrowDown` indicate forward navigation.
+   */
+  _isForwardKey(t) {
+    return t.code === "ArrowRight" && !this.isRTL || t.code === "ArrowLeft" && this.isRTL || t.code === "ArrowDown";
+  }
+  /**
+   * Determines if a key press indicates backward navigation within the radio group.
+   *
+   * This method evaluates a keyboard event to check if the pressed key corresponds
+   * to backward navigation based on the current text direction (LTR or RTL).
+   *
+   * **Behaviour:**
+   * - For LTR (Left-to-Right) layouts:
+   *   - `ArrowLeft` and `ArrowUp` indicate backward navigation.
+   * - For RTL (Right-to-Left) layouts:
+   *   - `ArrowRight` and `ArrowUp` indicate backward navigation.
+   */
+  _isBackwardKey(t) {
+    return t.code === "ArrowLeft" && !this.isRTL || t.code === "ArrowRight" && this.isRTL || t.code === "ArrowUp";
+  }
+  /**
+   * Handles keyboard navigation within the radio group using arrow keys.
+   *
+   * This method responds to `keydown` events and determines the appropriate navigation
+   * action (forward or backward) based on the pressed key and the current focus. It prevents
+   * the default browser behaviour (e.g., scrolling) when arrow keys are used for navigation.
+   */
+  _handleKeyDown(t) {
+    const e = this._slottedChildren.find((i) => i === document.activeElement);
+    if (!e)
+      return;
+    const s = this._slottedChildren.indexOf(e);
+    s !== -1 && (["ArrowRight", "ArrowDown", "ArrowLeft", "ArrowUp"].includes(t.code) && t.preventDefault(), this._isForwardKey(t) ? this._moveFocus(s, 1) : this._isBackwardKey(t) && this._moveFocus(s, -1));
+  }
+  _focusAndClickOption(t) {
+    var e, s;
+    t.focus(), (s = (e = t.shadowRoot) == null ? void 0 : e.querySelector("input")) == null || s.click(), this._toggleFieldsetTabindex(!1);
   }
   disconnectedCallback() {
     super.disconnectedCallback(), this._abortController.abort();
   }
   render() {
     const {
-      name: e,
-      isInline: t,
-      disabled: d,
-      status: a,
-      assistiveText: i
-    } = this, r = !!(i != null && i.length), f = {
+      name: t,
+      isInline: e,
+      disabled: s,
+      status: i,
+      assistiveText: a
+    } = this, n = !!(a != null && a.length), b = {
       "c-radioGroup": !0,
-      "c-radioGroup--inline": t,
-      "c-radioGroup--hasAssistiveText": r
+      "c-radioGroup--inline": e,
+      "c-radioGroup--hasAssistiveText": n
     };
-    return p`
+    return c`
             <fieldset
-                name=${w(e)}
-                ?disabled=${d}
+                tabindex="0"
+                name=${L(t)}
+                ?disabled=${s}
                 data-test-id="pie-radio-group"
-                aria-describedby=${r ? g : u}
-                class="${L(f)}">
+                aria-describedby=${n ? f : p}
+                class="${E(b)}">
                     ${this._renderWrappedLabel()}
                 <slot></slot>
             </fieldset>
-            ${r ? p`
+            ${n ? c`
                 <pie-assistive-text
-                    id=${g}
-                    variant=${a}
+                    id=${f}
+                    variant=${i}
                     data-test-id="pie-radio-group-assistive-text">
-                        ${i}
-                    </pie-assistive-text>` : u}
+                        ${a}
+                    </pie-assistive-text>` : p}
         `;
   }
-};
-h.styles = m(A);
-let s = h;
-o([
-  _()
-], s.prototype, "_hasLabel");
-o([
+}, r._wasShiftTabPressed = !1, r.styles = m(R), r);
+d([
+  v()
+], o.prototype, "_hasLabel");
+d([
   l({ type: String })
-], s.prototype, "name");
-o([
+], o.prototype, "name");
+d([
   l({ type: String })
-], s.prototype, "value");
-o([
+], o.prototype, "value");
+d([
   l({ type: Boolean })
-], s.prototype, "isInline");
-o([
+], o.prototype, "isInline");
+d([
   l({ type: Boolean, reflect: !0 })
-], s.prototype, "disabled");
-o([
+], o.prototype, "disabled");
+d([
   l({ type: String })
-], s.prototype, "assistiveText");
-o([
+], o.prototype, "assistiveText");
+d([
   l({ type: String }),
-  E(b, I, n.status)
-], s.prototype, "status");
-o([
+  A(_, k, h.status)
+], o.prototype, "status");
+d([
   y({ selector: "pie-radio" })
-], s.prototype, "_slottedChildren");
-$(b, s);
+], o.prototype, "_slottedChildren");
+d([
+  w("fieldset")
+], o.prototype, "_fieldset");
+let D = o;
+T(_, D);
 export {
-  G as ON_RADIO_GROUP_DISABLED,
-  s as PieRadioGroup,
-  n as defaultProps,
-  I as statusTypes
+  F as ON_RADIO_GROUP_DISABLED,
+  D as PieRadioGroup,
+  h as defaultProps,
+  k as statusTypes
 };

package/dist/react.d.ts

@@ -36,7 +36,15 @@ declare class PieRadioGroup_2 extends PieRadioGroup_base implements RadioGroupPr
     assistiveText?: RadioGroupProps['assistiveText'];
     status: "default" | "error" | "success";
     _slottedChildren: Array<HTMLInputElement>;
+    private _fieldset;
     private _abortController;
+    /**
+     * Tracks whether the `Shift` key was held during the last `Tab` key press.
+     *
+     * The property is static because it needs to be shared across all instances of the
+     * `PieRadioGroup` component on the same page, ensuring consistent behavior.
+     */
+    private static _wasShiftTabPressed;
     /**
      * Dispatches a custom event to notify each slotted child radio element
      * when the radio group is disabled.
@@ -74,7 +82,65 @@ declare class PieRadioGroup_2 extends PieRadioGroup_base implements RadioGroupPr
      */
     private _renderWrappedLabel;
     protected updated(_changedProperties: PropertyValues<this>): void;
+    protected firstUpdated(): void;
     connectedCallback(): void;
+    /**
+     * Updates the state of `_wasShiftTabPressed` based on the last `Tab` key press.
+     */
+    private _updateShiftTabState;
+    /**
+     * Handles the `focusin` event to manage focus within the radio group.
+     *
+     * This method determines the appropriate element to focus when the radio group
+     * gains focus. It considers the last navigation action (whether `Shift+Tab` was used)
+     * and focuses the checked option, the first option, or the last option as needed.
+     */
+    private _handleFocusIn;
+    /**
+     * Handles the `focusout` event to restore the `tabindex` on the radio group's `fieldset`.
+     *
+     * When focus leaves the radio group, this method enables the `tabindex` attribute
+     * on the `fieldset` element. This ensures the radio group remains accessible for
+     * keyboard navigation and can be re-focused when tabbing back into the group.
+     */
+    private _handleFocusOut;
+    private _toggleFieldsetTabindex;
+    private _moveFocus;
+    /**
+     * Determines if a key press indicates forward navigation within the radio group.
+     *
+     * This method evaluates a keyboard event to check if the pressed key corresponds
+     * to forward navigation based on the current text direction (LTR or RTL).
+     *
+     * **Behaviour:**
+     * - For LTR (Left-to-Right) layouts:
+     *   - `ArrowRight` and `ArrowDown` indicate forward navigation.
+     * - For RTL (Right-to-Left) layouts:
+     *   - `ArrowLeft` and `ArrowDown` indicate forward navigation.
+     */
+    private _isForwardKey;
+    /**
+     * Determines if a key press indicates backward navigation within the radio group.
+     *
+     * This method evaluates a keyboard event to check if the pressed key corresponds
+     * to backward navigation based on the current text direction (LTR or RTL).
+     *
+     * **Behaviour:**
+     * - For LTR (Left-to-Right) layouts:
+     *   - `ArrowLeft` and `ArrowUp` indicate backward navigation.
+     * - For RTL (Right-to-Left) layouts:
+     *   - `ArrowRight` and `ArrowUp` indicate backward navigation.
+     */
+    private _isBackwardKey;
+    /**
+     * Handles keyboard navigation within the radio group using arrow keys.
+     *
+     * This method responds to `keydown` events and determines the appropriate navigation
+     * action (forward or backward) based on the pressed key and the current focus. It prevents
+     * the default browser behaviour (e.g., scrolling) when arrow keys are used for navigation.
+     */
+    private _handleKeyDown;
+    private _focusAndClickOption;
     disconnectedCallback(): void;
     render(): TemplateResult<1>;
     static styles: CSSResult;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@justeattakeaway/pie-radio-group",
   "description": "PIE Design System Radio Group built using Web Components",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "type": "module",
   "main": "dist/index.js",
   "module": "dist/index.js",
@@ -38,11 +38,11 @@
     "@custom-elements-manifest/analyzer": "0.9.0",
     "@justeattakeaway/pie-components-config": "0.18.0",
     "@justeattakeaway/pie-css": "0.13.1",
-    "@justeattakeaway/pie-radio": "0.5.0",
+    "@justeattakeaway/pie-radio": "0.6.0",
     "cem-plugin-module-file-extensions": "0.0.5"
   },
   "dependencies": {
-    "@justeattakeaway/pie-assistive-text": "0.8.0",
+    "@justeattakeaway/pie-assistive-text": "0.8.1",
     "@justeattakeaway/pie-webc-core": "0.24.2"
   },
   "volta": {

package/src/index.ts

@@ -6,7 +6,9 @@ import {
     type PropertyValues,
     type TemplateResult,
 } from 'lit';
-import { property, queryAssignedElements, state } from 'lit/decorators.js';
+import {
+    property, query, queryAssignedElements, state,
+} from 'lit/decorators.js';
 import {
     RtlMixin,
     defineCustomElement,
@@ -63,8 +65,19 @@ export class PieRadioGroup extends FormControlMixin(RtlMixin(LitElement)) implem
     @queryAssignedElements({ selector: 'pie-radio' })
         _slottedChildren!: Array<HTMLInputElement>;
 
+    @query('fieldset')
+    private _fieldset!: HTMLInputElement;
+
     private _abortController!: AbortController;
 
+    /**
+     * Tracks whether the `Shift` key was held during the last `Tab` key press.
+     *
+     * The property is static because it needs to be shared across all instances of the
+     * `PieRadioGroup` component on the same page, ensuring consistent behavior.
+     */
+    private static _wasShiftTabPressed = false;
+
     /**
      * Dispatches a custom event to notify each slotted child radio element
      * when the radio group is disabled.
@@ -147,12 +160,154 @@ export class PieRadioGroup extends FormControlMixin(RtlMixin(LitElement)) implem
         }
     }
 
+    protected firstUpdated (): void {
+        // Make all radios impossible to tab to
+        // This is because by default, we are able to tab to each individual radio button.
+        // This is not the behaviour we want, so applying -1 tabindex prevents it.
+        this._slottedChildren.forEach((radio) => radio.setAttribute('tabindex', '-1'));
+    }
+
     connectedCallback (): void {
         super.connectedCallback();
         this._abortController = new AbortController();
         const { signal } = this._abortController;
 
         this.shadowRoot?.addEventListener('change', this._handleRadioChange.bind(this), { signal });
+
+        this.addEventListener('focusin', this._handleFocusIn, { signal });
+        this.addEventListener('focusout', this._handleFocusOut, { signal });
+
+        this.addEventListener('keydown', this._handleKeyDown, { signal });
+        document.addEventListener('keydown', this._updateShiftTabState.bind(this), { signal });
+    }
+
+    /**
+     * Updates the state of `_wasShiftTabPressed` based on the last `Tab` key press.
+     */
+    private _updateShiftTabState (event: KeyboardEvent): void {
+        if (event.key === 'Tab') {
+            PieRadioGroup._wasShiftTabPressed = event.shiftKey;
+        }
+    }
+
+    /**
+     * Handles the `focusin` event to manage focus within the radio group.
+     *
+     * This method determines the appropriate element to focus when the radio group
+     * gains focus. It considers the last navigation action (whether `Shift+Tab` was used)
+     * and focuses the checked option, the first option, or the last option as needed.
+     */
+    private _handleFocusIn (event: FocusEvent): void {
+        if (this !== event.target) return;
+
+        const isShiftTab = PieRadioGroup._wasShiftTabPressed;
+        const focusTarget = this._slottedChildren?.find((child) => child.checked) ||
+            (isShiftTab ? this._slottedChildren.at(-1) : this._slottedChildren[0]);
+
+        if (!focusTarget) return;
+
+        focusTarget.focus();
+        this._toggleFieldsetTabindex(false);
+    }
+
+    /**
+     * Handles the `focusout` event to restore the `tabindex` on the radio group's `fieldset`.
+     *
+     * When focus leaves the radio group, this method enables the `tabindex` attribute
+     * on the `fieldset` element. This ensures the radio group remains accessible for
+     * keyboard navigation and can be re-focused when tabbing back into the group.
+     */
+    private _handleFocusOut (): void {
+        this._toggleFieldsetTabindex(true);
+    }
+
+    private _toggleFieldsetTabindex (enable: boolean): void {
+        if (enable) {
+            this._fieldset.setAttribute('tabindex', '0');
+        } else {
+            this._fieldset.removeAttribute('tabindex');
+        }
+    }
+
+    private _moveFocus (currentIndex: number, step: number): void {
+        const newIndex = (currentIndex + step + this._slottedChildren.length) % this._slottedChildren.length;
+        this._focusAndClickOption(this._slottedChildren[newIndex]);
+    }
+
+    /**
+     * Determines if a key press indicates forward navigation within the radio group.
+     *
+     * This method evaluates a keyboard event to check if the pressed key corresponds
+     * to forward navigation based on the current text direction (LTR or RTL).
+     *
+     * **Behaviour:**
+     * - For LTR (Left-to-Right) layouts:
+     *   - `ArrowRight` and `ArrowDown` indicate forward navigation.
+     * - For RTL (Right-to-Left) layouts:
+     *   - `ArrowLeft` and `ArrowDown` indicate forward navigation.
+     */
+    private _isForwardKey (event: KeyboardEvent): boolean {
+        return (event.code === 'ArrowRight' && !this.isRTL) ||
+            (event.code === 'ArrowLeft' && this.isRTL) ||
+            event.code === 'ArrowDown';
+    }
+
+    /**
+     * Determines if a key press indicates backward navigation within the radio group.
+     *
+     * This method evaluates a keyboard event to check if the pressed key corresponds
+     * to backward navigation based on the current text direction (LTR or RTL).
+     *
+     * **Behaviour:**
+     * - For LTR (Left-to-Right) layouts:
+     *   - `ArrowLeft` and `ArrowUp` indicate backward navigation.
+     * - For RTL (Right-to-Left) layouts:
+     *   - `ArrowRight` and `ArrowUp` indicate backward navigation.
+     */
+    private _isBackwardKey (event: KeyboardEvent): boolean {
+        return (event.code === 'ArrowLeft' && !this.isRTL) ||
+            (event.code === 'ArrowRight' && this.isRTL) ||
+            event.code === 'ArrowUp';
+    }
+
+    /**
+     * Handles keyboard navigation within the radio group using arrow keys.
+     *
+     * This method responds to `keydown` events and determines the appropriate navigation
+     * action (forward or backward) based on the pressed key and the current focus. It prevents
+     * the default browser behaviour (e.g., scrolling) when arrow keys are used for navigation.
+     */
+    private _handleKeyDown (event: KeyboardEvent): void {
+        const currentlyFocusedChild = this._slottedChildren.find((child) => child === document.activeElement);
+
+        if (!currentlyFocusedChild) {
+            return;
+        }
+
+        const currentIndex = this._slottedChildren.indexOf(currentlyFocusedChild);
+        if (currentIndex === -1) {
+            return;
+        }
+
+        // Prevent default scrolling behavior when using Arrow keys for Radio Group navigation
+        if (['ArrowRight', 'ArrowDown', 'ArrowLeft', 'ArrowUp'].includes(event.code)) {
+            event.preventDefault();
+        }
+
+        if (this._isForwardKey(event)) {
+            this._moveFocus(currentIndex, 1);
+        } else if (this._isBackwardKey(event)) {
+            this._moveFocus(currentIndex, -1);
+        }
+    }
+
+    private _focusAndClickOption (option: HTMLInputElement): void {
+        option.focus();
+        // This is quite hacky, but it ensures the radio elements correct emit a real change event.
+        // Simply setting option.checked as true would require re-architecture of both this component and the radio button
+        // to ensure that property changes are observed and correctly propagated up.
+        option.shadowRoot?.querySelector('input')?.click();
+        this._toggleFieldsetTabindex(false);
     }
 
     disconnectedCallback (): void {
@@ -179,6 +334,7 @@ export class PieRadioGroup extends FormControlMixin(RtlMixin(LitElement)) implem
 
         return html`
             <fieldset
+                tabindex="0"
                 name=${ifDefined(name)}
                 ?disabled=${disabled}
                 data-test-id="pie-radio-group"