@f-ewald/components 0.6.0 → 1.0.0

package/docs/calendar-entry.md

@@ -0,0 +1,53 @@
+# `<calendar-entry>`
+
+Declarative metadata for one calendar event, consumed by a parent
+`calendar-month` or `calendar-year`. Read-only/non-interactive; renders
+nothing itself.
+
+## Install
+
+```js
+import "@f-ewald/components/calendar-entry.js";
+```
+
+## Usage
+
+```html
+<calendar-entry
+  start="2026-07-10"
+  end="2026-07-18"
+  label="Vacation"
+  color="success"
+>
+  <span slot="title">Vacation</span>
+  <span slot="detail">Out of office</span>
+  <span slot="detail">Road trip along the California coast with several scenic stops</span>
+  <span slot="footer">Return July 19 at 6 PM</span>
+</calendar-entry>
+```
+
+## Attributes / properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `start` | `start` | `string` | `""` | Inclusive start date, `"YYYY-MM-DD"`. |
+| `end` | `end` | `string` | `""` | Inclusive end date, `"YYYY-MM-DD"`. Falls back to `start` when unset (single-day entry). |
+| `label` | `label` | `string` | `""` | Fallback title used when no `title` slot is provided. |
+| `color` | `color` | `StatusPillColor` | `"neutral"` | Color variant, reusing `status-pill`'s palette. |
+| `href` | `href` | `string | undefined` | `—` | Optional link target; the parent renders the entry as an `<a>` when set. |
+
+## Events
+
+_None._
+
+## Slots
+
+| Slot | Description |
+| --- | --- |
+| `title` | Plain-text title shown instead of the `label` fallback. |
+| `detail` | Repeatable plain-text details rendered inside the shared body spanning all remaining days. |
+| `footer` | Plain-text ending note pinned to the bottom of the shared body. |
+
+## CSS custom properties
+
+_None._

package/docs/calendar-month.md

@@ -0,0 +1,77 @@
+# `<calendar-month>`
+
+One month rendered as a top-to-bottom list of days — weekends and today
+highlighted, with declarative `calendar-entry` children shown as colored
+bars spanning the days they cover. An entry's title uses its first visible
+day; every remaining visible day becomes one shared body for wrapped
+details and an optional ending footer. Overlapping entries stack into
+side-by-side lanes rather than being layered/hidden. Read-only.
+
+Lanes are computed independently per instance, from only the entries
+overlapping this month — an entry spanning a month boundary may therefore
+land in a different lane index in the adjacent month's `calendar-month`.
+This is an accepted v1 limitation: cross-month lane continuity would
+require a shared parent (`calendar-year`) to assign lanes globally.
+
+Entry attributes and slotted title/detail text are observed, so a
+standalone month re-renders when consumers update declarative metadata.
+
+## Install
+
+```js
+import "@f-ewald/components/calendar-month.js";
+```
+
+## Usage
+
+```html
+<calendar-month year="2026" month="7">
+  <calendar-entry start="2026-07-10" end="2026-07-18" label="Vacation" color="success">
+    <span slot="title">Vacation</span>
+    <span slot="detail">Out of office</span>
+    <span slot="detail">Road trip along the California coast with several scenic stops</span>
+    <span slot="footer">Return July 19 at 6 PM</span>
+  </calendar-entry>
+  <calendar-entry start="2026-07-15" end="2026-07-20" label="Conference" color="warning" href="#conf">
+    <span slot="detail">Talks and workshops</span>
+    <span slot="footer">Closing keynote · July 20</span>
+  </calendar-entry>
+</calendar-month>
+```
+
+## Attributes / properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `year` | `year` | `number` | `—` | Calendar year, e.g. `2026`. |
+| `month` | `month` | `number` | `1` | Calendar month, 1-12 (January = 1). |
+
+## Events
+
+_None._
+
+## Slots
+
+| Slot | Description |
+| --- | --- |
+| `(default)` | Declarative `calendar-entry` elements to render for this month. |
+
+## CSS custom properties
+
+| Custom property |
+| --- |
+| `--ui-border` |
+| `--ui-danger` |
+| `--ui-focus-ring` |
+| `--ui-font` |
+| `--ui-font-size` |
+| `--ui-font-size-sm` |
+| `--ui-font-size-xs` |
+| `--ui-hover-overlay` |
+| `--ui-primary` |
+| `--ui-radius-sm` |
+| `--ui-success` |
+| `--ui-surface` |
+| `--ui-surface-muted` |
+| `--ui-text` |
+| `--ui-text-muted` |

package/docs/calendar-year.md

@@ -0,0 +1,53 @@
+# `<calendar-year>`
+
+A full year of `calendar-month` blocks, generated from declarative
+`calendar-entry` children. Each entry is re-projected into the
+`calendar-month` blocks it overlaps as a freshly-created `calendar-entry`
+element — the original elements stay slotted here and are never moved,
+since a DOM node can only have one parent. Read-only.
+
+## Install
+
+```js
+import "@f-ewald/components/calendar-year.js";
+```
+
+## Usage
+
+```html
+<calendar-year year="2026">
+  <calendar-entry start="2026-01-28" end="2026-02-03" label="Offsite" color="primary" href="#offsite">
+    <span slot="detail">New York</span>
+    <span slot="detail">Team workshops</span>
+    <span slot="footer">Closing dinner Friday</span>
+  </calendar-entry>
+  <calendar-entry start="2026-03-05" end="2026-03-18" label="Product launch" color="success" href="#launch">
+    <span slot="detail">Coordinate the release across engineering, design, support, and marketing.</span>
+    <span slot="detail">Monitor adoption and production health throughout the rollout.</span>
+    <span slot="footer">Public launch · March 18 at 9 AM</span>
+  </calendar-entry>
+  <calendar-entry start="2026-07-10" end="2026-07-18" label="Vacation" color="success"></calendar-entry>
+</calendar-year>
+```
+
+## Attributes / properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `year` | `year` | `number` | `—` | Calendar year to render all 12 months for, e.g. `2026`. |
+
+## Events
+
+_None._
+
+## Slots
+
+| Slot | Description |
+| --- | --- |
+| `(default)` | Declarative `calendar-entry` elements spanning the displayed year, re-projected into each month. |
+
+## CSS custom properties
+
+| Custom property |
+| --- |
+| `--ui-font` |

package/docs/dropdown-button.md

@@ -0,0 +1,61 @@
+# `<dropdown-button>`
+
+A primary-styled button with a label and chevron that opens an anchored
+menu of actions — essentially `form-select` minus "current value"
+semantics: a menu, not a select. Use for a set of mutually exclusive
+next-step actions (e.g. a failed task's Retry / Close / Backlog).
+
+## Install
+
+```js
+import "@f-ewald/components/dropdown-button.js";
+```
+
+## Usage
+
+```html
+<dropdown-button label="Resolve…"></dropdown-button>
+<script type="module">
+  const dropdown = document.querySelector("dropdown-button");
+  dropdown.options = [
+    { value: "retry", label: "Retry" },
+    { value: "close", label: "Close" },
+    { value: "backlog", label: "Backlog" },
+  ];
+  dropdown.addEventListener("select", (e) => console.log(e.detail.value));
+</script>
+```
+
+## Attributes / properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `label` | `label` | `string` | `""` | The trigger button's label. |
+| `options` | _(JS property only)_ | `DropdownOption[]` | `[]` | The menu's actions. |
+| `disabled` | `disabled` | `boolean` | `false` | Disables the trigger, preventing the menu from opening. |
+
+## Events
+
+| Event | Description |
+| --- | --- |
+| `select` | Fired with `{ value: string }` when a menu item is picked. |
+
+## Slots
+
+_None._
+
+## CSS custom properties
+
+| Custom property |
+| --- |
+| `--ui-border` |
+| `--ui-focus-ring` |
+| `--ui-font` |
+| `--ui-font-size-sm` |
+| `--ui-primary` |
+| `--ui-primary-hover` |
+| `--ui-radius-sm` |
+| `--ui-shadow` |
+| `--ui-surface` |
+| `--ui-surface-muted` |
+| `--ui-text` |

package/docs/form-select.md

@@ -6,6 +6,19 @@ a native `<select>` wherever consistent cross-browser styling and a
 `change` event carrying `{ value }` are wanted (e.g. a task's status
 picker).
 
+The trigger fills its host's width (`justify-content: space-between`
+pushes the chevron to the far edge), but the host itself stays
+`display: inline-block` — so usages that never size the host (a filter
+bar, a status picker) keep shrink-to-fit auto-width unchanged. To make an
+instance full-width, size the host itself: `form-select { width: 100%; }`.
+
+Set `searchable` to replace the button trigger with an editable combobox
+that filters the predefined options by case-insensitive label infix. Typed
+text is only a query: `value` changes exclusively when an actual option is
+selected, and an uncommitted query is discarded when the list closes.
+Each option may also provide a pre-rendered `icon` and square `iconSize`;
+iconless options reserve no leading space.
+
 ## Install
 
 ```js
@@ -15,13 +28,17 @@ import "@f-ewald/components/form-select.js";
 ## Usage
 
 ```html
-<form-select label="Task state"></form-select>
+<form-select label="Task state" searchable></form-select>
 <script type="module">
+  import { iconArrowPath, iconCheckCircle, iconListBullet } from "@f-ewald/components/icons.js";
+
   const select = document.querySelector("form-select");
   select.options = [
+    { value: "backlog", label: "Backlog", icon: iconListBullet(14), iconSize: 14 },
     { value: "open", label: "Open" },
-    { value: "in_progress", label: "In progress" },
-    { value: "done", label: "Done" },
+    { value: "in_progress", label: "In progress", icon: iconArrowPath(16), iconSize: 16 },
+    { value: "review", label: "Needs review" },
+    { value: "done", label: "Done", icon: iconCheckCircle(16), iconSize: 16 },
   ];
   select.value = "open";
   select.addEventListener("change", (e) => console.log(e.detail.value));
@@ -36,6 +53,7 @@ import "@f-ewald/components/form-select.js";
 | `value` | `value` | `string` | `""` | Currently selected value; must match one of `options[].value`. |
 | `label` | `label` | `string` | `""` | `aria-label` applied to the trigger button. |
 | `disabled` | `disabled` | `boolean` | `false` | Disables the trigger, preventing the popover from opening. |
+| `searchable` | `searchable` | `boolean` | `false` | Enables editable, case-insensitive infix filtering by option label. Typed text never becomes the selected `value`. |
 
 ## Events
 

package/docs/frame-box.md

@@ -0,0 +1,43 @@
+# `<frame-box>`
+
+A titled frame around a slot: a gray border with a small uppercase,
+muted label overlapping the top edge (fieldset/legend-style). Generic —
+the label text is entirely up to the consumer (e.g. "Debug" to visually
+fence off dev-only chrome from the product UI).
+
+## Install
+
+```js
+import "@f-ewald/components/frame-box.js";
+```
+
+## Usage
+
+```html
+<frame-box label="Debug">
+  Framed content goes here.
+</frame-box>
+```
+
+## Attributes / properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `label` | `label` | `string` | `""` | The overlapping title label, e.g. "Debug". |
+
+## Events
+
+_None._
+
+## Slots
+
+_None._
+
+## CSS custom properties
+
+| Custom property |
+| --- |
+| `--ui-border` |
+| `--ui-radius-sm` |
+| `--ui-surface` |
+| `--ui-text-muted` |

package/docs/icon-button.md

@@ -0,0 +1,52 @@
+# `<icon-button>`
+
+A borderless button wrapping a passed-in icon, with a rounded
+hover-highlight background. Use for a low-emphasis affordance next to
+content it acts on (e.g. an "Edit" pencil at the end of a table row)
+where a bordered `ui-button` would be too heavy.
+
+## Install
+
+```js
+import "@f-ewald/components/icon-button.js";
+```
+
+## Usage
+
+```html
+<icon-button label="Edit"></icon-button>
+<script type="module">
+  import { iconPencil } from "@f-ewald/components/icons.js";
+  const btn = document.querySelector("icon-button");
+  btn.icon = iconPencil(16);
+  btn.addEventListener("click", () => console.log("edit clicked"));
+</script>
+```
+
+## Attributes / properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `icon` | _(JS property only)_ | `TemplateResult | null` | `null` | Pre-rendered icon template, e.g. `iconPencil(16)` from this package's icon set. |
+| `label` | `label` | `string` | `""` | Required accessible label, applied as `aria-label`/`title`. |
+| `disabled` | `disabled` | `boolean` | `false` | Disables the button and dims it. |
+
+## Events
+
+| Event | Description |
+| --- | --- |
+| `click` | Native click, bubbling as usual — listen on the element itself. |
+
+## Slots
+
+_None._
+
+## CSS custom properties
+
+| Custom property |
+| --- |
+| `--ui-focus-ring` |
+| `--ui-radius-sm` |
+| `--ui-surface-muted` |
+| `--ui-text` |
+| `--ui-text-muted` |

package/docs/map-circle.md

@@ -5,6 +5,9 @@ outer ring, no point/tail (unlike `<map-pin>`) — for markers that don't
 need to visually "point" at their exact coordinate. Purely a visual
 primitive — it has no `mapbox-gl` (or any mapping library) dependency;
 the consumer positions it, e.g. via `new mapboxgl.Marker({ element: el })`.
+It can also replace the former `<map-point>` dense-layer primitive: use
+`size="14" ring-width="3"`, leave the slot empty, and rasterize one marker
+per color for use as a map `icon-image`.
 
 ## Install
 
@@ -16,6 +19,7 @@ import "@f-ewald/components/map-circle.js";
 
 ```html
 <map-circle color="#6b7280"></map-circle>
+<map-circle color="#0099D8" size="14" ring-width="3"></map-circle>
 <map-circle color="#1a73e8" size="24" ring-width="5" highlighted>1</map-circle>
 ```
 

package/docs/mcp-evaluation.md

@@ -1,31 +1,38 @@
 # MCP server evaluation
 
-**Recommendation: do not build an MCP server for this package now.**
+**Update (0.6.0 era, 34 components): built.** The catalog crossed the ~30+
+revisit threshold below, so the upgrade path described here was implemented
+as `src/mcp-server.ts`. See the "MCP server" section in the root `CLAUDE.md`
+for the current tools, build step, and how consuming projects wire it up.
+The original evaluation is kept below for the reasoning that justified
+waiting until this point.
+
+## Original recommendation (superseded): do not build an MCP server yet
 
 ## Rationale
 
-The component catalog is small (14 tags). `llms.txt` ships in the npm
+The component catalog was small (14 tags). `llms.txt` ships in the npm
 package and is fetchable directly from unpkg or GitHub raw, so any LLM or
 agent can load the full API surface — every component's attributes,
 properties, events, slots, tokens, and a usage example — in one small file,
 with no server, process, or additional versioning/packaging burden. An MCP
 server would duplicate that same data behind a stdio process that needs its
 own install, auth-free-but-still-a-process lifecycle, and release cadence
-kept in sync with the package — for zero functional gain at this scale.
+kept in sync with the package — for zero functional gain at that scale.
 
-## When to revisit
+## When to revisit (met)
 
 - The catalog grows past a size where `llms.txt` stops being comfortable to
-  load into a single context window (rule of thumb: ~30+ components).
+  load into a single context window (rule of thumb: ~30+ components). —
+  **met at 34 components.**
 - Consumers want live search, fuzzy matching, or filtered/paginated results
   instead of "load everything."
 - Consumers want examples or docs that go beyond what's derivable from
   `custom-elements.json` (e.g. runnable playground snippets, live preview).
 
-## Upgrade path
+## Upgrade path (implemented)
 
-If/when it's warranted, a thin stdio MCP server exposing two tools —
-`list_components` and `get_component_docs(tag)` — backed by the same
-`custom-elements.json` this package already generates and ships. No new
-data source would be needed; the server would just be a different transport
-over data that already exists.
+A thin stdio MCP server exposing two tools — `list_components` and
+`get_component_docs(tag)` — backed by the same `custom-elements.json` this
+package already generates and ships. No new data source was needed; the
+server is just a different transport over data that already existed.

package/docs/popover-panel.md

@@ -48,7 +48,11 @@ import "@f-ewald/components/popover-panel.js";
 
 ## Slots
 
-_None._
+| Slot | Description |
+| --- | --- |
+| `(default)` | Popover body content. |
+| `title` | Overrides the plain `heading` text with custom markup. |
+| `actions` | Extra header controls (e.g. an icon+label link) rendered between the title and the close button. |
 
 ## CSS custom properties