@dataverse-kit/surface-kit 0.4.0 → 0.5.0

package/dist/v9.d.cts

@@ -1,13 +1,23 @@
-import { DialogSizePreset } from './core.cjs';
-export { CALLOUT_DEFAULT_WIDTH, DIALOG_SIZE_PX, MODAL_AUTOSIZE_MIN_WIDTH, PANEL_DEFAULT_WIDTH, PanelKind, calloutFormDefaults, calloutWidthPx, dialogHeightCss, dialogWidthCss, dialogWidthPx, panelCustomWidthPx, panelKindFromWidth } from './core.cjs';
+import { SurfaceLook, DialogSizePreset } from './core.cjs';
+export { CALLOUT_DEFAULT_WIDTH, CE_LABEL_ABOVE_BELOW_ROW_WIDTH, CE_TAB_COLUMN_MIN_WIDTH, DIALOG_SIZE_PX, MODAL_AUTOSIZE_MIN_WIDTH, PANEL_DEFAULT_WIDTH, PanelKind, calloutFormDefaults, calloutWidthPx, dialogHeightCss, dialogWidthCss, dialogWidthPx, normalizeColumnShares, panelCustomWidthPx, panelKindFromWidth, resolveTabColumnWidths } from './core.cjs';
 export { C as ColumnCount, c as clampSpan, g as gridTemplateForColumns } from './columns-BlpFO5VD.cjs';
 import { Breakpoint } from './responsive.cjs';
 export { BREAKPOINTS, CARD_REFLOW_WIDTH, ResponsiveMode, ResponsiveValue, StyleObject, fieldGridStyle, fieldRowStyle, resolveBreakpoint, resolveResponsiveValue, sectionStackingStyle } from './responsive.cjs';
-export { colors, layout, radius, spacing, typography } from '@dataverse-kit/design-tokens';
-import { D as Density } from './useDensity-xEYt-GdJ.cjs';
-export { C as ContainerSize, f as DensityContext, d as densityScale, s as scaleSpacing, b as useContainerBreakpoint, u as useContainerSize, a as useContainerWidth, g as useDensity, e as useMediaQuery, c as useResponsiveValue } from './useDensity-xEYt-GdJ.cjs';
-import React__default, { ReactElement, CSSProperties, ReactNode, RefObject } from 'react';
-import { BrandVariants, Theme } from '@fluentui/react-components';
+export { ceForm, colors, layout, radius, spacing, typography } from '@dataverse-kit/design-tokens';
+import { D as Density } from './useDensity-CLglP89q.cjs';
+export { C as ContainerSize, a as DensityContext, d as densityScale, s as scaleSpacing, u as useContainerBreakpoint, b as useContainerSize, c as useContainerWidth, e as useDensity, f as useMediaQuery, g as useResponsiveValue } from './useDensity-CLglP89q.cjs';
+import * as React from 'react';
+import React__default, { ReactElement, RefObject, ReactNode, CSSProperties } from 'react';
+export { createDynamicsCeTheme, createDynamicsV9DarkTheme, createDynamicsV9Theme, dynamicsBrandRamp, dynamicsCeTheme, dynamicsV9DarkTheme, dynamicsV9Theme } from '@dataverse-kit/fluent-theme';
+
+/**
+ * Form-level appearance: `'default'` (the kit's existing look) or `'ce'` (the measured Dynamics CE
+ * model-driven form). `FormSurface` provides it and layouts read it, the same way `DensityContext`
+ * cascades density, so a single `look` on the form reaches every row and column.
+ */
+declare const LookContext: React.Context<SurfaceLook>;
+/** Read the ambient surface look (defaults to `'default'` outside a provider). */
+declare const useLook: () => SurfaceLook;
 
 type SurfaceVariant = 'card' | 'flat' | 'placeholder';
 type Alignment = 'left' | 'center' | 'right';
@@ -21,6 +31,14 @@ interface SurfaceToolbarItem {
     appearance?: 'primary' | 'subtle';
     disabled?: boolean;
     onClick?: () => void;
+    /**
+     * A dropdown. Without `split` the whole button opens the menu (Dynamics "Process ▾") and
+     * `onClick` is ignored; with `split` the main part runs `onClick` and a separate chevron opens
+     * the menu ("Connect | ▾") — in both looks; only `look="ce"` applies the measured split geometry.
+     * Menu entries' own `menuItems`/`split` are not rendered (one level only).
+     */
+    menuItems?: SurfaceToolbarItem[];
+    split?: boolean;
 }
 /** An action button in a v9 `ActionBar` / dialog footer. */
 interface SurfaceActionButton {
@@ -39,11 +57,11 @@ interface SurfaceActionButton {
 type SurfacePosition = 'above' | 'below' | 'before' | 'after';
 type SurfaceAlign = 'start' | 'center' | 'end';
 interface FormSurfaceProps {
-    /** Outer grid column count. Default 12. */
+    /** Outer grid column count. Default 12. Ignored under `look="ce"` (see `look`). */
     columns?: number;
-    /** Grid gap in px. Default 20. */
+    /** Grid gap in px. Default 20. Ignored under `look="ce"`. */
     gap?: number;
-    /** Padding in px. Default 20. */
+    /** Padding in px. Default 20; default 0 under `look="ce"`. */
     padding?: number;
     /** Spacing density: `'compact'` scales gap + padding by 0.75 and cascades to child
      *  Sections via context. Default `'comfortable'` (byte-identical to no density). */
@@ -52,6 +70,19 @@ interface FormSurfaceProps {
     background?: string;
     /** Container width hint (e.g. a PCF `context.allocatedWidth`) — drives stacking off the container, not the viewport. */
     containerWidth?: number;
+    /**
+     * Appearance family, cascaded to layouts via context: `'default'` (the kit's existing look) or
+     * `'ce'` (the MEASURED Dynamics CE model-driven form: 184px label column, 48px field rows,
+     * 340px tab-column floor…). Pair `'ce'` with `dynamicsCeTheme` on the `FluentProvider`.
+     * Default `'default'` (renders exactly as before).
+     *
+     * ★ Under `'ce'` the surface is a plain BLOCK, not the 12-column grid: a Dynamics form is page
+     *   chrome stacked top to bottom (command bar, header card, tab body), and its columns belong to
+     *   `TabColumns`. So `columns`/`gap`/`collapseBelow` are ignored, padding defaults to 0, and its
+     *   children fill the width with no `minWidth: 0` wrapper — `<FormSurface look="ce">` is all a
+     *   page needs.
+     */
+    look?: SurfaceLook;
     /** Collapse children to full width below this breakpoint. Default `'sm'`. */
     collapseBelow?: Breakpoint;
     maxWidth?: number | string;
@@ -69,7 +100,12 @@ interface SectionProps {
     columnSpan?: number;
     columnStart?: number;
     rowPosition?: number;
-    /** Internal field-grid column count. Default 12. */
+    /**
+     * Internal column count. Default look: the field grid's column count, default 12 (children are
+     * grid cells). Under `look="ce"`: the section's formxml column count, default 1; with more than
+     * one, pass ONE CHILD PER COLUMN, each holding that column's FieldRows (a dev warning fires
+     * otherwise).
+     */
     internalColumns?: number;
     /** Show a v9 `<Toolbar>` of `commandItems` in the section header. */
     showCommandBar?: boolean;
@@ -87,8 +123,21 @@ interface SectionProps {
     /** Min height for the `placeholder` variant. */
     minHeight?: number;
     /** Spacing density override; defaults to the ambient `FormSurface` density (`useDensity`).
-     *  `'compact'` scales the card padding + internal field gap by 0.75. */
+     *  `'compact'` scales the card padding + internal field gap by 0.75. Ignored under `look="ce"`,
+     *  whose spacing is measured. */
     density?: Density;
+    /**
+     * Appearance family; defaults to the ambient `FormSurface` look. Under `'ce'` the `card` variant
+     * is the MEASURED Dynamics section: shadow4 card, 8px radius, padding 4/16/16/16, the title as
+     * given (14/600/20, 4px top pad, no rule, not uppercased), and a gap-free body that pulls rows up
+     * by `ceFieldRowFirstOffset`. Children are the section's `FieldRow`s; with `internalColumns > 1`
+     * pass ONE CHILD PER COLUMN (Dynamics' section → columns → rows): columns are equal, with a 21px
+     * gutter on every column but the last. `internalColumns` defaults to 1 under `'ce'`.
+     * The collapse chevron and header commands still render under `'ce'`, but their CE geometry
+     * is unmeasured, as is multi-column reflow: below the phone breakpoint CE columns stack
+     * (provisional). Only the `card` variant has a CE form; `flat` and `placeholder` keep their chrome.
+     */
+    look?: SurfaceLook;
     className?: string;
     style?: CSSProperties;
     children?: ReactNode;
@@ -108,6 +157,8 @@ interface SectionHeaderProps {
     collapsible?: boolean;
     collapsed?: boolean;
     onToggle?: () => void;
+    /** Appearance family; defaults to the ambient `FormSurface` look. `'ce'` draws the measured Dynamics section title (no rule, no 48px bar). */
+    look?: SurfaceLook;
 }
 interface FormHeaderProps {
     title?: ReactNode;
@@ -120,6 +171,65 @@ interface FormHeaderProps {
     /** Right side of the header (e.g. KPI header fields). */
     actions?: ReactNode;
     className?: string;
+    /**
+     * Appearance family; defaults to the ambient `FormSurface` look. Under `'ce'` this is the
+     * MEASURED Dynamics record header region (padding 14/20/0/20): a 40px initials avatar in a 2px
+     * ring (Fluent `colorful`, hashed from `title` — which reproduces Dynamics' colour), the title at
+     * 20/600/28 followed by `- {status}`, an `entityName · form switcher` row, value-over-label
+     * `headerFields` separated by 1×38 dividers, the `owner` persona, and an expand chevron.
+     * Render it as `PivotSurface look="ce"`'s `header` to get the header card with the tab strip.
+     */
+    look?: SurfaceLook;
+    /** ce: the entity display name before the form switcher (e.g. `"Account"`). Falls back to `subtitle`. */
+    entityName?: ReactNode;
+    /** ce: the forms offered by the switcher. With fewer than two, the active form's name renders as text. */
+    forms?: SurfaceFormOption[];
+    activeFormId?: string;
+    onFormChange?: (formId: string) => void;
+    /** ce: value-over-label header fields (e.g. Annual Revenue). An empty value renders `---`. */
+    headerFields?: SurfaceHeaderField[];
+    /** ce: the owner persona at the end of the header fields. */
+    owner?: SurfaceHeaderOwner;
+    /** ce: shows the expand chevron; called when it is clicked. */
+    onExpand?: () => void;
+    expanded?: boolean;
+    /**
+     * ce: the element the title renders as. Default `'h1'` — right for a full-page record, as in
+     * Dynamics; pass `'h2'` (etc.) when the header sits inside a dialog, panel or an app shell that
+     * already has its own `h1`.
+     */
+    titleAs?: 'h1' | 'h2' | 'h3' | 'h4' | 'span';
+}
+/** A form offered by the record header's form switcher. */
+interface SurfaceFormOption {
+    id: string;
+    label: string;
+}
+/** A value-over-label field in the record header. */
+interface SurfaceHeaderField {
+    id?: string;
+    label: string;
+    /** Empty (`null`/`undefined`/`''`) renders Dynamics' `---`. */
+    value?: ReactNode;
+}
+/** The owner persona in the record header. */
+interface SurfaceHeaderOwner {
+    name: string;
+    /** Caption under the name. Default `"Owner"`. */
+    label?: string;
+    /**
+     * The avatar. Default: a 32px Fluent `Avatar` with `color="colorful"` (and a presence badge when
+     * `presence` is set). ★ Dynamics' owner colour does NOT follow Fluent's hash (measured: "System Administrator"
+     * renders solid red #d13438; Fluent's hash gives grape), and its rule is unmeasured — pass an
+     * avatar to match a specific org.
+     */
+    avatar?: ReactNode;
+    /**
+     * Presence shown on the DEFAULT avatar (ignored when `avatar` is given). No badge unless set:
+     * a badge is announced to screen readers, so it must reflect real presence.
+     */
+    presence?: 'available' | 'away' | 'busy' | 'do-not-disturb' | 'offline' | 'out-of-office' | 'blocked' | 'unknown';
+    onClick?: () => void;
 }
 interface SurfaceTab {
     id: string;
@@ -139,8 +249,32 @@ interface PivotSurfaceProps {
     /** v9 `TabList` size. Default `'medium'`. */
     size?: 'small' | 'medium' | 'large';
     className?: string;
+    /**
+     * Appearance family. OPT-IN: unlike most surfaces this does NOT follow the ambient `FormSurface`
+     * look (it is page-level chrome; a pivot nested in a ce Section stays plain). Under `'ce'` it
+     * ignores `appearance`/`size` and renders the MEASURED Dynamics header card — `header` (e.g. a `FormHeader`) above a tab strip (45px tabs,
+     * 16/28 text, 20px gaps, a 3px brand underline) — then the selected tab's content BELOW the
+     * card, in the tab body (16px top, 21px bottom), with the page's 8px left / 20px right insets.
+     */
+    look?: SurfaceLook;
+    /** Rendered above the tab strip — inside the header card under `'ce'`. Icon tabs are unmeasured under `'ce'`. */
+    header?: ReactNode;
 }
 interface CommandSurfaceProps {
+    /**
+     * Appearance family. OPT-IN (does not follow the ambient `FormSurface` look): under `'ce'` this is
+     * page chrome — the MEASURED Dynamics command bar card (1474×46 at 1710px; shadow4, 8px radius), 8px below the page top and
+     * 16px above the header card, with the page insets (16 left / 20 right): optional back and pop-out
+     * buttons each followed by a divider, then abutting 32px commands (16px icon, 7px gap, 14px REGULAR
+     * label), menu (▾) and split commands, the ⋮ overflow, and `farItems` as outlined 24px buttons
+     * (Share). Pass 16px Fluent icons (`*16Regular`) for commands and 20px (`*20Regular`) for farItems. Commands are NOT folded into ⋮ automatically
+     * (Dynamics does, by an unmeasured rule): pass `overflowItems` explicitly.
+     */
+    look?: SurfaceLook;
+    /** ce: shows the back button (before the first divider). */
+    onBack?: () => void;
+    /** ce: shows the "open in new window" button (before the second divider). */
+    onPopOut?: () => void;
     items: SurfaceToolbarItem[];
     /** Rendered behind a "more" overflow menu after the primary items. */
     overflowItems?: SurfaceToolbarItem[];
@@ -244,18 +378,62 @@ interface TooltipSurfaceProps {
     relationship?: 'label' | 'description';
     children: ReactElement;
 }
-
-declare const dynamicsBrandRamp: BrandVariants;
-/**
- * Build a Fluent v9 `Theme` for the Dynamics surfaces. Defaults to the Dynamics-blue
- * brand ramp; pass a custom `BrandVariants` (e.g. from your org's brand) to override.
- * Wrap the app (or a `./v9` surface subtree) in `<FluentProvider theme={createDynamicsV9Theme()}>`.
- */
-declare function createDynamicsV9Theme(brand?: BrandVariants): Theme;
-/** Dark-mode variant of the Dynamics v9 theme (same brand ramp). */
-declare function createDynamicsV9DarkTheme(brand?: BrandVariants): Theme;
-/** The default light Dynamics v9 theme (memoized module singleton). */
-declare const dynamicsV9Theme: Theme;
+/** Where a field's label sits relative to its control. */
+type FieldLabelPosition = 'beside' | 'above' | 'auto';
+interface FieldRowProps {
+    /**
+     * The field label. Omit for a label-less control: the control then sits where a beside control
+     * would, full width. (Dynamics' own label-less controls, such as the timeline, use different,
+     * control-specific padding that is not modelled here.)
+     */
+    label?: ReactNode;
+    /** Draws the required marker (`*`) after the label. */
+    required?: boolean;
+    /** Associates the label with the control (`<label htmlFor>`); pass the control's id. */
+    htmlFor?: string;
+    /**
+     * `'beside'` (formxml `Left`), `'above'` (formxml `Top`), or `'auto'`: beside while the row is
+     * wide enough, above when it is narrow, as Dynamics does (see CE_LABEL_ABOVE_BELOW_ROW_WIDTH —
+     * the switch point is provisional). An `'auto'` row is a CSS size container, so it needs a
+     * parent of definite width (not a shrink-to-fit popover or `auto` grid track).
+     * Default `'auto'` under the `ce` look, `'beside'` otherwise. Under the default look `'auto'`
+     * behaves as `'beside'` (with the phone stack at 480px).
+     */
+    labelPosition?: FieldLabelPosition;
+    /** Override the label column width (px or CSS length). Default: 184 under `ce`, 130 otherwise. */
+    labelWidth?: number | string;
+    /** Override the ambient look for this row. */
+    look?: SurfaceLook;
+    className?: string;
+    style?: CSSProperties;
+    /**
+     * ★ Rows span every column of a grid parent. Under `ce`, every row pads 12px on top; the section
+     *   body pulls up by `ceFieldRowFirstOffset` so the first row sits at Dynamics' 8px —
+     *   `Section look="ce"` does this for you.
+     *
+     * The control. Under the `ce` look use stock Fluent v9 controls with `appearance="filled-darker"`
+     * (the measured field: #f5f5f5 fill, transparent border, 32px) and `placeholder="---"` for the
+     * empty state, as Dynamics shows.
+     */
+    children?: ReactNode;
+}
+interface TabColumnsProps {
+    /**
+     * Declared column shares, as in the formxml tab `<column width="33%">`, e.g. `[33, 42, 25]`.
+     * One entry per child column. Default: equal shares.
+     */
+    widths?: readonly number[];
+    /** Minimum rendered column width in px. Default 340 under `ce` (measured), 300 otherwise. */
+    minColumnWidth?: number;
+    /** Gap between columns, and between sections stacked in a column, in px. Default 16 under `ce`, 20 otherwise. */
+    gap?: number;
+    /** Override the ambient look. */
+    look?: SurfaceLook;
+    className?: string;
+    style?: CSSProperties;
+    /** One child per column; each child's own children are the column's stacked sections. */
+    children?: ReactNode;
+}
 
 /** The N-column form canvas that hosts Sections (Fluent UI v9). */
 declare const FormSurface: React__default.FC<FormSurfaceProps>;
@@ -276,6 +454,7 @@ declare const SectionCard: React__default.FC<SectionCardProps>;
 /** Section header bar (Fluent v9): title + status (left), toolbar / actions (right), optional collapse toggle. */
 declare const SectionHeader: React__default.FC<SectionHeaderProps>;
 
+declare const cePresenceBadgeStyle: Readonly<React__default.CSSProperties>;
 /** Dynamics form header (Fluent v9): persona + title/status (left), KPI/header fields (right). */
 declare const FormHeader: React__default.FC<FormHeaderProps>;
 
@@ -291,6 +470,18 @@ declare const ActionBar: React__default.FC<ActionBarProps>;
 /** A sticky footer region (free-form children, Fluent v9) — e.g. for dialog/panel actions. */
 declare const Footer: React__default.FC<FooterProps>;
 
+/**
+ * How far a section body must pull its rows up so the first `FieldRow` pads 8px, as Dynamics'
+ * first row does, while every row itself pads 12px. `Section look="ce"` applies it; a hand-built
+ * body applies `marginTop: -ceFieldRowFirstOffset`.
+ */
+declare const ceFieldRowFirstOffset: number;
+/** A "Label : control" field row (Fluent UI v9). The control goes in `children`. */
+declare const FieldRow: React__default.FC<FieldRowProps>;
+
+/** Tab-body columns with declared shares and a width floor (Fluent UI v9). One child per column. */
+declare const TabColumns: React__default.FC<TabColumnsProps>;
+
 /**
  * Full Dynamics form-dialog (Fluent v9 `Dialog`). Default width 1200 (lg), height 95vh.
  * `onDismiss` is the close affordance — when omitted, no close button renders. `isBlocking`
@@ -310,4 +501,4 @@ declare const CalloutSurface: React__default.FC<CalloutSurfaceProps>;
 /** A tooltip wrapper (Fluent v9 `Tooltip`). */
 declare const TooltipSurface: React__default.FC<TooltipSurfaceProps>;
 
-export { ActionBar, type ActionBarProps, type Alignment, Breakpoint, CalloutSurface, type CalloutSurfaceProps, CommandSurface, type CommandSurfaceProps, Density, DialogSizePreset, Footer, type FooterProps, FormDialogSurface, type FormDialogSurfaceProps, FormHeader, type FormHeaderProps, FormSurface, type FormSurfaceProps, ModalSurface, type ModalSurfaceProps, PageSurface, type PageSurfaceProps, PanelSurface, type PanelSurfaceProps, PivotSurface, type PivotSurfaceProps, Section, SectionCard, type SectionCardProps, SectionHeader, type SectionHeaderProps, type SectionProps, type SurfaceActionButton, type SurfaceAlign, type SurfacePosition, type SurfaceTab, type SurfaceToolbarItem, type SurfaceVariant, TooltipSurface, type TooltipSurfaceProps, createDynamicsV9DarkTheme, createDynamicsV9Theme, dynamicsBrandRamp, dynamicsV9Theme };
+export { ActionBar, type ActionBarProps, type Alignment, Breakpoint, CalloutSurface, type CalloutSurfaceProps, CommandSurface, type CommandSurfaceProps, Density, DialogSizePreset, type FieldLabelPosition, FieldRow, type FieldRowProps, Footer, type FooterProps, FormDialogSurface, type FormDialogSurfaceProps, FormHeader, type FormHeaderProps, FormSurface, type FormSurfaceProps, LookContext, ModalSurface, type ModalSurfaceProps, PageSurface, type PageSurfaceProps, PanelSurface, type PanelSurfaceProps, PivotSurface, type PivotSurfaceProps, Section, SectionCard, type SectionCardProps, SectionHeader, type SectionHeaderProps, type SectionProps, type SurfaceActionButton, type SurfaceAlign, type SurfaceFormOption, type SurfaceHeaderField, type SurfaceHeaderOwner, SurfaceLook, type SurfacePosition, type SurfaceTab, type SurfaceToolbarItem, type SurfaceVariant, TabColumns, type TabColumnsProps, TooltipSurface, type TooltipSurfaceProps, ceFieldRowFirstOffset, cePresenceBadgeStyle, useLook };