@tensor_1/react 2.63.0 → 2.65.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (41) hide show
  1. package/README.md +18 -1
  2. package/component-inventory.json +8 -0
  3. package/dist/components/AuditLog.d.ts +1 -0
  4. package/dist/components/Card.d.ts +1 -1
  5. package/dist/components/Card.js +2 -2
  6. package/dist/components/EditorialHome.d.ts +1 -1
  7. package/dist/components/EditorialHome.js +2 -2
  8. package/dist/components/Field.d.ts +18 -3
  9. package/dist/components/Field.js +6 -6
  10. package/dist/components/InfoTip.d.ts +9 -3
  11. package/dist/components/InfoTip.js +6 -2
  12. package/dist/components/LinkTile.d.ts +28 -0
  13. package/dist/components/LinkTile.js +38 -0
  14. package/dist/components/Markdown.d.ts +12 -2
  15. package/dist/components/Markdown.js +3 -2
  16. package/dist/components/NumberInput.d.ts +28 -0
  17. package/dist/components/NumberInput.js +27 -0
  18. package/dist/components/PageHeader.d.ts +1 -1
  19. package/dist/components/PageHeader.js +2 -2
  20. package/dist/components/StatusPill.d.ts +11 -1
  21. package/dist/components/StatusPill.js +7 -2
  22. package/dist/components/Timeline.d.ts +14 -2
  23. package/dist/components/Timeline.js +6 -1
  24. package/dist/index.cjs +3415 -3325
  25. package/dist/index.d.cts +123 -12
  26. package/dist/index.d.ts +3 -1
  27. package/dist/index.js +6 -1
  28. package/dist/info-tip-model.d.ts +12 -1
  29. package/dist/info-tip-model.js +10 -2
  30. package/dist/labels-context.d.ts +10 -0
  31. package/dist/markdown.cjs +3 -2
  32. package/dist/markdown.d.cts +12 -2
  33. package/dist/rich-text.cjs +3 -2
  34. package/dist/usage-roles.d.ts +14 -1
  35. package/dist/usage-roles.js +11 -0
  36. package/package.json +9 -3
  37. package/page-rules/README.md +74 -0
  38. package/page-rules/cli.mjs +5 -0
  39. package/page-rules/index.mjs +158 -0
  40. package/page-rules/rules.mjs +669 -0
  41. package/page-rules/scan.mjs +281 -0
@@ -0,0 +1,74 @@
1
+ # UIx page rules
2
+
3
+ `uix-page-rules` checks how a product's pages use UIx. UIx's own tests hold the kit-level rules (control edges at 3:1, the 24 px hit area, the calm palette, the motion tokens), so every product gets those by installing the kit. A page can still misuse the kit, and these rules catch that. They come from the TENSOR UI council climbs (HAR-2954) and the page audit (HAR-3101), and workspace `Docs/lessons/12` and `13` explain each one.
4
+
5
+ The tool ships inside `@tensor_1/react`, so a product already has it and the rules match the kit version it renders. It has no dependencies and reads files only.
6
+
7
+ ## Rules
8
+
9
+ | Rule | What it stops | Inline ignore |
10
+ |---|---|---|
11
+ | `severity-through-status-tone` | A severity coloured through a generic tone helper (`statusTone('severity', …)`), or a hand map that sends "high" to a red tone. Use `severityTone()`. | yes |
12
+ | `label-break-anywhere` | `break-all`, `overflow-wrap: anywhere`, `wrap-anywhere`, `wordBreak: 'break-all'`, `overflowWrap: 'anywhere'`. Code in `font-mono`, `<code>` or `<pre>` is exempt. | yes |
13
+ | `heading-said-twice` | The `PageHeader` title said again as a heading, `title` or table `caption`. | yes |
14
+ | `row-menu-unnamed` | A row's ⋯ menu (`Menu`, `ActionMenu`) whose `label` and trigger `aria-label` do not name the row. | yes |
15
+ | `list-joined-in-cell` | A row's list joined with `", "` in a table cell. Use `ListSummary` or `OverflowRow`. | yes |
16
+ | `no-raw-button` | A raw `<button>`. The one allowed case is an invisible submitter (`type="submit" hidden aria-hidden`). | no |
17
+ | `no-raw-table` | A raw `<table>`. Use `DataWorkspace`, or `Table` in `TableWrap` for a matrix. | no |
18
+ | `no-raw-form-control` | A raw `<input>`, `<select>` or `<textarea>`. `<input type="hidden">` is allowed. | no |
19
+ | `no-arbitrary-font-size` | A literal font size, such as `text-[13px]` or `fontSize: 12`. Use the `--uix-text-*` tokens. | no |
20
+
21
+ `.css` files are checked against `label-break-anywhere` only. `.ts`, `.js` and `.mjs` files are checked against that rule and the severity rule. `.tsx` and `.jsx` files are checked against every rule. These are not read: tests and stories (`*.test.*`, `*.spec.*`, `*.stories.*`), `.d.ts` files, and anything under `__tests__`, `__mocks__` or `__fixtures__`.
22
+
23
+ Comments are never findings. That covers a trailing `// …`, a `{/* … */}` in JSX and a CSS block comment. The severity rules also match code that a formatter wrapped over several lines. Regex literals and URLs in JSX text are skipped whole, so neither can hide a tag.
24
+
25
+ One known limit: two apostrophes on one line of raw JSX text read as a string, and a tag between them is not seen. Products that translate every string have no raw JSX text.
26
+
27
+ The kit-control rules (`no-raw-*`, `no-arbitrary-font-size`) accept no inline ignore. If the kit cannot serve a case, build the missing piece in UIx first (workspace ADR-0038). For a structural exception, such as a printed document, add an `exempt` entry with its reason.
28
+
29
+ One rule is held back: `no-hand-built-pill` (`rounded-full` plus horizontal padding). It misses a class split by a template interpolation (HAR-3817), so it waits for that fix.
30
+
31
+ ## Adopting it in a product
32
+
33
+ 1. Pin `@tensor_1/react` at a version that ships the tool: 2.65.0 or later.
34
+ 2. Add `uix-page-rules.config.json` at the product root:
35
+
36
+ ```json
37
+ {
38
+ "roots": ["src"],
39
+ "baseline": "uix-page-rules-baseline.json"
40
+ }
41
+ ```
42
+
43
+ Optional keys:
44
+
45
+ - `skip`: files or directories not to scan, each with its reason. A prefix matches on a path-segment boundary, so `src/legacy` never covers `src/legacy-new/`.
46
+ - `exempt`: `{ "<rule>": { "<file>": "<reason>" } }`.
47
+ - `genericToneHelpers`: default `["statusTone"]`.
48
+ - `pageTitleComponents`: default `["PageHeader"]`.
49
+ - `rowMenuComponents`: default `["Menu", "ActionMenu"]`.
50
+
51
+ An unknown key is an error, so a typo can't switch a rule off.
52
+ 3. Seed the baseline once, on purpose, and commit it: `npx uix-page-rules baseline --seed`.
53
+ 4. Add a script, `"lint:uix-page-rules": "uix-page-rules"`, and run it as a required CI step.
54
+
55
+ ## What fails
56
+
57
+ `uix-page-rules` (same as `uix-page-rules check`) exits:
58
+
59
+ - **0** when nothing is new;
60
+ - **1** on any of these:
61
+ - a finding the baseline does not grandfather, in a new file or as one more in a grandfathered file;
62
+ - a baseline entry the tree no longer reaches (`stale-baseline`);
63
+ - a `skip` prefix or an `exempt` entry that matches nothing (`stale-exemption`);
64
+ - **2** when the run cannot judge the tree:
65
+ - the config is missing or invalid;
66
+ - the baseline is unreadable;
67
+ - the roots hold no source files;
68
+ - anything else goes wrong, such as an unreadable directory.
69
+
70
+ `baseline` writes nothing while the config has a stale `skip` or `exempt` entry. `--seed` can replace an unreadable baseline.
71
+
72
+ The baseline counts findings per rule, per file, and it only shrinks. After you fix a finding, run `npx uix-page-rules baseline` and commit the smaller file. That command refuses to write a baseline that grows. `--seed` writes it anyway, for the first baseline or a reviewed re-seed after files move. The PR diff then shows the growth.
73
+
74
+ `uix-page-rules rules` lists every rule and its fix, and `--json` prints the result for other tools. `import { scanSource, run } from '@tensor_1/react/page-rules'` gives the same functions to a product's own lint runner.
@@ -0,0 +1,5 @@
1
+ #!/usr/bin/env node
2
+ // `uix-page-rules` — the UIx page rules as a product gate (HAR-3874). See README.md.
3
+ import { run } from './index.mjs';
4
+
5
+ process.exitCode = run(process.argv.slice(2));
@@ -0,0 +1,158 @@
1
+ // UIx page rules (HAR-3874): `import { run, scanSource } from '@tensor_1/react/page-rules'`.
2
+ // The CLI is `uix-page-rules` (./cli.mjs); README.md has the product setup.
3
+
4
+ import { writeFileSync } from 'node:fs';
5
+ import { join, resolve } from 'node:path';
6
+ import { COUNTED_RULES, RULES } from './rules.mjs';
7
+ import {
8
+ baselineDocument,
9
+ CONFIG_FILE,
10
+ ConfigError,
11
+ evaluate,
12
+ growth,
13
+ loadBaseline,
14
+ loadConfig,
15
+ scanProject,
16
+ } from './scan.mjs';
17
+
18
+ export * from './rules.mjs';
19
+ export * from './scan.mjs';
20
+
21
+ const USAGE = `Usage: uix-page-rules [check | baseline [--seed] | rules] [--config <file>] [--root <dir>] [--json]
22
+
23
+ check (default) fail on any finding the baseline does not grandfather, and on
24
+ baseline or config entries the tree no longer needs
25
+ baseline rewrite the baseline from the tree; refuses to grow it (--seed writes it
26
+ anyway: the first baseline, or a reviewed re-seed after moving files)
27
+ rules list the rules and how to fix each
28
+
29
+ Exit codes: 0 clean, 1 violations or a refused baseline, 2 usage or config error.`;
30
+
31
+ function parseArgs(argv) {
32
+ const args = { command: 'check', config: CONFIG_FILE, root: '.', json: false, seed: false };
33
+ const rest = [...argv];
34
+ if (rest[0] && !rest[0].startsWith('-')) args.command = rest.shift();
35
+ while (rest.length) {
36
+ const a = rest.shift();
37
+ if (a === '--json') args.json = true;
38
+ else if (a === '--seed') args.seed = true;
39
+ else if (a === '--config' && rest.length) args.config = rest.shift();
40
+ else if (a === '--root' && rest.length) args.root = rest.shift();
41
+ else if (a === '--help' || a === '-h') args.command = 'help';
42
+ else throw new ConfigError(`unknown argument "${a}"`);
43
+ }
44
+ if (!['check', 'baseline', 'rules', 'help'].includes(args.command)) throw new ConfigError(`unknown command "${args.command}"`);
45
+ if (args.seed && args.command !== 'baseline') throw new ConfigError('--seed only applies to `baseline`');
46
+ return args;
47
+ }
48
+
49
+ const grandfathered = (counts, baseline) => {
50
+ let n = 0;
51
+ for (const rule of COUNTED_RULES) {
52
+ for (const [file, have] of Object.entries(counts[rule] ?? {})) n += Math.min(have, baseline.rules[rule]?.[file] ?? 0);
53
+ }
54
+ return n;
55
+ };
56
+
57
+ function report(violations, out) {
58
+ for (const v of violations) {
59
+ out(` ${v.file}:${v.line} ${v.rule} ${v.msg}`);
60
+ if (v.text) out(` ${v.text}`);
61
+ }
62
+ const rules = [...new Set(violations.map((v) => v.rule))];
63
+ out('');
64
+ out('How to fix:');
65
+ for (const rule of rules) out(` ${rule}: ${RULES[rule].fix} (workspace ${RULES[rule].lesson})`);
66
+ const ignorable = rules.filter((r) => RULES[r]?.ignorable);
67
+ if (ignorable.length) {
68
+ out(` A real exception to ${ignorable.join(', ')} takes an inline \`// uix-page-rules-ignore <rule>: <reason>\` on the line or the line above. The kit-control rules take none: a case the kit cannot serve is built in UIx first.`);
69
+ }
70
+ }
71
+
72
+ /**
73
+ * Run the CLI. Returns the exit code; writes through `io`.
74
+ * @param {string[]} argv
75
+ * @param {{ cwd?: string, stdout?: (s: string) => void, stderr?: (s: string) => void }} [io]
76
+ */
77
+ export function run(argv, io = {}) {
78
+ const out = io.stdout ?? ((s) => process.stdout.write(`${s}\n`));
79
+ const err = io.stderr ?? ((s) => process.stderr.write(`${s}\n`));
80
+ let args;
81
+ try {
82
+ args = parseArgs(argv);
83
+ } catch (error) {
84
+ err(`uix-page-rules: ${error.message}\n\n${USAGE}`);
85
+ return 2;
86
+ }
87
+ if (args.command === 'help') {
88
+ out(USAGE);
89
+ return 0;
90
+ }
91
+ if (args.command === 'rules') {
92
+ for (const rule of COUNTED_RULES) out(`${rule}${RULES[rule].ignorable ? '' : ' (no inline ignore)'}\n ${RULES[rule].fix}\n workspace ${RULES[rule].lesson}`);
93
+ out('\nHeld back: no-hand-built-pill (a class split by a template interpolation escapes it, HAR-3817).');
94
+ return 0;
95
+ }
96
+
97
+ const root = resolve(io.cwd ?? process.cwd(), args.root);
98
+ try {
99
+ const config = loadConfig(root, args.config);
100
+ // A reseed may replace an unreadable baseline; every other command needs it intact.
101
+ const seeding = args.command === 'baseline' && args.seed;
102
+ let baseline;
103
+ try {
104
+ baseline = loadBaseline(root, config);
105
+ } catch (error) {
106
+ if (!(seeding && error instanceof ConfigError)) throw error;
107
+ baseline = { exists: false, rules: {} };
108
+ }
109
+ const scan = scanProject(root, config);
110
+ if (scan.filesScanned === 0) {
111
+ err(`uix-page-rules: no source files under ${config.roots.join(', ')}; a gate that reads nothing proves nothing.`);
112
+ return 2;
113
+ }
114
+
115
+ if (args.command === 'baseline') {
116
+ if (scan.problems.length) {
117
+ err('uix-page-rules: fix the config first; the baseline was not written:');
118
+ report(scan.problems, err);
119
+ return 1;
120
+ }
121
+ const grown = baseline.exists ? growth(scan.counts, baseline) : [];
122
+ if (!args.seed && !baseline.exists && scan.findings.length) {
123
+ err(`uix-page-rules: ${config.baseline} does not exist. Seed it on purpose: uix-page-rules baseline --seed`);
124
+ return 1;
125
+ }
126
+ if (!args.seed && grown.length) {
127
+ err(`uix-page-rules: refusing to grow ${config.baseline}: ${grown.length} file(s) gained findings. Fix them instead:\n ${grown.join('\n ')}`);
128
+ return 1;
129
+ }
130
+ const doc = baselineDocument(scan.counts);
131
+ writeFileSync(join(root, config.baseline), `${JSON.stringify(doc, null, 2)}\n`);
132
+ out(`uix-page-rules: wrote ${config.baseline} (${doc.total} grandfathered finding(s) in ${scan.filesScanned} scanned files)`);
133
+ return 0;
134
+ }
135
+
136
+ const violations = evaluate(scan, baseline);
137
+ const kept = grandfathered(scan.counts, baseline);
138
+ if (args.json) {
139
+ out(JSON.stringify({ ok: violations.length === 0, filesScanned: scan.filesScanned, grandfathered: kept, violations }, null, 2));
140
+ return violations.length ? 1 : 0;
141
+ }
142
+ if (!violations.length) {
143
+ out(`✓ uix-page-rules: no new violations (${scan.filesScanned} file(s) scanned, ${kept} finding(s) grandfathered in ${config.baseline})`);
144
+ return 0;
145
+ }
146
+ err(`✗ uix-page-rules: ${violations.length} violation(s) (${scan.filesScanned} file(s) scanned, ${kept} finding(s) grandfathered in ${config.baseline})`);
147
+ report(violations, err);
148
+ return 1;
149
+ } catch (error) {
150
+ if (error instanceof ConfigError) {
151
+ err(`uix-page-rules: ${error.message}`);
152
+ return 2;
153
+ }
154
+ // An unreadable directory or any other surprise is a broken run, never a verdict.
155
+ err(`uix-page-rules: internal error, nothing was checked: ${error?.stack ?? error}`);
156
+ return 2;
157
+ }
158
+ }