@nanisoft/prism-ui 0.13.0 → 0.16.0

package/dist/blocks/permission-matrix-01/permission-matrix.d.ts

@@ -0,0 +1,282 @@
+import type { ReactNode } from 'react';
+import { type HeadingLevel } from '../../components/ui/section.js';
+/**
+ * One role, and everything the matrix needs to say about it beyond its name.
+ *
+ * `name` is a plain string and not a node, which is the one thing here that is
+ * not obvious, and the reason is on `PermissionMatrixColumn.header`: the header is
+ * display content and may carry a badge, a count styled as part of it, a node with
+ * a link in it, and `name` is what `valueLabel` composes an accessible sentence
+ * with. Those are two different jobs and one of them cannot be done with a node.
+ */
+export type PermissionMatrixRole = {
+    /** Stable identity. Matched by `columns`, which is what puts the role in the table. */
+    id: string;
+    /**
+     * The role's own name, in the product's own vocabulary, and the string handed to
+     * `valueLabel`.
+     *
+     * A short noun phrase, because a column of five role names is a column a reader
+     * scans rather than reads, and a name that wraps is a column whose cells sit
+     * against two lines of header.
+     */
+    name: string;
+    /** The line under the role's name: what the role is for, and what it inherits. */
+    description?: ReactNode;
+    /**
+     * How many people hold the role, when the product knows.
+     *
+     * A number and not a node because it is a count the product holds, and Prism
+     * formats no number here; the sentence around it is `countLabel`.
+     */
+    count?: number;
+    /**
+     * The words for the count, given the number.
+     *
+     * Required whenever `count` is given, because a bare figure in a heading is a
+     * number a reader has to guess the unit of, which is the one thing a headline
+     * figure cannot afford and the reason `metric` takes a node for its value.
+     */
+    countLabel?: (count: number) => string;
+};
+/**
+ * One column of the matrix, which is one role.
+ *
+ * The words above the column are the caller's and are a node, and the role's own
+ * name beside them in the `roles` array is a string. The split is the whole design
+ * and it is worth one sentence: a column heading is display content, and the
+ * commonest thing a consumer puts in one is a count rendered as part of it or a
+ * badge marking the role they are being walked towards, either of which is a node
+ * and neither of which is a string a sentence can be composed from. So the header
+ * is a node and `roles[].name` is the plain string, and the two are matched by
+ * `id`.
+ */
+export type PermissionMatrixColumn = {
+    /** The role's `id`. A column with no role, or a role with no column, is refused. */
+    id: string;
+    /** The words above this role's column. */
+    header: ReactNode;
+    /** Layout only: a width. */
+    className?: string;
+};
+/**
+ * One permission, and one answer per role.
+ *
+ * `values` is positional and its length must equal the number of roles, and the
+ * reason a mismatch is a thrown diagnostic rather than a short row is the Block's
+ * own JSDoc: a permission matrix is the surface where a mistake is most expensive,
+ * and a role quietly given no answer is a role a reader believes is refused.
+ */
+export type PermissionMatrixPermission = {
+    /** Stable identity, used for the row's key. */
+    id: string;
+    /**
+     * The permission's own name, and the row header the table announces.
+     *
+     * A short noun phrase in the imperative a product's own settings page uses. This
+     * is the cell a reader navigates to, and the one they read first, because it is
+     * the question they arrived with.
+     */
+    label: string;
+    /**
+     * The line under the permission's name: what it reaches, what turning it on
+     * costs, why it is conditional for one role.
+     *
+     * A node because the conditional cell in this matrix almost always carries a
+     * reference, and a caller who has to flatten theirs to a string loses the link
+     * that explains the condition.
+     */
+    description?: ReactNode;
+    /**
+     * One answer per role, in the order the columns were given.
+     *
+     * The union is the whole design of the cell and the Block's JSDoc argues for its
+     * third member at length: `true` is granted, `false` is refused, and a string is
+     * anything else, which is a category of its own rather than a spelling of the
+     * first two.
+     */
+    values: readonly (boolean | string)[];
+};
+/**
+ * A band of permissions under one name.
+ *
+ * Groups are the caller's because grouping is a claim about how the permissions
+ * relate, which is a fact about the product's own model and not about the matrix.
+ * Most matrices are one group, and that is a legitimate answer: pass one group with
+ * an empty `title` and it is the only row of headers the table carries.
+ */
+export type PermissionMatrixGroup = {
+    /** The group's own name, as the caller writes it. */
+    title: string;
+    /** The permissions in this group, in the order a reader should meet them. */
+    permissions: readonly PermissionMatrixPermission[];
+};
+/**
+ * The three marks and the words they answer with.
+ *
+ * All three required, and the reason is the one `PricingCompare01Labels` is built
+ * on: three marks in a matrix with no key is a matrix nobody can read. A check and
+ * a cross and a question mark are three shapes a reader learns once and applies
+ * forty times, and a matrix is the one place on a page where a reader is expected
+ * to apply a shape forty times. Without the key the third shape in particular is
+ * unreadable, because a question mark is a thing that went wrong to most readers
+ * and a condition to a few, and the reader has no way to find out which this is.
+ */
+export type PermissionMatrixLegend = {
+    /** Announced beside the check in a granted cell. */
+    allowed: string;
+    /** Announced beside the cross in a refused cell. */
+    denied: string;
+    /** Announced beside the question mark in a cell that depends on something else. */
+    conditional: string;
+};
+/**
+ * The props a PermissionMatrix01 takes.
+ *
+ * Every string is a prop and the Block ships none. There is no role, no
+ * permission, no cell value, no group name, no count sentence and not one of the
+ * three words a cell answers with. A permission matrix is the densest arrangement
+ * of claims a product makes about itself, and it is the arrangement where one
+ * hardcoded word is hardest to notice, because the reader is looking at forty cells
+ * and reading none of them.
+ */
+export type PermissionMatrix01Props = {
+    /** Optional label above the section title. See the No-Default-Eyebrow Rule. */
+    eyebrow?: ReactNode;
+    /** The section title. Required, because a matrix with no heading is a fragment. */
+    title: ReactNode;
+    /** One or two sentences under the title. */
+    description?: ReactNode;
+    /**
+     * The columns, one per role, in the order a reader should meet them.
+     *
+     * Required, and the `id` of each is matched against `roles`. The two arrays exist
+     * rather than one because of the split documented on `PermissionMatrixColumn`: a
+     * heading is a node and a role's name is a string, and a matrix that had to
+     * derive one from the other would force every consumer to flatten a heading into
+     * a string or to build a sentence out of a badge.
+     */
+    columns: readonly PermissionMatrixColumn[];
+    /** The roles the columns name, keyed by the same ids. */
+    roles: readonly PermissionMatrixRole[];
+    /**
+     * The permissions, grouped. Group order is the caller's, and so is the order
+     * inside each group, for the same reason: both are claims about what matters
+     * first.
+     */
+    groups: readonly PermissionMatrixGroup[];
+    /**
+     * The words one cell announces, given whether it is granted, the role it belongs
+     * to and the permission it is about.
+     *
+     * Required, and a function of three arguments because the honest answer is a
+     * sentence rather than a word in almost every case that is not a straight yes or
+     * no. "Publish without a review" is the answer; "Own billing" is the answer, in
+     * the reader's own words, in the reader's own language, with the reader's own
+     * plural rules. Prism will not compose it, and the alternative was a record of
+     * three English strings, which is exactly the defect the copy gate was written to
+     * end.
+     */
+    valueLabel: (allowed: boolean, role: string, permission: string) => string;
+    /**
+     * The key for the three marks.
+     *
+     * Required, because three marks with no key is a matrix nobody can read, and
+     * because the third mark is the one that most needs it: a question mark reads as
+     * a fault to most readers and as a condition to the few who have met one.
+     */
+    legend: PermissionMatrixLegend;
+    /** Heading level for the section title. @defaultValue 'h2' */
+    headingLevel?: HeadingLevel;
+    /**
+     * Layout only, exactly as on every Block. Changing a Prism-owned visual
+     * property from here is prohibited.
+     */
+    className?: string;
+};
+/**
+ * Roles against capabilities: the roles across the top, the permissions down the
+ * side, and one cell per intersection saying what that role does with that
+ * permission.
+ *
+ * **It is a real `<table>`, and the rejected alternative is a grid of `div`s that
+ * looks the same.** A permission matrix is the one table on a page where a mistake
+ * is the most expensive kind of mistake a page can have. A reader who is not sure
+ * whether the Billing role can publish will try to do it, and the failure arrives
+ * later as somebody else's problem, and the matrix is the document that was
+ * supposed to prevent it. So the structure has to be the platform's: a reader using
+ * a screen reader asks the table for a column and hears the role's name, then
+ * moves down the cells and hears each answer against that name, and asks for a row
+ * and hears the permission and then its answers. A grid of `div`s has no header
+ * cells to ask for, so the same reader receives forty cells of unlabelled marks
+ * and has to hold the column in their head while reading down it, which is the
+ * single task a matrix exists to remove, and on this particular table it is the
+ * task whose failure is most expensive. The cost of the table is the one every
+ * real table carries: `Table` wraps the whole thing in a horizontally scrollable
+ * container, because five roles do not fit a phone, and a matrix that reflowed into
+ * a stack would no longer be a matrix. The scroll is the price, and the alternative
+ * is not a narrower matrix, it is a div grid.
+ *
+ * **`values` is `boolean | string`, and the string is a third answer rather than a
+ * spelling of the other two.** `true` is granted and `false` is refused, and those
+ * two are marks the reader learns once. The third case is a permission that depends
+ * on something the reader has to go and look up: it is granted to a role that
+ * holds a particular licence, limited for a role in a particular plan, or granted
+ * only where a second role is also held. That answer is neither a yes nor a no, and
+ * a matrix that can only say yes or no forces a product to lie in one of the two
+ * directions. It will draw the conditional cell as granted, because the role can
+ * do the thing; and the reader goes away believing their role can publish, and
+ * finds out at the moment they press the button, on a surface with no explanation.
+ * Or it will draw it as refused, which is the worse of the two because it is
+ * untrue in the direction that looks like a restriction rather than a gap, and a
+ * reader who has been told twice that their role cannot do something stops asking
+ * anyone. So the union has a third member, the mark is a question rather than a
+ * tick or a cross, and the words are the caller's because only the caller knows
+ * what the condition is. The cost is stated rather than hidden: a conditional cell
+ * is wider than the two marks, so a matrix with many of them scrolls further, and
+ * a caller who finds that painful has an obvious and wrong answer available, which
+ * is to call the condition a limit and print a number.
+ *
+ * **A `values` array that does not match the columns throws.** Four roles and
+ * three values renders perfectly: the markup is valid, the header row is correct,
+ * the styling is right, and a column is simply not there. A silent truncation in a
+ * permission matrix is a claim about a role nobody made, on the one table where a
+ * reader will act on the claim, and nothing in the rendered result says a value is
+ * missing. So the Block refuses the props. The cost is a render that throws in
+ * development rather than a matrix that lies in production, and the alternative
+ * was considered and refused: a pad of empty cells would turn a caller's mistake
+ * into a document in which a role has no opinion about a permission, which is
+ * indistinguishable from a role that has been refused one.
+ *
+ * **The group is a row group, and a group's name is a table header rather than a
+ * heading.** Each group is its own `<tbody>` and its name is a `th` with
+ * `scope="rowgroup"`, which is what HTML offers for a header that names the rows
+ * below it, so a screen reader announces the group when the reader enters it
+ * rather than repeating it over every column. It is deliberately not in the page
+ * outline: a group name is a band of rows and not a section of the page, and seven
+ * group names in the outline would be seven entries for a reader navigating by
+ * heading who expected sections.
+ *
+ * **A role's name is a heading, at `childLevel(headingLevel)`.** The role is the
+ * column's title, a reader who navigates by heading wants to reach the role rather
+ * than the permissions under it, and a matrix embedded one level deeper than it was
+ * written for has to carry its role names with it. The count, when there is one, is
+ * inside the same element, because a role and the number of people holding it are
+ * one thing a reader takes together, and a count in a separate column would be a
+ * column of numbers a reader has to match back to a name.
+ *
+ * **The legend is drawn under the table and required, because three marks with no
+ * key is a matrix nobody can read.** This is the cheapest thing on the Block and
+ * the one whose absence costs the most: a reader who has met a check, a cross and a
+ * question mark in one matrix has learned three things and will apply them to the
+ * next forty cells, and a reader who has met two of them has learned a binary and
+ * will misread the third. The legend is a `tfoot` so it is inside the table and
+ * travels with it in the accessibility tree, rather than a row of prose below that
+ * a reader navigating the table never meets.
+ *
+ * It is a server Component: no hook, no state, no client code and no router. The
+ * three marks are drawn as vectors, so a matrix costs no JavaScript.
+ */
+export declare function PermissionMatrix01({ eyebrow, title, description, columns, roles, groups, valueLabel, legend, headingLevel, className, }: PermissionMatrix01Props): import("react").JSX.Element;
+export default PermissionMatrix01;
+//# sourceMappingURL=permission-matrix.d.ts.map

package/dist/blocks/permission-matrix-01/permission-matrix.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"permission-matrix.d.ts","sourceRoot":"","sources":["../../../src/blocks/permission-matrix-01/permission-matrix.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAEtC,OAAO,EAIL,KAAK,YAAY,EAClB,MAAM,6BAA6B,CAAA;AAYpC;;;;;;;;GAQG;AACH,MAAM,MAAM,oBAAoB,GAAG;IACjC,uFAAuF;IACvF,EAAE,EAAE,MAAM,CAAA;IACV;;;;;;;OAOG;IACH,IAAI,EAAE,MAAM,CAAA;IACZ,kFAAkF;IAClF,WAAW,CAAC,EAAE,SAAS,CAAA;IACvB;;;;;OAKG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IACd;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAA;CACvC,CAAA;AAED;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,sBAAsB,GAAG;IACnC,oFAAoF;IACpF,EAAE,EAAE,MAAM,CAAA;IACV,0CAA0C;IAC1C,MAAM,EAAE,SAAS,CAAA;IACjB,4BAA4B;IAC5B,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,CAAA;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,0BAA0B,GAAG;IACvC,+CAA+C;IAC/C,EAAE,EAAE,MAAM,CAAA;IACV;;;;;;OAMG;IACH,KAAK,EAAE,MAAM,CAAA;IACb;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE,SAAS,CAAA;IACvB;;;;;;;OAOG;IACH,MAAM,EAAE,SAAS,CAAC,OAAO,GAAG,MAAM,CAAC,EAAE,CAAA;CACtC,CAAA;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,qBAAqB,GAAG;IAClC,qDAAqD;IACrD,KAAK,EAAE,MAAM,CAAA;IACb,6EAA6E;IAC7E,WAAW,EAAE,SAAS,0BAA0B,EAAE,CAAA;CACnD,CAAA;AAED;;;;;;;;;;GAUG;AACH,MAAM,MAAM,sBAAsB,GAAG;IACnC,oDAAoD;IACpD,OAAO,EAAE,MAAM,CAAA;IACf,oDAAoD;IACpD,MAAM,EAAE,MAAM,CAAA;IACd,mFAAmF;IACnF,WAAW,EAAE,MAAM,CAAA;CACpB,CAAA;AAED;;;;;;;;;GASG;AACH,MAAM,MAAM,uBAAuB,GAAG;IACpC,+EAA+E;IAC/E,OAAO,CAAC,EAAE,SAAS,CAAA;IACnB,mFAAmF;IACnF,KAAK,EAAE,SAAS,CAAA;IAChB,4CAA4C;IAC5C,WAAW,CAAC,EAAE,SAAS,CAAA;IACvB;;;;;;;;OAQG;IACH,OAAO,EAAE,SAAS,sBAAsB,EAAE,CAAA;IAC1C,yDAAyD;IACzD,KAAK,EAAE,SAAS,oBAAoB,EAAE,CAAA;IACtC;;;;OAIG;IACH,MAAM,EAAE,SAAS,qBAAqB,EAAE,CAAA;IACxC;;;;;;;;;;;OAWG;IACH,UAAU,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,KAAK,MAAM,CAAA;IAC1E;;;;;;OAMG;IACH,MAAM,EAAE,sBAAsB,CAAA;IAC9B,8DAA8D;IAC9D,YAAY,CAAC,EAAE,YAAY,CAAA;IAC3B;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,CAAA;AA6DD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkFG;AACH,wBAAgB,kBAAkB,CAAC,EACjC,OAAO,EACP,KAAK,EACL,WAAW,EACX,OAAO,EACP,KAAK,EACL,MAAM,EACN,UAAU,EACV,MAAM,EACN,YAAmB,EACnB,SAAS,GACV,EAAE,uBAAuB,+BAsNzB;AAED,eAAe,kBAAkB,CAAA"}

package/dist/blocks/permission-matrix-01/permission-matrix.js

@@ -0,0 +1,173 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useId } from 'react';
+import { Check, CircleHelp, X } from 'lucide-react';
+import { Section, SectionHeading, childLevel, } from '../../components/ui/section.js';
+import { Table, TableBody, TableCell, TableFooter, TableHead, TableHeader, TableRow, } from '../../components/ui/table.js';
+import { cn } from '../../lib/utils.js';
+/**
+ * One cell: the mark, and the words, and a string where the answer is neither.
+ *
+ * A component in the module and not a second Item, because it has no public
+ * surface and nothing to document for a consumer. It exists so the two boolean
+ * arms are written once, and they are written once because the span wrapping the
+ * mark and the visually hidden words is the part that is easy to get subtly wrong
+ * three times in a row.
+ */
+function MatrixCell({ value, role, permission, valueLabel, conditionalLabel, }) {
+    if (typeof value === 'boolean') {
+        return value ? (_jsxs("span", { "data-slot": "permission-matrix-answer", className: "text-success inline-flex items-center gap-1.5", children: [_jsx(Check, { "aria-hidden": true, className: "size-4 shrink-0" }), _jsx("span", { className: "sr-only", children: valueLabel(true, role, permission) })] })) : (_jsxs("span", { "data-slot": "permission-matrix-answer", className: "text-muted-foreground inline-flex items-center gap-1.5", children: [_jsx(X, { "aria-hidden": true, className: "size-4 shrink-0" }), _jsx("span", { className: "sr-only", children: valueLabel(false, role, permission) })] }));
+    }
+    /*
+      The third answer, and the sentence beside the mark is `legend.conditional`
+      rather than `valueLabel`, which is a real distinction rather than a shortcut.
+      `valueLabel` composes the answer for a cell that is granted or refused; this
+      cell's answer is the string the caller wrote, and what the mark needs beside it
+      is the name of the category, so that a reader knows the sentence is a condition
+      to look up rather than a limit they have hit.
+    */
+    return (_jsxs("span", { "data-slot": "permission-matrix-conditional", className: "text-muted-foreground inline-flex items-center gap-1.5", children: [_jsx(CircleHelp, { "aria-hidden": true, className: "size-4 shrink-0" }), _jsx("span", { className: "text-sm text-pretty", children: value }), _jsx("span", { className: "sr-only", children: conditionalLabel })] }));
+}
+/**
+ * Roles against capabilities: the roles across the top, the permissions down the
+ * side, and one cell per intersection saying what that role does with that
+ * permission.
+ *
+ * **It is a real `<table>`, and the rejected alternative is a grid of `div`s that
+ * looks the same.** A permission matrix is the one table on a page where a mistake
+ * is the most expensive kind of mistake a page can have. A reader who is not sure
+ * whether the Billing role can publish will try to do it, and the failure arrives
+ * later as somebody else's problem, and the matrix is the document that was
+ * supposed to prevent it. So the structure has to be the platform's: a reader using
+ * a screen reader asks the table for a column and hears the role's name, then
+ * moves down the cells and hears each answer against that name, and asks for a row
+ * and hears the permission and then its answers. A grid of `div`s has no header
+ * cells to ask for, so the same reader receives forty cells of unlabelled marks
+ * and has to hold the column in their head while reading down it, which is the
+ * single task a matrix exists to remove, and on this particular table it is the
+ * task whose failure is most expensive. The cost of the table is the one every
+ * real table carries: `Table` wraps the whole thing in a horizontally scrollable
+ * container, because five roles do not fit a phone, and a matrix that reflowed into
+ * a stack would no longer be a matrix. The scroll is the price, and the alternative
+ * is not a narrower matrix, it is a div grid.
+ *
+ * **`values` is `boolean | string`, and the string is a third answer rather than a
+ * spelling of the other two.** `true` is granted and `false` is refused, and those
+ * two are marks the reader learns once. The third case is a permission that depends
+ * on something the reader has to go and look up: it is granted to a role that
+ * holds a particular licence, limited for a role in a particular plan, or granted
+ * only where a second role is also held. That answer is neither a yes nor a no, and
+ * a matrix that can only say yes or no forces a product to lie in one of the two
+ * directions. It will draw the conditional cell as granted, because the role can
+ * do the thing; and the reader goes away believing their role can publish, and
+ * finds out at the moment they press the button, on a surface with no explanation.
+ * Or it will draw it as refused, which is the worse of the two because it is
+ * untrue in the direction that looks like a restriction rather than a gap, and a
+ * reader who has been told twice that their role cannot do something stops asking
+ * anyone. So the union has a third member, the mark is a question rather than a
+ * tick or a cross, and the words are the caller's because only the caller knows
+ * what the condition is. The cost is stated rather than hidden: a conditional cell
+ * is wider than the two marks, so a matrix with many of them scrolls further, and
+ * a caller who finds that painful has an obvious and wrong answer available, which
+ * is to call the condition a limit and print a number.
+ *
+ * **A `values` array that does not match the columns throws.** Four roles and
+ * three values renders perfectly: the markup is valid, the header row is correct,
+ * the styling is right, and a column is simply not there. A silent truncation in a
+ * permission matrix is a claim about a role nobody made, on the one table where a
+ * reader will act on the claim, and nothing in the rendered result says a value is
+ * missing. So the Block refuses the props. The cost is a render that throws in
+ * development rather than a matrix that lies in production, and the alternative
+ * was considered and refused: a pad of empty cells would turn a caller's mistake
+ * into a document in which a role has no opinion about a permission, which is
+ * indistinguishable from a role that has been refused one.
+ *
+ * **The group is a row group, and a group's name is a table header rather than a
+ * heading.** Each group is its own `<tbody>` and its name is a `th` with
+ * `scope="rowgroup"`, which is what HTML offers for a header that names the rows
+ * below it, so a screen reader announces the group when the reader enters it
+ * rather than repeating it over every column. It is deliberately not in the page
+ * outline: a group name is a band of rows and not a section of the page, and seven
+ * group names in the outline would be seven entries for a reader navigating by
+ * heading who expected sections.
+ *
+ * **A role's name is a heading, at `childLevel(headingLevel)`.** The role is the
+ * column's title, a reader who navigates by heading wants to reach the role rather
+ * than the permissions under it, and a matrix embedded one level deeper than it was
+ * written for has to carry its role names with it. The count, when there is one, is
+ * inside the same element, because a role and the number of people holding it are
+ * one thing a reader takes together, and a count in a separate column would be a
+ * column of numbers a reader has to match back to a name.
+ *
+ * **The legend is drawn under the table and required, because three marks with no
+ * key is a matrix nobody can read.** This is the cheapest thing on the Block and
+ * the one whose absence costs the most: a reader who has met a check, a cross and a
+ * question mark in one matrix has learned three things and will apply them to the
+ * next forty cells, and a reader who has met two of them has learned a binary and
+ * will misread the third. The legend is a `tfoot` so it is inside the table and
+ * travels with it in the accessibility tree, rather than a row of prose below that
+ * a reader navigating the table never meets.
+ *
+ * It is a server Component: no hook, no state, no client code and no router. The
+ * three marks are drawn as vectors, so a matrix costs no JavaScript.
+ */
+export function PermissionMatrix01({ eyebrow, title, description, columns, roles, groups, valueLabel, legend, headingLevel = 'h2', className, }) {
+    // The handle a table below takes its name from; see the note on the table.
+    const headingId = useId();
+    if (roles.length === 0) {
+        throw new Error('PermissionMatrix01: roles is empty, so the matrix has no columns and the table would render a header ' +
+            'row and nothing else. Pass the roles a reader is choosing between.');
+    }
+    if (columns.length === 0) {
+        throw new Error('PermissionMatrix01: columns is empty, so the matrix has no headings and every cell would be a mark with ' +
+            'nothing to attach it to. Name one column per role.');
+    }
+    if (groups.length === 0) {
+        throw new Error('PermissionMatrix01: groups is empty, so the matrix has no rows. Pass one group, even when its title is ' +
+            'empty, rather than leaving the reader with a row of role names and no permissions beside them.');
+    }
+    for (const column of columns) {
+        if (!roles.some((role) => role.id === column.id)) {
+            throw new Error(`PermissionMatrix01: a column names the role ${JSON.stringify(column.id)} and no role carries that id, ` +
+                'so the heading would sit over a column no answers belong to. Give the column the id of a role, or ' +
+                'drop it.');
+        }
+    }
+    for (const role of roles) {
+        if (!columns.some((column) => column.id === role.id)) {
+            throw new Error(`PermissionMatrix01: the role ${JSON.stringify(role.name)} has no column, so the table would hold a ` +
+                'row of answers for a role no reader can name. Give the role a column whose id is its own.');
+        }
+        if (role.count !== undefined && role.countLabel === undefined) {
+            throw new Error(`PermissionMatrix01: the role ${JSON.stringify(role.name)} declares a count and no countLabel, so a ` +
+                'bare figure would sit in a column heading with nothing saying what it counts. Pass the function.');
+        }
+    }
+    for (const group of groups) {
+        for (const permission of group.permissions) {
+            if (permission.values.length !== columns.length) {
+                throw new Error(`PermissionMatrix01: the permission ${JSON.stringify(permission.label)} has ` +
+                    `${permission.values.length} value(s) and there are ${columns.length} column(s). A short row ` +
+                    'renders a role with no answer, which on this table is a claim nobody made, so it is refused ' +
+                    'rather than padded.');
+            }
+        }
+    }
+    // A role is a column, and a column is a title inside the section that
+    // introduces the set, so five roles under one `h2` are five `h3`s.
+    const RoleHeading = childLevel(headingLevel);
+    const width = columns.length + 1;
+    // Read once rather than searched per cell, because `valueLabel` is called for
+    // every cell and a linear search inside that is a cost the reader pays on the
+    // render. The `id` is the join, and the loop above has already refused a column
+    // or a role the other side does not carry.
+    const byId = new Map(roles.map((role) => [role.id, role]));
+    const nameOf = (id) => byId.get(id)?.name ?? id;
+    return (_jsxs(Section, { className: className, "data-slot": "permission-matrix", children: [_jsx(SectionHeading, { as: headingLevel, id: headingId, align: "left", eyebrow: eyebrow, title: title, description: description, className: "mb-12" }), _jsx("div", { "data-slot": "permission-matrix-table", className: "flex flex-col gap-4", children: _jsx("div", { className: "border-border overflow-hidden rounded-xl border", children: _jsxs(Table, { "aria-labelledby": headingId, children: [_jsx(TableHeader, { children: _jsxs(TableRow, { children: [_jsx(TableHead, { className: "w-56 align-bottom" }), columns.map((column) => {
+                                            const role = byId.get(column.id);
+                                            return (_jsxs(TableHead, { scope: "col", "data-role": column.id, className: cn('w-44 whitespace-normal align-bottom', column.className), children: [_jsxs(RoleHeading, { className: "flex flex-col items-start gap-1 text-base font-semibold tracking-tight text-balance", children: [_jsx("span", { "data-slot": "permission-matrix-role-name", children: column.header }), role?.count === undefined || role.countLabel === undefined ? null : (_jsx("span", { "data-slot": "permission-matrix-role-count", className: "text-muted-foreground text-xs font-normal tabular-nums", children: role.countLabel(role.count) }))] }), role?.description === undefined ? null : (_jsx("span", { "data-slot": "permission-matrix-role-description", className: "text-muted-foreground mt-1 block text-sm font-normal text-pretty", children: role.description }))] }, column.id));
+                                        })] }) }), groups.map((group, groupIndex) => (
+                            // Positional, because a group title is display content and a caller
+                            // may legitimately split a model into two bands under one name.
+                            _jsxs(TableBody, { "data-slot": "permission-matrix-group", children: [_jsx(TableRow, { children: _jsx(TableHead, { scope: "rowgroup", colSpan: width, className: "bg-muted/50 whitespace-normal", children: _jsx("span", { className: "text-sm font-semibold", children: group.title }) }) }), group.permissions.map((permission) => (_jsxs(TableRow, { "data-slot": "permission-matrix-permission", "data-permission": permission.id, children: [_jsx(TableHead, { scope: "row", className: "text-foreground h-auto w-56 whitespace-normal font-medium", children: _jsxs("span", { className: "flex flex-col gap-1", children: [_jsx("span", { className: "text-sm font-medium", children: permission.label }), permission.description === undefined ? null : (_jsx("span", { className: "text-muted-foreground text-xs font-normal text-pretty", children: permission.description }))] }) }), columns.map((column, index) => (_jsx(TableCell, { "data-role": column.id, children: _jsx(MatrixCell, { value: permission.values[index] ?? false, role: nameOf(column.id), permission: permission.label, valueLabel: valueLabel, conditionalLabel: legend.conditional }) }, column.id)))] }, permission.id)))] }, groupIndex))), _jsx(TableFooter, { children: _jsx(TableRow, { children: _jsx(TableCell, { colSpan: width, className: "bg-muted/50 whitespace-normal", children: _jsxs("span", { className: "flex flex-wrap items-center gap-x-6 gap-y-2", children: [_jsxs("span", { className: "text-success inline-flex items-center gap-1.5", children: [_jsx(Check, { "aria-hidden": true, className: "size-4 shrink-0" }), _jsx("span", { className: "text-foreground text-sm", children: legend.allowed })] }), _jsxs("span", { className: "text-muted-foreground inline-flex items-center gap-1.5", children: [_jsx(X, { "aria-hidden": true, className: "size-4 shrink-0" }), _jsx("span", { className: "text-foreground text-sm", children: legend.denied })] }), _jsxs("span", { className: "text-muted-foreground inline-flex items-center gap-1.5", children: [_jsx(CircleHelp, { "aria-hidden": true, className: "size-4 shrink-0" }), _jsx("span", { className: "text-foreground text-sm", children: legend.conditional })] })] }) }) }) })] }) }) })] }));
+}
+export default PermissionMatrix01;

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

@@ -1,2 +1,3 @@
 export { Pricing01, default } from './pricing.js';
+export type { Plan, Pricing01Props, PricingAction, PricingLinkAction, PricingSlotAction, } from './pricing.js';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/blocks/pricing-01/index.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/blocks/pricing-01/index.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAM9C,YAAY,EACV,IAAI,EACJ,cAAc,EACd,aAAa,EACb,iBAAiB,EACjB,iBAAiB,GAClB,MAAM,WAAW,CAAA"}

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

@@ -1,12 +1,123 @@
+import { type ReactNode } from 'react';
 import { type HeadingLevel } from '../../components/ui/section.js';
+/**
+ * One plan's control, when it is a destination.
+ *
+ * One of the two arms of `PricingAction`, and named rather than left as an inline
+ * member of the union so a caller building `plans` from its own data can say which
+ * arm it is building. `href` is required and that is the whole of the arm.
+ */
+export type PricingLinkAction = {
+    /** The words on the control. A plan's action is its pitch, so it is the caller's. */
+    label: string;
+    /**
+     * Where the control goes. Rendered as a native anchor's `href`.
+     *
+     * **Required, and this member did not exist.** `Plan` declared a required `cta`
+     * string and the Block rendered it as a `Button`, so every plan in every consumer's
+     * pricing table shipped a focusable control, announced as a button, that activated
+     * to nothing, at the foot of the card that a reader was about to decide on. A price
+     * is the one number on a marketing page a reader acts on, and the control beside it
+     * did nothing.
+     */
+    href: string;
+    /**
+     * Opens the destination in a new browsing context, which defaults the link
+     * relationship to `noopener noreferrer`. Declared rather than inferred, for the
+     * reason `Cta01Action.newTab` states.
+     */
+    newTab?: boolean;
+    /** Forbidden, so that an action cannot be both a destination and a caller's own control. */
+    slot?: never;
+};
+/**
+ * One plan's control, when it is the caller's own.
+ *
+ * **This is the arm that replaced a rendered button, and the reason it is a slot
+ * rather than an `onClick` is that a Block cannot receive one.** This is a server
+ * Component, so a handler is not a prop it can be given. A plan's control is also the
+ * one place a pricing table most often needs a control Prism cannot draw: a trial
+ * that opens a checkout dialog, a contact form for the top tier, a router's own
+ * `Link` for a client-side transition into the plan.
+ *
+ * The Block places the node in the card's foot and adds nothing to it, because a
+ * class it adds to a node it does not render is a style the caller cannot see and
+ * cannot remove, and this package has no override path.
+ */
+export type PricingSlotAction = {
+    /**
+     * The caller's own control, placed in the card's foot.
+     *
+     * The whole control, including its own label, its own weight and any icon. A plan
+     * with a slot action draws no `Button` of its own, so the caller's weight is the
+     * weight a reader sees and there is nothing here that can contradict it.
+     */
+    slot: ReactNode;
+    /**
+     * Forbidden on this arm, and for a reason rather than by tidiness: the Block
+     * renders `slot` and nothing else, so a `label` beside it would be a word no
+     * reader ever sees.
+     */
+    label?: never;
+    /** Forbidden: an anchor belongs on the other arm, where Prism renders it. */
+    href?: never;
+    /** Forbidden with `href`, for the same reason. */
+    newTab?: never;
+};
+/**
+ * One plan's control, as a union of the two things a control at the foot of a
+ * pricing card can honestly be.
+ *
+ * A plan carries exactly one control, so this is not an ordered row and the slot is
+ * an arm of the plan's own record rather than a sibling prop on the Block: `Plan` is
+ * one entry in a list, and a sibling `actionSlot` on `Pricing01` could not say which
+ * card it filled. Position and element are the same value here for the same reason
+ * they are in a hero's row.
+ *
+ * It is declared here rather than imported from `cta-01`, following
+ * `ProcessFlow01`'s note on the same point, and `scripts/check-block-controls.mjs`
+ * holds the shape: a shared type would make `@nanisoft/prism-ui/blocks/cta-01` a
+ * dependency of `@nanisoft/prism-ui/blocks/pricing-01`, and a consumer installing a
+ * pricing table would be made to resolve a closing call-to-action band to get it.
+ */
+export type PricingAction = PricingLinkAction | PricingSlotAction;
 export type Plan = {
+    /**
+     * A stable key for this plan, and the only thing about it React keys on.
+     *
+     * **Required, and it did not exist: the cards were keyed on `name`.** `name` is
+     * the word a reader reads on the card, so it is display content and not identity,
+     * and a Block that keyed on it had two ways to be wrong at once. Two plans
+     * sharing a name, which is a monthly and an annual row of the same tier or a
+     * "Standard" and a "Standard (legacy)" line a product is migrating away from,
+     * produced a duplicate key and cards the renderer had been told are ambiguous.
+     * And a rename in the copy was a rename in the key, which loses a caller's saved
+     * selection or expanded state over an edit to a sentence.
+     *
+     * The route or the product's own plan code is the usual value and needs no
+     * coordination. `Careers01` and every other Block in this package key on an `id`
+     * and say why in the same words; this is the last one that did not, and the reason
+     * it survived is recorded in the release that introduced `action` rather than
+     * here.
+     */
+    id: string;
+    /** The plan's own name, which is what the card's title reads. */
     name: string;
     price: string;
     /** Rendered after the price, e.g. " / month". Omit for a one-off figure. */
     period?: string;
     body?: string;
     features: string[];
-    cta: string;
+    /**
+     * The one control at the foot of this card.
+     *
+     * **A union of a destination and a slot, and it replaces a required `cta`
+     * string.** The string compiled and rendered a `Button`, which is a control that
+     * activates to nothing; a pricing card is the last thing a reader sees before they
+     * choose, so that is the worst place in the package to ship one. See
+     * `PricingAction`.
+     */
+    action: PricingAction;
     /** Lifts the plan with a primary border and a filled button. */
     featured?: boolean;
     /** Overrides the "Popular" badge on the featured plan. */
@@ -36,6 +147,12 @@ export type Pricing01Props = {
  * `Pricing01` and `FeatureGrid01` were the only two Blocks that left the heading
  * centred over content, and neither had a stated reason for it, so both were
  * taking the default rather than making a decision.
+ *
+ * **The card's foot is a link or the caller's own control, and never a button of
+ * this Block's.** `Plan` used to carry a required `cta` string and the Block
+ * rendered it as a `Button`, so every pricing table in every consumer's product
+ * shipped a focusable control, announced as a button, that activated to nothing,
+ * on the card a reader was about to choose from. See `PricingAction`.
  */
 export declare function Pricing01({ eyebrow, title, description, plans, headingLevel, }: Pricing01Props): import("react").JSX.Element;
 export default Pricing01;

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

@@ -1 +1 @@
-{"version":3,"file":"pricing.d.ts","sourceRoot":"","sources":["../../../src/blocks/pricing-01/pricing.tsx"],"names":[],"mappings":"AAYA,OAAO,EAAuC,KAAK,YAAY,EAAE,MAAM,6BAA6B,CAAA;AAEpG,MAAM,MAAM,IAAI,GAAG;IACjB,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;IACb,4EAA4E;IAC5E,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,QAAQ,EAAE,MAAM,EAAE,CAAA;IAClB,GAAG,EAAE,MAAM,CAAA;IACX,gEAAgE;IAChE,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,0DAA0D;IAC1D,KAAK,CAAC,EAAE,MAAM,CAAA;CACf,CAAA;AAED,MAAM,MAAM,cAAc,GAAG;IAC3B,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,KAAK,EAAE,IAAI,EAAE,CAAA;IACb,+DAA+D;IAC/D,YAAY,CAAC,EAAE,YAAY,CAAA;CAC5B,CAAA;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,SAAS,CAAC,EACxB,OAAO,EACP,KAAK,EACL,WAAW,EACX,KAAK,EACL,YAAmB,GACpB,EAAE,cAAc,+BAwEhB;AAED,eAAe,SAAS,CAAA"}
+{"version":3,"file":"pricing.d.ts","sourceRoot":"","sources":["../../../src/blocks/pricing-01/pricing.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAY,KAAK,SAAS,EAAE,MAAM,OAAO,CAAA;AAchD,OAAO,EAAuC,KAAK,YAAY,EAAE,MAAM,6BAA6B,CAAA;AAEpG;;;;;;GAMG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B,qFAAqF;IACrF,KAAK,EAAE,MAAM,CAAA;IACb;;;;;;;;;OASG;IACH,IAAI,EAAE,MAAM,CAAA;IACZ;;;;OAIG;IACH,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,4FAA4F;IAC5F,IAAI,CAAC,EAAE,KAAK,CAAA;CACb,CAAA;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B;;;;;;OAMG;IACH,IAAI,EAAE,SAAS,CAAA;IACf;;;;OAIG;IACH,KAAK,CAAC,EAAE,KAAK,CAAA;IACb,6EAA6E;IAC7E,IAAI,CAAC,EAAE,KAAK,CAAA;IACZ,kDAAkD;IAClD,MAAM,CAAC,EAAE,KAAK,CAAA;CACf,CAAA;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,aAAa,GAAG,iBAAiB,GAAG,iBAAiB,CAAA;AAEjE,MAAM,MAAM,IAAI,GAAG;IACjB;;;;;;;;;;;;;;;;;OAiBG;IACH,EAAE,EAAE,MAAM,CAAA;IACV,iEAAiE;IACjE,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;IACb,4EAA4E;IAC5E,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,QAAQ,EAAE,MAAM,EAAE,CAAA;IAClB;;;;;;;;OAQG;IACH,MAAM,EAAE,aAAa,CAAA;IACrB,gEAAgE;IAChE,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,0DAA0D;IAC1D,KAAK,CAAC,EAAE,MAAM,CAAA;CACf,CAAA;AAED,MAAM,MAAM,cAAc,GAAG;IAC3B,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,KAAK,EAAE,IAAI,EAAE,CAAA;IACb,+DAA+D;IAC/D,YAAY,CAAC,EAAE,YAAY,CAAA;CAC5B,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,SAAS,CAAC,EACxB,OAAO,EACP,KAAK,EACL,WAAW,EACX,KAAK,EACL,YAAmB,GACpB,EAAE,cAAc,+BAuFhB;AAED,eAAe,SAAS,CAAA"}