Saleor Dashboard Entity Detail

Entity detail update language

Conventions for models you work with daily — edit surfaces under src/<feature>/ that use DetailPageLayout. Canonical reference: channel details (src/channels/pages/ChannelDetailsPage/).

Not this skill: Configuration hubs under Configuration → use Settings* in src/components/Settings/ (SettingsSection, SettingsHubLayout). Same row idea, different surface — do not put entity detail UI in src/components/Settings/.

Also see: saleor-dashboard-detail-pages (metadata modal, TopNav wiring), saleor-dashboard-styles (tokens, DetailGroupBox), saleor-dashboard-microcopy (hint copy), saleor-dashboard-feedback (toasts vs inline/banner errors), saleor-dashboard-loading (skeletons, page gates, no fake defaults), saleor-dashboard-datagrid (product lists on detail pages).

External reference — Vercel design resources

Vercel splits product UI from editorial/report surfaces. Saleor Dashboard is product UI (macaw-ui-next), but several hubs are worth bookmarking:

Principles that reinforce our entity-detail rules (from Vercel’s report skill and Geist):

• Earn a surface — card/border only when selection, grouping, or empty state needs it; else DetailSection + gap.
• No card nesting — fields and toggle rows live inside one card, not a card per field.
• Typography before chrome — hierarchy via size/weight/color before adding tinted bands.
• Restraint test — if a border, pill, or extra section can be removed without losing meaning, remove it.

Do not port Vercel report layouts (masthead, vbg-* primitives, contrast bands) into Dashboard detail pages — different reader and density.

Page anatomy

DetailPageLayout
├── TopNav — title (+ status pill/meta when relevant) | Metadata | Translations | Menu
├── Content
│   ├── SetupChecklist (optional — guided setup only when entity has readiness funnel)
│   └── [ DetailSectionNav | sections ] — nav only when 4+ scroll sections
│         Use `DetailPageSectionLayout` (nav rail `25%` / `min 10rem` + main `gap={4}`)
│         1. DetailSettingsCard — general / identity / media
│         2. Primary entity content — products, rates, lists, …
│         3. SEO — last in the main column (default)
├── RightSidebar — operational membership / availability (not empty status cards)
└── Savebar (+ SavebarCompositionHint when Save bundles multiple areas)

Main column order (default): identity/settings → primary content (lists, products, rates) → SEO last.
Sidebar = things you assign or toggle per-channel (warehouses, shipping zones, channel visibility). Category children use CategoryListDatagrid in the right sidebar (tree expand, selection, bulk delete) — not custom link rows. Status that is not Save-gated lives in the header, not a hollow sidebar card.

Two surfaces — naming families

Detail* components (entity detail)

Until extraction lands during Phase B, keep legacy DashboardCard for shipping-style hints — do not use SettingsSection on entity detail.

DetailPageSectionLayout + DetailSectionNav

Path: src/components/DetailPageSectionLayout/DetailPageSectionLayout.tsx · nav primitive: src/components/DetailSectionNav/.

Canonical reference: ChannelDetailsPage (first consumer).

Use when the main column has 4+ scroll targets and needs a sticky left rail. Constants: DETAIL_PAGE_SECTION_NAV_WIDTH (25%), DETAIL_PAGE_SECTION_NAV_MIN_WIDTH (10rem). Nav is hidden on mobile (display: none below tablet).

import { DetailPageSectionLayout } from "@dashboard/components/DetailPageSectionLayout/DetailPageSectionLayout";
import { ChannelSectionNav } from "@dashboard/channels/components/ChannelSectionNav/ChannelSectionNav";

<DetailPageLayout.Content>
  <DetailPageSectionLayout
    nav={<ChannelSectionNav items={items} activeId={activeId} />}
  >
    <ChannelSection id={...}>...</ChannelSection>
  </DetailPageSectionLayout>
</DetailPageLayout.Content>

Phase B workflow: improve a pilot view (collections) in slices; extract Detail* when the slice needs it; rewire channels in the same PR. See plan: dogfood-driven extraction, not library-first.

DetailSettingToggleRow (boolean settings)

Path: src/components/DetailSettingToggleRow/DetailSettingToggleRow.tsx. Storybook: Components / DetailSettingToggleRow.

Canonical references: Channel Orders (ChannelOrdersSection — allow unpaid, expire orders) · Gift card Details expiry.

Use for on/off settings inside a primary DetailSettingsCard — not for membership assigns (sidebar) and not for free-form fields alone.

<DetailSettingsCard title="Details" contentFlush>
  <Box className={styles.paddedFields}>{/* tags, etc. */}</Box>
  <DetailSettingToggleRow
    title={<FormattedMessage {...messages.expiryTitle} />}
    description={<FormattedMessage {...messages.expiryDescription} />}
    pressed={expires}
   
  >
    {expires ? (
      <DetailSettingNestedField>
        <Input type="date" name="expiryDate" value={expiryDate} />
      </DetailSettingNestedField>
    ) : null}
  </DetailSettingToggleRow>
</DetailSettingsCard>

Anti-patterns: Checkbox + separate label instead of this row; toggle inside a nested card; putting toggles in a padded (non-flush) card body so borders look inset/double-padded.

Channel code may still import ChannelSettingToggleRow — that file re-exports DetailSettingToggleRow. Prefer the Detail* import in new code.

Settings card headers — primary vs secondary

Two header patterns; both use a bordered card surface but different chrome.

Primary = settings you edit in place. Secondary = assign/remove membership with count in the header.

headerEnd on primary cards: the card coerces macaw Button / ButtonGroupWithDropdown to size="small" so title-only and title+action headers share height. Right inset matches the Y gap (spacing-4). Callers pass the action — do not set size on headerEnd buttons. Same for ChannelAvailabilityCard Manage in the sidebar toolbar (set small there until that primitive coerces too).

DetailSettingsCard API (primary settings card)

Path: src/components/DetailSettingsCard/DetailSettingsCard.tsx. Storybook: Components / DetailSettingsCard.

Title typography is owned by the card. Pass plain copy / FormattedMessage / DetailSettingsCardTitle — do not wrap the title in your own Text/h2. DetailSettingsCardTitle only adds optional-mark layout.

<DetailSettingsCard
  title={<DetailSettingsCardTitle optional>Background image</DetailSettingsCardTitle>}
  headerEnd={<Button variant="secondary">Upload image</Button>}
  intro={
    <Text size={3} color="default2">
      …
    </Text>
  }
>
  {fields}
</DetailSettingsCard>

Fixed-at-creation fields

Values the API will not let you change after create (channel currency, attribute input type, attribute entity on references).

Use FixedAtCreationField (src/components/FixedAtCreationField/FixedAtCreationField.tsx). Canonical look: channel currency on edit.

<FixedAtCreationField
  data-test-id="channel-currency-locked-input"
  label={intl.formatMessage(messages.channelCurrency)}
  name="currencyCode"
  value={data.currencyCode}
  helperText={intl.formatMessage(messages.channelCurrencyHintLocked)}
/>

Copy examples:

• Currency: “Fixed at creation. To sell in another currency, create a second channel.”
• Attribute type: “Fixed at creation. To use a different type, create a new attribute.”

Do not grey out a Combobox and leave the chevron. That is the mistake this pattern replaces.

In-card assignable lists (AssignableList*)

Path: src/components/AssignableListTable/. Canonical references: collection products, attribute values, product-type attributes, voucher codes.

Do not copy CollectionProducts CSS, header height, search padding, or pagination chrome into a feature. Compose:

<AssignableListCard
  title="…"
  headerEnd={<Button variant="secondary">Assign …</Button>}
  search={<SearchInput … />}           // optional — padding owned by the card
  footer={
    <AssignableListPagination          // top border owned by pagination
      inset="drag"                     // card | nested | drag
      numberOfRows={…}
     
    />
  }
>
  <AssignableListTable density="compact" … />
  {/* MUI drag tables: ResponsiveTable + tableStyles.assignableTable */}
</AssignableListCard>

Tokens live in assignableListTableLayout.ts. MUI tables that still need dnd-kit (SortableTable) use tableStyles.assignableTable so the compact heading and density match GridTable.

Anti-patterns: per-view .listHeader { height: 40px }; wrapping pagination in a second top-border box; putting bulk delete in headerEnd; size="medium" assign buttons in the card header; 50px rows on text-only lists; copying CollectionProducts/Pagination.

When to use a card vs open section

Not everything on entity detail needs a card wrapper. Vercel’s Geist Card describes a card as a surface that groups related content and actions; community Geist patterns add: don’t nest cards, don’t use cards purely for layout. Vercel’s marketing layouts lean on section spacing rather than boxing every block — applicable to dashboards as “don’t card by default.”

Use a bordered card when the block is:

• A section-nav scroll target with its own title and fields (DetailSettingsCard)
• Sidebar ops — assign lists, channel availability, widgets (AssignListCard, ChannelAvailabilityCard, …)
• Self-contained + can be empty — needs empty state frame (no warehouses, no gateways)
• Visually separable from neighbors — different action model (assign vs edit fields)

Skip the card wrapper when:

• Content is the main body of a section and section nav + heading already provide the map (e.g. products datagrid — card chrome is optional)
• Fields are continuation of the same settings group inside an existing card (toggle rows, nested DetailGroupBox rows)
• Layout only — spacing between DetailSection blocks is enough; wrapping would nest surfaces without new semantics
• Single short group on a page without section nav — one DetailSettingsCard may be enough; don’t add outer card

Anti-patterns (aligned with Vercel): card inside card; card around every field group “for consistency”; card when only purpose is padding.

Channel availability (sidebar + main column)

Three established patterns — pick by depth of per-channel config, not by entity type alone.

Adjustments when rolling out:

• Align chrome (title, “In X of Y”, Manage placement) across tiers even if internals differ.
• Prefer ChannelAvailabilityCard list variant over legacy wrapper when you need honest readiness (missing price, draft channel) banners.
• Collections sidebar: legacy ChannelsAvailabilityCard is still correct ops placement; migrate to list variant only if you need status banners or search at scale.
• Product variant channels (VariantDetailsChannelsAvailabilityCardContainer) still uses old accordion-in-DashboardCard — converge on ChannelAvailabilityCard when touched.

Foldable blocks (DetailGroupBox vs accordion cards)

SEO on entity detail:

• Placement (default across the dashboard): SEO is always last in the main-column stack — after general/settings and after primary content (products, rates, lists). Create flows follow the same order when they include SEO. Exception only when explicitly decided for a specific entity (document why in the PR / skill example).
• Chrome: default SeoForm secondary + columnInset={false} inside DetailPageContent (collections / categories).
• With DetailSectionNav + SEO as its own scroll target → DetailSettingsCard + SeoForm unwrapped is allowed; SEO section still sorts last in the nav/map.
• Do not nest DetailGroupBox for SEO when section nav exists — double collapse hides optional fields unnecessarily.
• Carry Complete / Incomplete in the SEO surface (intro or foldable trigger), not above primary content.
• Use foldable DetailGroupBox SEO only on short pages without section nav where collapse saves space — still keep it last in the stack.
• Gift card Timeline is an open (non-carded) section — title + timeline only, last in the main column. Do not wrap in DetailSettingsCard / DetailGroupBox.

DetailGroupBox ≠ ChannelAvailabilityItem accordion: group box is for entity rows in a list; channel item is for homogeneous channel rows with shared status model.

When DashboardCard still fits

Shipping-style entity cards with DashboardCard.Subtitle + MicrocopyLink — hints above fields, not toggle/radio setting rows. Example: shipping zone settings sections.

Principles (apply on every entity detail refresh)

1. Create light, configure in place — minimal create modal; detail is the setup home when funnel exists.
2. Required vs worth-reviewing — checklist blockers ≠ optional review rows (tax, catalog).
3. Settings as a map — section cards; sticky DetailSectionNav when long; not one flat form.
4. Sidebar = ops — assign/availability; no empty bordered status-only sidebar.
5. Stage membership until Save — assign dialogs → form state; create-missing-entity may persist immediately (channel pattern).
6. Header owns lifecycle status — pill in title; activate/deactivate confirmed in header, not Save.
7. Metadata in header modal on edit views — never inline <Metadata> on update.
8. Modals for create/assign/wizard — page for ongoing config.
9. Honest readiness — don’t claim catalog/setup complete without data.
10. Recoverable setup — if checklist dismissible, offer reopen from TopNav menu.
11. SEO last in the main column — after identity/settings and primary content; exception only when explicitly decided for that entity.
12. Primitives own heading typography — DetailSettingsCard / AssignListCard / Title2 set size, weight, and heading level. Callers pass copy only (string / FormattedMessage / thin wrappers like DetailSettingsCardTitle). Never rely on bare browser <h2> styles.
13. Channel references use ChannelDisplay / ChannelDetailsLink — globe icon + normal text color; never a bare blue link for a channel name. Other in-card links prefer Link color="secondary" with hover underline. See saleor-dashboard-styles → Interactive affordances.
14. Create-time identity uses FixedAtCreationField — disabled Input + lock + “Fixed at creation. To {goal}, {alternative}.” Never a disabled Combobox/Select.

Not every entity needs all of these. Collections don’t need a setup checklist; channels do.

Entity detail refactor checklist

Work top-down. Skip steps that don’t apply.

• Shell — DetailPageLayout + Savebar; actionsGap={3} on TopNav when multiple actions
• TopNav — TopNav.MetadataButton (edit); TopNav.Menu for extensions + delete; back via href (no subtitleTop parent eyebrows yet). Destination hrefIcon must match the entity family (TopNavDestinationIcon.categories / .collections / .products — not the catalog parent for siblings).

TopNav.Menu (cogs menu)

Canonical reference: src/channels/pages/ChannelDetailsPage/ChannelDetailsPage.tsx (menuItems useMemo).

Savebar on entity detail: Spacer + composition hint (optional) + Cancel +

…(truncated)