@ptlm-azulejo/tooltip 0.0.1-alpha.95
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +4 -0
- package/README.md +178 -0
- package/dist/index.d.ts +3 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +3235 -0
- package/dist/index.umd.cjs +1 -0
- package/dist/src/index.vue.d.ts +150 -0
- package/dist/src/index.vue.d.ts.map +1 -0
- package/dist/style.css +1 -0
- package/package.json +46 -0
package/CHANGELOG.md
ADDED
package/README.md
ADDED
|
@@ -0,0 +1,178 @@
|
|
|
1
|
+
# Tooltip
|
|
2
|
+
|
|
3
|
+
A tooltip is a small, contextual message that appears when users hover over or
|
|
4
|
+
focus an element, providing additional information without cluttering the
|
|
5
|
+
interface. Also known as hint, info tip, or hover label.
|
|
6
|
+
|
|
7
|
+
Keep the text concise (1–2 lines). Prefer desktop or non-essential use — the
|
|
8
|
+
current pattern is not mobile-friendly.
|
|
9
|
+
|
|
10
|
+
## Installation
|
|
11
|
+
|
|
12
|
+
Install the tooltip, the theme package, and **the font package matching your
|
|
13
|
+
project's brand**:
|
|
14
|
+
|
|
15
|
+
**Leroy Merlin projects**
|
|
16
|
+
|
|
17
|
+
```bash
|
|
18
|
+
npm install @ptlm-azulejo/tooltip @ptlm-azulejo/themes @ptlm-azulejo/fonts-leroy-merlin
|
|
19
|
+
# or
|
|
20
|
+
yarn add @ptlm-azulejo/tooltip @ptlm-azulejo/themes @ptlm-azulejo/fonts-leroy-merlin
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
**Adeo projects**
|
|
24
|
+
|
|
25
|
+
```bash
|
|
26
|
+
npm install @ptlm-azulejo/tooltip @ptlm-azulejo/themes @ptlm-azulejo/fonts-adeo
|
|
27
|
+
# or
|
|
28
|
+
yarn add @ptlm-azulejo/tooltip @ptlm-azulejo/themes @ptlm-azulejo/fonts-adeo
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
## Styles & theming
|
|
32
|
+
|
|
33
|
+
The component ships no colors or typeface of its own — it reads design tokens from
|
|
34
|
+
CSS variables at runtime. Those tokens come from `@ptlm-azulejo/themes`, and **the
|
|
35
|
+
brand is selected by a class on your app's `<html>` element**, so switching brand
|
|
36
|
+
never touches component code.
|
|
37
|
+
|
|
38
|
+
| Project | Preset stylesheet | Root class | Typeface | Font package |
|
|
39
|
+
| --- | --- | --- | --- | --- |
|
|
40
|
+
| Leroy Merlin | `@ptlm-azulejo/themes/presets/leroy-merlin.css` | `preset-lm` | LeroyMerlinSans | `@ptlm-azulejo/fonts-leroy-merlin` |
|
|
41
|
+
| Adeo | `@ptlm-azulejo/themes/presets/adeo.css` | `preset-adeo` | Roboto | `@ptlm-azulejo/fonts-adeo` |
|
|
42
|
+
|
|
43
|
+
**Leroy Merlin projects**
|
|
44
|
+
|
|
45
|
+
```js
|
|
46
|
+
import '@ptlm-azulejo/themes/presets/leroy-merlin.css'
|
|
47
|
+
import '@ptlm-azulejo/fonts-leroy-merlin'
|
|
48
|
+
import '@ptlm-azulejo/tooltip/style.css'
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
```html
|
|
52
|
+
<html lang="pt" class="preset-lm">
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
**Adeo projects**
|
|
56
|
+
|
|
57
|
+
```js
|
|
58
|
+
import '@ptlm-azulejo/themes/presets/adeo.css'
|
|
59
|
+
import '@ptlm-azulejo/fonts-adeo'
|
|
60
|
+
import '@ptlm-azulejo/tooltip/style.css'
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
```html
|
|
64
|
+
<html lang="pt" class="preset-adeo">
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
> The preset class is what resolves the brand at runtime. Without it — even with
|
|
68
|
+
> the stylesheets imported — the component renders uncolored and in a fallback
|
|
69
|
+
> typeface. See the [themes package](../themes/README.md) for brand switching,
|
|
70
|
+
> dark mode, and custom brands.
|
|
71
|
+
|
|
72
|
+
### Light and dark mode
|
|
73
|
+
|
|
74
|
+
Add `data-theme` alongside the brand class to pin the color scheme. Leave it off
|
|
75
|
+
and the preset follows the OS `prefers-color-scheme`:
|
|
76
|
+
|
|
77
|
+
```html
|
|
78
|
+
<html lang="pt" class="preset-lm" data-theme="dark">
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
### Why the font package is separate
|
|
82
|
+
|
|
83
|
+
The preset only *names* its typeface in `--font-family` and ships no font files.
|
|
84
|
+
[Loading them is your app's job](../themes/README.md#fonts), as with upstream
|
|
85
|
+
Mozaic, so you keep control of hosting, subsetting and preload. Without the
|
|
86
|
+
matching font package, `font-sans` falls back to a generic sans-serif. A
|
|
87
|
+
multi-brand app can install both and switch by swapping the `.preset-*` class:
|
|
88
|
+
only the active brand's file is ever downloaded.
|
|
89
|
+
|
|
90
|
+
### Custom property
|
|
91
|
+
|
|
92
|
+
| Name | Type | Default | Description |
|
|
93
|
+
| --- | --- | --- | --- |
|
|
94
|
+
| `--tooltip-z-index` | `number` | `1` | Customise the z-index of the tooltip bubble |
|
|
95
|
+
|
|
96
|
+
## Props
|
|
97
|
+
|
|
98
|
+
| Name | Type | Default | Description |
|
|
99
|
+
| --- | --- | --- | --- |
|
|
100
|
+
| `id` | `string` | — | Unique id for `aria-describedby` / content `id` (required) |
|
|
101
|
+
| `text` | `string` | — | Tooltip content; keep concise (required) |
|
|
102
|
+
| `position` | `'top' \| 'bottom' \| 'left' \| 'right'` | `'top'` | Position relative to the trigger |
|
|
103
|
+
| `pointer` | `boolean` | `true` | Show the origin arrow pointing at the trigger |
|
|
104
|
+
| `helpCursor` | `boolean` | `false` | Show the help cursor (`?`) on hover / focus |
|
|
105
|
+
| `radius` | `'none' \| 'sm' \| 'md' \| 'lg'` | `'md'` | Bubble border radius (`none` or `--border-radius-s/m/l`) |
|
|
106
|
+
| `standalone` | `boolean` | `false` | Always visible, in normal flow (no hover gate) |
|
|
107
|
+
| `ui` | `TooltipUi` | `{}` | Per-part Tailwind class overrides |
|
|
108
|
+
|
|
109
|
+
### `:ui` keys
|
|
110
|
+
|
|
111
|
+
Pass Tailwind class strings; they **merge** with defaults via `cn()` (conflicting utilities win).
|
|
112
|
+
|
|
113
|
+
| Key | Targets | `data-testid` |
|
|
114
|
+
| --- | --- | --- |
|
|
115
|
+
| `root` | Wrapper around the trigger and bubble | `tooltip` |
|
|
116
|
+
| `content` | The bubble (`role="tooltip"`) | `tooltip-content` |
|
|
117
|
+
| `text` | The label inside the bubble | `tooltip-text` |
|
|
118
|
+
| `pointer` | Origin arrow on the bubble edge | `tooltip-pointer` |
|
|
119
|
+
|
|
120
|
+
```vue
|
|
121
|
+
<AzTooltip
|
|
122
|
+
id="styled-tip"
|
|
123
|
+
text="Custom look"
|
|
124
|
+
standalone
|
|
125
|
+
:ui="{
|
|
126
|
+
root: 'shadow-lg',
|
|
127
|
+
content: 'bg-[color:var(--color-background-accent-inverse)] border-transparent',
|
|
128
|
+
text: 'uppercase tracking-wide',
|
|
129
|
+
pointer: 'bg-[color:var(--color-background-accent-inverse)] border-transparent',
|
|
130
|
+
}"
|
|
131
|
+
>
|
|
132
|
+
Trigger
|
|
133
|
+
</AzTooltip>
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
When you recolour `content`, recolour `pointer` the same way so the arrow stays connected.
|
|
137
|
+
|
|
138
|
+
## Accessibility
|
|
139
|
+
|
|
140
|
+
Aligned with the [ARIA tooltip pattern](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tooltip_role) and WCAG **1.4.13 Content on Hover or Focus**:
|
|
141
|
+
|
|
142
|
+
| Requirement | Behavior |
|
|
143
|
+
| --- | --- |
|
|
144
|
+
| Name / role | Bubble has `role="tooltip"` and a stable `id` |
|
|
145
|
+
| Relationship | `aria-describedby` is set on the **owning control** — a focusable slotted element if present, otherwise the root (`tabindex="0"`) |
|
|
146
|
+
| Keyboard | Opens on focus; Escape dismisses without moving focus |
|
|
147
|
+
| Hoverable | Gap is sized so the arrow bridges trigger → bubble; hover stays on the root |
|
|
148
|
+
| Persistent | Stays open until blur / mouse leave / Escape |
|
|
149
|
+
| Decorative arrow | `aria-hidden="true"` |
|
|
150
|
+
| Non-essential only | Do not put critical information only in the tooltip (touch / some AT may miss it) |
|
|
151
|
+
|
|
152
|
+
## Slots
|
|
153
|
+
|
|
154
|
+
| Name | Description |
|
|
155
|
+
| --- | --- |
|
|
156
|
+
| `default` | The tooltip will point to the content of the slot (the trigger) |
|
|
157
|
+
|
|
158
|
+
## Basic usage
|
|
159
|
+
|
|
160
|
+
```vue
|
|
161
|
+
<script setup>
|
|
162
|
+
import { AzTooltip } from '@ptlm-azulejo/tooltip'
|
|
163
|
+
</script>
|
|
164
|
+
|
|
165
|
+
<template>
|
|
166
|
+
<AzTooltip id="help-tip" text="Keep the tooltip text concise.">
|
|
167
|
+
Hover me
|
|
168
|
+
</AzTooltip>
|
|
169
|
+
</template>
|
|
170
|
+
```
|
|
171
|
+
|
|
172
|
+
With an interactive trigger (the button receives `aria-describedby`):
|
|
173
|
+
|
|
174
|
+
```vue
|
|
175
|
+
<AzTooltip id="save-tip" text="Saves your draft">
|
|
176
|
+
<button type="button">Save</button>
|
|
177
|
+
</AzTooltip>
|
|
178
|
+
```
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,IAAI,SAAS,EAAE,MAAM,iBAAiB,CAAA;AACtD,YAAY,EAAE,eAAe,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA"}
|