@compa11y/web 0.1.0 → 0.1.3

package/README.md

@@ -150,6 +150,508 @@ tabs.addEventListener('a11y-tabs-change', (e) => {
 });
 ```
 
+### Combobox
+
+```html
+<a11y-combobox
+  label="Choose a country"
+  placeholder="Search countries..."
+></a11y-combobox>
+
+<script>
+  const combobox = document.querySelector('a11y-combobox');
+  combobox.options = [
+    { value: 'us', label: 'United States' },
+    { value: 'uk', label: 'United Kingdom' },
+    { value: 'ca', label: 'Canada' },
+  ];
+
+  combobox.addEventListener('change', (e) => {
+    console.log('Selected:', e.detail.value);
+  });
+</script>
+```
+
+#### Attributes
+
+| Attribute       | Description                           | Default              |
+| --------------- | ------------------------------------- | -------------------- |
+| `label`         | Label text (required for a11y)        | —                    |
+| `placeholder`   | Input placeholder                     | —                    |
+| `value`         | Currently selected value              | —                    |
+| `disabled`      | Disable the combobox                  | `false`              |
+| `clearable`     | Show clear button when value selected | `false`              |
+| `empty-message` | Message when no options match         | `'No results found'` |
+
+#### Properties
+
+```js
+const combobox = document.querySelector('a11y-combobox');
+combobox.options = [...]; // Set options
+combobox.value = 'us'; // Set value
+```
+
+#### Events
+
+```js
+combobox.addEventListener('change', (e) => {
+  console.log(e.detail.value, e.detail.option);
+});
+```
+
+### Select
+
+```html
+<a11y-select aria-label="Choose a fruit" placeholder="Pick a fruit...">
+  <option value="apple">Apple</option>
+  <option value="banana">Banana</option>
+  <option value="cherry">Cherry</option>
+  <option value="dragonfruit" disabled>Dragon Fruit (unavailable)</option>
+  <option value="elderberry">Elderberry</option>
+</a11y-select>
+```
+
+#### Attributes
+
+| Attribute         | Description              | Default                 |
+| ----------------- | ------------------------ | ----------------------- |
+| `placeholder`     | Trigger placeholder text | `'Select an option...'` |
+| `value`           | Currently selected value | —                       |
+| `disabled`        | Disable the select       | `false`                 |
+| `aria-label`      | Accessible label         | —                       |
+| `aria-labelledby` | ID of labelling element  | —                       |
+
+#### Properties
+
+```js
+const select = document.querySelector('a11y-select');
+select.value = 'apple'; // Set value programmatically
+```
+
+#### Methods
+
+```js
+const select = document.querySelector('a11y-select');
+select.show(); // Open
+select.close(); // Close
+```
+
+#### Events
+
+```js
+select.addEventListener('change', (e) => {
+  console.log('Value:', e.detail.value);
+  console.log('Label:', e.detail.label);
+});
+
+select.addEventListener('a11y-select-change', (e) => {
+  console.log('Selected:', e.detail);
+});
+
+select.addEventListener('a11y-select-open', () => {});
+select.addEventListener('a11y-select-close', () => {});
+```
+
+#### Keyboard Navigation
+
+| Key               | Action                                    |
+| ----------------- | ----------------------------------------- |
+| `Enter` / `Space` | Open listbox or select highlighted option |
+| `ArrowDown`       | Open listbox / move highlight down        |
+| `ArrowUp`         | Open listbox / move highlight up          |
+| `Home` / `End`    | Jump to first / last option               |
+| `Escape`          | Close listbox                             |
+| `Tab`             | Close listbox and move focus              |
+| Type characters   | Jump to matching option (type-ahead)      |
+
+### Switch
+
+```html
+<a11y-switch label="Enable notifications"></a11y-switch>
+
+<!-- Checked by default -->
+<a11y-switch checked label="Dark mode"></a11y-switch>
+
+<!-- Disabled -->
+<a11y-switch disabled label="Premium feature"></a11y-switch>
+```
+
+#### Attributes
+
+| Attribute  | Description               | Default |
+| ---------- | ------------------------- | ------- |
+| `label`    | Label text                | —       |
+| `checked`  | Whether switch is on      | `false` |
+| `disabled` | Disable the switch        | `false` |
+| `value`    | Value for form submission | —       |
+| `name`     | Name for form submission  | —       |
+
+#### Properties
+
+```js
+const switchEl = document.querySelector('a11y-switch');
+switchEl.checked = true; // Set checked state
+```
+
+#### Events
+
+```js
+switchEl.addEventListener('change', (e) => {
+  console.log('Checked:', e.detail.checked);
+  console.log('Value:', e.detail.value);
+  console.log('Name:', e.detail.name);
+});
+```
+
+### Listbox
+
+```html
+<!-- Single select -->
+<a11y-listbox aria-label="Favorite fruit" value="apple">
+  <a11y-optgroup label="Citrus">
+    <a11y-option value="orange">Orange</a11y-option>
+    <a11y-option value="lemon">Lemon</a11y-option>
+    <a11y-option value="grapefruit">Grapefruit</a11y-option>
+  </a11y-optgroup>
+  <a11y-optgroup label="Berries">
+    <a11y-option value="strawberry">Strawberry</a11y-option>
+    <a11y-option value="blueberry">Blueberry</a11y-option>
+    <a11y-option value="raspberry" disabled>Raspberry (sold out)</a11y-option>
+  </a11y-optgroup>
+  <a11y-option value="apple">Apple</a11y-option>
+  <a11y-option value="banana">Banana</a11y-option>
+</a11y-listbox>
+
+<!-- Multi select -->
+<a11y-listbox multiple aria-label="Pizza toppings" value="cheese,mushrooms">
+  <a11y-option value="cheese">Cheese</a11y-option>
+  <a11y-option value="pepperoni">Pepperoni</a11y-option>
+  <a11y-option value="mushrooms">Mushrooms</a11y-option>
+  <a11y-option value="onions">Onions</a11y-option>
+  <a11y-option value="pineapple" disabled>Pineapple (unavailable)</a11y-option>
+</a11y-listbox>
+```
+
+#### Listbox Attributes
+
+| Attribute         | Description                                   | Default    |
+| ----------------- | --------------------------------------------- | ---------- |
+| `value`           | Selected value(s) (comma-separated for multi) | —          |
+| `multiple`        | Enable multi-select mode                      | `false`    |
+| `disabled`        | Disable all options                           | `false`    |
+| `discoverable`    | Keep disabled listbox in tab order            | `true`     |
+| `orientation`     | `horizontal` or `vertical`                    | `vertical` |
+| `aria-label`      | Accessible label                              | —          |
+| `aria-labelledby` | ID of labelling element                       | —          |
+
+#### Option Attributes
+
+| Attribute      | Description                       | Default |
+| -------------- | --------------------------------- | ------- |
+| `value`        | Value for this option             | —       |
+| `disabled`     | Disable this option               | `false` |
+| `discoverable` | Keep disabled option in tab order | `true`  |
+
+#### Optgroup Attributes
+
+| Attribute  | Description                     | Default |
+| ---------- | ------------------------------- | ------- |
+| `label`    | Group label (visible, required) | —       |
+| `disabled` | Disable all options in group    | `false` |
+
+#### Properties
+
+```js
+const listbox = document.querySelector('a11y-listbox');
+listbox.value = 'apple'; // Set selected value (single)
+listbox.value = 'cheese,onions'; // Set selected values (multi, comma-separated)
+listbox.multiple = true; // Toggle multi-select mode
+listbox.disabled = true; // Disable all options
+```
+
+#### Events
+
+```js
+listbox.addEventListener('change', (e) => {
+  console.log('Value:', e.detail.value);
+  console.log('Label:', e.detail.label);
+});
+
+listbox.addEventListener('a11y-listbox-change', (e) => {
+  console.log('Selected:', e.detail);
+});
+```
+
+#### Keyboard Navigation
+
+| Key                     | Single Select                      | Multi Select                    |
+| ----------------------- | ---------------------------------- | ------------------------------- |
+| `ArrowDown` / `ArrowUp` | Move focus and select              | Move focus only                 |
+| `Home` / `End`          | First/last option and select       | Move focus only                 |
+| `Space`                 | —                                  | Toggle focused option           |
+| `Shift+ArrowDown/Up`    | —                                  | Move focus and toggle selection |
+| `Ctrl+Shift+Home/End`   | —                                  | Select range to first/last      |
+| `Ctrl+A` / `Cmd+A`      | —                                  | Toggle select all               |
+| Type characters         | Jump to matching option and select | Jump to matching option         |
+
+#### CSS Custom Properties
+
+```css
+a11y-listbox {
+  --compa11y-listbox-bg: white;
+  --compa11y-listbox-border: 1px solid #ccc;
+  --compa11y-listbox-radius: 6px;
+  --compa11y-listbox-max-height: 300px;
+  --compa11y-listbox-padding: 4px;
+}
+
+a11y-option {
+  --compa11y-option-padding: 0.5rem 0.75rem;
+  --compa11y-option-radius: 4px;
+  --compa11y-option-hover-bg: #f5f5f5;
+  --compa11y-option-focused-bg: #e6f0ff;
+  --compa11y-option-focused-border: #0066cc;
+  --compa11y-option-selected-bg: #e6f0ff;
+  --compa11y-option-selected-color: #0066cc;
+  --compa11y-option-check-color: #0066cc;
+  --compa11y-option-disabled-color: #999;
+  --compa11y-option-disabled-bg: transparent;
+  --compa11y-focus-color: #0066cc;
+}
+```
+
+### Input
+
+```html
+<a11y-input
+  label="Full Name"
+  hint="Enter your first and last name"
+  required
+  placeholder="John Doe"
+  type="text"
+></a11y-input>
+
+<!-- With error -->
+<a11y-input
+  label="Email"
+  error="Please enter a valid email"
+  type="email"
+></a11y-input>
+
+<!-- Read-only -->
+<a11y-input label="User ID" value="USR-12345" readonly></a11y-input>
+
+<!-- Disabled -->
+<a11y-input label="Organization" value="Compa11y Inc." disabled></a11y-input>
+```
+
+#### Attributes
+
+| Attribute         | Description              | Default  |
+| ----------------- | ------------------------ | -------- |
+| `label`           | Visible label text       | —        |
+| `hint`            | Hint/description text    | —        |
+| `error`           | Error message text       | —        |
+| `type`            | Input type               | `'text'` |
+| `placeholder`     | Placeholder text         | —        |
+| `value`           | Current value            | —        |
+| `disabled`        | Disable the input        | `false`  |
+| `readonly`        | Read-only input          | `false`  |
+| `required`        | Required field           | `false`  |
+| `name`            | Name for form submission | —        |
+| `aria-label`      | Accessible label         | —        |
+| `aria-labelledby` | ID of labelling element  | —        |
+
+#### Properties
+
+```js
+const input = document.querySelector('a11y-input');
+input.value = 'Hello'; // Set value
+input.error = 'Required'; // Set error (shows role="alert")
+input.error = ''; // Clear error
+input.disabled = true; // Disable
+```
+
+#### Methods
+
+```js
+const input = document.querySelector('a11y-input');
+input.focus(); // Focus the input
+input.blur(); // Blur the input
+input.select(); // Select all text
+```
+
+#### Events
+
+```js
+input.addEventListener('input', (e) => {
+  console.log('Value:', e.detail.value);
+});
+
+input.addEventListener('change', (e) => {
+  console.log('Final value:', e.detail.value);
+});
+
+input.addEventListener('a11y-input-focus', () => {});
+input.addEventListener('a11y-input-blur', () => {});
+```
+
+### Textarea
+
+```html
+<a11y-textarea
+  label="Description"
+  hint="Provide at least 10 characters"
+  required
+  rows="4"
+  placeholder="Enter a description..."
+></a11y-textarea>
+
+<!-- With error -->
+<a11y-textarea label="Bio" error="Bio is required" rows="5"></a11y-textarea>
+
+<!-- Read-only -->
+<a11y-textarea
+  label="Terms"
+  value="Read only content..."
+  readonly
+  rows="3"
+></a11y-textarea>
+
+<!-- Disabled -->
+<a11y-textarea
+  label="Notes"
+  value="Disabled content"
+  disabled
+  rows="2"
+></a11y-textarea>
+```
+
+#### Attributes
+
+| Attribute         | Description              | Default      |
+| ----------------- | ------------------------ | ------------ |
+| `label`           | Visible label text       | —            |
+| `hint`            | Hint/description text    | —            |
+| `error`           | Error message text       | —            |
+| `rows`            | Number of visible rows   | `3`          |
+| `resize`          | Resize behavior          | `'vertical'` |
+| `placeholder`     | Placeholder text         | —            |
+| `value`           | Current value            | —            |
+| `disabled`        | Disable the textarea     | `false`      |
+| `readonly`        | Read-only textarea       | `false`      |
+| `required`        | Required field           | `false`      |
+| `name`            | Name for form submission | —            |
+| `aria-label`      | Accessible label         | —            |
+| `aria-labelledby` | ID of labelling element  | —            |
+
+#### Properties
+
+```js
+const textarea = document.querySelector('a11y-textarea');
+textarea.value = 'Hello'; // Set value
+textarea.error = 'Required'; // Set error (shows role="alert")
+textarea.error = ''; // Clear error
+textarea.disabled = true; // Disable
+```
+
+#### Methods
+
+```js
+const textarea = document.querySelector('a11y-textarea');
+textarea.focus(); // Focus the textarea
+textarea.blur(); // Blur the textarea
+textarea.select(); // Select all text
+```
+
+#### Events
+
+```js
+textarea.addEventListener('input', (e) => {
+  console.log('Value:', e.detail.value);
+});
+
+textarea.addEventListener('change', (e) => {
+  console.log('Final value:', e.detail.value);
+});
+
+textarea.addEventListener('a11y-textarea-focus', () => {});
+textarea.addEventListener('a11y-textarea-blur', () => {});
+```
+
+### Button
+
+```html
+<a11y-button variant="primary">Save</a11y-button>
+<a11y-button variant="danger">Delete</a11y-button>
+<a11y-button variant="outline">Cancel</a11y-button>
+
+<!-- Loading state -->
+<a11y-button variant="primary" loading>Saving...</a11y-button>
+
+<!-- Disabled but discoverable (stays in tab order) -->
+<a11y-button variant="primary" disabled discoverable>Unavailable</a11y-button>
+
+<!-- Sizes -->
+<a11y-button variant="primary" size="sm">Small</a11y-button>
+<a11y-button variant="primary" size="md">Medium</a11y-button>
+<a11y-button variant="primary" size="lg">Large</a11y-button>
+```
+
+#### Attributes
+
+| Attribute      | Description                                                 | Default       |
+| -------------- | ----------------------------------------------------------- | ------------- |
+| `variant`      | Visual variant (primary, secondary, danger, outline, ghost) | `'secondary'` |
+| `size`         | Size (sm, md, lg)                                           | `'md'`        |
+| `type`         | Button type (button, submit, reset)                         | `'button'`    |
+| `disabled`     | Disable the button                                          | `false`       |
+| `discoverable` | Keep disabled button in tab order                           | `false`       |
+| `loading`      | Loading state (shows spinner, aria-busy)                    | `false`       |
+| `aria-label`   | Accessible label                                            | —             |
+
+#### Properties
+
+```js
+const btn = document.querySelector('a11y-button');
+btn.disabled = true; // Disable
+btn.loading = true; // Set loading
+btn.variant = 'danger'; // Change variant
+btn.size = 'lg'; // Change size
+```
+
+#### Methods
+
+```js
+const btn = document.querySelector('a11y-button');
+btn.focus(); // Focus the button
+btn.blur(); // Blur the button
+btn.click(); // Programmatic click
+```
+
+#### Events
+
+```js
+btn.addEventListener('a11y-button-click', () => {
+  console.log('Button clicked');
+});
+```
+
+#### CSS Custom Properties
+
+```css
+a11y-button {
+  --compa11y-button-radius: 4px;
+  --compa11y-button-font-weight: 500;
+  --compa11y-button-disabled-opacity: 0.5;
+  --compa11y-button-primary-bg: #0066cc;
+  --compa11y-button-primary-color: white;
+  --compa11y-button-danger-bg: #ef4444;
+  --compa11y-button-danger-color: white;
+  --compa11y-focus-color: #0066cc;
+}
+```
+
 ## Styling
 
 Use CSS custom properties for theming:
@@ -182,6 +684,112 @@ a11y-tabs {
   --compa11y-tab-active-color: #0066cc;
 }
 
+/* Combobox */
+a11y-combobox {
+  --compa11y-combobox-width: 300px;
+  --compa11y-combobox-border: 1px solid #ccc;
+  --compa11y-combobox-radius: 4px;
+  --compa11y-combobox-option-hover-bg: #f5f5f5;
+  --compa11y-combobox-option-selected-bg: #e6f0ff;
+}
+
+/* Select */
+a11y-select {
+  --compa11y-select-width: 300px;
+  --compa11y-select-border: 1px solid #ccc;
+  --compa11y-select-radius: 4px;
+  --compa11y-select-bg: white;
+  --compa11y-select-placeholder-color: #999;
+  --compa11y-select-chevron-color: #666;
+  --compa11y-select-option-hover-bg: #f5f5f5;
+  --compa11y-select-option-selected-bg: #e6f0ff;
+  --compa11y-select-check-color: #0066cc;
+  --compa11y-select-shadow: 0 4px 6px rgba(0, 0, 0, 0.1);
+}
+
+/* Switch */
+a11y-switch {
+  --compa11y-switch-bg: #d1d5db;
+  --compa11y-switch-checked-bg: #0066cc;
+  --compa11y-switch-thumb-bg: white;
+  --compa11y-switch-width: 2.75rem;
+  --compa11y-switch-height: 1.5rem;
+  --compa11y-switch-thumb-shadow: 0 1px 3px rgba(0, 0, 0, 0.2);
+}
+
+/* Input */
+a11y-input {
+  --compa11y-input-border: 1px solid #ccc;
+  --compa11y-input-border-focus: #0066cc;
+  --compa11y-input-border-error: #ef4444;
+  --compa11y-input-bg: white;
+  --compa11y-input-radius: 4px;
+  --compa11y-input-padding: 0.5rem 0.75rem;
+  --compa11y-input-font-size: 0.875rem;
+  --compa11y-input-label-color: inherit;
+  --compa11y-input-label-size: 0.875rem;
+  --compa11y-input-label-weight: 500;
+  --compa11y-input-hint-color: #666;
+  --compa11y-input-hint-size: 0.8125rem;
+  --compa11y-input-error-color: #ef4444;
+  --compa11y-input-error-size: 0.8125rem;
+  --compa11y-input-required-color: #ef4444;
+  --compa11y-input-disabled-bg: #f5f5f5;
+  --compa11y-input-placeholder-color: #999;
+}
+
+/* Textarea */
+a11y-textarea {
+  --compa11y-textarea-border: 1px solid #ccc;
+  --compa11y-textarea-border-focus: #0066cc;
+  --compa11y-textarea-border-error: #ef4444;
+  --compa11y-textarea-bg: white;
+  --compa11y-textarea-radius: 4px;
+  --compa11y-textarea-padding: 0.5rem 0.75rem;
+  --compa11y-textarea-font-size: 0.875rem;
+  --compa11y-textarea-resize: vertical;
+  --compa11y-textarea-label-color: inherit;
+  --compa11y-textarea-label-size: 0.875rem;
+  --compa11y-textarea-label-weight: 500;
+  --compa11y-textarea-hint-color: #666;
+  --compa11y-textarea-hint-size: 0.8125rem;
+  --compa11y-textarea-error-color: #ef4444;
+  --compa11y-textarea-error-size: 0.8125rem;
+  --compa11y-textarea-required-color: #ef4444;
+  --compa11y-textarea-disabled-bg: #f5f5f5;
+  --compa11y-textarea-placeholder-color: #999;
+}
+
+/* Button */
+a11y-button {
+  --compa11y-button-radius: 4px;
+  --compa11y-button-font-weight: 500;
+  --compa11y-button-disabled-opacity: 0.5;
+  --compa11y-button-primary-bg: #0066cc;
+  --compa11y-button-primary-color: white;
+  --compa11y-button-danger-bg: #ef4444;
+  --compa11y-button-danger-color: white;
+}
+
+/* Listbox */
+a11y-listbox {
+  --compa11y-listbox-bg: white;
+  --compa11y-listbox-border: 1px solid #ccc;
+  --compa11y-listbox-radius: 6px;
+  --compa11y-listbox-max-height: 300px;
+  --compa11y-listbox-padding: 4px;
+}
+
+a11y-option {
+  --compa11y-option-padding: 0.5rem 0.75rem;
+  --compa11y-option-radius: 4px;
+  --compa11y-option-hover-bg: #f5f5f5;
+  --compa11y-option-focused-bg: #e6f0ff;
+  --compa11y-option-selected-bg: #e6f0ff;
+  --compa11y-option-check-color: #0066cc;
+  --compa11y-option-disabled-color: #999;
+}
+
 /* Focus ring */
 :root {
   --compa11y-focus-color: #0066cc;