@tristan2828/ui-foundation 4.40.0 → 4.41.0

package/conventions/docs/cell-patterns.md

@@ -26,14 +26,14 @@
   - [A variant: a pressed icon inside another value's cell](#a-variant-a-pressed-icon-inside-another-values-cell) · lines 564–647
 - [16. Title linking to the record's view](#16-title-linking-to-the-records-view) · lines 649–684
 - [17. Quick action on the view](#17-quick-action-on-the-view) · lines 686–759
-- [18. Editable value](#18-editable-value) · lines 761–1176
-  - [A list of sub-items](#a-list-of-sub-items) · lines 1020–1077
-  - [In a table's rows](#in-a-tables-rows) · lines 1079–1164
-  - [A table of a few short columns: `width="content"`](#a-table-of-a-few-short-columns-widthcontent) · lines 1166–1176
-- [19. Stage circle for an ordered status](#19-stage-circle-for-an-ordered-status) · lines 1178–1244
-- [20. Count linking to the related records](#20-count-linking-to-the-related-records) · lines 1246–1310
-- [21. Rows grouped under headings, and a pill filter](#21-rows-grouped-under-headings-and-a-pill-filter) · lines 1312–1377
-- [22. A highlighted row, and rows that are done](#22-a-highlighted-row-and-rows-that-are-done) · lines 1379–1407
+- [18. Editable value](#18-editable-value) · lines 761–1207
+  - [A list of sub-items](#a-list-of-sub-items) · lines 1023–1108
+  - [In a table's rows](#in-a-tables-rows) · lines 1110–1195
+  - [A table of a few short columns: `width="content"`](#a-table-of-a-few-short-columns-widthcontent) · lines 1197–1207
+- [19. Stage circle for an ordered status](#19-stage-circle-for-an-ordered-status) · lines 1209–1275
+- [20. Count linking to the related records](#20-count-linking-to-the-related-records) · lines 1277–1341
+- [21. Rows grouped under headings, and a pill filter](#21-rows-grouped-under-headings-and-a-pill-filter) · lines 1343–1408
+- [22. A highlighted row, and rows that are done](#22-a-highlighted-row-and-rows-that-are-done) · lines 1410–1438
 
 <!-- /index -->
 
@@ -781,8 +781,11 @@ the form stay.
 **At rest: says it's editable without shouting.** The value reads as it
 always did. Hover tints it (`bg-muted`) and shows a pencil; the pencil is
 a real button ("Edit <label>"), so Tab reaches it and Enter opens the
-field, and its focus ring tints the value too. On a touch screen the
-pencil always shows. A click anywhere on the value opens it, except on a
+field, and its focus ring tints the value too. Muted text inside it (the
+view's "Not set", a "No caption", a done item) turns `text-foreground`
+on that tint, since muted on `bg-muted` is under 4.5:1; the package does
+it, so an app just uses `text-muted-foreground` as anywhere else. On a
+touch screen the pencil always shows. A click anywhere on the value opens it, except on a
 link inside it (a reference to a record with a view, a link in the
 notes), which still navigates.
 
@@ -1056,6 +1059,14 @@ Checklist is the reference (`checklist` in `widgetEdits`). It's built on
   option is still inside the row, and Enter in the row's text box or
   leaving the row saves the item, ids only on the wire. A new item starts
   with no pick, which the list's schema refuses on that row.
+- **Items that come from elsewhere** (a record's files, added by upload):
+  `add` in place of `newItem` and `addLabel`. It renders the app's own
+  control (an "Add files" button over a hidden file input) and is given
+  `add(items)`, which saves them at the end through `save`, as a move is
+  ("Saving…", a refusal under the list, the caret back on the control),
+  plus `items` (to stop at a limit), `disabled` (a change is saving) and
+  `onProblem(message)` (an upload refused, under the list). Each item
+  then reads, edits, moves and removes like a checklist's.
 
 ```tsx
 const checklist = editInPlace<ChecklistItem>({
@@ -1076,6 +1087,26 @@ The row's fields are one component shared with the form
 (`WidgetChecklistItemFields` in `widget-fields.tsx`), each field named by
 position ("Item 2 text") as the row buttons name the item.
 
+A list added by upload:
+
+```tsx
+const files = editInPlace<Attachment>({
+  kind: 'list',
+  value: record.attachments,
+  save: (change) => editField.mutateAsync((current) => ({ attachments: change(current.attachments) })),
+  itemName: (index) => record.attachments[index]?.name ?? `file ${index + 1}`,
+  add: ({ add, items, disabled, onProblem }) => (
+    <UploadButton                                           // the app's: a button over <input type="file" hidden>
+      disabled={disabled || items.length >= MAX}
+      onUploaded={(stored) => add(stored.map(toAttachment))}
+      onRefused={(error) => onProblem(error.message)}
+    />
+  ),
+  renderShown: (file) => <FileRow file={file} />,           // its thumbnail, name and caption
+  renderItem: (props) => <CaptionInput {...props} />,       // what edits on a click: the caption
+})
+```
+
 ### In a table's rows
 
 For a **small entity edited in its table** (a name and a few fields,

package/dist/components/app/edit-in-place.d.ts

@@ -123,14 +123,31 @@ export type EditListItemProps<TItem> = EditControlProps<TItem> & {
     /** The item being added at the end, not one already in the list. */
     isNew: boolean;
 };
+/** What a list's own `add` is given: how to put new items at the end, saved as the list's other changes are. */
+export type EditListAddProps<TItem> = {
+    /**
+     * Saves these items at the end of the list, through the list's `save`
+     * (built on its latest list, after whatever is open and whatever is
+     * still saving). "Saving…" and a refusal show under the list, as for a
+     * move. Resolves once it's done: `true` saved, `false` refused.
+     */
+    add: (items: TItem[]) => Promise<boolean>;
+    /** The list as saved: to stop adding at a limit (`items.length >= max`). */
+    items: readonly TItem[];
+    /** A change is saving: the list's buttons wait, and so should this one. */
+    disabled: boolean;
+    /** Why the add can't happen (an upload refused), under the list where a refused save shows; `null` clears it. */
+    onProblem: (message: string | null) => void;
+};
 /**
- * A list of sub-items edited in place (a checklist, a list of links), on
- * a `content` section of EntityView. Make one with `editInPlace({ kind:
- * 'list', ... })`. Every item reads as `renderShown` (a quick action, such
- * as its done box, still works there); clicking it or its pencil turns it
- * into `renderItem`, the form's own row. "Add" at the end opens a new item;
- * move up, move down and remove are ListEditor's buttons. Each change is one
- * save of the whole list.
+ * A list of sub-items edited in place (a checklist, a list of links, a
+ * record's files), on a `content` section of EntityView. Make one with
+ * `editInPlace({ kind: 'list', ... })`. Every item reads as `renderShown`
+ * (a quick action, such as its done box, still works there); clicking it
+ * or its pencil turns it into `renderItem`, the form's own row. "Add" at
+ * the end opens a new item (`newItem`), or the app's own `add` puts items
+ * there (an upload); move up, move down and remove are ListEditor's
+ * buttons. Each change is one save of the whole list.
  */
 export type EditInPlaceListOptions<TItem> = {
     kind: 'list';
@@ -145,12 +162,19 @@ export type EditInPlaceListOptions<TItem> = {
     renderItem: (props: EditListItemProps<TItem>) => ReactNode;
     /** How the item reads when it isn't being edited. Its own controls (a done box) keep working. */
     renderShown: (item: TItem, index: number) => ReactNode;
-    /** A blank item, what "Add" starts from. */
-    newItem: () => TItem;
+    /** A blank item, what "Add" starts from. Not needed with `add`; one or the other is. */
+    newItem?: () => TItem;
+    /**
+     * In place of "Add" and its blank item: what adds items, such as a file
+     * upload or a picker, e.g. a button that uploads, then calls
+     * `props.add(stored.map(toItem))`. The items save at the end of the list
+     * through `save`, so they read, move and save like any other.
+     */
+    add?: (props: EditListAddProps<TItem>) => ReactNode;
     /** How the buttons name an item, as on the form: (i) => `item ${i + 1}` gives "Move item 2 up". */
     itemName: (index: number) => string;
-    /** The Add button's text, e.g. "Add item". */
-    addLabel: string;
+    /** The Add button's text, e.g. "Add item". Not needed with `add`, whose control has its own. */
+    addLabel?: string;
     /**
      * The form's schema for the whole list (`widgetFormSchema.shape.checklist`).
      * Each change is checked as the list it would make; a message about an
@@ -169,7 +193,8 @@ export type EditInPlaceListOptions<TItem> = {
     save: (change: (current: TItem[]) => TItem[]) => Promise<unknown>;
 };
 /** A list marked editable in place. Make one with `editInPlace({ kind: 'list', ... })`. */
-export type EditInPlaceList = Omit<EditInPlaceListOptions<unknown>, 'renderItem' | 'renderShown' | 'schema' | 'save'> & {
+export type EditInPlaceList = Omit<EditInPlaceListOptions<unknown>, 'renderItem' | 'renderShown' | 'schema' | 'save' | 'add'> & {
+    add?: (props: EditListAddProps<unknown>) => ReactNode;
     renderItem: (props: EditListItemProps<unknown>) => ReactNode;
     renderShown: (item: unknown, index: number) => ReactNode;
     schema?: {

package/dist/components/app/editable-list.js

@@ -9,7 +9,8 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 //   form's row (`renderItem`), an EditableValue like any field: leaving or
 //   Enter saves, Esc gives up, one field open at a time.
 // - "Add" at the end opens a new item the same way. Enter saves it and
-//   opens the next, so a run of items goes in from the keyboard.
+//   opens the next, so a run of items goes in from the keyboard. Or the
+//   app's own `add` (an upload) puts items at the end, saved as a move is.
 // - Move and remove save at once. Whatever is open is saved first; while
 //   the change saves, the buttons wait, "Saving…" shows under the list,
 //   and a refusal leaves the list as it was with the reason under it.
@@ -56,16 +57,22 @@ function checkItem(edit, items, index, draft) {
     const issue = issues.find(({ path }) => path?.[0] === index) ?? issues.find(({ path }) => !path?.length) ?? issues[0];
     return { success: false, error: { issues: issue ? [issue] : [] } };
 }
+// The app's own add, as a component of its own: it renders the app's
+// control with what it's given, and holds nothing.
+function ListAdd({ render, ...props }) {
+    return _jsx("div", { "data-list-add-slot": "", children: render(props) });
+}
 export function EditableList({ label, edit, emptyLabel }) {
     const store = useContext(EditInPlaceContext);
     if (!store)
         throw new Error('A list edited in place works inside an <EntityView>, which runs editing in place.');
     const items = edit.value;
     const statusId = useId();
-    const [status, setStatus] = useState({ saving: false, error: null });
+    const [status, setStatus] = useState({ saving: false, inFlight: 0, error: null });
     // The buttons are disabled while a change saves, which drops the caret.
     // Once the list shows the outcome it goes to the first of these buttons
-    // (by name) that's there and enabled, else to Add.
+    // (by name) that's there and enabled, else to Add (or the app's add's
+    // first button).
     const root = useRef(null);
     const focusNext = useRef(null);
     useEffect(() => {
@@ -75,26 +82,30 @@ export function EditableList({ label, edit, emptyLabel }) {
         focusNext.current = null;
         const buttons = [...(root.current?.querySelectorAll('button:not(:disabled)') ?? [])];
         const target = names.map((name) => buttons.find((button) => button.getAttribute('aria-label') === name)).find(Boolean);
-        (target ?? root.current?.querySelector('[data-list-add]:not(:disabled)'))?.focus();
+        (target ?? root.current?.querySelector('[data-list-add]:not(:disabled), [data-list-add-slot] button:not(:disabled)'))?.focus();
     }, [items, status.saving]);
-    // Move and remove: save the open field first (if it can't save, it stays
-    // and nothing else happens), then the change.
-    const act = async (change, focusAfter, focusIfRefused) => {
-        if (status.saving)
-            return;
+    // Move, remove and the app's own add: save the open field first (if it
+    // can't save, it stays and nothing else happens), then the change. An
+    // add that lands while a change saves (an upload finishing) still goes:
+    // `save` builds on the latest list, and "Saving…" stays until both are done.
+    const act = async (change, focusAfter, focusIfRefused, waits = true) => {
+        if (waits && status.saving)
+            return false;
         const open = store.open;
         if (open !== null && !(await store.commit(open)))
-            return;
-        setStatus({ saving: true, error: null });
+            return false;
+        setStatus((now) => ({ saving: true, inFlight: now.inFlight + 1, error: null }));
+        let error = null;
         try {
             await edit.save(change);
             focusNext.current = focusAfter;
-            setStatus({ saving: false, error: null });
         }
-        catch (error) {
+        catch (refused) {
             focusNext.current = focusIfRefused;
-            setStatus({ saving: false, error: messageOf(error) });
+            error = messageOf(refused);
         }
+        setStatus((now) => ({ saving: now.inFlight > 1, inFlight: now.inFlight - 1, error: error ?? now.error }));
+        return error === null;
     };
     const move = (from, to) => {
         const direction = to < from ? 'up' : 'down';
@@ -124,13 +135,19 @@ export function EditableList({ label, edit, emptyLabel }) {
             return current.map((other, i) => (i === at ? item : other));
         }),
     });
+    // The app's own add: its items saved at the end, the caret back on it.
+    const addItems = (added) => added.length === 0 ? Promise.resolve(true) : act((current) => [...current, ...added], [], [], false);
+    const onProblem = (message) => setStatus((now) => ({ ...now, error: message }));
     // The item being added, at the end.
+    const newItem = edit.newItem;
+    if (!newItem && !edit.add)
+        throw new Error('A list edited in place needs `newItem` (a blank item to add) or `add` (its own control).');
     const addEdit = {
         kind: 'text',
-        value: edit.newItem(),
+        value: newItem?.(),
         control: (props) => _jsx(ItemRow, { children: edit.renderItem({ ...props, index: items.length, isNew: true }) }),
         schema: { safeParse: (draft) => checkItem(edit, items, items.length, draft) },
         save: (item) => edit.save((current) => [...current, item]),
     };
-    return (_jsxs("div", { ref: root, className: "flex flex-col gap-2", "data-slot": "editable-list", children: [_jsx(ListEditor, { "aria-label": label, items: items.map((_, index) => ({ id: String(index) })), itemName: edit.itemName, addLabel: edit.addLabel, emptyText: emptyLabel, disabled: status.saving, onRemove: remove, onMove: move, renderItem: (index) => (_jsx(EditableField, { label: edit.itemName(index), edit: itemEdit(index), children: edit.renderShown(items[index], index) })), add: _jsx(EditableField, { label: edit.itemName(items.length), edit: addEdit, reopenAfterKeyboardSave: true, children: null, trigger: (start) => (_jsx("div", { children: _jsxs(Button, { "data-list-add": "", type: "button", variant: "outline", size: "sm", disabled: status.saving, onClick: start, children: [_jsx(PlusIcon, {}), edit.addLabel] }) })) }) }), _jsx("span", { id: statusId, className: "type-body", children: status.saving ? (_jsxs("span", { role: "status", className: "inline-flex items-center gap-1.5 type-caption text-muted-foreground", children: [_jsx(Spinner, { "aria-hidden": "true", className: "size-3.5" }), "Saving\u2026"] })) : (status.error && _jsx(FieldError, { className: "type-caption", children: status.error })) })] }));
+    return (_jsxs("div", { ref: root, className: "flex flex-col gap-2", "data-slot": "editable-list", children: [_jsx(ListEditor, { "aria-label": label, items: items.map((_, index) => ({ id: String(index) })), itemName: edit.itemName, addLabel: edit.addLabel ?? '', emptyText: emptyLabel, disabled: status.saving, onRemove: remove, onMove: move, renderItem: (index) => (_jsx(EditableField, { label: edit.itemName(index), edit: itemEdit(index), children: edit.renderShown(items[index], index) })), add: edit.add ? (_jsx(ListAdd, { render: edit.add, add: addItems, items: items, disabled: status.saving, onProblem: onProblem })) : (_jsx(EditableField, { label: edit.itemName(items.length), edit: addEdit, reopenAfterKeyboardSave: true, children: null, trigger: (start) => (_jsx("div", { children: _jsxs(Button, { "data-list-add": "", type: "button", variant: "outline", size: "sm", disabled: status.saving, onClick: start, children: [_jsx(PlusIcon, {}), edit.addLabel] }) })) })) }), _jsx("span", { id: statusId, className: "type-body", children: status.saving ? (_jsxs("span", { role: "status", className: "inline-flex items-center gap-1.5 type-caption text-muted-foreground", children: [_jsx(Spinner, { "aria-hidden": "true", className: "size-3.5" }), "Saving\u2026"] })) : (status.error && _jsx(FieldError, { className: "type-caption", children: status.error })) })] }));
 }

package/dist/components/app/editable-value.js

@@ -206,7 +206,7 @@ export function EditableField({ label, edit, children, layout = 'block', classNa
     if (state.status === 'closed' && !always) {
         if (trigger)
             return (_jsx("span", { ref: triggerBox, className: "contents", children: trigger(start) }));
-        return (_jsxs("span", { "data-slot": "editable-value", onClick: onShownClick, className: cn('group/editable relative -mx-1.5 cursor-text items-start gap-1 rounded-md px-1.5 transition-colors hover:bg-muted has-[[data-edit]:focus-visible]:bg-muted', layout === 'block' ? 'flex w-full' : 'inline-flex max-w-full align-top', className), children: [_jsx("span", { className: "min-w-0 flex-1", children: children }), _jsx(Button, { ref: editButton, "data-edit": "", type: "button", variant: "ghost", size: "icon-xs", "aria-label": `Edit ${label}`, onClick: start, className: "shrink-0 text-muted-foreground opacity-0 group-hover/editable:opacity-100 focus-visible:opacity-100 pointer-coarse:opacity-100", children: _jsx(PencilIcon, {}) })] }));
+        return (_jsxs("span", { "data-slot": "editable-value", onClick: onShownClick, className: cn('group/editable relative -mx-1.5 cursor-text items-start gap-1 rounded-md px-1.5 transition-colors hover:bg-muted has-[[data-edit]:focus-visible]:bg-muted', layout === 'block' ? 'flex w-full' : 'inline-flex max-w-full align-top', className), children: [_jsx("span", { className: "min-w-0 flex-1 group-hover/editable:[&_.text-muted-foreground]:text-foreground group-has-[[data-edit]:focus-visible]/editable:[&_.text-muted-foreground]:text-foreground", children: children }), _jsx(Button, { ref: editButton, "data-edit": "", type: "button", variant: "ghost", size: "icon-xs", "aria-label": `Edit ${label}`, onClick: start, className: "shrink-0 text-muted-foreground opacity-0 group-hover/editable:opacity-100 focus-visible:opacity-100 pointer-coarse:opacity-100", children: _jsx(PencilIcon, {}) })] }));
     }
     // Always editable, before the store has it (the first render): the saved value.
     const open = state.status === 'closed' ? { status: 'open', draft: edit.value, error: null, autosave: undefined, revision: 0 } : state;

package/dist/index.d.ts

@@ -8,7 +8,7 @@ export { type RowGroup } from './components/app/table-groups.js';
 export { byDay, type ByDayOptions } from './lib/group-by-day.js';
 export { EntityForm, type EntityFormProps } from './components/app/entity-form.js';
 export { EntityView, type EntityViewField, type EntityViewLayout, type EntityViewPlacement, type EntityViewProps, type EntityViewSection, } from './components/app/entity-view.js';
-export { editInPlace, type EditControlProps, type EditInPlace, type EditInPlaceList, type EditInPlaceListOptions, type EditInPlaceOptions, type EditKind, type EditListItemProps, } from './components/app/edit-in-place.js';
+export { editInPlace, type EditControlProps, type EditInPlace, type EditInPlaceList, type EditInPlaceListOptions, type EditInPlaceOptions, type EditKind, type EditListAddProps, type EditListItemProps, } from './components/app/edit-in-place.js';
 export { DataEnvironmentBanner } from './components/app/data-environment-banner.js';
 export { EditableValue, type EditableValueProps } from './components/app/editable-value.js';
 export { ErrorState } from './components/app/error-state.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tristan2828/ui-foundation",
-  "version": "4.40.0",
+  "version": "4.41.0",
   "description": "Shared UI foundation for contract-first, database-backed React apps: shadcn primitives, DataTable/EntityForm composites, auth, the gateway error seam, design tokens, lint rules and the AI playbook.",
   "license": "MIT",
   "repository": {