@akonwi/mica 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Akonwi Ngoh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,81 @@
+# mica
+
+**Custom elements. Native behavior. Nearly no JavaScript.**
+
+Mica is a front-end library built from custom element tags, native HTML
+elements, and CSS. No runtime, no build step, no framework. View source —
+there's nothing there but HTML and a stylesheet.
+
+```html
+<link rel="stylesheet" href="mica.css">
+
+<m-vstack gap="lg">
+  <h1>That's it</h1>
+  <m-hstack gap="sm">
+    <button class="primary">Save</button>
+    <button class="ghost">Cancel</button>
+  </m-hstack>
+</m-vstack>
+```
+
+`<m-vstack>` is never registered — an unknown custom element is a valid,
+stylable element. The behavior everywhere else (dialogs, accordions, menus,
+form validation) comes from the browser, not from a runtime.
+
+## Getting it
+
+**Copy the file** — mica is one dependency-free CSS file. Vendoring is a
+first-class distribution channel, not a workaround:
+
+```sh
+curl -O https://raw.githubusercontent.com/akonwi/mica/v0.1.0/mica.css
+```
+
+**npm** — for toolchains:
+
+```sh
+npm install @akonwi/mica
+```
+
+```js
+import "@akonwi/mica/mica.css";
+```
+
+**CDN** — for trying it out:
+
+```html
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@akonwi/mica@0.1/mica.css">
+```
+
+## The three tiers
+
+Every component states where its behavior comes from
+(see [TIERS.md](TIERS.md)):
+
+- **Tier 0 — CSS is the behavior.** Layout primitives: `m-vstack`,
+  `m-hstack`, `m-zstack`, `m-center`, `m-box`, `m-grid`, `m-sidecar`,
+  `m-switcher`, `m-reel`. Zero JS, work with JS disabled.
+- **Tier 1 — the browser is the behavior.** Styled native elements:
+  buttons, forms, `<dialog>`, `<details>` accordions, popover menus,
+  tooltips, toasts. Delete the stylesheet and everything still works.
+- **Tier 2 — script, honestly.** Where accessibility genuinely requires
+  JS: `tabs.js`, `combobox.js`, `field.js` (declarative validation),
+  `select.js`, `toast.js`. Each is a tiny standalone module that enhances
+  working markup — never renders it. There is no shared runtime.
+
+## Your CSS always wins
+
+All of mica ships inside `@layer mica.*`. Unlayered user CSS beats layered
+CSS by spec — overriding mica never requires specificity games. Theming is
+swapping token values (`--hue`, semantic color roles, spacing scale); dark
+mode is `light-dark()` — automatic, no classes.
+
+## Docs
+
+Read [VISION.md](VISION.md) for the philosophy, [TIERS.md](TIERS.md) for
+the tier system, and the `docs/` pages for every component. Or open
+`demo.html` — the whole library on one page.
+
+## License
+
+[MIT](LICENSE)

package/combobox.js

@@ -0,0 +1,138 @@
+/* mica/combobox.js — <m-combobox>: filterable input + listbox. Tier 2.
+ *
+ * The no-JS state is a native <datalist> — real autocomplete, fully
+ * functional, just unstylable. The module upgrades it into the ARIA
+ * combobox pattern: styled listbox, substring filtering, arrow-key
+ * active-descendant navigation. Options come from the author's
+ * datalist markup — the module presents them, it doesn't invent them.
+ *
+ *   <m-combobox>
+ *     <input list="langs" placeholder="Language…" />
+ *     <datalist id="langs">
+ *       <option>Ard</option>
+ *       <option>Go</option>
+ *     </datalist>
+ *   </m-combobox>
+ */
+
+let uid = 0;
+
+class MCombobox extends HTMLElement {
+  #input;
+  #list;
+  #options = [];
+  #active = -1;
+
+  connectedCallback() {
+    this.#input = this.querySelector("input");
+    const datalist = this.querySelector("datalist");
+    if (!this.#input || !datalist) return;
+
+    // disable the native popup; the module takes over
+    this.#input.removeAttribute("list");
+    this.#input.setAttribute("role", "combobox");
+    this.#input.setAttribute("aria-expanded", "false");
+    this.#input.setAttribute("aria-autocomplete", "list");
+    this.#input.autocomplete = "off";
+
+    const listId = `m-cb-${++uid}`;
+    this.#list = document.createElement("div");
+    this.#list.id = listId;
+    this.#list.setAttribute("role", "listbox");
+    this.#list.hidden = true;
+
+    this.#options = [...datalist.options].map((o, i) => {
+      const d = document.createElement("div");
+      d.setAttribute("role", "option");
+      d.id = `${listId}-${i}`;
+      d.textContent = o.value || o.textContent;
+      // pointerdown so the input never loses focus
+      d.addEventListener("pointerdown", (e) => {
+        e.preventDefault();
+        this.#choose(d);
+      });
+      // hover moves the highlight (cmdk behavior)
+      d.addEventListener("pointerenter", () => {
+        this.#setActive(this.#visible().indexOf(d));
+      });
+      this.#list.append(d);
+      return d;
+    });
+    this.append(this.#list);
+    this.#input.setAttribute("aria-controls", listId);
+
+    this.#input.addEventListener("input", (e) => {
+      // ignore our own dispatched events from #choose — they'd reopen
+      if (e.isTrusted) this.#openAndFilter();
+    });
+    this.#input.addEventListener("keydown", (e) => this.#onKey(e));
+    this.addEventListener("focusout", (e) => {
+      if (!this.contains(e.relatedTarget)) this.#close();
+    });
+  }
+
+  #visible() {
+    return this.#options.filter((o) => !o.hidden);
+  }
+
+  #openAndFilter() {
+    const q = this.#input.value.trim().toLowerCase();
+    let any = false;
+    for (const o of this.#options) {
+      o.hidden = q !== "" && !o.textContent.toLowerCase().includes(q);
+      if (!o.hidden) any = true;
+    }
+    this.#list.hidden = !any;
+    this.#input.setAttribute("aria-expanded", String(any));
+    // first match is pre-highlighted so Enter always has a target
+    this.#setActive(any ? 0 : -1);
+  }
+
+  #close() {
+    this.#list.hidden = true;
+    this.#input.setAttribute("aria-expanded", "false");
+    this.#setActive(-1);
+  }
+
+  #setActive(i) {
+    const vis = this.#visible();
+    this.#active = i;
+    for (const o of this.#options) o.setAttribute("aria-selected", "false");
+    if (i >= 0 && vis[i]) {
+      vis[i].setAttribute("aria-selected", "true");
+      vis[i].scrollIntoView({ block: "nearest" });
+      this.#input.setAttribute("aria-activedescendant", vis[i].id);
+    } else {
+      this.#input.removeAttribute("aria-activedescendant");
+    }
+  }
+
+  #onKey(e) {
+    const vis = this.#visible();
+    if (e.key === "ArrowDown") {
+      e.preventDefault();
+      if (this.#list.hidden) this.#openAndFilter();
+      if (this.#visible().length) this.#setActive((this.#active + 1) % this.#visible().length);
+    } else if (e.key === "ArrowUp") {
+      e.preventDefault();
+      if (vis.length) this.#setActive((this.#active - 1 + vis.length) % vis.length);
+    } else if (e.key === "Enter") {
+      if (this.#active >= 0 && !this.#list.hidden) {
+        e.preventDefault();
+        this.#choose(vis[this.#active]);
+      }
+    } else if (e.key === "Escape") {
+      this.#close();
+    }
+  }
+
+  #choose(option) {
+    this.#input.value = option.textContent;
+    this.#close();
+    this.#input.dispatchEvent(new Event("input", { bubbles: true }));
+    this.#input.dispatchEvent(new Event("change", { bubbles: true }));
+    this.#input.focus();
+  }
+}
+
+if (!customElements.get("m-combobox")) customElements.define("m-combobox", MCombobox);

package/field.js

@@ -0,0 +1,111 @@
+/* mica/field.js — <m-field>: declarative validation errors. Tier 2.
+ *
+ * Enhances working light-DOM markup; never renders it. Without this
+ * module, fields inside <m-field> fall back to native bubbles plus the
+ * CSS-only generic <m-error> (see mica.css).
+ *
+ *   <m-field>
+ *     <label for="email">Email</label>
+ *     <input id="email" type="email" required>
+ *     <m-error match="value-missing">Email is required.</m-error>
+ *     <m-error match="type-mismatch">Not a valid email.</m-error>
+ *     <m-error></m-error>  <!-- catch-all; empty = browser's message -->
+ *   </m-field>
+ *
+ * What the module does:
+ * - preventDefault() on `invalid` — kills the browser bubble while the
+ *   form still blocks bad submits
+ * - focuses the first invalid field on a submit attempt (the browser
+ *   normally does this; preventDefault suppresses it)
+ * - mirrors ValidityState onto <m-field invalid="value-missing ...">
+ * - activates the first <m-error> whose `match` applies, else the
+ *   catch-all; empty catch-alls get the browser's validationMessage
+ * - wires aria-invalid + aria-describedby to the active error
+ */
+
+const CAUSES = {
+  "value-missing": "valueMissing",
+  "type-mismatch": "typeMismatch",
+  "pattern-mismatch": "patternMismatch",
+  "too-long": "tooLong",
+  "too-short": "tooShort",
+  "range-underflow": "rangeUnderflow",
+  "range-overflow": "rangeOverflow",
+  "step-mismatch": "stepMismatch",
+  "bad-input": "badInput",
+  "custom-error": "customError",
+};
+
+class MField extends HTMLElement {
+  #uid;
+
+  connectedCallback() {
+    this.addEventListener("invalid", this.#onInvalid, true);
+    this.addEventListener("blur", this.#onBlur, true);
+    this.addEventListener("input", this.#onInput);
+  }
+
+  get field() {
+    return this.querySelector("input, textarea, select");
+  }
+
+  #onInvalid = (event) => {
+    event.preventDefault();
+    this.#update(true);
+    // focus the first invalid field on a submit attempt (the browser
+    // normally does this; preventDefault suppressed it). Checked
+    // deterministically — invalid events fire per-field and flags
+    // can't survive the interleaved microtask checkpoints.
+    const form = event.target.form;
+    const first = form?.querySelector(
+      "input:invalid, select:invalid, textarea:invalid",
+    );
+    if (event.target === first) event.target.focus();
+  };
+
+  #onBlur = (event) => {
+    if (event.target.matches?.(":user-invalid")) this.#update(true);
+  };
+
+  #onInput = () => {
+    // once an error is showing, revalidate live so it clears on fix
+    if (this.hasAttribute("invalid")) this.#update(true);
+  };
+
+  #update(show) {
+    const field = this.field;
+    if (!field) return;
+    const errors = [...this.querySelectorAll("m-error")];
+
+    if (field.validity.valid) {
+      this.removeAttribute("invalid");
+      field.removeAttribute("aria-invalid");
+      field.removeAttribute("aria-describedby");
+      for (const el of errors) el.removeAttribute("active");
+      return;
+    }
+    if (!show) return;
+
+    const causes = Object.keys(CAUSES).filter((k) => field.validity[CAUSES[k]]);
+    this.setAttribute("invalid", causes.join(" "));
+
+    const active =
+      errors.find((el) => causes.includes(el.getAttribute("match"))) ??
+      errors.find((el) => !el.hasAttribute("match"));
+    for (const el of errors) el.toggleAttribute("active", el === active);
+
+    if (active) {
+      if ("auto" in active.dataset || !active.textContent.trim()) {
+        active.dataset.auto = "";
+        active.textContent = field.validationMessage;
+      }
+      active.id ||=
+        `m-error-${(this.#uid ??= Math.random().toString(36).slice(2, 8))}` +
+        `-${errors.indexOf(active)}`;
+      field.setAttribute("aria-describedby", active.id);
+      field.setAttribute("aria-invalid", "true");
+    }
+  }
+}
+
+if (!customElements.get("m-field")) customElements.define("m-field", MField);