@skewedaspect/sleekspace-ui 0.2.0-beta.1 → 0.2.0-beta.3

package/src/components/Textarea/SkTextarea.vue

@@ -28,9 +28,19 @@
 
 <script setup lang="ts">
     /**
-     * @component
-     * A multiline textarea component with validation states and semantic color support.
-     * Supports flexible sizing and row configuration.
+     * @component SkTextarea
+     * @description A multiline text input component for longer form content like descriptions, comments, or messages.
+     * Features semantic color theming, validation state support, and configurable height via the rows prop.
+     * Integrates with SkField for labels and error messages. Use with `v-model` for two-way data binding.
+     *
+     * @example
+     * ```vue
+     * <SkTextarea v-model="description" placeholder="Enter a description..." :rows="6" />
+     * <SkTextarea v-model="notes" kind="primary" size="lg" />
+     * <SkField label="Bio" :error="errors.bio">
+     *   <SkTextarea v-model="bio" name="bio" :rows="4" />
+     * </SkField>
+     * ```
      */
 
     import { type ComputedRef, computed, inject, toRef } from 'vue';
@@ -44,28 +54,76 @@
 
     //------------------------------------------------------------------------------------------------------------------
 
-    /**
-     * A multiline textarea component with validation states and semantic color support.
-     */
     export interface SkTextareaComponentProps extends ComponentCustomColors
     {
-        /** Semantic color kind (useful for validation states) */
+        /**
+         * Semantic color kind for the textarea border and focus ring. Use semantic kinds like
+         * 'success' or 'danger' to indicate validation states. When used inside an SkField with
+         * a `state` prop, the field's kind automatically overrides this value.
+         * @default 'neutral'
+         */
         kind ?: SkTextareaKind;
-        /** Textarea size */
+
+        /**
+         * Textarea size controlling padding and font size. The height is primarily controlled
+         * by the `rows` prop. Available sizes: 'sm' (small), 'md' (medium, default), 'lg' (large),
+         * 'xl' (extra large).
+         * @default 'md'
+         */
         size ?: SkTextareaSize;
-        /** Placeholder text */
+
+        /**
+         * Placeholder text displayed when the textarea is empty. Use to provide hints about
+         * expected content or formatting. The placeholder disappears when the user begins typing.
+         * @default undefined
+         */
         placeholder ?: string;
-        /** Disabled state */
+
+        /**
+         * When true, disables the textarea preventing all user interaction. The textarea appears
+         * with reduced opacity and the cursor changes to not-allowed. Disabled textareas are
+         * excluded from form submission.
+         * @default false
+         */
         disabled ?: boolean;
-        /** Read-only state */
+
+        /**
+         * When true, makes the textarea read-only. The user can select and copy text but cannot
+         * modify it. Unlike disabled, read-only textareas are still included in form submission
+         * and maintain normal visual appearance.
+         * @default false
+         */
         readonly ?: boolean;
-        /** Required for form validation */
+
+        /**
+         * When true, marks the textarea as required for form validation. The browser will prevent
+         * form submission if the textarea is empty. For visual required indicators, wrap the
+         * textarea in an SkField component with `required` prop.
+         * @default false
+         */
         required ?: boolean;
-        /** Form field name */
+
+        /**
+         * The form field name used when submitting the textarea value. Required for native form
+         * submission and useful for form libraries that track fields by name.
+         * @default undefined
+         */
         name ?: string;
-        /** Number of visible text rows */
+
+        /**
+         * The number of visible text lines (rows) for the textarea. This sets the initial height
+         * of the textarea. Users can still resize it vertically if the CSS allows. Use more rows
+         * for content that typically requires more space (e.g., descriptions, messages).
+         * @default 4
+         */
         rows ?: number;
-        /** Autocomplete hint */
+
+        /**
+         * Autocomplete hint for the browser's autofill feature. For textareas, common values
+         * include 'off' to disable autofill, or 'street-address' for address fields. Most
+         * other autocomplete values are more relevant for single-line inputs.
+         * @default undefined
+         */
         autocomplete ?: string;
     }
 
@@ -85,6 +143,11 @@
 
     //------------------------------------------------------------------------------------------------------------------
 
+    /**
+     * The textarea value. Use with `v-model` for two-way binding. Always a string value
+     * representing the multiline text content.
+     * @default ''
+     */
     const modelValue = defineModel<string>({ default: '' });
 
     //------------------------------------------------------------------------------------------------------------------

package/src/components/Theme/SkTheme.vue

@@ -12,17 +12,41 @@
 
 <script setup lang="ts">
     /**
-     * @component
-     * A theme provider component that controls the color scheme for all child components.
-     * Wrap your application or sections in this component to apply a theme.
+     * @component SkTheme
+     * @description A theme provider component that establishes the color scheme context for all child components.
+     * Place SkTheme at the root of your application or wrap specific sections to apply different themes.
+     * The component sets the `data-scheme` attribute and provides theme context to portal components
+     * (SkDropdown, SkModal, SkTooltip, etc.) so they render with correct colors even when portaled to the body.
+     *
+     * @example
+     * ```vue
+     * <SkTheme theme="colorful">
+     *     <SkButton kind="primary">Themed Button</SkButton>
+     *     <SkDropdown trigger-text="Menu">
+     *         <SkDropdownMenuItem>Item 1</SkDropdownMenuItem>
+     *     </SkDropdown>
+     * </SkTheme>
+     * ```
+     *
+     * @slot default - All application content that should inherit this theme context. Nested SkTheme components
+     *                 can override the theme for subsections of the UI.
      */
 
     import { provide, watch } from 'vue';
+
+    // Types
     import type { SkThemeComponentProps } from './types';
+
+    // Composables
     import { provideTheme } from './useTheme';
 
     //------------------------------------------------------------------------------------------------------------------
 
+    /**
+     * Props interface is defined in ./types.ts and includes:
+     * - `theme`: The theme name ('greyscale' or 'colorful') that controls the overall color scheme.
+     *   The theme value is reactive and can be changed dynamically to switch themes at runtime.
+     */
     const props = withDefaults(defineProps<SkThemeComponentProps>(), {
         theme: 'greyscale',
     });

package/src/components/Theme/types.ts

@@ -2,15 +2,24 @@
 // Theme Component Types
 //----------------------------------------------------------------------------------------------------------------------
 
-export type SkThemeName = 'greyscale' | 'colorful';
-
 /**
- * A theme provider component that controls the color scheme for all child components.
- * Wrap your application or sections in this component to apply a theme.
+ * Available theme names that control the overall color scheme of the application.
+ * - 'greyscale': A monochromatic theme with neutral grays and subtle accents
+ * - 'colorful': A vibrant theme with saturated colors and stronger contrasts
  */
+export type SkThemeName = 'greyscale' | 'colorful';
+
+//----------------------------------------------------------------------------------------------------------------------
+
 export interface SkThemeComponentProps
 {
-    /** Theme name controlling the overall color scheme (greyscale or colorful) */
+    /**
+     * The active theme name that controls the color scheme for all child components.
+     * Changing this prop reactively updates the theme across the entire subtree.
+     * Portal components (dropdowns, modals, tooltips) automatically inherit this
+     * theme even though they render outside the DOM hierarchy.
+     * @default 'greyscale'
+     */
     theme ?: SkThemeName;
 }
 

package/src/components/Toast/SkToast.vue

@@ -93,9 +93,25 @@
 
 <script setup lang="ts">
     /**
-     * @component
-     * Internal toast component used by SkToastProvider.
-     * Not exported directly - use useToast() to create toasts.
+     * @component SkToast
+     * @description Internal toast notification component used by SkToastProvider. This component renders individual
+     * toast messages with an icon, title, message, and optional close button. Built on RekaUI's Toast primitive
+     * with semantic color variants and auto-dismiss functionality. Not exported directly - use the `useToast()`
+     * composable to create toasts programmatically.
+     *
+     * @example
+     * ```vue
+     * <!-- Used internally by SkToastProvider - do not use directly -->
+     * <SkToast
+     *   id="toast-1"
+     *   kind="success"
+     *   title="Success!"
+     *   message="Your changes have been saved."
+     *   :duration="5000"
+     *   :closable="true"
+     *   @dismiss="handleDismiss"
+     * />
+     * ```
      */
 
     import { computed } from 'vue';
@@ -113,17 +129,43 @@
 
     interface SkToastProps
     {
-        /** Toast ID for tracking */
+        /**
+         * Unique identifier for this toast instance. Used internally for tracking and dismissing
+         * specific toasts. Generated automatically by SkToastProvider when using useToast().
+         */
         id : string;
-        /** Semantic kind */
+
+        /**
+         * Semantic color kind that determines the toast's visual appearance and icon. Each kind
+         * displays a contextually appropriate icon: info (circle-i), success (checkmark),
+         * warning (triangle), danger (x-circle). The kind also sets the background and text colors.
+         */
         kind : SkToastKind;
-        /** Optional title */
+
+        /**
+         * Optional bold title text displayed above the message. Use for brief headings like
+         * "Success!", "Error", or "Warning". When omitted, only the message is displayed.
+         */
         title ?: string;
-        /** Toast message */
+
+        /**
+         * The main toast message content. This is the primary text users will read, describing
+         * what happened or what action was taken. Keep messages concise and actionable.
+         */
         message : string;
-        /** Duration in ms (0 = no auto-dismiss) */
+
+        /**
+         * Time in milliseconds before the toast automatically dismisses. Set to 0 or undefined
+         * to disable auto-dismiss and require manual closure. When set, a progress indicator
+         * may show remaining time. Overrides the provider's default duration.
+         */
         duration ?: number;
-        /** Whether to show close button */
+
+        /**
+         * When true, displays an X button allowing users to manually dismiss the toast before
+         * the duration expires. Essential for toasts with important information users may need
+         * more time to read, or when auto-dismiss is disabled.
+         */
         closable : boolean;
     }
 
@@ -131,6 +173,11 @@
 
     const props = defineProps<SkToastProps>();
 
+    /**
+     * @event dismiss - Emitted when the toast is dismissed, either by auto-dismiss timeout,
+     * user clicking the close button, or swipe gesture. The toast ID is passed to allow
+     * the provider to remove it from the active toasts list.
+     */
     const emit = defineEmits<{
         dismiss : [ id : string ];
     }>();

package/src/components/Toast/SkToastProvider.vue

@@ -35,11 +35,33 @@
 
 <script setup lang="ts">
     /**
-     * @component
-     * Toast provider and viewport combined.
+     * @component SkToastProvider
+     * @description Toast notification system provider that manages and displays toast messages. Wrap your application
+     * (or a section of it) with this component to enable toast notifications. Use the `useToast()` composable from
+     * anywhere within the provider tree to show notifications programmatically. Supports swipe-to-dismiss, keyboard
+     * navigation, and configurable positioning.
      *
-     * Wrap your app (or a section) with this component to enable toasts.
-     * Use the useToast() composable to show toasts from anywhere in the tree.
+     * @example
+     * ```vue
+     * <!-- In your App.vue or layout component -->
+     * <SkTheme>
+     *   <SkToastProvider position="bottom-right" :duration="5000">
+     *     <RouterView />
+     *   </SkToastProvider>
+     * </SkTheme>
+     * ```
+     *
+     * @example Using the toast API in any child component
+     * ```ts
+     * import { useToast } from 'sleekspace-ui';
+     *
+     * const toast = useToast();
+     * toast.add({ kind: 'success', message: 'Settings saved!' });
+     * ```
+     *
+     * @slot default - Your application content. All child components can access the toast API via useToast().
+     *
+     * @see useToast - Composable for showing toasts from any component
      */
 
     import { computed, provide, ref } from 'vue';
@@ -57,41 +79,45 @@
 
     //------------------------------------------------------------------------------------------------------------------
 
-    /**
-     * Toast provider that manages and displays toast notifications.
-     *
-     * Wrap your app with this component to enable toasts. Use useToast() composable
-     * to show notifications from anywhere in the tree.
-     *
-     * @see useToast - Composable for showing toasts
-     */
     export interface SkToastProviderComponentProps
     {
         /**
-         * Preset position for the viewport. If omitted, position via CSS/classes.
+         * Preset position for the toast viewport on the screen. Controls where toasts appear
+         * and stack. Choose a position that doesn't obstruct important UI elements. Common
+         * choices are 'bottom-right' for desktop apps and 'top-center' for mobile-first designs.
+         * When omitted, you can position the viewport via custom CSS instead.
+         * @default undefined
          */
         position ?: SkToastPosition;
 
         /**
-         * Default duration (ms) before auto-dismiss.
+         * Default duration in milliseconds before toasts automatically dismiss. Individual
+         * toasts can override this value. Set to 0 to disable auto-dismiss by default,
+         * requiring users to manually close each toast. Recommended range: 3000-7000ms.
          * @default 5000
          */
         duration ?: number;
 
         /**
-         * Direction to swipe to dismiss.
+         * Direction users can swipe to dismiss toasts on touch devices. The natural direction
+         * often matches the toast position - 'right' for right-positioned toasts, 'up' for
+         * top-positioned, etc. Set to the direction that feels like "dismissing" the toast.
          * @default 'right'
          */
         swipeDirection ?: SkToastSwipeDirection;
 
         /**
-         * Distance (px) to swipe before dismissing.
+         * Minimum distance in pixels a user must swipe before the toast dismisses. Lower values
+         * make dismissal easier but may cause accidental dismissals. Higher values require more
+         * intentional swipes. Balance based on your target devices and user needs.
          * @default 50
          */
         swipeThreshold ?: number;
 
         /**
-         * Keyboard shortcut to focus toasts.
+         * Keyboard shortcut(s) to focus the toast region for screen reader users and keyboard
+         * navigation. When pressed, focus moves to the toast viewport. Use an array to define
+         * multiple shortcuts. Keys use standard keyboard event key names.
          * @default ['F8']
          */
         hotkey ?: string[];

package/src/components/Tooltip/SkTooltip.vue

@@ -52,8 +52,26 @@
 
 <script setup lang="ts">
     /**
-     * @component
-     * Tooltip component for displaying hover hints
+     * @component SkTooltip
+     * @description A tooltip component for displaying contextual hints on hover or focus. Built on RekaUI's Tooltip
+     * primitive with beveled corner styling and full accessibility support. Works standalone with its own timing,
+     * or wrap multiple tooltips in SkTooltipProvider for coordinated "skip delay" behavior where moving quickly
+     * between tooltips shows them instantly.
+     *
+     * @example
+     * ```vue
+     * <SkTooltip side="right" kind="primary">
+     *   <template #trigger>
+     *     <SkButton icon>?</SkButton>
+     *   </template>
+     *   Click here to learn more about this feature.
+     * </SkTooltip>
+     * ```
+     *
+     * @slot trigger - The element that triggers the tooltip on hover/focus. Use `as-child` behavior - the trigger
+     *   slot content becomes the actual trigger element. Required slot.
+     * @slot default - The tooltip content to display. Can include text, formatted content, or simple components.
+     *   Keep content brief for tooltips; use SkPopover for richer interactions.
      */
 
     import { computed, inject, toRef } from 'vue';
@@ -76,49 +94,62 @@
 
     //------------------------------------------------------------------------------------------------------------------
 
-    /**
-     * Tooltip component for displaying hover hints.
-     *
-     * Works in two modes:
-     * - **Standalone**: Each tooltip manages its own timing (default)
-     * - **With Provider**: Wrap tooltips in SkTooltipProvider for coordinated behavior
-     *
-     * The provider enables "skip delay" - moving quickly between tooltips shows them instantly.
-     *
-     * @example Standalone (works out of the box)
-     * ```vue
-     * <SkTooltip>
-     *   <template #trigger><SkButton>Hover me</SkButton></template>
-     *   Tooltip content
-     * </SkTooltip>
-     * ```
-     *
-     * @example With provider (coordinated tooltips)
-     * ```vue
-     * <SkTooltipProvider :delay-duration="300">
-     *   <SkTooltip>...</SkTooltip>
-     *   <SkTooltip>...</SkTooltip>
-     * </SkTooltipProvider>
-     * ```
-     */
     export interface SkTooltipComponentProps extends ComponentCustomColors
     {
-        /** Semantic color kind */
+        /**
+         * Semantic color kind that controls the tooltip's background and text colors. Semantic kinds
+         * (neutral, primary, accent, info, success, warning, danger) adapt to your theme. Use 'neutral'
+         * for general hints, or match the kind to contextual meaning (e.g., 'warning' for caution tips).
+         * @default 'neutral'
+         */
         kind ?: ComponentKind;
-        /** Visual variant */
+
+        /**
+         * Visual variant that controls the tooltip's appearance. 'solid' shows a filled background
+         * with the kind color, ideal for high-contrast visibility. 'outline' shows a bordered style
+         * with transparent background, useful for subtle hints that don't distract from content.
+         * @default 'solid'
+         */
         variant ?: 'solid' | 'outline';
-        /** Which side of the trigger to show the tooltip */
+
+        /**
+         * Which side of the trigger element to display the tooltip. The tooltip automatically
+         * flips to the opposite side if there isn't enough space. Common choices: 'top' for
+         * buttons, 'right' for inline help icons, 'bottom' for navigation items.
+         * @default 'top'
+         */
         side ?: SkTooltipSide;
-        /** Alignment along the side */
+
+        /**
+         * Alignment of the tooltip along its side. 'center' centers the tooltip on the trigger,
+         * 'start' aligns to the left/top edge, 'end' aligns to the right/bottom edge. Use 'start'
+         * or 'end' when the trigger is near a screen edge to prevent clipping.
+         * @default 'center'
+         */
         align ?: 'start' | 'center' | 'end';
-        /** Offset from the trigger in pixels */
+
+        /**
+         * Distance in pixels between the tooltip and its trigger element. Increase for more
+         * breathing room, decrease for tighter coupling. The arrow (if shown) extends from
+         * this offset toward the trigger.
+         * @default 5
+         */
         sideOffset ?: number;
+
         /**
-         * Delay before showing tooltip (ms). Only used in standalone mode.
-         * When inside SkTooltipProvider, the provider's delayDuration is used instead.
+         * Delay in milliseconds before the tooltip appears after hovering the trigger. Only used
+         * in standalone mode - when inside SkTooltipProvider, the provider's delayDuration takes
+         * precedence. Set to 0 for instant tooltips, or higher values to avoid accidental triggers.
+         * @default 400
          */
         delayDuration ?: number;
-        /** Whether to show the arrow pointing to the trigger */
+
+        /**
+         * Whether to display a small arrow pointing from the tooltip toward its trigger element.
+         * Arrows help visually connect the tooltip to its trigger, especially useful when multiple
+         * interactive elements are close together. Disable for a cleaner, more minimal appearance.
+         * @default true
+         */
         showArrow ?: boolean;
     }
 

package/src/components/Tooltip/SkTooltipProvider.vue

@@ -15,80 +15,80 @@
 
 <script setup lang="ts">
     /**
-     * @component
-     * Provider component for tooltips that enables shared behavior across all child SkTooltip instances.
+     * @component SkTooltipProvider
+     * @description Provider component that enables coordinated tooltip behavior across all child SkTooltip instances.
+     * When tooltips share a provider, they gain "skip delay" functionality - users can quickly move between tooltips
+     * without waiting for the delay each time. Also centralizes configuration like delay duration and accessibility
+     * options. Optional but recommended for apps with multiple tooltips.
      *
-     * When SkTooltip components are wrapped in SkTooltipProvider, they share a common context that enables:
-     * - **Skip delay**: Moving quickly between tooltips shows the next one immediately
-     * - **Shared configuration**: Set delay duration once for all tooltips
-     * - **Consistent behavior**: All tooltips behave as a coordinated group
-     *
-     * Without a provider, each SkTooltip creates its own isolated context and works independently.
-     * Both patterns are valid - use the provider when you want coordinated tooltip behavior.
-     */
-
-    import { provide } from 'vue';
-    import { TooltipProvider } from 'reka-ui';
-
-    //------------------------------------------------------------------------------------------------------------------
-
-    /**
-     * Provider component for tooltips that enables shared behavior.
-     *
-     * @example Basic usage - wrap your app or a section
-     * ```vue
-     * <SkTooltipProvider :delay-duration="300" :skip-delay-duration="100">
-     *   <MyApp />
-     * </SkTooltipProvider>
-     * ```
-     *
-     * @example In App.vue for app-wide tooltip coordination
+     * @example
      * ```vue
      * <template>
      *   <SkTheme theme="colorful">
-     *     <SkTooltipProvider>
+     *     <SkTooltipProvider :delay-duration="300" :skip-delay-duration="100">
      *       <RouterView />
      *     </SkTooltipProvider>
      *   </SkTheme>
      * </template>
      * ```
+     *
+     * @slot default - Your application content containing SkTooltip components. All descendant tooltips
+     *   will share the provider's timing and behavior configuration.
      */
+
+    import { provide } from 'vue';
+    import { TooltipProvider } from 'reka-ui';
+
+    //------------------------------------------------------------------------------------------------------------------
+
     export interface SkTooltipProviderProps
     {
         /**
-         * The duration (ms) from when the pointer enters the trigger until the tooltip opens.
+         * Delay in milliseconds from when the pointer enters a tooltip trigger until the tooltip
+         * opens. Applies to all SkTooltip components within this provider. A short delay (200-400ms)
+         * prevents tooltips from flashing when users move the mouse across the UI. Set to 0 for
+         * instant tooltips, though this may feel jarring.
          * @default 400
          */
         delayDuration ?: number;
 
         /**
-         * How much time (ms) a user has to enter another trigger without incurring a delay again.
-         * This creates the "skip delay" behavior where moving between tooltips feels instant.
+         * Time window in milliseconds during which moving to another tooltip skips the delay entirely.
+         * After showing one tooltip, if the user hovers another trigger within this window, it appears
+         * instantly. This creates smooth "scanning" behavior when exploring a toolbar or menu. Set to
+         * 0 to disable skip delay behavior.
          * @default 300
          */
         skipDelayDuration ?: number;
 
         /**
-         * When true, hovering over the tooltip content will close it (pointer must stay on trigger).
+         * When true, moving the pointer from the trigger onto the tooltip content closes the tooltip.
+         * By default, users can hover over tooltip content (useful for links or selectable text).
+         * Enable this for simpler tooltips where you want strict trigger-only behavior.
          * @default false
          */
         disableHoverableContent ?: boolean;
 
         /**
-         * When true, clicking on the trigger will not close the tooltip.
+         * When true, clicking the trigger element does not close an open tooltip. By default,
+         * clicking the trigger dismisses the tooltip. Enable this if your trigger performs an
+         * action where the tooltip should remain visible for confirmation feedback.
          * @default false
          */
         disableClosingTrigger ?: boolean;
 
         /**
-         * When true, tooltips only open on keyboard focus (not mouse focus).
-         * Matches against :focus-visible selector.
+         * When true, tooltips only appear on keyboard focus (Tab navigation), not on mouse focus.
+         * Uses the `:focus-visible` heuristic to distinguish intentional keyboard focus from
+         * programmatic or mouse-triggered focus. Enable for reduced visual noise on mouse-heavy UIs.
          * @default false
          */
         ignoreNonKeyboardFocus ?: boolean;
 
         /**
-         * When true, disables all tooltips within this provider.
+         * When true, completely disables all tooltips within this provider. Useful for temporarily
+         * suppressing tooltips during certain UI states (like drag operations or touch interactions)
+         * or for user preference settings. Tooltips remain in the DOM but won't open.
          * @default false
          */
         disabled ?: boolean;

package/src/composables/usePortalContext.test.ts

@@ -2,6 +2,8 @@
 // Portal Context Composable Tests
 //----------------------------------------------------------------------------------------------------------------------
 
+/* eslint-disable vue/one-component-per-file */
+
 import { describe, expect, it } from 'vitest';
 import { defineComponent, h, inject, provide, ref } from 'vue';
 import { mount } from '@vue/test-utils';