@pequity/squirrel 8.4.4 → 8.5.0

package/squirrel/components/p-table/usePTableHeaderWrap.spec.js

@@ -0,0 +1,118 @@
+import { HEADER_CELL_ONE_LINE_HEIGHT } from '@squirrel/components/p-table/p-table.types';
+import { usePTableHeaderWrap } from '@squirrel/components/p-table/usePTableHeaderWrap';
+import { waitNT } from '@tests/vitest.helpers';
+import { mount } from '@vue/test-utils';
+import { defineComponent, useTemplateRef } from 'vue';
+
+// Mock ResizeObserver to capture the composable's callback
+let composableResizeCallback;
+const mockResizeObserver = vi.fn((callback) => {
+  composableResizeCallback = callback;
+  return {
+    observe: vi.fn(),
+    unobserve: vi.fn(),
+    disconnect: vi.fn(),
+  };
+});
+
+const createWrapper = (refName = 'theadRef') => {
+  const TestComponent = defineComponent({
+    setup() {
+      const theadRef = useTemplateRef('theadRef');
+      const { hasWrap } = usePTableHeaderWrap(theadRef);
+
+      return {
+        theadRef,
+        hasWrap,
+      };
+    },
+    template: `
+      <table>
+        <thead ref="${refName}" :data-has-wrap="hasWrap">
+          <tr>
+            <th>
+              <div data-p-table-header-text class="div-to-resize">Short</div>
+            </th>
+            <th>
+              <span data-p-table-header-text>Very Long Header That Could Potentially Wrap To Multiple Lines</span>
+            </th>
+          </tr>
+        </thead>
+      </table>
+    `,
+  });
+
+  return mount(TestComponent, {
+    attachTo: document.body,
+  });
+};
+
+describe('usePTableHeaderWrap', () => {
+  const originalOffsetHeight = Object.getOwnPropertyDescriptor(HTMLElement.prototype, 'offsetHeight');
+  const originalGlobalResizeObserver = globalThis.ResizeObserver;
+
+  beforeAll(() => {
+    Object.defineProperty(HTMLElement.prototype, 'offsetHeight', {
+      configurable: true,
+      value: HEADER_CELL_ONE_LINE_HEIGHT,
+    });
+    globalThis.ResizeObserver = mockResizeObserver;
+  });
+
+  afterAll(() => {
+    Object.defineProperty(HTMLElement.prototype, 'offsetHeight', originalOffsetHeight);
+    globalThis.ResizeObserver = originalGlobalResizeObserver;
+  });
+
+  beforeEach(() => {
+    mockResizeObserver.mockClear();
+    composableResizeCallback = null;
+  });
+
+  it('should have hasWrap false when all divs are single line height', async () => {
+    const wrapper = createWrapper();
+
+    // Trigger the composable's ResizeObserver callback
+    if (composableResizeCallback) {
+      composableResizeCallback();
+      await waitNT(wrapper.vm);
+    }
+
+    expect(wrapper.find('thead').attributes()['data-has-wrap']).toBe('false');
+
+    wrapper.unmount();
+  });
+
+  it('should have hasWrap true when one div is double line height', async () => {
+    // Override offsetHeight for the "div-to-resize" element
+    Object.defineProperty(HTMLElement.prototype, 'offsetHeight', {
+      configurable: true,
+      get() {
+        if (this.classList.contains('div-to-resize')) {
+          return HEADER_CELL_ONE_LINE_HEIGHT * 2;
+        }
+        return HEADER_CELL_ONE_LINE_HEIGHT;
+      },
+    });
+
+    const wrapper = createWrapper();
+
+    // Trigger the composable's ResizeObserver callback
+    if (composableResizeCallback) {
+      composableResizeCallback();
+      await waitNT(wrapper.vm);
+    }
+
+    expect(wrapper.find('thead').attributes()['data-has-wrap']).toBe('true');
+
+    wrapper.unmount();
+  });
+
+  it('should handle null theadRef gracefully', () => {
+    const wrapper = createWrapper('nullRef');
+
+    expect(wrapper.find('thead').attributes()['data-has-wrap']).toBe('false');
+
+    wrapper.unmount();
+  });
+});

package/squirrel/components/p-table/usePTableHeaderWrap.ts

@@ -0,0 +1,45 @@
+import { HEADER_CELL_ONE_LINE_HEIGHT } from '@squirrel/components/p-table/p-table.types';
+import { onBeforeUnmount, onMounted, type Ref, ref } from 'vue';
+
+export const usePTableHeaderWrap = (theadRef: Ref<HTMLElement | null>) => {
+  let headerObserver: ResizeObserver | null = null;
+  const hasWrap = ref(false);
+
+  const setupObserver = () => {
+    if (!theadRef.value) return;
+
+    headerObserver = new ResizeObserver(() => {
+      if (theadRef.value) {
+        const textDivs = theadRef.value.querySelectorAll('[data-p-table-header-text]') as NodeListOf<HTMLElement>;
+
+        for (const div of textDivs) {
+          if (div.offsetHeight > HEADER_CELL_ONE_LINE_HEIGHT) {
+            hasWrap.value = true;
+            return;
+          }
+        }
+
+        hasWrap.value = false;
+      }
+    });
+
+    headerObserver.observe(theadRef.value);
+  };
+
+  const cleanupObserver = () => {
+    if (headerObserver) {
+      headerObserver.disconnect();
+      headerObserver = null;
+    }
+  };
+
+  onMounted(() => {
+    setupObserver();
+  });
+
+  onBeforeUnmount(() => {
+    cleanupObserver();
+  });
+
+  return { hasWrap };
+};

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

@@ -25,7 +25,11 @@ describe('PTableHeaderCell.vue', () => {
       'text-xs',
       'leading-5',
       'font-semibold',
-      'truncate',
+      'line-clamp-2',
+      'break-words',
+      'hyphens-auto',
+      'whitespace-normal',
+      'max-h-10',
       'shrink',
       'test-class',
       'text-p-gray-60',

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

@@ -4,6 +4,7 @@
       :class="[DEFAULT_CLASSES, textClass, textColorClass, { 'mr-auto': !tooltipText }]"
       :style="style"
       :title="text"
+      data-p-table-header-text
     >
       {{ text }}
     </div>
@@ -23,8 +24,15 @@ import PInfoIcon from '@squirrel/components/p-info-icon/p-info-icon.vue';
 import PTableFilterIcon from '@squirrel/components/p-table-header-cell/p-table-filter-icon.vue';
 import { defineComponent } from 'vue';
 
-const DEFAULT_CLASSES = `text-xs leading-5 font-semibold truncate shrink`;
+const DEFAULT_CLASSES = `text-xs leading-5 font-semibold line-clamp-2 break-words hyphens-auto whitespace-normal max-h-10 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 +40,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>

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

@@ -15,30 +15,72 @@ import { type Size, SIZES } from '@squirrel/components/p-btn/p-btn.types';
 import { useInputClasses } from '@squirrel/composables/useInputClasses';
 import { computed, type PropType, type StyleValue, useAttrs } from 'vue';
 
+/**
+ * A textarea component for multi-line text input.
+ * Provides consistent styling and behavior with other form components.
+ * Supports custom labels, error states, and various sizes.
+ *
+ * @displayName PTextarea
+ */
 defineOptions({
   name: 'PTextarea',
   inheritAttrs: false,
 });
 
-const emit = defineEmits(['update:modelValue']);
+const emit = defineEmits<{
+  /**
+   * Emitted when the textarea value changes.
+   * @param {string} value - The new textarea value
+   */
+  'update:modelValue': [value: string];
+}>();
+
+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 value of the textarea (v-model).
+   * Supports two-way binding for form inputs.
+   */
   modelValue: {
     type: [String, Number, null] as PropType<string | number | null>,
     default: '',
   },
+  /**
+   * Text label for the textarea field.
+   * If not provided, you can use the label slot instead.
+   */
   label: {
     type: String,
     default: '',
   },
+  /**
+   * Error message to display below the textarea.
+   * When provided, the textarea will show error styling.
+   */
   errorMsg: {
     type: String,
     default: '',
   },
+  /**
+   * Whether the textarea is required.
+   * Adds required attribute and visual indicator.
+   */
   required: {
     type: Boolean,
     default: false,
   },
+  /**
+   * The size of the textarea - affects padding, font size, and spacing.
+   * Valid values: 'sm', 'md', 'lg'
+   */
   size: {
     type: String as PropType<Size>,
     default: 'md',

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

@@ -56,30 +56,73 @@ const TOGGLE_CLASSES = [
 </script>
 
 <script setup lang="ts">
+/**
+ * A toggle switch component that provides a modern switch interface.
+ * Supports different sizes, labels, error states, and accessibility features.
+ * Uses a checkbox input with custom styling for the toggle appearance.
+ *
+ * @displayName PToggle
+ */
 defineOptions({
   name: 'PToggle',
   inheritAttrs: false,
 });
 
-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 emit = defineEmits<{
+  /**
+   * Emitted when the toggle state changes.
+   * @param {boolean} value - The new toggle state
+   */
+  'update:modelValue': [value: boolean];
+}>();
 
 const props = defineProps({
+  /**
+   * The current toggle state (v-model).
+   * Supports two-way binding for form inputs.
+   */
   modelValue: {
     type: Boolean,
     default: false,
   },
+  /**
+   * Text label for the toggle switch.
+   * If not provided, you can use the label slot instead.
+   */
   label: {
     type: String,
     default: '',
   },
+  /**
+   * Error message to display below the toggle.
+   * When provided, the toggle will show error styling.
+   */
   errorMsg: {
     type: String,
     default: '',
   },
+  /**
+   * Whether the toggle is required.
+   * Adds required attribute and visual indicator.
+   */
   required: {
     type: Boolean,
     default: false,
   },
+  /**
+   * The size of the toggle switch.
+   * Valid values: 'sm', 'md', 'lg'
+   * @values sm, md, lg
+   */
   size: {
     type: String as PropType<Size>,
     default: 'md',