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

package/src/components/Listbox/SkListboxSeparator.vue

@@ -16,8 +16,22 @@
 
 <script setup lang="ts">
     /**
-     * @component
-     * A listbox separator for use within SkListbox.
+     * @component SkListboxSeparator
+     * @description A visual divider for organizing options within an SkListbox dropdown. Use to create
+     * logical groups of related options without affecting selection behavior. Renders as a horizontal
+     * line between items with appropriate spacing.
+     *
+     * @example
+     * ```vue
+     * <SkListbox v-model="selected">
+     *     <SkListboxItem value="recent1">Recent Document 1</SkListboxItem>
+     *     <SkListboxItem value="recent2">Recent Document 2</SkListboxItem>
+     *     <SkListboxSeparator />
+     *     <SkListboxItem value="all">Browse All Documents...</SkListboxItem>
+     * </SkListbox>
+     * ```
+     *
+     * @slot - Not applicable. This component does not accept slot content.
      */
 
     import { ComboboxSeparator } from 'reka-ui';

package/src/components/Modal/SkModal.vue

@@ -58,8 +58,34 @@
 
 <script setup lang="ts">
     /**
-     * @component
-     * Modal dialog component for displaying content in an overlay
+     * @component SkModal
+     * @description A modal dialog component for displaying focused content in an overlay. Built on RekaUI's Dialog
+     * primitive with full accessibility support including focus trapping and ARIA attributes. Modals interrupt the
+     * user workflow to capture attention for important information, confirmations, or forms.
+     *
+     * @example
+     * ```vue
+     * <SkModal v-model:open="showModal" title="Confirm Action">
+     *     <p>Are you sure you want to proceed?</p>
+     *     <template #footer="{ close }">
+     *         <SkButton @click="close">Cancel</SkButton>
+     *         <SkButton kind="primary" @click="confirm(); close()">Confirm</SkButton>
+     *     </template>
+     * </SkModal>
+     * ```
+     *
+     * @example With trigger button
+     * ```vue
+     * <SkModal title="Settings" trigger-text="Open Settings" kind="primary">
+     *     <SettingsForm />
+     * </SkModal>
+     * ```
+     *
+     * @slot trigger - Custom trigger element to open the modal. Receives no slot props. If not provided, uses
+     *                 a default SkButton with `triggerText`.
+     * @slot title - Custom title content. Receives `{ close }` slot prop for programmatic closing.
+     * @slot default - The main modal body content. Receives `{ close }` slot prop for programmatic closing.
+     * @slot footer - Footer content, typically containing action buttons. Receives `{ close }` slot prop.
      */
 
     import { computed, ref, toRef, watch } from 'vue';
@@ -85,50 +111,73 @@
 
     //------------------------------------------------------------------------------------------------------------------
 
-    /**
-     * Modal dialog component for displaying content in an overlay
-     *
-     * @example Basic usage with footer close button
-     * ```vue
-     * <SkModal title="Confirm Action" trigger-text="Open">
-     *   <p>Are you sure?</p>
-     *   <template #footer="{ close }">
-     *     <SkButton @click="close">Cancel</SkButton>
-     *     <SkButton kind="primary" @click="doAction(); close()">Confirm</SkButton>
-     *   </template>
-     * </SkModal>
-     * ```
-     *
-     * @example Prevent escape/overlay dismissal
-     * ```vue
-     * <SkModal
-     *   title="Important Form"
-     *   no-close-on-escape
-     *   no-close-on-overlay
-     * >
-     *   <!-- User must use buttons to close -->
-     * </SkModal>
-     * ```
-     */
     export interface SkModalComponentProps extends ComponentCustomColors
     {
-        /** Semantic color kind for the modal */
+        /**
+         * Semantic color kind that controls the modal's accent colors, including the header,
+         * close button, and any kind-styled elements within the modal. Semantic kinds
+         * (neutral, primary, accent, etc.) adapt to your theme.
+         * @default 'neutral'
+         */
         kind ?: ComponentKind;
-        /** Size of the modal (width) */
+
+        /**
+         * Size of the modal dialog, controlling its maximum width. Use 'sm' for simple
+         * confirmations, 'md' for standard forms, 'lg' for complex content, and 'xl' for
+         * dashboards or data-heavy dialogs.
+         * @default 'md'
+         */
         size ?: ComponentSize;
-        /** Title text displayed in the header */
+
+        /**
+         * Title text displayed in the modal header. When provided, a header section with
+         * the title and close button is automatically rendered. Can be overridden with
+         * the title slot for custom header content.
+         */
         title ?: string;
-        /** Text for the default trigger button */
+
+        /**
+         * Text label for the default trigger button. When provided (and no trigger slot is
+         * used), renders an SkButton that opens the modal when clicked. Omit both this and
+         * the trigger slot to control the modal programmatically via v-model:open.
+         */
         triggerText ?: string;
-        /** Whether the modal is open (v-model:open) */
+
+        /**
+         * Controls whether the modal is open. Use with `v-model:open` for two-way binding.
+         * Set to true to open the modal programmatically, false to close it. The modal
+         * can also be closed via the close button, Escape key, or overlay click.
+         * @default false
+         */
         open ?: boolean;
-        /** Whether pressing Escape closes the modal (default: true) */
+
+        /**
+         * Whether pressing the Escape key closes the modal. Set to false for important
+         * dialogs where accidental dismissal should be prevented, such as unsaved form
+         * data or critical confirmations.
+         * @default true
+         */
         closeOnEscape ?: boolean;
-        /** Whether clicking the overlay closes the modal (default: true) */
+
+        /**
+         * Whether clicking the overlay (dark backdrop) closes the modal. Set to false to
+         * require users to interact with modal buttons rather than dismissing accidentally.
+         * @default true
+         */
         closeOnOverlay ?: boolean;
-        /** Prevent closing on Escape key (alternative to :close-on-escape="false") */
+
+        /**
+         * Boolean shorthand to prevent closing on Escape key. Equivalent to
+         * `:close-on-escape="false"`. Use when you prefer attribute syntax over bound values.
+         * @default false
+         */
         noCloseOnEscape ?: boolean;
-        /** Prevent closing on overlay click (alternative to :close-on-overlay="false") */
+
+        /**
+         * Boolean shorthand to prevent closing on overlay click. Equivalent to
+         * `:close-on-overlay="false"`. Use when you prefer attribute syntax over bound values.
+         * @default false
+         */
         noCloseOnOverlay ?: boolean;
     }
 

package/src/components/NavBar/SkNavBar.vue

@@ -24,9 +24,32 @@
 
 <script setup lang="ts">
     /**
-     * @component
-     * A navigation bar component for site-wide navigation with brand, nav items, and action slots.
-     * Supports sticky positioning and semantic color theming.
+     * @component SkNavBar
+     * @description A horizontal navigation bar component for site-wide header navigation. Provides a structured
+     * layout with three distinct zones: brand/logo area (left), main navigation links (center), and action
+     * buttons (right). Supports sticky positioning to remain visible while scrolling and adapts to your
+     * theme's semantic colors.
+     *
+     * @example
+     * ```vue
+     * <SkNavBar kind="primary">
+     *   <template #brand>
+     *     <img src="/logo.svg" alt="Logo" />
+     *   </template>
+     *   <SkButton as="a" href="/features">Features</SkButton>
+     *   <SkButton as="a" href="/pricing">Pricing</SkButton>
+     *   <template #actions>
+     *     <SkButton kind="accent">Sign Up</SkButton>
+     *   </template>
+     * </SkNavBar>
+     * ```
+     *
+     * @slot brand - Left-aligned area for your logo, site name, or brand identity. Typically contains an
+     *               image or text link to the homepage.
+     * @slot default - Center area for main navigation items. Place navigation buttons, links, or menu
+     *                 triggers here. Items are displayed in a horizontal row.
+     * @slot actions - Right-aligned area for call-to-action buttons, user menus, or utility controls.
+     *                 Ideal for login buttons, shopping carts, or profile dropdowns.
      */
 
     import { computed, toRef, useSlots } from 'vue';
@@ -36,15 +59,22 @@
 
     //------------------------------------------------------------------------------------------------------------------
 
-    /**
-     * A navigation bar component for site-wide navigation with brand, nav items, and action slots.
-     * Supports sticky positioning and semantic color theming.
-     */
     export interface SkNavBarComponentProps extends ComponentCustomColors
     {
-        /** Semantic color kind for the navbar */
+        /**
+         * Semantic color kind that controls the navbar's background and text colors. Use semantic kinds
+         * like 'primary' or 'accent' to match your theme, or color kinds like 'neon-blue' for fixed
+         * branding colors. The kind affects the entire navbar including all three slot areas.
+         * @default 'neutral'
+         */
         kind ?: SkNavBarKind;
-        /** Whether the navbar sticks to the top of the viewport when scrolling */
+
+        /**
+         * When true, the navbar uses CSS `position: sticky` to remain fixed at the top of the viewport
+         * as the user scrolls down the page. The navbar will overlay page content below it. Set to false
+         * for a navbar that scrolls with the page content.
+         * @default true
+         */
         sticky ?: boolean;
     }
 

package/src/components/NumberInput/SkNumberInput.vue

@@ -59,9 +59,19 @@
 
 <script setup lang="ts">
     /**
-     * @component
-     * A numeric input component with stepper buttons powered by RekaUI.
-     * Supports keyboard navigation, min/max values, and step increments.
+     * @component SkNumberInput
+     * @description A numeric input component with built-in increment/decrement stepper buttons. Built on RekaUI's
+     * NumberField primitive with full keyboard accessibility (arrow keys, page up/down, home/end). Supports
+     * min/max constraints and configurable step values. Use with `v-model` for two-way binding of the numeric value.
+     *
+     * @example
+     * ```vue
+     * <SkNumberInput v-model="quantity" :min="1" :max="100" />
+     * <SkNumberInput v-model="price" :step="0.01" :min="0" placeholder="0.00" />
+     * <SkField label="Age" :error="errors.age">
+     *   <SkNumberInput v-model="age" name="age" :min="0" :max="150" />
+     * </SkField>
+     * ```
      */
 
     import { type ComputedRef, computed, inject, toRef } from 'vue';
@@ -81,30 +91,84 @@
 
     //------------------------------------------------------------------------------------------------------------------
 
-    /**
-     * A numeric input component with stepper buttons powered by RekaUI.
-     */
     export interface SkNumberInputComponentProps extends ComponentCustomColors
     {
-        /** Semantic color kind (useful for validation states) */
+        /**
+         * Semantic color kind for the input 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 ?: SkNumberInputKind;
-        /** Input size */
+
+        /**
+         * Input size controlling height, padding, font size, and stepper button dimensions.
+         * Available sizes: 'sm' (small, compact forms), 'md' (medium, default), 'lg' (large),
+         * 'xl' (extra large).
+         * @default 'md'
+         */
         size ?: SkNumberInputSize;
-        /** Placeholder text */
+
+        /**
+         * Placeholder text displayed when the input is empty or has no value. Use to indicate
+         * expected format (e.g., "0.00" for currency) or provide a hint about the field's purpose.
+         * @default undefined
+         */
         placeholder ?: string;
-        /** Disabled state */
+
+        /**
+         * When true, disables the input and stepper buttons preventing all user interaction.
+         * The component appears with reduced opacity and the cursor changes to not-allowed.
+         * Disabled inputs are excluded from form submission.
+         * @default false
+         */
         disabled ?: boolean;
-        /** Read-only state */
+
+        /**
+         * When true, makes the input read-only. The user can select and copy the value but
+         * cannot modify it via typing or stepper buttons. Unlike disabled, read-only inputs
+         * are still included in form submission.
+         * @default false
+         */
         readonly ?: boolean;
-        /** Required for form validation */
+
+        /**
+         * When true, marks the input as required for form validation. The browser will prevent
+         * form submission if the input is empty. For visual required indicators, wrap the input
+         * in an SkField component with `required` prop.
+         * @default false
+         */
         required ?: boolean;
-        /** Form field name */
+
+        /**
+         * The form field name used when submitting the input value. Required for native form
+         * submission and useful for form libraries that track fields by name.
+         * @default undefined
+         */
         name ?: string;
-        /** Minimum value */
+
+        /**
+         * Minimum allowed value. The stepper buttons will not decrement below this value, and
+         * manual input will be constrained on blur. Use to enforce business rules like positive
+         * quantities or minimum prices.
+         * @default undefined
+         */
         min ?: number;
-        /** Maximum value */
+
+        /**
+         * Maximum allowed value. The stepper buttons will not increment above this value, and
+         * manual input will be constrained on blur. Use to enforce limits like maximum quantity
+         * or inventory caps.
+         * @default undefined
+         */
         max ?: number;
-        /** Step increment/decrement amount */
+
+        /**
+         * The increment/decrement step amount when using stepper buttons or arrow keys. Use
+         * fractional values like 0.01 for currency or 0.1 for percentages. Pressing Shift while
+         * stepping may multiply the step for faster navigation.
+         * @default 1
+         */
         step ?: number;
     }
 
@@ -125,6 +189,11 @@
 
     //------------------------------------------------------------------------------------------------------------------
 
+    /**
+     * The numeric value of the input. Use with `v-model` for two-way binding. The value is
+     * constrained by `min` and `max` props when set. Returns a number type.
+     * @default 0
+     */
     const modelValue = defineModel<number>({ default: 0 });
 
     //------------------------------------------------------------------------------------------------------------------

package/src/components/Page/SkPage.vue

@@ -31,8 +31,35 @@
 <script setup lang="ts">
     /**
      * @component SkPage
-     * A full-page layout component with header, sidebar, content, and footer slots.
-     * Provides a standard page structure with optional fixed header/footer and configurable sidebar.
+     * @description A full-page layout component that provides a structured application shell with header, sidebar,
+     * main content, and footer regions. Designed for building complete application pages with optional fixed
+     * positioning for header/footer and flexible sidebar placement. The layout automatically handles scrolling
+     * behavior and responsive spacing.
+     *
+     * @example
+     * ```vue
+     * <SkPage fixed-header sidebar-position="left" sidebar-width="280px">
+     *     <template #header>
+     *         <AppNavbar />
+     *     </template>
+     *     <template #sidebar>
+     *         <AppMenu />
+     *     </template>
+     *     <MainContent />
+     *     <template #footer>
+     *         <AppFooter />
+     *     </template>
+     * </SkPage>
+     * ```
+     *
+     * @slot default - The main content area of the page. This is where your primary page content goes. Automatically
+     *                 handles scrolling when header/footer are fixed.
+     * @slot header - The page header region, typically used for navigation bars, branding, or page titles. Spans the
+     *                full width above the sidebar and content areas.
+     * @slot sidebar - Optional sidebar region for navigation menus, filters, or secondary content. Position is
+     *                 controlled by the `sidebarPosition` prop.
+     * @slot footer - The page footer region for copyright notices, links, or secondary navigation. Spans the full
+     *                width below the sidebar and content areas.
      */
 
     import { computed } from 'vue';
@@ -44,13 +71,35 @@
 
     export interface SkPageComponentProps
     {
-        /** Sidebar position */
+        /**
+         * Controls which side of the page the sidebar appears on. The sidebar slot content
+         * will be positioned on the specified side, with the main content area filling the
+         * remaining space. Has no effect if the sidebar slot is not provided.
+         * @default 'left'
+         */
         sidebarPosition ?: SkPageSidebarPosition;
-        /** Fixed header (stays at top when scrolling) */
+
+        /**
+         * When true, the header remains fixed at the top of the viewport while the main
+         * content scrolls beneath it. Useful for keeping navigation always accessible.
+         * The content area adjusts its top padding to prevent overlap with the fixed header.
+         * @default false
+         */
         fixedHeader ?: boolean;
-        /** Fixed footer (stays at bottom when scrolling) */
+
+        /**
+         * When true, the footer remains fixed at the bottom of the viewport while the main
+         * content scrolls above it. Useful for persistent action bars or important links.
+         * The content area adjusts its bottom padding to prevent overlap with the fixed footer.
+         * @default false
+         */
         fixedFooter ?: boolean;
-        /** Custom sidebar width */
+
+        /**
+         * Custom width for the sidebar region. Accepts any valid CSS width value (px, rem, %, etc.).
+         * When not specified, the sidebar uses the default width defined in the design tokens.
+         * Only applies when the sidebar slot is provided.
+         */
         sidebarWidth ?: string;
     }
 

package/src/components/Pagination/SkPagination.vue

@@ -53,6 +53,28 @@
 <!--------------------------------------------------------------------------------------------------------------------->
 
 <script setup lang="ts">
+    /**
+     * @component SkPagination
+     * @description A pagination navigation component for splitting content across multiple pages. Automatically
+     * calculates page ranges with ellipsis for large page counts and provides first/last and previous/next navigation
+     * buttons. Use with `v-model` for two-way binding of the current page number.
+     *
+     * @example
+     * ```vue
+     * <SkPagination v-model="currentPage" :total="50" kind="primary" />
+     * ```
+     *
+     * @example Minimal pagination (no first/last buttons)
+     * ```vue
+     * <SkPagination
+     *     v-model="page"
+     *     :total="10"
+     *     :show-first-last="false"
+     *     variant="outline"
+     * />
+     * ```
+     */
+
     import { computed, provide, toRef } from 'vue';
 
     // Types
@@ -63,6 +85,72 @@
 
     export interface SkPaginationComponentProps extends SkPaginationProps, ComponentCustomColors
     {
+        /**
+         * The total number of pages available. This is a required prop that determines
+         * how many page numbers to display and when to show ellipsis indicators.
+         */
+        total : number;
+
+        /**
+         * The current active page number. Use with `v-model` for two-way binding. Page
+         * numbers are 1-indexed, so the first page is 1, not 0.
+         * @default 1
+         */
+        modelValue ?: number;
+
+        /**
+         * The number of sibling pages to show on each side of the current page. For example,
+         * if the current page is 5 and siblingCount is 1, pages 4 and 6 will be shown.
+         * Higher values show more page numbers but take up more space.
+         * @default 1
+         */
+        siblingCount ?: number;
+
+        /**
+         * Whether to show the "first page" and "last page" navigation buttons. These
+         * buttons allow users to jump directly to page 1 or the final page. Set to false
+         * for a more compact pagination layout.
+         * @default true
+         */
+        showFirstLast ?: boolean;
+
+        /**
+         * Whether to show the "previous" and "next" navigation buttons. These buttons
+         * allow single-page navigation forward or backward. Typically left enabled for
+         * standard pagination behavior.
+         * @default true
+         */
+        showPrevNext ?: boolean;
+
+        /**
+         * Semantic color kind that controls the pagination appearance. Affects the active
+         * page indicator and navigation button colors. Semantic kinds (neutral, primary,
+         * accent, etc.) adapt to your theme.
+         * @default 'neutral'
+         */
+        kind ?: SkPaginationProps['kind'];
+
+        /**
+         * Size of the pagination buttons. Controls both the button dimensions and text size.
+         * Available sizes: 'xs' (extra small), 'sm' (small), 'md' (medium), 'lg' (large), 'xl' (extra large).
+         * @default 'md'
+         */
+        size ?: SkPaginationProps['size'];
+
+        /**
+         * Visual style variant for the pagination buttons. Choose 'solid' for filled buttons,
+         * 'outline' for bordered buttons, 'subtle' for lightly tinted backgrounds, or 'ghost'
+         * for transparent buttons that only show color on hover.
+         * @default 'solid'
+         */
+        variant ?: SkPaginationProps['variant'];
+
+        /**
+         * When true, the entire pagination component is disabled. All buttons become
+         * non-interactive and appear with reduced opacity. The cursor changes to not-allowed.
+         * @default false
+         */
+        disabled ?: boolean;
     }
 
     //------------------------------------------------------------------------------------------------------------------

package/src/components/Pagination/SkPaginationItem.vue

@@ -24,6 +24,21 @@
 <!--------------------------------------------------------------------------------------------------------------------->
 
 <script setup lang="ts">
+    /**
+     * @component SkPaginationItem
+     * @description An individual pagination button used internally by SkPagination. Renders different content based
+     * on its type: page numbers, navigation arrows, or ellipsis indicators. Inherits styling from the parent
+     * SkPagination component via Vue's provide/inject. Not typically used directly—use SkPagination instead.
+     *
+     * @example
+     * ```vue
+     * <!-- Used internally by SkPagination -->
+     * <SkPaginationItem type="page" :page="5" :active="true" />
+     * <SkPaginationItem type="prev" :page="4" />
+     * <SkPaginationItem type="ellipsis" />
+     * ```
+     */
+
     import { type Ref, computed, inject } from 'vue';
 
     // Types
@@ -31,7 +46,42 @@
 
     //------------------------------------------------------------------------------------------------------------------
 
-    export type SkPaginationItemComponentProps = SkPaginationItemProps;
+    export interface SkPaginationItemComponentProps
+    {
+        /**
+         * The page number this item represents. Required for 'page', 'prev', 'next', 'first',
+         * and 'last' types. When clicked, this value is emitted to navigate to that page.
+         * Not needed for 'ellipsis' type items.
+         */
+        page ?: number;
+
+        /**
+         * Whether this item is the currently active page. Only applicable to 'page' type items.
+         * Active items receive distinct styling and include aria-current="page" for accessibility.
+         * @default false
+         */
+        active ?: boolean;
+
+        /**
+         * When true, the item is disabled and cannot be clicked. The item appears with
+         * reduced opacity and the cursor changes to not-allowed. Commonly used on
+         * prev/first buttons when on page 1, or next/last buttons when on the final page.
+         * @default false
+         */
+        disabled ?: boolean;
+
+        /**
+         * The type of pagination item to render. Determines both the visual content and behavior:
+         * - 'page': Shows a page number button
+         * - 'prev': Shows a previous arrow (‹)
+         * - 'next': Shows a next arrow (›)
+         * - 'first': Shows a first-page arrow (‹‹)
+         * - 'last': Shows a last-page arrow (››)
+         * - 'ellipsis': Shows non-interactive dots (...)
+         * @default 'page'
+         */
+        type ?: SkPaginationItemProps['type'];
+    }
 
     //------------------------------------------------------------------------------------------------------------------