@terreno/mcp 57.19.2 → 57.20.0

package/dist/docs/versioned/next/how-to/build-list-detail-screens.md

@@ -0,0 +1,160 @@
+# Build a list/detail screen
+
+Put the list and its detail route in one route group, and make `ListDetailLayout` the group's
+layout. On a phone the list pushes the detail. On a tablet or a wide browser the list stays in a
+left pane and the detail opens beside it. The URL always names the open item.
+
+```text
+app/mail/
+  _layout.tsx   ListDetailLayout
+  index.tsx     ListDetailIndex
+  [id].tsx      the detail screen
+```
+
+```tsx
+// app/mail/_layout.tsx
+import {ListDetailLayout, Text} from "@terreno/ui";
+import type React from "react";
+
+import {MailList} from "@/components/MailList";
+
+// A deep link to /mail/3 on a phone still has the list to go back to.
+export const unstable_settings = {initialRouteName: "index"};
+
+const MailLayout: React.FC = () => (
+  <ListDetailLayout
+    detailHref={(id) => `/mail/${id}`}
+    emptyDetail={<Text>Select a message</Text>}
+    indexHref="/mail"
+    list={<MailList />}
+    screenOptions={{title: "Inbox"}}
+  />
+);
+export default MailLayout;
+```
+
+```tsx
+// app/mail/index.tsx
+import {ListDetailIndex} from "@terreno/ui";
+import type React from "react";
+
+const MailIndex: React.FC = () => <ListDetailIndex />;
+export default MailIndex;
+```
+
+```tsx
+// app/mail/[id].tsx
+import {Page, Text} from "@terreno/ui";
+import {useLocalSearchParams} from "expo-router";
+import type React from "react";
+
+const MailMessage: React.FC = () => {
+  const {id} = useLocalSearchParams<{id: string}>();
+  return (
+    <Page>
+      <Text>Message {id}</Text>
+    </Page>
+  );
+};
+export default MailMessage;
+```
+
+## Select rows from the list
+
+Read the open item and open others with `useListDetail()`. Mark the open row as selected so
+screen readers announce it. On web a clickable `Box` row sends this as `aria-current="true"`.
+
+```tsx
+import {Box, Text, useListDetail} from "@terreno/ui";
+import type React from "react";
+
+export const MailRow: React.FC<{id: string; subject: string}> = ({id, subject}) => {
+  const {select, selectedId} = useListDetail();
+  const isSelected = id === selectedId;
+  return (
+    <Box
+      accessibilityHint="Opens the message"
+      accessibilityLabel={subject}
+      accessibilityState={{selected: isSelected}}
+      color={isSelected ? "primary" : "base"}
+      onClick={() => select(id)}
+      padding={3}
+      testID={`mail-row-${id}`}
+    >
+      <Text color={isSelected ? "inverted" : "primary"}>{subject}</Text>
+    </Box>
+  );
+};
+```
+
+| Call | Stacked (phone) | Split (tablet, wide web) |
+| --- | --- | --- |
+| `select(id)`, nothing open | Pushes `detailHref(id)` | Pushes `detailHref(id)` |
+| `select(id)`, another item open | Pushes `detailHref(id)` | Replaces the open detail |
+| `select(selectedId)` | Pushes again | Does nothing |
+| `clear()` | `router.dismissTo(indexHref)`: pops back to the list inside this group | Same |
+| `clear()`, nothing open | Does nothing | Does nothing |
+
+Because split mode replaces the open detail, the stack is never deeper than the list plus one
+detail, so back returns to the list after a rotation too. When split, the header's back button
+(`list-detail-leave`) leaves the whole group instead, since the list is already on screen.
+
+When another screen opens a detail directly, push it with `withAnchor` so the list sits below it
+and back lands on the list instead of leaving the group:
+
+```tsx
+router.push("/mail/3", {withAnchor: true});
+<Link href="/mail/3" withAnchor>Open message</Link>
+```
+
+`selectedId` is the `paramName` param (default `id`) of the route directly below `indexHref`
+whose segment is `detailRoute` (default `[id]`). An `id` from a parent dynamic segment, such as
+`/orgs/[id]/mail`, never counts.
+
+## Publish the detail URL
+
+A static web export (`web.output: "static"`) writes an HTML file only for paths
+`generateStaticParams` returns. Without it, opening `/mail/3` directly is a 404 on a host that
+does not rewrite unknown paths.
+
+```tsx
+// app/mail/[id].tsx
+export const generateStaticParams = (): {id: string}[] =>
+  messages.map((message) => ({id: message.id}));
+```
+
+Ids that are not known at build time need the host fallback from
+[Build for web](build-for-web.md): Netlify `_redirects` with `/* /index.html 200`, or the Vercel
+rewrite in [Deploy to Vercel](deploy-to-vercel.md). The demo inbox exports one page per fixture
+message at `/demo/list-detail/:id` and `/demo/sidebar-navigation/mail/:id`. The Netlify demo
+deploy also writes that fallback, so an id outside the fixtures still opens the missing-message
+screen.
+
+## Keep list state across the breakpoint
+
+The open item survives a rotation or a browser resize. The `list` element does not: it moves
+between the index screen and the left pane, so it remounts. Keep filters, search text, and other
+list state in the route (`router.setParams`) or a store.
+
+## Nest it inside a sidebar
+
+`ListDetailLayout` measures its own width, so it splits correctly inside `SidebarNavigation` or
+an admin rail. Make the group a screen of the sidebar navigator:
+
+```text
+app/workspace/
+  _layout.tsx         SidebarNavigation with <SidebarNavigation.Screen name="mail" />
+  mail/_layout.tsx    ListDetailLayout with indexHref="/workspace/mail"
+  mail/index.tsx
+  mail/[id].tsx
+```
+
+## Choose SplitPage instead
+
+Use `SplitPage` when the list and detail do not have their own routes, such as a picker inside a
+modal. `SplitPage` keeps the selection in component state, so it has no URL, deep links, or back
+navigation for the open item.
+
+## Reference
+
+Props, defaults, and testIDs: [`ListDetailLayout`](../reference/ui.md#listdetaillayout).

package/dist/docs/versioned/next/how-to/circleci.md

@@ -106,7 +106,9 @@ when the package imports them. Coverage-script unit tests run in the cheap
 Playwright runs five shards after `e2e-prepare` (`auth`, `app`, `admin-core`,
 `admin-table`, `syncdb`) instead of one container per spec file. Each shard
 first checks the [affected gate](#e2e-affected-gate) and halts when no changed
-file can reach it. Repository
+file can reach it. The cross-site bearer specs run beside them in `e2e-cross-site`,
+which builds its own web bundle and backend (`playwright.config.ts` with
+`E2E_CROSS_SITE_BEARER=true`), has no affected gate, and is not a required check. Repository
 policy checks share one `repo-policies` job so eight small checkouts do not
 sit in the concurrency queue. `repo-policies` uses Node 22.14 because Knip's
 oxc-parser throws `ERR_REQUIRE_ESM` on the shared 22.11 executor.
@@ -316,6 +318,7 @@ the same commands through the parameterized `packages-ci` job, gated by
 | Admin SPA Build and E2E | `admin-spa-ci` |
 | Lint, compile, and coverage (matrix package) | `packages-ci` (`admin-backend`, `admin-frontend`, `api-health`, `feature-flags`, `test`) |
 | E2E · `<shard>` | `e2e` (matrix `shard`: `auth`, `app`, `admin-core`, `admin-table`, `syncdb`) |
+| _(cross-site bearer specs, not required)_ | `e2e-cross-site` (after `e2e-prepare`; also the explicit-linking pass) |
 | E2E Load · syncdb-loadlab | `e2e-load` (trigger-gated, see below) |
 | Admin SPA Backend Integration E2E | `admin-spa-integration` |
 | _(e2e compile+export once)_ | `e2e-prepare` |
@@ -368,10 +371,17 @@ To teach the agent from what reviewers actually say, run
 <file>` of pasted comments): it opens one PR editing `docs/approval-rubric.md` and the
 path rules from the review comments since the last pass.
 
-Rollout: `approveLevels` is `[]`, so every PR gets a `COMMENT` review that says the
-risk level and why, and nothing approves. After a dozen PRs, compare the levels with
-how humans reviewed them, tune the path rules and rubric, then set
-`"approveLevels": ["low"]` in a one-line PR. The prompts and answers behind each
+Levels and human approvals (defined in `docs/approval-rubric.md`):
+
+| Level | Human approvals | Examples |
+| --- | --- | --- |
+| low | None once automated review and security checks are green | docs, copy, internal-only features, additive changes behind a flag |
+| medium | One person | ordinary product changes, and sensitive areas such as caching, app updates, and AI system prompts |
+| high | One person | security-related code: auth, permissions, secrets, crypto, PHI handling |
+
+`approveLevels` is `["low"]`, so the App's approval satisfies master's one-review rule
+for low PRs. Medium and high PRs get a `COMMENT` review that says the risk level and
+why, and a human approves. The prompts and answers behind each
 verdict are stored as the `brewery-approve` job artifact. Full reference:
 [brewery `docs/approve.md`](https://github.com/joshgachnang/brewery/blob/master/docs/approve.md).