@manik02/vue3-timepicker 0.1.2 → 0.2.0

package/README.md

@@ -1,9 +1,11 @@
 # Vue3 Timepicker
 
+[![Live Playground](https://img.shields.io/badge/Live-Playground-4f46e5?style=for-the-badge&logo=storybook&logoColor=white)](https://manos02.github.io/vue3-time-picker/)
+
 A flexible, customisable timepicker component for Vue 3 with TypeScript support.
 
-| Demo | Default | Dark |
-|------|---------|------|
+| Demo                                                                                     | Default                                                                                                   | Dark                                                                                                |
+| ---------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
 | ![Demo](https://raw.githubusercontent.com/manos02/vue3-time-picker/main/assets/demo.gif) | ![Default](https://raw.githubusercontent.com/manos02/vue3-time-picker/main/assets/screenshot-default.png) | ![Dark](https://raw.githubusercontent.com/manos02/vue3-time-picker/main/assets/screenshot-dark.png) |
 
 ![All themes](https://raw.githubusercontent.com/manos02/vue3-time-picker/main/assets/screenshot-all.png)
@@ -21,6 +23,8 @@ A flexible, customisable timepicker component for Vue 3 with TypeScript support.
 npm install @manik02/vue3-timepicker
 ```
 
+Try it live: [Interactive Playground](https://manos02.github.io/vue3-time-picker/)
+
 ## Quick start
 
 ```vue
@@ -37,17 +41,118 @@ const time = ref("14:30:00");
 </template>
 ```
 
+## Interactive Playground (Storybook)
+
+Run Storybook locally and experiment with all props via controls:
+
+```bash
+npm run storybook
+```
+
+Build static Storybook:
+
+```bash
+npm run build-storybook
+```
+
+The repository includes [storybook deploy workflow](.github/workflows/storybook.yml) to publish Storybook to GitHub Pages on push to `main`.
+
 ## Props
 
-| Prop         | Type                                 | Default     | Description                                                              |
-| ------------ | ------------------------------------ | ----------- | ------------------------------------------------------------------------ |
-| `modelValue` | `string \| [string, string] \| null` | `undefined` | Time value in `HH:mm:ss` format. Use a two-element array for range mode. |
-| `format`     | `TimeFormat`                         | `"HH:mm"`   | Display format (see format tokens below).                                |
-| `range`      | `boolean`                            | `false`     | Enable range selection with two time inputs.                             |
-| `hourStep`   | `number`                             | `1`         | Step interval for the hour column.                                       |
-| `minuteStep` | `number`                             | `1`         | Step interval for the minute column.                                     |
-| `secondStep` | `number`                             | `1`         | Step interval for the second column.                                     |
-| `size`       | `"sm" \| "md" \| "lg"`               | `"md"`     | Size preset that maps to CSS variables.                                  |
+| Prop             | Type                                   | Default     | Description                                                                             |
+| ---------------- | -------------------------------------- | ----------- | --------------------------------------------------------------------------------------- |
+| `modelValue`     | `string \| [string, string] \| null`   | `undefined` | Time value in `HH:mm:ss` format. Use a two-element array for range mode.                |
+| `format`         | `TimeFormat`                           | `"HH:mm"`   | Display format (see format tokens below).                                               |
+| `range`          | `boolean`                              | `false`     | Enable range selection with two time inputs.                                            |
+| `disabled`       | `boolean`                              | `false`     | Disables the timepicker input(s) and prevents opening/selecting.                        |
+| `hourStep`       | `number`                               | `1`         | Step interval for the hour column.                                                      |
+| `minuteStep`     | `number`                               | `1`         | Step interval for the minute column.                                                    |
+| `secondStep`     | `number`                               | `1`         | Step interval for the second column.                                                    |
+| `minTime`        | `string`                               | `undefined` | Lower bound in `HH:mm` or `HH:mm:ss`; input and dropdown are constrained.               |
+| `maxTime`        | `string`                               | `undefined` | Upper bound in `HH:mm` or `HH:mm:ss`; input and dropdown are constrained.               |
+| `disabledTimes`  | `(string \| [string, string])[]`       | `undefined` | Disabled points/ranges in `HH:mm:ss`; e.g. `"12:00:00"` or `[["13:00:00","14:00:00"]]`. |
+| `isTimeDisabled` | `(time: InternalFormat) => boolean`    | `undefined` | Callback for custom disable rules. Return `true` to block a time.                       |
+| `size`           | `"xs" \| "sm" \| "md" \| "lg" \| "xl"` | `"md"`      | Size preset that maps to CSS variables.                                                 |
+
+## Validation API
+
+The component exposes a validation state and emits validation events for predictable form handling:
+
+- `update:validationState` emits one of: `"valid"`, `"invalid"`, `"out-of-range"`
+- `validate` emits payload:
+
+```ts
+{
+  target: "first" | "second";
+  state: "valid" | "invalid" | "out-of-range";
+  reason?: "BAD_TIME" | "OUT_OF_RANGE" | "DISABLED";
+  value: string | null; // always HH:mm:ss when present
+}
+```
+
+`out-of-range` means the value was outside `minTime`/`maxTime` and got clamped.
+`invalid` means bad/incomplete input or a blocked value from `disabledTimes`/`isTimeDisabled`.
+
+### Example
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+
+const time = ref("12:00:00");
+const validationState = ref<"valid" | "invalid" | "out-of-range">("valid");
+
+function onValidate(payload: {
+  state: "valid" | "invalid" | "out-of-range";
+  reason?: "BAD_TIME" | "OUT_OF_RANGE" | "DISABLED";
+}) {
+  console.log("validate", payload.state, payload.reason);
+}
+</script>
+
+<template>
+  <TimePicker
+    v-model="time"
+    v-model:validationState="validationState"
+    minTime="09:00:00"
+    maxTime="18:00:00"
+    @validate="onValidate"
+  />
+
+  <small>State: {{ validationState }}</small>
+</template>
+```
+
+### Range Example
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+
+const range = ref<[string, string]>(["09:00:00", "17:00:00"]);
+const validationState = ref<"valid" | "invalid" | "out-of-range">("valid");
+
+function onValidate(payload: {
+  target: "first" | "second";
+  state: "valid" | "invalid" | "out-of-range";
+  reason?: "BAD_TIME" | "OUT_OF_RANGE" | "DISABLED";
+}) {
+  console.log(payload.target, payload.state, payload.reason);
+}
+</script>
+
+<template>
+  <TimePicker
+    v-model="range"
+    :range="true"
+    v-model:validationState="validationState"
+    :disabled-times="[["12:00:00", "13:00:00"]]"
+    @validate="onValidate"
+  />
+
+  <small>State: {{ validationState }}</small>
+</template>
+```
 
 ## Format tokens
 
@@ -109,9 +214,11 @@ The dropdown columns will show values at the specified intervals (e.g. 00, 15, 3
 ```vue
 <template>
   <div class="sizes">
+    <TimePicker v-model="time" format="HH:mm" size="xs" />
     <TimePicker v-model="time" format="HH:mm" size="sm" />
     <TimePicker v-model="time" format="HH:mm" size="md" />
     <TimePicker v-model="time" format="HH:mm" size="lg" />
+    <TimePicker v-model="time" format="HH:mm" size="xl" />
   </div>
 </template>
 ```

package/dist/TimePicker/TimePicker.vue.d.ts

@@ -1,3 +1,4 @@
+import { InternalFormat, DisabledTimeInput, ValidationReason, ValidationState } from './types';
 declare const _default: import('vue').DefineComponent<import('vue').ExtractPropTypes<{
     readonly modelValue: {
         readonly type: import('vue').PropType<string | [string, string] | null>;
@@ -8,6 +9,10 @@ declare const _default: import('vue').DefineComponent<import('vue').ExtractPropT
         readonly type: BooleanConstructor;
         readonly default: false;
     };
+    readonly disabled: {
+        readonly type: BooleanConstructor;
+        readonly default: false;
+    };
     readonly hourStep: {
         readonly type: NumberConstructor;
         readonly default: 1;
@@ -20,22 +25,48 @@ declare const _default: import('vue').DefineComponent<import('vue').ExtractPropT
         readonly type: NumberConstructor;
         readonly default: 1;
     };
+    readonly minTime: {
+        readonly type: import('vue').PropType<string | undefined>;
+        readonly default: undefined;
+        readonly validator: (v?: string) => boolean;
+    };
+    readonly maxTime: {
+        readonly type: import('vue').PropType<string | undefined>;
+        readonly default: undefined;
+        readonly validator: (v?: string) => boolean;
+    };
+    readonly disabledTimes: {
+        readonly type: import('vue').PropType<ReadonlyArray<DisabledTimeInput> | undefined>;
+        readonly default: undefined;
+        readonly validator: (v?: ReadonlyArray<DisabledTimeInput>) => boolean;
+    };
+    readonly isTimeDisabled: {
+        readonly type: import('vue').PropType<(time: InternalFormat) => boolean>;
+        readonly default: undefined;
+    };
     readonly format: {
         readonly type: import('vue').PropType<import('./types').TimeFormat>;
         readonly default: "HH:mm";
         readonly validator: (fmt: string) => boolean;
     };
     readonly size: {
-        readonly type: import('vue').PropType<"sm" | "md" | "lg">;
+        readonly type: import('vue').PropType<"xs" | "sm" | "md" | "lg" | "xl">;
         readonly default: "md";
-        readonly validator: (v: string) => v is "sm" | "md" | "lg";
+        readonly validator: (v: string) => v is "xs" | "sm" | "md" | "lg" | "xl";
     };
 }>, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {} & {
     "update:modelValue": (v: string | [string, string] | null) => any;
+    "update:validationState": (v: ValidationState) => any;
+    validate: (payload: {
+        target: "first" | "second";
+        state: ValidationState;
+        reason?: ValidationReason;
+        value: string | null;
+    }) => any;
     open: () => any;
     close: () => any;
     error: (payload: {
-        code: "BAD_TIME" | "OUT_OF_RANGE";
+        code: ValidationReason;
         message: string;
     }) => any;
 }, string, import('vue').PublicProps, Readonly<import('vue').ExtractPropTypes<{
@@ -48,6 +79,10 @@ declare const _default: import('vue').DefineComponent<import('vue').ExtractPropT
         readonly type: BooleanConstructor;
         readonly default: false;
     };
+    readonly disabled: {
+        readonly type: BooleanConstructor;
+        readonly default: false;
+    };
     readonly hourStep: {
         readonly type: NumberConstructor;
         readonly default: 1;
@@ -60,32 +95,63 @@ declare const _default: import('vue').DefineComponent<import('vue').ExtractPropT
         readonly type: NumberConstructor;
         readonly default: 1;
     };
+    readonly minTime: {
+        readonly type: import('vue').PropType<string | undefined>;
+        readonly default: undefined;
+        readonly validator: (v?: string) => boolean;
+    };
+    readonly maxTime: {
+        readonly type: import('vue').PropType<string | undefined>;
+        readonly default: undefined;
+        readonly validator: (v?: string) => boolean;
+    };
+    readonly disabledTimes: {
+        readonly type: import('vue').PropType<ReadonlyArray<DisabledTimeInput> | undefined>;
+        readonly default: undefined;
+        readonly validator: (v?: ReadonlyArray<DisabledTimeInput>) => boolean;
+    };
+    readonly isTimeDisabled: {
+        readonly type: import('vue').PropType<(time: InternalFormat) => boolean>;
+        readonly default: undefined;
+    };
     readonly format: {
         readonly type: import('vue').PropType<import('./types').TimeFormat>;
         readonly default: "HH:mm";
         readonly validator: (fmt: string) => boolean;
     };
     readonly size: {
-        readonly type: import('vue').PropType<"sm" | "md" | "lg">;
+        readonly type: import('vue').PropType<"xs" | "sm" | "md" | "lg" | "xl">;
         readonly default: "md";
-        readonly validator: (v: string) => v is "sm" | "md" | "lg";
+        readonly validator: (v: string) => v is "xs" | "sm" | "md" | "lg" | "xl";
     };
 }>> & Readonly<{
     "onUpdate:modelValue"?: ((v: string | [string, string] | null) => any) | undefined;
+    "onUpdate:validationState"?: ((v: ValidationState) => any) | undefined;
+    onValidate?: ((payload: {
+        target: "first" | "second";
+        state: ValidationState;
+        reason?: ValidationReason;
+        value: string | null;
+    }) => any) | undefined;
     onOpen?: (() => any) | undefined;
     onClose?: (() => any) | undefined;
     onError?: ((payload: {
-        code: "BAD_TIME" | "OUT_OF_RANGE";
+        code: ValidationReason;
         message: string;
     }) => any) | undefined;
 }>, {
     readonly modelValue: string | [string, string] | null;
     readonly range: boolean;
+    readonly disabled: boolean;
     readonly hourStep: number;
     readonly minuteStep: number;
     readonly secondStep: number;
+    readonly minTime: string | undefined;
+    readonly maxTime: string | undefined;
+    readonly disabledTimes: readonly DisabledTimeInput[] | undefined;
+    readonly isTimeDisabled: (time: InternalFormat) => boolean;
     readonly format: import('./types').TimeFormat;
-    readonly size: "sm" | "md" | "lg";
+    readonly size: "xs" | "sm" | "md" | "lg" | "xl";
 }, {}, {}, {}, string, import('vue').ComponentProvideOptions, true, {
     secondInputRef: HTMLInputElement;
 }, any>;

package/dist/TimePicker/TimeSelection.vue.d.ts

@@ -3,6 +3,10 @@ type __VLS_Props = {
     open: boolean;
     initTime: InternalFormat;
     format: string;
+    minTime?: InternalFormat | null;
+    maxTime?: InternalFormat | null;
+    disabledRanges?: Array<[InternalFormat, InternalFormat]>;
+    isTimeDisabled?: (time: InternalFormat) => boolean;
     hourStep?: number;
     minuteStep?: number;
     secondStep?: number;

package/dist/TimePicker/types.d.ts

@@ -13,6 +13,9 @@ export type InternalFormat = {
     m: number;
     s: number;
 };
+export type DisabledTimeInput = string | [string, string];
+export type ValidationState = "valid" | "invalid" | "out-of-range";
+export type ValidationReason = "BAD_TIME" | "OUT_OF_RANGE" | "DISABLED";
 export declare const FORMAT_SHAPE: RegExp;
 export declare const TIME_SHAPE: RegExp;
 export declare const timePickerProps: {
@@ -25,6 +28,10 @@ export declare const timePickerProps: {
         readonly type: BooleanConstructor;
         readonly default: false;
     };
+    readonly disabled: {
+        readonly type: BooleanConstructor;
+        readonly default: false;
+    };
     readonly hourStep: {
         readonly type: NumberConstructor;
         readonly default: 1;
@@ -37,15 +44,34 @@ export declare const timePickerProps: {
         readonly type: NumberConstructor;
         readonly default: 1;
     };
+    readonly minTime: {
+        readonly type: PropType<string | undefined>;
+        readonly default: undefined;
+        readonly validator: (v?: string) => boolean;
+    };
+    readonly maxTime: {
+        readonly type: PropType<string | undefined>;
+        readonly default: undefined;
+        readonly validator: (v?: string) => boolean;
+    };
+    readonly disabledTimes: {
+        readonly type: PropType<ReadonlyArray<DisabledTimeInput> | undefined>;
+        readonly default: undefined;
+        readonly validator: (v?: ReadonlyArray<DisabledTimeInput>) => boolean;
+    };
+    readonly isTimeDisabled: {
+        readonly type: PropType<(time: InternalFormat) => boolean>;
+        readonly default: undefined;
+    };
     readonly format: {
         readonly type: PropType<TimeFormat>;
         readonly default: "HH:mm";
         readonly validator: (fmt: string) => boolean;
     };
     readonly size: {
-        readonly type: PropType<"sm" | "md" | "lg">;
+        readonly type: PropType<"xs" | "sm" | "md" | "lg" | "xl">;
         readonly default: "md";
-        readonly validator: (v: string) => v is "sm" | "md" | "lg";
+        readonly validator: (v: string) => v is "xs" | "sm" | "md" | "lg" | "xl";
     };
 };
 export type TimePickerProps = ExtractPropTypes<typeof timePickerProps>;
@@ -80,10 +106,17 @@ export declare const TimeSelectionProps: {
 export type TimeSelectionProps = ExtractPropTypes<typeof TimeSelectionProps>;
 export interface TimePickerEmits {
     (e: "update:modelValue", v: string | [string, string] | null): void;
+    (e: "update:validationState", v: ValidationState): void;
+    (e: "validate", payload: {
+        target: "first" | "second";
+        state: ValidationState;
+        reason?: ValidationReason;
+        value: string | null;
+    }): void;
     (e: "open"): void;
     (e: "close"): void;
     (e: "error", payload: {
-        code: "BAD_TIME" | "OUT_OF_RANGE";
+        code: ValidationReason;
         message: string;
     }): void;
 }

package/dist/helpers.d.ts

@@ -13,3 +13,7 @@ export declare function to12(h24: number): number;
 export declare function to24(h12: number, isPM: boolean): number;
 export declare function hasSeconds(fmt: string): boolean;
 export declare function formatTime(fmt: string, time: InternalFormat): string;
+export declare function compareTimes(a: InternalFormat, b: InternalFormat): number;
+export declare function clampTimeToBounds(time: InternalFormat, minTime?: InternalFormat | null, maxTime?: InternalFormat | null): InternalFormat;
+export declare function isTimeWithinBounds(time: InternalFormat, minTime?: InternalFormat | null, maxTime?: InternalFormat | null): boolean;
+export declare function isTimeInRanges(time: InternalFormat, ranges: Array<[InternalFormat, InternalFormat]>): boolean;

package/dist/index.d.ts

@@ -1,3 +1,3 @@
 import { default as TimePicker } from './TimePicker/TimePicker.vue';
 export { TimePicker };
-export type { TimeFormat, InternalFormat, TimePickerProps, } from './TimePicker/types';
+export type { DisabledTimeInput, TimeFormat, InternalFormat, TimePickerProps, ValidationReason, ValidationState, } from './TimePicker/types';