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

package/src/components/Breadcrumbs/SkBreadcrumbs.vue

@@ -1,3 +1,7 @@
+<!----------------------------------------------------------------------------------------------------------------------
+  - Breadcrumbs Component
+  --------------------------------------------------------------------------------------------------------------------->
+
 <template>
     <nav :class="classes" :style="customColorStyles" aria-label="Breadcrumb">
         <ol class="sk-breadcrumbs-list">
@@ -18,6 +22,24 @@
 <!--------------------------------------------------------------------------------------------------------------------->
 
 <script setup lang="ts">
+    /**
+     * @component SkBreadcrumbs
+     * @description A navigation component that displays a hierarchical trail of links showing the user's current
+     * location within an application. Automatically inserts separators between breadcrumb items and provides
+     * ARIA-compliant navigation landmarks for screen readers.
+     *
+     * @example
+     * ```vue
+     * <SkBreadcrumbs kind="primary">
+     *     <SkBreadcrumbItem to="/">Home</SkBreadcrumbItem>
+     *     <SkBreadcrumbItem to="/products">Products</SkBreadcrumbItem>
+     *     <SkBreadcrumbItem current>Widget Pro</SkBreadcrumbItem>
+     * </SkBreadcrumbs>
+     * ```
+     *
+     * @slot default - Contains `SkBreadcrumbItem` components representing each level in the navigation hierarchy.
+     */
+
     import { type Slots, type VNode, computed, provide, toRef, useSlots } from 'vue';
 
     // Types
@@ -28,6 +50,20 @@
 
     export interface SkBreadcrumbsComponentProps extends SkBreadcrumbsProps, ComponentCustomColors
     {
+        /**
+         * Semantic color kind that controls the appearance of breadcrumb links. The kind affects link colors
+         * for normal, hover, and active states. All child `SkBreadcrumbItem` components inherit this kind.
+         * @default 'neutral'
+         */
+        kind ?: SkBreadcrumbsProps['kind'];
+
+        /**
+         * Character or string displayed between breadcrumb items. Common separators include '/', '>', and
+         * unicode characters like '\u203A' (single right-pointing angle quotation mark). Can be overridden
+         * on individual `SkBreadcrumbSeparator` components for custom patterns.
+         * @default '/'
+         */
+        separator ?: string;
     }
 
     //------------------------------------------------------------------------------------------------------------------

package/src/components/Button/SkButton.vue

@@ -43,41 +43,107 @@
 
 <script setup lang="ts">
     /**
-     * @component
-     * A versatile button component with multiple variants, sizes, and states.
-     * Supports rendering as button, link (a), or router-link.
+     * @component SkButton
+     * @description A versatile button component supporting multiple visual variants, sizes, and interactive states.
+     * Automatically renders as a `<button>`, `<a>`, or `<router-link>` based on the props provided. Use for
+     * primary actions, navigation, form submissions, and toggleable controls with full keyboard accessibility.
+     *
+     * @example
+     * ```vue
+     * <SkButton kind="primary" @click="save">Save Changes</SkButton>
+     * <SkButton variant="outline" href="/docs">Documentation</SkButton>
+     * <SkButton :loading="isSaving" kind="accent">Submit</SkButton>
+     * ```
+     *
+     * @slot default - Button label text or content. Supports text, icons, or any inline elements.
+     * @slot leading - Icon or element displayed before the button text. Ideal for action icons.
+     * @slot trailing - Icon or element displayed after the button text. Useful for arrows or indicators.
+     * @slot icon - Icon for icon-only buttons. When used without the default slot, creates a square icon button.
      */
 
     import { type Slots, computed, toRef, useSlots } from 'vue';
-    import type { SkButtonKind, SkButtonSize, SkButtonType, SkButtonVariant } from './types';
+
+    // Types
     import type { ComponentCustomColors } from '@/types';
+    import type { SkButtonKind, SkButtonSize, SkButtonType, SkButtonVariant } from './types';
+
+    // Composables
     import { useCustomColors } from '@/composables/useCustomColors';
 
     //------------------------------------------------------------------------------------------------------------------
 
-    /**
-     * A versatile button component with multiple variants, sizes, and states.
-     * Supports rendering as button, link (a), or router-link.
-     */
     export interface SkButtonComponentProps extends ComponentCustomColors
     {
-        /** HTML button type attribute */
+        /**
+         * The HTML `type` attribute for the button element. Only applies when rendering as a `<button>`
+         * (i.e., when neither `href` nor `to` props are provided). Use 'submit' for form submission
+         * buttons and 'reset' for form reset buttons.
+         * @default 'button'
+         */
         type ?: SkButtonType;
-        /** Semantic color kind */
+
+        /**
+         * Semantic color kind that controls the button's color scheme. Semantic kinds (neutral, primary,
+         * accent, etc.) adapt to your theme colors, while color kinds (neon-blue, neon-purple, etc.)
+         * provide fixed branding colors that remain consistent across themes.
+         * @default 'neutral'
+         */
         kind ?: SkButtonKind;
-        /** Visual variant style */
+
+        /**
+         * Visual variant that determines the button's styling approach. 'solid' provides a filled
+         * background, 'outline' shows a bordered button with transparent background, and 'ghost'
+         * renders a minimal button with no background or border until hovered.
+         * @default 'solid'
+         */
         variant ?: SkButtonVariant;
-        /** Button size */
+
+        /**
+         * Button size controlling padding, font size, and overall dimensions. Available sizes:
+         * 'sm' (small, compact), 'md' (medium, default), 'lg' (large), 'xl' (extra large).
+         * Icon-only buttons automatically adjust to square proportions at each size.
+         * @default 'md'
+         */
         size ?: SkButtonSize;
-        /** Disabled state */
+
+        /**
+         * When true, disables the button preventing all user interaction. The button appears with
+         * reduced opacity and the cursor changes to not-allowed. Also disables any navigation
+         * for link-style buttons.
+         * @default false
+         */
         disabled ?: boolean;
-        /** Loading state with spinner */
+
+        /**
+         * When true, displays a loading spinner and disables the button. The button content remains
+         * visible but dimmed while the spinner overlays it. Use this to indicate async operations
+         * like form submissions or data fetching.
+         * @default false
+         */
         loading ?: boolean;
-        /** Toggle pressed state */
+
+        /**
+         * Toggle state for buttons used as toggle controls. When true, applies the pressed visual
+         * state and sets `aria-pressed="true"` for accessibility. Use with `@click` to toggle
+         * the value for toolbar buttons or toggle switches.
+         * @default false
+         */
         pressed ?: boolean;
-        /** Href for anchor tag rendering */
+
+        /**
+         * URL for the button to navigate to. When provided, the button renders as an `<a>` element
+         * instead of a `<button>`. Use for external links or simple navigation that doesn't require
+         * Vue Router.
+         * @default undefined
+         */
         href ?: string;
-        /** Route for router-link rendering */
+
+        /**
+         * Vue Router route for the button to navigate to. When provided, the button renders as a
+         * `<router-link>` component. Accepts either a string path or a route location object with
+         * name, params, and query properties.
+         * @default undefined
+         */
         to ?: string | Record<string, any>;
     }
 

package/src/components/Card/SkCard.vue

@@ -34,40 +34,107 @@
 
 <script setup lang="ts">
     /**
-     * @component
-     * A structured card component with optional header, media, content, and footer sections.
-     * Built on top of SkPanel with additional styling and layout features.
+     * @component SkCard
+     * @description A structured card component with distinct header, media, content, and footer sections. Built on top
+     * of SkPanel, cards are ideal for displaying grouped information like product listings, user profiles, or article
+     * previews. Supports scrollable content areas for fixed-height layouts.
+     *
+     * @example
+     * ```vue
+     * <SkCard title="Product Details" kind="primary">
+     *     <template #media>
+     *         <img src="/product.jpg" alt="Product" />
+     *     </template>
+     *     <p>Product description goes here.</p>
+     *     <template #footer>
+     *         <SkButton>Add to Cart</SkButton>
+     *     </template>
+     * </SkCard>
+     * ```
+     *
+     * @slot default - The main content area of the card. Displays below the header and media sections.
+     * @slot header - Custom header content. Renders alongside or instead of the `title` prop. Use for action buttons,
+     *                badges, or complex header layouts.
+     * @slot media - Media content area (images, videos, etc.) that spans the full width without padding. Displays
+     *               between the header and content sections.
+     * @slot footer - Footer content area for actions, links, or metadata. Displays at the bottom of the card with
+     *                appropriate spacing.
      */
 
     import { computed } from 'vue';
-    import SkPanel from '../Panel/SkPanel.vue';
+
+    // Types
+    import type { ComponentCustomColors } from '@/types';
     import type { SkCardKind } from './types';
     import type { SkPanelSize } from '../Panel/types';
-    import type { ComponentCustomColors } from '@/types';
+
+    // Components
+    import SkPanel from '../Panel/SkPanel.vue';
 
     //------------------------------------------------------------------------------------------------------------------
 
-    /**
-     * A structured card component with optional header, media, content, and footer sections.
-     * Built on top of SkPanel with additional styling and layout features.
-     */
     export interface SkCardComponentProps extends ComponentCustomColors
     {
-        /** Semantic color kind for the card */
+        /**
+         * Semantic color kind that controls the card'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.
+         * @default 'neutral'
+         */
         kind ?: SkCardKind;
-        /** Size of the card affecting padding and spacing */
+
+        /**
+         * Controls the internal padding of the card's content areas. Larger sizes provide more
+         * breathing room, while smaller sizes create compact layouts. The header, content, and
+         * footer sections all respect this sizing. Available: 'sm', 'md', 'lg', 'xl'.
+         * @default 'md'
+         */
         size ?: SkPanelSize;
-        /** Whether to show the decorative accent border (when not explicitly disabled by noDecoration) */
+
+        /**
+         * When true, displays a colored accent stripe along the top edge of the card.
+         * Can be explicitly set to override the default behavior. Takes precedence over
+         * `noDecoration` when explicitly set to true.
+         * @default undefined (defaults to true unless noDecoration is set)
+         */
         showDecoration ?: boolean;
-        /** Explicitly disable the decorative accent border */
+
+        /**
+         * When true, explicitly disables the decorative accent stripe. Use this for cleaner
+         * card appearances where the color accent is not needed. This is overridden if
+         * `showDecoration` is explicitly set to true.
+         * @default false
+         */
         noDecoration ?: boolean;
-        /** Whether to hide the card border entirely */
+
+        /**
+         * When true, removes the border entirely from the card. Useful for flat card designs
+         * or when cards are displayed on contrasting backgrounds. Note: This automatically
+         * disables the decoration stripe since it's part of the border styling.
+         * @default false
+         */
         noBorder ?: boolean;
-        /** Optional title text displayed in the header section */
+
+        /**
+         * Title text displayed prominently in the card header section. The title is rendered
+         * as an h3 element for proper document semantics. For more complex headers, use the
+         * `header` slot instead of or alongside this prop.
+         */
         title ?: string;
-        /** Custom background color for the card header */
+
+        /**
+         * Custom CSS background color for the header section only. Accepts any valid CSS color
+         * value (hex, rgb, oklch, etc.). Use this to create visual distinction between the
+         * header and content areas, or to match brand colors.
+         */
         headerColor ?: string;
-        /** Makes the content area scrollable (card needs a constrained height) */
+
+        /**
+         * When true, makes the content area scrollable with a fixed maximum height. The card
+         * itself must have a constrained height (via CSS or parent container) for scrolling
+         * to take effect. Header and footer remain fixed while content scrolls.
+         * @default false
+         */
         scrollable ?: boolean;
     }
 

package/src/components/Checkbox/SkCheckbox.vue

@@ -58,9 +58,17 @@
 
 <script setup lang="ts">
     /**
-     * @component
-     * A checkbox component for boolean or indeterminate states powered by RekaUI.
-     * Supports semantic color kinds and flexible sizing.
+     * @component SkCheckbox
+     * @description A checkbox input component supporting boolean and indeterminate states. Built on RekaUI's
+     * Checkbox primitive with beveled corner styling and full keyboard accessibility. Use with `v-model` for
+     * two-way binding of the checked state.
+     *
+     * @example
+     * ```vue
+     * <SkCheckbox v-model="accepted" label="Accept terms" kind="primary" />
+     * ```
+     *
+     * @slot default - Custom label content. Overrides the `label` prop when provided.
      */
 
     import { computed, toRef } from 'vue';
@@ -75,22 +83,47 @@
 
     //------------------------------------------------------------------------------------------------------------------
 
-    /**
-     * A checkbox component for boolean or indeterminate states powered by RekaUI.
-     */
     export interface SkCheckboxComponentProps extends ComponentCustomColors
     {
-        /** Semantic color kind */
+        /**
+         * Semantic color kind that controls the checkbox appearance when checked. Semantic kinds
+         * (neutral, primary, accent, etc.) adapt to your theme, while color kinds (neon-blue,
+         * neon-purple, etc.) provide fixed branding colors.
+         * @default 'neutral'
+         */
         kind ?: SkCheckboxKind;
-        /** Checkbox size */
+
+        /**
+         * Checkbox size. Controls both the checkbox box dimensions and the label text size.
+         * Available sizes: 'sm' (small), 'md' (medium), 'lg' (large), 'xl' (extra large).
+         * @default 'md'
+         */
         size ?: SkCheckboxSize;
-        /** Disabled state */
+
+        /**
+         * When true, the checkbox is disabled and cannot be interacted with. The checkbox
+         * appears with reduced opacity and the cursor changes to not-allowed.
+         * @default false
+         */
         disabled ?: boolean;
-        /** Required for form validation */
+
+        /**
+         * When true, marks the checkbox as required for form validation. 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 checkbox value in a form.
+         * Required for native form submission.
+         */
         name ?: string;
-        /** Label text (can be overridden by default slot) */
+
+        /**
+         * Label text displayed next to the checkbox. Can be overridden by the default slot
+         * for custom label content (icons, formatted text, etc.).
+         */
         label ?: string;
     }
 
@@ -107,6 +140,13 @@
 
     //------------------------------------------------------------------------------------------------------------------
 
+    /**
+     * The checkbox state. Use with `v-model` for two-way binding.
+     * - `true` — checked (displays checkmark)
+     * - `false` — unchecked (empty box)
+     * - `'indeterminate'` — indeterminate state (displays horizontal line)
+     * @default false
+     */
     const checked = defineModel<boolean | 'indeterminate'>({ default: false });
 
     //------------------------------------------------------------------------------------------------------------------

package/src/components/Collapsible/SkCollapsible.vue

@@ -54,8 +54,36 @@
 
 <script setup lang="ts">
     /**
-     * @component
-     * Collapsible component for showing/hiding content with smooth animations.
+     * @component SkCollapsible
+     * @description An expandable/collapsible container that reveals or hides content with smooth height animations.
+     * Built on RekaUI's Collapsible primitive for robust accessibility and keyboard support. Use for FAQ sections,
+     * expandable details, or any content that should be hidden by default to reduce visual clutter.
+     *
+     * @example
+     * ```vue
+     * <SkCollapsible v-model:open="showDetails" trigger-text="Show Details" kind="primary">
+     *     <p>This content is hidden until the user clicks the trigger.</p>
+     * </SkCollapsible>
+     * ```
+     *
+     * @example Custom trigger with slot
+     * ```vue
+     * <SkCollapsible v-model:open="isExpanded">
+     *     <template #trigger="{ open }">
+     *         <SkButton variant="outline">
+     *             {{ open ? 'Hide' : 'Show' }} Advanced Options
+     *         </SkButton>
+     *     </template>
+     *     <div class="options-panel">
+     *         <!-- Advanced options content -->
+     *     </div>
+     * </SkCollapsible>
+     * ```
+     *
+     * @slot default - The collapsible content that is shown/hidden. This content animates smoothly when the
+     *                 collapsed state changes.
+     * @slot trigger - Custom trigger element. Receives `{ open: boolean }` slot props to allow the trigger to
+     *                 reflect the current state. When not provided, a default SkButton with chevron icon is rendered.
      */
 
     import { computed, toRef } from 'vue';
@@ -77,37 +105,47 @@
 
     //------------------------------------------------------------------------------------------------------------------
 
-    /**
-     * Collapsible component for showing/hiding content with smooth animations.
-     *
-     * @example Basic usage
-     * ```vue
-     * <SkCollapsible v-model:open="isOpen" trigger-text="Show more">
-     *   <p>Hidden content here</p>
-     * </SkCollapsible>
-     * ```
-     *
-     * @example Custom trigger
-     * ```vue
-     * <SkCollapsible v-model:open="isOpen">
-     *   <template #trigger="{ open }">
-     *     <SkButton>{{ open ? 'Hide' : 'Show' }} Details</SkButton>
-     *   </template>
-     *   <p>Collapsible content here</p>
-     * </SkCollapsible>
-     * ```
-     */
     export interface SkCollapsibleComponentProps extends ComponentCustomColors
     {
-        /** Controlled state (v-model:open) */
+        /**
+         * Controls the expanded/collapsed state of the component. Use with `v-model:open` for
+         * two-way binding. When true, the content is visible; when false, it's hidden. If not
+         * provided, the component manages its own state internally starting with `defaultOpen`.
+         * @default undefined (uncontrolled mode)
+         */
         open ?: boolean;
-        /** Initial uncontrolled state */
+
+        /**
+         * The initial expanded state when the component is first rendered in uncontrolled mode.
+         * Only applies when the `open` prop is not provided. After initial render, the component
+         * manages its own state.
+         * @default false
+         */
         defaultOpen ?: boolean;
-        /** Disable interaction */
+
+        /**
+         * When true, disables the trigger and prevents state changes. The current expanded/collapsed
+         * state is preserved but cannot be changed by user interaction. The trigger element appears
+         * with reduced opacity and cursor changes to not-allowed.
+         * @default false
+         */
         disabled ?: boolean;
-        /** Semantic color kind */
+
+        /**
+         * Semantic color kind that controls the default trigger button appearance. Semantic kinds
+         * (neutral, primary, accent, etc.) adapt to your theme, while color kinds provide fixed
+         * branding colors. Only applies when using the default trigger; ignored when using the
+         * trigger slot.
+         * @default 'neutral'
+         */
         kind ?: SkCollapsibleKind;
-        /** Text for default trigger */
+
+        /**
+         * Label text for the default trigger button. Displayed alongside the animated chevron
+         * icon. Only applies when the trigger slot is not provided. For more control over the
+         * trigger appearance, use the trigger slot instead.
+         * @default 'Toggle'
+         */
         triggerText ?: string;
     }
 

package/src/components/Divider/SkDivider.vue

@@ -10,30 +10,70 @@
 
 <script setup lang="ts">
     /**
-     * @component
-     * A visual separator component for dividing content.
-     * Supports horizontal and vertical orientations with subtle or default styling.
+     * @component SkDivider
+     * @description A visual separator component used to divide content into distinct sections. Renders as a semantic
+     * `<hr>` element with proper ARIA attributes for accessibility. Use horizontal dividers to separate stacked
+     * content, or vertical dividers to separate inline elements like toolbar buttons.
+     *
+     * @example
+     * ```vue
+     * <div>
+     *     <p>First section content</p>
+     *     <SkDivider kind="primary" />
+     *     <p>Second section content</p>
+     * </div>
+     * ```
+     *
+     * @example Vertical divider in a toolbar
+     * ```vue
+     * <SkGroup orientation="horizontal">
+     *     <SkButton>Edit</SkButton>
+     *     <SkDivider orientation="vertical" variant="subtle" />
+     *     <SkButton>Delete</SkButton>
+     * </SkGroup>
+     * ```
      */
 
     import { computed } from 'vue';
+
+    // Types
     import type { ComponentKind, ComponentSize } from '@/types';
     import type { SkDividerOrientation, SkDividerVariant } from './types';
 
     //------------------------------------------------------------------------------------------------------------------
 
-    /**
-     * A visual separator component for dividing content.
-     * Supports horizontal and vertical orientations with subtle or default styling.
-     */
     export interface SkDividerComponentProps
     {
-        /** Orientation of the divider line (horizontal or vertical) */
+        /**
+         * Controls the direction of the divider line. Use 'horizontal' for separating
+         * vertically stacked content (the divider spans width), or 'vertical' for
+         * separating horizontally arranged elements (the divider spans height).
+         * @default 'horizontal'
+         */
         orientation ?: SkDividerOrientation;
-        /** Semantic color kind for the divider */
+
+        /**
+         * Semantic color kind that controls the divider's line color. Semantic kinds
+         * (neutral, primary, accent, etc.) adapt to your theme. Use colored dividers
+         * sparingly to draw attention to important content boundaries.
+         * @default 'neutral'
+         */
         kind ?: ComponentKind;
-        /** Visual variant (subtle for lighter appearance) */
+
+        /**
+         * Visual intensity variant for the divider. The default variant provides a
+         * clearly visible line, while 'subtle' reduces opacity for a softer, less
+         * prominent separation that doesn't compete with content for attention.
+         * @default undefined (uses default styling)
+         */
         variant ?: SkDividerVariant;
-        /** Size of the divider (controls thickness and spacing) */
+
+        /**
+         * Controls the thickness of the divider line and the spacing (margin) around it.
+         * Larger sizes create bolder visual breaks between content sections, while smaller
+         * sizes provide minimal separation. Available: 'sm', 'md', 'lg', 'xl'.
+         * @default 'md'
+         */
         size ?: ComponentSize;
     }