@velkymx/vibeui 1.0.2 → 1.1.0

package/docs/components/advanced/popover.md

@@ -18,7 +18,7 @@ Provide either `text` or `content` (they are interchangeable). Content is always
 
 | Event | Payload | Description |
 |-------|---------|-------------|
-| `component-error` | `{ message, componentName, originalError }` | Emitted if Bootstrap JS is unavailable at mount |
+| `component-error` | `ComponentError` | Emitted if Bootstrap JS is unavailable at mount |
 
 ## Slots
 

package/docs/components/advanced/scrollspy.md

@@ -9,7 +9,7 @@ Automatically update navigation based on scroll position.
 | `target` | `String` | Required | CSS selector of navigation element to update |
 | `rootMargin` | `String` | `'0px 0px -25%'` | Intersection margin for triggering activation. Format: `'top right bottom left'` in CSS units |
 | `offset` | `Number` | `undefined` | **Deprecated.** Use `rootMargin` instead. Ignored in Bootstrap 5.2+. |
-| `method` | `String` | `'auto'` | Scroll detection method: `'auto'`, `'offset'`, or `'position'` |
+| `method` | `String` | `'auto'` | Scroll detection method: `'auto'`, `'offset'`, or `'position'`. Note: `'offset'` is deprecated in Bootstrap 5.2+ (IntersectionObserver-based detection supersedes it); prefer `'auto'` or `'position'`. |
 | `smoothScroll` | `Boolean` | `false` | Enable smooth scrolling |
 | `tag` | `String` | `'div'` | HTML tag to render |
 | `height` | `String` | `'100%'` | CSS height of the scrollable container. Validated as a CSS length; invalid values fall back to `'100%'` |
@@ -19,7 +19,7 @@ Automatically update navigation based on scroll position.
 | Event | Payload | Description |
 |-------|---------|-------------|
 | `activate` | `event` | Emitted when a new nav item is activated |
-| `component-error` | `{ message, componentName, originalError }` | Emitted if Bootstrap JS is unavailable |
+| `component-error` | `ComponentError` | Emitted if Bootstrap JS is unavailable |
 
 ## Slots
 

package/docs/components/advanced/tooltip.md

@@ -17,7 +17,7 @@ Content is always rendered as plain text — HTML is not supported (this is inte
 
 | Event | Payload | Description |
 |-------|---------|-------------|
-| `component-error` | `{ message, componentName, originalError }` | Emitted if Bootstrap JS is unavailable at mount |
+| `component-error` | `ComponentError` | Emitted if Bootstrap JS is unavailable at mount |
 
 ## Slots
 

package/docs/components/core/button.md

@@ -16,12 +16,30 @@ Button component with variants, sizes, and support for links and router-links.
 | `active` | `Boolean` | `false` | Apply active state styling |
 | `focusRing` | `Boolean` | `false` | Enable the Bootstrap 5.3 focus-ring helper |
 
+## Accessibility
+
+**Disabled contrast (WCAG 1.4.3):** The disabled state overrides Bootstrap's default `opacity: 0.65` fade with full-opacity body tokens (`--bs-body-color` / `--bs-tertiary-bg`), keeping label contrast ≥ 4.5:1 in both light and dark mode.
+
+**Icon-only buttons (WCAG 4.1.2):** A button whose slot contains only an icon (no visible text) must have an `aria-label` or `aria-labelledby` attribute so screen readers can announce its purpose. In development mode, VibeButton logs a `console.warn` when this is missing.
+
+```vue
+<!-- correct -->
+<VibeButton aria-label="Delete item">
+  <i class="bi bi-trash" aria-hidden="true" />
+</VibeButton>
+
+<!-- incorrect — no accessible name -->
+<VibeButton>
+  <i class="bi bi-trash" />
+</VibeButton>
+```
+
 ## Events
 
 | Event | Payload | Description |
 |-------|---------|-------------|
 | `click` | `MouseEvent` | Emitted when button is clicked (unless disabled) |
-| `component-error` | `Object` | Emitted when an error occurs |
+| `component-error` | `ComponentError` | Emitted when an error occurs |
 
 ## Slots
 

package/docs/components/core/close-button.md

@@ -15,7 +15,7 @@ Generic close button for dismissing content like modals and alerts.
 | Event | Payload | Description |
 |-------|---------|-------------|
 | `click` | `MouseEvent` | Emitted when button is clicked (unless disabled) |
-| `component-error` | `Object` | Emitted when an error occurs |
+| `component-error` | `ComponentError` | Emitted when an error occurs |
 
 ## Usage
 

package/docs/components/data/datatable.md

@@ -20,7 +20,7 @@ Powerful data table component with search, sorting, and pagination - similar to
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
 | `items` | `T[]` | `[]` | Array of data objects to display |
-| `columns` | `DataTableColumn<T>[]` | Required | Column definitions |
+| `columns` | `DataTableColumn<T>[]` | `[]` | Column definitions. Defaults to an empty array, so an unset/loading state renders an empty table rather than erroring. |
 | `rowKey` | `String` | `'id'` | Property name used as the unique key for each row. **Recommended** — set it to a unique field in your data (e.g. `'id'`, `'uuid'`) so Vue tracks rows correctly across sorting, filtering, and pagination. Falls back to a positional key (with a DEV warning) when missing. |
 
 > **Typing tip**: `DataTableColumn` is generic over your row type. For full slot-prop / formatter typing, annotate the column array:
@@ -56,6 +56,7 @@ Powerful data table component with search, sorting, and pagination - similar to
 | `searchable` | `Boolean` | `true` | Enable search functionality |
 | `sortable` | `Boolean` | `true` | Enable column sorting |
 | `paginated` | `Boolean` | `true` | Enable pagination |
+| `clickable` | `Boolean` | `false` | Show a pointer cursor on rows to signal they are interactive (pair with a `@row-clicked` listener) |
 
 ### Search Props
 
@@ -119,6 +120,7 @@ interface DataTableColumn {
 | `update:sortBy` | `String` | Emitted when sort column changes |
 | `update:sortDesc` | `Boolean` | Emitted when sort direction changes |
 | `row-clicked` | `(item, globalIndex)` | Emitted when a row is clicked. `globalIndex` is the index within the full filtered/sorted dataset, not the current page. Only emitted when a `@row-clicked` listener is attached (rows show a pointer cursor in that case). |
+| `component-error` | `ComponentError` | Emitted if an internal error occurs |
 
 ## Slots
 

package/docs/components/hero/hero.md

@@ -22,6 +22,7 @@ A hero / banner section. Renders a `<section>` with consistent padding, an inner
 | `minHeight` | `String` | `undefined` | Sanitized via `safeLength`; when set, content is vertically centered |
 | `bgImage` | `String` | `undefined` | Full-bleed background image URL; sanitized via `safeHref` (blocks `javascript:`/`data:`), rendered `cover`/`center` |
 | `overlay` | `Boolean \| String` | `false` | Darkening layer over `bgImage` for legibility — `true` for a default dark scrim, or a CSS color (sanitized via `safeColor`) |
+| `overlayOpacity` | `Number` | `0.5` | Opacity of the default dark scrim when `overlay` is `true`; clamped to `[0, 1]`. Ignored when `overlay` is a CSS color string |
 | `gradient` | `String` | `undefined` | CSS gradient background (e.g. `linear-gradient(135deg, #667eea, #764ba2)`); validated to `*-gradient(...)` only — no `url()`/`expression()` |
 | `tag` | `Tag` | `'section'` | Root element tag |
 

package/docs/components/interactive/modal.md

@@ -17,6 +17,8 @@ Modal dialogs for lightboxes, user notifications, or custom content.
 | `hideHeader` | `Boolean` | `false` | Hide header section |
 | `hideFooter` | `Boolean` | `false` | Hide footer section |
 | `teleport` | `Boolean\|String` | `'body'` | Destination for Vue Teleport |
+| `autoFocus` | `Boolean` | `true` | Focus the first focusable descendant when the modal opens (WCAG 2.4.3). |
+| `submitOnMetaEnter` | `Boolean` | `true` | Submit the first `<form>` inside the modal on `Cmd+Enter` / `Ctrl+Enter` (WCAG 2.1.1). |
 
 ## Events
 
@@ -116,8 +118,14 @@ function save() {
 
 **Teleportation:** By default, this component teleports its DOM elements to the `<body>` to avoid stacking context issues. You can customize this with the `teleport` prop.
 
+**Auto-focus (WCAG 2.4.3):** On open, focus moves to the first focusable descendant (input, select, button, etc.). Repeated opens re-focus. Disable with `:auto-focus="false"` when you need to control focus yourself.
+
+**Focus trap (WCAG 2.1.2):** While the modal is open, `Tab` and `Shift+Tab` cycle within the modal only. All sibling elements receive the `inert` attribute so screen readers cannot reach the page behind the modal. `inert` is cleared on close and on unmount.
+
 **Focus Return (WCAG 2.4.3):** When the modal closes, focus is automatically returned to the element that opened it, including for programmatically opened modals.
 
+**Cmd/Ctrl+Enter submit (WCAG 2.1.1):** Pressing `Cmd+Enter` (macOS) or `Ctrl+Enter` (Windows/Linux) inside the modal submits the first `<form>` descendant via `requestSubmit()`. Disable with `:submit-on-meta-enter="false"` for non-form modals.
+
 **Escape Hatch:** The exposed `_unsafe_bsInstance` template ref gives raw access to the underlying Bootstrap Modal instance. It is **not** part of the stable API — calling `dispose()` or other lifecycle methods on it directly **will** break the component. Prefer `v-model` and the exposed `show()` / `hide()` methods.
 
 ## Mobile Optimization

package/docs/components/navigation/navbar.md

@@ -39,6 +39,12 @@ Mobile collapse toggle button.
 | `target` | `String` | Required | The `id` of the `VibeCollapse` to toggle |
 | `ariaLabel` | `String` | `'Toggle navigation'` | Accessible label for the button |
 
+#### Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `component-error` | `ComponentError` | Emitted if the Bootstrap collapse toggle fails (e.g. Bootstrap JS unavailable) |
+
 ### VibeNavbarNav
 Navigation links container. Supports regular links and dropdown items.
 

package/docs/components/navigation/pagination.md

@@ -21,6 +21,7 @@ Data-driven pagination component with v-model support.
 |-------|---------|-------------|
 | `update:currentPage` | `page: number` | Emitted when page changes (v-model) |
 | `page-click` | `page: number` | Emitted when a page is clicked |
+| `component-error` | `ComponentError` | Emitted if an internal error occurs |
 
 ## Slots
 

package/docs/forms/form-error-summary.md

@@ -0,0 +1,96 @@
+# VibeFormErrorSummary
+
+Top-of-form error summary that lists all field errors in one place with links to the offending fields. Satisfies WCAG 3.3.1 (Error Identification) for forms with multiple validation errors.
+
+## Props
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `errors` | `Record<string, string>` | yes | Map of field name → error message. Entries with an empty string are ignored. |
+
+## Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `focus` | `string` | Emitted when the user clicks an error link. Payload is the field key. Use it to programmatically focus the field. |
+
+## Slots
+
+None.
+
+## Usage
+
+### Basic
+
+```vue
+<script setup lang="ts">
+import { reactive } from 'vue'
+
+const errors = reactive<Record<string, string>>({
+  email: '',
+  password: '',
+})
+
+function handleSubmit() {
+  errors.email = ''
+  errors.password = ''
+  if (!form.email) errors.email = 'Email is required.'
+  if (!form.password) errors.password = 'Password must be at least 8 characters.'
+}
+
+function focusField(key: string) {
+  document.getElementById(`field-${key}`)?.focus()
+}
+</script>
+
+<template>
+  <form @submit.prevent="handleSubmit">
+    <VibeFormErrorSummary :errors="errors" @focus="focusField" />
+
+    <VibeFormGroup label="Email" required :validation-state="errors.email ? 'invalid' : null" :validation-message="errors.email">
+      <VibeFormInput id="field-email" v-model="form.email" type="email" autocomplete="email" />
+    </VibeFormGroup>
+
+    <VibeFormGroup label="Password" required :validation-state="errors.password ? 'invalid' : null" :validation-message="errors.password">
+      <VibeFormInput id="field-password" v-model="form.password" type="password" autocomplete="current-password" />
+    </VibeFormGroup>
+
+    <VibeButton type="submit" variant="primary">Sign in</VibeButton>
+  </form>
+</template>
+```
+
+### With useForm
+
+```vue
+<script setup lang="ts">
+import { useForm, validators } from '@velkymx/vibeui'
+
+const { fields, errors, handleSubmit } = useForm({
+  email: { value: '', rules: [validators.required(), validators.email()] },
+  password: { value: '', rules: [validators.required(), validators.minLength(8)] },
+})
+
+function focusField(key: string) {
+  document.getElementById(`field-${key}`)?.focus()
+}
+</script>
+
+<template>
+  <form @submit.prevent="handleSubmit">
+    <VibeFormErrorSummary :errors="errors" @focus="focusField" />
+    <!-- fields … -->
+  </form>
+</template>
+```
+
+## Important Notes
+
+- **Anchor convention:** error links use `href="#field-{key}"`. Set `:id="\`field-${key}\`"` on each input so the links resolve (and so `focusField` can look them up). The component itself does not set these ids — you control the field ids.
+- **`role="alert"` (WCAG 4.1.3):** the container carries `role="alert" aria-live="polite"` so screen readers announce the error list automatically when errors appear, without requiring focus.
+- **Auto-hides when clean:** when all `errors` values are empty strings the summary renders nothing. No need to conditionally mount it.
+- **`@focus` vs native anchor:** the `@click.prevent` on each link suppresses the default scroll-to-anchor jump and lets you implement the focus strategy (e.g. scroll + focus, or open a collapsed section first).
+
+## Bootstrap CSS Classes
+
+- `.alert`, `.alert-danger`

package/docs/forms/form-group.md

@@ -12,7 +12,7 @@ Wrapper that owns a form control's label, help text, validation feedback, and id
 |------|------|---------|-------------|
 | `label` | `string` | `undefined` | Label text rendered for the first child control. |
 | `labelFor` | `string` | `undefined` | Explicit id to use instead of the auto-generated one. |
-| `required` | `boolean` | `false` | Append a `*` to the label. |
+| `required` | `boolean` | `false` | `true` appends a red `*` (aria-hidden) and a visually-hidden "required" span to the label. `false` (default) appends a gray "(optional)" label (aria-hidden). Omit on the child control — the group renders the indicator. |
 | `validationState` | `'valid' \| 'invalid' \| null` | `null` | Render valid/invalid feedback. |
 | `validationMessage` | `string` | `undefined` | Feedback message text. |
 | `helpText` | `string` | `undefined` | Help text rendered below the control. |
@@ -105,6 +105,9 @@ const city = ref('')
 - **Single-consumer rule:** only the first child control consumes the group id. With multiple controls (e.g. a checkbox or radio group), subsequent controls generate their own ids — the group's label still describes the set.
 - **Don't double up:** when the group provides `label`, `helpText`, or validation, omit those same props on the child control; the child suppresses its own copies to avoid duplicates.
 - **Floating labels** require the label to render after the control, which the group handles automatically; pair it with a `placeholder` on the input.
+- **Required/optional indicator (WCAG 3.3.2):** the `required` prop renders both a visual indicator (`*` / "(optional)") and a visually-hidden text node for screen readers. The visual spans carry `aria-hidden="true"` so the screen-reader announcement comes from the hidden span, not the symbol.
+- **`aria-describedby` (WCAG 1.3.1):** `helpText` and `validationMessage` elements are assigned stable ids; the child control's `aria-describedby` is wired automatically — no manual id plumbing needed.
+- **Live error region (WCAG 4.1.3):** the invalid-feedback div carries `role="alert"` so new errors are announced by screen readers without requiring the user to re-focus the field.
 
 ## Bootstrap CSS Classes
 

package/docs/forms/form-input.md

@@ -23,6 +23,10 @@ Single-line text input supporting all standard HTML input types, with built-in v
 | `plaintext` | `boolean` | `false` | Render as read-only plain text (`.form-control-plaintext`). |
 | `noWrapper` | `boolean` | `false` | Render only the `<input>` (no wrapper/label/feedback). Use inside `VibeInputGroup`. |
 | `focusRing` | `boolean` | `false` | Add the Bootstrap 5.3 `.focus-ring` helper. |
+| `showToggle` | `boolean` | `false` | Show a show/hide password toggle button. Only applies when `type="password"`. |
+| `showPasswordStrength` | `boolean` | `false` | Show a 4-segment strength meter and `aria-live` strength label below the input. Only applies when `type="password"`. |
+| `autocomplete` | `AutocompleteType` | auto-detected | HTML `autocomplete` attribute. Auto-detected: `type="email"` → `"email"`. Set `"off"` to disable. |
+| `inputmode` | `InputMode` | auto-detected | Mobile keyboard hint. Auto-detected: `number` → `decimal`, `email` → `email`, `tel` → `tel`, `url` → `url`, `search` → `search`. Override explicitly when needed. |
 
 ## Events
 
@@ -97,11 +101,35 @@ const search = ref('')
 </template>
 ```
 
+### Password field with toggle and strength meter
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+const password = ref('')
+</script>
+
+<template>
+  <VibeFormGroup label="Password" required>
+    <VibeFormInput
+      v-model="password"
+      type="password"
+      autocomplete="new-password"
+      show-toggle
+      show-password-strength
+    />
+  </VibeFormGroup>
+</template>
+```
+
 ## Important Notes
 
 - **Automatic ID & label linking:** when wrapped in a `VibeFormGroup`, the first child control consumes the group id, so the group's `<label>`, help text, and feedback are linked automatically. Do not also set `label`/`helpText` on the input in that case — the group renders them.
 - **Number coercion:** with `type="number"`, an empty field emits `''`; otherwise the emitted value is a `number`.
 - **Plain text:** `plaintext` forces the control read-only.
+- **Placeholder contrast (WCAG 1.4.3):** placeholder text is rendered at full opacity using `--bs-secondary-color`, overriding the browser-default ~0.6 alpha that drops contrast below 3:1.
+- **`autocomplete` auto-detection:** the component sets `autocomplete="email"` automatically for `type="email"` inputs. For password fields, set `autocomplete="current-password"` (login) or `autocomplete="new-password"` (registration) explicitly — the component cannot infer intent from type alone.
+- **`inputmode` auto-detection:** overrides only apply when the prop is not set. Pass an explicit `inputmode` to override (e.g. `inputmode="numeric"` for a 4-digit PIN field that uses `type="text"`).
 
 ## Bootstrap CSS Classes
 

package/llms.txt

@@ -402,17 +402,36 @@ Components like `VibeBreadcrumb`, `VibeListGroup`, `VibeDropdown`, `VibeAccordio
 ]" />
 ```
 
-### VibeFormGroup — automatic label linking
+### VibeFormGroup — automatic label linking and accessibility
 
-`VibeFormGroup` uses Vue's `provide`/`inject` to share a generated ID with child inputs. This means `id` and `label-for` are optional — the group handles accessibility automatically:
+`VibeFormGroup` uses Vue's `provide`/`inject` to share a generated ID with child inputs. `id`, `for`, and `aria-describedby` are all wired automatically — no manual ids needed:
 
 ```vue
-<VibeFormGroup label="Email Address">
+<!-- required prop renders red * + visually-hidden "required" for screen readers -->
+<!-- invalid-feedback has role="alert" — errors announced without focus -->
+<VibeFormGroup label="Email Address" required :validation-state="err ? 'invalid' : null" :validation-message="err">
   <VibeFormInput v-model="email" type="email" />
-  <!-- label is automatically linked to input, no id needed -->
 </VibeFormGroup>
 ```
 
+For multi-field forms, place `<VibeFormErrorSummary :errors="errors" @focus="focusField" />` at the top of the form. It renders a `role="alert"` block listing all non-empty errors with focus links (WCAG 3.3.1).
+
+### VibeFormInput — password, autocomplete, and mobile keyboard
+
+```vue
+<!-- show-toggle: eye button to reveal password -->
+<!-- show-password-strength: 4-segment strength bar with aria-live -->
+<!-- autocomplete: typed enum — "current-password", "new-password", "email", etc. -->
+<!-- inputmode: auto-detected (number→decimal, email→email, tel→tel, url→url, search→search) -->
+<VibeFormInput
+  v-model="password"
+  type="password"
+  autocomplete="new-password"
+  show-toggle
+  show-password-strength
+/>
+```
+
 ### Programmatic control (template ref)
 
 Visibility is normally driven by `v-model` — prefer that. When you must trigger an action imperatively (e.g. open a modal from a non-template handler), interactive components expose **safe methods** via a template ref. Use these, not the underlying Bootstrap object:
@@ -773,7 +792,7 @@ Per-component and per-API reference. **Read the relevant page before building wi
 
 **Progress:** [VibeProgress](docs/components/progress/progress.md)
 
-**Forms:** [overview](docs/forms/README.md) · [VibeAutocomplete](docs/forms/autocomplete.md) · [VibeFileInput](docs/forms/file-input.md) · [VibeFormCheckbox](docs/forms/form-checkbox.md) · [VibeFormDatepicker](docs/forms/form-datepicker.md) · [VibeFormGroup](docs/forms/form-group.md) · [VibeFormInput](docs/forms/form-input.md) · [VibeFormRadio](docs/forms/form-radio.md) · [VibeFormSelect](docs/forms/form-select.md) · [VibeFormSpinbutton](docs/forms/form-spinbutton.md) · [VibeFormSwitch](docs/forms/form-switch.md) · [VibeFormTextarea](docs/forms/form-textarea.md) · [VibeFormWysiwyg](docs/forms/form-wysiwyg.md) · [VibeInputGroup](docs/forms/input-group.md) · [Validation & useForm](docs/forms/validation.md)
+**Forms:** [overview](docs/forms/README.md) · [VibeAutocomplete](docs/forms/autocomplete.md) · [VibeFileInput](docs/forms/file-input.md) · [VibeFormCheckbox](docs/forms/form-checkbox.md) · [VibeFormDatepicker](docs/forms/form-datepicker.md) · [VibeFormErrorSummary](docs/forms/form-error-summary.md) · [VibeFormGroup](docs/forms/form-group.md) · [VibeFormInput](docs/forms/form-input.md) · [VibeFormRadio](docs/forms/form-radio.md) · [VibeFormSelect](docs/forms/form-select.md) · [VibeFormSpinbutton](docs/forms/form-spinbutton.md) · [VibeFormSwitch](docs/forms/form-switch.md) · [VibeFormTextarea](docs/forms/form-textarea.md) · [VibeFormWysiwyg](docs/forms/form-wysiwyg.md) · [VibeInputGroup](docs/forms/input-group.md) · [Validation & useForm](docs/forms/validation.md)
 
 **Composables:** [useBackButton](docs/composables/back-button.md) · [useBreakpoints](docs/composables/breakpoints.md) · [useColorMode](docs/composables/color-mode.md) · [useForm](docs/composables/use-form.md) · [usePosition](docs/composables/use-position.md) · [useToast](docs/composables/use-toast.md)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@velkymx/vibeui",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "description": "A lightweight Vue 3 component library for Bootstrap 5.3 with dual-mode support (shorthand props and composable slots)",
   "main": "./dist/vibeui.umd.js",
   "module": "./dist/vibeui.es.js",