@nanisoft/prism-ui 0.13.0 → 0.15.0

package/dist/blocks/two-factor-01/two-factor-01.js

@@ -0,0 +1,273 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useId, useState } from 'react';
+import { Button } from '../../components/ui/button.js';
+import { Card } from '../../components/ui/card.js';
+import { Checkbox } from '../../components/ui/checkbox.js';
+import { Field, FieldDescription, FieldError, FieldLabel } from '../../components/ui/field.js';
+import { LiveRegion } from '../../components/ui/live-region.js';
+import { OneTimeCode } from '../../components/ui/one-time-code.js';
+import { Section, SectionHeading } from '../../components/ui/section.js';
+import { cn } from '../../lib/utils.js';
+/**
+ * Whether a caller passed a word that is not there.
+ *
+ * Read as `string | undefined` rather than as the declared type, because the check
+ * is about the value that turned up rather than about what the type promised. A
+ * JavaScript caller and a value out of a session store both arrive with the type's
+ * guarantee already gone, and the diagnostic below is the last place that can still
+ * say what was wrong.
+ */
+function blank(value) {
+    return value === undefined || value.trim() === '';
+}
+/**
+ * The refusals, checked before anything is drawn so a caller's mistake is one
+ * diagnostic in a console rather than a nameless control on the screen where a reader
+ * is about to be asked to prove who they are.
+ *
+ * Six shapes, and this is the screen on which they are least forgivable. A code with
+ * no name is six anonymous fields. A code of length zero is a form that cannot be
+ * completed, and a reader cannot tell that from a broken one. Two selected methods is
+ * a screen that asks for one factor and reports another. A nameless remember row is a
+ * tick box a reader cannot find, and a tick box they cannot find is a session
+ * somebody else's colleague can walk into. A nameless resend control is a button
+ * whose only job is to be pressed and which announces itself as a button. A
+ * `remember.value` with no `onValueChange` is a control that will show one state and
+ * then stop agreeing with the caller, which on this screen is a claim about the
+ * reader's session.
+ */
+function assertTwoFactor(input) {
+    const { code, methods, remember, resend, cancel, submitLabel } = input;
+    if (blank(code.label)) {
+        throw new Error('TwoFactor01: the code field declares no label, so its six segments would be six anonymous fields ' +
+            'and a reader could not say out loud which one they were in. Pass the words the product uses for the ' +
+            'code it has sent.');
+    }
+    if (!Number.isInteger(code.length) || code.length < 1) {
+        throw new Error(`TwoFactor01: the code field declares a length of ${JSON.stringify(code.length)}, so the field would ` +
+            'render no segments at all, which is a form that cannot be completed and looks to a reader exactly ' +
+            'like one that is broken. Pass the number of characters the code your service issues has.');
+    }
+    let chosen = 0;
+    for (const method of methods ?? []) {
+        if (blank(method.name)) {
+            throw new Error(`TwoFactor01: the method ${JSON.stringify(method.id)} declares no name, so the row would announce ` +
+                'nothing about which factor it is, on the one screen where the reader has to be able to tell. Pass ' +
+                'the words the product uses.');
+        }
+        if (method.selected === true)
+            chosen += 1;
+    }
+    if (chosen > 1) {
+        throw new Error(`TwoFactor01: ${chosen} methods are marked selected, so the screen would be asking the reader for one ` +
+            'factor while handing their caller another, and the code that would be accepted is not the one the ' +
+            'reader was told to look for. Mark one, or none.');
+    }
+    if (blank(submitLabel)) {
+        throw new Error('TwoFactor01: submitLabel is blank, so the one control that verifies the reader would be announced as ' +
+            'a button. Pass the sentence.');
+    }
+    if (remember !== undefined) {
+        if (blank(remember.label)) {
+            throw new Error('TwoFactor01: a remember row was passed with no label, so the control would be a tick box with no ' +
+                'words beside it, and a tick box a reader cannot find is a session somebody can walk into on a ' +
+                'shared machine. Pass the sentence, or drop the row.');
+        }
+        if (remember.value !== undefined && remember.onValueChange === undefined) {
+            throw new Error('TwoFactor01: remember.value was passed with no onValueChange, so the row would show one state and ' +
+                'then stop agreeing with the caller, which on this screen is a claim about the reader own session. ' +
+                'Pass the pair, or neither.');
+        }
+    }
+    if (resend !== undefined && blank(resend.label)) {
+        throw new Error('TwoFactor01: a resend control was passed with no label, so the button whose only job is to be pressed ' +
+            'would be announced as a button. Pass the sentence.');
+    }
+    if (cancel !== undefined && blank(cancel.label)) {
+        throw new Error('TwoFactor01: a cancel control was passed with no label, so the way off this screen would be a button ' +
+            'a reader can reach and not identify, which is the wrong thing to leave unnamed on the screen where a ' +
+            'reader who arrived on the wrong link most needs to leave. Pass the sentence.');
+    }
+}
+/**
+ * A second factor: which one is being asked for, the code itself, the control that
+ * asks for it again, and the caller's own words for what happened.
+ *
+ * **The translation, because the pattern is not ours and the framing is.** A
+ * storefront publishes a verification screen: a method line saying where the code
+ * came from, a field for the code, a "send another" link, a "remember this device"
+ * tick, a button and the way back, and its purpose is to confirm that the person
+ * holding the card is the person who has the account, before a purchase is taken. The
+ * composition is that screen and is unchanged, down to the composition of the code
+ * field. What the screen authorises is a machine acting on this reader's behalf for
+ * the first time, and that is why the standard for what it refuses is higher here
+ * than anywhere else in this package.
+ *
+ * **It does not verify the code. It does not count the attempts. And it does not own
+ * the lockout.** Each of those is the consumer's, and each is a security decision
+ * rather than a rendering one, and the three together are what this Block is for.
+ *
+ * A Block that counted attempts would be shipping a lockout policy into every product
+ * that installed it: three tries on one product and five on another, with no
+ * configuration point a consumer can find, in a file none of them reads. A lockout is
+ * an availability decision and it belongs to the product, because only the product
+ * knows what being locked out of an estate observation tool costs. It costs a
+ * two-person shift nothing when a market is closed, and it costs a whole capture
+ * window when the market is open, and the number of attempts a caller will accept is
+ * a different number on Tuesday from the number it will accept on Wednesday at nine.
+ * Worse, a lockout is a denial of service that anybody can aim at a reader: a
+ * component library that enforces one has handed every installer a way for a stranger
+ * to lock a colleague out of their own work by typing six wrong characters, and it
+ * has done that invisibly.
+ *
+ * So the Block hands the code across a form boundary and draws what it is given. It
+ * keeps no count because it has no memory between the reader's attempts to record, it
+ * has no clock to expire a lockout with, and it cannot know whether an attempt even
+ * reached the caller's server. The caller's `status` is the only thing on this screen
+ * that says whether anything happened, and the caller's `code.error` is the only thing
+ * that says what was wrong with the entry.
+ *
+ * **What it authorises.** A successful `onSubmit` means the caller's own server has
+ * accepted this code for this session and will now let this reader's machine act. That
+ * is a larger grant than the sign-in it completes: a sign-in opens a session for a
+ * person, and a second factor decides whether the machine that person is holding may
+ * act on their behalf. It is also the least reversible grant on this surface, because
+ * the reader is here because something already knows they are the account's owner, and
+ * a code that was guessed, replayed or phished is accepted exactly the same as one
+ * that was typed by the person it belongs to.
+ *
+ * **What it deliberately does not do, beside the three above.** It will not generate
+ * a code, and it will not say how long one is valid. Both of those are the caller's
+ * verification service, and a Block that drew an expiry it had invented would be
+ * telling a reader their code is still good when the caller's server has already
+ * stopped accepting it, which is the one error on this screen that costs a reader a
+ * second attempt they could have avoided. The `expiresLabel` idea from the
+ * passwordless screen is deliberately absent here for that reason: there is no prop
+ * for it, because there is no honest reading of a duration this Block can reach, and
+ * a caller that wants to state one composes it into `description` or `status.message`
+ * where it is their sentence and not this Block's claim.
+ *
+ * **The code field is `OneTimeCode` and not six `<input>` elements written here, and
+ * the Component's own arguments are the reason and they are worth restating once
+ * because this is the screen they matter on.** A paste of the whole code lands in
+ * every segment: a reader who has the code on their clipboard has already done the
+ * hard part, and a field that accepted one character per paste would make them retype
+ * it one box at a time, which is what they are on their phone to avoid. A refused
+ * character is refused rather than stored, so "123 456" pastes as `123456` and
+ * `12345a6` pastes as `123456`, because the alternative is a field that looks right
+ * and a form that does not submit. The code is one value and not six, so Backspace
+ * removes a character from the string and the characters after it close up, because
+ * six boxes that each had to be emptied by hand would need a rule for what Backspace
+ * on an empty box means and every version of that rule is wrong for somebody. And the
+ * whole code is one Tab stop, so the reader reaches the first segment once and the
+ * rest follow as they type. Five decisions, each of which is wrong in a different
+ * product if this Block made its own.
+ *
+ * **The code's description cannot be wired to the segments, and the reason is that
+ * `OneTimeCode` forwards no props beyond the ones it declares.** It is a deliberate
+ * decision in that Component, so a caller cannot attach a description or an error to
+ * the segments by accident. The consequence here is that `code.description` is drawn
+ * above the field where a reader reaches it first and `code.error` is drawn below it
+ * with `role="alert"` so it is announced when it appears rather than when the reader
+ * finds it. That is the next best arrangement available and it is stated rather than
+ * hidden, because on a security surface a wiring somebody assumed and did not check
+ * is exactly the kind of thing this Block's documentation exists to prevent.
+ *
+ * **The honest failure state is the caller's sentence, and the reason is that a
+ * second factor has more failure shapes than a design system should be able to name.**
+ * The code can be wrong, expired, already used, for a factor the reader did not
+ * choose, for a session that has gone, or for an account that has just been locked by
+ * the caller's own attempt counter. The reader can dismiss a prompt, arrive with a
+ * code for another device, or be rate limited. And the distinction between them is
+ * itself a security fact: a screen that says "that code has expired" is telling a
+ * reader something an attacker learns too. So `status` and `code.error` are both props
+ * with the caller's words, this file holds no accepted flag and no failure flag, and
+ * what the Block does about an outcome is the two rendering decisions: the submit and
+ * resend controls are refused while the caller's own state says a request is in
+ * flight, because a second press is a second attempt counted against a limit the
+ * Block cannot see, and the outcome is drawn in one live region, `assertive` for the
+ * refusal, because a reader who has typed six characters and got nothing back is a
+ * reader who will type six more.
+ *
+ * **The method list is drawn and never changed, and the cost is that the Block cannot
+ * offer the reader another way in.** A product with three factors and a reader
+ * without access to the one being asked for has a problem, and the honest answer is a
+ * control that changes the selection, which is a request to the caller's server and a
+ * state this Block would then be reporting rather than holding. So `selected` is the
+ * caller's, the selected row is marked with `aria-current` and a rule in the primary
+ * colour so the mark is not a colour alone, and a consumer who needs the chooser
+ * composes their own beside this Block.
+ *
+ * **It is a client Component, and the directive is unconditional.** `onSubmit` is a
+ * function, a function is a piece of state, and state is a client module: a server
+ * Component cannot hand an event handler to a `<form>`, so a caller rendering this
+ * from a server component gets a form that submits and calls nothing. The code itself
+ * is already client-side for the same reason it is a segmented field, and
+ * `OneTimeCode` is a client Component whichever way this one is drawn.
+ */
+export function TwoFactor01({ eyebrow, title, description, methods, code, onSubmit, submitLabel, submitting = false, remember, resend, status, cancel, headingLevel = 'h2', className, }) {
+    assertTwoFactor({ code, methods, remember, resend, cancel, submitLabel });
+    const generated = useId();
+    const codeId = `${generated}-code`;
+    const rememberId = `${generated}-remember`;
+    const rememberDescriptionId = `${generated}-remember-description`;
+    const errorId = code.error === undefined ? undefined : `${generated}-code-error`;
+    const busy = submitting || status?.state === 'working';
+    const chosen = methods?.find((method) => method.selected === true);
+    /*
+     * The tick, and the one piece of render-time state that lets the control leave the
+     * confirmed state. The confirm state is entered by the reader pressing resend, which
+     * the Block knows about because it is the Block own control, and it is left when the
+     * caller's own status changes, which is the only signal this Block has that the
+     * outcome of that resend was reported. Adjusted during render rather than in an
+     * effect, because the trigger is a prop changing and this is the arrangement React
+     * documents for it.
+     */
+    const [remembered, setRemembered] = useState(remember?.value ?? false);
+    const [seenRemember, setSeenRemember] = useState(remember?.value);
+    if (seenRemember !== remember?.value) {
+        setSeenRemember(remember?.value);
+        setRemembered(remember?.value ?? false);
+    }
+    const [resent, setResent] = useState(false);
+    const [seenState, setSeenState] = useState(status?.state);
+    if (seenState !== status?.state) {
+        setSeenState(status?.state);
+        setResent(false);
+    }
+    const setRemember = (value) => {
+        setRemembered(value);
+        remember?.onValueChange?.(value);
+    };
+    /*
+     * The three sentences the resend control can carry, resolved once here rather than
+     * as a nested ternary inside the call: the caller's own state first, because a
+     * second press while the first request is in flight is a second code asked for
+     * against a limit this Block cannot see; then the fact that the reader has already
+     * asked; then the resting name. Each of the two optional names falls back to the
+     * one that is required, so a caller who passes only `label` gets one sentence
+     * throughout, which is a control that reads the same before and after and a trap
+     * the caller's own status can still get them out of.
+     */
+    const resendText = resend === undefined
+        ? undefined
+        : busy && resent
+            ? (resend.cooldownLabel ?? resend.confirmLabel ?? resend.label)
+            : resent
+                ? (resend.confirmLabel ?? resend.label)
+                : resend.label;
+    const handleSubmit = (event) => {
+        event.preventDefault();
+        onSubmit({ code: code.value, method: chosen?.id, remember: remembered });
+    };
+    return (_jsx(Section, { "data-slot": "two-factor-01", className: cn(className), children: _jsxs("div", { "data-slot": "two-factor-01-body", className: "flex flex-col gap-10", children: [_jsx(SectionHeading, { as: headingLevel, align: "left", eyebrow: eyebrow, title: title, description: description }), _jsxs(Card, { "data-slot": "two-factor-01-card", className: "max-w-measure-narrow gap-0 px-6", children: [_jsxs("form", { "data-slot": "two-factor-01-form", onSubmit: handleSubmit, className: "flex w-full flex-col gap-5", children: [methods === undefined || methods.length === 0 ? null : (_jsx("ul", { "data-slot": "two-factor-01-methods", className: "border-border flex flex-col border-t", children: methods.map((method) => (_jsxs("li", { "data-slot": "two-factor-01-method", "data-method": method.id, "aria-current": method.selected === true ? 'true' : undefined, className: cn('flex flex-col gap-0.5 border-b border-s-2 py-3 ps-3 last:border-b-0', 
+                                        // One colour class and not two, because the two would be two
+                                        // single-class declarations of the same property and the one that
+                                        // won would be the one Tailwind happened to emit last.
+                                        method.selected === true ? 'border-primary' : 'border-border'), children: [_jsx("span", { "data-slot": "two-factor-01-method-name", className: "text-sm font-medium", children: method.name }), method.detail === undefined ? null : (_jsx("span", { "data-slot": "two-factor-01-method-detail", className: "text-muted-foreground text-sm text-pretty", children: method.detail }))] }, method.id))) })), _jsxs(Field, { "data-slot": "two-factor-01-code", "data-invalid": errorId === undefined ? undefined : 'true', children: [code.description === undefined ? null : (_jsx(FieldDescription, { children: code.description })), _jsx(FieldLabel, { htmlFor: codeId, children: code.label }), _jsx(OneTimeCode, { id: codeId, label: code.label, length: code.length, value: code.value, onValueChange: code.onValueChange, ...(code.characters === undefined ? null : { characters: code.characters }), ...(code.segmentLabel === undefined ? null : { segmentLabel: code.segmentLabel }) }), errorId === undefined ? null : (_jsx(FieldError, { id: errorId, children: code.error }))] }), resend === undefined ? null : (_jsx("div", { "data-slot": "two-factor-01-resend-row", children: _jsx(Button, { "data-slot": "two-factor-01-resend", type: "button", variant: "ghost", size: "sm", disabled: busy, onClick: () => {
+                                            setResent(true);
+                                            resend.onResend();
+                                        }, className: "self-start", children: resendText }) })), remember === undefined ? null : (_jsxs("div", { "data-slot": "two-factor-01-remember", className: "flex items-start gap-2.5", children: [_jsx(Checkbox, { id: rememberId, checked: remembered, onCheckedChange: (next) => setRemember(next === true), className: "mt-0.5" }), _jsxs("div", { className: "flex flex-col gap-1", children: [_jsx(FieldLabel, { htmlFor: rememberId, className: "font-normal", children: remember.label }), remember.description === undefined ? null : (_jsx(FieldDescription, { id: rememberDescriptionId, children: remember.description }))] })] })), _jsxs("div", { "data-slot": "two-factor-01-actions", className: "flex flex-col gap-3", children: [_jsx(Button, { "data-slot": "two-factor-01-submit", type: "submit", disabled: busy, className: "w-full", children: submitLabel }), _jsx(LiveRegion, { "data-slot": "two-factor-01-status", politeness: status?.state === 'error' ? 'assertive' : 'polite', busy: busy, className: cn('text-sm', status?.state === 'error' ? 'text-destructive font-medium' : 'text-muted-foreground'), children: status?.message })] })] }), cancel === undefined ? null : (_jsx("div", { "data-slot": "two-factor-01-cancel-row", className: "border-border border-t pt-5", children: _jsx(Button, { "data-slot": "two-factor-01-cancel", type: "button", variant: "ghost", size: "sm", onClick: cancel.onCancel, children: cancel.label }) }))] })] }) }));
+}
+export default TwoFactor01;

package/dist/blocks/user-profile-01/index.d.ts

@@ -0,0 +1,3 @@
+export { UserProfile01, default } from './user-profile-01.js';
+export type { UserProfile01Fact, UserProfile01Props } from './user-profile-01.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/blocks/user-profile-01/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/blocks/user-profile-01/index.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAA;AAI1D,YAAY,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAA"}

package/dist/blocks/user-profile-01/index.js

@@ -0,0 +1 @@
+export { UserProfile01, default } from './user-profile-01.js';

package/dist/blocks/user-profile-01/user-profile-01.d.ts

@@ -0,0 +1,258 @@
+import type { ReactNode } from 'react';
+import { type HeadingLevel } from '../../components/ui/section.js';
+/**
+ * One fact about a person, as a profile states it: the term and the answer.
+ *
+ * A node of its own rather than a re-export of `Fact`, and the reason is that
+ * `Fact` is four fields and this profile has two of them. A re-export would put a
+ * `href` and a `newTab` on a type whose only drawing is a definition list with no
+ * anchor in it, and a caller reading the type would reasonably expect those two to
+ * do something. The cost of the narrower type is that a caller whose fact value is
+ * a destination composes `FactList` themselves rather than passing it here, and
+ * that is the honest answer because the destination is a decision about their own
+ * routes rather than a fact about a person.
+ */
+export type UserProfile01Fact = {
+    /**
+     * The caller's stable key for this fact.
+     *
+     * Required, because a profile's facts are very often assembled from a store the
+     * caller already keys, and re-deriving a key here would be a second identity for
+     * one value. It is not drawn and it is not on the markup: `FactList` owns the
+     * row and keys it by position, so a caller whose facts reorder between renders
+     * and who needs row identity composes `FactList` directly. That is the cost and
+     * it is a small one.
+     */
+    id: string;
+    /**
+     * The term that names the fact.
+     *
+     * A short noun phrase, because a column of these is read by scanning its left
+     * edge and a term that wraps to two lines costs the whole column its alignment.
+     * A `string` rather than a node, for the same reason `Fact`'s own `label` is
+     * scanned rather than read.
+     */
+    label: string;
+    /**
+     * The answer.
+     *
+     * A node, and the reason is that a profile's answers are not all the same kind
+     * of thing: a date is a `RelativeTime`, a place is a place, a count is a figure
+     * the caller has already formatted in their own locale, and a licence key is
+     * something this Block must not set in a mono face on the caller's behalf
+     * because it does not know what a key looks like in their product.
+     */
+    value: ReactNode;
+};
+/**
+ * The props a UserProfile01 takes.
+ *
+ * Every string is a prop and the Block ships none: no name, no role, no
+ * biography, no fact and not one letter of any of them. A profile is a claim about
+ * a person, and a Block that shipped a name would put Prism's staff, or a
+ * stranger's, into every consumer's product.
+ */
+export type UserProfile01Props = {
+    /**
+     * The person's own name, as they publish it.
+     *
+     * Required, and it is the section heading rather than a line inside the body,
+     * which is the decision this Block is shaped around. A reader who arrives at a
+     * profile is arriving for one person, so the name is the thing the section is
+     * about and it belongs in the outline at the level the surrounding document
+     * gives this Block. A profile whose name was a `span` inside a band would be a
+     * page a reader cannot navigate to by heading, and a page whose only content is
+     * one person is exactly the page a reader navigates to by heading.
+     */
+    name: string;
+    /**
+     * What they do, in the words the caller uses.
+     *
+     * Drawn as the section's supporting line rather than as a fact, because a role
+     * is the answer to the question a reader arrives with and everything in `facts`
+     * is the answer to a question they did not know to ask. It is a `string` and not
+     * a node because a role is a short noun phrase in a product's own vocabulary and
+     * there is nothing in it to emphasise.
+     */
+    role?: string;
+    /**
+     * A paragraph or two about the person, in the caller's own words.
+     *
+     * A node, and drawn at the reading measure, because a biography is prose and a
+     * line of prose at card width is a caption. Nothing here truncates it: a Block
+     * that cut a biography at three lines with an ellipsis would be deciding which
+     * part of a person's account of their own work matters, and it would do it by
+     * cutting mid-sentence, which is the one place a truncation reliably removes the
+     * qualification rather than the flattery. A caller who wants three lines writes
+     * three lines.
+     */
+    bio?: ReactNode;
+    /**
+     * The portrait, with the name the initials come from.
+     *
+     * **A slot and never a drawn silhouette, and the reason is that a fallback which
+     * is a person-shaped glyph is a claim about a person the system knows nothing
+     * about.** A grey disc with a head and shoulders in it says there is a person
+     * here, which is a fact, and it says the same thing about every reader of every
+     * product that installs this Block, so a reader who has seen three of them has
+     * learned nothing about anybody. The fallback here is the person's own initials,
+     * which is derived from the caller's own data rather than chosen by this package,
+     * so a reader who cannot see the photograph still recognises the name beside it.
+     * Omit the whole field for a person the caller has no photograph of: this Block
+     * then draws no mark at all rather than a placeholder, and a profile with no
+     * portrait and a name is a complete profile.
+     */
+    avatar?: {
+        /** The photograph. Omit it, or pass a URL that fails, for the initials. */
+        src?: string;
+        /** The person's name, which is the initials' source. */
+        name: string;
+    };
+    /**
+     * The facts, in the order a reader should meet them.
+     *
+     * Order is the caller's because it is a claim about what matters most, and a list
+     * that sorted itself would be making that claim on the caller's behalf. Omit it
+     * for a person whose whole profile is a name and a role, which is a real and
+     * common case rather than a thin one.
+     */
+    facts?: readonly UserProfile01Fact[];
+    /**
+     * The controls that belong to this person rather than to the page: follow,
+     * message, assign, remove.
+     *
+     * A slot and not a set of named controls, because which actions a person has is
+     * the caller's fact, and a Block that drew a message button and a kebab menu
+     * would be drawing one product's idea of what can be done to a colleague. Each
+     * control inside is the caller's own Component, so this is where a caller
+     * composes their own menu rather than asking the Block to grow one.
+     */
+    actions?: ReactNode;
+    /**
+     * The caller's own sections, under a rule: activity, permissions, history.
+     *
+     * A slot and not a tab strip, and the reason is that tabs are a behaviour as well
+     * as a look. Which sections exist, which one is showing, and what happens when
+     * the reader changes it are three decisions about the caller's application, and a
+     * Block that drew the strip would have to own all three to make it work. So the
+     * space is here, a rule is drawn above it, and `Tabs` is the caller's to compose.
+     */
+    tabs?: ReactNode;
+    /**
+     * Whether the portrait sits beside the name or above it.
+     *
+     * @defaultValue 'header'
+     *
+     * `header` is the wide arrangement and it is right wherever the profile is a band
+     * across a page. `sidebar` is the narrow one: portrait above, everything stacked
+     * in a single column at the reading measure, which is what a profile looks like
+     * in a rail or on a phone. It is a layout prop and not a `className` because
+     * swapping the arrangement is a decision a page makes repeatedly, and
+     * re-deriving it from utility classes at each call site is how a page ends up
+     * with two profiles on opposite sides and no reason why.
+     */
+    layout?: 'header' | 'sidebar';
+    /**
+     * Heading level for the person's name. Defaults to `h2` because a Block is
+     * composed, not a page. See `HeadingLevel`.
+     */
+    headingLevel?: HeadingLevel;
+    /**
+     * Layout only, exactly as on every Component and Block. Changing a Prism-owned
+     * visual property from here is prohibited.
+     */
+    className?: string;
+};
+/**
+ * One person in full: a portrait where there is one, a name, a role, a biography,
+ * a set of facts, the caller's own controls, and room for the caller's own
+ * sections underneath.
+ *
+ * **This is a Block and not a Card, and not `MemberList01`, and the three facts
+ * that separate them are all about how many people are on the page and why the
+ * reader came.** A profile is one person in full and the reader arrived for them:
+ * they followed a link, they opened a record, they are looking at the one subject
+ * the page is about, and everything on it is about that person. A member list is
+ * many people and the reader is looking for one, which is the opposite reading
+ * order: the reader scans a column of names and stops at one, so a member list is
+ * optimised for scanning and a profile is optimised for reading. A card is a
+ * bounded group of related content, and a profile is not a group: it has one
+ * subject, and a subject in a frame reads as a set of facts about a thing rather
+ * than as the thing. The three are separately the right answers to three different
+ * pages, and a Block that blurred them would be a Block whose weight was wrong for
+ * whichever page used it.
+ *
+ * **The facts compose `FactList` rather than being drawn as a definition list
+ * here, and the reason is the empty case, quoted from the Component: "An empty
+ * list renders nothing rather than an empty frame, so a caller that has nothing to
+ * say does not get a bordered box with a title above it."** A profile is very
+ * often a person with three facts and also a person with none, and the second case
+ * is not a defect to be papered over with a placeholder row; it is a person whose
+ * whole profile is a name. `FactList` draws the real `<dl>` with the term before its
+ * answer, which is what a specification is and what a pair of columns is not, and
+ * it draws the hairlines and the alignment that a hand-rolled version gets subtly
+ * wrong. Writing a second definition list here would put a second answer to "how
+ * does a set of facts read" in one package, and the second answer is always the one
+ * that disagrees. The cost is stated rather than hidden: `FactList` keys its own
+ * rows by position, so a caller whose facts reorder between renders and who needs
+ * row identity composes the Component directly rather than passing them here.
+ *
+ * **The portrait is a slot and no mark is drawn in its place, because a fallback
+ * which is a person-shaped glyph is a claim about a person this system knows
+ * nothing about.** A silhouette says there is a person here, which is true, and it
+ * says it identically about every reader of every product that installs this
+ * Block, so a reader who has seen four of them has learned nothing about any of
+ * them. The fallback that ships is the person's own initials, derived from the
+ * caller's data by a rule this file repeats rather than imports, so a reader who
+ * cannot see the photograph still recognises the name printed beside it. Omit
+ * `avatar` entirely and nothing is drawn where the portrait would be, which is the
+ * honest state: a person the caller has no photograph of is still a person, and a
+ * grey disc is a claim that the absence is a gap.
+ *
+ * **The name is the section heading and not a line in the body, and that is the
+ * decision the rest of the Block follows from.** A page whose only subject is one
+ * person is a page a reader reaches by following a link and navigates away from by
+ * heading, so a name in a `span` is a name no reader can come back to. It also
+ * settles the arrangement: the name is at `headingLevel`, the role is the
+ * supporting line under it, and the facts are the answers to questions the reader
+ * did not arrive with, which is why they are a definition list and not more
+ * headings. The cost is that the section heading is the person's name, so a page
+ * with two profiles on it has two sections whose titles are people, and a
+ * consumer who wants a page titled by the product instead composes the profile
+ * inside their own `Section` rather than using this one.
+ *
+ * **`actions` and `tabs` are slots, and both are refused as anything else.** The
+ * controls that belong to a person rather than to the page are the caller's fact:
+ * follow, message, assign and remove are four different products' ideas, and a
+ * Block that drew one of them would be drawing a workflow. Tabs are worse, because
+ * a tab strip is a behaviour as much as a look: which sections exist, which one is
+ * showing, and what happens when the reader changes it are three decisions about
+ * the caller's application, and a Block that drew the strip would have to own all
+ * three for it to work. So the space is here, a rule is drawn above it, and
+ * `Tabs` is the caller's to compose. The cost is that this Block does not enforce
+ * a relationship between the two, and a caller who passes neither gets a profile
+ * with a facts list and nothing else, which is a valid page.
+ *
+ * **There is no motion in this Block, and the reason is worth stating because the
+ * absence is a decision rather than an oversight.** The first law of motion covers
+ * feedback, which is a response to something the reader did, and a profile has
+ * nothing the reader pressed: there is no control that opens, no panel that
+ * closes, and no row that changes state. The second law covers a cycle, which is a
+ * demonstration of a mechanism, and the test that decides which law a motion falls
+ * under is falsifiable: stop the animation, is the figure still true and still
+ * legible? There is no figure here at all, so the question does not arise, and a
+ * Block that answered it by animating the portrait in would be decoration wearing
+ * the costume of a demonstration, which is the thing the first law was written to
+ * exclude. The one place a transition could honestly go is the caller's own
+ * controls, and those are the caller's Components with their own motion already
+ * settled.
+ *
+ * It is a server Component: no hook, no state, no effect and no client code of its
+ * own. The portrait is `Avatar`, which is a client Component whose only client work
+ * is measuring whether an image has loaded, so a profile costs a consumer nothing
+ * in client JavaScript beyond that and a caller composing a client `actions` slot
+ * pays for the action rather than for the profile.
+ */
+export declare function UserProfile01({ name, role, bio, avatar, facts, actions, tabs, layout, headingLevel, className, }: UserProfile01Props): import("react").JSX.Element;
+export default UserProfile01;
+//# sourceMappingURL=user-profile-01.d.ts.map

package/dist/blocks/user-profile-01/user-profile-01.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"user-profile-01.d.ts","sourceRoot":"","sources":["../../../src/blocks/user-profile-01/user-profile-01.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAItC,OAAO,EAA2B,KAAK,YAAY,EAAE,MAAM,6BAA6B,CAAA;AAwBxF;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B;;;;;;;;;OASG;IACH,EAAE,EAAE,MAAM,CAAA;IACV;;;;;;;OAOG;IACH,KAAK,EAAE,MAAM,CAAA;IACb;;;;;;;;OAQG;IACH,KAAK,EAAE,SAAS,CAAA;CACjB,CAAA;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC/B;;;;;;;;;;OAUG;IACH,IAAI,EAAE,MAAM,CAAA;IACZ;;;;;;;;OAQG;IACH,IAAI,CAAC,EAAE,MAAM,CAAA;IACb;;;;;;;;;;OAUG;IACH,GAAG,CAAC,EAAE,SAAS,CAAA;IACf;;;;;;;;;;;;;;OAcG;IACH,MAAM,CAAC,EAAE;QACP,2EAA2E;QAC3E,GAAG,CAAC,EAAE,MAAM,CAAA;QACZ,wDAAwD;QACxD,IAAI,EAAE,MAAM,CAAA;KACb,CAAA;IACD;;;;;;;OAOG;IACH,KAAK,CAAC,EAAE,SAAS,iBAAiB,EAAE,CAAA;IACpC;;;;;;;;;OASG;IACH,OAAO,CAAC,EAAE,SAAS,CAAA;IACnB;;;;;;;;OAQG;IACH,IAAI,CAAC,EAAE,SAAS,CAAA;IAChB;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,EAAE,QAAQ,GAAG,SAAS,CAAA;IAC7B;;;OAGG;IACH,YAAY,CAAC,EAAE,YAAY,CAAA;IAC3B;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyFG;AACH,wBAAgB,aAAa,CAAC,EAC5B,IAAI,EACJ,IAAI,EACJ,GAAG,EACH,MAAM,EACN,KAAK,EACL,OAAO,EACP,IAAI,EACJ,MAAiB,EACjB,YAAmB,EACnB,SAAS,GACV,EAAE,kBAAkB,+BAyGpB;AAED,eAAe,aAAa,CAAA"}