@ticatec/uniface-element 0.2.0 → 0.2.2

package/docs/form-components/en/options-multi-select.md

@@ -0,0 +1,177 @@
+# OptionsMultiSelect Component
+
+Multi-selection dropdown component that allows selecting multiple values from options, displaying them as tags.
+
+## 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` | `''` | Selected values (joined by delimiter) |
+| `delimiter` | `string` | `';'` | Value delimiter |
+| `options` | `Array<any>` | `[]` | Options array |
+| `keyField` | `string` | `'code'` | Value field name |
+| `textField` | `string` | `'text'` | Display field name |
+| `placeholder` | `string` | `''` | Placeholder text |
+| `emptyText` | `string` | `''` | Empty value display text |
+| `disableOptions` | `Array<string>` | `[]` | Disabled option values |
+| `hideOptions` | `Array<string>` | `[]` | Hidden option values |
+| `displayMode` | `DisplayMode` | `DisplayMode.Edit` | Display mode |
+| `menu$height` | `number` | `0` | Dropdown menu height |
+| `tagColor` | `string` | `''` | Tag color |
+| `tagVariant` | `'borderless' \| 'border' \| 'round'` | `'border'` | Tag style |
+| `style` | `string` | `''` | Custom styles |
+| `onChange` | `OnChangeHandler<Array<string>>` | - | Value change callback |
+
+## Usage Examples
+
+```svelte
+<script lang="ts">
+  import OptionsMultiSelect from '@ticatec/uniface-element/OptionsMultiSelect';
+  
+  interface Option {
+    code: string;
+    text: string;
+  }
+  
+  // Skill options
+  const skills: Option[] = [
+    { code: 'js', text: 'JavaScript' },
+    { code: 'ts', text: 'TypeScript' },
+    { code: 'svelte', text: 'Svelte' },
+    { code: 'vue', text: 'Vue.js' },
+    { code: 'react', text: 'React' },
+    { code: 'node', text: 'Node.js' },
+    { code: 'python', text: 'Python' },
+    { code: 'java', text: 'Java' }
+  ];
+  
+  // Hobby options
+  const hobbies: Option[] = [
+    { code: 'reading', text: 'Reading' },
+    { code: 'music', text: 'Music' },
+    { code: 'sports', text: 'Sports' },
+    { code: 'travel', text: 'Travel' },
+    { code: 'photography', text: 'Photography' },
+    { code: 'cooking', text: 'Cooking' }
+  ];
+  
+  let selectedSkills: string = '';
+  let selectedHobbies: string = '';
+  
+  const handleSkillsChange = (values: string[]): void => {
+    console.log('Selected skills:', values);
+  };
+  
+  const handleHobbiesChange = (values: string[]): void => {
+    console.log('Selected hobbies:', values);
+  };
+</script>
+
+<!-- Skills multi-select -->
+<OptionsMultiSelect 
+  placeholder="Please select your skills"
+  options={skills}
+  keyField="code"
+  textField="text"
+  bind:value={selectedSkills}
+  onChange={handleSkillsChange}
+/>
+
+<!-- Hobbies multi-select (round tags) -->
+<OptionsMultiSelect 
+  placeholder="Please select your hobbies"
+  options={hobbies}
+  keyField="code"
+  textField="text"
+  tagVariant="round"
+  tagColor="#007bff"
+  bind:value={selectedHobbies}
+  onChange={handleHobbiesChange}
+/>
+```
+
+## Advanced Usage
+
+### Dynamic Options Management
+```svelte
+<script lang="ts">
+  interface Category {
+    id: string;
+    name: string;
+    parent_id: string | null;
+  }
+  
+  let selectedCategories: string = '';
+  let availableCategories: Category[] = [];
+  let userLevel: 'basic' | 'premium' | 'admin' = 'basic';
+  
+  // Filter available categories based on user level
+  $: filteredCategories = availableCategories.filter(cat => {
+    if (userLevel === 'basic') {
+      return cat.parent_id === null; // Only show top-level categories
+    } else if (userLevel === 'premium') {
+      return true; // Show all categories
+    } else {
+      return true; // Admin sees all categories
+    }
+  });
+  
+  // Set disabled options based on user level
+  $: disabledOptions = userLevel === 'basic' 
+    ? availableCategories.filter(cat => cat.parent_id !== null).map(cat => cat.id)
+    : [];
+</script>
+
+<OptionsMultiSelect 
+  placeholder="Please select categories"
+  options={filteredCategories}
+  keyField="id"
+  textField="name"
+  {disabledOptions}
+  bind:value={selectedCategories}
+/>
+```
+
+## Best Practices
+
+### 1. Limit Selection Count
+```svelte
+<script lang="ts">
+  let selectedTags: string = '';
+  let maxTags: number = 5;
+  let tagError: string = '';
+  
+  const handleTagsChange = (values: string[]): void => {
+    if (values.length > maxTags) {
+      tagError = `Maximum ${maxTags} tags allowed`;
+      // Keep only first maxTags items
+      selectedTags = values.slice(0, maxTags).join(';');
+    } else {
+      tagError = '';
+    }
+  };
+</script>
+
+<OptionsMultiSelect 
+  options={tagOptions}
+  bind:value={selectedTags}
+  onChange={handleTagsChange}
+/>
+{#if tagError}
+  <div class="error-message">{tagError}</div>
+{/if}
+```
+
+### 2. Custom Tag Styling
+```svelte
+<OptionsMultiSelect 
+  options={colorOptions}
+  tagVariant="round"
+  tagColor="var(--primary-color)"
+  bind:value={selectedColors}
+/>
+```

package/docs/form-components/en/options-select.md

@@ -0,0 +1,83 @@
+# OptionsSelect Component
+
+Single-selection dropdown component for selecting one value from predefined options.
+
+## 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` | `any` | `null` | Selected value |
+| `options` | `Array<any>` | `[]` | Options array |
+| `keyField` | `string` | `'code'` | Value field name |
+| `textField` | `string` | `'text'` | Display field name |
+| `placeholder` | `string` | `''` | Placeholder text |
+| `emptyText` | `string` | `''` | Empty value display text |
+| `disableOptions` | `Array<string>` | `[]` | Disabled option values |
+| `hideOptions` | `Array<string>` | `[]` | Hidden option values |
+| `displayMode` | `DisplayMode` | `DisplayMode.Edit` | Display mode |
+| `menu$height` | `number` | `0` | Dropdown menu height |
+| `style` | `string` | `''` | Custom styles |
+| `onChange` | `OnChangeHandler<any>` | - | Value change callback |
+
+## Usage Examples
+
+```svelte
+<script lang="ts">
+  import OptionsSelect from '@ticatec/uniface-element/OptionsSelect';
+  
+  // Country options
+  const countries = [
+    { code: 'US', text: 'United States' },
+    { code: 'GB', text: 'United Kingdom' },
+    { code: 'CA', text: 'Canada' },
+    { code: 'AU', text: 'Australia' },
+    { code: 'DE', text: 'Germany' }
+  ];
+  
+  // Status options
+  const statuses = [
+    { code: 'active', text: 'Active' },
+    { code: 'inactive', text: 'Inactive' },
+    { code: 'pending', text: 'Pending' },
+    { code: 'suspended', text: 'Suspended' }
+  ];
+  
+  let selectedCountry = '';
+  let userStatus = 'active';
+  
+  const handleCountryChange = (value: string) => {
+    selectedCountry = value;
+    console.log('Selected country:', value);
+  };
+  
+  const handleStatusChange = (value: string) => {
+    userStatus = value;
+    console.log('User status:', value);
+  };
+</script>
+
+<!-- Country selection -->
+<OptionsSelect 
+  placeholder="Please select country"
+  options={countries}
+  keyField="code"
+  textField="text"
+  bind:value={selectedCountry}
+  onChange={handleCountryChange}
+/>
+
+<!-- User status selection (with disabled options) -->
+<OptionsSelect 
+  placeholder="Please select status"
+  options={statuses}
+  keyField="code"
+  textField="text"
+  disableOptions={['suspended']}
+  bind:value={userStatus}
+  onChange={handleStatusChange}
+/>
+```