@kubex/zinc 1.0.25 → 1.0.98

package/docs/pages/components/input-group.md

@@ -5,7 +5,7 @@ meta:
 layout: component
 ---
 
-Input Groups allow you to group multiple form controls together into a single visual unit.
+Input Groups allow you to group multiple form controls together into a single visual unit. They are ideal for creating compound inputs where multiple fields are related and should be visually connected, such as address fields, URL builders, or search interfaces with action buttons.
 
 ```html:preview
 <zn-input-group>
@@ -14,24 +14,27 @@ Input Groups allow you to group multiple form controls together into a single vi
 </zn-input-group>
 ```
 
+:::tip
+Input Groups support `zn-input`, `zn-select`, and `zn-button` components. The component automatically styles the borders and corners to create a seamless visual connection between controls.
+:::
+
 ## Examples
 
-### Mixed Inputs and Selects
+### Basic Input Group
 
-You can combine inputs and selects.
+The simplest input group combines two or more inputs. Borders between controls are merged, and corner radii are adjusted automatically to create a unified appearance.
 
 ```html:preview
 <zn-input-group>
-  <zn-select value="http://" style="width: 125px;">
-    <zn-option value="http://">http://</zn-option>
-    <zn-option value="https://">https://</zn-option>
-  </zn-select>
-  <zn-input placeholder="example.com"></zn-input>
+  <zn-input placeholder="First Name"></zn-input>
+  <zn-input placeholder="Last Name"></zn-input>
 </zn-input-group>
 ```
 
 ### Multiple Inputs
 
+You can group three or more inputs together. Middle inputs will have no border radius, creating a continuous flow.
+
 ```html:preview
 <zn-input-group>
   <zn-input placeholder="City"></zn-input>
@@ -40,22 +43,213 @@ You can combine inputs and selects.
 </zn-input-group>
 ```
 
-### Labeled Group
+### Label
 
-Use the `label` attribute to add a label to the input group.
+Use the `label` attribute to give the input group an accessible label. For labels that contain HTML, use the `label` slot instead.
 
 ```html:preview
 <zn-input-group label="Personal Information">
   <zn-input placeholder="First Name"></zn-input>
   <zn-input placeholder="Last Name"></zn-input>
 </zn-input-group>
+<br />
+<zn-input-group>
+  <span slot="label">Mailing Address</span>
+  <zn-input placeholder="Street Address"></zn-input>
+  <zn-input placeholder="City"></zn-input>
+  <zn-input placeholder="State"></zn-input>
+  <zn-input placeholder="Zip Code"></zn-input>
+</zn-input-group>
 ```
 
-### Input with Submit Button
+### Mixed Inputs and Selects
+
+Combine inputs and selects to create powerful compound controls. This is useful for URL builders, phone number inputs with country codes, or any scenario where a predefined option needs to be paired with user input.
 
 ```html:preview
-<zn-input-group>
-  <zn-input placeholder="Email Address" type="email"></zn-input>
+<zn-input-group label="Website URL">
+  <zn-select value="https://" style="width: 125px;">
+    <zn-option value="http://">http://</zn-option>
+    <zn-option value="https://">https://</zn-option>
+  </zn-select>
+  <zn-input placeholder="example.com"></zn-input>
+</zn-input-group>
+<br />
+<zn-input-group label="Phone Number">
+  <zn-select value="+1" style="width: 100px;">
+    <zn-option value="+1">+1</zn-option>
+    <zn-option value="+44">+44</zn-option>
+    <zn-option value="+86">+86</zn-option>
+    <zn-option value="+91">+91</zn-option>
+  </zn-select>
+  <zn-input type="tel" placeholder="(555) 123-4567"></zn-input>
+</zn-input-group>
+```
+
+### Input with Button
+
+Add a button to create search interfaces, newsletter signups, or any input that requires immediate action. Buttons integrate seamlessly with the grouped styling.
+
+```html:preview
+<zn-input-group label="Email Newsletter">
+  <zn-input placeholder="Enter your email" type="email"></zn-input>
   <zn-button>Subscribe</zn-button>
 </zn-input-group>
+<br />
+<zn-input-group label="Search Products">
+  <zn-input placeholder="Search..." type="search"></zn-input>
+  <zn-button color="secondary">Search</zn-button>
+</zn-input-group>
+```
+
+### Button at the Start
+
+Place a button at the beginning of the group for actions that should precede the input.
+
+```html:preview
+<zn-input-group label="Quick Search">
+  <zn-button icon="search"></zn-button>
+  <zn-input placeholder="Type to search..."></zn-input>
+</zn-input-group>
+```
+
+### Multiple Controls with Buttons
+
+Create more complex interfaces by combining multiple inputs, selects, and buttons in a single group.
+
+```html:preview
+<zn-input-group label="Transfer Funds">
+  <zn-select value="USD" style="width: 100px;">
+    <zn-option value="USD">USD</zn-option>
+    <zn-option value="EUR">EUR</zn-option>
+    <zn-option value="GBP">GBP</zn-option>
+  </zn-select>
+  <zn-input type="currency" placeholder="0.00"></zn-input>
+  <zn-button color="success">Transfer</zn-button>
+</zn-input-group>
+<br />
+<zn-input-group label="Date Range Filter">
+  <zn-input type="date" placeholder="Start Date"></zn-input>
+  <zn-input type="date" placeholder="End Date"></zn-input>
+  <zn-button color="secondary">Apply</zn-button>
+</zn-input-group>
+```
+
+### Flexible Width Distribution
+
+Use the `span` attribute on individual controls to control their relative widths within the group. The span attribute accepts values from 1 to 12 and works similarly to CSS grid column spans. This is particularly useful when one field should be larger than others.
+
+```html:preview
+<zn-input-group label="Address">
+  <zn-input span="8" placeholder="Street Address"></zn-input>
+  <zn-input span="4" placeholder="Apt/Unit"></zn-input>
+</zn-input-group>
+<br />
+<zn-input-group label="Contact Information">
+  <zn-input span="6" placeholder="First Name"></zn-input>
+  <zn-input span="6" placeholder="Last Name"></zn-input>
+</zn-input-group>
+<br />
+<zn-input-group label="Location">
+  <zn-input span="6" placeholder="City"></zn-input>
+  <zn-input span="3" placeholder="State"></zn-input>
+  <zn-input span="3" placeholder="Zip"></zn-input>
+</zn-input-group>
+```
+
+:::tip
+**Usage:** The `span` attribute only takes effect on medium screens and above. On smaller screens, all inputs will be equal width to ensure proper mobile usability.
+:::
+
+### Different Input Types
+
+Input groups work with all input types, allowing you to create diverse compound controls.
+
+```html:preview
+<zn-input-group label="Payment Information">
+  <zn-input type="text" placeholder="Cardholder Name" span="12"></zn-input>
+</zn-input-group>
+<br />
+<zn-input-group>
+  <zn-input type="text" placeholder="Card Number" span="8"></zn-input>
+  <zn-input type="text" placeholder="CVV" span="4"></zn-input>
+</zn-input-group>
+<br />
+<zn-input-group label="Price Range">
+  <zn-input type="currency" placeholder="Min"></zn-input>
+  <zn-input type="currency" placeholder="Max"></zn-input>
+</zn-input-group>
+```
+
+### Form Integration
+
+Input groups work seamlessly within forms. Each control maintains its individual `name` attribute for form submission.
+
+```html:preview
+<form class="input-group-form">
+  <zn-input-group label="Full Name">
+    <zn-input name="firstName" placeholder="First Name" required></zn-input>
+    <zn-input name="lastName" placeholder="Last Name" required></zn-input>
+  </zn-input-group>
+  <br />
+  <zn-input-group label="Contact">
+    <zn-select name="countryCode" value="+1" style="width: 100px;">
+      <zn-option value="+1">+1</zn-option>
+      <zn-option value="+44">+44</zn-option>
+    </zn-select>
+    <zn-input name="phone" type="tel" placeholder="Phone Number" required></zn-input>
+  </zn-input-group>
+  <br />
+  <zn-button type="submit" color="success">Submit</zn-button>
+</form>
+
+<script type="module">
+  const form = document.querySelector('.input-group-form');
+
+  await Promise.all([
+    customElements.whenDefined('zn-input'),
+    customElements.whenDefined('zn-select'),
+    customElements.whenDefined('zn-button')
+  ]).then(() => {
+    form.addEventListener('submit', (e) => {
+      e.preventDefault();
+      const formData = new FormData(form);
+      const data = Object.fromEntries(formData);
+      alert('Form submitted!\n\n' + JSON.stringify(data, null, 2));
+    });
+  });
+</script>
 ```
+
+### Focus Behavior
+
+When a control within the group receives focus, its z-index increases to ensure the focus ring displays properly over adjacent controls.
+
+```html:preview
+<zn-input-group label="Try clicking into each field">
+  <zn-input placeholder="First Name"></zn-input>
+  <zn-input placeholder="Last Name"></zn-input>
+  <zn-input placeholder="Email"></zn-input>
+</zn-input-group>
+```
+
+### Styling Individual Controls
+
+You can still apply individual styling to controls within a group. However, note that border-radius is controlled by the input group and will be overridden.
+
+```html:preview
+<zn-input-group label="Custom Styled Controls">
+  <zn-input placeholder="Normal" span="4"></zn-input>
+  <zn-input placeholder="Disabled" disabled span="4"></zn-input>
+  <zn-input placeholder="With Value" value="Prefilled" span="4"></zn-input>
+</zn-input-group>
+<br />
+<zn-input-group label="Different Sizes">
+  <zn-input placeholder="Medium (default)" size="medium"></zn-input>
+  <zn-input placeholder="Large" size="large"></zn-input>
+</zn-input-group>
+```
+
+:::warning
+**Note:** While controls within a group can have different sizes, it's recommended to use consistent sizes for better visual harmony. The component adjusts alignment automatically, but mixed sizes may not look as polished.
+:::

package/docs/pages/components/input.md

@@ -134,6 +134,33 @@ The `type` attribute controls the type of input the browser renders. As shown in
 have default prefix and suffix elements. Not all available types are shown below. See
 the [Properties table](#properties) for the full list of options.
 
+#### Color Input
+
+The color input type displays a clickable color swatch on the left that opens the browser's native color picker. The color value is shown as editable text in the input field, allowing users to either pick a color visually or enter a color value directly.
+
+Use the `color-format` attribute to specify the format: `hex` (default), `rgb`, or `oklch`.
+
+```html:preview
+<zn-input type="color" label="Hex Format (default)" value="#3b82f6">
+  <div slot="help-text">Default format. Click the swatch to pick a color, or type a hex value like #3b82f6.</div>
+</zn-input>
+<br />
+<zn-input type="color" label="RGB Format" color-format="rgb" value="rgb(139, 92, 246)">
+  <div slot="help-text">Type RGB values like rgb(139, 92, 246). The picker converts to/from hex automatically.</div>
+</zn-input>
+<br />
+<zn-input type="color" label="OKLCH Format" color-format="oklch" value="oklch(0.628 0.225 292.6)">
+  <div slot="help-text">Type OKLCH values like oklch(0.628 0.225 292.6). The picker converts to/from hex automatically.</div>
+</zn-input>
+<br />
+<zn-input type="color" label="Background Color" value="#f59e0b" clearable>
+  <div slot="help-text">Use the <code>clearable</code> attribute to allow clearing the color value.</div>
+</zn-input>
+<br />
+```
+
+#### Other Input Types
+
 ```html:preview
 <zn-input type="currency" label="Input type: Currency"><div slot="help-text">Has <code>$</code> prefix and <code>USD</code> suffix by default and native input type set to <code>number</code>. The currency input does <strong>NOT</strong> have input masking at this time.</div></zn-input>
 <br />
@@ -222,6 +249,173 @@ Or as a Prefix
 </zn-input>
 ```
 
+### Form Navigation with Enter Key
+
+Add the `data-enter-navigation` attribute to a form to enable Enter key navigation through form inputs. When enabled, pressing Enter will move focus to the next input field, and submit the form when all named fields are filled and valid.
+
+:::tip
+**Usage:** This feature is useful for forms where users naturally want to press Enter to move between fields, such as data entry forms, registration forms, or checkout flows.
+:::
+
+#### Basic Example
+
+```html:preview
+<form class="form-nav-basic" data-enter-navigation>
+  <zn-input name="firstName" label="First Name" required></zn-input>
+  <br />
+  <zn-input name="lastName" label="Last Name" required></zn-input>
+  <br />
+  <zn-input name="email" type="email" label="Email" required></zn-input>
+  <br />
+  <zn-input name="phone" type="tel" label="Phone"></zn-input>
+  <br />
+  <zn-button type="submit" variant="primary">Submit</zn-button>
+</form>
+
+<script type="module">
+  const form = document.querySelector('.form-nav-basic');
+
+  // Wait for controls to be defined before attaching form listeners
+  await Promise.all([
+    customElements.whenDefined('zn-button'),
+    customElements.whenDefined('zn-input')
+  ]).then(() => {
+    form.addEventListener('submit', (e) => {
+      e.preventDefault();
+      const formData = new FormData(form);
+      const data = Object.fromEntries(formData);
+      alert('Form submitted!\n\n' + JSON.stringify(data, null, 2));
+    });
+  });
+</script>
+```
+
+#### All Input Types Example
+
+This example demonstrates Enter key navigation with various input types including text, email, phone, number, currency, and date inputs:
+
+```html:preview
+<form class="form-nav-all-types" data-enter-navigation>
+  <zn-input name="fullName" label="Full Name" required></zn-input>
+  <br />
+  <zn-input name="email" type="email" label="Email Address" required></zn-input>
+  <br />
+  <zn-input name="phone" type="tel" label="Phone Number" required></zn-input>
+  <br />
+  <zn-input name="age" type="number" label="Age" min="18" max="100" required></zn-input>
+  <br />
+  <zn-input name="salary" type="currency" label="Expected Salary" required></zn-input>
+  <br />
+  <zn-datepicker name="availableDate" label="Available Start Date" required></zn-datepicker>
+  <br />
+  <zn-input name="website" type="url" label="Portfolio Website"></zn-input>
+  <br />
+  <zn-button type="submit" variant="primary">Continue</zn-button>
+</form>
+
+<script type="module">
+  const allTypesForm = document.querySelector('.form-nav-all-types');
+
+  // Wait for controls to be defined before attaching form listeners
+  await Promise.all([
+    customElements.whenDefined('zn-button'),
+    customElements.whenDefined('zn-datepicker'),
+    customElements.whenDefined('zn-input')
+  ]).then(() => {
+    allTypesForm.addEventListener('submit', (e) => {
+      e.preventDefault();
+      const formData = new FormData(allTypesForm);
+      const data = Object.fromEntries(formData);
+      alert('Form submitted!\n\n' + JSON.stringify(data, null, 2));
+    });
+  });
+</script>
+```
+
+**Navigation flow:** Press Enter to move through each field. The form submits when all named fields are filled and valid.
+
+#### Mixed Form Controls
+
+Form navigation works with all Zinc form controls including selects, radios, checkboxes, toggles, and textareas. Textareas are excluded from navigation since they need Enter for their own functionality.
+
+```html:preview
+<form class="form-nav-mixed" data-enter-navigation>
+  <zn-input name="productName" label="Product Name" required></zn-input>
+  <br />
+  <zn-input name="sku" label="SKU" required></zn-input>
+  <br />
+  <zn-input name="price" type="currency" label="Price" required></zn-input>
+  <br />
+  <zn-input name="quantity" type="number" label="Quantity" required min="1"></zn-input>
+  <br />
+  <zn-select name="category" label="Category" required clearable>
+    <zn-option value="electronics">Electronics</zn-option>
+    <zn-option value="clothing">Clothing</zn-option>
+    <zn-option value="books">Books</zn-option>
+    <zn-option value="home">Home & Garden</zn-option>
+  </zn-select>
+  <br />
+  <zn-radio-group name="condition" label="Condition" required>
+    <zn-radio value="new">New</zn-radio>
+    <zn-radio value="used">Used</zn-radio>
+    <zn-radio value="refurbished">Refurbished</zn-radio>
+  </zn-radio-group>
+  <br /><br />
+  <zn-checkbox name="featured" value="yes">Feature this product</zn-checkbox>
+  <br /><br />
+  <zn-toggle name="available" value="yes">Available for purchase</zn-toggle>
+  <br /><br />
+  <zn-textarea name="description" label="Description (Press Tab to navigate, Enter for new lines)"></zn-textarea>
+  <br />
+  <zn-button type="submit" variant="primary">Add Product</zn-button>
+</form>
+
+<script type="module">
+  const mixedForm = document.querySelector('.form-nav-mixed');
+
+  // Wait for controls to be defined before attaching form listeners
+  await Promise.all([
+    customElements.whenDefined('zn-button'),
+    customElements.whenDefined('zn-checkbox'),
+    customElements.whenDefined('zn-input'),
+    customElements.whenDefined('zn-option'),
+    customElements.whenDefined('zn-radio'),
+    customElements.whenDefined('zn-radio-group'),
+    customElements.whenDefined('zn-select'),
+    customElements.whenDefined('zn-textarea'),
+    customElements.whenDefined('zn-toggle')
+  ]).then(() => {
+    mixedForm.addEventListener('submit', (e) => {
+      e.preventDefault();
+      const formData = new FormData(mixedForm);
+      const data = Object.fromEntries(formData);
+      alert('Product added!\n\n' + JSON.stringify(data, null, 2));
+    });
+  });
+</script>
+```
+
+**Navigation behavior by control type:**
+- **Text inputs:** Enter moves to next field
+- **Number/Currency inputs:** Enter moves to next field
+- **Datepicker:** Enter moves to next field
+- **Select dropdowns:** Automatically opens when navigated to. Enter on an option selects it and moves to next field.
+- **Radio buttons:** Arrow keys select different options within the radio group. Space or Enter selects the current option. Press Enter to move to next field.
+- **Checkboxes:** Space toggles the checkbox. Enter, Arrow Down, or Arrow Up moves to next/previous field.
+- **Toggles:** Space toggles the toggle. Enter, Arrow Down, or Arrow Up moves to next/previous field.
+- **Textareas:** You can navigate TO a textarea with Enter, but pressing Enter inside a textarea adds newlines. Use Tab to navigate away from textareas.
+- **Search inputs:** You can navigate TO a search input with Enter, but pressing Enter inside a search input triggers search. Use Tab to navigate away from search inputs.
+
+**Keyboard shortcuts:**
+- **Enter** - Move to next field (or submit form if all fields complete)
+- **Arrow Down/Up** - On checkboxes and toggles, moves to next/previous field. On radios, selects next/previous option in group.
+- **Space** - Toggle checkboxes and toggles. Select current radio option.
+- **Tab** - Standard browser tab navigation
+
+:::warning
+**Note:** While you can navigate TO textareas and search inputs using Enter, pressing Enter while inside these controls uses the Enter key for their own functionality (new lines and search triggers, respectively). Use Tab to navigate away from these controls.
+:::
+
 ### Customizing Label Position
 
 Use [CSS parts](#css-parts) to customize the way form controls are drawn. This example uses CSS grid to position the

package/docs/pages/components/key-container.md

@@ -0,0 +1,115 @@
+---
+meta:
+  title: Key Container
+  description: A legend container that manages key items, typically used alongside charts to toggle visibility of data series by category.
+layout: component
+---
+
+```html:preview
+<zn-key-container filter-attribute="data-type">
+  <zn-key icon="circle" color="primary" attribute="sale" active>Sales</zn-key>
+  <zn-key icon="circle" color="success" attribute="refund" active>Refunds</zn-key>
+  <zn-key icon="circle" color="warning" attribute="pending" active>Pending</zn-key>
+
+  <div style="margin-top: 16px; display: flex; flex-direction: column; gap: 4px;">
+    <zn-chip data-type="sale" type="primary">Sale #1001</zn-chip>
+    <zn-chip data-type="refund" type="success">Refund #2001</zn-chip>
+    <zn-chip data-type="sale" type="primary">Sale #1002</zn-chip>
+    <zn-chip data-type="pending" type="warning">Pending #3001</zn-chip>
+    <zn-chip data-type="refund" type="success">Refund #2002</zn-chip>
+  </div>
+</zn-key-container>
+```
+
+## Examples
+
+### Basic Usage
+
+Place `zn-key` elements and filterable content inside a `zn-key-container`. Use `filter-attribute` to specify which attribute on content items should be matched against each key's `attribute` value. Deactivating a key hides items that match it.
+
+```html:preview
+<zn-key-container filter-attribute="data-category">
+  <zn-key icon="circle" color="primary" attribute="frontend" active>Frontend</zn-key>
+  <zn-key icon="circle" color="success" attribute="backend" active>Backend</zn-key>
+  <zn-key icon="circle" color="info" attribute="devops" active>DevOps</zn-key>
+
+  <div style="margin-top: 16px; display: flex; flex-direction: column; gap: 4px;">
+    <zn-chip data-category="frontend" type="primary">React component</zn-chip>
+    <zn-chip data-category="backend" type="success">API endpoint</zn-chip>
+    <zn-chip data-category="devops" type="info">CI pipeline</zn-chip>
+    <zn-chip data-category="frontend" type="primary">CSS update</zn-chip>
+    <zn-chip data-category="backend" type="success">Database migration</zn-chip>
+  </div>
+</zn-key-container>
+```
+
+### Using Attribute and Value
+
+When keys specify both `attribute` and `value`, items are matched by checking if the given attribute contains the given value.
+
+```html:preview
+<zn-key-container>
+  <zn-key icon="circle" color="success" attribute="data-status" value="active" active>Active</zn-key>
+  <zn-key icon="circle" color="warning" attribute="data-status" value="pending" active>Pending</zn-key>
+  <zn-key icon="circle" color="error" attribute="data-status" value="closed" active>Closed</zn-key>
+
+  <div style="margin-top: 16px; display: flex; flex-direction: column; gap: 4px;">
+    <zn-chip data-status="active" type="success">Ticket #101 - Active</zn-chip>
+    <zn-chip data-status="pending" type="warning">Ticket #102 - Pending</zn-chip>
+    <zn-chip data-status="closed" type="error">Ticket #103 - Closed</zn-chip>
+    <zn-chip data-status="active" type="success">Ticket #104 - Active</zn-chip>
+    <zn-chip data-status="pending" type="warning">Ticket #105 - Pending</zn-chip>
+  </div>
+</zn-key-container>
+```
+
+### External Target
+
+Use the `target` attribute to filter content in a separate element by its ID, instead of filtering slotted content.
+
+```html:preview
+<zn-key-container target="target-list" filter-attribute="data-type">
+  <zn-key icon="circle" color="primary" attribute="order" active>Orders</zn-key>
+  <zn-key icon="circle" color="success" attribute="payment" active>Payments</zn-key>
+</zn-key-container>
+
+<div id="target-list" style="margin-top: 16px; display: flex; flex-direction: column; gap: 4px;">
+  <zn-chip data-type="order" type="primary">Order #5001</zn-chip>
+  <zn-chip data-type="payment" type="success">Payment #6001</zn-chip>
+  <zn-chip data-type="order" type="primary">Order #5002</zn-chip>
+  <zn-chip data-type="payment" type="success">Payment #6002</zn-chip>
+</div>
+```
+
+### No Scroll
+
+By default, the container allows its content to scroll. Use the `no-scroll` attribute to disable this behaviour.
+
+```html:preview
+<zn-key-container filter-attribute="data-type" no-scroll>
+  <zn-key icon="circle" color="primary" attribute="alpha" active>Alpha</zn-key>
+  <zn-key icon="circle" color="error" attribute="beta" active>Beta</zn-key>
+
+  <div style="margin-top: 16px; display: flex; flex-direction: column; gap: 4px;">
+    <zn-chip data-type="alpha" type="primary">Alpha item 1</zn-chip>
+    <zn-chip data-type="beta" type="error">Beta item 1</zn-chip>
+    <zn-chip data-type="alpha" type="primary">Alpha item 2</zn-chip>
+  </div>
+</zn-key-container>
+```
+
+### Custom Item Selector
+
+Use the `item-selector` attribute to change the CSS selector used to find filterable items. The default is `[data-type]`.
+
+```html:preview
+<zn-key-container item-selector=".filterable">
+  <zn-key icon="circle" color="info" attribute="class" value="filterable" active>Show items</zn-key>
+
+  <div style="margin-top: 16px; display: flex; flex-direction: column; gap: 4px;">
+    <zn-chip class="filterable" type="info">Filterable item</zn-chip>
+    <zn-chip type="neutral">Always visible (no class)</zn-chip>
+    <zn-chip class="filterable" type="info">Another filterable item</zn-chip>
+  </div>
+</zn-key-container>
+```