@danxbot/ui 11.0.0 → 12.0.0

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

@@ -0,0 +1,30 @@
+import { type ReactNode } from "react";
+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.
+     */
+    label: string;
+    /**
+     * Render the field, spreading the activation onto it:
+     * `{(edit) => <InlineEdit {...edit} … />}`.
+     */
+    children: (activation: EditActivation) => ReactNode;
+    /** Render no pencil — the field cannot be edited here. */
+    disabled?: boolean;
+    className?: string;
+}
+/**
+ * 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,23 +1,19 @@
 import { type Ref } from "react";
 import { useRender } from "@base-ui/react/use-render";
-/**
- * The caller's refusal of a value, with the reason that will be shown.
- * Unchanged from 5.2.1 — see `InlineEditOutcome`.
- */
-export interface InlineEditRefusal {
-    refusal: string;
-}
-/** What `onCommit` may report. Returning nothing accepts the value. */
-export type InlineEditOutcome = void | InlineEditRefusal;
-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
@@ -30,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: (value: string, base: string) => InlineEditOutcome | Promise<InlineEditOutcome>;
+    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`.
@@ -100,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;
@@ -109,18 +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;
-    /**
-     * Fires exactly when editing starts and exactly when it ends — never while a
-     * read-only control merely declines to open. 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.
-     */
-    onEditingChange?: (editing: boolean) => void;
     /** Render as a different element — see `Button`'s own `render` for the shape. */
     render?: useRender.RenderProp;
     /**
@@ -135,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, 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

@@ -0,0 +1,55 @@
+import { type ReactNode } from "react";
+import type { ImageUploader } from "../lib/markdown/image-pipeline";
+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;
+    /**
+     * Commit a new value — the same contract as `InlineEdit.onCommit`: called
+     * only when the draft differs from `value`, with `base` = the value editing
+     * began from; return/resolve `{ refusal }` to refuse with a reason, throw or
+     * reject to report a failed save.
+     */
+    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 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" */
+    placeholder?: string;
+    /** Collapse the rendered view to this many lines behind a `ReadMore`. */
+    collapsedLines?: number;
+    /** Extra toolbar content for the editor, after its built-in groups. */
+    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(props: InlineMarkdownEditProps): import("react").JSX.Element;

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

@@ -10,7 +10,20 @@ import { type ImageUploadState, type ImageUploader } from "../lib/markdown/image
  * contenteditable host, never a proxy element.
  */
 export interface MarkdownEditorHandle {
-    focus: () => void;
+    /**
+     * Focus the surface. `caret` places the caret at the document's `"start"` or
+     * `"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;
 }
 export interface MarkdownEditorProps {
     /** The markdown. Controlled when `onChange` is given. */

package/dist/types/components/code-editor/recipe.d.ts

@@ -9,11 +9,11 @@ export declare const code: import("tailwind-variants").TVReturnType<{
             footer?: import("tailwind-variants").ClassValue;
             hint?: import("tailwind-variants").ClassValue;
             root?: import("tailwind-variants").ClassValue;
-            control?: import("tailwind-variants").ClassValue;
             rendered?: import("tailwind-variants").ClassValue;
             layers?: import("tailwind-variants").ClassValue;
             gutter?: import("tailwind-variants").ClassValue;
             fade?: import("tailwind-variants").ClassValue;
+            control?: import("tailwind-variants").ClassValue;
             scroller?: import("tailwind-variants").ClassValue;
             expand?: import("tailwind-variants").ClassValue;
         };
@@ -29,11 +29,11 @@ export declare const code: import("tailwind-variants").TVReturnType<{
             footer?: import("tailwind-variants").ClassValue;
             hint?: import("tailwind-variants").ClassValue;
             root?: import("tailwind-variants").ClassValue;
-            control?: import("tailwind-variants").ClassValue;
             rendered?: import("tailwind-variants").ClassValue;
             layers?: import("tailwind-variants").ClassValue;
             gutter?: import("tailwind-variants").ClassValue;
             fade?: import("tailwind-variants").ClassValue;
+            control?: import("tailwind-variants").ClassValue;
             scroller?: import("tailwind-variants").ClassValue;
             expand?: import("tailwind-variants").ClassValue;
         };
@@ -65,11 +65,11 @@ export declare const code: import("tailwind-variants").TVReturnType<{
             footer?: import("tailwind-variants").ClassValue;
             hint?: import("tailwind-variants").ClassValue;
             root?: import("tailwind-variants").ClassValue;
-            control?: import("tailwind-variants").ClassValue;
             rendered?: import("tailwind-variants").ClassValue;
             layers?: import("tailwind-variants").ClassValue;
             gutter?: import("tailwind-variants").ClassValue;
             fade?: import("tailwind-variants").ClassValue;
+            control?: import("tailwind-variants").ClassValue;
             scroller?: import("tailwind-variants").ClassValue;
             expand?: import("tailwind-variants").ClassValue;
         };

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

@@ -0,0 +1,41 @@
+/**
+ * The caller's refusal of a value, with the reason that will be shown.
+ */
+export interface EditRefusal {
+    refusal: string;
+}
+/** What `onCommit` may report. Returning nothing accepts the value. */
+export type EditOutcome = void | EditRefusal;
+/** Every in-place editor's `onCommit`: the new value and the value editing began from. */
+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
+ * reason is a programming error, thrown rather than rendered.
+ */
+export declare function assertReadableRefusal(component: string, reason: string, source: "validate" | "onCommit"): void;
+/**
+ * THE MESSAGE IS AN OVERLAY, for the reason `InlineEdit` measured: in normal
+ * flow a refusal grows the control's own wrapper, which inside a fixed-height
+ * row shoves everything beside it. Absolutely positioned, it cannot contribute
+ * height. The parent must be `relative`.
+ */
+export declare function OutcomeMessage({ id, children, className, }: {
+    id?: string;
+    children: string;
+    className?: string;
+}): import("react").JSX.Element;

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,7 +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, } from "./components/InlineEdit";
+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.0.0",
+  "version": "12.0.0",
   "type": "module",
   "description": "Danxbot — a domain-agnostic React design system with motion as a first-class primitive.",
   "license": "MIT",