bitboss-ui 2.1.135 → 3.0.0-alpha.4

package/dist/ai/guides/inline-edit-playbook.md

@@ -0,0 +1,267 @@
+---
+title: Inline Edit Playbook
+summary: Who owns the edit? Choosing between draft-map, autosave, and write-back persistence for inline-editing tables — commit rules per control kind, optimistic overlays with rollback, and the dirty-ring / chevron-to-spinner feedback grammar.
+---
+
+# Inline Edit Playbook
+
+Use this playbook whenever a table or dense form edits values **in place** —
+no edit page, no modal form. It answers the one question every inline-edit
+surface must answer before a line of code: **who owns the uncommitted value?**
+
+Companions: [BbTable](../BbTable.md) (the Inline editing section has a live
+example), [BbSelectPopover](../BbSelectPopover.md) (the one-popover-per-row
+canon), [Fetch Data Items](./fetch-items-playbook.md) (the provider behind a
+search-backed cell), [Design language](./design-language.md) (the editable
+badge grammar and the soft status palette).
+
+## The question: who owns the edit?
+
+There are exactly three possible owners for a value the user has changed but
+the server hasn't confirmed:
+
+1. **The rows themselves** — the cell writes straight back into the row object
+   (write-back). Terse at the cell, and wrong everywhere else; see the
+   anti-pattern section.
+2. **A page-level draft map** — edits accumulate in a map keyed by row id, and
+   an explicit Save sends them (draft map).
+3. **Nobody** — every commit persists immediately and optimistically; the
+   server is the only truth (autosave).
+
+A single static select flatters all three equally. The costs only separate
+once a row can be **partially** dirty, once a field is backed by an **async
+search**, and once a field changes **on every keystroke**. Design for those
+three stressors and the right owner falls out.
+
+## Ground rules — every pattern, no exceptions
+
+- **Typed inputs commit on `@change` (blur/Enter), never `v-model`.** A text
+  or number cell bound with `v-model` fires per keystroke; autosaving that is
+  one request per character. Bind `:model-value` down and commit in `@change`.
+  Don't reach for `@blur` + `@keydown.enter` as a substitute for `@change` —
+  binding both fires the commit **twice** for the ordinary Enter-then-blur
+  sequence (pressing Enter commits, and the field still blurs right after,
+  which is a second, separate event on the same control). A "value unchanged"
+  guard in the handler does not save you: the first commit's request is still
+  in flight when the blur fires, so the handler is comparing the draft against
+  a _stale_ prop that hasn't round-tripped yet, finds a difference, and sends
+  a second, identical request. `@change` fires once for that whole sequence —
+  that's the reason to prefer it over composing the two events yourself.
+- **Pickers commit on pick.** For a select-backed cell the click already IS
+  the commit — there is nothing to debounce and no blur to wait for.
+- **Slot rows are read-only.** Props down, events up: the cell reads
+  `item.field` (or a read-through, below) and emits/calls an action. The
+  moment a cell needs `(item as any).field = value`, the types are telling you
+  the ownership model is wrong.
+- **Options resolve once, at page level, as an array — never a per-row
+  provider.** Fifty rows with a shared statuses array cost zero requests;
+  fifty rows each owning a provider cost fifty. The exception is a genuinely
+  query-driven picker (an assignee search): share **one** provider function
+  across all rows so each row's popover stays lazy and unopened rows cost
+  nothing. See [BbSelectPopover](../BbSelectPopover.md) § One popover per
+  table row.
+- **Label the trigger from the row, never from the popover's `text`.** A lazy
+  provider has no items until first open, so `text` is empty — but the row
+  already knows its value.
+
+## Pattern: draft map keyed by id (explicit save)
+
+The page owns a `drafts` map; rows are never mutated. The map **is** the dirty
+set **and** the save payload — no snapshot, no diff, no field list, and it
+survives a refetch (a filter change or a poll cannot destroy edits).
+
+```ts
+import { reactive } from 'vue';
+
+type Patch = Partial<Pick<Row, 'title' | 'estimate' | 'status' | 'assignee'>>;
+
+const drafts = reactive<Record<string, Patch>>({});
+
+/**
+ * Read-through: the draft wins, the row is the fallback. Use a `key in`
+ * check, NOT `??` — a field legitimately drafted to `null` (a cleared
+ * number) is nullish, and `??` would silently fall through to the row.
+ */
+const valueOf = <K extends keyof Patch>(item: Row, key: K) => {
+	const draft = drafts[item.id];
+	return draft && key in draft ? (draft[key] as Row[K]) : item[key];
+};
+
+/** One setter covers every field and control kind. */
+const setField = <K extends keyof Patch>(
+	item: Row,
+	key: K,
+	value: Patch[K]
+) => {
+	if (JSON.stringify(value) === JSON.stringify(item[key])) {
+		// Re-picking the original value un-dirties for free.
+		delete drafts[item.id]?.[key];
+		if (drafts[item.id] && !Object.keys(drafts[item.id]).length)
+			delete drafts[item.id];
+		return;
+	}
+	(drafts[item.id] ??= {})[key] = value;
+};
+
+const save = async () => {
+	await api.bulkPatch(drafts); // the map IS the payload
+	Object.keys(drafts).forEach((id) => delete drafts[id]);
+	refreshKey.value += 1;
+};
+```
+
+Cells read `valueOf(item, key)` and call `setField`; a field is dirty exactly
+when `drafts[item.id]?.[key] !== undefined` — drive the dirty ring from that.
+The Save button is dirty-gated (`Object.keys(drafts).length`).
+
+**Reach for it when** the domain wants review-before-save: accounting lines,
+settings pages, anything where a half-finished batch must not hit the server.
+Assembled example: the line-item editor in the
+[record form recipe](../recipes/vue/record-form.md) (drafted rows, one
+explicit Save).
+
+## Pattern: autosave — optimistic per-field (the flagship)
+
+No dirty state exists at all. Each commit writes an **optimistic overlay**
+for that one field, fires a single-field PATCH, and refreshes; failure rolls
+back just that field. Two fields on the same row can be in flight
+independently.
+
+```ts
+import { reactive, ref } from 'vue';
+
+const pending = reactive<Record<string, Patch>>({});
+const failed = ref(new Set<string>()); // keyed `${id}:${field}`
+const refreshKey = ref(0);
+
+// `key in` rather than `??`: an overlay holding a committed `null` (a
+// cleared number mid-flight) must still win over the row.
+const valueOf = <K extends keyof Patch>(item: Row, key: K) => {
+	const patch = pending[item.id];
+	return patch && key in patch ? (patch[key] as Row[K]) : item[key];
+};
+
+const persistField = async <K extends keyof Patch>(
+	item: Row,
+	key: K,
+	value: Patch[K]
+) => {
+	if (JSON.stringify(value) === JSON.stringify(item[key])) return; // no-op commit
+	(pending[item.id] ??= {})[key] = value; // optimistic: the UI moves now
+	failed.value.delete(`${item.id}:${key}`);
+	try {
+		await api.patch(item.id, { [key]: value });
+		refreshKey.value += 1; // reload; the fetch retires the overlay (below)
+	} catch {
+		// Rollback: drop just this field — the cell reverts to the row's value.
+		delete pending[item.id]?.[key];
+		if (pending[item.id] && !Object.keys(pending[item.id]).length)
+			delete pending[item.id];
+		failed.value = new Set(failed.value).add(`${item.id}:${key}`);
+		toast({ title: 'Save failed', variant: 'destructive' });
+	}
+};
+```
+
+### Overlay retirement — the subtlety that bites
+
+**Retire the overlay in the fetch, and only for fields the response actually
+confirms — never when the save resolves.** Between the save landing and the
+reload arriving, the table still holds the OLD row; clearing the overlay early
+makes the cell revert to the stale value for the whole reload — visibly,
+new → old → new. Fields still in flight are left alone:
+
+```ts
+const fetchRows = async (): Promise<Row[]> => {
+	const rows = await api.list(filters);
+	for (const row of rows) {
+		const patch = pending[row.id];
+		if (!patch) continue;
+		for (const key of Object.keys(patch) as (keyof Patch)[]) {
+			if (JSON.stringify(patch[key]) === JSON.stringify(row[key]))
+				delete patch[key]; // the server's own data carries it now
+		}
+		if (!Object.keys(patch).length) delete pending[row.id];
+	}
+	return rows;
+};
+```
+
+**Reach for it when** the product is a workspace with no Save button — the
+Linear model. Assembled example: the
+[inline-edit workspace recipe](../recipes/vue/inline-edit-workspace.md)
+(also [nuxt](../recipes/nuxt/inline-edit-workspace.md) /
+[inertia](../recipes/inertia/inline-edit-workspace.md)).
+
+## Anti-pattern: write-back + snapshot diff
+
+The terse-looking third option — the cell writes straight into the slot row —
+is the one that never survives contact:
+
+```ts
+// The cast is the contract telling you no.
+const writeBack = (item: Row, key: EditableKey, value: unknown) => {
+	(item as any)[key] = value;
+};
+// Dirty set and save patch are REDISCOVERED by a diff against a snapshot,
+// which must enumerate every editable field — forever.
+```
+
+Three structural failures: the dirty set and the patch are rediscovered by a
+diff that must enumerate every editable field; the write needs an `any` cast
+(slot rows are typed read-only for a reason); and the edits live in the rows,
+so **any refetch — a filter change, a poll — silently destroys them**. Recipe
+code additionally bans `as any` outright, so this pattern is unshippable by
+doctrine, not just by taste.
+
+## Save feedback: the editable badge grammar
+
+Option-backed cells share one visual grammar (see
+[Design language](./design-language.md) § Badges label state):
+
+- The cell is a **self-contained component** (`StatusCell`, `RoleCell`) with
+  `editable` / `dirty` / `loading` props: a plain `BbBadge` when not editable,
+  and a `BbBadge` hosting a **`BbBadgeButton`** (bound to its own
+  `BbSelectPopover` activator) when it is — never a button and a badge
+  assembled at the call site, and never an outer button wrapping the badge.
+- Changeability is signalled by an **internal trailing chevron**
+  (`append:icon="lucide:chevron-down"` on the badge itself).
+- While the commit is in flight, set the badge's **`loading`** — the spinner
+  takes the chevron's place ([BbBadge](../BbBadge.md) § Loading state; the
+  swap is same-size, nothing shifts).
+- **The dirty ring belongs to explicit-save patterns; the spinner belongs to
+  autosave.** A draft-map cell shows a `box-shadow: 0 0 0 2px var(--bb-primary)`
+  ring meaning "changed, unsaved"; an autosave cell has no such state — its
+  only transient is "saving", which the spinner carries. Never show both on
+  one surface.
+- Status colors come from the **soft palette** in
+  [Design language](./design-language.md) § Using color — five accents
+  (`soft-gray/blue/green/amber/red`), one shared treatment. The library ships
+  none of them, so **register the names you use** in the plugin's
+  `badgeVariants` **and** style `.bb-badge.bb-badge--<name>` in the project
+  stylesheet. That registration is part of building this page, not a
+  prerequisite someone else must have done — an editable status cell whose
+  statuses are all `outline` has lost the signal the cell exists to carry.
+
+## Choosing — the decision table
+
+|                    | Write-back                   | Draft map                  | Autosave                   |
+| ------------------ | ---------------------------- | -------------------------- | -------------------------- |
+| Who owns the edit  | the rows (mutated)           | a page-level map           | nobody — the server        |
+| Survives a refetch | **no — edits destroyed**     | yes                        | yes (overlay + retirement) |
+| Requests per save  | 1 bulk (after a diff)        | 1 bulk (the map)           | 1 per field commit         |
+| State you maintain | snapshot + diff + field list | one map                    | overlay + failed set       |
+| Save button        | yes                          | yes, dirty-gated           | none                       |
+| Feedback grammar   | dirty ring                   | dirty ring                 | spinner in the chevron     |
+| Reach for it       | never                        | review-before-save domains | Linear-style workspaces    |
+
+## Where to see it assembled
+
+- [BbTable](../BbTable.md) § Inline editing — a live, tested autosave example
+  (commit-on-blur title cell + spinner-in-the-chevron status cell).
+- [inline-edit workspace recipe](../recipes/vue/inline-edit-workspace.md) —
+  the full autosave page (sprint backlog, every cell persists itself).
+- [upload center recipe](../recipes/vue/upload-center.md) — one-click badge
+  pickers (§6.1) plus commit-on-blur text/number/date cells on a mixed queue.
+- [Fetch Data Items](./fetch-items-playbook.md) — the provider contract behind
+  a search-backed assignee cell.