@danxbot/ui 3.9.1 → 3.10.0

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

@@ -0,0 +1,141 @@
+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.
+ *
+ * ONE OBJECT RATHER THAN TWO LOOSE RETURNS — `false` plus a separate message
+ * prop, say — because those two can disagree: a refusal with no sentence beside
+ * it is the mute rejection this whole component exists to prevent, and a
+ * sentence with nothing refusing it is a lie. This library already settled that
+ * shape three times over: `StatusOption.refusal`, `KanbanLane.refusal` and
+ * `SettingRow.readOnly: { reason }`.
+ *
+ * Written for the person who typed it — "a demand with this name already
+ * exists", not "invalid". It is the only thing they will see.
+ */
+export interface InlineEditRefusal {
+    refusal: string;
+}
+/**
+ * What `onCommit` may report. Returning nothing accepts the value.
+ *
+ * A REFUSAL IS NOT AN EXCEPTION, and keeping the two apart is the point: a
+ * refusal is the caller's rule saying no (shown as its own sentence, the field
+ * stays open for a correction), while a thrown error or a rejected promise is
+ * the save FAILING (shown as `failureMessage`, the same text kept, retryable).
+ * Folding them together would put a stack trace's message in front of an
+ * end user, or bury a real outage as a validation note.
+ */
+export type InlineEditOutcome = void | InlineEditRefusal;
+export interface InlineEditProps {
+    /**
+     * The committed value. Controlled — this component never holds the truth,
+     * it only holds the draft while somebody is typing one.
+     */
+    value: string;
+    /**
+     * Commit a new value. Called ONLY when the text actually differs from
+     * `value`; see the module comment.
+     *
+     * May return a promise, in which case the field stays open and pending until
+     * it settles. Resolve/return `{ refusal }` to reject the value with a reason;
+     * throw or reject to report that the save itself failed.
+     *
+     * A SERVER'S 422 IS A REFUSAL, NOT A FAILURE — catch it and resolve to
+     * `{ refusal: <what the server said> }`. A duplicate name is the caller's
+     * rule being applied by the only party who can check it, and it reads to the
+     * person exactly like the local one; a rejected promise means the write did
+     * not happen for a reason nobody can act on by retyping.
+     */
+    onCommit: (value: string) => InlineEditOutcome | Promise<InlineEditOutcome>;
+    /**
+     * The refusals that are knowable WITHOUT a request. Return the reason, or
+     * `null` to accept.
+     *
+     * Runs after the unchanged check and before `onCommit`, so a value that fails
+     * here never reaches the network — which is the whole point of it being
+     * separate: emptiness and length are decidable locally, uniqueness is not,
+     * and a client that guesses at the second one drifts from the server.
+     *
+     * A BARE STRING RATHER THAN `{ refusal }`, unlike `onCommit`'s return, and
+     * the difference is not an inconsistency: `onCommit` has to say WHICH of
+     * accepted-or-refused happened, so the reason needs a name to sit under.
+     * Everything this function returns is the reason, which is the same position
+     * `StatusOption.refusal` and `KanbanLane.refusal` are already a bare string
+     * in. An empty string throws, for the reason those do.
+     *
+     * It is shown through exactly the same channel a refusal from `onCommit` is —
+     * the person is not told where in the stack their name was turned down.
+     */
+    validate?: (value: string) => string | null;
+    /**
+     * The accessible name, in BOTH modes. REQUIRED — see the module comment on
+     * why a control that renames itself mid-interaction is the defect this
+     * prevents.
+     *
+     * Name the FIELD ("Demand title"), not the action ("Edit") and not the
+     * current value: it is read in a list of controls where the value is
+     * announced separately.
+     */
+    label: string;
+    /**
+     * What the display shows in place of a blank value, and the field's
+     * placeholder.
+     *
+     * A WORD, not an em-dash, and not nothing: a display whose entire content is
+     * punctuation has no name worth announcing, and one whose content is empty
+     * collapses to a few pixels — a control that cannot be hit. See
+     * `scripts/probe-card-header.mjs` for the zero-width family this belongs to.
+     */
+    placeholder?: string;
+    /** Box ramp. Matches `Input`'s names; see the recipe on why not its padding. */
+    size?: "sm" | "md" | "lg";
+    /**
+     * Edit as a `<textarea>` that grows with its content.
+     *
+     * THE COMMIT KEY MOVES, because Enter has to insert a newline. Enter is a
+     * newline, Cmd/Ctrl+Enter commits, Escape still cancels and blur still
+     * commits. Nothing else changes.
+     */
+    multiline?: boolean;
+    /**
+     * This value cannot be edited at all, AND WHY — a different fact from a
+     * value being refused, and it belongs on a different prop. `{ reason }`
+     * matches `SettingRow.readOnly`; there is no boolean form, because a control
+     * that refuses in silence is indistinguishable from one that is broken.
+     *
+     * The display stays focusable and `aria-disabled`, carrying the reason as
+     * its description and in a tooltip, so it can be asked.
+     */
+    readOnly?: {
+        reason: string;
+    };
+    /**
+     * What is shown when the commit REJECTS. Deliberately not the error's own
+     * message: that text is written for a log, and this one is read by whoever
+     * just typed a name.
+     *
+     * @default "Could not save. Your text is still here — press Enter to try again."
+     */
+    failureMessage?: string;
+    /**
+     * The rejected error, handed on so it can be logged or reported. Without
+     * this the exception is swallowed entirely, which is the silent failure this
+     * library treats as a defect rather than as tidiness.
+     */
+    onError?: (error: unknown) => void;
+    /**
+     * Render the DISPLAY as a different element. See the module comment: the
+     * rendered element is given `role="button"`, which replaces its own role.
+     */
+    render?: useRender.RenderProp;
+    /**
+     * Applied to BOTH forms, and there is only one of these on purpose. Anything
+     * that changes one box's geometry has to change the other's, or the control
+     * jumps on click — a second `fieldClassName` would make that jump one prop
+     * away at all times.
+     */
+    className?: string;
+    ref?: Ref<HTMLElement>;
+}
+export declare function InlineEdit({ value, onCommit, validate, label, placeholder, size, multiline, readOnly, failureMessage, onError, render, className, ref, }: InlineEditProps): import("react").JSX.Element;

package/dist/types/index.d.ts

@@ -21,6 +21,7 @@ export { Skeleton, SkeletonText, LoadingOverlay, type SkeletonProps, type Skelet
 export { ErrorBoundary } 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 { SecretField, type SecretFieldProps, type SecretValue } from "./components/SecretField";
 export { SettingRow, SettingGroup, type SettingRowProps, type SettingGroupProps, type SettingRowControlRenderProps, } from "./components/SettingRow";
 export { ConnectionCard, type ConnectionCardProps, type ConnectionHealth, } from "./components/ConnectionCard";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danxbot/ui",
-  "version": "3.9.1",
+  "version": "3.10.0",
   "type": "module",
   "description": "Danxbot — a domain-agnostic React design system with motion as a first-class primitive.",
   "license": "MIT",
@@ -73,7 +73,7 @@
     "gates": "npm run shoot && npm run a11y && node scripts/shoot-overlays.mjs && npm run probe",
     "a11y": "node scripts/a11y-scan.mjs",
     "shoot": "node scripts/shoot.mjs",
-    "probe": "node scripts/probe-scale.mjs && node scripts/probe-switch.mjs && node scripts/probe-slider.mjs && node scripts/probe-panel.mjs && node scripts/probe-popover-width.mjs && node scripts/probe-api.mjs && node scripts/probe-api-live.mjs && node scripts/probe-tabs-overflow.mjs && node scripts/probe-stat-row.mjs && node scripts/probe-packaging.mjs && node scripts/probe-containment.mjs && node scripts/probe-shell.mjs && node scripts/probe-card-header.mjs",
+    "probe": "node scripts/probe-scale.mjs && node scripts/probe-switch.mjs && node scripts/probe-slider.mjs && node scripts/probe-panel.mjs && node scripts/probe-popover-width.mjs && node scripts/probe-api.mjs && node scripts/probe-api-live.mjs && node scripts/probe-tabs-overflow.mjs && node scripts/probe-stat-row.mjs && node scripts/probe-packaging.mjs && node scripts/probe-containment.mjs && node scripts/probe-shell.mjs && node scripts/probe-card-header.mjs && node scripts/probe-inline-edit.mjs",
     "sync": "node scripts/sync.mjs",
     "visual": "node scripts/visual-docker.mjs",
     "visual:update": "node scripts/visual-docker.mjs --update-snapshots",