@indielayer/ui 2.0.0 → 2.1.0

package/src/components/menu/MenuItem.vue

@@ -7,36 +7,85 @@ const menuItemProps = {
   item: {
     type: Object as PropType<MenuArrayItem>,
     default: () => {},
+    description: 'Item data object. Individual props override matching fields.',
+  },
+  active: {
+    type: Boolean,
+    description: 'Forces active styling when not using router link classes.',
   },
-  active: Boolean,
   attrs: {
     type: Object,
     default: () => {},
+    description: 'Extra HTML attributes merged onto the root element.',
+  },
+  onClick: {
+    type: Function,
+    description: 'Click handler invoked when the item is activated.',
+  },
+  value: {
+    type: [Number, String],
+    description: 'Item value identifier.',
+  },
+  to: {
+    type: [String, Object],
+    description: 'Vue Router location; renders as a router-link when set.',
+  },
+  exact: {
+    type: Boolean,
+    description: 'Requires exact route match for active state.',
+  },
+  href: {
+    type: String,
+    description: 'Native link URL; renders as an anchor when set.',
+  },
+  target: {
+    type: String,
+    description: 'Anchor target when `href` is set.',
+  },
+  label: {
+    type: String,
+    description: 'Visible label text.',
+  },
+  icon: {
+    type: String,
+    description: 'Icon name shown before the label.',
+  },
+  iconRight: {
+    type: String,
+    description: 'Icon name shown after the label.',
+  },
+  loading: {
+    type: Boolean,
+    description: 'Shows a spinner in place of the trailing icon.',
   },
-  onClick: Function,
-  value: [Number, String],
-  to: [String, Object],
-  exact: Boolean,
-  href: String,
-  target: String,
-  label: String,
-  icon: String,
-  iconRight: String,
-  loading: Boolean,
   rounded: {
     type: Boolean,
     default: true,
+    description: 'Applies rounded corners.',
   },
   filled: {
     type: Boolean,
     default: true,
+    description: 'Filled background style.',
+  },
+  selected: {
+    type: Boolean,
+    description: 'Selected visual state.',
   },
-  selected: Boolean,
-  disabled: Boolean,
-  minimal: optionalBooleanProp(),
-  prefix: String,
-  suffix: String,
-  checkbox: optionalBooleanProp(),
+  disabled: {
+    type: Boolean,
+    description: 'Disables interaction.',
+  },
+  minimal: optionalBooleanProp('Hides the label; icon-only layout.'),
+  prefix: {
+    type: String,
+    description: 'Text before the label when no prefix slot is used.',
+  },
+  suffix: {
+    type: String,
+    description: 'Text after the label when no suffix slot is used.',
+  },
+  checkbox: optionalBooleanProp('Shows a checkbox before the label.'),
 }
 
 export type MenuItemProps = ExtractPublicPropTypes<typeof menuItemProps>
@@ -50,6 +99,18 @@ export default {
   validators: {
     ...useCommon.validators(),
   },
+  docs: {
+    slots: {
+      default: 'Label content. Slot prop: item.',
+      prefix: 'Content before the label. Slot prop: item.',
+      suffix: 'Content after the label. Slot prop: item.',
+    },
+    emits: {
+      active: 'Emitted when the item becomes active (route or `active` prop).',
+      click: 'Emitted on item click when not disabled.',
+      'checkbox-click': 'Emitted when the checkbox is clicked.',
+    },
+  },
 }
 </script>
 

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

@@ -4,18 +4,21 @@ import { optionalBooleanProp } from '../../common/props'
 const paginationVariant = ['simple', 'quick', 'dots'] as const
 const paginationProps = {
   ...useCommon.props(),
-  links: optionalBooleanProp(),
+  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).',
   },
 }
 
@@ -31,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

@@ -6,9 +6,13 @@ const paginationItemProps = {
   value: {
     type: Number,
     default: 0,
+    description: 'Page number shown on the control.',
   },
-  selected: Boolean,
-  links: optionalBooleanProp(),
+  selected: {
+    type: Boolean,
+    description: 'Marks this page as the current selection.',
+  },
+  links: optionalBooleanProp('Renders as a link to `?page=` instead of a button.'),
 }
 
 export type PaginationItemProps = ExtractPublicPropTypes<typeof paginationItemProps>
@@ -21,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,7 +234,9 @@ 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>