@pequity/squirrel 8.4.3 → 8.4.5

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>

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

@@ -133,6 +133,13 @@ import { toString } from '@squirrel/utils/string';
 import { splitStringForHighlight } from '@squirrel/utils/text';
 import { type ComponentPublicInstance, computed, onMounted, type PropType, ref, type StyleValue, useAttrs } from 'vue';
 
+/**
+ * A select list component with advanced features like search, multiple selection, and virtual scrolling.
+ * Provides a customizable list interface with support for single/multiple selection, search filtering,
+ * and virtual scrolling for large datasets.
+ *
+ * @displayName PSelectList
+ */
 defineOptions({
   name: 'PSelectList',
   inheritAttrs: false,

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

@@ -30,10 +30,17 @@
 <script lang="ts">
 import { defineComponent, type PropType } from 'vue';
 
+/**
+ * Represents a single option in the select pill component.
+ */
 type Option = Record<string, unknown> & {
+  /** Display text for the option */
   text: string;
+  /** Optional subtext displayed below the main text */
   subtext?: string;
+  /** Unique value identifier for the option */
   value: string | number;
+  /** Whether the option is disabled and cannot be selected */
   disabled?: boolean;
 };
 
@@ -46,6 +53,8 @@ const ACTIVE_CLASS = 'text-p-purple-60';
  * In cases that p-select-pill is rendered before its parent component is visible,
  * we need to calculate the offsets by cloning the container div and put it in the DOM momentarily.
  * This way the buttons actually have measurable dimensions.
+ * @param {HTMLElement} container - The container element to clone
+ * @returns {Object} Object containing width and left position of the active button
  */
 const getOffsetValues = (container: HTMLElement) => {
   const el = container.cloneNode(true) as HTMLElement;
@@ -60,29 +69,61 @@ const getOffsetValues = (container: HTMLElement) => {
   return res;
 };
 
+/**
+ * A select pill component that displays options as connected buttons with a sliding indicator.
+ * Provides a pill-style selection interface with smooth animations and visual feedback.
+ * The active option is highlighted with a sliding background indicator.
+ *
+ * @displayName PSelectPill
+ */
 export default defineComponent({
   name: 'PSelectPill',
   props: {
+    /**
+     * The currently selected value (v-model).
+     * Should match one of the item values in the items array.
+     */
     modelValue: {
       type: [String, Number],
       default: '',
     },
+    /**
+     * Array of options to display as pills.
+     * Each option should have text, value, and optional subtext and disabled properties.
+     */
     items: {
       type: Array as PropType<Option[] | [] | undefined | null>,
       default: () => [],
     },
+    /**
+     * Property name to use as the item display text.
+     * Used for button label content.
+     */
     itemText: {
       type: String,
       default: 'text',
     },
+    /**
+     * Property name to use as the item subtext.
+     * Displayed below the main text when provided.
+     */
     itemSubtext: {
       type: String,
       default: 'subtext',
     },
+    /**
+     * Property name to use as the item value.
+     * Used for selection comparison and v-model binding.
+     */
     itemValue: {
       type: [String, Number],
       default: 'value',
     },
+    /**
+     * The size of the pill buttons.
+     * Valid values: 'sm', 'md', 'lg'
+     * @values sm, md, lg
+     */
     size: {
       type: String as PropType<Size>,
       default: 'md',
@@ -91,7 +132,13 @@ export default defineComponent({
       },
     },
   },
-  emits: ['update:modelValue'],
+  emits: {
+    /**
+     * Emitted when the selected value changes.
+     * @param {string | number} value - The new selected value
+     */
+    'update:modelValue': (value: string | number) => true,
+  },
   data() {
     return {
       SIZES,
@@ -118,7 +165,10 @@ export default defineComponent({
   methods: {
     click(e: Event, option: Option) {
       if (!option.disabled) {
-        this.$emit('update:modelValue', option[this.itemValue]);
+        const value = option[this.itemValue];
+        if (typeof value === 'string' || typeof value === 'number') {
+          this.$emit('update:modelValue', value);
+        }
       }
     },
     setPillStyle() {

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

@@ -30,9 +30,21 @@ const isHexColor = (hexColor: string) => {
 
 const hexToRgb = (hex: string) => `${hex.match(/\w\w/g)?.map((x) => +`0x${x}`)}`;
 
+/**
+ * A skeleton loader component that displays animated loading placeholders.
+ * Provides customizable shapes, colors, and shimmer effects to indicate
+ * content loading states. Supports both rectangle and circle shapes with
+ * configurable background and shimmer colors.
+ *
+ * @displayName PSkeletonLoader
+ */
 export default defineComponent({
   name: 'PSkeletonLoader',
   props: {
+    /**
+     * The shape type of the skeleton loader.
+     * Determines the border radius and overall appearance.
+     */
     type: {
       type: String as PropType<LoaderType>,
       default: LOADER_TYPES.rectangle,
@@ -40,14 +52,26 @@ export default defineComponent({
         return Object.values(LOADER_TYPES).includes(value);
       },
     },
+    /**
+     * The background CSS class for the skeleton loader.
+     * Controls the base color of the loading placeholder.
+     */
     bgClass: {
       type: String,
       default: 'bg-p-gray-30',
     },
+    /**
+     * Additional CSS classes to apply to the loader.
+     * Allows for custom styling beyond the default type-based classes.
+     */
     cssClass: {
       type: String,
       default: '',
     },
+    /**
+     * The color of the shimmer effect in hex format.
+     * Controls the color of the animated shimmer overlay.
+     */
     shimmerColor: {
       type: String,
       default: SHIMMER_COLOR,

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

@@ -25,13 +25,32 @@ import type { StepItem } from '@squirrel/components/p-steps/p-steps.types';
 import { startCase } from 'lodash-es';
 import { computed } from 'vue';
 
+/**
+ * A steps component that displays a sequence of steps with visual indicators.
+ * Shows the current step, completed steps, and upcoming steps with different styling.
+ * Supports clickable steps and custom step text with automatic fallback to formatted step values.
+ *
+ * @displayName PSteps
+ */
 defineOptions({
   name: 'PSteps',
 });
 
 type Props = {
+  /**
+   * The currently active step value.
+   * Should match one of the step values in the steps array.
+   */
   activeStep?: StepItem['value'];
+  /**
+   * Array of step items to display.
+   * Each step should have a value and optional text and disabled properties.
+   */
   steps?: readonly StepItem[];
+  /**
+   * Whether steps are clickable to navigate between them.
+   * When true, steps become interactive and emit click events.
+   */
   clickable?: boolean;
 };
 
@@ -42,6 +61,12 @@ const props = withDefaults(defineProps<Props>(), {
 });
 
 const emit = defineEmits<{
+  /**
+   * Emitted when a step is clicked.
+   * Only emitted when clickable is true and the step is not disabled.
+   * @param {StepItem} step - The clicked step item
+   * @param {number} index - The index of the clicked step
+   */
   'click:step': [step: StepItem, index: number];
 }>();
 

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

@@ -114,19 +114,58 @@ import { kebabCase } from 'lodash-es';
 import { computed, onBeforeUnmount, onMounted, provide, ref, watch } from 'vue';
 
 type Props = {
+  /**
+   * Array of column definitions for the table.
+   * Each column defines its display properties, filtering, and styling.
+   */
   cols: TableCol[];
+  /**
+   * Whether columns can be resized by dragging.
+   * Enables column width adjustment functionality.
+   */
   colsResizable?: boolean;
+  /**
+   * Whether the first column is fixed in position.
+   * Useful for keeping important columns visible during horizontal scrolling.
+   */
   isFirstColFixed?: boolean;
+  /**
+   * Whether the last column is fixed in position.
+   * Useful for keeping action columns visible during horizontal scrolling.
+   */
   isLastColFixed?: boolean;
+  /**
+   * Whether to prevent horizontal scrolling.
+   * Forces the table to fit within its container.
+   */
   lockScroll?: boolean;
+  /**
+   * Whether to show subheader content below the main header.
+   * Provides additional header information or controls.
+   */
   subheader?: boolean;
+  /**
+   * Virtual scrolling configuration for large datasets.
+   * Controls padding for virtualized rows.
+   */
   virtualizer?: {
     paddingTop: number;
     paddingBottom: number;
   };
+  /**
+   * Array of data objects to display in the table.
+   * Each object should have properties matching the column names.
+   */
   data?: T[];
 };
 
+/**
+ * A comprehensive table component with advanced features like column resizing, fixed columns, and virtual scrolling.
+ * Provides a flexible table interface with support for custom cell rendering, column filtering, and responsive design.
+ * Supports both simple data display and complex interactive features.
+ *
+ * @displayName PTable
+ */
 defineOptions({ name: 'PTable' });
 
 const emit = defineEmits<{

package/squirrel/components/p-table-header-cell/p-table-filter-icon.vue

@@ -3,12 +3,21 @@
 </template>
 
 <script setup lang="ts">
+/**
+ * A filter icon component for table headers, used to indicate and toggle filter state.
+ * Changes its appearance based on the active state and supports hover effects.
+ *
+ * @displayName PTableFilterIcon
+ */
 defineOptions({
   name: 'PTableFilterIcon',
   inheritAttrs: false,
 });
 
 defineProps({
+  /**
+   * Whether the filter icon is active (filtered state).
+   */
   active: {
     type: Boolean,
     default: false,