@dataverse-kit/surface-kit 0.2.0 → 0.3.0

package/dist/v9.d.ts

@@ -0,0 +1,313 @@
+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';
+export { C as ColumnCount, c as clampSpan, g as gridTemplateForColumns } from './columns-BlpFO5VD.js';
+import { Breakpoint } from './responsive.js';
+export { BREAKPOINTS, CARD_REFLOW_WIDTH, ResponsiveMode, ResponsiveValue, StyleObject, fieldGridStyle, fieldRowStyle, resolveBreakpoint, resolveResponsiveValue, sectionStackingStyle } from './responsive.js';
+export { colors, layout, radius, spacing, typography } from '@dataverse-kit/design-tokens';
+import { D as Density } from './useDensity-BePwtUzY.js';
+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-BePwtUzY.js';
+import React__default, { ReactElement, CSSProperties, ReactNode, RefObject } from 'react';
+import { BrandVariants, Theme } from '@fluentui/react-components';
+
+type SurfaceVariant = 'card' | 'flat' | 'placeholder';
+type Alignment = 'left' | 'center' | 'right';
+/** A single command in a v9 command surface / section header (renders a `<ToolbarButton>`). */
+interface SurfaceToolbarItem {
+    id: string;
+    label: string;
+    /** A rendered v9 icon element (e.g. `<Save20Regular />`). */
+    icon?: ReactElement;
+    /** `primary` uses the brand appearance; otherwise a subtle toolbar button. */
+    appearance?: 'primary' | 'subtle';
+    disabled?: boolean;
+    onClick?: () => void;
+}
+/** An action button in a v9 `ActionBar` / dialog footer. */
+interface SurfaceActionButton {
+    id: string;
+    label: string;
+    /** A rendered v9 icon element (e.g. `<Dismiss20Regular />`). */
+    icon?: ReactElement;
+    /** Maps to a v9 `Button` appearance: primary → `primary`, default → `secondary`, subtle → `subtle`. */
+    appearance?: 'primary' | 'default' | 'subtle';
+    position?: 'left' | 'right';
+    disabled?: boolean;
+    hidden?: boolean;
+    onClick?: () => void;
+}
+/** v9 overlay position (a subset of the v9 `Popover`/`Tooltip` positioning shorthand). */
+type SurfacePosition = 'above' | 'below' | 'before' | 'after';
+type SurfaceAlign = 'start' | 'center' | 'end';
+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;
+    /** Spacing density: `'compact'` scales gap + padding by 0.75 and cascades to child
+     *  Sections via context. Default `'comfortable'` (byte-identical to no density). */
+    density?: Density;
+    /** Canvas background. Default the v9 neutral-2 background (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;
+    /** Show a v9 `<Toolbar>` of `commandItems` in the section header. */
+    showCommandBar?: boolean;
+    commandItems?: SurfaceToolbarItem[];
+    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;
+    /** Spacing density override; defaults to the ambient `FormSurface` density (`useDensity`).
+     *  `'compact'` scales the card padding + internal field gap by 0.75. */
+    density?: Density;
+    className?: string;
+    style?: CSSProperties;
+    children?: ReactNode;
+}
+interface SectionCardProps extends SectionProps {
+    /** Accent color of the top border (Dynamics blue). Default the v9 brand stroke. */
+    accentColor?: string;
+    /** Accent top-border width in px. Default 3. */
+    accentWidth?: number;
+}
+interface SectionHeaderProps {
+    title?: string;
+    statusText?: string;
+    showCommandBar?: boolean;
+    commandItems?: SurfaceToolbarItem[];
+    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 (e.g. a v9 `<Avatar>` / `<Persona>`). */
+    persona?: ReactNode;
+    /** Right side of the header (e.g. KPI header fields). */
+    actions?: ReactNode;
+    className?: string;
+}
+interface SurfaceTab {
+    id: string;
+    label: string;
+    content: ReactNode;
+    /** A rendered v9 icon element for the tab. */
+    icon?: ReactElement;
+    disabled?: boolean;
+}
+interface PivotSurfaceProps {
+    tabs: SurfaceTab[];
+    selectedId?: string;
+    defaultSelectedId?: string;
+    onTabChange?: (id: string) => void;
+    /** v9 `TabList` appearance. Default `'transparent'`. */
+    appearance?: 'transparent' | 'subtle';
+    /** v9 `TabList` size. Default `'medium'`. */
+    size?: 'small' | 'medium' | 'large';
+    className?: string;
+}
+interface CommandSurfaceProps {
+    items: SurfaceToolbarItem[];
+    /** Rendered behind a "more" overflow menu after the primary items. */
+    overflowItems?: SurfaceToolbarItem[];
+    /** Right-aligned items (e.g. a settings button). */
+    farItems?: SurfaceToolbarItem[];
+    /** v9 `Toolbar` size. Default `'small'`. */
+    size?: 'small' | 'medium' | 'large';
+    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;
+}
+/** Full form-dialog (Fluent v9 `Dialog`) 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;
+    /** `true` (default) is a modal dialog; `false` is non-modal. */
+    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 v9 `Dialog`) — 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;
+}
+/** A Dynamics side panel (Fluent v9 `OverlayDrawer`). */
+interface PanelSurfaceProps {
+    isOpen: boolean;
+    onDismiss?: () => void;
+    title?: string;
+    /** v9 Drawer size. Default derived from `width`: >500 → `medium`, else `small`. An explicit `width` renders a custom-width drawer. */
+    drawerSize?: 'small' | 'medium' | 'large' | 'full';
+    width?: number;
+    hasCloseButton?: boolean;
+    /** Dismiss on overlay click / Esc. Default true. */
+    isLightDismiss?: boolean;
+    /** Non-modal drawer (no blocking overlay). Default false. */
+    isNonModal?: boolean;
+    footer?: ReactNode;
+    children?: ReactNode;
+}
+/** A lightweight contextual callout (Fluent v9 `Popover`) anchored to a target. */
+interface CalloutSurfaceProps {
+    /** Anchor — a selector string, an element, or a ref. */
+    target: string | Element | RefObject<Element> | null;
+    isOpen?: boolean;
+    onDismiss?: () => void;
+    width?: number;
+    /** v9 position relative to the target. Default `'below'`. */
+    position?: SurfacePosition;
+    /** v9 alignment along the position edge. Default `'start'`. */
+    align?: SurfaceAlign;
+    /** Show the pointing arrow. Default true. */
+    isBeakVisible?: boolean;
+    className?: string;
+    children?: ReactNode;
+}
+interface TooltipSurfaceProps {
+    /** Tooltip body — what the v9 `Tooltip` renders (string or element). */
+    content: string | ReactElement;
+    /** v9 position relative to the child. Default `'above'`. */
+    position?: SurfacePosition;
+    /** Delay before showing: `zero`→0ms, `medium`→250ms, `long`→500ms. Default `medium`. */
+    delay?: 'zero' | 'medium' | 'long';
+    /** Whether the tooltip labels or merely describes its child (v9 `relationship`). Default `'label'`. */
+    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;
+
+/** The N-column form canvas that hosts Sections (Fluent UI v9). */
+declare const FormSurface: React__default.FC<FormSurfaceProps>;
+
+/** A full-page FormSurface (Fluent v9) — optionally centered with a comfortable max width. */
+declare const PageSurface: React__default.FC<PageSurfaceProps>;
+
+/** A Dynamics-CE form section (Fluent v9): positioned card with a header and an internal field grid. */
+declare const Section: React__default.FC<SectionProps>;
+
+/**
+ * A Section with the Dynamics blue accent top border (Fluent v9).
+ * The accent is an inline `borderTop` so it wins over the card variant's inline `border`
+ * (see Section: `style` is spread after the card chrome). Defaults to the v9 brand stroke.
+ */
+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>;
+
+/** Dynamics form header (Fluent v9): persona + title/status (left), KPI/header fields (right). */
+declare const FormHeader: React__default.FC<FormHeaderProps>;
+
+/** Tabbed surface (Fluent v9 `TabList`). Controlled via `selectedId`/`onTabChange` or uncontrolled. */
+declare const PivotSurface: React__default.FC<PivotSurfaceProps>;
+
+/** A Dynamics-style command bar (Fluent v9 `Toolbar`), with an optional overflow menu + far items. */
+declare const CommandSurface: React__default.FC<CommandSurfaceProps>;
+
+/** A sticky footer bar of action buttons (Fluent v9), with optional left-aligned buttons. */
+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>;
+
+/**
+ * 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`
+ * maps to the dialog `modalType` (`modal` vs `non-modal`).
+ */
+declare const FormDialogSurface: React__default.FC<FormDialogSurfaceProps>;
+
+/** A generic modal (Fluent v9 `Dialog`) — title + content + optional footer; lighter than FormDialogSurface. */
+declare const ModalSurface: React__default.FC<ModalSurfaceProps>;
+
+/** A Dynamics side panel (Fluent v9 `OverlayDrawer`). */
+declare const PanelSurface: React__default.FC<PanelSurfaceProps>;
+
+/** A lightweight contextual callout (Fluent v9 `Popover`) anchored to a target. */
+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 };