@the-portland-company/shell 0.86.0 → 0.88.0

package/CHANGELOG.md

@@ -1,3 +1,29 @@
+## 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.
+
+## 0.87.0
+
+The top-bar search works in Relationship Mode. Spec cited: Reference/UI-Platform "Top bar — required elements" (Relationship search returns the Account's Contacts only) and Data-System/UVP §7.1 (a result opens the Contact Card).
+
+- **Why.** Reported by Ben 2026-10-18: clicking the search box in Contacts did nothing. The frame passed only a placeholder, so `NavTopBar` drew a read-only input in every app.
+- **Relationship Mode.** The box takes typing; Enter opens Contacts → All Contacts filtered to the query: `?mode=relationship&page=contacts&tab=contacts&section=table&org_id=<tail>&q=<query>`. Same origin from inside Contacts, the `-staging` twin from a staging host. No app wiring and no new prop (an app never passes chrome configuration).
+- **Campaign and Petition.** Unchanged: decorative until their search is built (Campaign voter lookup is Campaign-Voter-Record §3).
+- **New export** `relationshipSearchHref(query, { orgId, fromApp, hostname })`.
+- **Needs** Contacts to read `q` into its table search (politogy-contacts, same day).
+- Tests: `__tests__/relationshipSearch.test.ts`, `__tests__/topbarSearch.test.tsx`.
+
 ## 0.86.0
 
 Campaign Mode gets a Tribes row. Spec cited: Specs/Tribes §2.3–§2.4 and Specs/Left-Navigation §9.2 (decided 2026-10-16 by Ben: Campaign and Relationship Tribes are separate; Campaign Tribes live in Campaign Mode).

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 }

package/dist/app-chrome.cjs

@@ -4549,6 +4549,67 @@ function LoadingScreen({
     }
   );
 }
+
+// src/url-state.ts
+var URL_STATE_MODES = ["relationship", "campaign", "petition"];
+var URL_STATE_KEYS = ["mode", "page", "tab", "section", "org_id"];
+var SLUG_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+function isUrlStateMode(v) {
+  return typeof v === "string" && URL_STATE_MODES.includes(v);
+}
+function searchOf(input) {
+  if (input instanceof URLSearchParams) return new URLSearchParams(input);
+  return new URLSearchParams();
+}
+var slugOrNull = (v) => v && SLUG_RE.test(v) ? v : null;
+function shortOrgId(v) {
+  if (!v) return null;
+  const tail = orgIdTail(v);
+  if (tail) return tail;
+  const t = String(v).trim().toLowerCase();
+  return /^[0-9a-f]{6,7}$/.test(t) ? t : null;
+}
+function readUrlState(input) {
+  const params = searchOf(input);
+  const mode = params.get("mode");
+  const orgRaw = params.get("org_id");
+  const feature = new URLSearchParams();
+  for (const [k, v] of params) if (!URL_STATE_KEYS.includes(k)) feature.append(k, v);
+  return {
+    mode: isUrlStateMode(mode) ? mode : null,
+    page: slugOrNull(params.get("page")),
+    tab: slugOrNull(params.get("tab")),
+    section: slugOrNull(params.get("section")),
+    org_id: shortOrgId(orgRaw),
+    feature
+  };
+}
+function buildSearch(state) {
+  const out = new URLSearchParams();
+  for (const key of URL_STATE_KEYS) {
+    const v = state[key];
+    if (v) out.set(key, v);
+  }
+  for (const [k, v] of state.feature) out.append(k, v);
+  const s = out.toString();
+  return s ? `?${s}` : "";
+}
+function writeUrlState(current, patch) {
+  const state = readUrlState(current);
+  if (patch.mode !== void 0) state.mode = patch.mode;
+  if (patch.page !== void 0) state.page = patch.page;
+  if (patch.tab !== void 0) state.tab = patch.tab;
+  if (patch.section !== void 0) state.section = patch.section;
+  if (patch.org_id !== void 0) state.org_id = shortOrgId(patch.org_id);
+  if (patch.feature) {
+    for (const [k, v] of Object.entries(patch.feature)) {
+      if (URL_STATE_KEYS.includes(k)) continue;
+      if (v === null) state.feature.delete(k);
+      else state.feature.set(k, v);
+    }
+  }
+  return buildSearch(state);
+}
 function parseCssUrl(value) {
   if (!value) return null;
   const m = /^url\(\s*(['"]?)(.*?)\1\s*\)$/i.exec(value.trim());
@@ -4686,6 +4747,22 @@ var MODE_SEARCH_PLACEHOLDER = {
   campaign: "Search voters, walk lists, polls",
   petition: "Search petitions, sheets, circulators"
 };
+function relationshipSearchHref(query, opts = {}) {
+  const q = query.trim();
+  if (!q) return null;
+  const search = writeUrlState("", {
+    mode: "relationship",
+    page: "contacts",
+    tab: "contacts",
+    section: "table",
+    org_id: opts.orgId ?? null,
+    feature: { q }
+  });
+  if (opts.fromApp === "contacts") return `/${search}`;
+  const staging = (opts.hostname ?? "").toLowerCase().includes("staging");
+  const origin = staging ? "https://contacts-staging.politogyvrm.com" : POLITOGY_APPS.contacts.origin;
+  return `${origin}/${search}`;
+}
 function PolitogyAppFrame({
   app,
   pathname,
@@ -4847,6 +4924,8 @@ function FrameBody({
   }, [cookieMode]);
   const coreOrgs = chrome?.orgs ?? [];
   const activeCoreOrg = coreOrgs.find((o) => o.id === chrome?.orgId) ?? null;
+  const searchMode = appMode ?? mode.id ?? "relationship";
+  const [searchText, setSearchText] = react.useState("");
   const navDisplay = chrome?.navDisplay ?? "both";
   const navMode = appMode ?? (app !== CORE_APP && isStandardNavMode(mode.id) ? mode.id : "relationship");
   const activeOrgId = chrome?.orgId ?? null;
@@ -4959,11 +5038,25 @@ function FrameBody({
           userMenu,
           onSignOut: handleSignOut,
           // Reference/UI-Platform "Top bar — required elements": Universal
-          // search is the only thing on the left end of the bar. No app wires
-          // search yet, so this stays decorative (`NavTopBarProps.search` — "an
-          // app that has not wired search yet still gets the correct chrome").
+          // search is the only thing on the left end of the bar. In
+          // Relationship Mode it searches the Account's Contacts: Enter opens
+          // Contacts → All Contacts filtered to the query, from every app, with
+          // no app wiring (an app never passes chrome configuration). Campaign
+          // and Petition search are not built yet and stay decorative.
           search: {
-            placeholder: data?.searchPlaceholder ?? MODE_SEARCH_PLACEHOLDER[appMode ?? mode.id ?? "relationship"] ?? "Search"
+            placeholder: data?.searchPlaceholder ?? MODE_SEARCH_PLACEHOLDER[searchMode] ?? "Search",
+            ...searchMode === "relationship" ? {
+              value: searchText,
+              onChange: setSearchText,
+              onSubmit: (value) => {
+                const href = relationshipSearchHref(value, {
+                  orgId: activeCoreOrg?.id ?? session.accountId ?? null,
+                  fromApp: app,
+                  hostname: typeof window === "undefined" ? "" : window.location.hostname
+                });
+                if (href) window.location.assign(href);
+              }
+            } : {}
           },
           // No Build notes control (Reference/UI-Platform, decided 2026-10-03).
           // The action cluster is IDENTICAL everywhere — core included. Page
@@ -5692,6 +5785,7 @@ exports.footerLinks = footerLinks;
 exports.looksLikeEmail = looksLikeEmail;
 exports.modeLandingHref = modeLandingHref;
 exports.orgSwitchLanding = orgSwitchLanding;
+exports.relationshipSearchHref = relationshipSearchHref;
 exports.resolveIdentity = resolveIdentity;
 exports.standardNavIcons = standardNavIcons;
 exports.useChromeFooter = useChromeFooter;