nicklabs-ui 1.0.107 → 1.0.110

package/README.md

@@ -2,7 +2,7 @@
 
 A Vue 3 component library with glassmorphism design, built for modern web applications.
 
-**Version**: 1.0.106 | **Framework**: Vue 3.5+
+**Version**: 1.0.110 | **Framework**: Vue 3.5+
 
 ---
 
@@ -23,6 +23,7 @@ A Vue 3 component library with glassmorphism design, built for modern web applic
     - [NAudioSelect](#naudioselect)
     - [NSwitch](#nswitch)
     - [NDatePicker](#ndatepicker)
+    - [NTimePicker](#ntimepicker)
   - [Data Display](#data-display)
     - [NTable](#ntable)
     - [NVirtualTable](#nvirtualtable)
@@ -30,6 +31,7 @@ A Vue 3 component library with glassmorphism design, built for modern web applic
     - [NTag](#ntag)
     - [NEmpty](#nempty)
     - [NCode](#ncode)
+    - [NImage](#nimage)
   - [Modals & Overlays](#modals--overlays)
     - [NModal](#nmodal)
     - [NDrawer](#ndrawer)
@@ -860,6 +862,58 @@ const endDate = ref('')
 
 ---
 
+#### NTimePicker
+
+Time picker for selecting hour, minute, and second. Each unit can be toggled on or off independently, and the bound string is trimmed to match the enabled units. Uses a scrolling-list dropdown on desktop and a bottom sheet on mobile.
+
+**Props**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `modelValue` | `string` | `""` | Bound value (v-model). Format follows the enabled units, e.g. `HH:mm:ss`, `HH:mm`, `mm:ss` |
+| `hour` | `boolean` | `true` | Show the "hour" column |
+| `minute` | `boolean` | `true` | Show the "minute" column |
+| `second` | `boolean` | `true` | Show the "second" column |
+| `placeholder` | `string` | `"請選擇時間"` | Placeholder text |
+| `disabled` | `boolean` | `false` | Disable picker |
+| `clearable` | `boolean` | `false` | Show clear button |
+| `title` | `string` | `""` | Label above picker |
+| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Trigger size |
+
+**Events**
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `update:modelValue` | `string` | Value changed (v-model) |
+| `change` | `string` | Value changed |
+| `clear` | — | Clear button clicked |
+
+**Usage**
+
+```vue
+<template>
+  <!-- Hour : minute : second -->
+  <NTimePicker v-model="time" title="Select Time" clearable />
+
+  <!-- Hour : minute only (value becomes "HH:mm") -->
+  <NTimePicker v-model="timeHM" :second="false" title="Hour & Minute" />
+
+  <!-- Hour only (value becomes "HH") -->
+  <NTimePicker v-model="hourOnly" :minute="false" :second="false" title="Hour" />
+</template>
+
+<script setup>
+import { ref } from 'vue'
+import { NTimePicker } from 'nicklabs-ui'
+
+const time = ref('09:30:00')
+const timeHM = ref('14:30')
+const hourOnly = ref('08')
+</script>
+```
+
+---
+
 ### Data Display
 
 ---
@@ -1329,6 +1383,67 @@ const snippet = `const greeting = (name: string) => {
 
 ---
 
+#### NImage
+
+An image display component that behaves like a native `<img>` by default, with sizing, `object-fit`, and corner-radius props. Enable `preview` to make the thumbnail clickable — it opens a teleported, blurred-backdrop lightbox showing the full image, closable via the × button, the ESC key, or an overlay click.
+
+**Props**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `src` | `string` | — | Image source (required) |
+| `alt` | `string` | `""` | Alternative text |
+| `width` | `string \| number` | — | Thumbnail width (number is treated as px) |
+| `height` | `string \| number` | — | Thumbnail height (number is treated as px) |
+| `fit` | `"fill" \| "contain" \| "cover" \| "none" \| "scale-down"` | `"cover"` | Maps to CSS `object-fit` |
+| `radiusSize` | `"none" \| "sm" \| "md" \| "lg" \| "xl"` | `"md"` | Corner radius |
+| `lazy` | `boolean` | `false` | Use `loading="lazy"` for deferred loading |
+| `preview` | `boolean` | `false` | Click the image to open a full-size lightbox |
+| `previewSrc` | `string` | `src` | High-resolution source for the lightbox; falls back to `src` |
+| `zIndex` | `number` | `1000` | Lightbox overlay z-index |
+| `closeOnClickOverlay` | `boolean` | `true` | Close the lightbox when the backdrop is clicked |
+
+**Events**
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `load` | `Event` | Image finished loading |
+| `error` | `Event` | Image failed to load |
+| `preview-open` | — | Lightbox opened |
+| `preview-close` | — | Lightbox closed |
+
+**Usage**
+
+```vue
+<template>
+  <!-- Basic: behaves like <img> -->
+  <NImage src="/photo.jpg" :width="200" :height="140" alt="Scenery" />
+
+  <!-- Lightbox: click to view the full image -->
+  <NImage src="/photo.jpg" :width="200" :height="140" preview />
+
+  <!-- Separate thumbnail and full-resolution sources -->
+  <NImage
+    src="/photo-thumb.jpg"
+    preview-src="/photo-full.jpg"
+    :width="200"
+    :height="140"
+    preview
+  />
+
+  <!-- object-fit and corner radius -->
+  <NImage src="/photo.jpg" :width="160" :height="160" fit="contain" radius-size="xl" />
+</template>
+
+<script setup lang="ts">
+import { NImage } from 'nicklabs-ui'
+</script>
+```
+
+> Distinct from [NImageSelect](#nimageselect): `NImage` **displays** an image (with an optional lightbox), while `NImageSelect` is an **uploader** for picking image files.
+
+---
+
 ### Modals & Overlays
 
 ---