@nuvia-ui/components 4.0.1

package/src/ds-tooltip/ds-tooltip.a11y.test.js

@@ -0,0 +1,110 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import axe from 'axe-core';
+import './ds-tooltip.js';
+
+describe('ds-tooltip a11y', () => {
+    let container;
+
+    beforeEach(() => {
+        container = document.createElement('div');
+        document.body.appendChild(container);
+    });
+
+    afterEach(() => {
+        container.remove();
+    });
+
+    it('should pass axe accessibility checks for simple tooltip', async () => {
+        container.innerHTML = '<ds-tooltip content="Accessible tooltip"><button>Trigger</button></ds-tooltip>';
+        await new Promise(resolve => setTimeout(resolve, 100));
+
+        const options = {
+            rules: {
+                'color-contrast': { enabled: false }
+            }
+        };
+
+        const results = await axe.run(container, options);
+        if (results.violations.length > 0) {
+            console.log('Violations:', JSON.stringify(results.violations, null, 2));
+        }
+        expect(results.violations).toHaveLength(0);
+    });
+
+    it('should pass axe accessibility checks for custom tooltip with header and body', async () => {
+        container.innerHTML = `
+            <ds-tooltip>
+                <button>Trigger</button>
+                <div slot="header">Header Text</div>
+                <div slot="body">Body Text</div>
+            </ds-tooltip>
+        `;
+        await new Promise(resolve => setTimeout(resolve, 100));
+
+        const options = {
+            rules: {
+                'color-contrast': { enabled: false }
+            }
+        };
+
+        const results = await axe.run(container, options);
+        if (results.violations.length > 0) {
+            console.log('Violations:', JSON.stringify(results.violations, null, 2));
+        }
+        expect(results.violations).toHaveLength(0);
+    });
+
+    it('should pass axe accessibility checks for all placement variants', async () => {
+        const placements = ['top', 'bottom', 'left', 'right', 'top-start', 'bottom-end'];
+
+        const options = {
+            rules: {
+                'color-contrast': { enabled: false }
+            }
+        };
+
+        for (const placement of placements) {
+            container.innerHTML = `<ds-tooltip placement="${placement}" content="Test tooltip"><button>Test</button></ds-tooltip>`;
+            await new Promise(resolve => setTimeout(resolve, 100));
+
+            const results = await axe.run(container, options);
+            if (results.violations.length > 0) {
+                console.log(`Violations for placement ${placement}:`, JSON.stringify(results.violations, null, 2));
+            }
+            expect(results.violations).toHaveLength(0);
+        }
+    });
+
+    it('should have proper ARIA attributes', async () => {
+        container.innerHTML = '<ds-tooltip content="Test tooltip"><button id="trigger">Trigger</button></ds-tooltip>';
+        const el = container.querySelector('ds-tooltip');
+        await new Promise(resolve => setTimeout(resolve, 100));
+
+        const tooltip = el.shadowRoot.querySelector('#tooltip');
+        const slot = el.shadowRoot.querySelector('slot:not([name])');
+
+        // Check that tooltip has role="tooltip"
+        expect(tooltip.getAttribute('role')).toBe('tooltip');
+
+        // Check that slot has aria-describedby
+        expect(slot.getAttribute('aria-describedby')).toBe('tooltip');
+    });
+
+    it('should be keyboard accessible', async () => {
+        container.innerHTML = '<ds-tooltip content="Test tooltip"><button tabindex="0">Focus me</button></ds-tooltip>';
+        await new Promise(resolve => setTimeout(resolve, 100));
+
+        const options = {
+            rules: {
+                'color-contrast': { enabled: false }
+            }
+        };
+
+        const results = await axe.run(container, options);
+        expect(results.violations).toHaveLength(0);
+
+        // Verify button is focusable
+        const button = container.querySelector('button');
+        expect(button.tabIndex).toBe(0);
+    });
+});

package/src/ds-tooltip/ds-tooltip.js

@@ -0,0 +1,217 @@
+import { LitElement, html, css } from 'lit';
+import { PositionerController } from './positioner.js';
+
+/**
+ * @summary Tooltip component for displaying contextual information.
+ *
+ * @slot - The trigger element (e.g., a button or icon).
+ * @slot header - Optional header content for the custom tooltip variant.
+ * @slot body - Optional body content for the custom tooltip variant.
+ *
+ * @cssprop --ds-tooltip-z-index - Z-index for the tooltip (default: var(--ds-zindex-tooltip))
+ */
+export class DsTooltip extends LitElement {
+  static properties = {
+    placement: { type: String },
+    content: { type: String },
+    manual: { type: Boolean }, // When true, tooltip is controlled programmatically
+    _open: { state: true },
+  };
+
+  constructor() {
+    super();
+    this.placement = 'top';
+    this.content = '';
+    this.manual = false;
+    this._open = false;
+    this.positioner = new PositionerController(this);
+    this._triggerElements = [];
+  }
+
+  disconnectedCallback() {
+    super.disconnectedCallback();
+    this._removeEventListeners();
+  }
+
+  static styles = css`
+    :host {
+      display: inline-block;
+      position: relative;
+    }
+
+    /* The tooltip container */
+    .tooltip {
+      position: absolute; /* Absolute within the host container */
+      top: 0;
+      left: 0;
+      width: max-content;
+      max-width: 300px;
+      
+      background-color: var(--ds-color-bg-default);
+      color: var(--ds-color-text-default);
+      
+      /* Typography */
+      font: var(--ds-typo-content-body-regular);
+      
+      /* Spacing & Shape */
+      padding: var(--ds-space-md); /* 16px */
+      border-radius: var(--ds-radius-container);
+      
+      /* Shadow */
+      box-shadow: var(--ds-elevation-floating);
+      
+      /* Visibility */
+      display: none;
+      z-index: var(--ds-zindex-tooltip, 1000);
+      
+      /* Prevent mouse interaction with tooltip itself (optional, but good for simple tooltips) 
+         Use pointer-events: auto if we want interactive tooltips (e.g. links inside)
+      */
+      pointer-events: none;
+    }
+
+    .tooltip[data-show] {
+      display: block;
+    }
+
+    /* Content Layout */
+    .content-wrapper {
+      display: flex;
+      flex-direction: column;
+      gap: var(--ds-space-xs); /* Inner spacing if needed, but requirements say logic for divider */
+    }
+
+    /* Custom variant: Header & Body handling */
+    .header {
+        font: var(--ds-typo-content-body-bold);
+        margin-bottom: var(--ds-space-xs);
+    }
+
+    .divider {
+      height: 1px;
+      background-color: var(--ds-color-border-default);
+      width: 100%;
+      /* Negative margins to span full width including padding? 
+         Requirement: "divider que vai de uma ponta a ponta. Mantendo o espaço de 16 pixels."
+         This implies the divider should be inside the padding or the padding is around the content?
+         "divisão entre o header e o body... divider vai de ponta a ponta" often means full bleed.
+         If padding is on container, full bleed needs negative margins. 
+      */
+      margin-left: calc(var(--ds-space-md) * -1);
+      width: calc(100% + (var(--ds-space-md) * 2));
+      margin-top: var(--ds-space-xs);
+      margin-bottom: var(--ds-space-xs);
+    }
+  `;
+
+  firstUpdated() {
+    // Set up trigger and target for positioner
+    const tooltipEl = this.shadowRoot.getElementById('tooltip');
+
+    // Use the host element as reference. This ensures correct positioning
+    // even when the tooltip is inside another Shadow DOM (e.g., ds-input).
+    // Floating UI will calculate coordinates relative to the host's bounding box.
+    this.positioner.target = this;
+    this.positioner.floating = tooltipEl;
+    this.positioner.placement = this.placement;
+
+    // Only add automatic event listeners if not in manual mode
+    if (!this.manual) {
+      this._addEventListeners();
+    }
+  }
+
+  updated(changedProperties) {
+    if (changedProperties.has('placement')) {
+      this.positioner.placement = this.placement;
+    }
+  }
+
+  _addEventListeners() {
+    // Get the default slot to find the trigger element(s)
+    const slot = this.shadowRoot.querySelector('slot:not([name])');
+    this._triggerElements = slot.assignedElements({ flatten: true });
+
+    // Attach events to each slotted trigger element
+    this._triggerElements.forEach(trigger => {
+      trigger.addEventListener('mouseenter', this._show);
+      trigger.addEventListener('mouseleave', this._hide);
+      trigger.addEventListener('focusin', this._show);
+      trigger.addEventListener('focusout', this._hide);
+    });
+
+    // Also listen on the host as fallback for empty slots or direct interactions
+    this.addEventListener('mouseenter', this._show);
+    this.addEventListener('mouseleave', this._hide);
+    this.addEventListener('focusin', this._show);
+    this.addEventListener('focusout', this._hide);
+  }
+
+  _removeEventListeners() {
+    // Remove listeners from trigger elements
+    this._triggerElements.forEach(trigger => {
+      trigger.removeEventListener('mouseenter', this._show);
+      trigger.removeEventListener('mouseleave', this._hide);
+      trigger.removeEventListener('focusin', this._show);
+      trigger.removeEventListener('focusout', this._hide);
+    });
+
+    // Remove listeners from host
+    this.removeEventListener('mouseenter', this._show);
+    this.removeEventListener('mouseleave', this._hide);
+    this.removeEventListener('focusin', this._show);
+    this.removeEventListener('focusout', this._hide);
+  }
+
+  _show = () => {
+    this._open = true;
+  }
+
+  _hide = () => {
+    this._open = false;
+  }
+
+  render() {
+    return html`
+      <!-- Trigger Slot -->
+      <slot aria-describedby="tooltip"></slot>
+
+      <!-- Tooltip Container -->
+      <div 
+        id="tooltip" 
+        class="tooltip" 
+        role="tooltip" 
+        ?data-show=${this._open}
+      >
+        ${this.content
+        ? html`${this.content}`
+        : html`
+              <div class="content-wrapper">
+                <slot name="header" @slotchange=${this._handleSlotChange}></slot>
+                ${this._hasHeader && this._hasBody
+            ? html`<div class="divider"></div>`
+            : ''}
+                <slot name="body" @slotchange=${this._handleSlotChange}></slot>
+              </div>
+            `
+      }
+      </div>
+    `;
+  }
+
+  get _hasHeader() {
+    const slot = this.shadowRoot.querySelector('slot[name="header"]');
+    return slot && slot.assignedNodes().length > 0;
+  }
+
+  get _hasBody() {
+    const slot = this.shadowRoot.querySelector('slot[name="body"]');
+    return slot && slot.assignedNodes().length > 0;
+  }
+
+  _handleSlotChange() {
+    this.requestUpdate();
+  }
+}
+
+customElements.define('ds-tooltip', DsTooltip);

package/src/ds-tooltip/ds-tooltip.mdx

@@ -0,0 +1,75 @@
+import { Meta, Canvas, Controls } from '@storybook/blocks';
+import * as TooltipStories from './ds-tooltip.stories';
+
+<Meta of={TooltipStories} />
+
+# Tooltip
+
+Tooltips provide additional, contextual information when users hover over or focus on an element.
+
+## Playground
+
+<Canvas of={TooltipStories.Simple} />
+<Controls of={TooltipStories.Simple} />
+
+## Usage
+
+Use tooltips to clarify actions, icons, or truncated text. Do not use them for essential information that users need to complete a task.
+
+```html
+<ds-tooltip content="Copy to clipboard">
+  <ds-button icon="copy"></ds-button>
+</ds-tooltip>
+```
+
+## Variants
+
+### Simple (Text Only)
+
+For short descriptions, use the `content` attribute.
+
+<Canvas of={TooltipStories.Simple} />
+
+### Custom (Header + Body)
+
+For more complex information, use the `header` and `body` slots. A divider will automatically appear between them if both are present.
+
+<Canvas of={TooltipStories.Custom} />
+
+## Positioning
+
+The tooltip supports robust positioning options using the `placement` attribute. You can specify main directions (`top`, `bottom`, `left`, `right`) and combine them with alignment suffixes (`-start`, `-end`) to precisely control where the tooltip appears relative to the trigger.
+
+- **Main Directions**: `top`, `bottom`, `left`, `right`
+- **Alignments**: 
+    - `-start`: Aligns to the start (left/top) of the trigger.
+    - `-end`: Aligns to the end (right/bottom) of the trigger.
+- **Auto**: `auto` (automatically finds the best position).
+
+### Examples
+
+- `right-start`: Places tooltip to the right, aligned to the top edge.
+- `top-end`: Places tooltip above, aligned to the right edge.
+
+<Canvas of={TooltipStories.AlignmentVariations} />
+
+## Accessibility
+
+- The tooltip triggers on both `hover` and `keyboard focus`.
+- It automatically handles `ARIA` attributes (`role="tooltip"`).
+- Dismissal occurs on `mouseleave` or `focusout`.
+
+## API
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `placement` | string | `'top'` | Position of tooltip relative to trigger |
+| `content` | string | `''` | Text content for simple tooltips |
+
+### Slots
+
+| Name | Description |
+|------|-------------|
+| (default) | The trigger element |
+| `header` | Optional header content (styled with Body Bold) |
+| `body` | Optional body content |

package/src/ds-tooltip/ds-tooltip.stories.js

@@ -0,0 +1,72 @@
+import { html } from 'lit';
+import './index.js';
+import '../ds-button/index.js'; // Assuming we have a button to use as trigger
+
+export default {
+  title: 'Components/Tooltip',
+  component: 'ds-tooltip',
+  argTypes: {
+    placement: {
+      control: { type: 'select' },
+      options: [
+        'top', 'top-start', 'top-end',
+        'bottom', 'bottom-start', 'bottom-end',
+        'left', 'left-start', 'left-end',
+        'right', 'right-start', 'right-end',
+        'auto'
+      ],
+    },
+    content: { control: 'text' },
+  },
+};
+
+const Template = ({ placement, content }) => html`
+  <div style="display: flex; justify-content: center; align-items: center; height: 300px;">
+    <ds-tooltip placement=${placement} content=${content}>
+      <ds-button>Hover me</ds-button>
+    </ds-tooltip>
+  </div>
+`;
+
+export const Simple = Template.bind({});
+Simple.args = {
+  placement: 'top',
+  content: 'This is a simple tooltip',
+};
+
+export const Custom = () => html`
+  <div style="display: flex; justify-content: center; align-items: center; height: 300px;">
+    <ds-tooltip placement="bottom">
+      <ds-button variant="secondary">Hover for Details</ds-button>
+      <div slot="header">Tooltip Header</div>
+      <div slot="body">
+        This is the body content of the tooltip. It has more details.
+      </div>
+    </ds-tooltip>
+  </div>
+`;
+
+export const AlignmentVariations = () => html`
+  <div style="display: grid; grid-template-columns: 1fr 1fr; gap: 80px; padding: 100px; justify-items: center;">
+    
+    <!-- Right Start: To the right, aligned top -->
+    <ds-tooltip placement="right-start" content="Right Start">
+      <ds-button>Right-Start</ds-button>
+    </ds-tooltip>
+
+    <!-- Right End: To the right, aligned bottom -->
+    <ds-tooltip placement="right-end" content="Right End">
+      <ds-button>Right-End</ds-button>
+    </ds-tooltip>
+
+    <!-- Top Start: Above, aligned left -->
+    <ds-tooltip placement="top-start" content="Top Start">
+      <ds-button>Top-Start</ds-button>
+    </ds-tooltip>
+
+    <!-- Bottom End: Below, aligned right -->
+    <ds-tooltip placement="bottom-end" content="Bottom End">
+      <ds-button>Bottom-End</ds-button>
+    </ds-tooltip>
+  </div>
+`;

package/src/ds-tooltip/ds-tooltip.test.js

@@ -0,0 +1,191 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import './ds-tooltip.js';
+
+describe('ds-tooltip', () => {
+    let container;
+
+    beforeEach(() => {
+        container = document.createElement('div');
+        document.body.appendChild(container);
+    });
+
+    afterEach(() => {
+        container.remove();
+    });
+
+    it('should render with default placement top', async () => {
+        container.innerHTML = '<ds-tooltip content="Test tooltip"><button>Hover me</button></ds-tooltip>';
+        const el = container.querySelector('ds-tooltip');
+        await new Promise(resolve => setTimeout(resolve, 100));
+
+        expect(el.placement).toBe('top');
+        const tooltip = el.shadowRoot.querySelector('#tooltip');
+        expect(tooltip).toBeTruthy();
+    });
+
+    it('should reflect content attribute', async () => {
+        container.innerHTML = '<ds-tooltip content="Simple tooltip"><button>Trigger</button></ds-tooltip>';
+        const el = container.querySelector('ds-tooltip');
+        await new Promise(resolve => setTimeout(resolve, 100));
+
+        expect(el.content).toBe('Simple tooltip');
+        expect(el.getAttribute('content')).toBe('Simple tooltip');
+    });
+
+    it('should support different placements', async () => {
+        const placements = ['top', 'bottom', 'left', 'right', 'top-start', 'top-end', 'auto'];
+
+        for (const placement of placements) {
+            container.innerHTML = `<ds-tooltip placement="${placement}" content="Test"><button>Test</button></ds-tooltip>`;
+            const el = container.querySelector('ds-tooltip');
+            await new Promise(resolve => setTimeout(resolve, 100));
+
+            expect(el.placement).toBe(placement);
+        }
+    });
+
+    it('should show tooltip when _open is true', async () => {
+        container.innerHTML = '<ds-tooltip content="Test tooltip"><button>Hover me</button></ds-tooltip>';
+        const el = container.querySelector('ds-tooltip');
+        await new Promise(resolve => setTimeout(resolve, 100));
+
+        const tooltip = el.shadowRoot.querySelector('#tooltip');
+        expect(tooltip.hasAttribute('data-show')).toBe(false);
+
+        // Manually trigger open state
+        el._open = true;
+        await el.updateComplete;
+
+        expect(tooltip.hasAttribute('data-show')).toBe(true);
+    });
+
+    it('should hide tooltip when _open is false', async () => {
+        container.innerHTML = '<ds-tooltip content="Test tooltip"><button>Hover me</button></ds-tooltip>';
+        const el = container.querySelector('ds-tooltip');
+        await new Promise(resolve => setTimeout(resolve, 100));
+
+        el._open = true;
+        await el.updateComplete;
+
+        const tooltip = el.shadowRoot.querySelector('#tooltip');
+        expect(tooltip.hasAttribute('data-show')).toBe(true);
+
+        el._open = false;
+        await el.updateComplete;
+
+        expect(tooltip.hasAttribute('data-show')).toBe(false);
+    });
+
+    it('should render custom variant with header and body slots', async () => {
+        container.innerHTML = `
+            <ds-tooltip>
+                <button>Trigger</button>
+                <div slot="header">Header Text</div>
+                <div slot="body">Body Text</div>
+            </ds-tooltip>
+        `;
+        const el = container.querySelector('ds-tooltip');
+        await new Promise(resolve => setTimeout(resolve, 100));
+
+        const slots = el.shadowRoot.querySelectorAll('slot');
+        const headerSlot = el.shadowRoot.querySelector('slot[name="header"]');
+        const bodySlot = el.shadowRoot.querySelector('slot[name="body"]');
+
+        expect(headerSlot).toBeTruthy();
+        expect(bodySlot).toBeTruthy();
+    });
+
+    it('should show divider when both header and body are present', async () => {
+        container.innerHTML = `
+            <ds-tooltip>
+                <button>Trigger</button>
+                <div slot="header">Header</div>
+                <div slot="body">Body</div>
+            </ds-tooltip>
+        `;
+        const el = container.querySelector('ds-tooltip');
+        await new Promise(resolve => setTimeout(resolve, 100));
+
+        // Force open to check divider
+        el._open = true;
+        await el.updateComplete;
+
+        const divider = el.shadowRoot.querySelector('.divider');
+        expect(divider).toBeTruthy();
+    });
+
+    it('should have role="tooltip" on tooltip element', async () => {
+        container.innerHTML = '<ds-tooltip content="Test"><button>Test</button></ds-tooltip>';
+        const el = container.querySelector('ds-tooltip');
+        await new Promise(resolve => setTimeout(resolve, 100));
+
+        const tooltip = el.shadowRoot.querySelector('#tooltip');
+        expect(tooltip.getAttribute('role')).toBe('tooltip');
+    });
+
+    it('should trigger tooltip on mouseenter event', async () => {
+        container.innerHTML = '<ds-tooltip content="Test tooltip"><button id="trigger">Hover me</button></ds-tooltip>';
+        const el = container.querySelector('ds-tooltip');
+        await new Promise(resolve => setTimeout(resolve, 100));
+
+        const button = container.querySelector('#trigger');
+        expect(el._open).toBe(false);
+
+        // Simulate mouseenter
+        button.dispatchEvent(new MouseEvent('mouseenter', { bubbles: true }));
+        await el.updateComplete;
+
+        expect(el._open).toBe(true);
+    });
+
+    it('should hide tooltip on mouseleave event', async () => {
+        container.innerHTML = '<ds-tooltip content="Test tooltip"><button id="trigger">Hover me</button></ds-tooltip>';
+        const el = container.querySelector('ds-tooltip');
+        await new Promise(resolve => setTimeout(resolve, 100));
+
+        const button = container.querySelector('#trigger');
+
+        // Open tooltip
+        button.dispatchEvent(new MouseEvent('mouseenter', { bubbles: true }));
+        await el.updateComplete;
+        expect(el._open).toBe(true);
+
+        // Close tooltip
+        button.dispatchEvent(new MouseEvent('mouseleave', { bubbles: true }));
+        await el.updateComplete;
+        expect(el._open).toBe(false);
+    });
+
+    it('should trigger tooltip on focusin event', async () => {
+        container.innerHTML = '<ds-tooltip content="Test tooltip"><button id="trigger">Focus me</button></ds-tooltip>';
+        const el = container.querySelector('ds-tooltip');
+        await new Promise(resolve => setTimeout(resolve, 100));
+
+        const button = container.querySelector('#trigger');
+        expect(el._open).toBe(false);
+
+        // Simulate focusin
+        button.dispatchEvent(new FocusEvent('focusin', { bubbles: true }));
+        await el.updateComplete;
+
+        expect(el._open).toBe(true);
+    });
+
+    it('should hide tooltip on focusout event', async () => {
+        container.innerHTML = '<ds-tooltip content="Test tooltip"><button id="trigger">Focus me</button></ds-tooltip>';
+        const el = container.querySelector('ds-tooltip');
+        await new Promise(resolve => setTimeout(resolve, 100));
+
+        const button = container.querySelector('#trigger');
+
+        // Open tooltip
+        button.dispatchEvent(new FocusEvent('focusin', { bubbles: true }));
+        await el.updateComplete;
+        expect(el._open).toBe(true);
+
+        // Close tooltip
+        button.dispatchEvent(new FocusEvent('focusout', { bubbles: true }));
+        await el.updateComplete;
+        expect(el._open).toBe(false);
+    });
+});

package/src/ds-tooltip/index.js

@@ -0,0 +1 @@
+export { DsTooltip } from './ds-tooltip.js';