nicklabs-ui 1.0.4 → 1.0.7

package/README.md

@@ -0,0 +1,1604 @@
+# nicklabs-ui
+
+A Vue 3 component library with glassmorphism design, built for modern web applications.
+
+**Version**: 1.0.6 | **Framework**: Vue 3.5+
+
+---
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Setup](#setup)
+- [Components](#components)
+  - [Form Components](#form-components)
+    - [NButton](#nbutton)
+    - [NInput](#ninput)
+    - [NTextarea](#ntextarea)
+    - [NCheckbox](#ncheckbox)
+    - [NSelect](#nselect)
+    - [NFileSelect](#nfileselect)
+    - [NSwitch](#nswitch)
+  - [Data Display](#data-display)
+    - [NTable](#ntable)
+    - [NList](#nlist)
+    - [NTag](#ntag)
+    - [NEmpty](#nempty)
+    - [NCode](#ncode)
+  - [Modals & Overlays](#modals--overlays)
+    - [NModal](#nmodal)
+    - [NAlert](#nalert)
+    - [NToast](#ntoast)
+    - [NTooltip](#ntooltip)
+    - [NLoading](#nloading)
+  - [Layout](#layout)
+    - [NLayout](#nlayout)
+    - [NNavigation](#nnavigation)
+    - [NSidebar](#nsidebar)
+    - [NCard](#ncard)
+    - [NForm](#nform)
+    - [NLoginLayout](#nloginlayout)
+    - [NBreadcrumb](#nbreadcrumb)
+    - [NPaginate](#npaginate)
+    - [NHeroSection](#nherosection)
+    - [NSideFilter](#nsidefilter)
+- [Composables](#composables)
+  - [useToast](#usetoast)
+  - [useAlert](#usealert)
+  - [useDisclosure](#usedisclosure)
+  - [useSidebarManager](#usesidebarmanager)
+- [Type Reference](#type-reference)
+- [CSS Variables](#css-variables)
+
+---
+
+## Installation
+
+```bash
+npm install nicklabs-ui
+# or
+pnpm add nicklabs-ui
+```
+
+---
+
+## Setup
+
+### 1. Import Styles
+
+In your main entry file (e.g., `main.ts`):
+
+```typescript
+import { createApp } from 'vue'
+import App from './App.vue'
+
+// Required: reset and CSS variables
+import 'nicklabs-ui/reset.css'
+import 'nicklabs-ui/variables.css'
+
+// Required: component styles
+import 'nicklabs-ui/nicklabs-ui.css'
+
+createApp(App).mount('#app')
+```
+
+### 2. Import Components
+
+Import components individually as needed:
+
+```typescript
+import { NButton, NInput, NModal, useToast } from 'nicklabs-ui'
+```
+
+---
+
+## Components
+
+---
+
+### Form Components
+
+---
+
+#### NButton
+
+A versatile button supporting multiple visual variants and semantic intents.
+
+**Props**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `variant` | `"none" \| "solid" \| "outline" \| "ghost" \| "mute"` | `"solid"` | Visual style |
+| `intent` | `"none" \| "primary" \| "error" \| "success" \| "warning" \| "info"` | `"none"` | Semantic color intent |
+| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Button size |
+| `radiusSize` | `"sm" \| "md" \| "lg" \| "xl" \| "full"` | `"md"` | Border radius |
+| `disabled` | `boolean` | `false` | Disable interaction |
+| `type` | `"button" \| "submit" \| "reset"` | `"button"` | HTML button type |
+| `square` | `boolean` | `false` | Equal width/height (icon button) |
+| `padding` | `string` | — | Custom padding override |
+| `width` | `string` | — | Custom width override |
+| `height` | `string` | — | Custom height override |
+
+**Usage**
+
+```vue
+<template>
+  <!-- Basic -->
+  <NButton>Click me</NButton>
+
+  <!-- Variants -->
+  <NButton variant="solid" intent="primary">Primary</NButton>
+  <NButton variant="outline" intent="success">Success</NButton>
+  <NButton variant="ghost" intent="warning">Warning</NButton>
+  <NButton variant="mute" intent="error">Danger</NButton>
+
+  <!-- Sizes -->
+  <NButton size="sm">Small</NButton>
+  <NButton size="md">Medium</NButton>
+  <NButton size="lg">Large</NButton>
+
+  <!-- Submit button -->
+  <NButton type="submit" intent="primary">Submit</NButton>
+
+  <!-- Disabled -->
+  <NButton disabled>Disabled</NButton>
+
+  <!-- Icon button (square) -->
+  <NButton square size="sm">
+    <svg>...</svg>
+  </NButton>
+</template>
+
+<script setup>
+import { NButton } from 'nicklabs-ui'
+</script>
+```
+
+---
+
+#### NInput
+
+A full-featured text input with support for password visibility, number controls, and clearing.
+
+**Props**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `modelValue` | `string \| number` | — | Bound value (v-model) |
+| `type` | `string` | `"text"` | HTML input type |
+| `placeholder` | `string` | — | Placeholder text |
+| `disabled` | `boolean` | `false` | Disable input |
+| `readonly` | `boolean` | `false` | Read-only mode |
+| `clearable` | `boolean` | `false` | Show clear button |
+| `maxlength` | `number` | — | Maximum character length |
+| `min` | `number` | — | Minimum value (for type="number") |
+| `max` | `number` | — | Maximum value (for type="number") |
+| `title` | `string` | — | Label above the input |
+| `autocomplete` | `string` | — | HTML autocomplete attribute |
+
+**Events**
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `update:modelValue` | `string \| number` | Value changed |
+| `focus` | `FocusEvent` | Input focused |
+| `blur` | `FocusEvent` | Input blurred |
+| `input` | `Event` | Input event |
+| `change` | `Event` | Change event |
+| `keydown` | `KeyboardEvent` | Key pressed |
+| `clear` | — | Clear button clicked |
+
+**Usage**
+
+```vue
+<template>
+  <NInput v-model="username" placeholder="Enter username" title="Username" />
+
+  <!-- Password with visibility toggle -->
+  <NInput v-model="password" type="password" placeholder="Enter password" />
+
+  <!-- Clearable -->
+  <NInput v-model="search" placeholder="Search..." clearable />
+
+  <!-- Number with min/max -->
+  <NInput v-model="age" type="number" :min="0" :max="120" title="Age" />
+</template>
+
+<script setup>
+import { ref } from 'vue'
+import { NInput } from 'nicklabs-ui'
+
+const username = ref('')
+const password = ref('')
+const search = ref('')
+const age = ref(0)
+</script>
+```
+
+---
+
+#### NTextarea
+
+Multi-line text input with optional character count display.
+
+**Props**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `modelValue` | `string` | — | Bound value (v-model) |
+| `placeholder` | `string` | — | Placeholder text |
+| `disabled` | `boolean` | `false` | Disable textarea |
+| `readonly` | `boolean` | `false` | Read-only mode |
+| `rows` | `number` | `4` | Visible row count |
+| `maxLength` | `number` | — | Maximum character count |
+| `title` | `string` | — | Label above the textarea |
+| `showCount` | `boolean` | `false` | Show character counter |
+| `wrap` | `"soft" \| "off"` | `"soft"` | Text wrapping behavior |
+| `autofocus` | `boolean` | `false` | Auto-focus on mount |
+| `autocomplete` | `string` | — | HTML autocomplete attribute |
+
+**Events**
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `update:modelValue` | `string` | Value changed |
+| `focus` | `FocusEvent` | Textarea focused |
+| `blur` | `FocusEvent` | Textarea blurred |
+| `input` | `Event` | Input event |
+| `change` | `Event` | Change event |
+| `keydown` | `KeyboardEvent` | Key pressed |
+| `paste` | `ClipboardEvent` | Content pasted |
+
+**Usage**
+
+```vue
+<template>
+  <NTextarea
+    v-model="description"
+    title="Description"
+    placeholder="Enter description..."
+    :rows="5"
+    :maxLength="500"
+    showCount
+  />
+</template>
+
+<script setup>
+import { ref } from 'vue'
+import { NTextarea } from 'nicklabs-ui'
+
+const description = ref('')
+</script>
+```
+
+---
+
+#### NCheckbox
+
+Checkbox input supporting both single and multi-option modes.
+
+**Props**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `modelValue` | `boolean \| any[]` | — | Bound value (v-model) |
+| `multiple` | `boolean` | `false` | Enable multi-option mode |
+| `options` | `OptionItem[]` | — | Options for multi mode |
+| `disabled` | `boolean` | `false` | Disable input |
+| `title` | `string` | — | Label |
+| `direction` | `"row" \| "column"` | `"row"` | Layout direction for options |
+| `autofocus` | `boolean` | `false` | Auto-focus on mount |
+| `ariaLabel` | `string` | — | Accessibility label |
+
+**Events**
+
+| Event | Description |
+|-------|-------------|
+| `update:modelValue` | Value changed |
+| `change` | Generic change event |
+| `change:item` | Selected OptionItem changed |
+| `change:value` | Selected value changed |
+| `change:values` | Selected values array changed (multiple mode) |
+
+**Usage**
+
+```vue
+<template>
+  <!-- Single checkbox -->
+  <NCheckbox v-model="agreed" title="I agree to terms" />
+
+  <!-- Multiple checkboxes -->
+  <NCheckbox
+    v-model="selected"
+    multiple
+    :options="options"
+    direction="column"
+    title="Select interests"
+  />
+</template>
+
+<script setup>
+import { ref } from 'vue'
+import { NCheckbox } from 'nicklabs-ui'
+
+const agreed = ref(false)
+const selected = ref([])
+const options = [
+  { label: 'Vue', value: 'vue' },
+  { label: 'React', value: 'react' },
+  { label: 'Angular', value: 'angular' },
+]
+</script>
+```
+
+---
+
+#### NSelect
+
+Dropdown select with search, multi-select, and clear support.
+
+**Props**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `modelValue` | `any \| any[]` | — | Bound value (v-model) |
+| `options` | `OptionItem[]` | `[]` | Dropdown options |
+| `multiple` | `boolean` | `false` | Allow multiple selection |
+| `searchable` | `boolean` | `false` | Enable search/filter |
+| `clearable` | `boolean` | `false` | Show clear button |
+| `placeholder` | `string` | — | Placeholder text |
+| `disabled` | `boolean` | `false` | Disable input |
+| `title` | `string` | — | Label above dropdown |
+| `multipleDisplay` | `"count" \| "tags"` | `"tags"` | How selected items display |
+
+**Events**
+
+| Event | Description |
+|-------|-------------|
+| `update:modelValue` | Value changed |
+| `change` | Generic change event |
+| `change:item` | Selected OptionItem |
+| `change:value` | Selected value |
+| `change:values` | Selected values array (multiple mode) |
+
+**Usage**
+
+```vue
+<template>
+  <!-- Basic select -->
+  <NSelect v-model="city" :options="cities" placeholder="Select city" title="City" />
+
+  <!-- Searchable + clearable -->
+  <NSelect v-model="country" :options="countries" searchable clearable />
+
+  <!-- Multiple selection -->
+  <NSelect
+    v-model="tags"
+    :options="tagOptions"
+    multiple
+    multipleDisplay="tags"
+    title="Tags"
+  />
+</template>
+
+<script setup>
+import { ref } from 'vue'
+import { NSelect } from 'nicklabs-ui'
+
+const city = ref('')
+const country = ref(null)
+const tags = ref([])
+
+const cities = [
+  { label: 'Taipei', value: 'taipei' },
+  { label: 'Tokyo', value: 'tokyo' },
+  { label: 'Seoul', value: 'seoul' },
+]
+const countries = [
+  { label: 'Taiwan', value: 'TW' },
+  { label: 'Japan', value: 'JP' },
+]
+const tagOptions = [
+  { label: 'Frontend', value: 'frontend' },
+  { label: 'Backend', value: 'backend' },
+  { label: 'DevOps', value: 'devops' },
+]
+</script>
+```
+
+---
+
+#### NFileSelect
+
+Drag-and-drop file selector.
+
+**Props**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `multiple` | `boolean` | `false` | Allow multiple file selection |
+| `disabled` | `boolean` | `false` | Disable input |
+| `label` | `string` | — | Button/drop zone label |
+| `hint` | `string` | — | Helper text below |
+| `accept` | `string` | — | Accepted MIME types (e.g. `"image/*"`) |
+| `title` | `string` | — | Label above component |
+
+**Events**
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `change:file` | `File` | Single file selected |
+| `change:files` | `File[]` | Files selected (multiple mode) |
+
+**Usage**
+
+```vue
+<template>
+  <NFileSelect
+    title="Upload Avatar"
+    label="Drop image here or click to browse"
+    hint="Accepts PNG, JPG up to 2MB"
+    accept="image/*"
+    @change:file="handleFile"
+  />
+
+  <!-- Multiple files -->
+  <NFileSelect multiple accept=".pdf,.doc" @change:files="handleFiles" />
+</template>
+
+<script setup>
+import { NFileSelect } from 'nicklabs-ui'
+
+function handleFile(file: File) {
+  console.log('Selected:', file.name)
+}
+
+function handleFiles(files: File[]) {
+  console.log('Selected:', files.length, 'files')
+}
+</script>
+```
+
+---
+
+#### NSwitch
+
+Animated toggle switch.
+
+**Props**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `modelValue` | `boolean` | `false` | Bound value (v-model) |
+| `disabled` | `boolean` | `false` | Disable switch |
+| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Switch size |
+| `label` | `string` | — | Label text |
+
+**Events**
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `update:modelValue` | `boolean` | Value changed |
+| `change` | `boolean` | Value changed |
+
+**Usage**
+
+```vue
+<template>
+  <NSwitch v-model="enabled" label="Enable notifications" />
+  <NSwitch v-model="darkMode" size="lg" label="Dark mode" />
+</template>
+
+<script setup>
+import { ref } from 'vue'
+import { NSwitch } from 'nicklabs-ui'
+
+const enabled = ref(false)
+const darkMode = ref(false)
+</script>
+```
+
+---
+
+### Data Display
+
+---
+
+#### NTable
+
+A type-safe, sortable data table with support for custom formatters and action slots.
+
+**Props**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `columns` | `NTableColumn<T>[]` | `[]` | Column definitions |
+| `rows` | `T[]` | `[]` | Row data |
+| `striped` | `boolean` | `false` | Alternating row colors |
+| `bordered` | `boolean` | `false` | Show borders |
+| `hoverable` | `boolean` | `true` | Highlight rows on hover |
+| `loading` | `boolean` | `false` | Show loading state |
+| `emptyText` | `string` | — | Message when no data |
+| `rowKey` | `string` | `"id"` | Unique key field |
+
+**Events**
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `sort` | `NTableSortState` | Column sort changed |
+| `row-click` | `T` | Row was clicked |
+
+**Slots**
+
+| Slot | Description |
+|------|-------------|
+| `action` | Custom action buttons per row (scoped: `{ row }`) |
+
+**NTableColumn Interface**
+
+```typescript
+interface NTableColumn<T = any> {
+  key: string           // Data field key
+  label: string         // Column header text
+  width?: string        // CSS width (e.g. "120px")
+  align?: "left" | "center" | "right"
+  sortable?: boolean    // Enable column sorting
+  formatter?: (value: any, row: T) => string  // Custom cell renderer
+}
+```
+
+**Usage**
+
+```vue
+<template>
+  <NTable
+    :columns="columns"
+    :rows="users"
+    striped
+    hoverable
+    @sort="handleSort"
+    @row-click="handleRowClick"
+  >
+    <template #action="{ row }">
+      <NButton size="sm" variant="ghost" intent="primary" @click="edit(row)">Edit</NButton>
+      <NButton size="sm" variant="ghost" intent="error" @click="remove(row)">Delete</NButton>
+    </template>
+  </NTable>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue'
+import { NTable, NButton } from 'nicklabs-ui'
+import type { NTableColumn, NTableSortState } from 'nicklabs-ui'
+
+interface User {
+  id: number
+  name: string
+  email: string
+  role: string
+  createdAt: string
+}
+
+const columns: NTableColumn<User>[] = [
+  { key: 'name', label: 'Name', sortable: true },
+  { key: 'email', label: 'Email' },
+  { key: 'role', label: 'Role', align: 'center' },
+  {
+    key: 'createdAt',
+    label: 'Created',
+    formatter: (value) => new Date(value).toLocaleDateString(),
+  },
+]
+
+const users = ref<User[]>([
+  { id: 1, name: 'Alice', email: 'alice@example.com', role: 'Admin', createdAt: '2024-01-01' },
+  { id: 2, name: 'Bob', email: 'bob@example.com', role: 'User', createdAt: '2024-02-15' },
+])
+
+function handleSort(state: NTableSortState) {
+  console.log('Sort by:', state.key, state.order)
+}
+
+function handleRowClick(row: User) {
+  console.log('Clicked:', row)
+}
+</script>
+```
+
+---
+
+#### NList
+
+A full-featured data management component combining table, pagination, filtering, and CRUD operations.
+
+**Props**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `items` | `T[]` | `[]` | Data items |
+| `columns` | `NTableColumn<T>[]` | `[]` | Column definitions |
+| `pageSize` | `number` | `10` | Items per page |
+| `maxPageButtons` | `number` | `5` | Visible page buttons |
+| `filterable` | `boolean` | `false` | Show filter panel |
+| `rowEditable` | `boolean` | `false` | Show row edit button |
+| `rowDeletable` | `boolean` | `false` | Show row delete button |
+| `creatable` | `boolean` | `false` | Show create button |
+| `batchDeletable` | `boolean` | `false` | Enable batch delete |
+| `refreshable` | `boolean` | `false` | Show refresh button |
+
+**Events**
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `onRowEdit` | `T` | Row edit clicked |
+| `onRowDelete` | `T` | Row delete clicked |
+| `onPageChange` | `number` | Page changed |
+| `onCreate` | — | Create clicked |
+| `onBatchDelete` | `T[]` | Batch delete initiated |
+| `onRefresh` | — | Refresh clicked |
+| `onFilter` | — | Filter applied |
+| `row-click` | `T` | Row clicked |
+| `sort` | `NTableSortState` | Sort changed |
+
+**Usage**
+
+```vue
+<template>
+  <NList
+    :items="users"
+    :columns="columns"
+    :page-size="20"
+    filterable
+    row-editable
+    row-deletable
+    creatable
+    refreshable
+    @on-row-edit="handleEdit"
+    @on-row-delete="handleDelete"
+    @on-create="handleCreate"
+    @on-refresh="loadUsers"
+  />
+</template>
+
+<script setup lang="ts">
+import { NList } from 'nicklabs-ui'
+
+// ... same column/data setup as NTable
+</script>
+```
+
+---
+
+#### NTag
+
+Semantic tag/badge component.
+
+**Props**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `intent` | `"none" \| "primary" \| "success" \| "warning" \| "error" \| "info"` | `"none"` | Color intent |
+| `variant` | `"solid" \| "light" \| "outline"` | `"light"` | Visual style |
+| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Tag size |
+| `closable` | `boolean` | `false` | Show close button |
+| `round` | `boolean` | `false` | Fully rounded (pill shape) |
+
+**Events**
+
+| Event | Description |
+|-------|-------------|
+| `close` | Close button clicked |
+
+**Usage**
+
+```vue
+<template>
+  <NTag intent="success">Active</NTag>
+  <NTag intent="warning" variant="outline">Pending</NTag>
+  <NTag intent="error" variant="solid" round>Blocked</NTag>
+  <NTag intent="info" closable @close="removeTag">Vue 3</NTag>
+</template>
+
+<script setup>
+import { NTag } from 'nicklabs-ui'
+</script>
+```
+
+---
+
+#### NEmpty
+
+Empty state placeholder component.
+
+**Props**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `title` | `string` | — | Main message |
+| `description` | `string` | — | Sub-message |
+| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Component size |
+| `icon` | `string` | — | Custom SVG string |
+
+**Usage**
+
+```vue
+<template>
+  <NEmpty
+    title="No results found"
+    description="Try adjusting your search filters"
+    size="lg"
+  />
+</template>
+
+<script setup>
+import { NEmpty } from 'nicklabs-ui'
+</script>
+```
+
+---
+
+#### NCode
+
+Syntax-highlighted code display with copy-to-clipboard.
+
+**Props**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `code` | `string` | — | Code content to display |
+| `language` | `string` | — | Language for highlighting |
+| `showLineNumbers` | `boolean` | `false` | Show line numbers |
+
+**Usage**
+
+```vue
+<template>
+  <NCode
+    :code="snippet"
+    language="typescript"
+    showLineNumbers
+  />
+</template>
+
+<script setup>
+import { NCode } from 'nicklabs-ui'
+
+const snippet = `const greeting = (name: string) => {
+  return \`Hello, \${name}!\`
+}`
+</script>
+```
+
+---
+
+### Modals & Overlays
+
+---
+
+#### NModal
+
+A teleported modal dialog.
+
+**Props**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `show` | `boolean` | `false` | Visibility (v-model:show) |
+| `title` | `string` | — | Modal title |
+| `width` | `string` | `"500px"` | Modal width |
+| `closeOnClickOverlay` | `boolean` | `true` | Close when backdrop clicked |
+| `showClose` | `boolean` | `true` | Show close button |
+| `zIndex` | `number` | — | Custom z-index |
+
+**Events**
+
+| Event | Description |
+|-------|-------------|
+| `update:show` | Visibility changed |
+| `close` | Modal closed |
+| `open` | Modal opened |
+
+**Slots**
+
+| Slot | Description |
+|------|-------------|
+| `default` | Modal body content |
+| `footer` | Footer actions area |
+
+**Usage**
+
+```vue
+<template>
+  <NButton @click="open">Open Modal</NButton>
+
+  <NModal v-model:show="isOpen" title="Confirm Action" width="400px">
+    <p>Are you sure you want to proceed?</p>
+
+    <template #footer>
+      <NButton variant="ghost" @click="isOpen = false">Cancel</NButton>
+      <NButton intent="primary" @click="confirm">Confirm</NButton>
+    </template>
+  </NModal>
+</template>
+
+<script setup>
+import { ref } from 'vue'
+import { NModal, NButton } from 'nicklabs-ui'
+
+const isOpen = ref(false)
+
+function open() { isOpen.value = true }
+function confirm() {
+  // do something
+  isOpen.value = false
+}
+</script>
+```
+
+---
+
+#### NAlert
+
+Programmatic alert and confirm dialogs via the `useAlert` composable.
+
+> `NAlert` must be mounted once at the app root level.
+
+**Setup**
+
+```vue
+<!-- App.vue -->
+<template>
+  <RouterView />
+  <NAlert />
+</template>
+
+<script setup>
+import { NAlert } from 'nicklabs-ui'
+</script>
+```
+
+**Usage via `useAlert`**
+
+See [useAlert composable](#usealert) below.
+
+---
+
+#### NToast
+
+Notification toasts via the `useToast` composable.
+
+> `NToast` must be mounted once at the app root level.
+
+**Setup**
+
+```vue
+<!-- App.vue -->
+<template>
+  <RouterView />
+  <NToast />
+</template>
+
+<script setup>
+import { NToast } from 'nicklabs-ui'
+</script>
+```
+
+**Usage via `useToast`**
+
+See [useToast composable](#usetoast) below.
+
+---
+
+#### NTooltip
+
+Hover/focus tooltip with directional positioning.
+
+**Props**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `content` | `string` | — | Tooltip text |
+| `position` | `"top" \| "right" \| "bottom" \| "left"` | `"top"` | Tooltip position |
+| `disabled` | `boolean` | `false` | Disable tooltip |
+
+**Usage**
+
+```vue
+<template>
+  <NTooltip content="Delete this item" position="top">
+    <NButton variant="ghost" intent="error" square>
+      <svg>...</svg>
+    </NButton>
+  </NTooltip>
+</template>
+
+<script setup>
+import { NTooltip, NButton } from 'nicklabs-ui'
+</script>
+```
+
+---
+
+#### NLoading
+
+Loading indicator for inline use or full-page overlay.
+
+**Props**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `loading` | `boolean` | `false` | Show loading state |
+| `title` | `string` | — | Loading message |
+| `variant` | `"spinner" \| "dots"` | `"spinner"` | Animation style |
+| `overlay` | `boolean` | `false` | Full-page overlay mode |
+
+**Usage**
+
+```vue
+<template>
+  <!-- Inline -->
+  <NLoading :loading="isFetching" title="Loading data..." />
+
+  <!-- Full-page overlay -->
+  <NLoading :loading="isSubmitting" overlay title="Saving..." variant="dots" />
+</template>
+
+<script setup>
+import { ref } from 'vue'
+import { NLoading } from 'nicklabs-ui'
+
+const isFetching = ref(true)
+const isSubmitting = ref(false)
+</script>
+```
+
+---
+
+### Layout
+
+---
+
+#### NLayout
+
+Main application shell integrating sidebar and navigation.
+
+**Props**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `menus` | `Menu[]` | `[]` | Sidebar menu items |
+| `isShowSidebar` | `boolean` | `true` | Show/hide sidebar |
+| `copyright` | `string` | — | Footer copyright text |
+| `currentPath` | `string` | — | Active route path |
+
+**Events**
+
+| Event | Description |
+|-------|-------------|
+| `logout` | Logout triggered |
+| `navigate` | Menu item clicked |
+
+**Menu Type**
+
+```typescript
+type Menu = {
+  icon: string        // SVG string
+  title: string
+  children?: {
+    icon: string
+    title: string
+    route: string
+  }[]
+}
+```
+
+**Usage**
+
+```vue
+<template>
+  <NLayout
+    :menus="menus"
+    :current-path="$route.path"
+    copyright="© 2025 MyApp"
+    @logout="handleLogout"
+    @navigate="handleNavigate"
+  >
+    <RouterView />
+  </NLayout>
+</template>
+
+<script setup>
+import { NLayout } from 'nicklabs-ui'
+
+const menus = [
+  {
+    icon: '<svg>...</svg>',
+    title: 'Dashboard',
+    children: [
+      { icon: '<svg>...</svg>', title: 'Overview', route: '/dashboard' },
+    ],
+  },
+]
+</script>
+```
+
+---
+
+#### NNavigation
+
+Top navigation bar with sidebar toggle, fullscreen, and user controls.
+
+**Props**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `isShowSidebar` | `boolean` | `true` | Show sidebar toggle button |
+| `isShowFullscreen` | `boolean` | `true` | Show fullscreen button |
+| `isShowUser` | `boolean` | `true` | Show user pill |
+| `isShowLogoutButton` | `boolean` | `true` | Show logout button |
+
+**Events**
+
+| Event | Description |
+|-------|-------------|
+| `toggleSidebar` | Sidebar toggle clicked |
+| `logout` | Logout clicked |
+
+---
+
+#### NSidebar
+
+Collapsible side navigation menu.
+
+**Props**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `isOpen` | `boolean` | `true` | Sidebar open state |
+| `menus` | `Menu[]` | `[]` | Menu items |
+| `currentPath` | `string` | — | Active route path |
+
+**Events**
+
+| Event | Description |
+|-------|-------------|
+| `update:isOpen` | Open state changed |
+| `logout` | Logout triggered |
+| `navigate` | Menu item clicked |
+
+---
+
+#### NCard
+
+Content card with glassmorphism styling.
+
+**Props**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `size` | `"none" \| "sm" \| "md" \| "lg"` | `"md"` | Padding size |
+| `radius` | `"none" \| "sm" \| "md" \| "lg" \| "xl"` | `"lg"` | Border radius |
+
+**Usage**
+
+```vue
+<template>
+  <NCard size="lg" radius="xl">
+    <h2>Card Title</h2>
+    <p>Card content goes here.</p>
+  </NCard>
+</template>
+
+<script setup>
+import { NCard } from 'nicklabs-ui'
+</script>
+```
+
+---
+
+#### NForm
+
+Form wrapper with optional tab navigation and hero section header.
+
+**Props**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `model` | `object` | — | Form data object |
+| `disabled` | `boolean` | `false` | Disable all inputs |
+| `title` | `string` | — | Form header title |
+| `icon` | `string` | — | Header icon (SVG string) |
+| `tabs` | `string[]` | — | Tab labels for multi-section forms |
+
+**Events**
+
+| Event | Description |
+|-------|-------------|
+| `submit` | Form submitted |
+| `reset` | Form reset |
+
+**Usage**
+
+```vue
+<template>
+  <NForm
+    :model="formData"
+    title="User Profile"
+    :tabs="['Basic Info', 'Security', 'Preferences']"
+    @submit="handleSubmit"
+  >
+    <!-- Content renders based on active tab -->
+    <NInput v-model="formData.name" title="Name" />
+  </NForm>
+</template>
+
+<script setup>
+import { reactive } from 'vue'
+import { NForm, NInput } from 'nicklabs-ui'
+
+const formData = reactive({ name: '' })
+
+function handleSubmit() {
+  console.log('Submitted:', formData)
+}
+</script>
+```
+
+---
+
+#### NLoginLayout
+
+Full-screen login page wrapper with animated card.
+
+**Props**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `backgroundImage` | `string` | — | Background image URL |
+| `logo` | `string` | — | Logo image URL or SVG |
+| `title` | `string` | — | Application name |
+| `description` | `string` | — | Subtitle/tagline |
+
+**Usage**
+
+```vue
+<template>
+  <NLoginLayout
+    title="MyApp"
+    description="Sign in to your account"
+    background-image="/images/bg.jpg"
+    logo="/images/logo.png"
+  >
+    <NInput v-model="email" type="email" placeholder="Email" />
+    <NInput v-model="password" type="password" placeholder="Password" />
+    <NButton type="submit" intent="primary" style="width: 100%">Sign In</NButton>
+  </NLoginLayout>
+</template>
+
+<script setup>
+import { ref } from 'vue'
+import { NLoginLayout, NInput, NButton } from 'nicklabs-ui'
+
+const email = ref('')
+const password = ref('')
+</script>
+```
+
+---
+
+#### NBreadcrumb
+
+Static breadcrumb navigation display.
+
+**Usage**
+
+```vue
+<template>
+  <NBreadcrumb />
+</template>
+
+<script setup>
+import { NBreadcrumb } from 'nicklabs-ui'
+</script>
+```
+
+---
+
+#### NPaginate
+
+Pagination control with smart ellipsis.
+
+**Props**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `totalItems` | `number` | `0` | Total number of items |
+| `pageSize` | `number` | `10` | Items per page |
+| `maxPageButtons` | `number` | `5` | Max visible page buttons |
+
+**Events**
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `onPageChange` | `number` | New page number |
+
+**Usage**
+
+```vue
+<template>
+  <NPaginate
+    :total-items="totalCount"
+    :page-size="20"
+    :max-page-buttons="7"
+    @on-page-change="loadPage"
+  />
+</template>
+
+<script setup>
+import { ref } from 'vue'
+import { NPaginate } from 'nicklabs-ui'
+
+const totalCount = ref(350)
+
+function loadPage(page: number) {
+  // fetch page data
+}
+</script>
+```
+
+---
+
+#### NHeroSection
+
+Page header with icon, title, breadcrumb, and toolbar slot.
+
+**Props**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `title` | `string` | — | Section title |
+| `icon` | `string` | — | Icon (SVG string) |
+
+**Slots**
+
+| Slot | Description |
+|------|-------------|
+| `default` | Toolbar content (buttons, filters, etc.) |
+
+**Usage**
+
+```vue
+<template>
+  <NHeroSection title="User Management" :icon="userIcon">
+    <NButton intent="primary" @click="create">New User</NButton>
+  </NHeroSection>
+</template>
+
+<script setup>
+import { NHeroSection, NButton } from 'nicklabs-ui'
+
+const userIcon = '<svg>...</svg>'
+</script>
+```
+
+---
+
+#### NSideFilter
+
+A slide-out side drawer for filter interfaces.
+
+**Props**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `open` | `boolean` | `false` | Open state (v-model:open) |
+| `title` | `string` | — | Drawer title |
+
+**Events**
+
+| Event | Description |
+|-------|-------------|
+| `update:open` | Open state changed |
+| `close` | Drawer closed |
+
+**Usage**
+
+```vue
+<template>
+  <NButton @click="filterOpen = true">Filters</NButton>
+
+  <NSideFilter v-model:open="filterOpen" title="Filter Results">
+    <NSelect v-model="status" :options="statusOptions" title="Status" />
+    <NInput v-model="search" placeholder="Search name..." title="Name" />
+  </NSideFilter>
+</template>
+
+<script setup>
+import { ref } from 'vue'
+import { NSideFilter, NButton, NSelect, NInput } from 'nicklabs-ui'
+
+const filterOpen = ref(false)
+const status = ref(null)
+const search = ref('')
+</script>
+```
+
+---
+
+## Composables
+
+---
+
+### useToast
+
+Display notification toasts programmatically.
+
+```typescript
+import { useToast } from 'nicklabs-ui'
+
+const { toasts, toast, removeToast } = useToast()
+```
+
+**Methods**
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `toast` | `(message: string, options?: ToastOptions) => void` | Show a toast |
+| `toast.success` | `(message: string, options?) => void` | Success toast |
+| `toast.danger` | `(message: string, options?) => void` | Error toast |
+| `toast.warning` | `(message: string, options?) => void` | Warning toast |
+| `toast.info` | `(message: string, options?) => void` | Info toast |
+| `removeToast` | `(id: string) => void` | Remove a specific toast |
+
+**ToastOptions**
+
+```typescript
+interface ToastOptions {
+  title?: string    // Optional heading
+  duration?: number // Auto-dismiss ms (default: 4000)
+}
+```
+
+**Usage**
+
+```vue
+<script setup>
+import { useToast } from 'nicklabs-ui'
+
+const { toast } = useToast()
+
+function save() {
+  toast.success('Saved successfully!', { title: 'Done' })
+}
+
+function handleError() {
+  toast.danger('Something went wrong.', { duration: 6000 })
+}
+</script>
+```
+
+---
+
+### useAlert
+
+Display programmatic alert and confirm dialogs.
+
+```typescript
+import { useAlert } from 'nicklabs-ui'
+
+const { alert, confirm, clearAlerts } = useAlert()
+```
+
+**Methods**
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `alert(message, options?)` | `Promise<void>` | Show an alert dialog |
+| `alert.success(message, options?)` | `Promise<void>` | Success alert |
+| `alert.warning(message, options?)` | `Promise<void>` | Warning alert |
+| `alert.danger(message, options?)` | `Promise<void>` | Danger alert |
+| `alert.info(message, options?)` | `Promise<void>` | Info alert |
+| `confirm(message, options?)` | `Promise<boolean>` | Show a confirm dialog |
+| `clearAlerts()` | `void` | Dismiss all alerts |
+
+**AlertOptions**
+
+```typescript
+interface AlertOptions {
+  title?: string
+  confirmText?: string
+  cancelText?: string   // confirm() only
+}
+```
+
+**Usage**
+
+```vue
+<script setup>
+import { useAlert } from 'nicklabs-ui'
+
+const { alert, confirm } = useAlert()
+
+async function deleteUser(id: number) {
+  const confirmed = await confirm(
+    'This action cannot be undone.',
+    { title: 'Delete user?', confirmText: 'Delete', cancelText: 'Cancel' }
+  )
+
+  if (confirmed) {
+    await api.deleteUser(id)
+    await alert.success('User deleted.')
+  }
+}
+</script>
+```
+
+---
+
+### useDisclosure
+
+Simple boolean state management for modals and drawers.
+
+```typescript
+import { useDisclosure } from 'nicklabs-ui'
+
+// Array destructuring
+const [isOpen, open, close] = useDisclosure()
+
+// Object destructuring
+const { isOpen, open, close } = useDisclosure()
+```
+
+**Usage**
+
+```vue
+<template>
+  <NButton @click="open">Open Modal</NButton>
+  <NModal v-model:show="isOpen" title="My Modal">
+    <p>Content</p>
+    <template #footer>
+      <NButton @click="close">Close</NButton>
+    </template>
+  </NModal>
+</template>
+
+<script setup>
+import { NModal, NButton, useDisclosure } from 'nicklabs-ui'
+
+const [isOpen, open, close] = useDisclosure()
+</script>
+```
+
+---
+
+### useSidebarManager
+
+Manage sidebar open/close state and expandable menu items, persisted to localStorage.
+
+```typescript
+import { useSidebarManager } from 'nicklabs-ui'
+
+const {
+  isMenuExpanded,
+  toggleMenu,
+  isSidebarExpanded,
+  toggleSidebar,
+} = useSidebarManager(sidebarId?)
+```
+
+**Parameters**
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `sidebarId` | `string` | `"default"` | Unique ID for localStorage key |
+
+**Returns**
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `isMenuExpanded` | `(menuTitle: string) => boolean` | Check if a menu group is expanded |
+| `toggleMenu` | `(menuTitle: string) => void` | Toggle a menu group |
+| `isSidebarExpanded` | `() => boolean` | Check if sidebar is open |
+| `toggleSidebar` | `() => void` | Toggle sidebar open/close |
+
+---
+
+## Type Reference
+
+```typescript
+// Common
+interface OptionItem {
+  label: string
+  value: any
+}
+
+// Table
+interface NTableColumn<T = any> {
+  key: string
+  label: string
+  width?: string
+  align?: 'left' | 'center' | 'right'
+  sortable?: boolean
+  formatter?: (value: any, row: T) => string
+}
+
+interface NTableSortState {
+  key: string
+  order: 'asc' | 'desc' | null
+}
+
+// Layout
+type Menu = {
+  icon: string
+  title: string
+  children?: { icon: string; title: string; route: string }[]
+}
+
+// Sizes / Variants
+type NSize = 'sm' | 'md' | 'lg'
+type NButtonVariant = 'none' | 'solid' | 'outline' | 'ghost' | 'mute'
+type NButtonIntent = 'none' | 'primary' | 'error' | 'success' | 'warning' | 'info'
+type NTagIntent = 'none' | 'primary' | 'success' | 'warning' | 'error' | 'info'
+type NTagVariant = 'solid' | 'light' | 'outline'
+```
+
+---
+
+## CSS Variables
+
+The library reads these CSS custom properties from the host application. Override them to theme the components.
+
+```css
+:root {
+  /* Colors */
+  --primary-color: #4f6ef7;
+  --primary-light: #7b93fa;
+  --primary-dark: #3554e1;
+  --success-color: #22c55e;
+  --error-color: #ef4444;
+  --warning-color: #f59e0b;
+  --info-color: #3b82f6;
+
+  /* Text */
+  --text-main: #1e293b;
+  --text-secondary: #475569;
+  --text-muted: #94a3b8;
+  --text-inverse: #ffffff;
+
+  /* Backgrounds */
+  --bg-body: #f1f5f9;
+  --bg-gradient: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+
+  /* Surfaces (glassmorphism) */
+  --surface-solid: #ffffff;
+  --surface-glass: rgba(255, 255, 255, 0.7);
+  --surface-glass-border: rgba(255, 255, 255, 0.3);
+  --surface-glass-hover: rgba(255, 255, 255, 0.85);
+
+  /* Border */
+  --border-color: #e2e8f0;
+
+  /* Radius */
+  --radius-sm: 4px;
+  --radius-md: 8px;
+  --radius-lg: 12px;
+  --radius-xl: 16px;
+
+  /* Layout */
+  --header-height: 56px;
+  --sidebar-width: 60px;
+  --sidebar-width-open: 240px;
+  --sidebar-logo-height: 48px;
+
+  /* Inputs */
+  --input-bg: #ffffff;
+  --input-disabled-bg: #f8fafc;
+  --input-disabled-text: #94a3b8;
+
+  /* Transitions */
+  --transition-fast: 0.15s ease;
+  --transition-normal: 0.25s ease;
+}
+```
+
+> The `variables.css` export from `nicklabs-ui` provides a default set of these variables. Import it as a starting point and override as needed in your own stylesheet.