@vibe/core 4.2.6 → 4.3.0

package/dist/metadata/accessibility/Accordion.md

@@ -0,0 +1,10 @@
+# Accordion - Accessibility Requirements
+
+1. Provide an `id` for the Accordion to enable proper accessibility associations and unique
+      identification.
+2. Provide unique `id` props for each AccordionItem to ensure proper ARIA relationships between buttons
+      and their controlled content regions.
+3. Use descriptive `title` props for AccordionItem headers that clearly indicate what content will be
+      revealed when expanded.
+4. Use the `defaultIndex` prop to set initial expanded states appropriately. Avoid auto-expanding too many
+      items to prevent overwhelming screen reader users.

package/dist/metadata/accessibility/AlertBanner.md

@@ -0,0 +1,9 @@
+# AlertBanner - Accessibility Requirements
+
+1. Use the `ariaLabel` prop to provide a descriptive accessible name for the banner that clearly indicates
+      the type and purpose of the alert.
+2. For dismissible AlertBanners, use the `closeButtonAriaLabel` prop to provide a descriptive accessible
+      name for the close button.
+3. When the banner text should be announced by screen readers (e.g., for dynamic updates), set the{" "}
+      `ariaLive` prop on AlertBannerText to control the live region behavior ("polite", "assertive", or
+      "off"). By default, AlertBannerText does not set a live region.

package/dist/metadata/accessibility/Avatar.md

@@ -0,0 +1,12 @@
+# Avatar - Accessibility Requirements
+
+1. Always provide an `ariaLabel` prop to describe the person or entity represented by the avatar (e.g.,
+      "John Smith", "Design Team", "Guest User"). This label is automatically used as tooltip content.
+2. Use the `role` prop when the avatar represents something other than a person (e.g.,{" "}
+      `role="img"` for team avatars, `role="button"` for clickable workspace avatars).
+3. For clickable avatars, ensure the `ariaLabel` describes the action that will occur when clicked (e.g.,
+      "Open John Smith's profile", "View Design Team details").
+4. Use `ariaHidden` prop appropriately when the avatar is purely decorative and provides no meaningful
+      information to screen readers.
+5. For avatars with badges (status indicators), ensure the `ariaLabel` includes relevant status
+      information (e.g., "John Smith (Away)", "Design Team (3 members online)").

package/dist/metadata/accessibility/AvatarGroup.md

@@ -0,0 +1,6 @@
+# AvatarGroup - Accessibility Requirements
+
+1. Use the `counterAriaLabel` prop to provide a descriptive accessible name for the counter (e.g., "3
+      additional team members", "5 more participants", "2 hidden collaborators").
+2. Ensure each `Avatar` in the group has a meaningful `ariaLabel` prop that describes the
+      person or entity (e.g., "John Smith", "Sarah Johnson", "Design Team").

package/dist/metadata/accessibility/BreadcrumbsBar.md

@@ -0,0 +1,10 @@
+# BreadcrumbsBar - Accessibility Requirements
+
+1. Use the `type="navigation"` prop when breadcrumbs are clickable for navigation. This automatically
+      enables keyboard navigation and proper button/link semantics.
+2. For clickable breadcrumbs, ensure all items have descriptive `text` props that clearly indicate what
+      section or page they represent.
+3. When using icons in breadcrumbs, ensure they are purely decorative and don't replace the descriptive text, as
+      screen readers will announce the text content.
+4. Use the `isCurrent` prop on BreadcrumbItem to mark the current page. This ensures screen readers
+      understand the user's current location in the navigation hierarchy.

package/dist/metadata/accessibility/Button.md

@@ -0,0 +1,13 @@
+# Button - Accessibility Requirements
+
+1. Using an `id` is recommended for all instances to ensure proper label association.
+2. Always provide descriptive text content for buttons, or use `ariaLabel` prop when buttons contain only
+      icons.
+3. Use `ariaLabel` prop when you need to provide a custom accessible name that differs from the visible
+      button text or for icon-only buttons.
+4. Use `ariaLabeledBy` prop when an external element provides the accessible name for the button.
+5. Use `ariaHasPopup` prop when the button triggers a popup menu or dialog.
+6. Use `ariaExpanded` prop to indicate when a popup triggered by the button is open or closed.
+7. Use `ariaControls` prop to link the button to the element it controls.
+8. Use `aria-describedby` prop when additional descriptive text is needed for the button.
+9. Use `aria-pressed` prop for toggle buttons to indicate their current pressed state.

package/dist/metadata/accessibility/ButtonGroup.md

@@ -0,0 +1,9 @@
+# ButtonGroup - Accessibility Requirements
+
+1. Always provide a `groupAriaLabel` prop to describe the purpose of the button group. This provides
+      context for screen readers about what the group represents (e.g., "View options", "Sort options", "Display
+      settings").
+2. For individual buttons, ensure each option has clear, descriptive `text` content, or provide
+      `ariaLabel` in the options array for icon-only buttons.
+3. Use `ariaLabel` in the options array when you need a different accessible name than the visible button
+      text, or for icon-only buttons (e.g., `ariaLabel: "Grid view"`).

package/dist/metadata/accessibility/Checkbox.md

@@ -0,0 +1,13 @@
+# Checkbox - Accessibility Requirements
+
+1. Using an `id` is highly recommended for all instances to ensure proper label association.
+2. Always provide a visible `label` prop to ensure the checkbox's purpose is clear to all users.
+3. It is recommended to use `separateLabel` mode for better screen reader support as it provides clearer,
+      more explicit label-input associations. When using this mode, the `id` prop is required for proper
+      label association.
+4. Use `ariaLabel` prop when you need to provide a custom accessible name.
+5. Use `ariaLabelledBy` prop when the checkbox is described by external elements.
+6. Use `indeterminate` prop for mixed selection states (e.g., when some but not all sub-items are
+      selected).
+7. Use `tabIndex` prop for custom keyboard navigation order.
+8. Use `autoFocus` prop when the checkbox should receive initial focus for keyboard navigation.

package/dist/metadata/accessibility/Chips.md

@@ -0,0 +1,10 @@
+# Chips - Accessibility Requirements
+
+1. Provide an `id` for the Chips to enable proper accessibility associations and unique identification.
+2. For removable chips, use the `closeButtonAriaLabel` prop to provide a descriptive accessible name for
+      the remove button (defaults to "Remove", but should be more specific like "Remove John Smith" or "Delete tag").
+3. Use the `ariaLabel` prop when the visible `label` text alone doesn't provide enough context
+      for screen readers to understand the chip's purpose or when chips contain complex content.
+4. For clickable chips, ensure the `ariaLabel` describes the action that will occur when clicked.
+5. When using icons or avatars in chips, ensure they are purely decorative and don't replace the descriptive text.
+      Screen readers will announce the text content, and icons should be hidden from assistive technologies.

package/dist/metadata/accessibility/Combobox.md

@@ -0,0 +1,6 @@
+# Combobox - Accessibility Requirements
+
+1. Using an `id` is highly recommended for all instances to ensure proper label association.
+2. Use `searchInputAriaLabel` prop when you need to provide a custom accessible name for the search input.
+3. Use `disabled` prop appropriately to indicate when the combobox is not available for interaction.
+4. Use `autoFocus` prop when the combobox should receive initial focus for keyboard navigation.

package/dist/metadata/accessibility/DropdownBasicDropdown.md

@@ -0,0 +1,10 @@
+# DropdownBasicDropdown - Accessibility Requirements
+
+1. Using an `id` is highly recommended for all instances to ensure proper label association.
+2. Always provide a `label` prop to ensure the dropdown's purpose is clear to all users.
+3. Use `ariaLabel` prop when you need to provide a custom accessible name for the dropdown.
+4. Use `clearAriaLabel` prop when dropdown is clearable.
+5. Use `inputAriaLabel` prop when you need to provide a specific accessible name for the input field in
+      searchable dropdowns.
+6. Use `menuAriaLabel` prop when you need to provide a custom accessible name for the dropdown menu.
+7. Use `autoFocus` prop when the dropdown should receive initial focus for keyboard navigation.

package/dist/metadata/accessibility/IconButton.md

@@ -0,0 +1,26 @@
+# IconButton - Accessibility Requirements
+
+1. Provide an `id` for the IconButton to enable proper accessibility associations and unique
+      identification.
+2. Always provide an accessible name using either `ariaLabel` prop or `tooltipContent` prop.
+      The component automatically uses `tooltipContent` as the accessible name if no `ariaLabel`{" "}
+      is provided.
+3. Use `ariaLabel` prop when you need a different accessible name than the tooltip text, or when the icon
+      button doesn't have a tooltip.
+4. Use `ariaLabeledBy` prop when an external element provides the accessible name for the icon button.
+      Pass the `id` of that external element.
+5. Use `ariaHasPopup` prop when the icon button opens a menu, dialog, or popup.
+6. Use `ariaExpanded` prop to indicate when a popup or menu opened by the icon button is currently open (
+      `true`) or closed (`false`).
+7. Use `ariaControls` prop to link the icon button to the element it controls. Pass the `id` of
+      the controlled element.
+8. Use `aria-describedby` prop to link the icon button to additional descriptive text. Pass the{" "}
+      `id` of the descriptive element.
+9. Use `aria-pressed` prop for toggle icon buttons to indicate their current pressed state (
+      `true`, `false`, or `mixed`).
+10. Use `aria-hidden` prop appropriately to hide the icon button from screen readers when necessary, but
+      use sparingly as it removes the button from the accessibility tree entirely.
+11. Use `tabIndex` prop to control the icon button's position in the keyboard navigation order. The default
+      value allows normal tab navigation.
+12. Provide `disabledReason` prop when disabling an icon button to give users context about why the button
+      is unavailable. This will be displayed in the tooltip.

package/dist/metadata/accessibility/Info.md

@@ -0,0 +1,12 @@
+# Info - Accessibility Requirements
+
+1. Provide an `id` for the Info component to enable proper accessibility associations and unique
+      identification.
+2. You should provide an accessible name using the `aria-label` prop to describe the purpose of the info
+      button (e.g., "More information about this feature").
+3. Use `aria-labelledby` prop when an external element provides the accessible name for the info button.
+      Pass the `id` of that external element (instead of using `aria-label`).
+4. The component automatically manages `aria-controls`, `aria-haspopup="dialog"`, and{" "}
+      `aria-expanded` attributes to indicate the relationship with the dialog and its current state.
+5. Focus management is handled automatically - when the dialog opens, focus moves to the content, and when closed
+      with Escape, focus returns to the info button.

package/dist/metadata/accessibility/Link.md

@@ -0,0 +1,8 @@
+# Link - Accessibility Requirements
+
+1. Use the `ariaLabelDescription` prop when the link text alone doesn't provide enough context for screen
+      readers to understand the link's purpose.
+2. Use `ariaDescribedby` prop to link the link to additional descriptive text that provides more context
+      about the link's destination or action.
+3. Use `ariaLabeledBy` prop when an external element provides the accessible name for the link. Pass the{" "}
+      `id` of that external element.

package/dist/metadata/accessibility/List.md

@@ -0,0 +1,11 @@
+# List - Accessibility Requirements
+
+1. Always provide an `ariaLabel` prop to give the list a meaningful accessible name that describes its
+      purpose (e.g., "Navigation menu", "Settings options").
+2. The List component provides comprehensive keyboard navigation: <strong>Arrow Up/Down</strong> to navigate between
+      items (wraps around), <strong>Home/End</strong> to jump to first/last item, <strong>PageUp/PageDown</strong> to
+      move by 10 items, and <strong>Enter/Space</strong> to activate the focused item.
+3. Use `defaultFocusIndex` to set which item should receive focus when the list first becomes focused.
+4. Use `onFocusChange` callback to track focus changes for custom focus management scenarios.
+5. Ensure individual `ListItem` components have descriptive `label` text. For items with only
+      icons, provide additional context through the label.

package/dist/metadata/accessibility/Menu.md

@@ -0,0 +1,10 @@
+# Menu - Accessibility Requirements
+
+1. Provide an `id` for the Menu to enable proper accessibility associations and unique identification.
+2. Use the `ariaLabel` prop to provide a meaningful accessible name for the menu that describes its
+      purpose (e.g., "Navigation menu", "Actions menu", "Options menu").
+3. Use the `ariaDescribedBy` prop to link the menu to additional descriptive text by providing the{" "}
+      `id` of the descriptive element.
+4. It is recommended to use `focusItemIndexOnMount={0}` to focus the first menu item when the menu opens.
+5. Ensure menu items have clear, descriptive text or use appropriate `ariaLabel` props on individual menu
+      items for icon-only items.

package/dist/metadata/accessibility/MenuButton.md

@@ -0,0 +1,6 @@
+# MenuButton - Accessibility Requirements
+
+1. Provide an `id` for the MenuButton to enable proper accessibility associations.
+2. Use descriptive `ariaLabel` values for MenuButtons that clearly indicate the menu's purpose.
+3. Use `ariaControls` prop to link the MenuButton to its menu content. Pass the `id` of the
+      menu element to establish the relationship between the button and its controlled menu.

package/dist/metadata/accessibility/MenuItem.md

@@ -0,0 +1,8 @@
+# MenuItem - Accessibility Requirements
+
+1. Use the `aria-label` prop when you need to provide a custom accessible name that differs from the
+      visible title text, especially for icon-only menu items.
+2. For menu items with submenus, ensure the submenu content is properly structured with descriptive menu item titles
+      for clear navigation hierarchy.
+3. Use the `disabled` prop appropriately with a `disableReason` to provide context for why a
+      menu item cannot be selected.

package/dist/metadata/accessibility/Modal.md

@@ -0,0 +1,35 @@
+# Modal - Accessibility Requirements
+
+1. ",
+    </span>,
+    <span>
+      <b>Focus lock:</b> Keeps focus within the modal elements, preventing users from tabbing outside of the modal while
+      it is open. Focus also automatically returns to the last focused element upon closing.
+    </span>,
+    <span>
+      <b>Aria attributes:</b> For better screen reader support, using `ModalHeader` - with simple string
+      values for `title` and `description` props - automatically sets the necessary{"
+2. "}
+      `aria-labelledby` and `aria-describedby` attributes on the modal.
+    </span>,
+    <span>
+      <b>Manual ARIA for complex content:</b> If you pass a <b>ReactNode</b> (e.g., a custom component) as the{"
+3. "}
+      `title` or `description` prop to `ModalHeader`, you <b>must</b> assign a unique{"
+4. "}
+      `id` to your primary custom element within that ReactNode. Then, pass this `id` directly to
+      the parent `Modal` component using the `aria-labelledby` (for title) or{"
+5. "}
+      `aria-describedby` (for description) prop. This ensures assistive technologies can correctly identify
+      the modal's label and description. For example, if your custom title is{"
+6. "}
+      `&lt;CustomTitleComponent id="
+7. /&gt;`, you would pass{
+8. "}
+      `aria-labelledby="
+9. "` to the `&lt;Modal&gt;` component.
+    </span>,
+    <span>
+      <b>Overriding ARIA attributes:</b> Additionally, you can directly provide the `aria-labelledby` and{"
+10. "}
+      `aria-describedby` props to the `Modal` component itself, regardless of how you use the{"

package/dist/metadata/accessibility/NumberField.md

@@ -0,0 +1,9 @@
+# NumberField - Accessibility Requirements
+
+1. Using an `id` is highly recommended for all instances to ensure the best accessibility.
+2. Always provide a visible `label` or an `aria-label` to ensure the input's purpose is clear
+      to all users.
+3. When using `label` or `infoText`, you must also provide an `id`. This is crucial,
+      as it allows screen readers to correctly associate the input with its label and description.
+4. Providing an `id` also automatically links the Increment and Decrement buttons to the input via the{" "}
+      `aria-controls` attribute, further improving the experience for users of assistive technologies.

package/dist/metadata/accessibility/RadioButton.md

@@ -0,0 +1,11 @@
+# RadioButton - Accessibility Requirements
+
+1. Using an `id` is recommended for all instances to ensure proper label association.
+2. Always provide a `text` prop to ensure the radio button's purpose is clear to all users.
+3. Use the same `name` prop for all radio buttons in a group to ensure proper keyboard navigation and
+      screen reader grouping.
+4. Use `disabled` prop appropriately to indicate when radio buttons are not available for interaction.
+5. Use `disabledReason` prop to provide an explanation for disabled radio buttons, shown in a tooltip.
+6. Use `autoFocus` prop when a radio button should receive initial focus for keyboard navigation.
+7. Use `childrenTabIndex` prop to control the tab order when radio buttons have interactive children.
+8. Use `retainChildClick` prop to control whether clicking on children triggers radio button selection.

package/dist/metadata/accessibility/Search.md

@@ -0,0 +1,10 @@
+# Search - Accessibility Requirements
+
+1. Using an `id` is highly recommended for all instances to ensure proper label association.
+2. Use `inputAriaLabel` prop when you need to provide a custom accessible name for the search input.
+3. Use `searchResultsContainerId` prop to link the search input to its results container for screen reader
+      navigation.
+4. Use `currentAriaResultId` prop to indicate the currently active/focused search result.
+5. Use `ariaExpanded` prop to indicate when search results dropdown is open or closed.
+6. Use `ariaHasPopup` prop to specify the type of popup (e.g., 'listbox', 'menu') for search results.
+7. Use `clearIconLabel` prop to provide a custom accessible name for the clear button.

package/dist/metadata/accessibility/Tabs.md

@@ -0,0 +1,10 @@
+# Tabs - Accessibility Requirements
+
+1. Provide an `id` for the `TabList` and individual `Tab` components to enable
+      proper accessibility associations and unique identification.
+2. Ensure each `Tab` has clear, descriptive text content or appropriate icon with accessible name to
+      indicate what content will be displayed when selected.
+3. Use the `tabPanelIds` prop in `TabList` to establish proper relationships between tabs and
+      their corresponding tab panels. Pass an array of `TabPanel` IDs in the same order as the tabs.
+4. Provide unique `id` props for each `TabPanel` to enable the `aria-controls`
+      relationships established by the tabs.

package/dist/metadata/accessibility/TextArea.md

@@ -0,0 +1,17 @@
+# TextArea - Accessibility Requirements
+
+1. Using an `id` is highly recommended for all instances to ensure the best accessibility.
+2. Always provide a visible `label` to ensure the textarea's purpose is clear to all users.
+3. When using `label` or `helpText`, you must also provide an `id`. This is crucial,
+      as it allows screen readers to correctly associate the textarea with its label and description.
+4. For required fields, use the `required` prop to ensure proper screen reader announcements and native
+      browser validation.
+5. Provide descriptive error messages using the `error` prop with `helpText` to help users
+      understand and correct validation issues.
+6. The component automatically sets `aria-invalid` when validation fails, including when character count
+      exceeds `maxLength`.
+7. Character counting with `showCharCount` automatically provides accessibility labels for screen readers.
+8. Use the `aria-label` prop when a visible label is not desired but accessibility support is still
+      needed.
+9. The component automatically handles `aria-describedby` attributes for help text and character limit
+      information when applicable.

package/dist/metadata/accessibility/TextField.md

@@ -0,0 +1,16 @@
+# TextField - Accessibility Requirements
+
+1. Using an `id` is highly recommended for all instances to ensure the best accessibility.
+2. Always provide a visible `title` or an `inputAriaLabel` to ensure the input's purpose is
+      clear to all users.
+3. When using `title` or validation text, you must also provide an `id`. This is crucial, as it
+      allows screen readers to correctly associate the input with its label and description.
+4. For required fields, use the `required` prop to ensure proper screen reader announcements and native
+      browser validation.
+5. Provide descriptive error messages using `validation` prop with status 'error' to help users understand
+      and correct validation issues.
+6. When using icons, provide meaningful labels through `iconLabel` and{" "}
+      `secondaryIconLabel` props for screen reader users.
+7. For search inputs, use `type='search'` and provide `searchResultsContainerId` to properly
+      associate with search results.
+8. Character counting with `showCharCount` automatically provides accessibility labels for screen readers.

package/dist/metadata/accessibility/Toast.md

@@ -0,0 +1,4 @@
+# Toast - Accessibility Requirements
+
+1. For dismissible Toasts, use the `closeButtonAriaLabel` prop to provide a descriptive accessible name
+      for the close button (e.g., "Dismiss notification", "Close success message").

package/dist/metadata/accessibility/Toggle.md

@@ -0,0 +1,7 @@
+# Toggle - Accessibility Requirements
+
+1. Using an `id` is highly recommended for all instances to ensure proper label association.
+2. Use `ariaLabel` prop when you need to provide additional context for screen readers.
+3. Use `ariaLabelledBy` prop when an external element provides the accessible name for the toggle.
+4. Use `ariaControls` prop when the toggle controls other elements on the page.
+5. Use `disabled` prop appropriately to indicate when toggles are not available for interaction.

package/dist/metadata/accessibility/Tooltip.md

@@ -0,0 +1,11 @@
+# Tooltip - Accessibility Requirements
+
+1. Provide an `id` for the Tooltip to enable proper accessibility associations and unique identification.
+2. Ensure tooltip content is descriptive and provides meaningful information. Avoid using tooltips to repeat
+      information that's already visible in the UI.
+3. Configure `showTrigger` and `hideTrigger` events to ensure tooltips are accessible via both
+      mouse and keyboard interactions.
+4. Use `hideWhenReferenceHidden` prop to ensure tooltips disappear when their reference elements are
+      hidden or removed from the DOM.
+5. Avoid placing critical information only in tooltips - ensure the core functionality is accessible without tooltips
+      for users who cannot see them.