@pequity/squirrel 8.4.4 → 8.4.5

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,

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

@@ -25,6 +25,13 @@ import { defineComponent } from 'vue';
 
 const DEFAULT_CLASSES = `text-xs leading-5 font-semibold truncate shrink`;
 
+/**
+ * A table header cell component that displays text with optional tooltip and filter icon.
+ * Provides consistent styling for table headers with support for custom text colors,
+ * tooltips, and filter functionality.
+ *
+ * @displayName PTableHeaderCell
+ */
 export default defineComponent({
   name: 'PTableHeaderCell',
   components: {
@@ -32,31 +39,60 @@ export default defineComponent({
     PInfoIcon,
   },
   props: {
+    /**
+     * The text content to display in the header cell.
+     * Also used as the title attribute for accessibility.
+     */
     text: {
       type: String,
       default: '',
     },
+    /**
+     * CSS classes to apply to the text element.
+     * Can be a string, object, or array for flexible styling.
+     */
     textClass: {
       type: [String, Object, Array],
       default: 'text-left',
     },
+    /**
+     * Whether the filter icon is in an active state.
+     * Controls the visual appearance of the filter icon and text color.
+     */
     filterActive: {
       type: Boolean,
       default: false,
     },
+    /**
+     * Whether to show the filter icon.
+     * When false, the filter icon is hidden regardless of other states.
+     */
     showFilterIcon: {
       type: Boolean,
       default: false,
     },
+    /**
+     * Tooltip text to display when hovering over the info icon.
+     * When provided, shows an info icon with the tooltip content.
+     */
     tooltipText: {
       type: String,
       default: '',
     },
+    /**
+     * Custom text color to apply to the header text.
+     * Overrides the default text color when provided.
+     */
     textColor: {
       type: String,
       default: '',
     },
   },
+  /**
+   * Emitted when the filter icon is clicked.
+   * @param {Event} event - The click event
+   * @param {boolean} filterActive - The current filter active state
+   */
   emits: ['click-filter-icon'],
   data() {
     return {

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

@@ -25,27 +25,55 @@
 <script setup lang="ts">
 import PSkeletonLoader from '@squirrel/components/p-skeleton-loader/p-skeleton-loader.vue';
 
+/**
+ * A table skeleton loader component that displays a loading placeholder for table data.
+ * Renders a complete table structure with skeleton loaders for headers and data cells.
+ * Supports customizable dimensions, styling, and optional subheaders to match
+ * the expected table layout during loading states.
+ *
+ * @displayName PTableLoader
+ */
 defineOptions({
   name: 'PTableLoader',
 });
 
 defineProps({
+  /**
+   * The number of rows to display in the skeleton table.
+   * Controls the vertical size of the loading placeholder.
+   */
   rows: {
     type: [Number, String],
     default: 4,
   },
+  /**
+   * The number of columns to display in the skeleton table.
+   * Controls the horizontal size of the loading placeholder.
+   */
   columns: {
     type: [Number, String],
     default: 6,
   },
+  /**
+   * CSS classes to apply to each table cell.
+   * Allows customization of cell padding and styling.
+   */
   tdClasses: {
     type: String,
     default: 'px-4 py-5',
   },
+  /**
+   * CSS classes to apply to the skeleton loader within each cell.
+   * Controls the height and appearance of individual skeleton elements.
+   */
   tdSkeletonClasses: {
     type: String,
     default: 'h-5',
   },
+  /**
+   * Whether to display subheaders in the table header.
+   * Adds an additional row below the main header for more complex table structures.
+   */
   withSubheader: {
     type: Boolean,
     default: false,

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

@@ -59,13 +59,31 @@
 import { SORTING_TYPES, type SortingType } from '@squirrel/components/p-table-sort/p-table-sort.config';
 import { type PropType } from 'vue';
 
+/**
+ * A table sorting component that provides ascending, descending, and no-sorting options.
+ * Displays sort options with visual indicators and allows clearing the sort state.
+ * Used for table column sorting functionality.
+ *
+ * @displayName PTableSort
+ */
 defineOptions({
   name: 'PTableSort',
 });
 
-defineEmits(['update:modelValue']);
+defineEmits<{
+  /**
+   * Emitted when the sorting state changes.
+   * @param {SortingType} value - The new sorting state
+   */
+  'update:modelValue': [value: SortingType];
+}>();
 
 defineProps({
+  /**
+   * The current sorting state (v-model).
+   * Valid values: 'asc', 'desc', 'no-sorting'
+   * Controls which sort option is visually active.
+   */
   modelValue: {
     type: String as PropType<SortingType>,
     default: SORTING_TYPES.NO_SORTING,

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

@@ -22,11 +22,31 @@ import {
 } from '@squirrel/components/p-table/p-table.types';
 import { computed, inject, type Ref, ref } from 'vue';
 
+/**
+ * A table cell component that provides advanced styling and behavior for table data.
+ * Supports fixed columns, editable cells, selection states, and responsive design.
+ * Integrates with the table system through dependency injection for coordinated
+ * styling and behavior across the entire table structure.
+ *
+ * @displayName PTableTd
+ */
 defineOptions({ name: 'PTableTd', inheritAttrs: false });
 
 type Props = {
+  /**
+   * The index of the column this cell belongs to.
+   * Used for determining positioning and styling based on column position.
+   */
   colIndex: number;
+  /**
+   * Whether the cell is editable.
+   * Adds cursor pointer styling and enables edit functionality.
+   */
   isEditable?: boolean;
+  /**
+   * Whether the cell is part of a selected row.
+   * Applies selection styling and hover effects.
+   */
   isSelected?: boolean;
 };
 

package/squirrel/components/p-tabs/p-tabs.stories.js

@@ -1,4 +1,4 @@
-import PaginateRightIcon from '@squirrel/assets/pagination-right-icon.svg?inline';
+import KeyboardPressEnterIcon from '@squirrel/assets/keyboard-press-enter.svg?inline';
 import PTabs from '@squirrel/components/p-tabs/p-tabs.vue';
 import { action } from 'storybook/actions';
 import { markRaw } from 'vue';
@@ -35,7 +35,7 @@ export const Default = {
       {
         title: 'Tab 2',
         name: 'tab2',
-        icon: markRaw(PaginateRightIcon),
+        icon: markRaw(KeyboardPressEnterIcon),
       },
       {
         title: 'Tab 3',

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

@@ -30,31 +30,63 @@
 import { type ShallowRef } from 'vue';
 import { type RouteLocationRaw } from 'vue-router';
 
+/**
+ * A tabs component for navigation between different sections.
+ * Displays tabs with optional icons and supports router navigation.
+ * Provides hover effects and active state styling.
+ *
+ * @displayName PTabs
+ */
 defineOptions({
   name: 'PTabs',
 });
 
+/**
+ * Represents a single tab in the tabs component.
+ */
 type Tab = {
+  /** Unique identifier for the tab */
   name: string;
+  /** Display text for the tab */
   title: string;
+  /** Optional icon component or icon name */
   icon?: string | ShallowRef<string>;
+  /** Optional router link destination */
   to?: RouteLocationRaw;
 };
 
 defineProps({
+  /**
+   * Array of tab objects to display.
+   * Each tab should have a name, title, and optional icon and route.
+   */
   tabs: {
     type: Array as () => Tab[],
     required: true,
   },
+  /**
+   * The currently active tab name.
+   * Controls which tab is visually highlighted.
+   */
   activeTab: {
     type: String,
     required: true,
   },
+  /**
+   * Left padding for the tabs container in pixels.
+   * Useful for aligning tabs with other content.
+   */
   tabsLeftPadding: {
     type: Number,
     default: 0,
   },
 });
 
-defineEmits(['click:tab']);
+defineEmits<{
+  /**
+   * Emitted when a tab is clicked.
+   * @param {string} tabName - The name of the clicked tab
+   */
+  'click:tab': [tabName: string];
+}>();
 </script>

package/squirrel/components/p-tabs-pills/p-tabs-pills.vue

@@ -30,20 +30,49 @@
 </template>
 
 <script setup lang="ts">
+/**
+ * A tabs pills component that displays navigation tabs in a pill-style interface.
+ * Provides a compact tab navigation with smooth transitions and accessibility features.
+ * Supports disabled states and custom item text/value properties.
+ *
+ * @displayName PTabsPills
+ */
 defineOptions({
   name: 'PTabsPills',
 });
 
+/**
+ * Valid value types for tab items.
+ */
 type Value = string | number | boolean;
 
+/**
+ * Represents a single tab option in the pills component.
+ */
 type Option = {
   [key: string]: Value;
 };
 
 type Props = {
+  /**
+   * The currently selected tab value (v-model).
+   * Should match one of the item values in the items array.
+   */
   modelValue?: Value;
+  /**
+   * Array of tab items to display as pills.
+   * Each item should have properties matching itemValue and itemText.
+   */
   items?: readonly Option[];
+  /**
+   * Property name to use as the item display text.
+   * Used for button label content.
+   */
   itemText?: string;
+  /**
+   * Property name to use as the item value.
+   * Used for selection comparison and v-model binding.
+   */
   itemValue?: string;
 };
 
@@ -55,6 +84,10 @@ withDefaults(defineProps<Props>(), {
 });
 
 defineEmits<{
+  /**
+   * Emitted when the selected tab value changes.
+   * @param {Value} val - The new selected tab value
+   */
   'update:modelValue': [val: Value];
 }>();
 </script>