@imaginario27/air-ui-ds 1.13.4 → 1.13.5

package/CHANGELOG.md

@@ -5,6 +5,17 @@ All notable changes to this package are documented in this file.
 Historical releases were reconstructed from git history (GitHub repository) and npm publish dates.
 Future releases will include detailed entries generated with Changesets.
 
+## 1.13.4 - 2026-05-26
+
+Release type: patch.
+Commits found in range: 1.
+
+### Added
+
+1. make MetricCard description prop optional ([53937fb](https://github.com/imaginario27/air-ui/commit/53937fbca5cb1e3f350effdcb36a6a20bc9c50c5))
+
+- Package: @imaginario27/air-ui-ds.
+
 ## 1.13.3 - 2026-05-21
 
 Release type: patch.

package/components/accordions/AccordionItem.vue

@@ -1,20 +1,28 @@
 <template>
     <div class="w-full flex flex-col gap-2 py-3">
-        <div class="accordion-header flex justify-between gap-4 hover:cursor-pointer" @click="toggle">
+        <button
+            type="button"
+            :id="headerId"
+            class="accordion-header w-full flex justify-between gap-4 hover:cursor-pointer text-left"
+            :aria-expanded="isOpen"
+            :aria-controls="panelId"
+            @click="toggle"
+        >
             <span class="font-semibold mt-1">
                 {{ title }}
             </span>
-            
-            <!-- This button does not have click event because the toggle is being controlled by the accordeon header div-->
-            <ActionIconButton 
+
+            <ActionIconButton
                 :icon="isOpen ? 'mdi:minus' : 'mdi:plus'"
                 :styleType="ButtonStyleType.NEUTRAL_TRANSPARENT"
-                :size="ButtonSize.MD" 
+                :size="ButtonSize.MD"
+                tabindex="-1"
+                aria-hidden="true"
             />
-        </div>
+        </button>
 
         <VerticalExpansionTransition v-show="isOpen">
-            <p class="text-sm">
+            <p :id="panelId" role="region" :aria-labelledby="headerId" class="text-sm">
                 {{ content }}
             </p>
         </VerticalExpansionTransition>
@@ -34,6 +42,10 @@ defineProps({
     }
 })
 
+// IDs
+const headerId = useId()
+const panelId = useId()
+
 // Composables
 const { isOpen, toggle } = useAccordion()
 </script>

package/components/alerts/Alert.vue

@@ -1,5 +1,6 @@
 <template>
-    <div 
+    <div
+        role="alert"
         :class="[
             'w-full',
             'flex gap-3',

package/components/badges/Badge.vue

@@ -49,6 +49,7 @@
             class="ml-1 h-[24px] flex items-center"
         >
             <button
+                aria-label="Remove"
                 class="flex items-center justify-center h-full w-[20px]"
                 :class="[
                     textClass,

package/components/buttons/ActionIconButton.vue

@@ -17,7 +17,7 @@
             ...(actionType === ButtonActionType.ACTION ? { onClick: emitClick } : {})
         }"
         :disabled="disabled"
-        
+        :aria-label="ariaLabel"
     >
         <Icon 
             :name="icon"
@@ -84,6 +84,7 @@ const props = defineProps({
         default: false
     },
     id: String as PropType<string>,
+    ariaLabel: String as PropType<string>,
 })
 
 // Emits

package/components/buttons/options/OptionButtonGroup.vue

@@ -1,5 +1,7 @@
 <template>
-    <div 
+    <div
+        role="group"
+        aria-label="Options"
         :class="[
             'flex',
             'flex-wrap gap-2',
@@ -8,6 +10,7 @@
         <OptionButton
             v-for="(button, index) in displayButtons"
             :key="index"
+            :aria-pressed="isButtonActive(button)"
             :active="isButtonActive(button)"
             :text="button.text"
             :size

package/components/buttons/toggle/ToggleButton.vue

@@ -1,6 +1,7 @@
 <template>
     <button
         type="button"
+        :aria-pressed="active"
         :disabled
         :class="[
             'flex items-center justify-center',

package/components/buttons/toggle/ToggleButtonGroup.vue

@@ -1,5 +1,7 @@
 <template>
-    <div 
+    <div
+        role="group"
+        aria-label="Toggle options"
         :class="[
             'flex',
             groupStyle === ToggleButtonGroupStyle.GROUPED ? 'border border-border-default' : 'flex-wrap gap-3',

package/components/buttons/toggle/ToggleIconButton.vue

@@ -1,6 +1,8 @@
 <template>
     <button
         type="button"
+        :aria-pressed="active"
+        :aria-label="ariaLabel"
         :disabled
         :class="[
             'flex items-center justify-center',
@@ -39,6 +41,7 @@ const props = defineProps({
         type: Boolean as PropType<boolean>,
         default: false,
     },
+    ariaLabel: String as PropType<string>,
 })
 
 // Emits

package/components/cards/specific/SelectableCard.vue

@@ -1,14 +1,22 @@
 <template>
-    <Card 
+    <Card
         :hasShadow
+        v-bind="selectMode === CardSelectionMode.CARD ? {
+            role: 'checkbox',
+            'aria-checked': modelValue,
+            tabindex: disabled ? -1 : 0,
+        } : {}"
         :class="[
             'lg:p-5',
-            selectMode === CardSelectionMode.CARD && isHoverable && 
+            selectMode === CardSelectionMode.CARD && isHoverable &&
                 'hover:border-border-neutral-hover cursor-pointer transition-shadow duration-300',
+            selectMode === CardSelectionMode.CARD && 'outline-none focus-visible:ring-2 focus-visible:ring-border-primary-brand-default',
             modelValue && '!border-border-primary-brand-active',
             disabled && 'opacity-disabled cursor-not-allowed',
         ]"
         @click="handleCardClick"
+        @keydown.enter.prevent="handleCardClick($event as any)"
+        @keydown.space.prevent="handleCardClick($event as any)"
     >
         <CardHeader 
             :class="[
@@ -221,15 +229,16 @@ const props = defineProps({
 const emit = defineEmits(['update:modelValue', 'buttonClick'])
 
 // Methods
-const handleCardClick = (event: MouseEvent) => {
+const handleCardClick = (event: MouseEvent | KeyboardEvent) => {
     if (props.selectMode !== CardSelectionMode.CARD) return
 
-    const path = event.composedPath?.()
-    const isInsideButton = path?.some((el: any) => el?.tagName === 'BUTTON')
-
-    if (!isInsideButton) {
-        emit('update:modelValue', !props.modelValue)
+    if (event instanceof MouseEvent) {
+        const path = event.composedPath?.()
+        const isInsideButton = path?.some((el: any) => el?.tagName === 'BUTTON')
+        if (isInsideButton) return
     }
+
+    emit('update:modelValue', !props.modelValue)
 }
 
 const handleButtonClick = (event: Event | undefined) => {

package/components/collapsibles/Collapsible.vue

@@ -1,27 +1,39 @@
 <template>
     <div class="w-full flex flex-col gap-2 py-3">
-        <div
-            class="collapsible-header flex justify-between gap-4 hover:cursor-pointer"
+        <button
+            type="button"
+            :id="headerId"
+            class="collapsible-header w-full flex justify-between gap-4 hover:cursor-pointer text-left"
+            :aria-expanded="isOpen"
+            :aria-controls="panelId"
             @click="toggle"
         >
             <span class="font-semibold mt-1">
                 {{ title }}
             </span>
 
-            <ActionIconButton 
+            <ActionIconButton
                 :icon="isOpen ? 'mdi:unfold-less-horizontal' : 'mdi:unfold-more-horizontal'"
                 :styleType="ButtonStyleType.NEUTRAL_OUTLINED"
-                :size="ButtonSize.MD" 
+                :size="ButtonSize.MD"
+                tabindex="-1"
+                aria-hidden="true"
             />
-        </div>
+        </button>
 
         <VerticalExpansionTransition v-show="isOpen">
-            <slot />
+            <div :id="panelId" role="region" :aria-labelledby="headerId">
+                <slot />
+            </div>
         </VerticalExpansionTransition>
     </div>
 </template>
 
 <script setup lang="ts">
+// IDs
+const headerId = useId()
+const panelId = useId()
+
 // Props
 const props = defineProps({
     title: {

package/components/dropdowns/DropdownMenuItem.vue

@@ -1,6 +1,8 @@
 <template>
     <component
         :is="dynamicComponent"
+        role="menuitem"
+        :tabindex="disabled ? -1 : 0"
         v-bind="{
             ...componentProps,
             ...$attrs,
@@ -12,12 +14,15 @@
             'text-sm',
             'hover:bg-background-neutral-hover-subtle hover:cursor-pointer',
             'w-full',
+            'outline-none',
+            'focus-visible:bg-background-neutral-hover-subtle',
             sizeClass,
             typeClass,
             hasSeparator ? 'border-b border-border-default' : undefined,
             helpText ? 'py-2' : undefined,
             disabled && 'opacity-disabled cursor-not-allowed pointer-events-none',
         ]"
+        @keydown.enter.prevent="actionType === DropdownActionType.ACTION && emitClick()"
     >
         <div class="flex items-center gap-3 w-full">
             <Icon 

package/components/dropdowns/DropdownSelect.vue

@@ -17,8 +17,13 @@
             <template #activator="{ isOpen }">
                 <!-- Select Box -->
                 <div
-                    :class="[ 
-                        'select-box', // Class identifier for unit test
+                    role="combobox"
+                    :aria-expanded="isOpen"
+                    aria-haspopup="listbox"
+                    :aria-label="placeholder"
+                    :tabindex="disabled ? -1 : 0"
+                    :class="[
+                        'select-box',
                         'flex items-center justify-between',
                         'w-full',
                         'px-3',
@@ -28,10 +33,14 @@
                         'border border-border-default',
                         'text-sm',
                         disabled ? 'text-text-neutral-disabled' : 'text-text-default',
+                        'outline-none',
+                        'focus-visible:ring-2 focus-visible:ring-border-primary-brand-default',
                         sizeClass,
                         selectBoxClass,
                     ]"
                     @click="handleSelectBoxClick"
+                    @keydown.enter.prevent="handleSelectBoxClick($event as any)"
+                    @keydown.space.prevent="handleSelectBoxClick($event as any)"
                 >
                     <div v-if="multiple">
                         <template v-if="Array.isArray(selected) && selected.length">
@@ -96,11 +105,12 @@
 
                     <div class="flex gap-2 items-center">
                         <!-- Clear button -->
-                        <ActionIconButton 
+                        <ActionIconButton
                             v-if="multiple && Array.isArray(selected) && selected.length"
                             :size="ButtonSize.SM"
                             :styleType="ButtonStyleType.NEUTRAL_TRANSPARENT_SUBTLE"
                             icon="mdi:close-circle"
+                            ariaLabel="Clear selection"
                             @click="selected = []"
                         />
 
@@ -135,6 +145,7 @@
                         <input
                             v-model="searchQuery"
                             type="text"
+                            :aria-label="searchFieldPlaceholder"
                             :placeholder="searchFieldPlaceholder"
                             :class="[ 
                                 'w-full', 

package/components/forms/Checkbox.vue

@@ -4,12 +4,16 @@
             :id="id"
             type="checkbox"
             :checked="modelValue"
-            class="hidden"
+            class="sr-only"
             :disabled="disabled"
             @change="handleNativeChange"
+            @keydown.space.prevent="toggleCheckbox"
         >
 
         <div
+            role="checkbox"
+            :aria-checked="modelValue"
+            :aria-label="id"
             :class="[
                 'flex items-center justify-center',
                 controlFieldSizeClass,

package/components/forms/fields/SearchField.vue

@@ -66,11 +66,12 @@
             >
 
             <!-- Clear button -->
-            <ActionIconButton 
+            <ActionIconButton
                 v-if="filled"
                 :size="ButtonSize.SM"
                 :styleType="ButtonStyleType.NEUTRAL_TRANSPARENT_SUBTLE"
                 icon="mdi:close-circle"
+                ariaLabel="Clear search"
                 @click="clearField"
             />
         </div>

package/components/forms/fields/SwitchField.vue

@@ -54,19 +54,23 @@
                 />
             </div>
 
-            <!-- Hidden native checkbox -->
-            <input 
-                :id="id" 
-                type="checkbox" 
-                :checked="modelValue" 
-                class="hidden" 
+            <!-- Visually hidden native checkbox (remains accessible to screen readers) -->
+            <input
+                :id="id"
+                type="checkbox"
+                :checked="modelValue"
+                class="sr-only"
                 :disabled="disabled"
-                @change="handleChange" 
+                @change="handleChange"
+                @keydown.space.prevent="toggleCheckbox"
             >
 
             <!-- Custom Switch -->
-            <div 
-                :class="[ 
+            <div
+                role="switch"
+                :aria-checked="modelValue"
+                :aria-label="label || legend || 'Toggle'"
+                :class="[
                     'relative flex items-center',
                     controlFieldSizeClass,
                     'rounded-full transition-colors',

package/components/images/QRCode.vue

@@ -1,5 +1,7 @@
 <template>
     <div
+        role="img"
+        :aria-label="ariaLabel || `QR code: ${modelValue}`"
         :class="[
             'relative flex items-center justify-center',
             hasBorder && 'border border-border-default rounded-md p-2',
@@ -98,6 +100,7 @@ const props = defineProps({
         default: false,
     },
     containerClass: String as PropType<string>,
+    ariaLabel: String as PropType<string>,
 })
 
 // Computed

package/components/loaders/Loading.vue

@@ -1,6 +1,8 @@
 <template>
-    <div 
-        v-if="isLoading" 
+    <div
+        v-if="isLoading"
+        role="status"
+        aria-live="polite"
         class="flex flex-col items-center gap-4"
     >
         <Spinner :class="[spinnerSizeClass, spinnerClass]" />

package/components/modals/ModalDialog.vue

@@ -42,6 +42,10 @@
                     >
                         <div
                             v-show="modelValue"
+                            ref="dialogRef"
+                            role="dialog"
+                            aria-modal="true"
+                            :aria-labelledby="ariaLabelledby"
                             :class="[
                                 'bg-background-surface rounded-lg shadow-xl',
                                 'relative w-full my-8',
@@ -54,6 +58,7 @@
                                 :styleType="ButtonStyleType.NEUTRAL_TRANSPARENT"
                                 :size="ButtonSize.MD"
                                 icon="mdi:close"
+                                ariaLabel="Close"
                                 class="absolute top-4 right-4 z-10"
                                 @click="closeModal"
                             />
@@ -70,6 +75,10 @@
 </template>
 
 <script setup lang="ts">
+// Refs
+const dialogRef = ref<HTMLElement | null>(null)
+const previouslyFocusedElement = ref<HTMLElement | null>(null)
+
 // State
 const previousBodyOverflow = ref<string | null>(null)
 const previousBodyPaddingRight = ref<string | null>(null)
@@ -95,6 +104,7 @@ const props = defineProps({
         default: 'max-w-[600px]',
     },
     id: String as PropType<string>,
+    ariaLabelledby: String as PropType<string>,
 })
 
 // Emits
@@ -118,13 +128,39 @@ const handleEscKey = (event: KeyboardEvent) => {
     }
 }
 
+const handleFocusTrap = (event: KeyboardEvent) => {
+    if (event.key !== 'Tab' || !dialogRef.value) return
+
+    const focusableElements = dialogRef.value.querySelectorAll<HTMLElement>(
+        'a[href], button:not([disabled]), input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])'
+    )
+    if (focusableElements.length === 0) return
+
+    const first = focusableElements[0]!
+    const last = focusableElements[focusableElements.length - 1]!
+
+    if (event.shiftKey) {
+        if (document.activeElement === first) {
+            event.preventDefault()
+            last.focus()
+        }
+    } else {
+        if (document.activeElement === last) {
+            event.preventDefault()
+            first.focus()
+        }
+    }
+}
+
 // Event listeners
 const addEscListener = () => {
     globalThis.addEventListener('keydown', handleEscKey)
+    globalThis.addEventListener('keydown', handleFocusTrap)
 }
 
 const removeEscListener = () => {
     globalThis.removeEventListener('keydown', handleEscKey)
+    globalThis.removeEventListener('keydown', handleFocusTrap)
 }
 
 const lockScroll = () => {
@@ -162,11 +198,19 @@ watch(
     () => props.modelValue,
     newValue => {
         if (newValue) {
-            addEscListener() // Add Esc key listener
+            previouslyFocusedElement.value = document.activeElement as HTMLElement
+            addEscListener()
             lockScroll()
+            nextTick(() => {
+                const firstFocusable = dialogRef.value?.querySelector<HTMLElement>(
+                    'a[href], button:not([disabled]), input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])'
+                )
+                firstFocusable?.focus()
+            })
         } else {
-            removeEscListener() // Remove Esc key listener
+            removeEscListener()
             unlockScroll()
+            previouslyFocusedElement.value?.focus()
         }
     },
     { immediate: true },

package/components/progress/ProgressBar.vue

@@ -14,6 +14,12 @@
         </div>
 
         <div
+            role="progressbar"
+            :aria-valuenow="isIndeterminate ? undefined : normalizedProgress"
+            :aria-valuemin="min"
+            :aria-valuemax="max"
+            :aria-valuetext="isIndeterminate ? loadingText : undefined"
+            :aria-label="ariaLabel"
             :class="[
                 'w-full',
                 'overflow-hidden',
@@ -114,6 +120,10 @@ const props = defineProps({
     },
     progressClass: String as PropType<string>,
     progressLabelClass: String as PropType<string>,
+    ariaLabel: {
+        type: String as PropType<string>,
+        default: 'Progress',
+    },
 })
 
 // Computed

package/components/rating/Rating.vue

@@ -1,18 +1,33 @@
 <template>
     <div
+        :role="isInteractive ? 'radiogroup' : 'img'"
+        :aria-label="isInteractive ? 'Rating' : `Rating: ${displayValue} out of 5`"
         class="flex gap-1"
         @mouseleave="hoverIndex = null"
+        @keydown="isInteractive && handleKeydown($event)"
     >
-        <RatingItem
+        <div
             v-for="(icon, index) in items"
             :key="index"
-            :icon
-            :size
-            :color
-            :isInteractive
+            v-bind="isInteractive ? {
+                role: 'radio',
+                'aria-checked': modelValue === index + 1,
+                'aria-label': `${index + 1} star${index + 1 > 1 ? 's' : ''}`,
+                tabindex: modelValue === index + 1 || (modelValue === 0 && index === 0) ? 0 : -1,
+            } : {
+                'aria-hidden': 'true',
+            }"
+            class="inline-flex"
             @click="isInteractive && handleClick(index)"
             @mouseenter="isInteractive && onMouseEnter(index)"
-        />
+        >
+            <RatingItem
+                :icon
+                :size
+                :color
+                :isInteractive
+            />
+        </div>
     </div>
 </template>
 
@@ -68,6 +83,22 @@ const onMouseEnter = (index: number) => {
     }
 }
 
+const handleKeydown = (event: KeyboardEvent) => {
+    let newValue = props.modelValue
+
+    if (event.key === 'ArrowRight' || event.key === 'ArrowUp') {
+        event.preventDefault()
+        newValue = Math.min(5, props.modelValue + 1)
+    } else if (event.key === 'ArrowLeft' || event.key === 'ArrowDown') {
+        event.preventDefault()
+        newValue = Math.max(0, props.modelValue - 1)
+    } else {
+        return
+    }
+
+    emit('update:modelValue', newValue)
+}
+
 const handleClick = (index: number) => {
     const clickedValue = index + 1
 

package/components/spinners/Spinner.vue

@@ -1,5 +1,7 @@
 <template>
-    <div 
+    <div
+        role="status"
+        aria-label="Loading"
         :class="[
             'animate-spin',
             'rounded-full',

package/components/tabs/Tab.vue

@@ -1,5 +1,8 @@
 <template>
-    <div 
+    <div
+        role="tab"
+        :aria-selected="active"
+        :tabindex="tabindex"
         :class="[
             'flex',
             'items-center',
@@ -7,6 +10,8 @@
             'px-3',
             'hover:cursor-pointer',
             'group',
+            'outline-none',
+            'focus-visible:ring-2 focus-visible:ring-border-primary-brand-default',
             disabled && 'opacity-disabled cursor-not-allowed pointer-events-none',
             styleClass,
         ]"
@@ -94,6 +99,10 @@ const props = defineProps({
         type: Boolean as PropType<boolean>,
         default: false,
     },
+    tabindex: {
+        type: Number as PropType<number>,
+        default: 0,
+    },
 })
 
 // States

package/components/tabs/TabBar.vue

@@ -1,5 +1,6 @@
 <template>
-    <div 
+    <div
+        role="tablist"
         :class="[
             'flex flex-wrap',
             hasContainer && 'border border-border-default',
@@ -7,19 +8,22 @@
             hasContainer && isContainerFullWidth && 'w-full',
             disabled && 'opacity-disabled cursor-not-allowed pointer-events-none',
         ]"
+        @keydown="handleKeydown"
     >
-        <Tab 
-            v-for="(tab, index) in tabs" 
-            :key="index" 
-            :text="tab.text" 
+        <Tab
+            v-for="(tab, index) in tabs"
+            :key="index"
+            ref="tabRefs"
+            :text="tab.text"
             :icon="tab.icon"
-            :imgUrl="tab.imgUrl" 
+            :imgUrl="tab.imgUrl"
             :badgeValue="tab.badgeValue"
-            :active="index === activeIndex" 
+            :active="index === activeIndex"
             :disabled="disabled || tab.disabled"
             :tabStyle
             :size="tabSize"
             :decoration
+            :tabindex="index === activeIndex ? 0 : -1"
             @click="handleTabClick(index, tab.to)"
             @pointerenter="handleTabPrefetch(tab.to)"
             @focus="handleTabPrefetch(tab.to)"
@@ -73,6 +77,9 @@ const props = defineProps({
     },
 })
 
+// Refs
+const tabRefs = ref<ComponentPublicInstance[]>([])
+
 // Local
 const activeIndex = ref(props.modelValue)
 
@@ -112,6 +119,40 @@ const handleTabPrefetch = (to?: string) => {
     // fire and forget - do not await to avoid blocking
     preloadRouteComponents(to)
 }
+const handleKeydown = (event: KeyboardEvent) => {
+    const tabCount = props.tabs.length
+    let newIndex = activeIndex.value
+
+    if (event.key === 'ArrowRight' || event.key === 'ArrowDown') {
+        event.preventDefault()
+        newIndex = (activeIndex.value + 1) % tabCount
+    } else if (event.key === 'ArrowLeft' || event.key === 'ArrowUp') {
+        event.preventDefault()
+        newIndex = (activeIndex.value - 1 + tabCount) % tabCount
+    } else if (event.key === 'Home') {
+        event.preventDefault()
+        newIndex = 0
+    } else if (event.key === 'End') {
+        event.preventDefault()
+        newIndex = tabCount - 1
+    } else {
+        return
+    }
+
+    while (props.tabs[newIndex]?.disabled && newIndex !== activeIndex.value) {
+        if (event.key === 'ArrowRight' || event.key === 'ArrowDown' || event.key === 'End') {
+            newIndex = (newIndex + 1) % tabCount
+        } else {
+            newIndex = (newIndex - 1 + tabCount) % tabCount
+        }
+    }
+
+    handleTabClick(newIndex, props.tabs[newIndex]?.to)
+    nextTick(() => {
+        (tabRefs.value[newIndex]?.$el as HTMLElement)?.focus()
+    })
+}
+
 // Watchers
 watch(() => props.modelValue, (newVal) => {
     activeIndex.value = newVal

package/components/tabs/TabContent.vue

@@ -1,5 +1,5 @@
 <template>
-    <div class="flex flex-col gap-6 w-full">
+    <div role="tabpanel" class="flex flex-col gap-6 w-full">
         <slot />
     </div>
 </template>

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@imaginario27/air-ui-ds",
-    "version": "1.13.4",
+    "version": "1.13.5",
     "author": "imaginario27",
     "type": "module",
     "homepage": "https://air-ui.netlify.app/",