@dataverse-kit/surface-kit 0.1.0 → 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 khester
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

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.