@nanisoft/prism-ui 0.13.0 → 0.16.0

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

@@ -0,0 +1,202 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useId } from 'react';
+import { Field, FieldDescription, FieldLabel } from '../../components/ui/field.js';
+import { Section, SectionHeading, childLevel, } from '../../components/ui/section.js';
+import { Switch } from '../../components/ui/switch.js';
+/**
+ * The refusals, so that a preferences surface never renders a control it cannot
+ * explain.
+ *
+ * A switch that moves and reports nothing, a switch that reports a move and
+ * cannot move, an event marked as one the product cannot work without and no
+ * words for the reader on either side of that, and a required set with no note
+ * saying so anywhere on the page. 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 { channels, onToggle, updateLabel, disabledLabel } = props;
+    if (onToggle !== undefined && updateLabel === undefined) {
+        throw new Error('SettingsNotifications01: onToggle was passed with no updateLabel, so every switch would be announced ' +
+            'by the name of the event alone. That name says what the control is, not what pressing it does, and ' +
+            'a reader who cannot tell those two things apart has to press the control to find out.');
+    }
+    if (onToggle === undefined && updateLabel !== undefined) {
+        throw new Error('SettingsNotifications01: updateLabel was passed with no onToggle, so the sentences would be composed ' +
+            'and then discarded, which is a caller who believes they have named the switches on a surface that ' +
+            'has none.');
+    }
+    for (const channel of channels) {
+        if (channel.events.length === 0) {
+            throw new Error(`SettingsNotifications01: the channel ${JSON.stringify(channel.name)} carries no events, so the group ` +
+                'would be a heading with a line under it and nothing to decide. Omit the channel, or give it the ' +
+                'events it is for.');
+        }
+        for (const event of channel.events) {
+            if (event.required === true &&
+                (event.requiredLabel === undefined || event.requiredLabel.trim() === '')) {
+                throw new Error('SettingsNotifications01: an event is marked required and passed no requiredLabel, so the control ' +
+                    'that will not move would say nothing about why. Pass the mark, and the note on the section.');
+            }
+        }
+    }
+    const anyRequired = channels.some((channel) => channel.events.some((event) => event.required === true));
+    if (anyRequired && (disabledLabel === undefined || disabledLabel.trim() === '')) {
+        throw new Error('SettingsNotifications01: an event is marked required and no disabledLabel was passed, so a reader ' +
+            'would meet a control that will not move with no sentence anywhere on the page explaining that a ' +
+            'product decision is what stopped them. Pass the note.');
+    }
+}
+/**
+ * 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 function SettingsNotifications01({ eyebrow, title, description, channels, onToggle, updateLabel, disabledLabel, empty, headingLevel = 'h2', className, }) {
+    assertProps({ channels, onToggle, updateLabel, disabledLabel });
+    // A channel is a group inside the section, so its name is one level below the
+    // section's own heading and travels with it when the Block is composed deeper.
+    const ChannelTitle = childLevel(headingLevel);
+    const base = useId();
+    const noteId = disabledLabel === undefined ? undefined : `${base}-note`;
+    // Whether there is anything at all to decide, which is a fact about the data
+    // rather than a prop a caller has to keep in step with the channels.
+    const hasEvents = channels.some((channel) => channel.events.length > 0);
+    if (!hasEvents) {
+        return (_jsxs(Section, { className: className, "data-slot": "settings-notifications", children: [_jsx(SectionHeading, { as: headingLevel, align: "left", eyebrow: eyebrow, title: title, description: description }), _jsx("p", { "data-slot": "settings-notifications-empty", className: "text-muted-foreground text-pretty text-sm", children: empty })] }));
+    }
+    return (_jsxs(Section, { className: className, "data-slot": "settings-notifications", children: [_jsx(SectionHeading, { as: headingLevel, align: "left", eyebrow: eyebrow, title: title, description: description, className: "mb-8" }), noteId === undefined ? null : (_jsx("p", { id: noteId, "data-slot": "settings-notifications-note", className: "text-muted-foreground mb-8 text-pretty text-sm", children: disabledLabel })), _jsx("div", { "data-slot": "settings-notifications-channels", className: "flex flex-col gap-10", children: channels.map((channel) => {
+                    if (channel.events.length === 0)
+                        return null;
+                    return (_jsxs("section", { "data-slot": "settings-notifications-channel", "data-channel": channel.id, className: "flex flex-col gap-5", children: [_jsxs("div", { className: "flex flex-col gap-1.5", children: [_jsx(ChannelTitle, { "data-slot": "settings-notifications-channel-name", className: "text-lg font-semibold tracking-tight", children: channel.name }), channel.description === undefined ? null : (_jsx("p", { className: "text-muted-foreground text-pretty text-sm", children: channel.description }))] }), _jsx("ul", { "data-slot": "settings-notifications-events", className: "flex flex-col", children: channel.events.map((event) => {
+                                    const controlId = `${base}-${channel.id}-${event.id}`;
+                                    const required = event.required === true;
+                                    const descriptionId = event.description === undefined ? undefined : `${controlId}-description`;
+                                    /*
+                                     * Up to two referrers, one attribute, assembled rather than chosen
+                                     * between. The event's own description says what the event is and
+                                     * what it carries, and the note says why a control will not move; a
+                                     * read-only event has both, and a reader who meets one without the
+                                     * other has to guess which half they are missing. Assembled from
+                                     * templates rather than from a `join`, for the reason
+                                     * `MultiCombobox` gives for its own pair: a bare separator literal
+                                     * is a string the copy gate reads as a space somebody typed.
+                                     */
+                                    const describedBy = descriptionId === undefined
+                                        ? required
+                                            ? noteId
+                                            : undefined
+                                        : required && noteId !== undefined
+                                            ? `${descriptionId} ${noteId}`
+                                            : descriptionId;
+                                    const describedByIds = describedBy === '' ? undefined : describedBy;
+                                    return (_jsxs("li", { "data-slot": "settings-notifications-event", "data-event": event.id, "data-required": required ? 'true' : undefined, className: "border-border flex flex-col gap-3 border-b py-4 last:border-b-0 sm:flex-row sm:items-start sm:justify-between sm:gap-6", children: [_jsxs(Field, { className: "min-w-0 gap-1", children: [_jsx(FieldLabel, { htmlFor: controlId, className: "text-base", children: event.label }), event.description === undefined ? null : (_jsx(FieldDescription, { id: descriptionId, children: event.description }))] }), _jsxs("div", { "data-slot": "settings-notifications-control", className: "flex shrink-0 items-center gap-3 pt-0.5 sm:pt-1", children: [required && event.requiredLabel === undefined ? null : (_jsx("span", { "data-slot": "settings-notifications-required", className: "text-muted-foreground text-xs font-medium", children: event.requiredLabel })), _jsx(Switch, { id: controlId, checked: event.on, readOnly: required, "aria-label": required || updateLabel === undefined
+                                                            ? undefined
+                                                            : updateLabel(channel, event, !event.on), "aria-describedby": describedByIds, onCheckedChange: onToggle === undefined
+                                                            ? undefined
+                                                            : (next) => onToggle(channel.id, event.id, next) })] })] }, event.id));
+                                }) })] }, channel.id));
+                }) })] }));
+}
+export default SettingsNotifications01;

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

@@ -0,0 +1,3 @@
+export { SettingsSecurity01, default } from './settings-security.js';
+export type { SettingsSecurity01Props, SettingsSecurityChangePassword, SettingsSecurityLabels, SettingsSecurityMethod, SettingsSecurityMethodState, SettingsSecurityPasswordField, SettingsSecuritySession, SettingsSecurityTwoFactor, SettingsSecurityTwoFactorState, } from './settings-security.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/blocks/settings-security-01/index.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAMjE,YAAY,EACV,uBAAuB,EACvB,8BAA8B,EAC9B,sBAAsB,EACtB,sBAAsB,EACtB,2BAA2B,EAC3B,6BAA6B,EAC7B,uBAAuB,EACvB,yBAAyB,EACzB,8BAA8B,GAC/B,MAAM,qBAAqB,CAAA"}

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

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

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

@@ -0,0 +1,439 @@
+import { type ReactNode } from 'react';
+import { type HeadingLevel } from '../../components/ui/section.js';
+/**
+ * Where a sign-in method stands.
+ *
+ * `pending` is the member that is not a binary, and the Block's JSDoc says what
+ * it does with it: a setup that is half finished is not a setting that is on, and
+ * a control drawn on it would let a reader turn off something that was never on.
+ */
+export type SettingsSecurityMethodState = 'enabled' | 'disabled' | 'pending';
+/**
+ * Where a second factor stands.
+ *
+ * `enrolled` is the third answer and it is the one a two-state surface cannot
+ * give: a secret has been generated and the reader has not yet confirmed it, so
+ * the account is neither protected nor unprotected and the honest word is neither
+ * on nor off.
+ */
+export type SettingsSecurityTwoFactorState = 'on' | 'off' | 'enrolled';
+/**
+ * One way a reader can prove who they are.
+ *
+ * A method and not a credential: the Block never sees a secret, and the words in
+ * every field here are the product's statements about its own authentication.
+ */
+export type SettingsSecurityMethod = {
+    /** A stable key for the row, passed back to `onMethodChange`, and carried as `data-method`. */
+    id: string;
+    /** The method's own name, as the product writes it: a passkey, a phrase, a code. */
+    name: string;
+    /** Where the method stands. Required, because a row with no state cannot be acted on. */
+    state: SettingsSecurityMethodState;
+    /**
+     * The words for the state, in the product's own vocabulary.
+     *
+     * Required whenever `state` is given, which is always, and a thrown diagnostic
+     * rather than a silent absence, for the reason `Status` states in full: the tone
+     * is a colour and the words are the information.
+     */
+    stateLabel?: string;
+    /**
+     * The line under the method's name: where the secret is kept, when it was last
+     * used, what turning it on will ask for.
+     *
+     * A node because half of the useful sentences in this position carry a link to
+     * the document that explains the method, and a caller who has to flatten theirs
+     * to a string loses it.
+     */
+    detail?: ReactNode;
+    /**
+     * The line naming when this method was added, already written as it should be
+     * read.
+     *
+     * A string rather than a moment and a formatter for the reason the other Blocks
+     * in this wave take it: a Block that formatted the moment would be choosing a
+     * locale and a granularity on a reader's behalf. A caller who wants "three months
+     * ago" composes `relative-time` and passes the reading.
+     */
+    addedLabel?: string;
+};
+/**
+ * One field of the change-password form, and which of the three it is.
+ *
+ * The union of three is what lets the Block make the reveal decision per field,
+ * which is the decision this Block's JSDoc argues for at length.
+ */
+export type SettingsSecurityPasswordField = {
+    /** A stable key for the field, and the element's `id`. */
+    id: string;
+    /** The field's own label, as the product writes it. */
+    label: string;
+    /**
+     * Which of the three fields this is.
+     *
+     * The name is a machine value and the arrangement is the whole of it: a `current`
+     * field is the one a reader is proving they know a secret, and a `new` or
+     * `confirm` field is the one they are about to retype. The Block draws a reveal
+     * control on the second kind and not on the first, and the Block's JSDoc gives
+     * the reason in full.
+     */
+    type: 'current' | 'new' | 'confirm';
+    /**
+     * The form field name the platform's password manager offers to save.
+     *
+     * Defaults to the right hint for the field's own kind, which is the arrangement
+     * `PasswordField` insists on and the reason this prop exists at all: a
+     * `current` field wants `current-password` and the other two want `new-password`,
+     * and getting it wrong on a new password produces an account the browser will
+     * not offer to sign in with.
+     */
+    autoComplete?: string;
+};
+/**
+ * The change-password form, and everything the caller has to say about it.
+ *
+ * `revealLabel` and `hideLabel` are here rather than being defaulted because they
+ * cannot be defaulted: a reveal control that says one sentence in a product whose
+ * interface is in another language is the defect the Component's own JSDoc was
+ * written against, and a Block that filled them in would be shipping English into
+ * every consumer's password field.
+ */
+export type SettingsSecurityChangePassword = {
+    /** The three fields, in the order a reader should meet them. */
+    fields: readonly SettingsSecurityPasswordField[];
+    /**
+     * Called with the three entries when the reader submits the form.
+     *
+     * The Block holds the values only long enough to hand them over, and it hands
+     * over all three whatever the form is missing, so a caller that renders two
+     * fields still receives a `confirm` of the empty string rather than `undefined`.
+     */
+    onSubmit: (value: {
+        current: string;
+        next: string;
+        confirm: string;
+    }) => void;
+    /** The words on the submit control. */
+    submitLabel: string;
+    /**
+     * The accessible name of a reveal control while the password is hidden.
+     *
+     * Required, and a prop rather than a default for the reason
+     * `PasswordField.revealLabel` gives in full.
+     */
+    revealLabel: string;
+    /**
+     * The accessible name of a reveal control while the password is showing.
+     *
+     * Required as a second sentence rather than as a state flag, because the name
+     * has to describe what pressing the control will do rather than what is
+     * currently true.
+     */
+    hideLabel: string;
+    /**
+     * What the product has to say about the change, after the reader pressed the
+     * control.
+     *
+     * The state is the caller's, so a form that shows a failure is showing a truth
+     * the Block cannot know, and the `error` state takes `role="alert"` so the
+     * message is announced when it appears rather than when the reader finds it.
+     */
+    status?: {
+        state: 'idle' | 'sending' | 'done' | 'error';
+        message: ReactNode;
+    };
+};
+/**
+ * One place a session is signed in from.
+ *
+ * A device and not a browser, and no address, because a security surface that
+ * shows a reader their own IP addresses is showing them something they cannot act
+ * on and did not ask for.
+ */
+export type SettingsSecuritySession = {
+    /** A stable key for the row, passed back to `onRevokeSession`, and carried as `data-session`. */
+    id: string;
+    /** The device, as the product describes it. */
+    device: string;
+    /** Where the session was opened, in the product's own terms. */
+    location?: string;
+    /**
+     * When the session began, in whichever of the two forms the caller already has
+     * it. Printed exactly as passed.
+     */
+    startedAt?: number | string;
+    /**
+     * The words for the start, given the moment. A function because the honest
+     * reading is a localised sentence.
+     */
+    startedAtLabel?: (value: number | string) => string;
+    /**
+     * Marks the session the reader is currently signed in through.
+     *
+     * The mark changes no control. See the Block's JSDoc for why revocation is
+     * offered on this row anyway, which is the part of this Block most likely to be
+     * got wrong.
+     */
+    isCurrent?: boolean;
+    /**
+     * The words that mark the reader's own session.
+     *
+     * Required whenever `isCurrent` is set, and a thrown diagnostic rather than a
+     * silent absence: a row the Block has decided is the reader's own, marked by
+     * nothing a reader can see, is a claim with no document to check it against.
+     */
+    currentLabel?: string;
+    /**
+     * The caller's own control for this row, in place of the Block's revoke
+     * control.
+     *
+     * A slot because revoking a session is an action a product usually confirms, and
+     * the confirmation is the product's: a sheet on some surfaces, a toast on
+     * others, and on a security surface a bare click is not a confirmation.
+     */
+    revoke?: ReactNode;
+};
+/**
+ * The second factor's state, and the caller's own control for it.
+ *
+ * A named type and not an inline object, for the ordinary reason: a consumer
+ * assembling a security surface in its own module has to be able to declare this
+ * shape once and hand the same object to the Block.
+ */
+export type SettingsSecurityTwoFactor = {
+    /** Where the second factor stands. */
+    state: SettingsSecurityTwoFactorState;
+    /**
+     * The words for the state, in the product's own vocabulary.
+     *
+     * Required whenever `state` is given, which is always, and a thrown diagnostic
+     * rather than a silent absence: this is the most load-bearing control on the page
+     * and a coloured dot with nothing beside it is a claim about the reader's account
+     * that nothing in the document backs up.
+     */
+    stateLabel?: string;
+    /**
+     * The control that moves the second factor, because it is a different control in
+     * each of the three states: enroll, turn on, turn off. A Block that chose would be
+     * choosing for every product that has one.
+     */
+    action?: ReactNode;
+};
+/**
+ * The four group names, all optional, and the reason they are optional is the
+ * Block's JSDoc.
+ *
+ * A caller who names a group gets a real heading one level below the section; a
+ * caller who names none gets a section of rows under the section heading, which
+ * is the right arrangement for the common case of a product with one group.
+ */
+export type SettingsSecurityLabels = {
+    /** Above the sign-in methods. */
+    methods?: ReactNode;
+    /** The card's title, on the change-password form. */
+    password?: ReactNode;
+    /** Above the sessions list. */
+    sessions?: ReactNode;
+    /** Above the second-factor row. */
+    twoFactor?: ReactNode;
+};
+/**
+ * The props a SettingsSecurity01 takes.
+ *
+ * Every string is a prop and the Block ships none. There is no method list, no
+ * session list, no device vocabulary, no state word, no field label, no submit
+ * sentence, no reveal sentence and not one of the sentences a security surface is
+ * most tempted to ship. A security surface is where a hardcoded word is least
+ * excusable and most likely, because the reader is reading about their own
+ * account and assumes every word on the page was chosen for them.
+ */
+export type SettingsSecurity01Props = {
+    /** Optional label above the section title. See the No-Default-Eyebrow Rule. */
+    eyebrow?: ReactNode;
+    /** The section title. Required, because a security surface with no heading is a fragment. */
+    title: ReactNode;
+    /** One or two sentences under the title. */
+    description?: ReactNode;
+    /**
+     * The names of the four groups this surface can draw.
+     *
+     * All four optional, and the reason is in the Block's JSDoc: a group with no name
+     * is not a mystery, and four required names would be four sentences a consumer
+     * writes for groups they may not have. A group whose name is passed becomes a
+     * real heading at `childLevel(headingLevel)`; a group whose name is not passed
+     * draws no heading and is a set of rows under the section's own.
+     */
+    labels?: SettingsSecurityLabels;
+    /** The sign-in methods, in the order a reader should meet them. */
+    methods: readonly SettingsSecurityMethod[];
+    /**
+     * Called when a reader turns a method on or off.
+     *
+     * A request and not a mutation, for the same reason as the other Blocks in this
+     * wave: the row's state comes from the data, so a control that moved and rolled
+     * back would show a reader a method state the product did not change.
+     */
+    onMethodChange?: (id: string) => void;
+    /**
+     * The accessible name of a method's control, given the method and the state the
+     * control would move to.
+     *
+     * Required whenever `onMethodChange` is set, and a function for the reasons
+     * `SettingsNotifications01.updateLabel` is one: a control's accessible name has
+     * to say what pressing it does, and the sentence has to contain the method's own
+     * name because that is the visible label of the control and the WCAG rule that a
+     * visible label must be inside the accessible name is what lets a reader using
+     * voice control act on the words they can see.
+     *
+     * It is not consulted for a method in the `pending` state, which draws no
+     * control at all, for the reason the Block's JSDoc gives.
+     */
+    methodToggleLabel?: (method: {
+        id: string;
+        name: string;
+    }, on: boolean) => string;
+    /**
+     * The change-password form. Omit it and the card is not drawn, which is right
+     * for a product that authenticates entirely by a method this Block already
+     * lists.
+     */
+    changePassword?: SettingsSecurityChangePassword;
+    /**
+     * The sessions this workspace is signed in from. Omit the group and it is not
+     * drawn.
+     */
+    sessions?: readonly SettingsSecuritySession[];
+    /**
+     * Called when a reader revokes a session.
+     *
+     * Offered on every row, including the reader's own. See the Block's JSDoc.
+     */
+    onRevokeSession?: (id: string) => void;
+    /**
+     * The words on a revoke control, given the session.
+     *
+     * Required whenever `onRevokeSession` is set, and a function because a column of
+     * controls all announced as "Revoke" is a column a screen reader user cannot act
+     * on, and because the honest sentence names the device: "Revoke the session on a
+     * work laptop" and "Revoke the session on a phone" are different consequences.
+     */
+    revokeLabel?: (session: {
+        id: string;
+        device: string;
+    }) => string;
+    /**
+     * The second factor's state, and the caller's own control for it.
+     *
+     * Omit it and the row is not drawn, which is right for a product with no second
+     * factor at all.
+     */
+    twoFactor?: SettingsSecurityTwoFactor;
+    /**
+     * What the surface shows when there are no methods.
+     *
+     * Required, and the reason is the one the other Blocks in this wave take: a
+     * workspace with no way to sign in and a workspace whose methods failed to load
+     * are not the same page.
+     */
+    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;
+};
+/**
+ * The security surface of a workspace: the ways in, the form that changes the one
+ * secret a reader is most likely to have forgotten, the places it is signed in
+ * from, and whether there is a second factor.
+ *
+ * **A settings surface is where a design system's care is most visible and least
+ * appreciated, and this is the one where the stakes of a small mistake are
+ * highest.** The reader came to change one thing and leave. They came because
+ * something worried them: a login they do not recognise, a device they do not
+ * own, a warning they read somewhere else. They are not reading this page, they
+ * are checking it, and the two or three questions they arrived with are answered
+ * somewhere in it. Everything below is arranged so that those questions are
+ * answerable without reading anything twice and without finding that the page
+ * moved while they were on it.
+ *
+ * **The reveal control is on the new password and the confirmation, and not on
+ * the current one, and the reason is what each field is for.** A reader retyping
+ * a password they have just chosen needs to see the characters, because they are
+ * checking their own memory of what they typed and the failure they are guarding
+ * against is a single wrong character in a string they cannot read. A reader
+ * typing the password they set six months ago is doing the opposite: they are
+ * proving they know a secret, and a reveal control on that field turns the proof
+ * into a lookup. Put it there and the field stops being a check, it becomes a
+ * read, and a password change is exactly the moment at which an observer over a
+ * reader's shoulder is most likely to be looking. The arrangement also matches
+ * what the platform already knows: the current field is the one a password manager
+ * can fill, and the other two are the ones it must offer to save.
+ *
+ * **A method that is pending draws no control, because a half-finished setup is
+ * not a setting that is on.** The three states are not a boolean with an extra
+ * case, and a switch drawn on a pending method would be a control offering to turn
+ * off something that was never on, in a panel whose whole job is to tell a reader
+ * what is protecting their account. A pending method is a device that asked to be
+ * added and has not been confirmed, and the only honest thing to draw beside it
+ * is the caller's words about that, and the reader's own control for finishing it.
+ *
+ * **The revoke control is offered on the session the reader is in, and that is the
+ * decision most likely to be got wrong.** Every instinct on a security page is to
+ * withhold the dangerous control from the row the reader is sitting on, and the
+ * instinct is wrong for a reason that has nothing to do with the interface: a
+ * reader who wants to end the session they are in is a reader who will find
+ * another way. They will ask an administrator, or they will sign out everywhere and
+ * guess, or they will simply carry on, and the third is the common one and the one
+ * that leaves the thing they were worried about open. Withholding the control does
+ * not remove the wish, it removes the honest route to it, and what it leaves behind
+ * is a support ticket and a still-open session. So the control is drawn on every
+ * row, and the mark on the reader's own row says which one they are in, so the
+ * consequence is legible rather than surprising. What the Block does not do is
+ * confirm: a bare click that signs the reader out of the page they are reading is
+ * not a confirmation, and the caller's `revoke` slot is where that belongs.
+ *
+ * **The three entries are handed over together whatever the form contains, and the
+ * form holds them only long enough to hand them over.** A caller who renders two
+ * fields receives a `confirm` of the empty string rather than `undefined`, because
+ * a value that is sometimes a string and sometimes absent is a value every caller
+ * has to narrow before it can use, and a password is not a value to narrow. The
+ * Block clears the three entries when the caller's status becomes `done`, which is
+ * the one piece of state it keeps about them, and that is a decision rather than an
+ * omission: a new password sitting in a form on a page about the reader's security
+ * is a worse thing than a caller who wanted to keep it, and the caller's `status`
+ * prop is exactly where the truth about the change lives.
+ *
+ * **The second factor has three states, and the third is the one a two-state
+ * surface cannot give.** A secret has been generated and the reader has not
+ * confirmed it, so the account is neither protected nor unprotected, and a surface
+ * offering only on and off makes a consumer draw an enrolled account as one of the
+ * two, which is either a false claim of protection or a false claim of exposure.
+ * The tone for it is `info` and for an off factor `neutral`, because turning a
+ * second factor off is a decision a reader is allowed to make on an account they
+ * control, and a page that alarms about it is a page that nags about something
+ * legal.
+ *
+ * **The four group names are optional, and the reason is that a group with no name
+ * is not a mystery.** A caller who names a group gets a real heading one level
+ * below the section's own, and a caller who names none gets a section of rows
+ * under the section heading, which is the right arrangement for the common case of
+ * a product with one group and no second factor. The alternative, four required
+ * names, is four sentences a consumer writes for a page they may not have: a
+ * product with no second factor would have to name that group's heading to satisfy
+ * a type, and the name would then sit in their source describing something they do
+ * not render. The cost is stated rather than hidden: a Block with four groups and
+ * no names is four lists under one heading, and a reader navigating by heading
+ * finds one entry where there are four regions. That is the caller's arrangement
+ * to make and easy to correct by passing four words.
+ *
+ * It is a client Component, and the directive is unconditional: the form holds
+ * state, the controls attach handlers, and a surface that owns either owns the
+ * JavaScript that carries it.
+ */
+export declare function SettingsSecurity01({ eyebrow, title, description, labels, methods, onMethodChange, methodToggleLabel, changePassword, sessions, onRevokeSession, revokeLabel, twoFactor, empty, headingLevel, className, }: SettingsSecurity01Props): import("react").JSX.Element;
+export default SettingsSecurity01;
+//# sourceMappingURL=settings-security.d.ts.map