@ticatec/uniface-element 0.2.0 → 0.2.2

package/docs/form-components/en/time-editor.md

@@ -0,0 +1,159 @@
+# TimeEditor Component
+
+Time input component supporting hour and minute selection.
+
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `variant` | `'' \| 'plain' \| 'outlined' \| 'filled'` | `''` | Appearance variant |
+| `disabled` | `boolean` | `false` | Whether disabled |
+| `readonly` | `boolean` | `false` | Whether read-only |
+| `compact` | `boolean` | `false` | Whether compact mode |
+| `value` | `string` | `''` | Time value (format: HH:MM) |
+| `placeholder` | `string` | `''` | Placeholder text |
+| `displayMode` | `DisplayMode` | `DisplayMode.Edit` | Display mode |
+| `format24h` | `boolean` | `true` | Whether to use 24-hour format |
+| `minuteStep` | `number` | `1` | Minute step |
+| `style` | `string` | `''` | Custom styles |
+| `onChange` | `OnChangeHandler<string>` | - | Value change callback |
+
+## Usage Examples
+
+```svelte
+<script lang="ts">
+  import TimeEditor from '@ticatec/uniface-element/TimeEditor';
+  
+  let startTime: string = '09:00';
+  let endTime: string = '17:30';
+  
+  const handleStartTimeChange = (value: string) => {
+    startTime = value;
+    console.log('Start time:', value);
+  };
+  
+  const handleEndTimeChange = (value: string) => {
+    endTime = value;
+    console.log('End time:', value);
+  };
+</script>
+
+<!-- Start time -->
+<TimeEditor 
+  placeholder="Select start time"
+  bind:value={startTime}
+  onChange={handleStartTimeChange}
+/>
+
+<!-- End time (15-minute intervals) -->
+<TimeEditor 
+  placeholder="Select end time"
+  minuteStep={15}
+  bind:value={endTime}
+  onChange={handleEndTimeChange}
+/>
+```
+
+## Advanced Usage
+
+### Working Hours Setup
+```svelte
+<script lang="ts">
+  interface WorkingHours {
+    start: string;
+    end: string;
+    break_start: string;
+    break_end: string;
+  }
+  
+  let workingHours: WorkingHours = {
+    start: '09:00',
+    end: '18:00',
+    break_start: '12:00',
+    break_end: '13:00'
+  };
+  
+  const updateWorkingHours = (field: keyof WorkingHours) => (value: string) => {
+    workingHours = { ...workingHours, [field]: value };
+  };
+</script>
+
+<div class="working-hours">
+  <div class="time-range">
+    <label>Working Hours:</label>
+    <TimeEditor 
+      placeholder="Start time"
+      minuteStep={30}
+      bind:value={workingHours.start}
+      onChange={updateWorkingHours('start')}
+    />
+    <span>to</span>
+    <TimeEditor 
+      placeholder="End time"
+      minuteStep={30}
+      bind:value={workingHours.end}
+      onChange={updateWorkingHours('end')}
+    />
+  </div>
+  
+  <div class="time-range">
+    <label>Break Time:</label>
+    <TimeEditor 
+      placeholder="Start time"
+      minuteStep={15}
+      bind:value={workingHours.break_start}
+      onChange={updateWorkingHours('break_start')}
+    />
+    <span>to</span>
+    <TimeEditor 
+      placeholder="End time"
+      minuteStep={15}
+      bind:value={workingHours.break_end}
+      onChange={updateWorkingHours('break_end')}
+    />
+  </div>
+</div>
+```
+
+## Best Practices
+
+### 1. Set Appropriate Step Size
+```svelte
+<!-- Meeting time: 15-minute intervals -->
+<TimeEditor minuteStep={15} />
+
+<!-- Work shifts: 30-minute intervals -->
+<TimeEditor minuteStep={30} />
+
+<!-- Precise time: 1-minute intervals -->
+<TimeEditor minuteStep={1} />
+```
+
+### 2. Time Range Validation
+```svelte
+<script lang="ts">
+  let startTime: string = '';
+  let endTime: string = '';
+  let timeError: string = '';
+  
+  const validateTimeRange = (start: string, end: string): void => {
+    if (start && end) {
+      const startMinutes = timeToMinutes(start);
+      const endMinutes = timeToMinutes(end);
+      
+      if (startMinutes >= endMinutes) {
+        timeError = 'End time must be later than start time';
+      } else {
+        timeError = '';
+      }
+    }
+  };
+  
+  const timeToMinutes = (time: string): number => {
+    const [hours, minutes] = time.split(':').map(Number);
+    return hours * 60 + minutes;
+  };
+  
+  $: validateTimeRange(startTime, endTime);
+</script>
+```

package/docs/form-components/en/unit-number-editor.md

@@ -0,0 +1,164 @@
+# UnitNumberEditor Component
+
+Number input component with units, allowing users to select different measurement units.
+
+## Type Definitions
+
+```typescript
+interface UnitOption {
+  code: string;
+  text: string;
+  ratio: number; // Conversion ratio to base unit
+}
+```
+
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `variant` | `'' \| 'plain' \| 'outlined' \| 'filled'` | `''` | Appearance variant |
+| `disabled` | `boolean` | `false` | Whether disabled |
+| `readonly` | `boolean` | `false` | Whether read-only |
+| `compact` | `boolean` | `false` | Whether compact mode |
+| `value` | `number \| null` | `null` | Numeric value |
+| `unit` | `string` | `''` | Currently selected unit code |
+| `units` | `UnitOption[]` | `[]` | Available unit options |
+| `placeholder` | `string` | `''` | Placeholder text |
+| `displayMode` | `DisplayMode` | `DisplayMode.Edit` | Display mode |
+| `precision` | `number \| null` | `null` | Number of decimal places |
+| `style` | `string` | `''` | Custom styles |
+| `onChange` | `OnChangeHandler<{value: number, unit: string}>` | - | Value change callback |
+
+## Usage Examples
+
+```svelte
+<script lang="ts">
+  import UnitNumberEditor, { type UnitOption } from '@ticatec/uniface-element/UnitNumberEditor';
+  
+  // Weight unit options
+  const weightUnits: UnitOption[] = [
+    { code: 'kg', text: 'Kilogram', ratio: 1 },
+    { code: 'g', text: 'Gram', ratio: 0.001 },
+    { code: 'lb', text: 'Pound', ratio: 0.453592 }
+  ];
+  
+  // Distance unit options
+  const distanceUnits: UnitOption[] = [
+    { code: 'm', text: 'Meter', ratio: 1 },
+    { code: 'cm', text: 'Centimeter', ratio: 0.01 },
+    { code: 'km', text: 'Kilometer', ratio: 1000 },
+    { code: 'in', text: 'Inch', ratio: 0.0254 }
+  ];
+  
+  let weight: number | null = null;
+  let weightUnit: string = 'kg';
+  let distance: number | null = null;
+  let distanceUnit: string = 'm';
+  
+  interface UnitValue {
+    value: number;
+    unit: string;
+  }
+  
+  const handleWeightChange = ({value, unit}: UnitValue): void => {
+    weight = value;
+    weightUnit = unit;
+    console.log(`Weight: ${value} ${unit}`);
+  };
+  
+  const handleDistanceChange = ({value, unit}: UnitValue): void => {
+    distance = value;
+    distanceUnit = unit;
+    console.log(`Distance: ${value} ${unit}`);
+  };
+</script>
+
+<!-- Weight input -->
+<UnitNumberEditor 
+  placeholder="Enter weight"
+  units={weightUnits}
+  precision={2}
+  bind:value={weight}
+  bind:unit={weightUnit}
+  onChange={handleWeightChange}
+/>
+
+<!-- Distance input -->
+<UnitNumberEditor 
+  placeholder="Enter distance"
+  units={distanceUnits}
+  precision={2}
+  bind:value={distance}
+  bind:unit={distanceUnit}
+  onChange={handleDistanceChange}
+/>
+```
+
+## Advanced Usage
+
+### Unit Conversion
+```svelte
+<script lang="ts">
+  let inputValue: number | null = null;
+  let inputUnit: string = 'kg';
+  let baseValue: number | null = null; // Base unit value
+  
+  const convertToBase = (value: number, unit: string, units: UnitOption[]): number => {
+    const unitOption = units.find(u => u.code === unit);
+    return value * (unitOption?.ratio || 1);
+  };
+  
+  const handleValueChange = ({value, unit}: UnitValue): void => {
+    inputValue = value;
+    inputUnit = unit;
+    
+    if (value !== null) {
+      baseValue = convertToBase(value, unit, weightUnits);
+      console.log(`Base value: ${baseValue} kg`);
+    } else {
+      baseValue = null;
+    }
+  };
+</script>
+
+<UnitNumberEditor 
+  placeholder="Enter weight"
+  units={weightUnits}
+  precision={3}
+  bind:value={inputValue}
+  bind:unit={inputUnit}
+  onChange={handleValueChange}
+/>
+
+{#if baseValue !== null}
+  <p>Equals: {baseValue.toFixed(3)} kg</p>
+{/if}
+```
+
+## Best Practices
+
+### 1. Set Reasonable Precision
+```svelte
+<!-- Weight: 3 decimal places -->
+<UnitNumberEditor units={weightUnits} precision={3} />
+
+<!-- Distance: 2 decimal places -->
+<UnitNumberEditor units={distanceUnits} precision={2} />
+
+<!-- Temperature: 1 decimal place -->
+<UnitNumberEditor units={temperatureUnits} precision={1} />
+```
+
+### 2. Provide Common Units
+```svelte
+<script lang="ts">
+  // Sorted by usage frequency
+  const lengthUnits: UnitOption[] = [
+    { code: 'm', text: 'Meter', ratio: 1 },      // Most common
+    { code: 'cm', text: 'Centimeter', ratio: 0.01 }, // Common
+    { code: 'mm', text: 'Millimeter', ratio: 0.001 }, // Common
+    { code: 'km', text: 'Kilometer', ratio: 1000 },  // Less common
+    { code: 'in', text: 'Inch', ratio: 0.0254 } // Special needs
+  ];
+</script>
+```