@pequity/squirrel 8.4.4 → 8.4.5

package/squirrel/components/p-alert/p-alert.vue

@@ -26,11 +26,35 @@ const ALERT_TYPES = {
 </script>
 
 <script setup lang="ts">
+/**
+ * An alert component that displays informational, warning, error, or success messages.
+ * Supports different alert types with appropriate styling and icons.
+ * Provides customizable content through slots.
+ *
+ * @displayName PAlert
+ */
 defineOptions({
   name: 'PAlert',
 });
 
+defineSlots<{
+  /**
+   * Custom icon slot - use this to override the default alert type icon.
+   * If not provided, a default icon will be shown based on the alert type.
+   */
+  icon?: () => unknown;
+
+  /**
+   * Default slot - the main content of the alert message.
+   * This should contain the text or HTML to display in the alert.
+   */
+  default?: () => unknown;
+}>();
+
 const props = defineProps({
+  /**
+   * The type of the alert which determines its appearance and icon
+   */
   type: {
     type: String as PropType<keyof typeof ALERT_TYPES>,
     default: 'info',

package/squirrel/components/p-avatar/p-avatar.vue

@@ -17,10 +17,16 @@
 <script lang="ts">
 import { computed, type PropType, ref, watch } from 'vue';
 
+/**
+ * Available avatar shapes
+ */
 const SHAPES = ['rectangle', 'circle'] as const;
 
 type Shape = (typeof SHAPES)[number];
 
+/**
+ * CSS classes for each avatar shape
+ */
 const SHAPE_CLASSES = {
   rectangle: 'rounded-lg',
   circle: 'rounded-full',
@@ -28,28 +34,50 @@ const SHAPE_CLASSES = {
 </script>
 
 <script setup lang="ts">
+/**
+ * An avatar component that displays user images or fallback text.
+ * Supports different shapes and handles image loading errors gracefully.
+ *
+ * @displayName PAvatar
+ */
 defineOptions({
   name: 'PAvatar',
 });
 
 const props = defineProps({
+  /**
+   * The shape of the avatar
+   */
   shape: {
     type: String as PropType<Shape>,
     default: 'circle',
     validator: (value: Shape) => SHAPES.includes(value),
   },
+  /**
+   * URL of the image to display
+   */
   imageSrc: {
     type: String,
     default: '',
   },
+  /**
+   * Text to display when image is not available
+   * Also used as the alt text for the image
+   */
   label: {
     type: String,
     required: true,
   },
+  /**
+   * Additional CSS classes to apply to the image
+   */
   imageClass: {
     type: String,
     default: '',
   },
+  /**
+   * Additional CSS classes to apply to the label container
+   */
   labelClass: {
     type: String,
     default: '',

package/squirrel/components/p-btn/p-btn.vue

@@ -21,8 +21,14 @@ import { tv, type VariantProps } from 'tailwind-variants';
 import { computed, type PropType, useAttrs } from 'vue';
 import { type RouteLocationRaw } from 'vue-router';
 
+/**
+ * Type for the icon prop
+ */
 type Icon = InstanceType<typeof PIcon>['$props']['icon'];
 
+/**
+ * Button styles configuration using tailwind-variants
+ */
 const btnClasses = {
   slots: {
     button:
@@ -91,8 +97,19 @@ const btnClasses = {
 
 const btn = tv(btnClasses);
 
+/**
+ * Available button types
+ */
 const BUTTON_TYPES = Object.keys(btnClasses.variants.type);
+
+/**
+ * Native button types (HTML attribute values)
+ */
 const BUTTON_NATIVE_TYPES = ['button', 'submit', 'reset'] as const;
+
+/**
+ * Loader sizes mapped to button sizes
+ */
 const LOADER_SIZES = { sm: 24, md: 30, lg: 40 } as const satisfies { [key in Size]: number };
 
 type ButtonNativeType = (typeof BUTTON_NATIVE_TYPES)[number];
@@ -100,10 +117,25 @@ type ButtonType = NonNullable<VariantProps<typeof btn>['type']>;
 </script>
 
 <script setup lang="ts">
+/**
+ * A versatile button component with multiple variants, sizes, and states.
+ * Supports different button types, loading states, icons, and link functionality.
+ * Built with tailwind-variants for consistent styling and theming.
+ *
+ * @displayName PBtn
+ */
 defineOptions({
   name: 'PBtn',
 });
 
+defineSlots<{
+  /**
+   * Default slot - the content of the button.
+   * This should contain the text or HTML to display inside the button.
+   */
+  default?: () => void;
+}>();
+
 const attrs = useAttrs();
 
 const props = defineProps({
@@ -166,6 +198,9 @@ const props = defineProps({
     type: String as PropType<Icon>,
     default: '',
   },
+  /**
+   * The icon to display on the right side of the button
+   */
   iconRight: {
     type: String as PropType<Icon>,
     default: '',

package/squirrel/components/p-card/p-card.vue

@@ -5,14 +5,37 @@
         {{ title }}
       </div>
     </slot>
-    <slot />
+    <slot></slot>
   </div>
 </template>
 
 <script setup lang="ts">
+/**
+ * A card component that provides a container for content with optional header and footer.
+ * Supports different variants and customizable styling.
+ *
+ * @displayName PCard
+ */
 defineOptions({ name: 'PCard' });
 
+defineSlots<{
+  /**
+   * Title slot - custom content for the card title.
+   * Receives the titleClass prop for consistent styling.
+   */
+  title?: (props: { titleClass: string }) => void;
+
+  /**
+   * Default slot - the main content of the card.
+   */
+  default?: () => void;
+}>();
+
 defineProps({
+  /**
+   * The title of the card - displayed at the top
+   * If not provided, you can use the title slot instead
+   */
   title: {
     type: String,
     default: '',

package/squirrel/components/p-checkbox/p-checkbox.vue

@@ -32,13 +32,35 @@ defineOptions({
   inheritAttrs: false,
 });
 
-defineEmits(['update:modelValue']);
+defineSlots<{
+  /**
+   * Content displayed before the checkbox
+   */
+  'label-before'?: () => void;
+
+  /**
+   * Custom label content - overrides the label prop
+   */
+  label?: () => void;
+}>();
+
+defineEmits<{
+  /** Emitted when the checkbox value changes */
+  'update:modelValue': [val: boolean];
+}>();
 
 defineProps({
+  /**
+   * The checked state of the checkbox (v-model)
+   */
   modelValue: {
     type: Boolean,
     default: false,
   },
+  /**
+   * Text label for the checkbox
+   * Ignored if using the label slot
+   */
   label: {
     type: String,
     default: '',

package/squirrel/components/p-chips/p-chips.vue

@@ -31,18 +31,42 @@
 import { isObject } from 'lodash-es';
 import { defineComponent } from 'vue';
 
+/**
+ * A chips component that displays a horizontal list of items with overflow handling.
+ * Automatically calculates how many chips can fit in the available space and shows
+ * an overflow indicator when there are more items than can be displayed.
+ * Supports custom item text properties and before/after slot content.
+ *
+ * @displayName PChips
+ */
 export default defineComponent({
   name: 'PChips',
   props: {
+    /**
+     * Array of items to display as chips.
+     * Can be strings or objects with a text property.
+     */
     items: {
       type: Array,
       default: () => [],
     },
+    /**
+     * Property name to use as the item display text.
+     * Used when items are objects to extract the text value.
+     */
     itemText: {
       type: String,
       default: 'text',
     },
   },
+  /**
+   * Emitted when a chip is clicked.
+   * @param {any} item - The clicked item
+   */
+  /**
+   * Emitted when the overflow indicator is clicked.
+   * Indicates that there are more chips than can be displayed.
+   */
   emits: ['click:chip', 'click:overflow'],
   data() {
     return {

package/squirrel/components/p-close-btn/p-close-btn.vue

@@ -11,13 +11,28 @@
 <script setup lang="ts">
 import { type PropType } from 'vue';
 
+/**
+ * A close button component with different visual variants.
+ * Provides a consistent close button interface with hover effects and accessibility features.
+ * Supports different styling variants for various UI contexts.
+ *
+ * @displayName PCloseBtn
+ */
 defineOptions({
   name: 'PCloseBtn',
 });
 
+/**
+ * Available visual variants for the close button.
+ */
 type Variant = 'transparent' | 'gray' | 'dark';
 
 defineProps({
+  /**
+   * The visual variant of the close button.
+   * Controls the background color and hover effects.
+   * Valid values: 'transparent', 'gray', 'dark'
+   */
   variant: {
     type: String as PropType<Variant>,
     default: 'transparent',

package/squirrel/components/p-date-picker/p-date-picker.vue

@@ -19,14 +19,33 @@ import PInput from '@squirrel/components/p-input/p-input.vue';
 import VueDatePicker, { type VueDatePickerProps } from '@vuepic/vue-datepicker';
 import { computed, useAttrs } from 'vue';
 
+/**
+ * A date picker component that displays a dropdown calendar for date selection.
+ * Wraps VueDatePicker with a custom input field using PInput component.
+ * Supports custom labels, error states, and inherits all VueDatePicker props.
+ *
+ * @displayName PDatePicker
+ */
 defineOptions({
   name: 'PDatePicker',
   inheritAttrs: false,
 });
 
 type Props = {
+  /**
+   * Text label for the date picker field.
+   * Passed to the underlying PInput component.
+   */
   label?: string;
+  /**
+   * Error message to display below the date picker.
+   * Passed to the underlying PInput component and shows error styling.
+   */
   errorMsg?: string;
+  /**
+   * Whether the date picker is required.
+   * Passed to the underlying PInput component and adds visual indicator.
+   */
   required?: boolean;
 } & VueDatePickerProps;
 
@@ -44,6 +63,10 @@ const props = withDefaults(defineProps<Props>(), {
   format: 'dd-MMM-yyyy',
 });
 
+/**
+ * The selected date value (v-model).
+ * Supports two-way binding for form inputs.
+ */
 const model = defineModel<Date | string | null>({ default: '' });
 
 // Data
@@ -70,7 +93,6 @@ const inputPropsAndAttrs = computed(() => {
   return res;
 });
 
-// Methods
 const handleInput = (e: Event, onInputFn: (e: Event) => void, onClearFn: (e: Event) => void) => {
   if (e.target instanceof HTMLInputElement && e.target.value === '') {
     onClearFn(e);

package/squirrel/components/p-drawer/p-drawer.vue

@@ -84,6 +84,13 @@ import PAlert from '@squirrel/components/p-alert/p-alert.vue';
 import PCloseBtn from '@squirrel/components/p-close-btn/p-close-btn.vue';
 import { defineComponent } from 'vue';
 
+/**
+ * A drawer component that slides in from the side with backdrop and animations.
+ * Provides a side panel interface with customizable position, width, and content areas.
+ * Supports teleporting to different DOM elements and comprehensive lifecycle events.
+ *
+ * @displayName PDrawer
+ */
 export default defineComponent({
   name: 'PDrawer',
   components: {
@@ -91,66 +98,132 @@ export default defineComponent({
     PCloseBtn,
   },
   props: {
+    /**
+     * Target element to append the drawer to.
+     * Usually 'body' for proper z-index stacking.
+     */
     appendTo: {
       type: String,
       default: 'body',
     },
+    /**
+     * Title displayed in the drawer header.
+     * Used for accessibility and visual identification.
+     */
     title: {
       type: String,
       default: '',
     },
+    /**
+     * Whether the drawer content is disabled.
+     * Prevents user interaction with drawer content.
+     */
     disabled: {
       type: Boolean,
       default: false,
     },
+    /**
+     * Error message to display in the drawer.
+     * Shows an error alert above the drawer content.
+     */
     errorMsg: {
       type: String,
       default: '',
     },
+    /**
+     * The position of the drawer on the screen.
+     * Valid values: 'left', 'right'
+     * @values left, right
+     */
     position: {
       type: String,
       default: 'right',
     },
+    /**
+     * Base z-index for the drawer.
+     * Higher values ensure the drawer appears above other content.
+     */
     zIndex: {
       type: Number,
       default: 900,
     },
+    /**
+     * Inline styles for the drawer element.
+     * Applied directly to the drawer element.
+     */
     drawerStyle: {
       type: Object,
       default: () => ({}),
     },
+    /**
+     * CSS class for the drawer container.
+     * Controls the base styling of the drawer.
+     */
     drawerClass: {
       type: String,
       default: 'drawer',
     },
+    /**
+     * CSS class for the drawer entrance animation.
+     * Overrides the default position-based animation.
+     */
     inClass: {
       type: String,
       default: '',
     },
+    /**
+     * CSS class for the drawer exit animation.
+     * Overrides the default position-based animation.
+     */
     outClass: {
       type: String,
       default: '',
     },
+    /**
+     * Whether the drawer should be mounted immediately.
+     * Useful for drawers that are always present in the DOM.
+     */
     live: {
       type: Boolean,
       default: false,
     },
+    /**
+     * Controls the visibility of the drawer (v-model).
+     * Supports two-way binding for drawer state.
+     */
     modelValue: {
       type: Boolean,
       default: false,
     },
+    /**
+     * Accessibility label for the close button.
+     * Used by screen readers for better accessibility.
+     */
     closeLabel: {
       type: String,
       default: 'Close',
     },
+    /**
+     * Whether to show the backdrop behind the drawer.
+     * When true, displays a semi-transparent overlay.
+     */
     showBackdrop: {
       type: Boolean,
       default: false,
     },
+    /**
+     * Whether the drawer can be closed by user interaction.
+     * Controls close button visibility and backdrop click behavior.
+     */
     enableClose: {
       type: Boolean,
       default: true,
     },
+    /**
+     * Width of the drawer.
+     * Must be a valid CSS width value ending with 'px'.
+     * @values 460px, 600px, 800px, etc.
+     */
     width: {
       type: String,
       default: '460px',
@@ -159,6 +232,28 @@ export default defineComponent({
       },
     },
   },
+  /**
+   * Emitted before the drawer starts opening.
+   */
+  /**
+   * Emitted when the drawer is opening (animation in progress).
+   */
+  /**
+   * Emitted when the drawer has finished opening.
+   */
+  /**
+   * Emitted before the drawer starts closing.
+   */
+  /**
+   * Emitted when the drawer is closing (animation in progress).
+   */
+  /**
+   * Emitted when the drawer has finished closing.
+   */
+  /**
+   * Emitted when the drawer visibility changes (v-model).
+   * @param {boolean} value - The new visibility state
+   */
   emits: ['update:modelValue', 'before-open', 'opening', 'opened', 'before-close', 'closing', 'closed'],
   data() {
     return {

package/squirrel/components/p-dropdown/p-dropdown.vue

@@ -90,6 +90,9 @@ import {
 } from '@squirrel/utils/listKeyboardNavigation';
 import { defineComponent } from 'vue';
 
+/**
+ * Represents the VPopper component structure for type safety.
+ */
 type VPopper = {
   $refs: {
     popperContent: {
@@ -120,6 +123,13 @@ const nextFrame = () => {
   );
 };
 
+/**
+ * A dropdown component that extends VDropdown with keyboard navigation and Pequity design system styling.
+ * Provides dropdown menu functionality with arrow key navigation, escape key closing, and customizable styling.
+ * Supports both dropdown lists and generic popover content with comprehensive accessibility features.
+ *
+ * @displayName PDropdown
+ */
 export default defineComponent({
   name: 'PDropdown',
   inheritAttrs: false,
@@ -134,6 +144,7 @@ export default defineComponent({
     },
     /**
      * Enables closing the dropdown with the Escape key.
+     * When true, pressing Escape will close the dropdown.
      */
     enableCloseOnEsc: {
       type: Boolean,
@@ -141,7 +152,7 @@ export default defineComponent({
     },
     /**
      * v-tooltip wraps the popper trigger with a div that has `display: inline-block` set by default.
-     * This prop is used to override the CSS style of that wrapper div
+     * This prop is used to override the CSS style of that wrapper div.
      */
     triggerStyle: {
       type: Object,

package/squirrel/components/p-dropdown-select/p-dropdown-select.vue

@@ -224,6 +224,13 @@ import {
 type AnyValue = string | number | boolean | null | undefined | Record<string, unknown>;
 type AnyObject = Record<string, AnyValue>;
 
+/**
+ * A dropdown select component with advanced features like search, multiple selection, and virtual scrolling.
+ * Provides a customizable dropdown interface with support for single/multiple selection, search filtering,
+ * pill display for multiple selections, and virtual scrolling for large datasets.
+ *
+ * @displayName PDropdownSelect
+ */
 defineOptions({
   name: 'PDropdownSelect',
   inheritAttrs: false,
@@ -241,6 +248,10 @@ defineSlots<{
 const emit = defineEmits(['update:modelValue', 'select', 'create']);
 
 const props = defineProps({
+  /**
+   * The selected value(s) for the dropdown (v-model).
+   * Can be a single value or array of values depending on multiple prop.
+   */
   modelValue: {
     type: [String, Number, Boolean, Array, Object] as PropType<ModelValue>,
     default: null,
@@ -262,18 +273,30 @@ const props = defineProps({
     type: Array as PropType<AnyValue[] | AnyObject[]>,
     default: () => [],
   },
+  /**
+   * Label text displayed above the dropdown.
+   */
   label: {
     type: String,
     default: '',
   },
+  /**
+   * Error message to display below the dropdown.
+   */
   errorMsg: {
     type: String,
     default: '',
   },
+  /**
+   * Whether the field is required.
+   */
   required: {
     type: Boolean,
     default: false,
   },
+  /**
+   * The size of the dropdown component.
+   */
   size: {
     type: String as PropType<Size>,
     default: 'md',
@@ -310,26 +333,44 @@ const props = defineProps({
     type: Number,
     default: 7,
   },
+  /**
+   * Additional attributes to apply to the dropdown menu.
+   */
   dropdownMenuAttrs: {
     type: Object,
     default: () => ({}),
   },
+  /**
+   * CSS classes to apply to the dropdown menu.
+   */
   dropdownMenuClass: {
     type: String,
     default: 'overflow-x-hidden',
   },
+  /**
+   * Inline styles to apply to the dropdown menu.
+   */
   dropdownMenuStyle: {
     type: Object,
     default: () => ({}),
   },
+  /**
+   * Props to pass to the underlying PDropdown component.
+   */
   pDropdownProps: {
     type: Object,
     default: () => ({}),
   },
+  /**
+   * Whether to enable search functionality within the dropdown.
+   */
   searchable: {
     type: Boolean,
     default: false,
   },
+  /**
+   * Whether to show a clear button when items are selected.
+   */
   clearable: {
     type: Boolean,
     default: false,