@pequity/squirrel 8.4.4 → 8.5.0

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-basic.spec.js

@@ -1,5 +1,5 @@
 import PModal from '@squirrel/components/p-modal/p-modal.vue';
-import { waitRAF } from '@tests/vitest.helpers';
+import { waitNT, waitRAF } from '@tests/vitest.helpers';
 import { mount } from '@vue/test-utils';
 
 const createWrapperContainer = (componentArgs) => {
@@ -85,18 +85,44 @@ describe('Modal basic functionality', () => {
     await wrapper.setData({ showModal: true });
 
     expect(wrapper.find('[data-pm-id]').classes()).toEqual(
-      'pm relative flex flex-col rounded-2xl pb-6 cursor-default bg-surface shadow-xl'.split(' ')
+      'pm relative flex flex-col rounded-2xl cursor-default bg-surface shadow-xl pb-6'.split(' ')
     );
 
     wrapper.unmount();
   });
 
+  it('sets the correct base modal class when modal-wrapper slot is used', async () => {
+    const wrapper = mount(PModal, {
+      attachTo: document.body,
+      global: {
+        stubs: {
+          transition: true,
+          teleport: true,
+        },
+      },
+      props: {
+        modelValue: true,
+      },
+      slots: {
+        'modal-wrapper': '<div>Modal content goes here...</div>',
+      },
+    });
+
+    await waitNT(wrapper.vm);
+
+    const modalContent = wrapper.find('[data-pm-id]');
+
+    expect(modalContent.classes()).not.toContain('pb-6');
+
+    wrapper.unmount();
+  });
+
   it('passes the modalBaseClass prop to the modal', async () => {
     const wrapper = createWrapperContainer({ modalBaseClass: 'custom-class' });
 
     await wrapper.setData({ showModal: true });
 
-    expect(wrapper.find('[data-pm-id]').classes()).toEqual(['custom-class']);
+    expect(wrapper.find('[data-pm-id]').classes()).toEqual(['custom-class', 'pb-6']);
 
     wrapper.unmount();
   });

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

@@ -29,40 +29,47 @@
         @click="overlayClick($event)"
         @keydown="keydown($event)"
       >
-        <div ref="pm" :data-pm-id="id" :class="[modalBaseClass, modalClass]" :style="modalStyle">
-          <slot name="title-wrapper">
-            <div class="flex pb-4 pl-8 pr-4 pt-4">
-              <h3 v-if="title" :id="`${id}-title`" class="mr-auto pt-4 text-xl font-semibold">
-                {{ title }}
-              </h3>
-              <div class="ml-auto">
-                <PCloseBtn
-                  :disabled="disabled"
-                  :class="{ invisible: !enableClose }"
-                  :aria-label="closeLabel"
-                  @click.prevent="close"
-                />
+        <div
+          ref="pm"
+          :data-pm-id="id"
+          :class="[modalBaseClass, modalClass, { 'pb-6': !$slots['modal-wrapper'] }]"
+          :style="modalStyle"
+        >
+          <slot name="modal-wrapper">
+            <slot name="title-wrapper">
+              <div class="flex pb-4 pl-8 pr-4 pt-4">
+                <h3 v-if="title" :id="`${id}-title`" class="mr-auto pt-4 text-xl font-semibold">
+                  {{ title }}
+                </h3>
+                <div class="ml-auto">
+                  <PCloseBtn
+                    :disabled="disabled"
+                    :class="{ invisible: !enableClose }"
+                    :aria-label="closeLabel"
+                    @click.prevent="close"
+                  />
+                </div>
               </div>
+            </slot>
+            <div v-if="errorMsg" class="mb-4 px-8">
+              <PAlert type="error">{{ errorMsg }}</PAlert>
             </div>
-          </slot>
-          <div v-if="errorMsg" class="mb-4 px-8">
-            <PAlert type="error">{{ errorMsg }}</PAlert>
-          </div>
-          <slot name="content-wrapper">
-            <div
-              :id="`${id}-content`"
-              :class="[
-                'relative grow overflow-y-auto overflow-x-hidden px-8',
-                { 'pointer-events-none opacity-50': disabled },
-              ]"
-            >
-              <slot></slot>
-            </div>
-          </slot>
-          <slot name="footer-wrapper">
-            <div v-if="$slots.footer" class="px-8 pt-6">
-              <slot name="footer"></slot>
-            </div>
+            <slot name="content-wrapper">
+              <div
+                :id="`${id}-content`"
+                :class="[
+                  'relative grow overflow-y-auto overflow-x-hidden px-8',
+                  { 'pointer-events-none opacity-50': disabled },
+                ]"
+              >
+                <slot></slot>
+              </div>
+            </slot>
+            <slot name="footer-wrapper">
+              <div v-if="$slots.footer" class="px-8 pt-6">
+                <slot name="footer"></slot>
+              </div>
+            </slot>
           </slot>
         </div>
       </div>
@@ -90,99 +97,239 @@ 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 modal wrapper content.
+   */
+  'modal-wrapper'?: () => 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',
+    default: 'pm relative flex flex-col rounded-2xl 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,

package/squirrel/components/p-progress-bar/p-progress-bar.vue

@@ -11,20 +11,47 @@
 </template>
 
 <script setup lang="ts">
+/**
+ * A progress bar component that displays multiple progress segments with different colors.
+ * Each segment represents a portion of the total progress and can have its own color
+ * and optional label. Useful for showing complex progress states or multi-part progress.
+ *
+ * @displayName PProgressBar
+ */
+defineOptions({
+  name: 'PProgressBar',
+});
+
+/**
+ * Represents a single progress segment with its value, color, and optional label.
+ */
 export type ProgressItem = {
+  /**
+   * The numeric value of this progress segment.
+   */
   value: number;
+  /**
+   * The background color for this progress segment.
+   */
   color: string;
+  /**
+   * Optional label to display on hover tooltip.
+   */
   label?: string;
 };
 
 type Props = {
+  /**
+   * The total value used to calculate percentage widths.
+   * All segment values should sum to this total for accurate representation.
+   */
   total: number;
+  /**
+   * Array of progress segments to display.
+   * Each item represents a portion of the total progress.
+   */
   items: ProgressItem[];
 };
 
-defineOptions({
-  name: 'PProgressBar',
-});
-
 defineProps<Props>();
 </script>