@pequity/squirrel 8.4.4 → 8.4.5

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,

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>

package/squirrel/components/p-ring-loader/p-ring-loader.vue

@@ -6,12 +6,29 @@
 import PIcon from '@squirrel/components/p-icon/p-icon.vue';
 import { computed } from 'vue';
 
+/**
+ * A ring loader component that displays a spinning ring animation.
+ * Provides a consistent loading indicator with customizable size and color.
+ * Uses an SVG spinner icon with smooth animation.
+ *
+ * @displayName PRingLoader
+ */
 defineOptions({
   name: 'PRingLoader',
 });
 
 type Props = {
+  /**
+   * The size of the ring loader in pixels.
+   * Controls the overall dimensions of the spinner.
+   * Default: 80px
+   */
   size?: number;
+  /**
+   * Custom color for the ring loader.
+   * Overrides the default blue color when provided.
+   * Can be any valid CSS color value.
+   */
   color?: string;
 };
 

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

@@ -20,6 +20,14 @@ import { useInputClasses } from '@squirrel/composables/useInputClasses';
 import { type PropType, type StyleValue } from 'vue';
 import { computed, useAttrs } from 'vue';
 
+/**
+ * A select dropdown component for choosing from a list of options.
+ * Provides consistent styling and behavior with other form components.
+ * Supports custom labels, error states, and flexible item structure.
+ * Automatically handles null values and boolean conversions.
+ *
+ * @displayName PSelect
+ */
 defineOptions({
   name: 'PSelect',
   inheritAttrs: false,
@@ -27,27 +35,61 @@ defineOptions({
 
 const emit = defineEmits(['update:modelValue']);
 
+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;
+}>();
+
 const props = defineProps({
+  /**
+   * The current selected value (v-model).
+   * Supports two-way binding for form inputs.
+   */
   modelValue: {
     type: [String, Number, Boolean, null] as PropType<string | number | boolean | null>,
     default: '',
   },
+  /**
+   * Array of objects representing the select options.
+   * Each object should have properties specified by itemText and itemValue.
+   * @example [{ text: 'Option 1', value: 1 }, { text: 'Option 2', value: 2 }]
+   */
   items: {
     type: Array as PropType<Record<string, unknown>[]>,
     default: () => [],
   },
+  /**
+   * Text label for the select field.
+   * If not provided, you can use the label slot instead.
+   */
   label: {
     type: String,
     default: '',
   },
+  /**
+   * Error message to display below the select.
+   * When provided, the select will show error styling.
+   */
   errorMsg: {
     type: String,
     default: '',
   },
+  /**
+   * Whether the select is required.
+   * Adds required attribute and visual indicator.
+   */
   required: {
     type: Boolean,
     default: false,
   },
+  /**
+   * The size of the select - affects padding, font size, and spacing.
+   * Valid values: 'sm', 'md', 'lg'
+   */
   size: {
     type: String as PropType<Size>,
     default: 'md',
@@ -55,10 +97,18 @@ const props = defineProps({
       return SIZES.includes(value);
     },
   },
+  /**
+   * Property name to use as the display text for each option.
+   * Defaults to 'text' - each item should have this property.
+   */
   itemText: {
     type: String,
     default: 'text',
   },
+  /**
+   * Property name to use as the value for each option.
+   * Defaults to 'value' - each item should have this property.
+   */
   itemValue: {
     type: [String, Number, Boolean, null] as PropType<string | number | boolean | null>,
     default: 'value',
@@ -98,7 +148,6 @@ const innerOptions = computed(() => {
   });
 });
 
-// Methods
 const onChange = (e: Event) => {
   const value = (e.target as HTMLSelectElement).value;
 

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

@@ -31,19 +31,71 @@
 import { type Size } from '@squirrel/components/p-btn/p-btn.types';
 import PBtn from '@squirrel/components/p-btn/p-btn.vue';
 
+/**
+ * A select button group component that displays multiple buttons as a connected group.
+ * Provides a button-based selection interface with support for single/multiple selection,
+ * custom styling, tooltips, and flexible item structure.
+ *
+ * @displayName PSelectBtn
+ */
 type BtnGroupItem = Record<string, string | number | boolean>;
 
 type Props = {
-  modelValue?: string | number | null | BtnGroupItem[];
+  /**
+   * The current selected value(s) (v-model).
+   * For single selection: string, number, boolean, or null
+   * For multiple selection: array of BtnGroupItem objects
+   */
+  modelValue?: string | number | boolean | null | BtnGroupItem[];
+  /**
+   * Array of items to display as buttons.
+   * Each item should have properties matching itemValue, itemText, and itemTooltipText.
+   */
   items?: BtnGroupItem[] | readonly BtnGroupItem[];
+  /**
+   * Property name to use as the item value.
+   * Used for selection comparison and v-model binding.
+   */
   itemValue?: string | number;
+  /**
+   * Property name to use as the item display text.
+   * Used for button label content.
+   */
   itemText?: string;
+  /**
+   * Property name to use as the item tooltip text.
+   * Used when showTooltip is enabled.
+   */
   itemTooltipText?: string;
+  /**
+   * The size of the buttons in the group.
+   * Valid values: 'sm', 'md', 'lg'
+   */
   size?: Size;
+  /**
+   * Whether to show tooltips on button hover.
+   * Uses the itemTooltipText property for tooltip content.
+   */
   showTooltip?: boolean;
+  /**
+   * Whether to highlight selected buttons visually.
+   * Applies selected styling to chosen buttons.
+   */
   highlightSelected?: boolean;
+  /**
+   * Whether buttons should grow to fill available space.
+   * Makes all buttons equal width within the container.
+   */
   grow?: boolean;
+  /**
+   * Whether multiple items can be selected simultaneously.
+   * When true, modelValue becomes an array of selected items.
+   */
   multiple?: boolean;
+  /**
+   * Whether to remove padding from button containers.
+   * Useful for custom spacing control.
+   */
   noPadding?: boolean;
 };
 
@@ -51,7 +103,23 @@ defineOptions({
   name: 'PSelectBtn',
 });
 
-const emit = defineEmits(['update:modelValue']);
+defineSlots<{
+  /**
+   * Custom content for each button in the group.
+   * Overrides the default item text display.
+   * @param {BtnGroupItem} item - The current item data
+   * @param {boolean} isSelected - Whether the current item is selected
+   */
+  [key: `btn-${number}`]: (props: { item: BtnGroupItem; isSelected: boolean }) => unknown;
+}>();
+
+const emit = defineEmits<{
+  /**
+   * Emitted when the selection changes.
+   * @param {string | number | boolean | null | BtnGroupItem[]} value - The new selected value(s)
+   */
+  'update:modelValue': [value: string | number | boolean | null | BtnGroupItem[]];
+}>();
 
 // Props
 const props = withDefaults(defineProps<Props>(), {
@@ -69,10 +137,22 @@ const props = withDefaults(defineProps<Props>(), {
 });
 
 // Methods
+/**
+ * Gets the tooltip text for a given item.
+ * Returns the item's tooltip text if showTooltip is enabled, otherwise empty string.
+ * @param {BtnGroupItem} item - The item to get tooltip text for
+ * @returns {string} The tooltip text or empty string
+ */
 const tooltipText = (item: BtnGroupItem) => {
   return props.showTooltip ? item[props.itemTooltipText] : '';
 };
 
+/**
+ * Handles item selection based on single/multiple mode.
+ * For single selection: emits the item value directly.
+ * For multiple selection: toggles the item in the selection array.
+ * @param {BtnGroupItem} item - The item being selected
+ */
 const select = (item: BtnGroupItem) => {
   if (!props.multiple) {
     emit('update:modelValue', item[props.itemValue]);
@@ -95,6 +175,13 @@ const select = (item: BtnGroupItem) => {
   }
 };
 
+/**
+ * Checks if a given item is currently selected.
+ * For single selection: compares with modelValue directly.
+ * For multiple selection: checks if item exists in modelValue array.
+ * @param {BtnGroupItem} item - The item to check
+ * @returns {boolean} True if the item is selected
+ */
 const isSelected = (item: BtnGroupItem) => {
   if (!props.multiple) {
     return props.modelValue === item[props.itemValue];
@@ -105,5 +192,6 @@ const isSelected = (item: BtnGroupItem) => {
       return index !== -1;
     }
   }
+  return false;
 };
 </script>