@nanisoft/prism-ui 0.13.0 → 0.16.0

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

@@ -0,0 +1,396 @@
+import { type ReactNode } from 'react';
+import { type HeadingLevel } from '../../components/ui/section.js';
+/**
+ * One role a member can hold, as the caller names it.
+ *
+ * The option list is the caller's rather than a `Role` union in this module, and
+ * the argument is the same one `SettingsPanel01`'s `options` makes: the set of
+ * roles a workspace has is that workspace's own fact, it changes with its plan
+ * and with its commercial agreements, and a Block that shipped a list would
+ * install a permission model into every consumer's settings page.
+ */
+export type SettingsMembersRole = {
+    /** The value handed back to `onRoleChange`. */
+    id: string;
+    /**
+     * The role's own name, as the product writes it.
+     *
+     * The fallback for the words, and the only one used when `roleLabel` is not
+     * passed. See `SettingsMembers01Props.roleLabel` for why the function is
+     * normally the one that draws the control.
+     */
+    label: string;
+};
+/**
+ * One member of the workspace, as a settings surface shows them.
+ *
+ * The six fields are the six questions a reader asks of a row on this surface:
+ * who is this, what can they do, when did they arrive, and what can I do about
+ * it. A row that answers four of them is a directory entry, which is
+ * `member-list-01`.
+ */
+export type SettingsMembersMember = {
+    /**
+     * A stable key for the row, passed back to `onRoleChange`, and carried on the
+     * markup as `data-member` so a test can name one row rather than the first.
+     */
+    id: string;
+    /** The member's own name, and the identity the row is read by. */
+    name: string;
+    /**
+     * Where the member can be reached, which is how a reader tells two people with
+     * the same name apart. Omit it rather than passing an empty string.
+     */
+    email?: string;
+    /**
+     * The role's machine value, so the select can show the current one and so a
+     * row with no select still states what the person can do.
+     */
+    role: string;
+    /**
+     * The words for the role, drawn by `roleLabel` when it is passed.
+     *
+     * A member with no control on the row still has a role, and a role with no
+     * words is a machine value in a place a reader reads: `admin` is a term of art
+     * in one product and a typo in another. See `SettingsMembers01Props.roleLabel`.
+     */
+    roleLabel?: string;
+    /**
+     * When the member arrived, in whichever of the two forms the caller already
+     * has it.
+     *
+     * A moment rather than a reading, and the reading is `joinedLabel`. The Block
+     * prints the value exactly as passed when no formatter is given, which is
+     * honest and rarely what was wanted; see the Block's JSDoc for the whole of
+     * that argument, which `compliance-01` states for a review date and
+     * `member-list-01` for a last-seen.
+     */
+    joined?: number | string;
+    /**
+     * The words for the arrival, given the moment.
+     *
+     * A function rather than a string because the honest reading of when somebody
+     * joined is a localised sentence, which is what `relative-time` hands back and
+     * what no Block in this package prints on its own.
+     */
+    joinedLabel?: (value: number | string) => string;
+    /**
+     * The portrait, with the name the initials come from.
+     *
+     * Omit it for a member the consumer has no photograph of. The initials rule is
+     * the one `AvatarGroup` applies and is repeated rather than imported; see that
+     * Component for why the helper is not exported.
+     */
+    avatar?: {
+        /** The photograph. Omit it, or pass a URL that fails, for the initials. */
+        src?: string;
+        /** The member's name, which is the initials' source. */
+        name: string;
+    };
+    /**
+     * Marks this row as the reader's own, and the marking is what stops the Block
+     * drawing a role control on it.
+     *
+     * The argument for the flag is in the Block's JSDoc and it is long, because
+     * this is the one field here whose absence is a trap rather than a gap: a
+     * settings surface that lets a reader remove themselves without saying so is a
+     * trap, and one that lets a reader change their own role is worse.
+     */
+    isSelf?: boolean;
+    /**
+     * The words that mark the reader's own row, such as the second person.
+     *
+     * Required whenever `isSelf` is set, and a thrown diagnostic rather than a
+     * silent absence, for the reason `Status` gives for its own label: 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.
+     */
+    selfLabel?: string;
+    /**
+     * The controls at the trailing edge of this row.
+     *
+     * A node rather than a function of the member id, because a member list this
+     * size is a list where each row's action differs and the caller composes them
+     * in their own map. A function would be the shape `member-list-01` uses for a
+     * list of any length; here it would be a function returning a function, and
+     * the caller has already got the map.
+     */
+    actions?: ReactNode;
+};
+/**
+ * One invitation that has been sent and not yet accepted.
+ *
+ * Four fields and no state, which is the decision this Block's JSDoc defends at
+ * length: the only signal that an invitation has expired is that the caller
+ * passed `expiresLabel`, because the Block holds no clock and a design system
+ * that guessed would be guessing about somebody else's deadline.
+ */
+export type SettingsMembersInvitation = {
+    /** A stable key for the row, carried on the markup as `data-invitation`. */
+    id: string;
+    /** The address the invitation went to, and the row's identity. */
+    email: string;
+    /**
+     * When it was sent, in whichever of the two forms the caller already has it.
+     *
+     * Printed exactly as passed. See `SettingsMembersMember.joined` for why a Block
+     * does not format it.
+     */
+    sentAt?: number | string;
+    /**
+     * The words for an invitation that has expired.
+     *
+     * Its presence is the mark: the row is dimmed, the words are read beside the
+     * address, and the invitation is not removed from the list. See the Block's
+     * JSDoc for why a list that shrinks is worse than a list with a faded row.
+     */
+    expiresLabel?: string;
+};
+/**
+ * The three things a members table can put in a column, and the words above it.
+ *
+ * A closed set, and the closure is the point, for the reason
+ * `ResourceListCell` gives: the cells are the Block's, so a table with a fourth
+ * column would be a column with nothing to put in it. The names are the caller's,
+ * which is the other half of the same thing. A members table has one column
+ * whose name is worth arguing over, the role column, and a product that calls it
+ * "Access" and a product that calls it "What they can do" are both right.
+ */
+export type SettingsMembersColumn = {
+    /** Which cell the column draws. */
+    id: 'name' | 'role' | 'joined';
+    /** The heading above the column. */
+    header: ReactNode;
+    /** Layout only: a width, or an alignment. */
+    className?: string;
+};
+/**
+ * The props a SettingsMembers01 takes.
+ *
+ * Every string is a prop and the Block ships none. There is no member, no role
+ * list, no invite copy, no column name, no arrival reading and not one of the
+ * four sentences a settings surface is most tempted to ship. A settings Block is
+ * where a hardcoded word does the most damage, because the reader is already
+ * looking at their own account while they read it.
+ */
+export type SettingsMembers01Props = {
+    /** Optional label above the section title. See the No-Default-Eyebrow Rule. */
+    eyebrow?: ReactNode;
+    /** The section title. Required, because a members list with no heading is a fragment. */
+    title: ReactNode;
+    /** One or two sentences under the title. */
+    description?: ReactNode;
+    /** The members, in the order a reader should meet them. The Block does not sort. */
+    members: readonly SettingsMembersMember[];
+    /**
+     * The invitations sent and not yet accepted.
+     *
+     * Omit it and the group is not drawn at all, which is right for a workspace
+     * that invites by link rather than by address.
+     */
+    invitations?: readonly SettingsMembersInvitation[];
+    /**
+     * The name of the group holding the pending invitations.
+     *
+     * Required whenever `invitations` is non-empty, and a thrown diagnostic rather
+     * than a silent absence. A group with no name is not a group: it is a second
+     * list on the page that a reader cannot point at, and the reader who is trying
+     * to work out whether an invitation they sent is still pending is exactly the
+     * reader who needs to be able to.
+     */
+    pendingTitle?: ReactNode;
+    /**
+     * The caller's own invite control, drawn above the members.
+     *
+     * A slot and not an `inviteLabel` string with a handler of the Block's, for
+     * the reason every toolbar slot in this package is a slot: the invite control
+     * in a real product is a dialog trigger, a route, a popover or a command, and
+     * a Block that chose would be choosing for four products at once.
+     */
+    inviteLabel?: ReactNode;
+    /**
+     * The roles a member can be moved between, in the order a reader should meet
+     * them.
+     *
+     * Passing it is what puts a role control on each row that is not the reader's
+     * own, so it and `onRoleChange` travel together; the Block refuses either
+     * without the other rather than rendering a control that does nothing.
+     */
+    roleOptions?: readonly SettingsMembersRole[];
+    /**
+     * The words for one role, given the option.
+     *
+     * Required whenever `roleOptions` is passed, and a function rather than a
+     * record of strings for the reason `Integration01`'s `stateLabel` is one: a
+     * role name in a consumer's settings page is exactly the defect the copy gate
+     * was written to end, and three products that call the same set Owner, Admin
+     * and Workspace admin cannot be given one word by a design system. The
+     * function rather than a record because the honest rendering is often longer
+     * than the trigger can show, and because one option may need a qualifier the
+     * others do not.
+     */
+    roleLabel?: (option: SettingsMembersRole) => string;
+    /**
+     * Called when a reader moves a member to another role.
+     *
+     * The Block holds no role state: the select is uncontrolled, the value comes
+     * from `member.role`, and a change is a request the consumer answers by
+     * re-rendering with the new value. That is the arrangement a server action
+     * wants, and it is stated rather than hidden: a select that moved and then
+     * snapped back when the request failed is a control that lied, and the fix
+     * belongs where the failure is known.
+     */
+    onRoleChange?: (memberId: string, roleId: string) => void;
+    /**
+     * What the list shows when there are no members.
+     *
+     * Required, and the reason is that a members surface has two honest empty
+     * sentences and they are opposites: one is about the workspace and one is
+     * about the reader who just arrived in it, and no design system knows which
+     * one this consumer is in the middle of. With nothing passed this Block would
+     * have to render nothing, and a heading over an empty panel reads as a fault.
+     */
+    empty: ReactNode;
+    /**
+     * The caller's own column names, which is what turns the member list into a
+     * table.
+     *
+     * Optional, and its absence is a decision rather than a default: without it
+     * the members are rows, which is the right shape for the four-to-twenty-member
+     * workspace and the one that holds a portrait, a name and a role on one line.
+     * With it they are a real table, and the column names are then required for
+     * the reason `compliance-01` states: a table whose columns are identified by
+     * position is a grid, and a grid of people is a list a screen reader user
+     * cannot navigate.
+     */
+    columns?: readonly SettingsMembersColumn[];
+    /** 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;
+};
+/**
+ * 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 declare function SettingsMembers01({ eyebrow, title, description, members, invitations, pendingTitle, inviteLabel, roleOptions, roleLabel, onRoleChange, empty, columns, headingLevel, className, }: SettingsMembers01Props): import("react").JSX.Element;
+export default SettingsMembers01;
+//# sourceMappingURL=settings-members.d.ts.map

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

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