@nanisoft/prism-ui 0.13.0 → 0.16.0

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

@@ -0,0 +1,285 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useId } from 'react';
+import { CtaLink } from '../../components/ui/cta-link.js';
+import { Metric } from '../../components/ui/metric.js';
+import { Price } from '../../components/ui/price.js';
+import { Section, SectionHeading, } from '../../components/ui/section.js';
+import { Status } from '../../components/ui/status.js';
+import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow, } from '../../components/ui/table.js';
+import { cn } from '../../lib/utils.js';
+/**
+ * The tone each of the four states is drawn in, from the semantic contract and no
+ * other.
+ */
+const STATE_TONE = {
+    settled: 'success',
+    pending: 'info',
+    refunded: 'neutral',
+    disputed: 'destructive',
+};
+/**
+ * The classes each cell takes, before the caller's own layout classes merge in.
+ *
+ * Only the reference wraps, and the reason is the one `FieldMap01` gives for its
+ * two prose columns: `table.tsx` sets every cell to `whitespace-nowrap` so a
+ * column of numbers lines up, and a reference is whatever the caller's ledger
+ * made it, which is sometimes a long one. A table that scrolls an identifier
+ * sideways to keep it on one line is a table nobody reads a whole row of.
+ */
+const CELL = {
+    at: 'text-muted-foreground whitespace-nowrap',
+    reference: 'font-mono text-xs whitespace-normal',
+    kind: 'text-muted-foreground whitespace-normal',
+    quantity: 'text-muted-foreground whitespace-nowrap tabular-nums',
+    amount: 'text-right whitespace-nowrap',
+    state: 'whitespace-nowrap',
+    link: 'text-right whitespace-nowrap',
+};
+/**
+ * The refusals, checked before anything is drawn so a caller's mistake is one
+ * diagnostic in a console rather than a nameless control on a page.
+ *
+ * Five, and each one is a row that would be unreadable rather than ugly. A state
+ * with no words, because a coloured dot is invisible to a reader who cannot
+ * separate the tones and unreadable to a screen reader whatever the tones are. A
+ * quantity with no unit, because `1204` beside a price is a number nobody can act
+ * on and a reader's next question is always what the number counts. A link with
+ * no words, or a name with no link beside it. A moment the platform cannot read,
+ * so there is no value to put in the `time` element and the row would claim to be
+ * a moment it cannot name. And a set of columns this Block cannot fill, which is
+ * either an empty one or a header row a reader counts rather than reads.
+ */
+function assertHistory(columns, entries) {
+    const seen = new Set();
+    for (const column of columns) {
+        if (seen.has(column.id)) {
+            throw new Error(`History01: the column ${JSON.stringify(column.id)} is declared twice, so the table would have two ` +
+                'columns reading the same value and every cell after the first would be read under the wrong name. ' +
+                'Declare each cell once.');
+        }
+        if (column.id === 'quantity' && !entries.some((entry) => entry.quantity !== undefined)) {
+            throw new Error('History01: the "quantity" column was declared and no line passed a quantity, so the table would carry ' +
+                'a column of empty cells, which is a column every reader scans twice. Pass the quantities, or drop the ' +
+                'column.');
+        }
+        if (column.id === 'link' && !entries.some((entry) => entry.href !== undefined)) {
+            throw new Error('History01: the "link" column was declared and no line passed an href, so the table would carry a ' +
+                'column of empty cells. Pass the destinations, or drop the column.');
+        }
+        seen.add(column.id);
+    }
+    if (!seen.has('reference')) {
+        throw new Error('History01: the columns name no "reference" cell, so the header row would have a cell fewer than every ' +
+            'body row and a reader who landed on one cell would not be told which charge they are looking at. ' +
+            'Declare the reference column, which is also the row header for every row.');
+    }
+    for (const entry of entries) {
+        if (entry.stateLabel === undefined || entry.stateLabel.trim() === '') {
+            throw new Error(`History01: the line ${JSON.stringify(entry.reference)} declares a state and no words for it, so the ` +
+                'tone would be a coloured dot with no sentence beside it, in a record a reader may have to show to ' +
+                'somebody else. Pass stateLabel in the vocabulary this product uses, which is not this Block choice.');
+        }
+        if ((entry.href === undefined) !== (entry.hrefLabel === undefined)) {
+            throw new Error(`History01: the line ${JSON.stringify(entry.reference)} declares one of href and hrefLabel without ` +
+                'the other, so the row would carry a link with no words on it, or a name with no link beside it. ' +
+                'Pass the words that say what following it does, or omit the href.');
+        }
+        if (!Number.isFinite(new Date(entry.at).getTime())) {
+            throw new Error(`History01: the line ${JSON.stringify(entry.reference)} passes an at the platform cannot read, so there ` +
+                'is no value to put in the time element and the row would claim to be a moment it cannot name. Pass ' +
+                'epoch milliseconds, or a string the platform parses.');
+        }
+        if (entry.quantity !== undefined && entry.quantityLabel === undefined) {
+            throw new Error(`History01: the line ${JSON.stringify(entry.reference)} passes a quantity and no quantityLabel, so the ` +
+                'cell would hold a bare number beside a price, and a bare number is a number nobody can act on. Pass ' +
+                'the words this product uses for the unit, given the value and the line.');
+        }
+    }
+}
+/**
+ * What a workspace has been charged for and what it has consumed: a moment, a
+ * reference, a kind, an amount, a quantity, a state and a link, in a real table,
+ * under an optional summary of the period.
+ *
+ * **The storefront version of this pattern is an order history, and the pattern is
+ * the same one.** A shop shows a shopper what they bought, when, how much and
+ * whether it settled. What changes here is what the rows are: a workspace is
+ * charged for runs it triggered, capture volume it stored and agent minutes it
+ * burned, and the same record is read from the other side to answer what it has
+ * consumed. There is no shop and no basket anywhere in this Block, and a reader
+ * who has used both will recognise the shape and none of the vocabulary, which is
+ * the point: the columns are the caller's, the kinds are the caller's, the state
+ * words are the caller's, and the only thing this Block contributes is the
+ * rectangle they sit in.
+ *
+ * **It is a real table, and the reference is its row header.** A history is read
+ * by comparing: which month cost the most, how many runs are in that line, which
+ * reference keeps appearing. Comparison is what a table is for and it is what a
+ * grid of `div`s cannot do, because a `div` grid has no `th` to navigate by, no
+ * association between a row and its cells, and nothing for a browser's own table
+ * commands to act on. So every header is a `th` with `scope="col"` and the
+ * reference is a `th` with `scope="row"`, which is the cell a caller can rely on
+ * being present because `reference` is required on every entry. The rejected
+ * alternative was a `DataTable01`, which is the same table with a `cell` function
+ * per column and a full toolbar of its own; this is that table for the seven cells
+ * a history has, which means a caller cannot add an eighth and gets a row header
+ * for free.
+ *
+ * **The reference is set in the mono face, for the reason `SectionHeading` states
+ * for its own `index` prop.** That prop's documentation says a section's position
+ * in a sequence is machine notation rather than a word, and the mono stack is what
+ * this repository annotates machine-readable values with. A billing reference is
+ * the same kind of value by a stronger margin: it is copied, compared, quoted to
+ * support and typed, and it is the one cell on the row a reader may read aloud. A
+ * reference set in the interface face reads as a word somebody chose, and the
+ * difference is the difference between an identifier and a name. The cost is a
+ * row whose reference is a hand-written phrase rather than a code, and a caller
+ * who has one should put the phrase in `kind` where it belongs.
+ *
+ * **The order is the caller's and the Block never sorts, and on this surface that
+ * is not a nicety.** An audit trail that a Block reordered would be a claim about
+ * which record came first, and on a billing surface the same claim is a bill: a
+ * line moved above another one is a different statement about when a workspace was
+ * charged. Every other Block in this package refuses to sort because order is a
+ * claim about importance, and here it is a claim about fact, which is why the cost
+ * is named rather than implied. A ledger whose records arrive out of order has a
+ * problem, and the honest answers are to sort once at the store with a stable
+ * comparison on the moment plus the record's own sequence, or to pass them through
+ * and let the table read as it was received. Both are decisions about a system's
+ * truth, and a Block that made either one on the caller's behalf would be inserting
+ * itself into a financial record. A caller who wants newest first sorts once,
+ * upstream, and the Block draws what it was given in the order it was given it.
+ *
+ * **A state needs the caller's words and the run throws without them.** That is
+ * `StatusLedger01`'s argument with nothing added: the state is a colour and the
+ * words are the information, and a publisher that says "reversed" where another's
+ * says "credited back" cannot be given one vocabulary by a design system. A
+ * missing label throws rather than falling back to the union's own name, which
+ * would print `refunded` into a financial record as if it were a term of art, and
+ * a financial record is the last place a bare machine word belongs.
+ *
+ * **A quantity needs the caller's words too, and the reason is narrower.** A
+ * quantity on a billing line is never a bare number in a product anybody would
+ * ship: it is a count of runs, a count of gigabytes, a count of minutes, and the
+ * unit is the whole of what the number means. `1204` beside a price is a number a
+ * reader cannot act on, and their next question is always what it counts, so the
+ * reading is a function of the value and the line. The entry is in the argument
+ * because a history holds more than one unit: a metered line counts runs and a
+ * storage line counts gigabytes, and a Block that chose between them would be
+ * choosing which product this table is for.
+ *
+ * **The amount composes `Price` rather than printing a currency, and the moment
+ * prints exactly as passed.** A symbol says the currency and nothing else, while
+ * an amount also has a currency code, a precision, a period and a locale, and
+ * `Intl` already knows all four; a history that hardcoded a dollar sign would make
+ * a claim about every consumer's market. The moment goes the other way: a Block
+ * that formatted a date would be choosing a locale, a calendar and a granularity
+ * on a reader's behalf, so the value is printed as given and the ISO form goes on
+ * the `time` element, which means a caller who holds "the March invoice period"
+ * can pass exactly that. The cost of printing as given is a raw timestamp beside
+ * a price for a caller who passes milliseconds and no formatter, which is honest
+ * and almost never what was wanted.
+ *
+ * **The summary composes `Metric` and draws no card titles.** A period summary is
+ * figures, and `Metric` already owns the arrangement a figure is read in: the
+ * figure lands first and the name sits under it, and a string value is set in the
+ * mono face while a composed one is not. The cost is the one `Metric` states, and
+ * it is worth naming here because a caller will meet it on a billing page: a
+ * `delta` with no `deltaFormat` prints the bare number, because a Component cannot
+ * print a change it has no unit for. A caller who has a formatted change passes
+ * the reading as `value` and leaves `delta` off, which is the same amount of work
+ * and one fewer prop.
+ *
+ * **An empty history draws the caller's sentence and no table.** A table of
+ * column heads with no rows is a grid a reader looks through, and on this surface
+ * it is worse than that: a billing table with headers and nothing in it reads as a
+ * statement that was truncated rather than as a period with nothing in it. The
+ * cost is that a heading can survive on a page whose history has been purged, and
+ * a consumer who would rather see nothing at all should not render the Block.
+ *
+ * It is a server Component: no hook, no state, no client code and no router. The
+ * toolbar and the summary are the caller's own nodes, so a consumer who passes a
+ * client toolbar pays for the toolbar and not for the history.
+ */
+export function History01({ eyebrow, title, description, columns, entries, summary, toolbar, empty, headingLevel = 'h2', className, }) {
+    // The handle a table below takes its name from; see the note on the table.
+    const headingId = useId();
+    if (columns.length === 0) {
+        throw new Error('History01: columns is empty, so the history would be a table with no named columns, which is a grid of ' +
+            'amounts with nothing to check them against. Name the columns in the order they should be read.');
+    }
+    /*
+      The empty case is decided before the per-entry diagnostics rather than after
+      them, and the reason is that two of those diagnostics are about columns no row
+      fills. A period with nothing in it has no quantity to put under a quantity
+      column, and running that check over an empty array would fail a caller for the
+      one state in which the table is not drawn at all.
+    */
+    if (entries.length === 0) {
+        return (_jsxs(Section, { "data-slot": "history-01", className: className, children: [_jsx(SectionHeading, { as: headingLevel, id: headingId, align: "left", eyebrow: eyebrow, title: title, description: description }), _jsx("div", { "data-slot": "history-01-empty", className: "text-muted-foreground text-sm", children: empty })] }));
+    }
+    assertHistory(columns, entries);
+    return (_jsxs(Section, { "data-slot": "history-01", className: className, children: [_jsx(SectionHeading, { as: headingLevel, id: headingId, align: "left", eyebrow: eyebrow, title: title, description: description, className: "mb-10" }), _jsxs("div", { "data-slot": "history-01-body", className: "flex flex-col gap-8", children: [summary === undefined || summary.length === 0 ? null : (
+                    /*
+                      The period summary, in a grid rather than in a row, because a figure
+                      with a name under it is a tile and four tiles in a row of a 68rem
+                      container leave each one about sixteen. The cost is that the row wraps
+                      on a phone, which is the right thing for a figure rather than the wrong
+                      thing, and the grid is one track per figure rather than a count this
+                      Block chooses, because a summary of two and a summary of six are both
+                      real and neither is a mistake.
+                    */
+                    _jsx("div", { "data-slot": "history-01-summary", className: "grid gap-6 sm:grid-cols-2 lg:grid-cols-4", children: summary.map((item) => (_jsx(Metric, { "data-slot": "history-01-figure", value: item.value, label: item.label, delta: item.delta }, item.label))) })), toolbar === undefined ? null : (_jsx("div", { "data-slot": "history-01-toolbar", className: "flex flex-wrap items-center gap-3", children: toolbar })), _jsx("div", { "data-slot": "history-01-table-frame", className: "border-border overflow-hidden rounded-xl border", children: _jsxs(Table, { "aria-labelledby": headingId, "data-slot": "history-01-table", children: [_jsx(TableHeader, { children: _jsx(TableRow, { children: columns.map((column) => (_jsx(TableHead, { scope: "col", className: column.className, children: column.header }, column.id))) }) }), _jsx(TableBody, { children: entries.map((entry) => (_jsx(TableRow, { "data-slot": "history-01-entry", "data-entry": entry.id, children: columns.map((column) => (_jsx(Cell, { column: column, entry: entry }, column.id))) }, entry.id))) })] }) })] })] }));
+}
+/**
+ * The one cell of one row, and the whole of this Block's switch over a closed set.
+ *
+ * A switch rather than a map of render functions, for the reason `FieldMap01`
+ * gives: a map keyed by cell id would be a second recipe of the kind this package
+ * keeps off the public surface, and a switch over seven cases is the same table
+ * with the strings in the same file as the drawing that uses them.
+ *
+ * The reference is a `TableHead` with `scope="row"` rather than a cell, so a
+ * reader who navigates into a single cell is told which charge they are looking
+ * at rather than hearing an amount with nothing to attach it to. That is also why
+ * the class list sets the ink and the weight explicitly: `TableHead` carries the
+ * muted header ink and the header weight, and a row header in the row's own ink
+ * is a different thing from a column header that happens to be in the first
+ * column.
+ */
+function Cell({ column, entry }) {
+    const key = column.id;
+    const classes = cn(CELL[key], column.className);
+    if (key === 'reference') {
+        return (_jsx(TableHead, { scope: "row", className: cn(classes, 'text-foreground font-normal'), children: entry.reference }));
+    }
+    if (key === 'at') {
+        return (_jsx(TableCell, { className: classes, children: _jsx("time", { dateTime: new Date(entry.at).toISOString(), children: entry.at }) }));
+    }
+    if (key === 'kind') {
+        return _jsx(TableCell, { className: classes, children: entry.kindLabel ?? entry.kind });
+    }
+    if (key === 'amount') {
+        return (_jsx(TableCell, { className: classes, children: _jsx(Price, { ...entry.amount, size: "sm" }) }));
+    }
+    if (key === 'quantity') {
+        if (entry.quantity === undefined)
+            return _jsx(TableCell, { className: classes });
+        return (_jsx(TableCell, { className: classes, children: entry.quantityLabel === undefined
+                ? entry.quantity
+                : entry.quantityLabel(entry.quantity, { id: entry.id, reference: entry.reference }) }));
+    }
+    if (key === 'state') {
+        /*
+          The two are narrowed rather than asserted. The diagnostic in `assertHistory`
+          has already refused a state with no words, so this condition cannot be false
+          here, and spelling it out means the types read the same rule the runtime does
+          rather than a non-null assertion standing in for it.
+        */
+        if (entry.stateLabel === undefined)
+            return _jsx(TableCell, { className: classes });
+        return (_jsx(TableCell, { className: classes, children: _jsx(Status, { size: "sm", tone: STATE_TONE[entry.state], label: entry.stateLabel }) }));
+    }
+    return (_jsx(TableCell, { className: classes, children: entry.href === undefined || entry.hrefLabel === undefined ? null : (_jsx(CtaLink, { href: entry.href, variant: "ghost", size: "sm", children: entry.hrefLabel })) }));
+}
+export default History01;

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

@@ -0,0 +1,3 @@
+export { History01, default } from './history-01.js';
+export type { History01Props, HistoryColumn, HistoryColumnId, HistoryEntry, HistoryState, HistorySummaryItem, } from './history-01.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/blocks/history-01/index.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAKjD,YAAY,EACV,cAAc,EACd,aAAa,EACb,eAAe,EACf,YAAY,EACZ,YAAY,EACZ,kBAAkB,GACnB,MAAM,cAAc,CAAA"}

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

@@ -0,0 +1 @@
+export { History01, default } from './history-01.js';

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

@@ -0,0 +1,349 @@
+import { type ReactNode } from 'react';
+import { type HeadingLevel } from '../../components/ui/section.js';
+/**
+ * How pressing a queue is one of four things, and the tone each one is drawn in.
+ *
+ * The four are a queue's whole vocabulary and they are not a severity ladder, which
+ * is why the tones are not in order: `urgent` is a judgement about lateness, `new`
+ * is a fact about age, and a queue where everything is urgent is a queue where
+ * nothing is. `urgent` takes the destructive tone because it is the one state a
+ * reader must not miss, `high` takes warning because it is the one they should
+ * reach for soon, `normal` takes the cool role that means not an alarm, and `low`
+ * takes the muted ink because nothing is being asked of the reader.
+ *
+ * A fifth would be the one that splits a state that does not need splitting, and
+ * each such tier is a colour a reader must learn and a word a maintainer must keep
+ * true. The words themselves are the caller's; see `InboxItem.priorityLabel`.
+ */
+export type InboxPriority = 'low' | 'normal' | 'high' | 'urgent';
+/**
+ * The four states one queued item can be in, and the tone each one is drawn in.
+ *
+ * `new` is unread, `open` is being worked, `waiting` is with somebody else, and
+ * `done` is finished. The tones are the same four in the same order as a reader
+ * would sort them by how much they care: `new` is the cool role, `open` is muted,
+ * `waiting` is warning because it is a queue a reader cannot advance alone, and
+ * `done` is success because it is the only state that is finished.
+ *
+ * `done` is in this list rather than removed, and the row stays in the table, so a
+ * reader can see what a queue has already absorbed. Removing the row would make a
+ * queue look emptier every time it worked.
+ */
+export type InboxState = 'new' | 'open' | 'waiting' | 'done';
+/**
+ * The six cells a row can draw, and the six column names a caller names them with.
+ *
+ * A closed set, and the closure is the point: the cells are the Block's, so a table
+ * with a seventh column would be a column with nothing to put in it. The names are
+ * the caller's, which is the other half of the same thing. A queue is drawn by
+ * four products with four vocabularies, and the words a reader needs above the
+ * same column are "Priority" in one and "Urgency" in the next, so `header` is a
+ * prop and `id` is not.
+ */
+export type InboxCell = 'subject' | 'source' | 'priority' | 'at' | 'state' | 'actions';
+/**
+ * One column of a queue: which cell it draws, and the words above it.
+ *
+ * The shape follows `ResourceListColumn` for the reason that type gives: the cells
+ * are closed, so the `cell` function `DataTableColumn` takes is deliberately
+ * dropped, and what is left is genuinely the caller's, which is the column's name,
+ * its order, and where it sits. `className` is layout, for alignment or a fixed
+ * width, and it changes where a column sits and never what a cell looks like.
+ */
+export type InboxColumn = {
+    /** Which of the six cells this column draws. */
+    id: InboxCell;
+    /** The column's name, in the product's own words. */
+    header: ReactNode;
+    /**
+     * Layout classes for the column, applied to the header cell and to every cell
+     * under it.
+     */
+    className?: string;
+};
+/**
+ * One thing waiting for a person, and everything a reader needs to decide whether
+ * to be that person.
+ *
+ * `subject` is the only required field beside `id`, because a row with no subject
+ * is a row nobody can act on. Everything else is optional because a queue is
+ * heterogeneous by nature: some items came from a system that knows its source and
+ * some did not, some are urgent and some are not, and a shape that made every field
+ * required would be a table where two thirds of every row is an empty cell drawn as
+ * a placeholder.
+ */
+export type InboxItem = {
+    /** The item's stable key within the queue. */
+    id: string;
+    /**
+     * What the item is, in the words a reader would use about it.
+     *
+     * It is the row's identity, so it is the row head, and it is also the words on
+     * whatever control opens the item: a link when there is an `href` and a button
+     * when there is an `onSelect`. A subject a reader cannot scan down a column is a
+     * subject that has to be read one row at a time, which is the one thing a queue
+     * is not.
+     */
+    subject: string;
+    /**
+     * Where the item came from, in the product's own words: a system, a form, a
+     * person, a feed.
+     *
+     * Drawn as passed and in the muted ink, and it is the reason the `source` cell
+     * is a column rather than a prefix on the subject: the source is a facet a reader
+     * compares, and a prefix is a facet nobody can scan.
+     */
+    source?: string;
+    /**
+     * How pressing the item is, which is a judgement only the caller can make.
+     *
+     * The Block maps it to a tone and refuses to print the word, because
+     * `urgent` and `waiting` are English and this table ships into operations tools
+     * that are not in English. See `InboxItem.priorityLabel`.
+     */
+    priority?: InboxPriority;
+    /**
+     * The words for the priority, given the priority the caller passed.
+     *
+     * Required whenever `priority` is set and the run fails without it, for the
+     * reason the Component JSDoc on `Status` gives at length: a status with no words
+     * is a coloured dot, and a coloured dot is invisible to a reader who cannot
+     * separate the tones and unreadable to a screen reader whatever the tones are.
+     * The function is a function and not a string because the honest sentence is
+     * usually per priority and per product: "overdue", "drop everything", "P1".
+     */
+    priorityLabel?: (priority: InboxPriority) => string;
+    /**
+     * When the item arrived, in whichever of the three forms the caller holds it.
+     *
+     * Drawn through `relative-time`, so a number arrives as a date in the reader's
+     * own locale and a string is handed to the platform untouched: a date-only key,
+     * an ISO 8601 date-time and a locale's own written date all work and none of
+     * them is interpreted here. The rejected alternative was drawing the value as
+     * passed, which puts a raw epoch on the page for every caller who had
+     * milliseconds, and a queue sorted by nothing is a queue a reader cannot trust.
+     * A caller who wants a relative phrase composes `relative-time` themselves and
+     * passes the node, which is the one case where `at` is not a value.
+     */
+    at?: number | string | ReactNode;
+    /**
+     * Where the item is in its life, which is a judgement only the caller can make.
+     * See `InboxItem.priorityLabel` for why the words are required with it.
+     */
+    state?: InboxState;
+    /** The words for the state, in the product's own vocabulary. */
+    stateLabel?: string;
+    /**
+     * One line about the item, under the subject.
+     *
+     * A node because a queue's second line is not always a sentence: it is a quoted
+     * first line of a message, a diff summary, a product name, a chart. The Block
+     * draws it in the muted ink at one step below the subject and never truncates
+     * it, because a truncated sentence on a queue is a sentence the reader has to
+     * open the item to read anyway.
+     */
+    excerpt?: ReactNode;
+    /**
+     * Where the item goes. Its presence makes the subject render as a native
+     * anchor, so the destination is real and the browser's own link affordances all
+     * work on it.
+     */
+    href?: string;
+    /**
+     * The words on the link beside the subject, and required whenever `href` is.
+     *
+     * A link whose only words are the item's own subject tells a reader nothing
+     * about what activating it does, which is the same defect `Download01` refuses
+     * and for the same reason: the destination is a route in the caller's own
+     * application and only the caller knows what is behind it.
+     */
+    hrefLabel?: string;
+    /**
+     * The controls that act on this one item: assign, defer, dismiss, snooze.
+     *
+     * A slot and not a set of named controls, because which actions a queue has is
+     * the consumer's fact, and a Block that drew a menu would be drawing four
+     * products' ideas of what can be done to a queued item. Each control inside is
+     * the caller's own Component, so this is where a caller composes their own
+     * menu rather than asking the Block to grow one.
+     */
+    actions?: ReactNode;
+};
+/**
+ * The props an Inbox01 takes.
+ *
+ * Every string is a prop and the Block ships none. There is no sample queue, no
+ * column heading, no priority word, no state word, no moment format and no
+ * sentence for an empty set, and the absence of the first is the sharpest version
+ * of the rule: a queue is a claim about what is waiting on a person right now, and
+ * a Block that named one would be publishing somebody else's backlog.
+ */
+export type Inbox01Props = {
+    /** Optional label above the section title. See the No-Default-Eyebrow Rule. */
+    eyebrow?: string;
+    /**
+     * The section title, and required.
+     *
+     * Not optional as the other Blocks' titles are, because a table with no heading
+     * is an orphan and a queue with no heading is a list a reader cannot name.
+     */
+    title: ReactNode;
+    /** One or two sentences under the title. */
+    description?: ReactNode;
+    /**
+     * The items, in the order a reader should act on them.
+     *
+     * Order is the caller's and the Block does not sort, because a queue's order is
+     * a claim about what matters first and a Block that sorted it would be making
+     * that claim on the caller's behalf. A caller who wants it sorted by priority
+     * sorts it before passing it, and a queue whose order is a database query is
+     * not a Block's problem.
+     */
+    items: readonly InboxItem[];
+    /**
+     * The columns, in the order the reader should meet them.
+     *
+     * The `subject` column has to be among them and the run fails without it, for
+     * the reason `ResourceList01` states: a header row with a cell fewer than every
+     * body row is a table a reader cannot read, and the subject is also the row head
+     * every other cell is read under.
+     */
+    columns: readonly InboxColumn[];
+    /**
+     * The row above the table: the caller's own `data-toolbar` with its search, its
+     * filters and its count.
+     *
+     * A slot and not a set of named controls, for the reason `data-toolbar` gives:
+     * which controls a queue has is the consumer's fact, and a Block that drew a
+     * search box and a sort would be a Block that assumed the set is searchable and
+     * sortable. The number of rows the Block was given is drawn at the trailing edge
+     * of the same row, beside whatever the caller passed, and never inside it.
+     */
+    toolbar?: ReactNode;
+    /**
+     * The count, as the caller's own words.
+     *
+     * A node and not a number, and the reason is the one `list-panel` gives for the
+     * same prop on a panel: the sentence around a number belongs to the product.
+     * "12 of 40" is true in one language and false in another, and so is "Showing
+     * archived", and a Block that assembled the sentence would have assembled it in
+     * this package's language, into an operations tool that may not be in English.
+     * Omit it and the row is drawn with nothing at its trailing edge rather than
+     * with a bare numeral, because a bare number beside a search box is a number
+     * with nothing to say what it counts.
+     */
+    count?: ReactNode;
+    /**
+     * Called with an item's `id` when the reader activates that item's subject and
+     * the item has no `href`.
+     *
+     * A callback and not a router, for the reason the whole package holds: a Block
+     * reports an interaction and the consumer decides what it means. An item with an
+     * `href` renders as a link and never calls this, so a caller who wants one
+     * behaviour for the whole queue passes either a destination for every item or
+     * this for every item rather than both and hoping the reader picks correctly.
+     */
+    onSelect?: (id: string) => void;
+    /**
+     * What the Block renders in place of the rows when there are none.
+     *
+     * Required and a node, and the reason is the sharpest one in this file: a reader
+     * who opened a queue and found nothing is reading exactly one line, and that
+     * line is the most load-bearing sentence on the page. "All clear" is a claim,
+     * and it is a different claim in a product where the queue is genuinely empty
+     * and in a product where the query is broken.
+     */
+    empty: 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 queue of things waiting for a person: a priority, a source, a subject, a
+ * moment, a state and a row of controls, in a real table under the caller's own
+ * toolbar.
+ *
+ * **What an inbox is not in this system, and why it is worth saying first.** It is
+ * not a place a queue is fetched, read, refreshed or marked as seen. A Block takes
+ * its content as props and fetches no application data, and that is a law held by
+ * a gate rather than a habit: `packages/ui/scripts/check-block-imports.mjs` fails a
+ * Block that imports a router or a data client or calls a network function. So
+ * this is the frame for a queue the consumer populates. A Block that fetched its
+ * own queue would have to be reimplemented by every consumer whose queue lives
+ * somewhere else, and there is no version of that which is not a fork: four
+ * consumers with four stores would each either patch the fetch or copy the Block,
+ * and the corpus publishes it as a product-agnostic section, so an agent composing
+ * a page from it composes a request the consumer never asked for. What the Block
+ * refuses is not the queue, it is the transport.
+ *
+ * **The table is `table.tsx` and the two words that matter are the caller's.** A
+ * queue is read by comparing: which of these four is most pressing, how many are
+ * urgent, which source keeps producing them. Comparison is what a table is for and
+ * it is what a grid of divs cannot do, because a `div` grid has no `th` to
+ * navigate by, no association between a subject and its cells, and nothing for a
+ * browser's own table commands to act on. So every header is a `th` with
+ * `scope="col"`, the subject is a `th` with `scope="row"`, and the caller names
+ * the columns. The rejected alternative was a `DataTable01`, which is the same
+ * table with a `cell` function per column and a full toolbar of its own; this
+ * Block is that table for the six cells a queue has, which means a caller cannot
+ * add a seventh and gets a row header for free.
+ *
+ * **The priority and the state are drawn in the caller's words or not at all.**
+ * Both are closed unions, and both refuse to print themselves. A queue that
+ * rendered `urgent` and `waiting` in English into a consumer's operations tool
+ * would be the exact defect `check-block-copy.mjs` was written to end, and it is a
+ * worse one here than anywhere else in the package, because an operations tool is
+ * the place a person reads under time pressure in a product that is very often not
+ * in English. So each item that declares a tone must also declare the words, the
+ * run fails without them, and `Status` draws the dot beside the caller's sentence.
+ * The rejected alternative was to print the union's own name as a fallback, and
+ * the cost of that is the whole argument: it is a sentence a consumer cannot
+ * translate, inside a design system rather than inside their own code, which is
+ * where a translation tool is least likely to look.
+ *
+ * **The subject is a real control, and which real control depends on the item.** An
+ * item with an `href` renders the subject as a native anchor, so the destination
+ * is announced as a link, the browser's own affordances work, and middle-click
+ * opens it in a new tab. An item without one renders the subject as a `Button`,
+ * which is a real `<button>` with the focus ring and the hit target already
+ * solved. The rejected arrangement is a `<tr onClick>`, and it is rejected for the
+ * same reason `Todo01` refuses a `div` with an `onClick`: a row that listens for a
+ * click is not reachable by keyboard at all, and a queue whose every row is
+ * unreachable is a queue a keyboard user cannot work. A caller who needs a third
+ * arrangement composes their own control in the item's `actions` slot.
+ *
+ * **The moment goes through `relative-time` rather than being printed, and the
+ * cost of that is named.** A bare number is milliseconds and a string is anything,
+ * so a cell that drew the value as passed would put a raw epoch on the page for
+ * every caller whose data layer holds milliseconds, which is most of them, and
+ * would print a number with no date on it for the rest. `relative-time` hands the
+ * value to the platform, which knows the reader's locale and does the formatting
+ * in it, and hands the sentence back to the caller for the relative half. What
+ * that costs is that the moment is in the client graph rather than the server one,
+ * which is a cost this Block was already paying: the module carries `'use client'`
+ * because a queue has a control in it.
+ *
+ * **A `done` item keeps its row.** It is drawn in the muted ink and nothing else
+ * changes about it, and the reason is the one the whole Block rests on: a queue is
+ * read to decide what to do next, and a row that disappears is a decision a reader
+ * cannot audit. Removing a completed item is the consumer's filter, and the
+ * consumer is the only one who knows whether the reader wanted it.
+ *
+ * It is a client Component, and the reason is the callback rather than the state:
+ * `onSelect` is a function, a function is a piece of state, and state is a client
+ * module. A server component cannot hand an event handler to a `<button>`, so a
+ * caller rendering this from a server component would get a queue whose subjects
+ * do nothing. The rest of the rendering is a table, which is the price of that and
+ * a small one.
+ */
+export declare function Inbox01({ eyebrow, title, description, items, columns, toolbar, count, onSelect, empty, headingLevel, className, }: Inbox01Props): import("react").JSX.Element;
+export default Inbox01;
+//# sourceMappingURL=inbox.d.ts.map

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

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