feat(features): document more concepts and motivations

Author: AlexVipond

package-lock.json

@@ -4,25 +4,22 @@ publish: true
 order: 0
 ---
 
-Baleada Features implements comprehensive, reusable, flexible features for **accessibility**, one of the core motivations behind the package.
+Baleada Features implements comprehensive **accessibility**.
 
-Some accessibility features—like ARIA role & attribute management, keyboard interactions, and focus management—are always required.
-Baleada Features takes care of all of those things for you!
+This includes accessibility features that are always required (like ARIA role & attribute management, keyboard interactions, and focus management) as well as optional, situational, and dynamic features.
 
-For example, use your mouse, keyboard, touch, and screen reader to play with this custom multiselectable listbox, and note:
+For example, use your mouse, keyboard, touch, and screen reader to play with this custom multiselectable listbox, and note these features, required by WAI-ARIA guidelines:
 - It announces itself properly to assistive tech, including selection state and disabled state
 - It supports Excel-inspired pointer and keyboard interactions
 - It automatically manages focus on the listbox options
 
 <ExampleListboxAccessible class="mt-6 mx-auto w-full with-max-w" variant="default" />
 
-Other accessibility features are optional or situational.
-
-For example, after you add the required accessible label to a listbox, you might want to add an optional description, announced to assistive tech. Baleada Features makes it easy to do so.
+And note how this listbox, which has the required label, also has a fully optional description that gets announced to assistive tech. Baleada Features makes this easy to do.
 
 <ExampleListboxAccessible class="mt-6 mx-auto w-full with-max-w" variant="described" />
 
-Other accessibility features are required, but configurable.
+Other accessibility features are situational and [configurable](/docs/features/motivations/configurability).
 
 For example, in the listboxes above:
 - We use a vertical orientation
@@ -65,9 +62,7 @@ And on top of that, Baleada Features adds these features to UI elements where yo
 
 <ExampleListboxAccessible class="mt-6 mx-auto w-full with-max-w" variant="dynamic" />
 
-The web platform is amazing, but when it comes to accessibility, it's still missing so many UI components, and so much configurability.
-
-Baleada Features aims to close that gap.
+When it comes to accessibility, the web platform is amazing, but it's still missing so many UI components, and so much configurability. Baleada Features aims to close that gap.
 
 ::: type="success"
 Accessibility is great UX!

src/prose/features/00-motivations/accessibility.md

@@ -4,135 +4,31 @@ publish: true
 order: 1
 ---
 
-Baleada Features is designed around **composability**—the ability to build complex features by combining simpler, reusable pieces.
+Baleada Features is designed for **composability**—the ability to build complex UIs by combining smaller reusable pieces.
 
-The package organizes features into layers that build on each other:
+You can use an [interface](/docs/features/interfaces-overview) or a [combo](/docs/features/combo-overview) to wire up essential UI logic and [accessibility](/docs/features/motivations/accessibility) features, then add [extensions](/docs/features/extensions-overview) to bring additional functionality. You can even drop down to [affordances](/docs/features/affordances-overview) for lower level tasks like binding props or adding custom event listeners to an existing element.
 
-1. **Affordances** — Low-level tools for binding attributes, handling events, and showing/hiding elements
-2. **Extensions** — Reusable behaviors like `usePopup`, `useFocus`, `usePress`, and `useHover`
-3. **Interfaces** — Complete accessible UI patterns like `useListbox`, `useButton`, and `useTextbox`
-4. **Combos** — Full components that combine interfaces and extensions, like `useCombobox`, `useSelect`, and `useMenu`
-
-Each layer composes features from the layers below it, and you can use any layer directly depending on your needs.
-
-
-:::
-## Extensions compose into interfaces
 :::
-
-Extensions add focused, reusable behaviors to elements. For example, `usePress` handles all the complexity of pointer and keyboard press interactions:
-
-::: canCopy
 ```ts
-import { usePress } from '@baleada/vue-features'
-
-const press = usePress(element)
-
-// React to press events
-watch(press.firstDescriptor, () => {
-  console.log('Pressed!')
-})
-```
-:::
-
-Interfaces like `useButton` compose extensions internally. A button needs press detection, ability state, and proper ARIA bindings—`useButton` composes all of these together:
-
-::: canCopy
-```ts
-import { useButton } from '@baleada/vue-features'
-
-const button = useButton()
-// Internally composes usePress, useAbility, bind(), and more
-```
-:::
-
-
-:::
-## Interfaces compose into combos
-:::
-
-When you need a complete component, like a combobox with a textbox, button, and popup listbox, you can use a combo. Combos compose multiple interfaces and extensions:
-
-::: canCopy
-```ts
-import { useCombobox } from '@baleada/vue-features'
-
-const combobox = useCombobox()
-// Internally composes:
-// - useTextbox (for the input)
-// - useButton (for the trigger)
-// - useListbox (for the options)
-// - usePopup (for show/hide behavior)
-```
-:::
-
-
-:::
-## Mix and match layers
-:::
-
-You can combine features from any layer to build exactly what you need.
-
-Need a custom select that uses your own trigger instead of a button? Compose a listbox with a popup yourself:
-
-::: canCopy
-```ts
-import { useListbox, usePopup } from '@baleada/vue-features'
+import { useListbox, useFocus, bind, on } from '@baleada/vue-features'
 
 const listbox = useListbox()
-const popup = usePopup(listbox)
-
-// Wire up your custom trigger
-watch(customTrigger.activated, popup.toggle)
-```
-:::
-
-Need press detection with custom behavior that isn't covered by the built-in button? Use the extension directly:
-
-::: canCopy
-```ts
-import { usePress } from '@baleada/vue-features'
-
-const press = usePress(element, {
-  pointer: {
-    minDuration: 500, // Long press
-  },
-})
-```
-:::
 
+// Extend with focus tracking
+const focus = useFocus(listbox)
 
-:::
-## Compose extensions onto interfaces
-:::
-
-Extensions can enhance interfaces after the fact. For example, add focus tracking to a button:
-
-::: canCopy
-```ts
-import { useButton, useFocus } from '@baleada/vue-features'
-
-const button = useButton()
-const focus = useFocus(button.root)
-
-// Now you have both button behavior and focus state
-watch(focus.status, status => {
-  console.log(`Button focus: ${status}`)
-})
-```
-:::
-
-Or add hover detection to a listbox option:
-
-::: canCopy
-```ts
-import { useListbox, useHover } from '@baleada/vue-features'
-
-const listbox = useListbox()
+// Bind a custom class to the root element
+bind(
+  listbox.root.element,
+  { class: 'my-listbox' }
+)
 
-// Track hover on a specific option
-const optionHover = useHover(listbox.options.list.value[0])
+// Add a custom event listener to the root element
+on(
+  listbox.root.element,
+  { keydown: event => console.log('keydown', event.key) }
+)
 ```
 :::
 
-Composability means you're never locked into a single approach. Start with a high-level combo, drop down to interfaces when you need more control, and use extensions and affordances when you need to build something truly custom.
+Baleada Features is a love letter to the Vue 3 Composition API, showcasing the composability it unlocks.