@nadicodeai/ui 12.1.102 → 12.1.104

package/dist/components/settings-section.d.ts

@@ -1,57 +1,113 @@
 import * as React from "react";
 import { type SettingsSave } from "../internal/settings-save.js";
 import { Field } from "./field.js";
+import { Switch } from "./switch.js";
 export type { SettingsSave, SettingsSaveFailure } from "../internal/settings-save.js";
 export type SettingsFieldControlProps = {
     id: string;
+    "aria-labelledby": string;
     "aria-invalid"?: true;
     "aria-describedby"?: string;
     disabled?: boolean;
     required?: boolean;
 };
-export type SettingsSectionProps = Omit<React.ComponentProps<"section">, "title" | "children"> & {
-    title: string;
-    /** One line saying what changing it does. */
+export type SettingsSectionTone = "error" | "warning";
+export type SettingsHeaderSwitch = Pick<React.ComponentProps<typeof Switch>, "checked" | "defaultChecked" | "onCheckedChange" | "disabled" | "name">;
+type SettingsInfo = {
+    /** Names the (i) button: "About build command". */
+    label: string;
+    /** One sentence, shown in a tooltip and read with the control. */
+    text: string;
+};
+type SettingsSectionBase = Omit<React.ComponentProps<"section">, "title" | "children"> & {
+    /** One line saying what changing it does. It is the card's only help: no field carries its own. */
     description: string;
-    /** A control on the section's own header: an avatar's upload, a state. */
-    actions?: React.ReactNode;
-    /** Two columns where related fields fit. */
-    columns?: 1 | 2;
+};
+type Titled = {
+    /** The section's h2, on every card. */
+    title: string;
     children?: React.ReactNode;
-} & ({
+};
+type SavingSection = Titled & {
     save: SettingsSave;
     footer?: never;
     footerHint?: never;
-} | {
+    tone?: never;
+    lockedReason?: never;
+    unlock?: never;
+    headerSwitch?: never;
+    /** A control on the section's own header: an avatar's upload. */
+    actions?: React.ReactNode;
+};
+type FooterSection = Titled & {
     save?: never;
+    /** The buttons on the footer's right. */
     footer?: React.ReactNode;
+    /** What is specific to this card, on the footer's left: a limit, what a value is for, a plan it needs, a link. Absent: nothing. */
     footerHint?: React.ReactNode;
-});
+    /** A condition of the whole card: 1px border, a tinted footer; the title, line, fields and buttons stay neutral. */
+    tone?: SettingsSectionTone;
+    lockedReason?: never;
+    unlock?: never;
+    headerSwitch?: never;
+    /** A button or a badge on the section's own header. A switch is `headerSwitch`. */
+    actions?: React.ReactNode;
+};
+type SwitchedSection = Titled & {
+    save?: never;
+    footer?: never;
+    /** What is specific to this card, on the footer's left: a limit, what a value is for, a plan it needs, a link. Absent: nothing. */
+    footerHint?: React.ReactNode;
+    tone?: never;
+    lockedReason?: never;
+    unlock?: never;
+    actions?: never;
+    /** The switch that is the whole card, at the title's right, named by the title; it applies at once. */
+    headerSwitch: SettingsHeaderSwitch;
+};
+type LockedSection = Titled & {
+    save?: never;
+    footer?: never;
+    footerHint?: never;
+    tone?: never;
+    /** Why the person may not change this section: the plan that has it, the role it needs. */
+    lockedReason: string | React.ReactElement;
+    /** The way to get access: an Upgrade button, a Contact sales link. Left out when nothing the person does unlocks it. */
+    unlock?: React.ReactNode;
+    headerSwitch?: never;
+    actions?: never;
+};
+type UntitledSection = {
+    /** Left out only on a card with no control, whose description then names it. */
+    title?: undefined;
+    children?: undefined;
+    save?: never;
+    footer?: never;
+    /** What is specific to this card, on the footer's left: a limit, what a value is for, a plan it needs, a link. Absent: nothing. */
+    footerHint?: React.ReactNode;
+    tone?: never;
+    lockedReason?: never;
+    unlock?: never;
+    headerSwitch?: never;
+    actions?: never;
+};
+export type SettingsSectionProps = SettingsSectionBase & (SavingSection | FooterSection | SwitchedSection | LockedSection | UntitledSection);
+export type SavingSettingsSectionProps = SettingsSectionBase & SavingSection;
 /**
- * A card of related settings that says what changing them does and saves them from its own footer.
+ * A card of one setting that says what changing it does and ends in a footer.
  *
  * @family Compositions
- * @when A few related settings on a SettingsPage or as a section of an ObjectPage: choices that apply at once, without `save` (Notifications), or typed values a person saves together, with `save` (Personal details, Company identity).
- * @instead Read-only values are a SettingsFactsSection; a collection is a CollectionPage; a record's edit in a list is a RowEditForm.
- * @behaviour With `save`: Save stays disabled until a field differs from what is saved, says `pendingLabel` while saving with Cancel held beside it, then calls `saved`, which the product answers with its own toast; the footer never shows a saved state. A failure keeps every value and shows under its field until that field changes, or above the footer until the next save. A `cancel` that runs work of its own says its `pendingLabel` while `pending`. Without `save`, the footer holds `footerHint` and `footer`, and is left out when both are.
- * @words The title names the values ("Personal details"); the description says what changing them does, in one line; the hint is optional and says what is specific to this card: a limit ("Please use 32 characters at maximum."), what a value is for, the plan a feature needs, or a "Learn more" link, never one sentence every card repeats; Save and Saving come from the product's catalogue, and the saved toast from its notices.
- * @access The title is the section's h2 and names the form that saves it. The saved toast is announced by the product's toast region; a failure under a field marks the control invalid and describes it.
+ * @when One setting a person changes on a SettingsPage or as a section of an ObjectPage: Personal details, Company identity, Notifications. A typed value takes `save`; a switch or a short reversible choice applies at once through its own control's change, with no Save. Also a plan-gated feature, a delete card, one read-only value (an ID in a read-only mono InputGroup with its copy button, no Save), and a paid quantity (its stepper field, the price as the description, a two-fact summary under it).
+ * @instead Read-only facts of an object are a SettingsFactsSection; a table or a list of records is a TableCard; Theme and Language live in the account menu; a record's edit in a list is a RowEditForm.
+ * @behaviour "Groups related form controls inside a bordered card with optional footer actions." (https://vercel.com/geist/fieldset) Ours: one setting per card: a single SettingsField, the description its only help. One more shape exists, declared by a part and never by classes at the call site. A card of several settings holds SettingsRows, label left and control right, only when every row is a switch or every row is a select. "Use Toggle for a single boolean setting where ON takes effect immediately, like `Password Protection` or `Auto-Cancel Builds`." (https://vercel.com/geist/toggle) "Pair with a form footer only when the setting needs an explicit `Save` step." (https://vercel.com/geist/toggle) "Disable Toggle only when the action is impossible (missing plan, locked policy); pair with helper text or a `Tooltip` that names the resolver." (https://vercel.com/geist/toggle) Ours: that switch is `headerSwitch`: at the title's right, named by the title, the footer holding only its line, no Save; a switch blocked from above is shown off and disabled, the footer saying why and never a tooltip. Required: the title and the description. The header's actions stand at the title's right; on a card narrower than 28 rem they keep the title's row and the description runs under both, as Vercel's cards read on a phone. The footer's left line (`footerHint`, `save.hint`) is optional and specific to the card, never a generic line repeated on every card: a limit, what a value is for, a plan it needs, a link; absent, it is nothing, and a card with neither a line nor a button has no footer. Ours: `save`: a typed value, one card with Save. Save stays disabled until a field differs from what is saved and says `pendingLabel` while saving with Cancel beside it; a completed save calls `saved`, and the product raises one toast from its catalogue ("Completion toasts follow `{Noun} {past-participle}`: `Blob deleted`, `Domain added`, `Environment variable saved`. Never include `successfully`; the action name implies it." https://vercel.com/geist/toast), and Save returns to disabled. Ours: the section never raises a toast itself. A failed save keeps every value and shows under its field, or above the footer when no field owns it. `tone` marks a state with a command (a failed payment, a trial ending): a 1px border and a footer tinted in the hue with its line in it; title, line, fields and buttons stay neutral, an outline secondary then a default primary. A button takes the hue of its command, not of the card: `destructive` for a permanent loss, `warning` for a disruptive command that can be undone. A delete card is `tone="error"` with the object's summary as its body; an archive card is neutral with a `warning` button in the footer. "Use a Note for inline contextual feedback next to the field, card, or section it describes: a region change warning above a region picker, a rate-limit notice next to a usage gauge." (https://vercel.com/geist/note) "One Note per concept." (https://vercel.com/geist/note) Ours: a message about the fields inside is a MessageNotice in the body, the card staying neutral. "Disabled checkboxes still need a Tooltip naming the reason; a greyed box with no explanation reads as a bug." (https://vercel.com/geist/checkbox) Ours: `lockedReason` is the reason, in the card, not in a tooltip; it keeps the fields in view, inert with muted text, under a not-allowed cursor, the title and line unchanged; `unlock` is the way to get access, left out when nothing the person does unlocks it.
+ * @words "Helper text is sentence case, one sentence with a trailing period, on a sibling element wired through `aria-describedby`." (https://vercel.com/geist/input) Ours: the description is that helper text for the whole card, and no field has its own. "Render an optional one-sentence description as a sibling under the label that explains ON only. Don’t describe OFF; it’s the negation." (https://vercel.com/geist/toggle) Ours: a header-switch card's description says what turning it on does. The title names the values ("Personal details"); the description says what changing them does, in one line; the footer line is a Learn more link, a limit ("Use 32 characters at most."), what stays unaffected, or what is blocked and why ("Ask an owner to change this."); Save and Saving come from the product's catalogue, and so does the toast a `saved` callback raises; a delete card's description opens "Permanently delete".
+ * @access "Provide an accessible name through `children`, `aria-label`, or `aria-labelledby`." (https://vercel.com/geist/toggle) Ours: the title is the section's h2 and names the form that saves it, and the header switch. The footer's line is one status, announced politely; a failure under a field marks the control invalid and describes it. Locked fields are inert, so the section's title, description and reason are what a screen reader meets.
  */
-declare function SettingsSection({ title, description, actions, columns, children, className, save, footer, footerHint, ...props }: SettingsSectionProps): React.JSX.Element;
-/**
- * One setting: its label and help above its control, and what went wrong under it.
- *
- * @family Inputs
- * @when A value inside a SettingsSection: a name, an address, a choice, a switch.
- * @instead A field of a drawer's or a dialog's form is a Field from the form's own owner; a read-only value is a fact in a SettingsFactsSection.
- * @behaviour The control is 20rem wide under its label and help by default; a switch row passes `orientation="horizontal"` and sits at the end of its label's row at its own width. A validation `error`, or a failed save about this field, shows under the control and marks it invalid.
- * @words The label is a noun for the value ("Display name"); the help is one line saying what it is for or where it shows; an error says what to do next.
- * @access The control receives its id, `aria-invalid` and `aria-describedby` through `controlProps`, so the label, help and error are read with it.
- */
-declare function SettingsField({ id, label, description, error, invalid, disabled, required, orientation, children, className, contentClassName, controlClassName, controlWidth, ...props }: Omit<React.ComponentProps<typeof Field>, "children"> & {
+declare function SettingsSection({ title, description, actions, headerSwitch, tone, children, className, save, footer, footerHint, lockedReason, unlock, ...props }: SettingsSectionProps): React.JSX.Element;
+type SettingsFieldBase = Omit<React.ComponentProps<typeof Field>, "children" | "orientation"> & {
     id: string;
-    label: React.ReactNode;
-    description?: React.ReactNode;
+    label: NonNullable<React.ReactNode>;
+    info?: SettingsInfo;
     error?: React.ReactNode;
     invalid?: boolean;
     disabled?: boolean;
@@ -59,9 +115,79 @@ declare function SettingsField({ id, label, description, error, invalid, disable
     children: (props: {
         controlProps: SettingsFieldControlProps;
     }) => React.ReactNode;
-    contentClassName?: string;
-    controlClassName?: string;
+};
+type SettingsFieldProps = SettingsFieldBase & ({
+    /** A text box, a textarea, a select or a combobox: the label above it. */
+    control?: "box";
     controlWidth?: "natural" | "standard" | "full";
-}): React.JSX.Element;
-export { SettingsField, SettingsSection };
+    stateLabel?: never;
+} | {
+    /** A checkbox or a radio with its sentence beside it. */
+    control: "choice";
+    controlWidth?: never;
+    stateLabel?: never;
+} | {
+    /** A switch followed by the word for its state, as a draft the card's Save applies. */
+    control: "switch";
+    controlWidth?: never;
+    /** "Enabled" or "Disabled", whichever the switch shows now. */
+    stateLabel: string;
+});
+/**
+ * One setting: its label above its control, and what went wrong under it.
+ *
+ * @family Inputs
+ * @when The one value of a SettingsSection: a name, an address, a choice, a switch.
+ * @instead A field of a drawer's or a dialog's form is a Field from the form's own owner; a read-only fact is a SettingsFactsSection; several switches or selects in one card are SettingsRows; a switch that is the whole card and applies at once is the section's `headerSwitch`.
+ * @behaviour "Helper text is sentence case, one sentence with a trailing period, on a sibling element wired through `aria-describedby`." (https://vercel.com/geist/input) Ours: label required, no help line: the card's description helps, and the (i) `info` is for a part of a value that needs a sentence. The control is 20rem wide under its label (`controlWidth`: `full` for a textarea, `natural` for a segmented control). `control="choice"` puts a checkbox or radio before its sentence; `control="switch"` puts the word for the switch's state after it and requires `stateLabel`. "Validate on blur, not on every keystroke; surface the message by passing a string to `error`." (https://vercel.com/geist/input) Ours: a validation `error` updates as the value is corrected, and it or a failed save about this field shows under the control and marks it invalid; colour sits on the control's edge and the message, never the label.
+ * @words "Labels are short Title Case nouns: `Project Name`, `Domain`, `Environment Variable Name`." (https://vercel.com/geist/input) Ours: sentence case, a noun for the value ("Display name"). "Validation names the field and the constraint, ends in a period, and skips `please` (`Project name is required.`, `Code must be 6 digits.`)." (https://vercel.com/geist/input) Ours: an error says what to do next; `info.text` is one sentence and `info.label` names its button ("About display name"); a switch shows its state word ("Enabled", "Disabled") beside it.
+ * @access "Don’t wrap a labelled `<Input>` in a `Tooltip`; put the explainer on a sibling icon button so the label stays announced." (https://vercel.com/geist/input) Ours: that sibling button is the (i) `info`. The control receives its id, `aria-invalid` and `aria-describedby` through `controlProps`, so the label, the info and the error are read with it. The info button has its own name and opens on focus.
+ */
+declare function SettingsField({ id, label, info, error, invalid, disabled, required, control, controlWidth, stateLabel, children, className, ...props }: SettingsFieldProps): React.JSX.Element;
+type SettingsRowBase = {
+    id: string;
+    label: string;
+    /** Every row has its (i): the card's description covers the group, the tooltip covers the row. */
+    info: SettingsInfo;
+    error?: React.ReactNode;
+    disabled?: boolean;
+    name?: string;
+};
+type SettingsSwitchRow = SettingsRowBase & {
+    checked: boolean;
+    onCheckedChange: (checked: boolean) => void;
+};
+type SettingsSelectRow = SettingsRowBase & {
+    value: string;
+    onValueChange: (value: string) => void;
+    options: readonly {
+        value: string;
+        label: string;
+    }[];
+};
+type SettingsRowsProps = {
+    kind: "switch";
+    /** The word beside each switch for its state: "Enabled" and "Disabled". */
+    stateLabels: {
+        on: string;
+        off: string;
+    };
+    rows: readonly SettingsSwitchRow[];
+} | {
+    kind: "select";
+    stateLabels?: never;
+    rows: readonly SettingsSelectRow[];
+};
+/**
+ * Several switches, or several selects, in one card: each row its label on the left and its control on the right.
+ *
+ * @family Inputs
+ * @when A card of settings of one kind, all switches or all selects, that the card's one description covers: a project's Git switches, a team's notification channels, a set of defaults.
+ * @instead One setting is a SettingsField. Fields of different kinds, text boxes among them, are one card each. A switch that is the whole card and applies at once is the section's `headerSwitch`.
+ * @behaviour Declares `kind` once; every row is that kind, so a card cannot mix a switch with a select. Required on every row: the label and its `info` (an (i) with its sentence in a tooltip and on the control); no help line sits under a row. A switch row shows its state word beside the switch (`stateLabels`) and is controlled, so the word always follows the switch. Rows stand 16 px apart; below 28rem a row stacks its control under its label. "Pair with a form footer only when the setting needs an explicit `Save` step." (https://vercel.com/geist/toggle) Ours: a switch in a card with a Save is a draft the Save applies; in a card without one it applies at once through its `onCheckedChange`, and the card's footer holds only its line, if it has one.
+ * @words "Title Case noun phrase, 1–4 words, naming what is true when ON: `Password Protection`, not `Enable Password Protection`." (https://vercel.com/geist/toggle) Ours: sentence case, a noun for what it controls ("Pull request comments"), the same for a switch as for a select. "Render an optional one-sentence description as a sibling under the label that explains ON only. Don’t describe OFF; it’s the negation." (https://vercel.com/geist/toggle) Ours: that sentence is `info.text`. "Options are Title Case when short and match canonical branding (`Next.js`, not `NextJS`); keep the same register across the list." (https://vercel.com/geist/select) Ours: a select's options are sentence case.
+ * @access Each row's control is named by the row's label and described by its info and its error. The info button has its own name and opens on focus.
+ */
+declare function SettingsRows(props: SettingsRowsProps): React.JSX.Element;
+export { SettingsField, SettingsRows, SettingsSection };
 //# sourceMappingURL=settings-section.d.ts.map

package/dist/components/settings-section.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"settings-section.d.ts","sourceRoot":"","sources":["../../src/components/settings-section.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAI/B,OAAO,EACL,KAAK,YAAY,EAGlB,MAAM,0BAA0B,CAAC;AAElC,OAAO,EACL,KAAK,EAMN,MAAM,oBAAoB,CAAC;AAE5B,YAAY,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAElF,MAAM,MAAM,yBAAyB,GAAG;IACtC,EAAE,EAAE,MAAM,CAAC;IACX,cAAc,CAAC,EAAE,IAAI,CAAC;IACtB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,SAAS,CAAC,EAAE,OAAO,GAAG,UAAU,CAAC,GAAG;IAC/F,KAAK,EAAE,MAAM,CAAC;IACd,6CAA6C;IAC7C,WAAW,EAAE,MAAM,CAAC;IACpB,0EAA0E;IAC1E,OAAO,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IAC1B,4CAA4C;IAC5C,OAAO,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC;IAChB,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;CAC5B,GAAG,CACE;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,MAAM,CAAC,EAAE,KAAK,CAAC;IAAC,UAAU,CAAC,EAAE,KAAK,CAAA;CAAE,GAC1D;IAAE,IAAI,CAAC,EAAE,KAAK,CAAC;IAAC,MAAM,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IAAC,UAAU,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;CAAE,CAC3E,CAAC;AAEJ;;;;;;;;;GASG;AACH,iBAAS,eAAe,CAAC,EACvB,KAAK,EACL,WAAW,EACX,OAAO,EACP,OAAW,EACX,QAAQ,EACR,SAAS,EACT,IAAI,EACJ,MAAM,EACN,UAAU,EACV,GAAG,KAAK,EACT,EAAE,oBAAoB,qBAwCtB;AAED;;;;;;;;;GASG;AACH,iBAAS,aAAa,CAAC,EACrB,EAAE,EACF,KAAK,EACL,WAAW,EACX,KAAK,EACL,OAAwB,EACxB,QAAQ,EACR,QAAQ,EACR,WAAwB,EACxB,QAAQ,EACR,SAAS,EACT,gBAAgB,EAChB,gBAAgB,EAChB,YAAoE,EACpE,GAAG,KAAK,EACT,EAAE,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,OAAO,KAAK,CAAC,EAAE,UAAU,CAAC,GAAG;IACxD,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,KAAK,CAAC,SAAS,CAAC;IACvB,WAAW,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IAC9B,KAAK,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IACxB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,QAAQ,EAAE,CAAC,KAAK,EAAE;QAAE,YAAY,EAAE,yBAAyB,CAAA;KAAE,KAAK,KAAK,CAAC,SAAS,CAAC;IAClF,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,YAAY,CAAC,EAAE,SAAS,GAAG,UAAU,GAAG,MAAM,CAAC;CAChD,qBAyDA;AAED,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,CAAC"}
+{"version":3,"file":"settings-section.d.ts","sourceRoot":"","sources":["../../src/components/settings-section.tsx"],"names":[],"mappings":"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"}

package/dist/components/settings-section.js

@@ -1,56 +1,109 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { Info } from "lucide-react";
 import * as React from "react";
 import { cn } from "../lib/utils.js";
 import { FooterStrip } from "../internal/footer-strip.js";
 import { SettingsFieldFailure, SettingsSaveForm, } from "../internal/settings-save.js";
+import { Button } from "./button.js";
 import { Card, CardAction, CardContent, CardDescription, CardHeader, CardTitle } from "./card.js";
-import { Field, FieldContent, FieldDescription, FieldError, FieldGroup, FieldLabel, } from "./field.js";
+import { Field, FieldContent, FieldError, FieldGroup, FieldLabel } from "./field.js";
+import { NativeSelect, NativeSelectOption } from "./native-select.js";
+import { Switch } from "./switch.js";
+import { Tooltip, TooltipContent, TooltipTrigger } from "./tooltip.js";
+const toneClassNames = {
+    error: "border border-destructive *:data-[slot=card-footer]:border-destructive *:data-[slot=card-footer]:bg-destructive-soft *:data-[slot=card-footer]:*:data-[slot=settings-section-hint]:text-destructive-soft-foreground",
+    warning: "border border-warning *:data-[slot=card-footer]:border-warning *:data-[slot=card-footer]:bg-warning-soft *:data-[slot=card-footer]:*:data-[slot=settings-section-hint]:text-warning-soft-foreground",
+};
+/** Below a 28 rem card the actions keep the title's row and the description takes the card's width under both. */
+const ACTIONS_ON_TITLE_ROW_WHEN_NARROW = "@max-md/settings-section:[&>[data-slot=card-action]]:row-span-1 @max-md/settings-section:[&>[data-slot=card-action]]:row-start-1 @max-md/settings-section:[&>[data-slot=card-description]]:col-span-2 @max-md/settings-section:[&>[data-slot=card-description]]:col-start-1";
 /**
- * A card of related settings that says what changing them does and saves them from its own footer.
+ * A card of one setting that says what changing it does and ends in a footer.
  *
  * @family Compositions
- * @when A few related settings on a SettingsPage or as a section of an ObjectPage: choices that apply at once, without `save` (Notifications), or typed values a person saves together, with `save` (Personal details, Company identity).
- * @instead Read-only values are a SettingsFactsSection; a collection is a CollectionPage; a record's edit in a list is a RowEditForm.
- * @behaviour With `save`: Save stays disabled until a field differs from what is saved, says `pendingLabel` while saving with Cancel held beside it, then calls `saved`, which the product answers with its own toast; the footer never shows a saved state. A failure keeps every value and shows under its field until that field changes, or above the footer until the next save. A `cancel` that runs work of its own says its `pendingLabel` while `pending`. Without `save`, the footer holds `footerHint` and `footer`, and is left out when both are.
- * @words The title names the values ("Personal details"); the description says what changing them does, in one line; the hint is optional and says what is specific to this card: a limit ("Please use 32 characters at maximum."), what a value is for, the plan a feature needs, or a "Learn more" link, never one sentence every card repeats; Save and Saving come from the product's catalogue, and the saved toast from its notices.
- * @access The title is the section's h2 and names the form that saves it. The saved toast is announced by the product's toast region; a failure under a field marks the control invalid and describes it.
+ * @when One setting a person changes on a SettingsPage or as a section of an ObjectPage: Personal details, Company identity, Notifications. A typed value takes `save`; a switch or a short reversible choice applies at once through its own control's change, with no Save. Also a plan-gated feature, a delete card, one read-only value (an ID in a read-only mono InputGroup with its copy button, no Save), and a paid quantity (its stepper field, the price as the description, a two-fact summary under it).
+ * @instead Read-only facts of an object are a SettingsFactsSection; a table or a list of records is a TableCard; Theme and Language live in the account menu; a record's edit in a list is a RowEditForm.
+ * @behaviour "Groups related form controls inside a bordered card with optional footer actions." (https://vercel.com/geist/fieldset) Ours: one setting per card: a single SettingsField, the description its only help. One more shape exists, declared by a part and never by classes at the call site. A card of several settings holds SettingsRows, label left and control right, only when every row is a switch or every row is a select. "Use Toggle for a single boolean setting where ON takes effect immediately, like `Password Protection` or `Auto-Cancel Builds`." (https://vercel.com/geist/toggle) "Pair with a form footer only when the setting needs an explicit `Save` step." (https://vercel.com/geist/toggle) "Disable Toggle only when the action is impossible (missing plan, locked policy); pair with helper text or a `Tooltip` that names the resolver." (https://vercel.com/geist/toggle) Ours: that switch is `headerSwitch`: at the title's right, named by the title, the footer holding only its line, no Save; a switch blocked from above is shown off and disabled, the footer saying why and never a tooltip. Required: the title and the description. The header's actions stand at the title's right; on a card narrower than 28 rem they keep the title's row and the description runs under both, as Vercel's cards read on a phone. The footer's left line (`footerHint`, `save.hint`) is optional and specific to the card, never a generic line repeated on every card: a limit, what a value is for, a plan it needs, a link; absent, it is nothing, and a card with neither a line nor a button has no footer. Ours: `save`: a typed value, one card with Save. Save stays disabled until a field differs from what is saved and says `pendingLabel` while saving with Cancel beside it; a completed save calls `saved`, and the product raises one toast from its catalogue ("Completion toasts follow `{Noun} {past-participle}`: `Blob deleted`, `Domain added`, `Environment variable saved`. Never include `successfully`; the action name implies it." https://vercel.com/geist/toast), and Save returns to disabled. Ours: the section never raises a toast itself. A failed save keeps every value and shows under its field, or above the footer when no field owns it. `tone` marks a state with a command (a failed payment, a trial ending): a 1px border and a footer tinted in the hue with its line in it; title, line, fields and buttons stay neutral, an outline secondary then a default primary. A button takes the hue of its command, not of the card: `destructive` for a permanent loss, `warning` for a disruptive command that can be undone. A delete card is `tone="error"` with the object's summary as its body; an archive card is neutral with a `warning` button in the footer. "Use a Note for inline contextual feedback next to the field, card, or section it describes: a region change warning above a region picker, a rate-limit notice next to a usage gauge." (https://vercel.com/geist/note) "One Note per concept." (https://vercel.com/geist/note) Ours: a message about the fields inside is a MessageNotice in the body, the card staying neutral. "Disabled checkboxes still need a Tooltip naming the reason; a greyed box with no explanation reads as a bug." (https://vercel.com/geist/checkbox) Ours: `lockedReason` is the reason, in the card, not in a tooltip; it keeps the fields in view, inert with muted text, under a not-allowed cursor, the title and line unchanged; `unlock` is the way to get access, left out when nothing the person does unlocks it.
+ * @words "Helper text is sentence case, one sentence with a trailing period, on a sibling element wired through `aria-describedby`." (https://vercel.com/geist/input) Ours: the description is that helper text for the whole card, and no field has its own. "Render an optional one-sentence description as a sibling under the label that explains ON only. Don’t describe OFF; it’s the negation." (https://vercel.com/geist/toggle) Ours: a header-switch card's description says what turning it on does. The title names the values ("Personal details"); the description says what changing them does, in one line; the footer line is a Learn more link, a limit ("Use 32 characters at most."), what stays unaffected, or what is blocked and why ("Ask an owner to change this."); Save and Saving come from the product's catalogue, and so does the toast a `saved` callback raises; a delete card's description opens "Permanently delete".
+ * @access "Provide an accessible name through `children`, `aria-label`, or `aria-labelledby`." (https://vercel.com/geist/toggle) Ours: the title is the section's h2 and names the form that saves it, and the header switch. The footer's line is one status, announced politely; a failure under a field marks the control invalid and describes it. Locked fields are inert, so the section's title, description and reason are what a screen reader meets.
  */
-function SettingsSection({ title, description, actions, columns = 1, children, className, save, footer, footerHint, ...props }) {
+function SettingsSection({ title, description, actions, headerSwitch, tone, children, className, save, footer, footerHint, lockedReason, unlock, ...props }) {
     const titleId = React.useId();
-    const fields = children != null ? (_jsx(CardContent, { children: _jsx(FieldGroup, { "data-slot": "settings-section-fields", className: cn("gap-4.5", columns === 2 && "grid @2xl/settings-section:grid-cols-2"), children: children }) })) : null;
-    return (_jsxs(Card, { render: _jsx("section", { ...props, "data-slot": "settings-section" }), className: cn("@container/settings-section min-w-0", className), children: [_jsxs(CardHeader, { children: [_jsx(CardTitle, { children: _jsx("h2", { id: titleId, children: title }) }), _jsx(CardDescription, { children: description }), actions ? _jsx(CardAction, { children: actions }) : null] }), save ? (_jsx(SettingsSaveForm, { save: save, titleId: titleId, children: fields })) : (_jsxs(_Fragment, { children: [fields, _jsx(FooterStrip, { hint: footerHint, hintSlot: "settings-section-hint", children: footer })] }))] }));
+    const locked = lockedReason !== undefined;
+    const fields = children != null ? (_jsx(CardContent, { children: _jsx(FieldGroup, { "data-slot": "settings-section-fields", inert: locked, className: cn(locked && "**:text-muted-foreground"), children: children }) })) : null;
+    return (_jsxs(Card, { render: _jsx("section", { ...props, "data-slot": "settings-section", "data-tone": tone, "data-locked": locked || undefined }), className: cn("@container/settings-section min-w-0", tone && toneClassNames[tone], locked && "cursor-not-allowed *:data-[slot=card-footer]:cursor-default", className), children: [_jsxs(CardHeader, { className: cn(ACTIONS_ON_TITLE_ROW_WHEN_NARROW, !title && "has-data-[slot=card-description]:grid-rows-none"), children: [title ? (_jsx(CardTitle, { children: _jsx("h2", { id: titleId, children: title }) })) : null, _jsx(CardDescription, { children: description }), actions ? _jsx(CardAction, { children: actions }) : null, headerSwitch ? (_jsx(CardAction, { className: "mt-0.75", children: _jsx(Switch, { ...headerSwitch, "aria-labelledby": titleId, size: "md" }) })) : null] }), save ? (_jsx(SettingsSaveForm, { save: save, titleId: titleId, children: fields })) : (_jsxs(_Fragment, { children: [fields, _jsx(FooterStrip, { hint: locked ? lockedReason : footerHint, hintSlot: "settings-section-hint", children: locked ? unlock : footer })] }))] }));
 }
-/**
- * One setting: its label and help above its control, and what went wrong under it.
- *
- * @family Inputs
- * @when A value inside a SettingsSection: a name, an address, a choice, a switch.
- * @instead A field of a drawer's or a dialog's form is a Field from the form's own owner; a read-only value is a fact in a SettingsFactsSection.
- * @behaviour The control is 20rem wide under its label and help by default; a switch row passes `orientation="horizontal"` and sits at the end of its label's row at its own width. A validation `error`, or a failed save about this field, shows under the control and marks it invalid.
- * @words The label is a noun for the value ("Display name"); the help is one line saying what it is for or where it shows; an error says what to do next.
- * @access The control receives its id, `aria-invalid` and `aria-describedby` through `controlProps`, so the label, help and error are read with it.
- */
-function SettingsField({ id, label, description, error, invalid = Boolean(error), disabled, required, orientation = "vertical", children, className, contentClassName, controlClassName, controlWidth = orientation === "horizontal" ? "natural" : "standard", ...props }) {
-    const descriptionId = description ? `${id}-description` : undefined;
-    const errorId = error ? `${id}-error` : undefined;
-    const describedBy = [descriptionId, errorId].filter(Boolean).join(" ");
-    const controlProps = {
+function controlPropsOf({ id, info, error, invalid, disabled, required, }) {
+    return {
         id,
+        "aria-labelledby": `${id}-label`,
         disabled,
         required,
         "aria-invalid": invalid ? true : undefined,
-        "aria-describedby": describedBy || undefined,
+        "aria-describedby": [info ? `${id}-info` : undefined, error ? `${id}-error` : undefined]
+            .filter(Boolean)
+            .join(" ") || undefined,
     };
-    const errors = (_jsxs(_Fragment, { children: [error ? _jsx(FieldError, { id: errorId, children: error }) : null, _jsx(SettingsFieldFailure, { id: id })] }));
-    const errorsUnderControl = orientation === "vertical";
-    return (_jsx("div", { "data-slot": "settings-field", "data-invalid": invalid ? true : undefined, className: "contents", children: _jsxs(Field, { "data-invalid": invalid ? true : undefined, "data-disabled": disabled ? true : undefined, orientation: orientation, className: cn("items-start", className), ...props, children: [_jsxs(FieldContent, { className: contentClassName, children: [_jsx(FieldLabel, { htmlFor: id, children: label }), description ? (_jsx(FieldDescription, { id: descriptionId, children: description })) : null, errorsUnderControl ? null : errors] }), _jsx("div", { "data-slot": "settings-field-control", className: cn("flex min-w-0", controlWidth === "standard"
-                        ? "w-full max-w-80 justify-start [&>:not([role=checkbox],[role=switch],[role=radio])]:w-full"
-                        : controlWidth === "full"
-                            ? "w-full justify-start [&>:not([role=checkbox],[role=switch],[role=radio])]:w-full"
-                            : orientation === "vertical"
-                                ? "w-full justify-start"
-                                : orientation === "horizontal"
-                                    ? "shrink-0 justify-end"
-                                    : "w-full justify-start @md/field-group:w-auto @md/field-group:min-w-64 @md/field-group:justify-end", controlClassName), children: children({ controlProps }) }), errorsUnderControl ? errors : null] }) }));
-}
-export { SettingsField, SettingsSection };
+}
+function SettingsFieldLabel({ id, label, info, }) {
+    const fieldLabel = (_jsx(FieldLabel, { htmlFor: id, id: `${id}-label`, children: label }));
+    if (!info)
+        return fieldLabel;
+    return (_jsxs("div", { className: "flex items-center gap-1", children: [fieldLabel, _jsxs(Tooltip, { children: [_jsx(TooltipTrigger, { render: _jsx(Button, { "aria-label": info.label, size: "icon-xs", variant: "ghost" }), children: _jsx(Info, { "aria-hidden": "true" }) }), _jsx(TooltipContent, { children: info.text })] }), _jsx("span", { hidden: true, id: `${id}-info`, children: info.text })] }));
+}
+function SettingsFieldErrors({ id, error }) {
+    return (_jsxs(_Fragment, { children: [error ? _jsx(FieldError, { id: `${id}-error`, children: error }) : null, _jsx(SettingsFieldFailure, { id: id })] }));
+}
+const boxControl = "[&>:not([role=checkbox],[role=switch],[role=radio])]:w-full";
+function controlCellClassName(control, controlWidth) {
+    if (control === "choice")
+        return "mt-0.5 shrink-0";
+    if (control === "switch")
+        return "items-center gap-2";
+    if (controlWidth === "standard")
+        return `w-full max-w-80 justify-start ${boxControl}`;
+    if (controlWidth === "full")
+        return `w-full justify-start ${boxControl}`;
+    return "w-full justify-start";
+}
+/**
+ * One setting: its label above its control, and what went wrong under it.
+ *
+ * @family Inputs
+ * @when The one value of a SettingsSection: a name, an address, a choice, a switch.
+ * @instead A field of a drawer's or a dialog's form is a Field from the form's own owner; a read-only fact is a SettingsFactsSection; several switches or selects in one card are SettingsRows; a switch that is the whole card and applies at once is the section's `headerSwitch`.
+ * @behaviour "Helper text is sentence case, one sentence with a trailing period, on a sibling element wired through `aria-describedby`." (https://vercel.com/geist/input) Ours: label required, no help line: the card's description helps, and the (i) `info` is for a part of a value that needs a sentence. The control is 20rem wide under its label (`controlWidth`: `full` for a textarea, `natural` for a segmented control). `control="choice"` puts a checkbox or radio before its sentence; `control="switch"` puts the word for the switch's state after it and requires `stateLabel`. "Validate on blur, not on every keystroke; surface the message by passing a string to `error`." (https://vercel.com/geist/input) Ours: a validation `error` updates as the value is corrected, and it or a failed save about this field shows under the control and marks it invalid; colour sits on the control's edge and the message, never the label.
+ * @words "Labels are short Title Case nouns: `Project Name`, `Domain`, `Environment Variable Name`." (https://vercel.com/geist/input) Ours: sentence case, a noun for the value ("Display name"). "Validation names the field and the constraint, ends in a period, and skips `please` (`Project name is required.`, `Code must be 6 digits.`)." (https://vercel.com/geist/input) Ours: an error says what to do next; `info.text` is one sentence and `info.label` names its button ("About display name"); a switch shows its state word ("Enabled", "Disabled") beside it.
+ * @access "Don’t wrap a labelled `<Input>` in a `Tooltip`; put the explainer on a sibling icon button so the label stays announced." (https://vercel.com/geist/input) Ours: that sibling button is the (i) `info`. The control receives its id, `aria-invalid` and `aria-describedby` through `controlProps`, so the label, the info and the error are read with it. The info button has its own name and opens on focus.
+ */
+function SettingsField({ id, label, info, error, invalid = Boolean(error), disabled, required, control = "box", controlWidth = "standard", stateLabel, children, className, ...props }) {
+    const controlProps = controlPropsOf({ id, info, error, invalid, disabled, required });
+    const errors = _jsx(SettingsFieldErrors, { id: id, error: error });
+    const beside = control === "choice";
+    const controlCell = (_jsxs("div", { "data-slot": "settings-field-control", className: cn("flex min-w-0", controlCellClassName(control, controlWidth)), children: [children({ controlProps }), control === "switch" ? _jsx("span", { className: "text-sm", children: stateLabel }) : null] }));
+    return (_jsx("div", { "data-slot": "settings-field", "data-invalid": invalid ? true : undefined, className: "contents", children: _jsxs(Field, { "data-invalid": invalid ? true : undefined, "data-disabled": disabled ? true : undefined, orientation: beside ? "horizontal" : "vertical", className: cn("items-start", className), ...props, children: [beside ? controlCell : null, _jsxs(FieldContent, { children: [_jsx(SettingsFieldLabel, { id: id, label: label, info: info }), beside ? errors : null] }), beside ? null : controlCell, beside ? null : errors] }) }));
+}
+function SettingsRow({ id, label, info, error, disabled, children, }) {
+    const invalid = Boolean(error);
+    const controlProps = controlPropsOf({ id, info, error, invalid, disabled });
+    return (_jsx("div", { "data-slot": "settings-row", "data-invalid": invalid ? true : undefined, className: "contents", children: _jsxs(Field, { "data-invalid": invalid ? true : undefined, "data-disabled": disabled ? true : undefined, orientation: "horizontal", className: "flex-wrap has-[>[data-slot=field-content]]:items-center", children: [_jsxs(FieldContent, { className: "flex-auto", children: [_jsx(SettingsFieldLabel, { id: id, label: label, info: info }), _jsx(SettingsFieldErrors, { id: id, error: error })] }), _jsx("div", { "data-slot": "settings-row-control", className: "flex items-center gap-2 group-data-[kind=select]/settings-rows:w-48 group-data-[kind=select]/settings-rows:max-w-full", children: children({ controlProps }) })] }) }));
+}
+/**
+ * Several switches, or several selects, in one card: each row its label on the left and its control on the right.
+ *
+ * @family Inputs
+ * @when A card of settings of one kind, all switches or all selects, that the card's one description covers: a project's Git switches, a team's notification channels, a set of defaults.
+ * @instead One setting is a SettingsField. Fields of different kinds, text boxes among them, are one card each. A switch that is the whole card and applies at once is the section's `headerSwitch`.
+ * @behaviour Declares `kind` once; every row is that kind, so a card cannot mix a switch with a select. Required on every row: the label and its `info` (an (i) with its sentence in a tooltip and on the control); no help line sits under a row. A switch row shows its state word beside the switch (`stateLabels`) and is controlled, so the word always follows the switch. Rows stand 16 px apart; below 28rem a row stacks its control under its label. "Pair with a form footer only when the setting needs an explicit `Save` step." (https://vercel.com/geist/toggle) Ours: a switch in a card with a Save is a draft the Save applies; in a card without one it applies at once through its `onCheckedChange`, and the card's footer holds only its line, if it has one.
+ * @words "Title Case noun phrase, 1–4 words, naming what is true when ON: `Password Protection`, not `Enable Password Protection`." (https://vercel.com/geist/toggle) Ours: sentence case, a noun for what it controls ("Pull request comments"), the same for a switch as for a select. "Render an optional one-sentence description as a sibling under the label that explains ON only. Don’t describe OFF; it’s the negation." (https://vercel.com/geist/toggle) Ours: that sentence is `info.text`. "Options are Title Case when short and match canonical branding (`Next.js`, not `NextJS`); keep the same register across the list." (https://vercel.com/geist/select) Ours: a select's options are sentence case.
+ * @access Each row's control is named by the row's label and described by its info and its error. The info button has its own name and opens on focus.
+ */
+function SettingsRows(props) {
+    return (_jsx("div", { "data-slot": "settings-rows", "data-kind": props.kind, className: "group/settings-rows flex flex-col gap-4", children: props.kind === "switch" ? switchRows(props.rows, props.stateLabels) : selectRows(props.rows) }));
+}
+function switchRows(rows, stateLabels) {
+    return rows.map((row) => (_jsx(SettingsRow, { ...row, children: ({ controlProps }) => (_jsxs(_Fragment, { children: [_jsx(Switch, { ...controlProps, checked: row.checked, name: row.name, onCheckedChange: row.onCheckedChange, size: "md" }), _jsx("span", { className: "text-sm", children: row.checked ? stateLabels.on : stateLabels.off })] })) }, row.id)));
+}
+function selectRows(rows) {
+    return rows.map((row) => (_jsx(SettingsRow, { ...row, children: ({ controlProps }) => (_jsx(NativeSelect, { ...controlProps, name: row.name, onChange: (event) => row.onValueChange(event.target.value), value: row.value, children: row.options.map((option) => (_jsx(NativeSelectOption, { value: option.value, children: option.label }, option.value))) })) }, row.id)));
+}
+export { SettingsField, SettingsRows, SettingsSection };

package/dist/components/sheet.d.ts

@@ -1,30 +1,61 @@
 import * as React from "react";
 import { Dialog as SheetPrimitive } from "@base-ui/react/dialog";
+type SheetProps = Omit<SheetPrimitive.Root.Props, "modal" | "disablePointerDismissal"> & {
+    /**
+     * The sheet owns the screen: the scrim dims the page and the page ignores the pointer. Without it
+     * the page behind stays usable and toasts stay reachable.
+     */
+    modal?: boolean;
+    /**
+     * A press on the scrim closes the sheet, for the navigation on a phone, which holds nothing a
+     * person could lose. Every other sheet stays open until Escape or Close.
+     */
+    closesOnScrimPress?: boolean;
+};
 /**
- * A panel beside a record, or the navigation on a narrow window.
+ * A panel from the edge of the window, beside what it describes.
  *
  * @family Menus
- * @when Context that belongs beside a record: inspecting a row's details. And the product's
- * navigation when the window is too narrow for the sidebar.
- * @instead For a catalogue or steps use `FormDrawer` (built on this). For editing use the row or
- * the record's page. For a blocking decision use `ConfirmDialog`.
- * @behaviour From any side, 12 px from the edges, 12 px corners all round, modal over the scrim.
- * Default 3/4 of the window up to 384 px; navigation 288 px. Header 24 px padding; body scrolls;
- * footer recessed.
- * @words Title is the record's name, never the page's heading again. A footer link names where it
- * goes: *Open Rossi Ottica*.
- * @access A modal dialog named by its title with a named close. Focus returns to the row it
- * inspects, or to the navigation button.
+ * @when "Use Sheet for persistent associated context like deployment details, log row inspection, or a member profile, where the underlying page stays useful." (https://vercel.com/geist/sheet)
+ * Ours: also the product's navigation when the window is too narrow for the sidebar.
+ * @instead "For a blocking decision, use `Modal`. For a mobile-only bottom sheet, use `Drawer`." (https://vercel.com/geist/sheet)
+ * "Don’t use Sheet to confirm destructive actions. The default `modal=false` keeps the page interactive, which weakens severity for a delete or revoke." (https://vercel.com/geist/sheet)
+ * Ours: a blocking decision is `ConfirmDialog` or `Dialog`. A catalogue or steps use `FormDrawer`
+ * (built on this). For editing use the row or the record's page.
+ * @behaviour "Sheet defaults to `modal=false` so toasts and other high-z elements stay reachable. Keep that default unless the sheet owns the screen." (https://vercel.com/geist/sheet)
+ * "Pick `side` from the trigger location: a row inspector slides from `right`, a global filter from `left`. Don’t change sides mid-session." (https://vercel.com/geist/sheet)
+ * "Outside-click does not auto-close, so always render an explicit close affordance and honor Escape." (https://vercel.com/geist/sheet)
+ * Ours: `modal` dims the page and blocks it, for a sheet that owns the screen, and `noOverlay` on
+ * its content drops the scrim again. An inset card with 16 px corners, 12 px from the window's
+ * edges; a side panel has one width that no caller sets. A given kind of sheet always opens on the
+ * same side. A press outside never closes it, Escape does, except the phone navigation, which
+ * `closesOnScrimPress` closes on a press on its scrim. The body scrolls between a header and a
+ * footer with its actions at the trailing edge, as Vercel's drawers (Production Checklist): the
+ * footer keeps the sheet's fill and stands under a 1 px rule, so its actions stay put while the
+ * body scrolls. Neutral only, with no hue but the focus ring; the primary is the only filled
+ * control. `closeLabel` is required.
+ * @words "Title is Title Case and names the entity (`Deployment Details`, `Member Profile`), not the page action." (https://vercel.com/geist/sheet)
+ * "Body is read-mostly: sentence case prose with Title Case sub-headings. Action buttons are optional; when present, follow `Verb + Noun`." (https://vercel.com/geist/sheet)
+ * "Don’t duplicate the page header inside the sheet; the sheet is the detail layer." (https://vercel.com/geist/sheet)
+ * Ours: titles and sub-headings are sentence case where Geist writes Title Case. A footer link names
+ * where it goes: *Open Rossi Ottica*.
+ * @access "Trap focus inside the sheet while it’s open and return focus to the trigger row on close so keyboard users keep their place in the list." (https://vercel.com/geist/sheet)
+ * "Provide a visible close button labeled `Close` (or an icon button with `aria-label="Close"`) since clicking outside doesn’t dismiss." (https://vercel.com/geist/sheet)
+ * "Announce the sheet with `aria-labelledby` pointing at the title; pair it with `aria-describedby` only when the body is short and load-bearing." (https://vercel.com/geist/sheet)
+ * Ours: a dialog named by its title, with a Close named in the product's words by `closeLabel`.
+ * Focus returns to the row or the navigation button that opened it.
  */
-declare function Sheet({ ...props }: SheetPrimitive.Root.Props): React.JSX.Element;
+declare function Sheet({ modal, closesOnScrimPress, ...props }: SheetProps): React.JSX.Element;
 declare function SheetTrigger({ ...props }: SheetPrimitive.Trigger.Props): React.JSX.Element;
 declare function SheetClose({ ...props }: SheetPrimitive.Close.Props): React.JSX.Element;
 type SheetContentProps = SheetPrimitive.Popup.Props & {
     side?: "top" | "right" | "bottom" | "left";
-    showCloseButton?: boolean;
-    closeLabel?: React.ReactNode;
+    /** Draw no scrim although the sheet is `modal`. */
+    noOverlay?: boolean;
+    /** The Close control's accessible name, from the product's catalogue. */
+    closeLabel: string;
 };
-declare function SheetContent({ className, children, side, showCloseButton, closeLabel, ...props }: SheetContentProps): React.JSX.Element;
+declare function SheetContent({ className, children, side, noOverlay, closeLabel, finalFocus, ...props }: SheetContentProps): React.JSX.Element;
 declare function SheetHeader({ className, ...props }: React.ComponentProps<"div">): React.JSX.Element;
 declare function SheetFooter({ className, ...props }: React.ComponentProps<"div">): React.JSX.Element;
 declare function SheetTitle({ className, ...props }: SheetPrimitive.Title.Props): React.JSX.Element;

package/dist/components/sheet.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sheet.d.ts","sourceRoot":"","sources":["../../src/components/sheet.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAC/B,OAAO,EAAE,MAAM,IAAI,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAOjE;;;;;;;;;;;;;;;GAeG;AACH,iBAAS,KAAK,CAAC,EAAE,GAAG,KAAK,EAAE,EAAE,cAAc,CAAC,IAAI,CAAC,KAAK,qBAErD;AAED,iBAAS,YAAY,CAAC,EAAE,GAAG,KAAK,EAAE,EAAE,cAAc,CAAC,OAAO,CAAC,KAAK,qBAE/D;AAED,iBAAS,UAAU,CAAC,EAAE,GAAG,KAAK,EAAE,EAAE,cAAc,CAAC,KAAK,CAAC,KAAK,qBAE3D;AAqBD,KAAK,iBAAiB,GAAG,cAAc,CAAC,KAAK,CAAC,KAAK,GAAG;IACpD,IAAI,CAAC,EAAE,KAAK,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAM,CAAC;IAC3C,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,UAAU,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;CAC9B,CAAC;AAEF,iBAAS,YAAY,CAAC,EACpB,SAAS,EACT,QAAQ,EACR,IAAc,EACd,eAAsB,EACtB,UAAoB,EACpB,GAAG,KAAK,EACT,EAAE,iBAAiB,qBAiCnB;AAED,iBAAS,WAAW,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,KAAK,CAAC,cAAc,CAAC,KAAK,CAAC,qBAQxE;AAED,iBAAS,WAAW,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,KAAK,CAAC,cAAc,CAAC,KAAK,CAAC,qBAWxE;AAED,iBAAS,UAAU,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,cAAc,CAAC,KAAK,CAAC,KAAK,qBAQtE;AAED,iBAAS,gBAAgB,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,cAAc,CAAC,WAAW,CAAC,KAAK,qBAQlF;AAED,OAAO,EACL,KAAK,EACL,YAAY,EACZ,UAAU,EACV,YAAY,EACZ,WAAW,EACX,WAAW,EACX,UAAU,EACV,gBAAgB,GACjB,CAAC"}
+{"version":3,"file":"sheet.d.ts","sourceRoot":"","sources":["../../src/components/sheet.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAC/B,OAAO,EAAE,MAAM,IAAI,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAUjE,KAAK,UAAU,GAAG,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,KAAK,EAAE,OAAO,GAAG,yBAAyB,CAAC,GAAG;IACvF;;;OAGG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;;;OAGG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,iBAAS,KAAK,CAAC,EAAE,KAAa,EAAE,kBAA0B,EAAE,GAAG,KAAK,EAAE,EAAE,UAAU,qBAWjF;AAED,iBAAS,YAAY,CAAC,EAAE,GAAG,KAAK,EAAE,EAAE,cAAc,CAAC,OAAO,CAAC,KAAK,qBAE/D;AAED,iBAAS,UAAU,CAAC,EAAE,GAAG,KAAK,EAAE,EAAE,cAAc,CAAC,KAAK,CAAC,KAAK,qBAE3D;AAqBD,KAAK,iBAAiB,GAAG,cAAc,CAAC,KAAK,CAAC,KAAK,GAAG;IACpD,IAAI,CAAC,EAAE,KAAK,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAM,CAAC;IAC3C,mDAAmD;IACnD,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,yEAAyE;IACzE,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,iBAAS,YAAY,CAAC,EACpB,SAAS,EACT,QAAQ,EACR,IAAc,EACd,SAAiB,EACjB,UAAU,EACV,UAAqC,EACrC,GAAG,KAAK,EACT,EAAE,iBAAiB,qBAiCnB;AAED,iBAAS,WAAW,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,KAAK,CAAC,cAAc,CAAC,KAAK,CAAC,qBAQxE;AAED,iBAAS,WAAW,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,KAAK,CAAC,cAAc,CAAC,KAAK,CAAC,qBAWxE;AAED,iBAAS,UAAU,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,cAAc,CAAC,KAAK,CAAC,KAAK,qBAQtE;AAED,iBAAS,gBAAgB,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,cAAc,CAAC,WAAW,CAAC,KAAK,qBAQlF;AAED,OAAO,EACL,KAAK,EACL,YAAY,EACZ,UAAU,EACV,YAAY,EACZ,WAAW,EACX,WAAW,EACX,UAAU,EACV,gBAAgB,GACjB,CAAC"}