@pequity/squirrel 8.4.3 → 8.4.5

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

@@ -10,6 +10,7 @@
     </div>
     <div class="relative w-full">
       <div v-if="!!$slots.prefix || prefixString">
+        <!-- Slot for custom prefix content - overrides the prefixString prop -->
         <slot name="prefix">
           <div
             :class="[{ 'absolute left-3 flex items-center': prefixString }, prefixString ? prefixClasses[size] : '']"
@@ -53,30 +54,82 @@ const prefixClasses: Record<Size, string> = {
   lg: 'text-lg h-12 left-5',
 };
 
+/**
+ * A specialized input component for numeric values with currency formatting.
+ * Provides number-only input with configurable currency display, precision, and formatting options.
+ * Supports custom labels, error states, tooltips, and prefix content.
+ * Uses vue-currency-input for robust number handling and formatting.
+ */
 defineOptions({
   name: 'PInputNumber',
   inheritAttrs: false,
 });
 
-const emit = defineEmits(['update:modelValue', 'change']);
+const emit = defineEmits<{
+  /**
+   * Emitted when the numeric value changes.
+   * @param {number | null} value - The new numeric value
+   */
+  'update:modelValue': [value: number | null];
+  /**
+   * Emitted when the value changes (includes the new value).
+   * @param {number | null} value - The new numeric value
+   */
+  change: [value: number | null];
+}>();
+
+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;
+
+  /**
+   * Custom prefix content - overrides the prefixString prop.
+   * Use this slot for custom prefix content instead of the prefixString prop.
+   */
+  prefix?: () => unknown;
+}>();
 
 const props = defineProps({
+  /**
+   * The current numeric value of the input (v-model).
+   * Supports two-way binding for form inputs.
+   */
   modelValue: {
     type: [Number, String] as PropType<number | string | null | undefined>,
     default: null,
   },
+  /**
+   * 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',
@@ -84,14 +137,26 @@ const props = defineProps({
       return SIZES.includes(value);
     },
   },
+  /**
+   * Whether to select all text when the input receives focus.
+   * Provides better UX for number input fields.
+   */
   selectOnClick: {
     type: Boolean,
     default: true,
   },
+  /**
+   * Text for the info tooltip displayed next to the label.
+   * Uses PInfoIcon component for consistent tooltip styling.
+   */
   tooltipText: {
     type: String,
     default: '',
   },
+  /**
+   * String to display as prefix in the input field.
+   * Can be overridden by the prefix slot for custom content.
+   */
   prefixString: {
     type: String,
     default: '',
@@ -155,9 +220,21 @@ const style = computed(() => {
   return attrs.style as StyleValue;
 });
 
+/**
+ * Handles focus event on the input field.
+ * Selects all text if selectOnClick is enabled.
+ * @param {void} - No parameters
+ * @returns {void}
+ */
 const focus = () => {
   props.selectOnClick && inputRef.value.select();
 };
 
+/**
+ * Programmatically sets the numeric value of the input.
+ * Useful for external control of the input value.
+ * @param {number | null} value - The numeric value to set
+ * @returns {void}
+ */
 defineExpose({ setValue });
 </script>

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

@@ -11,6 +11,7 @@
 <script setup lang="ts">
 import { type Size } from '@squirrel/components/p-btn/p-btn.types';
 import PInputNumber from '@squirrel/components/p-input-number/p-input-number.vue';
+import { toNumberOrNull } from '@squirrel/utils/number';
 import { isNumber } from 'lodash-es';
 import { computed, type PropType } from 'vue';
 
@@ -20,25 +21,48 @@ const prefixClasses: Record<Size, string> = {
   lg: 'text-lg h-12 left-5',
 };
 
+/**
+ * A percentage input component that wraps PInputNumber with automatic decimal conversion.
+ * Displays values as percentages (multiplied by 100) while storing the actual decimal value.
+ * Provides a consistent interface for percentage inputs with proper formatting and validation.
+ *
+ * @displayName PInputPercent
+ */
 defineOptions({
   name: 'PInputPercent',
 });
 
 const props = defineProps({
+  /**
+   * The current value (v-model).
+   * Stored as a decimal (0.5 = 50%) but displayed as a percentage.
+   * Supports two-way binding for form inputs.
+   */
   modelValue: {
     type: [Number, String] as PropType<number | string | null | undefined>,
     default: null,
   },
+  /**
+   * The size of the input field.
+   * Valid values: 'sm', 'md', 'lg'
+   * @values sm, md, lg
+   */
   size: {
     type: String as PropType<Size>,
     default: 'md',
   },
 });
 
-const emit = defineEmits(['update:modelValue']);
+const emit = defineEmits<{
+  /**
+   * Emitted when the percentage value changes.
+   * @param {number | null} value - The new decimal value
+   */
+  'update:modelValue': [value: number | null];
+}>();
 
 const convertedValue = computed({
-  get: () => (isNumber(props.modelValue) ? props.modelValue * 100 : props.modelValue),
-  set: (nV) => emit('update:modelValue', isNumber(nV) ? nV / 100 : nV),
+  get: () => (isNumber(props.modelValue) ? props.modelValue * 100 : toNumberOrNull(props.modelValue)),
+  set: (nV) => emit('update:modelValue', isNumber(nV) ? nV / 100 : toNumberOrNull(nV)),
 });
 </script>

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

@@ -40,23 +40,47 @@ import PIcon from '@squirrel/components/p-icon/p-icon.vue';
 import PInput from '@squirrel/components/p-input/p-input.vue';
 import { type PropType, ref, useTemplateRef, watch } from 'vue';
 
-type PInputInstance = InstanceType<typeof PInput>;
-
+/**
+ * A search input component that provides a specialized input field for search functionality.
+ * Features include a search icon prefix, optional enter key icon, clear button,
+ * and automatic focus management. Built on top of PInput with search-specific styling
+ * and behavior.
+ *
+ * @displayName PInputSearch
+ */
 defineOptions({
   name: 'PInputSearch',
   inheritAttrs: false,
 });
 
+type PInputInstance = InstanceType<typeof PInput>;
+
 const emit = defineEmits<{
+  /**
+   * Emitted when the search query value changes.
+   * @param {string} value - The new search query
+   */
   'update:modelValue': [value: string];
+  /**
+   * Emitted when the enter key is pressed.
+   * @param {string} value - The current search query
+   */
   enter: [value: string];
 }>();
 
 const props = defineProps({
+  /**
+   * The search query value (v-model).
+   * Controls the input field content and visibility of the clear button.
+   */
   modelValue: {
     type: String,
     default: '',
   },
+  /**
+   * The size of the search input.
+   * Affects the overall dimensions and icon positioning.
+   */
   size: {
     type: String as PropType<Size>,
     default: 'md',
@@ -64,6 +88,10 @@ const props = defineProps({
       return SIZES.includes(value);
     },
   },
+  /**
+   * Whether to show the enter key icon when the input is focused.
+   * Provides visual feedback that pressing enter will trigger a search.
+   */
   showEnterIcon: {
     type: Boolean,
     default: false,

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

@@ -12,9 +12,22 @@ import { isExternalLink } from '@squirrel/utils/link';
 import { sanitizeUrl } from '@squirrel/utils/sanitization';
 import { RouterLink, type RouterLinkProps } from 'vue-router';
 
+/**
+ * A link component that intelligently handles both internal and external links.
+ * Automatically detects external URLs and renders them as anchor tags with
+ * proper security attributes, while internal links use Vue Router's RouterLink.
+ * Supports all RouterLink props for internal navigation.
+ *
+ * @displayName PLink
+ */
 defineOptions({
   name: 'PLink',
 });
 
+/**
+ * All props from Vue Router's RouterLink component are supported.
+ * The component automatically handles external vs internal link detection
+ * and applies appropriate rendering and security measures.
+ */
 defineProps<RouterLinkProps>();
 </script>

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

@@ -33,12 +33,19 @@ import { usePLoading } from '@squirrel/components/p-loading/usePLoading';
 import { isComponent } from '@squirrel/utils/component';
 import { onBeforeUnmount, ref, toValue, watch } from 'vue';
 
-const textDivClass = `flex h-8 justify-center gap-x-1.5 overflow-hidden whitespace-nowrap px-6 pt-1 text-sm font-semibold text-p-purple-60`;
-
+/**
+ * A loading component that displays a loading rectangle at the top center of the screen.
+ * Shows a customizable content area with smooth animations and dynamic sizing.
+ * Supports both text content and component content with automatic dimension calculation.
+ *
+ * @displayName PLoading
+ */
 defineOptions({
   name: 'PLoading',
 });
 
+const textDivClass = `flex h-8 justify-center gap-x-1.5 overflow-hidden whitespace-nowrap px-6 pt-1 text-sm font-semibold text-p-purple-60`;
+
 const { show, content, props: componentProps, loadingHide } = usePLoading();
 const dimsReference = ref<HTMLElement | null>(null);
 const width = ref(0);

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

@@ -90,99 +90,235 @@ const FOCUSABLE_ELEMENTS =
   'a[href], area[href], input:not([disabled]), select:not([disabled]), textarea:not([disabled]), button:not([disabled]), [tabindex]:not([tabindex="-1"])';
 let animatingZIndex = 0;
 
+/**
+ * A modal dialog component with advanced features like animations, focus management, and accessibility.
+ * Provides a teleported modal interface with backdrop, customizable styling, and lifecycle events.
+ * Supports both controlled and uncontrolled modes with proper keyboard navigation.
+ *
+ * @displayName PModal
+ */
 defineOptions({
   name: 'PModal',
 });
 
+defineSlots<{
+  /**
+   * Default content slot for the modal body.
+   */
+  default?: () => unknown;
+  /**
+   * Custom title wrapper content.
+   */
+  'title-wrapper'?: () => unknown;
+  /**
+   * Custom content wrapper.
+   */
+  'content-wrapper'?: () => unknown;
+  /**
+   * Custom footer content.
+   */
+  footer?: () => unknown;
+  /**
+   * Custom footer wrapper.
+   */
+  'footer-wrapper'?: () => unknown;
+}>();
+
 const emit = defineEmits<{
+  /**
+   * Emitted before the modal starts opening.
+   */
   'before-open': [];
+  /**
+   * Emitted when the modal is opening (animation in progress).
+   */
   opening: [];
+  /**
+   * Emitted when the modal has finished opening.
+   */
   opened: [];
+  /**
+   * Emitted before the modal starts closing.
+   */
   'before-close': [];
+  /**
+   * Emitted when the modal is closing (animation in progress).
+   */
   closing: [];
+  /**
+   * Emitted when the modal has finished closing.
+   */
   closed: [];
-  'update:modelValue': [boolean];
-  'click:overlay': [MouseEvent];
+  /**
+   * Emitted when the modal visibility changes (v-model).
+   * @param {boolean} value - The new visibility state
+   */
+  'update:modelValue': [value: boolean];
+  /**
+   * Emitted when the backdrop is clicked.
+   * @param {MouseEvent} event - The click event
+   */
+  'click:overlay': [event: MouseEvent];
 }>();
 
 const props = defineProps({
+  /**
+   * Unique name for the modal when using the modal service.
+   * Used for programmatic control of the modal.
+   */
   name: {
     type: String,
     default: '',
   },
+  /**
+   * Title displayed in the modal header.
+   * Used for accessibility and visual identification.
+   */
   title: {
     type: String,
     default: '',
   },
+  /**
+   * Base z-index for the modal.
+   * Higher values ensure the modal appears above other content.
+   */
   baseZindex: {
     type: Number,
     default: 1051,
   },
+  /**
+   * CSS classes for the backdrop element.
+   * Controls the appearance of the modal overlay.
+   */
   bgClass: {
     type: [String, Object, Array] as PropType<StyleValue>,
     default: 'fixed bottom-0 left-0 right-0 top-0 bg-black/20',
   },
+  /**
+   * CSS classes for the modal wrapper element.
+   * Controls the positioning and layout of the modal container.
+   */
   wrapperClass: {
     type: [String, Object, Array] as PropType<StyleValue>,
     default:
       'fixed bottom-0 left-0 right-0 top-0 flex flex-col items-center justify-center overflow-y-auto overflow-x-hidden outline-none',
   },
+  /**
+   * Base CSS classes for the modal content.
+   * Controls the appearance of the modal dialog itself.
+   */
   modalBaseClass: {
     type: [String, Object, Array] as PropType<StyleValue>,
     default: 'pm relative flex flex-col rounded-2xl pb-6 cursor-default bg-surface shadow-xl',
   },
+  /**
+   * Additional CSS classes for the modal content.
+   * Merged with modalBaseClass for custom styling.
+   */
   modalClass: {
     type: [String, Object, Array] as PropType<StyleValue>,
     default: '',
   },
+  /**
+   * Inline styles for the modal content.
+   * Applied directly to the modal element.
+   */
   modalStyle: {
     type: [String, Object, Array] as PropType<StyleValue>,
     default: '',
   },
+  /**
+   * CSS class for the modal entrance animation.
+   * Controls how the modal appears.
+   */
   inClass: {
     type: String,
     default: 'slideInTop',
   },
+  /**
+   * CSS class for the modal exit animation.
+   * Controls how the modal disappears.
+   */
   outClass: {
     type: String,
     default: 'slideOutTop',
   },
+  /**
+   * CSS class for the backdrop entrance animation.
+   * Controls how the backdrop appears.
+   */
   bgInClass: {
     type: String,
     default: 'fadeIn',
   },
+  /**
+   * CSS class for the backdrop exit animation.
+   * Controls how the backdrop disappears.
+   */
   bgOutClass: {
     type: String,
     default: 'fadeOut',
   },
+  /**
+   * Target element to append the modal to.
+   * Usually 'body' for proper z-index stacking.
+   */
   appendTo: {
     type: String,
     default: 'body',
   },
+  /**
+   * Whether the modal should be mounted immediately.
+   * Useful for modals that are always present in the DOM.
+   */
   live: {
     type: Boolean,
     default: false,
   },
+  /**
+   * Whether the modal can be closed by user interaction.
+   * Controls close button visibility and backdrop click behavior.
+   */
   enableClose: {
     type: Boolean,
     default: true,
   },
+  /**
+   * Controls the visibility of the modal (v-model).
+   * Supports two-way binding for modal 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 the modal content is disabled.
+   * Prevents user interaction with modal content.
+   */
   disabled: {
     type: Boolean,
     default: false,
   },
+  /**
+   * Error message to display in the modal.
+   * Shows an error alert above the modal content.
+   */
   errorMsg: {
     type: String,
     default: '',
   },
+  /**
+   * Maximum width of the modal.
+   * Controls the responsive behavior of the modal.
+   */
   maxWidth: {
     type: String,
     default: '500px',

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

@@ -6,7 +6,7 @@
       aria-label="go to the previous page"
       @click="setPage(Number(modelValue) - 1)"
     >
-      <img src="@squirrel/assets/pagination-left-icon.svg" />
+      <PIcon icon="chevron-left" width="24px" />
     </div>
     <div v-for="(page, index) in pages" :key="index" @click="setPage(Number(page))">
       <div class="flex">
@@ -25,51 +25,71 @@
       aria-label="go to the next page"
       @click="setPage(Number(modelValue) + 1)"
     >
-      <img src="@squirrel/assets/pagination-right-icon.svg" />
+      <PIcon icon="chevron-right" width="24px" />
     </div>
   </div>
 </template>
 
 <script setup lang="ts">
+import PIcon from '@squirrel/components/p-icon/p-icon.vue';
 import PSkeletonLoader from '@squirrel/components/p-skeleton-loader/p-skeleton-loader.vue';
 import { createPagingRange } from '@squirrel/utils/pagination';
 import { computed, type PropType } from 'vue';
 
+/**
+ * A pagination component that displays page numbers with navigation controls.
+ * Provides a complete pagination interface with previous/next buttons, page numbers,
+ * loading states, and ellipsis for large page ranges.
+ * Supports customizable page sizes and offset ranges for optimal display.
+ *
+ * @displayName PPagination
+ */
 defineOptions({ name: 'PPagination' });
 
-const emit = defineEmits(['update:modelValue']);
+const emit = defineEmits<{
+  /**
+   * Emitted when the current page changes.
+   * @param {number} value - The new page number
+   */
+  'update:modelValue': [value: number];
+}>();
 
 const props = defineProps({
   /**
-   * The current page.
+   * The current page number (v-model).
+   * Controls which page is visually active and navigable.
    */
   modelValue: {
     type: Number as PropType<number | null>,
     default: null,
   },
   /**
-   * The amount of data pagination should iterate through.
+   * The total amount of items to paginate through.
+   * Used to calculate the total number of pages.
    */
   count: {
     type: Number,
     default: 0,
   },
   /**
-   * The amount of data to be displayed at 1 page. Used to calculate the length of pagination.
+   * The number of items to display per page.
+   * Used to calculate the total number of pages.
    */
   pageSize: {
     type: Number,
     default: 10,
   },
   /**
-   * The amount of pages to be displayed before and after the current page.
+   * The number of pages to show before and after the current page.
+   * Controls the range of page numbers displayed around the current page.
    */
   pageOffset: {
     type: Number,
     default: 2,
   },
   /**
-   * Whether the pagination is loading.
+   * Whether the pagination is in a loading state.
+   * When true, shows a skeleton loader instead of the pagination controls.
    */
   loading: {
     type: Boolean,

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

@@ -10,32 +10,44 @@
 import PSkeletonLoader from '@squirrel/components/p-skeleton-loader/p-skeleton-loader.vue';
 import { computed } from 'vue';
 
+/**
+ * A pagination info component that displays current page information and result counts.
+ * Shows the range of items being displayed (e.g., "Showing 1 to 10 of 100 results")
+ * and provides a customizable slot for when no results are found.
+ * Includes loading state with skeleton loader.
+ *
+ * @displayName PPaginationInfo
+ */
 defineOptions({ name: 'PPaginationInfo' });
 
 const props = defineProps({
   /**
-   * The current page.
+   * The current page number (1-based).
+   * Used to calculate the starting item number in the display range.
    */
   currentPage: {
     type: Number,
     default: 0,
   },
   /**
-   * The amount of data pagination iterates through.
+   * The total number of items across all pages.
+   * Used to calculate the total count and ending item number.
    */
   count: {
     type: Number,
     default: 0,
   },
   /**
-   * The amount of data to be displayed at 1 page. Used to calculate the `from` and `to` limits.
+   * The number of items displayed per page.
+   * Used to calculate the `from` and `to` limits for the current page.
    */
   pageSize: {
     type: Number,
     default: 0,
   },
   /**
-   * Whether the pagination is loading.
+   * Whether the pagination data is loading.
+   * When true, shows a skeleton loader instead of the info text.
    */
   loading: {
     type: Boolean,