@akonwi/mica 0.7.0 → 0.9.0

package/README.md

@@ -65,6 +65,11 @@ Every component states where its behavior comes from
   `select.js`, `toast.js`. Each is a tiny standalone module that enhances
   working markup — never renders it. There is no shared runtime.
 
+`m-avatar` accepts authored initials or a direct native `img`, both CSS-only.
+`avatar.js` is a separate opt-in visual enhancement: importing it locally
+derives deterministic color and features from the `blobatar` seed without a
+network request.
+
 ## Your CSS always wins
 
 All of mica ships inside `@layer mica.*`. Unlayered user CSS beats layered

package/THIRD_PARTY_LICENSES.md

@@ -0,0 +1,28 @@
+# Third-party licenses
+
+## Blobatar 2.4.0
+
+Mica's optional `avatar.js` module incorporates code from
+[Blobatar](https://github.com/Alain00/blobatar).
+
+MIT License
+
+Copyright (c) 2026 Alain
+
+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/avatar.d.ts

@@ -0,0 +1,10 @@
+/* Type declarations for mica/avatar.js — side-effect module.
+ * Registers <m-avatar> and locally generates Blobatar-derived paint for its
+ * `blobatar` seed. Authored initials remain the no-module fallback.
+ */
+declare global {
+  interface HTMLElementTagNameMap {
+    "m-avatar": HTMLElement;
+  }
+}
+export {};

package/avatar.js

@@ -0,0 +1,301 @@
+/*! mica/avatar.js — generated by tools/build-avatar.ts.
+ * Includes Blobatar 2.4.0 (MIT); see THIRD_PARTY_LICENSES.md. */
+// node_modules/blobatar/dist/index.js
+function L({ l: t, c: n, h: e }) {
+  let o = e * Math.PI / 180, a = n * Math.cos(o), r = n * Math.sin(o), s = t + 0.3963377774 * a + 0.2158037573 * r, c = t - 0.1055613458 * a - 0.0638541728 * r, i = t - 0.0894841775 * a - 1.291485548 * r, m = s * s * s, l = c * c * c, u = i * i * i;
+  return [4.0767416621 * m - 3.3077115913 * l + 0.2309699292 * u, -1.2684380046 * m + 2.6097574011 * l - 0.3413193965 * u, -0.0041960863 * m - 0.7034186147 * l + 1.707614701 * u];
+}
+var q = (t) => t.every((n) => n >= -0.0001 && n <= 1.0001);
+function K(t) {
+  let n = L(t);
+  if (!q(n)) {
+    let e = 0, o = t.c;
+    for (let a = 0;a < 12; a++) {
+      let r = (e + o) / 2;
+      if (q(L({ ...t, c: r })))
+        e = r;
+      else
+        o = r;
+    }
+    n = L({ ...t, c: e });
+  }
+  return n.map((e) => Math.min(1, Math.max(0, e)));
+}
+function D(t) {
+  let [n, e, o] = K(t);
+  return 0.2126 * n + 0.7152 * e + 0.0722 * o;
+}
+function k(t, n) {
+  let e = D(t), o = D(n);
+  return (Math.max(e, o) + 0.05) / (Math.min(e, o) + 0.05);
+}
+function B(t, n, e) {
+  if (k(t, n) >= e)
+    return t;
+  let o = t.l >= n.l ? 1 : -1;
+  for (let s of [o, -o]) {
+    let c = { ...t };
+    for (let i = 0;i < 60; i++) {
+      if (c.l = Math.min(1, Math.max(0, c.l + s * 0.02)), k(c, n) >= e)
+        return c;
+      if (c.l === 0 || c.l === 1)
+        break;
+    }
+  }
+  let a = { ...t, l: 0, c: 0 }, r = { ...t, l: 1, c: 0 };
+  return k(a, n) >= k(r, n) ? a : r;
+}
+function P(t) {
+  return "#" + K(t).map((n) => {
+    let e = n <= 0.0031308 ? 12.92 * n : 1.055 * Math.pow(n, 0.4166666666666667) - 0.055;
+    return Math.round(e * 255).toString(16).padStart(2, "0");
+  }).join("");
+}
+var Z = [[0.2, { l: 0.86, c: 0.085 }], [0.36, { l: 0.9, c: 0.028 }], [0.62, { l: 0.73, c: 0.135 }], [0.8, { l: 0.62, c: 0.165 }], [0.93, { l: 0.87, c: 0.16 }], [1, { l: 0.34, c: 0.035 }]];
+var Et = (t) => Z.find(([n]) => t < n)?.[1] ?? Z[0][1];
+var U = { l: 0.145, c: 0, h: 0 };
+var Q = 1.5;
+var Lt = (t, n) => {
+  let e = Et(n), o = B({ l: e.l, c: e.c, h: t }, U, Q);
+  return { bg: { l: 0.965, c: 0.01, h: t }, head: o, eye: o.l >= 0.5 ? { l: 0.17, c: 0.02, h: t } : { l: 0.97, c: 0.012, h: t } };
+};
+var X = [["head", "bg", 1.25], ["eye", "head", 4.5]];
+function Y(t, n = true, e = 0) {
+  let o = Lt(t, e);
+  if (n)
+    for (let [a, r, s] of X)
+      o[a] = B(o[a], o[r], s);
+  return o;
+}
+function w(t, n = true, e = 0) {
+  let o = Y(t, n, e), a = {};
+  for (let r in o)
+    a[r] = P(o[r]);
+  return a;
+}
+var y = (t) => {
+  let n = Math.round(t * 100) / 100;
+  return Object.is(n, -0) ? "0" : String(n);
+};
+function T({ cx: t, cy: n, rx: e, ry: o, n: a = 4, rot: r = 0 }) {
+  let s = Math.min(1, (8 * Math.pow(2, -1 / a) - 4) / 3), c = e, i = o, m = c * s, l = i * s, u = [[c, 0], [c, l], [m, i], [0, i], [-m, i], [-c, l], [-c, 0], [-c, -l], [-m, -i], [0, -i], [m, -i], [c, -l], [c, 0]], x = r * Math.PI / 180, p = Math.cos(x), d = Math.sin(x), h = (b) => {
+    let [g, M] = u[b];
+    return `${y(t + g * p - M * d)} ${y(n + g * d + M * p)}`;
+  }, f = `M${h(0)}`;
+  for (let b = 1;b < 13; b += 3)
+    f += `C${h(b)} ${h(b + 1)} ${h(b + 2)}`;
+  return f + "Z";
+}
+function G(t, n, e, o, a, r = 0) {
+  let s = a.length, c = r * Math.PI / 180, i = a.map((u, x) => {
+    let p = c + 2 * Math.PI * x / s;
+    return [t + e * u * Math.cos(p), n + o * u * Math.sin(p)];
+  }), m = (u) => i[(u % s + s) % s], l = `M${y(m(0)[0])} ${y(m(0)[1])}`;
+  for (let u = 0;u < s; u++) {
+    let [x, p] = m(u - 1), [d, h] = m(u), [f, b] = m(u + 1), [g, M] = m(u + 2);
+    l += `C${y(d + (f - x) / 6)} ${y(h + (b - p) / 6)} ${y(f - (g - d) / 6)} ${y(b - (M - h) / 6)} ${y(f)} ${y(b)}`;
+  }
+  return l + "Z";
+}
+function J({ cx: t, cy: n, rx: e, ry: o, sides: a, round: r = 0.3, rot: s = 0 }) {
+  let c = r > 0 ? r < 1 ? r / 2 : 0.5 : 0, i = s * Math.PI / 180 - Math.PI / 2, m = Array.from({ length: a }, (p, d) => {
+    let h = i + 2 * Math.PI * d / a;
+    return [t + e * Math.cos(h), n + o * Math.sin(h)];
+  }), l = (p) => m[(p % a + a) % a], u = (p, d) => {
+    let [h, f] = l(p), [b, g] = l(d);
+    return `${y(h + (b - h) * c)} ${y(f + (g - f) * c)}`;
+  }, x = `M${u(0, -1)}`;
+  for (let p = 0;p < a; p++) {
+    let [d, h] = l(p);
+    if (x += `Q${y(d)} ${y(h)} ${u(p, p + 1)}`, c < 0.5)
+      x += `L${u(p + 1, p)}`;
+  }
+  return x + "Z";
+}
+function W(t, n, e, o) {
+  let a = y(t - e), r = y(t + e);
+  return `M${a} ${y(n - o)}H${r}V${y(n + o)}H${a}Z`;
+}
+function tt(t, n, e, o, a) {
+  let r = Math.max(1.05, a), s = e * Math.sqrt(1 - 1 / (r * r)), c = n - o / r, i = n - r * o, m = s * 0.14, l = c + 0.86 * (i - c);
+  return `M${y(t - s)} ${y(c)}L${y(t - m)} ${y(l)}Q${y(t)} ${y(i)} ${y(t + m)} ${y(l)}L${y(t + s)} ${y(c)}Z`;
+}
+function I(t, n) {
+  for (let e = 0;e < n.length; e++)
+    t = Math.imul(t ^ n[e], 3432918353), t = t << 13 | t >>> 19;
+  return t;
+}
+function wt(t) {
+  return t = Math.imul(t ^ t >>> 16, 2246822507), t = Math.imul(t ^ t >>> 13, 3266489909), (t ^ t >>> 16) >>> 0;
+}
+var nt = new TextEncoder;
+function et(t) {
+  return t.normalize("NFC").trim().toLowerCase();
+}
+function rt(t, n = true) {
+  let e = n ? et(t) : t;
+  return I(1779033703 ^ e.length, nt.encode(e));
+}
+function v(t, n) {
+  return wt(I(I(t, Uint8Array.of(255)), nt.encode(n))) / 4294967296;
+}
+function A(t, n = true, e) {
+  let o = rt(t, n), a = (r) => {
+    let s = e?.[r], c = Array.isArray(s) ? s[Math.floor(v(o, r) * s.length)] : s;
+    return c === undefined ? v(o, r) : c > 0 ? c < 1 ? c : 0.999999 : 0;
+  };
+  return a.num = (r, s, c) => s + a(r) * (c - s), a.int = (r, s, c) => s + Math.floor(a(r) * (c - s + 1)), a.pick = (r, s) => s[Math.floor(a(r) * s.length)], a.bool = (r, s = 0.5) => a(r) < s, a.jitter = (r, s) => (a(r) * 2 - 1) * s, a;
+}
+function ot(t, n, e) {
+  let o = n.expression;
+  if (e || !o)
+    return { l: t, wrap: "" };
+  return o.bake(t, o.p);
+}
+var It = (t, n) => n?.tint ? n.tint(t, n.p) : t;
+var at = (t, n) => n ? `<g transform="${n}">${t}</g>` : t;
+var vt = (t) => t.replace(/[&<>]/g, (n) => n === "&" ? "&amp;" : n === "<" ? "&lt;" : "&gt;");
+function S(t, n) {
+  let e = A(t, n.normalize ?? true, n.traits);
+  return { t: e, palette: { ...w(n.hue ?? e.num("hue", 0, 360), n.contrast ?? true, n.tone ?? e("tone")), ...n.palette } };
+}
+var At = (t) => t.title ? `<title>${vt(t.title)}</title>` : "";
+function st(t, n, e) {
+  let o = n.background ?? t.background;
+  if (o === false)
+    return;
+  return { d: o === "square" ? "M0 0H100V100H0Z" : T({ cx: 50, cy: 50, rx: 50, ry: 50, n: o === "circle" ? 2 : 6 }), fill: e.bg };
+}
+var Rt = (t) => t ? `<path d="${t.d}" fill="${t.fill}"/>` : "";
+function ct(t) {
+  return (n, e = {}) => {
+    let { t: o, palette: a } = S(n, e), r = It(a, e.expression), s = e.size ? ` width="${e.size}" height="${e.size}"` : "", c = ot(t.layout(o), e), i = At(e) + Rt(st(t, e, r)) + at(t.render(c.l, r), c.wrap);
+    return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100"${s}>${i}</svg>`;
+  };
+}
+var ut = (t, n, e) => {
+  let o = n.rx, a = t.num("eye.rx", 0.075, 0.105) * o, r = t.num("eye.ratio", 1.9, 3.2), s = t.num("eye.scale", 0.78, 1.24), c = t.num("eye.stretch", 0.85, 1.18), i = t.num("eye.gap", 0.1, 0.24) * o, m = a * Math.max(1, s), l = a * r * Math.max(1, s * c), u = m + o * 0.03 + i, x = t.jitter("gaze.x", 0.09) * e.rx, p = t.num("gaze.y", -0.2, 0.08) * e.ry, d = t.jitter("eye.dy", 0.04) * e.ry, h = Math.hypot(m, l), f = Math.hypot((Math.abs(x) + u + h) / e.rx, (Math.abs(p) + Math.abs(d) + h) / e.ry), b = f > 0.9 ? 0.9 / f : 1, g = a * b, M = g * r, F = u * b, Pt = Math.max(0, Math.min(1, i / l)), Tt = Math.min(12, Math.asin(Pt) * 180 / Math.PI), j = t.num("eye.lean", -1, 1) * Tt, Bt = Math.max(-12, Math.min(12, j + t.jitter("eye.lean2", 3.5))), z = e.cx + x * b, C = e.cy + p * b;
+  return [{ cx: z - F, cy: C, rx: g, ry: M, n: t.num("eye.n", 3.5, 6), rot: j }, { cx: z + F, cy: C + d * b, rx: g * s, ry: M * s * c, n: t.num("eye.n", 3.5, 6), rot: Bt }];
+};
+function mt(t, n) {
+  let e = (r) => (t.find(([, s]) => r < s) ?? t[t.length - 1])[0];
+  function o(r) {
+    let s = e(r("shape")), c = r.num("body.r", 31, 38) * s.core, i = { cx: 50 + r.jitter("body.x", 1.5), cy: 50 + r.jitter("body.y", 1.5), rx: c, ry: c * r.num("body.ratio", 0.92, 1.08), n: r.num("body.n", 1.9, 2.5), rot: 0, radii: Array.from({ length: r.int("body.pts", 6, 8) }, (u, x) => 1 + r.jitter(`body.r${x}`, 0.16)) };
+    s.body?.(r, i);
+    let m = s.face?.(i) ?? i, l = { petals: [], extra: [] };
+    return s.decorate?.(r, i, l), { shape: s.name, draw: s.path, body: i, face: m, petals: l.petals, extra: l.extra, eyes: n(r, i, m) };
+  }
+  function a(r, s, c) {
+    let i = (u) => Math.round(u * 100) / 100, m = (u, x) => {
+      let p = `<path d="${T(u)}"/>`;
+      return c ? `<g class="mo-eye" style="--mo-wrap:${x ? 1 : -1};--mo-lean:${i(u.rot)};transform-origin:${i(u.cx)}px ${i(u.cy)}px">${p}</g>` : p;
+    }, l = `<g fill="${s.head}">` + r.petals.map((u) => `<circle cx="${i(u.cx)}" cy="${i(u.cy)}" r="${i(u.r)}"/>`).join("") + r.extra.map((u) => `<path d="${u}"/>`).join("") + `<path d="${r.draw ? r.draw(r.body) : T(r.body)}"/></g><g fill="${s.eye}"${c ? ' class="mo-eyes"' : ""}>` + r.eyes.map(m).join("") + "</g>";
+    return c ? `<g class="mo-breathe"><g class="mo-bob">${l}</g></g>` : l;
+  }
+  return { layout: o, render: a, background: false };
+}
+var lt = (t) => J(t);
+var pt = (t) => G(t.cx, t.cy, t.rx, t.ry, t.radii, t.rot);
+var R = (t) => (n) => ({ cx: n.cx, cy: n.cy, rx: n.rx * t, ry: n.ry * t });
+var yt = (t) => R(Math.min(...t.radii) * 0.95)(t);
+var Ft = (t) => R(0.84)(t);
+var xt = { name: "round", core: 1 };
+var bt = { name: "organic", core: 0.98, path: pt, face: yt };
+var ht = { name: "boxy", core: 0.86, body: (t, n) => {
+  n.n = t.num("body.n", 3.4, 6), n.rot = t.num("body.rot", -20, 20);
+} };
+var dt = { name: "capsule", core: 1.02, body: (t, n) => {
+  n.ry *= t.num("capsule.squat", 0.55, 0.68);
+}, face: R(0.94), decorate: (t, n, e) => {
+  for (let o of [-1, 1])
+    e.petals.push({ cx: n.cx + o * (n.rx - n.ry), cy: n.cy, r: n.ry });
+}, path: (t) => W(t.cx, t.cy, t.rx - t.ry, t.ry) };
+var ft = { name: "nub", core: 0.88, decorate: (t, n, e) => {
+  let o = t.int("nub.n", 1, 2);
+  for (let a = 0;a < o; a++) {
+    let r = t.num(`nub.a${a}`, 0, 2 * Math.PI);
+    e.petals.push({ cx: n.cx + Math.cos(r) * n.rx * 0.88, cy: n.cy + Math.sin(r) * n.rx * 0.88, r: n.rx * t.num(`nub.r${a}`, 0.24, 0.4) });
+  }
+} };
+var gt = { name: "cloud", core: 0.78, face: yt, path: pt, decorate: (t, n, e) => {
+  let o = t.int("cloud.n", 4, 6);
+  for (let a = 0;a < o; a++) {
+    let r = Math.PI + Math.PI * (a + 0.5) / o;
+    e.petals.push({ cx: n.cx + Math.cos(r) * n.rx * 0.8, cy: n.cy + Math.sin(r) * n.rx * 0.5, r: n.rx * t.num(`cloud.r${a}`, 0.44, 0.62) });
+  }
+} };
+var Mt = { name: "droplet", core: 0.78, body: (t, n) => {
+  n.cy += 0.22 * n.ry, n.n = 2;
+}, face: (t) => ({ cx: t.cx, cy: t.cy + t.ry * 0.05, rx: t.rx * 0.88, ry: t.ry * 0.88 }), decorate: (t, n, e) => {
+  e.extra.push(tt(n.cx, n.cy, n.rx, n.ry, t.num("droplet.tip", 1.4, 1.65)));
+} };
+var $t = { name: "hexagon", core: 1.05, path: lt, face: Ft, body: (t, n) => {
+  n.sides = 6, n.rot = t.num("body.rot", -12, 12), n.round = t.num("poly.round", 0.24, 0.5);
+} };
+var kt = { name: "sun", core: 0.7, decorate: (t, n, e) => {
+  let o = t.int("sun.n", 6, 9), a = n.rx * t.num("sun.dist", 1, 1.08), r = n.rx * t.num("sun.r", 0.2, 0.26), s = t.num("sun.rot", 0, 2 * Math.PI);
+  for (let c = 0;c < o; c++) {
+    let i = s + 2 * Math.PI * c / o;
+    e.petals.push({ cx: n.cx + Math.cos(i) * a, cy: n.cy + Math.sin(i) * a, r });
+  }
+} };
+var Ot = { name: "triangle", core: 1.15, path: lt, body: (t, n) => {
+  n.sides = 3, n.rot = t.num("body.rot", -5, 5), n.round = t.num("poly.round", 0.24, 0.5);
+}, face: (t) => ({ cx: t.cx, cy: t.cy + t.ry * 0.1, rx: t.rx * 0.54, ry: t.ry * 0.36 }) };
+var jt = [[xt, 0.22], [bt, 0.48], [ht, 0.6], [dt, 0.7], [ft, 0.79], [gt, 0.86], [Mt, 0.915], [$t, 0.95], [kt, 0.98], [Ot, 1]];
+var E = mt(jt, ut);
+var zt = ct(E);
+
+// tools/avatar.js
+var PROPERTIES = [
+  "--m-avatar-content-color",
+  "--m-avatar-body-color",
+  "--m-avatar-eye-color",
+  "--m-avatar-body-inset-block",
+  "--m-avatar-body-inset-inline",
+  "--m-avatar-body-x",
+  "--m-avatar-body-y",
+  "--m-avatar-eye-top",
+  "--m-avatar-eye-left",
+  "--m-avatar-eye-width",
+  "--m-avatar-eye-height",
+  "--m-avatar-eye-gap",
+  "--m-avatar-eye-drop"
+];
+var percent = (value) => `${Math.round(value * 100) / 100}%`;
+
+class MAvatar extends HTMLElement {
+  static observedAttributes = ["blobatar"];
+  connectedCallback() {
+    this.#update();
+  }
+  attributeChangedCallback() {
+    if (this.isConnected)
+      this.#update();
+  }
+  #update() {
+    const seed = this.getAttribute("blobatar");
+    if (seed === null) {
+      for (const property of PROPERTIES)
+        this.style.removeProperty(property);
+      return;
+    }
+    const t = A(seed);
+    const colors = w(t.num("hue", 0, 360), true, t("tone"));
+    this.style.setProperty("--m-avatar-content-color", "transparent");
+    this.style.setProperty("--m-avatar-body-color", colors.head);
+    this.style.setProperty("--m-avatar-eye-color", colors.eye);
+    this.style.setProperty("--m-avatar-body-inset-block", percent(t.num("mica.body.block", 11, 16)));
+    this.style.setProperty("--m-avatar-body-inset-inline", percent(t.num("mica.body.inline", 10, 16)));
+    this.style.setProperty("--m-avatar-body-x", percent(t.jitter("mica.body.x", 2)));
+    this.style.setProperty("--m-avatar-body-y", percent(t.jitter("mica.body.y", 2)));
+    this.style.setProperty("--m-avatar-eye-top", percent(t.num("mica.eye.top", 42, 49)));
+    this.style.setProperty("--m-avatar-eye-left", percent(t.num("mica.eye.left", 36, 40)));
+    this.style.setProperty("--m-avatar-eye-width", percent(t.num("mica.eye.width", 2.5, 3.5)));
+    this.style.setProperty("--m-avatar-eye-height", percent(t.num("mica.eye.height", 7.5, 10)));
+    this.style.setProperty("--m-avatar-eye-gap", percent(t.num("mica.eye.gap", 19, 23)));
+    this.style.setProperty("--m-avatar-eye-drop", percent(t.jitter("mica.eye.drop", 2)));
+  }
+}
+if (!customElements.get("m-avatar"))
+  customElements.define("m-avatar", MAvatar);

package/combobox.js

@@ -20,13 +20,16 @@ let uid = 0;
 class MCombobox extends HTMLElement {
   #input;
   #list;
+  #datalist;
+  #listId;
   #options = [];
   #active = -1;
+  #observer;
 
   connectedCallback() {
     this.#input = this.querySelector("input");
-    const datalist = this.querySelector("datalist");
-    if (!this.#input || !datalist) return;
+    this.#datalist = this.querySelector("datalist");
+    if (!this.#input || !this.#datalist) return;
 
     // disable the native popup; the module takes over
     this.#input.removeAttribute("list");
@@ -35,16 +38,49 @@ class MCombobox extends HTMLElement {
     this.#input.setAttribute("aria-autocomplete", "list");
     this.#input.autocomplete = "off";
 
-    const listId = `m-cb-${++uid}`;
+    this.#listId = `m-cb-${++uid}`;
     this.#list = document.createElement("div");
-    this.#list.id = listId;
+    this.#list.id = this.#listId;
     this.#list.setAttribute("role", "listbox");
     this.#list.hidden = true;
 
-    this.#options = [...datalist.options].map((o, i) => {
+    this.#buildOptions();
+    this.append(this.#list);
+    this.#input.setAttribute("aria-controls", this.#listId);
+
+    // Options may be rendered asynchronously (a search-backed combobox):
+    // rebuild the listbox whenever the author's datalist changes.
+    this.#observer = new MutationObserver(() => {
+      this.#buildOptions();
+      if (document.activeElement === this.#input) this.#openAndFilter();
+    });
+    this.#observer.observe(this.#datalist, {
+      childList: true,
+      subtree: true,
+      attributes: true,
+      attributeFilter: ["value"],
+    });
+
+    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();
+    });
+  }
+
+  disconnectedCallback() {
+    this.#observer?.disconnect();
+  }
+
+  #buildOptions() {
+    this.#list.replaceChildren();
+    this.#options = [...this.#datalist.options].map((o, i) => {
       const d = document.createElement("div");
       d.setAttribute("role", "option");
-      d.id = `${listId}-${i}`;
+      d.id = `${this.#listId}-${i}`;
       d.textContent = o.value || o.textContent;
       // pointerdown so the input never loses focus
       d.addEventListener("pointerdown", (e) => {
@@ -58,17 +94,7 @@ class MCombobox extends HTMLElement {
       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();
-    });
+    this.#active = -1;
   }
 
   #visible() {
@@ -127,7 +153,15 @@ class MCombobox extends HTMLElement {
   }
 
   #choose(option) {
-    this.#input.value = option.textContent;
+    // Write through the native prototype setter: frameworks that patch
+    // the value property to track controlled inputs (React) only observe
+    // the change when it lands on the native setter.
+    const setter = Object.getOwnPropertyDescriptor(
+      HTMLInputElement.prototype,
+      "value",
+    )?.set;
+    if (setter) setter.call(this.#input, option.textContent);
+    else this.#input.value = option.textContent;
     this.#close();
     this.#input.dispatchEvent(new Event("input", { bubbles: true }));
     this.#input.dispatchEvent(new Event("change", { bubbles: true }));

package/drawer.d.ts

@@ -1,5 +1,6 @@
 /* Type declarations for mica/drawer.js — side-effect module.
- * Swipe-to-dismiss drag physics for dialog[data-drawer] bottom sheets.
- * No exports; sets :root[data-drawer-gestures] when active.
+ * Swipe-to-dismiss drag physics and a managed overlay scrim for
+ * dialog[data-drawer] bottom sheets. No exports; sets
+ * :root[data-drawer-gestures] when active.
  */
 export {};

package/drawer.js

@@ -1,12 +1,14 @@
-/* mica/drawer.js — JS-enhanced: swipe-to-dismiss for dialog[data-drawer]
- * bottom sheets on small screens.
+/* mica/drawer.js — JS-enhanced: swipe-to-dismiss and a managed scrim for
+ * dialog[data-drawer] bottom sheets on small screens.
  *
  * Enhances working markup, never replaces it: without this module the
  * drawer opens/closes via buttons and Esc; with it, the mobile sheet
  * grows a grab handle (CSS keys off :root[data-drawer-gestures] — an
  * affordance may only appear when the behavior exists) and vaul-style
  * drag physics: the sheet follows a downward drag, resists upward,
- * and dismisses past 1/3 of its height or on a flick.
+ * and dismisses past 1/3 of its height or on a flick. A fixed visual
+ * overlay replaces the CSS-only scrim so its dimming can follow the drag
+ * and fade on iOS, where ::backdrop disappears immediately on close.
  *
  * Drag surface: the handle / header strip. Drag-from-content is
  * deliberately out of scope — it requires scroll-vs-drag heuristics
@@ -18,7 +20,47 @@ const CLOSE_DISTANCE = 1 / 3; // of sheet height
 const CLOSE_VELOCITY = 0.6; // px/ms, downward flick
 const DRAWER = "dialog[data-drawer]";
 
+let overlay;
+const dismissCleanup = new WeakMap();
+
+const overlayElement = () => {
+  if (overlay) return overlay;
+  overlay = document.createElement("div");
+  overlay.setAttribute("data-mica-drawer-overlay", "");
+  overlay.setAttribute("aria-hidden", "true");
+  overlay.inert = true;
+  overlay.style.setProperty("--m-drawer-overlay-opacity", "0");
+  document.body.append(overlay);
+  // Commit the transparent state before the first open transition.
+  overlay.getBoundingClientRect();
+  return overlay;
+};
+
+const setOverlayOpacity = (value) => {
+  if (!overlay && value === 0) return;
+  overlayElement().style.setProperty(
+    "--m-drawer-overlay-opacity",
+    String(Math.max(0, Math.min(1, value))),
+  );
+};
+
+const syncOverlay = () => {
+  const openDrawer = document.querySelector(`${DRAWER}[open]`);
+  // iOS can drop the closed dialog before its translate transition runs,
+  // so transitionend never clears the drag-dismiss inline style. Clear a
+  // pending exit synchronously on reopen, before the next frame paints.
+  if (openDrawer) dismissCleanup.get(openDrawer)?.();
+  setOverlayOpacity(openDrawer ? 1 : 0);
+};
+
+new MutationObserver(syncOverlay).observe(document.documentElement, {
+  attributes: true,
+  attributeFilter: ["open"],
+  subtree: true,
+});
+
 document.documentElement.setAttribute("data-drawer-gestures", "");
+syncOverlay();
 
 document.addEventListener("pointerdown", (down) => {
   if (!SHEET.matches) return;
@@ -40,7 +82,10 @@ document.addEventListener("pointerdown", (down) => {
 
   dialog.setPointerCapture(down.pointerId);
   const baseTransition = dialog.style.transition;
+  const scrim = overlayElement();
+  const baseOverlayTransition = scrim.style.transition;
   dialog.style.transition = "none";
+  scrim.style.transition = "none";
 
   const move = (e) => {
     dy = e.clientY - down.clientY;
@@ -49,6 +94,9 @@ document.addEventListener("pointerdown", (down) => {
     lastT = e.timeStamp;
     // follow downward; resist upward
     dialog.style.translate = `0 ${dy > 0 ? dy : dy / 4}px`;
+    // Clear by half a sheet: a one-to-one distance mapping was too subtle
+    // against dark surfaces (a quarter pull only moved alpha .4 → .3).
+    setOverlayOpacity(1 - Math.max(0, dy) / (rect.height / 2));
   };
 
   const up = () => {
@@ -56,22 +104,38 @@ document.addEventListener("pointerdown", (down) => {
     dialog.removeEventListener("pointerup", up);
     dialog.removeEventListener("pointercancel", up);
     dialog.style.transition = baseTransition;
+    scrim.style.transition = baseOverlayTransition;
     if (dy > rect.height * CLOSE_DISTANCE || velocity > CLOSE_VELOCITY) {
       // continue the motion DOWNWARD off-screen. close() fires its exit
-      // (backdrop fade + display flip at the end via allow-discrete);
+      // (scrim fade + display flip at the end via allow-discrete);
       // the inline translate overrides the small CSS exit offset so the
       // sheet keeps sliding down instead of snapping back up into view
       // (the flash). Clear it only at transitionend — display:none by
-      // then, so clearing is invisible and the next open starts clean.
-      dialog.addEventListener(
-        "transitionend",
-        (e) => { if (e.propertyName === "translate") dialog.style.translate = ""; },
-        { once: true },
-      );
+      // then, so clearing is invisible. iOS may never fire that event,
+      // so a timeout clears it while closed and syncOverlay clears it if
+      // the drawer reopens first.
+      let cleanupTimer;
+      const onTransitionEnd = (e) => {
+        if (e.propertyName === "translate") clearDismiss();
+      };
+      const clearDismiss = () => {
+        if (dismissCleanup.get(dialog) !== clearDismiss) return;
+        clearTimeout(cleanupTimer);
+        dialog.removeEventListener("transitionend", onTransitionEnd);
+        dialog.style.translate = "";
+        dismissCleanup.delete(dialog);
+      };
+      dismissCleanup.set(dialog, clearDismiss);
+      dialog.addEventListener("transitionend", onTransitionEnd);
+      cleanupTimer = setTimeout(() => {
+        if (!dialog.open) clearDismiss();
+      }, 200);
+      setOverlayOpacity(0);
       requestAnimationFrame(() => { dialog.style.translate = "0 100dvh"; });
       dialog.close();
     } else {
       dialog.style.translate = ""; // spring back
+      setOverlayOpacity(1);
     }
   };
 

package/mica.css

@@ -771,6 +771,82 @@
     --m-badge-numerals: tabular-nums;
   }
 
+  /* --- avatar: authored initials, optionally Blobatar-painted -------- */
+  :where(m-avatar) {
+    display: inline-grid;
+    place-items: center;
+    position: relative;
+    flex: none;
+    box-sizing: border-box;
+    inline-size: var(--avatar-size, 3rem);
+    block-size: var(--avatar-size, 3rem);
+    overflow: hidden;
+    border-radius: var(--radius-md);
+    background: var(--color-surface-raised);
+    color: var(--m-avatar-content-color, var(--color-text));
+    font-size: calc(var(--avatar-size, 3rem) * 0.5);
+    font-weight: 600;
+    line-height: 1;
+    text-transform: uppercase;
+    vertical-align: middle;
+    white-space: nowrap;
+    user-select: none;
+  }
+
+  :where(m-avatar > img) {
+    position: absolute;
+    inset: 0;
+    z-index: 1;
+    inline-size: 100%;
+    block-size: 100%;
+    object-fit: cover;
+  }
+
+  /* Attribute selectors only transport values. The pseudo rules below
+     render them, so missing avatar.js leaves authored initials untouched. */
+  :where(m-avatar[blobatar]) {
+    --m-avatar-decoration: "";
+    --m-avatar-render-inset-block: 0;
+    --m-avatar-render-inset-inline: 0;
+    --m-avatar-render-x: 0;
+    --m-avatar-render-y: 0;
+  }
+
+  :where(m-avatar[blobatar][contained]) {
+    --m-avatar-render-inset-block: var(--m-avatar-body-inset-block);
+    --m-avatar-render-inset-inline: var(--m-avatar-body-inset-inline);
+    --m-avatar-render-x: var(--m-avatar-body-x);
+    --m-avatar-render-y: var(--m-avatar-body-y);
+  }
+
+  :where(m-avatar)::before {
+    content: var(--m-avatar-decoration, none);
+    position: absolute;
+    inset-block: var(--m-avatar-render-inset-block);
+    inset-inline: var(--m-avatar-render-inset-inline);
+    border-radius: inherit;
+    background: var(--m-avatar-body-color);
+    transform: translate(var(--m-avatar-render-x), var(--m-avatar-render-y));
+  }
+
+  :where(m-avatar)::after {
+    content: var(--m-avatar-decoration, none);
+    position: absolute;
+    inset: 0;
+    background:
+      radial-gradient(
+        ellipse var(--m-avatar-eye-width) var(--m-avatar-eye-height)
+        at var(--m-avatar-eye-left) var(--m-avatar-eye-top),
+        var(--m-avatar-eye-color) 98%, transparent 100%
+      ),
+      radial-gradient(
+        ellipse var(--m-avatar-eye-width) var(--m-avatar-eye-height)
+        at calc(var(--m-avatar-eye-left) + var(--m-avatar-eye-gap))
+          calc(var(--m-avatar-eye-top) + var(--m-avatar-eye-drop)),
+        var(--m-avatar-eye-color) 98%, transparent 100%
+      );
+  }
+
   /* --- content: tables, lists, code, quotes ------------------------ */
   :where(table) {
     inline-size: 100%;
@@ -1132,6 +1208,14 @@
     border-block-start: 0;
   }
 
+  /* Internal visual layer injected by drawer.js. It stays ordinary page
+     content beneath the dialog's transparent top-layer ::backdrop, so it
+     survives iOS removing that backdrop on close. Hidden outside the
+     mobile-sheet breakpoint; aria-hidden + inert are set by the module. */
+  :where([data-mica-drawer-overlay]) {
+    display: none;
+  }
+
   /* small screens: the drawer becomes a bottom sheet — shadcn's own
      mobile drawer (vaul/radix) is exactly this. Anchored to the bottom
      edge via auto top margin: bottom attachment is the one thing iOS
@@ -1148,7 +1232,7 @@
       max-inline-size: none;
       border-inline-start: 0;
       border-block-start: 1px solid var(--color-border);
-      /* Two box-shadows, both painted by the SHEET element so they
+      /* CSS-only fallback: two shadows painted by the SHEET so they
          persist through the exit (display:allow-discrete keeps the box
          rendered) — unlike ::backdrop, which iOS drops from the top
          layer the instant you close, cutting the scrim. So the dim
@@ -1184,8 +1268,28 @@
           0 0 0 100vmax oklch(0 0 0 / 0);
       }
     }
-    /* the box-shadow scrim replaces ::backdrop here; keep the native
-       backdrop clear so they don't double up or flash on the iOS cut. */
+    /* With drawer.js, keep only the bleed slab; its ordinary fixed
+       overlay owns the visible scrim and follows drag progress. */
+    :where(:root[data-drawer-gestures])
+      :where(dialog[data-drawer]) {
+      box-shadow: 0 4rem 0 0 var(--color-surface-overlay);
+    }
+
+    :where([data-mica-drawer-overlay]) {
+      display: block;
+      position: fixed;
+      inset: 0;
+      z-index: 50;
+      inline-size: 100lvw;
+      block-size: 100lvh;
+      background: oklch(0 0 0 / 0.4);
+      opacity: var(--m-drawer-overlay-opacity, 0);
+      pointer-events: none;
+      transition: opacity 0.15s;
+    }
+
+    /* The fallback shadow or managed overlay replaces ::backdrop here;
+       keep it clear so the scrims don't double up or flash on iOS. */
     :where(dialog[data-drawer][open])::backdrop {
       background: oklch(0 0 0 / 0);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akonwi/mica",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "Custom elements. Native behavior. Nearly no JavaScript.",
   "keywords": [
     "css",
@@ -21,19 +21,46 @@
   "exports": {
     ".": "./mica.css",
     "./mica.css": "./mica.css",
-    "./invoker.js": { "types": "./invoker.d.ts", "default": "./invoker.js" },
-    "./drawer.js": { "types": "./drawer.d.ts", "default": "./drawer.js" },
-    "./field.js": { "types": "./field.d.ts", "default": "./field.js" },
-    "./select.js": { "types": "./select.d.ts", "default": "./select.js" },
-    "./tabs.js": { "types": "./tabs.d.ts", "default": "./tabs.js" },
-    "./toast.js": { "types": "./toast.d.ts", "default": "./toast.js" },
-    "./combobox.js": { "types": "./combobox.d.ts", "default": "./combobox.js" },
+    "./avatar.js": {
+      "types": "./avatar.d.ts",
+      "default": "./avatar.js"
+    },
+    "./invoker.js": {
+      "types": "./invoker.d.ts",
+      "default": "./invoker.js"
+    },
+    "./drawer.js": {
+      "types": "./drawer.d.ts",
+      "default": "./drawer.js"
+    },
+    "./field.js": {
+      "types": "./field.d.ts",
+      "default": "./field.js"
+    },
+    "./select.js": {
+      "types": "./select.d.ts",
+      "default": "./select.js"
+    },
+    "./tabs.js": {
+      "types": "./tabs.d.ts",
+      "default": "./tabs.js"
+    },
+    "./toast.js": {
+      "types": "./toast.d.ts",
+      "default": "./toast.js"
+    },
+    "./combobox.js": {
+      "types": "./combobox.d.ts",
+      "default": "./combobox.js"
+    },
     "./types/react": {
       "types": "./types/react.d.ts"
     }
   },
   "files": [
     "mica.css",
+    "avatar.js",
+    "avatar.d.ts",
     "invoker.js",
     "invoker.d.ts",
     "drawer.js",
@@ -48,16 +75,22 @@
     "toast.d.ts",
     "combobox.js",
     "combobox.d.ts",
-    "types/react.d.ts"
+    "types/react.d.ts",
+    "THIRD_PARTY_LICENSES.md"
   ],
   "sideEffects": true,
   "devDependencies": {
     "axe-core": "^4.12.1",
+    "blobatar": "2.4.0",
     "pixelmatch": "^7.2.0",
     "playwright": "^1.61.1",
     "pngjs": "^7.0.0"
   },
   "scripts": {
+    "build:avatar": "bun tools/build-avatar.ts",
+    "docs:build": "bun tools/build-docs.ts",
+    "docs:check": "bun tools/build-docs.ts --check",
+    "docs:serve": "bun run docs:build && bun tools/serve.ts",
     "snapshot": "bun tools/snapshot.ts",
     "snapshot:check": "bun tools/snapshot.ts --check",
     "snapshot:setup": "playwright install chromium webkit"

package/types/react.d.ts

@@ -56,6 +56,10 @@ declare module 'react' {
         variant?: 'primary' | 'success' | 'warning' | 'danger'
         count?: boolean
       }>
+      'm-avatar': MicaElement<{
+        blobatar?: string
+        contained?: boolean
+      }>
       'm-toast': MicaElement<{
         popover?: 'manual'
         variant?: 'success' | 'warning' | 'danger'