@danxbot/ui 5.2.1 → 6.0.0

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

@@ -2,168 +2,99 @@ 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.
+ * Unchanged from 5.2.1 — see `InlineEditOutcome`.
  */
 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.
- */
+/** What `onCommit` may report. Returning nothing accepts the value. */
 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.
+     * only 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.
+     * Commit a new value. Called ONLY when the live text actually differs from
+     * `value`.
      *
-     * 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.
+     * `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
+     * the save takes. Compare it against whatever you currently believe is
+     * authoritative to tell "this would overwrite a change that landed while I
+     * was editing" from "nothing has moved". See the module comment
+     * ("THE OVERWRITE-PROTECTION CONTRACT") for the DX-2907 problem this closes.
      *
-     * A SERVER'S VALIDATION RESPONSE 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.
-     *
-     * WHICH RESPONSES THOSE ARE IS YOUR API'S BUSINESS, and worth checking
-     * against a real one: the first integration's duplicate-name refusal arrived
-     * as HTTP 400, so a handler keyed to 422 would have shown "Could not save"
-     * for a name the server had merely declined.
+     * 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.
      */
-    onCommit: (value: string) => InlineEditOutcome | Promise<InlineEditOutcome>;
+    onCommit: (value: string, base: 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.
+     * `null` to accept. Runs after the unchanged check and before `onCommit`.
      */
     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.
+     * The accessible name AND accessible value's label, in both states —
+     * `role="textbox"` computes its accessible value from its own text content,
+     * so this is the one thing that has to be said separately. REQUIRED.
      */
     label: string;
     /**
-     * What the display shows in place of a blank value, and the field's
-     * placeholder.
+     * What the control shows in place of a blank value, and its
+     * `aria-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.
+     * @default "Empty"
      */
     placeholder?: string;
-    /** Box ramp. Matches `Input`'s names; see the recipe on why not its padding. */
+    /** Box ramp. Matches `Input`'s names. */
     size?: "sm" | "md" | "lg";
     /**
-     * Edit as a `<textarea>` that grows with its content.
+     * Edit as a growing multi-line block instead of a single line.
      *
-     * 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.
+     * THE COMMIT KEY MOVES, because Enter has to insert a newline instead: Enter
+     * inserts "\n", Cmd/Ctrl+Enter commits, Escape still cancels, blur still
+     * commits.
      */
     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.
+     * 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.
      */
     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.
+     * 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."
      */
     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.
-     */
+    /** The rejected error, handed on so it can be logged or reported. */
     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.
+     * 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;
     /**
-     * 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.
-     *
-     * TYPOGRAPHY REACHES BOTH FORMS AND DOES LAND — `font-medium`, `text-lg`,
-     * `tracking-tight` all work. That is worth saying because for one release it
-     * silently did not: the shared box declared `[font:inherit]` as a utility,
-     * the `font` shorthand resets weight, and Tailwind's emission order gave the
-     * shorthand the win, so `font-medium` computed as 400 with no error. The
-     * declaration now lives in `@layer components` (`dx-inline-type`), where
-     * every utility of equal specificity beats it.
+     * Applied in both states, and there is only one of these on purpose — see
+     * `box` above: anything that changes the box's geometry has to reach both
+     * states or the control shifts on click, and a control cannot shift on click
+     * when both states are the same element unless a class only reaches one of
+     * them.
      */
     className?: string;
-    /**
-     * The refusal/failure message only — NOT the box.
-     *
-     * A separate prop here where `className` deliberately refuses to have one,
-     * and the difference is the coupling: the display and the field must measure
-     * identically, so their classes cannot be set apart; the message is out of
-     * flow and coupled to neither.
-     *
-     * What it is FOR: the message is absolutely positioned below the control, so
-     * an `overflow: hidden` ancestor clips it and a control at the bottom of a
-     * panel points it off the edge. Reposition it (`bottom-full mb-1` to flip
-     * above), or drop `absolute` where nothing is fixed-height and the growth is
-     * fine. Without this there was no way to do either — reported as exactly that.
-     */
+    /** The refusal/failure message only — NOT the box. See 5.2.1's own doc for why it is a separate prop. */
     messageClassName?: string;
     ref?: Ref<HTMLElement>;
 }
-export declare function InlineEdit({ value, onCommit, validate, label, placeholder, size, multiline, readOnly, failureMessage, onError, render, className, messageClassName, ref, }: InlineEditProps): import("react").JSX.Element;
+export declare function InlineEdit({ value, onCommit, validate, label, placeholder, size, multiline, readOnly, failureMessage, onError, onEditingChange, render, className, messageClassName, ref, }: InlineEditProps): import("react").JSX.Element;

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

@@ -1,4 +1,16 @@
-import { type ReactNode } from "react";
+import { type ReactNode, type Ref } from "react";
+/**
+ * The imperative half of the DX-2930 / DX-2907-problem-137 contract: a
+ * consumer that needs to move focus into the surface from code (a "Edit"
+ * button, a just-opened panel) gets a NAMED method instead of reaching for
+ * `data-md-editable` inside the page — the internal it was reduced to
+ * querying for before this existed. `focus()` mirrors what the toolbar's own
+ * `apply()` already does after a command: `editor.root.focus()`, the actual
+ * contenteditable host, never a proxy element.
+ */
+export interface MarkdownEditorHandle {
+    focus: () => void;
+}
 export interface MarkdownEditorProps {
     /** The markdown. Controlled when `onChange` is given. */
     value: string;
@@ -20,5 +32,13 @@ export interface MarkdownEditorProps {
     className?: string;
     /** Height of the editable area. Grows with content when omitted. */
     minHeight?: number | string;
+    /**
+     * Focus the surface once, on mount — the same one-shot semantics as an
+     * `<input autoFocus>`. Ignored on `readOnly`, since there is nothing to
+     * focus into.
+     */
+    autoFocus?: boolean;
+    /** Imperative focus handle — see `MarkdownEditorHandle`. */
+    ref?: Ref<MarkdownEditorHandle>;
 }
-export declare function MarkdownEditor({ value, onChange, readOnly, label, hideLabel, placeholder, toolbar, className, minHeight, }: MarkdownEditorProps): import("react").JSX.Element;
+export declare function MarkdownEditor({ value, onChange, readOnly, label, hideLabel, placeholder, toolbar, className, minHeight, autoFocus, ref, }: MarkdownEditorProps): import("react").JSX.Element;

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

@@ -0,0 +1,76 @@
+import { type ReactNode, type Ref } from "react";
+declare const readMore: import("tailwind-variants").TVReturnType<{
+    [key: string]: {
+        [key: string]: import("tailwind-variants").ClassValue | {
+            bar?: import("tailwind-variants").ClassValue;
+            content?: import("tailwind-variants").ClassValue;
+            toggle?: import("tailwind-variants").ClassValue;
+            root?: import("tailwind-variants").ClassValue;
+            viewport?: import("tailwind-variants").ClassValue;
+        };
+    };
+} | {
+    [x: string]: {
+        [x: string]: import("tailwind-variants").ClassValue | {
+            bar?: import("tailwind-variants").ClassValue;
+            content?: import("tailwind-variants").ClassValue;
+            toggle?: import("tailwind-variants").ClassValue;
+            root?: import("tailwind-variants").ClassValue;
+            viewport?: import("tailwind-variants").ClassValue;
+        };
+    };
+} | {}, {
+    root: string;
+    viewport: string[];
+    content: string;
+    bar: string;
+    toggle: string;
+}, undefined, {
+    [key: string]: {
+        [key: string]: import("tailwind-variants").ClassValue | {
+            bar?: import("tailwind-variants").ClassValue;
+            content?: import("tailwind-variants").ClassValue;
+            toggle?: import("tailwind-variants").ClassValue;
+            root?: import("tailwind-variants").ClassValue;
+            viewport?: import("tailwind-variants").ClassValue;
+        };
+    };
+} | {}, {
+    root: string;
+    viewport: string[];
+    content: string;
+    bar: string;
+    toggle: string;
+}, import("tailwind-variants").TVReturnTypeLike<unknown, {
+    root: string;
+    viewport: string[];
+    content: string;
+    bar: string;
+    toggle: string;
+}>>;
+export interface ReadMoreProps {
+    /** Collapsed line count — how many rendered lines show before the fade strip. Must be a positive integer; anything else throws. */
+    lines: number;
+    /** Typically rendered Markdown — paragraphs, headings, lists, code, images. See the module comment on why the clamp is a measured line boundary rather than a computed height. */
+    children: ReactNode;
+    /** Controlled expanded state. Omit to let the component hold its own (seeded by `defaultExpanded`). */
+    expanded?: boolean;
+    /** Uncontrolled initial state. Ignored once `expanded` is supplied. @default false */
+    defaultExpanded?: boolean;
+    /** Fires on every toggle, controlled or not. */
+    onExpandedChange?: (expanded: boolean) => void;
+    /** @default "Read more" */
+    moreLabel?: string;
+    /** @default "Show less" */
+    lessLabel?: string;
+    className?: string;
+    ref?: Ref<HTMLDivElement>;
+}
+/**
+ * Clamp block content to `lines` rendered lines behind a fade strip and a
+ * single "Read more" / "Show less" toggle. Renders neither the strip nor the
+ * toggle when the content already fits — see the module comment for how that
+ * is decided.
+ */
+export declare function ReadMore({ lines, children, expanded: expandedProp, defaultExpanded, onExpandedChange, moreLabel, lessLabel, className, ref, }: ReadMoreProps): import("react").JSX.Element;
+export { readMore as readMoreVariants };

package/dist/types/components/provenance/ProvenanceDetail.d.ts

@@ -45,6 +45,15 @@ export interface ProvenanceDetailProps {
      * consumer putting its editor in `actions`, which reads as "here is the
      * value, and separately, down here, a form about some value".
      *
+     * AN `InlineEdit` HERE STILL NEEDS THE OVERWRITE-PROTECTION CONTRACT IT
+     * SHIPS WITH (DX-2930) — this panel can stay open while the underlying
+     * record keeps changing (a re-extraction, another reviewer's own edit), so
+     * an `onCommit={(next, base) => …}` that compares `base` against whatever
+     * the caller currently believes is authoritative, plus an
+     * `onEditingChange` that suspends re-rendering `record` while someone is
+     * mid-edit, is what stops this panel from resetting a draft out from under
+     * whoever opened it. See `content/docs/provenance.mdx` for the shape.
+     *
      * IT OVERRIDES THE ABSENCES TOO — redacted, empty and failed alike. A slot
      * that disappeared whenever the value was missing would vanish in exactly the
      * case a value editor is most wanted: a field that was never extracted is the

package/dist/types/index.d.ts

@@ -57,7 +57,8 @@ export { Progress, Meter, ProgressRing, type ProgressProps, type MeterProps, typ
 export { Stat, StatRow, Sparkline, type StatProps, type StatRowProps, type SparklineProps, type StatSize, type StatTrend, type StatSentiment, } from "./components/Stat";
 export { DataTable, TableEmptyState, CellStack, type DataTableProps, type TableDensity, } from "./components/Table";
 export { CodeEditor, CodeEditorToolbar, CodeEditorCaption, CodeEditorCopyButton, CodeEditorWrapToggle, CodeEditorViewSwitch, type CodeEditorProps, type CodeEditorToolbarProps, type CodeEditorView, } from "./components/CodeEditor";
-export { MarkdownEditor, type MarkdownEditorProps } from "./components/MarkdownEditor";
+export { MarkdownEditor, type MarkdownEditorProps, type MarkdownEditorHandle, } from "./components/MarkdownEditor";
+export { ReadMore, readMoreVariants, type ReadMoreProps } from "./components/ReadMore";
 export { MarkdownSurface, type SurfaceOptions, type Splice } from "./lib/markdown/surface";
 export { project, projectedText, ProjectionError } from "./lib/markdown/project";
 export type { Projection, PNode, PText, PElement } from "./lib/markdown/project";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danxbot/ui",
-  "version": "5.2.1",
+  "version": "6.0.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-popover-containment.mjs && node scripts/probe-shell.mjs && node scripts/probe-card-header.mjs && node scripts/probe-inline-edit.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-popover-containment.mjs && node scripts/probe-shell.mjs && node scripts/probe-card-header.mjs && node scripts/probe-inline-edit.mjs && node scripts/probe-read-more.mjs",
     "sync": "node scripts/sync.mjs",
     "visual": "node scripts/visual-docker.mjs",
     "visual:update": "node scripts/visual-docker.mjs --update-snapshots",