@cocreate/aria 1.6.0 → 1.8.0

package/CONTRIBUTING.md

@@ -13,7 +13,7 @@ Fork the [project on Github](https://github.com/CoCreate-app/CoCreate-aria) and
 ```
 git clone https://github.com/contributor/CoCreate-aria.git
 cd CoCreate-aria
-git remote add upstream https://github.com/CoCreate-app/CoCreate-aria.git
+git remote add upstream https://gitlab.com/cocreatejs/CoCreate-aria.git
 ```
 
 ## Create a Topic Branch

package/README.md

@@ -83,3 +83,118 @@ We appreciate your continued support, thank you!
 # License
 
 [The MIT License (MIT)](https://github.com/CoCreate-app/CoCreate-aria/blob/master/LICENSE)
+
+## Toggle buttons and selection groups
+
+Use `aria-pressed` on a button for an independent toggle. Related toggles can
+sit inside `role="group"`; grouping does not make them mutually exclusive.
+
+```html
+<div role="group" aria-label="Text formatting">
+    <button type="button" aria-pressed="false">Bold</button>
+    <button type="button" aria-pressed="false">Italic</button>
+</div>
+```
+
+For one selected option, use custom radios inside a labelled `radiogroup`.
+These controls do not need `aria-controls` or a panel to display.
+
+```html
+<div role="radiogroup" aria-label="API category">
+    <button type="button" role="radio" aria-checked="true">All</button>
+    <button type="button" role="radio" aria-checked="false">Storage</button>
+    <button type="button" role="radio" aria-checked="false">Cloud</button>
+</div>
+```
+
+Activating a radio selects it and deselects its siblings. Arrow keys move and
+select, Home/End jump to the first/last available item, and Space/Enter activate.
+Inside a toolbar, arrow keys move focus without selecting. Nested radio groups
+are independent. Disabled and hidden items are skipped during group navigation.
+
+Custom `role="checkbox"` and `role="switch"` controls toggle `aria-checked`.
+Native checkbox and radio inputs retain native behavior. Toggle and custom
+checked controls synchronize their `active` class with the state attribute;
+external attribute changes and dynamically inserted controls are supported.
+An initial `mixed` state is preserved until activation, which selects `true`.
+
+Controls handled by this module block activation when disabled or when
+`aria-disabled="true"`. Existing tab panel behavior continues to use
+`aria-selected` with its `tablist` and `aria-controls` targets.
+
+CoCreate links selection controls that reference the same `aria-controls` target.
+Clicking a custom radio clears linked pressed/checked controls; activating a
+linked toggle clears the radios while preserving other toggles. Mark a radio
+with `aria-default="true"` (or an empty `aria-default`) to select it when the
+last toggle is cleared. Without a default, all controls may remain unselected.
+`aria-default="false"` disables fallback; disabled radios are not eligible.
+If multiple eligible defaults are declared, no fallback is selected.
+`aria-checked` describes current selection independently of this default.
+`aria-default` is a CoCreate extension, not a standard ARIA attribute.
+This is CoCreate behavior, not native ARIA grouping. Tabs and disclosure
+controls remain separate, and the target's visibility is unchanged.
+
+Use `aria-default="next"` for a moving default. Its initial radio is the
+starting fallback. Selecting another radio sharing the controlled target
+removes the marker from the previous radio and places it on the selected one.
+"Next" means the next radio selected by the user, including keyboard activation,
+not the next radio in DOM order. Pressed buttons and checked toggles never
+receive or move this marker. Clearing the last toggle returns to the radio
+currently carrying it. A fixed `aria-default="true"` does not move.
+Declare one default per linked set; use either a fixed or a moving default.
+The marker lives in DOM attributes and is not automatically persisted across
+reloads. Direct changes to `aria-checked` do not transfer it.
+
+```html
+<div role="group" aria-label="Results mode">
+    <div role="radiogroup" aria-label="Preset">
+        <button role="radio" aria-checked="true" aria-controls="results" aria-default="next">All</button>
+        <button role="radio" aria-checked="false" aria-controls="results">Recommended</button>
+    </div>
+    <button aria-pressed="false" aria-controls="results">Storage</button>
+    <button aria-pressed="false" aria-controls="results">Cloud</button>
+</div>
+<div id="results"></div>
+```
+
+Native `input[type="radio"]` and `input[type="checkbox"]` with `aria-controls`
+also participate in linked selection and fixed/moving defaults. They use their
+native `checked` property and keyboard behavior, without redundant `aria-checked`
+or `aria-pressed` attributes. When coordination changes another native input,
+CoCreate dispatches `input` and `change` after the linked values are updated;
+unselected radios do not dispatch these notifications.
+
+## Multiselectable grids
+
+An element with `role="grid" aria-multiselectable="true"` scopes selection to
+its descendant rows. Mark selectable rows with `role="row"` and
+`aria-selected="false"`; include a `gridcell` in each row. Native `table`, `tr`,
+and `td` elements provide the corresponding row and cell structure. The module
+sets one row in the grid's tab sequence and leaves selection on the row's
+`aria-selected` attribute so other actions can query it directly.
+
+```html
+<div role="grid" aria-label="Files" aria-multiselectable="true">
+    <div role="row" aria-selected="false">
+        <div role="gridcell">Document A</div>
+    </div>
+    <div role="row" aria-selected="false">
+        <div role="gridcell">Document B</div>
+    </div>
+</div>
+```
+
+Click selects one row; Control/Command-click toggles one row; Shift-click
+selects a range; and Control/Command-Shift-click adds a range. Arrow keys and
+Home/End move focus without changing selection. Space toggles the focused row,
+Shift with an arrow extends selection, Control/Command-A selects the loaded
+rows, and Escape clears them. These interactions do not activate links or other
+controls inside a row. Selection actions are scoped to the nearest grid.
+
+A grid row can instead contain a native checkbox. Its own `checked` state is
+the selection state; the row does not need `aria-selected`. Checkbox clicks
+toggle independently, including Control/Command-click. Shift-click applies
+the clicked checkbox's new state to the range since the last checkbox click.
+Checkboxes with the same `name` form a range within one grid. CoCreate Aria
+does not synchronize checkbox `checked` with row `aria-selected`; an app can
+bind them explicitly when it needs both.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cocreate/aria",
-  "version": "1.6.0",
+  "version": "1.8.0",
   "description": "Orchestrate dynamic UI behavior and ARIA state with event-driven action chains, configured via HTML5 attributes or the JavaScript API.",
   "keywords": [
     "aria",
@@ -25,7 +25,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/CoCreate-app/CoCreate-aria.git"
+    "url": "git+https://gitlab.com/cocreatejs/CoCreate-aria.git"
   },
   "author": "CoCreate LLC",
   "license": "MIT",
@@ -39,10 +39,11 @@
   },
   "main": "./src/index.js",
   "dependencies": {
-    "@cocreate/observer": "^1.22.0"
+    "@cocreate/observer": "^1.23.0",
+    "@cocreate/state": "^1.29.0"
   },
   "devDependencies": {
-    "@cocreate/webpack": "^1.8.0"
+    "@cocreate/webpack": "^1.9.0"
   },
   "allowScripts": {
     "@cocreate/observer@1.19.0": true,