@the-portland-company/shell 0.87.1 → 0.88.0

package/CHANGELOG.md

@@ -1,3 +1,14 @@
+## 0.88.0
+
+Shared form primitives, so apps stop hand-rolling them.
+
+- **New exports** `Button`, `Input`, `Select`, `Textarea` (plus `ButtonProps`, `ButtonVariant`, `ButtonSize`, `InputProps`, `SelectProps`, `TextareaProps`).
+- **Button.** Variants `primary | secondary | ghost | danger`; sizes `md` (44px) and `sm` (36px); `loading` and `disabled`; `href` / `as` link-buttons; forwards its ref. Primary uses the `--app-btn-primary-*` tokens (Specs buttonPrimary).
+- **Input, Select, Textarea.** `label`, `helperText`, `error`, `invalid`; 44px control height for Input and Select; forward their refs; `--app-field-*` tokens.
+- **Rule.** Apps use these instead of a local Button / Input / Select / Textarea (README "Form primitives").
+- **Native subpath.** `Button`, `Input`, `Select`, `Textarea`, `Card`, `PageHeader`, `FormColumn`, `BreadcrumbBar`, `HeaderTabBar` (and their types) are also exported from `@the-portland-company/shell/native`, which has no Chakra or react-router peer. The native `PageHeader` and `BreadcrumbBar` render breadcrumb links as plain anchors. The main entry is unchanged.
+- Tests: `__tests__/formPrimitives.test.tsx`.
+
 ## 0.87.1
 
 Release fix only; same code as 0.87.0, which never reached npm. The 0.87.0 version bump regenerated `package-lock.json` with a newer npm that dropped two optional `yaml@2.9.1` entries, so the publish gate's `npm ci` refused it. The lock file is restored from 0.86.0 with only its version changed.

package/README.md

@@ -171,6 +171,52 @@ All `<ShellChrome>` props are optional — only supply what your app has. The ch
 
 ---
 
+## Form primitives
+
+Shared `Button`, `Input`, `Select` and `Textarea`, styled from the shell's tokens (`--app-btn-*`, `--app-field-*`, `--color-*`). 5px radius, 12px horizontal padding.
+
+| Export | Props |
+|---|---|
+| `<Button>` | `variant`: `primary` (default) \| `secondary` \| `ghost` \| `danger`; `size`: `md` (44px, default) \| `sm` (36px); `loading` (spinner, `aria-busy`, blocks clicks); `disabled`; `href` or `as` for a link-button (e.g. `as={Link} to="/x"`); `type` defaults to `button`; forwards its ref. |
+| `<Input>` | All native input props plus `label`, `helperText`, `error`, `invalid`, `wrapperClassName`. 44px tall. Forwards its ref to the `<input>`. |
+| `<Select>` | Same as `Input`, with `<option>` children. 44px tall. Forwards its ref to the `<select>`. |
+| `<Textarea>` | Same as `Input`, 88px minimum height. Forwards its ref to the `<textarea>`. |
+
+An `error` message marks the control invalid (`aria-invalid`, red border) and replaces the helper text; the label, helper and error are wired with `htmlFor` and `aria-describedby`.
+
+These primitives (and `Card`, `PageHeader`, `FormColumn`) are also exported from `@the-portland-company/shell/native`, which needs no Chakra or react-router peer. Apps without those peers should import from `native`.
+
+**Rule:** apps must use these instead of a local `Button`, `Input`, `Select` or `Textarea`. Do not hand-roll form controls or button styles in an app; if a control needs a new variant or state, add it here so every app gets it.
+
+## Enforcement
+
+Spec: Components — shared primitives are mandatory. Apps must not hand-roll Button/Card/Input/Select/Textarea, and must not fall behind the shell version. Both are checked mechanically.
+
+Adopt in three lines:
+
+```js
+// eslint.config.js (ESLint 9+ flat config)
+import shell from '@the-portland-company/shell/eslint'
+export default [...shell.configs.recommended /* , your other configs */]
+```
+
+```json
+// package.json
+{ "scripts": { "lint": "eslint . && shell-version-check" } }
+```
+
+Run `shell-version-check` in CI too (it is a package `bin`, so `npx shell-version-check` works after install).
+
+| Rule (`politogy-shell/…`) | Fails on |
+|---|---|
+| `no-local-primitives` | Declaring or exporting a local `Button`, `Card`, `Input`, `Select`, `Textarea`, `PageHeader` or `FormColumn` (re-exports from the shell are fine). |
+| `no-raw-control-styling` | JSX `<button>`, `<input>`, `<select>`, `<textarea>` with `className` or `style`. Allowed in a file that imports the shell primitive of the same kind (wrapping). |
+| `no-global-control-classes` | `className` strings matching `\b(btn\|input)(-[a-z]+)?\b`, including inside `clsx(...)`, ternaries and template literals. |
+
+Escape hatch: put `// shell-primitive-exempt: <reason>` on the line above (or the same line as) the offending code. A reason is required. Prefer adding the missing variant to the shell instead.
+
+`shell-version-check` exits 1 when the app's declared shell range cannot install the latest published version (`npm view`, 10s timeout; exit 2 if that lookup fails). `--offline` compares against the installed shell version instead; `--cwd=<dir>` checks another package. The shell package itself does not enable these rules.
+
 ## CSS imports
 
 ```tsx

package/bin/shell-version-check.mjs

@@ -0,0 +1,117 @@
+#!/usr/bin/env node
+// Fails when the app's declared @the-portland-company/shell range cannot
+// satisfy the latest published minor (or, with --offline, the installed one).
+// Exit: 0 ok, 1 behind, 2 could not determine.
+import { readFileSync, existsSync, realpathSync } from 'node:fs'
+import { execFileSync } from 'node:child_process'
+import { resolve, join } from 'node:path'
+import { pathToFileURL } from 'node:url'
+
+export const PKG = '@the-portland-company/shell'
+
+const V = /^v?(\d+)\.(\d+)\.(\d+)/
+export function parseVersion(s) {
+  const m = V.exec(String(s).trim())
+  return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null
+}
+const cmp = (a, b) => a[0] - b[0] || a[1] - b[1] || a[2] - b[2]
+
+// One comparator token -> predicate list. Supports ^ ~ >= > <= < = x-ranges and *.
+function comparator(tok) {
+  tok = tok.trim()
+  if (tok === '' || tok === '*' || tok === 'x' || tok === 'latest') return [() => true]
+  const m = /^(\^|~|>=|<=|>|<|=)?\s*v?(\d+|x|\*)(?:\.(\d+|x|\*))?(?:\.(\d+|x|\*))?(?:-[\w.]+)?$/.exec(tok)
+  if (!m) throw new Error(`Unsupported range "${tok}"`)
+  const op = m[1] || ''
+  const wild = (x) => x === undefined || x === 'x' || x === '*'
+  const p = [m[2], m[3], m[4]].map((x) => (wild(x) ? null : Number(x)))
+  const lo = [p[0] ?? 0, p[1] ?? 0, p[2] ?? 0]
+  const ge = (v) => cmp(v, lo) >= 0
+  if (p[0] === null) return [() => true]
+  if (op === '>=') return [ge]
+  if (op === '>') return [(v) => (p[1] === null ? v[0] > p[0] : p[2] === null ? v[0] > p[0] || (v[0] === p[0] && v[1] > p[1]) : cmp(v, lo) > 0)]
+  if (op === '<') return [(v) => cmp(v, lo) < 0]
+  if (op === '<=') return [(v) => (p[1] === null ? v[0] <= p[0] : p[2] === null ? v[0] < p[0] || (v[0] === p[0] && v[1] <= p[1]) : cmp(v, lo) <= 0)]
+  let upper
+  if (op === '^') {
+    upper = p[0] > 0 || p[1] === null ? [p[0] + 1, 0, 0] : p[1] > 0 || p[2] === null ? [0, p[1] + 1, 0] : [0, 0, p[2] + 1]
+  } else if (op === '~') {
+    upper = p[1] === null ? [p[0] + 1, 0, 0] : [p[0], p[1] + 1, 0]
+  } else {
+    // exact or x-range
+    upper = p[1] === null ? [p[0] + 1, 0, 0] : p[2] === null ? [p[0], p[1] + 1, 0] : [p[0], p[1], p[2] + 1]
+  }
+  return [ge, (v) => cmp(v, upper) < 0]
+}
+
+export function satisfies(version, range) {
+  const v = parseVersion(version)
+  if (!v) throw new Error(`Bad version "${version}"`)
+  const r = String(range).trim()
+  if (/^(npm:|file:|link:|git|https?:|workspace:)/.test(r)) throw new Error(`Cannot evaluate range "${r}"`)
+  return r.split('||').some((set) => {
+    const toks = set.trim().replace(/(>=|<=|>|<|=|\^|~)\s+/g, '$1').split(/\s+/)
+    return toks.every((t) => comparator(t).every((f) => f(v)))
+  })
+}
+
+export function declaredRange(pkgJson) {
+  for (const k of ['dependencies', 'devDependencies', 'peerDependencies', 'optionalDependencies']) {
+    if (pkgJson[k] && pkgJson[k][PKG]) return pkgJson[k][PKG]
+  }
+  return null
+}
+
+/** Pure decision: returns { ok, message }. */
+export function evaluate({ range, target, source }) {
+  if (satisfies(target, range)) {
+    return { ok: true, message: `ok: ${PKG} "${range}" accepts ${source} ${target}.` }
+  }
+  const [maj, min] = parseVersion(target)
+  return {
+    ok: false,
+    message:
+      `FAIL: ${PKG} is declared as "${range}", which cannot install ${source} ${target}.\n` +
+      `Upgrade: npm install ${PKG}@^${maj}.${min}.0 (apps must not fall behind the shell).`,
+  }
+}
+
+function main(argv) {
+  const offline = argv.includes('--offline')
+  const cwdArg = argv.find((a) => a.startsWith('--cwd='))
+  const cwd = resolve(cwdArg ? cwdArg.slice(6) : process.cwd())
+  const pj = join(cwd, 'package.json')
+  if (!existsSync(pj)) {
+    console.error(`shell-version-check: no package.json in ${cwd}`)
+    return 2
+  }
+  const range = declaredRange(JSON.parse(readFileSync(pj, 'utf8')))
+  if (!range) {
+    console.error(`shell-version-check: ${PKG} is not a dependency of this package.`)
+    return 2
+  }
+  let target, source
+  try {
+    if (offline) {
+      const ip = join(cwd, 'node_modules', ...PKG.split('/'), 'package.json')
+      if (!existsSync(ip)) throw new Error(`${PKG} is not installed (run npm install)`)
+      target = JSON.parse(readFileSync(ip, 'utf8')).version
+      source = 'installed'
+    } else {
+      const out = execFileSync('npm', ['view', PKG, 'version'], { encoding: 'utf8', timeout: 10_000, stdio: ['ignore', 'pipe', 'pipe'] })
+      target = out.trim()
+      source = 'latest published'
+    }
+    const res = evaluate({ range, target, source })
+    ;(res.ok ? console.log : console.error)(res.message)
+    return res.ok ? 0 : 1
+  } catch (e) {
+    console.error(`shell-version-check: could not determine version (${e.message.split('\n')[0]}). Use --offline to compare against the installed shell.`)
+    return 2
+  }
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href) {
+  process.exit(main(process.argv.slice(2)))
+}
+export { main }