ember-aria-voyager 0.2.4 → 1.0.0

package/README.md

@@ -1,7 +1,7 @@
 # ember-aria-voyager
 
-[![Test Coverage](https://api.codeclimate.com/v1/badges/6bd88c10540e66d94e2a/test_coverage)](https://codeclimate.com/github/hokulea/aria-voyager/test_coverage)
-[![Maintainability](https://api.codeclimate.com/v1/badges/6bd88c10540e66d94e2a/maintainability)](https://codeclimate.com/github/hokulea/aria-voyager/maintainability)
+[![Maintainability](https://qlty.sh/gh/hokulea/projects/aria-voyager/maintainability.svg)](https://qlty.sh/gh/hokulea/projects/aria-voyager)
+[![Code Coverage](https://qlty.sh/gh/hokulea/projects/aria-voyager/coverage.svg)](https://qlty.sh/gh/hokulea/projects/aria-voyager)
 
 _Canoe vessel that navigates your aria._
 
@@ -26,6 +26,57 @@ pnpm add ember-aria-voyager
 
 ## Usage
 
+### `{{ariaGroup}}`
+
+Basic example:
+
+```glimmer-ts
+import { ariaGroup } from 'ember-aria-voyager';
+
+<template>
+  <div role="group" {{ariaGroup}}>
+    <button type="button">Cut</button>
+    <button type="button">Copy</button>
+    <button type="button">Paste</button>
+  </div>
+</template>
+```
+
+Here are the options, you can pass to `{{ariaGroup}}`
+
+```ts
+interface GroupSignature<T> {
+  Element: HTMLElement;
+  Args: {
+    Positional: [];
+    Named: {
+      items?: T[];
+      disabled?: boolean;
+    };
+  };
+}
+```
+
+Full example with reactive items:
+
+```glimmer-ts
+import { ariaGroup } from 'ember-aria-voyager';
+import { tracked } from '@glimmer/tracking';
+
+const context = new class {
+  @tracked items = ['Cut', 'Copy', 'Paste'];
+  @tracked disabled = false;
+};
+
+<template>
+  <div role="group" {{ariaGroup items=context.items disabled=context.disabled}}>
+    {{#each context.items as |item|}}
+      <button type="button">{{item}}</button>
+    {{/each}}
+  </div>
+</template>
+```
+
 ### `{{ariaListbox}}`
 
 Basic example:
@@ -118,9 +169,11 @@ import { ariaMenu } from 'ember-aria-voyager';
 Here are the options, you can pass to `{{ariaMenu}}`
 
 ```ts
-interface MenuSignature<T> {
+interface MenuOptions<T> {
   items?: T[];
   disabled?: boolean;
+  select?: (selection: HTMLElement[]) => void;
+  check?: (selection: HTMLElement[]) => void;
 }
 ```
 
@@ -154,6 +207,86 @@ const items = [
 </template>
 ```
 
+#### `menuitemcheckbox`
+
+Menu supports checking items.
+
+```glimmer-js
+import { ariaMenu } from 'ember-aria-voyager';
+
+function check(selection: HTMLElement[]) {
+  console.log('checked items:', selection);
+}
+
+<template>
+  <div role="menu" {{ariaMenu check=check}}>
+    <span role="menuitemcheckbox">Bold</span>
+    <span role="menuitemcheckbox">Italic</span>
+    <span role="menuitemcheckbox">Underline</span>
+    <span role="menuitemcheckbox">Strikethrough</span>
+  </div>
+</template>
+```
+
+#### `menuitemradio`
+
+Menu supports radio selection.
+The `role="menu"` itself acts as group within one of all radio items is checked.
+
+Here is a minimal example:
+
+```glimmer-js
+import { ariaMenu } from 'ember-aria-voyager';
+
+function select(selection: HTMLElement[]) {
+  console.log('selected items:', selection);
+}
+
+<template>
+  <div role="menu" {{ariaMenu select=select}}>
+    <span role="menuitemradio">Left</span>
+    <span role="menuitemradio">Center</span>
+    <span role="menuitemradio">Right</span>
+    <span role="menuitemradio">Justified</span>
+  </div>
+</template>
+```
+
+Though menus do support multiple groups of radio selection.
+This is supported as well.
+Here are all combinations:
+
+```glimmer-js
+import { ariaMenu } from 'ember-aria-voyager';
+
+function select(selection: HTMLElement) {
+  console.log('selected items across all groups:', selection);
+}
+
+<template>
+  <div role="menu" {{ariaMenu select=select}}>
+    <span role="menuitemradio">A</span>
+    <div role="group">
+      <span role="menuitemradio">B</span>
+      <span role="menuitemradio">C</span>
+    </div>
+    <span role="menuitemradio">D</span>
+    <div role="presentation">
+      <span role="menuitemradio">E</span>
+      <hr>
+      <span role="menuitemradio">F</span>
+    </div>
+    <span role="menuitemradio">G</span>
+    <span role="separator"></span>
+    <span role="menuitemradio">H</span>
+  </div>
+</template>
+```
+
+- B+C are one group
+- All others are in their own respective group
+- `select()` will return the selection across all groups
+
 ### `{{ariaTablist}}`
 
 Basic example:
@@ -198,3 +331,70 @@ interface TablistSignature<T> {
 ```
 
 When passing `items` the `select()` and `selection` can work off of your passed items, anyway will fall back to the HTMLElement
+
+### `{{ariaRadioGroup}}`
+
+Basic example:
+
+```glimmer-ts
+import { ariaRadioGroup } from 'ember-aria-voyager';
+
+<template>
+  <div role="radiogroup" {{ariaRadioGroup}}>
+    <button type="button" role="radio" aria-checked="false">Top</button>
+    <button type="button" role="radio" aria-checked="false">Bottom</button>
+    <button type="button" role="radio" aria-checked="false">Left</button>
+  </div>
+</template>
+```
+
+Here are the options, you can pass to `{{ariaRadioGroup}}`
+
+```ts
+interface RadioGroupSignature<T> {
+  Element: HTMLElement;
+  Args: {
+    Positional: [];
+    Named: {
+      items?: T[];
+      select?: (selection: HTMLElement) => void;
+      disabled?: boolean;
+    };
+  };
+}
+```
+
+Full example with selection callback:
+
+```glimmer-ts
+import { ariaRadioGroup } from 'ember-aria-voyager';
+import { tracked } from '@glimmer/tracking';
+
+const context = new class {
+  @tracked selected?: HTMLElement;
+
+  select = (item: HTMLElement) => {
+    this.selected = item;
+  };
+};
+
+<template>
+  <div role="radiogroup" {{ariaRadioGroup select=context.select}}>
+    <button type="button" role="radio" aria-checked="false">Top</button>
+    <button type="button" role="radio" aria-checked="false">Bottom</button>
+    <button type="button" role="radio" aria-checked="false">Left</button>
+  </div>
+</template>
+```
+
+## Use in Classic Apps
+
+`ember-aria-voyager` is primed to be used with polaris edition of ember using
+imports. Classic v1 addons and v2 addons with compat automatically provide
+re-exports, which this addon does not. Re-export it manually. Here is an example
+for `ariaListbox`:
+
+```ts
+// app/modifiers/aria-listbox.js
+export { ariaListbox as default } from 'ember-aria-voyager';
+```

package/dist/aria-tablist-Bpm0pW99.d.cts

@@ -0,0 +1,198 @@
+import Modifier, { ArgsFor, NamedArgs, PositionalArgs } from "ember-modifier";
+import Owner from "@ember/owner";
+import { Orientation, TablistBehavior } from "aria-voyager";
+
+//#region src/modifiers/aria-group.d.ts
+interface GroupSignature<T> {
+  Element: HTMLElement;
+  Args: {
+    Positional: [];
+    Named: {
+      items?: T[];
+      disabled?: boolean;
+    };
+  };
+}
+declare class GroupModifier<T> extends Modifier<GroupSignature<T>> {
+  private group?;
+  private updater;
+  private emitter;
+  private prevItems?;
+  private prevDisabled?;
+  constructor(owner: Owner, args: ArgsFor<GroupSignature<T>>);
+  modify(element: Element, _: PositionalArgs<GroupSignature<T>>, options: NamedArgs<GroupSignature<T>>): void;
+}
+//#endregion
+//#region ../../node_modules/.pnpm/type-fest@5.7.0/node_modules/type-fest/source/simplify.d.ts
+/**
+Useful to flatten the type output to improve type hints shown in editors. And also to transform an interface into a type to aide with assignability.
+
+@example
+```
+import type {Simplify} from 'type-fest';
+
+type PositionProps = {
+	top: number;
+	left: number;
+};
+
+type SizeProps = {
+	width: number;
+	height: number;
+};
+
+// In your editor, hovering over `Props` will show a flattened object with all the properties.
+type Props = Simplify<PositionProps & SizeProps>;
+```
+
+Sometimes it is desired to pass a value as a function argument that has a different type. At first inspection it may seem assignable, and then you discover it is not because the `value`'s type definition was defined as an interface. In the following example, `fn` requires an argument of type `Record<string, unknown>`. If the value is defined as a literal, then it is assignable. And if the `value` is defined as type using the `Simplify` utility the value is assignable.  But if the `value` is defined as an interface, it is not assignable because the interface is not sealed and elsewhere a non-string property could be added to the interface.
+
+If the type definition must be an interface (perhaps it was defined in a third-party npm package), then the `value` can be defined as `const value: Simplify<SomeInterface> = ...`. Then `value` will be assignable to the `fn` argument.  Or the `value` can be cast as `Simplify<SomeInterface>` if you can't re-declare the `value`.
+
+@example
+```
+import type {Simplify} from 'type-fest';
+
+interface SomeInterface {
+	foo: number;
+	bar?: string;
+	baz: number | undefined;
+}
+
+type SomeType = {
+	foo: number;
+	bar?: string;
+	baz: number | undefined;
+};
+
+const literal = {foo: 123, bar: 'hello', baz: 456};
+const someType: SomeType = literal;
+const someInterface: SomeInterface = literal;
+
+declare function fn(object: Record<string, unknown>): void;
+
+fn(literal); // Good: literal object type is sealed
+fn(someType); // Good: type is sealed
+// @ts-expect-error
+fn(someInterface); // Error: Index signature for type 'string' is missing in type 'someInterface'. Because `interface` can be re-opened
+fn(someInterface as Simplify<SomeInterface>); // Good: transform an `interface` into a `type`
+```
+
+@link https://github.com/microsoft/TypeScript/issues/15300
+@see {@link SimplifyDeep}
+@category Object
+*/
+type Simplify<T> = { [KeyType in keyof T]: T[KeyType] } & {};
+//#endregion
+//#region src/modifiers/-emitter.d.ts
+type Items<T> = {
+  items: T[];
+};
+type ActivateHandler<T> = {
+  activateItem?: (item: T) => void;
+};
+type CheckHandler<T> = {
+  check?: (selection: T[]) => void;
+};
+type SingleSelectionHandler<T> = {
+  multi?: false;
+  selection?: T;
+  select?: (selection: T) => void;
+};
+type MultiSelectionHandler<T> = {
+  multi: true;
+  selection?: T[];
+  select?: (selection: T[]) => void;
+};
+type SelectionHandler<T> = SingleSelectionHandler<T> | MultiSelectionHandler<T>;
+//#endregion
+//#region src/modifiers/aria-listbox.d.ts
+type ListboxOptions<T> = Simplify<SelectionHandler<T> & (Items<T> | Partial<Items<T>>) & ActivateHandler<T> & {
+  disabled?: boolean;
+}>;
+interface ListboxSignature<T> {
+  Args: {
+    Positional: [];
+    Named: ListboxOptions<T>;
+  };
+}
+declare class ListboxModifier<T> extends Modifier<ListboxSignature<T>> {
+  private listbox?;
+  private updater;
+  private emitter;
+  private prevItems?;
+  private prevSelection?;
+  private prevMulti?;
+  private prevDisabled?;
+  constructor(owner: Owner, args: ArgsFor<ListboxSignature<T>>);
+  modify(element: Element, _: PositionalArgs<ListboxSignature<T>>, options: NamedArgs<ListboxSignature<T>>): void;
+}
+//#endregion
+//#region src/modifiers/aria-menu.d.ts
+type MenuOptions<T> = Simplify<Omit<MultiSelectionHandler<T>, 'multi'> & (Items<T> | Partial<Items<T>>) & ActivateHandler<T> & CheckHandler<T> & {
+  disabled?: boolean;
+}>;
+interface MenuSignature<T> {
+  Element: HTMLElement;
+  Args: {
+    Positional: [];
+    Named: MenuOptions<T>;
+  };
+}
+declare class MenuModifier<T> extends Modifier<MenuSignature<T>> {
+  private menu?;
+  private updater;
+  private emitter;
+  private prevItems?;
+  private prevDisabled?;
+  constructor(owner: Owner, args: ArgsFor<MenuSignature<T>>);
+  modify(element: Element, _: PositionalArgs<MenuSignature<T>>, options: NamedArgs<MenuSignature<T>>): void;
+}
+//#endregion
+//#region src/modifiers/aria-radiogroup.d.ts
+type RadioGroupOptions<T> = Simplify<SingleSelectionHandler<T> & (Items<T> | Partial<Items<T>>) & ActivateHandler<T> & {
+  disabled?: boolean;
+}>;
+interface RadioGroupSignature<T> {
+  Element: HTMLElement;
+  Args: {
+    Positional: [];
+    Named: RadioGroupOptions<T>;
+  };
+}
+declare class RadioGroupModifier<T> extends Modifier<RadioGroupSignature<T>> {
+  private radioGroup?;
+  private updater;
+  private emitter;
+  private prevItems?;
+  private prevDisabled?;
+  constructor(owner: Owner, args: ArgsFor<RadioGroupSignature<T>>);
+  modify(element: Element, _: PositionalArgs<RadioGroupSignature<T>>, options: NamedArgs<RadioGroupSignature<T>>): void;
+}
+//#endregion
+//#region src/modifiers/aria-tablist.d.ts
+type TablistOptions<T> = Simplify<Omit<SingleSelectionHandler<T>, 'multi'> & (Items<T> | Partial<Items<T>>) & ActivateHandler<T> & {
+  disabled?: boolean;
+  orientation?: Orientation;
+  behavior?: TablistBehavior;
+}>;
+interface TablistSignature<T> {
+  Element: HTMLElement;
+  Args: {
+    Positional: [];
+    Named: TablistOptions<T>;
+  };
+}
+declare class TablistModifier<T> extends Modifier<TablistSignature<T>> {
+  private tablist?;
+  private updater;
+  private emitter;
+  private prevItems?;
+  private prevSelection?;
+  private prevDisabled?;
+  private prevOrientation?;
+  constructor(owner: Owner, args: ArgsFor<TablistSignature<T>>);
+  modify(element: Element, _: PositionalArgs<TablistSignature<T>>, options: NamedArgs<TablistSignature<T>>): void;
+}
+//#endregion
+export { GroupModifier as a, ListboxModifier as i, RadioGroupModifier as n, MenuModifier as r, TablistModifier as t };

package/dist/aria-tablist-ZH-aeJQW.d.mts

@@ -0,0 +1,198 @@
+import { IndexEmitStrategy, ItemEmitStrategy, Orientation, TablistBehavior } from "aria-voyager";
+import Modifier, { ArgsFor, NamedArgs, PositionalArgs } from "ember-modifier";
+import Owner from "@ember/owner";
+
+//#region src/modifiers/aria-group.d.ts
+interface GroupSignature<T> {
+  Element: HTMLElement;
+  Args: {
+    Positional: [];
+    Named: {
+      items?: T[];
+      disabled?: boolean;
+    };
+  };
+}
+declare class GroupModifier<T> extends Modifier<GroupSignature<T>> {
+  private group?;
+  private updater;
+  private emitter;
+  private prevItems?;
+  private prevDisabled?;
+  constructor(owner: Owner, args: ArgsFor<GroupSignature<T>>);
+  modify(element: Element, _: PositionalArgs<GroupSignature<T>>, options: NamedArgs<GroupSignature<T>>): void;
+}
+//#endregion
+//#region ../../node_modules/.pnpm/type-fest@5.7.0/node_modules/type-fest/source/simplify.d.ts
+/**
+Useful to flatten the type output to improve type hints shown in editors. And also to transform an interface into a type to aide with assignability.
+
+@example
+```
+import type {Simplify} from 'type-fest';
+
+type PositionProps = {
+	top: number;
+	left: number;
+};
+
+type SizeProps = {
+	width: number;
+	height: number;
+};
+
+// In your editor, hovering over `Props` will show a flattened object with all the properties.
+type Props = Simplify<PositionProps & SizeProps>;
+```
+
+Sometimes it is desired to pass a value as a function argument that has a different type. At first inspection it may seem assignable, and then you discover it is not because the `value`'s type definition was defined as an interface. In the following example, `fn` requires an argument of type `Record<string, unknown>`. If the value is defined as a literal, then it is assignable. And if the `value` is defined as type using the `Simplify` utility the value is assignable.  But if the `value` is defined as an interface, it is not assignable because the interface is not sealed and elsewhere a non-string property could be added to the interface.
+
+If the type definition must be an interface (perhaps it was defined in a third-party npm package), then the `value` can be defined as `const value: Simplify<SomeInterface> = ...`. Then `value` will be assignable to the `fn` argument.  Or the `value` can be cast as `Simplify<SomeInterface>` if you can't re-declare the `value`.
+
+@example
+```
+import type {Simplify} from 'type-fest';
+
+interface SomeInterface {
+	foo: number;
+	bar?: string;
+	baz: number | undefined;
+}
+
+type SomeType = {
+	foo: number;
+	bar?: string;
+	baz: number | undefined;
+};
+
+const literal = {foo: 123, bar: 'hello', baz: 456};
+const someType: SomeType = literal;
+const someInterface: SomeInterface = literal;
+
+declare function fn(object: Record<string, unknown>): void;
+
+fn(literal); // Good: literal object type is sealed
+fn(someType); // Good: type is sealed
+// @ts-expect-error
+fn(someInterface); // Error: Index signature for type 'string' is missing in type 'someInterface'. Because `interface` can be re-opened
+fn(someInterface as Simplify<SomeInterface>); // Good: transform an `interface` into a `type`
+```
+
+@link https://github.com/microsoft/TypeScript/issues/15300
+@see {@link SimplifyDeep}
+@category Object
+*/
+type Simplify<T> = { [KeyType in keyof T]: T[KeyType] } & {};
+//#endregion
+//#region src/modifiers/-emitter.d.ts
+type Items<T> = {
+  items: T[];
+};
+type ActivateHandler<T> = {
+  activateItem?: (item: T) => void;
+};
+type CheckHandler<T> = {
+  check?: (selection: T[]) => void;
+};
+type SingleSelectionHandler<T> = {
+  multi?: false;
+  selection?: T;
+  select?: (selection: T) => void;
+};
+type MultiSelectionHandler<T> = {
+  multi: true;
+  selection?: T[];
+  select?: (selection: T[]) => void;
+};
+type SelectionHandler<T> = SingleSelectionHandler<T> | MultiSelectionHandler<T>;
+//#endregion
+//#region src/modifiers/aria-listbox.d.ts
+type ListboxOptions<T> = Simplify<SelectionHandler<T> & (Items<T> | Partial<Items<T>>) & ActivateHandler<T> & {
+  disabled?: boolean;
+}>;
+interface ListboxSignature<T> {
+  Args: {
+    Positional: [];
+    Named: ListboxOptions<T>;
+  };
+}
+declare class ListboxModifier<T> extends Modifier<ListboxSignature<T>> {
+  private listbox?;
+  private updater;
+  private emitter;
+  private prevItems?;
+  private prevSelection?;
+  private prevMulti?;
+  private prevDisabled?;
+  constructor(owner: Owner, args: ArgsFor<ListboxSignature<T>>);
+  modify(element: Element, _: PositionalArgs<ListboxSignature<T>>, options: NamedArgs<ListboxSignature<T>>): void;
+}
+//#endregion
+//#region src/modifiers/aria-menu.d.ts
+type MenuOptions<T> = Simplify<Omit<MultiSelectionHandler<T>, 'multi'> & (Items<T> | Partial<Items<T>>) & ActivateHandler<T> & CheckHandler<T> & {
+  disabled?: boolean;
+}>;
+interface MenuSignature<T> {
+  Element: HTMLElement;
+  Args: {
+    Positional: [];
+    Named: MenuOptions<T>;
+  };
+}
+declare class MenuModifier<T> extends Modifier<MenuSignature<T>> {
+  private menu?;
+  private updater;
+  private emitter;
+  private prevItems?;
+  private prevDisabled?;
+  constructor(owner: Owner, args: ArgsFor<MenuSignature<T>>);
+  modify(element: Element, _: PositionalArgs<MenuSignature<T>>, options: NamedArgs<MenuSignature<T>>): void;
+}
+//#endregion
+//#region src/modifiers/aria-radiogroup.d.ts
+type RadioGroupOptions<T> = Simplify<SingleSelectionHandler<T> & (Items<T> | Partial<Items<T>>) & ActivateHandler<T> & {
+  disabled?: boolean;
+}>;
+interface RadioGroupSignature<T> {
+  Element: HTMLElement;
+  Args: {
+    Positional: [];
+    Named: RadioGroupOptions<T>;
+  };
+}
+declare class RadioGroupModifier<T> extends Modifier<RadioGroupSignature<T>> {
+  private radioGroup?;
+  private updater;
+  private emitter;
+  private prevItems?;
+  private prevDisabled?;
+  constructor(owner: Owner, args: ArgsFor<RadioGroupSignature<T>>);
+  modify(element: Element, _: PositionalArgs<RadioGroupSignature<T>>, options: NamedArgs<RadioGroupSignature<T>>): void;
+}
+//#endregion
+//#region src/modifiers/aria-tablist.d.ts
+type TablistOptions<T> = Simplify<Omit<SingleSelectionHandler<T>, 'multi'> & (Items<T> | Partial<Items<T>>) & ActivateHandler<T> & {
+  disabled?: boolean;
+  orientation?: Orientation;
+  behavior?: TablistBehavior;
+}>;
+interface TablistSignature<T> {
+  Element: HTMLElement;
+  Args: {
+    Positional: [];
+    Named: TablistOptions<T>;
+  };
+}
+declare class TablistModifier<T> extends Modifier<TablistSignature<T>> {
+  private tablist?;
+  private updater;
+  private emitter;
+  private prevItems?;
+  private prevSelection?;
+  private prevDisabled?;
+  private prevOrientation?;
+  constructor(owner: Owner, args: ArgsFor<TablistSignature<T>>);
+  modify(element: Element, _: PositionalArgs<TablistSignature<T>>, options: NamedArgs<TablistSignature<T>>): void;
+}
+//#endregion
+export { GroupModifier as a, ListboxModifier as i, RadioGroupModifier as n, MenuModifier as r, TablistModifier as t };