Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 18 additions & 0 deletions .changeset/editable-card-in-place.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
---
"@tailor-platform/app-shell": minor
---

Add `EditableCard` for editing part of a record in place. View and edit are one card with one field list, so every field keeps its exact position when Edit is pressed and only its value turns into a control. Fields the user can't change keep their view rendering and show a hint icon whose tooltip gives the reason (`readOnly={{ kind: "system" | "calculated" | "locked" | "permission", reason }}`); an empty value shows a dash. Save submits only that card, after the fields pass validation; an async `onSave` keeps the card in edit mode until it resolves, and a rejected or throwing `onSave` keeps it there with the user's changes. Pass server errors back through `errors` to show them under their fields. Type the saved values with a type argument (`<EditableCard<OrderValues>>`). Edit moves focus to the first control; Cancel or Escape (which also calls `onCancel`) and a successful save return it to Edit.

```tsx
<EditableCard<OrderValues> title="Order details" errors={errors} onSave={saveOrder}>
<EditableCard.Field
label="Status"
value={<Badge variant="outline-info">Confirmed</Badge>}
readOnly={{ reason: "Changes as the order moves through approval." }}
/>
<EditableCard.Field name="shipTo" label="Ship to" value={order.shipTo}>
<Select items={warehouses} defaultValue={order.shipTo} />
</EditableCard.Field>
</EditableCard>
```
30 changes: 24 additions & 6 deletions docs-manifest.json
Original file line number Diff line number Diff line change
Expand Up @@ -260,7 +260,7 @@
"hashes": {
"typeSurface": "6ce6f0fdf2450cec",
"outline": "95de4d29491affb3",
"snapshot": "e6783ef54e17e11e",
"snapshot": "4374ca5851d87d1c",
"outputMd": "c1f88a287f197d79",
"examples": "7357698425183256"
}
Expand Down Expand Up @@ -694,6 +694,23 @@
"examples": "d56bfd9ea31be76a"
}
},
"editable-card": {
"slug": "editable-card",
"kind": "code-backed",
"outline": "docs-src/components/editable-card.docs.outline.md",
"output": "docs/components/editable-card.md",
"examples": "docs-src/components/editable-card.docs.examples.tsx",
"sources": ["packages/core/src/components/editable-card/**"],
"claims": [],
"symbols": ["EditableCard", "EditableCardFieldProps", "EditableCardProps"],
"hashes": {
"typeSurface": "445fdd51e74d0c1a",
"outline": "2f6a7fe2b7b8b8b7",
"snapshot": "edd1b6ae6cf8ba36",
"outputMd": "d1efabe746318c10",
"examples": "b72a3c39c3ca18e2"
}
},
"file-based-routing": {
"slug": "file-based-routing",
"kind": "prose",
Expand Down Expand Up @@ -779,9 +796,9 @@
],
"hashes": {
"typeSurface": "6210ea28649026a8",
"outline": "7c64761beea57d38",
"outline": "96ab58d9b67a4418",
"snapshot": "b222cdafb62c9883",
"outputMd": "bdbe2cece53829eb",
"outputMd": "0feb0fece857a21e",
"examples": "56c8f6cc9667bb78"
}
},
Expand Down Expand Up @@ -1426,7 +1443,7 @@
"hashes": {
"typeSurface": "bc60676f880b485b",
"outline": "6df1a21eb91b6fbc",
"snapshot": "c788f8a131677ada",
"snapshot": "01fd5adff00216fb",
"outputMd": "c5933b640a78c3bf",
"examples": "d44fc86f972fd234"
}
Expand Down Expand Up @@ -1870,9 +1887,10 @@
"packages/core/skills/app-shell-patterns/references/components/description-card.md": "8930a410d7d45f89",
"packages/core/skills/app-shell-patterns/references/components/dialog.md": "7117e72d36b059b0",
"packages/core/skills/app-shell-patterns/references/components/document-progress-card.md": "cabfb86627aefd6f",
"packages/core/skills/app-shell-patterns/references/components/editable-card.md": "d1efabe746318c10",
"packages/core/skills/app-shell-patterns/references/components/filter-rail.md": "12021e27b57f45e9",
"packages/core/skills/app-shell-patterns/references/components/form.md": "75ba9388fea50563",
"packages/core/skills/app-shell-patterns/references/components/form-layout.md": "bdbe2cece53829eb",
"packages/core/skills/app-shell-patterns/references/components/form-layout.md": "0feb0fece857a21e",
"packages/core/skills/app-shell-patterns/references/components/global-header-layout.md": "fe86450720c4d586",
"packages/core/skills/app-shell-patterns/references/components/grid.md": "d048e972ae8aba3e",
"packages/core/skills/app-shell-patterns/references/components/input.md": "876dca4c3b3bc9c5",
Expand Down Expand Up @@ -1933,7 +1951,7 @@
"packages/core/skills/app-shell-patterns/references/patterns/interaction-toast.md": "f68bdab855730f48",
"packages/core/skills/app-shell-patterns/references/pages/document-collection.md": "e79d9120d86db198",
"packages/core/skills/app-shell-patterns/references/pages/document-detail.md": "e07c7fee2478a21d",
"packages/core/skills/app-shell-patterns/SKILL.md": "63874609c07182d7",
"packages/core/skills/app-shell-patterns/SKILL.md": "47ccd442d3ae2226",
"packages/core/skills/app-shell-upgrade/references/migrations.md": "85b8177b2b14f3f8",
"packages/core/skills/app-shell-upgrade/SKILL.md": "f9be942f3e596c00"
}
Expand Down
87 changes: 87 additions & 0 deletions docs-src/components/editable-card.docs.examples.tsx
Original file line number Diff line number Diff line change
@@ -0,0 +1,87 @@
import * as React from "react";
import { Badge, EditableCard, Field, Select } from "@tailor-platform/app-shell";

const WAREHOUSES = ["Tokyo DC", "Osaka DC", "Nagoya DC"];
const PAYMENT_TERMS = ["Net 15", "Net 30", "Net 60"];

type OrderValues = {
shipTo: string;
paymentTerms: string;
};

export function BasicUsage() {
return (
<EditableCard<OrderValues>
title="Order details"
columns={3}
onSave={async (values) => {
await saveOrder(values);
}}
>
<EditableCard.Field
label="Status"
value={<Badge variant="outline-info">Confirmed</Badge>}
readOnly={{ kind: "system", reason: "Changes as the order moves through approval." }}
/>
<EditableCard.Field
label="Supplier"
value="Kansai Textile Co."
readOnly={{ kind: "locked", reason: "Can't change after the order is confirmed." }}
/>
<EditableCard.Field name="shipTo" label="Ship to" value="Osaka DC">
<Select items={WAREHOUSES} defaultValue="Osaka DC" />
</EditableCard.Field>
<EditableCard.Field name="paymentTerms" label="Payment terms" value="Net 30">
<Select items={PAYMENT_TERMS} defaultValue="Net 30" />
</EditableCard.Field>
<EditableCard.Field
label="Order total"
value="US$12,526.20"
readOnly={{ kind: "calculated", reason: "Sum of the order lines." }}
/>
</EditableCard>
);
}

type ContactValues = {
email: string;
};

export function ServerErrors() {
const [contact, setContact] = React.useState({ email: "orders@kansai-textile.example" });
const [errors, setErrors] = React.useState<Record<string, string>>({});

return (
<EditableCard<ContactValues>
title="Supplier contact"
columns={2}
errors={errors}
onCancel={() => setErrors({})}
onSave={async (values) => {
const result = await saveContact(values);
if (result.errors) {
setErrors(result.errors);
// Rejecting keeps the card in edit mode with the user's changes
throw new Error("Contact not saved");
}
setErrors({});
setContact(values);
}}
>
<EditableCard.Field name="email" label="Order email" value={contact.email} required>
<Field.Control type="email" defaultValue={contact.email} required />
</EditableCard.Field>
<EditableCard.Field label="Phone" value={null} />
</EditableCard>
);
}

async function saveOrder(values: OrderValues) {
console.log(values);
}

async function saveContact(values: ContactValues): Promise<{ errors?: Record<string, string> }> {
return values.email.endsWith("@example.com")
? { errors: { email: "Use an address at the supplier's own domain." } }
: {};
}
105 changes: 105 additions & 0 deletions docs-src/components/editable-card.docs.outline.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,105 @@
---
kind: code-backed
group: editable-card
title: EditableCard
description: Record card edited in place — fields keep their exact position between view and edit, with a save per card
sources:
- packages/core/src/components/editable-card/**
---

# EditableCard

`EditableCard` shows part of a record as a card and lets the user edit it in place. View and edit are one card with one field list, so every field keeps its exact position when Edit is pressed — only its value turns into a control. Save submits only this card, so a page can hold several cards that are each saved on their own.

Use it on detail pages where users change a few values at a time. For a whole record, or a form with its own URL, use [`FormLayout`](./form-layout.md) in a page or dialog instead. For a card that is never edited, use [`DescriptionCard`](./description-card.md).

## Import

```tsx
import { EditableCard } from "@tailor-platform/app-shell";
```

## Basic Usage

<!-- example: basic-usage -->

`value` is how the field reads in view mode. The children are the control shown in edit mode. A field without children, or with `readOnly`, keeps its value in edit mode.

## Sub-components

| Sub-component | Description |
| -------------------- | ----------------------------------------------------------------------------- |
| `EditableCard` | The card: title, Edit / Cancel / Save, and a `FormLayout` grid for the fields |
| `EditableCard.Field` | One field, drawn the same way in view and edit mode |

## Props

### EditableCard Props

| Prop | Type | Default | Description |
| ----------------- | ------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------- |
| `title` | `ReactNode` | - | Card title. It stays on one line in both modes |
| `columns` | `1 \| 2 \| 3 \| 4` | `3` | The most columns to show, as in `FormLayout` |
| `editing` | `boolean` | - | Edit mode (controlled) |
| `defaultEditing` | `boolean` | `false` | Initial edit mode when uncontrolled |
| `onEditingChange` | `(editing: boolean) => void` | - | Called on Edit, Cancel, Escape, and after a successful save |
| `onSave` | `(values: Values) => void \| Promise<void>` | - | Called with the named fields' values once they pass validation. Return a promise to stay in edit mode until it resolves |
| `onCancel` | `() => void` | - | Called when the user cancels editing, with Cancel or Escape |
| `errors` | `Record<string, string \| string[]>` | - | Errors to show under fields, keyed by field `name` — as `errors` on `Form`. A field's error clears when the user edits it |
| `editDisabled` | `boolean` | `false` | Disables Edit — for example while another card on the page is being edited |
| `className` | `string` | - | Additional CSS classes |
| `style` | `CSSProperties` | - | Inline styles |

`Values` defaults to `Record<string, unknown>`. Pass the shape of the named fields as a type argument to type `onSave`: `<EditableCard<OrderValues> onSave={(values) => …}>`.

### EditableCard.Field Props

| Prop | Type | Default | Description |
| ---------- | ----------------------------------------- | ------- | ----------------------------------------------------------------------------------------------- |
| `label` | `string` | - | Field label, shown in both modes |
| `value` | `ReactNode` | - | How the value reads in view mode — text, a Badge, a link. `null`, `undefined` and `""` show "–" |
| `children` | `ReactNode` | - | The control shown in edit mode. Leave it out for a field that is never editable |
| `name` | `string` | - | The key of this field's value in `onSave`. Required when the field has `children` |
| `span` | `2 \| 3 \| "full"` | - | Grid columns the field covers, as `span` on `Field.Root` |
| `readOnly` | `{ kind?: ReadOnlyKind; reason: string }` | - | Keeps the field read-only in edit mode, with a hint that gives the reason |
| `required` | `boolean` | - | Shows the required marker in edit mode. Put `required` on the control as well |

`EditableCard.Field` must be rendered inside an `EditableCard`; on its own it throws. To type the `readOnly` value separately, use `EditableCardFieldProps["readOnly"]`.

## Fields you can't edit

Read-only fields are never hidden, greyed out or turned into disabled inputs — any of those would move or restyle them. They keep their view rendering (a status badge stays a badge) and, in edit mode, show an icon after the label. Its tooltip gives `reason`; `kind` picks the icon:

| `kind` | For | Icon |
| -------------- | ----------------------------------------------------------------- | ---------- |
| `"system"` | Status, document number, created by, last updated | Cog |
| `"calculated"` | Due date, totals — keep the value updating while editing | Calculator |
| `"locked"` | Values frozen by the record's state (supplier after confirmation) | Lock |
| `"permission"` | Values this user isn't allowed to change | Shield |

Write the reason so it tells the user what to do: "Can't change after the order is confirmed. Cancel and re-create it instead."

## Saving

Save validates the fields first: a required field left empty, or any other invalid value, keeps the card in edit mode and shows the browser's message under the field, and `onSave` is not called.

`onSave` receives the values of the fields that have a `name`. If it returns a promise, Save and Cancel are disabled and the form is marked `aria-busy` until it settles; the card leaves edit mode when the promise resolves. When the promise rejects, or `onSave` throws, the card stays in edit mode with the user's changes so they can retry. The card logs the error to the console but doesn't show it: report it yourself. Pass errors for particular fields back through `errors` — each shows under its field, and focus moves to the first one — and show anything else in a toast.

<!-- example: server-errors -->

For a page of several cards, keep one card in edit mode at a time: control `editing` and set `editDisabled` on the others, so there is never more than one set of unsaved changes.

## Keyboard and focus

- Edit moves focus to the first control in the card.
- Escape cancels, as Cancel does, and `onCancel` is called. An Escape that a control handles itself — closing a Select, Combobox or DatePicker popup — only closes the popup.
- Cancel, Escape and a successful save return focus to the Edit button.
- When `editing` is changed from outside the card, focus is left where it is.

## Keeping fields in place

The card renders the same cell for each field in both modes: the same grid slot, a label row of fixed height and a value slot the height of a control (`Field.Value`). A few things are still yours to keep:

- Show every field in both modes. An empty value shows "–" rather than hiding the field.
- Put multi-line controls (a `Textarea`) last, with `span="full"`: they are taller than a value, so they grow their own row.
- Validation messages appear under a field and push the rows below it down. The card adds a `Field.Error` to each editable field, so don't add your own.
15 changes: 8 additions & 7 deletions docs-src/components/form-layout.docs.outline.md
Original file line number Diff line number Diff line change
Expand Up @@ -129,13 +129,14 @@ Mark required fields with `Field.Label required` and put `required` on the contr

`FormLayout` handles the fields; the container depends on the form:

| If the form… | Use |
| ------------------------------------------------ | --------------------------------------------------------------------------------------------- |
| Has header fields plus line items | `Layout maxWidth="xl"`, `FormLayout columns={4}` for the header, sections in the view's order |
| Has ordered steps that depend on earlier answers | A [wizard](../patterns/form-wizard.md): one `Form` per step |
| Needs its own URL, or is long enough to scroll | `Layout maxWidth="lg"` with card sections; add a section nav column if it helps (see below) |
| Edits part of a record shown beside it | `Sheet` (`size="lg"`) with `FormLayout columns={2}` |
| Anything else | `Dialog` sized to the form (`sm`–`xl`); plain sections once it has groups |
| If the form… | Use |
| --------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| Has header fields plus line items | `Layout maxWidth="xl"`, `FormLayout columns={4}` for the header, sections in the view's order |
| Has ordered steps that depend on earlier answers | A [wizard](../patterns/form-wizard.md): one `Form` per step |
| Edits one card of a record that's already on screen | [`EditableCard`](./editable-card.md) — edit in place, saved per card |
| Needs its own URL, or is long enough to scroll | `Layout maxWidth="lg"` with card sections; add a section nav column if it helps (see below) |
| Edits part of a record shown beside it | `Sheet` (`size="lg"`) with `FormLayout columns={2}` |
| Anything else | `Dialog` sized to the form (`sm`–`xl`); plain sections once it has groups |

A section nav is optional. It usually earns its column from about three sections; when you add one, widen the page to `Layout maxWidth="xl"` so the form keeps its width.

Expand Down
Loading
Loading