@htlkg/components 0.0.1

package/src/forms/DateRange.demo.vue

@@ -0,0 +1,273 @@
+<template>
+  <div class="space-y-8">
+    <div>
+      <h2 class="text-2xl font-bold mb-4">DateRange Component Demo</h2>
+      <p class="text-gray-600 mb-6">
+        A date range selector with start/end dates and search button.
+      </p>
+    </div>
+
+    <!-- Basic Example -->
+    <div class="border rounded-lg p-6">
+      <h3 class="text-lg font-semibold mb-4">Basic Usage</h3>
+      <DateRange
+        v-model="basicRange"
+        label="Select date range"
+        @search="handleBasicSearch"
+      />
+      <div class="mt-4 p-4 bg-gray-50 rounded">
+        <p class="text-sm font-medium mb-2">Current v-model value:</p>
+        <pre class="text-xs bg-white p-2 rounded border">{{ JSON.stringify(basicRange, null, 2) }}</pre>
+      </div>
+      <div v-if="basicResult" class="mt-4 p-4 bg-blue-50 rounded">
+        <p class="text-sm font-medium mb-2">Search clicked with:</p>
+        <pre class="text-xs bg-white p-2 rounded border">{{ JSON.stringify(basicResult, null, 2) }}</pre>
+      </div>
+    </div>
+
+    <!-- Custom Literals -->
+    <div class="border rounded-lg p-6">
+      <h3 class="text-lg font-semibold mb-4">Custom Literals</h3>
+      <DateRange
+        v-model="customRange"
+        :literals="customLiterals"
+        label="Report Period"
+        @search="handleCustomSearch"
+      />
+      <div class="mt-4 p-4 bg-gray-50 rounded">
+        <p class="text-sm font-medium mb-2">Current v-model value:</p>
+        <pre class="text-xs bg-white p-2 rounded border">{{ JSON.stringify(customRange, null, 2) }}</pre>
+      </div>
+      <div v-if="customResult" class="mt-4 p-4 bg-green-50 rounded">
+        <p class="text-sm font-medium mb-2">Report generated for:</p>
+        <pre class="text-xs bg-white p-2 rounded border">{{ JSON.stringify(customResult, null, 2) }}</pre>
+      </div>
+    </div>
+
+    <!-- With Validation -->
+    <div class="border rounded-lg p-6">
+      <h3 class="text-lg font-semibold mb-4">With Validation</h3>
+      <DateRange
+        ref="validationRef"
+        v-model="validationRange"
+        :error="validationError"
+        :color="validationError ? 'red' : undefined"
+        label="Booking Dates"
+        @search="handleValidation"
+      />
+      <div class="mt-4 p-4 bg-gray-50 rounded">
+        <p class="text-sm font-medium mb-2">Current v-model value:</p>
+        <pre class="text-xs bg-white p-2 rounded border">{{ JSON.stringify(validationRange, null, 2) }}</pre>
+        <p v-if="validationError" class="text-sm text-red-600 mt-2 font-medium">
+          Error: {{ validationError }}
+        </p>
+      </div>
+      <button
+        @click="resetValidation"
+        class="mt-4 px-4 py-2 bg-gray-200 rounded hover:bg-gray-300"
+      >
+        Reset
+      </button>
+    </div>
+
+    <!-- Loading State -->
+    <div class="border rounded-lg p-6">
+      <h3 class="text-lg font-semibold mb-4">Loading State</h3>
+      <DateRange
+        v-model="loadingRange"
+        :loading="isLoading"
+        label="Loading example"
+        @search="handleLoadingSearch"
+      />
+      <div class="mt-4 p-4 bg-gray-50 rounded">
+        <p class="text-sm font-medium mb-2">Current v-model value:</p>
+        <pre class="text-xs bg-white p-2 rounded border">{{ JSON.stringify(loadingRange, null, 2) }}</pre>
+        <p class="text-sm mt-2">Loading state: <span class="font-mono">{{ isLoading }}</span></p>
+      </div>
+      <button
+        @click="toggleLoading"
+        class="mt-4 px-4 py-2 bg-blue-500 text-white rounded hover:bg-blue-600"
+      >
+        {{ isLoading ? 'Stop Loading' : 'Start Loading' }}
+      </button>
+    </div>
+
+    <!-- Disabled State -->
+    <div class="border rounded-lg p-6">
+      <h3 class="text-lg font-semibold mb-4">Disabled State</h3>
+      <DateRange
+        v-model="disabledRange"
+        :disabled="isDisabled"
+        label="Disabled example"
+      />
+      <div class="mt-4 p-4 bg-gray-50 rounded">
+        <p class="text-sm font-medium mb-2">Current v-model value:</p>
+        <pre class="text-xs bg-white p-2 rounded border">{{ JSON.stringify(disabledRange, null, 2) }}</pre>
+        <p class="text-sm mt-2">Disabled state: <span class="font-mono">{{ isDisabled }}</span></p>
+      </div>
+      <button
+        @click="isDisabled = !isDisabled"
+        class="mt-4 px-4 py-2 bg-gray-500 text-white rounded hover:bg-gray-600"
+      >
+        {{ isDisabled ? 'Enable' : 'Disable' }}
+      </button>
+    </div>
+
+    <!-- Programmatic Control -->
+    <div class="border rounded-lg p-6">
+      <h3 class="text-lg font-semibold mb-4">Programmatic Control</h3>
+      <DateRange
+        ref="programmaticRef"
+        v-model="programmaticRange"
+        label="Controlled example"
+      />
+      <div class="mt-4 p-4 bg-gray-50 rounded">
+        <p class="text-sm font-medium mb-2">Current v-model value:</p>
+        <pre class="text-xs bg-white p-2 rounded border">{{ JSON.stringify(programmaticRange, null, 2) }}</pre>
+      </div>
+      <div class="mt-4 space-x-2">
+        <button
+          @click="setLastWeek"
+          class="px-4 py-2 bg-purple-500 text-white rounded hover:bg-purple-600"
+        >
+          Last Week
+        </button>
+        <button
+          @click="setLastMonth"
+          class="px-4 py-2 bg-purple-500 text-white rounded hover:bg-purple-600"
+        >
+          Last Month
+        </button>
+        <button
+          @click="resetProgrammatic"
+          class="px-4 py-2 bg-gray-500 text-white rounded hover:bg-gray-600"
+        >
+          Reset
+        </button>
+      </div>
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import { DateRange } from '@htlkg/components';
+import type { DateRangeValue } from '@htlkg/components';
+
+// Basic example
+const basicRange = ref<DateRangeValue>({
+  from: '',
+  to: new Date().toISOString().slice(0, 16)
+});
+const basicResult = ref<DateRangeValue | null>(null);
+
+function handleBasicSearch(dates: DateRangeValue | undefined) {
+  basicResult.value = dates || null;
+}
+
+// Custom literals
+const customLiterals = {
+  from: 'Start Date',
+  to: 'End Date',
+  search: 'Generate Report'
+};
+const customRange = ref<DateRangeValue>({
+  from: '',
+  to: new Date().toISOString().slice(0, 16)
+});
+const customResult = ref<DateRangeValue | null>(null);
+
+function handleCustomSearch(dates: DateRangeValue | undefined) {
+  customResult.value = dates || null;
+}
+
+// Validation example
+const validationRef = ref<InstanceType<typeof DateRange>>();
+const validationRange = ref<DateRangeValue>({
+  from: '',
+  to: ''
+});
+const validationError = ref('');
+
+function handleValidation(dates: DateRangeValue | undefined) {
+  if (!dates || !dates.from || !dates.to) {
+    validationError.value = 'Both dates are required';
+    return;
+  }
+
+  const fromDate = new Date(dates.from);
+  const toDate = new Date(dates.to);
+
+  if (fromDate > toDate) {
+    validationError.value = 'Start date must be before end date';
+    return;
+  }
+
+  const diffDays = Math.ceil((toDate.getTime() - fromDate.getTime()) / (1000 * 60 * 60 * 24));
+  if (diffDays > 365) {
+    validationError.value = 'Maximum range is 1 year';
+    return;
+  }
+
+  validationError.value = '';
+  alert(`Valid range: ${dates.from} to ${dates.to}`);
+}
+
+function resetValidation() {
+  validationRef.value?.reset();
+  validationError.value = '';
+}
+
+// Loading example
+const isLoading = ref(false);
+const loadingRange = ref<DateRangeValue>({
+  from: '',
+  to: new Date().toISOString().slice(0, 16)
+});
+
+function toggleLoading() {
+  isLoading.value = !isLoading.value;
+}
+
+function handleLoadingSearch(dates: DateRangeValue | undefined) {
+  if (dates) {
+    alert(`Searching from ${dates.from} to ${dates.to}`);
+  }
+}
+
+// Disabled example
+const isDisabled = ref(true);
+const disabledRange = ref<DateRangeValue>({
+  from: new Date(Date.now() - 7 * 24 * 60 * 60 * 1000).toISOString().slice(0, 16),
+  to: new Date().toISOString().slice(0, 16)
+});
+
+// Programmatic control
+const programmaticRef = ref<InstanceType<typeof DateRange>>();
+const programmaticRange = ref<DateRangeValue>({
+  from: '',
+  to: new Date().toISOString().slice(0, 16)
+});
+
+function setLastWeek() {
+  const to = new Date();
+  const from = new Date(Date.now() - 7 * 24 * 60 * 60 * 1000);
+  programmaticRef.value?.setValue({
+    from: from.toISOString().slice(0, 16),
+    to: to.toISOString().slice(0, 16)
+  });
+}
+
+function setLastMonth() {
+  const to = new Date();
+  const from = new Date(Date.now() - 30 * 24 * 60 * 60 * 1000);
+  programmaticRef.value?.setValue({
+    from: from.toISOString().slice(0, 16),
+    to: to.toISOString().slice(0, 16)
+  });
+}
+
+function resetProgrammatic() {
+  programmaticRef.value?.reset();
+}
+</script>

package/src/forms/DateRange.md

@@ -0,0 +1,337 @@
+# DateRange Component
+
+A date range selector component that allows users to choose a start and end date with a search button. Built on top of `uiDateRange` from `@hotelinking/ui`.
+
+## Features
+
+- **Dual date inputs**: Separate inputs for start and end dates using `datetime-local` type
+- **Visual addons**: "From" and "To" labels appear as addons in the inputs
+- **Search button**: Dedicated button to trigger the search action
+- **v-model support**: Two-way binding for the date range value
+- **Validation states**: Support for error messages and color states
+- **Loading state**: Shows skeleton loaders while data is loading
+- **Disabled state**: Can disable all inputs and button
+- **Responsive**: Adapts between horizontal (desktop) and vertical (mobile) layouts
+- **Customizable literals**: All text labels are configurable
+- **Max date constraint**: Both inputs have max set to current date/time
+- **Exposed methods**: Programmatic control via `reset()`, `getValue()`, `setValue()`
+
+## Import
+
+```typescript
+import { DateRange } from '@htlkg/components';
+import type { DateRangeValue, DateRangeLiterals } from '@htlkg/components';
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `id` | `string` | auto-generated | Unique identifier for the component |
+| `modelValue` | `DateRangeValue` | `{ from: '', to: now }` | Current date range value |
+| `literals` | `DateRangeLiterals` | `{ from: 'From', to: 'To', search: 'Search' }` | Text labels for the component |
+| `loading` | `boolean` | `false` | Shows skeleton loaders when true |
+| `color` | `string` | `undefined` | Color for validation states (green, red, yellow, etc.) |
+| `error` | `string` | `undefined` | Error message to display below inputs |
+| `disabled` | `boolean` | `false` | Disables all inputs and button |
+| `label` | `string` | `undefined` | Label text above the first input |
+| `placeholder` | `string` | `undefined` | Placeholder text for inputs |
+
+### Type Definitions
+
+```typescript
+interface DateRangeValue {
+  from: Date | string;
+  to: Date | string;
+}
+
+interface DateRangeLiterals {
+  from: string;
+  to: string;
+  search: string;
+}
+```
+
+## Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `update:modelValue` | `DateRangeValue \| undefined` | Emitted when search button is clicked (v-model support) |
+| `search` | `DateRangeValue \| undefined` | Emitted when search button is clicked |
+| `change` | `DateRangeValue \| undefined` | Emitted when search button is clicked |
+
+## Exposed Methods
+
+| Method | Parameters | Returns | Description |
+|--------|------------|---------|-------------|
+| `reset()` | - | `void` | Resets the date range to default values |
+| `getValue()` | - | `DateRangeValue` | Returns the current date range value |
+| `setValue(value)` | `DateRangeValue` | `void` | Sets the date range value programmatically |
+
+## Usage Examples
+
+### Basic Usage
+
+```vue
+<template>
+  <DateRange
+    v-model="dateRange"
+    label="Select date range"
+    @search="handleSearch"
+  />
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import { DateRange } from '@htlkg/components';
+import type { DateRangeValue } from '@htlkg/components';
+
+const dateRange = ref<DateRangeValue>({
+  from: '',
+  to: new Date().toISOString().slice(0, 16)
+});
+
+function handleSearch(dates: DateRangeValue | undefined) {
+  if (dates) {
+    console.log('Search from:', dates.from, 'to:', dates.to);
+    // Perform search with date range
+  }
+}
+</script>
+```
+
+### Report Filter
+
+```vue
+<template>
+  <DateRange
+    v-model="reportDates"
+    :literals="literals"
+    :loading="loading"
+    :error="error"
+    :color="error ? 'red' : undefined"
+    label="Report period"
+    @search="generateReport"
+  />
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import { DateRange } from '@htlkg/components';
+import type { DateRangeValue } from '@htlkg/components';
+
+const loading = ref(false);
+const error = ref('');
+
+const literals = {
+  from: 'Start date',
+  to: 'End date',
+  search: 'Generate Report'
+};
+
+const reportDates = ref<DateRangeValue>({
+  from: new Date(Date.now() - 30 * 24 * 60 * 60 * 1000).toISOString().slice(0, 16),
+  to: new Date().toISOString().slice(0, 16)
+});
+
+async function generateReport(dates: DateRangeValue | undefined) {
+  if (!dates) return;
+  
+  // Validate date range
+  const from = new Date(dates.from);
+  const to = new Date(dates.to);
+  const diffDays = Math.ceil((to.getTime() - from.getTime()) / (1000 * 60 * 60 * 24));
+  
+  if (diffDays > 365) {
+    error.value = 'Maximum range is 1 year';
+    return;
+  }
+  
+  error.value = '';
+  loading.value = true;
+  
+  try {
+    // await fetchReport(dates.from, dates.to);
+    console.log('Generating report...');
+  } finally {
+    loading.value = false;
+  }
+}
+</script>
+```
+
+### With Validation
+
+```vue
+<template>
+  <DateRange
+    ref="dateRangeRef"
+    v-model="dates"
+    :error="errorMessage"
+    :color="errorMessage ? 'red' : 'green'"
+    label="Booking dates"
+    @search="validateAndSearch"
+  />
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import { DateRange } from '@htlkg/components';
+import type { DateRangeValue } from '@htlkg/components';
+
+const dateRangeRef = ref<InstanceType<typeof DateRange>>();
+const errorMessage = ref('');
+
+const dates = ref<DateRangeValue>({
+  from: '',
+  to: ''
+});
+
+function validateAndSearch(dates: DateRangeValue | undefined) {
+  if (!dates || !dates.from || !dates.to) {
+    errorMessage.value = 'Both dates are required';
+    return;
+  }
+  
+  const fromDate = new Date(dates.from);
+  const toDate = new Date(dates.to);
+  
+  if (fromDate > toDate) {
+    errorMessage.value = 'Start date must be before end date';
+    return;
+  }
+  
+  errorMessage.value = '';
+  // Proceed with search
+  console.log('Valid date range:', dates);
+}
+
+// Programmatic control
+function resetDates() {
+  dateRangeRef.value?.reset();
+  errorMessage.value = '';
+}
+</script>
+```
+
+### Custom Literals (Internationalization)
+
+```vue
+<template>
+  <DateRange
+    v-model="dateRange"
+    :literals="spanishLiterals"
+    label="Rango de fechas"
+    @search="handleSearch"
+  />
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import { DateRange } from '@htlkg/components';
+import type { DateRangeValue } from '@htlkg/components';
+
+const spanishLiterals = {
+  from: 'Desde',
+  to: 'Hasta',
+  search: 'Buscar'
+};
+
+const dateRange = ref<DateRangeValue>({
+  from: '',
+  to: new Date().toISOString().slice(0, 16)
+});
+
+function handleSearch(dates: DateRangeValue | undefined) {
+  console.log('Búsqueda:', dates);
+}
+</script>
+```
+
+### Disabled State
+
+```vue
+<template>
+  <DateRange
+    v-model="dateRange"
+    :disabled="isProcessing"
+    label="Date range"
+    @search="handleSearch"
+  />
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import { DateRange } from '@htlkg/components';
+
+const isProcessing = ref(false);
+const dateRange = ref({
+  from: '',
+  to: new Date().toISOString().slice(0, 16)
+});
+
+async function handleSearch(dates) {
+  isProcessing.value = true;
+  try {
+    // Process search
+  } finally {
+    isProcessing.value = false;
+  }
+}
+</script>
+```
+
+## TypeScript Support
+
+The component is fully typed with TypeScript:
+
+```typescript
+import { DateRange } from '@htlkg/components';
+import type { DateRangeValue, DateRangeLiterals } from '@htlkg/components';
+
+// Type-safe date range
+const dateRange = ref<DateRangeValue>({
+  from: '2024-01-01T00:00',
+  to: '2024-12-31T23:59'
+});
+
+// Type-safe literals
+const literals: DateRangeLiterals = {
+  from: 'Start',
+  to: 'End',
+  search: 'Apply'
+};
+
+// Type-safe ref
+const dateRangeRef = ref<InstanceType<typeof DateRange>>();
+dateRangeRef.value?.reset();
+```
+
+## Best Practices
+
+1. **Always validate date ranges**: Check that start date is before end date
+2. **Set reasonable limits**: Consider adding maximum range validation (e.g., 1 year)
+3. **Provide clear error messages**: Use the `error` prop to guide users
+4. **Use appropriate literals**: Customize text based on context (e.g., "Check-in" / "Check-out")
+5. **Handle empty values**: Check for undefined or empty dates before processing
+6. **Consider time zones**: Be aware that datetime-local uses local time
+7. **Provide default values**: Set sensible defaults (e.g., last 7 days)
+8. **Use loading state**: Show loading while fetching data based on date range
+
+## Accessibility
+
+- Uses native `datetime-local` inputs for better accessibility
+- Proper label association with inputs
+- Keyboard navigation support
+- Screen reader friendly
+- Error messages are properly announced
+
+## Demo
+
+See the component in action at `/demo/components/date-range`
+
+## Related Components
+
+- [JsonSchemaForm](./JsonSchemaForm.md) - For complex forms with date fields
+- [Table](../data/Table.md) - Often used with date range filters
+- [Chart](../data/Chart.md) - Commonly filtered by date ranges