@nanisoft/prism-ui 0.10.2 → 0.15.0

package/dist/blocks/feedback-01/feedback.d.ts

@@ -0,0 +1,235 @@
+import type { ReactNode } from 'react';
+import { type HeadingLevel } from '../../components/ui/section.js';
+/**
+ * One point on the caller's own scale.
+ *
+ * **`id` is a key and `value` is the number.** The separation is what lets a caller
+ * keep their own record stable while the scale is reordered, and what lets one scale
+ * be a set of words at one end and a number at the other, which is most of them. On
+ * submit the Block hands over both, so a caller storing by key and a caller
+ * aggregating by number are both served without either reading the other's field.
+ */
+export type Feedback01Point = {
+    /** A stable key for the point. What the Block selects on and what it hands back. */
+    id: string;
+    /** The words drawn beside the control, and all a screen reader announces. */
+    label: string;
+    /** The number this point contributes, for a caller who aggregates. */
+    value: number;
+};
+/** The free-text half of a feedback panel, and its counter. */
+export type Feedback01Comment = {
+    /** The field's visible label, and its accessible name. */
+    label: string;
+    /** The comment as the caller holds it, which makes the field controlled. */
+    value?: string;
+    /** Called as the reader types. */
+    onValueChange?: (value: string) => void;
+    /**
+     * The character ceiling, enforced by the control itself.
+     *
+     * A number and not a sentence, because "200 characters" is a fact about a limit
+     * and the sentence for it belongs to whoever set the limit. Pass the same number
+     * to `counter` and the reader can see the ceiling before they reach it.
+     */
+    maxLength?: number;
+    /**
+     * Whether to draw the character count beside the field.
+     *
+     * A count and not a limit, because a reader who has been typing for a while needs
+     * to know how much room is left rather than what the rule is. It is drawn in
+     * `tabular-nums` so the digits do not shuffle the field's width as they change,
+     * and it is not announced, because a counter that reads itself aloud on every
+     * keystroke is the fastest way to make a screen reader unusable.
+     */
+    counter?: boolean;
+};
+/** The optional file the reader can hand over with their words. */
+export type Feedback01Artefact = {
+    /** The caller's name for what may be attached. Drawn on the drop target. */
+    label: string;
+    /**
+     * Called with the files the reader chose or dropped.
+     *
+     * Required, and the Block calls it as well as recording the files, because the
+     * upload is the caller's: Prism never reads a byte, never sends one and never
+     * knows a size limit. A consumer who wants the files at submit instead reads them
+     * off `FeedbackValue.files`.
+     */
+    onFiles: (files: File[]) => void;
+    /**
+     * The file types the platform's own picker offers, as an `accept` value.
+     *
+     * A hint to the browser and to nothing else. Files dragged onto the target arrive
+     * whatever they are, so the check belongs in `onFiles`, which is the caller's.
+     */
+    accept?: string;
+};
+/**
+ * What a submit hands over, and the whole of what this Block collects.
+ *
+ * **`files` is here as well as in `onFiles` because the two answer different
+ * questions.** `onFiles` fires the moment a reader picks, so an upload can start
+ * while they are still typing. `files` is what the panel holds at submit, so a
+ * caller who wanted to hold everything until the reader pressed the button can.
+ * Neither is the transport, and both are the caller's to use or ignore.
+ */
+export type FeedbackValue = {
+    /** The `id` of the point the reader chose, when they chose one. */
+    rating?: string;
+    /** That point's `value`, read out of the caller's own scale. */
+    ratingValue?: number;
+    /** The comment as typed, when the panel has a comment field. */
+    comment?: string;
+    /** The files the reader attached, when the panel has an artefact field. */
+    files?: File[];
+};
+/** The outcome of the caller's own request, drawn in a live region. */
+export type Feedback01Status = {
+    /** Which of the four the request is in. Read by the Block for two things only. */
+    state: 'idle' | 'sending' | 'sent' | 'error';
+    /** The words for that state, in the product's own voice. */
+    message: ReactNode;
+};
+/** The props a Feedback01 takes. Every string in this Block is one of them. */
+export type Feedback01Props = {
+    /** The short line above the title, usually what the feedback is about. */
+    eyebrow?: ReactNode;
+    /** The heading. Required, because a panel with no heading is a form in a page. */
+    title: ReactNode;
+    /** One supporting line under the heading, for the part the title cannot carry. */
+    description?: ReactNode;
+    /**
+     * The scale, in the order the reader should meet it.
+     *
+     * **Required, and the caller's data rather than five faces Prism chose.** The
+     * number of points and the words at each end are the caller's product knowledge,
+     * and they differ per product in ways no design system can decide. A five-point
+     * scale labelled "bad" to "great" is a survey instrument, and a feedback form
+     * usually is not one: it is one reader telling one team something they could not
+     * have guessed. A support scale has three points with "Blocked" at one end, a
+     * design review scale is arguably not ordered at all, and a rating scale has ten.
+     * So Prism takes the points, the order and the words, and supplies none of the
+     * three. The cost is stated rather than hidden: a caller who passes two points
+     * gets two controls, because rounding up would be the Block inventing a data
+     * point on the caller's behalf.
+     */
+    scale: Feedback01Point[];
+    /**
+     * The scale's own name: what the points are measuring.
+     *
+     * Required, because a `RadioGroup` with no name is a set of radios a reader cannot
+     * identify. A screen reader announces the position within a set, and without this
+     * it announces "3 of 5" and nothing about what is being rated, so a panel that
+     * collected a rating of the support rather than of the interface is one nobody can
+     * catch. It is drawn above the group and the group is named from that same
+     * element, so what a sighted reader reads and what is announced are one thing
+     * rather than two.
+     */
+    scaleLabel: string;
+    /** The chosen point's `id`, which makes the group controlled. */
+    value?: string;
+    /** Called with the chosen point's `id` as the reader moves through the scale. */
+    onValueChange?: (id: string) => void;
+    /** The free-text field. Omit it for a panel that collects a rating only. */
+    comment?: Feedback01Comment;
+    /** The file the reader may attach. Omit it where nothing may be attached. */
+    artefact?: Feedback01Artefact;
+    /**
+     * Called with everything the panel collected when the reader submits.
+     *
+     * **Required, and the requirement is the design.** A panel that gathered a rating,
+     * a comment and a screenshot and then had nowhere to put them would be a component
+     * collecting product data and discarding it, and there is no destination Prism
+     * could pick that would not be wrong for three of the four products that install
+     * it. Making the handler required moves that question to the caller, where it is
+     * answerable.
+     */
+    onSubmit: (value: FeedbackValue) => void;
+    /** The label on the one control that submits. */
+    submitLabel: string;
+    /**
+     * The caller's own way out, as a slot.
+     *
+     * A slot and not a label with a handler, for the reason `Announcement` gives: the
+     * way out of a feedback panel is never only here. It belongs in the surrounding
+     * surface too, so a reader who has decided not to leave feedback is not held by a
+     * Block they cannot dismiss.
+     */
+    cancel?: ReactNode;
+    /**
+     * The outcome of the caller's request, drawn in a live region and announced.
+     *
+     * A prop and never an internal state Prism writes, for the reason every Block in
+     * this wave states it: a sentence this package wrote would be inherited by every
+     * consumer, and a feedback form has more outcomes than any other form here, from a
+     * queued ticket to a duplicate to a rate limit to an artefact that was too large.
+     */
+    status?: Feedback01Status;
+    /** Heading level for the section heading. See `HeadingLevel`. */
+    headingLevel?: HeadingLevel;
+    /** Layout only. Changing a Prism-owned visual property from here is prohibited. */
+    className?: string;
+};
+/**
+ * The panel that asks a reader one question properly: a scale, a place to say more,
+ * and optionally the thing they are talking about.
+ *
+ * **The scale is the caller's data, and that is the argument for the whole Block.** A
+ * five-point scale labelled from "bad" to "great" is a survey instrument, and a
+ * feedback form usually is not one: it is one reader telling one team something they
+ * could not have guessed. How many points there are and what the ends are called is
+ * product knowledge, and it differs per product in ways no design system can decide:
+ * a support scale has three points with "Blocked" at one end, a design review scale
+ * is arguably not ordered at all, and a rating scale has ten. So `scale` is required
+ * and Prism supplies none of it, and the cost is named: a caller who passes two
+ * points gets two controls rather than three, because rounding up would be the Block
+ * inventing a data point.
+ *
+ * **The scale renders as a `RadioGroup` and this Block refuses to render it as five
+ * buttons.** A set of mutually exclusive options is a radio group, and that is not a
+ * styling preference: a screen reader announces the size of the set and the checked
+ * state only when it is one, so a reader of five buttons is told he is on the third
+ * of five undifferentiated controls rather than that he has chosen three out of
+ * five. The keyboard model is the second half of it. Arrow keys move within the
+ * group and Tab crosses it as one stop, which is the model `RadioGroup` already owns
+ * and which five buttons each take a Tab stop of their own instead. Five buttons are
+ * what a sentiment scale looks like on a gallery page, and they are what this Block
+ * deliberately is not.
+ *
+ * **`scaleLabel` is required and it is drawn.** A `RadioGroup` with no name is a set
+ * of radios a reader cannot identify: the reader hears a count and a position and no
+ * indication of what is being rated. Prism draws the name above the group and points
+ * the group's accessible name at that same element, so the two are one thing rather
+ * than a sentence that appears once on the page and once in the accessibility tree.
+ *
+ * **The artefact is a `Dropzone` and a `FileUpload`, and there is no remove control
+ * on purpose.** The list is a record of what was attached, and `FileUpload` is
+ * explicit that a record a reader cannot change is the right rendering of a receipt.
+ * The cost is real and is named here rather than hidden: a reader who picked the
+ * wrong screenshot has to pick again, and the way out is to compose `Dropzone` and
+ * `FileUpload` directly with an `onRemove` and a `removeLabel` of your own rather
+ * than to reach into this Block. Prism did not add the control because doing so
+ * would mean shipping a remove button whose confirmation sentence and whose
+ * replacement state are both sentences about the caller's upload.
+ *
+ * **Nothing here validates anything.** There is no minimum comment length, no
+ * required point, no file size rule and no address format. Each of those is a
+ * decision about the caller's product and its data, and a Block that guessed one
+ * would refuse a reader on the caller's behalf. What Prism does do is hand over the
+ * number a point contributes, so a caller who wants to reject a rating below three
+ * can do it in their own handler with their own sentence.
+ *
+ * **The submit control is disabled while the caller's state reads `sending`**, which
+ * is the same one reading of that state every Block in this wave makes: a second
+ * press while the first request is in flight is a duplicate report no triage queue
+ * wants. The control is disabled rather than replaced so its label never changes
+ * under the reader's finger, and the live region carries the busy state.
+ *
+ * It is a client Component, and there are three reasons rather than one: the handler
+ * is a function, the attached files are state, and the counter reads state on every
+ * keystroke. A server component cannot hand an event handler down to a `<form>`.
+ */
+export declare function Feedback01({ eyebrow, title, description, scale, scaleLabel, value, onValueChange, comment, artefact, onSubmit, submitLabel, cancel, status, headingLevel, className, }: Feedback01Props): import("react").JSX.Element;
+export default Feedback01;
+//# sourceMappingURL=feedback.d.ts.map

package/dist/blocks/feedback-01/feedback.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"feedback.d.ts","sourceRoot":"","sources":["../../../src/blocks/feedback-01/feedback.tsx"],"names":[],"mappings":"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"}

package/dist/blocks/feedback-01/feedback.js

@@ -0,0 +1,113 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useId, useState } from 'react';
+import { Button } from '../../components/ui/button.js';
+import { Card, CardContent, CardFooter } from '../../components/ui/card.js';
+import { Dropzone } from '../../components/ui/dropzone.js';
+import { Field, FieldLabel } from '../../components/ui/field.js';
+import { FileUpload } from '../../components/ui/file-upload.js';
+import { LiveRegion } from '../../components/ui/live-region.js';
+import { RadioGroup, RadioGroupItem } from '../../components/ui/radio-group.js';
+import { Section, SectionHeading } from '../../components/ui/section.js';
+import { Textarea } from '../../components/ui/textarea.js';
+import { cn } from '../../lib/utils.js';
+/**
+ * A character count as the runtime's own locale groups it, because a counter is a
+ * number a reader reads and the separator between its digits is their locale's.
+ */
+function countOf(text) {
+    return text.length.toLocaleString();
+}
+/**
+ * The panel that asks a reader one question properly: a scale, a place to say more,
+ * and optionally the thing they are talking about.
+ *
+ * **The scale is the caller's data, and that is the argument for the whole Block.** A
+ * five-point scale labelled from "bad" to "great" is a survey instrument, and a
+ * feedback form usually is not one: it is one reader telling one team something they
+ * could not have guessed. How many points there are and what the ends are called is
+ * product knowledge, and it differs per product in ways no design system can decide:
+ * a support scale has three points with "Blocked" at one end, a design review scale
+ * is arguably not ordered at all, and a rating scale has ten. So `scale` is required
+ * and Prism supplies none of it, and the cost is named: a caller who passes two
+ * points gets two controls rather than three, because rounding up would be the Block
+ * inventing a data point.
+ *
+ * **The scale renders as a `RadioGroup` and this Block refuses to render it as five
+ * buttons.** A set of mutually exclusive options is a radio group, and that is not a
+ * styling preference: a screen reader announces the size of the set and the checked
+ * state only when it is one, so a reader of five buttons is told he is on the third
+ * of five undifferentiated controls rather than that he has chosen three out of
+ * five. The keyboard model is the second half of it. Arrow keys move within the
+ * group and Tab crosses it as one stop, which is the model `RadioGroup` already owns
+ * and which five buttons each take a Tab stop of their own instead. Five buttons are
+ * what a sentiment scale looks like on a gallery page, and they are what this Block
+ * deliberately is not.
+ *
+ * **`scaleLabel` is required and it is drawn.** A `RadioGroup` with no name is a set
+ * of radios a reader cannot identify: the reader hears a count and a position and no
+ * indication of what is being rated. Prism draws the name above the group and points
+ * the group's accessible name at that same element, so the two are one thing rather
+ * than a sentence that appears once on the page and once in the accessibility tree.
+ *
+ * **The artefact is a `Dropzone` and a `FileUpload`, and there is no remove control
+ * on purpose.** The list is a record of what was attached, and `FileUpload` is
+ * explicit that a record a reader cannot change is the right rendering of a receipt.
+ * The cost is real and is named here rather than hidden: a reader who picked the
+ * wrong screenshot has to pick again, and the way out is to compose `Dropzone` and
+ * `FileUpload` directly with an `onRemove` and a `removeLabel` of your own rather
+ * than to reach into this Block. Prism did not add the control because doing so
+ * would mean shipping a remove button whose confirmation sentence and whose
+ * replacement state are both sentences about the caller's upload.
+ *
+ * **Nothing here validates anything.** There is no minimum comment length, no
+ * required point, no file size rule and no address format. Each of those is a
+ * decision about the caller's product and its data, and a Block that guessed one
+ * would refuse a reader on the caller's behalf. What Prism does do is hand over the
+ * number a point contributes, so a caller who wants to reject a rating below three
+ * can do it in their own handler with their own sentence.
+ *
+ * **The submit control is disabled while the caller's state reads `sending`**, which
+ * is the same one reading of that state every Block in this wave makes: a second
+ * press while the first request is in flight is a duplicate report no triage queue
+ * wants. The control is disabled rather than replaced so its label never changes
+ * under the reader's finger, and the live region carries the busy state.
+ *
+ * It is a client Component, and there are three reasons rather than one: the handler
+ * is a function, the attached files are state, and the counter reads state on every
+ * keystroke. A server component cannot hand an event handler down to a `<form>`.
+ */
+export function Feedback01({ eyebrow, title, description, scale, scaleLabel, value, onValueChange, comment, artefact, onSubmit, submitLabel, cancel, status, headingLevel = 'h2', className, }) {
+    const generated = useId();
+    const scaleLabelId = `${generated}-scale-label`;
+    const commentId = `${generated}-comment`;
+    const sending = status?.state === 'sending';
+    const [files, setFiles] = useState([]);
+    const handleSubmit = (event) => {
+        event.preventDefault();
+        const chosen = scale.find((point) => point.id === value);
+        const next = {};
+        if (chosen !== undefined) {
+            next.rating = chosen.id;
+            next.ratingValue = chosen.value;
+        }
+        if (comment !== undefined)
+            next.comment = comment.value ?? '';
+        if (artefact !== undefined)
+            next.files = files;
+        onSubmit(next);
+    };
+    return (_jsx(Section, { "data-slot": "feedback-01", className: cn(className), children: _jsxs("div", { "data-slot": "feedback-01-body", className: "flex flex-col gap-8", children: [_jsx(SectionHeading, { eyebrow: eyebrow, title: title, description: description, align: "left", as: headingLevel }), _jsx(Card, { "data-slot": "feedback-01-panel", children: _jsxs("form", { "data-slot": "feedback-01-form", onSubmit: handleSubmit, className: "flex w-full flex-col gap-6", children: [_jsxs(CardContent, { "data-slot": "feedback-01-fields", className: "flex flex-col gap-6", children: [_jsxs(Field, { "data-slot": "feedback-01-scale", className: "gap-2", children: [_jsx("span", { id: scaleLabelId, "data-slot": "feedback-01-scale-label", className: "text-foreground text-sm leading-none font-medium", children: scaleLabel }), _jsx(RadioGroup, { "aria-labelledby": scaleLabelId, value: value, onValueChange: onValueChange, className: "flex w-full flex-wrap gap-2", children: scale.map((point) => (_jsxs(FieldLabel, { htmlFor: `${generated}-${point.id}`, className: "border-input hover:border-primary focus-within:border-ring inline-flex cursor-pointer items-center gap-2 rounded-md border px-3 py-2", children: [_jsx(RadioGroupItem, { value: point.id, id: `${generated}-${point.id}` }), point.label] }, point.id))) })] }), comment === undefined ? null : (_jsxs(Field, { "data-slot": "feedback-01-comment", children: [_jsx(FieldLabel, { htmlFor: commentId, children: comment.label }), _jsx(Textarea, { id: commentId, rows: 4, value: comment.value, maxLength: comment.maxLength, onChange: comment.onValueChange
+                                                    ? (event) => comment.onValueChange?.(event.target.value)
+                                                    : undefined }), comment.counter === true ? (_jsx("span", { "data-slot": "feedback-01-counter", className: "text-muted-foreground self-end text-xs tabular-nums", children: comment.maxLength === undefined
+                                                    ? countOf(comment.value ?? '')
+                                                    : `${countOf(comment.value ?? '')} / ${countOf(String(comment.maxLength))}` })) : null] })), artefact === undefined ? null : (_jsxs(Field, { "data-slot": "feedback-01-artefact", className: "gap-3", children: [_jsx(Dropzone, { label: artefact.label, onFiles: (chosen) => {
+                                                    setFiles(chosen);
+                                                    artefact.onFiles(chosen);
+                                                }, ...(artefact.accept === undefined ? null : { accept: artefact.accept }) }), _jsx(FileUpload, { files: files.map((file, index) => ({
+                                                    id: `${file.name}-${file.size}-${index}`,
+                                                    name: file.name,
+                                                    size: file.size,
+                                                })) })] }))] }), _jsxs(CardFooter, { "data-slot": "feedback-01-actions", className: "flex-col items-stretch gap-3 sm:flex-row sm:items-center", children: [_jsx(Button, { "data-slot": "feedback-01-submit", type: "submit", disabled: sending, children: submitLabel }), cancel === undefined ? null : cancel, _jsx(LiveRegion, { politeness: status?.state === 'error' ? 'assertive' : 'polite', busy: sending, className: "ml-auto text-sm", children: status?.message })] })] }) })] }) }));
+}
+export default Feedback01;

package/dist/blocks/feedback-01/index.d.ts

@@ -0,0 +1,3 @@
+export { Feedback01, default } from './feedback.js';
+export type { Feedback01Artefact, Feedback01Comment, Feedback01Point, Feedback01Props, Feedback01Status, FeedbackValue, } from './feedback.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/blocks/feedback-01/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/blocks/feedback-01/index.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,YAAY,CAAA;AAKhD,YAAY,EACV,kBAAkB,EAClB,iBAAiB,EACjB,eAAe,EACf,eAAe,EACf,gBAAgB,EAChB,aAAa,GACd,MAAM,YAAY,CAAA"}

package/dist/blocks/feedback-01/index.js

@@ -0,0 +1 @@
+export { Feedback01, default } from './feedback.js';

package/dist/blocks/field-map-01/field-map.d.ts

@@ -0,0 +1,247 @@
+import { type ReactNode } from 'react';
+import { type HeadingLevel } from '../../components/ui/section.js';
+/**
+ * The four states a mapped field can be in, and the tone each one draws.
+ *
+ * The states are the caller's, the tone is this Block's, and the split is the
+ * whole design for the same reason it is the design in `StatusLedger01`: a tone
+ * is a colour and colour is not information a reader can act on, while the words
+ * are the information and the words belong to the product. Out loud, because a
+ * caller picking a state needs to know what they are picking: `mapped` is a field
+ * that lands in the target under the same name, `unmapped` is one with no
+ * counterpart there yet, `transformed` is one that lands under a different name
+ * or in a different shape, and `excluded` is one deliberately not carried across
+ * at all. Four, and the fifth would be the one that splits a state that does not
+ * need splitting, which is a colour a reader has to learn and a word a maintainer
+ * has to keep true.
+ */
+export type FieldMapState = 'mapped' | 'unmapped' | 'transformed' | 'excluded';
+/**
+ * The columns of the detail table a caller can name, beyond the two systems.
+ *
+ * `source` and `target` are deliberately not members. See `FieldMapColumnId`.
+ */
+export type FieldMapColumnId = 'required' | 'type' | 'transform' | 'state' | 'note';
+/**
+ * One of the caller's own columns: which part of the row fills the cell, and
+ * what the column is called in the caller's own words.
+ *
+ * The shape follows `DataTableColumn` with the `cell` function dropped, and the
+ * reason is worth stating because it is the one place this Block and that one
+ * look alike and are not the same. `DataTable01` takes a render function per
+ * column because it has no idea what a row contains. This Block knows the seven
+ * fields a row has, so a caller that could write a `cell` function could draw
+ * this table without this Block, and shipping the function would have been an
+ * invitation to do exactly that. What is left is the part that is genuinely the
+ * caller's: the name of the column, its order, and where it sits.
+ */
+export type FieldMapColumn = {
+    /** Which part of the row fills the cell. */
+    id: FieldMapColumnId;
+    /** The column heading, in the caller's own words. */
+    header: ReactNode;
+    /** Layout classes for the column, for alignment or a fixed width. */
+    className?: string;
+};
+/**
+ * One row: a field at the source, what it becomes at the target, and the facts
+ * about the move.
+ */
+export type FieldMapRow = {
+    /** A stable key for the row. */
+    id: string;
+    /**
+     * The field's name at the source, exactly as the source system spells it. It
+     * is the row's identity, so it is the row head, and it is set in the mono face
+     * because a field name is a name in an alphabet a machine reads.
+     */
+    source: string;
+    /**
+     * The field's name at the target. Omit it for a field with no counterpart
+     * there yet, and the cell renders `unmappedLabel` rather than a dash.
+     */
+    target?: string;
+    /**
+     * Whether the target will not accept the row without it. Omit it for a field
+     * whose requiredness has not been decided, and the cell renders nothing rather
+     * than guessing either way.
+     */
+    required?: boolean;
+    /** The field's type at the source, in the source system's own words. */
+    type?: string;
+    /** What has to happen to the value on the way across. */
+    transform?: ReactNode;
+    /** Anything else the reader needs before acting on the row. */
+    note?: ReactNode;
+    /**
+     * The state the field is in. Omit it and the row's own data settles it, which
+     * is a restatement rather than a claim: a field with a target has been mapped
+     * and a field without one has not.
+     */
+    state?: FieldMapState;
+};
+/**
+ * The props a FieldMap01 takes.
+ *
+ * Every string is a prop and the Block ships none. There is no source system, no
+ * target system, no set of states, no column headings and no wording for a field
+ * that has not been mapped yet, and the absence of the first two is the sharpest
+ * version of the rule: a mapping table is a document about two named systems, and
+ * a Block that named either of them would hand every consumer a table about
+ * somebody else's estate.
+ */
+export type FieldMap01Props = {
+    /** Optional label above the section title. See the No-Default-Eyebrow Rule. */
+    eyebrow?: string;
+    /** The section title. Required, because a table with no heading is an orphan. */
+    title: ReactNode;
+    /** One or two sentences under the title. */
+    description?: ReactNode;
+    /**
+     * The caller's own columns, in the order they should be read.
+     *
+     * The two system columns are not in this list and cannot be: the Block renders
+     * those itself from `sourceLabel` and `targetLabel`, so a `columns` entry that
+     * named one of them would be an entry the table ignores, which is a list whose
+     * contents are not the table. Everything else this Block knows how to fill is
+     * named here, and a caller who wants two of them can have both.
+     */
+    columns: readonly FieldMapColumn[];
+    /** The rows, in the order a reader should act on them. Order is the caller's. */
+    rows: readonly FieldMapRow[];
+    /**
+     * The name of the source system, and the heading over the first column.
+     *
+     * Required, and required together with `targetLabel` rather than on its own,
+     * because the two columns are the two systems. See the Component JSDoc.
+     */
+    sourceLabel: string;
+    /**
+     * The name of the target system, and the heading over the second column.
+     *
+     * Required for the same reason and in the same breath.
+     */
+    targetLabel: string;
+    /**
+     * The words for a state, given the state and the field it belongs to.
+     *
+     * Required rather than optional because the Block always resolves a state, and
+     * an unresolved state would be a dot with no sentence beside it.
+     */
+    stateLabel: (state: FieldMapState, source: string) => string;
+    /**
+     * The words for whether the target will not accept the row without the field.
+     *
+     * Required rather than optional for the same reason `stateLabel` is: the cell
+     * is a mark plus a sentence, and the mark alone is a coloured dot that a
+     * reader who cannot see the tone has learned nothing from.
+     */
+    requiredLabel: (required: boolean) => string;
+    /**
+     * What the target cell says for a field that has no counterpart there yet.
+     *
+     * Required, and a slot rather than a string, because the two answers are not the
+     * same sentence: one is a task waiting to be done and the other is a decision
+     * that was made. The cell renders this rather than a dash because a mapping
+     * table is a document somebody acts on, and an empty cell is a thing to do
+     * while a dash is a piece of typography.
+     */
+    unmappedLabel: ReactNode;
+    /**
+     * Heading level for the section title. @defaultValue 'h2'
+     *
+     * See `HeadingLevel`.
+     */
+    headingLevel?: HeadingLevel;
+    /**
+     * Layout only, exactly as on every Block. Changing a Prism-owned visual
+     * property from here is prohibited.
+     */
+    className?: string;
+};
+/**
+ * A source-to-target field mapping: what a field is called on one side, what it
+ * becomes on the other, whether it is required, what type it is, and what has to
+ * happen to the value.
+ *
+ * **This is the artefact a pipeline and an estate both produce, and it is why the
+ * Block is a Block rather than a component.** A component is a control with one
+ * job. This is a section: a heading, a paragraph of why the table is here, and a
+ * document a reader works down row by row, and it composes `Section`,
+ * `SectionHeading`, `Status` and the `Table` parts. A consumer whose data is a
+ * mapping and a consumer whose data is a data dictionary are drawing the same
+ * table, and the difference between their two tables is the names in two cells.
+ *
+ * **The two system names are required together, and the reason is that the two
+ * columns are the two systems.** A mapping table's whole content is the
+ * correspondence between one named thing and another, and a header that says
+ * "Source" on the left and "Destination" on the right has thrown both names away
+ * and replaced them with the shape of the operation. That table is not useless,
+ * it is worse than useless, because it reads correctly in the deployment where
+ * the two systems happen to be obvious and is misread in every deployment where
+ * they are not, and nobody catches it because the table looks finished. A reader
+ * holding "Customer__c" on the left and "buyer_ref" on the right, with no system
+ * named, has to guess which way the migration runs, and a migration run backwards
+ * is the single most expensive mistake this document can cause. So the Block asks
+ * for both names, asks for them together, and refuses one without the other: a
+ * table with a source name and a generic destination name is the half-answered
+ * case, and it is worse than a compile error because it renders. Prism will not
+ * name either system itself, because Prism does not know whether the consumer is
+ * moving from a CRM into a warehouse or out of one into a CRM, and printing the
+ * wrong pair in the other direction would be a confident answer to a question it
+ * cannot see.
+ *
+ * **The four states use the `Status` tones, and the words are the caller's
+ * through a required `stateLabel`.** Out loud, because a caller choosing a state
+ * needs to know what the colours mean before they choose: `mapped` lands in the
+ * target under the same name and is drawn `success`, `unmapped` has no
+ * counterpart there yet and is drawn `warning`, `transformed` lands under a
+ * different name or in a different shape and is drawn `info`, and `excluded` was
+ * deliberately left behind and is drawn `neutral`. Every one of those dots is
+ * `aria-hidden` and the words beside it are not, so a reader who cannot separate
+ * `warning` from `destructive` still reads which is which, which is also why the
+ * state list can stay as small as it is. `stateLabel` takes the field's name as
+ * well as the state, because a mapping table is read one row at a time and a
+ * reader who has navigated to a cell needs to know which field they are in, and
+ * because the honest sentence is per row in most of them: "not carried across",
+ * "renamed on the way in", "held back pending a decision about the buyer".
+ *
+ * **A row with no target renders the caller's `unmappedLabel`, and that is the
+ * decision this Block is most particular about.** The obvious thing in an empty
+ * table cell is a dash, and the dash is wrong here for a reason that has nothing
+ * to do with taste. A mapping table is a document somebody acts on: it is the
+ * thing an engineer reads before a migration and a reviewer reads during one, and
+ * a field with no counterpart is a task, not an absence. An em dash says the
+ * author had nothing to say, and the reader who believes it files the row as done.
+ * The caller's own words say what the row actually is, which is either a thing
+ * still to be done or a decision already taken, and those are opposite actions on
+ * the same empty cell. A slot rather than a string, because the two sentences are
+ * not variants of one.
+ *
+ * **The two system columns are not in `columns`, and that is a closed set rather
+ * than an omission.** `columns` names the caller's own headings for the rest of
+ * the table and the order they are read in, which is genuinely the caller's
+ * decision. The two system headings are not, because the Block already has them
+ * in `sourceLabel` and `targetLabel` and a list that could also name them would
+ * be a list with two entries the table ignores. A caller who has to look at a
+ * list and ask which of its entries is being dropped has been handed a list that
+ * does not describe the thing, and the type here is how that is prevented rather
+ * than a comment asking them to be careful.
+ *
+ * **It is a real table, and that is the accessibility claim.** The header cells
+ * are `<th scope="col">` and the field name is a `<th scope="row">`, so a reader
+ * navigating by cell hears which column and which field every value belongs to,
+ * and a reader moving by row hears the field before the values under it. The
+ * alternative was a grid of `div`s with `role="presentation"` and a caption, and
+ * it is the arrangement most hand-written mapping tables use, because it is easier
+ * to make responsive. What it costs is that the correspondence between a value
+ * and its field is then a position, and a position is the one thing a screen
+ * reader, a crawler and a print stylesheet cannot read.
+ *
+ * It is a server Component: no hook, no state, no client code and no router. The
+ * table is markup, so a mapping document costs a consumer nothing in client
+ * JavaScript and reads identically with scripting off.
+ */
+export declare function FieldMap01({ eyebrow, title, description, columns, rows, sourceLabel, targetLabel, stateLabel, requiredLabel, unmappedLabel, headingLevel, className, }: FieldMap01Props): import("react").JSX.Element | null;
+export default FieldMap01;
+//# sourceMappingURL=field-map.d.ts.map

package/dist/blocks/field-map-01/field-map.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"field-map.d.ts","sourceRoot":"","sources":["../../../src/blocks/field-map-01/field-map.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAS,KAAK,SAAS,EAAE,MAAM,OAAO,CAAA;AAE7C,OAAO,EAA2B,KAAK,YAAY,EAAE,MAAM,6BAA6B,CAAA;AAYxF;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,aAAa,GAAG,QAAQ,GAAG,UAAU,GAAG,aAAa,GAAG,UAAU,CAAA;AAqB9E;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG,UAAU,GAAG,MAAM,GAAG,WAAW,GAAG,OAAO,GAAG,MAAM,CAAA;AAEnF;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,4CAA4C;IAC5C,EAAE,EAAE,gBAAgB,CAAA;IACpB,qDAAqD;IACrD,MAAM,EAAE,SAAS,CAAA;IACjB,qEAAqE;IACrE,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,CAAA;AAED;;;GAGG;AACH,MAAM,MAAM,WAAW,GAAG;IACxB,gCAAgC;IAChC,EAAE,EAAE,MAAM,CAAA;IACV;;;;OAIG;IACH,MAAM,EAAE,MAAM,CAAA;IACd;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;IACf;;;;OAIG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,wEAAwE;IACxE,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,yDAAyD;IACzD,SAAS,CAAC,EAAE,SAAS,CAAA;IACrB,+DAA+D;IAC/D,IAAI,CAAC,EAAE,SAAS,CAAA;IAChB;;;;OAIG;IACH,KAAK,CAAC,EAAE,aAAa,CAAA;CACtB,CAAA;AAqBD;;;;;;;;;GASG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,+EAA+E;IAC/E,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,iFAAiF;IACjF,KAAK,EAAE,SAAS,CAAA;IAChB,4CAA4C;IAC5C,WAAW,CAAC,EAAE,SAAS,CAAA;IACvB;;;;;;;;OAQG;IACH,OAAO,EAAE,SAAS,cAAc,EAAE,CAAA;IAClC,iFAAiF;IACjF,IAAI,EAAE,SAAS,WAAW,EAAE,CAAA;IAC5B;;;;;OAKG;IACH,WAAW,EAAE,MAAM,CAAA;IACnB;;;;OAIG;IACH,WAAW,EAAE,MAAM,CAAA;IACnB;;;;;OAKG;IACH,UAAU,EAAE,CAAC,KAAK,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,KAAK,MAAM,CAAA;IAC5D;;;;;;OAMG;IACH,aAAa,EAAE,CAAC,QAAQ,EAAE,OAAO,KAAK,MAAM,CAAA;IAC5C;;;;;;;;OAQG;IACH,aAAa,EAAE,SAAS,CAAA;IACxB;;;;OAIG;IACH,YAAY,CAAC,EAAE,YAAY,CAAA;IAC3B;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkFG;AACH,wBAAgB,UAAU,CAAC,EACzB,OAAO,EACP,KAAK,EACL,WAAW,EACX,OAAO,EACP,IAAI,EACJ,WAAW,EACX,WAAW,EACX,UAAU,EACV,aAAa,EACb,aAAa,EACb,YAAmB,EACnB,SAAS,GACV,EAAE,eAAe,sCAwHjB;AAqBD,eAAe,UAAU,CAAA"}