@jirawatpyk/aura-tokens 5.3.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.3.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.3.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.3.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

@@ -1286,6 +1286,14 @@ window.Aura = (() => {
     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);

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. */
@@ -419,7 +429,10 @@ export type SelectOption = string | {
 };
 /** 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 FieldProps, Omit<React$1.SelectHTMLAttributes<HTMLSelectElement>, "required"> {
+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. */

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.3.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.3.0",
+  "version": "5.4.0",
   "meta": {
     "name": "AURA Design System",
     "tier": "3-tier",