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

package/src/components/Dropdown/SkDropdown.vue

@@ -51,9 +51,26 @@
 
 <script setup lang="ts">
     /**
-     * @component
-     * A dropdown menu component combining a trigger button and menu content powered by RekaUI.
-     * Use with SkMenuItem and SkMenuSeparator components.
+     * @component SkDropdown
+     * @description A dropdown menu component that displays a list of actions or options when triggered. Built on
+     * RekaUI's dropdown primitives with full keyboard navigation, focus management, and accessibility. The menu
+     * content is portaled to the document body to prevent overflow issues. Supports nested submenus via
+     * SkDropdownSubmenu.
+     *
+     * @example
+     * ```vue
+     * <SkDropdown trigger-text="Actions" kind="primary">
+     *     <SkDropdownMenuItem @click="handleEdit">Edit</SkDropdownMenuItem>
+     *     <SkDropdownMenuItem @click="handleDuplicate">Duplicate</SkDropdownMenuItem>
+     *     <SkDropdownMenuSeparator />
+     *     <SkDropdownMenuItem @click="handleDelete">Delete</SkDropdownMenuItem>
+     * </SkDropdown>
+     * ```
+     *
+     * @slot trigger - Custom trigger element. When provided, replaces the default SkButton trigger.
+     *                 The slot content should be an interactive element (button, link, etc.).
+     * @slot default - Menu content containing SkDropdownMenuItem, SkDropdownMenuSeparator, and/or
+     *                 SkDropdownSubmenu components.
      */
 
     import { computed, provide, toRef } from 'vue';
@@ -77,20 +94,46 @@
 
     //------------------------------------------------------------------------------------------------------------------
 
-    /**
-     * A dropdown menu component combining a trigger button and menu content powered by RekaUI.
-     */
     export interface SkDropdownComponentProps extends ComponentCustomColors
     {
-        /** Semantic color kind */
+        /**
+         * Semantic color kind that controls the menu's accent colors for hover states and
+         * focus indicators. The kind is inherited by nested SkDropdownSubmenu components
+         * unless they specify their own kind.
+         * @default 'neutral'
+         */
         kind ?: SkDropdownKind;
-        /** Text for default trigger button (use trigger slot for custom trigger) */
+
+        /**
+         * Text displayed on the default trigger button. Only used when the trigger slot
+         * is not provided. For custom trigger elements (icons, avatar buttons, etc.),
+         * use the trigger slot instead.
+         * @default 'Menu'
+         */
         triggerText ?: string;
-        /** Side of the trigger to position menu */
+
+        /**
+         * Which side of the trigger element to position the dropdown menu. The menu
+         * will automatically flip to the opposite side if there isn't enough space.
+         * The caret icon on the default trigger rotates to match this direction.
+         * @default 'bottom'
+         */
         side ?: SkDropdownSide;
-        /** Alignment relative to trigger */
+
+        /**
+         * Horizontal alignment of the dropdown menu relative to the trigger. 'start'
+         * aligns the menu's left edge with the trigger's left edge, 'center' centers
+         * the menu, and 'end' aligns right edges.
+         * @default 'start'
+         */
         align ?: SkDropdownAlign;
-        /** Offset from the trigger in pixels */
+
+        /**
+         * Distance in pixels between the trigger element and the dropdown menu.
+         * Increase for more visual separation or decrease for a tighter connection
+         * to the trigger element.
+         * @default 4
+         */
         sideOffset ?: number;
     }
 

package/src/components/Dropdown/SkDropdownMenuItem.vue

@@ -18,8 +18,21 @@
 
 <script setup lang="ts">
     /**
-     * @component
-     * A menu item component for use within SkDropdown.
+     * @component SkDropdownMenuItem
+     * @description An individual menu item for use inside SkDropdown or SkDropdownSubmenu. Provides keyboard
+     * navigation support (arrow keys, Enter/Space to select) and proper focus management. Menu items automatically
+     * close the dropdown when clicked unless the event is prevented.
+     *
+     * @example
+     * ```vue
+     * <SkDropdown trigger-text="File">
+     *     <SkDropdownMenuItem @click="handleNew">New Document</SkDropdownMenuItem>
+     *     <SkDropdownMenuItem @click="handleOpen">Open...</SkDropdownMenuItem>
+     *     <SkDropdownMenuItem disabled>Save (disabled)</SkDropdownMenuItem>
+     * </SkDropdown>
+     * ```
+     *
+     * @slot default - The menu item label content. Can include text, icons, keyboard shortcuts, or any inline elements.
      */
 
     import { computed } from 'vue';
@@ -27,12 +40,14 @@
 
     //------------------------------------------------------------------------------------------------------------------
 
-    /**
-     * A menu item component for use within SkDropdown.
-     */
     export interface SkDropdownMenuItemComponentProps
     {
-        /** Disabled state */
+        /**
+         * When true, the menu item is visually dimmed and cannot be interacted with.
+         * Disabled items are skipped during keyboard navigation. Use for actions that
+         * are temporarily unavailable based on application state.
+         * @default false
+         */
         disabled ?: boolean;
     }
 
@@ -44,6 +59,10 @@
 
     //------------------------------------------------------------------------------------------------------------------
 
+    /**
+     * @event click - Emitted when the menu item is clicked or activated via keyboard (Enter/Space).
+     * The dropdown menu automatically closes after this event unless `event.preventDefault()` is called.
+     */
     defineEmits<{
         click : [event : Event];
     }>();

package/src/components/Dropdown/SkDropdownMenuSeparator.vue

@@ -16,8 +16,22 @@
 
 <script setup lang="ts">
     /**
-     * @component
-     * A menu separator component for use within SkDropdown.
+     * @component SkDropdownMenuSeparator
+     * @description A visual divider line for grouping related menu items within SkDropdown or SkDropdownSubmenu.
+     * Use separators to create logical sections in longer menus, improving scannability and organization.
+     * This is a purely visual component with no interactive behavior.
+     *
+     * @example
+     * ```vue
+     * <SkDropdown trigger-text="Edit">
+     *     <SkDropdownMenuItem>Undo</SkDropdownMenuItem>
+     *     <SkDropdownMenuItem>Redo</SkDropdownMenuItem>
+     *     <SkDropdownMenuSeparator />
+     *     <SkDropdownMenuItem>Cut</SkDropdownMenuItem>
+     *     <SkDropdownMenuItem>Copy</SkDropdownMenuItem>
+     *     <SkDropdownMenuItem>Paste</SkDropdownMenuItem>
+     * </SkDropdown>
+     * ```
      */
 
     import { DropdownMenuSeparator } from 'reka-ui';

package/src/components/Dropdown/SkDropdownSubmenu.vue

@@ -40,9 +40,25 @@
 
 <script setup lang="ts">
     /**
-     * @component
-     * A dropdown submenu component for nested menus.
-     * Use with SkDropdownMenuItem components in default slot.
+     * @component SkDropdownSubmenu
+     * @description A nested submenu component that expands from a parent SkDropdown or another SkDropdownSubmenu.
+     * The submenu opens to the side when the trigger item is hovered or focused, with full keyboard navigation
+     * support (arrow keys to navigate, Enter/Space or Right arrow to open, Left arrow or Escape to close).
+     * Content is portaled to prevent overflow clipping.
+     *
+     * @example
+     * ```vue
+     * <SkDropdown trigger-text="Options">
+     *     <SkDropdownMenuItem>Simple Action</SkDropdownMenuItem>
+     *     <SkDropdownSubmenu trigger-text="More Actions">
+     *         <SkDropdownMenuItem>Nested Item 1</SkDropdownMenuItem>
+     *         <SkDropdownMenuItem>Nested Item 2</SkDropdownMenuItem>
+     *     </SkDropdownSubmenu>
+     * </SkDropdown>
+     * ```
+     *
+     * @slot default - Menu content containing SkDropdownMenuItem, SkDropdownMenuSeparator, or further
+     *                 nested SkDropdownSubmenu components.
      */
 
     import { computed, inject } from 'vue';
@@ -61,14 +77,20 @@
 
     //------------------------------------------------------------------------------------------------------------------
 
-    /**
-     * A dropdown submenu component for nested menus.
-     */
     export interface SkDropdownSubmenuComponentProps
     {
-        /** Text for submenu trigger */
+        /**
+         * The label text displayed on the submenu trigger item. This appears as a menu
+         * item in the parent menu with a right-pointing caret indicating it opens a submenu.
+         */
         triggerText : string;
-        /** Semantic color kind (inherits from parent dropdown if not set) */
+
+        /**
+         * Semantic color kind for the submenu content. When not specified, the submenu
+         * automatically inherits the kind from its parent SkDropdown, ensuring visual
+         * consistency throughout nested menu structures.
+         * @default inherited from parent
+         */
         kind ?: SkDropdownKind;
     }
 

package/src/components/Field/SkField.vue

@@ -33,9 +33,26 @@
 
 <script setup lang="ts">
     /**
-     * @component
-     * A form field wrapper that provides label, description, and error message support.
-     * Automatically wires up accessibility attributes (id, aria-describedby, aria-invalid).
+     * @component SkField
+     * @description A form field wrapper that provides consistent label, description, and error message layout.
+     * Automatically generates unique IDs and wires up ARIA attributes (aria-describedby, aria-invalid) for
+     * accessibility. Child input components (SkInput, SkTextarea, etc.) automatically inherit the validation
+     * kind based on the `state` prop.
+     *
+     * @example
+     * ```vue
+     * <SkField label="Email" description="We'll never share your email" :error="errors.email">
+     *   <SkInput v-model="email" type="email" />
+     * </SkField>
+     *
+     * <SkField label="Username" required :state="isValid" label-position="left">
+     *   <SkInput v-model="username" />
+     * </SkField>
+     * ```
+     *
+     * @slot default - The form input component (SkInput, SkTextarea, SkNumberInput, etc.). Receives slot props:
+     *   `id` (string) - unique ID for the input, `aria-describedby` (string) - ID of description/error element,
+     *   `aria-invalid` (string) - "true" when error present, `kind` (string) - semantic kind based on state.
      */
 
     import { computed, provide } from 'vue';
@@ -45,28 +62,79 @@
 
     //------------------------------------------------------------------------------------------------------------------
 
-    /**
-     * A form field wrapper that provides label, description, and error message support.
-     */
     export interface SkFieldComponentProps
     {
-        /** Label text for the field */
+        /**
+         * Label text displayed above or beside the input. The label is automatically associated
+         * with the input via the `for` attribute using the generated or provided ID. Leave empty
+         * for inputs that don't need a visible label (use aria-label on the input instead).
+         * @default undefined
+         */
         label ?: string;
-        /** Description/help text */
+
+        /**
+         * Help text displayed below the input providing additional context or instructions.
+         * When an error message is present, the description is hidden and replaced by the error.
+         * Connected to the input via aria-describedby for screen reader accessibility.
+         * @default undefined
+         */
         description ?: string;
-        /** Error message (overrides description when present) */
+
+        /**
+         * Error message displayed below the input in a danger/red color. When present, replaces
+         * the description text and sets aria-invalid="true" on the input. Typically populated
+         * from form validation results.
+         * @default undefined
+         */
         error ?: string;
-        /** Required field indicator */
+
+        /**
+         * When true, displays a red asterisk (*) after the label to indicate the field is required.
+         * This is a visual indicator only—you must also set the `required` attribute on the input
+         * itself for form validation.
+         * @default false
+         */
         required ?: boolean;
-        /** Label position */
+
+        /**
+         * Position of the label relative to the input. 'top' places the label above the input
+         * (default, best for most forms). 'left' places the label to the left of the input
+         * (useful for horizontal form layouts or settings panels).
+         * @default 'top'
+         */
         labelPosition ?: SkFieldLabelPosition;
-        /** Custom field ID (auto-generated if not provided) */
+
+        /**
+         * Custom ID for the field. When provided, this ID is passed to the slotted input and
+         * used for label association. When not provided, a unique ID is auto-generated. Use
+         * custom IDs when you need to reference the input from elsewhere in your code.
+         * @default undefined (auto-generated)
+         */
         id ?: string;
-        /** Validation state (true = valid, false = invalid, null/undefined = neutral) */
+
+        /**
+         * Validation state that controls the visual kind of the child input. `true` applies the
+         * `validKind` (default: 'success'), `false` applies the `invalidKind` (default: 'danger'),
+         * and `null`/`undefined` lets the input use its own kind prop. Child inputs automatically
+         * inherit this via provide/inject.
+         * @default null
+         */
         state ?: boolean | null;
-        /** Kind to use when state is true (valid) */
+
+        /**
+         * Semantic kind to apply to the child input when `state` is `true` (valid). Typically
+         * 'success' for green styling indicating valid input. The kind is provided to child
+         * inputs via Vue's provide/inject system.
+         * @default 'success'
+         */
         validKind ?: string;
-        /** Kind to use when state is false (invalid) */
+
+        /**
+         * Semantic kind to apply to the child input when `state` is `false` (invalid). Typically
+         * 'danger' for red styling indicating validation errors. The kind is provided to child
+         * inputs via Vue's provide/inject system.
+         * @default 'danger'
+         */
         invalidKind ?: string;
     }
 

package/src/components/Group/SkGroup.vue

@@ -12,23 +12,38 @@
 
 <script setup lang="ts">
     /**
-     * @component
-     * A layout container that groups child elements with consistent spacing.
-     * Automatically arranges children in horizontal or vertical orientation.
+     * @component SkGroup
+     * @description A flexbox-based layout container that groups child elements with consistent spacing and alignment.
+     * Use SkGroup to arrange buttons, form controls, or any elements that should be visually grouped together.
+     * The component uses CSS gap for reliable spacing that works correctly regardless of conditional rendering.
+     *
+     * @example
+     * ```vue
+     * <SkGroup orientation="horizontal">
+     *     <SkButton>Save</SkButton>
+     *     <SkButton variant="outline">Cancel</SkButton>
+     * </SkGroup>
+     * ```
+     *
+     * @slot default - The child elements to be grouped. All direct children will be arranged according to the
+     *                 orientation prop with consistent spacing between them.
      */
 
     import { computed } from 'vue';
-    import type { SkGroupOrientation } from './types.ts';
+
+    // Types
+    import type { SkGroupOrientation } from './types';
 
     //------------------------------------------------------------------------------------------------------------------
 
-    /**
-     * A layout container that groups child elements with consistent spacing.
-     * Automatically arranges children in horizontal or vertical orientation.
-     */
     export interface SkGroupComponentProps
     {
-        /** Orientation for arranging child elements (horizontal or vertical) */
+        /**
+         * Controls how child elements are arranged within the group. Use 'horizontal' for
+         * side-by-side layouts (like button groups or inline form controls), or 'vertical'
+         * for stacked layouts (like form field groups or menu items).
+         * @default 'horizontal'
+         */
         orientation ?: SkGroupOrientation;
     }
 

package/src/components/Input/SkInput.vue

@@ -28,9 +28,19 @@
 
 <script setup lang="ts">
     /**
-     * @component
-     * A text input component with validation states and semantic color support.
-     * Supports various input types and flexible sizing.
+     * @component SkInput
+     * @description A single-line text input component with semantic color theming and validation state support.
+     * Supports various HTML input types (text, email, password, etc.) and integrates with SkField for labels
+     * and error messages. Use with `v-model` for two-way data binding of the input value.
+     *
+     * @example
+     * ```vue
+     * <SkInput v-model="email" type="email" placeholder="Enter your email" />
+     * <SkInput v-model="search" kind="primary" size="lg" />
+     * <SkField label="Username" :error="errors.username">
+     *   <SkInput v-model="username" name="username" required />
+     * </SkField>
+     * ```
      */
 
     import { type ComputedRef, computed, inject, toRef } from 'vue';
@@ -44,28 +54,75 @@
 
     //------------------------------------------------------------------------------------------------------------------
 
-    /**
-     * A text input component with validation states and semantic color support.
-     */
     export interface SkInputComponentProps extends ComponentCustomColors
     {
-        /** Input type */
+        /**
+         * The HTML input type attribute controlling the input behavior and keyboard on mobile devices.
+         * Common types include 'text', 'email', 'password', 'tel', 'url', 'search', and 'number'.
+         * Note: For numeric inputs with stepper buttons, consider using SkNumberInput instead.
+         * @default 'text'
+         */
         type ?: SkInputType;
-        /** 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 ?: SkInputKind;
-        /** Input size */
+
+        /**
+         * Input size controlling height, padding, and font size. Available sizes: 'sm' (small,
+         * compact forms), 'md' (medium, default), 'lg' (large), 'xl' (extra large, prominent inputs).
+         * @default 'md'
+         */
         size ?: SkInputSize;
-        /** Placeholder text */
+
+        /**
+         * Placeholder text displayed when the input is empty. Use to provide hints about expected
+         * input format or example values. The placeholder disappears when the user begins typing.
+         * @default undefined
+         */
         placeholder ?: string;
-        /** Disabled state */
+
+        /**
+         * When true, disables the input preventing all user interaction. The input 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 text but cannot
+         * modify it. Unlike disabled, read-only inputs are still included in form submission
+         * and maintain normal visual appearance.
+         * @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;
-        /** Autocomplete hint */
+
+        /**
+         * Autocomplete hint for the browser's autofill feature. Common values include 'off',
+         * 'email', 'username', 'current-password', 'new-password', 'given-name', 'family-name',
+         * 'street-address', etc. See MDN for the complete list of valid values.
+         * @default undefined
+         */
         autocomplete ?: string;
     }
 
@@ -85,6 +142,11 @@
 
     //------------------------------------------------------------------------------------------------------------------
 
+    /**
+     * The input value. Use with `v-model` for two-way binding. Accepts both string and number
+     * values to support various input types.
+     * @default ''
+     */
     const modelValue = defineModel<string | number>({ default: '' });
 
     //------------------------------------------------------------------------------------------------------------------

package/src/components/Listbox/SkListbox.vue

@@ -53,9 +53,22 @@
 
 <script setup lang="ts">
     /**
-     * @component
-     * A searchable listbox component for selecting from predefined options.
-     * Use with SkListboxItem components.
+     * @component SkListbox
+     * @description A searchable dropdown listbox for selecting from predefined options. Features a text input
+     * for filtering options and a dropdown panel displaying matching items. Built on RekaUI's Combobox
+     * primitive with full keyboard navigation, type-ahead search, and portal rendering for proper z-index.
+     *
+     * @example
+     * ```vue
+     * <SkListbox v-model="selectedCountry" kind="primary" placeholder="Select a country...">
+     *     <SkListboxItem value="us">United States</SkListboxItem>
+     *     <SkListboxItem value="uk">United Kingdom</SkListboxItem>
+     *     <SkListboxItem value="ca">Canada</SkListboxItem>
+     * </SkListbox>
+     * ```
+     *
+     * @slot default - SkListboxItem components representing the available options. Use SkListboxSeparator
+     *                 to create visual dividers between groups of options.
      */
 
     import { type ComputedRef, computed, inject, toRef } from 'vue';
@@ -79,18 +92,38 @@
 
     //------------------------------------------------------------------------------------------------------------------
 
-    /**
-     * A searchable listbox component for selecting from predefined options.
-     */
     export interface SkListboxComponentProps extends ComponentCustomColors
     {
-        /** Semantic color kind */
+        /**
+         * Semantic color kind that controls the input border, focus ring, and selected
+         * item highlight appearance. When used inside SkField, inherits the field's
+         * kind if not explicitly set.
+         * @default 'neutral' (or inherited from parent SkField)
+         */
         kind ?: SkListboxKind;
-        /** Input size */
+
+        /**
+         * Size of the input field and dropdown content. Controls the input height,
+         * text size, and option item dimensions. Available sizes: 'sm' (small),
+         * 'md' (medium), 'lg' (large).
+         * @default 'md'
+         */
         size ?: SkListboxSize;
-        /** Placeholder text */
+
+        /**
+         * Placeholder text displayed in the input field when no option is selected
+         * and no search text is entered. Use to guide users on what type of selection
+         * to make or to indicate the field purpose.
+         * @default 'Search...'
+         */
         placeholder ?: string;
-        /** Disabled state */
+
+        /**
+         * When true, the listbox is disabled and cannot be interacted with. The input
+         * field is non-editable and the dropdown cannot be opened. The component
+         * appears with reduced opacity and the cursor changes to not-allowed.
+         * @default false
+         */
         disabled ?: boolean;
     }
 
@@ -105,6 +138,11 @@
 
     //------------------------------------------------------------------------------------------------------------------
 
+    /**
+     * The selected value(s). Use with `v-model` for two-way binding. Pass a string
+     * for single selection mode, or an array of strings for multi-select mode.
+     * The value corresponds to the `value` prop of the selected SkListboxItem(s).
+     */
     const modelValue = defineModel<string | string[]>();
 
     //------------------------------------------------------------------------------------------------------------------

package/src/components/Listbox/SkListboxItem.vue

@@ -32,8 +32,22 @@
 
 <script setup lang="ts">
     /**
-     * @component
-     * A listbox item for use within SkListbox.
+     * @component SkListboxItem
+     * @description A selectable option within an SkListbox dropdown. When selected, the item displays a
+     * checkmark indicator and its value is set as the listbox's v-model. Built on RekaUI's ComboboxItem
+     * with keyboard navigation and type-ahead search support.
+     *
+     * @example
+     * ```vue
+     * <SkListbox v-model="selected">
+     *     <SkListboxItem value="option1">First Option</SkListboxItem>
+     *     <SkListboxItem value="option2">Second Option</SkListboxItem>
+     *     <SkListboxItem value="option3" disabled>Unavailable Option</SkListboxItem>
+     * </SkListbox>
+     * ```
+     *
+     * @slot default - The display content for this option. Can be plain text or rich content including
+     *                 icons, formatted text, or custom layouts. This is what users see in the dropdown.
      */
 
     import { computed } from 'vue';
@@ -41,14 +55,21 @@
 
     //------------------------------------------------------------------------------------------------------------------
 
-    /**
-     * A listbox item for use within SkListbox.
-     */
     export interface SkListboxItemComponentProps
     {
-        /** Value for this item */
+        /**
+         * The value this option represents. When selected, the parent SkListbox's v-model
+         * will be set to this value. Can be a string, number, or object for complex data.
+         * Must be unique within the listbox to ensure proper selection behavior.
+         */
         value : string | number | object;
-        /** Disabled state */
+
+        /**
+         * When true, this option is disabled and cannot be selected. The item appears
+         * with reduced opacity and is skipped during keyboard navigation. Use for
+         * temporarily unavailable options that should still be visible.
+         * @default false
+         */
         disabled ?: boolean;
     }