@ticatec/uniface-element 0.3.17 → 0.3.19

package/dist/navigator/README.md

@@ -0,0 +1,377 @@
+# Navigator
+
+A step/wizard navigation component that guides users through a multi-step process. Visualizes progress and allows users to navigate between steps with clear status indicators.
+
+## Features
+
+- **Step Visualization**: Visual representation of wizard steps
+- **Status Indicators**: Completed, Warning, and Not Started states
+- **Active Tracking**: Highlights the current active step
+- **Item Highlighting**: Highlight specific items for attention
+- **Click Navigation**: Click to navigate between steps
+- **Custom Styling**: Flexible styling options
+- **Dynamic Items**: Support for dynamic step lists
+
+## Installation
+
+```bash
+npm install @ticatec/uniface-element
+```
+
+```typescript
+import Navigator, { NavItemStatus } from '@ticatec/uniface-element/Navigator';
+```
+
+## Basic Usage
+
+```svelte
+<script>
+  import Navigator, { NavItemStatus } from '@ticatec/uniface-element/Navigator';
+
+  let activeItem = 0;
+  let items = [
+    { text: 'Step 1' },
+    { text: 'Step 2' },
+    { text: 'Step 3' },
+    { text: 'Step 4' }
+  ];
+
+  function getStatus(item) {
+    const index = items.indexOf(item);
+    if (index < activeItem) return NavItemStatus.Completed;
+    if (index === activeItem) return NavItemStatus.Completed;
+    return NavItemStatus.NotStart;
+  }
+
+  function handleClick(item) {
+    activeItem = items.indexOf(item);
+    console.log('Navigated to:', item.text);
+  }
+</script>
+
+<Navigator
+  {items}
+  activeItem={items[activeItem]}
+  retrieveStatus={getStatus}
+  itemClickHandler={handleClick}
+/>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `items` | `Array<any>` | Required | Array of navigation items (must have `text` property) |
+| `activeItem` | `any` | `null` | Currently active item |
+| `highlights` | `Array<any>` | `[]` | Items to highlight for attention |
+| `itemClickHandler` | `(item: any) => void` | Required | Callback when item is clicked |
+| `retrieveStatus` | `(item: any) => NavItemStatus` | Required | Function to get item status |
+| `style` | `string` | `''` | Custom CSS styles |
+
+## NavItemStatus Enum
+
+| Status | Value | Description |
+|--------|-------|-------------|
+| `NavItemStatus.Completed` | `'nav-completed'` | Step is completed |
+| `NavItemStatus.Warning` | `'nav-warning'` | Step has warnings |
+| `NavItemStatus.NotStart` | `'nav-not-start'` | Step not started |
+
+## Examples
+
+### Basic Wizard Navigation
+
+```svelte
+<script>
+  import Navigator, { NavItemStatus } from '@ticatec/uniface-element/Navigator';
+
+  let currentStep = 0;
+
+  const steps = [
+    { text: 'Personal Info' },
+    { text: 'Contact Details' },
+    { text: 'Preferences' },
+    { text: 'Review' }
+  ];
+
+  function getStepStatus(step) {
+    const index = steps.indexOf(step);
+    if (index < currentStep) return NavItemStatus.Completed;
+    if (index === currentStep) return NavItemStatus.Completed;
+    return NavItemStatus.NotStart;
+  }
+
+  function handleStepClick(step) {
+    const index = steps.indexOf(step);
+    if (index <= currentStep) {
+      currentStep = index;
+    }
+  }
+
+  function nextStep() {
+    if (currentStep < steps.length - 1) {
+      currentStep++;
+    }
+  }
+
+  function prevStep() {
+    if (currentStep > 0) {
+      currentStep--;
+    }
+  }
+</script>
+
+<Navigator
+  items={steps}
+  activeItem={steps[currentStep]}
+  retrieveStatus={getStepStatus}
+  itemClickHandler={handleStepClick}
+/>
+
+<div style="margin-top: 32px; padding: 24px; border: 1px solid #ddd;">
+  <h2>{steps[currentStep].text}</h2>
+  <p>Content for step {currentStep + 1}</p>
+
+  <div style="margin-top: 16px; display: flex; gap: 8px;">
+    <button disabled={currentStep === 0} on:click={prevStep}>Previous</button>
+    <button disabled={currentStep === steps.length - 1} on:click={nextStep}>Next</button>
+  </div>
+</div>
+```
+
+### With Warning Status
+
+```svelte
+<script>
+  import Navigator, { NavItemStatus } from '@ticatec/uniface-element/Navigator';
+
+  let currentStep = 2;
+  const warningSteps = [1];
+
+  const steps = [
+    { text: 'Account' },
+    { text: 'Profile' },
+    { text: 'Settings' },
+    { text: 'Confirm' }
+  ];
+
+  function getStepStatus(step) {
+    const index = steps.indexOf(step);
+    if (warningSteps.includes(index)) return NavItemStatus.Warning;
+    if (index <= currentStep) return NavItemStatus.Completed;
+    return NavItemStatus.NotStart;
+  }
+
+  function handleStepClick(step) {
+    const index = steps.indexOf(step);
+    if (index <= currentStep) {
+      currentStep = index;
+    }
+  }
+</script>
+
+<Navigator
+  items={steps}
+  activeItem={steps[currentStep]}
+  retrieveStatus={getStepStatus}
+  itemClickHandler={handleStepClick}
+/>
+```
+
+### With Highlights
+
+```svelte
+<script>
+  import Navigator, { NavItemStatus } from '@ticatec/uniface-element/Navigator';
+
+  let currentStep = 1;
+  let highlightedSteps = [2, 3];
+
+  const steps = [
+    { text: 'Upload' },
+    { text: 'Process' },
+    { text: 'Verify' },
+    { text: 'Complete' }
+  ];
+
+  function getStepStatus(step) {
+    const index = steps.indexOf(step);
+    if (index < currentStep) return NavItemStatus.Completed;
+    if (index === currentStep) return NavItemStatus.Completed;
+    return NavItemStatus.NotStart;
+  }
+
+  function handleStepClick(step) {
+    const index = steps.indexOf(step);
+    if (index <= currentStep) {
+      currentStep = index;
+    }
+  }
+</script>
+
+<Navigator
+  items={steps}
+  activeItem={steps[currentStep]}
+  highlights={highlightedSteps.map(i => steps[i])}
+  retrieveStatus={getStepStatus}
+  itemClickHandler={handleStepClick}
+/>
+```
+
+### Custom Styling
+
+```svelte
+<script>
+  import Navigator, { NavItemStatus } from '@ticatec/uniface-element/Navigator';
+
+  const steps = [
+    { text: '①' },
+    { text: '②' },
+    { text: '③' },
+    { text: '④' }
+  ];
+
+  function getStepStatus(step) {
+    return NavItemStatus.NotStart;
+  }
+
+  function handleStepClick(step) {
+    console.log('Clicked:', step.text);
+  }
+</script>
+
+<Navigator
+  items={steps}
+  activeItem={steps[0]}
+  retrieveStatus={getStepStatus}
+  itemClickHandler={handleStepClick}
+  style="background: #f5f5f5; padding: 16px; border-radius: 8px;"
+/>
+```
+
+### Complete Form Wizard
+
+```svelte
+<script>
+  import Navigator, { NavItemStatus } from '@ticatec/uniface-element/Navigator';
+  import Button from '@ticatec/uniface-element/Button';
+
+  let currentStep = 0;
+  let formData = {
+    name: '',
+    email: '',
+    phone: '',
+    address: ''
+  };
+
+  const wizardSteps = [
+    { text: 'Personal' },
+    { text: 'Contact' },
+    { text: 'Location' },
+    { text: 'Review' }
+  ];
+
+  function getStepStatus(step) {
+    const index = wizardSteps.indexOf(step);
+    if (index < currentStep) return NavItemStatus.Completed;
+    if (index === currentStep) return NavItemStatus.Completed;
+    return NavItemStatus.NotStart;
+  }
+
+  function handleStepClick(step) {
+    const index = wizardSteps.indexOf(step);
+    if (index <= currentStep) {
+      currentStep = index;
+    }
+  }
+
+  function canProceed() {
+    switch(currentStep) {
+      case 0: return formData.name.length > 0;
+      case 1: return formData.email.length > 0;
+      case 2: return formData.address.length > 0;
+      default: return true;
+    }
+  }
+</script>
+
+<div style="max-width: 800px; margin: 0 auto; padding: 24px;">
+  <Navigator
+    items={wizardSteps}
+    activeItem={wizardSteps[currentStep]}
+    retrieveStatus={getStepStatus}
+    itemClickHandler={handleStepClick}
+  />
+
+  <div style="margin-top: 32px; padding: 24px; border: 1px solid #ddd; border-radius: 8px;">
+    {#if currentStep === 0}
+      <h2>Personal Information</h2>
+      <label>
+        Full Name:
+        <input type="text" bind:value={formData.name} placeholder="Enter your name" />
+      </label>
+    {:else if currentStep === 1}
+      <h2>Contact Information</h2>
+      <label>
+        Email:
+        <input type="email" bind:value={formData.email} placeholder="your@email.com" />
+      </label>
+    {:else if currentStep === 2}
+      <h2>Location</h2>
+      <label>
+        Address:
+        <input type="text" bind:value={formData.address} placeholder="Your address" />
+      </label>
+    {:else}
+      <h2>Review Your Information</h2>
+      <pre>{JSON.stringify(formData, null, 2)}</pre>
+    {/if}
+
+    <div style="margin-top: 24px; display: flex; justify-content: space-between;">
+      <Button
+        disabled={currentStep === 0}
+        onclick={() => currentStep--}
+      >
+        Previous
+      </Button>
+
+      {#if currentStep < wizardSteps.length - 1}
+        <Button
+          type="primary"
+          disabled={!canProceed()}
+          onclick={() => currentStep++}
+        >
+          Next
+        </Button>
+      {:else}
+        <Button type="primary" onclick={() => console.log('Submit:', formData)}>
+          Submit
+        </Button>
+      {/if}
+    </div>
+  </div>
+</div>
+```
+
+## Best Practices
+
+1. **Clear Steps**: Use concise, descriptive text for each step
+2. **Status Logic**: Implement clear status logic based on your workflow
+3. **Navigation Control**: Control which steps are clickable based on progress
+4. **Visual Feedback**: Use warnings to indicate issues or attention needed
+5. **Validation**: Prevent proceeding if current step is incomplete
+6. **Progress Indication**: Make it clear which step is active
+
+## Use Cases
+
+- **Multi-step Forms**: Break complex forms into manageable steps
+- **Wizards**: Guide users through complex processes
+- **Onboarding**: Step-by-step user onboarding flows
+- **Checkouts**: E-commerce checkout processes
+- **Configuration**: Multi-stage configuration workflows
+
+## Accessibility
+
+- Keyboard navigation support
+- Clear visual indicators for current step
+- Semantic HTML structure
+- ARIA attributes for screen readers