@jirawatpyk/aura-tokens 5.2.0 → 5.4.0

package/README.md

@@ -15,7 +15,7 @@ Enterprise Standard, Human Creative. Tokens, Tailwind preset, Figma variables a
 | `figma-variables.csv`                        | 204 variables: all colours in both modes (aliases kept), spacing, radius and sizes. **Generated.**                                                                                                                                                                              |
 | `components/`                                | `aura.bundle.js` (sets `window.Aura`), `aura.components.css`, `index.d.ts`.                                                                                                                                                                                                     |
 | `eslint-plugin-aura.js`                      | `aura/no-hardcoded-color`: hex, colour functions (rgb, hsl, oklch, color-mix…), named colours in style values and Tailwind palette / `bg-[#…]` classes. ESLint 9: `import aura from '@jirawatpyk/aura-tokens/eslint-plugin'; export default [aura.configs.recommended];` (5.2). |
-| `scripts/build-tokens.js`                    | Rebuilds the generated files from `tokens.json`.                                                                                                                                                                                                                                |
+| `scripts/build-tokens.mts`                    | Rebuilds the generated files from `tokens.json`.                                                                                                                                                                                                                                |
 | `scripts/a11y-check.js`                      | Checks 210 pairs in both themes: text on its grounds (WCAG AA), control edges and state marks at 3:1, neighbouring chart and status fills a lightness step apart.                                                                                                               |
 | `scripts/lint-tokens.js`                     | Fails on hard-coded colours (a file that must hold them says `aura-lint: allow-colours` with a reason).                                                                                                                                                                         |
 

package/aura-tailwind.css

@@ -1,4 +1,4 @@
-/* AURA v5.2.0 — Tailwind v4 theme. GENERATED by scripts/build-tokens.js from tokens.json. Do not edit by hand.
+/* AURA v5.4.0 — Tailwind v4 theme. GENERATED by scripts/build-tokens.mts from tokens.json. Do not edit by hand.
  *   @import "tailwindcss";
  *   @import "@jirawatpyk/aura-tokens/tailwind.css";
  * Gives bg-bg-surface, text-fg-primary, border-border-strong, p-aura-6, rounded-aura-xl, shadow-aura-overlay,

package/aura-tailwind.prefixed.css

@@ -1,4 +1,4 @@
-/* AURA v5.2.0 — Tailwind v4 theme with aura- prefixed names. GENERATED by scripts/build-tokens.js. Do not edit by hand.
+/* AURA v5.4.0 — Tailwind v4 theme with aura- prefixed names. GENERATED by scripts/build-tokens.mts. Do not edit by hand.
  * For apps that already have a Tailwind theme (shadcn): nothing here redefines an existing name.
  *   @layer aura-tokens, theme, base, aura, components, utilities;
  *   @import "tailwindcss";

package/aura.css

@@ -1,4 +1,4 @@
-/* AURA v5.2.0 — GENERATED by scripts/build-tokens.js from tokens.json. Do not edit by hand. */
+/* AURA v5.4.0 — GENERATED by scripts/build-tokens.mts from tokens.json. Do not edit by hand. */
 /* Fonts: load aura-fonts.css (or the <link> tags in README) separately, so a blocked Google Fonts never breaks this file. */
 
 :root, [data-theme="light"] {

package/components/aura.bundle.js

@@ -1224,7 +1224,52 @@ window.Aura = (() => {
 
   // src/Select.tsx
   var React13 = __toESM(require_react(), 1);
+  var import_react_dom2 = __toESM(require_react_dom(), 1);
   var h3 = React13.createElement;
+  var FORM_KEYS = ["name", "form", "value", "defaultValue", "disabled", "autoComplete", "onInput", "onInvalid"];
+  var HANDLED_KEYS = FORM_KEYS.concat([
+    "onChange",
+    "onBlur",
+    "onFocus",
+    "onKeyDown",
+    "onClick",
+    "autoFocus",
+    "tabIndex",
+    "aria-label",
+    "aria-labelledby",
+    "aria-describedby",
+    "multiple",
+    "size"
+  ]);
+  function pick(o, keys) {
+    const r = {};
+    for (const k of keys) if (k in o) r[k] = o[k];
+    return r;
+  }
+  function readItems(el) {
+    if (!el) return [];
+    return Array.prototype.map.call(el.options, function(o, i) {
+      const g = o.parentElement && o.parentElement.tagName === "OPTGROUP" ? o.parentElement : null;
+      return {
+        value: o.value,
+        label: o.textContent || "",
+        disabled: o.disabled || !!(g && g.disabled),
+        group: g ? g.label : null,
+        index: i
+      };
+    });
+  }
+  function initialLabel(props) {
+    const opts = (props.options || []).map(function(o) {
+      return typeof o === "object" ? o : { value: o, label: o };
+    });
+    const v = props.value !== void 0 && props.value !== null ? String(props.value) : props.defaultValue !== void 0 && props.defaultValue !== null ? String(props.defaultValue) : props.placeholder ? "" : opts[0] ? opts[0].value : "";
+    const hit = opts.filter(function(o) {
+      return o.value === v;
+    })[0];
+    if (hit) return { label: hit.label, empty: false };
+    return { label: props.placeholder || "", empty: true };
+  }
   var Select = React13.forwardRef(function Select2(props, ref) {
     const auto = uid(), id = props.id || auto;
     const rest = omit(props, FIELD_KEYS.concat(["children"]));
@@ -1237,10 +1282,267 @@ window.Aura = (() => {
         /* @__PURE__ */ React13.createElement("option", { key: "__ph", value: "", disabled: true }, props.placeholder)
       );
     const extra = props.value === void 0 && props.defaultValue === void 0 && props.placeholder ? { defaultValue: "" } : {};
-    return /* @__PURE__ */ React13.createElement(
+    const native = !!props.multiple || props.size != null && props.size > 1;
+    const mounted = useMounted();
+    const live = !native && mounted;
+    const density = useDensity();
+    React13.useEffect(function() {
+      if (props.label || props["aria-label"] || props["aria-labelledby"] || props.title) return;
+      if (document.querySelector('label[for="' + id.replace(/["\\]/g, "\\$&") + '"]')) return;
+      devWarnOnce(
+        "select-name",
+        "Select needs a label, aria-label or aria-labelledby: screen readers announce it with no name."
+      );
+    }, []);
+    const selRef = React13.useRef(null), trigRef = React13.useRef(null), listRef = React13.useRef(null);
+    const shown = React13.useState(function() {
+      return initialLabel(props);
+    });
+    const openState = React13.useState(false), open = openState[0];
+    const activeState = React13.useState(-1), active = activeState[0];
+    const items2 = React13.useState([]);
+    const pos = React13.useState(null);
+    const typed = React13.useRef({ text: "", at: 0 });
+    const sync = React13.useCallback(function() {
+      const el = selRef.current;
+      if (!el) return;
+      const o = el.selectedIndex >= 0 ? el.options[el.selectedIndex] : null;
+      const next = o ? { label: o.textContent || "", empty: o.value === "" } : { label: "", empty: true };
+      shown[1](function(cur) {
+        return cur.label === next.label && cur.empty === next.empty ? cur : next;
+      });
+    }, []);
+    const hook = React13.useCallback(
+      function(el) {
+        selRef.current = el;
+        if (!el || native || el.__auraHooked) return;
+        el.__auraHooked = true;
+        const proto = HTMLSelectElement.prototype;
+        const pv = Object.getOwnPropertyDescriptor(proto, "value"), pi = Object.getOwnPropertyDescriptor(proto, "selectedIndex");
+        if (pv && pv.set && pv.get)
+          Object.defineProperty(el, "value", {
+            configurable: true,
+            get: function() {
+              return pv.get.call(el);
+            },
+            set: function(v) {
+              pv.set.call(el, v);
+              sync();
+            }
+          });
+        if (pi && pi.set && pi.get)
+          Object.defineProperty(el, "selectedIndex", {
+            configurable: true,
+            get: function() {
+              return pi.get.call(el);
+            },
+            set: function(v) {
+              pi.set.call(el, v);
+              sync();
+            }
+          });
+        el.focus = function(o) {
+          if (trigRef.current) trigRef.current.focus(o);
+          else proto.focus.call(el, o);
+        };
+      },
+      [native, sync]
+    );
+    const selMerged = useMergedRef(ref, hook);
+    React13.useEffect(
+      function() {
+        const f = selRef.current && selRef.current.form;
+        if (!f || native) return;
+        function onReset() {
+          setTimeout(sync, 0);
+        }
+        f.addEventListener("reset", onReset);
+        return function() {
+          f.removeEventListener("reset", onReset);
+        };
+      },
+      [native, sync]
+    );
+    const focusedOnce = React13.useRef(false);
+    React13.useEffect(
+      function() {
+        if (!live || focusedOnce.current || !trigRef.current) return;
+        focusedOnce.current = true;
+        if (props.autoFocus || selRef.current && document.activeElement === selRef.current) trigRef.current.focus();
+      },
+      [live]
+    );
+    useIsoLayoutEffect(function() {
+      if (!live) return;
+      sync();
+      if (!open) return;
+      const now = readItems(selRef.current), was = items2[0];
+      const same2 = now.length === was.length && now.every(function(it, i) {
+        const w = was[i];
+        return w.value === it.value && w.label === it.label && w.disabled === it.disabled && w.group === it.group;
+      });
+      if (same2) return;
+      items2[1](now);
+      if (!choices(now).length) {
+        close(false);
+        return;
+      }
+      const hv = was[active] ? was[active].value : null;
+      const again = now.filter(function(it) {
+        return !it.disabled && it.value === hv;
+      })[0];
+      const cur = selRef.current ? selRef.current.selectedIndex : -1;
+      activeState[1](again ? again.index : now[cur] && !now[cur].disabled ? cur : choices(now)[0].index);
+    });
+    function choices(list) {
+      return list.filter(function(i) {
+        return !i.disabled;
+      });
+    }
+    function choose(it) {
+      const el = selRef.current;
+      if (!el || it.disabled) return;
+      if (el.value !== it.value) {
+        el.value = it.value;
+        el.dispatchEvent(new Event("input", { bubbles: true }));
+        el.dispatchEvent(new Event("change", { bubbles: true }));
+      }
+      sync();
+      close(true);
+    }
+    function openList(at) {
+      if (props.disabled || trigRef.current && trigRef.current.disabled) return;
+      const list = readItems(selRef.current);
+      const ok = choices(list);
+      if (!ok.length) return;
+      items2[1](list);
+      const cur = selRef.current ? selRef.current.selectedIndex : -1;
+      let a = at === "first" ? ok[0].index : at === "last" ? ok[ok.length - 1].index : cur;
+      if (typeof at === "number") a = at;
+      if (a < 0 || !list[a] || list[a].disabled) a = ok[0].index;
+      activeState[1](a);
+      openState[1](true);
+    }
+    function close(focus) {
+      openState[1](false);
+      pos[1](null);
+      if (focus && trigRef.current) trigRef.current.focus();
+    }
+    function step(from, dir, list) {
+      for (let i = from + dir; i >= 0 && i < list.length; i += dir) if (!list[i].disabled) return i;
+      return from;
+    }
+    function typing() {
+      return !!typed.current.text && Date.now() - typed.current.at < 500;
+    }
+    function typeahead(ch, list, from) {
+      const now = Date.now(), t = typed.current;
+      t.text = now - t.at < 500 ? t.text + ch : ch;
+      t.at = now;
+      const q = t.text.toLocaleLowerCase();
+      for (let k = 1; k <= list.length; k++) {
+        const i = (from + (t.text.length > 1 ? 0 : 1) + k - 1 + list.length) % list.length;
+        if (!list[i].disabled && list[i].label.toLocaleLowerCase().indexOf(q) === 0) return i;
+      }
+      t.text = "";
+      return -1;
+    }
+    function onKeyDown(e) {
+      const k = e.key;
+      const printable = k.length === 1 && !e.ctrlKey && !e.metaKey && !e.altKey;
+      const search = printable && (k !== " " || typing());
+      if (!open) {
+        if (search) {
+          const list2 = readItems(selRef.current);
+          const i = typeahead(k, list2, selRef.current ? selRef.current.selectedIndex : -1);
+          e.preventDefault();
+          if (i >= 0) openList(i);
+        } else if (k === "ArrowDown" || k === "ArrowUp" || k === "Enter" || k === " ") {
+          e.preventDefault();
+          openList(k === "ArrowUp" && !(selRef.current && selRef.current.value) ? "last" : void 0);
+        }
+        return;
+      }
+      const list = items2[0];
+      if (search) {
+        e.preventDefault();
+        const i = typeahead(k, list, active);
+        if (i >= 0) activeState[1](i);
+      } else if (k === "ArrowDown") {
+        e.preventDefault();
+        activeState[1](step(active, 1, list));
+      } else if (k === "ArrowUp") {
+        e.preventDefault();
+        activeState[1](step(active, -1, list));
+      } else if (k === "Home" || k === "PageUp") {
+        e.preventDefault();
+        activeState[1](k === "Home" ? step(-1, 1, list) : Math.max(step(-1, 1, list), step(active - 9, 1, list)));
+      } else if (k === "End" || k === "PageDown") {
+        e.preventDefault();
+        activeState[1](
+          k === "End" ? step(list.length, -1, list) : Math.min(step(list.length, -1, list), step(active + 9, -1, list))
+        );
+      } else if (k === "Enter" || k === " ") {
+        e.preventDefault();
+        if (list[active]) choose(list[active]);
+      } else if (k === "Escape") {
+        e.preventDefault();
+        e.stopPropagation();
+        close(true);
+      } else if (k === "Tab") {
+        close(false);
+      }
+    }
+    useIsoLayoutEffect(
+      function() {
+        if (!open) return;
+        function place() {
+          const t = trigRef.current && trigRef.current.parentElement;
+          if (!t) return;
+          const r = t.getBoundingClientRect(), below2 = window.innerHeight - r.bottom - 8, above = r.top - 8, want = listRef.current ? listRef.current.scrollHeight : 320, up = below2 < Math.min(want, 200) && above > below2;
+          pos[1]({
+            left: r.left,
+            width: r.width,
+            top: up ? void 0 : r.bottom + 4,
+            bottom: up ? window.innerHeight - r.top + 4 : void 0,
+            maxHeight: Math.min(320, (up ? above : below2) - 4)
+          });
+        }
+        place();
+        function outside(e) {
+          const n2 = e.target;
+          if (listRef.current && listRef.current.contains(n2)) return;
+          if (trigRef.current && trigRef.current.contains(n2)) return;
+          close(false);
+        }
+        function onScroll(e) {
+          if (!listRef.current || !listRef.current.contains(e.target)) place();
+        }
+        document.addEventListener("pointerdown", outside, true);
+        window.addEventListener("scroll", onScroll, true);
+        window.addEventListener("resize", place);
+        return function() {
+          document.removeEventListener("pointerdown", outside, true);
+          window.removeEventListener("scroll", onScroll, true);
+          window.removeEventListener("resize", place);
+        };
+      },
+      [open]
+    );
+    React13.useEffect(
+      function() {
+        if (!open || !listRef.current || active < 0) return;
+        const el = listRef.current.querySelector('[data-idx="' + active + '"]');
+        if (el && el.scrollIntoView) el.scrollIntoView({ block: "nearest" });
+      },
+      [open, active, pos[0] != null]
+    );
+    const described = [describedBy(id, props), rest["aria-describedby"]].filter(Boolean).join(" ") || void 0;
+    const field = (child) => /* @__PURE__ */ React13.createElement(
       Field,
       {
         id,
+        labelId: native ? void 0 : id + "-label",
         label: props.label,
         hint: props.hint,
         error: props.error,
@@ -1249,19 +1551,180 @@ window.Aura = (() => {
         disabled: props.disabled,
         className: props.className
       },
-      /* @__PURE__ */ React13.createElement("div", { className: cx("aura-input aura-select", props.icon && "has-icon") }, props.icon ? /* @__PURE__ */ React13.createElement(Icon, { name: props.icon, className: "aura-input__icon" }) : null, h3(
-        "select",
-        Object.assign(extra, rest, {
-          ref,
-          id,
-          className: "aura-input__control",
-          required: props.required,
-          "aria-invalid": props.error ? true : void 0,
-          "aria-describedby": describedBy(id, props)
-        }),
-        opts,
-        props.children
-      ), /* @__PURE__ */ React13.createElement(Icon, { name: "chevron-down", className: "aura-select__chevron" }))
+      child
+    );
+    if (!live)
+      return field(
+        /* @__PURE__ */ React13.createElement("div", { className: cx("aura-input aura-select", props.icon && "has-icon") }, props.icon ? /* @__PURE__ */ React13.createElement(Icon, { name: props.icon, className: "aura-input__icon" }) : null, h3(
+          "select",
+          Object.assign(extra, rest, {
+            ref: native ? ref : selMerged,
+            id,
+            className: "aura-input__control",
+            required: props.required,
+            "aria-invalid": props.error ? true : void 0,
+            "aria-describedby": described
+          }),
+          opts,
+          props.children
+        ), /* @__PURE__ */ React13.createElement(Icon, { name: "chevron-down", className: "aura-select__chevron" }))
+      );
+    const listId = id + "-list", labelId = id + "-label";
+    const optId = function(i) {
+      return id + "-opt-" + i;
+    };
+    const labelledBy = rest["aria-labelledby"] || (props.label ? labelId : void 0);
+    const selIndex = selRef.current ? selRef.current.selectedIndex : -1;
+    const option = function(it) {
+      const sel = selIndex === it.index;
+      return /* @__PURE__ */ React13.createElement(
+        "div",
+        {
+          key: it.index,
+          id: optId(it.index),
+          role: "option",
+          "data-idx": it.index,
+          "aria-selected": sel,
+          "aria-disabled": it.disabled || void 0,
+          className: cx(
+            "aura-combo__option",
+            it.index === active && "is-active",
+            sel && "is-selected",
+            it.disabled && "is-disabled"
+          ),
+          onPointerDown: function(e) {
+            e.preventDefault();
+          },
+          onPointerMove: function() {
+            if (!it.disabled && active !== it.index) activeState[1](it.index);
+          },
+          onClick: function() {
+            choose(it);
+          }
+        },
+        /* @__PURE__ */ React13.createElement("span", { className: "aura-combo__text" }, /* @__PURE__ */ React13.createElement("span", { className: "aura-combo__label" }, it.label)),
+        sel ? /* @__PURE__ */ React13.createElement(Icon, { name: "check", className: "aura-combo__check" }) : null
+      );
+    };
+    const runs = [];
+    items2[0].forEach(function(it) {
+      if (it.value === "" && it.disabled) return;
+      const last = runs[runs.length - 1];
+      if (last && last.group === it.group) last.items.push(it);
+      else runs.push({ group: it.group, items: [it] });
+    });
+    const popup = open ? (0, import_react_dom2.createPortal)(
+      /* @__PURE__ */ React13.createElement(
+        "div",
+        {
+          ref: listRef,
+          "data-density": density,
+          className: "aura-combo__popover aura-select__popover",
+          style: pos[0] ? {
+            left: pos[0].left,
+            minWidth: pos[0].width,
+            top: pos[0].top,
+            bottom: pos[0].bottom,
+            maxHeight: pos[0].maxHeight
+          } : { left: -9999, top: -9999 }
+        },
+        /* @__PURE__ */ React13.createElement(
+          "div",
+          {
+            id: listId,
+            role: "listbox",
+            "aria-labelledby": labelledBy,
+            "aria-label": labelledBy ? void 0 : rest["aria-label"],
+            className: "aura-combo__list"
+          },
+          runs.map(function(r, n2) {
+            if (r.group === null) return /* @__PURE__ */ React13.createElement(React13.Fragment, { key: "r" + n2 }, r.items.map(option));
+            const gid = id + "-group-" + n2;
+            return /* @__PURE__ */ React13.createElement("div", { key: "r" + n2, role: "group", "aria-labelledby": gid }, /* @__PURE__ */ React13.createElement("div", { id: gid, className: "aura-select__group" }, r.group), r.items.map(option));
+          })
+        )
+      ),
+      document.body
+    ) : null;
+    const userFocus = rest.onFocus, userBlur = rest.onBlur, userKey = rest.onKeyDown, userClick = rest.onClick;
+    return field(
+      /* @__PURE__ */ React13.createElement(
+        "div",
+        {
+          className: cx("aura-input aura-select aura-select--custom", props.icon && "has-icon", open && "is-open"),
+          "data-invalid": props.error ? "" : void 0
+        },
+        props.icon ? /* @__PURE__ */ React13.createElement(Icon, { name: props.icon, className: "aura-input__icon" }) : null,
+        h3(
+          "select",
+          Object.assign(extra, pick(rest, FORM_KEYS), {
+            ref: selMerged,
+            id: id + "-select",
+            className: "aura-select__native",
+            tabIndex: -1,
+            "aria-hidden": true,
+            required: props.required,
+            onChange: function(e) {
+              sync();
+              if (props.onChange) props.onChange(e);
+            },
+            /* A browser focusing the <select> (the required bubble, a label click) hands focus to the button. */
+            onFocus: function() {
+              if (trigRef.current) trigRef.current.focus();
+            },
+            /* Only the blur the button reports (below): the <select>'s own, while it hands focus over, is not one. */
+            onBlur: function(e) {
+              if (!e.nativeEvent.isTrusted && userBlur) userBlur(e);
+            }
+          }),
+          opts,
+          props.children
+        ),
+        /* @__PURE__ */ React13.createElement(
+          "button",
+          {
+            ...omit(rest, HANDLED_KEYS),
+            ref: trigRef,
+            type: "button",
+            role: "combobox",
+            form: id + "-no-form",
+            className: "aura-input__control aura-select__trigger",
+            disabled: props.disabled,
+            tabIndex: rest.tabIndex,
+            "aria-haspopup": "listbox",
+            "aria-expanded": open,
+            "aria-controls": open ? listId : void 0,
+            "aria-activedescendant": open && active >= 0 ? optId(active) : void 0,
+            id,
+            "aria-label": rest["aria-label"],
+            "aria-labelledby": rest["aria-labelledby"],
+            "aria-required": props.required || void 0,
+            "aria-invalid": props.error ? true : void 0,
+            "aria-describedby": described,
+            onFocus: function(e) {
+              if (userFocus) userFocus(e);
+            },
+            onClick: function(e) {
+              if (userClick) userClick(e);
+              if (e.defaultPrevented) return;
+              if (open) close(true);
+              else openList();
+            },
+            onKeyDown: function(e) {
+              if (userKey) userKey(e);
+              if (!e.defaultPrevented) onKeyDown(e);
+            },
+            onBlur: function(e) {
+              if (listRef.current && e.relatedTarget && listRef.current.contains(e.relatedTarget)) return;
+              if (open) close(false);
+              if (selRef.current) selRef.current.dispatchEvent(new FocusEvent("focusout", { bubbles: true }));
+            }
+          },
+          /* @__PURE__ */ React13.createElement("span", { id: id + "-value", className: cx("aura-select__value", shown[0].empty && "is-placeholder") }, shown[0].label || " ")
+        ),
+        /* @__PURE__ */ React13.createElement(Icon, { name: "chevron-down", className: "aura-select__chevron" }),
+        popup
+      )
     );
   });
 
@@ -1360,7 +1823,7 @@ window.Aura = (() => {
 
   // src/Combobox.tsx
   var React16 = __toESM(require_react(), 1);
-  var import_react_dom2 = __toESM(require_react_dom(), 1);
+  var import_react_dom3 = __toESM(require_react_dom(), 1);
   function norm(s) {
     return String(s == null ? "" : s).normalize("NFC").toLocaleLowerCase("th");
   }
@@ -1380,6 +1843,7 @@ window.Aura = (() => {
       const multi = all.multiple === true;
       const mp = all;
       const t = useStrings();
+      const density = useDensity();
       const auto = uid(), id = props.id || auto, listId = id + "-list";
       const options = (props.options || []).map(toOpt);
       const st = useMaybeControlled(
@@ -1542,8 +2006,8 @@ window.Aura = (() => {
       const optId = function(i) {
         return id + "-opt-" + i;
       };
-      const list = open && mounted && posState[0] ? (0, import_react_dom2.createPortal)(
-        /* @__PURE__ */ React16.createElement("div", { ref: listRef, className: "aura-combo__popover", style: posState[0] }, live.length ? /* @__PURE__ */ React16.createElement(
+      const list = open && mounted && posState[0] ? (0, import_react_dom3.createPortal)(
+        /* @__PURE__ */ React16.createElement("div", { ref: listRef, "data-density": density, className: "aura-combo__popover", style: posState[0] }, live.length ? /* @__PURE__ */ React16.createElement(
           "ul",
           {
             id: listId,
@@ -1703,7 +2167,7 @@ window.Aura = (() => {
 
   // src/DatePicker.tsx
   var React17 = __toESM(require_react(), 1);
-  var import_react_dom3 = __toESM(require_react_dom(), 1);
+  var import_react_dom4 = __toESM(require_react_dom(), 1);
 
   // src/dates.ts
   var ERA = /^พ\.ศ\.\s?|\s?(BE|พ\.ศ\.)$/g;
@@ -2308,7 +2772,7 @@ window.Aura = (() => {
       pop.setOpen(false);
       if (inputRef.current) inputRef.current.focus();
     }
-    const cal = pop.open && pop.mounted && pop.pos ? (0, import_react_dom3.createPortal)(
+    const cal = pop.open && pop.mounted && pop.pos ? (0, import_react_dom4.createPortal)(
       /* @__PURE__ */ React17.createElement(
         "div",
         {
@@ -2433,7 +2897,7 @@ window.Aura = (() => {
         draft[1](null);
         if (inputRef.current) inputRef.current.focus();
       }
-      function pick(iso) {
+      function pick2(iso) {
         if (!draft[0]) {
           draft[1](iso);
           return;
@@ -2443,7 +2907,7 @@ window.Aura = (() => {
         st[1](a <= b ? { start: a, end: b } : { start: b, end: a });
         close();
       }
-      const cal = pop.open && pop.mounted && pop.pos ? (0, import_react_dom3.createPortal)(
+      const cal = pop.open && pop.mounted && pop.pos ? (0, import_react_dom4.createPortal)(
         /* @__PURE__ */ React17.createElement(
           "div",
           {
@@ -2477,7 +2941,7 @@ window.Aura = (() => {
               start: draft[0] || v.start,
               end: draft[0] ? null : v.end,
               focus: draft[0] || v.start,
-              onSelect: pick
+              onSelect: pick2
             }
           )
         ),
@@ -2547,7 +3011,7 @@ window.Aura = (() => {
 
   // src/Toaster.tsx
   var React19 = __toESM(require_react(), 1);
-  var import_react_dom4 = __toESM(require_react_dom(), 1);
+  var import_react_dom5 = __toESM(require_react_dom(), 1);
   var MAX_VISIBLE = 3;
   var toastState = {
     list: [],
@@ -2708,7 +3172,7 @@ window.Aura = (() => {
       };
     }, []);
     if (!mounted) return null;
-    return (0, import_react_dom4.createPortal)(
+    return (0, import_react_dom5.createPortal)(
       /* @__PURE__ */ React19.createElement(
         "div",
         {
@@ -2989,7 +3453,7 @@ window.Aura = (() => {
 
   // src/Command.tsx
   var React25 = __toESM(require_react(), 1);
-  var import_react_dom5 = __toESM(require_react_dom(), 1);
+  var import_react_dom6 = __toESM(require_react_dom(), 1);
 
   // src/useModal.tsx
   var React24 = __toESM(require_react(), 1);
@@ -3193,7 +3657,7 @@ window.Aura = (() => {
     }
     if (!modal.ready) return null;
     let i = -1;
-    return (0, import_react_dom5.createPortal)(
+    return (0, import_react_dom6.createPortal)(
       /* @__PURE__ */ React25.createElement(
         "div",
         {
@@ -3302,7 +3766,7 @@ window.Aura = (() => {
 
   // src/Tooltip.tsx
   var React26 = __toESM(require_react(), 1);
-  var import_react_dom6 = __toESM(require_react_dom(), 1);
+  var import_react_dom7 = __toESM(require_react_dom(), 1);
   var Tooltip = React26.forwardRef(function Tooltip2(props, ref) {
     const id = uid(), st = React26.useState(false), open = props.open !== void 0 ? props.open : st[0], set = st[1];
     const anchor = React26.useRef(null), anchorMerged = useMergedRef(ref, anchor), tip = React26.useRef(null), timer = React26.useRef(void 0);
@@ -3400,7 +3864,7 @@ window.Aura = (() => {
       },
       React26.cloneElement(child, { "aria-describedby": open ? id : child.props["aria-describedby"] })
     );
-    return /* @__PURE__ */ React26.createElement(React26.Fragment, null, trigger, open && mounted ? (0, import_react_dom6.createPortal)(
+    return /* @__PURE__ */ React26.createElement(React26.Fragment, null, trigger, open && mounted ? (0, import_react_dom7.createPortal)(
       /* @__PURE__ */ React26.createElement(
         "div",
         {
@@ -3422,7 +3886,7 @@ window.Aura = (() => {
 
   // src/Dialog.tsx
   var React27 = __toESM(require_react(), 1);
-  var import_react_dom7 = __toESM(require_react_dom(), 1);
+  var import_react_dom8 = __toESM(require_react_dom(), 1);
   var Dialog = React27.forwardRef(function Dialog2(props, ref) {
     const t = useStrings();
     const density = useDensity();
@@ -3437,7 +3901,7 @@ window.Aura = (() => {
       footSelector: ".aura-dialog__foot"
     });
     if (!modal.ready) return null;
-    return (0, import_react_dom7.createPortal)(
+    return (0, import_react_dom8.createPortal)(
       /* @__PURE__ */ React27.createElement("div", { className: "aura-dialog-layer", "data-density": density, onKeyDown: modal.onKeyDown }, /* @__PURE__ */ React27.createElement("div", { className: "aura-scrim", onClick: close, "aria-hidden": true }), /* @__PURE__ */ React27.createElement(
         "div",
         {
@@ -3472,7 +3936,7 @@ window.Aura = (() => {
     });
     if (!modal.ready) return null;
     const side = props.side === "left" ? "left" : "right";
-    return (0, import_react_dom7.createPortal)(
+    return (0, import_react_dom8.createPortal)(
       /* @__PURE__ */ React27.createElement("div", { className: "aura-dialog-layer aura-drawer-layer", "data-density": density, onKeyDown: modal.onKeyDown }, /* @__PURE__ */ React27.createElement("div", { className: "aura-scrim", onClick: close, "aria-hidden": true }), /* @__PURE__ */ React27.createElement(
         "div",
         {
@@ -3496,7 +3960,7 @@ window.Aura = (() => {
 
   // src/DataTable.tsx
   var React28 = __toESM(require_react(), 1);
-  var import_react_dom8 = __toESM(require_react_dom(), 1);
+  var import_react_dom9 = __toESM(require_react_dom(), 1);
   var BP = { sm: 640, md: 768, lg: 1024, xl: 1280 };
   var DEFAULT_COLUMNS = [
     { key: "id", label: "ID", width: 96, mono: true },
@@ -3653,7 +4117,7 @@ window.Aura = (() => {
     function hideFull() {
       setTip(null);
     }
-    const tipEl = tip && typeof document !== "undefined" ? (0, import_react_dom8.createPortal)(
+    const tipEl = tip && typeof document !== "undefined" ? (0, import_react_dom9.createPortal)(
       /* @__PURE__ */ React28.createElement(
         "div",
         {
@@ -4903,7 +5367,7 @@ window.Aura = (() => {
 
   // src/SideNav.tsx
   var React31 = __toESM(require_react(), 1);
-  var import_react_dom9 = __toESM(require_react_dom(), 1);
+  var import_react_dom10 = __toESM(require_react_dom(), 1);
   function contains(it, id) {
     return !!id && !!it.children && it.children.some(function(c) {
       return c.id === id || contains(c, id);
@@ -5096,7 +5560,7 @@ window.Aura = (() => {
           }
         }
       )) : null,
-      tip && typeof document !== "undefined" ? (0, import_react_dom9.createPortal)(
+      tip && typeof document !== "undefined" ? (0, import_react_dom10.createPortal)(
         /* @__PURE__ */ React31.createElement(
           "div",
           {
@@ -5540,7 +6004,7 @@ window.Aura = (() => {
 
   // src/TimePicker.tsx
   var React45 = __toESM(require_react(), 1);
-  var import_react_dom10 = __toESM(require_react_dom(), 1);
+  var import_react_dom11 = __toESM(require_react_dom(), 1);
 
   // src/text.ts
   function formatBytes(n2) {
@@ -5756,7 +6220,7 @@ window.Aura = (() => {
       }
     }
     const error = errState[0] || props.error;
-    const list = open && mounted && pos[0] ? (0, import_react_dom10.createPortal)(
+    const list = open && mounted && pos[0] ? (0, import_react_dom11.createPortal)(
       /* @__PURE__ */ React45.createElement("div", { ref: listRef, className: "aura-combo__popover aura-time__popover", style: pos[0] }, /* @__PURE__ */ React45.createElement("ul", { id: listId, role: "listbox", "aria-label": props.label, className: "aura-combo__list" }, slots.map(function(s, i) {
         const dis = blocked(s), sel = s === value;
         return /* @__PURE__ */ React45.createElement(
@@ -6747,7 +7211,7 @@ window.Aura = (() => {
 
   // src/Popover.tsx
   var React55 = __toESM(require_react(), 1);
-  var import_react_dom11 = __toESM(require_react_dom(), 1);
+  var import_react_dom12 = __toESM(require_react_dom(), 1);
   function position(anchor, pop, placement) {
     const r = anchor.getBoundingClientRect(), pw = pop.offsetWidth, ph = pop.scrollHeight, vw = window.innerWidth, vh = window.innerHeight, gap = 6;
     let side = (placement || "bottom-start").split("-")[0], align = (placement || "bottom-start").split("-")[1] || "start";
@@ -6825,7 +7289,7 @@ window.Aura = (() => {
       [open, mounted]
     );
     const child = React55.Children.only(props.trigger);
-    const panel = open && mounted ? (0, import_react_dom11.createPortal)(
+    const panel = open && mounted ? (0, import_react_dom12.createPortal)(
       /* @__PURE__ */ React55.createElement(
         "div",
         {

package/components/aura.components.css

@@ -424,7 +424,16 @@ a.aura-icon-btn { text-decoration: none; }
 .aura-select .aura-input__control { padding-right: calc(var(--aura-space-3) + var(--aura-icon-sm) + var(--aura-space-2)); cursor: pointer; }
 .aura-select__chevron { position: absolute; right: var(--aura-space-3); color: var(--aura-fg-secondary); pointer-events: none; }
 .aura-select select:invalid, .aura-select select:has(option[value=""]:checked) { color: var(--aura-fg-tertiary); }
+/* 5.3: the field is a button over an invisible <select> (forms, refs, events); the list is AURA's, like Combobox. */
 .aura-select option { color: var(--aura-fg-primary); background: var(--aura-bg-input); }
+.aura-select--custom { position: relative; }
+.aura-select__native { position: absolute; inset: 0; width: 100%; height: 100%; margin: 0; padding: 0; border: 0; opacity: 0; pointer-events: none; appearance: none; }
+.aura-select__trigger { display: flex; align-items: center; text-align: start; background: none; border: 0; color: inherit; font: inherit; width: 100%; min-width: 0; }
+.aura-select__trigger:disabled { cursor: not-allowed; }
+.aura-select__value { flex: 1; min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.aura-select__value.is-placeholder { color: var(--aura-fg-tertiary); }
+.aura-select__group { padding: var(--aura-space-2) var(--aura-space-2) var(--aura-space-1); font-family: var(--font-mono); font-size: 11px; text-transform: uppercase; letter-spacing: 0.04em; color: var(--aura-fg-tertiary); }
+.aura-select.is-open .aura-select__chevron { transform: rotate(180deg); }
 
 .aura-radio-group > legend { margin-bottom: 6px; }
 .aura-radio-group__list { display: flex; flex-direction: column; gap: var(--aura-space-3); }

package/components/index.d.ts

@@ -46,6 +46,11 @@ export interface DataTableState {
 	sort: DataTableSort | null;
 	page: number;
 }
+/** A callback that gets one row. Written with your own row type (`(r: Order) => …`) it still fits (5.4):
+ * the row is checked the way method parameters are, so no cast from `Record<string, any>` is needed. */
+export type RowCallback<R> = {
+	bivarianceHack(row: Record<string, any>): R;
+}["bivarianceHack"];
 export interface DataTableColumn {
 	/** Key into each row object. */
 	key: string;
@@ -62,9 +67,9 @@ export interface DataTableColumn {
 	/** Header becomes a button cycling asc → desc → unsorted. */
 	sortable?: boolean | undefined;
 	/** Value to sort by, when not the cell value (dates, amounts). */
-	sortValue?: ((row: Record<string, any>) => string | number | null) | undefined;
+	sortValue?: RowCallback<string | number | null> | undefined;
 	/** Custom cell content. */
-	render?: ((row: Record<string, any>) => React$1.ReactNode) | undefined;
+	render?: RowCallback<React$1.ReactNode> | undefined;
 	/** Set false to keep a sized column fixed when the table is `resizable`. */
 	resizable?: boolean | undefined;
 	/** Resize limits in px. Defaults 64 / 480. For the flexible column, minWidth defaults to 160. */
@@ -98,7 +103,9 @@ export interface DataTableEmpty {
 export interface DataTableProps {
 	/** Defaults to ID · NAME · STATUS · OWNER (96 / 160 / 112 / auto px). */
 	columns?: DataTableColumn[] | undefined;
-	rows: Array<Record<string, React$1.ReactNode>>;
+	/** Row objects. Any typed interface works (5.4: before, `interface Order {…}` rows needed a cast); cells show
+	 * the value at each column's key unless the column has `render`. */
+	rows: ReadonlyArray<Record<string, any>>;
 	/** Column key giving each row a unique React key. Default: the first column's key. */
 	rowKey?: string | undefined;
 	/** Accessible name for the table. */
@@ -145,7 +152,7 @@ export interface DataTableProps {
 	totalRows?: number | undefined;
 	/** Makes each row a link: the first column's content renders as the provider's linkComponent (or `<a>`), and a click
 	 * or Enter anywhere on the row follows it. Ctrl/⌘-click opens a new tab as usual. */
-	getRowHref?: ((row: Record<string, any>) => string) | undefined;
+	getRowHref?: RowCallback<string> | undefined;
 	/** Pager arrows become links to these URLs (search-param paging). Without onPageChange the link navigates. */
 	getPageHref?: ((page: number) => string) | undefined;
 	/** Router link for getRowHref / getPageHref. Default: AuraProvider's linkComponent, else `<a>`. */
@@ -153,7 +160,7 @@ export interface DataTableProps {
 	/** Skeleton row count when there is no pageSize. Default 5. */
 	skeletonRows?: number | undefined;
 	/** Called on row click or Enter. */
-	onRowActivate?: ((row: Record<string, any>) => void) | undefined;
+	onRowActivate?: RowCallback<void> | undefined;
 	/** Fixed height in px: sticky header, and only the rows in view are rendered. */
 	height?: number | undefined;
 	/** Column menu on every header, drag-to-reorder, and the show/hide columns button. */
@@ -321,11 +328,14 @@ export interface FormErrorItem {
 	message: React$1.ReactNode;
 }
 /** The list of problems at the top of a form after a failed submit; each links to its field (GOV.UK pattern). */
+/** react-hook-form's `formState.errors` (FieldErrors) or any object shaped like it: a `message` at any depth. */
+export type FormErrorTree = {
+	readonly [field: string]: object | undefined;
+};
 export interface FormErrorSummaryProps {
-	/** A list, or react-hook-form's `formState.errors` as is (`{ name: { message } }`). Empty → renders nothing. */
-	errors: FormErrorItem[] | Record<string, {
-		message?: React$1.ReactNode | undefined;
-	} | undefined>;
+	/** A list, or react-hook-form's `formState.errors` as is: `{ name: { message } }`, nested for `address.street`
+	 * and field arrays (`items.0.name`). Empty → renders nothing. */
+	errors: FormErrorItem[] | FormErrorTree;
 	/** Default "Fix N fields to continue" in the provider's language. */
 	title?: React$1.ReactNode | undefined;
 	/** Called with the field when a link is followed, e.g. react-hook-form's `setFocus`. Default: focus the element whose id (or name) is the field. */
@@ -417,9 +427,15 @@ export type SelectOption = string | {
 	label: string;
 	disabled?: boolean | undefined;
 };
-export interface SelectProps extends FieldProps, Omit<React$1.SelectHTMLAttributes<HTMLSelectElement>, "required"> {
-	options: SelectOption[];
-	/** A disabled first option shown in fg-tertiary until something is chosen. */
+/** 5.3: opens AURA's own list (light and dark alike) over a real `<select>`, which keeps `name`, `required`, the ref,
+ * `onChange`, react-hook-form `register` and form posts. `multiple` or `size > 1` keeps the native list box. */
+export interface SelectProps extends Omit<FieldProps, "label">, Omit<React$1.SelectHTMLAttributes<HTMLSelectElement>, "required"> {
+	/** Visible label; also the accessible name. Omit only with `aria-label` or `aria-labelledby` (a toolbar, a table
+	 * cell); development builds warn when the field has no name at all. */
+	label?: string | undefined;
+	/** The choices; or pass `<option>` / `<optgroup>` children instead (5.3: optional). */
+	options?: SelectOption[] | undefined;
+	/** Shown in fg-tertiary on the closed field until something is chosen; not listed as a choice. */
 	placeholder?: string | undefined;
 	icon?: IconInput | undefined;
 }
@@ -1217,6 +1233,7 @@ export interface FieldComponentProps extends Omit<FieldPropsPublic, "label"> {
 export declare const Field: React$1.ForwardRefExoticComponent<FieldComponentProps & React$1.RefAttributes<HTMLDivElement>>;
 export declare const TextField: React$1.ForwardRefExoticComponent<TextFieldProps & React$1.RefAttributes<HTMLInputElement>>;
 export declare const Textarea: React$1.ForwardRefExoticComponent<TextareaProps & React$1.RefAttributes<HTMLTextAreaElement>>;
+/** A select field: a button that opens an AURA list (5.3), over a real <select> that keeps forms, refs and events. */
 export declare const Select: React$1.ForwardRefExoticComponent<SelectProps & React$1.RefAttributes<HTMLSelectElement>>;
 export declare const RadioGroup: React$1.ForwardRefExoticComponent<RadioGroupProps & React$1.RefAttributes<HTMLFieldSetElement>>;
 export declare const Switch: React$1.ForwardRefExoticComponent<SwitchProps & React$1.RefAttributes<HTMLButtonElement>>;

package/eslint-plugin-aura.js

@@ -1,3 +1,4 @@
+// @ts-check
 // eslint-plugin-aura.js — AURA 5.2
 // Flags hard-coded colours in JS/TS: hex (#rgb, #rgba, #rrggbb, #rrggbbaa), colour functions (rgb/hsl/hwb/lab/lch/
 // oklab/oklch/color-mix), CSS named colours in a style value, Tailwind palette classes (bg-red-500, text-white) and
@@ -17,6 +18,7 @@ const HEX = /#(?:[0-9a-f]{8}|[0-9a-f]{6}|[0-9a-f]{3,4})(?![\w-])/i;
  * call a template literal continues (`rgb(${r}, …)`). Token-based ones pass: rgb(var(--brand-rgb) / .5),
  * color-mix(in srgb, var(--aura-accent) 20%, transparent). var() and url() are removed before any check. */
 const FN_CALL = /\b(?:rgba?|hsla?|hwb|lab|lch|oklab|oklch|color-mix)\(([^()]*)(\)|$)/gi;
+/** @param {string} v */
 function fnHit(v) {
   FN_CALL.lastIndex = 0;
   let m;
@@ -26,7 +28,7 @@ function fnHit(v) {
   }
   return null;
 }
-const stripRefs = (v) => v.replace(/var\([^()]*(?:\([^()]*\)[^()]*)*\)/g, ' ').replace(/url\([^)]*\)/g, ' ');
+const stripRefs = (/** @type {string} */ v) => v.replace(/var\([^()]*(?:\([^()]*\)[^()]*)*\)/g, ' ').replace(/url\([^)]*\)/g, ' ');
 const TW_ARB = new RegExp('(?:^|[\\s:"\'`])(?:' + UTIL + ')-\\[(?:#|rgb|hsl|oklch|color)', 'i');
 const TW_PAL = new RegExp(
   '(?:^|[\\s:"\'`!])(?:' + UTIL + ')-(?:(?:' + PALETTE + ')-\\d{2,3}|white|black)(?:\\/\\d+)?(?![\\w-])',
@@ -49,6 +51,10 @@ const COLOUR_KEY =
 const NOT_COLOUR_ATTR =
   /^(?:href|to|id|htmlFor|for|src|action|formAction|xlinkHref|xlink:href|aria-[a-z]+|data-[\w-]+|name|key)$/;
 
+/**
+ * @param {unknown} raw
+ * @param {boolean} colourKey
+ */
 function hitIn(raw, colourKey) {
   if (typeof raw !== 'string') return null;
   const value = stripRefs(raw);
@@ -59,6 +65,8 @@ function hitIn(raw, colourKey) {
   if (colourKey && NAMED_WHOLE.test(value)) return value.trim();
   return null;
 }
+/** An ESTree / JSX AST node, loosely (the plugin runs on whatever parser the project uses). @typedef {any} Node */
+/** @param {Node} node */
 function skip(node) {
   let p = node.parent;
   if (!p) return false;
@@ -80,11 +88,17 @@ function skip(node) {
     return true;
   return false;
 }
+/** @param {Node} node */
 function colourKeyOf(node) {
   const p = node.parent;
   if (p && p.type === 'Property' && p.value === node && p.key) return COLOUR_KEY.test(p.key.name || p.key.value || '');
   return false;
 }
+/**
+ * @param {{ report(d: { node: Node, message: string }): void }} context
+ * @param {Node} node
+ * @param {string} hit
+ */
 function report(context, node, hit) {
   context.report({
     node,
@@ -101,14 +115,14 @@ const plugin = {
         docs: { description: 'ห้ามใช้สี hardcode ให้ใช้ token — use AURA semantic tokens, never raw colours' },
         schema: [],
       },
-      create(context) {
+      create(/** @type {any} */ context) {
         return {
-          Literal(node) {
+          Literal(/** @type {Node} */ node) {
             if (skip(node)) return;
             const hit = hitIn(node.value, colourKeyOf(node));
             if (hit) report(context, node, hit);
           },
-          TemplateElement(node) {
+          TemplateElement(/** @type {Node} */ node) {
             if (skip(node)) return;
             const hit = hitIn(node.value && node.value.raw, false);
             if (hit) report(context, node, hit);
@@ -117,6 +131,7 @@ const plugin = {
       },
     },
   },
+  /** @type {Record<string, { plugins: unknown, rules: Record<string, string> }>} */
   configs: {},
 };
 /* Flat config (ESLint 9, the default): the plugin object itself, not a name. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jirawatpyk/aura-tokens",
-  "version": "5.2.0",
+  "version": "5.4.0",
   "description": "AURA Design System — tokens (CSS variables, Tailwind preset, Figma variables), theme contrast checks and token lint.",
   "main": "tailwind.tokens.cjs",
   "types": "components/index.d.ts",
@@ -55,14 +55,14 @@
     "./package.json": "./package.json"
   },
   "scripts": {
-    "build": "node scripts/build-tokens.js",
+    "build": "node scripts/build-tokens.mts",
     "a11y": "node scripts/a11y-check.js",
-    "check:tailwind4": "node scripts/tailwind4-check.mjs",
+    "check:tailwind4": "node scripts/tailwind4-check.mts",
     "lint:tokens": "node scripts/lint-tokens.js ../react/src && node scripts/lint-tokens.js ../react/styles",
-    "check:generated": "node scripts/build-tokens.js && git diff --exit-code -- aura.css aura-fonts.css aura-fonts.local.css tailwind.tokens.cjs aura-tailwind.css aura-tailwind.prefixed.css figma-variables.csv",
+    "check:generated": "node scripts/build-tokens.mts && git diff --exit-code -- aura.css aura-fonts.css aura-fonts.local.css tailwind.tokens.cjs aura-tailwind.css aura-tailwind.prefixed.css figma-variables.csv",
     "prepack": "npm run build",
-    "check:fonts": "node scripts/fonts-check.mjs",
-    "check:eslint": "node scripts/eslint-check.mjs"
+    "check:fonts": "node scripts/fonts-check.mts",
+    "check:eslint": "node scripts/eslint-check.mts"
   },
   "keywords": [
     "design-system",

package/scripts/a11y-check.js

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+// @ts-check
 /* AURA contrast check — resolves tokens.json and tests every documented text/ground pair in BOTH themes.
  * Text needs 4.5:1, control edges and focus rings 3:1 (WCAG 2.1 AA). Writes a11y-report.json; exits 1 on any failure. */
 const fs = require('fs');
@@ -6,6 +7,11 @@ const path = require('path');
 const TOKENS = path.join(__dirname, '..', 'tokens.json');
 const T = JSON.parse(fs.readFileSync(TOKENS, 'utf8'));
 
+/**
+ * @param {unknown} value
+ * @param {string} theme
+ * @returns {string}
+ */
 function resolve(value, theme, depth = 0) {
   if (depth > 16) throw new Error('alias loop at ' + value);
   const m = /^\{(primitive|semantic|component)\.([a-z0-9-]+)(?:\.([a-z0-9]+))?\}$/.exec(String(value).trim());
@@ -16,24 +22,38 @@ function resolve(value, theme, depth = 0) {
   if (v === undefined) throw new Error(`missing ${tier}.${a} (${theme})`);
   return resolve(v, theme, depth + 1);
 }
-const tok = (name, theme) => resolve(T.semantic[theme][name] ?? T.component[theme][name], theme);
+const tok = (/** @type {string} */ name, /** @type {string} */ theme) => resolve(T.semantic[theme][name] ?? T.component[theme][name], theme);
 
+/**
+ * @param {string} c
+ * @param {string} [ground]
+ * @returns {number[]}
+ */
 function rgb(c, ground) {
   let m = /^#([0-9a-f]{6})$/i.exec(c);
-  if (m) return [0, 2, 4].map((i) => parseInt(m[1].slice(i, i + 2), 16));
+  const hex = m && m[1];
+  if (hex) return [0, 2, 4].map((i) => parseInt(hex.slice(i, i + 2), 16));
   m = /^#([0-9a-f]{3})$/i.exec(c);
   if (m) return m[1].split('').map((x) => parseInt(x + x, 16));
   m = /^rgba?\(([^)]+)\)$/i.exec(c);
   if (m) {
     const [r, g, b, a = 1] = m[1].split(',').map(Number);
+    if ([r, g, b, a].some((x) => x === undefined || Number.isNaN(x))) throw new Error('unsupported colour ' + c);
     if (a >= 1 || !ground) return [r, g, b];
     const G = rgb(ground);
-    return [r, g, b].map((v, i) => Math.round(a * v + (1 - a) * G[i]));
+    /** @type {(v: number, i: number) => number} */
+    const mix = (v, i) => Math.round(a * v + (1 - a) * (G[i] || 0));
+    return [r || 0, g || 0, b || 0].map(mix);
   }
   throw new Error('unsupported colour ' + c);
 }
-const lum = (c) => rgb(c).map((v) => v / 255).map((v) => (v <= 0.03928 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4))
-  .reduce((s, v, i) => s + v * [0.2126, 0.7152, 0.0722][i], 0);
+const W = [0.2126, 0.7152, 0.0722];
+const lum = (/** @type {string} */ c) => rgb(c).map((v) => v / 255).map((v) => (v <= 0.03928 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4))
+  .reduce((s, v, i) => s + v * (W[i] || 0), 0);
+/**
+ * @param {string} fg
+ * @param {string} bg
+ */
 function ratio(fg, bg) {
   const B = '#' + rgb(bg).map((v) => v.toString(16).padStart(2, '0')).join('');
   const F = '#' + rgb(fg, B).map((v) => v.toString(16).padStart(2, '0')).join('');
@@ -43,6 +63,7 @@ function ratio(fg, bg) {
 
 const TEXT = 4.5, UI = 3;
 const grounds = ['bg-surface', 'bg-canvas', 'bg-surface-hover'];
+/** @type {[string, string, number][]} */
 const pairs = [];
 for (const fg of ['fg-primary', 'fg-secondary', 'fg-tertiary', 'fg-accent', 'fg-danger', 'fg-positive']) for (const bg of grounds) pairs.push([fg, bg, TEXT]);
 pairs.push(['fg-primary', 'bg-selected', TEXT], ['fg-secondary', 'bg-selected', TEXT]);

package/scripts/lint-tokens.js

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+// @ts-check
 /* Token lint — fails when source files hard-code colours instead of AURA tokens, or (CSS) motion:
  * a transition/animation must take its duration and easing from --aura-duration-* / --aura-ease / --aura-spring
  * (`linear` is allowed: it's for spinners and progress, not a feel).
@@ -24,16 +25,19 @@ const NAMED = 'white|black|red|green|blue|yellow|orange|purple|pink|gray|grey|si
 const CSS_NAMED = new RegExp('(?:^|[;{\\s])(?:color|background(?:-color)?|border(?:-[a-z]+)?-color|fill|stroke|outline-color)\\s*:\\s*[^;]*(?<![\\w-])(?:' + NAMED + ')(?![\\w-])');
 /* Colour functions count only with a literal colour inside (a hex or three numbers), as in eslint-plugin-aura. */
 const FN_CALL = /\b(?:rgba?|hsla?|hwb|lab|lch|oklab|oklch|color-mix)\(([^()]*)(\)|$)/gi;
+/** @param {string} v */
 function fnHit(v) {
   FN_CALL.lastIndex = 0;
   let m;
   while ((m = FN_CALL.exec(v))) if (!m[2] || /#[0-9a-f]{3}/i.test(m[1]) || (m[1].match(/-?\d*\.?\d+/g) || []).length >= 3) return m[0];
   return null;
 }
-const stripRefs = (v) => v.replace(/var\([^()]*(?:\([^()]*\)[^()]*)*\)/g, ' ').replace(/url\([^)]*\)/g, ' ');
+const stripRefs = (/** @type {string} */ v) => v.replace(/var\([^()]*(?:\([^()]*\)[^()]*)*\)/g, ' ').replace(/url\([^)]*\)/g, ' ');
 const MOTION_PROP = /\b(?:transition|animation)(?:-duration|-timing-function|-delay)?\s*:/i;
 const MOTION_RAW = /(?:^|[\s,:(])(?:\d*\.?\d+m?s)\b|cubic-bezier\(|\bease(?:-in-out|-in|-out)?\b/gi;
+/** @type {string[]} */
 const violations = [];
+/** @param {string} d */
 function scan(d) {
   if (!fs.existsSync(d)) return;
   for (const f of fs.readdirSync(d)) {
@@ -46,8 +50,9 @@ function scan(d) {
     if (/aura-lint:\s*allow-colours/.test(text.slice(0, 600))) continue;
     text.split('\n').forEach((line, i) => {
       const plain = stripRefs(line);
-      const m = plain.match(COLOUR) || (fnHit(plain) ? [fnHit(plain)] : null);
-      if (m) violations.push(`${path.relative(process.cwd(), full)}:${i + 1}  ${m.map((s) => s.trim().replace(/^[:"'`!]/, '')).join(', ')}`);
+      const fn = fnHit(plain);
+      const m = plain.match(COLOUR) || (fn ? [fn] : null);
+      if (m) violations.push(`${path.relative(process.cwd(), full)}:${i + 1}  ${m.map((/** @type {string} */ s) => s.trim().replace(/^[:"'`!]/, '')).join(', ')}`);
       if (/\.s?css$/.test(f) && !/^\s*--/.test(line)) {
         const n = CSS_NAMED.exec(stripRefs(line.replace(/\/\*.*?\*\//g, '')));
         if (n) violations.push(`${path.relative(process.cwd(), full)}:${i + 1}  named colour: ${n[0].trim()}`);

package/tailwind.tokens.cjs

@@ -1,4 +1,4 @@
-/* GENERATED by scripts/build-tokens.js from tokens.json. Do not edit by hand. */
+/* GENERATED by scripts/build-tokens.mts from tokens.json. Do not edit by hand. */
 module.exports = {
   "colors": {
     "aura": {

package/tokens.json

@@ -1,5 +1,5 @@
 {
-  "version": "5.2.0",
+  "version": "5.4.0",
   "meta": {
     "name": "AURA Design System",
     "tier": "3-tier",