[ToggleGroup]: New component (#258)

* New component: ToggleGroup

* Lint/fix

Author: NullVoxPopuli

docs-app/.prettierignore

@@ -3,6 +3,7 @@ app/templates/*.gts
 # unconventional js
 /blueprints/*/files/
 /vendor/
+.eslintcache
 
 # compiled output
 /dist/

docs-app/app/routes/application.ts

@@ -0,0 +1,12 @@
+import Route from '@ember/routing/route';
+import { service } from '@ember/service';
+
+import type { SetupService } from 'ember-primitives';
+
+export default class Application extends Route {
+  @service('ember-primitives/setup') declare primitives: SetupService;
+
+  beforeModel() {
+    this.primitives.setup();
+  }
+}

docs-app/public/docs/2-accessibility/intro.md

@@ -41,3 +41,39 @@ import { Switch } from 'ember-primitives';
 -->
 
 This only happens during development, and in production, the CSS that applies these warnings is not included.
+
+## Keyboard Support
+
+ember-primitives uses _The Platform_ where possible and implements W3C recommendations for patterns where _The Platform_ does not provide solutions. To help lift the burden of maintenance for keyboard support implementation, ember-primitives uses [tabster](https://tabster.io/) for adding that additional keyboard support.
+
+This keyboard support is enabled by default but does require initialization. You can initialize keyboard support in your application router by calling the `setup()` method on the `ember-primitives/setup` service:
+```ts
+import Route from '@ember/routing/route';
+import { service } from '@ember/service';
+
+import type { SetupService } from 'ember-primitives';
+
+export default class Application extends Route {
+  @service('ember-primitives/setup') declare primitives: SetupService;
+
+  beforeModel() {
+    this.primitives.setup();
+  }
+}
+```
+
+This is customizable, in case your application already uses tabster -- you may pass options to the `setup()` method:
+```ts
+// To use your own tabster
+this.primitives.setup({ tabster: myTabsterCoreInstance });
+// To specify your own "tabster root" 
+this.primitives.setup({ setTabsterRoot: false });
+```
+
+The tabster root is an element which which tells tabster to pay attention for tabster-using features.
+It can be set this way:
+```html
+<div data-tabster='{ "root": {} }'></div>
+```
+
+By default, this attribute-value pair is set on the `body` element.

docs-app/public/docs/3-ui/toggle-group.md

@@ -0,0 +1,162 @@
+# ToggleGroup
+
+A group of two-state buttons that can be toggled on or off.
+
+
+<div class="featured-demo">
+
+```gjs live preview no-shadow
+import { ToggleGroup } from 'ember-primitives';
+
+<template>
+  <div class="demo">
+    <ToggleGroup class="toggle-group" as |t|>
+      <t.Item @value="left" aria-label="Left align">
+        <AlignLeft />
+      </t.Item> 
+      <t.Item @value="center" aria-label="Center align">
+        <AlignCenter />
+      </t.Item> 
+      <t.Item @value="right" aria-label="Right align">
+        <AlignRight />
+      </t.Item> 
+    </ToggleGroup>
+  </div>
+
+  <style>
+    .demo { display: flex; justify-content: center; align-items: center;}
+    .toggle-group {
+      display: inline-flex;
+      background-color: #fff;
+      border-radius: 0.25rem;
+      filter: drop-shadow(0 2px 2px rgba(0,0,0,0.5));
+    }
+
+    .toggle-group > button {
+      background-color: white;
+      color: #fff;
+      height: 35px;
+      width: 35px;
+      display: flex;
+      font-size: 15px;
+      padding: 0.5rem;
+      line-height: 1;
+      align-items: center;
+      justify-content: center;
+      margin-left: 1px;
+      border: 0;
+    }
+    .toggle-group > button:first-child {
+      margin-left: 0;
+      border-top-left-radius: 4px;
+      border-bottom-left-radius: 4px;
+    }
+    .toggle-group > button:last-child {
+      border-top-right-radius: 4px;
+      border-bottom-right-radius: 4px;
+    }
+    .toggle-group > button:hover {
+      background-color: #eee;
+    }
+    .toggle-group > button[aria-pressed='true'] {
+      background-color: #ddf;
+      color: black;
+    }
+    .toggle-group > button:focus {
+      position: relative;
+      box-shadow: 0 0 0 2px black;
+    }
+  </style>
+</template>
+
+const AlignLeft = <template>
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 448 512"><!--!Font Awesome Free 6.5.1 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free Copyright 2024 Fonticons, Inc.--><path d="M288 64c0 17.7-14.3 32-32 32H32C14.3 96 0 81.7 0 64S14.3 32 32 32H256c17.7 0 32 14.3 32 32zm0 256c0 17.7-14.3 32-32 32H32c-17.7 0-32-14.3-32-32s14.3-32 32-32H256c17.7 0 32 14.3 32 32zM0 192c0-17.7 14.3-32 32-32H416c17.7 0 32 14.3 32 32s-14.3 32-32 32H32c-17.7 0-32-14.3-32-32zM448 448c0 17.7-14.3 32-32 32H32c-17.7 0-32-14.3-32-32s14.3-32 32-32H416c17.7 0 32 14.3 32 32z"/></svg>
+</template>;
+const AlignCenter = <template>
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 448 512"><!--!Font Awesome Free 6.5.1 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free Copyright 2024 Fonticons, Inc.--><path d="M352 64c0-17.7-14.3-32-32-32H128c-17.7 0-32 14.3-32 32s14.3 32 32 32H320c17.7 0 32-14.3 32-32zm96 128c0-17.7-14.3-32-32-32H32c-17.7 0-32 14.3-32 32s14.3 32 32 32H416c17.7 0 32-14.3 32-32zM0 448c0 17.7 14.3 32 32 32H416c17.7 0 32-14.3 32-32s-14.3-32-32-32H32c-17.7 0-32 14.3-32 32zM352 320c0-17.7-14.3-32-32-32H128c-17.7 0-32 14.3-32 32s14.3 32 32 32H320c17.7 0 32-14.3 32-32z"/></svg>
+</template>;
+const AlignRight = <template>
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 448 512"><!--!Font Awesome Free 6.5.1 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free Copyright 2024 Fonticons, Inc.--><path d="M448 64c0 17.7-14.3 32-32 32H192c-17.7 0-32-14.3-32-32s14.3-32 32-32H416c17.7 0 32 14.3 32 32zm0 256c0 17.7-14.3 32-32 32H192c-17.7 0-32-14.3-32-32s14.3-32 32-32H416c17.7 0 32 14.3 32 32zM0 192c0-17.7 14.3-32 32-32H416c17.7 0 32 14.3 32 32s-14.3 32-32 32H32c-17.7 0-32-14.3-32-32zM448 448c0 17.7-14.3 32-32 32H32c-17.7 0-32-14.3-32-32s14.3-32 32-32H416c17.7 0 32 14.3 32 32z"/></svg>
+</template>;
+```
+
+</div>
+
+## Features
+
+* Full keyboard navigation
+* Supports horizontal / vertical orientation
+* Support single and multiple pressed buttons
+* Can be controlled or uncontrolled
+
+## Installation 
+
+```bash 
+pnpm add ember-primitives
+```
+
+## Anatomy
+
+```js 
+import { ToggleGroup } from 'ember-primitives';
+```
+
+or for non-tree-shaking environments:
+```js 
+import { ToggleGroup } from 'ember-primitives/components/toggle';
+```
+
+
+```gjs 
+import { ToggleGroup } from 'ember-primitives';
+
+<template>
+  <ToggleGroup as |t|>
+    <t.Item /> 
+  </ToggleGroup>
+</template>
+```
+
+## API Reference
+
+```gjs live no-shadow
+import { ComponentSignature } from 'docs-app/docs-support';
+
+<template>
+  <ComponentSignature @module="components/toggle-group" @name="ToggleGroup" />
+</template>
+```
+
+<hr>
+
+### Item
+
+```gjs live no-shadow
+import { ComponentSignature } from 'docs-app/docs-support';
+
+<template>
+  <ComponentSignature @module="components/toggle-group" @name="ItemSignature" />
+</template>
+```
+
+## Accessibility
+
+Uses [roving tabindex](https://www.w3.org/TR/wai-aria-practices-1.2/examples/radio/radio.html) to manage focus movement among items using the [tabster](https://tabster.io/) library.
+
+As a caveat to using [tabster](https://tabster.io/), a "tabster-root" will need to be established separately if this component is used within a shadow-root, which escapes the parent-DOM's tabster instance.
+
+For more information, see [The Accessibility guide](/2-accessibility/intro.md).
+
+### Keyboard Interactions
+
+| key | description |  
+| :---: | :----------- |  
+| <kbd>Tab</kbd> | Moves focus to the first item in the group |  
+| <kbd>Space</kbd> | Toggles the item's state |  
+| <kbd>Enter</kbd> | Toggles the item's state |  
+| <kbd>ArrowDown</kbd> | Moves focus to the next item in the group |  
+| <kbd>ArrowRight</kbd> | Moves focus to the next item in the group |  
+| <kbd>ArrowDown</kbd> | Moves focus to the previous item in the group |  
+| <kbd>ArrowLeft</kbd> | Moves focus to the previous item in the group |  
+| <kbd>Home</kbd> | Moves focus to the first item in the group |  
+| <kbd>End</kbd> | Moves focus to the last item in the group |  

ember-primitives/package.json

@@ -43,6 +43,7 @@
     "ember-element-helper": "^0.8.4",
     "ember-velcro": "^2.1.3",
     "reactiveweb": "^1.2.0",
+    "tabster": "^7.0.1",
     "tracked-toolbox": "^2.0.0"
   },
   "devDependencies": {
@@ -115,8 +116,10 @@
       "./components/scroller.js": "./dist/_app_/components/scroller.js",
       "./components/shadowed.js": "./dist/_app_/components/shadowed.js",
       "./components/switch.js": "./dist/_app_/components/switch.js",
+      "./components/toggle-group.js": "./dist/_app_/components/toggle-group.js",
       "./components/toggle.js": "./dist/_app_/components/toggle.js",
-      "./helpers/service.js": "./dist/_app_/helpers/service.js"
+      "./helpers/service.js": "./dist/_app_/helpers/service.js",
+      "./services/ember-primitives/setup.js": "./dist/_app_/services/ember-primitives/setup.js"
     }
   },
   "exports": {

ember-primitives/rollup.config.mjs

@@ -15,7 +15,7 @@ export default {
   output: addon.output(),
   plugins: [
     addon.publicEntrypoints(["**/*.js"]),
-    addon.appReexports(["components/*.js", "helpers/**/*.js"]),
+    addon.appReexports(["components/*.js", "helpers/**/*.js", "services/**/*.js"]),
     addon.dependencies(),
     babel({ extensions, babelHelpers: "inline" }),
     addon.hbs(),

ember-primitives/src/components/-private/utils.ts

@@ -2,10 +2,14 @@
  * If the user provides an onChange or similar function, use that,
  * otherwise fallback to the uncontrolled toggle
  */
-export function toggleWithFallback(uncontrolledToggle: () => void, controlledToggle?: () => void) {
+export function toggleWithFallback(
+  uncontrolledToggle: (...args: unknown[]) => void,
+  controlledToggle?: (...args: unknown[]) => void,
+  ...args: unknown[]
+) {
   if (controlledToggle) {
-    return controlledToggle();
+    return controlledToggle(...args);
   }
 
-  uncontrolledToggle();
+  uncontrolledToggle(...args);
 }

ember-primitives/src/components/toggle-group.gts

@@ -0,0 +1,98 @@
+import Component from '@glimmer/component';
+import { hash } from '@ember/helper';
+
+import { Types } from 'tabster';
+// The consumer will need to provide types for tracked-toolbox.
+// Or.. better yet, we PR to trakcked-toolbox to provide them
+// eslint-disable-next-line @typescript-eslint/ban-ts-comment
+// @ts-ignore
+import { localCopy } from 'tracked-toolbox';
+
+import { Toggle } from './toggle.gts';
+
+import type { ComponentLike } from '@glint/template';
+
+const TABSTER_CONFIG = JSON.stringify({
+  mover: {
+    direction: Types.MoverDirections.Both,
+    cyclic: true,
+  },
+});
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export interface ItemSignature<Value = any> {
+  /**
+   * The button element will have aria-pressed="true" on it when the button is in the pressed state.
+   */
+  Element: HTMLButtonElement;
+  Args: {
+    /**
+     * When used in a group of Toggles, this option will be helpful to
+     * know which toggle was pressed if you're using the same @onChange
+     * handler for multiple toggles.
+     */
+    value?: Value;
+  };
+  Blocks: {
+    default: [
+      /**
+       * the current pressed state of the toggle button
+       *
+       * Useful when using the toggle button as an uncontrolled component
+       */
+      pressed: boolean,
+    ];
+  };
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type Item<Value = any> = ComponentLike<ItemSignature<Value>>;
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export class ToggleGroup<Value = any> extends Component<{
+  Element: HTMLDivElement;
+  Args: {
+    /**
+     * Optionally set the initial toggle state
+     */
+    value?: Value;
+    /**
+     * Callback for when the toggle-group's state is changed.
+     *
+     * Can be used to control the state of the component.
+     *
+     *
+     * When none of the toggles are selected, undefined will be passed.
+     */
+    onChange: (value: Value | undefined) => void;
+  };
+  Blocks: {
+    default: [
+      {
+        Item: Item;
+      },
+    ];
+  };
+}> {
+  @localCopy('args.value') activePressed?: Value;
+
+  handleToggle = (value: Value) => {
+    if (this.activePressed === value) {
+      this.activePressed = undefined;
+
+      return;
+    }
+
+    this.activePressed = value;
+
+    this.args.onChange?.(this.activePressed);
+  };
+
+  isPressed = (value: Value | undefined) => value === this.activePressed;
+
+  <template>
+    <div data-tabster={{TABSTER_CONFIG}} ...attributes>
+      {{yield (hash Item=(component Toggle onChange=this.handleToggle isPressed=this.isPressed))}}
+    </div>
+  </template>
+}