@nanisoft/prism-ui 0.16.0 → 1.0.0

package/dist/blocks/record-detail-01/record-detail.d.ts

@@ -0,0 +1,239 @@
+import { type ReactNode } from 'react';
+import { type HeadingLevel } from '../../components/ui/section.js';
+import type { RelationSpec } from '../../lib/spec.js';
+import { type EmptyReason } from '../empty-state-01/index.js';
+/**
+ * One fact a reader is told about the record, in the caller's own order.
+ *
+ * `id` is a stable key rather than the words of the label, for the reason every
+ * other key in this package gives: it is what a caller keys their own rendering
+ * by, and a key built out of a label breaks the moment the label is translated.
+ * The value is a node rather than a string because the facts a record carries are
+ * the caller's own and they are not all text: a status word, a moment, a link and
+ * a composed figure are all things a caller puts in one slot.
+ */
+export type RecordDetail01Field = {
+    /** A stable key for the field, so a caller and a test can name one. */
+    id: string;
+    /** What the fact is, in the product's own words. */
+    label: ReactNode;
+    /** What it reads. */
+    value: ReactNode;
+};
+/**
+ * The words a relationship draws in its own frame when it has no members.
+ *
+ * **A relation declares its own empty words, and the reason is that an empty
+ * collection and a reader who has chosen nothing are two different sentences.** A
+ * customer with no invoices, an order with no payments and a project with no
+ * people are all collections that are empty, narrowed, emptied or hidden, and
+ * every one of those is a reason `EmptyState01` was drawn for. The words are the
+ * caller's because only the product knows whether the answer is "nothing has ever
+ * been here" or "this reader may not see it", and a Block that published one
+ * sentence for all four would tell a reader who emptied a collection that their
+ * filter matched nothing.
+ *
+ * `reason` is `EmptyState01`'s own closed union, reused rather than re-spelled,
+ * so a relation cannot reach an empty state the Block that draws it does not
+ * have.
+ */
+export type RecordDetail01RelationEmpty = {
+    /** Which of the four situations this is. */
+    reason: EmptyReason;
+    /** The headline, in the reader's own words. */
+    title: string;
+    /** The sentence under the headline, for the part the headline cannot fit. */
+    body?: string;
+    /** The label of the one action, when the reader has something to do here. */
+    actionLabel?: string;
+    /** The handler for `actionLabel`, required whenever `actionLabel` is set. */
+    onAction?: () => void;
+};
+/**
+ * One relationship of a record, as the detail draws it.
+ *
+ * **It is the shared `RelationSpec` plus the words its empty frame needs, and the
+ * split is deliberate.** The specification carries the data: a stable `key`, the
+ * caller's `label`, the `kind`, an optional `href` on the heading with its
+ * required `hrefLabel`, an optional `count` that is the caller's own string, and
+ * the `members`. The empty words are a drawing rather than data, and the
+ * specification module stays plain serialisable data with no reference to a
+ * Block, which is why they sit here beside the Block that draws them rather than
+ * on the shared type.
+ *
+ * **Depth is one, and the bound is in `RelationSpec` rather than in this type.**
+ * `members` is `readonly unknown[]` and never names `RelationSpec`, so a relation
+ * cannot hold a relation. A member is a row, a person, an occurrence or a node in
+ * the caller's data, and a related record with its own related records is a graph
+ * the consumer walks: a member carries the caller's own `href` when it should
+ * open, and the destination is the caller's route.
+ */
+export type RecordDetail01Relation = RelationSpec & {
+    /** The words this relation draws when it has no members. */
+    empty: RecordDetail01RelationEmpty;
+};
+/**
+ * The props a `RecordDetail01` accepts.
+ *
+ * Every word is the caller's and the Block ships none: no title, no fact, no
+ * action label, no relation name, no empty sentence and not one figure. The
+ * record's own content arrives as `title`, `eyebrow`, `description`, `fields` and
+ * `children`, its own controls arrive as `actions`, and its relationships arrive
+ * as one ordered `relations` list. The Block fetches nothing, reads nothing by
+ * key and defaults to no record.
+ */
+export type RecordDetail01Props = {
+    /**
+     * The record's own heading, in the caller's words.
+     *
+     * Required, because a detail that does not name the record it is showing is a
+     * surface a reader has to identify from its fields, and the heading is the one
+     * thing the caller already holds when they put the record in the address.
+     */
+    title: ReactNode;
+    /**
+     * A line above the title, such as the record's own key or type.
+     *
+     * The caller's own words, and it is drawn in the mono face because an
+     * identifier is machine notation: it is what a reader pastes into a search box,
+     * quotes in a message and cites in a review, and this repository annotates
+     * machine-readable values with the mono stack rather than with anything else.
+     */
+    eyebrow?: ReactNode;
+    /** A sentence under the title, for the part the title cannot fit. */
+    description?: ReactNode;
+    /**
+     * The facts a reader is entitled to be told about the record, in the order they
+     * should be read.
+     *
+     * The caller's list, because a fixed set of fields would decide what a record
+     * is made of, which is a claim only the product can make. A record that carries
+     * a story point, a sprint, a customer and a severity has four facts this
+     * package knows nothing about, and a Block that named four of them would have
+     * to be forked to carry the fifth.
+     */
+    fields?: readonly RecordDetail01Field[];
+    /**
+     * The record's own content, composed by the caller.
+     *
+     * A slot, because what a record shows besides its facts is the caller's
+     * composition: a screen that wants a figure composes `Summary01` or `Stats01`
+     * here rather than asking this Block to keep a running total, and a screen with
+     * prose composes `Prose`. The Block places it and styles nothing inside it.
+     */
+    children?: ReactNode;
+    /**
+     * The controls that act on the record, placed in the record's own band.
+     *
+     * One optional node the caller wrote, and the Block renders no control of its
+     * own. What the screen can do to itself belongs to `PageHeader01`; what can be
+     * done to this record belongs beside its identity, and a detail in a split pane
+     * has no page header above it. There is no declared action union and no
+     * destination arm, so the strongest action beside a record is the caller's, and
+     * the confirmation for a destructive one is the caller's own `AlertDialog`
+     * composed around their control in this slot.
+     */
+    actions?: ReactNode;
+    /**
+     * The record's relationships, one ordered list, drawn open in the declared
+     * order.
+     *
+     * One list on one frame rather than a card per relation, so a record with four
+     * relationships and a record with one read the same way. Every relation is
+     * drawn open, because a relation a reader has to ask for is a disclosure, a
+     * disclosure is a control, and a control in a Block is the finding
+     * `scripts/check-block-controls.mjs` exists to catch.
+     */
+    relations?: readonly RecordDetail01Relation[];
+    /**
+     * Heading level for the record's own heading.
+     *
+     * Each relation's label sits one level under it, derived rather than asked for,
+     * so a Block moved one level deeper carries its relation headings with it.
+     *
+     * @defaultValue 'h2'
+     */
+    headingLevel?: HeadingLevel;
+    /** Layout only. Changing a Prism-owned visual property from here is prohibited. */
+    className?: string;
+};
+/**
+ * The record detail: one record in full, its relationships drawn open, and its
+ * own actions beside its identity.
+ *
+ * **It is handed the record and it owns no selection.** The consumer put the
+ * record in the address; a detail that knew which record it shows would own the
+ * selection state the split and the record index already hold, and a Page cannot
+ * own it either because a Page imports no router. So `title`, `eyebrow`,
+ * `description`, `fields` and `children` are the caller's, the `relations` are
+ * the caller's ordered list, and this Block fetches nothing, reads nothing by key
+ * and defaults to no record. A record that is gone, one this reader may not see
+ * and one whose fetch failed are three causes sharing one address and three
+ * different sentences, so whether this Block is drawn at all is the caller's
+ * answer.
+ *
+ * **Relationships are one declared list on one frame, not a card per relation.**
+ * Each entry is a `RelationSpec` from `@nanisoft/prism-ui/spec` plus the words its
+ * own empty frame needs. They are drawn in the declared order, under one heading
+ * level, inside one bounded frame with one rule between them, so a record with
+ * four relationships and a record with one read the same way rather than becoming
+ * a grid of equal panels. The `kind` names the collection arrangement this
+ * package already draws, and a relation the union does not name is the `slot`
+ * member, drawn open and placed by the caller.
+ *
+ * **Depth is one, and the bound is in the type.** `RelationSpec.members` is
+ * `readonly unknown[]` and never names `RelationSpec`, so a relation cannot hold
+ * a relation and this Block draws one ring of a graph the consumer walks. A
+ * descendant is reached by a link rather than by depth: a member carries the
+ * caller's own `href` when it should open, and the destination is the caller's
+ * route. The Block composes no disclosure anywhere, because a disclosure is a
+ * control and a control in a Block is the finding the block controls gate exists
+ * to catch, and because a relation behind a disclosure is a record the reader has
+ * to choose to find.
+ *
+ * **The record's actions are the caller's node, placed in the record's own band.**
+ * What the screen can do to itself belongs to `PageHeader01`; what can be done to
+ * this record belongs beside its identity, and a detail in a split pane has no
+ * page header above it. The prop is one optional `ReactNode` and the Block
+ * renders no control of its own, so there is no edit, archive or delete button
+ * here, and the confirmation for a destructive action is the caller's own
+ * `AlertDialog` composed around their control in the same slot. There is no cap
+ * on how many actions are placed, because a slot cannot be counted.
+ *
+ * **A relation with no members draws `EmptyState01` at a reason the caller names,
+ * in the relation's own frame.** Every one of that Block's reasons is a statement
+ * about a collection, and a relation with no members is exactly that: a customer
+ * with no invoices, an order with no payments and a project with no people are
+ * all collections that are empty, narrowed, emptied or hidden. `NothingChosen01`
+ * is a statement about a reader's pointer at a record in the index beside the
+ * pane, which this Block cannot be in, because a Block handed a record was handed
+ * the selection with it.
+ *
+ * **It takes no total, no count and no sum.** A relation's `count` is the
+ * caller's own string and is never derived from the members, because a count
+ * computed over the members a Block was handed is false the moment the collection
+ * is larger than the page. A screen that wants a figure composes `Summary01` or
+ * `Stats01` into `children` rather than asking this Block to keep a running
+ * total, and a record write form is a Block composed beside or below this one and
+ * never a mode of it.
+ *
+ * It owns no selection, fetch, ordering, paging or filtering of its relations,
+ * no navigation and no address, no edit state, no confirmation, toast, retry or
+ * undo, and no second pane. It is a server Component: no hook beyond `useId` and
+ * no state of its own, so a consumer that passes a client action inside a slot
+ * pays for the action and not for the frame. The trail relation is the one client
+ * island, because a dated occurrence is drawn by the client `ActivityFeed01`.
+ *
+ * **It is measured against `IssueDetail01`, which is deprecated in its favour.** An
+ * issue detail and a record detail are the same job: a key in the mono face, a state
+ * as a tone beside the caller's own words, declared facts, a body and a thread in the
+ * caller's order. The issue detail's name is wrong the moment the record is an invoice
+ * or a subscription, and a name that has to be wrong about nine tenths of its uses is
+ * a name that fails the test that its name survives being wrong, so that Item is
+ * deprecated rather than merged or replaced. A reader arriving at either Item arrives
+ * at the same answer: a record drawn in full is this Block, whatever the product calls
+ * its records.
+ */
+export declare function RecordDetail01({ title, eyebrow, description, fields, children, actions, relations, headingLevel, className, }: RecordDetail01Props): import("react").JSX.Element;
+export default RecordDetail01;
+//# sourceMappingURL=record-detail.d.ts.map

package/dist/blocks/record-detail-01/record-detail.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"record-detail.d.ts","sourceRoot":"","sources":["../../../src/blocks/record-detail-01/record-detail.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAS,KAAK,SAAS,EAAE,MAAM,OAAO,CAAA;AAK7C,OAAO,EAAyD,KAAK,YAAY,EAAE,MAAM,6BAA6B,CAAA;AAGtH,OAAO,KAAK,EAA2B,YAAY,EAAE,MAAM,gBAAgB,CAAA;AAG3E,OAAO,EAAgB,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAElE;;;;;;;;;GASG;AACH,MAAM,MAAM,mBAAmB,GAAG;IAChC,uEAAuE;IACvE,EAAE,EAAE,MAAM,CAAA;IACV,oDAAoD;IACpD,KAAK,EAAE,SAAS,CAAA;IAChB,qBAAqB;IACrB,KAAK,EAAE,SAAS,CAAA;CACjB,CAAA;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,2BAA2B,GAAG;IACxC,4CAA4C;IAC5C,MAAM,EAAE,WAAW,CAAA;IACnB,+CAA+C;IAC/C,KAAK,EAAE,MAAM,CAAA;IACb,6EAA6E;IAC7E,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,6EAA6E;IAC7E,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAA;CACtB,CAAA;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,MAAM,sBAAsB,GAAG,YAAY,GAAG;IAClD,4DAA4D;IAC5D,KAAK,EAAE,2BAA2B,CAAA;CACnC,CAAA;AAED;;;;;;;;;GASG;AACH,MAAM,MAAM,mBAAmB,GAAG;IAChC;;;;;;OAMG;IACH,KAAK,EAAE,SAAS,CAAA;IAChB;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,SAAS,CAAA;IACnB,qEAAqE;IACrE,WAAW,CAAC,EAAE,SAAS,CAAA;IACvB;;;;;;;;;OASG;IACH,MAAM,CAAC,EAAE,SAAS,mBAAmB,EAAE,CAAA;IACvC;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAA;IACpB;;;;;;;;;;OAUG;IACH,OAAO,CAAC,EAAE,SAAS,CAAA;IACnB;;;;;;;;;OASG;IACH,SAAS,CAAC,EAAE,SAAS,sBAAsB,EAAE,CAAA;IAC7C;;;;;;;OAOG;IACH,YAAY,CAAC,EAAE,YAAY,CAAA;IAC3B,mFAAmF;IACnF,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,CAAA;AA4HD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4EG;AACH,wBAAgB,cAAc,CAAC,EAC7B,KAAK,EACL,OAAO,EACP,WAAW,EACX,MAAM,EACN,QAAQ,EACR,OAAO,EACP,SAAS,EACT,YAAmB,EACnB,SAAS,GACV,EAAE,mBAAmB,+BAgFrB;AAED,eAAe,cAAc,CAAA"}

package/dist/blocks/record-detail-01/record-detail.js

@@ -0,0 +1,150 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useId } from 'react';
+import { AvatarGroup } from '../../components/ui/avatar-group.js';
+import { CtaLink } from '../../components/ui/cta-link.js';
+import { ListPanel } from '../../components/ui/list-panel.js';
+import { Section, SectionHeading, childLevel, headingSizeClass } from '../../components/ui/section.js';
+import { Table, TableBody } from '../../components/ui/table.js';
+import { Timeline } from '../../components/ui/timeline.js';
+import { cn } from '../../lib/utils.js';
+import { ActivityFeed01 } from '../activity-feed-01/index.js';
+import { EmptyState01 } from '../empty-state-01/index.js';
+/**
+ * The collection arrangements a relation is drawn in, keyed by the kind's
+ * lowercase name.
+ *
+ * The map covers every member of `RelationKind`, so a kind added to the union
+ * fails the compiler here until it is drawn. Each arrangement is one of the
+ * Items this package already ships, and each takes the relation's `members`
+ * as the shape that Item already declares: a `Table` relation's members are
+ * the caller's own row nodes, drawn in a `TableBody`; a `ListPanel` relation's
+ * members are the caller's own list rows; a `Timeline` relation's members are
+ * `TimelineEntry` values, which carry a duration and a state; an
+ * `ActivityFeed01` relation's members are `EventSpec` values, which carry a
+ * moment and an actor, so a record's event history is drawn as a dated trail
+ * and never as an instrument; an `AvatarGroup` relation's members are
+ * `{ name, src }` values; and a `slot` relation's members are the caller's own
+ * nodes, placed in the order given. The cast is the same one `DataTable01`
+ * makes for a cell, and for the same reason: the specification is the weakest
+ * type in the module on purpose, and the arrangement is the thing that knows
+ * what a member is.
+ *
+ * The trail is drawn by the client Block `ActivityFeed01`, so the frame stays a
+ * server Component and only the trail is a client island. Its own section padding
+ * is dropped here because the relation already draws the heading, the count and
+ * the frame around it, and its required `empty` is the relation's own empty words,
+ * which a relation with no members never reaches because it draws `EmptyState01`
+ * instead.
+ */
+const ARRANGEMENT = {
+    table: (members, { labelledBy }) => (_jsx(Table, { "aria-labelledby": labelledBy, children: _jsx(TableBody, { children: members }) })),
+    listpanel: (members) => (_jsx(ListPanel, { scroll: false, children: _jsx("ul", { className: "divide-border flex flex-col divide-y", children: members }) })),
+    timeline: (members, { label }) => (_jsx(Timeline, { entries: members, label: label })),
+    activityfeed01: (members, { empty }) => (_jsx(ActivityFeed01, { events: members, empty: empty, className: "py-0" })),
+    avatargroup: (members) => (_jsx(AvatarGroup, { avatars: members })),
+    slot: (members) => (_jsx("div", { "data-slot": "record-detail-01-slot", className: "flex flex-col gap-4", children: members })),
+};
+/**
+ * One relationship, drawn open: its heading and count, its optional destination,
+ * and either its members in the arrangement the kind names or the caller's empty
+ * state in the relation's own frame.
+ *
+ * The heading level is passed in rather than derived here, so every relation on a
+ * record sits at one level under the record's own heading.
+ */
+function Relation({ relation, level }) {
+    const headingId = useId();
+    const Heading = level;
+    // A `Timeline` names its list with a string, so a node label falls back to the
+    // relation's own key rather than to a flattened sentence the Block invented.
+    const labelText = typeof relation.label === 'string' ? relation.label : relation.key;
+    const arrangement = ARRANGEMENT[relation.kind.toLowerCase()];
+    return (_jsxs("section", { "data-slot": "record-detail-01-relation", "data-relation": relation.key, "aria-labelledby": headingId, className: "flex flex-col gap-4 p-6", children: [_jsxs("div", { className: "flex flex-wrap items-baseline justify-between gap-x-4 gap-y-1", children: [_jsx(Heading, { id: headingId, className: cn('font-semibold tracking-tight text-balance', headingSizeClass(level)), children: relation.label }), relation.href === undefined ? null : (_jsx(CtaLink, { "data-slot": "record-detail-01-relation-link", href: relation.href, variant: "ghost", size: "sm", children: relation.hrefLabel }))] }), relation.count === undefined ? null : (_jsx("p", { "data-slot": "record-detail-01-relation-count", className: "text-muted-foreground text-sm tabular-nums", children: relation.count })), relation.members.length === 0 ? (_jsx(EmptyState01, { reason: relation.empty.reason, title: relation.empty.title, body: relation.empty.body, actionLabel: relation.empty.actionLabel, onAction: relation.empty.onAction })) : (arrangement(relation.members, {
+                label: labelText,
+                labelledBy: headingId,
+                empty: relation.empty.title,
+            }))] }));
+}
+/**
+ * The record detail: one record in full, its relationships drawn open, and its
+ * own actions beside its identity.
+ *
+ * **It is handed the record and it owns no selection.** The consumer put the
+ * record in the address; a detail that knew which record it shows would own the
+ * selection state the split and the record index already hold, and a Page cannot
+ * own it either because a Page imports no router. So `title`, `eyebrow`,
+ * `description`, `fields` and `children` are the caller's, the `relations` are
+ * the caller's ordered list, and this Block fetches nothing, reads nothing by key
+ * and defaults to no record. A record that is gone, one this reader may not see
+ * and one whose fetch failed are three causes sharing one address and three
+ * different sentences, so whether this Block is drawn at all is the caller's
+ * answer.
+ *
+ * **Relationships are one declared list on one frame, not a card per relation.**
+ * Each entry is a `RelationSpec` from `@nanisoft/prism-ui/spec` plus the words its
+ * own empty frame needs. They are drawn in the declared order, under one heading
+ * level, inside one bounded frame with one rule between them, so a record with
+ * four relationships and a record with one read the same way rather than becoming
+ * a grid of equal panels. The `kind` names the collection arrangement this
+ * package already draws, and a relation the union does not name is the `slot`
+ * member, drawn open and placed by the caller.
+ *
+ * **Depth is one, and the bound is in the type.** `RelationSpec.members` is
+ * `readonly unknown[]` and never names `RelationSpec`, so a relation cannot hold
+ * a relation and this Block draws one ring of a graph the consumer walks. A
+ * descendant is reached by a link rather than by depth: a member carries the
+ * caller's own `href` when it should open, and the destination is the caller's
+ * route. The Block composes no disclosure anywhere, because a disclosure is a
+ * control and a control in a Block is the finding the block controls gate exists
+ * to catch, and because a relation behind a disclosure is a record the reader has
+ * to choose to find.
+ *
+ * **The record's actions are the caller's node, placed in the record's own band.**
+ * What the screen can do to itself belongs to `PageHeader01`; what can be done to
+ * this record belongs beside its identity, and a detail in a split pane has no
+ * page header above it. The prop is one optional `ReactNode` and the Block
+ * renders no control of its own, so there is no edit, archive or delete button
+ * here, and the confirmation for a destructive action is the caller's own
+ * `AlertDialog` composed around their control in the same slot. There is no cap
+ * on how many actions are placed, because a slot cannot be counted.
+ *
+ * **A relation with no members draws `EmptyState01` at a reason the caller names,
+ * in the relation's own frame.** Every one of that Block's reasons is a statement
+ * about a collection, and a relation with no members is exactly that: a customer
+ * with no invoices, an order with no payments and a project with no people are
+ * all collections that are empty, narrowed, emptied or hidden. `NothingChosen01`
+ * is a statement about a reader's pointer at a record in the index beside the
+ * pane, which this Block cannot be in, because a Block handed a record was handed
+ * the selection with it.
+ *
+ * **It takes no total, no count and no sum.** A relation's `count` is the
+ * caller's own string and is never derived from the members, because a count
+ * computed over the members a Block was handed is false the moment the collection
+ * is larger than the page. A screen that wants a figure composes `Summary01` or
+ * `Stats01` into `children` rather than asking this Block to keep a running
+ * total, and a record write form is a Block composed beside or below this one and
+ * never a mode of it.
+ *
+ * It owns no selection, fetch, ordering, paging or filtering of its relations,
+ * no navigation and no address, no edit state, no confirmation, toast, retry or
+ * undo, and no second pane. It is a server Component: no hook beyond `useId` and
+ * no state of its own, so a consumer that passes a client action inside a slot
+ * pays for the action and not for the frame. The trail relation is the one client
+ * island, because a dated occurrence is drawn by the client `ActivityFeed01`.
+ *
+ * **It is measured against `IssueDetail01`, which is deprecated in its favour.** An
+ * issue detail and a record detail are the same job: a key in the mono face, a state
+ * as a tone beside the caller's own words, declared facts, a body and a thread in the
+ * caller's order. The issue detail's name is wrong the moment the record is an invoice
+ * or a subscription, and a name that has to be wrong about nine tenths of its uses is
+ * a name that fails the test that its name survives being wrong, so that Item is
+ * deprecated rather than merged or replaced. A reader arriving at either Item arrives
+ * at the same answer: a record drawn in full is this Block, whatever the product calls
+ * its records.
+ */
+export function RecordDetail01({ title, eyebrow, description, fields, children, actions, relations, headingLevel = 'h2', className, }) {
+    const relationLevel = childLevel(headingLevel);
+    const list = relations ?? [];
+    return (_jsx(Section, { "data-slot": "record-detail-01", className: cn(className), children: _jsxs("div", { className: "flex flex-col gap-10", children: [_jsxs("div", { "data-slot": "record-detail-01-band", className: "flex flex-wrap items-start justify-between gap-x-6 gap-y-4", children: [_jsxs("div", { className: "flex min-w-0 flex-col gap-2", children: [eyebrow === undefined ? null : (_jsx("span", { "data-slot": "record-detail-01-eyebrow", className: "text-muted-foreground font-mono text-sm", children: eyebrow })), _jsx(SectionHeading, { as: headingLevel, align: "left", title: title, description: description, className: "mb-0" })] }), actions === undefined ? null : (_jsx("div", { "data-slot": "record-detail-01-actions", className: "flex shrink-0 flex-wrap items-center gap-2", children: actions }))] }), fields === undefined || fields.length === 0 ? null : (_jsx("dl", { "data-slot": "record-detail-01-fields", className: "grid gap-x-8 gap-y-3 sm:grid-cols-[auto_minmax(0,1fr)]", children: fields.map((field) => (_jsxs("div", { "data-slot": "record-detail-01-field", className: "contents", children: [_jsx("dt", { className: "text-muted-foreground text-sm font-medium", children: field.label }), _jsx("dd", { className: "min-w-0 text-sm", children: field.value })] }, field.id))) })), children === undefined ? null : (_jsx("div", { "data-slot": "record-detail-01-content", className: "flex flex-col gap-10", children: children })), list.length === 0 ? null : (_jsx("div", { "data-slot": "record-detail-01-relations", className: "divide-border divide-y overflow-hidden rounded-xl border", children: list.map((relation) => (_jsx(Relation, { relation: relation, level: relationLevel }, relation.key))) }))] }) }));
+}
+export default RecordDetail01;

package/dist/blocks/record-form-01/index.d.ts

@@ -0,0 +1,3 @@
+export { RecordForm01, default } from './record-form.js';
+export type { RecordForm01Props, RecordForm01Issue } from './record-form.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/blocks/record-form-01/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/blocks/record-form-01/index.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,eAAe,CAAA;AACrD,YAAY,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAA"}

package/dist/blocks/record-form-01/index.js

@@ -0,0 +1 @@
+export { RecordForm01, default } from './record-form.js';

package/dist/blocks/record-form-01/record-form.d.ts

@@ -0,0 +1,148 @@
+import { type ReactNode } from 'react';
+import { type HeadingLevel } from '../../components/ui/section.js';
+import type { FieldSpecGroup } from '../../lib/spec.js';
+/**
+ * One thing wrong with the form, in the caller's own words.
+ *
+ * `field` is the `key` of the field the message belongs to, and the key rather
+ * than the label because it is what the caller's values and the form's own
+ * `FormData` are keyed by: a message matched by a label's words breaks the moment
+ * the label is translated. The shape is the one `FormDialog` and `FormWizard`
+ * already publish, so this Block mints no third spelling of an issue.
+ */
+export type RecordForm01Issue = {
+    /** The `key` of the field this message belongs to. */
+    field: string;
+    /** The message, in the product's own words. */
+    message: string;
+};
+/** The members every arm of the save union shares. */
+type RecordForm01Base = {
+    /** The form's own heading, absent for a form that needs none. */
+    title?: ReactNode;
+    /** One line under the heading saying what submitting this will do. */
+    description?: ReactNode;
+    /**
+     * The fields, grouped and ordered.
+     *
+     * Every field belongs to a group, and a form with no headings is one group with
+     * no label. The array's order is the order they are drawn in.
+     */
+    groups: readonly FieldSpecGroup[];
+    /**
+     * How many columns the fields sit in.
+     *
+     * One at every width by default, and one column again at the narrow breakpoint
+     * when two are asked for. There is no per-field layout prop and no slot per
+     * region.
+     *
+     * @defaultValue 1
+     */
+    columns?: 1 | 2;
+    /** The issues to draw, keyed by field. Drawn under the control that owns them. */
+    issues?: readonly RecordForm01Issue[];
+    /**
+     * A message about the submission rather than about a control.
+     *
+     * It names no field and marks at most one, which is the arrangement `AuthForm01`
+     * argues for: telling a reader that two correctly filled fields are wrong is how
+     * they learn to stop trusting the rest of the form.
+     */
+    submitError?: ReactNode;
+    /**
+     * Heading level for the form's own heading. See `HeadingLevel`.
+     *
+     * @defaultValue 'h2'
+     */
+    headingLevel?: HeadingLevel;
+    /** A secondary control beside the save, such as a cancel link. */
+    footerStart?: ReactNode;
+    /** Layout only. Changing a Prism-owned visual property from here is prohibited. */
+    className?: string;
+};
+/**
+ * The props a `RecordForm01` accepts.
+ *
+ * **A discriminated union with three arms, at least one required, and each
+ * forbidding the other two.** The compiler holds that rule rather than a JSDoc
+ * block, so a caller cannot reach a save that activates to nothing and cannot
+ * pass a handler beside a form that posts to a URL. `action` posts the form to a
+ * URL the caller names; `onSubmit` hands the form's own element to a function and
+ * makes the Block a client Component; `submit` is a slot holding the caller's own
+ * control, placed unstyled in the footer.
+ */
+export type RecordForm01Props = (RecordForm01Base & {
+    /** The URL the form posts to, the browser's own activation. */
+    action: string;
+    /** The label of the save control. */
+    submitLabel: ReactNode;
+    onSubmit?: never;
+    submit?: never;
+}) | (RecordForm01Base & {
+    /** Called with the form element when the reader submits. */
+    onSubmit: (form: HTMLFormElement) => void;
+    /** The label of the save control. */
+    submitLabel: ReactNode;
+    action?: never;
+    submit?: never;
+}) | (RecordForm01Base & {
+    /** The caller's own control, placed unstyled in the footer. */
+    submit: ReactNode;
+    action?: never;
+    onSubmit?: never;
+    submitLabel?: never;
+});
+/**
+ * The record write form: a typed field specification, rendered whole.
+ *
+ * **It takes a field specification and draws the whole form.** `groups` is an
+ * ordered list of `FieldSpecGroup`, each an optional heading, an optional
+ * description and an ordered list of `FieldSpec`; every field carries a stable
+ * `key`, a required `label`, a required `kind` drawn from Prism's own input
+ * vocabulary, and optional help, hint, placeholder, disabled flag and starting
+ * value. A field whose control this package does not ship carries the `slot` arm,
+ * and the Block still draws the label, the help and the error around it, so a
+ * field has the same shell either way. Order is the array's order, and the Block
+ * never reorders, hides or drops a field.
+ *
+ * **Prism owns the shape and the vocabulary; the consumer owns the values, the
+ * errors and the fetch.** The specification carries no validator, no constraint
+ * object, no schema and no pattern, because evaluating a rule is behaviour and a
+ * Block ships none. Requiredness is not validation: it is a rendering fact and an
+ * HTML fact, so the Block draws the mark and sets the attribute and never checks a
+ * value against it.
+ *
+ * **The error state arrives as an issue list keyed by field.** An entry is a
+ * `field` naming a key and a `message` in the product's own words, the shape
+ * `FormDialog` and `FormWizard` already take, and a control's issue is drawn
+ * under that control. A message about the submission rather than about a control
+ * is `submitError`: it names no field and marks at most one.
+ *
+ * **Where the submission goes is a union with three arms, at least one
+ * required.** `action` posts the form to a URL the caller names. `onSubmit` hands
+ * the form's own element to a function and makes the Block a client Component.
+ * `submit` is a slot holding the caller's own control, placed unstyled in the
+ * footer. Each arm forbids the other two, so the compiler holds the rule rather
+ * than this paragraph. The save control is `type="submit"` inside a `<form>` the
+ * Block renders, and the Block never wires a save to a handler of its own.
+ *
+ * **Layout is derived, and the only knob is how many columns the fields sit
+ * in.** `columns` is `1 | 2` at the form level; two is the only multi-column form
+ * layout in which a label stays above its control, and a two-column form fills
+ * across rows rather than down columns, because column-wise filling breaks the
+ * reading order a screen reader and a keyboard follow. At the narrow breakpoint a
+ * two-column form is one column again. There is no per-field layout prop and no
+ * slot per region.
+ *
+ * **A field whose value is absent renders empty rather than absent**, because a
+ * form that changes shape while the reader is halfway through it is a form the
+ * reader has to read twice. The plain form is uncontrolled where a Prism control
+ * can be, so the caller reads the values out of the form element at submit: the
+ * `onSubmit` arm passes that element, and `action` lets the browser post it. The
+ * handful of Prism controls the platform will not submit on their own hold their
+ * value and carry a hidden input under the field's key, so the payload is
+ * complete either way.
+ */
+export declare function RecordForm01(props: RecordForm01Props): import("react").JSX.Element;
+export default RecordForm01;
+//# sourceMappingURL=record-form.d.ts.map

package/dist/blocks/record-form-01/record-form.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"record-form.d.ts","sourceRoot":"","sources":["../../../src/blocks/record-form-01/record-form.tsx"],"names":[],"mappings":"AAEA,OAAO,EAAmC,KAAK,SAAS,EAAE,MAAM,OAAO,CAAA;AAKvE,OAAO,EAAgC,KAAK,YAAY,EAAE,MAAM,6BAA6B,CAAA;AAS7F,OAAO,KAAK,EAAa,cAAc,EAAE,MAAM,gBAAgB,CAAA;AAG/D;;;;;;;;GAQG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B,sDAAsD;IACtD,KAAK,EAAE,MAAM,CAAA;IACb,+CAA+C;IAC/C,OAAO,EAAE,MAAM,CAAA;CAChB,CAAA;AAED,sDAAsD;AACtD,KAAK,gBAAgB,GAAG;IACtB,iEAAiE;IACjE,KAAK,CAAC,EAAE,SAAS,CAAA;IACjB,sEAAsE;IACtE,WAAW,CAAC,EAAE,SAAS,CAAA;IACvB;;;;;OAKG;IACH,MAAM,EAAE,SAAS,cAAc,EAAE,CAAA;IACjC;;;;;;;;OAQG;IACH,OAAO,CAAC,EAAE,CAAC,GAAG,CAAC,CAAA;IACf,kFAAkF;IAClF,MAAM,CAAC,EAAE,SAAS,iBAAiB,EAAE,CAAA;IACrC;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,SAAS,CAAA;IACvB;;;;OAIG;IACH,YAAY,CAAC,EAAE,YAAY,CAAA;IAC3B,kEAAkE;IAClE,WAAW,CAAC,EAAE,SAAS,CAAA;IACvB,mFAAmF;IACnF,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,CAAA;AAED;;;;;;;;;;GAUG;AACH,MAAM,MAAM,iBAAiB,GACzB,CAAC,gBAAgB,GAAG;IAClB,+DAA+D;IAC/D,MAAM,EAAE,MAAM,CAAA;IACd,qCAAqC;IACrC,WAAW,EAAE,SAAS,CAAA;IACtB,QAAQ,CAAC,EAAE,KAAK,CAAA;IAChB,MAAM,CAAC,EAAE,KAAK,CAAA;CACf,CAAC,GACF,CAAC,gBAAgB,GAAG;IAClB,4DAA4D;IAC5D,QAAQ,EAAE,CAAC,IAAI,EAAE,eAAe,KAAK,IAAI,CAAA;IACzC,qCAAqC;IACrC,WAAW,EAAE,SAAS,CAAA;IACtB,MAAM,CAAC,EAAE,KAAK,CAAA;IACd,MAAM,CAAC,EAAE,KAAK,CAAA;CACf,CAAC,GACF,CAAC,gBAAgB,GAAG;IAClB,+DAA+D;IAC/D,MAAM,EAAE,SAAS,CAAA;IACjB,MAAM,CAAC,EAAE,KAAK,CAAA;IACd,QAAQ,CAAC,EAAE,KAAK,CAAA;IAChB,WAAW,CAAC,EAAE,KAAK,CAAA;CACpB,CAAC,CAAA;AAEN;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,iBAAiB,+BAmKpD;AAED,eAAe,YAAY,CAAA"}