@tristan2828/ui-foundation 3.23.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/entity-plan-template.md

@@ -123,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/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

@@ -2,7 +2,7 @@ export { AppShell, type AppShellProps, type NavItem } from './components/app/app
 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tristan2828/ui-foundation",
-  "version": "3.23.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": {