@dataverse-kit/surface-kit 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,445 @@
+import { DialogSizePreset } from './core.js';
+export { CALLOUT_DEFAULT_WIDTH, DIALOG_SIZE_PX, MODAL_AUTOSIZE_MIN_WIDTH, PANEL_DEFAULT_WIDTH, PanelKind, calloutFormDefaults, calloutWidthPx, dialogHeightCss, dialogWidthCss, dialogWidthPx, panelCustomWidthPx, panelKindFromWidth } from './core.js';
+import { C as ColumnCount } from './columns-BlpFO5VD.js';
+export { c as clampSpan, g as gridTemplateForColumns } from './columns-BlpFO5VD.js';
+import { Breakpoint, ResponsiveValue } from './responsive.js';
+export { BREAKPOINTS, CARD_REFLOW_WIDTH, ResponsiveMode, StyleObject, fieldGridStyle, fieldRowStyle, resolveBreakpoint, resolveResponsiveValue, sectionStackingStyle } from './responsive.js';
+import { Theme, ICommandBarItemProps } from '@fluentui/react';
+import * as React from 'react';
+import React__default, { CSSProperties, ReactNode, RefObject, ReactElement } from 'react';
+
+declare const colors: {
+    readonly brand: "#0078d4";
+    readonly brandHover: "#106ebe";
+    readonly brandDark: "#005a9e";
+    readonly borderNeutral: "#edebe9";
+    readonly textPrimary: "#323130";
+    readonly textSecondary: "#605e5c";
+    readonly surface: "#ffffff";
+    readonly surfaceAlt: "#f5f5f5";
+    readonly canvas: "#fafafa";
+    readonly danger: "#a4262c";
+    readonly fieldFill: "#faf9f8";
+    readonly fieldFillReadonly: "#f3f2f1";
+    readonly fieldBorder: "#e1dfdd";
+};
+declare const spacing: {
+    readonly xs: 4;
+    readonly sm: 8;
+    readonly md: 12;
+    readonly lg: 16;
+    readonly xl: 24;
+    readonly xxl: 40;
+};
+declare const typography: {
+    readonly fontFamily: "\"Segoe UI\", Arial, sans-serif";
+    readonly fontFamilySemibold: "\"Segoe UI Semibold\", \"Segoe UI\", sans-serif";
+    readonly fontSize: {
+        readonly sm: "12px";
+        readonly smPlus: "13px";
+        readonly md: "14px";
+        readonly lg: "17px";
+    };
+    readonly fontWeight: {
+        readonly regular: 400;
+        readonly semibold: 600;
+    };
+};
+declare const radius: {
+    readonly card: "4px";
+    readonly lg: "8px";
+};
+declare const layout: {
+    readonly labelColWidth: "130px";
+};
+
+declare function createDynamicsTheme(): Theme;
+
+type Density = 'comfortable' | 'compact';
+declare const densityScale: {
+    readonly comfortable: 1;
+    readonly compact: 0.75;
+};
+/** Scale a base spacing value (px) by the active density. */
+declare function scaleSpacing(value: number, density?: Density): number;
+
+interface ContainerSize {
+    width: number;
+    height: number;
+    inlineSize: number;
+    blockSize: number;
+}
+/** Observe an element's size via ResizeObserver. Pass a ref; returns {width,height,inlineSize,blockSize}. */
+declare function useContainerSize<T extends HTMLElement = HTMLElement>(ref: React.RefObject<T>): ContainerSize;
+
+/**
+ * Create-and-return a ref plus the observed width of the element it is attached to.
+ * `const [ref, width] = useContainerWidth(); return <div ref={ref}>…</div>`.
+ */
+declare function useContainerWidth<T extends HTMLElement = HTMLDivElement>(): [React.RefObject<T>, number];
+
+/**
+ * Resolve the *container's* current breakpoint (not the viewport's) — the correctness
+ * fix for a surface inside a PCF, where width comes from `context.allocatedWidth`.
+ * Returns `[ref, breakpoint, width]`.
+ */
+declare function useContainerBreakpoint<T extends HTMLElement = HTMLDivElement>(): [React.RefObject<T>, Breakpoint, number];
+
+/**
+ * Resolve a responsive value against the *container's* current breakpoint.
+ * `const [ref, cols] = useResponsiveValue({ xs: 1, md: 2, lg: 3 });`
+ */
+declare function useResponsiveValue<T, E extends HTMLElement = HTMLDivElement>(value: ResponsiveValue<T>): [React.RefObject<E>, T | undefined];
+
+/** Viewport media-query match — the SSR-safe / no-ResizeObserver fallback to the container hooks. */
+declare function useMediaQuery(query: string): boolean;
+
+type SurfaceVariant = 'card' | 'flat' | 'placeholder';
+type Alignment = 'left' | 'center' | 'right';
+interface SurfaceActionButton {
+    id: string;
+    label: string;
+    iconName?: string;
+    appearance?: 'primary' | 'default' | 'subtle';
+    position?: 'left' | 'right';
+    disabled?: boolean;
+    hidden?: boolean;
+    onClick?: () => void;
+}
+interface ColumnLayoutProps {
+    columns: ColumnCount;
+    /** Gap (px number or any CSS value). Default `'4px 24px'`. */
+    gap?: number | string;
+    /** Stack responsively (caps at 2 cols <=768, 1 col <=480). Default true. */
+    responsive?: boolean;
+    /** Responsive driver: viewport `@media` (default) or `@container`. */
+    mode?: 'media' | 'container';
+    className?: string;
+    style?: CSSProperties;
+    children?: ReactNode;
+}
+interface TwoColumnLayoutProps {
+    gap?: number | string;
+    /** Collapse to one column below this breakpoint. Default `'sm'`. */
+    collapseBelow?: Breakpoint;
+    className?: string;
+    style?: CSSProperties;
+    children?: ReactNode;
+}
+interface FieldRowProps {
+    label?: ReactNode;
+    required?: boolean;
+    /** Span both columns of a two-column grid. */
+    fullWidth?: boolean;
+    /** Label column width. Default `'130px'`. */
+    labelWidth?: string;
+    /** Label beside the control (default) or stacked above it. */
+    labelPosition?: 'beside' | 'above';
+    className?: string;
+    children?: ReactNode;
+}
+interface FormSurfaceProps {
+    /** Outer grid column count. Default 12. */
+    columns?: number;
+    /** Grid gap in px. Default 20. */
+    gap?: number;
+    /** Padding in px. Default 20. */
+    padding?: number;
+    /** Canvas background. Default the Dynamics form canvas. */
+    background?: string;
+    /** Container width hint (e.g. a PCF `context.allocatedWidth`) — drives stacking off the container, not the viewport. */
+    containerWidth?: number;
+    /** Collapse children to full width below this breakpoint. Default `'sm'`. */
+    collapseBelow?: Breakpoint;
+    maxWidth?: number | string;
+    className?: string;
+    style?: CSSProperties;
+    children?: ReactNode;
+}
+interface PageSurfaceProps extends FormSurfaceProps {
+    /** Center the form and apply a comfortable max width. */
+    centered?: boolean;
+}
+interface SectionProps {
+    title?: string;
+    /** Span within the parent form grid. Default 12. */
+    columnSpan?: number;
+    columnStart?: number;
+    rowPosition?: number;
+    /** Internal field-grid column count. Default 12. */
+    internalColumns?: number;
+    showCommandBar?: boolean;
+    commandBarItems?: ICommandBarItemProps[];
+    statusText?: string;
+    notification?: ReactNode;
+    collapsible?: boolean;
+    /** Uncontrolled initial collapsed state. */
+    defaultCollapsed?: boolean;
+    /** Controlled collapsed state (pair with `onCollapsedChange`). */
+    collapsed?: boolean;
+    onCollapsedChange?: (collapsed: boolean) => void;
+    /** `card` (default), `flat` (no shadow), or `placeholder` (empty dashed spacer). */
+    variant?: SurfaceVariant;
+    /** Min height for the `placeholder` variant. */
+    minHeight?: number;
+    className?: string;
+    style?: CSSProperties;
+    children?: ReactNode;
+}
+interface SectionCardProps extends SectionProps {
+    /** Accent color of the top border (Dynamics blue). Default brand. */
+    accentColor?: string;
+    /** Accent top-border width in px. Default 3. */
+    accentWidth?: number;
+}
+interface SectionHeaderProps {
+    title?: string;
+    statusText?: string;
+    showCommandBar?: boolean;
+    commandBarItems?: ICommandBarItemProps[];
+    actions?: ReactNode;
+    collapsible?: boolean;
+    collapsed?: boolean;
+    onToggle?: () => void;
+}
+interface FormHeaderProps {
+    title?: ReactNode;
+    subtitle?: ReactNode;
+    status?: ReactNode;
+    titleColor?: string;
+    subtitleColor?: string;
+    /** Avatar/persona shown to the left of the title. */
+    persona?: ReactNode;
+    /** Right side of the header (e.g. KPI header fields). */
+    actions?: ReactNode;
+    className?: string;
+}
+interface SurfaceTab {
+    id: string;
+    label: string;
+    content: ReactNode;
+    iconName?: string;
+    disabled?: boolean;
+}
+interface PivotSurfaceProps {
+    tabs: SurfaceTab[];
+    selectedId?: string;
+    defaultSelectedId?: string;
+    onTabChange?: (id: string) => void;
+    /** Fluent Pivot link format. */
+    linkFormat?: 'links' | 'tabs';
+    className?: string;
+}
+interface CommandSurfaceProps {
+    items: ICommandBarItemProps[];
+    overflowItems?: ICommandBarItemProps[];
+    farItems?: ICommandBarItemProps[];
+    className?: string;
+}
+interface ActionBarProps {
+    buttons: SurfaceActionButton[];
+    /** Default `'right'`. */
+    alignment?: Alignment;
+    /** Stick to the bottom of the scroll container. Default true. */
+    sticky?: boolean;
+    className?: string;
+}
+interface FooterProps {
+    /** Default true. */
+    sticky?: boolean;
+    align?: Alignment;
+    className?: string;
+    children?: ReactNode;
+}
+interface MasterDetailSurfaceProps {
+    master: ReactNode;
+    detail: ReactNode;
+    /** Rendered in the detail pane when `detail` is null/undefined. */
+    detailFallback?: ReactNode;
+    /** Master pane width fraction (0–1). Default 0.38. */
+    splitRatio?: number;
+    /** Stack master over detail below this breakpoint. Default `'md'`. */
+    collapseBelow?: Breakpoint;
+    className?: string;
+}
+interface DashboardSurfaceProps {
+    tiles: ReactNode[];
+    /** Tile columns. Default 2. */
+    columns?: ColumnCount;
+    gap?: number;
+    className?: string;
+}
+type FluentPanelType = 'smallFixedFar' | 'smallFixedNear' | 'medium' | 'large' | 'largeFixed' | 'extraLarge' | 'custom' | 'customNear';
+type CalloutDirection = 'topLeftEdge' | 'topCenter' | 'topRightEdge' | 'topAutoEdge' | 'bottomLeftEdge' | 'bottomCenter' | 'bottomRightEdge' | 'bottomAutoEdge' | 'leftTopEdge' | 'leftCenter' | 'leftBottomEdge' | 'rightTopEdge' | 'rightCenter' | 'rightBottomEdge';
+/** Full form-dialog (Fluent v8 Modal) with header/counter/close + sticky footer. */
+interface FormDialogSurfaceProps {
+    isOpen: boolean;
+    onDismiss?: () => void;
+    title?: string;
+    subheader?: string;
+    /** Size preset (default `lg` = 1200). Explicit `width` wins. */
+    size?: DialogSizePreset;
+    width?: number;
+    height?: number;
+    isBlocking?: boolean;
+    /** "X of Y" record counter in the header. */
+    recordCounter?: {
+        current: number;
+        total: number;
+    };
+    /** Footer content (e.g. an ActionBar). */
+    footer?: ReactNode;
+    className?: string;
+    children?: ReactNode;
+}
+/** Generic modal (Fluent v8 Modal) — lighter than FormDialogSurface. */
+interface ModalSurfaceProps {
+    isOpen: boolean;
+    onDismiss?: () => void;
+    title?: string;
+    size?: DialogSizePreset;
+    width?: number;
+    isBlocking?: boolean;
+    /** Auto width with a 1000px min (Track-and-Ship pattern) instead of a fixed preset. */
+    autoSize?: boolean;
+    footer?: ReactNode;
+    className?: string;
+    children?: ReactNode;
+}
+interface PanelSurfaceProps {
+    isOpen: boolean;
+    onDismiss?: () => void;
+    title?: string;
+    /** Fluent PanelType (default derived from `width`: >500 → medium, else custom). */
+    panelType?: FluentPanelType;
+    width?: number;
+    hasCloseButton?: boolean;
+    isLightDismiss?: boolean;
+    isFooterAtBottom?: boolean;
+    isNonModal?: boolean;
+    footer?: ReactNode;
+    children?: ReactNode;
+}
+interface CalloutSurfaceProps {
+    /** Anchor — a selector string, an element, or a ref. */
+    target: string | Element | RefObject<Element> | null;
+    isOpen?: boolean;
+    onDismiss?: () => void;
+    width?: number;
+    directionalHint?: CalloutDirection;
+    isBeakVisible?: boolean;
+    beakWidth?: number;
+    gapSpace?: number;
+    className?: string;
+    children?: ReactNode;
+}
+interface TooltipSurfaceProps {
+    /** Tooltip body — what Fluent's TooltipHost actually renders (string or element(s)). */
+    content: string | ReactElement | ReactElement[];
+    directionalHint?: CalloutDirection;
+    delay?: 'zero' | 'medium' | 'long';
+    children: ReactElement;
+}
+
+/** N-column grid for form fields. Responsive by default (caps at 2 cols <=768, 1 <=480). */
+declare const ColumnLayout: React__default.FC<ColumnLayoutProps>;
+
+/** Two equal columns that collapse to one below `collapseBelow` (default 'sm' = 480). */
+declare const TwoColumnLayout: React__default.FC<TwoColumnLayoutProps>;
+
+/** A two-column "Label : control" row. The control goes in `children` (right column). */
+declare const FieldRow: React__default.FC<FieldRowProps>;
+
+/** The N-column form canvas that hosts Sections. */
+declare const FormSurface: React__default.FC<FormSurfaceProps>;
+
+/** A full-page FormSurface — optionally centered with a comfortable max width. */
+declare const PageSurface: React__default.FC<PageSurfaceProps>;
+
+/** A Dynamics-CE form section: positioned card with a header and an internal field grid. */
+declare const Section: React__default.FC<SectionProps>;
+
+/**
+ * A Section with the Dynamics blue 3px accent top border.
+ * NOTE: the accent is an inline style so it wins over the `card` variant's shorthand
+ * `border` (mergeStyles class). If the accent ever moves into a class, use the
+ * `borderTop*` longhand so it isn't clobbered by the shorthand `border`.
+ */
+declare const SectionCard: React__default.FC<SectionCardProps>;
+
+/** Section header bar: title + status (left), command bar / actions (right), optional collapse toggle. */
+declare const SectionHeader: React__default.FC<SectionHeaderProps>;
+
+/** Dynamics form header: persona + title/status (left), KPI/header fields (right). */
+declare const FormHeader: React__default.FC<FormHeaderProps>;
+
+/** Tabbed surface (Fluent Pivot). Controlled via `selectedId`/`onTabChange` or uncontrolled. */
+declare const PivotSurface: React__default.FC<PivotSurfaceProps>;
+
+/** A Dynamics-style command bar (thin wrapper over Fluent CommandBar, no card chrome). */
+declare const CommandSurface: React__default.FC<CommandSurfaceProps>;
+
+/** A sticky footer bar of action buttons, with optional left-aligned buttons. */
+declare const ActionBar: React__default.FC<ActionBarProps>;
+
+/** A sticky footer region (free-form children) — e.g. for dialog/panel actions. */
+declare const Footer: React__default.FC<FooterProps>;
+
+/**
+ * Full Dynamics form-dialog (Fluent v8 Modal). Default width 1200 (lg), height 95vh.
+ * `onDismiss` is the close affordance — when omitted, no close button renders, so a
+ * blocking dialog without `onDismiss` is intentionally non-dismissible.
+ */
+declare const FormDialogSurface: React__default.FC<FormDialogSurfaceProps>;
+
+/** A generic modal (Fluent v8 Modal) — title + content + optional footer; lighter than FormDialogSurface. */
+declare const ModalSurface: React__default.FC<ModalSurfaceProps>;
+
+/** A Dynamics side panel (Fluent v8 Panel). */
+declare const PanelSurface: React__default.FC<PanelSurfaceProps>;
+
+/** A lightweight contextual callout (Fluent v8 Callout) anchored to a target. */
+declare const CalloutSurface: React__default.FC<CalloutSurfaceProps>;
+
+/** A tooltip wrapper (Fluent v8 TooltipHost). New surface — no codegen counterpart. */
+declare const TooltipSurface: React__default.FC<TooltipSurfaceProps>;
+
+/** Master (left rail) + detail (right pane) split that stacks vertically below `collapseBelow`. */
+declare const MasterDetailSurface: React__default.FC<MasterDetailSurfaceProps>;
+
+/** A reflowing grid of dashboard tiles (N cols → 2 below 900px → 1 below 480px). */
+declare const DashboardSurface: React__default.FC<DashboardSurfaceProps>;
+
+/** The overlay FormTypes surface-kit knows how to resolve (form-runtime also has the tab-only 'related'/'audit'). */
+type SurfaceFormType = 'main' | 'dialog' | 'panel' | 'callout';
+interface FormSettingsLike {
+    width?: number;
+    height?: number;
+    panelType?: string;
+}
+interface FormDefinitionLike {
+    type?: SurfaceFormType;
+    name?: string;
+    settings?: FormSettingsLike;
+}
+type ResolvedSurface = {
+    kind: 'main';
+} | {
+    kind: 'dialog';
+    widthPx: number;
+    heightCss: string;
+    title?: string;
+} | {
+    kind: 'panel';
+    panelType: string;
+    customWidthPx?: number;
+    title?: string;
+} | {
+    kind: 'callout';
+    widthPx: number;
+    title?: string;
+};
+/** Resolve a (duck-typed) form-runtime FormDefinition to the right surface + sizing props. */
+declare function fromFormDefinition(def: FormDefinitionLike): ResolvedSurface;
+
+export { ActionBar, type ActionBarProps, type Alignment, Breakpoint, type CalloutDirection, CalloutSurface, type CalloutSurfaceProps, ColumnCount, ColumnLayout, type ColumnLayoutProps, CommandSurface, type CommandSurfaceProps, type ContainerSize, DashboardSurface, type DashboardSurfaceProps, type Density, DialogSizePreset, FieldRow, type FieldRowProps, type FluentPanelType, Footer, type FooterProps, type FormDefinitionLike, FormDialogSurface, type FormDialogSurfaceProps, FormHeader, type FormHeaderProps, type FormSettingsLike, FormSurface, type FormSurfaceProps, MasterDetailSurface, type MasterDetailSurfaceProps, ModalSurface, type ModalSurfaceProps, PageSurface, type PageSurfaceProps, PanelSurface, type PanelSurfaceProps, PivotSurface, type PivotSurfaceProps, type ResolvedSurface, ResponsiveValue, Section, SectionCard, type SectionCardProps, SectionHeader, type SectionHeaderProps, type SectionProps, type SurfaceActionButton, type SurfaceFormType, type SurfaceTab, type SurfaceVariant, TooltipSurface, type TooltipSurfaceProps, TwoColumnLayout, type TwoColumnLayoutProps, colors, createDynamicsTheme, densityScale, fromFormDefinition, layout, radius, scaleSpacing, spacing, typography, useContainerBreakpoint, useContainerSize, useContainerWidth, useMediaQuery, useResponsiveValue };