@pequity/squirrel 8.4.4 → 8.4.5

package/squirrel/components/p-file-upload/p-file-upload.vue

@@ -76,16 +76,31 @@ import { uniq } from 'lodash-es';
 import { computed, onMounted, type PropType, ref, shallowRef } from 'vue';
 import { useToast } from 'vue-toastification';
 
+/**
+ * A file upload component with drag-and-drop support and comprehensive validation.
+ * Provides a user-friendly interface for file selection with visual feedback,
+ * file type validation, size limits, and multiple file support.
+ *
+ * @displayName PFileUpload
+ */
 defineOptions({
   name: 'PFileUpload',
 });
 
 // Props
 const props = defineProps({
+  /**
+   * The current file(s) value (v-model).
+   * Supports both single file and multiple files based on the multiple prop.
+   */
   modelValue: {
     type: [Object, Array] as PropType<FileUploadFile | FileUploadFile[]>,
     default: () => [],
   },
+  /**
+   * Whether multiple files can be selected.
+   * When true, allows selecting multiple files at once.
+   */
   multiple: {
     type: Boolean,
     default: false,
@@ -98,33 +113,73 @@ const props = defineProps({
     type: Array as PropType<string[] | readonly string[]>,
     default: () => [],
   },
+  /**
+   * Whether the file upload is disabled.
+   * Prevents user interaction when true.
+   */
   disabled: {
     type: Boolean,
     default: false,
   },
+  /**
+   * Whether the file upload is required.
+   * Adds required attribute and visual indicator.
+   */
   required: {
     type: Boolean,
     default: false,
   },
+  /**
+   * Error message to display below the file upload.
+   * When provided, the upload area will show error styling.
+   */
   errorMsg: {
     type: String,
     default: '',
   },
+  /**
+   * Text label for the file upload field.
+   * Displayed above the upload area.
+   */
   label: {
     type: String,
     default: '',
   },
+  /**
+   * Maximum file size in bytes.
+   * Files exceeding this size will be rejected with an error message.
+   */
   maxSizeInBytes: {
     type: Number,
     default: 256 * 1000, // 256 KB
   },
+  /**
+   * Maximum number of files that can be uploaded.
+   * Only applies when multiple is true.
+   */
   maxNumberOfFiles: {
     type: Number,
     default: 10,
   },
 });
 
-const emit = defineEmits(['update:modelValue', 'file-removed', 'file-added']);
+const emit = defineEmits<{
+  /**
+   * Emitted when the file selection changes.
+   * @param {FileUploadFile | FileUploadFile[]} value - The new file selection
+   */
+  'update:modelValue': [value: FileUploadFile | FileUploadFile[]];
+  /**
+   * Emitted when a file is removed from the selection.
+   * @param {FileUploadFile} file - The removed file
+   */
+  'file-removed': [file: FileUploadFile];
+  /**
+   * Emitted when new files are added to the selection.
+   * @param {FileUploadFile[]} files - The newly added files
+   */
+  'file-added': [files: FileUploadFile[]];
+}>();
 
 // Data
 const fileInputRef = shallowRef<HTMLInputElement>();
@@ -217,9 +272,9 @@ const uploadFile = (e: Event | DragEvent) => {
     return;
   }
 
-  const validatedFiles = props.fileTypes ? validateFiles(Array.from(f)) : f;
+  const validatedFiles = props.fileTypes ? validateFiles(Array.from(f)) : Array.from(f);
 
-  files.value = props.multiple ? [...files.value, ...validatedFiles] : (validatedFiles as FileUploadFile[]);
+  files.value = props.multiple ? [...files.value, ...validatedFiles] : validatedFiles;
 
   emit('file-added', validatedFiles);
 };

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

@@ -7,15 +7,31 @@ import 'iconify-icon';
 import { P_ICON_ALIASES, type PIconAlias } from '@squirrel/components/p-icon/p-icon.types';
 import { type IconifyIconProperties } from 'iconify-icon';
 
+/**
+ * An icon component that renders icons using Iconify.
+ * Supports both custom icon aliases and standard Iconify icon names.
+ * Inherits all IconifyIconProperties for full icon customization.
+ *
+ * @displayName PIcon
+ */
 defineOptions({
   name: 'PIcon',
 });
 
 // eslint-disable-next-line @typescript-eslint/consistent-type-definitions
 interface Props extends /* @vue-ignore */ IconifyIconProperties {
+  /**
+   * The icon to display. Can be an icon alias or any valid Iconify icon name.
+   * Icon aliases provide consistent icon naming across the application.
+   */
   icon: PIconAlias | (string & {});
 }
 
+/**
+ * Checks if the provided icon is an icon alias.
+ * @param {string} icon - The icon name to check
+ * @returns {boolean} True if the icon is an icon alias
+ */
 const isPIcon = (icon: string): icon is PIconAlias => !!P_ICON_ALIASES[icon as PIconAlias];
 
 defineProps<Props>();

package/squirrel/components/p-info-icon/p-info-icon.vue

@@ -10,11 +10,30 @@
 <script setup lang="ts">
 import PIcon from '@squirrel/components/p-icon/p-icon.vue';
 
+/**
+ * An info icon component that displays a tooltip on hover.
+ * Shows an info icon with customizable tooltip content.
+ * Tooltip appears after 750ms delay and disappears immediately on mouse leave.
+ *
+ * @displayName PInfoIcon
+ */
 defineOptions({
   name: 'PInfoIcon',
 });
 
+defineSlots<{
+  /**
+   * Custom tooltip content - overrides the text prop.
+   * Use this slot for custom tooltip content instead of the text prop.
+   */
+  default?: () => unknown;
+}>();
+
 type Props = {
+  /**
+   * Text content for the tooltip.
+   * If not provided, you can use the default slot instead.
+   */
   text?: string | null;
 };
 

package/squirrel/components/p-inline-date-picker/p-inline-date-picker.vue

@@ -15,14 +15,42 @@ import { useInputClasses } from '@squirrel/composables/useInputClasses';
 import VueDatePicker, { type VueDatePickerProps } from '@vuepic/vue-datepicker';
 import { computed, type StyleValue, useAttrs } from 'vue';
 
+/**
+ * An inline date picker component that displays a calendar for date selection.
+ * Wraps VueDatePicker with consistent styling and form integration.
+ * Supports custom labels, error states, and inherits all VueDatePicker props.
+ *
+ * @displayName PInlineDatePicker
+ */
 defineOptions({
   name: 'PInlineDatePicker',
   inheritAttrs: false,
 });
 
+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;
+}>();
+
 type Props = {
+  /**
+   * Text label for the date picker field.
+   * If not provided, you can use the label slot instead.
+   */
   label?: string;
+  /**
+   * Error message to display below the date picker.
+   * When provided, the date picker will show error styling.
+   */
   errorMsg?: string;
+  /**
+   * Whether the date picker is required.
+   * Adds required attribute and visual indicator.
+   */
   required?: boolean;
 } & VueDatePickerProps;
 
@@ -38,6 +66,10 @@ const props = withDefaults(defineProps<Props>(), {
   weekStart: 0,
 });
 
+/**
+ * The selected date value (v-model).
+ * Supports two-way binding for form inputs.
+ */
 const model = defineModel<Date | string | null>({ default: '' });
 
 // Data

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

@@ -7,6 +7,7 @@
     </slot>
     <div class="relative w-full">
       <div v-if="!!$slots.prefix">
+        <!-- Slot for content displayed before the input field -->
         <slot name="prefix"></slot>
       </div>
       <input
@@ -17,6 +18,7 @@
         @input="(event: Event) => $emit('update:modelValue', (event.target as HTMLInputElement).value)"
       />
       <div v-if="!!$slots.suffix">
+        <!-- Slot for content displayed after the input field -->
         <slot name="suffix"></slot>
       </div>
     </div>
@@ -36,18 +38,56 @@ type InputType = (typeof INPUT_TYPES)[InputTypeKeys];
 </script>
 
 <script setup lang="ts">
+/**
+ * A versatile input component that supports various types, sizes, and states.
+ * Provides consistent styling and behavior across different input types.
+ * Supports custom labels, error states, and prefix/suffix content.
+ */
 defineOptions({
   name: 'PInput',
   inheritAttrs: false,
 });
 
-defineEmits(['update:modelValue']);
+defineEmits<{
+  /**
+   * Emitted when the input value changes.
+   * @param {string} value - The new input 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;
+
+  /**
+   * Content displayed before the input field.
+   */
+  prefix?: () => unknown;
+
+  /**
+   * Content displayed after the input field.
+   */
+  suffix?: () => unknown;
+}>();
 
 const props = defineProps({
+  /**
+   * The current value of the input (v-model).
+   * Supports two-way binding for form inputs.
+   */
   modelValue: {
     type: [String, Number, Boolean, null] as PropType<string | number | boolean | null>,
     default: '',
   },
+  /**
+   * The type of the input field.
+   * Valid values: 'text', 'password'
+   */
   type: {
     type: String as PropType<InputType>,
     default: INPUT_TYPES.TEXT,
@@ -55,18 +95,34 @@ const props = defineProps({
       return Object.values(INPUT_TYPES).includes(value);
     },
   },
+  /**
+   * Text label for the input field.
+   * If not provided, you can use the label slot instead.
+   */
   label: {
     type: String,
     default: '',
   },
+  /**
+   * Error message to display below the input.
+   * When provided, the input will show error styling.
+   */
   errorMsg: {
     type: String,
     default: '',
   },
+  /**
+   * Whether the input is required.
+   * Adds required attribute and visual indicator.
+   */
   required: {
     type: Boolean,
     default: false,
   },
+  /**
+   * The size of the input - affects padding, font size, and spacing.
+   * Valid values: 'sm', 'md', 'lg'
+   */
   size: {
     type: String as PropType<Size>,
     default: 'md',
@@ -74,6 +130,10 @@ const props = defineProps({
       return SIZES.includes(value);
     },
   },
+  /**
+   * Whether the input has rounded corners.
+   * Applies rounded styling to the input field.
+   */
   rounded: {
     type: Boolean,
     default: false,

package/squirrel/components/p-input-number/p-input-number.vue

@@ -10,6 +10,7 @@
     </div>
     <div class="relative w-full">
       <div v-if="!!$slots.prefix || prefixString">
+        <!-- Slot for custom prefix content - overrides the prefixString prop -->
         <slot name="prefix">
           <div
             :class="[{ 'absolute left-3 flex items-center': prefixString }, prefixString ? prefixClasses[size] : '']"
@@ -53,30 +54,82 @@ const prefixClasses: Record<Size, string> = {
   lg: 'text-lg h-12 left-5',
 };
 
+/**
+ * A specialized input component for numeric values with currency formatting.
+ * Provides number-only input with configurable currency display, precision, and formatting options.
+ * Supports custom labels, error states, tooltips, and prefix content.
+ * Uses vue-currency-input for robust number handling and formatting.
+ */
 defineOptions({
   name: 'PInputNumber',
   inheritAttrs: false,
 });
 
-const emit = defineEmits(['update:modelValue', 'change']);
+const emit = defineEmits<{
+  /**
+   * Emitted when the numeric value changes.
+   * @param {number | null} value - The new numeric value
+   */
+  'update:modelValue': [value: number | null];
+  /**
+   * Emitted when the value changes (includes the new value).
+   * @param {number | null} value - The new numeric value
+   */
+  change: [value: number | null];
+}>();
+
+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;
+
+  /**
+   * Custom prefix content - overrides the prefixString prop.
+   * Use this slot for custom prefix content instead of the prefixString prop.
+   */
+  prefix?: () => unknown;
+}>();
 
 const props = defineProps({
+  /**
+   * The current numeric value of the input (v-model).
+   * Supports two-way binding for form inputs.
+   */
   modelValue: {
     type: [Number, String] as PropType<number | string | null | undefined>,
     default: null,
   },
+  /**
+   * Text label for the input field.
+   * If not provided, you can use the label slot instead.
+   */
   label: {
     type: String,
     default: '',
   },
+  /**
+   * Error message to display below the input.
+   * When provided, the input will show error styling.
+   */
   errorMsg: {
     type: String,
     default: '',
   },
+  /**
+   * Whether the input is required.
+   * Adds required attribute and visual indicator.
+   */
   required: {
     type: Boolean,
     default: false,
   },
+  /**
+   * The size of the input - affects padding, font size, and spacing.
+   * Valid values: 'sm', 'md', 'lg'
+   */
   size: {
     type: String as PropType<Size>,
     default: 'md',
@@ -84,14 +137,26 @@ const props = defineProps({
       return SIZES.includes(value);
     },
   },
+  /**
+   * Whether to select all text when the input receives focus.
+   * Provides better UX for number input fields.
+   */
   selectOnClick: {
     type: Boolean,
     default: true,
   },
+  /**
+   * Text for the info tooltip displayed next to the label.
+   * Uses PInfoIcon component for consistent tooltip styling.
+   */
   tooltipText: {
     type: String,
     default: '',
   },
+  /**
+   * String to display as prefix in the input field.
+   * Can be overridden by the prefix slot for custom content.
+   */
   prefixString: {
     type: String,
     default: '',
@@ -155,9 +220,21 @@ const style = computed(() => {
   return attrs.style as StyleValue;
 });
 
+/**
+ * Handles focus event on the input field.
+ * Selects all text if selectOnClick is enabled.
+ * @param {void} - No parameters
+ * @returns {void}
+ */
 const focus = () => {
   props.selectOnClick && inputRef.value.select();
 };
 
+/**
+ * Programmatically sets the numeric value of the input.
+ * Useful for external control of the input value.
+ * @param {number | null} value - The numeric value to set
+ * @returns {void}
+ */
 defineExpose({ setValue });
 </script>

package/squirrel/components/p-input-percent/p-input-percent.vue

@@ -11,6 +11,7 @@
 <script setup lang="ts">
 import { type Size } from '@squirrel/components/p-btn/p-btn.types';
 import PInputNumber from '@squirrel/components/p-input-number/p-input-number.vue';
+import { toNumberOrNull } from '@squirrel/utils/number';
 import { isNumber } from 'lodash-es';
 import { computed, type PropType } from 'vue';
 
@@ -20,25 +21,48 @@ const prefixClasses: Record<Size, string> = {
   lg: 'text-lg h-12 left-5',
 };
 
+/**
+ * A percentage input component that wraps PInputNumber with automatic decimal conversion.
+ * Displays values as percentages (multiplied by 100) while storing the actual decimal value.
+ * Provides a consistent interface for percentage inputs with proper formatting and validation.
+ *
+ * @displayName PInputPercent
+ */
 defineOptions({
   name: 'PInputPercent',
 });
 
 const props = defineProps({
+  /**
+   * The current value (v-model).
+   * Stored as a decimal (0.5 = 50%) but displayed as a percentage.
+   * Supports two-way binding for form inputs.
+   */
   modelValue: {
     type: [Number, String] as PropType<number | string | null | undefined>,
     default: null,
   },
+  /**
+   * The size of the input field.
+   * Valid values: 'sm', 'md', 'lg'
+   * @values sm, md, lg
+   */
   size: {
     type: String as PropType<Size>,
     default: 'md',
   },
 });
 
-const emit = defineEmits(['update:modelValue']);
+const emit = defineEmits<{
+  /**
+   * Emitted when the percentage value changes.
+   * @param {number | null} value - The new decimal value
+   */
+  'update:modelValue': [value: number | null];
+}>();
 
 const convertedValue = computed({
-  get: () => (isNumber(props.modelValue) ? props.modelValue * 100 : props.modelValue),
-  set: (nV) => emit('update:modelValue', isNumber(nV) ? nV / 100 : nV),
+  get: () => (isNumber(props.modelValue) ? props.modelValue * 100 : toNumberOrNull(props.modelValue)),
+  set: (nV) => emit('update:modelValue', isNumber(nV) ? nV / 100 : toNumberOrNull(nV)),
 });
 </script>

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);