@f-ewald/components 0.1.0 → 0.2.1

package/docs/radio-cards.md

@@ -0,0 +1,58 @@
+# `<radio-cards>`
+
+Single-select group of full-width cards, each with a label and optional
+description — for a handful of meaningfully different choices where the
+description matters. For many short, same-shaped options (a color swatch,
+a basemap style), use `radio-pills` instead. Wraps native radio inputs for
+keyboard/a11y and fires `change` rather than relying on form submission.
+
+## Install
+
+```js
+import "@f-ewald/components/radio-cards.js";
+```
+
+## Usage
+
+```html
+<radio-cards></radio-cards>
+<script type="module">
+  const el = document.querySelector("radio-cards");
+  el.options = [
+    { value: "simple", label: "Simple", description: "Quick-ranking view" },
+    { value: "detailed", label: "Detailed", description: "Every section and layer" },
+  ];
+  el.value = "simple";
+  el.addEventListener("change", (e) => console.log(e.detail.value));
+</script>
+```
+
+## Attributes / properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `options` | _(JS property only)_ | `RadioCardOption[]` | `[]` | Options to render, one card each. |
+| `value` | `value` | `string` | `""` | Currently selected value. |
+
+## Events
+
+| Event | Description |
+| --- | --- |
+| `change` | A card was selected; detail: { value }. |
+
+## Slots
+
+_None._
+
+## CSS custom properties
+
+| Custom property |
+| --- |
+| `--ui-border` |
+| `--ui-font` |
+| `--ui-font-size-sm` |
+| `--ui-primary` |
+| `--ui-radius-sm` |
+| `--ui-surface-muted` |
+| `--ui-text` |
+| `--ui-text-muted` |

package/docs/radio-pills.md

@@ -0,0 +1,56 @@
+# `<radio-pills>`
+
+Single-select group of compact pill-shaped options — for many short,
+same-shaped choices (a basemap style, a unit toggle). For a handful of
+choices where a description matters, use `radio-cards` instead. Wraps
+native radio inputs for keyboard/a11y and fires `change` rather than
+relying on form submission.
+
+## Install
+
+```js
+import "@f-ewald/components/radio-pills.js";
+```
+
+## Usage
+
+```html
+<radio-pills></radio-pills>
+<script type="module">
+  const el = document.querySelector("radio-pills");
+  el.options = [
+    { value: "light", label: "Light" },
+    { value: "streets", label: "Streets" },
+  ];
+  el.value = "light";
+  el.addEventListener("change", (e) => console.log(e.detail.value));
+</script>
+```
+
+## Attributes / properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `options` | _(JS property only)_ | `RadioPillOption[]` | `[]` | Options to render, one pill each. |
+| `value` | `value` | `string` | `""` | Currently selected value. |
+
+## Events
+
+| Event | Description |
+| --- | --- |
+| `change` | A pill was selected; detail: { value }. |
+
+## Slots
+
+_None._
+
+## CSS custom properties
+
+| Custom property |
+| --- |
+| `--ui-border` |
+| `--ui-font` |
+| `--ui-font-size-sm` |
+| `--ui-primary` |
+| `--ui-surface-muted` |
+| `--ui-text` |

package/docs/ui-button.md

@@ -0,0 +1,67 @@
+# `<ui-button>`
+
+Button (or link styled as one) with an optional leading icon, in three
+visual weights. Set `href` to render an `<a>` instead of a `<button>` —
+same styling either way — for cross-page navigation that should look like
+an action button; a disabled/busy link stays a real `<a>` with
+`aria-disabled` + `pointer-events: none` rather than losing its href.
+Put the icon in the `icon` slot and the label in the default slot.
+
+Form-associated (`type="submit"`/`"reset"`): the actual `<button>` lives in
+this element's shadow root, which native HTML form association does not
+cross into from an ancestor light-DOM `<form>`. `type="submit"`/`"reset"`
+is instead wired through `ElementInternals.form` — the same mechanism
+`address-autocomplete` uses to associate with an ancestor form.
+
+## Install
+
+```js
+import "@f-ewald/components/ui-button.js";
+```
+
+## Usage
+
+```html
+<ui-button variant="primary">
+  <span slot="icon">...</span>
+  New property
+</ui-button>
+<ui-button variant="danger">Delete</ui-button>
+<ui-button variant="secondary" href="/properties?edit=42">Edit</ui-button>
+```
+
+## Attributes / properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `variant` | `variant` | `ButtonVariant` | `"primary"` | Visual weight. |
+| `href` | `href` | `string | null` | `null` | Renders an `<a href="...">` instead of a `<button>` when set. |
+| `type` | `type` | `"button" | "submit" | "reset"` | `"button"` | Native button `type`. Ignored when `href` is set. |
+| `disabled` | `disabled` | `boolean` | `false` | Disables the control and dims it. |
+| `busy` | `busy` | `boolean` | `false` | Shows a spinner in place of the icon slot and disables the control. |
+
+## Events
+
+_None._
+
+## Slots
+
+| Slot | Description |
+| --- | --- |
+| `(default)` | Button label. |
+| `icon` | Optional leading icon (e.g. an inline SVG). |
+
+## CSS custom properties
+
+| Custom property |
+| --- |
+| `--ui-border` |
+| `--ui-danger` |
+| `--ui-danger-hover` |
+| `--ui-font` |
+| `--ui-font-size-sm` |
+| `--ui-primary` |
+| `--ui-primary-hover` |
+| `--ui-radius-sm` |
+| `--ui-text` |
+| `--ui-text-muted` |

package/docs/user-avatar.md

@@ -0,0 +1,42 @@
+# `<user-avatar>`
+
+Circular avatar. Shows `src` when it loads successfully; falls back to the
+first letter of `name` (uppercased) if `src` is unset or fails to load
+(e.g. an expired OAuth profile-photo URL); falls back further to a generic
+person icon if `name` is also unset. A broken image never leaves a blank
+circle.
+
+## Install
+
+```js
+import "@f-ewald/components/user-avatar.js";
+```
+
+## Usage
+
+```html
+<user-avatar src="https://example.com/photo.jpg" name="Freddy" size="40"></user-avatar>
+```
+
+## Attributes / properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `src` | `src` | `string | null` | `null` | Image URL to show. Falls back to initials/icon if unset or it fails to load. |
+| `name` | `name` | `string | null` | `null` | Source string for the fallback initial (e.g. a display name or email) — first character, uppercased. |
+| `size` | `size` | `number` | `32` | Diameter in CSS pixels. |
+
+## Events
+
+_None._
+
+## Slots
+
+_None._
+
+## CSS custom properties
+
+| Custom property |
+| --- |
+| `--ui-font` |
+| `--ui-primary` |

package/llms.txt

@@ -234,6 +234,62 @@ Example:
 </script>
 ```
 
+## <radio-cards>
+
+Single-select group of full-width cards, each with a label and optional
+description — for a handful of meaningfully different choices where the
+description matters. For many short, same-shaped options (a color swatch,
+a basemap style), use `radio-pills` instead. Wraps native radio inputs for
+keyboard/a11y and fires `change` rather than relying on form submission.
+
+Import: `import "@f-ewald/components/radio-cards.js";`
+
+Properties: `options` (JS property only) : RadioCardOption[], default []; `value` (attribute `value`) : string, default ""
+Events: `change`
+CSS custom properties: `--ui-border`, `--ui-font`, `--ui-font-size-sm`, `--ui-primary`, `--ui-radius-sm`, `--ui-surface-muted`, `--ui-text`, `--ui-text-muted`
+
+Example:
+```html
+<radio-cards></radio-cards>
+<script type="module">
+  const el = document.querySelector("radio-cards");
+  el.options = [
+    { value: "simple", label: "Simple", description: "Quick-ranking view" },
+    { value: "detailed", label: "Detailed", description: "Every section and layer" },
+  ];
+  el.value = "simple";
+  el.addEventListener("change", (e) => console.log(e.detail.value));
+</script>
+```
+
+## <radio-pills>
+
+Single-select group of compact pill-shaped options — for many short,
+same-shaped choices (a basemap style, a unit toggle). For a handful of
+choices where a description matters, use `radio-cards` instead. Wraps
+native radio inputs for keyboard/a11y and fires `change` rather than
+relying on form submission.
+
+Import: `import "@f-ewald/components/radio-pills.js";`
+
+Properties: `options` (JS property only) : RadioPillOption[], default []; `value` (attribute `value`) : string, default ""
+Events: `change`
+CSS custom properties: `--ui-border`, `--ui-font`, `--ui-font-size-sm`, `--ui-primary`, `--ui-surface-muted`, `--ui-text`
+
+Example:
+```html
+<radio-pills></radio-pills>
+<script type="module">
+  const el = document.querySelector("radio-pills");
+  el.options = [
+    { value: "light", label: "Light" },
+    { value: "streets", label: "Streets" },
+  ];
+  el.value = "light";
+  el.addEventListener("change", (e) => console.log(e.detail.value));
+</script>
+```
+
 ## <relative-time>
 
 Inline relative-time display (e.g. "3 hours ago"). Accepts either a
@@ -333,6 +389,56 @@ Example:
 </script>
 ```
 
+## <ui-button>
+
+Button (or link styled as one) with an optional leading icon, in three
+visual weights. Set `href` to render an `<a>` instead of a `<button>` —
+same styling either way — for cross-page navigation that should look like
+an action button; a disabled/busy link stays a real `<a>` with
+`aria-disabled` + `pointer-events: none` rather than losing its href.
+Put the icon in the `icon` slot and the label in the default slot.
+
+Form-associated (`type="submit"`/`"reset"`): the actual `<button>` lives in
+this element's shadow root, which native HTML form association does not
+cross into from an ancestor light-DOM `<form>`. `type="submit"`/`"reset"`
+is instead wired through `ElementInternals.form` — the same mechanism
+`address-autocomplete` uses to associate with an ancestor form.
+
+Import: `import "@f-ewald/components/ui-button.js";`
+
+Properties: `variant` (attribute `variant`) : ButtonVariant, default "primary"; `href` (attribute `href`) : string | null, default null; `type` (attribute `type`) : "button" | "submit" | "reset", default "button"; `disabled` (attribute `disabled`) : boolean, default false; `busy` (attribute `busy`) : boolean, default false
+Events: none
+CSS custom properties: `--ui-border`, `--ui-danger`, `--ui-danger-hover`, `--ui-font`, `--ui-font-size-sm`, `--ui-primary`, `--ui-primary-hover`, `--ui-radius-sm`, `--ui-text`, `--ui-text-muted`
+
+Example:
+```html
+<ui-button variant="primary">
+  <span slot="icon">...</span>
+  New property
+</ui-button>
+<ui-button variant="danger">Delete</ui-button>
+<ui-button variant="secondary" href="/properties?edit=42">Edit</ui-button>
+```
+
+## <user-avatar>
+
+Circular avatar. Shows `src` when it loads successfully; falls back to the
+first letter of `name` (uppercased) if `src` is unset or fails to load
+(e.g. an expired OAuth profile-photo URL); falls back further to a generic
+person icon if `name` is also unset. A broken image never leaves a blank
+circle.
+
+Import: `import "@f-ewald/components/user-avatar.js";`
+
+Properties: `src` (attribute `src`) : string | null, default null; `name` (attribute `name`) : string | null, default null; `size` (attribute `size`) : number, default 32
+Events: none
+CSS custom properties: `--ui-font`, `--ui-primary`
+
+Example:
+```html
+<user-avatar src="https://example.com/photo.jpg" name="Freddy" size="40"></user-avatar>
+```
+
 ## <weight-bar-chart>
 
 Sorted horizontal bar chart of labeled weights (normalized fractions

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@f-ewald/components",
   "private": false,
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "A collection of universally usable web components for various tasks.",
   "type": "module",
   "main": "dist/index.js",