@kubex/zinc 1.0.25 → 1.0.99

package/docs/pages/components/priority-list.md

@@ -0,0 +1,233 @@
+---
+meta:
+  title: Priority List
+  description: Priority lists allow users to reorder items via drag-and-drop or keyboard, assigning a numerical priority to each position.
+layout: component
+---
+
+## Examples
+
+### Basic Priority List
+
+Use the `label` attribute to give the list an accessible label. Each child element must have a `value` attribute that
+uniquely identifies it.
+
+```html:preview
+<zn-priority-list label="Task Priority">
+  <div value="bug-fixes">Bug Fixes</div>
+  <div value="new-features">New Features</div>
+  <div value="documentation">Documentation</div>
+  <div value="testing">Testing</div>
+</zn-priority-list>
+```
+
+:::tip
+This component works with standard `<form>` elements. Please refer to the section
+on [form controls](/getting-started/form-controls) to learn more about form submission and client-side validation.
+:::
+
+### Help Text
+
+Add descriptive help text with the `help-text` attribute. For help text that contains HTML, use the `help-text` slot
+instead.
+
+```html:preview
+<zn-priority-list label="Deployment Order" help-text="Drag items to set the deployment sequence">
+  <div value="database">Database Migrations</div>
+  <div value="backend">Backend Services</div>
+  <div value="frontend">Frontend App</div>
+  <div value="cdn">CDN Cache Invalidation</div>
+</zn-priority-list>
+```
+
+### Label with Tooltip
+
+Use the `label-tooltip` attribute to add text that appears in a tooltip triggered by an info icon next to the label.
+
+```html:preview
+<zn-priority-list label="Processing Order" label-tooltip="Items will be processed from highest to lowest priority" help-text="Drag to reorder">
+  <div value="validation">Input Validation</div>
+  <div value="transform">Data Transformation</div>
+  <div value="enrichment">Data Enrichment</div>
+  <div value="storage">Storage</div>
+</zn-priority-list>
+```
+
+### Initial Order
+
+Use the `order` attribute to define the initial display order as a comma-separated list of item keys. Items not listed
+in `order` are appended at the end in their DOM order.
+
+```html:preview
+<zn-priority-list label="Release Pipeline" order="testing,staging,production,development">
+  <div value="development">Development</div>
+  <div value="testing">Testing</div>
+  <div value="staging">Staging</div>
+  <div value="production">Production</div>
+</zn-priority-list>
+```
+
+### Custom Priority Start
+
+Use the `priority-start` attribute to change the starting priority number. This is useful when priorities don't start at
+1.
+
+```html:preview
+<zn-priority-list label="Priority Queue" priority-start="0">
+  <div value="critical">Critical</div>
+  <div value="high">High</div>
+  <div value="medium">Medium</div>
+  <div value="low">Low</div>
+</zn-priority-list>
+```
+
+### Sizes
+
+Use the `size` attribute to change the size of the list items.
+
+```html:preview
+<zn-priority-list label="Small" size="small">
+  <div value="a">Item A</div>
+  <div value="b">Item B</div>
+  <div value="c">Item C</div>
+</zn-priority-list>
+<br />
+<zn-priority-list label="Medium" size="medium">
+  <div value="a">Item A</div>
+  <div value="b">Item B</div>
+  <div value="c">Item C</div>
+</zn-priority-list>
+<br />
+<zn-priority-list label="Large" size="large">
+  <div value="a">Item A</div>
+  <div value="b">Item B</div>
+  <div value="c">Item C</div>
+</zn-priority-list>
+```
+
+### Disabled
+
+Use the `disabled` attribute to prevent reordering.
+
+```html:preview
+<zn-priority-list label="Locked Order" disabled>
+  <div value="first">First</div>
+  <div value="second">Second</div>
+  <div value="third">Third</div>
+</zn-priority-list>
+```
+
+### Rich Content
+
+Slotted items can contain any HTML content, not just text.
+
+```html:preview
+<zn-priority-list label="Feature Roadmap">
+  <div value="auth">
+    <strong>Authentication</strong>
+    <br /><small>OAuth2 + SSO integration</small>
+  </div>
+  <div value="dashboard">
+    <strong>Dashboard</strong>
+    <br /><small>Analytics and reporting</small>
+  </div>
+  <div value="api">
+    <strong>Public API</strong>
+    <br /><small>REST and GraphQL endpoints</small>
+  </div>
+  <div value="mobile">
+    <strong>Mobile App</strong>
+    <br /><small>iOS and Android support</small>
+  </div>
+</zn-priority-list>
+```
+
+### Item Actions
+
+Use the `action-{value}` slot to add interactive elements (buttons, links, etc.) to the right side of each item. Actions are fully clickable and won't interfere with drag behaviour.
+
+```html:preview
+<zn-priority-list id="action-list" label="Task Queue">
+  <div value="deploy">Deploy to Production</div>
+  <zn-button slot="action-deploy" size="small" variant="text" theme="danger" onclick="this.closest('zn-priority-list').querySelector('[value=deploy]').remove()">
+    <zn-icon src="delete" size="16"></zn-icon>
+  </zn-button>
+
+  <div value="review">Code Review</div>
+  <zn-button slot="action-review" size="small" variant="text" theme="danger" onclick="this.closest('zn-priority-list').querySelector('[value=review]').remove()">
+    <zn-icon src="delete" size="16"></zn-icon>
+  </zn-button>
+
+  <div value="test">Run Test Suite</div>
+  <zn-button slot="action-test" size="small" variant="text" theme="danger" onclick="this.closest('zn-priority-list').querySelector('[value=test]').remove()">
+    <zn-icon src="delete" size="16"></zn-icon>
+  </zn-button>
+</zn-priority-list>
+```
+
+### Form Submission
+
+When a `name` is set, the component generates hidden inputs for each item as `name[itemValue]=priority`. This example
+shows the submitted form data.
+
+```html:preview
+<form id="priority-form">
+  <zn-priority-list name="priority" label="Reorder and Submit">
+    <div value="alpha">Alpha</div>
+    <div value="beta">Beta</div>
+    <div value="gamma">Gamma</div>
+  </zn-priority-list>
+  <br />
+  <zn-button type="submit">Submit</zn-button>
+</form>
+
+<br />
+<pre id="priority-output">Submit the form to see the data</pre>
+
+<script type="module">
+  const form = document.getElementById('priority-form');
+  const output = document.getElementById('priority-output');
+
+  form.addEventListener('submit', event => {
+    event.preventDefault();
+    const formData = new FormData(form);
+    const entries = [...formData.entries()].map(([key, val]) => `${key} = ${val}`);
+    output.textContent = entries.join('\n');
+  });
+</script>
+```
+
+### Listening for Changes
+
+Use the `zn-reorder` event to react to order changes. Call `getPriorityMap()` on the component to get the current
+priority assignments.
+
+```html:preview
+<zn-priority-list id="event-list" label="Reorder to see events">
+  <div value="red">Red</div>
+  <div value="green">Green</div>
+  <div value="blue">Blue</div>
+</zn-priority-list>
+
+<br />
+<pre id="event-output">Reorder items to see the priority map</pre>
+
+<script type="module">
+  const list = document.getElementById('event-list');
+  const output = document.getElementById('event-output');
+
+  list.addEventListener('zn-reorder', () => {
+    const map = list.getPriorityMap();
+    output.textContent = JSON.stringify(map, null, 2);
+  });
+</script>
+```
+
+### Keyboard Navigation
+
+Focus any item and use the keyboard to reorder:
+
+- **Arrow Up** — Move the focused item up one position
+- **Arrow Down** — Move the focused item down one position
+- **Home** — Move the focused item to the top
+- **End** — Move the focused item to the bottom

package/docs/pages/components/progress-bar.md

@@ -1,22 +1,403 @@
 ---
 meta:
   title: Progress Bar
-  description:
+  description: Progress bars provide visual feedback about the completion status of a task or process.
 layout: component
 ---
 
 ```html:preview
-<zn-progress-bar></zn-progress-bar>
+<zn-progress-bar value="50"></zn-progress-bar>
 ```
 
 ## Examples
 
-### First Example
+### Basic Progress Bar
 
-TODO
+A basic progress bar displays the completion percentage using the `value` attribute. The value should be a number between 0 and 100.
 
-### Second Example
+```html:preview
+<zn-progress-bar value="25"></zn-progress-bar>
+<br />
+<zn-progress-bar value="50"></zn-progress-bar>
+<br />
+<zn-progress-bar value="75"></zn-progress-bar>
+<br />
+<zn-progress-bar value="100"></zn-progress-bar>
+```
+
+### With Caption
+
+Use the `caption` attribute to add a label above the progress bar. This helps identify what the progress bar represents.
+
+```html:preview
+<zn-progress-bar caption="Upload Progress" value="45"></zn-progress-bar>
+<br />
+<zn-progress-bar caption="Installation" value="70"></zn-progress-bar>
+<br />
+<zn-progress-bar caption="Download Complete" value="100"></zn-progress-bar>
+```
+
+### Showing Progress Percentage
+
+Use the `show-progress` attribute to display the numerical percentage value next to the caption.
+
+```html:preview
+<zn-progress-bar caption="File Transfer" value="35" show-progress></zn-progress-bar>
+<br />
+<zn-progress-bar caption="Processing Data" value="62" show-progress></zn-progress-bar>
+<br />
+<zn-progress-bar caption="Backup Complete" value="100" show-progress></zn-progress-bar>
+```
+
+### Progress Only (No Caption)
+
+You can show the progress percentage without a caption by using `show-progress` without the `caption` attribute.
+
+```html:preview
+<zn-progress-bar value="40" show-progress></zn-progress-bar>
+```
+
+### With Description
+
+Use the `description` attribute to add helpful information or context below the progress bar.
+
+```html:preview
+<zn-progress-bar
+  caption="Uploading files"
+  value="55"
+  show-progress
+  description="3 of 10 files uploaded">
+</zn-progress-bar>
+<br />
+<zn-progress-bar
+  caption="Processing"
+  value="30"
+  description="Estimated time remaining: 2 minutes">
+</zn-progress-bar>
+```
+
+### Complete Progress States
+
+Examples showing different stages of task completion with captions, progress percentages, and descriptions.
+
+```html:preview
+<zn-progress-bar
+  caption="Starting"
+  value="0"
+  show-progress
+  description="Initializing...">
+</zn-progress-bar>
+<br />
+<zn-progress-bar
+  caption="In Progress"
+  value="45"
+  show-progress
+  description="Processing 45 of 100 items">
+</zn-progress-bar>
+<br />
+<zn-progress-bar
+  caption="Almost Done"
+  value="95"
+  show-progress
+  description="Finalizing...">
+</zn-progress-bar>
+<br />
+<zn-progress-bar
+  caption="Complete"
+  value="100"
+  show-progress
+  description="All tasks finished successfully">
+</zn-progress-bar>
+```
+
+### Dynamic Progress Updates
+
+Progress bars can be updated dynamically using JavaScript to reflect real-time progress.
+
+```html:preview
+<zn-progress-bar
+  id="dynamic-progress"
+  caption="Dynamic Update"
+  value="0"
+  show-progress
+  description="Click the button to start">
+</zn-progress-bar>
+<br />
+<zn-button id="start-progress">Start Progress</zn-button>
+<zn-button id="reset-progress" color="secondary">Reset</zn-button>
+
+<script type="module">
+  const progressBar = document.getElementById('dynamic-progress');
+  const startBtn = document.getElementById('start-progress');
+  const resetBtn = document.getElementById('reset-progress');
+  let interval;
+
+  startBtn.addEventListener('click', () => {
+    progressBar.value = 0;
+    progressBar.description = 'Processing...';
+    startBtn.disabled = true;
+
+    interval = setInterval(() => {
+      if (progressBar.value < 100) {
+        progressBar.value = progressBar.value + 1;
+        progressBar.description = `Processing ${progressBar.value} of 100 items`;
+      } else {
+        clearInterval(interval);
+        progressBar.description = 'Complete!';
+        startBtn.disabled = false;
+      }
+    }, 50);
+  });
+
+  resetBtn.addEventListener('click', () => {
+    clearInterval(interval);
+    progressBar.value = 0;
+    progressBar.description = 'Click the button to start';
+    startBtn.disabled = false;
+  });
+</script>
+```
+
+### File Upload Simulation
+
+A practical example simulating a file upload process with dynamic updates.
+
+```html:preview
+<zn-progress-bar
+  id="upload-progress"
+  caption="Uploading document.pdf"
+  value="0"
+  show-progress
+  description="Preparing upload...">
+</zn-progress-bar>
+<br />
+<zn-button id="simulate-upload" icon="cloud_upload">Upload File</zn-button>
+
+<script type="module">
+  const uploadProgress = document.getElementById('upload-progress');
+  const uploadBtn = document.getElementById('simulate-upload');
+
+  uploadBtn.addEventListener('click', () => {
+    uploadProgress.value = 0;
+    uploadBtn.disabled = true;
+    uploadBtn.loading = true;
+
+    let uploadSpeed = 2; // Percentage per interval
+    const interval = setInterval(() => {
+      if (uploadProgress.value < 100) {
+        uploadProgress.value = Math.min(uploadProgress.value + uploadSpeed, 100);
 
-TODO
+        // Calculate approximate KB uploaded (simulate 5MB file)
+        const totalKB = 5120;
+        const uploadedKB = Math.floor((uploadProgress.value / 100) * totalKB);
+        uploadProgress.description = `Uploaded ${uploadedKB} KB of ${totalKB} KB`;
 
+        // Slow down near the end (realistic upload behavior)
+        if (uploadProgress.value > 90) {
+          uploadSpeed = 0.5;
+        }
+      } else {
+        clearInterval(interval);
+        uploadProgress.caption = 'Upload Complete';
+        uploadProgress.description = 'File uploaded successfully';
+        uploadBtn.loading = false;
+        uploadBtn.disabled = false;
+      }
+    }, 100);
+  });
+</script>
+```
+
+### Multiple Progress Bars
+
+Display multiple progress bars to track different concurrent tasks or processes.
+
+```html:preview
+<zn-progress-bar
+  caption="Frontend Build"
+  value="100"
+  show-progress
+  description="Completed">
+</zn-progress-bar>
+<br />
+<zn-progress-bar
+  caption="Backend Build"
+  value="85"
+  show-progress
+  description="Compiling...">
+</zn-progress-bar>
+<br />
+<zn-progress-bar
+  caption="Running Tests"
+  value="60"
+  show-progress
+  description="156 of 260 tests passed">
+</zn-progress-bar>
+<br />
+<zn-progress-bar
+  caption="Deployment"
+  value="0"
+  show-progress
+  description="Waiting for builds to complete">
+</zn-progress-bar>
+```
+
+### Minimal Progress Bar
+
+A clean, minimal progress bar without any text, useful for compact layouts or when context is provided elsewhere.
+
+```html:preview
+<zn-progress-bar value="33"></zn-progress-bar>
+<br />
+<zn-progress-bar value="66"></zn-progress-bar>
+<br />
+<zn-progress-bar value="99"></zn-progress-bar>
+```
+
+## Customization
+
+### Styling with CSS Parts
+
+Use [CSS parts](#css-parts) to customize the appearance of the progress bar. The component exposes several parts that can be styled.
+
+```html:preview
+<zn-progress-bar
+  class="custom-progress"
+  caption="Custom Styled Progress"
+  value="75"
+  show-progress
+  description="Customized with CSS parts">
+</zn-progress-bar>
+
+<style>
+  .custom-progress::part(fill) {
+    fill: rgb(255, 107, 53);
+  }
+
+  .custom-progress::part(track) {
+    fill: rgba(255, 107, 53, 0.2);
+  }
+
+  .custom-progress::part(caption) {
+    color: rgb(255, 107, 53);
+    font-weight: 600;
+    font-size: 14px;
+  }
+
+  .custom-progress::part(progress) {
+    color: rgb(255, 107, 53);
+    font-weight: 600;
+  }
+</style>
+```
+
+### Custom Height
 
+Adjust the height of the progress bar using CSS custom properties and parts.
+
+```html:preview
+<zn-progress-bar
+  class="tall-progress"
+  caption="Tall Progress Bar"
+  value="60"
+  show-progress>
+</zn-progress-bar>
+
+<style>
+  .tall-progress::part(bar) {
+    height: 16px;
+  }
+
+  .tall-progress::part(track),
+  .tall-progress::part(fill) {
+    rx: 8px;
+  }
+</style>
+```
+
+### Themed Progress Bars
+
+Create themed progress bars for different use cases like success, warning, or error states.
+
+```html:preview
+<zn-progress-bar
+  class="success-progress"
+  caption="Success"
+  value="100"
+  show-progress
+  description="Operation completed successfully">
+</zn-progress-bar>
+<br />
+<zn-progress-bar
+  class="warning-progress"
+  caption="Warning"
+  value="65"
+  show-progress
+  description="Approaching storage limit">
+</zn-progress-bar>
+<br />
+<zn-progress-bar
+  class="error-progress"
+  caption="Error"
+  value="30"
+  show-progress
+  description="Upload failed, retrying...">
+</zn-progress-bar>
+
+<style>
+  .success-progress::part(fill) {
+    fill: rgb(var(--zn-success));
+  }
+  .success-progress::part(track) {
+    fill: rgba(var(--zn-success), 0.2);
+  }
+
+  .warning-progress::part(fill) {
+    fill: rgb(var(--zn-warning));
+  }
+  .warning-progress::part(track) {
+    fill: rgba(var(--zn-warning), 0.2);
+  }
+
+  .error-progress::part(fill) {
+    fill: rgb(var(--zn-error));
+  }
+  .error-progress::part(track) {
+    fill: rgba(var(--zn-error), 0.2);
+  }
+</style>
+```
+
+### Animated Progress
+
+Add smooth animations to the progress bar fill using CSS transitions.
+
+```html:preview
+<zn-progress-bar
+  id="animated-progress"
+  class="animated-progress"
+  caption="Animated Progress"
+  value="20"
+  show-progress
+  description="Watch the smooth animation">
+</zn-progress-bar>
+<br />
+<zn-button id="increase-animated">Increase Progress</zn-button>
+
+<style>
+  .animated-progress::part(fill) {
+    transition: width 0.5s ease-in-out;
+  }
+</style>
+
+<script type="module">
+  const animatedProgress = document.getElementById('animated-progress');
+  const increaseBtn = document.getElementById('increase-animated');
+
+  increaseBtn.addEventListener('click', () => {
+    const newValue = Math.min(animatedProgress.value + 20, 100);
+    animatedProgress.value = newValue;
+    animatedProgress.description = newValue === 100 ? 'Complete!' : 'Watch the smooth animation';
+  });
+</script>
+```