@f-ewald/components 0.6.0 → 0.7.0

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
 

package/llms.txt

@@ -246,6 +246,33 @@ Example:
 </script>
 ```
 
+## <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).
+
+Import: `import "@f-ewald/components/dropdown-button.js";`
+
+Properties: `label` (attribute `label`) : string, default ""; `options` (JS property only) : DropdownOption[], default []; `disabled` (attribute `disabled`) : boolean, default false
+Events: `select`
+CSS custom properties: `--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`
+
+Example:
+```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>
+```
+
 ## <editable-text>
 
 Jira/GitHub-style click-to-edit text: a display span that turns into an
@@ -273,6 +300,12 @@ 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%; }`.
+
 Import: `import "@f-ewald/components/form-select.js";`
 
 Properties: `options` (JS property only) : SelectOption[], default []; `value` (attribute `value`) : string, default ""; `label` (attribute `label`) : string, default ""; `disabled` (attribute `disabled`) : boolean, default false
@@ -294,6 +327,26 @@ Example:
 </script>
 ```
 
+## <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).
+
+Import: `import "@f-ewald/components/frame-box.js";`
+
+Properties: `label` (attribute `label`) : string, default ""
+Events: none
+CSS custom properties: `--ui-border`, `--ui-radius-sm`, `--ui-surface`, `--ui-text-muted`
+
+Example:
+```html
+<frame-box label="Debug">
+  Framed content goes here.
+</frame-box>
+```
+
 ## <gallery-item>
 
 Declarative image metadata consumed by a parent `photo-gallery`.
@@ -336,6 +389,30 @@ Example:
 ></gallery-item-variant>
 ```
 
+## <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.
+
+Import: `import "@f-ewald/components/icon-button.js";`
+
+Properties: `icon` (JS property only) : TemplateResult | null, default null; `label` (attribute `label`) : string, default ""; `disabled` (attribute `disabled`) : boolean, default false
+Events: `click`
+CSS custom properties: `--ui-focus-ring`, `--ui-radius-sm`, `--ui-surface-muted`, `--ui-text`, `--ui-text-muted`
+
+Example:
+```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>
+```
+
 ## <live-timer>
 
 Per-second ticking count-up timer, e.g. a live "running for 12s" or

package/package.json

@@ -1,12 +1,15 @@
 {
   "name": "@f-ewald/components",
   "private": false,
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "A collection of universally usable web components for various tasks.",
   "type": "module",
   "main": "dist/index.js",
   "module": "dist/index.js",
   "types": "dist/index.d.ts",
+  "bin": {
+    "f-ewald-components-mcp": "dist/mcp-server.js"
+  },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -31,11 +34,12 @@
   ],
   "scripts": {
     "dev": "vite",
-    "build": "rm -rf dist && tsc && node scripts/generate-tokens-css.mjs",
+    "build": "rm -rf dist && tsc && node scripts/generate-tokens-css.mjs && chmod +x dist/mcp-server.js",
     "build:demo": "vite build",
     "analyze": "cem analyze --litelement --globs \"src/**/*.ts\"",
     "docs": "npm run analyze && node scripts/generate-docs.mjs",
     "icons": "node scripts/generate-icons.mjs",
+    "mcp": "node dist/mcp-server.js",
     "test": "playwright test",
     "prepublishOnly": "npm run build && npm run docs && npm run test"
   },
@@ -45,10 +49,12 @@
   "author": "Friedrich Ewald",
   "license": "BSD-3-Clause",
   "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
     "d3-array": "^3.2.4",
     "d3-scale": "^4.0.2",
     "d3-shape": "^3.2.0",
-    "lit": "^3.3.3"
+    "lit": "^3.3.3",
+    "zod": "^4.4.3"
   },
   "publishConfig": {
     "access": "public"
@@ -61,6 +67,7 @@
     "@types/d3-array": "^3.2.2",
     "@types/d3-scale": "^4.0.9",
     "@types/d3-shape": "^3.1.8",
+    "@types/node": "^26.1.1",
     "heroicons": "^2.2.0",
     "tailwindcss": "^4.3.3",
     "typescript": "^7.0.2",