@dataverse-kit/surface-kit 0.1.0 → 0.2.0

package/README.md

@@ -0,0 +1,59 @@
+# @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
+
+```bash
+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
+
+```tsx
+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`](./CLAUDE.md) for the full architecture / contributor reference.