@tristan2828/ui-foundation 3.22.0 → 3.24.0

package/conventions/docs/add-an-entity.md

@@ -241,6 +241,13 @@ is a filled-in example while the Widgets demo is still here).
      section that holds one long text or one sub-record list is a block
      (`content`) with no label of its own, since a label would only repeat
      the heading.
+   - **Layout.** With the plan's `Layout: rail`, pass `layout="rail"` and
+     give each section its Placement (`placement: 'rail'`; `main` is the
+     default and needs nothing). Without a `Layout` line, drop `layout`
+     and every `placement` from the copied view (one column). Widget's
+     view is `rail`, with Details in the rail. The rail's sections come
+     first in the page (header, rail, main) at every width, so the
+     view's specs find them first too.
    - **Every value renders the way its table cell does**: badges, names
      of linked records, a done-count, from the shared lookups in
      `<entity>-format.ts`. Never re-derive one for the view.
@@ -431,7 +438,11 @@ is a filled-in example while the Widgets demo is still here).
    a heading, a list, a table, a link and raw HTML, and asserts the HTML
    shows as text. Add the view's spec to `playwright.config.ts`'s
    `mobile-chrome` `testMatch`, with a test that at phone width each
-   label sits above its value and nothing scrolls sideways.
+   label sits above its value and nothing scrolls sideways. With
+   `Layout: rail`, that test also checks the rail's sections come before
+   the main ones, and another that on a wide screen the main column
+   starts beside the rail (copy `wide screens: …` in
+   `e2e/widget-view.spec.ts`).
    States forced via a first-load init script (loading, load-time error)
    need `page.addInitScript` before navigation; states forced after the
    page is already up (a mutation's error response) can use a

package/conventions/docs/cell-patterns.md

@@ -10,14 +10,14 @@ alternatives ([`column-options.md`](column-options.md)), not designed in the abs
 Patterns 12 (boolean), 15 (yes/no flipped in the row), 16 (title linking
 to its view), 17 (quick action on the view) and 18 (editable value) are
 the template's own references: Widget's In Stock and Name columns and its
-view render them, and their specs pin them. Pattern 19 (stage circle)
-and the multi-value variant of 4, the dependency list in 10 and the
-pressed icon in 15 were each built for a real app's screen first; the
-package's Storybook renders them (`app/StageCircle`,
-`patterns/CellPatterns`), and its checks pin their accessibility and
-contrast in both themes. The other patterns from 11 on are
-marked **Unproven**: written ahead of a real
-column, so no app has tested them on real data yet. Prefer a proven
+view render them, and their specs pin them. Patterns 19 (stage circle)
+and 20 (count linking to the related records), the multi-value variant
+of 4, the dependency list in 10 and the pressed icon in 15 were each
+built for a real app's screen first; the package's Storybook renders
+them (`app/StageCircle`, `app/CountLink`, `patterns/CellPatterns`), and
+its checks pin their accessibility and contrast in both themes. The
+other patterns from 11 on are marked **Unproven**: written ahead of a
+real column, so no app has tested them on real data yet. Prefer a proven
 pattern when one fits. When you use an unproven one, say so in the
 entity's plan, and raise what you learned for the foundation, so the
 entry can lose its label. A pattern that proves generic is worth raising
@@ -836,3 +836,69 @@ cell: ({ getValue }) => {
   `<EditableValue>` like a badge.
 - **Cost:** a reader learns the shapes once. Until then the word does the
   work, which is why it stays.
+
+## 20. Count linking to the related records
+
+A count of the records in another table that point at this row (open
+Tasks per Project, items per Tag), which opens that table already filtered
+to them. The count is a `computed` integer (the entity plan's type).
+The package ships it: `CountLink`, rendered in its Storybook
+(`app/CountLink`).
+
+```tsx
+import { CountLink } from '@tristan2828/ui-foundation'
+
+cell: ({ row }) => {
+  const { id, name, openTaskCount: count } = row.original
+  return (
+    <CountLink
+      count={count}
+      to={`/tasks?project=${id}`}
+      label={`open ${count === 1 ? 'task' : 'tasks'} in ${name}`}
+    />
+  )
+}
+```
+
+What the component decides, so a cell doesn't have to:
+
+- **Underlined at rest**, not only on hover as in pattern 16. A title
+  reads as a name to open; a bare number doesn't look like it goes
+  anywhere until it's underlined. Hover thickens the line. Foreground,
+  not `text-link`: `--link` is for links in written text, and a column of
+  blue numbers pulls the eye from every other column.
+- **Zero is a plain `0`**, not a link (a link to an empty list is a dead
+  end) and not an em dash: zero is a value (pattern 11). Same
+  `tabular-nums`, so it lines up with the links.
+- **The accessible name is the count, then `label`**: `3 open tasks in
+  Kitchen remodel`. Every row's link text is just a number, so `3` alone
+  isn't distinct, and starting with it keeps the link findable by what
+  it shows (speech input, `getByRole('link', { name: /^3 / })`).
+
+What the cell decides:
+
+- **`label` says what's counted and which row**, singular for one
+  (`open task in Garden`).
+- **The target is the other entity's list, filtered by the URL**:
+  `/<other>?<filterName>=<id>`, the same query string `useTableUrlState`
+  reads (a multi-value filter takes the id the same way). Back, forward,
+  a refresh and saved views keep working, and the other list needs a
+  filter by this reference (`Filter: yes` in its plan).
+- **The count and the list it opens must agree.** If the target list
+  narrows by default (hides finished records unless asked), the count
+  applies the same condition, and the word in the name says so (`open`
+  tasks). Where the list has a filter for that condition, prefer putting
+  it in the link too (`?project=7&status=open`), so the list shows what
+  was counted even if its default changes. Say the rule in the field's
+  `description` in `openapi.yaml` (`Tasks in this project that aren't
+  done; what /tasks?project=<id> lists`), so the backend, the mocks and
+  the next agent count the same thing.
+- **Sorted on the server, as a number**, like any computed field: the
+  scalar subquery is the sort expression, with a stable tiebreak (the
+  name, then the id) so rows with the same count don't change places
+  between pages.
+- **Cost:** one correlated subquery per row read. Fine at an app's scale;
+  give the other table's foreign key column an index, since every row's
+  count reads it.
+- **On the record's view**, the same `CountLink` beside its label (`Open
+  tasks: 3`), with the record's name in `label` like the table's.

package/conventions/docs/design-language.md

@@ -194,6 +194,10 @@ shade: note `info`, tip `success`, important category slot 2, warning
 `warning`, caution `destructive`. The package draws all of it; an app
 only renders `<Markdown>` or the editor.
 
+`--link` is for written text only. A link in a table cell is
+`text-foreground` and underlined, never blue: a column of coloured text
+pulls the eye from every other column (cell patterns 16 and 20).
+
 ## Density
 
 Tables have three densities, set with `data-density` on **any ancestor**

package/conventions/docs/entity-plan-template.md

@@ -43,7 +43,8 @@ One or two sentences: what one record is, and who uses the screens.
     every read and never stores it — give its rule, and if it's a choice,
     its values in sort order with a label for each; a read-only column, a filter and a sort the
     server evaluates, never on the form). A count of related records is a
-    `computed` integer.
+    `computed` integer; say whether its column links to those records
+    (cell pattern 20) and which of them it counts (`open tasks`).
   - *Close variants* (built by a small, stated change to the nearest
     pattern): `integer` (from decimal), `url` (from email — a format
     check), `date` (from date-time — no time part).
@@ -122,15 +123,27 @@ except the quick actions, if any.
   linked from the table: `title`.
 - Badges beside the title: a few status-like fields, as badges: `status`,
   `priority`.
+- Layout (optional; delete for one column): `rail` for a record with long
+  content (notes written as Markdown, long lists). The page takes the
+  screen's whole width, the short sections (a summary, label/value fields,
+  a few links) sit in a narrow column on the right that stays in view, and
+  the long ones fill the main column beside it. On a phone: one column,
+  the rail's sections first. Without this line, every section is in one
+  column, as wide as a long read.
+
+  Layout: rail
+
 - Sections, in order. Each lists its fields in the order they show. A
   section holding a single long text or a single sub-records list shows
-  it under the section's heading, with no label of its own.
-
-| Section | Fields |
-|---|---|
-| Details | dueDate, project, tags |
-| Checklist | checklist |
-| Notes | notes |
+  it under the section's heading, with no label of its own. With
+  `Layout: rail`, Placement says which column each goes in (`rail` or
+  `main`); otherwise delete the column.
+
+| Section | Fields | Placement |
+|---|---|---|
+| Details | dueDate, project, tags | rail |
+| Checklist | checklist | main |
+| Notes | notes | main |
 
 - "Not set" labels: what an empty optional field reads as on the view
   (`dueDate`: No due date; `checklist`: No items). A field not listed here

package/dist/components/app/count-link.d.ts

@@ -0,0 +1,14 @@
+import { type To } from 'react-router';
+export interface CountLinkProps {
+    /** How many related records there are. Count what `to` lists. */
+    count: number;
+    /** The other entity's list, filtered to this row: `/tasks?project=7`. */
+    to: To;
+    /**
+     * What's counted and for which row, read after the count: `open tasks in
+     * Kitchen remodel` (`open task` for one).
+     */
+    label: string;
+    className?: string;
+}
+export declare function CountLink({ count, to, label, className }: CountLinkProps): import("react").JSX.Element;

package/dist/components/app/count-link.js

@@ -0,0 +1,20 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+// A count linking to the related records (cell pattern 20): how many
+// records of another entity point at this row, as a link to that entity's
+// list filtered to them (`/tasks?project=7`, the query string
+// useTableUrlState reads).
+//
+// - Underlined at rest: a bare number doesn't look like it goes anywhere.
+//   Foreground, not text-link: --link is for written text.
+// - Zero is a plain 0, not a link (a list of nothing is a dead end) and
+//   not an em dash (zero is a value).
+// - The accessible name is the count, then `label`, so every row's link is
+//   distinct ("3 open tasks in Kitchen remodel") and still starts with
+//   what it shows.
+import { Link } from 'react-router';
+import { cn } from 'cn';
+export function CountLink({ count, to, label, className }) {
+    if (count === 0)
+        return _jsx("span", { className: cn('tabular-nums', className), children: "0" });
+    return (_jsx(Link, { to: to, "aria-label": `${count} ${label}`, className: cn('rounded-sm tabular-nums text-foreground underline underline-offset-4 outline-none', 'hover:decoration-2 focus-visible:ring-3 focus-visible:ring-ring/50', className), children: count }));
+}

package/dist/components/app/entity-view.d.ts

@@ -21,7 +21,7 @@ export type EntityViewField = {
  * only repeat the heading. A block that's empty shows `emptyLabel`, the
  * same rule as a field.
  */
-export type EntityViewSection = {
+export type EntityViewSection = ({
     /** The section's heading (an <h2>). Unique on the page. */
     title: string;
     fields: EntityViewField[];
@@ -31,7 +31,21 @@ export type EntityViewSection = {
     emptyLabel?: string;
     /** The block is editable in place (long text), named by the section's title. */
     edit?: EditInPlace;
+}) & {
+    /**
+     * Where the section goes in the `rail` layout: `rail` for the short ones
+     * (a summary, label/value fields, a few links), `main` (the default) for
+     * long text and long lists. The `column` layout ignores it.
+     */
+    placement?: EntityViewPlacement;
 };
+export type EntityViewPlacement = 'main' | 'rail';
+/**
+ * `column` (the default): one column, at most max-w-4xl wide. `rail`: the
+ * content area's whole width, with the sections placed `rail` in a narrow
+ * column on the right (one column on a narrow screen, rail first).
+ */
+export type EntityViewLayout = 'column' | 'rail';
 export type EntityViewProps = {
     /** The record's name or title, the page's <h1>. */
     title?: string;
@@ -48,6 +62,10 @@ export type EntityViewProps = {
     /** The header's actions: an Edit button, a Delete with its confirm dialog. */
     actions?: ReactNode;
     sections: EntityViewSection[];
+    /** `rail` puts the sections placed `rail` in a column on the right. Defaults to `column`. */
+    layout?: EntityViewLayout;
+    /** The rail's landmark name (its `<aside>`). Defaults to the title + " details". */
+    railLabel?: string;
     isLoading: boolean;
     /** A `notfound` error (including another user's record) shows "Not found" and a way back, never a retry. */
     error?: AppError | null;
@@ -58,4 +76,4 @@ export type EntityViewProps = {
         label: string;
     };
 };
-export declare function EntityView({ title, titleEdit, badges, actions, sections, isLoading, error, onRetry, back, }: EntityViewProps): import("react").JSX.Element;
+export declare function EntityView({ title, titleEdit, badges, actions, sections, layout, railLabel, isLoading, error, onRetry, back, }: EntityViewProps): import("react").JSX.Element;

package/dist/components/app/entity-view.js

@@ -1,4 +1,4 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 // Generic read-only view of one record, the read-side partner of
 // EntityForm: the record's title with a few status badges beside it, an
 // actions area (Edit, Delete), and sections of label/value rows laid out to
@@ -24,9 +24,18 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 // time, the leave-page prompt); EditableValue is each value's side, and a
 // header badge uses it directly. A field not marked renders exactly as
 // before. Edit, in `actions`, stays for everything else.
-import { useId, useState, useSyncExternalStore } from 'react';
+//
+// Two layouts. `column` (the default): every section in one column capped
+// at max-w-4xl. `rail`, for a record with long content: the page takes the
+// content area's whole width, sections placed `rail` go in a narrow column
+// on the right that stays in view while the main column scrolls (an issue
+// tracker's shape), and the rest fill the main column. Below the width two
+// columns need, one column: header, rail, main. The DOM is in that order at
+// every width, so reading and tab order match the screen.
+import { useEffect, useId, useState, useSyncExternalStore } from 'react';
 import { Link } from 'react-router';
 import { ArrowLeftIcon, SearchXIcon } from 'lucide-react';
+import { cn } from 'cn';
 import { ErrorState } from './error-state.js';
 import { Button } from '../ui/button.js';
 import { Card, CardContent, CardHeader } from '../ui/card.js';
@@ -50,18 +59,79 @@ function orEmptyLabel(value, emptyLabel) {
     return isEmptyValue(value) ? (_jsx("span", { className: "text-muted-foreground", children: emptyLabel ?? DEFAULT_EMPTY_LABEL })) : (value);
 }
 // Label beside value from `sm` up; below it (a phone) the label sits
-// above its value, so nothing is squeezed into a narrow second column.
-function FieldRow({ field }) {
-    return (_jsxs("div", { className: "flex flex-col gap-1 py-3 first:pt-0 last:pb-0 sm:grid sm:grid-cols-[minmax(8rem,12rem)_1fr] sm:gap-6", children: [_jsx("dt", { className: "type-label text-muted-foreground", children: field.label }), _jsx("dd", { className: "min-w-0 type-body break-words text-foreground", children: field.edit ? (_jsx(EditableValue, { label: field.label, edit: field.edit, children: orEmptyLabel(field.value, field.emptyLabel) })) : (orEmptyLabel(field.value, field.emptyLabel)) })] }));
+// above its value, so nothing is squeezed into a narrow second column. In
+// the rail the list's own width decides instead (a container query on the
+// <dl>): label above value in the narrow rail, beside it once the rail's
+// sections stack full width under the header.
+const FIELD_ROW = {
+    page: 'sm:grid sm:grid-cols-[minmax(8rem,12rem)_1fr] sm:gap-6',
+    rail: '@lg/fields:grid @lg/fields:grid-cols-[minmax(8rem,12rem)_1fr] @lg/fields:gap-6',
+};
+function FieldRow({ field, inRail }) {
+    return (_jsxs("div", { className: cn('flex flex-col gap-1 py-3 first:pt-0 last:pb-0', FIELD_ROW[inRail ? 'rail' : 'page']), children: [_jsx("dt", { className: "type-label text-muted-foreground", children: field.label }), _jsx("dd", { className: "min-w-0 type-body break-words text-foreground", children: field.edit ? (_jsx(EditableValue, { label: field.label, edit: field.edit, children: orEmptyLabel(field.value, field.emptyLabel) })) : (orEmptyLabel(field.value, field.emptyLabel)) })] }));
 }
-function ViewSection({ section }) {
+function ViewSection({ section, inRail = false }) {
     const headingId = useId();
-    return (_jsx("section", { "aria-labelledby": headingId, children: _jsxs(Card, { children: [_jsx(CardHeader, { children: _jsx("h2", { id: headingId, className: "type-section-title text-foreground", children: section.title }) }), _jsx(CardContent, { children: 'fields' in section ? (_jsx("dl", { className: "flex flex-col divide-y divide-border", children: section.fields.map((field) => (_jsx(FieldRow, { field: field }, field.label))) })) : (_jsx("div", { className: "min-w-0 type-body break-words text-foreground", children: section.edit ? (_jsx(EditableValue, { label: section.title, edit: section.edit, children: orEmptyLabel(section.content, section.emptyLabel) })) : (orEmptyLabel(section.content, section.emptyLabel)) })) })] }) }));
+    return (_jsx("section", { "aria-labelledby": headingId, children: _jsxs(Card, { children: [_jsx(CardHeader, { children: _jsx("h2", { id: headingId, className: "type-section-title text-foreground", children: section.title }) }), _jsx(CardContent, { children: 'fields' in section ? (_jsx("dl", { className: cn('flex flex-col divide-y divide-border', inRail && '@container/fields'), children: section.fields.map((field) => (_jsx(FieldRow, { field: field, inRail: inRail }, field.label))) })) : (_jsx("div", { className: "min-w-0 type-body break-words text-foreground", children: section.edit ? (_jsx(EditableValue, { label: section.title, edit: section.edit, children: orEmptyLabel(section.content, section.emptyLabel) })) : (orEmptyLabel(section.content, section.emptyLabel)) })) })] }) }));
+}
+// The rail layout's columns. The view is a container, so the switch to
+// two columns follows the width the page actually has (the sidebar open
+// or not), not the window's: two from 56rem (896px), where the main
+// column still gets ~32rem beside a 22rem rail. Below that, one column in
+// DOM order (header, rail, main); from it, the grid puts the rail on the
+// right of row 1 and main on its left, both starting under the header.
+const RAIL_LAYOUT = {
+    page: '@container/view flex min-w-0 flex-col gap-6',
+    columns: 'flex flex-col gap-6 @4xl/view:grid @4xl/view:grid-cols-[minmax(0,1fr)_22rem] @4xl/view:items-start',
+    rail: '@4xl/view:col-start-2 @4xl/view:row-start-1',
+    main: 'flex min-w-0 flex-col gap-6 @4xl/view:col-start-1 @4xl/view:row-start-1',
+    // Main alone (no rail sections): the whole row.
+    mainAlone: '@4xl/view:col-span-2',
+    // Sticky only beside main, and only while the whole rail fits on screen
+    // (`data-fits`, measured): a taller one scrolls with the page, so its end
+    // is never stuck below the fold.
+    sticky: '@4xl/view:data-[fits]:sticky @4xl/view:data-[fits]:top-6',
+};
+function SkeletonCard({ rows, stacked }) {
+    return (_jsxs(Card, { children: [_jsx(CardHeader, { children: _jsx(Skeleton, { className: "h-5 w-32" }) }), _jsx(CardContent, { className: "flex flex-col gap-4", children: Array.from({ length: rows }, (_, row) => (_jsxs("div", { className: cn('flex flex-col gap-1', !stacked && 'sm:flex-row sm:gap-6'), children: [_jsx(Skeleton, { className: "h-5 w-32" }), _jsx(Skeleton, { className: cn('h-5', stacked ? 'w-full' : 'flex-1') })] }, row))) })] }));
+}
+// The page's shape before the record arrives, in the layout it will have,
+// so nothing jumps when it loads.
+function EntityViewSkeleton({ layout }) {
+    const header = (_jsxs(_Fragment, { children: [_jsx(Skeleton, { className: "h-5 w-24" }), _jsxs("div", { className: "flex flex-col gap-2", children: [_jsx(Skeleton, { className: "h-7 w-64 max-w-full" }), _jsx(Skeleton, { className: "h-5 w-40" })] })] }));
+    if (layout === 'rail') {
+        return (_jsxs("div", { className: RAIL_LAYOUT.page, "data-state": "loading", "data-layout": "rail", children: [header, _jsxs("div", { className: RAIL_LAYOUT.columns, children: [_jsx("div", { className: cn(RAIL_LAYOUT.rail, 'flex flex-col gap-6'), children: _jsx(SkeletonCard, { rows: 4, stacked: true }) }), _jsx("div", { className: RAIL_LAYOUT.main, children: _jsx(SkeletonCard, { rows: 6, stacked: false }) })] })] }));
+    }
+    return (_jsxs("div", { className: "flex max-w-4xl flex-col gap-6", "data-state": "loading", children: [header, Array.from({ length: 2 }, (_, section) => (_jsx(SkeletonCard, { rows: 4, stacked: false }, section)))] }));
+}
+// The rail's top offset (top-6) plus as much again below it.
+const RAIL_MARGIN_PX = 48;
+// Whether `element` fits in the window with room around it, re-measured
+// whenever it or the window changes size (a field opening in place, a
+// rotated phone).
+function useFitsWindow() {
+    const [element, setElement] = useState(null);
+    const [fits, setFits] = useState(false);
+    useEffect(() => {
+        if (!element)
+            return;
+        const measure = () => setFits(element.offsetHeight + RAIL_MARGIN_PX <= window.innerHeight);
+        // A ResizeObserver reports once as soon as it observes: the first measure.
+        const observer = new ResizeObserver(measure);
+        observer.observe(element);
+        window.addEventListener('resize', measure);
+        return () => {
+            observer.disconnect();
+            window.removeEventListener('resize', measure);
+        };
+    }, [element]);
+    return [setElement, fits];
 }
-function EntityViewSkeleton() {
-    return (_jsxs("div", { className: "flex max-w-4xl flex-col gap-6", "data-state": "loading", children: [_jsx(Skeleton, { className: "h-5 w-24" }), _jsxs("div", { className: "flex flex-col gap-2", children: [_jsx(Skeleton, { className: "h-7 w-64 max-w-full" }), _jsx(Skeleton, { className: "h-5 w-40" })] }), Array.from({ length: 2 }, (_, section) => (_jsxs(Card, { children: [_jsx(CardHeader, { children: _jsx(Skeleton, { className: "h-5 w-32" }) }), _jsx(CardContent, { className: "flex flex-col gap-4", children: Array.from({ length: 4 }, (_, row) => (_jsxs("div", { className: "flex flex-col gap-1 sm:flex-row sm:gap-6", children: [_jsx(Skeleton, { className: "h-5 w-32" }), _jsx(Skeleton, { className: "h-5 flex-1" })] }, row))) })] }, section)))] }));
+function Rail({ label, sections }) {
+    const [ref, fits] = useFitsWindow();
+    return (_jsx("aside", { ref: ref, "aria-label": label, "data-fits": fits ? '' : undefined, className: cn(RAIL_LAYOUT.rail, RAIL_LAYOUT.sticky, 'flex min-w-0 flex-col gap-6'), children: sections.map((section) => (_jsx(ViewSection, { section: section, inRail: true }, section.title))) }));
 }
-export function EntityView({ title, titleEdit, badges, actions, sections, isLoading, error, onRetry, back, }) {
+export function EntityView({ title, titleEdit, badges, actions, sections, layout = 'column', railLabel, isLoading, error, onRetry, back, }) {
     // Editing in place: one store per view, and the leave-page prompt only
     // while a field is open.
     const [store] = useState(() => new EditInPlaceStore());
@@ -74,6 +144,8 @@ export function EntityView({ title, titleEdit, badges, actions, sections, isLoad
     if (error)
         return _jsx(ErrorState, { error: error, onRetry: onRetry });
     if (isLoading)
-        return _jsx(EntityViewSkeleton, {});
-    return (_jsx(EditInPlaceContext.Provider, { value: store, children: _jsxs("div", { className: "flex max-w-4xl flex-col gap-6", "data-state": "success", children: [openField !== null && _jsx(LeaveGuard, { store: store }), _jsx(BackLink, { back: back }), _jsxs("header", { className: "flex flex-col gap-3 sm:flex-row sm:items-start sm:justify-between", children: [_jsxs("div", { className: "flex min-w-0 flex-1 flex-col gap-2", children: [_jsx("h1", { className: "type-page-title break-words text-foreground", children: titleEdit ? (_jsx(EditableValue, { label: titleEdit.label, edit: titleEdit, layout: "inline", className: "w-full", children: title })) : (title) }), badges && _jsx("div", { className: "flex flex-wrap items-center gap-1.5", children: badges })] }), actions && _jsx("div", { className: "flex shrink-0 flex-wrap items-center gap-2", children: actions })] }), sections.map((section) => (_jsx(ViewSection, { section: section }, section.title)))] }) }));
+        return _jsx(EntityViewSkeleton, { layout: layout });
+    const railSections = sections.filter((section) => section.placement === 'rail');
+    const mainSections = sections.filter((section) => section.placement !== 'rail');
+    return (_jsx(EditInPlaceContext.Provider, { value: store, children: _jsxs("div", { className: layout === 'rail' ? RAIL_LAYOUT.page : 'flex max-w-4xl flex-col gap-6', "data-state": "success", "data-layout": layout, children: [openField !== null && _jsx(LeaveGuard, { store: store }), _jsx(BackLink, { back: back }), _jsxs("header", { className: "flex flex-col gap-3 sm:flex-row sm:items-start sm:justify-between", children: [_jsxs("div", { className: "flex min-w-0 flex-1 flex-col gap-2", children: [_jsx("h1", { className: "type-page-title break-words text-foreground", children: titleEdit ? (_jsx(EditableValue, { label: titleEdit.label, edit: titleEdit, layout: "inline", className: "w-full", children: title })) : (title) }), badges && _jsx("div", { className: "flex flex-wrap items-center gap-1.5", children: badges })] }), actions && _jsx("div", { className: "flex shrink-0 flex-wrap items-center gap-2", children: actions })] }), layout === 'rail' ? (_jsxs("div", { className: RAIL_LAYOUT.columns, children: [railSections.length > 0 && (_jsx(Rail, { label: railLabel ?? `${title ?? 'Record'} details`, sections: railSections })), _jsx("div", { className: cn(RAIL_LAYOUT.main, railSections.length === 0 && RAIL_LAYOUT.mainAlone), children: mainSections.map((section) => (_jsx(ViewSection, { section: section }, section.title))) })] })) : (sections.map((section) => _jsx(ViewSection, { section: section }, section.title)))] }) }));
 }

package/dist/index.d.ts

@@ -1,7 +1,8 @@
 export { AppShell, type AppShellProps, type NavItem } from './components/app/app-shell.js';
+export { CountLink, type CountLinkProps } from './components/app/count-link.js';
 export { DataTable, type DataTableProps, type SortingState } from './components/app/data-table.js';
 export { EntityForm, type EntityFormProps } from './components/app/entity-form.js';
-export { EntityView, type EntityViewField, type EntityViewProps, type EntityViewSection, } from './components/app/entity-view.js';
+export { EntityView, type EntityViewField, type EntityViewLayout, type EntityViewPlacement, type EntityViewProps, type EntityViewSection, } from './components/app/entity-view.js';
 export { editInPlace, type EditControlProps, type EditInPlace, type EditInPlaceOptions, type EditKind, } from './components/app/edit-in-place.js';
 export { DataEnvironmentBanner } from './components/app/data-environment-banner.js';
 export { EditableValue, type EditableValueProps } from './components/app/editable-value.js';

package/dist/index.js

@@ -4,6 +4,7 @@
 // points (`/gateway`, `/mocks`, `/testing`) so each stays behind its boundary.
 // Composites
 export { AppShell } from './components/app/app-shell.js';
+export { CountLink } from './components/app/count-link.js';
 export { DataTable } from './components/app/data-table.js';
 export { EntityForm } from './components/app/entity-form.js';
 export { EntityView, } from './components/app/entity-view.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tristan2828/ui-foundation",
-  "version": "3.22.0",
+  "version": "3.24.0",
   "description": "Shared UI foundation for contract-first, database-backed React apps: shadcn primitives, DataTable/EntityForm composites, auth, the gateway error seam, design tokens, lint rules and the AI playbook.",
   "license": "MIT",
   "repository": {