nicklabs-ui 1.0.25 → 1.0.27

package/README.md

@@ -2,7 +2,7 @@
 
 A Vue 3 component library with glassmorphism design, built for modern web applications.
 
-**Version**: 1.0.6 | **Framework**: Vue 3.5+
+**Version**: 1.0.26 | **Framework**: Vue 3.5+
 
 ---
 
@@ -19,6 +19,7 @@ A Vue 3 component library with glassmorphism design, built for modern web applic
     - [NSelect](#nselect)
     - [NFileSelect](#nfileselect)
     - [NSwitch](#nswitch)
+    - [NDatePicker](#ndatepicker)
   - [Data Display](#data-display)
     - [NTable](#ntable)
     - [NList](#nlist)
@@ -46,7 +47,9 @@ A Vue 3 component library with glassmorphism design, built for modern web applic
   - [useToast](#usetoast)
   - [useAlert](#usealert)
   - [useDisclosure](#usedisclosure)
+  - [useBreadcrumb](#usebreadcrumb)
   - [useSidebarManager](#usesidebarmanager)
+  - [useRouteModal](#useroutemodal)
 - [Type Reference](#type-reference)
 - [CSS Variables](#css-variables)
 
@@ -90,6 +93,22 @@ Import components individually as needed:
 import { NButton, NInput, NModal, useToast } from 'nicklabs-ui'
 ```
 
+### 3. Register All Components (Optional)
+
+```typescript
+import { createApp } from 'vue'
+import App from './App.vue'
+import router from './router'
+import { NickLabsUI } from 'nicklabs-ui'
+
+const app = createApp(App)
+app.use(router)
+app.use(NickLabsUI, { router })
+app.mount('#app')
+```
+
+> Passing `router` enables `useBreadcrumb` and `useRouteModal` without any additional setup.
+
 ---
 
 ## Components
@@ -394,10 +413,6 @@ const cities = [
   { 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' },
@@ -500,50 +515,110 @@ const darkMode = ref(false)
 
 ---
 
+#### NDatePicker
+
+Date picker with range selection and custom format support.
+
+**Props**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `modelValue` | `string \| Date` | — | Bound value (v-model) for single date |
+| `start` | `string` | — | Range start (v-model:start) |
+| `end` | `string` | — | Range end (v-model:end) |
+| `placeholder` | `string` | `"請選擇日期"` | Placeholder text |
+| `disabled` | `boolean` | `false` | Disable picker |
+| `clearable` | `boolean` | `false` | Show clear button |
+| `title` | `string` | — | Label above picker |
+| `format` | `string` | `"YYYY-MM-DD"` | Date format string (supports `YYYY`, `MM`, `DD`, `HH`, `mm`) |
+| `range` | `boolean` | `false` | Enable range selection mode |
+
+**Events**
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `update:modelValue` | `string` | Single date value changed |
+| `change` | `string` | Date changed |
+| `clear` | — | Clear button clicked |
+| `update:start` | `string` | Range start changed |
+| `update:end` | `string` | Range end changed |
+
+**Usage**
+
+```vue
+<template>
+  <!-- Single date -->
+  <NDatePicker v-model="date" title="Select Date" clearable />
+
+  <!-- With time format -->
+  <NDatePicker v-model="datetime" format="YYYY-MM-DD HH:mm" title="Date & Time" />
+
+  <!-- Date range -->
+  <NDatePicker
+    range
+    v-model:start="startDate"
+    v-model:end="endDate"
+    title="Date Range"
+  />
+</template>
+
+<script setup>
+import { ref } from 'vue'
+import { NDatePicker } from 'nicklabs-ui'
+
+const date = ref('')
+const datetime = ref('')
+const startDate = ref('')
+const endDate = ref('')
+</script>
+```
+
+---
+
 ### Data Display
 
 ---
 
 #### NTable
 
-A type-safe, sortable data table with support for custom formatters and action slots.
+A type-safe, sortable data table with support for batch selection and action slots.
 
 **Props**
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `columns` | `NTableColumn<T>[]` | `[]` | Column definitions |
-| `rows` | `T[]` | `[]` | Row data |
-| `striped` | `boolean` | `false` | Alternating row colors |
+| `columns` | `NTableColumn[]` | `[]` | Column definitions |
+| `items` | `T[]` | `[]` | Row data |
 | `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 |
+| `emptyTitle` | `string` | `"目前沒有資料"` | Title when no data |
+| `emptyDescription` | `string` | — | Description when no data |
+| `itemKey` | `string` | `"id"` | Unique key field |
 
 **Events**
 
 | Event | Payload | Description |
 |-------|---------|-------------|
 | `sort` | `NTableSortState` | Column sort changed |
-| `row-click` | `T` | Row was clicked |
+| `click` | `T` | Row was clicked |
 
 **Slots**
 
 | Slot | Description |
 |------|-------------|
-| `action` | Custom action buttons per row (scoped: `{ row }`) |
+| `batch` | Content in the batch selection header column |
+| `actions-header` | Custom header text for the actions column (default: "操作") |
+| `actions` | Custom action buttons per row (scoped: `{ item, column, index }`) |
+| `empty` | Custom empty state content |
 
 **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
+interface NTableColumn {
+  key: string       // Data field key
+  label: string     // Column header text
+  sortable?: boolean
 }
 ```
 
@@ -553,15 +628,14 @@ interface NTableColumn<T = any> {
 <template>
   <NTable
     :columns="columns"
-    :rows="users"
-    striped
+    :items="users"
     hoverable
     @sort="handleSort"
-    @row-click="handleRowClick"
+    @click="handleItemClick"
   >
-    <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 #actions="{ item }">
+      <NButton size="sm" variant="ghost" intent="primary" @click="edit(item)">Edit</NButton>
+      <NButton size="sm" variant="ghost" intent="error" @click="remove(item)">Delete</NButton>
     </template>
   </NTable>
 </template>
@@ -576,31 +650,25 @@ interface User {
   name: string
   email: string
   role: string
-  createdAt: string
 }
 
-const columns: NTableColumn<User>[] = [
+const columns: NTableColumn[] = [
   { 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(),
-  },
+  { key: 'role', label: 'Role' },
 ]
 
 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' },
+  { id: 1, name: 'Alice', email: 'alice@example.com', role: 'Admin' },
+  { id: 2, name: 'Bob', email: 'bob@example.com', role: 'User' },
 ])
 
 function handleSort(state: NTableSortState) {
   console.log('Sort by:', state.key, state.order)
 }
 
-function handleRowClick(row: User) {
-  console.log('Clicked:', row)
+function handleItemClick(item: User) {
+  console.log('Clicked:', item)
 }
 </script>
 ```
@@ -615,55 +683,77 @@ A full-featured data management component combining table, pagination, filtering
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `items` | `T[]` | `[]` | Data items |
-| `columns` | `NTableColumn<T>[]` | `[]` | Column definitions |
+| `title` | `string` | — | Section title displayed in hero header |
+| `description` | `string` | — | Section description displayed in hero header |
+| `items` | `T[]` | `[]` | Data items (T must extend `{ id: number }`) |
+| `columns` | `NTableColumn[]` | `[]` | Column definitions |
+| `itemKey` | `string` | `"id"` | Unique key field |
 | `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 |
+| `maxPageButtons` | `number` | `7` | Visible page buttons |
+| `filterable` | `boolean` | `false` | Show filter button |
+| `updatable` | `boolean` | `false` | Show row edit button |
+| `deletable` | `boolean` | `false` | Show row delete button |
 | `creatable` | `boolean` | `false` | Show create button |
-| `batchDeletable` | `boolean` | `false` | Enable batch delete |
+| `batchDeletable` | `boolean` | `false` | Enable batch delete with checkboxes |
 | `refreshable` | `boolean` | `false` | Show refresh button |
+| `emptyTitle` | `string` | `"目前沒有資料"` | Empty state title |
+| `emptyDescription` | `string` | — | Empty state description |
+| `emptyIcon` | `string` | — | Custom SVG string for empty state |
 
 **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 |
+| `update` | `T` | Row edit clicked |
+| `delete` | `T` | Row delete clicked |
+| `pageChange` | `number` | Page changed |
+| `create` | — | Create clicked |
+| `batchDelete` | `number[]` | Batch delete with selected IDs |
+| `refresh` | — | Refresh clicked |
+| `filter` | — | Filter clicked |
+| `click` | `T` | Row clicked |
 | `sort` | `NTableSortState` | Sort changed |
 
+**Slots**
+
+| Slot | Description |
+|------|-------------|
+| `toolbar` | Extra toolbar content (alongside create/refresh buttons) |
+| `item` | Custom cell renderer (scoped: `{ item, column, index }`) |
+| `actions` | Custom action buttons per row (scoped: `{ item, index }`) |
+| `actions-header` | Custom header text for the actions column |
+
 **Usage**
 
 ```vue
 <template>
   <NList
+    title="User Management"
     :items="users"
     :columns="columns"
     :page-size="20"
     filterable
-    row-editable
-    row-deletable
+    updatable
+    deletable
     creatable
     refreshable
-    @on-row-edit="handleEdit"
-    @on-row-delete="handleDelete"
-    @on-create="handleCreate"
-    @on-refresh="loadUsers"
+    @update="handleEdit"
+    @delete="handleDelete"
+    @create="handleCreate"
+    @refresh="loadUsers"
+    @filter="openFilter"
   />
 </template>
 
 <script setup lang="ts">
 import { NList } from 'nicklabs-ui'
 
-// ... same column/data setup as NTable
+// T must extend { id: number }
+interface User {
+  id: number
+  name: string
+  email: string
+}
 </script>
 ```
 
@@ -829,7 +919,6 @@ const isOpen = ref(false)
 
 function open() { isOpen.value = true }
 function confirm() {
-  // do something
   isOpen.value = false
 }
 </script>
@@ -960,37 +1049,29 @@ const isSubmitting = ref(false)
 
 #### NLayout
 
-Main application shell integrating sidebar and navigation.
+Main application shell integrating sidebar and main content area.
 
 **Props**
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `menus` | `Menu[]` | `[]` | Sidebar menu items |
+| `menus` | `Menu[]` | — | Sidebar menu items |
 | `isShowSidebar` | `boolean` | `true` | Show/hide sidebar |
 | `copyright` | `string` | — | Footer copyright text |
-| `currentPath` | `string` | — | Active route path |
+| `currentPath` | `string` | `""` | Active route path |
 
 **Events**
 
-| Event | Description |
-|-------|-------------|
-| `logout` | Logout triggered |
-| `navigate` | Menu item clicked |
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `logout` | — | Logout triggered |
+| `navigate` | `MenuChild` | Menu item clicked |
 
-**Menu Type**
+**Slots**
 
-```typescript
-type Menu = {
-  icon: string        // SVG string
-  title: string
-  children?: {
-    icon: string
-    title: string
-    route: string
-  }[]
-}
-```
+| Slot | Description |
+|------|-------------|
+| `default` | Main page content |
 
 **Usage**
 
@@ -1048,23 +1129,25 @@ Top navigation bar with sidebar toggle, fullscreen, and user controls.
 
 #### NSidebar
 
-Collapsible side navigation menu.
+Collapsible side navigation menu with hover-expand behavior.
 
 **Props**
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `isOpen` | `boolean` | `true` | Sidebar open state |
-| `menus` | `Menu[]` | `[]` | Menu items |
-| `currentPath` | `string` | — | Active route path |
+| `isOpen` | `boolean` | `false` | Sidebar open state |
+| `menus` | `Menu[]` | — | Menu items |
+| `currentPath` | `string` | `""` | Active route path |
+| `userName` | `string` | — | Display name shown in user area |
+| `userAvatarUrl` | `string` | — | Avatar image URL |
 
 **Events**
 
-| Event | Description |
-|-------|-------------|
-| `update:isOpen` | Open state changed |
-| `logout` | Logout triggered |
-| `navigate` | Menu item clicked |
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `update:isOpen` | `boolean` | Open state changed |
+| `logout` | — | Logout triggered |
+| `navigate` | `MenuChild` | Menu item clicked |
 
 ---
 
@@ -1077,7 +1160,7 @@ Content card with glassmorphism styling.
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
 | `size` | `"none" \| "sm" \| "md" \| "lg"` | `"md"` | Padding size |
-| `radius` | `"none" \| "sm" \| "md" \| "lg" \| "xl"` | `"lg"` | Border radius |
+| `radius` | `"none" \| "sm" \| "md" \| "lg" \| "xl"` | `"md"` | Border radius |
 
 **Usage**
 
@@ -1104,18 +1187,29 @@ Form wrapper with optional tab navigation and hero section header.
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `model` | `object` | — | Form data object |
+| `model` | `object` | `{}` | Form data object |
 | `disabled` | `boolean` | `false` | Disable all inputs |
 | `title` | `string` | — | Form header title |
+| `description` | `string` | — | Form header description |
 | `icon` | `string` | — | Header icon (SVG string) |
-| `tabs` | `string[]` | — | Tab labels for multi-section forms |
+| `tabs` | `string[]` | `[]` | Tab labels for multi-section forms |
 
 **Events**
 
-| Event | Description |
-|-------|-------------|
-| `submit` | Form submitted |
-| `reset` | Form reset |
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `submit` | `Record<string, any>` | Form submitted with model data |
+| `reset` | — | Form reset |
+
+**Slots**
+
+| Slot | Description |
+|------|-------------|
+| `toolbar` | Toolbar area in the hero header (buttons, etc.) |
+| `description` | Custom description content in hero header |
+| `tab0` | Content for first tab (or only content when no tabs) |
+| `tab1`, `tab2`, ... | Content for subsequent tabs |
+| `footer` | Form footer (submit/cancel buttons) |
 
 **Usage**
 
@@ -1124,22 +1218,37 @@ Form wrapper with optional tab navigation and hero section header.
   <NForm
     :model="formData"
     title="User Profile"
+    description="Manage your account details"
     :tabs="['Basic Info', 'Security', 'Preferences']"
     @submit="handleSubmit"
   >
-    <!-- Content renders based on active tab -->
-    <NInput v-model="formData.name" title="Name" />
+    <template #toolbar>
+      <NButton variant="ghost" @click="cancel">Cancel</NButton>
+    </template>
+
+    <template #tab0>
+      <NInput v-model="formData.name" title="Name" />
+      <NInput v-model="formData.email" title="Email" />
+    </template>
+
+    <template #tab1>
+      <NInput v-model="formData.password" type="password" title="Password" />
+    </template>
+
+    <template #footer>
+      <NButton type="submit" intent="primary">Save</NButton>
+    </template>
   </NForm>
 </template>
 
 <script setup>
 import { reactive } from 'vue'
-import { NForm, NInput } from 'nicklabs-ui'
+import { NForm, NInput, NButton } from 'nicklabs-ui'
 
-const formData = reactive({ name: '' })
+const formData = reactive({ name: '', email: '', password: '' })
 
-function handleSubmit() {
-  console.log('Submitted:', formData)
+function handleSubmit(model) {
+  console.log('Submitted:', model)
 }
 </script>
 ```
@@ -1154,8 +1263,8 @@ Full-screen login page wrapper with animated card.
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `backgroundImage` | `string` | — | Background image URL |
-| `logo` | `string` | — | Logo image URL or SVG |
+| `backgroundImage` | `string` | — | Background image URL (falls back to `--bg-gradient`) |
+| `logo` | `string` | — | Logo image URL or SVG string |
 | `title` | `string` | — | Application name |
 | `description` | `string` | — | Subtitle/tagline |
 
@@ -1188,7 +1297,9 @@ const password = ref('')
 
 #### NBreadcrumb
 
-Static breadcrumb navigation display.
+Breadcrumb navigation driven by `useBreadcrumb`. No props — reads from the composable's state automatically.
+
+> Configure breadcrumbs via [useBreadcrumb](#usebreadcrumb).
 
 **Usage**
 
@@ -1212,9 +1323,9 @@ Pagination control with smart ellipsis.
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `totalItems` | `number` | `0` | Total number of items |
-| `pageSize` | `number` | `10` | Items per page |
-| `maxPageButtons` | `number` | `5` | Max visible page buttons |
+| `totalItems` | `number` | — | Total number of items |
+| `pageSize` | `number` | — | Items per page |
+| `maxPageButtons` | `number` | `7` | Max visible page buttons (min: 5) |
 
 **Events**
 
@@ -1250,27 +1361,31 @@ function loadPage(page: number) {
 
 #### NHeroSection
 
-Page header with icon, title, breadcrumb, and toolbar slot.
+Page header with icon, title, description, breadcrumb, and toolbar slot.
 
 **Props**
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
 | `title` | `string` | — | Section title |
+| `description` | `string` | — | Section description |
 | `icon` | `string` | — | Icon (SVG string) |
 
 **Slots**
 
 | Slot | Description |
 |------|-------------|
-| `default` | Toolbar content (buttons, filters, etc.) |
+| `toolbar` | Toolbar content (buttons, filters, etc.) |
+| `description` | Custom description content |
 
 **Usage**
 
 ```vue
 <template>
-  <NHeroSection title="User Management" :icon="userIcon">
-    <NButton intent="primary" @click="create">New User</NButton>
+  <NHeroSection title="User Management" description="Manage system users" :icon="userIcon">
+    <template #toolbar>
+      <NButton intent="primary" @click="create">New User</NButton>
+    </template>
   </NHeroSection>
 </template>
 
@@ -1291,7 +1406,7 @@ A slide-out side drawer for filter interfaces.
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `open` | `boolean` | `false` | Open state (v-model:open) |
+| `open` | `boolean` | — | Open state (v-model:open) |
 | `title` | `string` | — | Drawer title |
 
 **Events**
@@ -1471,9 +1586,83 @@ const [isOpen, open, close] = useDisclosure()
 
 ---
 
+### useBreadcrumb
+
+Manage breadcrumb navigation state. `NBreadcrumb` reads from this composable automatically.
+
+```typescript
+import { useBreadcrumb } from 'nicklabs-ui'
+
+const {
+  breadcrumbs,
+  setLabelResolver,
+  setBreadcrumbSuffix,
+  clearSuffix,
+  navigate,
+} = useBreadcrumb()
+```
+
+**Methods**
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `setLabelResolver` | `(fn: (route) => string) => void` | Custom function to extract label from a route record |
+| `setBreadcrumbSuffix` | `(fn: (label: string) => string) => void` | Transform the last breadcrumb label (e.g. append a record name) |
+| `clearSuffix` | `() => void` | Reset the suffix transform |
+| `navigate` | `(path: string) => void` | Navigate to a breadcrumb path |
+
+**BreadcrumbItem**
+
+```typescript
+interface BreadcrumbItem {
+  label: string
+  path?: string  // undefined for the last (active) crumb
+}
+```
+
+**Setup**
+
+Pass `router` when installing the plugin (see [Setup](#setup)). The label is read from `route.meta.breadcrumb` by default — no additional configuration needed.
+
+**Route meta**
+
+```typescript
+const routes = [
+  {
+    path: '/users',
+    component: UserList,
+    meta: { breadcrumb: 'Users' },
+    children: [
+      {
+        path: ':id',
+        component: UserDetail,
+        meta: { breadcrumb: 'Detail' },
+      },
+    ],
+  },
+]
+```
+
+**Dynamic suffix example**
+
+```vue
+<script setup>
+import { onMounted, onUnmounted } from 'vue'
+import { useBreadcrumb } from 'nicklabs-ui'
+
+const { setBreadcrumbSuffix, clearSuffix } = useBreadcrumb()
+
+// Show user name as the last breadcrumb label
+onMounted(() => setBreadcrumbSuffix(() => user.value.name))
+onUnmounted(() => clearSuffix())
+</script>
+```
+
+---
+
 ### useSidebarManager
 
-Manage sidebar open/close state and expandable menu items, persisted to localStorage.
+Manage sidebar open/close state and expandable menu groups, persisted to localStorage.
 
 ```typescript
 import { useSidebarManager } from 'nicklabs-ui'
@@ -1503,6 +1692,77 @@ const {
 
 ---
 
+### useRouteModal
+
+Open and close route-based modals using Vue Router's nested routes.
+
+```typescript
+import { useRouteModal } from 'nicklabs-ui'
+
+const { isOpen, open, close, params } = useRouteModal({
+  routeName: 'user-detail',
+  parentRouteName: 'users',   // optional fallback when no history
+})
+```
+
+**Options**
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `routeName` | `string` | Yes | Named route that represents the open modal state |
+| `parentRouteName` | `string` | No | Fallback route to navigate to on close when there is no browser history |
+
+**Returns**
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `isOpen` | `ComputedRef<boolean>` | `true` when the named route is in the matched stack |
+| `open` | `(params?) => void` | Navigate to the modal route |
+| `close` | `() => void` | Navigate back (uses `router.back()` or parent route) |
+| `params` | `ComputedRef<RouteParams>` | Current route params |
+
+**Usage**
+
+```typescript
+// router/index.ts
+const routes = [
+  {
+    path: '/users',
+    name: 'users',
+    component: UserList,
+    children: [
+      {
+        path: ':id',
+        name: 'user-detail',
+        component: UserDetail,
+      },
+    ],
+  },
+]
+```
+
+```vue
+<template>
+  <NButton @click="open({ id: user.id })">View</NButton>
+
+  <NModal v-model:show="isOpen" title="User Detail" @close="close">
+    <p>ID: {{ params.id }}</p>
+  </NModal>
+</template>
+
+<script setup>
+import { useRouteModal } from 'nicklabs-ui'
+import { NModal, NButton } from 'nicklabs-ui'
+
+const { isOpen, open, close, params } = useRouteModal({
+  routeName: 'user-detail',
+  parentRouteName: 'users',
+})
+</script>
+```
+
+---
+
 ## Type Reference
 
 ```typescript
@@ -1512,34 +1772,50 @@ interface OptionItem {
   value: any
 }
 
+type NSize = 'sm' | 'md' | 'lg'
+
 // Table
-interface NTableColumn<T = any> {
+interface NTableColumn {
   key: string
   label: string
-  width?: string
-  align?: 'left' | 'center' | 'right'
   sortable?: boolean
-  formatter?: (value: any, row: T) => string
 }
 
+type NTableSortOrder = 'asc' | 'desc' | null
+
 interface NTableSortState {
   key: string
-  order: 'asc' | 'desc' | null
+  order: NTableSortOrder
 }
 
 // Layout
+type MenuChild = {
+  icon: string
+  title: string
+  route: string
+}
+
 type Menu = {
   icon: string
   title: string
-  children?: { icon: string; title: string; route: string }[]
+  children?: MenuChild[]
+}
+
+// Breadcrumb
+interface BreadcrumbItem {
+  label: string
+  path?: string
 }
 
 // Sizes / Variants
-type NSize = 'sm' | 'md' | 'lg'
 type NButtonVariant = 'none' | 'solid' | 'outline' | 'ghost' | 'mute'
 type NButtonIntent = 'none' | 'primary' | 'error' | 'success' | 'warning' | 'info'
+type NButtonRadiusSize = 'sm' | 'md' | 'lg' | 'xl' | 'full'
+type NButtonSize = 'sm' | 'md' | 'lg'
 type NTagIntent = 'none' | 'primary' | 'success' | 'warning' | 'error' | 'info'
 type NTagVariant = 'solid' | 'light' | 'outline'
+type PaddingSize = 'none' | 'sm' | 'md' | 'lg'
+type RadiusSize = 'none' | 'sm' | 'md' | 'lg' | 'xl'
 ```
 
 ---