@assembly-js/app-foundation 0.7.3 → 0.8.0

package/CHANGELOG.md

@@ -19,6 +19,11 @@ A patch release never changes what an app's build requires; a minor release may
 not by hand; see `changes/README.md`. CI fails a PR that changes a check script without a
 `bump: minor` change file.
 
+## 0.8.0
+- [new] `useUrlState('id')` from `@assembly-js/app-foundation/client` keeps a record selection in the URL search string, so a record panel is deep-linkable without its own route.
+- [new] `bun run build` runs `check:record-urls`, which fails when a record panel is opened from React state alone, with neither the helper nor a dynamic route. It only runs on apps that carry the inner-location skill.
+- [guidance] `assembly-app-inner-location` says selection state lives in the URL and a record opened from a list must load cold from its URL.
+
 ## 0.7.3
 - [guidance] The build agent's auth guide is now its own section in `CLAUDE.md` instead of sitting under "Design system", and the rule for choosing between `getAssembly()` and `getInstallerAssembly()` is stated once in `assembly-route-auth` rather than repeated in the notifications, automations and internal-users skills.
 

package/bin/check-record-urls.mjs

@@ -0,0 +1,128 @@
+#!/usr/bin/env node
+// Fails the build when a record opened from a list (a Dialog, Sheet, Drawer or
+// detail panel) is driven by React state alone: the host URL never changes, so a
+// reload or a shared link lands on the list instead of the record. The fix is
+// either `useUrlState('id')` from `@assembly-js/app-foundation/client` or a
+// dynamic route for the record on the internal surface. The match is a
+// heuristic on a `selected*`-style `useState` that feeds a panel-like element.
+// Dependency free on purpose: it runs inside the generated app's sandbox before
+// any deps beyond Node are guaranteed.
+//
+// Inert unless the inner-location skill was written into the app: that skill ships
+// only when the deep-link flag is on, while the layout mounts <LocationReporter />
+// in every build, so the reporter alone cannot tell an off-flag app apart.
+// On a platform update turn (ASSEMBLY_UPDATE_TURN=1) it only warns, because an
+// update never rewrites how an app navigates.
+import { readFileSync, readdirSync, existsSync } from 'node:fs';
+import { join, relative, sep } from 'node:path';
+
+const ROOT = process.cwd();
+const UPDATE_TURN = process.env.ASSEMBLY_UPDATE_TURN === '1';
+const APP_DIR = join(ROOT, 'app');
+const MANIFEST = join(ROOT, '.assembly', 'app.json');
+const INNER_LOCATION_SKILL = join(ROOT, '.claude', 'skills', 'assembly-app-inner-location', 'SKILL.md');
+const SOURCE_FILE = /\.(tsx|jsx)$/;
+const PAGE_FILE = /^page\.(tsx|ts|jsx|js)$/;
+
+// `const [selectedRequest, setSelectedRequest] = useState(...)`; the setter name is not trusted.
+const USE_STATE = /const\s+\[\s*([A-Za-z_$][\w$]*)\s*,\s*[A-Za-z_$][\w$]*\s*\]\s*=\s*useState\b/g;
+const RECORD_SELECTION = /^(?:selected|active|viewing|viewed|current|detail|open(?:ed)?)[A-Z_]/;
+// Selection of something that is not a record, or that is genuinely transient.
+const NOT_A_RECORD = /(?:Tab|Filter|Status|Sort|View|Option|Date|Range|Column|Mode|Step|Page|Menu)s?$|^(?:confirm|delete|remove|menu|pending)/i;
+const PANEL_ELEMENT = /<\w*(?:Dialog|Sheet|Drawer|Panel|Modal|Detail)\w*[\s>/]/;
+const OPT_OUT = /record-urls:\s*transient/;
+
+function sourceFiles(dir) {
+  const out = [];
+  if (!existsSync(dir)) return out;
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (entry.name === 'node_modules' || entry.name === '.next') continue;
+      out.push(...sourceFiles(full));
+    } else if (/\.(tsx|ts|jsx|js|mjs)$/.test(entry.name)) {
+      out.push(full);
+    }
+  }
+  return out;
+}
+
+// Prefixes of the client and notification surfaces; a dynamic route there does
+// not give the internal dashboard a record URL.
+function nonInternalPrefixes() {
+  const prefixes = new Set(['/c', '/n']);
+  try {
+    const manifest = JSON.parse(readFileSync(MANIFEST, 'utf8'));
+    for (const key of ['client', 'notification']) {
+      const p = manifest?.surfaces?.[key]?.path;
+      if (typeof p === 'string' && p.startsWith('/') && p !== '/') prefixes.add(p.replace(/\/+$/, ''));
+    }
+  } catch {
+    // defaults
+  }
+  return prefixes;
+}
+
+function routeForPageFile(file) {
+  const segments = relative(APP_DIR, file).split(sep).slice(0, -1);
+  const urlSegments = segments.filter(
+    (seg) => !(seg.startsWith('(') && seg.endsWith(')')) && !seg.startsWith('@'),
+  );
+  return '/' + urlSegments.join('/');
+}
+
+if (!existsSync(APP_DIR)) process.exit(0);
+
+const files = [...sourceFiles(APP_DIR), ...sourceFiles(join(ROOT, 'components'))];
+const contents = new Map(files.map((f) => [f, readFileSync(f, 'utf8')]));
+
+if (!existsSync(INNER_LOCATION_SKILL)) process.exit(0);
+
+const prefixes = nonInternalPrefixes();
+const hasInternalRecordRoute = files.some((f) => {
+  if (!PAGE_FILE.test(f.split(sep).pop())) return false;
+  const route = routeForPageFile(f);
+  if (!route.includes('[')) return false;
+  return ![...prefixes].some((p) => route === p || route.startsWith(`${p}/`));
+});
+if (hasInternalRecordRoute) process.exit(0);
+
+function escapeRe(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+const violations = [];
+for (const file of files) {
+  if (!SOURCE_FILE.test(file)) continue;
+  const src = contents.get(file);
+  if (/\buseUrlState\b/.test(src) || OPT_OUT.test(src) || !PANEL_ELEMENT.test(src)) continue;
+  for (const match of src.matchAll(USE_STATE)) {
+    const name = match[1];
+    if (!RECORD_SELECTION.test(name) || NOT_A_RECORD.test(name)) continue;
+    // Declared and read somewhere else in the file, i.e. it feeds the panel.
+    const uses = src.match(new RegExp(`(?<![\\w$.])${escapeRe(name)}(?![\\w$])`, 'g')) ?? [];
+    if (uses.length < 3) continue;
+    violations.push(`${relative(ROOT, file).split(sep).join('/')}  (useState: ${name})`);
+  }
+}
+
+if (violations.length > 0 && UPDATE_TURN) {
+  console.warn('');
+  console.warn('check-record-urls: record selection held in React state (this update turn is not failed for it):');
+  for (const v of violations) console.warn('  - ' + v);
+  console.warn('');
+} else if (violations.length > 0) {
+  console.error('');
+  console.error('Record selection lives only in React state — the URL never changes when a record opens:');
+  console.error('');
+  for (const v of violations) console.error('  - ' + v);
+  console.error('');
+  console.error('A reload or a shared link lands on the list, not on the record. Fix one of:');
+  console.error("  - Replace the useState with `const [id, setId] = useUrlState('id')` from");
+  console.error("    '@assembly-js/app-foundation/client' and render the record from `id`;");
+  console.error('    a cold load with ?id= must open it, and Back must close it.');
+  console.error('  - Give the record its own route (app/requests/[id]/page.tsx) and link to it.');
+  console.error('A genuinely transient UI (confirm dialog, menu) can add the comment');
+  console.error('`// record-urls: transient` to the file.');
+  process.exit(1);
+}

package/bin/foundation-exports.mjs

@@ -57,5 +57,5 @@ export const NON_CLIENT_EXPORTS = new Set([
   'redactUrl', 'replaceChildRows', 'requireAuth', 'requireCompanyScope', 'resolveFont',
   'resolveResource', 'sendThrottled', 'serializeBearerCookie', 'serializeBearerExpiryCookie', 'serializeCookieProbe',
   'setCookielessBearer', 'slackErrorCode', 'slackFindChannelId', 'slackListChannels',
-  'slackPostMessage', 'slackResolveMentions', 'snippetFromRequestBody', 'verifyBearer',
+  'slackPostMessage', 'slackResolveMentions', 'snippetFromRequestBody', 'useUrlState', 'verifyBearer',
 ]);

package/dist/client.d.ts

@@ -8,3 +8,4 @@ export * from './pagination.js';
 export * from './theme.js';
 export * from './resource-resolution.js';
 export { LocationReporter } from './location-reporter.js';
+export { useUrlState } from './url-state.js';

package/dist/client.js

@@ -25,3 +25,5 @@ export * from './theme.js';
 export * from './resource-resolution.js';
 // Browser-safe: the reporter pulls in no Node built-ins, unlike ./next.
 export { LocationReporter } from './location-reporter.js';
+// Keeps a record selection in the search string so the reporter mirrors it to the host URL.
+export { useUrlState } from './url-state.js';

package/dist/url-state.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The query string with `key` set to `value` (or removed when null), as a
+ * `?`-prefixed string or '' when nothing is left. Other params, including the
+ * host's embed-session ones, are carried through untouched.
+ */
+export declare function withSearchParam(search: URLSearchParams, key: string, value: string | null): string;
+export type SetUrlState = (value: string | null, opts?: {
+    replace?: boolean;
+}) => void;
+/**
+ * State that lives in the page's search string (`?id=abc`) instead of React
+ * state. The location reporter already mirrors the search string into the host
+ * URL, so a record panel driven by this hook is deep-linkable without its own
+ * route: a cold load with `?id=` reopens it and Back closes it.
+ *
+ * Plain Next navigation, so it behaves the same with no bridge present. The
+ * component must render under a Suspense boundary, as for any `useSearchParams`.
+ */
+export declare function useUrlState(key: string): [string | null, SetUrlState];

package/dist/url-state.js

@@ -0,0 +1,41 @@
+'use client';
+import { useCallback } from 'react';
+import { usePathname, useRouter, useSearchParams } from 'next/navigation';
+/**
+ * The query string with `key` set to `value` (or removed when null), as a
+ * `?`-prefixed string or '' when nothing is left. Other params, including the
+ * host's embed-session ones, are carried through untouched.
+ */
+export function withSearchParam(search, key, value) {
+    const next = new URLSearchParams(search);
+    if (value === null || value === '')
+        next.delete(key);
+    else
+        next.set(key, value);
+    const qs = next.toString();
+    return qs ? `?${qs}` : '';
+}
+/**
+ * State that lives in the page's search string (`?id=abc`) instead of React
+ * state. The location reporter already mirrors the search string into the host
+ * URL, so a record panel driven by this hook is deep-linkable without its own
+ * route: a cold load with `?id=` reopens it and Back closes it.
+ *
+ * Plain Next navigation, so it behaves the same with no bridge present. The
+ * component must render under a Suspense boundary, as for any `useSearchParams`.
+ */
+export function useUrlState(key) {
+    const pathname = usePathname();
+    const router = useRouter();
+    const searchParams = useSearchParams();
+    const value = searchParams.get(key);
+    const setValue = useCallback((next, opts) => {
+        const url = pathname + withSearchParam(new URLSearchParams(searchParams.toString()), key, next);
+        // Push by default so Back undoes the selection.
+        if (opts?.replace)
+            router.replace(url, { scroll: false });
+        else
+            router.push(url, { scroll: false });
+    }, [pathname, router, searchParams, key]);
+    return [value, setValue];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@assembly-js/app-foundation",
-  "version": "0.7.3",
+  "version": "0.8.0",
   "description": "Versioned foundation helpers and build context for Assembly generated apps",
   "type": "module",
   "files": [

package/skills/assembly-app-inner-location/SKILL.md

@@ -11,6 +11,10 @@ The host mirrors the app's inner page in its own address bar and can open the ap
 - Mount `<LocationReporter />` once, in `app/layout.tsx`, imported from `@assembly-js/app-foundation/client`. If it is already there, leave it.
 - Never write custom `location.report` or `location.onNavigate` code, and never hand-write a `LocationSync` component. The reporter already handles surface prefixes and route changes.
 
+## Records get a URL
+
+Keep which record is open in the URL, not in `useState`: `const [id, setId] = useUrlState('id')` from `@assembly-js/app-foundation/client` for a panel, Sheet or Dialog, or a route like `app/requests/[id]/page.tsx`. A record opened from a list must load cold from its URL and Back must close it. `bun run build` fails `check:record-urls` for a `selectedId`-style `useState` feeding a record panel; use the helper or a route to fix it.
+
 ## Notifications deep-link to the record, not the app root
 
 When the app sends an email or in-product notification about a specific record (a document request, a submission), the destination is set by the notification's `ctaParams` and surface, not by `linkTo`. Pass `ctaParams` that identify the record (`ctaParams: { requestId: request.id }`) and render that record from an existing inner route of this app, one that works when opened cold. Follow `assembly-notifications` for the send-and-open pattern.