@jirawatpyk/aura-react 5.3.0 → 5.4.0

package/README.md

@@ -41,7 +41,7 @@ npm i @jirawatpyk/aura-react @jirawatpyk/aura-tokens   # React 18 or 19; import
 npm i @aura/react@npm:@jirawatpyk/aura-react @aura/tokens@npm:@jirawatpyk/aura-tokens
 ```
 
-React 18.3 and 19 are both tested: the dev dependencies pin 18, and CI switches the whole workspace to 19 (`node scripts/use-react.mjs 19 && npm install`) and runs every suite again — contrast, token lint, SSR, types, build, hydration with 0 warnings, layout before hydration, the three pilot pages and Storybook (axe + behaviour).
+React 18.3 and 19 are both tested: the dev dependencies pin 18, and CI switches the whole workspace to 19 (`node scripts/use-react.mts 19 && npm install`) and runs every suite again — contrast, token lint, SSR, types, build, hydration with 0 warnings, layout before hydration, the three pilot pages and Storybook (axe + behaviour).
 
 Public on npmjs; internal projects can use GitHub Packages instead ([repository README](https://github.com/Jirawatpyk/Aura-design#use-it-in-a-project)).
 
@@ -186,6 +186,13 @@ DataTable with sort and page in the URL (4.17): `onStateChange={({ sort, page })
 - **Time zone**: `timeZone` on AuraProvider, DatePicker, DateRangePicker and Calendar decides "today" (the marker, `min`/`max="today"`, the first month shown); or pass `today` as an ISO date. `todayIn('Asia/Bangkok')` is exported from the root and `/server`.
 - **Toasts** queue past three instead of dropping: six in a row all show, in order, three at a time.
 
+## 5.4 — types, and TypeScript across the repo
+
+- **DataTable** takes rows of your own interface (`rows={orders}` with `interface Order {…}`; readonly arrays too), and `render`, `sortValue`, `getRowHref` and `onRowActivate` can be written with it: `render: (r: Order) => baht(r.amount)` — no cast from `Record<string, any>`.
+- **FormErrorSummary** `errors` accepts a nested object written by hand (`{ address: { street: { message } } }`, arrays for field arrays), not only react-hook-form's `formState.errors`. New type `FormErrorTree`.
+- **Select** `label` is optional when `aria-label` or `aria-labelledby` names the field (a toolbar, a table cell); development builds warn when it has no name at all. Every other field still requires `label`.
+- The example pages (`examples/*`) are TypeScript and type-checked in CI, as are the stories and the repo's scripts; the pilot checks run on Playwright Test instead of Python.
+
 ## 5.3 — Select opens AURA's own list
 
 - **Select** no longer hands its list to the operating system (a white list in dark mode on Windows, a different look on every OS). The field is a button that opens an AURA list like Combobox: tokens in light and dark, a check on the chosen item, `optgroup` headings, disabled options skipped, type to jump (Thai too), Home/End/PageUp/PageDown, Escape closes the list before a dialog. The same list is used on phones (as in shadcn), not the native picker.
@@ -311,11 +318,13 @@ Every optional prop takes `undefined` (4.16), so apps on `exactOptionalPropertyT
 ```bash
 npm run build        # dist/ (ESM, CJS, IIFE, CSS, types)
 npm run test:ssr     # server-render every component
-npm run typecheck    # tsc --strict over src/, then types-test/usage.tsx against the public API
+npm run typecheck    # tsc --strict over src/, types-test/ against the published API, and the example pages
 npm run size         # gzip size of what projects import, against size-budgets.json
-npm run test:pilots  # builds the pilots + 4 brand themes, then 37 behaviour/axe checks at 1440/820/390px (Playwright for Python, axe-core)
+npm run test:pilots  # builds the pilots + 4 brand themes, then 44 behaviour/axe checks at 1440/820/390px (Playwright, axe-core)
 ```
 
+From the repository root, `npm run typecheck` also checks the Storybook stories (strict) and every build, test and release script. The scripts are TypeScript that Node runs as is (type stripping), so working on the repo needs **Node 22.18 or later**; the published packages still run on Node 18+ (their CLI and checkers stay JavaScript, type-checked through `// @ts-check`).
+
 ## Source
 
 `src/` is TypeScript (strict) and JSX, formatted with Prettier (`npm run format`), **one file per component** (`Badge.tsx`, `Tooltip.tsx`, …) so a project that imports one component gets only that component's code. Public prop types live in `src/types.ts` with their docs; each component imports its props from there and `forwardRef`s with them, so the published `dist/index.d.ts` is generated from the code and can't drift from it. The build compiles JSX to `React.createElement` (classic runtime), so the `window.Aura` script needs only `window.React`.

package/dist/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/dist/cjs/index.cjs

@@ -1268,6 +1268,14 @@ var Select = React13.forwardRef(function Select2(props, ref) {
   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/dist/esm/Select.js

@@ -4,7 +4,7 @@ import { createPortal } from "react-dom";
 import { FIELD_KEYS, Field, describedBy } from "./Field.js";
 import { Icon } from "./Icon.js";
 import { useDensity } from "./locale.js";
-import { cx, omit, uid, useIsoLayoutEffect, useMergedRef, useMounted } from "./internal.js";
+import { cx, devWarnOnce, omit, uid, useIsoLayoutEffect, useMergedRef, useMounted } from "./internal.js";
 const h = React.createElement;
 const FORM_KEYS = ["name", "form", "value", "defaultValue", "disabled", "autoComplete", "onInput", "onInvalid"];
 const HANDLED_KEYS = FORM_KEYS.concat([
@@ -66,6 +66,14 @@ const Select = React.forwardRef(function Select2(props, ref) {
   const mounted = useMounted();
   const live = !native && mounted;
   const density = useDensity();
+  React.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 = React.useRef(null), trigRef = React.useRef(null), listRef = React.useRef(null);
   const shown = React.useState(function() {
     return initialLabel(props);

package/dist/index.d.cts

@@ -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/dist/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jirawatpyk/aura-react",
-  "version": "5.3.0",
+  "version": "5.4.0",
   "description": "AURA Design System — React components (Enterprise Standard, Human Creative). Thai-first: Buddhist-era dates, Thai collation.",
   "license": "MIT",
   "type": "module",
@@ -44,20 +44,20 @@
     "./dist/aura.bundle.js"
   ],
   "scripts": {
-    "build": "node scripts/build.mjs && node scripts/sync-bundle.mjs",
-    "test:ssr": "node scripts/ssr-test.mjs && node --conditions=react-server scripts/server-entry-test.mjs",
-    "typecheck": "tsc -p tsconfig.src.json && tsc -p tsconfig.json && tsc -p tsconfig.exact.json",
-    "examples": "node examples/build.mjs",
-    "themes": "node scripts/test-themes.mjs",
-    "test:pilots": "npm run examples && npm run themes && python3 tests/pilot_test.py && python3 tests/pilots_test.py",
+    "build": "node scripts/build.ts && node scripts/sync-bundle.ts",
+    "test:ssr": "node scripts/ssr-test.ts && node --conditions=react-server scripts/server-entry-test.ts",
+    "typecheck": "tsc -p tsconfig.src.json && tsc -p tsconfig.json && tsc -p tsconfig.exact.json && tsc -p examples/tsconfig.json",
+    "examples": "node examples/build.ts",
+    "themes": "node scripts/test-themes.ts",
+    "test:pilots": "npm run examples && npm run themes && playwright test -c tests/playwright.config.ts",
     "theme": "node scripts/aura-theme.mjs",
     "prepack": "npm run build",
-    "pretest:ssr": "node scripts/build.mjs",
-    "prethemes": "node scripts/build.mjs",
-    "test:hydrate": "node scripts/hydrate-test.mjs",
-    "size": "node scripts/size-check.mjs",
-    "preexamples": "node scripts/build.mjs",
-    "test:layout": "node scripts/layout-test.mjs"
+    "pretest:ssr": "node scripts/build.ts",
+    "prethemes": "node scripts/build.ts",
+    "test:hydrate": "node scripts/hydrate-test.ts",
+    "size": "node scripts/size-check.ts",
+    "preexamples": "node scripts/build.ts",
+    "test:layout": "node scripts/layout-test.ts"
   },
   "peerDependencies": {
     "react": ">=18",
@@ -72,7 +72,7 @@
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
     "react-hook-form": "^7.53.0",
-    "typescript": "^5.6.0",
+    "typescript": "^5.8.0",
     "@playwright/test": "^1.45.0"
   },
   "bin": {

package/scripts/aura-theme.mjs

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+// @ts-check
 /* aura-theme — write a project theme CSS file from a brand colour.
  *   npx aura-theme --brand "#0ea5e9" [--signal "#facc15"] [--primary brand] [--name acme] [--selector .tenant-acme] [--out src/aura-theme.css]
  * Prints every contrast check; exits 1 if any fails. */
@@ -7,39 +8,50 @@ import { createTheme } from '../dist/esm/theme.js';
 
 const USAGE = 'Usage: aura-theme --brand "#0ea5e9" [--signal "#facc15"] [--primary ink|brand] [--name acme] [--selector .tenant] [--out theme.css]';
 const KNOWN = ['brand', 'signal', 'primary', 'name', 'selector', 'out', 'help'];
+/**
+ * @param {string} msg
+ * @returns {never}
+ */
 function fail(msg) {
   console.error('aura-theme: ' + msg + '\n' + USAGE);
   process.exit(2);
 }
 /* --key value and --key=value (5.2); a value-taking option with no value is an error, not `true`. */
+/** @type {Record<string, string>} */
 const args = {};
+let help = false;
 for (let i = 2; i < process.argv.length; i++) {
-  const a = process.argv[i];
+  const a = process.argv[i] || '';
   if (!a.startsWith('--')) fail('unexpected "' + a + '"');
   const eq = a.indexOf('=');
   const k = eq > 0 ? a.slice(2, eq) : a.slice(2);
   if (KNOWN.indexOf(k) < 0) fail('unknown option --' + k);
-  if (k === 'help') { args.help = true; continue; }
-  const v = eq > 0 ? a.slice(eq + 1) : process.argv[i + 1] !== undefined && !process.argv[i + 1].startsWith('--') ? process.argv[++i] : undefined;
+  if (k === 'help') { help = true; continue; }
+  const next = process.argv[i + 1];
+  const v = eq > 0 ? a.slice(eq + 1) : next !== undefined && !next.startsWith('--') ? process.argv[++i] : undefined;
   if (v === undefined || v === '') fail('--' + k + ' needs a value');
   args[k] = v;
 }
-if (args.help) {
+if (help) {
   console.log(USAGE);
   process.exit(0);
 }
 if (!args.brand) fail('--brand is required');
 for (const k of ['brand', 'signal']) {
-  if (args[k] !== undefined && /^(?:[0-9a-f]{3}|[0-9a-f]{6})$/i.test(args[k])) args[k] = '#' + args[k]; /* a shell ate the # */
-  if (args[k] !== undefined && !/^#(?:[0-9a-f]{3}|[0-9a-f]{6})$/i.test(args[k])) fail('--' + k + ' must be a #rgb or #rrggbb colour (got "' + args[k] + '"; quote it in the shell: --' + k + ' "#0ea5e9")');
+  const c = args[k];
+  if (c !== undefined && /^(?:[0-9a-f]{3}|[0-9a-f]{6})$/i.test(c)) args[k] = '#' + c; /* a shell ate the # */
+  const hex = args[k];
+  if (hex !== undefined && !/^#(?:[0-9a-f]{3}|[0-9a-f]{6})$/i.test(hex)) fail('--' + k + ' must be a #rgb or #rrggbb colour (got "' + args[k] + '"; quote it in the shell: --' + k + ' "#0ea5e9")');
 }
 if (args.primary !== undefined && args.primary !== 'ink' && args.primary !== 'brand') fail('--primary is ink or brand');
-let t, css;
+/** @type {ReturnType<typeof createTheme>} */
+let t;
+let css = '';
 try {
   t = createTheme({ brand: args.brand, signal: args.signal, primary: args.primary, name: args.name });
   css = t.css(args.selector);
 } catch (e) {
-  fail(e.message);
+  fail(e instanceof Error ? e.message : String(e));
 }
 if (args.out) fs.writeFileSync(args.out, css); else process.stdout.write(css);
 const log = args.out ? console.log : console.error;