@cube-dev/ui-kit 0.136.0 → 0.137.0

package/docs/components/content/InlineInput.md

@@ -0,0 +1,278 @@
+# InlineInput
+
+Inline editable text. Displays a value as inline content and swaps to an auto-sizing text input when entering edit mode. Designed to drop into any text context (tab title, heading, paragraph, table cell) without style customization — typography, color, and font family all inherit from the parent.
+
+Unlike `TextInput`, `InlineInput` is intentionally **not** a form field. It manages its own commit lifecycle (`onSubmit` / `onCancel`) rather than participating in form validation.
+
+## When to Use
+
+- **Renameable items**: Tab titles, file names, board columns, list items
+- **Edit-in-place fields**: Inline document titles, profile names, project labels
+- **Lightweight string edits**: Cases where launching a modal or full form would be heavy
+
+## When Not to Use
+
+- **Form fields**: Use `TextInput` (with `<Form>` + `Field`) for inputs that need validation rules
+- **Multi-line text**: Single-line only in this version (multiline planned)
+- **Complex inputs**: Use a proper input component when you need masks, prefixes/suffixes, or rich validation
+
+## Component
+
+---
+
+### Properties
+
+- **`value`** `string` — Controlled value. When provided, the component is controlled.
+- **`defaultValue`** `string` — Initial value for uncontrolled usage.
+- **`onChange`** `(value: string) => void` — Fires on commit **only when the value actually changed**. Use this to update external state (controlled pattern).
+- **`isEditing`** `boolean` — Controlled editing state. When provided, the editing state is controlled.
+- **`defaultIsEditing`** `boolean` (default: `false`) — Default editing state for uncontrolled usage.
+- **`onEditingChange`** `(isEditing: boolean) => void` — Called when editing mode starts or ends.
+- **`onSubmit`** `(value: string) => void` — Fires every commit (Enter / submit-on-blur / `ref.stopEditing(true)`), even when the value did not change. Use for side effects (analytics, save toasts).
+- **`onCancel`** `() => void` — Called when editing is cancelled (Escape or empty submit when `allowEmpty` is `false`).
+- **`editTrigger`** `'dblclick' | 'click' | 'none'` (default: `dblclick`) — How edit mode is activated from the display element. Programmatic entry via `ref.startEditing()` works regardless.
+- **`submitOnBlur`** `boolean` (default: `true`) — Whether to submit when focus leaves the input.
+- **`trimOnSubmit`** `boolean` (default: `true`) — Whether to trim the value on submit.
+- **`allowEmpty`** `boolean` (default: `false`) — When `false`, submitting an empty/whitespace value cancels instead.
+- **`isDisabled`** `boolean` (default: `false`) — When `true`, edit mode cannot be entered (programmatically or otherwise).
+- **`isReadOnly`** `boolean` (default: `false`) — When `true`, edit mode cannot be entered, but the display reads as enabled.
+- **`placeholder`** `string` — Placeholder text shown in the input when the draft is empty.
+- **`renderDisplay`** `(value: string) => ReactNode` — Custom render for display (non-editing) mode.
+- **`inputStyles`** `Styles` — Convenience prop for styling the `Input` sub-element.
+
+### Base Properties
+
+Supports [Base properties](../../BaseProperties.md).
+
+### Imperative Ref
+
+The component exposes a ref with these methods:
+
+- **`startEditing()`** — Programmatically enter edit mode. Always works regardless of `editTrigger`; blocked only by `isDisabled` / `isReadOnly`.
+- **`stopEditing(submit?: boolean)`** — Programmatically exit edit mode. `submit=true` (default) commits, `submit=false` cancels.
+- **`focus()`** — Focus the underlying element (input when editing, root span otherwise).
+- **`getValue()`** — Get the current committed value.
+
+### Styling Properties
+
+#### styles
+
+Customizes the root element of the component.
+
+**Sub-elements:**
+
+- `Input` — The text input rendered in edit mode
+- `Placeholder` — The placeholder text rendered in display mode when the value is empty
+- `Measure` — The hidden text used to auto-size the input (rarely targeted)
+
+#### inputStyles
+
+Convenience prop equivalent to `styles={{ Input: { ... } }}`.
+
+### Style Properties
+
+These properties allow direct style application without using the `styles` prop:
+
+- **Position:** `gridArea`, `order`, `gridColumn`, `gridRow`, `placeSelf`, `alignSelf`, `justifySelf`, `zIndex`, `margin`, `inset`, `position`, `scrollMargin`
+- **Dimension:** `width`, `height`, `flexBasis`, `flexGrow`, `flexShrink`, `flex`
+- **Block:** `border`, `radius`, `shadow`, `outline`, `padding`, `paddingInline`, `paddingBlock`, `overflow`, `scrollbar`, `textAlign`
+- **Color:** `color`, `fill`, `fade`, `image`
+
+### Modifiers
+
+The `mods` property is automatically populated. Consumers can target these in their own `styles`:
+
+| Modifier   | Type      | Description                                                          |
+| ---------- | --------- | -------------------------------------------------------------------- |
+| editing    | `boolean` | Currently in edit mode                                               |
+| editable   | `boolean` | `editTrigger` is `dblclick` or `click` and not disabled/read-only    |
+| disabled   | `boolean` | `isDisabled` is `true`                                               |
+| read-only  | `boolean` | `isReadOnly` is `true`                                               |
+| empty      | `boolean` | The committed value is empty                                         |
+
+## Examples
+
+### Basic Usage
+
+```jsx
+<InlineInput defaultValue="Edit me" />
+```
+
+### Single-click Trigger
+
+Enter edit mode on a single click instead of double-click:
+
+```jsx
+<InlineInput defaultValue="Click me to edit" editTrigger="click" />
+```
+
+### Manual / Programmatic Trigger
+
+When `editTrigger` is `none`, the display element is inert. Use the imperative ref to enter edit mode:
+
+```jsx
+const ref = useRef<CubeInlineInputRef>(null);
+
+<>
+  <InlineInput ref={ref} editTrigger="none" defaultValue="Use the button" />
+  <Button onPress={() => ref.current?.startEditing()}>Rename</Button>
+</>
+```
+
+### Controlled Value
+
+Track the value externally:
+
+```jsx
+const [value, setValue] = useState('Controlled value');
+
+<InlineInput value={value} onChange={setValue} />
+```
+
+### Controlled Editing State
+
+Drive the editing state from outside (e.g. from a "Rename" button in a parent menu):
+
+```jsx
+const [editing, setEditing] = useState(false);
+
+<InlineInput
+  isEditing={editing}
+  onEditingChange={setEditing}
+  defaultValue="Controlled isEditing"
+  editTrigger="none"
+/>
+```
+
+### Inside a Heading
+
+The component inherits all typography from its parent:
+
+```jsx
+<Title level={2}>
+  <InlineInput defaultValue="Editable heading" />
+</Title>
+```
+
+### Inline in Paragraph
+
+Sits naturally inside text flow:
+
+```jsx
+<p>
+  Hello, my name is <InlineInput defaultValue="John Doe" /> and I love editing
+  text in place.
+</p>
+```
+
+### Placeholder for Empty Values
+
+```jsx
+<InlineInput defaultValue="" placeholder="Untitled" />
+```
+
+### Allow Empty Values
+
+By default, submitting an empty value cancels. Set `allowEmpty` to keep the empty value:
+
+```jsx
+<InlineInput defaultValue="Clearable" allowEmpty placeholder="Empty allowed" />
+```
+
+### Disabled / Read-only
+
+```jsx
+<InlineInput defaultValue="You can't edit me" isDisabled />
+<InlineInput defaultValue="Read-only value" isReadOnly />
+```
+
+## Accessibility
+
+### Keyboard Navigation
+
+- `Enter` — Commit the current draft
+- `Escape` — Cancel and revert to the previous value
+- `Tab` / focus loss — Commits when `submitOnBlur` is `true` (default), otherwise no-op
+- Arrow keys, Space, Delete, Backspace — Work normally inside the input and do not bubble to the host
+
+### ARIA Properties
+
+- **`aria-label`** — Provide a label when the input has no visible label associated. Recommended in all cases.
+- **`aria-labelledby`** — Reference the id of a visible label element.
+
+### Focus Management
+
+When entering edit mode, focus is taken explicitly by a `FocusScope` with `autoFocus`. This makes the transition deterministic even when triggered from a closing menu (which would otherwise restore focus to the menu trigger). The text content is selected automatically.
+
+When leaving edit mode, focus is not restored automatically — the host is responsible for moving focus back to a meaningful element (e.g. the parent button or row).
+
+## Best Practices
+
+1. **Do**: Always provide an `aria-label` or `aria-labelledby` for screen reader users.
+
+   ```jsx
+   <InlineInput defaultValue="My document" aria-label="Document name" />
+   ```
+
+2. **Do**: Use `editTrigger="dblclick"` for items that are also clickable for selection (the default).
+
+3. **Don't**: Use `InlineInput` as a form field. Use `TextInput` inside a `<Form>` for that.
+
+4. **Don't**: Rely on `onChange` for keystroke-by-keystroke updates — it fires only on commit. Use `isEditing` + `onEditingChange` if you need to observe the editing lifecycle.
+
+### onChange vs onSubmit
+
+These look similar but fire under different conditions. Pick the one that matches your intent:
+
+| Event       | Fires when                                                                | Typical use                              |
+| ----------- | ------------------------------------------------------------------------- | ---------------------------------------- |
+| `onChange`  | The committed value is **different** from the previous value             | Updating state (controlled pattern)      |
+| `onSubmit`  | The user commits (Enter / blur / `ref.stopEditing(true)`) — always fires | Side effects (server save, toasts)       |
+| `onCancel`  | Escape, empty submit (when `allowEmpty=false`), or `ref.stopEditing(false)` | Reverting UI, cleanup                    |
+
+### Optimistic Display
+
+When the component is **controlled** and the parent updates `value` asynchronously, the component shows the just-committed value optimistically until the parent's `value` catches up. This prevents a flicker back to the old value between commit and re-render.
+
+### Async Save & Rollback
+
+`onSubmit` may return a `Promise`. The component does not block the UI on the promise, but it watches the outcome:
+
+- **Promise resolves** — the parent is expected to have updated `value` (or chose not to). Optimistic display clears when `value` next changes.
+- **Promise rejects** — the component treats this as a save failure and **automatically reverts** the optimistic display back to the actual `value` prop. Stale optimistic state never lingers.
+
+A typical async-save pattern:
+
+```jsx
+<InlineInput
+  value={title}
+  onSubmit={async (next) => {
+    await saveToServer(next);  // throws on failure
+    setTitle(next);            // only on success
+  }}
+/>
+```
+
+If `saveToServer` throws, `InlineInput` reverts to `title` automatically. If you want to show a toast on failure, wrap inside `onSubmit` and re-throw to keep the rollback:
+
+```jsx
+<InlineInput
+  value={title}
+  onSubmit={async (next) => {
+    try {
+      await saveToServer(next);
+      setTitle(next);
+    } catch (err) {
+      showToast('Save failed');
+      throw err;
+    }
+  }}
+/>
+```
+
+If the user starts a new edit before a pending promise settles, the older promise's outcome is ignored (no late rollback can clobber the newer commit).
+
+## Related Components
+
+- [TextInput](../fields/TextInput.md) — Full form-aware text input
+- [Tabs](../navigation/Tabs.md) — Uses `InlineInput` internally for editable tab titles

package/docs/components/navigation/Tabs.md

@@ -343,7 +343,7 @@ Add dropdown menus to tabs using the `menu` prop. This replaces the need for man
 
 ### Editable Tabs with Menu
 
-Combine editable tabs with a menu for rename, duplicate, and delete actions.
+Combine editable tabs with a menu for rename, duplicate, and delete actions. The inline editing UI is provided by [InlineInput](../content/InlineInput.md), which can also be used standalone elsewhere.
 
 ```jsx
 <Tabs

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cube-dev/ui-kit",
-  "version": "0.136.0",
+  "version": "0.137.0",
   "type": "module",
   "description": "UIKit for Cube Projects",
   "repository": {

package/dist/components/navigation/Tabs/EditableTitle.js

@@ -1,100 +0,0 @@
-/** @license MIT | @cube-dev/ui-kit v0.136.0 | Cube Dev Team */
-import { useEvent } from "../../../_internal/hooks/use-event.js";
-import { EditableTitleInputElement, HiddenMeasure } from "./styled.js";
-import { useLayoutEffect, useRef, useState } from "react";
-import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
-import { useTextField } from "react-aria";
-
-//#region src/components/navigation/Tabs/EditableTitle.tsx
-/**
-* Inline editable title component for tab labels.
-*
-* When not editing, displays the title as a span with double-click to edit.
-* When editing, displays an auto-sizing input field.
-*/
-function EditableTitle({ title, isEditing, editValue, onEditValueChange, onStartEditing, onSubmit, onCancel }) {
-	const inputRef = useRef(null);
-	const measureRef = useRef(null);
-	const [inputWidth, setInputWidth] = useState(null);
-	const justEnteredEditModeRef = useRef(false);
-	const { inputProps } = useTextField({
-		"aria-label": "Edit tab title",
-		value: editValue,
-		onChange: onEditValueChange
-	}, inputRef);
-	useLayoutEffect(() => {
-		if (isEditing && inputRef.current) {
-			const input = inputRef.current;
-			justEnteredEditModeRef.current = true;
-			input.focus();
-			requestAnimationFrame(() => {
-				input.select();
-				requestAnimationFrame(() => {
-					requestAnimationFrame(() => {
-						justEnteredEditModeRef.current = false;
-					});
-				});
-			});
-		} else justEnteredEditModeRef.current = false;
-	}, [isEditing]);
-	useLayoutEffect(() => {
-		if (isEditing && measureRef.current) {
-			const width = measureRef.current.scrollWidth;
-			setInputWidth(width);
-		}
-	}, [isEditing, editValue]);
-	const handleKeyDown = useEvent((e) => {
-		if (e.key === "Enter") {
-			e.preventDefault();
-			onSubmit();
-		} else if (e.key === "Escape") {
-			e.preventDefault();
-			onCancel();
-		} else if (e.key === "ArrowLeft" || e.key === "ArrowRight" || e.key === " " || e.key === "Delete" || e.key === "Backspace") e.stopPropagation();
-	});
-	const handleBlur = useEvent(() => {
-		if (justEnteredEditModeRef.current) {
-			requestAnimationFrame(() => {
-				inputRef.current?.focus();
-				inputRef.current?.select();
-			});
-			return;
-		}
-		onSubmit();
-	});
-	const handleDoubleClick = useEvent((e) => {
-		e.preventDefault();
-		e.stopPropagation();
-		onStartEditing();
-	});
-	if (isEditing) {
-		const mergedProps = {
-			...inputProps,
-			onKeyDown: (e) => {
-				handleKeyDown(e);
-				inputProps.onKeyDown?.(e);
-			},
-			onBlur: (e) => {
-				handleBlur();
-				inputProps.onBlur?.(e);
-			}
-		};
-		return /* @__PURE__ */ jsxs(Fragment$1, { children: [/* @__PURE__ */ jsx(HiddenMeasure, {
-			ref: measureRef,
-			"aria-hidden": "true",
-			children: editValue || " "
-		}), /* @__PURE__ */ jsx(EditableTitleInputElement, {
-			...mergedProps,
-			ref: inputRef,
-			tokens: { "$input-width": inputWidth ? `${inputWidth}px` : "auto" }
-		})] });
-	}
-	return /* @__PURE__ */ jsx("span", {
-		onDoubleClick: handleDoubleClick,
-		children: title
-	});
-}
-
-//#endregion
-export { EditableTitle };
-//# sourceMappingURL=EditableTitle.js.map

package/dist/components/navigation/Tabs/EditableTitle.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"EditableTitle.js","names":[],"sources":["../../../../src/components/navigation/Tabs/EditableTitle.tsx"],"sourcesContent":["import { useLayoutEffect, useRef, useState } from 'react';\nimport { useTextField } from 'react-aria';\n\nimport { useEvent } from '../../../_internal/hooks';\n\nimport { EditableTitleInputElement, HiddenMeasure } from './styled';\n\nimport type { FocusEvent, KeyboardEvent, MouseEvent, ReactNode } from 'react';\n\n// =============================================================================\n// Types\n// =============================================================================\n\nexport interface EditableTitleProps {\n  /** The current title to display (when not editing) */\n  title: ReactNode;\n  /** Whether the title is currently being edited */\n  isEditing: boolean;\n  /** Current edit input value */\n  editValue: string;\n  /** Callback when edit value changes */\n  onEditValueChange: (value: string) => void;\n  /** Callback to start editing (e.g., on double-click) */\n  onStartEditing: () => void;\n  /** Callback when editing is submitted (Enter or blur) */\n  onSubmit: () => void;\n  /** Callback when editing is cancelled (Escape) */\n  onCancel: () => void;\n}\n\n// =============================================================================\n// Component\n// =============================================================================\n\n/**\n * Inline editable title component for tab labels.\n *\n * When not editing, displays the title as a span with double-click to edit.\n * When editing, displays an auto-sizing input field.\n */\nexport function EditableTitle({\n  title,\n  isEditing,\n  editValue,\n  onEditValueChange,\n  onStartEditing,\n  onSubmit,\n  onCancel,\n}: EditableTitleProps) {\n  const inputRef = useRef<HTMLInputElement>(null);\n  const measureRef = useRef<HTMLSpanElement>(null);\n  const [inputWidth, setInputWidth] = useState<number | null>(null);\n  const justEnteredEditModeRef = useRef(false);\n\n  // React Aria text field hook\n  const { inputProps } = useTextField(\n    {\n      'aria-label': 'Edit tab title',\n      value: editValue,\n      onChange: onEditValueChange,\n    },\n    inputRef,\n  );\n\n  // Focus and select input when entering edit mode\n  useLayoutEffect(() => {\n    if (isEditing && inputRef.current) {\n      const input = inputRef.current;\n\n      // Set flag to ignore immediate blur events\n      justEnteredEditModeRef.current = true;\n\n      input.focus();\n      // Use requestAnimationFrame to ensure selection happens after focus\n      requestAnimationFrame(() => {\n        input.select();\n        // Clear the flag after focus is established (allow 2 frames for menu to fully close)\n        requestAnimationFrame(() => {\n          requestAnimationFrame(() => {\n            justEnteredEditModeRef.current = false;\n          });\n        });\n      });\n    } else {\n      justEnteredEditModeRef.current = false;\n    }\n  }, [isEditing]);\n\n  // Measure text width and update input width\n  useLayoutEffect(() => {\n    if (isEditing && measureRef.current) {\n      const width = measureRef.current.scrollWidth;\n      setInputWidth(width);\n    }\n  }, [isEditing, editValue]);\n\n  const handleKeyDown = useEvent((e: KeyboardEvent) => {\n    if (e.key === 'Enter') {\n      e.preventDefault();\n      onSubmit();\n    } else if (e.key === 'Escape') {\n      e.preventDefault();\n      onCancel();\n    } else if (\n      e.key === 'ArrowLeft' ||\n      e.key === 'ArrowRight' ||\n      e.key === ' ' ||\n      e.key === 'Delete' ||\n      e.key === 'Backspace'\n    ) {\n      // Stop propagation to prevent tab navigation/deletion while editing\n      e.stopPropagation();\n    }\n  });\n\n  const handleBlur = useEvent(() => {\n    // Ignore blur events immediately after entering edit mode (menu closing causes focus loss)\n    if (justEnteredEditModeRef.current) {\n      // Re-focus the input since something else stole focus\n      requestAnimationFrame(() => {\n        inputRef.current?.focus();\n        inputRef.current?.select();\n      });\n      return;\n    }\n    // Submit on blur\n    onSubmit();\n  });\n\n  const handleDoubleClick = useEvent((e: MouseEvent) => {\n    e.preventDefault();\n    e.stopPropagation();\n    onStartEditing();\n  });\n\n  if (isEditing) {\n    // Merge our handlers with React Aria's inputProps\n    const mergedProps = {\n      ...inputProps,\n      onKeyDown: (e: KeyboardEvent<HTMLInputElement>) => {\n        handleKeyDown(e);\n        inputProps.onKeyDown?.(e);\n      },\n      onBlur: (e: FocusEvent<HTMLInputElement>) => {\n        handleBlur();\n        inputProps.onBlur?.(e);\n      },\n    };\n\n    return (\n      <>\n        <HiddenMeasure ref={measureRef} aria-hidden=\"true\">\n          {editValue || ' '}\n        </HiddenMeasure>\n        <EditableTitleInputElement\n          {...mergedProps}\n          ref={inputRef}\n          tokens={{ '$input-width': inputWidth ? `${inputWidth}px` : 'auto' }}\n        />\n      </>\n    );\n  }\n\n  return <span onDoubleClick={handleDoubleClick}>{title}</span>;\n}\n"],"mappings":";;;;;;;;;;;;;;AAwCA,SAAgB,cAAc,EAC5B,OACA,WACA,WACA,mBACA,gBACA,UACA,YACqB;CACrB,MAAM,WAAW,OAAyB,KAAK;CAC/C,MAAM,aAAa,OAAwB,KAAK;CAChD,MAAM,CAAC,YAAY,iBAAiB,SAAwB,KAAK;CACjE,MAAM,yBAAyB,OAAO,MAAM;CAG5C,MAAM,EAAE,eAAe,aACrB;EACE,cAAc;EACd,OAAO;EACP,UAAU;EACX,EACD,SACD;AAGD,uBAAsB;AACpB,MAAI,aAAa,SAAS,SAAS;GACjC,MAAM,QAAQ,SAAS;AAGvB,0BAAuB,UAAU;AAEjC,SAAM,OAAO;AAEb,+BAA4B;AAC1B,UAAM,QAAQ;AAEd,gCAA4B;AAC1B,iCAA4B;AAC1B,6BAAuB,UAAU;OACjC;MACF;KACF;QAEF,wBAAuB,UAAU;IAElC,CAAC,UAAU,CAAC;AAGf,uBAAsB;AACpB,MAAI,aAAa,WAAW,SAAS;GACnC,MAAM,QAAQ,WAAW,QAAQ;AACjC,iBAAc,MAAM;;IAErB,CAAC,WAAW,UAAU,CAAC;CAE1B,MAAM,gBAAgB,UAAU,MAAqB;AACnD,MAAI,EAAE,QAAQ,SAAS;AACrB,KAAE,gBAAgB;AAClB,aAAU;aACD,EAAE,QAAQ,UAAU;AAC7B,KAAE,gBAAgB;AAClB,aAAU;aAEV,EAAE,QAAQ,eACV,EAAE,QAAQ,gBACV,EAAE,QAAQ,OACV,EAAE,QAAQ,YACV,EAAE,QAAQ,YAGV,GAAE,iBAAiB;GAErB;CAEF,MAAM,aAAa,eAAe;AAEhC,MAAI,uBAAuB,SAAS;AAElC,+BAA4B;AAC1B,aAAS,SAAS,OAAO;AACzB,aAAS,SAAS,QAAQ;KAC1B;AACF;;AAGF,YAAU;GACV;CAEF,MAAM,oBAAoB,UAAU,MAAkB;AACpD,IAAE,gBAAgB;AAClB,IAAE,iBAAiB;AACnB,kBAAgB;GAChB;AAEF,KAAI,WAAW;EAEb,MAAM,cAAc;GAClB,GAAG;GACH,YAAY,MAAuC;AACjD,kBAAc,EAAE;AAChB,eAAW,YAAY,EAAE;;GAE3B,SAAS,MAAoC;AAC3C,gBAAY;AACZ,eAAW,SAAS,EAAE;;GAEzB;AAED,SACE,8CACE,oBAAC;GAAc,KAAK;GAAY,eAAY;aACzC,aAAa;IACA,EAChB,oBAAC;GACC,GAAI;GACJ,KAAK;GACL,QAAQ,EAAE,gBAAgB,aAAa,GAAG,WAAW,MAAM,QAAQ;IACnE,IACD;;AAIP,QAAO,oBAAC;EAAK,eAAe;YAAoB;GAAa"}