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