@f-ewald/components 0.6.0 → 0.7.0

package/README.md

@@ -50,10 +50,13 @@ import "@f-ewald/components/roman-numeral.js";
 | `<data-table>` | [docs/data-table.md](./docs/data-table.md) |
 | `<distance-value>` | [docs/distance-value.md](./docs/distance-value.md) |
 | `<distribution-chart>` | [docs/distribution-chart.md](./docs/distribution-chart.md) |
+| `<dropdown-button>` | [docs/dropdown-button.md](./docs/dropdown-button.md) |
 | `<editable-text>` | [docs/editable-text.md](./docs/editable-text.md) |
 | `<form-select>` | [docs/form-select.md](./docs/form-select.md) |
+| `<frame-box>` | [docs/frame-box.md](./docs/frame-box.md) |
 | `<gallery-item>` | [docs/gallery-item.md](./docs/gallery-item.md) |
 | `<gallery-item-variant>` | [docs/gallery-item-variant.md](./docs/gallery-item-variant.md) |
+| `<icon-button>` | [docs/icon-button.md](./docs/icon-button.md) |
 | `<live-timer>` | [docs/live-timer.md](./docs/live-timer.md) |
 | `<map-circle>` | [docs/map-circle.md](./docs/map-circle.md) |
 | `<map-pin>` | [docs/map-pin.md](./docs/map-pin.md) |
@@ -120,6 +123,36 @@ set. Don't reintroduce that pattern.)
 
 The full token set is defined in [`src/tokens.ts`](./src/tokens.ts).
 
+## MCP server
+
+`npm run mcp` (or `node dist/mcp-server.js` after `npm run build`) starts a
+stdio [MCP](https://modelcontextprotocol.io) server exposing the component
+catalog to AI coding assistants, with two tools:
+
+- `list_components` — every tag + one-line description.
+- `get_component_docs(tag)` — the full generated Markdown doc for one tag
+  (install snippet, usage example, attributes/properties, events, slots,
+  CSS custom properties).
+
+It's read-only over the same `custom-elements.json`/`docs/*.md` this package
+already generates via `npm run docs` — no separate data source to maintain.
+A consuming project wires it up with a `.mcp.json` at its repo root:
+
+```json
+{
+  "mcpServers": {
+    "f-ewald-components": {
+      "command": "node",
+      "args": ["/absolute/path/to/components/dist/mcp-server.js"]
+    }
+  }
+}
+```
+
+See the "MCP server" section in [`CLAUDE.md`](./CLAUDE.md) for more, and
+[`docs/mcp-evaluation.md`](./docs/mcp-evaluation.md) for why this was built
+now rather than earlier.
+
 ## Playground / development
 
 ```bash
@@ -145,6 +178,7 @@ npm run build:demo   # static build of the playground, into demo-dist/
 | `npm run icons` | Regenerate `src/icons.ts` from the Heroicons package. |
 | `npm run analyze` | Regenerate `custom-elements.json` via the custom-elements-manifest analyzer. |
 | `npm run docs` | Regenerate the manifest, `docs/*.md`, and `llms.txt`. |
+| `npm run mcp` | Run the MCP server (`dist/mcp-server.js`) directly, for manual testing. |
 | `npm run test` | Run the Playwright suite against the playground. |
 
 ## Contributing

package/custom-elements.json

@@ -2008,6 +2008,203 @@
         }
       ]
     },
+    {
+      "kind": "javascript-module",
+      "path": "src/dropdown-button.ts",
+      "declarations": [
+        {
+          "kind": "class",
+          "description": "A primary-styled button with a label and chevron that opens an anchored\nmenu of actions — essentially `form-select` minus \"current value\"\nsemantics: a menu, not a select. Use for a set of mutually exclusive\nnext-step actions (e.g. a failed task's Retry / Close / Backlog).",
+          "name": "DropdownButton",
+          "members": [
+            {
+              "kind": "field",
+              "name": "label",
+              "type": {
+                "text": "string"
+              },
+              "default": "\"\"",
+              "description": "The trigger button's label.",
+              "attribute": "label"
+            },
+            {
+              "kind": "field",
+              "name": "options",
+              "type": {
+                "text": "DropdownOption[]"
+              },
+              "default": "[]",
+              "description": "The menu's actions."
+            },
+            {
+              "kind": "field",
+              "name": "disabled",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Disables the trigger, preventing the menu from opening.",
+              "attribute": "disabled"
+            },
+            {
+              "kind": "field",
+              "name": "_open",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "private",
+              "default": "false"
+            },
+            {
+              "kind": "field",
+              "name": "_activeIndex",
+              "type": {
+                "text": "number"
+              },
+              "privacy": "private",
+              "default": "-1"
+            },
+            {
+              "kind": "field",
+              "name": "#onWindowMousedown",
+              "privacy": "private"
+            },
+            {
+              "kind": "method",
+              "name": "#toggle",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              }
+            },
+            {
+              "kind": "method",
+              "name": "#select",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "option",
+                  "type": {
+                    "text": "DropdownOption"
+                  }
+                }
+              ]
+            },
+            {
+              "kind": "method",
+              "name": "#onTriggerKeydown",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "e",
+                  "type": {
+                    "text": "KeyboardEvent"
+                  }
+                }
+              ]
+            },
+            {
+              "kind": "method",
+              "name": "#moveActive",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "delta",
+                  "type": {
+                    "text": "number"
+                  }
+                }
+              ]
+            },
+            {
+              "kind": "method",
+              "name": "#confirmActive",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              }
+            },
+            {
+              "kind": "method",
+              "name": "renderMenu",
+              "privacy": "private"
+            }
+          ],
+          "events": [
+            {
+              "name": "select",
+              "type": {
+                "text": "CustomEvent"
+              },
+              "description": "Fired with `{ value: string }` when a menu item is picked."
+            }
+          ],
+          "attributes": [
+            {
+              "name": "label",
+              "type": {
+                "text": "string"
+              },
+              "default": "\"\"",
+              "description": "The trigger button's label.",
+              "fieldName": "label"
+            },
+            {
+              "name": "disabled",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Disables the trigger, preventing the menu from opening.",
+              "fieldName": "disabled"
+            }
+          ],
+          "superclass": {
+            "name": "LitElement",
+            "package": "lit"
+          },
+          "tagName": "dropdown-button",
+          "customElement": true
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "DropdownButton",
+          "declaration": {
+            "name": "DropdownButton",
+            "module": "src/dropdown-button.ts"
+          }
+        },
+        {
+          "kind": "custom-element-definition",
+          "name": "dropdown-button",
+          "declaration": {
+            "name": "DropdownButton",
+            "module": "src/dropdown-button.ts"
+          }
+        }
+      ]
+    },
     {
       "kind": "javascript-module",
       "path": "src/editable-text.ts",
@@ -2246,7 +2443,7 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "A styled dropdown select: a trigger button showing the current option's\nlabel, opening a listbox popover on click. Drop-in generic replacement for\na native `<select>` wherever consistent cross-browser styling and a\n`change` event carrying `{ value }` are wanted (e.g. a task's status\npicker).",
+          "description": "A styled dropdown select: a trigger button showing the current option's\nlabel, opening a listbox popover on click. Drop-in generic replacement for\na native `<select>` wherever consistent cross-browser styling and a\n`change` event carrying `{ value }` are wanted (e.g. a task's status\npicker).\n\nThe trigger fills its host's width (`justify-content: space-between`\npushes the chevron to the far edge), but the host itself stays\n`display: inline-block` — so usages that never size the host (a filter\nbar, a status picker) keep shrink-to-fit auto-width unchanged. To make an\ninstance full-width, size the host itself: `form-select { width: 100%; }`.",
           "name": "FormSelect",
           "members": [
             {
@@ -2456,6 +2653,70 @@
         }
       ]
     },
+    {
+      "kind": "javascript-module",
+      "path": "src/frame-box.ts",
+      "declarations": [
+        {
+          "kind": "class",
+          "description": "A titled frame around a slot: a gray border with a small uppercase,\nmuted label overlapping the top edge (fieldset/legend-style). Generic —\nthe label text is entirely up to the consumer (e.g. \"Debug\" to visually\nfence off dev-only chrome from the product UI).",
+          "name": "FrameBox",
+          "slots": [
+            {
+              "description": "Framed content.",
+              "name": ""
+            }
+          ],
+          "members": [
+            {
+              "kind": "field",
+              "name": "label",
+              "type": {
+                "text": "string"
+              },
+              "default": "\"\"",
+              "description": "The overlapping title label, e.g. \"Debug\".",
+              "attribute": "label"
+            }
+          ],
+          "attributes": [
+            {
+              "name": "label",
+              "type": {
+                "text": "string"
+              },
+              "default": "\"\"",
+              "description": "The overlapping title label, e.g. \"Debug\".",
+              "fieldName": "label"
+            }
+          ],
+          "superclass": {
+            "name": "LitElement",
+            "package": "lit"
+          },
+          "tagName": "frame-box",
+          "customElement": true
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "FrameBox",
+          "declaration": {
+            "name": "FrameBox",
+            "module": "src/frame-box.ts"
+          }
+        },
+        {
+          "kind": "custom-element-definition",
+          "name": "frame-box",
+          "declaration": {
+            "name": "FrameBox",
+            "module": "src/frame-box.ts"
+          }
+        }
+      ]
+    },
     {
       "kind": "javascript-module",
       "path": "src/gallery-item-variant.ts",
@@ -2645,6 +2906,98 @@
         }
       ]
     },
+    {
+      "kind": "javascript-module",
+      "path": "src/icon-button.ts",
+      "declarations": [
+        {
+          "kind": "class",
+          "description": "A borderless button wrapping a passed-in icon, with a rounded\nhover-highlight background. Use for a low-emphasis affordance next to\ncontent it acts on (e.g. an \"Edit\" pencil at the end of a table row)\nwhere a bordered `ui-button` would be too heavy.",
+          "name": "IconButton",
+          "members": [
+            {
+              "kind": "field",
+              "name": "icon",
+              "type": {
+                "text": "TemplateResult | null"
+              },
+              "default": "null",
+              "description": "Pre-rendered icon template, e.g. `iconPencil(16)` from this package's icon set."
+            },
+            {
+              "kind": "field",
+              "name": "label",
+              "type": {
+                "text": "string"
+              },
+              "default": "\"\"",
+              "description": "Required accessible label, applied as `aria-label`/`title`.",
+              "attribute": "label"
+            },
+            {
+              "kind": "field",
+              "name": "disabled",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Disables the button and dims it.",
+              "attribute": "disabled"
+            }
+          ],
+          "events": [
+            {
+              "description": "Native click, bubbling as usual — listen on the element itself.",
+              "name": "click"
+            }
+          ],
+          "attributes": [
+            {
+              "name": "label",
+              "type": {
+                "text": "string"
+              },
+              "default": "\"\"",
+              "description": "Required accessible label, applied as `aria-label`/`title`.",
+              "fieldName": "label"
+            },
+            {
+              "name": "disabled",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Disables the button and dims it.",
+              "fieldName": "disabled"
+            }
+          ],
+          "superclass": {
+            "name": "LitElement",
+            "package": "lit"
+          },
+          "tagName": "icon-button",
+          "customElement": true
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "IconButton",
+          "declaration": {
+            "name": "IconButton",
+            "module": "src/icon-button.ts"
+          }
+        },
+        {
+          "kind": "custom-element-definition",
+          "name": "icon-button",
+          "declaration": {
+            "name": "IconButton",
+            "module": "src/icon-button.ts"
+          }
+        }
+      ]
+    },
     {
       "kind": "javascript-module",
       "path": "src/icons.ts",
@@ -3028,6 +3381,16 @@
               "default": "18"
             }
           ]
+        },
+        {
+          "kind": "function",
+          "name": "iconArrowTopRightOnSquare",
+          "parameters": [
+            {
+              "name": "size",
+              "default": "16"
+            }
+          ]
         }
       ],
       "exports": [
@@ -3334,6 +3697,14 @@
             "name": "iconChatBubbleLeftRight",
             "module": "src/icons.ts"
           }
+        },
+        {
+          "kind": "js",
+          "name": "iconArrowTopRightOnSquare",
+          "declaration": {
+            "name": "iconArrowTopRightOnSquare",
+            "module": "src/icons.ts"
+          }
         }
       ]
     },
@@ -3782,6 +4153,38 @@
             "module": "./popover-panel.js"
           }
         },
+        {
+          "kind": "js",
+          "name": "DropdownButton",
+          "declaration": {
+            "name": "DropdownButton",
+            "module": "./dropdown-button.js"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "DropdownOption",
+          "declaration": {
+            "name": "DropdownOption",
+            "module": "./dropdown-button.js"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "IconButton",
+          "declaration": {
+            "name": "IconButton",
+            "module": "./icon-button.js"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "FrameBox",
+          "declaration": {
+            "name": "FrameBox",
+            "module": "./frame-box.js"
+          }
+        },
         {
           "kind": "js",
           "name": "formatDuration",
@@ -4303,6 +4706,12 @@
         }
       ]
     },
+    {
+      "kind": "javascript-module",
+      "path": "src/mcp-server.ts",
+      "declarations": [],
+      "exports": []
+    },
     {
       "kind": "javascript-module",
       "path": "src/percent-bar-chart.ts",
@@ -5066,6 +5475,20 @@
           "kind": "class",
           "description": "Generic anchored popover shell: a floating card positioned relative to its\nnearest `position: relative` ancestor (place it next to its trigger button\ninside such a wrapper), as opposed to `slide-panel`'s fixed screen-edge\ndrawer. Closes on outside click or Escape. Header chrome and close button\nmatch `slide-panel`'s API (`heading`, `panel-close`) so either can be\nswapped in for the other with no consumer-side changes beyond the wrapper.\n\nSet `centered` to render as a screen-centered modal with a translucent\nbackdrop instead of the default anchored placement.",
           "name": "PopoverPanel",
+          "slots": [
+            {
+              "description": "Overrides the plain `heading` text with custom markup.",
+              "name": "title"
+            },
+            {
+              "description": "Extra header controls (e.g. an icon+label link) rendered between the title and the close button.",
+              "name": "actions"
+            },
+            {
+              "description": "Popover body content.",
+              "name": ""
+            }
+          ],
           "members": [
             {
               "kind": "field",

package/dist/dropdown-button.d.ts

@@ -0,0 +1,37 @@
+import { LitElement, type PropertyValues } from "lit";
+/** A single menu action. */
+export interface DropdownOption {
+    value: string;
+    label: string;
+}
+/**
+ * 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).
+ *
+ * @element dropdown-button
+ * @fires select - Fired with `{ value: string }` when a menu item is picked.
+ */
+export declare class DropdownButton extends LitElement {
+    #private;
+    static styles: import("lit").CSSResult[];
+    /** The trigger button's label. */
+    label: string;
+    /** The menu's actions. */
+    options: DropdownOption[];
+    /** Disables the trigger, preventing the menu from opening. */
+    disabled: boolean;
+    private _open;
+    private _activeIndex;
+    disconnectedCallback(): void;
+    protected updated(changed: PropertyValues): void;
+    private renderMenu;
+    render(): import("lit-html").TemplateResult<1>;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        "dropdown-button": DropdownButton;
+    }
+}
+//# sourceMappingURL=dropdown-button.d.ts.map

package/dist/dropdown-button.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dropdown-button.d.ts","sourceRoot":"","sources":["../src/dropdown-button.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAsB,KAAK,cAAc,EAAE,MAAM,KAAK,CAAC;AAK1E,4BAA4B;AAC5B,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;GAQG;AACH,qBACa,cAAe,SAAQ,UAAU;;IAC5C,OAAgB,MAAM,4BAoEpB;IAEF,kCAAkC;IACtB,KAAK,SAAM;IACvB,0BAA0B;IACM,OAAO,EAAE,cAAc,EAAE,CAAM;IAC/D,8DAA8D;IACjC,QAAQ,UAAS;IAErC,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,YAAY,CAAM;IAE1B,oBAAoB,IAAI,IAAI,CAGpC;IAED,UAAmB,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,IAAI,CAQxD;IA4CD,OAAO,CAAC,UAAU;IAsBT,MAAM,yCAgBd;CACF;AAED,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,qBAAqB;QAC7B,iBAAiB,EAAE,cAAc,CAAC;KACnC;CACF"}