@f-ewald/components 1.42.2 → 1.43.0

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.
@@ -0,0 +1,70 @@
1
+ # `<ui-tooltip>`
2
+
3
+ Hover and focus tooltip for its default-slot trigger. The `content` slot
4
+ holds the tooltip body — plain text or rich markup such as a list. It
5
+ appears after `show-delay` on hover and at once on keyboard focus, stays
6
+ open while the pointer is over the tooltip itself, and closes on Escape,
7
+ blur, or when the pointer leaves. It renders in the top layer, so
8
+ scrolling or `overflow: hidden` ancestors never clip it.
9
+
10
+ The trigger is described by the content (`aria-describedby`). A trigger
11
+ with nothing focusable inside (e.g. plain text) makes the tooltip host
12
+ focusable so keyboard users can reach the description too. ARIA references
13
+ can't cross shadow roots, so when the trigger is a custom element whose
14
+ focusable control lives in its own shadow root, screen readers won't
15
+ announce the description on focus; prefer a native trigger such as
16
+ `<button>` when that matters.
17
+
18
+ ## Install
19
+
20
+ ```js
21
+ import "@f-ewald/components/ui-tooltip.js";
22
+ ```
23
+
24
+ ## Usage
25
+
26
+ ```html
27
+ <ui-tooltip>
28
+ <button type="button">Copy link</button>
29
+ <span slot="content">Copies a shareable link to this view</span>
30
+ </ui-tooltip>
31
+ <!-- Plain-text trigger: the tooltip becomes focusable; rich content is fine -->
32
+ <ui-tooltip placement="bottom" show-delay="0">
33
+ <span>Partial snapshot</span>
34
+ <div slot="content">3 work items pending: <ul><li>mp:lap-service</li></ul></div>
35
+ </ui-tooltip>
36
+ ```
37
+
38
+ ## Attributes / properties
39
+
40
+ | Property | Attribute | Type | Default | Description |
41
+ | --- | --- | --- | --- | --- |
42
+ | `placement` | `placement` | `UiTooltipPlacement` | `"top"` | Preferred side of the trigger; flips to the other side when this one lacks room. |
43
+ | `showDelay` | `show-delay` | `number` | `300` | Hover delay in milliseconds before the tooltip appears; keyboard focus shows it at once. |
44
+ | `disabled` | `disabled` | `boolean` | `false` | Suppresses the tooltip and closes it if open. |
45
+ | `open` | _(JS property only)_ | `boolean` | `—` | Whether the tooltip is currently showing. _(read-only)_ |
46
+
47
+ ## Events
48
+
49
+ _None._
50
+
51
+ ## Slots
52
+
53
+ | Slot | Description |
54
+ | --- | --- |
55
+ | `(default)` | The trigger the tooltip describes. |
56
+ | `content` | The tooltip body: plain text or rich markup such as a list. |
57
+
58
+ ## CSS custom properties
59
+
60
+ | Custom property |
61
+ | --- |
62
+ | `--ui-focus-ring` |
63
+ | `--ui-font` |
64
+ | `--ui-font-size-sm` |
65
+ | `--ui-font-weight-regular` |
66
+ | `--ui-line-height-tight` |
67
+ | `--ui-radius-sm` |
68
+ | `--ui-shadow` |
69
+ | `--ui-tooltip` |
70
+ | `--ui-tooltip-text` |
package/llms.txt CHANGED
@@ -369,6 +369,10 @@ Supports two suggestion sources:
369
369
  request. Useful for small/fixed lists, offline use, or tests. Takes
370
370
  priority over `endpoint` whenever it's non-null.
371
371
 
372
+ Each option may also carry a pre-rendered `icon` (shown before the value)
373
+ and a `description` (a smaller, muted line under the value); options
374
+ without them render as a plain value.
375
+
372
376
  Set `clearable` to show an in-field clear action whenever a value is
373
377
  present.
374
378
 
@@ -384,9 +388,12 @@ Example:
384
388
  <autocomplete-input clearable name="language" placeholder="Start typing a language…"></autocomplete-input>
385
389
  </form>
386
390
  <script type="module">
387
- // Local mode: filters client-side, no network request.
391
+ import { iconGlobeAlt } from "@f-ewald/components/icons.js";
392
+
393
+ // Local mode: filters client-side, no network request. `icon` and
394
+ // `description` are optional.
388
395
  document.querySelector("autocomplete-input").options = [
389
- { key: "ts", value: "TypeScript" },
396
+ { key: "ts", value: "TypeScript", icon: iconGlobeAlt(14), description: "Typed superset of JavaScript" },
390
397
  { key: "py", value: "Python" },
391
398
  ];
392
399
 
@@ -1010,6 +1017,9 @@ and one `<tr>` per entry in `rows`, with each cell's content produced by
1010
1017
  `renderCell` (default: plain property lookup on the row object). Knows
1011
1018
  nothing about what a "row" means — callers own the data shape entirely.
1012
1019
 
1020
+ Each column may add a decorative header `icon` and an `align` for its
1021
+ header and cells (`end` right-aligns numbers, with tabular figures).
1022
+
1013
1023
  Optional `rowHref` makes whole rows clickable (navigating via `location.hash`),
1014
1024
  without hijacking clicks on nested interactive elements (links/buttons) a
1015
1025
  cell's rendered content might contain.
@@ -1035,6 +1045,21 @@ Example:
1035
1045
  ];
1036
1046
  table.rowHref = (row) => `#/tasks/${row.id}`;
1037
1047
  </script>
1048
+ <data-table id="packages"></data-table>
1049
+ <script type="module">
1050
+ import { iconArrowLongRight } from "@f-ewald/components/icons.js";
1051
+
1052
+ // Header icons and alignment, e.g. right-aligned numbers.
1053
+ const packages = document.getElementById("packages");
1054
+ packages.columns = [
1055
+ { key: "name", label: "Package" },
1056
+ { key: "dependents", label: "Dependents", icon: iconArrowLongRight(14), align: "end" },
1057
+ ];
1058
+ packages.rows = [
1059
+ { name: "requests", dependents: 1204 },
1060
+ { name: "attrs", dependents: 87 },
1061
+ ];
1062
+ </script>
1038
1063
  ```
1039
1064
 
1040
1065
  ## <distance-value>
@@ -1529,6 +1554,36 @@ Example:
1529
1554
  <kbd-hint keys="Mod+Shift+Enter" platform="mac"></kbd-hint>
1530
1555
  ```
1531
1556
 
1557
+ ## <kind-icon>
1558
+
1559
+ Inline icon for a named kind (e.g. a service, a library, an external
1560
+ package), looked up in a shared `kinds` map so tables, lists, and search
1561
+ results show the same icon and color as a `dag-graph` legend. With
1562
+ `show-label` the kind's label follows the icon as text; otherwise the
1563
+ icon alone is exposed as an image named by the label. Renders nothing for
1564
+ a kind missing from `kinds`.
1565
+
1566
+ Import: `import "@f-ewald/components/kind-icon.js";`
1567
+
1568
+ Properties: `kind` (attribute `kind`) : string, default ""; `kinds` (JS property only) : Record<string, KindIconStyle>, default {}; `size` (attribute `size`) : 14 | 18, default 14; `showLabel` (attribute `show-label`) : boolean, default false
1569
+ Events: none
1570
+ CSS custom properties: `--ui-primary`
1571
+
1572
+ Example:
1573
+ ```html
1574
+ <kind-icon kind="service" show-label></kind-icon>
1575
+ <kind-icon kind="package" size="18"></kind-icon>
1576
+ <script type="module">
1577
+ import { iconCube, iconServer } from "@f-ewald/components/icons.js";
1578
+
1579
+ const kinds = {
1580
+ service: { label: "Service", icon: iconServer, color: "#4269d0" },
1581
+ package: { label: "External package", icon: iconCube, color: "#9498a0" },
1582
+ };
1583
+ for (const el of document.querySelectorAll("kind-icon")) el.kinds = kinds;
1584
+ </script>
1585
+ ```
1586
+
1532
1587
  ## <link-card>
1533
1588
 
1534
1589
  A single linked-resource tile — logo (or an initial-letter fallback),
@@ -3091,6 +3146,42 @@ Example:
3091
3146
  <ui-checkbox label="Show list view"></ui-checkbox>
3092
3147
  ```
3093
3148
 
3149
+ ## <ui-tooltip>
3150
+
3151
+ Hover and focus tooltip for its default-slot trigger. The `content` slot
3152
+ holds the tooltip body — plain text or rich markup such as a list. It
3153
+ appears after `show-delay` on hover and at once on keyboard focus, stays
3154
+ open while the pointer is over the tooltip itself, and closes on Escape,
3155
+ blur, or when the pointer leaves. It renders in the top layer, so
3156
+ scrolling or `overflow: hidden` ancestors never clip it.
3157
+
3158
+ The trigger is described by the content (`aria-describedby`). A trigger
3159
+ with nothing focusable inside (e.g. plain text) makes the tooltip host
3160
+ focusable so keyboard users can reach the description too. ARIA references
3161
+ can't cross shadow roots, so when the trigger is a custom element whose
3162
+ focusable control lives in its own shadow root, screen readers won't
3163
+ announce the description on focus; prefer a native trigger such as
3164
+ `<button>` when that matters.
3165
+
3166
+ Import: `import "@f-ewald/components/ui-tooltip.js";`
3167
+
3168
+ Properties: `placement` (attribute `placement`) : UiTooltipPlacement, default "top"; `showDelay` (attribute `show-delay`) : number, default 300; `disabled` (attribute `disabled`) : boolean, default false; `open` (JS property only) : boolean, default —
3169
+ Events: none
3170
+ CSS custom properties: `--ui-focus-ring`, `--ui-font`, `--ui-font-size-sm`, `--ui-font-weight-regular`, `--ui-line-height-tight`, `--ui-radius-sm`, `--ui-shadow`, `--ui-tooltip`, `--ui-tooltip-text`
3171
+
3172
+ Example:
3173
+ ```html
3174
+ <ui-tooltip>
3175
+ <button type="button">Copy link</button>
3176
+ <span slot="content">Copies a shareable link to this view</span>
3177
+ </ui-tooltip>
3178
+ <!-- Plain-text trigger: the tooltip becomes focusable; rich content is fine -->
3179
+ <ui-tooltip placement="bottom" show-delay="0">
3180
+ <span>Partial snapshot</span>
3181
+ <div slot="content">3 work items pending: <ul><li>mp:lap-service</li></ul></div>
3182
+ </ui-tooltip>
3183
+ ```
3184
+
3094
3185
  ## <user-avatar>
3095
3186
 
3096
3187
  Circular avatar. Shows `src` when it loads successfully; falls back to the
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@f-ewald/components",
3
3
  "private": false,
4
- "version": "1.42.2",
4
+ "version": "1.43.0",
5
5
  "description": "A collection of universally usable web components for various tasks.",
6
6
  "type": "module",
7
7
  "main": "dist/index.js",