@kubex/zinc 1.0.25 → 1.0.99

package/docs/pages/components/tooltip.md

@@ -239,4 +239,371 @@ Tooltips will be clipped if they're inside a container that has `overflow: auto|
     padding: var(--zn-spacing-medium);
   }
 </style>
+```
+
+### Distance and Skidding
+
+Use the `distance` and `skidding` attributes to fine-tune the tooltip's position. The `distance` attribute controls how far the tooltip is from the anchor element, while `skidding` offsets the tooltip along the anchor element.
+
+```html:preview
+<div style="display: flex; gap: 2rem; margin: 2rem 0;">
+  <zn-tooltip content="Distance: 8px" distance="8">
+    <zn-button>Distance 8</zn-button>
+  </zn-tooltip>
+
+  <zn-tooltip content="Distance: 16px" distance="16">
+    <zn-button>Distance 16</zn-button>
+  </zn-tooltip>
+
+  <zn-tooltip content="Skidding: 20px" skidding="20">
+    <zn-button>Skidding 20</zn-button>
+  </zn-tooltip>
+
+  <zn-tooltip content="Distance: 12, Skidding: 15" distance="12" skidding="15">
+    <zn-button>Both</zn-button>
+  </zn-tooltip>
+</div>
+```
+
+### Disabled Tooltips
+
+Use the `disabled` attribute to disable a tooltip. The tooltip will not show when disabled.
+
+```html:preview
+<zn-tooltip content="This tooltip is disabled" disabled>
+  <zn-button>Disabled Tooltip</zn-button>
+</zn-tooltip>
+
+<zn-tooltip content="This tooltip is enabled">
+  <zn-button>Enabled Tooltip</zn-button>
+</zn-tooltip>
+
+<script>
+  const disabledTooltip = document.querySelector('zn-tooltip[disabled]');
+  const toggleButton = document.createElement('zn-button');
+  toggleButton.textContent = 'Toggle Disabled';
+  toggleButton.style.marginLeft = '1rem';
+  toggleButton.addEventListener('click', () => {
+    disabledTooltip.disabled = !disabledTooltip.disabled;
+  });
+  disabledTooltip.parentElement.appendChild(toggleButton);
+</script>
+```
+
+### Focus Trigger
+
+Use the `trigger` attribute with value `focus` to show the tooltip only when the anchor element receives focus.
+
+```html:preview
+<zn-tooltip content="Focus on the input to see this" trigger="focus">
+  <zn-input placeholder="Focus me"></zn-input>
+</zn-tooltip>
+```
+
+### Hover and Focus Trigger
+
+The default trigger is `hover focus`, which shows the tooltip on both hover and focus events.
+
+```html:preview
+<zn-tooltip content="Hover or focus to see this" trigger="hover focus">
+  <zn-button>Hover or Focus</zn-button>
+</zn-tooltip>
+```
+
+### Multiple Trigger Types
+
+You can combine multiple trigger types by separating them with spaces.
+
+```html:preview
+<div style="display: flex; gap: 1rem;">
+  <zn-tooltip content="Hover only" trigger="hover">
+    <zn-button>Hover</zn-button>
+  </zn-tooltip>
+
+  <zn-tooltip content="Click only" trigger="click">
+    <zn-button>Click</zn-button>
+  </zn-tooltip>
+
+  <zn-tooltip content="Focus only" trigger="focus">
+    <zn-button>Focus</zn-button>
+  </zn-tooltip>
+
+  <zn-tooltip content="Hover and click" trigger="hover click">
+    <zn-button>Hover & Click</zn-button>
+  </zn-tooltip>
+</div>
+```
+
+## Events
+
+Tooltips emit events when they show and hide, allowing you to respond to these state changes.
+
+### Show and Hide Events
+
+The `zn-show` event is emitted when the tooltip begins to show, and `zn-hide` is emitted when it begins to hide.
+
+```html:preview
+<div class="tooltip-events">
+  <zn-tooltip content="Hover me to trigger events">
+    <zn-button>Event Demo</zn-button>
+  </zn-tooltip>
+
+  <div class="event-log">
+    <strong>Event Log:</strong>
+    <ul id="event-list"></ul>
+  </div>
+</div>
+
+<script>
+  const tooltip = document.querySelector('.tooltip-events zn-tooltip');
+  const eventList = document.getElementById('event-list');
+
+  ['zn-show', 'zn-after-show', 'zn-hide', 'zn-after-hide'].forEach(eventName => {
+    tooltip.addEventListener(eventName, () => {
+      const li = document.createElement('li');
+      li.textContent = `${eventName} - ${new Date().toLocaleTimeString()}`;
+      eventList.insertBefore(li, eventList.firstChild);
+
+      // Keep only last 5 events
+      if (eventList.children.length > 5) {
+        eventList.removeChild(eventList.lastChild);
+      }
+    });
+  });
+</script>
+
+<style>
+  .tooltip-events {
+    display: flex;
+    gap: 2rem;
+    align-items: start;
+  }
+
+  .event-log {
+    background: var(--zn-color-neutral-50);
+    padding: 1rem;
+    border-radius: 4px;
+    min-width: 300px;
+  }
+
+  .event-log ul {
+    list-style: none;
+    padding: 0;
+    margin: 0.5rem 0 0 0;
+    font-size: 0.875rem;
+  }
+
+  .event-log li {
+    padding: 0.25rem 0;
+    border-bottom: 1px solid var(--zn-color-neutral-200);
+  }
+
+  .event-log li:last-child {
+    border-bottom: none;
+  }
+</style>
+```
+
+### After Show and After Hide Events
+
+The `zn-after-show` event is emitted after the tooltip is fully shown, and `zn-after-hide` is emitted after it is fully hidden.
+
+```html:preview
+<zn-tooltip content="Open and close events">
+  <zn-button id="after-events-btn">After Events Demo</zn-button>
+</zn-tooltip>
+
+<div id="after-events-status" style="margin-top: 1rem; padding: 0.5rem; background: var(--zn-color-neutral-100); border-radius: 4px;">
+  Status: <span id="status-text">Ready</span>
+</div>
+
+<script>
+  const afterTooltip = document.querySelector('#after-events-btn').parentElement;
+  const statusText = document.getElementById('status-text');
+
+  afterTooltip.addEventListener('zn-after-show', () => {
+    statusText.textContent = 'Tooltip fully shown';
+    statusText.style.color = 'var(--zn-color-success-600)';
+  });
+
+  afterTooltip.addEventListener('zn-after-hide', () => {
+    statusText.textContent = 'Tooltip fully hidden';
+    statusText.style.color = 'var(--zn-color-neutral-600)';
+  });
+</script>
+```
+
+## Methods
+
+Tooltips provide methods to programmatically control their visibility.
+
+### Show Method
+
+Call the `show()` method to display the tooltip programmatically. This method returns a promise that resolves after the `zn-after-show` event is emitted.
+
+```html:preview
+<zn-button id="show-method-btn">Show Tooltip Programmatically</zn-button>
+
+<zn-tooltip content="Programmatically shown!" trigger="manual" class="show-method-tooltip">
+  <zn-icon src="info" size="24"></zn-icon>
+</zn-tooltip>
+
+<script>
+  const showBtn = document.getElementById('show-method-btn');
+  const showTooltip = document.querySelector('.show-method-tooltip');
+
+  showBtn.addEventListener('click', async () => {
+    await showTooltip.show();
+    console.log('Tooltip is now visible');
+
+    // Automatically hide after 3 seconds
+    setTimeout(() => {
+      showTooltip.hide();
+    }, 3000);
+  });
+</script>
+```
+
+### Hide Method
+
+Call the `hide()` method to hide the tooltip programmatically.
+
+```html:preview
+<div style="display: flex; gap: 1rem; align-items: center;">
+  <zn-button id="toggle-show-btn">Show</zn-button>
+  <zn-button id="toggle-hide-btn" color="error">Hide</zn-button>
+
+  <zn-tooltip content="Control me with buttons!" trigger="manual" class="hide-method-tooltip">
+    <zn-icon src="star" size="32"></zn-icon>
+  </zn-tooltip>
+</div>
+
+<script>
+  const hideTooltip = document.querySelector('.hide-method-tooltip');
+  const showMethodBtn = document.getElementById('toggle-show-btn');
+  const hideMethodBtn = document.getElementById('toggle-hide-btn');
+
+  showMethodBtn.addEventListener('click', () => {
+    hideTooltip.show();
+  });
+
+  hideMethodBtn.addEventListener('click', () => {
+    hideTooltip.hide();
+  });
+</script>
+```
+
+## Slots
+
+Tooltips provide slots for customizing content and defining the anchor element.
+
+### Default Slot (Content)
+
+The default slot or the `content` slot can be used to add content to the tooltip. Use the slot for HTML content and the `content` attribute for simple text.
+
+```html:preview
+<zn-tooltip>
+  <div slot="content">
+    <strong>Rich Content</strong>
+    <p style="margin: 0.25rem 0 0 0;">This tooltip contains <em>formatted</em> text!</p>
+  </div>
+  <zn-button>Rich Tooltip</zn-button>
+</zn-tooltip>
+```
+
+### Anchor Slot
+
+The anchor slot (default unnamed slot) defines the element that triggers the tooltip. This should be a single element.
+
+```html:preview
+<zn-tooltip content="I'm anchored to this icon">
+  <zn-icon src="help_outline" size="32"></zn-icon>
+</zn-tooltip>
+
+<zn-tooltip content="I'm anchored to this input" style="margin-left: 2rem;">
+  <zn-input placeholder="Hover over me"></zn-input>
+</zn-tooltip>
+```
+
+### Complex Anchor
+
+When you need multiple elements as the anchor, wrap them in a container.
+
+```html:preview
+<zn-tooltip content="This tooltip anchors to the entire group">
+  <div style="display: flex; gap: 0.5rem; align-items: center;">
+    <zn-icon src="account_circle" size="24"></zn-icon>
+    <span>John Doe</span>
+    <zn-icon src="verified" size="20"></zn-icon>
+  </div>
+</zn-tooltip>
+```
+
+## CSS Custom Properties
+
+Tooltips can be customized using CSS custom properties.
+
+### Arrow Size
+
+Control the size of the tooltip arrow using the `--zn-tooltip-arrow-size` custom property.
+
+```html:preview
+<div style="display: flex; gap: 1rem;">
+  <zn-tooltip content="Default arrow">
+    <zn-button>Default</zn-button>
+  </zn-tooltip>
+
+  <zn-tooltip content="Large arrow" style="--zn-tooltip-arrow-size: 12px;">
+    <zn-button>Large Arrow</zn-button>
+  </zn-tooltip>
+
+  <zn-tooltip content="Extra large arrow" style="--zn-tooltip-arrow-size: 16px;">
+    <zn-button>XL Arrow</zn-button>
+  </zn-tooltip>
+</div>
+```
+
+### Background and Text Color
+
+Customize the tooltip appearance with CSS custom properties.
+
+```html:preview
+<div style="display: flex; gap: 1rem;">
+  <zn-tooltip
+    content="Custom styled tooltip"
+    style="
+      --zn-tooltip-background-color: var(--zn-color-success-600);
+      --zn-tooltip-color: white;
+    ">
+    <zn-button color="success">Success Style</zn-button>
+  </zn-tooltip>
+
+  <zn-tooltip
+    content="Error tooltip"
+    style="
+      --zn-tooltip-background-color: var(--zn-color-error-600);
+      --zn-tooltip-color: white;
+    ">
+    <zn-button color="error">Error Style</zn-button>
+  </zn-tooltip>
+</div>
+```
+
+## Accessibility
+
+Tooltips are built with accessibility in mind:
+
+- The tooltip uses `role="tooltip"` for proper semantics
+- The tooltip content has `aria-live="polite"` when open to announce changes to screen readers
+- Keyboard navigation is supported with Escape key to dismiss
+- Focus management works with the `focus` trigger option
+
+### Keyboard Support
+
+When a tooltip is open, you can press the `Escape` key to hide it.
+
+```html:preview
+<zn-tooltip content="Press Escape to close" trigger="click">
+  <zn-button>Click me, then press Escape</zn-button>
+</zn-tooltip>
 ```

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

@@ -0,0 +1,210 @@
+---
+meta:
+  title: Translation Group
+  description: A panel-styled container that provides a shared language toggle for multiple translation inputs.
+layout: component
+---
+
+The Translation Group component wraps multiple `zn-translations` components in a panel-styled container with a shared
+language toggle. A button group in the top right lets users switch between languages, controlling all child translation
+inputs simultaneously.
+
+```html:preview
+<zn-translation-group
+  label="Product Content"
+  languages='{"en":"English","fr":"French","de":"German"}'>
+  <zn-translations
+    label="Name"
+    name="name"
+    values='{"en":"Wireless Headphones","fr":"Écouteurs sans fil","de":"Kabellose Kopfhörer"}'
+  ></zn-translations>
+  <zn-translations
+    label="Description"
+    name="description"
+    values='{"en":"Premium noise-cancelling headphones","fr":"Écouteurs antibruit premium","de":"Premium-Kopfhörer mit Geräuschunterdrückung"}'
+  ></zn-translations>
+</zn-translation-group>
+```
+
+## Examples
+
+### Basic Usage
+
+A translation group with two translation inputs sharing one language button group.
+
+```html:preview
+<zn-translation-group languages='{"en":"English","fr":"French"}'>
+  <zn-translations label="Title" name="title"></zn-translations>
+  <zn-translations label="Subtitle" name="subtitle"></zn-translations>
+</zn-translation-group>
+```
+
+### With Label
+
+Use the `label` attribute to add a descriptive label in the panel header, displayed on the left side alongside the language toggle.
+
+```html:preview
+<zn-translation-group
+  label="Page Translations"
+  languages='{"en":"English","fr":"French","es":"Spanish"}'>
+  <zn-translations label="Heading" name="heading"></zn-translations>
+  <zn-translations label="Body" name="body"></zn-translations>
+</zn-translation-group>
+```
+
+### Pre-filled Values
+
+Set initial translations on each child. The group automatically collects all language codes from children and displays
+them as buttons in the toggle group.
+
+```html:preview
+<zn-translation-group
+  label="Notification Templates"
+  languages='{"en":"English","fr":"French","de":"German","es":"Spanish"}'>
+  <zn-translations
+    label="Subject"
+    name="subject"
+    values='{"en":"Welcome aboard!","fr":"Bienvenue !","de":"Willkommen!","es":"Bienvenido!"}'
+  ></zn-translations>
+  <zn-translations
+    label="Preview Text"
+    name="preview"
+    values='{"en":"Get started with your account","fr":"Commencez avec votre compte","de":"Starten Sie mit Ihrem Konto","es":"Comience con su cuenta"}'
+  ></zn-translations>
+</zn-translation-group>
+```
+
+### Many Fields
+
+The group scales well with multiple translation inputs under a single toggle.
+
+```html:preview
+<zn-translation-group
+  label="SEO Metadata"
+  languages='{"en":"English","fr":"French","de":"German"}'>
+  <zn-translations label="Page Title" name="seo-title"></zn-translations>
+  <zn-translations label="Meta Description" name="seo-description"></zn-translations>
+  <zn-translations label="Open Graph Title" name="og-title"></zn-translations>
+  <zn-translations label="Open Graph Description" name="og-description"></zn-translations>
+</zn-translation-group>
+```
+
+### Flush Layout
+
+Remove body padding for a more compact appearance using the `flush` attribute.
+
+```html:preview
+<zn-translation-group
+  flush
+  label="Compact Translations"
+  languages='{"en":"English","fr":"French"}'>
+  <zn-translations label="Label" name="label"></zn-translations>
+  <zn-translations label="Placeholder" name="placeholder"></zn-translations>
+</zn-translation-group>
+```
+
+### Listening to Language Changes
+
+The group emits a `zn-language-change` event when the active language changes.
+
+```html:preview
+<zn-translation-group
+  id="group-events"
+  label="Event Demo"
+  languages='{"en":"English","fr":"French","de":"German"}'>
+  <zn-translations label="Title" name="title"></zn-translations>
+  <zn-translations label="Description" name="description"></zn-translations>
+</zn-translation-group>
+
+<div style="margin-top: 1rem; padding: 1rem; background: var(--zn-color-neutral-50); border-radius: 4px;">
+  <strong>Active Language:</strong>
+  <span id="active-lang" style="font-family: monospace;">en</span>
+</div>
+
+<script type="module">
+  const group = document.getElementById('group-events');
+  const display = document.getElementById('active-lang');
+
+  group.addEventListener('zn-language-change', (event) => {
+    display.textContent = event.detail.language;
+  });
+</script>
+```
+
+### Real-World Use Case: Product Content Management
+
+A complete example showing how the translation group simplifies a product editing form.
+
+```html:preview
+<div style="max-width: 800px;">
+  <zn-panel caption="Product Details" icon="inventory_2">
+    <div style="display: flex; flex-direction: column; gap: 1rem;">
+      <zn-input
+        label="Product SKU"
+        value="PROD-12345"
+        readonly
+      ></zn-input>
+
+      <zn-translation-group
+        label="Translatable Content"
+        languages='{"en":"English","fr":"French","de":"German","es":"Spanish"}'>
+        <zn-translations
+          name="name"
+          label="Product Name"
+          values='{"en":"Premium Wireless Headphones","fr":"Écouteurs sans fil premium","de":"Premium kabellose Kopfhörer","es":"Auriculares inalámbricos premium"}'
+        ></zn-translations>
+        <zn-translations
+          name="short-description"
+          label="Short Description"
+          values='{"en":"High-quality wireless audio","fr":"Audio sans fil haute qualité","de":"Hochwertiges kabelloses Audio","es":"Audio inalámbrico de alta calidad"}'
+        ></zn-translations>
+        <zn-translations
+          name="description"
+          label="Full Description"
+          values='{"en":"Experience premium sound with active noise cancellation","fr":"Découvrez un son premium avec suppression active du bruit","de":"Erleben Sie Premium-Sound mit aktiver Geräuschunterdrückung","es":"Experimente sonido premium con cancelación activa de ruido"}'
+        ></zn-translations>
+      </zn-translation-group>
+
+      <zn-input
+        label="Price"
+        type="currency"
+        value="299.99"
+      ></zn-input>
+    </div>
+
+    <div slot="footer" style="display: flex; gap: 0.5rem; justify-content: flex-end;">
+      <zn-button color="secondary">Cancel</zn-button>
+      <zn-button color="success">Save Product</zn-button>
+    </div>
+  </zn-panel>
+</div>
+```
+
+## Properties
+
+| Property    | Type                     | Default      | Description                                            |
+|-------------|--------------------------|--------------|--------------------------------------------------------|
+| `label`     | `string`                 | `''`         | Label displayed in the panel header                    |
+| `languages` | `Record<string, string>` | `{en: "EN"}` | Object mapping language codes to display names          |
+| `flush`     | `boolean`                | `false`      | Removes body padding for compact layout                |
+
+## Events
+
+| Event                | Description                              | Event Detail           |
+|----------------------|------------------------------------------|------------------------|
+| `zn-language-change` | Emitted when the active language changes | `{ language: string }` |
+
+## Slots
+
+| Slot      | Description                                                |
+|-----------|------------------------------------------------------------|
+| (default) | Place `<zn-translations>` elements here                    |
+| `label`   | Alternative to the `label` attribute for rich HTML content |
+
+## CSS Parts
+
+| Part           | Description                                             |
+|----------------|---------------------------------------------------------|
+| `base`         | The outer panel wrapper                                 |
+| `header`       | The header area containing the label and language toggle |
+| `translations` | The body container wrapping the slotted children        |