feat(component): add tooltip

.stylelintrc.json

@@ -1,4 +1,12 @@
 {
   "extends": ["@juntossomosmais/linters/stylelint.config.scss.js"],
-  "ignoreFiles": ["utils/scss/**"]
+  "ignoreFiles": ["utils/scss/**"],
+  "rules": {
+    "at-rule-no-unknown": [
+      true,
+      {
+        "ignoreAtRules": ["function", "if", "each", "include", "mixin", "else"]
+      }
+    ]
+  }
 }

apps/docs/stories/architecture-decision-records/0014-why-use-popperjs.stories.mdx

@@ -0,0 +1,28 @@
+import { Meta } from '@storybook/addon-docs'
+
+<Meta title='Docs/Architecture Decision Records/ADR 0014: Why PopperJS' />
+
+# ADR 0014: Why PopperJS
+
+🗓️ 2024-11 · ✍️ [@igorwessel](https://github.com/igorwessel)
+
+## Context
+
+It was necessary due to the complexity of modifying the `ion-popover` to meet the tooltip requirements. This involved many changes to the `ion-popover` component to make it behave like a tooltip.
+
+## Problems
+
+These changes included things like:
+
+- Removing a class that locks the scroll on the site (added to the body) when using the `ion-popover`;
+- Adding scroll tracking;
+- Ensuring responsiveness in terms of automatically changing side/directio;
+
+## Decision Drivers
+
+- Bundle Size: The size of the library was considered. If the size was too large, it would be a NO-GO for inclusion in the project. As the entire library currently (2024/11/05) only 8.9KB, we understood that the size would not negatively impact the user experience;
+- Popularity and Maintenance: PopperJS is the most well-known library for handling this type of work. Many libraries that implement some type of "popper" use it to provide this functionality;
+
+## Decision
+
+Based on this, we understood that it does not make sense to spend effort recreating many of the functionalities that PopperJS offers. Given that the library size is small, we decided to add the library to the project to implement our tooltip.

package.json

@@ -31,6 +31,7 @@
   },
   "dependencies": {
     "@ionic/core": "^7.8.6",
+    "@popperjs/core": "^2.11.8",
     "@stencil/core": "~4.17.2"
   },
   "devDependencies": {
@@ -57,7 +58,6 @@
     "@storybook/theming": "^7.6.17",
     "@storybook/vue3": "^7.6.6",
     "@storybook/vue3-vite": "^7.6.6",
-    "@vitejs/plugin-vue": "^5.1.3",
     "@storybook/web-components": "^7.6.17",
     "@storybook/web-components-webpack5": "^7.6.17",
     "@testing-library/jest-dom": "^6.4.8",
@@ -104,6 +104,7 @@
     "tslib": "^2.8.1",
     "typescript": "^5.5.4",
     "vite": "^5.4.2",
+    "@vitejs/plugin-vue": "^5.1.3",
     "vue": "^3.4.38"
   },
   "lint-staged": {

packages/core/src/components.d.ts

@@ -265,6 +265,22 @@ export namespace Components {
         "value"?: IonTypes.IonTextarea['value'];
         "wrap"?: 'hard' | 'soft' | 'off';
     }
+    interface AtomTooltip {
+        "action": 'hover' | 'click';
+        "element": string;
+        "open": boolean;
+        "placement": | 'auto'
+    | 'auto-start'
+    | 'auto-end'
+    | 'top'
+    | 'top-start'
+    | 'top-end'
+    | 'bottom'
+    | 'bottom-start'
+    | 'bottom-end'
+    | 'right'
+    | 'left';
+    }
 }
 export interface AtomAlertCustomEvent<T> extends CustomEvent<T> {
     detail: T;
@@ -306,6 +322,10 @@ export interface AtomTextareaCustomEvent<T> extends CustomEvent<T> {
     detail: T;
     target: HTMLAtomTextareaElement;
 }
+export interface AtomTooltipCustomEvent<T> extends CustomEvent<T> {
+    detail: T;
+    target: HTMLAtomTooltipElement;
+}
 declare global {
     interface HTMLAtomAlertElementEventMap {
         "atomClose": any;
@@ -561,6 +581,24 @@ declare global {
         prototype: HTMLAtomTextareaElement;
         new (): HTMLAtomTextareaElement;
     };
+    interface HTMLAtomTooltipElementEventMap {
+        "atomClose": any;
+        "atomOpen": any;
+    }
+    interface HTMLAtomTooltipElement extends Components.AtomTooltip, HTMLStencilElement {
+        addEventListener<K extends keyof HTMLAtomTooltipElementEventMap>(type: K, listener: (this: HTMLAtomTooltipElement, ev: AtomTooltipCustomEvent<HTMLAtomTooltipElementEventMap[K]>) => any, options?: boolean | AddEventListenerOptions): void;
+        addEventListener<K extends keyof DocumentEventMap>(type: K, listener: (this: Document, ev: DocumentEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void;
+        addEventListener<K extends keyof HTMLElementEventMap>(type: K, listener: (this: HTMLElement, ev: HTMLElementEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void;
+        addEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void;
+        removeEventListener<K extends keyof HTMLAtomTooltipElementEventMap>(type: K, listener: (this: HTMLAtomTooltipElement, ev: AtomTooltipCustomEvent<HTMLAtomTooltipElementEventMap[K]>) => any, options?: boolean | EventListenerOptions): void;
+        removeEventListener<K extends keyof DocumentEventMap>(type: K, listener: (this: Document, ev: DocumentEventMap[K]) => any, options?: boolean | EventListenerOptions): void;
+        removeEventListener<K extends keyof HTMLElementEventMap>(type: K, listener: (this: HTMLElement, ev: HTMLElementEventMap[K]) => any, options?: boolean | EventListenerOptions): void;
+        removeEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | EventListenerOptions): void;
+    }
+    var HTMLAtomTooltipElement: {
+        prototype: HTMLAtomTooltipElement;
+        new (): HTMLAtomTooltipElement;
+    };
     interface HTMLElementTagNameMap {
         "atom-alert": HTMLAtomAlertElement;
         "atom-badge": HTMLAtomBadgeElement;
@@ -582,6 +620,7 @@ declare global {
         "atom-steps-modal": HTMLAtomStepsModalElement;
         "atom-tag": HTMLAtomTagElement;
         "atom-textarea": HTMLAtomTextareaElement;
+        "atom-tooltip": HTMLAtomTooltipElement;
     }
 }
 declare namespace LocalJSX {
@@ -865,6 +904,30 @@ declare namespace LocalJSX {
         "value"?: IonTypes.IonTextarea['value'];
         "wrap"?: 'hard' | 'soft' | 'off';
     }
+    interface AtomTooltip {
+        "action"?: 'hover' | 'click';
+        "element"?: string;
+        /**
+          * Event is dispatched when: 1. Mouse leave event in selector 2. Click "Close" button when is mobile
+         */
+        "onAtomClose"?: (event: AtomTooltipCustomEvent<any>) => void;
+        /**
+          * Event is dispatched when: 1. Mouse enter event in selector 2. Click in element when is mobile
+         */
+        "onAtomOpen"?: (event: AtomTooltipCustomEvent<any>) => void;
+        "open"?: boolean;
+        "placement"?: | 'auto'
+    | 'auto-start'
+    | 'auto-end'
+    | 'top'
+    | 'top-start'
+    | 'top-end'
+    | 'bottom'
+    | 'bottom-start'
+    | 'bottom-end'
+    | 'right'
+    | 'left';
+    }
     interface IntrinsicElements {
         "atom-alert": AtomAlert;
         "atom-badge": AtomBadge;
@@ -886,6 +949,7 @@ declare namespace LocalJSX {
         "atom-steps-modal": AtomStepsModal;
         "atom-tag": AtomTag;
         "atom-textarea": AtomTextarea;
+        "atom-tooltip": AtomTooltip;
     }
 }
 export { LocalJSX as JSX };
@@ -912,6 +976,7 @@ declare module "@stencil/core" {
             "atom-steps-modal": LocalJSX.AtomStepsModal & JSXBase.HTMLAttributes<HTMLAtomStepsModalElement>;
             "atom-tag": LocalJSX.AtomTag & JSXBase.HTMLAttributes<HTMLAtomTagElement>;
             "atom-textarea": LocalJSX.AtomTextarea & JSXBase.HTMLAttributes<HTMLAtomTextareaElement>;
+            "atom-tooltip": LocalJSX.AtomTooltip & JSXBase.HTMLAttributes<HTMLAtomTooltipElement>;
         }
     }
 }

packages/core/src/components/tooltip/stories/tooltip.args.ts

@@ -0,0 +1,94 @@
+import { Category } from '@atomium/storybook-utils/enums/table'
+import { withActions } from '@storybook/addon-actions/decorator'
+
+export const TooltipStoryArgs = {
+  parameters: {
+    actions: {
+      handles: ['atomOpen', 'atomClose'],
+    },
+    decorators: [withActions],
+    docs: {
+      description: {
+        component:
+          'Tooltip is a small pop-up box that appears when a user moves a mouse over an element',
+      },
+    },
+    layout: 'centered',
+  },
+  argTypes: {
+    placement: {
+      control: 'select',
+      defaultValue: { summary: 'top' },
+      options: [
+        'auto',
+        'auto-start',
+        'auto-end',
+        'top',
+        'top-start',
+        'top-end',
+        'bottom',
+        'bottom-start',
+        'bottom-end',
+        'right',
+        'left',
+      ],
+      description: 'Determines placement for tooltip',
+      table: {
+        category: Category.PROPERTIES,
+      },
+    },
+    action: {
+      control: 'select',
+      defaultValue: { summary: 'hover' },
+      options: ['hover', 'click'],
+      description:
+        'Determines the trigger action for the tooltip: `hover` or `click`.',
+      table: {
+        category: Category.PROPERTIES,
+      },
+    },
+    element: {
+      control: 'text',
+      description:
+        'Specifies the element responsible for opening/closing the tooltip.',
+      table: {
+        category: Category.PROPERTIES,
+      },
+    },
+    open: {
+      control: 'boolean',
+      description: 'Controls whether the tooltip is open or closed.',
+      table: {
+        category: Category.PROPERTIES,
+      },
+    },
+    text: {
+      control: 'text',
+      description: 'Determines a text for tooltip.',
+      table: {
+        category: Category.PROPERTIES,
+      },
+    },
+    atomOpen: {
+      description:
+        'Event emitted when hover element, but for mobile when click in element.',
+      table: {
+        category: Category.EVENTS,
+      },
+    },
+    atomClose: {
+      description: 'Event emitted when the tooltip is closed.',
+      table: {
+        category: Category.EVENTS,
+      },
+    },
+  },
+}
+
+export const TooltipComponentArgs = {
+  element: 'atomium-element',
+  placement: 'top',
+  text: 'Tooltip',
+  action: 'hover',
+  open: false,
+}

packages/core/src/components/tooltip/stories/tooltip.core.stories.tsx

@@ -0,0 +1,65 @@
+import { Meta, StoryObj } from '@storybook/web-components'
+import { html } from 'lit'
+
+import { TooltipComponentArgs, TooltipStoryArgs } from './tooltip.args'
+
+const createTooltip = (args, buttonText = 'hover') => {
+  return html`
+    <atom-button
+      fill="solid"
+      size="large"
+      id="${args.element}"
+      aria-describedby="atom-tooltip"
+    >
+      ${buttonText}
+    </atom-button>
+
+    <atom-tooltip
+      id="atom-tooltip"
+      placement="${args.placement}"
+      element="${args.element}"
+      action="${args.action}"
+      open="${args.open}"
+    >
+      ${args.text}
+    </atom-tooltip>
+  `
+}
+
+export default {
+  title: 'Components/Tooltip',
+  component: 'atom-tooltip',
+  ...TooltipStoryArgs,
+} as Meta
+
+export const Hover: StoryObj = {
+  render: (args) => createTooltip(args, 'Hover'),
+  args: {
+    ...TooltipComponentArgs,
+    element: 'hover',
+    placement: 'top',
+    open: false,
+  },
+}
+
+export const Click: StoryObj = {
+  render: (args) => createTooltip(args, 'Click'),
+  args: {
+    ...TooltipComponentArgs,
+    element: 'click',
+    placement: 'top',
+    action: 'click',
+    open: false,
+  },
+}
+
+export const Opened: StoryObj = {
+  render: (args) => createTooltip(args, 'Opened'),
+  args: {
+    ...TooltipComponentArgs,
+    element: 'opened',
+    placement: 'left',
+    action: 'click',
+    open: true,
+  },
+}