Skip to content

feat(form-layout): responsive form layout, dialog sizes and form templates - #708

Open
itsprade wants to merge 11 commits into
mainfrom
feat/form-layout
Open

itsprade wants to merge 11 commits into
mainfrom
feat/form-layout

Conversation

@itsprade

@itsprade itsprade commented Nov 10, 2026 •

Copy link
Copy Markdown
Contributor

What

A form layout layer for AppShell. Until now every form hand-wrote its own max-w-2xl, grid md:grid-cols-2, md:col-span-2 and Card-per-section. The result was single-column forms with "oceans of white space", and no shared answer to where a form should live.

Refs tailor-inc/platform-planning#1742, tailor-inc/platform-planning#1391

FormLayout lays out fields in a grid that reflows by its container's width. Column breakpoints are container queries at 400, 640 and 880px, and columns is the maximum. One field definition therefore fits a Dialog, a Sheet or a page.

<Form id="po-form" onFormSubmit={save}>
  <FormLayout columns={2}>
    <FormLayout.Section title="Supplier">
      <Field.Root name="supplier">
        <Field.Label required>Supplier</Field.Label>
        <Combobox items={suppliers} required />
      </Field.Root>
      <Field.Root name="notes" span="full">
        <Field.Label>Notes</Field.Label>
        <Textarea />
      </Field.Root>
    </FormLayout.Section>
    <FormLayout.Actions sticky>…</FormLayout.Actions>
  </FormLayout>
</Form>

New API

  • FormLayout: columns 1–4, the maximum. It's a container-query grid.
    • FormLayout.Section: a fieldset group, card or plain, with title, description, action, its own columns and disabled. The title is a real heading inside the legend, and the description is linked with aria-describedby.
    • FormLayout.Item: non-field content (an Alert or a table) with a span.
    • FormLayout.Actions: right-aligned buttons, optionally a sticky floating bar.
  • span on Field.Root and Fieldset.Root: 2 | 3 | "full", styled only inside FormLayout. A field holding a Textarea takes the full row by default. span works only on a direct child of the grid; the docs say so.
  • Field.Label required: a visual-only required marker.
  • Field.Value: a read-only value in the control's place, at an input's height so it lines up with editable fields. It's named by its label.
  • Layout maxWidth: "md" | "lg" | "xl", a centred page with a capped width.
  • Dialog.Content size: "sm" | "md" | "lg" | "xl", default md, matching Sheet.Content. Every size keeps a 1rem margin on each side.
  • Dialog.Body: scrolls long content while the header and footer stay in view.
  • New exports: FormLayout, FormLayoutProps, FormLayoutSectionProps, FormLayoutItemProps, FormLayoutActionsProps.

Changes to existing components (please check)

  • Dialog.Content is a flex column instead of a grid, so Dialog.Body can scroll.
    • Direct children other than Dialog.Body don't shrink, so a tall dialog without a Body still scrolls as a whole.
    • The height limit and default width are unchanged.
    • Snapshots of open dialogs change, including TreePicker's.
    • Breaking for hand-made scroll bodies: a dialog that made Dialog.Content a flex column itself and gave a child min-h-0 flex-1 overflow-y-auto (what main's Dialog docs used to suggest) now scrolls as a whole instead, header included. Wrap that content in Dialog.Body. ActivityCard's "All activities" dialog did this and is fixed here, with a regression test. There's a 1.21.0 migrations entry.
  • Footers: Dialog.Footer and Sheet.Footer now right-align their buttons at their natural width at every size.
    • Previously Sheet.Footer stacked buttons full width, and Dialog.Footer did so below sm.
    • Buttons show in source order from left to right, so a footer with the primary button first now shows it on the left.

All of this is in the changeset and, for the dialog scroll change, the migrations guide.

Docs

  • New FormLayout docs, with a "which container" table.
  • Updated form/* patterns (modal, sectioned, single-page) using FormLayout. The wizard pattern's steps also use FormLayout instead of hand-written grids; its step indicator is unchanged here (see Stack).
  • Dialog docs now point to Dialog.Body, and the live form example uses Dialog.Body, a footer submit with form, and FormLayout. Layout documents maxWidth.
  • Migrations guide: a 1.21.0 entry for dialog scroll bodies.

Demo (/showcase/form-templates, now in the sidebar)

Every template uses the same purchase-order fields; only the container and the column count change.

  • Templates: T1 Modal form (sm–xl), T2 Side sheet, T3 Page form (five card sections, four long and one short, with an optional section nav, on by default from three sections) and T4 Document form (Layout maxWidth="xl", line items edge to edge).
  • Field types: every AppShell control in one form, including file upload (Attachment), date range and read-only values.
  • Complex examples:
    • E1: a container-width playground.
    • E2: a dense 26-field master record.
    • E3: conditional fields and a locked section.
    • E4: a form beside a sticky summary.
    • E5: a document with editable DataTable line items.

Open questions for review

  • Where span lives: on Field.Root (no wrapper needed) or only on FormLayout.Item?
  • Textarea default: is full width for Textarea fields too implicit?
  • Shared field structure: Sean's grooming point, defining the structure once for view, create and edit, is the planned next layer (a declarative FormCard sharing DescriptionCard's field config). It isn't in this PR.
  • Real-form validation: the layouts haven't been tried against ERP Kit's real long forms yet. E2 is a synthetic form.

Testing

  • Behaviour tests cover:
    • disabled sections and the section's heading and description
    • Field.Value labelling
    • Dialog sizes keeping the margin, and non-Body children not shrinking
  • Column changes are checked by class, because jsdom can't evaluate container queries.
  • Checked in the browser at 375, 700, 1280 and 1920px.
  • All checks pass: tests (3,125), types, lint, format, docs and check-dts.

Stack

This PR now ships on its own, so Stepper and EditableCard can't hold up the forms release.

🤖 Generated with Claude Code

itsprade and others added 2 commits November 10, 2026 19:52
…lates

Add FormLayout, a grid for form fields that reflows by the width of its
container, so one form definition fits a Dialog, a Sheet or a page.
FormLayout.Section groups fields as cards or plain fieldsets, and
FormLayout.Actions is a sticky action bar for long page forms.

Supporting changes:
- span on Field.Root and Fieldset.Root; a field holding a Textarea takes
  the full row unless it sets its own span
- Field.Label required (visual marker) and Field.Value (a read-only value
  at an input's height)
- Dialog.Content size (sm-xl, matching Sheet) and Dialog.Body, which
  scrolls long content while the header and footer stay in view
- Dialog.Footer and Sheet.Footer right-align buttons at their natural width
- Layout maxWidth to centre and cap a page

The example app gets a form templates page (modal, side sheet, page form
with an optional section nav, document form, and a wizard built on
Stepper, in a dialog or on a page) and five larger examples. The
form/wizard pattern now uses Stepper for its step indicator.
Docs, form patterns and the consumer skill are updated.

Refs tailor-inc/platform-planning#1742

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

# Conflicts:
#	docs-manifest.json
#	docs-src/patterns/form-wizard.docs.examples.tsx
#	docs-src/patterns/form-wizard.docs.outline.md
#	docs/patterns/form-wizard.md
Add Stepper for wizard steps, approval stages, quality gates and other
fixed sequences. Each step has a status (complete, current, upcoming,
skipped), an optional badge and an optional description, and the line
between steps fills up to the furthest step reached. The current step
gets aria-current="step"; the others announce their status in English
or Japanese.

It lays out horizontally or vertically. A horizontal Stepper scrolls
sideways when its steps don't fit and, below 400px of container width,
shows only its markers with "Step 2 of 4" and the current step's label.
onStepClick makes completed steps clickable.

The Stepper only displays progress; the page decides each step's status.
The example app gets a Stepper showcase page.

Refs tailor-inc/platform-planning#2178

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
itsprade and others added 6 commits November 11, 2026 12:52
Replace the width table with seven rules (size by the value, not the
label; one short value takes one column; a long or two-part value takes
two; free text and non-values take the full row; keep related fields
together; don't widen to fill a row; don't size for mobile), with the
table kept as examples. The agent skill carries the same rules so agents
see them without opening the FormLayout reference.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
# Conflicts:
#	docs-manifest.json
# Conflicts:
#	docs-manifest.json
#	docs-src/components/form.docs.outline.md
#	docs/components/form.md
Stepper ships in its own PR. Take its component, docs and showcase out of
this branch, and with them the wizard template and the wizard pattern
rewrite, which depend on it. The form/wizard pattern stays as on main.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Five sections, four of them long enough to scroll past and one short, so
the section nav has somewhere to jump. The address block moves to the
shared fields so the page form and complex examples use one copy.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@itsprade
itsprade changed the base branch from feat/stepper to main November 17, 2026 09:37
@github-actions

github-actions Bot commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

Code Metrics Report

main (923933d) #708 (557a69b) +/-
Coverage 62.9% 62.9% +0.0%
Test Execution Time 4m3s 3m51s -12s
Details
  |                     | main (923933d) | #708 (557a69b) |  +/-  |
  |---------------------|----------------|----------------|-------|
+ | Coverage            |          62.9% |          62.9% | +0.0% |
  |   Files             |            294 |            296 |    +2 |
  |   Lines             |          13483 |          13532 |   +49 |
+ |   Covered           |           8485 |           8525 |   +40 |
+ | Test Execution Time |           4m3s |          3m51s |  -12s |

Code coverage of files in pull request scope (16.3% → 16.9%, patch 100.0%)

Files Coverage +/- Patch Coverage Status
dist/auth-context-DKJ0CX7P.js 0.0% -46.2% - affected
packages/core/dist/app-shell.js 8.7% +0.1% - affected
packages/core/dist/auth-context-h5dden34.js 46.2% +46.2% - affected
packages/core/src/components/activity-card/activity-card.tsx 59.6% 0.0% - modified
packages/core/src/components/dialog/dialog.tsx 97.4% +0.2% 100.0% modified
packages/core/src/components/field/field.tsx 100.0% 0.0% 100.0% modified
packages/core/src/components/fieldset/fieldset.tsx 100.0% 0.0% 100.0% modified
packages/core/src/components/form-layout/form-layout.tsx 100.0% +100.0% 100.0% added
packages/core/src/components/form-layout/index.ts 0.0% 0.0% - added
packages/core/src/components/layout/layout.tsx 100.0% 0.0% 100.0% modified
packages/core/src/components/sheet/sheet.tsx 97.1% 0.0% - modified
packages/core/src/index.ts 0.0% 0.0% - modified

Reported by octocov

@itsprade
itsprade marked this pull request as ready for review November 17, 2026 10:02
itsprade and others added 3 commits November 18, 2026 11:34
# Conflicts:
#	docs-manifest.json
#	docs-src/components/dialog.docs.outline.md
#	docs/components/dialog.md
- ActivityCard's "All activities" list scrolls in `Dialog.Body`. Only the
  body shrinks in the new flex-column `Dialog.Content`, so a plain scroll
  child grew to full height and scrolled the whole dialog, title included.
  Regression test added.
- Changeset and a 1.21.0 migrations entry tell apps that built their own
  flex-column dialog body to use `Dialog.Body`; the changeset also says
  footer buttons now show in source order.
- Dialog test now checks the body scrolls while the header and footer stay
  pinned, instead of a className flex column that no longer behaves so.
- Main's live Dialog form example uses `Dialog.Body`, a footer submit with
  `form`, and `FormLayout`.
- The wizard pattern's steps use `FormLayout` instead of hand-written
  grids, matching the skill rule.
- Demo overview no longer mentions editing in place (that's #709).
- Comment: a card section's grid is 48px narrower than the width its
  thresholds measure.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@IzumiSy

IzumiSy commented Nov 18, 2026

Copy link
Copy Markdown
Contributor

I would prefer to start by extending Grid, since we already have it as a general-purpose layout component, rather than introducing a parallel layout API specifically for forms.

We could then describe how to compose Grid, Card, Fieldset, and the existing form controls in our skills and documentation. That would give consumers and coding agents a clear recommended approach without adding another set of public components. If concrete gaps remain after that, we can consider a form-specific abstraction.

Looking at the implementation, the missing Grid capabilities seem to be:

  1. Container-based responsive columns

    • Change column counts based on the container width, not the viewport.
    • Allow the same layout to reflow correctly inside a page, dialog, or sheet.
  2. A controlled column count at each container size

    • Reflow down to one column, up to a configured maximum.
    • Preserve the configured tracks even when there are fewer children, rather than stretching a short field across the available width.
    • minChildWidth does not currently provide this: it uses auto-fit, overrides columns, and has no maximum column count.
  3. Numeric spans constrained to the available columns

    • For auto-placed items, a requested span of 3 should occupy 1, 2, or 3 columns depending on the current column count.
    • Avoid creating implicit columns when the container becomes narrower.
    • Preserve existing behavior for explicit placement and arbitrary column templates.

These additions would cover FormLayout's core responsive grid behavior. The remaining layout features are largely already available:

  • Field spacing → Grid gapX / gapY.
  • Full-width fields, textareas, or tables → Grid.Item colSpan="full".
  • Other multi-column content → Grid.Item colSpan.
  • Nested field groups → nested Grids.

For the rest, I would start with composition patterns in our skills and examples:

  • Sections → Card + Fieldset + Grid, preserving accessible names and descriptions and extending Fieldset only where needed.
  • Action bars → button layout and optional sticky styling.
  • Field widths → Grid.Item, rather than adding a separate span API to Field and Fieldset.

I would also defer Field.Value, since it is independent of the layout problem.

Could we focus this PR on the reusable Grid improvements and the recommended composition patterns first, then reassess whether a separate FormLayout is necessary?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants