@f-ewald/components 1.15.0 → 1.17.0

package/docs/mapbox-map.md

@@ -0,0 +1,62 @@
+# `<mapbox-map>`
+
+A thin, generic wrapper around a `mapboxgl.Map` — construction, access
+token, style loading/switching, and container resizing only. It carries no
+domain logic: no layer registry, no click-handler system, no markers or
+popups. A consumer registers its own sources/layers/handlers against the
+`mapboxgl.Map` instance handed back on `map-ready`, the same instance
+`mapbox-map` continues to own (this component never calls `map.remove()`
+except on disconnect, so a consumer's own registrations survive style
+reloads exactly as they would using `mapboxgl.Map` directly).
+
+Deliberately does not construct the map until `styleUrl` is a non-empty
+string — if a consumer knows the desired style only after an async
+lookup (e.g. a saved user preference), delay setting `styleUrl` rather
+than setting a default and swapping it later, which would visibly flash
+the wrong basemap before the real one loads.
+
+## Install
+
+```js
+import "@f-ewald/components/mapbox-map.js";
+```
+
+## Usage
+
+```html
+<mapbox-map
+  access-token="pk.your-token"
+  style-url="mapbox://styles/mapbox/light-v11"
+></mapbox-map>
+<script type="module">
+  document.querySelector("mapbox-map").addEventListener("map-ready", (e) => {
+    const map = e.detail.map; // the underlying mapboxgl.Map
+    map.addSource("mine", { type: "geojson", data: "/mine.geojson" });
+    map.addLayer({ id: "mine", type: "circle", source: "mine", paint: { "circle-color": "#4f46e5" } });
+  });
+</script>
+```
+
+## Attributes / properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `accessToken` | `access-token` | `string` | `""` | Mapbox access token. Required before the map can be constructed. |
+| `styleUrl` | `style-url` | `string` | `""` | Style URL (e.g. `mapbox://styles/mapbox/light-v11`). The map is not constructed until this is a non-empty string — see the class doc. |
+| `center` | _(JS property only)_ | `[number, number]` | `[0, 0]` | Initial center as `[lng, lat]`. Only read at construction time. |
+| `zoom` | `zoom` | `number` | `0` | Initial zoom level. Only read at construction time. |
+
+## Events
+
+| Event | Description |
+| --- | --- |
+| `map-style-reloaded` | A subsequent `styleUrl` change finished loading its new style (sources/layers registered by a consumer via the `map-ready` instance do not survive a style change and must be re-registered — same behavior as calling `map.setStyle()` directly); detail: `{ map: mapboxgl.Map }`. |
+| `map-ready` | The map (and, if `styleUrl` changed before the initial load finished, its final requested style) has finished loading; detail: `{ map: mapboxgl.Map }`. |
+
+## Slots
+
+_None._
+
+## CSS custom properties
+
+_None._

package/docs/photo-gallery.md

@@ -3,6 +3,10 @@
 Responsive, accessible image carousel composed from declarative
 `gallery-item` children.
 
+The image viewport keeps a fixed `aspect-ratio`, and the caption row is
+reserved for every slide whenever any slide has a caption, so the carousel's
+total height stays constant as it cycles — it never shifts the page below it.
+
 ## Install
 
 ```js
@@ -67,6 +71,7 @@ import "@f-ewald/components/photo-gallery.js";
 | `--ui-font` |
 | `--ui-font-size` |
 | `--ui-font-size-sm` |
+| `--ui-line-height-normal` |
 | `--ui-line-height-tight` |
 | `--ui-on-accent` |
 | `--ui-overlay` |

package/docs/range-slider.md

@@ -0,0 +1,59 @@
+# `<range-slider>`
+
+A form-associated numeric range slider, usable standalone or inside a
+native `<form>`. Wraps a native `<input type="range">` (kept for its free
+keyboard, drag, and screen-reader support) restyled to match this
+package's track/fill visual language (`stat-meter`, `percent-bar-chart`)
+instead of the browser-default appearance. Purely a value control — no
+built-in label; wrap in `form-field` for a labeled field, or render a
+value readout next to it (see the playground example), matching
+`autocomplete-input`/`form-select`.
+
+## Install
+
+```js
+import "@f-ewald/components/range-slider.js";
+```
+
+## Usage
+
+```html
+<range-slider min="100" max="5000" step="50" value="1000"></range-slider>
+<script type="module">
+  document.querySelector("range-slider").addEventListener("input", (e) => {
+    console.log(e.detail.value);
+  });
+</script>
+```
+
+## Attributes / properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `min` | `min` | `number` | `0` | Minimum value. |
+| `max` | `max` | `number` | `100` | Maximum value. |
+| `step` | `step` | `number` | `1` | Step increment. |
+| `value` | `value` | `number` | `0` | Current value. |
+| `disabled` | `disabled` | `boolean` | `false` | Disables interaction; merged with an ancestor `<fieldset disabled>`. |
+| `name` | `name` | `string` | `""` | Form field name. |
+
+## Events
+
+| Event | Description |
+| --- | --- |
+| `input` | Fires continuously while dragging/typing; detail: `{ value }`. |
+| `change` | Fires once the value is committed (drag released, arrow key released); detail: `{ value }`. |
+
+## Slots
+
+_None._
+
+## CSS custom properties
+
+| Custom property |
+| --- |
+| `--ui-focus-ring` |
+| `--ui-primary` |
+| `--ui-surface` |
+| `--ui-surface-muted` |
+| `--ui-text-muted` |

package/docs/toast-notification.md

@@ -1,13 +1,18 @@
 # `<toast-notification>`
 
 Fixed-position stack of dismissible notifications, anchored top-right
-(top-full-width on mobile). Not wired to any app state yet — callers add
-toasts imperatively via the `show()` method on a live element reference,
+(top-full-width on mobile). Every toast shares one fixed width so entries
+never appear narrower or wider than one another. Not wired to any app state
+yet — callers add toasts imperatively via the `show()` method on a live
+element reference,
 e.g. `document.querySelector('toast-notification')?.show('Offline', { variant: 'error' })`,
 or via the `notifySuccess`/`notifyError`/`notifyInfo` module-level helpers
-exported from this file. Each toast auto-dismisses after `duration` ms and
-can also be dismissed via its ✕ button. Appears/disappears instantly — no
-slide/fade transitions.
+exported from this file. The first argument is the required bold headline; an
+optional `description` renders a smaller, non-bold second line. Each variant
+leads with a matching status icon (success → check, error → exclamation
+circle, info → information circle, warning → exclamation triangle). Each toast
+auto-dismisses after `duration` ms and can also be dismissed via its ✕
+button. Appears/disappears instantly — no slide/fade transitions.
 
 ## Install
 
@@ -21,7 +26,7 @@ import "@f-ewald/components/toast-notification.js";
 <toast-notification></toast-notification>
 <script type="module">
   import { notifySuccess } from "@f-ewald/components/toast-notification.js";
-  notifySuccess("Saved!");
+  notifySuccess("Saved!", "Your changes are now live.");
 </script>
 ```
 
@@ -45,6 +50,9 @@ _None._
 | `--ui-focus-ring` |
 | `--ui-font` |
 | `--ui-font-size` |
+| `--ui-font-size-sm` |
+| `--ui-font-weight-regular` |
+| `--ui-font-weight-semibold` |
 | `--ui-hover-overlay` |
 | `--ui-info` |
 | `--ui-line-height-glyph` |
@@ -55,3 +63,4 @@ _None._
 | `--ui-shadow-lg` |
 | `--ui-success` |
 | `--ui-text` |
+| `--ui-warning` |

package/docs/tree-view.md

@@ -13,6 +13,10 @@ every folder expanded instead. Expansion state is otherwise managed
 internally and untouched by later `nodes` updates, so a user's manual
 toggles survive a data refresh.
 
+Set the `lines` boolean to draw classic file-tree connector guides: a
+vertical line per continuing ancestor level and a branch elbow (`└`) or
+tee (`├`) linking each node to its parent. Off by default (indentation only).
+
 ## Install
 
 ```js
@@ -22,7 +26,7 @@ import "@f-ewald/components/tree-view.js";
 ## Usage
 
 ```html
-<tree-view></tree-view>
+<tree-view lines></tree-view>
 <script type="module">
   const tree = document.querySelector("tree-view");
   tree.nodes = [
@@ -45,6 +49,7 @@ import "@f-ewald/components/tree-view.js";
 | `nodes` | _(JS property only)_ | `TreeNode[]` | `[]` | Tree data; opaque to this component beyond what `renderNode` does with it. |
 | `renderNode` | _(JS property only)_ | `(node: TreeNode) => unknown` | `—` | Produces a row's rendered content for `node`. Default: plain label text. |
 | `defaultExpanded` | `default-expanded` | `boolean` | `false` | Start every folder expanded instead of the default all-collapsed. |
+| `lines` | `lines` | `boolean` | `false` | Draw classic file-tree connector guides (vertical ancestor lines plus a branch elbow/tee per row) instead of indentation alone. Off by default. |
 
 ## Events
 
@@ -60,6 +65,7 @@ _None._
 
 | Custom property |
 | --- |
+| `--ui-border` |
 | `--ui-focus-ring` |
 | `--ui-font` |
 | `--ui-font-size-sm` |

package/docs/ui-checkbox.md

@@ -8,7 +8,11 @@ A form-associated boolean checkbox, usable standalone or inside a native
 Renders a native `<input type="checkbox">` wrapped in a `<label>`, styled
 via `:has()` on the wrapping label (matching `radio-pills`/`radio-cards`)
 rather than styling the native input directly; the checkbox itself renders
-at `1rem`, matching the existing radio-input convention.
+at `1rem`, matching the existing radio-input convention. An optional
+pre-rendered `icon` (matching `form-select`'s per-option icon convention)
+renders between the box and the label, inside the same clickable `<label>`
+— for a row that pairs a checkbox with an icon/swatch and needs the whole
+row, icon included, to stay one click target.
 
 ## Install
 
@@ -21,6 +25,8 @@ import "@f-ewald/components/ui-checkbox.js";
 ```html
 <ui-checkbox label="Subscribe to updates"></ui-checkbox>
 <ui-checkbox name="terms" label="I agree to the terms" required></ui-checkbox>
+<!-- .icon is set programmatically (a pre-rendered TemplateResult), not an attribute -->
+<ui-checkbox label="Show list view"></ui-checkbox>
 ```
 
 ## Attributes / properties
@@ -33,6 +39,8 @@ import "@f-ewald/components/ui-checkbox.js";
 | `required` | `required` | `boolean` | `false` | Marks the control invalid via `ElementInternals` while unchecked. |
 | `name` | `name` | `string` | `""` | Form field name; submitted as `name=on` only while checked. |
 | `label` | `label` | `string` | `""` | Visible label text rendered next to the box. |
+| `icon` | _(JS property only)_ | `TemplateResult | null` | `null` | Pre-rendered icon template displayed between the box and the label, e.g. `iconPencil(14)` from this package's icon set. |
+| `iconSize` | `iconSize` | `number` | `14` | Square icon size in pixels — 14 (inline icon size) by default. |
 
 ## Events
 

package/llms.txt

@@ -1082,6 +1082,44 @@ Example:
 <map-pin color="#22c55e" size="26" highlighted>🏠</map-pin>
 ```
 
+## <mapbox-map>
+
+A thin, generic wrapper around a `mapboxgl.Map` — construction, access
+token, style loading/switching, and container resizing only. It carries no
+domain logic: no layer registry, no click-handler system, no markers or
+popups. A consumer registers its own sources/layers/handlers against the
+`mapboxgl.Map` instance handed back on `map-ready`, the same instance
+`mapbox-map` continues to own (this component never calls `map.remove()`
+except on disconnect, so a consumer's own registrations survive style
+reloads exactly as they would using `mapboxgl.Map` directly).
+
+Deliberately does not construct the map until `styleUrl` is a non-empty
+string — if a consumer knows the desired style only after an async
+lookup (e.g. a saved user preference), delay setting `styleUrl` rather
+than setting a default and swapping it later, which would visibly flash
+the wrong basemap before the real one loads.
+
+Import: `import "@f-ewald/components/mapbox-map.js";`
+
+Properties: `accessToken` (attribute `access-token`) : string, default ""; `styleUrl` (attribute `style-url`) : string, default ""; `center` (JS property only) : [number, number], default [0, 0]; `zoom` (attribute `zoom`) : number, default 0
+Events: `map-style-reloaded`, `map-ready`
+CSS custom properties: none
+
+Example:
+```html
+<mapbox-map
+  access-token="pk.your-token"
+  style-url="mapbox://styles/mapbox/light-v11"
+></mapbox-map>
+<script type="module">
+  document.querySelector("mapbox-map").addEventListener("map-ready", (e) => {
+    const map = e.detail.map; // the underlying mapboxgl.Map
+    map.addSource("mine", { type: "geojson", data: "/mine.geojson" });
+    map.addLayer({ id: "mine", type: "circle", source: "mine", paint: { "circle-color": "#4f46e5" } });
+  });
+</script>
+```
+
 ## <markdown-view>
 
 Renders a markdown string as sanitized, styled HTML — headings, lists,
@@ -1273,11 +1311,15 @@ Example:
 Responsive, accessible image carousel composed from declarative
 `gallery-item` children.
 
+The image viewport keeps a fixed `aspect-ratio`, and the caption row is
+reserved for every slide whenever any slide has a caption, so the carousel's
+total height stays constant as it cycles — it never shifts the page below it.
+
 Import: `import "@f-ewald/components/photo-gallery.js";`
 
 Properties: `currentIndex` (attribute `current-index`) : number, default 0; `delay` (attribute `delay`) : number, default 0; `showControls` (attribute `show-controls`) : boolean, default true; `showCounter` (attribute `show-counter`) : boolean, default false; `showIndicators` (attribute `show-indicators`) : boolean, default false; `showAutoplayControl` (attribute `show-autoplay-control`) : boolean, default true; `paused` (attribute `paused`) : boolean, default false; `aspectRatio` (attribute `aspect-ratio`) : string, default "16 / 9"; `objectFit` (attribute `object-fit`) : PhotoGalleryObjectFit, default "cover"
 Events: `slide-change`
-CSS custom properties: `--ui-border`, `--ui-focus-ring`, `--ui-font`, `--ui-font-size`, `--ui-font-size-sm`, `--ui-line-height-tight`, `--ui-on-accent`, `--ui-overlay`, `--ui-primary`, `--ui-radius`, `--ui-radius-sm`, `--ui-surface`, `--ui-surface-muted`, `--ui-text`, `--ui-text-muted`
+CSS custom properties: `--ui-border`, `--ui-focus-ring`, `--ui-font`, `--ui-font-size`, `--ui-font-size-sm`, `--ui-line-height-normal`, `--ui-line-height-tight`, `--ui-on-accent`, `--ui-overlay`, `--ui-primary`, `--ui-radius`, `--ui-radius-sm`, `--ui-surface`, `--ui-surface-muted`, `--ui-text`, `--ui-text-muted`
 
 Example:
 ```html
@@ -1414,6 +1456,33 @@ Example:
 </script>
 ```
 
+## <range-slider>
+
+A form-associated numeric range slider, usable standalone or inside a
+native `<form>`. Wraps a native `<input type="range">` (kept for its free
+keyboard, drag, and screen-reader support) restyled to match this
+package's track/fill visual language (`stat-meter`, `percent-bar-chart`)
+instead of the browser-default appearance. Purely a value control — no
+built-in label; wrap in `form-field` for a labeled field, or render a
+value readout next to it (see the playground example), matching
+`autocomplete-input`/`form-select`.
+
+Import: `import "@f-ewald/components/range-slider.js";`
+
+Properties: `min` (attribute `min`) : number, default 0; `max` (attribute `max`) : number, default 100; `step` (attribute `step`) : number, default 1; `value` (attribute `value`) : number, default 0; `disabled` (attribute `disabled`) : boolean, default false; `name` (attribute `name`) : string, default ""
+Events: `input`, `change`
+CSS custom properties: `--ui-focus-ring`, `--ui-primary`, `--ui-surface`, `--ui-surface-muted`, `--ui-text-muted`
+
+Example:
+```html
+<range-slider min="100" max="5000" step="50" value="1000"></range-slider>
+<script type="module">
+  document.querySelector("range-slider").addEventListener("input", (e) => {
+    console.log(e.detail.value);
+  });
+</script>
+```
+
 ## <relative-time>
 
 Inline relative-time display (e.g. "3 hours ago"). Accepts either a
@@ -1712,26 +1781,31 @@ Example:
 ## <toast-notification>
 
 Fixed-position stack of dismissible notifications, anchored top-right
-(top-full-width on mobile). Not wired to any app state yet — callers add
-toasts imperatively via the `show()` method on a live element reference,
+(top-full-width on mobile). Every toast shares one fixed width so entries
+never appear narrower or wider than one another. Not wired to any app state
+yet — callers add toasts imperatively via the `show()` method on a live
+element reference,
 e.g. `document.querySelector('toast-notification')?.show('Offline', { variant: 'error' })`,
 or via the `notifySuccess`/`notifyError`/`notifyInfo` module-level helpers
-exported from this file. Each toast auto-dismisses after `duration` ms and
-can also be dismissed via its ✕ button. Appears/disappears instantly — no
-slide/fade transitions.
+exported from this file. The first argument is the required bold headline; an
+optional `description` renders a smaller, non-bold second line. Each variant
+leads with a matching status icon (success → check, error → exclamation
+circle, info → information circle, warning → exclamation triangle). Each toast
+auto-dismisses after `duration` ms and can also be dismissed via its ✕
+button. Appears/disappears instantly — no slide/fade transitions.
 
 Import: `import "@f-ewald/components/toast-notification.js";`
 
 Properties: none
 Events: none
-CSS custom properties: `--ui-danger`, `--ui-focus-ring`, `--ui-font`, `--ui-font-size`, `--ui-hover-overlay`, `--ui-info`, `--ui-line-height-glyph`, `--ui-line-height-normal`, `--ui-on-accent`, `--ui-radius`, `--ui-radius-sm`, `--ui-shadow-lg`, `--ui-success`, `--ui-text`
+CSS custom properties: `--ui-danger`, `--ui-focus-ring`, `--ui-font`, `--ui-font-size`, `--ui-font-size-sm`, `--ui-font-weight-regular`, `--ui-font-weight-semibold`, `--ui-hover-overlay`, `--ui-info`, `--ui-line-height-glyph`, `--ui-line-height-normal`, `--ui-on-accent`, `--ui-radius`, `--ui-radius-sm`, `--ui-shadow-lg`, `--ui-success`, `--ui-text`, `--ui-warning`
 
 Example:
 ```html
 <toast-notification></toast-notification>
 <script type="module">
   import { notifySuccess } from "@f-ewald/components/toast-notification.js";
-  notifySuccess("Saved!");
+  notifySuccess("Saved!", "Your changes are now live.");
 </script>
 ```
 
@@ -1750,15 +1824,19 @@ every folder expanded instead. Expansion state is otherwise managed
 internally and untouched by later `nodes` updates, so a user's manual
 toggles survive a data refresh.
 
+Set the `lines` boolean to draw classic file-tree connector guides: a
+vertical line per continuing ancestor level and a branch elbow (`└`) or
+tee (`├`) linking each node to its parent. Off by default (indentation only).
+
 Import: `import "@f-ewald/components/tree-view.js";`
 
-Properties: `nodes` (JS property only) : TreeNode[], default []; `renderNode` (JS property only) : (node: TreeNode) => unknown, default —; `defaultExpanded` (attribute `default-expanded`) : boolean, default false
+Properties: `nodes` (JS property only) : TreeNode[], default []; `renderNode` (JS property only) : (node: TreeNode) => unknown, default —; `defaultExpanded` (attribute `default-expanded`) : boolean, default false; `lines` (attribute `lines`) : boolean, default false
 Events: `node-click`
-CSS custom properties: `--ui-focus-ring`, `--ui-font`, `--ui-font-size-sm`, `--ui-radius-sm`, `--ui-surface-muted`, `--ui-text`, `--ui-text-muted`
+CSS custom properties: `--ui-border`, `--ui-focus-ring`, `--ui-font`, `--ui-font-size-sm`, `--ui-radius-sm`, `--ui-surface-muted`, `--ui-text`, `--ui-text-muted`
 
 Example:
 ```html
-<tree-view></tree-view>
+<tree-view lines></tree-view>
 <script type="module">
   const tree = document.querySelector("tree-view");
   tree.nodes = [
@@ -1815,11 +1893,15 @@ A form-associated boolean checkbox, usable standalone or inside a native
 Renders a native `<input type="checkbox">` wrapped in a `<label>`, styled
 via `:has()` on the wrapping label (matching `radio-pills`/`radio-cards`)
 rather than styling the native input directly; the checkbox itself renders
-at `1rem`, matching the existing radio-input convention.
+at `1rem`, matching the existing radio-input convention. An optional
+pre-rendered `icon` (matching `form-select`'s per-option icon convention)
+renders between the box and the label, inside the same clickable `<label>`
+— for a row that pairs a checkbox with an icon/swatch and needs the whole
+row, icon included, to stay one click target.
 
 Import: `import "@f-ewald/components/ui-checkbox.js";`
 
-Properties: `checked` (attribute `checked`) : boolean, default false; `indeterminate` (attribute `indeterminate`) : boolean, default false; `disabled` (attribute `disabled`) : boolean, default false; `required` (attribute `required`) : boolean, default false; `name` (attribute `name`) : string, default ""; `label` (attribute `label`) : string, default ""
+Properties: `checked` (attribute `checked`) : boolean, default false; `indeterminate` (attribute `indeterminate`) : boolean, default false; `disabled` (attribute `disabled`) : boolean, default false; `required` (attribute `required`) : boolean, default false; `name` (attribute `name`) : string, default ""; `label` (attribute `label`) : string, default ""; `icon` (JS property only) : TemplateResult | null, default null; `iconSize` (attribute `iconSize`) : number, default 14
 Events: `change`
 CSS custom properties: `--ui-danger`, `--ui-focus-ring`, `--ui-font`, `--ui-font-size-sm`, `--ui-line-height-tight`, `--ui-primary`, `--ui-radius-sm`, `--ui-text`
 
@@ -1827,6 +1909,8 @@ Example:
 ```html
 <ui-checkbox label="Subscribe to updates"></ui-checkbox>
 <ui-checkbox name="terms" label="I agree to the terms" required></ui-checkbox>
+<!-- .icon is set programmatically (a pre-rendered TemplateResult), not an attribute -->
+<ui-checkbox label="Show list view"></ui-checkbox>
 ```
 
 ## <user-avatar>

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@f-ewald/components",
   "private": false,
-  "version": "1.15.0",
+  "version": "1.17.0",
   "description": "A collection of universally usable web components for various tasks.",
   "type": "module",
   "main": "dist/index.js",
@@ -65,6 +65,7 @@
     "d3-shape": "^3.2.0",
     "dompurify": "^3.4.12",
     "lit": "^3.3.3",
+    "mapbox-gl": "^3.9.0",
     "marked": "^18.0.7",
     "zod": "^4.4.3"
   },
@@ -79,6 +80,7 @@
     "@types/d3-array": "^3.2.2",
     "@types/d3-scale": "^4.0.9",
     "@types/d3-shape": "^3.1.8",
+    "@types/mapbox-gl": "^3.4.1",
     "@types/node": "^26.1.1",
     "heroicons": "^2.2.0",
     "tailwindcss": "^4.3.3",