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

package/src/components/Panel/SkPanel.vue

@@ -21,31 +21,65 @@
 
 <script setup lang="ts">
     /**
-     * @component
-     * A foundational container component with borders, background colors, and optional decorative accents.
-     * Serves as the base for other components like SkCard and SkSidebar.
+     * @component SkPanel
+     * @description A foundational container component with beveled corners, borders, background colors, and an optional
+     * decorative accent stripe. Panels serve as the base building block for higher-level components like SkCard and
+     * SkSidebar, providing consistent styling and theming across the design system.
+     *
+     * @example
+     * ```vue
+     * <SkPanel kind="primary" size="lg">
+     *     <p>Panel content goes here</p>
+     * </SkPanel>
+     * ```
+     *
+     * @slot default - The main content of the panel. Accepts any valid Vue content including text, components, or HTML.
      */
 
     import { computed, toRef } from 'vue';
-    import type { SkPanelKind, SkPanelSize } from './types';
+
+    // Types
     import type { ComponentCustomColors } from '@/types';
+    import type { SkPanelKind, SkPanelSize } from './types';
+
+    // Composables
     import { useCustomColors } from '@/composables/useCustomColors';
 
     //------------------------------------------------------------------------------------------------------------------
 
-    /**
-     * A foundational container component with borders, background colors, and optional decorative accents.
-     * Serves as the base for other components like SkCard and SkSidebar.
-     */
     export interface SkPanelComponentProps extends ComponentCustomColors
     {
-        /** Semantic color kind for the panel */
+        /**
+         * Semantic color kind that controls the panel's border color and decorative accent stripe.
+         * Semantic kinds (neutral, primary, accent, etc.) automatically adapt to your current theme,
+         * while color kinds (neon-blue, neon-purple, etc.) provide fixed branding colors that remain
+         * consistent across themes.
+         * @default 'neutral'
+         */
         kind ?: SkPanelKind;
-        /** Size affecting padding and spacing inside the panel */
+
+        /**
+         * Controls the internal padding of the panel. Larger sizes provide more breathing room
+         * for content, while smaller sizes create compact, dense layouts. Available sizes:
+         * 'sm' (small), 'md' (medium), 'lg' (large), 'xl' (extra large).
+         * @default 'md'
+         */
         size ?: SkPanelSize;
-        /** Whether to display the decorative accent border */
+
+        /**
+         * When true, displays a colored accent stripe along the top edge of the panel.
+         * The stripe color matches the selected `kind`. This decoration is automatically
+         * disabled when `noBorder` is true since the decoration is part of the border styling.
+         * @default true
+         */
         showDecoration ?: boolean;
-        /** Whether to remove the border entirely */
+
+        /**
+         * When true, removes the border entirely from the panel, creating a borderless container.
+         * Useful for nested panels or when you want the panel background without visual boundaries.
+         * Note: Setting this to true automatically disables the decoration stripe.
+         * @default false
+         */
         noBorder ?: boolean;
     }
 

package/src/components/Popover/SkPopover.vue

@@ -68,9 +68,36 @@
 
 <script setup lang="ts">
     /**
-     * @component
-     * Popover component for floating panels positioned relative to a trigger.
-     * Combines tooltip-like positioning with card-like structure.
+     * @component SkPopover
+     * @description A floating panel component for displaying rich interactive content anchored to a trigger element.
+     * Combines tooltip-like positioning with a card-like structure including optional header, body, and footer
+     * sections. Built on RekaUI's Popover primitive with full accessibility support, smart collision detection,
+     * and keyboard navigation. Use for contextual menus, confirmations, mini-forms, or any content that benefits
+     * from staying connected to its trigger.
+     *
+     * @example
+     * ```vue
+     * <SkPopover title="Quick Settings" kind="primary">
+     *   <template #trigger>
+     *     <SkButton icon><GearIcon /></SkButton>
+     *   </template>
+     *   <SkSwitch v-model="darkMode" label="Dark mode" />
+     *   <SkSwitch v-model="notifications" label="Notifications" />
+     *   <template #footer>
+     *     <SkButton variant="ghost" size="sm">Reset</SkButton>
+     *     <SkButton kind="primary" size="sm">Apply</SkButton>
+     *   </template>
+     * </SkPopover>
+     * ```
+     *
+     * @slot trigger - The element that opens the popover when clicked. Uses `as-child` behavior so your
+     *   trigger element becomes the actual clickable trigger. Required slot.
+     * @slot header - Optional header content displayed after the title. Use for additional header elements
+     *   like badges, status indicators, or secondary actions.
+     * @slot default - Main body content of the popover. Can include any components, forms, or interactive content.
+     *   Scrolls if content exceeds available space.
+     * @slot footer - Optional footer content, typically for action buttons. Commonly contains Cancel/Confirm
+     *   button pairs or other closing actions.
      */
 
     import { computed, toRef } from 'vue';
@@ -93,48 +120,71 @@
 
     //------------------------------------------------------------------------------------------------------------------
 
-    /**
-     * Popover component for floating panels positioned relative to a trigger.
-     *
-     * Combines tooltip-like positioning with card-like structure for rich content.
-     *
-     * @example Basic usage with title
-     * ```vue
-     * <SkPopover title="Settings">
-     *   <template #trigger><SkButton>Open</SkButton></template>
-     *   <p>Popover content here</p>
-     * </SkPopover>
-     * ```
-     *
-     * @example With footer actions
-     * ```vue
-     * <SkPopover title="Confirm Action" kind="danger">
-     *   <template #trigger><SkButton kind="danger">Delete</SkButton></template>
-     *   <p>Are you sure you want to delete this item?</p>
-     *   <template #footer>
-     *     <SkButton variant="ghost" size="sm">Cancel</SkButton>
-     *     <SkButton kind="danger" size="sm">Delete</SkButton>
-     *   </template>
-     * </SkPopover>
-     * ```
-     */
     export interface SkPopoverComponentProps extends ComponentCustomColors
     {
-        /** Semantic color kind */
+        /**
+         * Semantic color kind that controls the popover's header accent and overall color scheme.
+         * Semantic kinds (neutral, primary, accent, info, success, warning, danger) adapt to your
+         * theme. Use 'neutral' for general popovers, or match the kind to contextual meaning
+         * (e.g., 'danger' for delete confirmations, 'success' for completion messages).
+         * @default 'neutral'
+         */
         kind ?: ComponentKind;
-        /** Which side of the trigger to show the popover */
+
+        /**
+         * Which side of the trigger element to display the popover. The popover automatically
+         * repositions if there isn't enough space on the preferred side. 'bottom' works well
+         * for toolbars, 'right' for sidebar items, 'top' for footer elements.
+         * @default 'bottom'
+         */
         side ?: SkPopoverSide;
-        /** Alignment along the side */
+
+        /**
+         * Alignment of the popover along its side. 'center' centers the popover on the trigger,
+         * 'start' aligns to the left/top edge, 'end' aligns to the right/bottom edge. Useful
+         * when triggers are near screen edges or when you want the arrow to point at a specific
+         * part of the trigger.
+         * @default 'center'
+         */
         align ?: SkPopoverAlign;
-        /** Offset from the trigger in pixels */
+
+        /**
+         * Distance in pixels between the popover and its trigger element. Increase for more
+         * visual separation, decrease for tighter coupling. The arrow (if shown) bridges
+         * this gap to maintain visual connection.
+         * @default 8
+         */
         sideOffset ?: number;
-        /** Whether to show the arrow pointing to the trigger */
+
+        /**
+         * Whether to display a small arrow pointing from the popover toward its trigger element.
+         * Arrows help visually anchor the popover to its trigger, especially important when
+         * multiple triggers are close together. Disable for a cleaner, card-like appearance.
+         * @default true
+         */
         showArrow ?: boolean;
-        /** Optional title displayed in the header */
+
+        /**
+         * Optional title text displayed in the popover header. Creates a header section with
+         * the title and close button (if closable). When omitted and no header slot is provided,
+         * no header is rendered, creating a content-only popover.
+         */
         title ?: string;
-        /** Whether to show a close button in the header */
+
+        /**
+         * Whether to show an X close button in the header. Provides an obvious way for users
+         * to dismiss the popover beyond clicking outside. Automatically creates a header section
+         * if title is also set. Users can always close by clicking outside or pressing Escape.
+         * @default true
+         */
         closable ?: boolean;
-        /** Control the open state (v-model) */
+
+        /**
+         * Controls the popover's open state for two-way binding with `v-model:open`. When provided,
+         * you control when the popover opens and closes. When omitted, the popover manages its own
+         * state internally (opens on trigger click, closes on outside click or Escape).
+         * @default undefined
+         */
         open ?: boolean;
     }
 
@@ -151,6 +201,11 @@
         open: undefined,
     });
 
+    /**
+     * @event update:open - Emitted when the popover's open state changes. Use with `v-model:open` for
+     * two-way binding. Receives `true` when the popover opens (trigger clicked) and `false` when it
+     * closes (outside click, Escape key, or close button).
+     */
     const emit = defineEmits<{
         'update:open' : [ value : boolean ];
     }>();

package/src/components/Progress/SkProgress.vue

@@ -29,8 +29,30 @@
 <script setup lang="ts">
     /**
      * @component SkProgress
-     * A progress bar component with determinate and indeterminate modes.
-     * Supports all 7 semantic kinds and custom colors.
+     * @description A progress bar component for displaying completion status or loading states. Supports both
+     * determinate mode (showing specific progress percentage) and indeterminate mode (animated loading indicator
+     * when progress is unknown). Built on RekaUI's Progress primitive with beveled corner styling.
+     *
+     * @example
+     * ```vue
+     * <SkProgress :value="75" kind="primary" show-value />
+     * ```
+     *
+     * @example Indeterminate loading state
+     * ```vue
+     * <SkProgress :value="null" kind="accent" />
+     * ```
+     *
+     * @example Custom colors with file upload
+     * ```vue
+     * <SkProgress
+     *     :value="uploadProgress"
+     *     base-color="oklch(0.7 0.2 145)"
+     *     track-color="oklch(0.3 0.05 145)"
+     *     show-value
+     *     value-position="right"
+     * />
+     * ```
      */
 
     import { computed } from 'vue';
@@ -44,21 +66,63 @@
 
     export interface SkProgressComponentProps
     {
-        /** Progress value (0 to max). Use null or undefined for indeterminate state */
+        /**
+         * The current progress value between 0 and `max`. Pass `null` or `undefined` to enable
+         * indeterminate mode, which displays an animated loading indicator instead of a specific
+         * percentage. Use indeterminate mode when the operation duration is unknown.
+         * @default null
+         */
         value ?: number | null;
-        /** Maximum value */
+
+        /**
+         * The maximum value representing 100% completion. Adjust this when your progress is
+         * measured in units other than percentages (e.g., bytes downloaded, steps completed).
+         * The percentage is calculated as `(value / max) * 100`.
+         * @default 100
+         */
         max ?: number;
-        /** Semantic color kind */
+
+        /**
+         * Semantic color kind that controls the progress bar fill color. Semantic kinds
+         * (neutral, primary, accent, etc.) adapt to your theme, making it easy to indicate
+         * success (primary/success), warning states, or danger levels.
+         * @default 'primary'
+         */
         kind ?: ComponentKind;
-        /** Bar height size */
+
+        /**
+         * Height size of the progress bar. Use 'sm' for inline or compact layouts, 'md' for
+         * standard forms, and 'lg' or 'xl' for prominent progress displays.
+         * @default 'md'
+         */
         size ?: SkProgressSize;
-        /** Show percentage label */
+
+        /**
+         * When true, displays the current percentage value as a text label on the progress bar.
+         * The label is automatically hidden in indeterminate mode since no percentage is available.
+         * @default false
+         */
         showValue ?: boolean;
-        /** Position of the value label */
+
+        /**
+         * Position of the percentage label when `showValue` is true. Choose 'left' for
+         * left-aligned, 'center' for centered over the bar, or 'right' for right-aligned.
+         * @default 'center'
+         */
         valuePosition ?: SkProgressValuePosition;
-        /** Custom bar color (overrides kind) */
+
+        /**
+         * Custom color for the progress bar fill, overriding the `kind` color. Accepts any
+         * valid CSS color value. Use OKLCH colors for consistency with the design system
+         * (e.g., "oklch(0.7 0.2 145)").
+         */
         baseColor ?: string;
-        /** Custom track/background color */
+
+        /**
+         * Custom color for the progress bar track (background), overriding the default track
+         * color. Accepts any valid CSS color value. Useful for creating custom color schemes
+         * or matching specific brand colors.
+         */
         trackColor ?: string;
     }
 

package/src/components/Radio/SkRadio.vue

@@ -28,9 +28,22 @@
 
 <script setup lang="ts">
     /**
-     * @component
-     * An individual radio button component powered by RekaUI.
-     * Must be used within SkRadioGroup.
+     * @component SkRadio
+     * @description An individual radio button for mutually exclusive selection within a group. Must be used as
+     * a child of SkRadioGroup, which manages the selection state and keyboard navigation. Built on RekaUI's
+     * RadioGroup primitive with beveled corner styling and full accessibility support.
+     *
+     * @example
+     * ```vue
+     * <SkRadioGroup v-model="selectedSize" kind="primary">
+     *     <SkRadio value="sm" label="Small" />
+     *     <SkRadio value="md" label="Medium" />
+     *     <SkRadio value="lg" label="Large" />
+     * </SkRadioGroup>
+     * ```
+     *
+     * @slot default - Custom label content. Overrides the `label` prop when provided, allowing for rich
+     *                 formatting, icons, or complex layouts alongside the radio button.
      */
 
     import { type ComputedRef, computed, inject, toRef } from 'vue';
@@ -45,21 +58,44 @@
 
     //------------------------------------------------------------------------------------------------------------------
 
-    /**
-     * An individual radio button component powered by RekaUI.
-     * Must be used within SkRadioGroup.
-     */
     export interface SkRadioComponentProps extends ComponentCustomColors
     {
-        /** Value for this radio option */
+        /**
+         * The value this radio option represents. When selected, the parent SkRadioGroup's
+         * v-model will be set to this value. Must be unique within the radio group to ensure
+         * proper selection behavior.
+         */
         value : string | number;
-        /** Label text (can be overridden by default slot) */
+
+        /**
+         * Label text displayed next to the radio button. Can be overridden by the default
+         * slot for custom label content (icons, formatted text, etc.). If neither label
+         * nor slot content is provided, only the radio circle is rendered.
+         */
         label ?: string;
-        /** Disabled state */
+
+        /**
+         * When true, this radio option is disabled and cannot be selected. The radio
+         * button appears with reduced opacity and the cursor changes to not-allowed.
+         * Does not affect other radio options in the same group.
+         * @default false
+         */
         disabled ?: boolean;
-        /** Semantic color kind (inherits from parent if not set) */
+
+        /**
+         * Semantic color kind that controls the radio button appearance when selected.
+         * If not set, inherits from the parent SkRadioGroup's kind prop. Use to style
+         * individual radio options differently from the group default.
+         * @default Inherited from SkRadioGroup, or 'neutral' if not set
+         */
         kind ?: SkRadioKind;
-        /** Size (inherits from parent if not set) */
+
+        /**
+         * Radio button size. Controls both the radio circle dimensions and the label text
+         * size. If not set, inherits from the parent SkRadioGroup's size prop.
+         * Available sizes: 'sm' (small), 'md' (medium), 'lg' (large), 'xl' (extra large).
+         * @default Inherited from SkRadioGroup, or 'md' if not set
+         */
         size ?: SkRadioSize;
     }
 

package/src/components/Radio/SkRadioGroup.vue

@@ -25,9 +25,22 @@
 
 <script setup lang="ts">
     /**
-     * @component
-     * A radio group container for exclusive selection powered by RekaUI.
-     * Manages state and keyboard navigation for child SkRadio components.
+     * @component SkRadioGroup
+     * @description A container for SkRadio components that manages exclusive selection state and keyboard
+     * navigation. Only one radio option can be selected at a time within a group. Built on RekaUI's
+     * RadioGroup primitive with full accessibility support including arrow key navigation and focus management.
+     *
+     * @example
+     * ```vue
+     * <SkRadioGroup v-model="paymentMethod" kind="primary" orientation="vertical">
+     *     <SkRadio value="credit" label="Credit Card" />
+     *     <SkRadio value="debit" label="Debit Card" />
+     *     <SkRadio value="paypal" label="PayPal" />
+     * </SkRadioGroup>
+     * ```
+     *
+     * @slot default - The SkRadio components that make up the group. Each radio should have a unique
+     *                 `value` prop. Other content like labels or descriptions can also be included.
      */
 
     import { computed, provide } from 'vue';
@@ -38,24 +51,62 @@
 
     //------------------------------------------------------------------------------------------------------------------
 
-    /**
-     * A radio group container for exclusive selection powered by RekaUI.
-     */
     export interface SkRadioGroupComponentProps
     {
-        /** Orientation for layout */
+        /**
+         * Layout orientation of the radio options. Controls how child SkRadio components
+         * are arranged. 'vertical' stacks options top to bottom, 'horizontal' arranges
+         * them left to right. Keyboard arrow navigation adapts to match the orientation.
+         * @default 'vertical'
+         */
         orientation ?: SkRadioGroupOrientation;
-        /** Semantic color kind for all radios */
+
+        /**
+         * Semantic color kind applied to all child SkRadio components. Sets the default
+         * appearance for the entire group. Individual radios can override this by setting
+         * their own `kind` prop.
+         * @default 'neutral'
+         */
         kind ?: SkRadioKind;
-        /** Size for all radios */
+
+        /**
+         * Size applied to all child SkRadio components. Controls the radio circle
+         * dimensions and label text size for the entire group. Individual radios can
+         * override this by setting their own `size` prop.
+         * Available sizes: 'sm' (small), 'md' (medium), 'lg' (large), 'xl' (extra large).
+         * @default 'md'
+         */
         size ?: SkRadioSize;
-        /** Disabled state for entire group */
+
+        /**
+         * When true, the entire radio group is disabled and no options can be selected.
+         * All child radios appear with reduced opacity. Use for temporarily unavailable
+         * form fields or read-only states.
+         * @default false
+         */
         disabled ?: boolean;
-        /** Required for form validation */
+
+        /**
+         * When true, marks the radio group as required for form validation. At least one
+         * option must be selected before the form can be submitted. This does not add
+         * visual indication—use a SkField wrapper for required field styling.
+         * @default false
+         */
         required ?: boolean;
-        /** Form field name */
+
+        /**
+         * The form field name used when submitting the selected value in a form.
+         * Required for native form submission. The selected radio's value is submitted
+         * under this name.
+         */
         name ?: string;
-        /** Enable circular keyboard navigation */
+
+        /**
+         * Enables circular keyboard navigation within the group. When true, pressing
+         * arrow down/right on the last option moves focus to the first option, and
+         * vice versa. When false, navigation stops at the boundaries.
+         * @default true
+         */
         loop ?: boolean;
     }
 
@@ -73,6 +124,11 @@
 
     //------------------------------------------------------------------------------------------------------------------
 
+    /**
+     * The currently selected radio value. Use with `v-model` for two-way binding.
+     * The value corresponds to the `value` prop of the selected SkRadio child.
+     * Initially undefined until the user makes a selection or a default is provided.
+     */
     const modelValue = defineModel<string | number>();
 
     //------------------------------------------------------------------------------------------------------------------

package/src/components/Sidebar/SkSidebar.vue

@@ -23,9 +23,29 @@
 
 <script setup lang="ts">
     /**
-     * @component
-     * A sticky navigation sidebar container with semantic color theming.
-     * Wrap SkSidebarSection and SkSidebarItem components inside.
+     * @component SkSidebar
+     * @description A vertical navigation container designed for persistent page-level navigation. Built on
+     * SkPanel, it provides a scrollable area with a sticky position that remains visible as users scroll
+     * the main content. Organize navigation links using SkSidebarSection for grouped items and SkSidebarItem
+     * for individual navigation links.
+     *
+     * @example
+     * ```vue
+     * <SkSidebar kind="primary" width="200px">
+     *   <SkSidebarSection title="Getting Started">
+     *     <SkSidebarItem as="RouterLink" to="/docs/install">Installation</SkSidebarItem>
+     *     <SkSidebarItem as="RouterLink" to="/docs/usage">Basic Usage</SkSidebarItem>
+     *   </SkSidebarSection>
+     *   <SkSidebarSection title="Components">
+     *     <SkSidebarItem as="RouterLink" to="/docs/button">Button</SkSidebarItem>
+     *     <SkSidebarItem as="RouterLink" to="/docs/input">Input</SkSidebarItem>
+     *   </SkSidebarSection>
+     * </SkSidebar>
+     * ```
+     *
+     * @slot default - Container for SkSidebarSection and/or SkSidebarItem components. Content is wrapped
+     *                 in a scrollable nav element, allowing long navigation lists to scroll independently
+     *                 of the main page content.
      */
 
     import { computed } from 'vue';
@@ -35,35 +55,22 @@
 
     //------------------------------------------------------------------------------------------------------------------
 
-    /**
-     * A sticky navigation sidebar container with semantic color theming.
-     * Wrap SkSidebarSection and SkSidebarItem components inside.
-     *
-     * @example Basic sidebar
-     * ```vue
-     * <SkSidebar>
-     *   <SkSidebarSection title="Navigation">
-     *     <SkSidebarItem to="/home">Home</SkSidebarItem>
-     *     <SkSidebarItem to="/about">About</SkSidebarItem>
-     *   </SkSidebarSection>
-     * </SkSidebar>
-     * ```
-     *
-     * @example Custom colors
-     * ```vue
-     * <SkSidebar
-     *   base-color="oklch(0.3 0.15 260)"
-     *   text-color="oklch(0.85 0.05 260)"
-     * >
-     *   <!-- Sidebar content -->
-     * </SkSidebar>
-     * ```
-     */
     export interface SkSidebarComponentProps extends ComponentCustomColors
     {
-        /** Semantic color kind for the sidebar */
+        /**
+         * Semantic color kind that controls the sidebar panel's background, border, and text colors.
+         * The kind is passed to the underlying SkPanel component. Use semantic kinds like 'neutral'
+         * or 'primary' to match your theme, or use `baseColor`/`textColor` props for custom colors.
+         * @default 'neutral'
+         */
         kind ?: SkSidebarKind;
-        /** CSS width value for the sidebar */
+
+        /**
+         * CSS width value for the sidebar. Accepts any valid CSS width including pixels, rems,
+         * percentages, or viewport units. The sidebar maintains this fixed width while the main
+         * content area fills the remaining space in a typical sidebar layout.
+         * @default '180px'
+         */
         width ?: string;
     }
 

package/src/components/Sidebar/SkSidebarItem.vue

@@ -16,24 +16,49 @@
 
 <script setup lang="ts">
     /**
-     * @component
-     * An individual navigation item in the sidebar.
-     * Can render as any element (a, RouterLink, button, etc).
+     * @component SkSidebarItem
+     * @description A navigation link item for use within SkSidebar. Renders as a polymorphic component that
+     * can be an anchor tag, Vue Router's RouterLink, a button, or any other element/component. Provides
+     * consistent styling with hover and active states that match the parent sidebar's theme.
+     *
+     * @example
+     * ```vue
+     * <!-- As a regular anchor -->
+     * <SkSidebarItem as="a" href="/about">About Us</SkSidebarItem>
+     *
+     * <!-- As Vue Router link -->
+     * <SkSidebarItem as="RouterLink" to="/dashboard" :active="route.path === '/dashboard'">
+     *   Dashboard
+     * </SkSidebarItem>
+     *
+     * <!-- As a button for actions -->
+     * <SkSidebarItem as="button" @click="openSettings">Settings</SkSidebarItem>
+     * ```
+     *
+     * @slot default - The navigation item's label content. Can be plain text or include icons and badges.
      */
 
     import { computed } from 'vue';
 
     //------------------------------------------------------------------------------------------------------------------
 
-    /**
-     * An individual navigation item in the sidebar.
-     * Can render as any element (a, RouterLink, button, etc).
-     */
     export interface SkSidebarItemComponentProps
     {
-        /** HTML tag or component name to render as */
+        /**
+         * The HTML element or Vue component to render as. Use 'a' for standard links, 'RouterLink'
+         * for Vue Router navigation, 'button' for click actions, or any custom component. All
+         * additional attributes (href, to, @click, etc.) are passed through via v-bind="$attrs".
+         * @default 'a'
+         */
         as ?: string;
-        /** Whether this item is currently active */
+
+        /**
+         * When true, applies active/selected styling to indicate this is the current page or
+         * selected item. The active state uses a distinct background color and may include
+         * additional visual indicators. You must manage this prop yourself based on your
+         * routing logic (e.g., comparing against the current route path).
+         * @default false
+         */
         active ?: boolean;
     }