@danxbot/ui 11.1.0 → 12.0.0

package/dist/types/components/EditGutter.d.ts

@@ -1,10 +1,6 @@
 import { type ReactNode } from "react";
-/** The controlled activation pair every pencil-activated field takes. */
-export interface EditActivation {
-    editing: boolean;
-    onEditingChange: (editing: boolean) => void;
-}
-export interface EditGutterProps {
+import { type EditActivation } from "./edit/activation";
+interface EditGutterFieldProps {
     /**
      * The pencil's accessible name — say WHAT it edits ("Edit title"), because
      * a screen reader lists it among every other pencil on the page.
@@ -15,6 +11,20 @@ export interface EditGutterProps {
      * `{(edit) => <InlineEdit {...edit} … />}`.
      */
     children: (activation: EditActivation) => ReactNode;
+    /** Render no pencil — the field cannot be edited here. */
+    disabled?: boolean;
     className?: string;
 }
-export declare function EditGutter({ label, children, className }: EditGutterProps): import("react").JSX.Element;
+/**
+ * The gutter keeps `editing` itself (omit both), or the caller owns it: pass
+ * `editing` AND `onEditingChange` (`EditActivation`) — the pencil then asks
+ * through `onEditingChange(true)` and the field's close arrives through
+ * `onEditingChange(false)`. One without the other is a type error and throws
+ * at render, for the reason `assertActivationPair` gives.
+ */
+export type EditGutterProps = EditGutterFieldProps & ({
+    editing?: undefined;
+    onEditingChange?: (editing: boolean) => void;
+} | EditActivation);
+export declare function EditGutter({ label, children, editing: editingProp, onEditingChange, disabled, className }: EditGutterProps): import("react").JSX.Element;
+export {};

package/dist/types/components/InlineEdit.d.ts

@@ -1,16 +1,19 @@
 import { type Ref } from "react";
 import { useRender } from "@base-ui/react/use-render";
-import { type InlineEditCommit } from "./edit/outcome";
-export type { InlineEditCommit, InlineEditOutcome, InlineEditRefusal } from "./edit/outcome";
-export interface InlineEditProps {
+import { type EditActivation } from "./edit/activation";
+import { type EditCommit } from "./edit/outcome";
+interface InlineEditFieldProps {
     /**
      * The committed value. Controlled — this component never holds the truth,
      * only the draft while somebody is typing one.
      */
     value: string;
     /**
-     * Commit a new value. Called ONLY when the live text actually differs from
-     * `value`.
+     * Commit a new value. Called ONLY when the live text differs both from
+     * `value` and from the value editing began from — text the reader did not
+     * change is never written back, even if `value` moved underneath the open
+     * field (with `autosaveMs`, "unchanged" is measured against the last value
+     * this edit committed instead — see "AUTOSAVE").
      *
      * `base` is the `value` this control saw at the moment editing BEGAN —
      * captured once and handed back unchanged regardless of how long the edit or
@@ -23,7 +26,7 @@ export interface InlineEditProps {
      * it settles. Resolve/return `{ refusal }` to reject the value with a
      * reason; throw or reject to report that the save itself failed.
      */
-    onCommit: InlineEditCommit;
+    onCommit: EditCommit;
     /**
      * The refusals that are knowable WITHOUT a request. Return the reason, or
      * `null` to accept. Runs after the unchanged check and before `onCommit`.
@@ -93,7 +96,10 @@ export interface InlineEditProps {
     /**
      * This value cannot be edited at all, AND WHY. `{ reason }`, matching
      * `SettingRow.readOnly` — a control that refuses in silence is
-     * indistinguishable from one that is broken.
+     * indistinguishable from one that is broken. Under controlled activation a
+     * request to open (`editing` true) is declined by handing the closed state
+     * straight back through `onEditingChange(false)`, so a pencil driving it
+     * returns instead of waiting on a field that will never open (DX-3372 H3).
      */
     readOnly?: {
         reason: string;
@@ -102,33 +108,13 @@ export interface InlineEditProps {
      * What is shown when the commit REJECTS (a thrown error or a rejected
      * promise — never a `{ refusal }`, which renders its own text).
      *
-     * @default "Could not save. Your text is still here — press Enter to try again."
+     * @default "Could not save. Your text is still here — press <key> to try again.",
+     * where <key> is the key that commits in this configuration: Enter, or
+     * Ctrl+Enter for a `multiline` field without `autosaveMs`.
      */
     failureMessage?: string;
     /** The rejected error, handed on so it can be logged or reported. */
     onError?: (error: unknown) => void;
-    /**
-     * CONTROLLED ACTIVATION (DX-3372). Pass it and the control never opens
-     * ITSELF — no click, Enter or F2 — because something else (the pencil of an
-     * `EditGutter`, a menu item, a shortcut) is the way in. Setting it `true`
-     * opens the field, focused, caret at the end; the control asks to close
-     * through `onEditingChange(false)` once a commit lands or Escape cancels.
-     * Setting it `false` yourself while it is open abandons the draft exactly as
-     * Escape would — nothing is written. At rest the element leaves the tab
-     * order and drops its hover affordance, so the trigger is the one stop.
-     *
-     * Omit it for the self-opening control (click, Enter or F2).
-     */
-    editing?: boolean;
-    /**
-     * Fires exactly when the control itself starts or ends editing — never while
-     * a read-only control merely declines to open, and never for a change the
-     * caller made through `editing`. Use it to suspend any re-render-from-server
-     * logic of your own for as long as someone is actually looking at the
-     * field; see the module comment. With `editing` controlled, this is how the
-     * control hands the closed state back.
-     */
-    onEditingChange?: (editing: boolean) => void;
     /** Render as a different element — see `Button`'s own `render` for the shape. */
     render?: useRender.RenderProp;
     /**
@@ -143,4 +129,31 @@ export interface InlineEditProps {
     messageClassName?: string;
     ref?: Ref<HTMLElement>;
 }
-export declare function InlineEdit({ value, onCommit, validate, liveValidate, label, placeholder, size, multiline, autosaveMs, readOnly, failureMessage, onError, editing: editingProp, onEditingChange, render, className, messageClassName, inputMode, ref, }: InlineEditProps): import("react").JSX.Element;
+/**
+ * SELF-ACTIVATED: omit `editing` and the control opens itself on click, Enter
+ * or F2. `onEditingChange` then only observes — it fires when the control
+ * starts editing and when it stops, so a caller can suspend its own
+ * re-render-from-server logic for exactly as long as someone is typing.
+ */
+interface InlineEditSelfActivated {
+    editing?: undefined;
+    onEditingChange?: (editing: boolean) => void;
+}
+/**
+ * The props. `editing` + `onEditingChange` are a discriminated pair
+ * (DX-3372 review P0): either omit `editing` (self-activated, above) or pass
+ * BOTH (`EditActivation` — controlled). Controlled, the control never opens
+ * itself; `true` opens it focused with the caret at the end; it hands the
+ * closed state back through `onEditingChange(false)` after a landed commit,
+ * Escape, or a refused opening (read-only). Setting `editing` false yourself
+ * ends the edit exactly as Escape does — nothing more is written. A save that
+ * is already out when you do cannot be recalled: it still reaches your
+ * `onCommit` promise, but its outcome no longer touches the field — no
+ * message, no focus move, no second `onEditingChange(false)` — and a commit
+ * from the next opening waits for it before starting (see
+ * `edit/use-edit-session.ts`). At rest a controlled control leaves the tab
+ * order and drops its hover affordance, so the trigger is the one stop.
+ */
+export type InlineEditProps = InlineEditFieldProps & (InlineEditSelfActivated | EditActivation);
+export declare function InlineEdit(props: InlineEditProps): import("react").JSX.Element;
+export {};

package/dist/types/components/InlineMarkdownEdit.d.ts

@@ -1,7 +1,8 @@
 import { type ReactNode } from "react";
 import type { ImageUploader } from "../lib/markdown/image-pipeline";
-import { type InlineEditCommit } from "./edit/outcome";
-export interface InlineMarkdownEditProps {
+import { type EditActivation } from "./edit/activation";
+import { type EditCommit } from "./edit/outcome";
+export interface InlineMarkdownEditProps extends EditActivation {
     /** The committed markdown. Controlled — the field only ever holds a draft. */
     value: string;
     /**
@@ -10,11 +11,18 @@ export interface InlineMarkdownEditProps {
      * began from; return/resolve `{ refusal }` to refuse with a reason, throw or
      * reject to report a failed save.
      */
-    onCommit: InlineEditCommit;
-    /** Whether the editor is open. REQUIRED — see the module comment. */
+    onCommit: EditCommit;
+    /**
+     * Whether the editor is open — REQUIRED, see the module comment. The field
+     * hands the closed state back through `onEditingChange(false)` once a commit
+     * lands, on Escape, and when asked to open while `readOnly`. Setting it
+     * `false` yourself drops the draft exactly as Escape does. A save already
+     * out when you do cannot be recalled: your `onCommit` promise still settles,
+     * but its outcome no longer touches the field — no message, no focus move,
+     * no `onEditingChange(false)` — and a commit from the next opening waits for
+     * it before starting.
+     */
     editing: boolean;
-    /** The field asks to close through this, once a commit lands or Escape cancels. */
-    onEditingChange: (editing: boolean) => void;
     /** The accessible name of the field and of its editor. */
     label: string;
     /** Shown at rest and in the editor when the value is empty. @default "Empty" */
@@ -25,13 +33,23 @@ export interface InlineMarkdownEditProps {
     toolbar?: ReactNode;
     /** Stores a pasted/dropped/picked image — see `MarkdownEditorProps.uploadImage`. */
     uploadImage?: ImageUploader;
+    /**
+     * This value cannot be edited at all, AND WHY — `InlineEdit.readOnly`'s
+     * shape and rule: asked to open, the field hands `onEditingChange(false)`
+     * straight back, and the reason is the rest view's accessible description.
+     */
+    readOnly?: {
+        reason: string;
+    };
     /**
      * What is shown when the commit REJECTS (never a `{ refusal }`, which
      * renders its own text).
+     *
+     * @default "Could not save. Your text is still here — press Ctrl+Enter to try again."
      */
     failureMessage?: string;
     /** The rejected error, handed on so it can be logged or reported. */
     onError?: (error: unknown) => void;
     className?: string;
 }
-export declare function InlineMarkdownEdit({ value, onCommit, editing, onEditingChange, label, placeholder, collapsedLines, toolbar, uploadImage, failureMessage, onError, className, }: InlineMarkdownEditProps): import("react").JSX.Element;
+export declare function InlineMarkdownEdit(props: InlineMarkdownEditProps): import("react").JSX.Element;

package/dist/types/components/MarkdownEditor.d.ts

@@ -15,6 +15,13 @@ export interface MarkdownEditorHandle {
      * `"end"` (snapped to a real caret stop); omit it to leave the caret wherever
      * the browser puts it. DX-3372: `InlineMarkdownEdit` opens with the caret at
      * the end, the same place `InlineEdit` puts it.
+     *
+     * THROWS rather than returning quietly (DX-3372 review P0) when it cannot do
+     * what it was asked: the surface is not built yet (it is created in an
+     * effect, so a render or a layout effect is too early), the editor is
+     * read-only, focus did not land on the surface, or the caret could not be
+     * placed. A caller that goes on to assume focus is inside would otherwise
+     * wait for a blur that never comes.
      */
     focus: (caret?: "start" | "end") => void;
 }

package/dist/types/components/edit/activation.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The controlled activation pair every pencil-activated field takes, and the
+ * pair `EditGutter` hands out — so wiring a pencil to a field is one spread.
+ *
+ * `editing` says whether the field is open. The field calls
+ * `onEditingChange(false)` when it closes itself (a landed commit, Escape) and
+ * when it declines to open (read-only); it never calls `onEditingChange(true)`
+ * for an opening the caller made. The pair is all-or-nothing: a controlled
+ * `editing` with no way to hand the closed state back would leave the field
+ * shut after its first commit while the caller still believes it is open.
+ */
+export interface EditActivation {
+    editing: boolean;
+    onEditingChange: (editing: boolean) => void;
+}
+/**
+ * Throws when a caller controls `editing` without `onEditingChange`. The
+ * types already forbid it; this covers a caller that got past them (a cast,
+ * a spread of `any`, plain JavaScript). DX-3372 review P0.
+ */
+export declare function assertActivationPair(component: string, editing: boolean | undefined, onEditingChange: ((editing: boolean) => void) | undefined): void;

package/dist/types/components/edit/outcome.d.ts

@@ -1,16 +1,27 @@
 /**
  * The caller's refusal of a value, with the reason that will be shown.
  */
-export interface InlineEditRefusal {
+export interface EditRefusal {
     refusal: string;
 }
 /** What `onCommit` may report. Returning nothing accepts the value. */
-export type InlineEditOutcome = void | InlineEditRefusal;
+export type EditOutcome = void | EditRefusal;
 /** Every in-place editor's `onCommit`: the new value and the value editing began from. */
-export type InlineEditCommit = (value: string, base: string) => InlineEditOutcome | Promise<InlineEditOutcome>;
-export declare function isRefusal(outcome: InlineEditOutcome): outcome is InlineEditRefusal;
-export declare function isPromise(outcome: InlineEditOutcome | Promise<InlineEditOutcome>): outcome is Promise<InlineEditOutcome>;
-export declare const DEFAULT_FAILURE = "Could not save. Your text is still here \u2014 press Enter to try again.";
+export type EditCommit = (value: string, base: string) => EditOutcome | Promise<EditOutcome>;
+export declare function isRefusal(outcome: EditOutcome): outcome is EditRefusal;
+export declare function isPromise(outcome: EditOutcome | Promise<EditOutcome>): outcome is Promise<EditOutcome>;
+/**
+ * The key that retries a failed save in a given field: Enter where Enter
+ * commits, Ctrl+Enter where Enter inserts a newline. (Both fields accept
+ * Cmd+Enter as well as Ctrl+Enter, so "Ctrl+Enter" is true on every platform.)
+ */
+export type RetryKey = "Enter" | "Ctrl+Enter";
+/**
+ * The default failure message. It names the retry key because blur never
+ * re-attempts a failed value — DX-3372 review L1: the single shared sentence
+ * said "press Enter" in fields where Enter inserts a newline.
+ */
+export declare function defaultFailureMessage(retryKey: RetryKey): string;
 /**
  * A refusal nobody can read leaves the field open with nothing beside it — the
  * exact silent failure the outcome contract exists to rule out — so an empty

package/dist/types/components/edit/use-edit-session.d.ts

@@ -0,0 +1,55 @@
+import { type EditCommit, type EditOutcome } from "./outcome";
+export type SaveResult = {
+    outcome: EditOutcome;
+} | {
+    error: unknown;
+};
+export interface EditSessionOptions {
+    /** Named in the thrown message when a refusal carries an empty reason. */
+    component: string;
+    /** The committed value — "unchanged" is measured against it. Read live. */
+    value: string;
+    onCommit: EditCommit;
+    onError?: (error: unknown) => void;
+    failureMessage: string;
+    /** End editing after a commit that landed (or had nothing to write). */
+    close: () => void;
+    /** Put focus back on the field after a refusal or a failure. */
+    refocus: () => void;
+}
+export interface EditSession {
+    pending: boolean;
+    refusal: string | null;
+    failure: string | null;
+    /** The message on screen, if any — a refusal or a failure. */
+    blocked: string | null;
+    /** The value this session began from — `onCommit`'s `base`. */
+    readonly base: string;
+    /** Start a new session. `refusal` seeds the message slot (live validation). */
+    begin: (base: string, refusal?: string | null) => void;
+    /** Finish the current session: every save still out becomes stale. */
+    end: () => void;
+    /** Commit `next` — unchanged check (see the module comment), `validate`, `onCommit`, outcome. */
+    commit: (next: string, validate?: (next: string) => string | null) => void;
+    refuse: (reason: string, source: "validate" | "onCommit") => void;
+    fail: (error: unknown) => void;
+    setPending: (pending: boolean) => void;
+    isPending: () => boolean;
+    setRefusal: (refusal: string | null) => void;
+    clearFailure: () => void;
+    /** The current session's token, for a caller that tracks its own save. */
+    token: () => number;
+    /** Whether a save from any session is still out. */
+    busy: () => boolean;
+    /** The in-flight save, settled or not — chain after it to stay in order. */
+    inFlight: () => Promise<void> | null;
+    /**
+     * Track a save sent under `token`. `onResult` runs only if that session is
+     * still current when it settles; otherwise `onStale` does (after a stale
+     * rejection has reached `onError`).
+     */
+    track: (save: Promise<EditOutcome>, token: number, onResult: (result: SaveResult) => void, onStale?: (result: SaveResult) => void) => void;
+    /** Run `fn` once no save is out — dropped if this session ends first. */
+    whenIdle: (fn: () => void) => void;
+}
+export declare function useEditSession(options: EditSessionOptions): EditSession;

package/dist/types/index.d.ts

@@ -21,9 +21,11 @@ export { Skeleton, SkeletonText, LoadingOverlay, type SkeletonProps, type Skelet
 export { ErrorBoundary, type ErrorBoundaryProps } from "./components/ErrorBoundary";
 export { Field, FieldSet, type FieldProps, type FieldSetProps } from "./components/Field";
 export { Input, Textarea, type InputProps, type TextareaProps } from "./components/Input";
-export { InlineEdit, type InlineEditProps, type InlineEditRefusal, type InlineEditOutcome, type InlineEditCommit, } from "./components/InlineEdit";
-export { EditGutter, type EditGutterProps, type EditActivation } from "./components/EditGutter";
+export { InlineEdit, type InlineEditProps } from "./components/InlineEdit";
+export { EditGutter, type EditGutterProps } from "./components/EditGutter";
 export { InlineMarkdownEdit, type InlineMarkdownEditProps } from "./components/InlineMarkdownEdit";
+export type { EditActivation } from "./components/edit/activation";
+export type { EditCommit, EditOutcome, EditRefusal } from "./components/edit/outcome";
 export { SecretField, type SecretFieldProps, type SecretValue } from "./components/SecretField";
 export { SettingRow, SettingGroup, type SettingRowProps, type SettingGroupProps, type SettingRowControlRenderProps, } from "./components/SettingRow";
 export { DescriptionList, DescriptionListItem, type DescriptionListProps, type DescriptionListItemProps, type DescriptionListEntry, } from "./components/DescriptionList";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danxbot/ui",
-  "version": "11.1.0",
+  "version": "12.0.0",
   "type": "module",
   "description": "Danxbot — a domain-agnostic React design system with motion as a first-class primitive.",
   "license": "MIT",