nicklabs-ui 1.0.32 → 1.0.34

package/README.md

@@ -2,7 +2,7 @@
 
 A Vue 3 component library with glassmorphism design, built for modern web applications.
 
-**Version**: 1.0.26 | **Framework**: Vue 3.5+
+**Version**: 1.0.34 | **Framework**: Vue 3.5+
 
 ---
 
@@ -306,13 +306,15 @@ Checkbox input supporting both single and multi-option modes.
 |------|------|---------|-------------|
 | `modelValue` | `boolean \| any[]` | — | Bound value (v-model) |
 | `multiple` | `boolean` | `false` | Enable multi-option mode |
-| `options` | `OptionItem[]` | — | Options for multi mode |
+| `options` | `Record<string, any>[]` | — | Options for multi mode |
 | `disabled` | `boolean` | `false` | Disable input |
 | `title` | `string` | — | Group label displayed above options |
 | `label` | `string` | — | Text beside checkbox in single mode (overridable by default slot) |
 | `inline` | `boolean` | `false` | Display title and options on the same line |
 | `direction` | `"row" \| "column"` | `"row"` | Layout direction for options |
 | `autofocus` | `boolean` | `false` | Auto-focus on mount |
+| `formatLabel` | `(option: any) => string` | `(opt) => opt.label` | Function to extract display text from an option |
+| `formatValue` | `(option: any) => any` | `(opt) => opt.value` | Function to extract the value from an option |
 
 **Events**
 
@@ -342,6 +344,15 @@ Checkbox input supporting both single and multi-option modes.
 
   <!-- Inline title -->
   <NCheckbox v-model="selected" multiple :options="options" title="Interests" inline />
+
+  <!-- Custom field names -->
+  <NCheckbox
+    v-model="selected"
+    multiple
+    :options="[{ name: 'Apple', id: 'apple' }, { name: 'Banana', id: 'banana' }]"
+    :format-label="(opt) => opt.name"
+    :format-value="(opt) => opt.id"
+  />
 </template>
 
 <script setup>
@@ -377,6 +388,8 @@ Dropdown select with search, multi-select, and clear support.
 | `disabled` | `boolean` | `false` | Disable input |
 | `title` | `string` | — | Label above dropdown |
 | `multipleDisplay` | `"count" \| "tags"` | `"tags"` | How selected items display |
+| `formatLabel` | `(option: any) => string` | `(opt) => opt.label` | Function to extract display text from an option |
+| `formatValue` | `(option: any) => any` | `(opt) => opt.value` | Function to extract the value from an option |
 
 **Events**
 
@@ -406,6 +419,23 @@ Dropdown select with search, multi-select, and clear support.
     multipleDisplay="tags"
     title="Tags"
   />
+
+  <!-- Custom keys (API data with non-standard field names) -->
+  <NSelect
+    v-model="city"
+    :options="[{ name: 'Taipei', id: 'taipei' }, { name: 'Tokyo', id: 'tokyo' }]"
+    :format-label="(opt) => opt.name"
+    :format-value="(opt) => opt.id"
+    placeholder="Select city"
+  />
+
+  <!-- Combine multiple fields into display text -->
+  <NSelect
+    v-model="city"
+    :options="apiData"
+    :format-label="(opt) => `${opt.name} (${opt.code})`"
+    :format-value="(opt) => opt.id"
+  />
 </template>
 
 <script setup>
@@ -1018,26 +1048,34 @@ import { NTooltip, NButton } from 'nicklabs-ui'
 
 #### NLoading
 
-Loading indicator for inline use or full-page overlay.
+Loading indicator supporting inline, overlay, and fullscreen modes.
 
 **Props**
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `loading` | `boolean` | `false` | Show loading state |
+| `loading` | `boolean` | `true` | Show loading state |
 | `title` | `string` | — | Loading message |
 | `variant` | `"spinner" \| "dots"` | `"spinner"` | Animation style |
-| `overlay` | `boolean` | `false` | Full-page overlay mode |
+| `overlay` | `boolean` | `false` | Overlay mode — covers slot content with a backdrop |
+| `fullscreen` | `boolean` | `false` | Fullscreen mode — covers the entire viewport and blocks interaction |
 
 **Usage**
 
 ```vue
 <template>
-  <!-- Inline -->
-  <NLoading :loading="isFetching" title="Loading data..." />
-
-  <!-- Full-page overlay -->
-  <NLoading :loading="isSubmitting" overlay title="Saving..." variant="dots" />
+  <!-- Inline: shows spinner while loading, slot content when done -->
+  <NLoading :loading="isFetching" title="Loading data...">
+    <p>Content loaded!</p>
+  </NLoading>
+
+  <!-- Overlay: spinner overlaid on top of slot content -->
+  <NLoading :loading="isSubmitting" overlay title="Saving..." variant="dots">
+    <div>Form content here</div>
+  </NLoading>
+
+  <!-- Fullscreen: blocks entire viewport, no slot needed -->
+  <NLoading :loading="isProcessing" fullscreen title="處理中..." />
 </template>
 
 <script setup>
@@ -1046,6 +1084,7 @@ import { NLoading } from 'nicklabs-ui'
 
 const isFetching = ref(true)
 const isSubmitting = ref(false)
+const isProcessing = ref(false)
 </script>
 ```