@pequity/squirrel 8.4.3 → 8.4.5

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,

package/squirrel/components/p-file-upload/p-file-upload.vue

@@ -76,16 +76,31 @@ import { uniq } from 'lodash-es';
 import { computed, onMounted, type PropType, ref, shallowRef } from 'vue';
 import { useToast } from 'vue-toastification';
 
+/**
+ * A file upload component with drag-and-drop support and comprehensive validation.
+ * Provides a user-friendly interface for file selection with visual feedback,
+ * file type validation, size limits, and multiple file support.
+ *
+ * @displayName PFileUpload
+ */
 defineOptions({
   name: 'PFileUpload',
 });
 
 // Props
 const props = defineProps({
+  /**
+   * The current file(s) value (v-model).
+   * Supports both single file and multiple files based on the multiple prop.
+   */
   modelValue: {
     type: [Object, Array] as PropType<FileUploadFile | FileUploadFile[]>,
     default: () => [],
   },
+  /**
+   * Whether multiple files can be selected.
+   * When true, allows selecting multiple files at once.
+   */
   multiple: {
     type: Boolean,
     default: false,
@@ -98,33 +113,73 @@ const props = defineProps({
     type: Array as PropType<string[] | readonly string[]>,
     default: () => [],
   },
+  /**
+   * Whether the file upload is disabled.
+   * Prevents user interaction when true.
+   */
   disabled: {
     type: Boolean,
     default: false,
   },
+  /**
+   * Whether the file upload is required.
+   * Adds required attribute and visual indicator.
+   */
   required: {
     type: Boolean,
     default: false,
   },
+  /**
+   * Error message to display below the file upload.
+   * When provided, the upload area will show error styling.
+   */
   errorMsg: {
     type: String,
     default: '',
   },
+  /**
+   * Text label for the file upload field.
+   * Displayed above the upload area.
+   */
   label: {
     type: String,
     default: '',
   },
+  /**
+   * Maximum file size in bytes.
+   * Files exceeding this size will be rejected with an error message.
+   */
   maxSizeInBytes: {
     type: Number,
     default: 256 * 1000, // 256 KB
   },
+  /**
+   * Maximum number of files that can be uploaded.
+   * Only applies when multiple is true.
+   */
   maxNumberOfFiles: {
     type: Number,
     default: 10,
   },
 });
 
-const emit = defineEmits(['update:modelValue', 'file-removed', 'file-added']);
+const emit = defineEmits<{
+  /**
+   * Emitted when the file selection changes.
+   * @param {FileUploadFile | FileUploadFile[]} value - The new file selection
+   */
+  'update:modelValue': [value: FileUploadFile | FileUploadFile[]];
+  /**
+   * Emitted when a file is removed from the selection.
+   * @param {FileUploadFile} file - The removed file
+   */
+  'file-removed': [file: FileUploadFile];
+  /**
+   * Emitted when new files are added to the selection.
+   * @param {FileUploadFile[]} files - The newly added files
+   */
+  'file-added': [files: FileUploadFile[]];
+}>();
 
 // Data
 const fileInputRef = shallowRef<HTMLInputElement>();
@@ -217,9 +272,9 @@ const uploadFile = (e: Event | DragEvent) => {
     return;
   }
 
-  const validatedFiles = props.fileTypes ? validateFiles(Array.from(f)) : f;
+  const validatedFiles = props.fileTypes ? validateFiles(Array.from(f)) : Array.from(f);
 
-  files.value = props.multiple ? [...files.value, ...validatedFiles] : (validatedFiles as FileUploadFile[]);
+  files.value = props.multiple ? [...files.value, ...validatedFiles] : validatedFiles;
 
   emit('file-added', validatedFiles);
 };

package/squirrel/components/p-icon/p-icon.types.ts

@@ -2,7 +2,7 @@ export const P_ICON_ALIASES = {
   delete: 'octicon:trash-24',
   edit: 'simple-line-icons:pencil',
   send: 'mingcute:send-plane-fill',
-  settings: 'heroicons:cog-8-tooth-20-solid',
+  settings: 'heroicons:cog-8-tooth',
   empty: 'ph:empty',
   'chevron-left': 'material-symbols:chevron-left-rounded',
   'chevron-right': 'material-symbols:chevron-right-rounded',
@@ -24,7 +24,7 @@ export const P_ICON_ALIASES = {
   copy: 'ph:copy',
   plus: 'ic:outline-plus',
   add: 'ic:outline-plus',
-  more: 'lineicons:more-alt',
+  more: 'ep:more-filled',
   filters: 'mage:filter',
   'bar-chart': 'material-symbols:bar-chart-4-bars-rounded',
   list: 'material-symbols:format-list-bulleted',
@@ -33,6 +33,7 @@ export const P_ICON_ALIASES = {
   download: 'tdesign:download',
   upload: 'tdesign:upload',
   info: 'streamline:information-circle',
+  help: 'ph:question',
   search: 'streamline:magnifying-glass-solid',
 } as const;
 

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

@@ -7,15 +7,31 @@ import 'iconify-icon';
 import { P_ICON_ALIASES, type PIconAlias } from '@squirrel/components/p-icon/p-icon.types';
 import { type IconifyIconProperties } from 'iconify-icon';
 
+/**
+ * An icon component that renders icons using Iconify.
+ * Supports both custom icon aliases and standard Iconify icon names.
+ * Inherits all IconifyIconProperties for full icon customization.
+ *
+ * @displayName PIcon
+ */
 defineOptions({
   name: 'PIcon',
 });
 
 // eslint-disable-next-line @typescript-eslint/consistent-type-definitions
 interface Props extends /* @vue-ignore */ IconifyIconProperties {
+  /**
+   * The icon to display. Can be an icon alias or any valid Iconify icon name.
+   * Icon aliases provide consistent icon naming across the application.
+   */
   icon: PIconAlias | (string & {});
 }
 
+/**
+ * Checks if the provided icon is an icon alias.
+ * @param {string} icon - The icon name to check
+ * @returns {boolean} True if the icon is an icon alias
+ */
 const isPIcon = (icon: string): icon is PIconAlias => !!P_ICON_ALIASES[icon as PIconAlias];
 
 defineProps<Props>();

package/squirrel/components/p-info-icon/p-info-icon.vue

@@ -10,11 +10,30 @@
 <script setup lang="ts">
 import PIcon from '@squirrel/components/p-icon/p-icon.vue';
 
+/**
+ * An info icon component that displays a tooltip on hover.
+ * Shows an info icon with customizable tooltip content.
+ * Tooltip appears after 750ms delay and disappears immediately on mouse leave.
+ *
+ * @displayName PInfoIcon
+ */
 defineOptions({
   name: 'PInfoIcon',
 });
 
+defineSlots<{
+  /**
+   * Custom tooltip content - overrides the text prop.
+   * Use this slot for custom tooltip content instead of the text prop.
+   */
+  default?: () => unknown;
+}>();
+
 type Props = {
+  /**
+   * Text content for the tooltip.
+   * If not provided, you can use the default slot instead.
+   */
   text?: string | null;
 };
 

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

@@ -15,14 +15,42 @@ import { useInputClasses } from '@squirrel/composables/useInputClasses';
 import VueDatePicker, { type VueDatePickerProps } from '@vuepic/vue-datepicker';
 import { computed, type StyleValue, useAttrs } from 'vue';
 
+/**
+ * An inline date picker component that displays a calendar for date selection.
+ * Wraps VueDatePicker with consistent styling and form integration.
+ * Supports custom labels, error states, and inherits all VueDatePicker props.
+ *
+ * @displayName PInlineDatePicker
+ */
 defineOptions({
   name: 'PInlineDatePicker',
   inheritAttrs: false,
 });
 
+defineSlots<{
+  /**
+   * Custom label content - overrides the label prop.
+   * @param {string} label - The label text
+   * @param {string} label-classes - CSS classes for the label
+   */
+  label?: (props: { label: string; labelClasses: string }) => unknown;
+}>();
+
 type Props = {
+  /**
+   * Text label for the date picker field.
+   * If not provided, you can use the label slot instead.
+   */
   label?: string;
+  /**
+   * Error message to display below the date picker.
+   * When provided, the date picker will show error styling.
+   */
   errorMsg?: string;
+  /**
+   * Whether the date picker is required.
+   * Adds required attribute and visual indicator.
+   */
   required?: boolean;
 } & VueDatePickerProps;
 
@@ -38,6 +66,10 @@ const props = withDefaults(defineProps<Props>(), {
   weekStart: 0,
 });
 
+/**
+ * The selected date value (v-model).
+ * Supports two-way binding for form inputs.
+ */
 const model = defineModel<Date | string | null>({ default: '' });
 
 // Data

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

@@ -7,6 +7,7 @@
     </slot>
     <div class="relative w-full">
       <div v-if="!!$slots.prefix">
+        <!-- Slot for content displayed before the input field -->
         <slot name="prefix"></slot>
       </div>
       <input
@@ -17,6 +18,7 @@
         @input="(event: Event) => $emit('update:modelValue', (event.target as HTMLInputElement).value)"
       />
       <div v-if="!!$slots.suffix">
+        <!-- Slot for content displayed after the input field -->
         <slot name="suffix"></slot>
       </div>
     </div>
@@ -36,18 +38,56 @@ type InputType = (typeof INPUT_TYPES)[InputTypeKeys];
 </script>
 
 <script setup lang="ts">
+/**
+ * A versatile input component that supports various types, sizes, and states.
+ * Provides consistent styling and behavior across different input types.
+ * Supports custom labels, error states, and prefix/suffix content.
+ */
 defineOptions({
   name: 'PInput',
   inheritAttrs: false,
 });
 
-defineEmits(['update:modelValue']);
+defineEmits<{
+  /**
+   * Emitted when the input value changes.
+   * @param {string} value - The new input value
+   */
+  'update:modelValue': [value: string];
+}>();
+
+defineSlots<{
+  /**
+   * Custom label content - overrides the label prop.
+   * @param {string} label - The label text
+   * @param {string} label-classes - CSS classes for the label
+   */
+  label?: (props: { label: string; labelClasses: string }) => unknown;
+
+  /**
+   * Content displayed before the input field.
+   */
+  prefix?: () => unknown;
+
+  /**
+   * Content displayed after the input field.
+   */
+  suffix?: () => unknown;
+}>();
 
 const props = defineProps({
+  /**
+   * The current value of the input (v-model).
+   * Supports two-way binding for form inputs.
+   */
   modelValue: {
     type: [String, Number, Boolean, null] as PropType<string | number | boolean | null>,
     default: '',
   },
+  /**
+   * The type of the input field.
+   * Valid values: 'text', 'password'
+   */
   type: {
     type: String as PropType<InputType>,
     default: INPUT_TYPES.TEXT,
@@ -55,18 +95,34 @@ const props = defineProps({
       return Object.values(INPUT_TYPES).includes(value);
     },
   },
+  /**
+   * Text label for the input field.
+   * If not provided, you can use the label slot instead.
+   */
   label: {
     type: String,
     default: '',
   },
+  /**
+   * Error message to display below the input.
+   * When provided, the input will show error styling.
+   */
   errorMsg: {
     type: String,
     default: '',
   },
+  /**
+   * Whether the input is required.
+   * Adds required attribute and visual indicator.
+   */
   required: {
     type: Boolean,
     default: false,
   },
+  /**
+   * The size of the input - affects padding, font size, and spacing.
+   * Valid values: 'sm', 'md', 'lg'
+   */
   size: {
     type: String as PropType<Size>,
     default: 'md',
@@ -74,6 +130,10 @@ const props = defineProps({
       return SIZES.includes(value);
     },
   },
+  /**
+   * Whether the input has rounded corners.
+   * Applies rounded styling to the input field.
+   */
   rounded: {
     type: Boolean,
     default: false,