feat(evo-marko): evo-combobox

.changeset/bright-socks-care.md

@@ -0,0 +1,5 @@
+---
+"@evo-web/marko": patch
+---
+
+Add evo-combobox

.claude/skills/evo-migrate-marko/SKILL.md

@@ -67,6 +67,23 @@ packages/evo-marko/src/tags/evo-{name}/
 
 **Key difference from ebayui-core:** Everything lives in `index.marko`. There is no separate `component.ts`, `component-browser.ts`, or `marko-tag.json`.
 
+### README format
+
+**Minimal only — no props tables, no usage examples, no extra sections.**
+Reference: `packages/evo-marko/src/tags/evo-chip/README.md`
+
+```html
+<h1 style="display: flex; justify-content: space-between; align-items: center;">
+  <span> evo-[name] </span>
+  <span style="font-weight: normal; font-size: medium; margin-bottom: -15px;">
+    DS v1.0.0
+  </span>
+</h1>
+
+One-line description. ## Examples and Documentation - [Storybook](...) -
+[Storybook Docs](...) - [Code Examples](...)
+```
+
 ---
 
 ## Template syntax migration rules

CLAUDE.md

@@ -99,6 +99,14 @@ HTML Semantic Structure → @ebay/skin (CSS/BEM) → Framework Components → In
 
 Declare `<const/>`, `<let/>`, `<id/>`, and other tag variables close to where they are first used, not grouped at the top. Exception is variables needed in multiple distant locations.
 
+**Marko 6 extractor scope bug:** `value?.toString() ?? ""` (optional chain + nullish coalesce) inside a native-tag event handler confuses the Marko language tools extractor and causes all `<let>` assignments in that handler to be flagged as TS2588 "cannot assign to const". Use `String(value ?? "")` instead.
+
+**Marko 6 pass-through event handlers:** Call destructured handlers with `onFoo && onFoo(e, el)`. Do NOT use `(onFoo || null)?.(e, el)` — Marko handler types are not plain functions so optional-call syntax fails type checking.
+
+**Marko 6 event handler types:** Don't annotate `e`/`el` on native HTML tags — types are inferred. `onClick(e) {}` not `onClick(e: MouseEvent) {}`. Exception: dynamic tags (`<${tag}>`) have no type info and require explicit annotations.
+
+**Marko 6 AttrTag content:** When already spreading an AttrTag onto a native element with no other body content, use self-closing — `<button ...button/>`. Never `<button ...button><${button.content}/></button>`.
+
 **React Package Differences:**
 
 - `ebayui-core-react`: Requires `React.forwardRef` wrapper

packages/evo-marko/src/tags/evo-combobox/README.md

@@ -0,0 +1,16 @@
+<h1 style='display: flex; justify-content: space-between; align-items: center;'>
+    <span>
+        evo-combobox
+    </span>
+    <span style='font-weight: normal; font-size: medium; margin-bottom: -15px;'>
+        DS v1.0.0
+    </span>
+</h1>
+
+An accessible combobox input with an optional inline listbox of suggestions.
+
+## Examples and Documentation
+
+- [Storybook](https://ebay.github.io/evo-web/ebayui-core/?path=/story/form-input-evo-combobox)
+- [Storybook Docs](https://ebay.github.io/evo-web/ebayui-core/?path=/docs/form-input-evo-combobox)
+- [Code Examples](https://github.com/eBay/evo-web/tree/main/packages/evo-marko/src/tags/evo-combobox/examples)

packages/evo-marko/src/tags/evo-combobox/combobox.stories.ts

@@ -0,0 +1,130 @@
+import { buildExtensionTemplate } from "../../common/storybook/utils";
+import { type Meta } from "@storybook/marko";
+import Readme from "./README.md";
+import Component, { type Input } from "./index.marko";
+import DefaultTemplate from "./examples/default.marko";
+import DefaultCode from "./examples/default.marko?raw";
+import ControllableTemplate from "./examples/controllable.marko";
+import ControllableCode from "./examples/controllable.marko?raw";
+import AsyncFilteringTemplate from "./examples/async-filtering.marko";
+import AsyncFilteringCode from "./examples/async-filtering.marko?raw";
+
+export default {
+  title: "form input/evo-combobox",
+  component: Component,
+  parameters: {
+    docs: {
+      description: { component: Readme },
+    },
+  },
+  argTypes: {
+    autocomplete: {
+      type: "string",
+      options: ["none", "list"],
+      control: "inline-radio",
+      description:
+        "`list` filters displayed options to those matching the typed text. `none` always shows all options.",
+    },
+    listSelection: {
+      type: "string",
+      options: ["automatic", "manual"],
+      control: "inline-radio",
+      description:
+        "Whether arrow-key navigation writes the highlighted option text into the input automatically.",
+    },
+    floatingLabel: {
+      type: "string",
+      control: "text",
+      description:
+        "Floating label text shown above the input when focused or filled.",
+    },
+    borderless: {
+      type: "boolean",
+      control: "boolean",
+      description: "Removes the control border.",
+    },
+    fluid: {
+      type: "boolean",
+      control: "boolean",
+      description: "Stretches the component to fill its container.",
+    },
+    strategy: {
+      type: "string",
+      options: ["absolute", "fixed"],
+      control: "select",
+      description: "Listbox CSS position strategy (`absolute` by default).",
+    },
+    disabled: {
+      type: "boolean",
+      control: "boolean",
+      description: "Disables the input.",
+    },
+    value: {
+      controllable: true,
+      type: "string",
+      control: "text",
+      description: "Current input value. Two-way bindable via `:=`.",
+    },
+    open: {
+      controllable: true,
+      type: "boolean",
+      control: "boolean",
+      description: "Controls listbox visibility. Two-way bindable via `:=`.",
+    },
+    option: {
+      description: "Repeatable `@option` attribute tag.",
+      "@": {
+        text: {
+          type: { name: "string", required: true },
+          control: "text",
+          description: "Display text for the option.",
+        },
+        value: {
+          type: "string",
+          control: "text",
+          description: "Optional value; defaults to `text`.",
+        },
+        sticky: {
+          type: "boolean",
+          control: "boolean",
+          description: "Always shown regardless of `autocomplete` filter.",
+        },
+        ["<div> attributes" as any]: {
+          description:
+            "All attributes and event handlers from [the native HTML `<div>` tag](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/div) will be passed through to `<@option>`.",
+        },
+      },
+    },
+    button: {
+      description:
+        "Optional `@button` attr tag — renders an icon button inside the control.",
+      "@": {
+        ["<button> attributes" as any]: {
+          description:
+            "All attributes and event handlers from [the native HTML `<button>` tag](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button) will be passed through to `<@button>`.",
+        },
+      },
+    },
+    ["<input> attributes" as any]: {
+      description:
+        "All attributes and event handlers from [the native HTML `<input>` tag](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input) will be passed through.",
+    },
+  },
+} satisfies Meta<Input>;
+
+export const Default = buildExtensionTemplate(DefaultTemplate, DefaultCode, {
+  "aria-label": "Campaign",
+  placeholder: "Choose a campaign",
+});
+
+export const Controllable = buildExtensionTemplate(
+  ControllableTemplate,
+  ControllableCode,
+  { "aria-label": "Campaign", placeholder: "Choose a campaign" },
+);
+
+export const AsyncFiltering = buildExtensionTemplate(
+  AsyncFilteringTemplate,
+  AsyncFilteringCode,
+  { placeholder: "Type a country name..." },
+);

packages/evo-marko/src/tags/evo-combobox/examples/async-filtering.marko

@@ -0,0 +1,24 @@
+import countries from "./data.json" with { type: "json" };
+
+static async function searchCountries(query: string, signal: AbortSignal) {
+    await new Promise((r) => setTimeout(r, 300));
+    if (signal.aborted) return;
+    return query
+        ? countries.filter((c) => c.name.toLowerCase().startsWith(query.toLowerCase())).slice(0, 10)
+        : ([] as typeof countries);
+}
+
+<let/value="">
+<let/options=[] as typeof countries>
+
+<script>
+    const results = await searchCountries(value, $signal);
+    if (results) options = results;
+</script>
+
+<evo-combobox ...input value:=value>
+    <for|country| of=options>
+        <@option data-code=country.code text=country.name/>
+    </for>
+</evo-combobox>
+<p>Selected: ${value || "(none)"}</p>

packages/evo-marko/src/tags/evo-combobox/examples/controllable.marko

@@ -0,0 +1,14 @@
+<let/value="">
+<p>Current value: ${value}</p>
+<evo-combobox ...input value:=value>
+    <@option text="August Campaign"/>
+    <@option text="4th of July Sale (paused)"/>
+    <@option text="Basic Offer"/>
+    <@option text="Basic Offer 1"/>
+    <@option text="Basic Offer 3"/>
+    <if=value>
+        <@button onClick() { value = "" } a11yText="clear">
+            <evo-icon-close-12/>
+        </@button>
+    </if>
+</evo-combobox>