@indielayer/ui 1.18.1 → 2.1.0

package/src/components/modal/Modal.vue

@@ -5,46 +5,92 @@ const modalProps = {
   size: {
     type: String as PropType<ModalSize>,
     default: 'lg',
+    description: 'Dialog width preset (xs, sm, md, lg, xl, full).',
   },
   position: {
     type: String as PropType<ModalPosition>,
     default: 'center',
+    description: 'Vertical placement of the dialog (top, center, bottom).',
+  },
+  modelValue: {
+    type: Boolean,
+    description: 'Open state (v-model).',
+  },
+  showClose: {
+    type: Boolean,
+    description: 'Shows a close button in the corner.',
   },
-  modelValue: Boolean,
-  showClose: Boolean,
   backdrop: {
     type: Boolean,
     default: true,
+    description: 'Shows a dimmed backdrop behind the dialog.',
   },
   hasActions: {
     type: Boolean,
     default: true,
+    description: 'Renders the default actions footer region when no footer slot is used.',
   },
   hasHeader: {
     type: Boolean,
     default: true,
+    description: 'Renders the default header region when no header slot is used.',
+  },
+  title: {
+    type: String,
+    description: 'Header title text.',
+  },
+  description: {
+    type: String,
+    description: 'Body description shown above the default slot.',
+  },
+  label: {
+    type: String,
+    description: 'Small label above the title in the header.',
+  },
+  loading: {
+    type: Boolean,
+    description: 'Loading state for the modal (theme/visual).',
+  },
+  loadingText: {
+    type: String,
+    description: 'Text shown while loading.',
+  },
+  fluid: {
+    type: Boolean,
+    description: 'Stretches the dialog to fill available width within its size.',
   },
-  title: String,
-  description: String,
-  label: String,
-  loading: Boolean,
-  loadingText: String,
-  fluid: Boolean,
 
   // form props
-  isForm: Boolean,
-  formDisabled: Boolean,
-  formDescription: String,
-  formTitle: String,
+  isForm: {
+    type: Boolean,
+    description: 'Wraps content in x-form and enables form submit handling.',
+  },
+  formDisabled: {
+    type: Boolean,
+    description: 'Disables the inner form when `isForm` is set.',
+  },
+  formDescription: {
+    type: String,
+    description: 'Description passed to the inner form when `isForm` is set.',
+  },
+  formTitle: {
+    type: String,
+    description: 'Title passed to the inner form when `isForm` is set.',
+  },
   formAutoValidate: {
     type: Boolean,
     default: true,
+    description: 'Auto-validate the inner form on submit when `isForm` is set.',
   },
   formErrors: {
     type: [Array, Object] as PropType<FormError[] | FormError>,
     default: () => ([]),
+    description: 'External form errors passed to the inner form when `isForm` is set.',
+  },
+  persistent: {
+    type: Boolean,
+    description: 'Prevents closing on Escape or backdrop click.',
   },
-  persistent: Boolean,
 }
 
 export type ModalSize = typeof modalSize[number]
@@ -63,6 +109,28 @@ export default {
     size: modalSize,
     position: modalPosition,
   },
+  docs: {
+    slots: {
+      default: 'Main modal body content.',
+      image: 'Optional media above the header.',
+      header: 'Replaces the default header region.',
+      'header-content': 'Custom header content inside the default header layout.',
+      footer: 'Replaces the default actions footer.',
+      actions: 'Custom actions row inside the default footer.',
+      'cancel-action': 'Cancel / dismiss control in the actions row.',
+      'tertiary-action': 'Tertiary action control in the actions row.',
+      'secondary-action': 'Secondary action control in the actions row.',
+      'primary-action': 'Primary action control in the actions row.',
+    },
+    emits: {
+      'update:modelValue': 'Emitted when open state changes (v-model).',
+      submit: 'Emitted when the inner form submits. Payload is the validation result.',
+    },
+    methods: {
+      open: 'Open the modal.',
+      close: 'Close the modal.',
+    },
+  },
 }
 </script>
 
@@ -100,7 +168,7 @@ watch(value, (val) => {
   if (val) {
     setTimeout(() => {
       stopClickOutside = onClickOutside(modalRef, clickOutsideCallback, {
-        ignore: ['.v-popper__popper'],
+        ignore: ['.v-popper__popper', '.dp__menu', '.dp--menu-wrapper'],
       })
     })
   }
@@ -113,6 +181,13 @@ watch(() => props.modelValue, checkVisibility, { immediate: true })
 async function checkVisibility() {
   const val = props.modelValue
 
+  if (typeof document === 'undefined' || typeof window === 'undefined') {
+    value.value = val
+    visible.value = val
+
+    return
+  }
+
   if (val) {
     const scrollbarWidth = window.innerWidth - document.documentElement.clientWidth
 
@@ -141,7 +216,7 @@ async function checkVisibility() {
 if (typeof window !== 'undefined') useEventListener(document, 'keydown', onKeyDown)
 
 const shouldIgnoreEvent = (event: KeyboardEvent) => {
-  return ['.v-popper__popper', '.x-datepicker'].some((target) => {
+  return ['.v-popper__popper', '.x-datepicker', '.dp__menu', '.dp--menu-wrapper'].some((target) => {
     if (typeof target === 'string') {
       return Array.from(window.document.querySelectorAll(target))
         .some((el) => el === event.target || event.composedPath().includes(el))

package/src/components/notifications/Notifications.vue

@@ -5,31 +5,38 @@ const notificationsProps = {
     type: String as PropType<NotificationsAlign>,
     default: 'right',
     validator: (value: string) => validators.align.includes(value as NotificationsAlign),
+    description: 'Horizontal placement of the toast stack (left or right).',
   },
   position: {
     type: String as PropType<NotificationsPosition>,
     default: 'bottom',
     validator: (value: string) => validators.position.includes(value as NotificationsPosition),
+    description: 'Vertical placement of the toast stack (top or bottom).',
   },
   timeout: {
     type: Number,
     default: 3500,
+    description: 'Default auto-dismiss delay in milliseconds. Set 0 to keep until removed.',
   },
   removable: {
     type: Boolean,
     default: true,
+    description: 'Shows a dismiss control on each notification by default.',
   },
   pauseOnHover: {
     type: Boolean,
     default: true,
+    description: 'Pauses the dismiss timer while the pointer hovers a notification.',
   },
   injectKey: {
     type: [Symbol, String],
     default: injectNotificationKey,
+    description: 'Provide/inject key for notification helpers (log, info, success, warn, error).',
   },
   offset: {
     type: [String, Number],
     default: 0,
+    description: 'Extra inset from the viewport edge in pixels.',
   },
 }
 
@@ -78,6 +85,19 @@ export interface NotificationsTheme extends ThemeComponent<NotificationsProps, I
 export default {
   name: 'XNotifications',
   validators,
+  docs: {
+    slots: {
+      default: 'App content that can inject notification helpers.',
+    },
+    methods: {
+      log: 'Show a plain notification.',
+      info: 'Show an info-styled notification.',
+      success: 'Show a success-styled notification.',
+      warn: 'Show a warning-styled notification.',
+      warning: 'Alias of `warn`.',
+      error: 'Show an error-styled notification.',
+    },
+  },
 }
 </script>
 
@@ -274,6 +294,7 @@ defineExpose({ log, info, success, warn, warning: warn, error })
       :class="[
         className,
         classes.wrapper,
+        'pointer-events-none',
         {
           // align
           'left-0': internalAlign === 'left',
@@ -290,6 +311,7 @@ defineExpose({ log, info, success, warn, warning: warn, error })
         ]"
         :class="[
           classes.list,
+          'pointer-events-none',
           { 'flex-col-reverse': internalPosition }
         ]"
         enter-active-class="transition ease-out duration-200"
@@ -305,6 +327,7 @@ defineExpose({ log, info, success, warn, warning: warn, error })
           :key="notification.id"
           :class="[
             classes.item,
+            'pointer-events-auto',
             {
               'mb-2': internalPosition === 'bottom',
               'mt-2': internalPosition === 'top',

package/src/components/notifications/__tests__/Notifications.spec.ts

@@ -1,11 +1,51 @@
-import { describe, it, expect } from 'vitest'
-import { mount } from '@vue/test-utils'
-import Notifications from '../Notifications.vue'
+import { describe, it, expect, afterEach } from 'vitest'
+import { mount, type VueWrapper } from '@vue/test-utils'
+import type { ComponentPublicInstance } from 'vue'
+import Notifications, { type NotificationInjection } from '../Notifications.vue'
 
 describe('Notifications', () => {
+  let wrapper: VueWrapper<ComponentPublicInstance & NotificationInjection>
+
+  afterEach(() => {
+    wrapper?.unmount()
+  })
+
   it('renders without errors', () => {
-    const wrapper = mount(Notifications)
+    wrapper = mount(Notifications)
 
     expect(wrapper.vm).toBeTruthy()
   })
+
+  it('does not capture pointer events on offset padding', async () => {
+    wrapper = mount(Notifications, {
+      props: { offset: 60, timeout: 0 },
+      attachTo: document.body,
+    })
+
+    const overlay = document.body.querySelector('.x-notifications') as HTMLElement | null
+    const list = overlay?.querySelector('ul') as HTMLElement | null
+
+    expect(overlay?.classList.contains('pointer-events-none')).toBe(true)
+    expect(list?.classList.contains('pointer-events-none')).toBe(true)
+    expect(list?.style.paddingBottom).toBe('60px')
+
+    wrapper.vm.log('Hello')
+    await wrapper.vm.$nextTick()
+
+    const item = overlay?.querySelector('li')
+
+    expect(item?.classList.contains('pointer-events-auto')).toBe(true)
+  })
+
+  it('applies offset as padding-top when stacked at the top', () => {
+    wrapper = mount(Notifications, {
+      props: { offset: 48, position: 'top' },
+      attachTo: document.body,
+    })
+
+    const list = document.body.querySelector('.x-notifications ul') as HTMLElement | null
+
+    expect(list?.style.paddingTop).toBe('48px')
+    expect(list?.classList.contains('pointer-events-none')).toBe(true)
+  })
 })

package/src/components/pagination/Pagination.vue

@@ -1,19 +1,24 @@
 <script lang="ts">
+import { optionalBooleanProp } from '../../common/props'
+
 const paginationVariant = ['simple', 'quick', 'dots'] as const
 const paginationProps = {
   ...useCommon.props(),
-  links: Boolean,
+  links: optionalBooleanProp('Renders page buttons as links (`?page=` query).'),
   totalPages: {
     type: Number,
     default: 1,
+    description: 'Total number of pages.',
   },
   modelValue: {
     type: Number,
     default: 1,
+    description: 'Current page (v-model).',
   },
   variant: {
     type: String as PropType<PaginationVariant>,
     default: 'simple',
+    description: 'Layout style (simple, quick, or dots).',
   },
 }
 
@@ -29,6 +34,11 @@ export default {
     ...useCommon.validators(),
     variant: paginationVariant,
   },
+  docs: {
+    emits: {
+      'update:modelValue': 'Emitted when the current page changes (v-model).',
+    },
+  },
 }
 </script>
 

package/src/components/pagination/PaginationItem.vue

@@ -1,12 +1,18 @@
 <script lang="ts">
+import { optionalBooleanProp } from '../../common/props'
+
 const paginationItemProps = {
   ...useCommon.props(),
   value: {
     type: Number,
     default: 0,
+    description: 'Page number shown on the control.',
+  },
+  selected: {
+    type: Boolean,
+    description: 'Marks this page as the current selection.',
   },
-  selected: Boolean,
-  links: Boolean,
+  links: optionalBooleanProp('Renders as a link to `?page=` instead of a button.'),
 }
 
 export type PaginationItemProps = ExtractPublicPropTypes<typeof paginationItemProps>
@@ -19,6 +25,11 @@ export default {
   validators: {
     ...useCommon.validators(),
   },
+  docs: {
+    emits: {
+      input: 'Emitted with the page number when an unselected item is clicked.',
+    },
+  },
 }
 </script>
 

package/src/components/popover/Popover.vue

@@ -7,53 +7,106 @@ export type PopoverPlacement = Placement
 export type PopoverTriggerEvent = TriggerEvent
 
 const popoverProps = {
-  disabled: Boolean,
-  positioningDisabled: Boolean,
+  disabled: {
+    type: Boolean,
+    description: 'Disables showing the popover.',
+  },
+  positioningDisabled: {
+    type: Boolean,
+    description: 'Keeps the popover in the DOM flow without floating positioning.',
+  },
   placement: {
     type: String as PropType<PopoverPlacement>,
     default: 'bottom-start',
+    description: 'Preferred placement relative to the trigger.',
   },
   delay: {
     type: [String, Number, Object] as PropType<string | number | { show: number; hide: number; }>,
     default: 0,
+    description: 'Show/hide delay in ms, or `{ show, hide }`.',
+  },
+  distance: {
+    type: [Number, String],
+    description: 'Offset along the placement axis in pixels.',
+  },
+  skidding: {
+    type: [Number, String],
+    description: 'Offset along the trigger edge in pixels.',
   },
-  distance: [Number, String],
-  skidding: [Number, String],
   triggers: {
     type: Array as PropType<Array<PopoverTriggerEvent>>,
     default: () => ['click'],
+    description: 'Events that toggle the popover (for example click, hover, focus).',
   },
   hideArrow: {
     type: Boolean,
     default: true,
+    description: 'Hides the popover arrow.',
+  },
+  showTriggers: {
+    type: [Array, Function] as PropType<Array<PopoverTriggerEvent> | ((triggers: Array<PopoverTriggerEvent>) => Array<PopoverTriggerEvent>)>,
+    description: 'Events that show the popover, or a function deriving them from `triggers`.',
+  },
+  hideTriggers: {
+    type: [Array, Function] as PropType<Array<PopoverTriggerEvent> | ((triggers: Array<PopoverTriggerEvent>) => Array<PopoverTriggerEvent>)>,
+    description: 'Events that hide the popover, or a function deriving them from `triggers`.',
+  },
+  popperTriggers: {
+    type: Array as PropType<Array<PopoverTriggerEvent>>,
+    description: 'Events on the popover content that keep it open.',
+  },
+  popperShowTriggers: {
+    type: [Array, Function] as PropType<Array<PopoverTriggerEvent> | ((triggers: Array<PopoverTriggerEvent>) => Array<PopoverTriggerEvent>)>,
+    description: 'Events on the content that show the popover.',
+  },
+  popperHideTriggers: {
+    type: [Array, Function] as PropType<Array<PopoverTriggerEvent> | ((triggers: Array<PopoverTriggerEvent>) => Array<PopoverTriggerEvent>)>,
+    description: 'Events on the content that hide the popover.',
   },
-  showTriggers: [Array, Function] as PropType<Array<PopoverTriggerEvent> | ((triggers: Array<PopoverTriggerEvent>) => Array<PopoverTriggerEvent>)>,
-  hideTriggers: [Array, Function] as PropType<Array<PopoverTriggerEvent> | ((triggers: Array<PopoverTriggerEvent>) => Array<PopoverTriggerEvent>)>,
-  popperTriggers: Array as PropType<Array<PopoverTriggerEvent>>,
-  popperShowTriggers: [Array, Function] as PropType<Array<PopoverTriggerEvent> | ((triggers: Array<PopoverTriggerEvent>) => Array<PopoverTriggerEvent>)>,
-  popperHideTriggers: [Array, Function] as PropType<Array<PopoverTriggerEvent> | ((triggers: Array<PopoverTriggerEvent>) => Array<PopoverTriggerEvent>)>,
   container: {
     type: [String, Object, Boolean],
     default: 'body',
+    description: 'Element that contains the floating popover DOM.',
+  },
+  boundary: {
+    type: [String, Object],
+    description: 'Overflow boundary used for flip/shift positioning.',
   },
-  boundary: [String, Object],
   strategy: {
     type: String as PropType<'absolute' | 'fixed'>,
     default: 'absolute',
+    description: 'CSS position strategy for the floating element.',
   },
   autoHide: {
     type: [Boolean, Function] as PropType<boolean | ((event: Event) => boolean)>,
     default: true,
+    description: 'Hides on outside click, or a predicate deciding whether to hide.',
+  },
+  shown: {
+    type: Boolean,
+    description: 'Controlled open state.',
   },
-  shown: Boolean,
   handleResize: {
     type: Boolean,
     default: true,
+    description: 'Repositions when the popover content size changes.',
+  },
+  instantMove: {
+    type: Boolean,
+    description: 'Skips transition when the popover moves between placements.',
+  },
+  eagerMount: {
+    type: Boolean,
+    description: 'Mounts popover content immediately instead of on first open.',
+  },
+  popperClass: {
+    type: [String, Array, Object],
+    description: 'Extra class(es) on the floating popover element.',
+  },
+  computeTransformOrigin: {
+    type: Boolean,
+    description: 'Computes transform-origin for scale transitions.',
   },
-  instantMove: Boolean,
-  eagerMount: Boolean,
-  popperClass: [String, Array, Object],
-  computeTransformOrigin: Boolean,
 }
 
 export type PopoverProps = ExtractPublicPropTypes<typeof popoverProps>
@@ -64,13 +117,47 @@ export interface PopoverTheme extends ThemeComponent<PopoverProps, InternalClass
 export default {
   name: 'XPopover',
   validators,
+  docs: {
+    slots: {
+      default: 'Trigger element.',
+      content: 'Popover panel content.',
+    },
+    emits: {
+      show: 'Emitted when the popover starts opening.',
+      hide: 'Emitted when the popover starts closing.',
+      'update:shown': 'Emitted when open state changes.',
+      'apply-show': 'Emitted after the show transition is applied.',
+      'apply-hide': 'Emitted after the hide transition is applied.',
+      'close-group': 'Emitted when a popover group close is requested.',
+      'close-directive': 'Emitted when closed via the close directive.',
+      'auto-hide': 'Emitted when auto-hide closes the popover.',
+      resize: 'Emitted when popover content is resized.',
+    },
+    methods: {
+      show: 'Show the popover.',
+      hide: 'Hide the popover.',
+      toggle: 'Toggle open state.',
+    },
+  },
 }
 </script>
 
 <script setup lang="ts">
-import { type PropType, type ExtractPublicPropTypes, ref } from 'vue'
+import { type PropType, type ExtractPublicPropTypes, ref, inject, computed } from 'vue'
 import { useTheme, type ThemeComponent } from '../../composables/useTheme'
+import { injectButtonGroupKey } from '../../composables/keys'
 import { Dropdown as VDropdown, type Placement, type TriggerEvent } from 'floating-vue'
+import PopoverContentBoundary from './PopoverContentBoundary.vue'
+import type { ButtonGroupInjection } from '../button/ButtonGroup.vue'
+
+const inactiveButtonGroup: ButtonGroupInjection = {
+  isButtonGroup: false,
+  groupProps: {},
+  registerChild: () => {},
+  unregisterChild: () => {},
+  getPosition: () => 'only',
+  childOrder: computed(() => []),
+}
 
 const props = defineProps(popoverProps)
 
@@ -95,6 +182,8 @@ const isOpen = ref(false)
 
 defineExpose({ show, hide, toggle, isOpen })
 
+const buttonGroup = inject(injectButtonGroupKey, inactiveButtonGroup)
+
 const { styles, classes, className } = useTheme('Popover', {}, props)
 </script>
 
@@ -102,7 +191,11 @@ const { styles, classes, className } = useTheme('Popover', {}, props)
   <v-dropdown
     ref="elRef"
     :style="styles"
-    :class="[className, classes.wrapper]"
+    :class="[
+      className,
+      classes.wrapper,
+      { 'inline-flex self-stretch': buttonGroup.isButtonGroup },
+    ]"
     :positioning-disabled="positioningDisabled"
     :placement="placement"
     :disabled="disabled"
@@ -141,15 +234,14 @@ const { styles, classes, className } = useTheme('Popover', {}, props)
   >
     <slot></slot>
     <template #popper>
-      <slot name="content"></slot>
+      <popover-content-boundary>
+        <slot name="content"></slot>
+      </popover-content-boundary>
     </template>
   </v-dropdown>
 </template>
 
-<style lang="postcss">
-/* stylelint-disable no-duplicate-selectors */
-/* stylelint-disable no-descending-specificity */
-/* stylelint-disable selector-class-pattern */
+<style>
 .resize-observer {
   position: absolute;
   top: 0;
@@ -163,18 +255,18 @@ const { styles, classes, className } = useTheme('Popover', {}, props)
   display: block;
   overflow: hidden;
   opacity: 0;
+}
 
-  object {
-    display: block;
-    position: absolute;
-    top: 0;
-    left: 0;
-    height: 100%;
-    width: 100%;
-    overflow: hidden;
-    pointer-events: none;
-    z-index: -1;
-  }
+.resize-observer object {
+  display: block;
+  position: absolute;
+  top: 0;
+  left: 0;
+  height: 100%;
+  width: 100%;
+  overflow: hidden;
+  pointer-events: none;
+  z-index: -1;
 }
 
 .v-popper__popper {

package/src/components/popover/PopoverContainer.vue

@@ -3,6 +3,7 @@ const popoverContainerProps = {
   tag: {
     default: 'div',
     type: String,
+    description: 'Root element tag.',
   },
 }
 
@@ -11,7 +12,14 @@ export type PopoverContainerProps = ExtractPublicPropTypes<typeof popoverContain
 type InternalClasses = 'wrapper'
 export interface PopoverContainerTheme extends ThemeComponent<PopoverContainerProps, InternalClasses> {}
 
-export default { name: 'XPopoverContainer' }
+export default {
+  name: 'XPopoverContainer',
+  docs: {
+    slots: {
+      default: 'Styled container content for popover panels.',
+    },
+  },
+}
 </script>
 
 <script setup lang="ts">

package/src/components/popover/PopoverContentBoundary.vue

@@ -0,0 +1,32 @@
+<script lang="ts">
+export default {
+  name: 'XPopoverContentBoundary',
+  docs: {
+    slots: {
+      default: 'Popover content isolated from parent ButtonGroup provide/inject.',
+    },
+  },
+}
+</script>
+
+<script setup lang="ts">
+import { computed, provide } from 'vue'
+import { injectButtonGroupKey } from '../../composables/keys'
+import type { ButtonGroupInjection } from '../button/ButtonGroup.vue'
+
+/** Isolate popover content from parent ButtonGroup (provide/inject crosses teleport). */
+const inactiveButtonGroup: ButtonGroupInjection = {
+  isButtonGroup: false,
+  groupProps: {},
+  registerChild: () => {},
+  unregisterChild: () => {},
+  getPosition: () => 'only',
+  childOrder: computed(() => []),
+}
+
+provide(injectButtonGroupKey, inactiveButtonGroup)
+</script>
+
+<template>
+  <slot ></slot>
+</template>