# Luminescent UI Documentation

> Complete component reference and API specifications for Luminescent UI (`@luminescent/ui`, `@luminescent/ui-qwik`, and `@luminescent/ui-react`).

## Quick Start & Installation

```bash
# Install Qwik UI components
npm install @luminescent/ui-qwik @luminescent/ui

# Install React UI components
npm install @luminescent/ui-react @luminescent/ui
```

## Component Catalog & API Reference

---

### LumClasses (`#classes`)
- **Category**: Tailwind Components
- **Description**: Core Luminescent UI CSS classes and design tokens built on Tailwind CSS v4.

#### Qwik Usage Example
```tsx
<div class="lum-card lum-bg-lum-card-bg rounded-lum p-4">
  <p class="lum-text-secondary text-sm">Design System Token Example</p>
</div>
```

#### React Usage Example
```tsx
<div className="lum-card lum-bg-lum-card-bg rounded-lum p-4">
  <p className="lum-text-secondary text-sm">Design System Token Example</p>
</div>
```

---

### LumBtn (`#button`)
- **Category**: Tailwind Components
- **Description**: Luminescent UI button utility classes providing consistent button variants, hover states, and padding options.

#### Qwik Usage Example
```tsx
<button class="lum-btn lum-bg-blue rounded-lum-2 p-2">
  Click Me
</button>
```

#### React Usage Example
```tsx
<button className="lum-btn lum-bg-blue rounded-lum-2 p-2">
  Click Me
</button>
```

---

### LumCard (`#card`)
- **Category**: Tailwind Components
- **Description**: Card container styling with glassmorphic background blur and gradient border utilities.

#### Qwik Usage Example
```tsx
<div class="lum-card border-gradient-1 p-4">
  <h3 class="text-lg font-bold">Card Title</h3>
  <p>Card content text</p>
</div>
```

#### React Usage Example
```tsx
<div className="lum-card border-gradient-1 p-4">
  <h3 className="text-lg font-bold">Card Title</h3>
  <p>Card content text</p>
</div>
```

---

### LumInput (`#input`)
- **Category**: Tailwind Components
- **Description**: Styled form inputs, textareas, and select menus with unified focus rings and background colors.

#### Qwik Usage Example
```tsx
<input class="lum-input" placeholder="Enter text..." />
```

#### React Usage Example
```tsx
<input className="lum-input" placeholder="Enter text..." />
```

---

### Anchor (`#anchor`)
- **Category**: Qwik / React Components
- **Description**: Header title wrapper component providing auto-generated scroll anchor links.

#### Props
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` | `-` | Unique element ID for the anchor scroll target |

#### Qwik Usage Example
```tsx
<Anchor id="my-section">
  <h2 id="my-section" class="text-2xl font-bold">My Section Title</h2>
</Anchor>
```

---

### ButtonContainer (`#button-container`)
- **Category**: Qwik / React Components
- **Description**: Flex container for grouping interactive buttons and links with consistent spacing, rounding, and hover styles.

#### Props
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `class` | `ClassList | string` | `-` | Additional CSS class list for custom positioning |

#### Qwik Usage Example
```tsx
<ButtonContainer>
  <button class="lum-btn lum-bg-transparent">Button 1</button>
  <button class="lum-btn lum-bg-transparent">Button 2</button>
</ButtonContainer>
```

#### React Usage Example
```tsx
<ButtonContainer>
  <button className="lum-btn lum-bg-transparent">Button 1</button>
  <button className="lum-btn lum-bg-transparent">Button 2</button>
</ButtonContainer>
```

---

### ColorPicker (`#color-picker`)
- **Category**: Qwik / React Components
- **Description**: Interactive color picker component supporting HEX, HSL, RGB, and opacity controls.

#### Props
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `string` | `-` | Current color string (e.g. #3b82f6) |
| `onChange$` | `QRL<(color: string) => void>` | `-` | Color change callback |

#### Qwik Usage Example
```tsx
<ColorPicker
  value={color.value}
  onChange$={(newColor) => (color.value = newColor)}
/>
```

---

### Dropdown (`#dropdown`)
- **Category**: Qwik / React Components
- **Description**: Dropdown menu component with customizable alignment, hover trigger, and panel placement.

#### Props
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` | `-` | Unique identifier for the dropdown |
| `align` | `'left' | 'right' | 'center'` | `'left'` | Alignment of the dropdown panel relative to trigger |
| `hover` | `boolean` | `false` | Open dropdown menu on hover instead of click |
| `top` | `boolean` | `false` | Position panel above the trigger button |
| `panelProps` | `PropsOf<'div'>` | `-` | Additional props for the dropdown panel container |

#### Slots
| Slot Name | Description |
| --- | --- |
| `dropdown` | Content rendered inside the trigger button |
| `default` | Options rendered inside the dropdown panel |

#### Qwik Usage Example
```tsx
<Dropdown id="demo-dropdown" align="left">
  <span q:slot="dropdown">Open Dropdown</span>
  <button class="lum-btn lum-bg-transparent rounded-lum-1">Option 1</button>
  <button class="lum-btn lum-bg-transparent rounded-lum-1">Option 2</button>
</Dropdown>
```

#### React Usage Example
```tsx
<Dropdown id="demo-dropdown" align="left" mobile={<span>Open Dropdown</span>}>
  <button className="lum-btn lum-bg-transparent rounded-lum-1">Option 1</button>
  <button className="lum-btn lum-bg-transparent rounded-lum-1">Option 2</button>
</Dropdown>
```

---

### DropdownButton (`#dropdown-button`)
- **Category**: Qwik / React Components
- **Description**: Interactive trigger button component for standalone or custom dropdown menus.

#### Props
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `opened` | `boolean` | `-` | Controls the active open indicator state |
| `hover` | `boolean` | `-` | Enables hover mode styling |

#### Qwik Usage Example
```tsx
<DropdownButton
  opened={opened.value}
  onClick$={() => (opened.value = !opened.value)}
>
  Dropdown Trigger
</DropdownButton>
```

---

### Label (`#label`)
- **Category**: Qwik / React Components
- **Description**: Form field wrapper component providing accessible labels and consistent spacing.

#### Props
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `for` | `string` | `-` | Target input element ID |
| `label` | `string` | `-` | Label text to display |

#### Qwik Usage Example
```tsx
<Label for="my-input" label="Username">
  <input id="my-input" class="lum-input" />
</Label>
```

---

### Nav (`#nav`)
- **Category**: Qwik / React Components
- **Description**: Responsive navigation header component supporting start, center, end, hamburger dropdown, and fixed bottom mobile navigation bar slots.

#### Props
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `fixed` | `boolean` | `-` | Fix navigation bar at the top of the viewport |
| `floating` | `boolean` | `-` | Enable floating card layout style with margin |
| `nohamburger` | `boolean` | `-` | Hide the top-right hamburger menu button on mobile |
| `colorClass` | `ClassList | string` | `-` | Custom background/border styling class |
| `innerProps` | `PropsOf<'div'>` | `-` | Props for main inner navigation bar container |
| `panelProps` | `PropsOf<'div'>` | `-` | Props for top hamburger menu dropdown container |
| `mobileNavProps` | `PropsOf<'div'>` | `-` | Props for bottom fixed mobile navigation bar container |

#### Slots
| Slot Name | Description |
| --- | --- |
| `start` | Left-aligned brand logo or title |
| `center` | Center navigation items (hidden on mobile by default) |
| `end` | Right-aligned navigation links, search, or profile menu |
| `hamburger` | Navigation items displayed inside the top hamburger dropdown menu |
| `mobile` | Navigation items displayed inside the fixed bottom mobile navigation bar |

#### Qwik Usage Example
```tsx
<Nav floating>
  <a q:slot="start" href="/" class="lum-btn lum-bg-transparent">Brand</a>
  <a q:slot="end" href="/docs" class="lum-btn lum-bg-transparent">Docs</a>
  <button q:slot="hamburger" class="lum-btn lum-bg-transparent">Hamburger Menu Item</button>
  <button q:slot="mobile" class="lum-btn lum-bg-transparent">Mobile Bar Item</button>
</Nav>
```

#### React Usage Example
```tsx
<Nav
  floating
  start={<a href="/" className="lum-btn lum-bg-transparent">Brand</a>}
  end={<a href="/docs" className="lum-btn lum-bg-transparent">Docs</a>}
  hamburger={<button className="lum-btn lum-bg-transparent">Hamburger Item</button>}
  mobile={<button className="lum-btn lum-bg-transparent">Mobile Item</button>}
/>
```

---

### NumberInput (`#number-input`)
- **Category**: Qwik / React Components
- **Description**: Stepper numeric input component with increment (+) and decrement (-) buttons.

#### Props
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `number` | `-` | Current numeric value |
| `min` | `number` | `-` | Minimum allowed numeric value |
| `max` | `number` | `-` | Maximum allowed numeric value |
| `step` | `number` | `1` | Step increment value |
| `onChange$` | `QRL<(val: number) => void>` | `-` | Value change handler |

#### Qwik Usage Example
```tsx
<NumberInput
  value={count.value}
  min={0}
  max={10}
  onChange$={(val) => (count.value = val)}
/>
```

---

### RangeInput (`#range-input`)
- **Category**: Qwik / React Components
- **Description**: Dynamic range slider input component.

#### Props
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `number` | `-` | Current slider value |
| `min` | `number` | `-` | Minimum slider value |
| `max` | `number` | `-` | Maximum slider value |
| `onChange$` | `QRL<(val: number) => void>` | `-` | Slider value change handler |

#### Qwik Usage Example
```tsx
<RangeInput
  value={slider.value}
  min={0}
  max={100}
  onChange$={(val) => (slider.value = val)}
/>
```

---

### SelectMenu (`#select-menu`)
- **Category**: Qwik / React Components
- **Description**: Custom dropdown select menu with support for icons, custom option slots, and placement alignment.

#### Props
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `values` | `SelectMenuValue[]` | `-` | Array of option items ({ name: string, value: string }) |
| `value` | `string` | `-` | Currently selected option value |
| `align` | `'left' | 'right' | 'center'` | `-` | Alignment of the select menu dropdown panel |

#### Qwik Usage Example
```tsx
<SelectMenu
  values={[
    { name: 'Option 1', value: '1' },
    { name: 'Option 2', value: '2' },
  ]}
  value="1"
  onChange$={(e, el) => (selected.value = el.value)}
/>
```

---

### Sidebar (`#sidebar`)
- **Category**: Qwik / React Components
- **Description**: Responsive collapsible sidebar layout component.

#### Props
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `floating` | `boolean` | `-` | Enable floating card layout style |

#### Slots
| Slot Name | Description |
| --- | --- |
| `title` | Sidebar header title text or icon |
| `default` | Sidebar navigation items and links |

#### Qwik Usage Example
```tsx
<Sidebar floating>
  <h3 q:slot="title" class="text-lg font-bold">Navigation</h3>
  <a class="lum-btn lum-bg-transparent" href="#link1">Link 1</a>
  <a class="lum-btn lum-bg-transparent" href="#link2">Link 2</a>
</Sidebar>
```

---

### Tabs (`#tabs`)
- **Category**: Qwik / React Components
- **Description**: Horizontal tab strip component built on ButtonContainer for switching views with optional add (+) and delete (x) actions.

#### Props
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `values` | `TabValue[]` | `-` | Array of tab objects ({ name: string, value: string }) |
| `value` | `TabValue` | `-` | Currently active tab object |
| `onClick$` | `QRL<(tab: TabValue) => void>` | `-` | Tab selection click handler |
| `onPlus$` | `QRL<() => void>` | `-` | Optional handler for add tab (+) button |
| `onDelete$` | `QRL<(tab: TabValue) => void>` | `-` | Optional handler for delete tab (x) button |

#### Qwik Usage Example
```tsx
<Tabs
  values={tabs.value}
  value={activeTab.value}
  onClick$={(tab) => (activeTab.value = tab)}
  onPlus$={() => { /* add tab logic */ }}
  onDelete$={(tab) => { /* delete tab logic */ }}
/>
```

#### React Usage Example
```tsx
<Tabs
  values={tabs}
  value={activeTab}
  onClick={(tab) => setActiveTab(tab)}
  onPlus={() => { /* add tab logic */ }}
  onDelete={(tab) => { /* delete tab logic */ }}
/>
```

---

### Toggle (`#toggle`)
- **Category**: Qwik / React Components
- **Description**: Accessible switch toggle component for boolean options.

#### Props
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` | `-` | Unique toggle input element ID |
| `checked` | `boolean` | `-` | Controls the active checked toggle state |
| `onChange$` | `QRL<(e, el) => void>` | `-` | Toggle change event callback |

#### Qwik Usage Example
```tsx
<Toggle
  id="my-toggle"
  checked={enabled.value}
  onChange$={(e, el) => (enabled.value = el.checked)}
>
  Enable Option
</Toggle>
```

#### React Usage Example
```tsx
<Toggle
  id="my-toggle"
  checked={enabled}
  onChange={(e) => setEnabled(e.target.checked)}
>
  Enable Option
</Toggle>
```