@kubex/zinc 1.0.25 → 1.0.99

package/docs/pages/components/stepper.md

@@ -1,20 +1,577 @@
 ---
 meta:
   title: Stepper
-  description:
+  description: Steppers provide visual feedback about progress through a multi-step process or workflow, showing current position and total steps.
 layout: component
 ---
 
 ```html:preview
-<zn-stepper caption="Caption here" label="Label here" steps="3" value="2" show-progress></zn-stepper>
+<zn-stepper caption="Setup Progress" label="Installation Wizard" steps="5" value="3" show-progress></zn-stepper>
 ```
 
 ## Examples
 
-### First Example
+### Basic Stepper
 
-TODO
+A basic stepper displays progress through a sequence of steps. Use the `steps` attribute to define the total number of steps and `value` to indicate the current step position.
 
-### Second Example
+```html:preview
+<zn-stepper steps="4" value="2"></zn-stepper>
+```
+
+### With Caption
+
+Use the `caption` attribute to add a descriptive label above the stepper. This helps users understand what process or workflow the stepper represents.
+
+```html:preview
+<zn-stepper caption="Account Setup" steps="5" value="2"></zn-stepper>
+<br />
+<zn-stepper caption="Order Processing" steps="6" value="4"></zn-stepper>
+<br />
+<zn-stepper caption="Project Onboarding" steps="3" value="1"></zn-stepper>
+```
+
+### With Label
+
+Use the `label` attribute to display information above the caption. This is useful for showing the wizard or workflow name.
+
+```html:preview
+<zn-stepper label="New User Registration" caption="Personal Information" steps="5" value="1"></zn-stepper>
+<br />
+<zn-stepper label="Checkout Process" caption="Shipping Details" steps="4" value="2"></zn-stepper>
+```
+
+### Showing Progress Count
+
+Use the `show-progress` attribute to display the current step number alongside the total number of steps (e.g., "2 / 5 steps").
+
+```html:preview
+<zn-stepper caption="Installation" steps="5" value="2" show-progress></zn-stepper>
+<br />
+<zn-stepper caption="Data Import" steps="10" value="7" show-progress></zn-stepper>
+<br />
+<zn-stepper caption="Configuration" steps="3" value="3" show-progress></zn-stepper>
+```
+
+### Complete Progress States
+
+Examples showing different stages of a workflow, from start to completion.
+
+```html:preview
+<zn-stepper
+  label="Project Setup Wizard"
+  caption="Getting Started"
+  steps="5"
+  value="0"
+  show-progress>
+</zn-stepper>
+<br />
+<zn-stepper
+  label="Project Setup Wizard"
+  caption="Configure Settings"
+  steps="5"
+  value="2"
+  show-progress>
+</zn-stepper>
+<br />
+<zn-stepper
+  label="Project Setup Wizard"
+  caption="Review & Deploy"
+  steps="5"
+  value="4"
+  show-progress>
+</zn-stepper>
+<br />
+<zn-stepper
+  label="Project Setup Wizard"
+  caption="Complete!"
+  steps="5"
+  value="5"
+  show-progress>
+</zn-stepper>
+```
+
+### All Properties Combined
+
+A comprehensive example showing all available properties working together.
+
+```html:preview
+<zn-stepper
+  label="E-commerce Checkout"
+  caption="Payment Information"
+  steps="4"
+  value="3"
+  show-progress>
+</zn-stepper>
+```
+
+### Dynamic Progress Updates
+
+Steppers can be updated dynamically using JavaScript to reflect real-time progress through a workflow.
+
+```html:preview
+<zn-stepper
+  id="dynamic-stepper"
+  label="Form Wizard"
+  caption="Step 1: Personal Details"
+  steps="4"
+  value="1"
+  show-progress>
+</zn-stepper>
+<br />
+<zn-button id="next-step">Next Step</zn-button>
+<zn-button id="prev-step" color="secondary">Previous Step</zn-button>
+<zn-button id="reset-stepper" color="transparent">Reset</zn-button>
+
+<script type="module">
+  const stepper = document.getElementById('dynamic-stepper');
+  const nextBtn = document.getElementById('next-step');
+  const prevBtn = document.getElementById('prev-step');
+  const resetBtn = document.getElementById('reset-stepper');
+
+  const stepNames = [
+    'Personal Details',
+    'Contact Information',
+    'Preferences',
+    'Review & Submit'
+  ];
+
+  function updateStepCaption() {
+    const stepIndex = stepper.value - 1;
+    if (stepIndex >= 0 && stepIndex < stepNames.length) {
+      stepper.caption = `Step ${stepper.value}: ${stepNames[stepIndex]}`;
+    } else if (stepper.value === 0) {
+      stepper.caption = 'Getting Started';
+    }
+  }
+
+  nextBtn.addEventListener('click', () => {
+    if (stepper.value < stepper.steps) {
+      stepper.value = stepper.value + 1;
+      updateStepCaption();
+      if (stepper.value === stepper.steps) {
+        stepper.caption = 'Complete!';
+      }
+    }
+  });
+
+  prevBtn.addEventListener('click', () => {
+    if (stepper.value > 0) {
+      stepper.value = stepper.value - 1;
+      updateStepCaption();
+    }
+  });
+
+  resetBtn.addEventListener('click', () => {
+    stepper.value = 1;
+    updateStepCaption();
+  });
+</script>
+```
+
+### Multi-Step Form Wizard
+
+A practical example showing a stepper integrated with a form wizard interface.
+
+```html:preview
+<zn-stepper
+  id="wizard-stepper"
+  label="Account Creation Wizard"
+  caption="Step 1: Basic Information"
+  steps="3"
+  value="1"
+  show-progress>
+</zn-stepper>
+
+<div id="wizard-content" style="margin-top: 20px; padding: 20px; border: 1px solid rgb(var(--zn-border-color)); border-radius: 4px;">
+  <div class="wizard-step" data-step="1">
+    <h3>Basic Information</h3>
+    <p>Please enter your basic details to get started.</p>
+  </div>
+  <div class="wizard-step" data-step="2" style="display: none;">
+    <h3>Account Settings</h3>
+    <p>Configure your account preferences.</p>
+  </div>
+  <div class="wizard-step" data-step="3" style="display: none;">
+    <h3>Confirmation</h3>
+    <p>Review your information and complete the setup.</p>
+  </div>
+</div>
+
+<div style="margin-top: 20px;">
+  <zn-button id="wizard-next" color="default">Next</zn-button>
+  <zn-button id="wizard-prev" color="secondary" style="display: none;">Previous</zn-button>
+  <zn-button id="wizard-finish" color="success" style="display: none;">Finish</zn-button>
+</div>
+
+<script type="module">
+  const wizardStepper = document.getElementById('wizard-stepper');
+  const nextBtn = document.getElementById('wizard-next');
+  const prevBtn = document.getElementById('wizard-prev');
+  const finishBtn = document.getElementById('wizard-finish');
+  const steps = document.querySelectorAll('.wizard-step');
+
+  const stepTitles = [
+    'Basic Information',
+    'Account Settings',
+    'Confirmation'
+  ];
+
+  function updateWizard() {
+    const currentStep = wizardStepper.value;
+
+    // Update stepper caption
+    wizardStepper.caption = `Step ${currentStep}: ${stepTitles[currentStep - 1]}`;
+
+    // Show/hide content
+    steps.forEach((step, index) => {
+      step.style.display = (index + 1 === currentStep) ? 'block' : 'none';
+    });
+
+    // Show/hide buttons
+    prevBtn.style.display = currentStep > 1 ? 'inline-block' : 'none';
+    nextBtn.style.display = currentStep < wizardStepper.steps ? 'inline-block' : 'none';
+    finishBtn.style.display = currentStep === wizardStepper.steps ? 'inline-block' : 'none';
+  }
+
+  nextBtn.addEventListener('click', () => {
+    if (wizardStepper.value < wizardStepper.steps) {
+      wizardStepper.value++;
+      updateWizard();
+    }
+  });
+
+  prevBtn.addEventListener('click', () => {
+    if (wizardStepper.value > 1) {
+      wizardStepper.value--;
+      updateWizard();
+    }
+  });
+
+  finishBtn.addEventListener('click', () => {
+    alert('Wizard completed!');
+  });
+
+  updateWizard();
+</script>
+```
+
+### Installation Progress Simulation
+
+A realistic example simulating an installation or setup process with automatic progress updates.
+
+```html:preview
+<zn-stepper
+  id="install-stepper"
+  label="Software Installation"
+  caption="Click Start to begin"
+  steps="5"
+  value="0"
+  show-progress>
+</zn-stepper>
+<br />
+<zn-button id="start-install" icon="download">Start Installation</zn-button>
+<zn-button id="cancel-install" color="secondary" disabled>Cancel</zn-button>
+
+<script type="module">
+  const installStepper = document.getElementById('install-stepper');
+  const startBtn = document.getElementById('start-install');
+  const cancelBtn = document.getElementById('cancel-install');
+  let installInterval;
+
+  const installSteps = [
+    'Downloading files...',
+    'Extracting packages...',
+    'Installing dependencies...',
+    'Configuring settings...',
+    'Finalizing installation...',
+    'Installation complete!'
+  ];
+
+  startBtn.addEventListener('click', () => {
+    installStepper.value = 0;
+    startBtn.disabled = true;
+    startBtn.loading = true;
+    cancelBtn.disabled = false;
+
+    let currentStep = 0;
+
+    installInterval = setInterval(() => {
+      if (currentStep < installStepper.steps) {
+        currentStep++;
+        installStepper.value = currentStep;
+        installStepper.caption = installSteps[currentStep];
+      } else {
+        clearInterval(installInterval);
+        installStepper.caption = installSteps[installSteps.length - 1];
+        startBtn.disabled = false;
+        startBtn.loading = false;
+        cancelBtn.disabled = true;
+      }
+    }, 1500);
+  });
 
-TODO
+  cancelBtn.addEventListener('click', () => {
+    clearInterval(installInterval);
+    installStepper.caption = 'Installation cancelled';
+    startBtn.disabled = false;
+    startBtn.loading = false;
+    cancelBtn.disabled = true;
+  });
+</script>
+```
+
+### Multiple Steppers
+
+Display multiple steppers to track different concurrent processes or workflows.
+
+```html:preview
+<zn-stepper
+  label="Frontend Build"
+  caption="Build Complete"
+  steps="4"
+  value="4"
+  show-progress>
+</zn-stepper>
+<br />
+<zn-stepper
+  label="Backend Build"
+  caption="Running Tests"
+  steps="4"
+  value="3"
+  show-progress>
+</zn-stepper>
+<br />
+<zn-stepper
+  label="Database Migration"
+  caption="Migrating Schema"
+  steps="6"
+  value="2"
+  show-progress>
+</zn-stepper>
+<br />
+<zn-stepper
+  label="Asset Optimization"
+  caption="Waiting to Start"
+  steps="3"
+  value="0"
+  show-progress>
+</zn-stepper>
+```
+
+### Minimal Stepper
+
+A clean, minimal stepper without any text labels, useful for compact layouts or when context is provided elsewhere.
+
+```html:preview
+<zn-stepper steps="5" value="1"></zn-stepper>
+<br />
+<zn-stepper steps="5" value="3"></zn-stepper>
+<br />
+<zn-stepper steps="5" value="5"></zn-stepper>
+```
+
+### Progress Overflow
+
+The stepper handles cases where the value exceeds the total steps by capping the visual progress at 100%.
+
+```html:preview
+<zn-stepper
+  caption="Over Limit Example"
+  steps="5"
+  value="7"
+  show-progress>
+</zn-stepper>
+```
+
+### Different Step Counts
+
+Steppers work with any number of steps, from simple two-step processes to complex multi-step workflows.
+
+```html:preview
+<zn-stepper caption="Two Steps" steps="2" value="1" show-progress></zn-stepper>
+<br />
+<zn-stepper caption="Five Steps" steps="5" value="3" show-progress></zn-stepper>
+<br />
+<zn-stepper caption="Ten Steps" steps="10" value="6" show-progress></zn-stepper>
+<br />
+<zn-stepper caption="Twenty Steps" steps="20" value="15" show-progress></zn-stepper>
+```
+
+## Customization
+
+### Styling with CSS
+
+Customize the appearance of the stepper using CSS custom properties and standard CSS.
+
+```html:preview
+<zn-stepper
+  class="custom-stepper"
+  label="Custom Styled Stepper"
+  caption="With Custom Colors"
+  steps="5"
+  value="3"
+  show-progress>
+</zn-stepper>
+
+<style>
+  .custom-stepper .step-progress {
+    background-color: rgb(var(--zn-success));
+  }
+
+  .custom-stepper .step {
+    background-color: rgba(var(--zn-success), 0.3);
+  }
+
+  .custom-stepper .header {
+    color: rgb(var(--zn-success));
+  }
+
+  .custom-stepper .label {
+    font-weight: 700;
+  }
+</style>
+```
+
+### Themed Steppers
+
+Create themed steppers for different use cases or states.
+
+```html:preview
+<zn-stepper
+  class="success-stepper"
+  caption="Success State"
+  steps="4"
+  value="4"
+  show-progress>
+</zn-stepper>
+<br />
+<zn-stepper
+  class="warning-stepper"
+  caption="Warning State"
+  steps="4"
+  value="2"
+  show-progress>
+</zn-stepper>
+<br />
+<zn-stepper
+  class="error-stepper"
+  caption="Error State"
+  steps="4"
+  value="1"
+  show-progress>
+</zn-stepper>
+
+<style>
+  .success-stepper .step-progress {
+    background-color: rgb(var(--zn-success));
+  }
+  .success-stepper .step {
+    background-color: rgba(var(--zn-success), 0.3);
+  }
+
+  .warning-stepper .step-progress {
+    background-color: rgb(var(--zn-warning));
+  }
+  .warning-stepper .step {
+    background-color: rgba(var(--zn-warning), 0.3);
+  }
+
+  .error-stepper .step-progress {
+    background-color: rgb(var(--zn-error));
+  }
+  .error-stepper .step {
+    background-color: rgba(var(--zn-error), 0.3);
+  }
+</style>
+```
+
+### Custom Height and Styling
+
+Adjust the visual appearance of the stepper to match your design requirements.
+
+```html:preview
+<zn-stepper
+  class="large-stepper"
+  caption="Large Stepper"
+  steps="4"
+  value="2"
+  show-progress>
+</zn-stepper>
+
+<style>
+  .large-stepper .step-container {
+    height: 20px;
+  }
+
+  .large-stepper .step {
+    width: 24px;
+    height: 24px;
+    border-width: 4px;
+  }
+
+  .large-stepper .step-progress {
+    height: 12px;
+    top: 4px;
+  }
+
+  .large-stepper .step-line {
+    height: 4px;
+  }
+</style>
+```
+
+## Wizard Patterns
+
+### Using with Vertical Stepper
+
+Combine horizontal and vertical steppers for comprehensive workflow navigation. The horizontal stepper shows overall progress while vertical steppers can show sub-steps within each main step.
+
+```html:preview
+<zn-stepper
+  label="Multi-Stage Process"
+  caption="Stage 2: Configuration"
+  steps="3"
+  value="2"
+  show-progress>
+</zn-stepper>
+<br /><br />
+<zn-vertical-stepper caption="Database Setup" description="Configure database connection" first active></zn-vertical-stepper>
+<zn-vertical-stepper caption="API Keys" description="Enter your API credentials" active></zn-vertical-stepper>
+<zn-vertical-stepper caption="Deployment" description="Deploy to production" last></zn-vertical-stepper>
+```
+
+### Progressive Disclosure
+
+Use steppers to guide users through complex forms with progressive disclosure of information.
+
+```html:preview
+<zn-stepper
+  id="disclosure-stepper"
+  label="Registration Process"
+  caption="Step 1 of 4"
+  steps="4"
+  value="1"
+  show-progress>
+</zn-stepper>
+<br />
+<p>Steppers help break down complex multi-step processes into manageable chunks, improving user experience and reducing cognitive load.</p>
+```
+
+### Validation States
+
+Combine steppers with validation feedback to show progress and validation status.
+
+```html:preview
+<zn-stepper
+  label="Form Validation"
+  caption="Step 2: Validation Required"
+  steps="3"
+  value="2"
+  show-progress>
+</zn-stepper>
+<br />
+<zn-alert color="warning" open>
+  Please complete all required fields before proceeding to the next step.
+</zn-alert>
+```