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

package/src/components/Tabs/SkTab.vue

@@ -26,9 +26,25 @@
 
 <script setup lang="ts">
     /**
-     * @component
-     * An individual tab trigger component powered by RekaUI.
-     * Used within SkTabList to switch between tab panels.
+     * @component SkTab
+     * @description An individual tab trigger button used within `SkTabList` to switch between tab panels.
+     * Clicking a tab activates the corresponding `SkTabPanel` with a matching `name`. Supports keyboard
+     * navigation (arrow keys), focus management, and disabled states.
+     *
+     * @example
+     * ```vue
+     * <SkTabList>
+     *     <SkTab name="files" label="Files" />
+     *     <SkTab name="settings" kind="accent">
+     *         <template #icon><GearIcon /></template>
+     *         Settings
+     *     </SkTab>
+     *     <SkTab name="help" disabled>Help</SkTab>
+     * </SkTabList>
+     * ```
+     *
+     * @slot default - Custom tab label content. Overrides the `label` prop when provided.
+     * @slot icon - Optional icon displayed before the tab label. Useful for visual indicators.
      */
 
     import { type ComputedRef, computed, inject } from 'vue';
@@ -37,19 +53,33 @@
 
     //------------------------------------------------------------------------------------------------------------------
 
-    /**
-     * An individual tab trigger component powered by RekaUI.
-     * Used within SkTabList to switch between tab panels.
-     */
     export interface SkTabComponentProps
     {
-        /** Unique identifier matching the corresponding SkTabPanel */
+        /**
+         * Unique identifier that links this tab trigger to its corresponding `SkTabPanel`. The `name`
+         * must exactly match the `name` prop on the panel you want to display when this tab is active.
+         * Can be a string or number for flexibility with dynamic tab generation.
+         */
         name : string | number;
-        /** Text label displayed in the tab (can be overridden by default slot) */
+
+        /**
+         * Text label displayed in the tab button. Can be overridden by the default slot for custom
+         * content like icons with text or formatted labels.
+         */
         label ?: string;
-        /** Whether the tab is disabled and unclickable */
+
+        /**
+         * When true, the tab cannot be clicked or focused via keyboard. Disabled tabs are skipped
+         * during arrow key navigation and appear with reduced opacity.
+         * @default false
+         */
         disabled ?: boolean;
-        /** Semantic color kind (overrides parent tabs kind if provided) */
+
+        /**
+         * Semantic color kind for this specific tab. When provided, overrides the `kind` set on the
+         * parent `SkTabs` component. Use this for highlighting important tabs or creating visual
+         * hierarchy within a tab bar.
+         */
         kind ?: ComponentKind;
     }
 

package/src/components/Tabs/SkTabList.vue

@@ -12,9 +12,25 @@
 
 <script setup lang="ts">
     /**
-     * @component
-     * A container component for SkTab components powered by RekaUI.
-     * Arranges tabs in horizontal or vertical orientation.
+     * @component SkTabList
+     * @description A container component that holds and arranges `SkTab` trigger buttons. Provides the visual
+     * tab bar with appropriate ARIA `tablist` role. The orientation determines whether tabs are arranged
+     * horizontally (row) or vertically (column) and affects keyboard navigation direction.
+     *
+     * @example
+     * ```vue
+     * <SkTabs v-model="activeTab">
+     *     <SkTabList>
+     *         <SkTab name="tab1">First Tab</SkTab>
+     *         <SkTab name="tab2">Second Tab</SkTab>
+     *     </SkTabList>
+     *     <SkTabPanels>
+     *         <!-- Panels here -->
+     *     </SkTabPanels>
+     * </SkTabs>
+     * ```
+     *
+     * @slot default - Contains `SkTab` components that make up the tab triggers.
      */
 
     import { computed, inject } from 'vue';
@@ -23,13 +39,13 @@
 
     //------------------------------------------------------------------------------------------------------------------
 
-    /**
-     * A container component for SkTab components powered by RekaUI.
-     * Arranges tabs in horizontal or vertical orientation.
-     */
     export interface SkTabListComponentProps
     {
-        /** Orientation for arranging tabs (overrides parent SkTabs orientation if provided) */
+        /**
+         * Layout orientation for arranging tab triggers. When 'horizontal', tabs appear in a row
+         * with left/right arrow key navigation. When 'vertical', tabs stack in a column with
+         * up/down arrow key navigation. If not provided, inherits from the parent `SkTabs` component.
+         */
         orientation ?: SkTabsOrientation;
     }
 

package/src/components/Tabs/SkTabPanel.vue

@@ -16,24 +16,46 @@
 
 <script setup lang="ts">
     /**
-     * @component
-     * A content panel component for displaying tab content powered by RekaUI.
-     * Automatically shown/hidden based on the active tab in the parent SkTabs.
+     * @component SkTabPanel
+     * @description A content container that displays when its corresponding `SkTab` is active. The panel is
+     * automatically shown or hidden based on the active tab state in the parent `SkTabs`. By default, inactive
+     * panels are unmounted from the DOM to improve performance; use `keepAlive` to preserve state.
+     *
+     * @example
+     * ```vue
+     * <SkTabPanels>
+     *     <SkTabPanel name="overview">
+     *         <h2>Overview</h2>
+     *         <p>Welcome to the overview section.</p>
+     *     </SkTabPanel>
+     *     <SkTabPanel name="form" keep-alive>
+     *         <!-- Form state preserved when switching tabs -->
+     *         <FormComponent />
+     *     </SkTabPanel>
+     * </SkTabPanels>
+     * ```
+     *
+     * @slot default - The content to display when this panel's tab is active.
      */
 
     import { TabsContent } from 'reka-ui';
 
     //------------------------------------------------------------------------------------------------------------------
 
-    /**
-     * A content panel component for displaying tab content powered by RekaUI.
-     * Automatically shown/hidden based on the active tab in the parent SkTabs.
-     */
     export interface SkTabPanelComponentProps
     {
-        /** Unique identifier matching the corresponding SkTab */
+        /**
+         * Unique identifier that links this panel to its corresponding `SkTab` trigger. The `name`
+         * must exactly match the `name` prop on the tab that should activate this panel.
+         */
         name : string | number;
-        /** Whether to keep panel mounted in DOM even when inactive */
+
+        /**
+         * When true, the panel content remains mounted in the DOM even when the tab is inactive.
+         * This is useful for preserving form state, scroll position, or expensive component state
+         * that would otherwise be lost when switching tabs. Use sparingly as it increases memory usage.
+         * @default false
+         */
         keepAlive ?: boolean;
     }
 

package/src/components/Tabs/SkTabPanels.vue

@@ -12,12 +12,29 @@
 
 <script setup lang="ts">
     /**
-     * @component
-     * A simple container component for grouping SkTabPanel components.
-     * Provides semantic structure for organizing tab content.
+     * @component SkTabPanels
+     * @description A container component that groups `SkTabPanel` components together. Provides semantic structure
+     * and consistent styling for the content area of a tabbed interface. While technically optional, using this
+     * wrapper ensures proper layout and spacing between the tab list and content panels.
+     *
+     * @example
+     * ```vue
+     * <SkTabs v-model="activeTab">
+     *     <SkTabList>
+     *         <SkTab name="a">Tab A</SkTab>
+     *         <SkTab name="b">Tab B</SkTab>
+     *     </SkTabList>
+     *     <SkTabPanels>
+     *         <SkTabPanel name="a">Content for Tab A</SkTabPanel>
+     *         <SkTabPanel name="b">Content for Tab B</SkTabPanel>
+     *     </SkTabPanels>
+     * </SkTabs>
+     * ```
+     *
+     * @slot default - Contains `SkTabPanel` components, one for each tab in the interface.
      */
 
-    // No props or logic needed - just provides semantic structure
+    // No props or logic needed - provides semantic structure and styling hook
 </script>
 
 <!--------------------------------------------------------------------------------------------------------------------->

package/src/components/Tabs/SkTabs.vue

@@ -18,9 +18,26 @@
 
 <script setup lang="ts">
     /**
-     * @component
-     * A tabbed interface component for organizing content into switchable panels powered by RekaUI.
-     * Manages active tab state and provides context to child tab components.
+     * @component SkTabs
+     * @description A tabbed interface component for organizing content into switchable panels. Built on RekaUI's
+     * Tabs primitive with full keyboard navigation (arrow keys, Home, End) and ARIA tab pattern compliance.
+     * Use with `v-model` to control the active tab programmatically.
+     *
+     * @example
+     * ```vue
+     * <SkTabs v-model="activeTab" kind="primary">
+     *     <SkTabList>
+     *         <SkTab name="overview">Overview</SkTab>
+     *         <SkTab name="details">Details</SkTab>
+     *     </SkTabList>
+     *     <SkTabPanels>
+     *         <SkTabPanel name="overview">Overview content here</SkTabPanel>
+     *         <SkTabPanel name="details">Details content here</SkTabPanel>
+     *     </SkTabPanels>
+     * </SkTabs>
+     * ```
+     *
+     * @slot default - Contains `SkTabList` and `SkTabPanels` components that make up the tabbed interface.
      */
 
     import { computed, provide, toRef } from 'vue';
@@ -34,46 +51,41 @@
 
     //------------------------------------------------------------------------------------------------------------------
 
-    /**
-     * A tabbed interface component for organizing content into switchable panels powered by RekaUI.
-     * Manages active tab state and provides context to child tab components.
-     *
-     * @example Basic tabs
-     * ```vue
-     * <SkTabs v-model="activeTab">
-     *   <SkTabList>
-     *     <SkTab name="overview">Overview</SkTab>
-     *     <SkTab name="details">Details</SkTab>
-     *   </SkTabList>
-     *   <SkTabPanels>
-     *     <SkTabPanel name="overview">Overview content</SkTabPanel>
-     *     <SkTabPanel name="details">Details content</SkTabPanel>
-     *   </SkTabPanels>
-     * </SkTabs>
-     * ```
-     *
-     * @example Custom colors
-     * ```vue
-     * <SkTabs
-     *   v-model="activeTab"
-     *   base-color="oklch(0.65 0.2 280)"
-     *   text-color="white"
-     * >
-     *   <!-- Tab content -->
-     * </SkTabs>
-     * ```
-     */
     export interface SkTabsComponentProps extends ComponentCustomColors
     {
-        /** Currently active tab identifier (matching a SkTab name) */
+        /**
+         * The currently active tab identifier, matching the `name` prop of the corresponding `SkTab`
+         * and `SkTabPanel`. Use with `v-model` for two-way binding to control which tab is displayed.
+         */
         modelValue : string | number;
-        /** Orientation for tab layout (horizontal or vertical) */
+
+        /**
+         * Layout orientation for the tab list. In 'horizontal' mode, tabs are arranged in a row and
+         * arrow keys navigate left/right. In 'vertical' mode, tabs stack vertically and arrow keys
+         * navigate up/down.
+         * @default 'horizontal'
+         */
         orientation ?: SkTabsOrientation;
-        /** Placement of tabs relative to content (start, center, end) */
+
+        /**
+         * Alignment of the tab list within its container. 'start' aligns tabs to the left (horizontal)
+         * or top (vertical), 'end' aligns to the opposite side. Useful for positioning tabs in
+         * different layout contexts.
+         * @default 'start'
+         */
         placement ?: SkTabsPlacement;
-        /** Semantic color kind for all tabs (can be overridden per tab) */
+
+        /**
+         * Semantic color kind applied to all tabs in this group. Individual `SkTab` components can
+         * override this with their own `kind` prop for mixed-color tab bars.
+         */
         kind ?: ComponentKind;
-        /** Whether to use negative margins to align with parent container edges */
+
+        /**
+         * When true, applies negative margins to align the tab list flush with the parent container's
+         * edges. Useful when the parent has padding but you want tabs to extend edge-to-edge.
+         * @default false
+         */
         flush ?: boolean;
     }
 

package/src/components/Tag/SkTag.vue

@@ -1,6 +1,6 @@
-<!-------------------------------------------------------------------------------------------------------------------
+<!----------------------------------------------------------------------------------------------------------------------
   - Tag Component
-  ------------------------------------------------------------------------------------------------------------------->
+  --------------------------------------------------------------------------------------------------------------------->
 
 <template>
     <span :class="classes" :style="customColorStyles">
@@ -32,52 +32,73 @@
     </span>
 </template>
 
-<!------------------------------------------------------------------------------------------------------------------->
+<!--------------------------------------------------------------------------------------------------------------------->
+
+<style lang="scss" scoped>
+    // Component styles are implemented in /src/styles/components/_tag.scss
+</style>
+
+<!--------------------------------------------------------------------------------------------------------------------->
 
 <script setup lang="ts">
     /**
-     * @component
-     * A compact label component for displaying metadata, categories, or status information.
-     * Supports multiple variants, sizes, and optional remove functionality.
+     * @component SkTag
+     * @description A compact label component for displaying metadata, categories, or status information. Tags are
+     * ideal for showing keywords, filter chips, selected items in multi-selects, or status indicators. Supports
+     * four visual variants (solid, outline, subtle, ghost) and optional removable functionality with a dismiss button.
+     *
+     * @example
+     * ```vue
+     * <SkTag kind="primary">Featured</SkTag>
+     * <SkTag kind="success" removable @remove="handleRemove">Active</SkTag>
+     * ```
+     *
+     * @slot default - The tag label content. Can include text, icons, or any inline elements.
      */
 
     import { computed, toRef } from 'vue';
+
+    // Types
     import type { ComponentCustomColors, ComponentKind } from '@/types';
     import type { SkTagSize, SkTagVariant } from './types';
+
+    // Composables
     import { useCustomColors } from '@/composables/useCustomColors';
 
     //------------------------------------------------------------------------------------------------------------------
 
-    /**
-     * A compact label component for displaying metadata, categories, or status information.
-     * Supports multiple variants, sizes, and optional remove functionality.
-     *
-     * @example Basic tags
-     * ```vue
-     * <SkTag kind="primary">Featured</SkTag>
-     * <SkTag kind="success" removable @remove="handleRemove">Active</SkTag>
-     * ```
-     *
-     * @example Custom colored tag
-     * ```vue
-     * <SkTag
-     *   base-color="oklch(0.75 0.2 150)"
-     *   text-color="white"
-     *   variant="solid"
-     * >
-     *   Custom Green Tag
-     * </SkTag>
-     * ```
-     */
     export interface SkTagComponentProps extends ComponentCustomColors
     {
-        /** Semantic color kind for the tag */
+        /**
+         * Semantic color kind that controls the tag's color scheme. The kind determines both
+         * background and text colors across all variants. Use semantic kinds (primary, success,
+         * danger, etc.) to convey meaning, or use accent for decorative highlighting.
+         * @default 'neutral'
+         */
         kind ?: ComponentKind;
-        /** Visual variant style (solid, outline, subtle, or ghost) */
+
+        /**
+         * Visual variant that controls how the tag is rendered. Choose based on visual hierarchy:
+         * 'solid' for maximum emphasis with filled background, 'outline' for medium emphasis with
+         * a border, 'subtle' for low emphasis with a tinted background, 'ghost' for minimal
+         * presence with just text color.
+         * @default 'solid'
+         */
         variant ?: SkTagVariant;
-        /** Size of the tag affecting padding and font size */
+
+        /**
+         * Controls the tag dimensions including padding, font size, and remove button size.
+         * Available sizes: 'sm' (compact), 'md' (default), 'lg' (prominent), 'xl' (maximum).
+         * @default 'md'
+         */
         size ?: SkTagSize;
-        /** Whether to show a remove button that emits a 'remove' event when clicked */
+
+        /**
+         * When true, displays a small X button on the right side of the tag that emits a
+         * 'remove' event when clicked. Useful for filter chips, multi-select displays, or
+         * any tags that can be dismissed by the user.
+         * @default false
+         */
         removable ?: boolean;
     }
 
@@ -92,6 +113,10 @@
 
     //------------------------------------------------------------------------------------------------------------------
 
+    /**
+     * @event remove - Emitted when the remove button is clicked. Only fires when `removable` is true.
+     * Use this event to remove the tag from your data model or trigger a filter update.
+     */
     const emit = defineEmits<{
         remove : [];
     }>();
@@ -126,4 +151,4 @@
     );
 </script>
 
-<!------------------------------------------------------------------------------------------------------------------->
+<!--------------------------------------------------------------------------------------------------------------------->

package/src/components/TagsInput/SkTagsInput.vue

@@ -46,9 +46,22 @@
 
 <script setup lang="ts">
     /**
-     * @component
-     * A multi-value tag input component powered by RekaUI.
-     * Add tags by typing and pressing Enter, remove with backspace or delete button.
+     * @component SkTagsInput
+     * @description A multi-value tag input for collecting lists of string values. Users add tags by typing
+     * and pressing Enter (or pasting multiple values), and remove them by clicking the delete button or
+     * pressing Backspace. Built on RekaUI's TagsInput primitive with full keyboard accessibility.
+     *
+     * @example
+     * ```vue
+     * <SkTagsInput
+     *     v-model="skills"
+     *     kind="primary"
+     *     placeholder="Add a skill..."
+     *     :max="10"
+     * />
+     * ```
+     *
+     * @slot - Not applicable. This component does not accept slot content.
      */
 
     import { type ComputedRef, computed, inject, toRef } from 'vue';
@@ -69,26 +82,68 @@
 
     //------------------------------------------------------------------------------------------------------------------
 
-    /**
-     * A multi-value tag input component powered by RekaUI.
-     */
     export interface SkTagsInputComponentProps extends ComponentCustomColors
     {
-        /** Semantic color kind for input */
+        /**
+         * Semantic color kind that controls the input border and focus ring appearance.
+         * Also sets the default color for tags unless overridden by `tagKind`. When used
+         * inside SkField, inherits the field's kind if not explicitly set.
+         * @default 'neutral' (or inherited from parent SkField)
+         */
         kind ?: SkTagsInputKind;
-        /** Input size */
+
+        /**
+         * Size of the input field and tags. Controls the input height, tag size, and
+         * text sizing throughout the component. Available sizes: 'sm' (small),
+         * 'md' (medium), 'lg' (large).
+         * @default 'md'
+         */
         size ?: SkTagsInputSize;
-        /** Placeholder text */
+
+        /**
+         * Placeholder text displayed in the input field when no text is being typed.
+         * Visible even when tags are present. Use to guide users on what type of
+         * values to enter.
+         * @default 'Add tag...'
+         */
         placeholder ?: string;
-        /** Disabled state */
+
+        /**
+         * When true, the input is disabled and no tags can be added or removed.
+         * Existing tags remain visible but the delete buttons are non-functional.
+         * The entire component appears with reduced opacity.
+         * @default false
+         */
         disabled ?: boolean;
-        /** Maximum number of tags */
+
+        /**
+         * Maximum number of tags allowed. When the limit is reached, the input field
+         * is disabled (preventing new tags) but existing tags can still be removed.
+         * Useful for limiting selections in constrained contexts like form fields.
+         */
         max ?: number;
-        /** Add tags on paste */
+
+        /**
+         * When true, pasting text containing separators (commas, semicolons, newlines)
+         * automatically creates multiple tags. When false, pasted text is inserted as
+         * a single value in the input field.
+         * @default true
+         */
         addOnPaste ?: boolean;
-        /** Kind for tag badges (inherits from input kind if not set) */
+
+        /**
+         * Semantic color kind specifically for the tag badges. When not set, inherits
+         * from the `kind` prop. Use to differentiate tag appearance from the input
+         * styling, such as colorful tags in a neutral-bordered input.
+         */
         tagKind ?: string;
-        /** Variant for tag badges */
+
+        /**
+         * Visual variant for the tag badges. 'solid' renders filled tags with colored
+         * background, 'outline' shows bordered tags with transparent background, and
+         * 'ghost' provides subtle tags with minimal styling.
+         * @default 'solid'
+         */
         tagVariant ?: 'solid' | 'outline' | 'ghost';
     }
 
@@ -107,6 +162,12 @@
 
     //------------------------------------------------------------------------------------------------------------------
 
+    /**
+     * The array of tag values. Use with `v-model` for two-way binding. Each string
+     * in the array represents one tag displayed in the input. Tags maintain their
+     * order as entered by the user.
+     * @default []
+     */
     const modelValue = defineModel<string[]>({ default: () => [] });
 
     //------------------------------------------------------------------------------------------------------------------