@dataverse-kit/surface-kit

Responsive form shells, containers, sections, and overlay surfaces for Dynamics 365, built on Fluent UI v8 to match Dynamics CE.

What it does

surface-kit is the shared surface/layout layer for Dynamics 365 React apps. It provides the form canvas (FormSurface), positioned card sections (Section, SectionCard), responsive layouts (ColumnLayout, TwoColumnLayout, FieldRow), chrome (FormHeader, CommandSurface, ActionBar, PivotSurface, Footer), and overlay surfaces (FormDialogSurface, ModalSurface, PanelSurface, CalloutSurface, TooltipSurface) — all styled to match Dynamics CE and to host grid-kit grids. Every responsive stacking decision flows through shared breakpoints, so viewport (@media) and container (PCF allocatedWidth) layouts behave identically. The ./core (pure sizing scalars) and ./responsive (pure breakpoint/style builders) subpaths are framework-agnostic — no React or Fluent — and are inlined by the export-engine codegen at zero React cost.

When to use it

Reach for surface-kit when you need the form shell — the page canvas, sections, tabs, command bars, and dialog/panel/modal/callout overlays that wrap your content. For the data grids that sit inside those sections, use @dataverse-kit/grid-kit instead (surface-kit containers just render children; you pass the grid in). For one-off custom-page business controls, use reusable-components. surface-kit is the responsive, Dynamics-CE-matching chrome around everything else.

Install

npm install @dataverse-kit/surface-kit

Requires React 18 and Fluent UI v8 as peer dependencies: react, react-dom, and @fluentui/react (^8.115.6).

Minimal example

import { FormSurface, Section, TwoColumnLayout } from '@dataverse-kit/surface-kit';
import { TextField } from '@fluentui/react';

export function AccountForm() {
  return (
    <FormSurface columns={12} maxWidth={1200}>
      <Section title="Account Information" columnSpan={12} collapsible>
        <TwoColumnLayout>
          <TextField label="Account Name" />
          <TextField label="Phone" />
        </TwoColumnLayout>
      </Section>

      <Section title="Address" columnSpan={6} variant="flat">
        <TextField label="City" />
      </Section>
    </FormSurface>
  );
}

Key exports

| Export | Purpose | |--------|---------| | FormSurface | The N-column form canvas that hosts Sections; stacks to one column below a breakpoint (viewport or PCF container width). | | Section / SectionCard | Dynamics-CE form section — a grid-positioned card with header, optional command bar, and an internal field grid; supports card/flat/placeholder variants and collapse. | | TwoColumnLayout / ColumnLayout / FieldRow | Responsive field layouts that collapse to a single column below collapseBelow. | | FormDialogSurface / ModalSurface / PanelSurface / CalloutSurface / TooltipSurface | Fluent v8 overlay surfaces sized to match the Dynamics CE / codegen presets. | | FormHeader / CommandSurface / ActionBar / PivotSurface / Footer | Form chrome — header, command bars, tabs, and footer. | | MasterDetailSurface / DashboardSurface | Composite multi-pane surfaces. | | fromFormDefinition | Adapter that builds a surface tree from a (duck-typed) form definition. | | createDynamicsTheme | Canonical Dynamics token theme factory. | | ./core, ./responsive (subpaths) | Pure-TS sizing scalars and breakpoint/style builders — framework-agnostic, shared with the export-engine codegen. |

See CLAUDE.md for the full architecture / contributor reference.