@nanisoft/prism-ui 0.13.0 → 0.16.0

package/dist/blocks/settings-members-01/settings-members.js

@@ -0,0 +1,255 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useId } from 'react';
+import { Avatar, AvatarFallback, AvatarImage } from '../../components/ui/avatar.js';
+import { Field, FieldLabel } from '../../components/ui/field.js';
+import { ListPanel } from '../../components/ui/list-panel.js';
+import { Section, SectionHeading, childLevel, } from '../../components/ui/section.js';
+import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue, } from '../../components/ui/select.js';
+import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow, } from '../../components/ui/table.js';
+import { cn } from '../../lib/utils.js';
+/**
+ * The initials a name produces, and the rule that produces them.
+ *
+ * Two letters from the first and last words, and the first two characters of a
+ * single word. It is the same rule `AvatarGroup` applies, repeated rather than
+ * imported, and the boundary is the reason: that helper is private to its module
+ * and exporting it would make a private derivation part of a published surface
+ * to save six lines in a Block. The cost is stated rather than hidden: two
+ * modules carry the rule, so a change to it is a change in both.
+ */
+function initialsOf(name) {
+    const words = name.trim().split(/\s+/).filter(Boolean);
+    const first = words[0];
+    if (first === undefined)
+        return '';
+    if (words.length === 1)
+        return first.slice(0, 2).toUpperCase();
+    return `${first.charAt(0)}${words[words.length - 1].charAt(0)}`.toUpperCase();
+}
+/**
+ * The three refusals, so that a members surface never renders something it
+ * cannot justify.
+ *
+ * A role control with nothing to move a member to, a role control that does
+ * nothing when it is moved, a row the Block has decided is the reader's own and
+ * has marked in no way a reader can see, and a group of invitations under no
+ * name. Each is a caller's mistake rather than a request, so each throws in a
+ * console rather than rendering the quiet version of itself.
+ */
+function assertProps(props) {
+    const { members, invitations, roleOptions, roleLabel, onRoleChange, pendingTitle, columns } = props;
+    if (roleOptions !== undefined && roleLabel === undefined) {
+        throw new Error('SettingsMembers01: roleOptions was passed with no roleLabel, so each role control would draw the ' +
+            'option own label and no sentence about what the set is called in this product. Pass the function.');
+    }
+    if (onRoleChange !== undefined && roleOptions === undefined) {
+        throw new Error('SettingsMembers01: onRoleChange was passed with no roleOptions, so every row would be a control with ' +
+            'nowhere to move a member to. Pass the roles, or drop the handler and draw your own control.');
+    }
+    if (members.some((member) => member.isSelf === true) && members.every((member) => member.isSelf === true)) {
+        throw new Error('SettingsMembers01: every member is marked as the reader own, so the surface is a list of one person ' +
+            'and no role control is drawn on any row. A workspace with one member is a real state; the honest ' +
+            'answer for it is your empty sentence rather than a table of yourself.');
+    }
+    for (const member of members) {
+        if (member.isSelf === true && (member.selfLabel === undefined || member.selfLabel.trim() === '')) {
+            throw new Error('SettingsMembers01: a member is marked isSelf and passed no selfLabel, so the row the Block has ' +
+                'decided is the reader own would be marked by nothing a reader can see. Pass the words that say so.');
+        }
+    }
+    if ((invitations?.length ?? 0) > 0 && pendingTitle === undefined) {
+        throw new Error('SettingsMembers01: invitations were passed with no pendingTitle, so the group would be a second list ' +
+            'on the page under no name at all. Name it, so a reader can say which list they are looking at.');
+    }
+    for (const column of props.columns ?? []) {
+        if (column.id !== 'name' && column.id !== 'role' && column.id !== 'joined') {
+            throw new Error(`SettingsMembers01: a column names the cell ${JSON.stringify(column.id)}, which is not one of the ` +
+                'three cells this table can draw. A column with nothing to put in it is a column a reader counts ' +
+                'past, so add the cell rather than the heading.');
+        }
+    }
+    if (columns !== undefined && !columns.some((column) => column.id === 'name')) {
+        throw new Error('SettingsMembers01: columns were passed with no name column, so the table would hold no row header and ' +
+            'a screen reader navigating it by row would be given numbers with nothing to attach them to. A column ' +
+            'of people is the one column that names the row.');
+    }
+}
+/**
+ * Who is in a workspace, what each of them can do, when they arrived, and one
+ * control per row, under a group for the invitations that have not been taken up.
+ *
+ * **This is the Block a reader visits to change one thing and leave, which is why
+ * it is a Block and not a page.** A settings surface is where a design system's
+ * care is most visible and least appreciated. Nothing here is impressive. The
+ * reader came to demote one colleague, they find the row, they change it, they
+ * leave, and they never learn that the Block was good. They will learn it
+ * immediately if one control is in a different place from the one above it, if a
+ * row moves when they type, or if a word on the page is in a language they do
+ * not read. So the three decisions below are all about a page that must not
+ * change under the reader, and none of them is about how the page looks.
+ *
+ * **A members list is rows or a table, and the caller chooses rather than the
+ * count.** Below the count at which a workspace stops being a list of people a
+ * reader knows, a portrait and a name and a role on one line is easier to read
+ * than four columns. Above it, the same data has to be compared across rows, and
+ * a reader comparing a role down a column against another role is doing the job
+ * a table exists for. So `columns` is the switch, the type is a closed set of
+ * three cells, and the Block derives which arrangement to draw rather than being
+ * told twice. The cost is that the two arrangements are not one tree: a caller
+ * that switches at render time gets both in the accessibility tree, which is
+ * correct, because they asked for both.
+ *
+ * **A table has to have a name column, and the Block refuses one that does
+ * not.** This is the one requirement inside a type whose members are all
+ * optional, and it is there because a table of people with no row header is the
+ * arrangement a screen reader cannot use at all: the reader asks the table for a
+ * row, gets nothing to attach the answers to, and is left holding twenty cells of
+ * role names with no idea whose any of them are. A name column is not a default
+ * because the name is also the identity the initials and the self mark hang off,
+ * and a table that drew the portrait and the role without the person is a table
+ * about a job title. The row's own controls get a column with nothing above it,
+ * because a heading over a column of buttons would be naming the buttons rather
+ * than the data, and every control in it is the caller's and carries its own
+ * name.
+ *
+ * **`isSelf` marks the reader's own row, and the marking is what stops the Block
+ * drawing a role control on it.** This is the load-bearing decision in the whole
+ * Block and it is worth the paragraph. A settings surface that lets a reader
+ * remove themselves without saying so is a trap: the control is in the same place
+ * as every other row's, it looks the same, and the consequence is a workspace the
+ * reader is no longer in. A surface that lets a reader change their own role is
+ * worse, because the consequence is a workspace with nobody left who can undo it.
+ * A self-service role editor is how a team loses its last owner, and it loses it
+ * on the settings page, in front of a reader who believed the page. So the flag
+ * is a prop the caller passes, and when it is passed the row states the role as
+ * words and offers no control, and the row's own `actions` still render because
+ * what a reader may do about their own membership is the caller's decision and
+ * the Block is not the party that should have an opinion about it. The cost is
+ * stated rather than hidden: a workspace of one has no row to change, which is
+ * why every row being self is a thrown diagnostic rather than a quiet page.
+ *
+ * **An invitation that has expired is dimmed, and not deleted.** The signal is
+ * the presence of `expiresLabel`, because the Block holds no clock and a design
+ * system that guessed would be guessing about somebody else's deadline. The
+ * reason for keeping the row is the reason `careers-01` gives for a closed role:
+ * a reader who sent an invitation and finds it gone learns nothing at all,
+ * because the absence is indistinguishable from a fault, from a list that failed
+ * to load, and from a product that quietly discards invitations. A list that
+ * silently shrinks is a list a reader stops trusting, and a members surface is
+ * the last place to spend that trust: the reader's next question is usually
+ * about somebody else's access. So the row stays, it is dimmed, and the caller's
+ * words say what happened. The Block refuses to invent those words, which is why
+ * their absence leaves a row that is not dimmed rather than a row that is dimmed
+ * with nothing to read.
+ *
+ * **A role is a machine value with a sentence beside it, and the sentence is a
+ * function.** `member.role` is the value, `roleLabel` is the words, and the
+ * separation is what `Status` argues for a dot and `Integration01` argues for a
+ * connection state: a design system that knows what a role is called is deciding
+ * for four products whose permission models share nothing but the word. The
+ * function rather than a record of strings because the honest rendering is
+ * usually longer than a select trigger can show, so the caller needs to say more
+ * than one string per option, and because one option may need a qualifier the
+ * others do not.
+ *
+ * **The Block holds no role state, so a failed change is the caller's to show.**
+ * The select is uncontrolled, the value comes from `member.role`, and
+ * `onRoleChange` is a request. That is the arrangement a server action wants and
+ * it is the arrangement where the truth is visible: when the request fails the
+ * caller re-renders with the old value and the select is where the reader left
+ * it, which is a control that told the truth. A Block that kept the new value
+ * and rolled it back on a timer would show a reader a role that was not theirs
+ * for as long as the rollback took, and a reader who acted on it would be acting
+ * on a fiction.
+ *
+ * **`joined` and `sentAt` are moments, printed exactly as passed, and the
+ * honest reading is a Component the caller composes.** The argument is the one
+ * `compliance-01` makes for a review date and `member-list-01` makes for a
+ * last-seen: a Block that formatted the moment would be choosing a locale, a
+ * calendar and a granularity on a colleague's behalf, and would put `Intl` into
+ * every consumer's bundle for a rendering Prism has no stake in. So the value is
+ * printed as given, `joinedLabel` is offered for the caller who already has a
+ * formatter, and a caller who wants "three months ago" composes `relative-time`
+ * beside this Block. The cost is stated rather than hidden: a caller who passes a
+ * raw timestamp into a row that has no `joinedLabel` gets a raw timestamp beside
+ * a colleague's name, which is honest and rarely what was wanted.
+ *
+ * **A row's role control is named by the person whose role it changes, and the
+ * label is visually hidden because the name is already on screen.** In the rows
+ * arrangement the name is beside the control; in the table arrangement it is the
+ * row header. Either way it is on the page, so the visually hidden label adds
+ * nothing a reader sees and a great deal to a screen reader, which would
+ * otherwise meet twenty comboboxes with no idea which person any of them belongs
+ * to. Naming the control by the role instead was the alternative and it fails the
+ * WCAG rule that a visible label must be contained in the accessible name, and it
+ * would leave a reader asking which row.
+ *
+ * **It is a client Component, and the directive is unconditional.** The rule this
+ * follows is the one `member-list-01` states in full: a surface that attaches a
+ * handler is a client Component, and the directive is on the module rather than
+ * in a leaf so that a consumer composing a server page gets the boundary in one
+ * place they can see. The cost is that with `onRoleChange` omitted the whole
+ * module is still in the client graph, where the static arrangement would have
+ * shipped no JavaScript at all; the price was judged worth paying for one
+ * boundary rather than two arrangements of the same surface.
+ */
+export function SettingsMembers01({ eyebrow, title, description, members, invitations, pendingTitle, inviteLabel, roleOptions, roleLabel, onRoleChange, empty, columns, headingLevel = 'h2', className, }) {
+    // The handle a table below takes its name from; see the note on the table.
+    const headingId = useId();
+    const props = {
+        members,
+        invitations,
+        roleOptions,
+        roleLabel,
+        onRoleChange,
+        pendingTitle,
+        columns,
+    };
+    assertProps(props);
+    // The group holding the pending invitations is a group inside the section, so
+    // its title is one level below the section's own and travels with it.
+    const GroupTitle = childLevel(headingLevel);
+    const base = useId();
+    const asTable = columns !== undefined;
+    // A row's own controls get a column in the table arrangement, with no heading
+    // over it, for the reason `pricing-compare-01` leaves its corner empty: a
+    // heading would name a column of controls, which is not what the column is, and
+    // the controls are the caller's so each one carries its own accessible name.
+    const hasActions = members.some((member) => member.actions !== undefined);
+    // A role control needs somewhere to move a member to and somewhere to report
+    // the move, and it is withheld from the row the reader is on. See the Block
+    // JSDoc for why that last part is a decision rather than an omission.
+    const canChangeRole = onRoleChange !== undefined && roleOptions !== undefined;
+    const optionLabel = (option) => roleLabel === undefined ? option.label : roleLabel(option);
+    const renderRoleControl = (member) => {
+        if (!canChangeRole || roleOptions === undefined)
+            return null;
+        if (member.isSelf === true)
+            return null;
+        const controlId = `${base}-${member.id}-role`;
+        return (_jsxs(Field, { className: "min-w-40", "data-slot": "settings-members-role", children: [_jsx(FieldLabel, { htmlFor: controlId, className: "sr-only", children: member.name }), _jsxs(Select, { defaultValue: member.role, onValueChange: (value) => onRoleChange?.(member.id, value ?? ''), items: Object.fromEntries(roleOptions.map((option) => [option.id, optionLabel(option)])), children: [_jsx(SelectTrigger, { id: controlId, className: "w-full", children: _jsx(SelectValue, {}) }), _jsx(SelectContent, { children: roleOptions.map((option) => (_jsx(SelectItem, { value: option.id, children: optionLabel(option) }, option.id))) })] })] }));
+    };
+    const renderRoleWords = (member) => {
+        const control = renderRoleControl(member);
+        if (control !== null)
+            return control;
+        return (_jsx("span", { "data-slot": "settings-members-role", className: "text-sm", children: member.roleLabel ?? member.role }));
+    };
+    return (_jsxs(Section, { className: className, "data-slot": "settings-members", children: [_jsx(SectionHeading, { as: headingLevel, id: headingId, align: "left", eyebrow: eyebrow, title: title, description: description, className: "mb-10" }), _jsxs("div", { className: "flex flex-col gap-10", children: [_jsxs("div", { "data-slot": "settings-members-panel", className: "flex flex-col gap-4", children: [inviteLabel === undefined ? null : (_jsx("div", { "data-slot": "settings-members-invite", className: "flex justify-end", children: inviteLabel })), members.length === 0 ? (_jsx("p", { "data-slot": "settings-members-empty", className: "text-muted-foreground text-pretty text-sm", children: empty })) : asTable ? (_jsx("div", { className: "border-border overflow-hidden rounded-xl border", children: _jsxs(Table, { "aria-labelledby": headingId, "data-slot": "settings-members-table", children: [_jsx(TableHeader, { children: _jsxs(TableRow, { children: [columns.map((column) => (_jsx(TableHead, { scope: "col", className: cn('whitespace-normal', column.className), children: column.header }, column.id))), hasActions ? _jsx(TableHead, { scope: "col" }) : null] }) }), _jsx(TableBody, { children: members.map((member) => (_jsxs(TableRow, { "data-slot": "settings-members-row", "data-member": member.id, "data-self": member.isSelf === true ? 'true' : undefined, children: [columns.map((column) => {
+                                                        if (column.id === 'name') {
+                                                            return (_jsx(TableHead, { scope: "row", className: cn('text-foreground h-auto font-medium whitespace-normal', column.className), children: _jsxs("span", { className: "flex items-center gap-3", children: [member.avatar === undefined ? null : (_jsxs(Avatar, { className: "size-8", children: [member.avatar.src === undefined ? null : (_jsx(AvatarImage, { src: member.avatar.src, alt: "" })), _jsx(AvatarFallback, { className: "text-mono", children: initialsOf(member.avatar.name) })] })), _jsxs("span", { className: "flex min-w-0 flex-col", children: [_jsx("span", { children: member.name }), member.email === undefined ? null : (_jsx("span", { className: "text-muted-foreground text-xs font-normal", children: member.email })), member.selfLabel === undefined ? null : (_jsx("span", { className: "text-muted-foreground text-xs font-normal", children: member.selfLabel }))] })] }) }, column.id));
+                                                        }
+                                                        if (column.id === 'role') {
+                                                            return (_jsx(TableCell, { className: cn('whitespace-normal', column.className), children: renderRoleWords(member) }, column.id));
+                                                        }
+                                                        return (_jsx(TableCell, { className: cn('whitespace-normal tabular-nums', column.className), children: member.joined === undefined
+                                                                ? null
+                                                                : member.joinedLabel === undefined
+                                                                    ? member.joined
+                                                                    : member.joinedLabel(member.joined) }, column.id));
+                                                    }), hasActions ? (_jsx(TableCell, { "data-slot": "settings-members-actions", children: member.actions ?? null })) : null] }, member.id))) })] }) })) : (_jsx("ul", { "data-slot": "settings-members-rows", className: "border-border flex flex-col border-t", children: members.map((member) => (_jsxs("li", { "data-slot": "settings-members-row", "data-member": member.id, "data-self": member.isSelf === true ? 'true' : undefined, className: "border-border flex flex-wrap items-center gap-x-4 gap-y-2 border-b px-3 py-3", children: [member.avatar === undefined ? null : (_jsxs(Avatar, { className: "size-8", children: [member.avatar.src === undefined ? null : (_jsx(AvatarImage, { src: member.avatar.src, alt: "" })), _jsx(AvatarFallback, { className: "text-mono", children: initialsOf(member.avatar.name) })] })), _jsxs("span", { className: "flex min-w-0 flex-1 flex-col", children: [_jsx("span", { className: "text-sm font-medium", children: member.name }), member.email === undefined ? null : (_jsx("span", { className: "text-muted-foreground text-xs", children: member.email })), member.selfLabel === undefined ? null : (_jsx("span", { className: "text-muted-foreground text-xs", children: member.selfLabel }))] }), renderRoleWords(member), member.joined === undefined ? null : (_jsx("span", { "data-slot": "settings-members-joined", className: "text-muted-foreground shrink-0 text-xs tabular-nums", children: member.joinedLabel === undefined
+                                                ? member.joined
+                                                : member.joinedLabel(member.joined) })), member.actions === undefined ? null : (_jsx("span", { "data-slot": "settings-members-actions", className: "flex shrink-0 items-center gap-1", children: member.actions }))] }, member.id))) }))] }), (invitations?.length ?? 0) === 0 ? null : (_jsx(ListPanel, { "data-slot": "settings-members-invitations", scroll: false, title: _jsx(GroupTitle, { "data-slot": "settings-members-pending-title", className: "text-sm font-semibold", children: pendingTitle }), children: _jsx("ul", { "data-slot": "settings-members-invitation-list", className: "flex flex-col", children: invitations?.map((invitation) => (_jsxs("li", { "data-slot": "settings-members-invitation", "data-invitation": invitation.id, "data-expired": invitation.expiresLabel === undefined ? undefined : 'true', className: "border-border flex flex-wrap items-center gap-x-4 gap-y-1 border-b px-4 py-3 last:border-b-0", children: [_jsx("span", { className: "min-w-0 flex-1 truncate text-sm", children: invitation.email }), invitation.sentAt === undefined ? null : (_jsx("span", { "data-slot": "settings-members-invitation-sent", className: "text-muted-foreground shrink-0 text-xs tabular-nums", children: invitation.sentAt })), invitation.expiresLabel === undefined ? null : (_jsx("span", { "data-slot": "settings-members-invitation-expired", className: "text-muted-foreground shrink-0 text-xs", children: invitation.expiresLabel }))] }, invitation.id))) }) }))] })] }));
+}
+export default SettingsMembers01;

package/dist/blocks/settings-notifications-01/index.d.ts

@@ -0,0 +1,3 @@
+export { SettingsNotifications01, default } from './settings-notifications.js';
+export type { SettingsNotifications01Props, SettingsNotificationsChannel, SettingsNotificationsEvent, } from './settings-notifications.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/blocks/settings-notifications-01/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/blocks/settings-notifications-01/index.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,uBAAuB,EAAE,OAAO,EAAE,MAAM,0BAA0B,CAAA;AAK3E,YAAY,EACV,4BAA4B,EAC5B,4BAA4B,EAC5B,0BAA0B,GAC3B,MAAM,0BAA0B,CAAA"}

package/dist/blocks/settings-notifications-01/index.js

@@ -0,0 +1 @@
+export { SettingsNotifications01, default } from './settings-notifications.js';

package/dist/blocks/settings-notifications-01/settings-notifications.d.ts

@@ -0,0 +1,270 @@
+import { type ReactNode } from 'react';
+import { type HeadingLevel } from '../../components/ui/section.js';
+/**
+ * One thing that can happen on a channel, and whether this workspace wants to
+ * hear about it.
+ *
+ * The `on` boolean is the preference and not a request, and the difference is
+ * stated in the Block's JSDoc because it decides what a controlled switch costs:
+ * a Block that held the next value would show a reader a preference the product
+ * has not stored.
+ */
+export type SettingsNotificationsEvent = {
+    /** A stable key for the row, and the value handed back to `onToggle`. */
+    id: string;
+    /**
+     * The event's own name, as the product writes it, and the visible label of the
+     * control that turns it on.
+     *
+     * A short noun phrase, because it sits on a row beside a switch. A phrase that
+     * wraps is a row whose control is vertically centred against two lines, and a
+     * list of preferences is scanned on the left edge.
+     */
+    label: string;
+    /**
+     * The line under the event's name: when it fires, what it carries, what it
+     * costs.
+     *
+     * A node rather than a string because half of the useful sentences in this
+     * position carry a link to the thing being described, and a caller who has to
+     * flatten theirs to a string loses it.
+     */
+    description?: ReactNode;
+    /**
+     * The preference as the product has it, and not what the reader is about to
+     * change it to.
+     *
+     * The switch is controlled from this value and nothing else, so a change is a
+     * request rather than a mutation. See the Block's JSDoc for why that is the
+     * arrangement rather than the one that feels more responsive.
+     */
+    on: boolean;
+    /**
+     * Marks an event the product cannot work without, which draws the control
+     * read-only and asks the reader to accept the state rather than to change it.
+     *
+     * This is the load-bearing flag in the whole Block and the argument for it is
+     * the Block's JSDoc at length. The short version: a preference surface where
+     * every control is optional will let a reader turn off something the product
+     * cannot work without, and the failure arrives later, somewhere else, with
+     * nothing on this page to point at.
+     */
+    required?: boolean;
+    /**
+     * The mark that says this event cannot be turned off.
+     *
+     * Required whenever `required` is set, and a thrown diagnostic rather than a
+     * silent absence, for the reason `Status` gives for its own label: a control
+     * that will not move with nothing beside it saying so is a control a reader
+     * cannot tell from a fault.
+     */
+    requiredLabel?: string;
+};
+/**
+ * One channel a workspace can be notified on, and the events on it.
+ *
+ * A channel is a group, and the group is named by the product: whether a
+ * notification goes by email, by a message inside the product, by a push to a
+ * device or by a webhook is a fact about the product's architecture and about
+ * its users, and a design system that shipped a channel list would be shipping
+ * an architecture.
+ */
+export type SettingsNotificationsChannel = {
+    /** A stable key for the group, and the value handed back to `onToggle`. */
+    id: string;
+    /** The channel's own name, and the heading of the group. */
+    name: string;
+    /** The line under the channel's name: what it is for, and who else sees it. */
+    description?: ReactNode;
+    /** The events on this channel, in the order a reader should meet them. */
+    events: readonly SettingsNotificationsEvent[];
+};
+/**
+ * The props a SettingsNotifications01 takes.
+ *
+ * Every string is a prop and the Block ships none. There is no channel, no event,
+ * no default preference, no required set and not one of the three sentences a
+ * notification surface is most tempted to ship, which are the words on a switch,
+ * the words beside a control that will not move, and the note that says a product
+ * needs the event. A Block that shipped any of the three would be stating
+ * somebody else's notification policy inside their own product.
+ */
+export type SettingsNotifications01Props = {
+    /** Optional label above the section title. See the No-Default-Eyebrow Rule. */
+    eyebrow?: ReactNode;
+    /** The section title. Required, because a preferences list with no heading is a fragment. */
+    title: ReactNode;
+    /** One or two sentences under the title. */
+    description?: ReactNode;
+    /** The channels, in the order a reader should meet them. The Block does not sort. */
+    channels: readonly SettingsNotificationsChannel[];
+    /**
+     * Called when a reader turns one event on or off.
+     *
+     * A request and not a mutation: the switch is controlled from `event.on`, so
+     * nothing moves on this page until the product says it has. See the Block's
+     * JSDoc for why the truth is worth more here than the immediacy.
+     */
+    onToggle?: (channelId: string, eventId: string, on: boolean) => void;
+    /**
+     * The accessible name of one switch, given the channel, the event and the
+     * state the control would move to.
+     *
+     * Required whenever `onToggle` is set, and the last argument is the state
+     * pressing the control would produce rather than the state it is in, because a
+     * switch's accessible name has to say what turning it does. A name that says
+     * what the control currently is asks the reader to combine two facts before
+     * they can act, and the whole of a switch is that it is one press.
+     *
+     * The sentence must contain the event's own `label`, because that is the
+     * visible label of the control and the WCAG rule that a visible label must be
+     * contained in the accessible name is not a formality on this Block: a reader
+     * using voice control says the words they can see, and a switch whose announced
+     * name does not contain its own label cannot be activated by saying them.
+     *
+     * It is not consulted for an event marked `required`, and the Block's JSDoc
+     * says why: that control does not move, so a sentence describing what pressing
+     * it would do is a claim about a thing that cannot happen.
+     */
+    updateLabel?: (channel: {
+        id: string;
+        name: string;
+    }, event: {
+        id: string;
+        label: string;
+    }, on: boolean) => string;
+    /**
+     * The note that says the product cannot work without the marked events.
+     *
+     * Required whenever any event is marked `required`, and drawn once at the top
+     * of the section rather than repeated on each row, because it is the product's
+     * standing reason for the whole set rather than an excuse for one control. It
+     * is also the described-by of every read-only control on the page, which is the
+     * arrangement that makes a control which cannot move legible rather than
+     * mysterious.
+     */
+    disabledLabel?: string;
+    /**
+     * What the surface shows when there are no channels.
+     *
+     * Required, and the reason is that a product with no notification channels and
+     * a product whose channels failed to load are not the same page, and a Block
+     * that guessed between them would be guessing about somebody else's outage.
+     */
+    empty: ReactNode;
+    /** 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;
+};
+/**
+ * Per-channel notification preferences: a channel, a line about it, a set of
+ * switches for the events on it, and a note where the product has a standing
+ * requirement of its own.
+ *
+ * **This is the Block where a design system's care is most visible and least
+ * appreciated, because the reader came to change one thing and leave.** A
+ * preferences surface is the densest set of controls a product puts in front of a
+ * reader, and it is the one they visit least often and trust most. They are not
+ * reading it, they are hunting. They want the switch for the one event and they
+ * want to be sure of three things when they find it: that this is the right
+ * event, that pressing it does what they think, and that it did what they wanted.
+ * Everything below is in service of the third of those, which is the one a
+ * surface usually gets wrong, usually by being optimistic.
+ *
+ * **The `required` flag is the load-bearing decision, and the set is a prop
+ * because a design system that fixed the list would be deciding for every
+ * product which of its events are load-bearing.** The argument has two halves and
+ * both matter. A preference surface where every control is optional is a surface
+ * that will let a reader turn off something the product cannot work without: the
+ * reader is told the switch is theirs, presses it, the product stores the answer,
+ * and the failure arrives days later in a different part of the product with
+ * nothing on this page to point at. The reader is right that the switch was
+ * there and the product is right that the event was needed, and neither of them
+ * is wrong, which is the worst possible place for a disagreement to live. So a
+ * required set has to exist. And the fixed-list alternative is worse than the
+ * problem: this package does not know what any product cannot work without. A
+ * product whose password reset email is load-bearing and a product that mails
+ * nothing at all are both real, and a Block that shipped the first product's list
+ * would install it into the second, where a reader could turn off a notification
+ * that does not exist and a support ticket would arrive with no cause anyone can
+ * find. So the flag is on the event, the note is the caller's, and the
+ * consequence is that a consumer wiring this Block up has to decide which of their
+ * own events are load-bearing. That is a sentence worth naming rather than
+ * hiding: it is a decision, and it is theirs.
+ *
+ * **A required control is drawn read-only rather than disabled, and the reason is
+ * that a disabled control is not in the tab order.** A keyboard reader who tabs
+ * across a preferences surface with three required events meets three holes where
+ * three controls used to be. They cannot find the setting, they cannot come back
+ * to it, and there is nothing in the document to tell them the setting exists at
+ * all, so the most likely reading is that the page is broken or that the product
+ * has hidden something from them. Both are worse than the truth, which is that a
+ * decision has been made on their behalf. So the control keeps its place in the
+ * order, keeps its state announced, and takes the note as its description: the
+ * reader meets it, hears that it will not move, and hears why. The cost is
+ * stated rather than hidden, because it is real: a read-only control is drawn in
+ * the same ink as a live one, so the mark beside it and the note under the title
+ * are what carry the fact, and there is no flag on this package that dims it. A
+ * caller who wants the visual weight of a disabled control has to choose between
+ * that and the focus hole, and the focus hole is the worse of the two, so the
+ * decision here is not that read-only is better but that it is less bad.
+ *
+ * **The switch's accessible name says what pressing it will do, and the sentence
+ * is the caller's.** A switch announces its state, so a reader who meets a
+ * control named "Deploys" with the state off knows the current answer and has to
+ * work out the consequence themselves, which is the one step a switch exists to
+ * remove. So the name is composed from the state the control would move to, and
+ * it is a function rather than a record of strings because the honest sentence
+ * names the event, the channel and sometimes a qualification, and because a
+ * consumer in three languages has the sentence in three languages and Prism has
+ * none of them. The name is not consulted for a required event, and that is a
+ * consequence rather than an omission: a sentence describing what pressing a
+ * read-only control would do is a claim about a thing that cannot happen, and a
+ * Block that printed one would be the defect it exists to prevent.
+ *
+ * **The note is described once and repeated by reference, so every read-only
+ * control on the page carries it.** It is drawn at the top rather than repeated on
+ * each row, for the reason `list-panel` states for a count: it is the product's
+ * standing reason for the whole set, so a reader who meets it once has met it. The
+ * `aria-describedby` is what makes it true per control, and that is a real
+ * difference rather than a nicety: a sentence a reader has to go and find is a
+ * sentence most readers do not go and find, and a control that will not move with
+ * an unfound reason behind it is exactly the control a reader reports as broken.
+ * The same attribute carries the event's own description, which was drawn and never
+ * referred to, so the two are assembled rather than chosen between: a read-only
+ * event has both, and a reader who meets one without the other has to work out
+ * which half they are missing.
+ *
+ * **A switch is the control, and not a checkbox and not a button.** `Switch` is
+ * composed for all three reasons the Component's own JSDoc gives, and the third
+ * is the one that matters on this surface: a switch takes effect immediately, so
+ * there is no save control on the page for a reader to press and no state in which
+ * the page is holding changes the reader has not committed. That is the whole
+ * reason a preferences surface is drawn as switches rather than as a form, and
+ * re-deriving it here would mean a hand-written checkbox with no keyboard model, a
+ * hidden input that may not submit, and a page where a reader has to look for a
+ * button to find out whether they pressed the right thing.
+ *
+ * **The Block holds no preference state, so a failed change is the caller's to
+ * show.** `event.on` is the truth, the switch is controlled from it, and
+ * `onToggle` is a request. A Block that moved the switch and rolled it back would
+ * show a reader a preference the product rejected, and a reader who left the page
+ * in the moment between would leave believing they had turned something off that
+ * was still on. The arrangement is the one a server action wants, and it is
+ * stated rather than hidden: with a slow network the switch does not move until
+ * the product answers, which is slower than the alternative and the only version
+ * of it that is not lying.
+ *
+ * It is a client Component, and the directive is unconditional: a surface that
+ * attaches a handler owns the JavaScript that carries it, and the directive is on
+ * the module rather than in a leaf so a consumer composing a server page gets the
+ * boundary in one place they can see. `Switch` is the only client leaf it draws,
+ * and it is a client leaf for the same reason.
+ */
+export declare function SettingsNotifications01({ eyebrow, title, description, channels, onToggle, updateLabel, disabledLabel, empty, headingLevel, className, }: SettingsNotifications01Props): import("react").JSX.Element;
+export default SettingsNotifications01;
+//# sourceMappingURL=settings-notifications.d.ts.map

package/dist/blocks/settings-notifications-01/settings-notifications.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"settings-notifications.d.ts","sourceRoot":"","sources":["../../../src/blocks/settings-notifications-01/settings-notifications.tsx"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,SAAS,EAAS,MAAM,OAAO,CAAA;AAG7C,OAAO,EAIL,KAAK,YAAY,EAClB,MAAM,6BAA6B,CAAA;AAGpC;;;;;;;;GAQG;AACH,MAAM,MAAM,0BAA0B,GAAG;IACvC,yEAAyE;IACzE,EAAE,EAAE,MAAM,CAAA;IACV;;;;;;;OAOG;IACH,KAAK,EAAE,MAAM,CAAA;IACb;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE,SAAS,CAAA;IACvB;;;;;;;OAOG;IACH,EAAE,EAAE,OAAO,CAAA;IACX;;;;;;;;;OASG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB;;;;;;;OAOG;IACH,aAAa,CAAC,EAAE,MAAM,CAAA;CACvB,CAAA;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,4BAA4B,GAAG;IACzC,2EAA2E;IAC3E,EAAE,EAAE,MAAM,CAAA;IACV,4DAA4D;IAC5D,IAAI,EAAE,MAAM,CAAA;IACZ,+EAA+E;IAC/E,WAAW,CAAC,EAAE,SAAS,CAAA;IACvB,0EAA0E;IAC1E,MAAM,EAAE,SAAS,0BAA0B,EAAE,CAAA;CAC9C,CAAA;AAED;;;;;;;;;GASG;AACH,MAAM,MAAM,4BAA4B,GAAG;IACzC,+EAA+E;IAC/E,OAAO,CAAC,EAAE,SAAS,CAAA;IACnB,6FAA6F;IAC7F,KAAK,EAAE,SAAS,CAAA;IAChB,4CAA4C;IAC5C,WAAW,CAAC,EAAE,SAAS,CAAA;IACvB,qFAAqF;IACrF,QAAQ,EAAE,SAAS,4BAA4B,EAAE,CAAA;IACjD;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,OAAO,KAAK,IAAI,CAAA;IACpE;;;;;;;;;;;;;;;;;;;OAmBG;IACH,WAAW,CAAC,EAAE,CACZ,OAAO,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EACrC,KAAK,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EACpC,EAAE,EAAE,OAAO,KACR,MAAM,CAAA;IACX;;;;;;;;;OASG;IACH,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB;;;;;;OAMG;IACH,KAAK,EAAE,SAAS,CAAA;IAChB,8DAA8D;IAC9D,YAAY,CAAC,EAAE,YAAY,CAAA;IAC3B;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,CAAA;AAyED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwGG;AACH,wBAAgB,uBAAuB,CAAC,EACtC,OAAO,EACP,KAAK,EACL,WAAW,EACX,QAAQ,EACR,QAAQ,EACR,WAAW,EACX,aAAa,EACb,KAAK,EACL,YAAmB,EACnB,SAAS,GACV,EAAE,4BAA4B,+BAuL9B;AAED,eAAe,uBAAuB,CAAA"}