@nexia/sdk 0.5.0

package/dist/shell.d.ts

@@ -0,0 +1,1297 @@
+import type { AnchorHTMLAttributes, ButtonHTMLAttributes, ComponentType, FieldsetHTMLAttributes, FormEvent, HTMLAttributes, InputHTMLAttributes, ReactElement, ReactNode, TextareaHTMLAttributes } from "react";
+import type { QueryClient } from "@tanstack/react-query";
+import type { PermissionsResponse } from "./context";
+import type { ResourcePickerRevalidation, ResourceReferenceIdentity } from "./resource-reference";
+import type { ResourceListSchema } from "./resources/resource-list";
+import type { ResourceTransferMeta } from "./resources/resource-transfer";
+/** A server-authorized, durable favorite identity. */
+export type FavoriteTarget = {
+    kind: "page";
+    key: string;
+} | {
+    kind: "record";
+    resourceKey: string;
+    resourceId: string;
+};
+export interface WorkTabRef<TData = unknown> {
+    type: string;
+    id: string;
+    label?: string;
+    route?: string;
+    data?: TData;
+    /** Omitted unless the server authorizes this resource as favoriteable. */
+    favorite_target?: FavoriteTarget | null;
+}
+/** @deprecated Use WorkTabRef. Kept for one release for App source compatibility. */
+export type ResourceRef<TData = unknown> = WorkTabRef<TData>;
+/** Identifies the picker that launched a route-backed Resource create flow. */
+export interface ResourceCreateContinuationTarget {
+    receiverKey: string;
+    /** Localized human field label shown by Shell continuation chrome. */
+    receiverLabel?: string;
+    resourceKey: string;
+}
+export interface ResourceCreateCompletionInput {
+    resourceId: string;
+    /** Optional owner-provided label used when no generic resolver exists. */
+    display?: string;
+}
+export interface ResourceCreateCompletion {
+    /** Complete a contextual create flow; returns true when the host handled navigation. */
+    complete: (input: ResourceCreateCompletionInput) => Promise<boolean>;
+    /** Cancel a contextual create flow; returns true when the host returned to its origin. */
+    cancel: () => boolean;
+    isContextual: boolean;
+}
+export interface ResourceCreateReceiverRegistration {
+    target: ResourceCreateContinuationTarget;
+    onCreated: (reference: ResourceReferenceIdentity) => void;
+}
+export interface ResourceInspectorStack {
+    readonly entries: ReadonlyArray<WorkTabRef>;
+    readonly index: number;
+    readonly current: WorkTabRef | null;
+    readonly isRoot: boolean;
+    readonly isEmpty: boolean;
+    push: (resource: WorkTabRef) => void;
+    back: () => void;
+    jumpTo: (index: number) => void;
+    reset: () => void;
+    openInTab: (resource: WorkTabRef) => void;
+}
+export interface ResourceInspectorAdapterProps<TData = unknown> {
+    resource: WorkTabRef<TData>;
+    stack: ResourceInspectorStack;
+}
+export type ResourceInspectorAdapter<TData = unknown> = (props: ResourceInspectorAdapterProps<TData>) => ReactNode;
+export type ResourceInspectorAdapterLoader<TData = never> = () => Promise<{
+    default: ResourceInspectorAdapter<TData>;
+}>;
+export interface ResourceInspectorAdapterRegistry {
+    register: <TData = never>(type: string, loader: ResourceInspectorAdapterLoader<NoInfer<TData>>) => void;
+    get: (type: string) => ComponentType<ResourceInspectorAdapterProps> | undefined;
+    ids: () => string[];
+    subscribe: (listener: () => void) => () => void;
+    snapshot: () => number;
+    resetForTests: () => void;
+}
+/** App-facing registration capability. Inspection remains host/test-only. */
+export interface ResourceInspectorAdapterRegistrar {
+    register: <TData = never>(type: string, loader: ResourceInspectorAdapterLoader<NoInfer<TData>>) => void;
+}
+export interface NxAlertProps {
+    variant?: "info" | "success" | "warning" | "error";
+    title?: ReactNode;
+    icon?: ReactNode;
+    actions?: ReactNode;
+    onDismiss?: () => void;
+    dismissLabel?: string;
+    children?: ReactNode;
+    className?: string;
+}
+export interface NxModalDialogProps {
+    open: boolean;
+    onClose: () => void;
+    title?: ReactNode;
+    description?: ReactNode;
+    children: ReactNode;
+    footer?: ReactNode;
+    width?: "sm" | "md" | "lg" | "xl" | "2xl" | "3xl" | "4xl" | "5xl" | "6xl";
+    height?: "auto" | "compact" | "tall";
+    placement?: "center" | "upper" | "top";
+    dismissOnBackdrop?: boolean;
+    dismissOnEscape?: boolean;
+    labelledBy?: string;
+    showClose?: boolean;
+}
+export interface NxColumnNode {
+    value: string;
+    label: string;
+    children?: NxColumnNode[];
+    icon?: ReactNode;
+    meta?: ReactNode;
+    disabled?: boolean;
+    keywords?: string;
+}
+export interface NxColumnBrowserLabels {
+    searchEmptyTitle?: string;
+    searchEmptyHint?: string;
+    previewEmpty?: string;
+    previewLabel?: string;
+    breadcrumbSeparator?: string;
+}
+export interface NxColumnBrowserProps {
+    roots: NxColumnNode[];
+    value?: string | null;
+    selectedValues?: readonly string[];
+    multiple?: boolean;
+    onSelect: (value: string, node: NxColumnNode) => void;
+    onClearSelection?: () => void;
+    onActivate?: (value: string, node: NxColumnNode) => void;
+    renderPreview?: (node: NxColumnNode) => ReactNode;
+    allLabel?: string;
+    searchable?: boolean;
+    autoFocus?: boolean;
+    searchPlaceholder?: string;
+    labels?: NxColumnBrowserLabels;
+    ariaLabel: string;
+    heightClassName?: string;
+    testId?: string;
+}
+export interface NxColumnPickerLabels extends NxColumnBrowserLabels {
+    clear?: string;
+    cancel?: string;
+    select?: string;
+}
+interface NxColumnPickerBaseProps {
+    open: boolean;
+    onClose: () => void;
+    title: string;
+    roots: NxColumnNode[];
+    onClear?: () => void;
+    allLabel?: string;
+    searchable?: boolean;
+    searchPlaceholder?: string;
+    labels?: NxColumnPickerLabels;
+    width?: "lg" | "xl" | "2xl" | "3xl" | "4xl" | "5xl" | "6xl";
+    testId?: string;
+}
+interface NxColumnPickerSingleProps {
+    multiple?: false;
+    value?: string | null;
+    onSelect: (value: string, node: NxColumnNode) => void;
+    renderPreview?: (node: NxColumnNode) => ReactNode;
+    renderSelectionPreview?: never;
+    values?: never;
+    onSelectMany?: never;
+}
+interface NxColumnPickerMultipleProps {
+    multiple: true;
+    values?: readonly string[];
+    onSelectMany: (values: string[], nodes: NxColumnNode[]) => void;
+    renderSelectionPreview?: (nodes: NxColumnNode[], onRemove: (value: string) => void) => ReactNode;
+    renderPreview?: never;
+    value?: never;
+    onSelect?: never;
+}
+export type NxColumnPickerProps = NxColumnPickerBaseProps & (NxColumnPickerSingleProps | NxColumnPickerMultipleProps);
+export interface NxMissingRequiredReferenceItem {
+    key: string;
+    label: string;
+    createLabel?: string;
+    onCreate?: () => void;
+}
+export interface NxMissingRequiredReferencesAlertProps {
+    title: string;
+    items: readonly NxMissingRequiredReferenceItem[];
+}
+export interface NxPaginationProps {
+    current: number;
+    total: number;
+    onChange: (page: number) => void;
+    disabled?: boolean;
+    className?: string;
+}
+export interface ResourceInspectorPanelProps {
+    testId?: string;
+    badges?: ReactNode;
+    actions?: ReactNode;
+    children?: ReactNode;
+}
+export interface ResourceInspectorStateProps {
+    testId?: string;
+    children: ReactNode;
+}
+export interface ResourceInspectorStackHostProps {
+    root?: WorkTabRef | null;
+    onClose?: () => void;
+    onOpenInTab?: (resource: WorkTabRef) => void;
+    emptyState?: ReactNode;
+    testId?: string;
+}
+export interface ResourceInspectorStackProviderProps {
+    root: WorkTabRef | null;
+    initialEntries?: WorkTabRef[];
+    onEntriesChange?: (entries: ReadonlyArray<WorkTabRef>) => void;
+    onOpenInTab?: (resource: WorkTabRef) => void;
+    children: ReactNode;
+}
+export interface NxComboboxOption<TValue extends string | number> {
+    value: TValue;
+    label: ReactNode;
+    meta?: ReactNode;
+    trailing?: ReactNode;
+    disabled?: boolean;
+    searchText?: string;
+}
+interface NxComboboxBaseProps<TValue extends string | number> {
+    options: readonly NxComboboxOption<TValue>[];
+    placeholder: ReactNode;
+    ariaLabel: string;
+    searchPlaceholder?: string;
+    emptyLabel?: ReactNode;
+    searchValue?: string;
+    onSearchChange?: (query: string) => void;
+    loading?: boolean;
+    id?: string;
+    describedBy?: string;
+    invalid?: boolean;
+    fullWidth?: boolean;
+    disabled?: boolean;
+    size?: "xs" | "sm" | "md";
+    triggerClassName?: string;
+    /** Optional panel width. By default the panel matches its trigger. */
+    panelWidth?: number | string;
+    testId?: string;
+    renderSummary?: (selected: NxComboboxOption<TValue>[]) => ReactNode;
+    closeLabel?: ReactNode;
+    showSelectedItems?: boolean;
+    selectedItemsAriaLabel?: string;
+    removeSelectedItemLabel?: (option: NxComboboxOption<TValue>) => string;
+    createAction?: {
+        label: string;
+        onCreate: (searchValue: string) => void;
+        disabled?: boolean;
+    };
+    revalidateOnOpen?: ResourcePickerRevalidation;
+    /** Registers this picker as the return target for a route-backed create flow. */
+    resourceCreateContinuation?: TValue extends string ? ResourceCreateContinuationTarget : never;
+}
+export type NxComboboxProps<TValue extends string | number> = (NxComboboxBaseProps<TValue> & {
+    multiple?: false;
+    value: TValue | null;
+    onChange: (value: TValue, option: NxComboboxOption<TValue>) => void;
+}) | (NxComboboxBaseProps<TValue> & {
+    multiple: true;
+    value: readonly TValue[];
+    onChange: (values: TValue[], option: NxComboboxOption<TValue>) => void;
+});
+/**
+ * Standard manual refresh control. The host owns its icon, label, sizing, and
+ * visual emphasis so App surfaces only choose the semantic placement.
+ */
+export interface NxRefreshControlProps {
+    context: "compact" | "section" | "snapshot";
+    onRefresh: () => void | Promise<void>;
+    isRefreshing?: boolean;
+    disabled?: boolean;
+    /** Optional status rendered beside a snapshot refresh action. */
+    status?: ReactNode;
+    /** Optional pending status for a snapshot refresh action. */
+    refreshingLabel?: ReactNode;
+    testId?: string;
+    className?: string;
+}
+export interface InspectorActionProps {
+    id: string;
+    label: string;
+    permission: string;
+    onSelect: () => void;
+    icon?: ReactNode;
+    destructive?: boolean;
+    disabled?: boolean;
+    testId?: string;
+}
+/**
+ * Presentation-neutral Resource action shared by row menus and Inspectors.
+ *
+ * `id` is deliberately open-ended: the host applies canonical presentation
+ * for known IDs and a neutral fallback for App-specific operations.
+ */
+export interface ResourceActionDescriptor extends NxDropdownMenuItem {
+    permissions?: readonly string[];
+}
+export interface InspectorResourceActionsProps {
+    actions: readonly ResourceActionDescriptor[];
+}
+interface ResourceLinkOwnProps {
+    /** Reference identity pushed into the active Inspector stack by default. */
+    resource: WorkTabRef;
+    children: ReactNode;
+    /**
+     * Optional owner activation for row identity or another local selection.
+     * When supplied, it runs instead of the Inspector stack/navigation fallback.
+     */
+    onActivate?: (resource: WorkTabRef) => void;
+    /** Stop the click from also activating an enclosing clickable row. */
+    stopPropagation?: boolean;
+}
+export type ResourceLinkProps = ResourceLinkOwnProps & Omit<ButtonHTMLAttributes<HTMLButtonElement>, keyof ResourceLinkOwnProps | "children">;
+export type ResourceListFilterValue = string | string[];
+export type ResourceListFilters = Record<string, ResourceListFilterValue>;
+export interface ResourceTableSort {
+    key: string;
+    dir: "asc" | "desc";
+}
+export interface ResourceListParams {
+    search: string;
+    sort: ResourceTableSort | null;
+    filters: ResourceListFilters;
+    page: number;
+    perPage?: number;
+}
+export interface ResourceListParamsControls extends ResourceListParams {
+    setSearch: (value: string) => void;
+    setSort: (value: ResourceTableSort | null) => void;
+    setFilter: (key: string, value: ResourceListFilterValue | null) => void;
+    setFilters: (value: ResourceListFilters) => void;
+    setParams: (partial: Partial<Pick<ResourceListParams, "search" | "filters" | "sort">>) => void;
+    setPage: (value: number) => void;
+    setPerPage: (value: number | undefined) => void;
+    reset: () => void;
+}
+export interface UseResourceListParamsOptions {
+    scope?: string;
+    filterKeys?: readonly string[];
+    sortKeys?: readonly string[];
+    defaultSort?: ResourceTableSort | null;
+    defaultPage?: number;
+    searchDebounceMs?: number;
+}
+export interface ResourceListToolbarConfig {
+    leading?: ReactNode;
+    actions?: ReactNode;
+    filters?: ReactNode;
+    refresh?: ReactNode;
+    more?: ReactNode;
+    testId?: string;
+}
+export interface ResourceListRefreshConfig {
+    onRefresh: () => void | Promise<void>;
+    isRefreshing?: boolean;
+}
+export interface ResourceListFooterConfig {
+    pagination?: {
+        current: number;
+        total: number;
+        onChange: (page: number) => void;
+        disabled?: boolean;
+    } | null;
+    pageSize?: {
+        value: number;
+        onChange: (pageSize: number) => void;
+        options?: readonly number[];
+        disabled?: boolean;
+    } | null;
+    testId?: string;
+}
+export interface ResourceTableColumn<T> {
+    key: string;
+    header: ReactNode;
+    cell: (row: T, index: number) => ReactNode;
+    size?: "primary" | "text" | "meta" | "compact" | "actions";
+    colClassName?: string;
+    headerClassName?: string;
+    cellClassName?: string;
+    align?: "left" | "right";
+    priority?: 1 | 2;
+    sortable?: false;
+    sortKey?: string;
+    hideable?: false;
+    defaultVisible?: false;
+}
+export type ResourceTableDensity = "compact" | "standard" | "comfortable";
+export type ResourceTableStyle = "striped" | "grid";
+export interface ResourceTableSummaryRow {
+    cells: Partial<Record<string, ReactNode>>;
+    label?: string;
+    testId?: string;
+}
+export interface ResourceTableProps<T> {
+    tableId?: string;
+    label: string;
+    showLabel?: boolean;
+    labelTooltip?: ReactNode;
+    rows: T[];
+    columns: ResourceTableColumn<T>[];
+    /** Opt in to the host's card presentation. Omit for table-only list semantics. */
+    renderCard?: (row: T, index: number) => ReactNode;
+    /** Initial view when no actor-scoped table preference has been saved. */
+    defaultView?: "table" | "cards";
+    getKey: (row: T, index: number) => string | number;
+    toolbar?: true | ResourceListToolbarConfig;
+    footer?: true | ResourceListFooterConfig;
+    density?: ResourceTableDensity;
+    summaryRow?: ResourceTableSummaryRow;
+    refresh?: ResourceListRefreshConfig;
+    schema?: ResourceListSchema;
+    filters?: ResourceListFilters;
+    onFiltersChange?: (next: ResourceListFilters) => void;
+    transferMeta?: ResourceTransferMeta | null;
+    onTransferImported?: () => void | Promise<void>;
+    pagination?: {
+        current_page: number;
+        last_page: number;
+        per_page?: number;
+        total: number;
+    };
+    onPageChange?: (page: number) => void;
+    onPerPageChange?: (pageSize: number) => void;
+    paginationDisabled?: boolean;
+    loading?: boolean;
+    loadingLabel?: ReactNode;
+    loadingRows?: number;
+    empty?: ReactNode;
+    emptyState?: {
+        kind?: "empty" | "noResults";
+        title?: ReactNode;
+        description?: ReactNode;
+        action?: ReactNode;
+        testId?: string;
+    };
+    hasActiveQuery?: boolean;
+    error?: boolean;
+    errorDescription?: ReactNode;
+    onRetry?: () => void;
+    retryLabel?: ReactNode;
+    rowTestId?: (row: T, index: number) => string;
+    rowAttributes?: (row: T, index: number) => {
+        className?: string;
+        "aria-label"?: string;
+        "data-testid"?: string;
+    } | undefined;
+    rowSelected?: (row: T, index: number) => boolean;
+    onRowClick?: (row: T, index: number) => void;
+    tableMinWidth?: number;
+    responsiveMode?: "auto" | "table";
+    sort?: ResourceTableSort | null;
+    onSortChange?: (next: ResourceTableSort | null) => void;
+    className?: string;
+    headerTestId?: string;
+    tableTestId?: string;
+}
+export interface NxDropdownMenuItem {
+    id: string;
+    label: ReactNode;
+    href?: string;
+    testId?: string;
+    icon?: ReactNode;
+    trailing?: ReactNode;
+    destructive?: boolean;
+    separatorBefore?: boolean;
+    disabled?: boolean;
+    onSelect?: () => void;
+}
+export interface NxDropdownMenuProps {
+    /** A single element (typically an `NxButton`) that opens the menu. */
+    trigger: ReactElement;
+    items: NxDropdownMenuItem[];
+    /** Accessible label announced for the menu. Defaults to "Actions". */
+    "aria-label"?: string;
+    side?: "top" | "bottom";
+    align?: "start" | "end";
+    className?: string;
+}
+export interface ResourceListToolbarViewOption<TValue extends string> {
+    value: TValue;
+    label: ReactNode;
+    icon?: ReactNode;
+    disabled?: boolean;
+}
+export interface ResourceListToolbarMoreMenuProps<TValue extends string = string> {
+    label: string;
+    items?: NxDropdownMenuItem[];
+    viewOptions?: {
+        label: string;
+        value: TValue;
+        items: readonly ResourceListToolbarViewOption<TValue>[];
+        onChange: (value: TValue) => void;
+    };
+    testId?: string;
+}
+export interface ResourcePrimaryCellProps {
+    resource: WorkTabRef;
+    label: ReactNode;
+    onActivate?: (resource: WorkTabRef) => void;
+    meta?: Array<{
+        kind: "resource";
+        key: string;
+        label: ReactNode;
+        resource: WorkTabRef;
+        onActivate?: (resource: WorkTabRef) => void;
+        testId?: string;
+        className?: string;
+    } | {
+        kind: "text" | "badge";
+        key: string;
+        label: ReactNode;
+        testId?: string;
+        className?: string;
+    }>;
+    testId?: string;
+    className?: string;
+    labelClassName?: string;
+    /** Canonical server-authorized favorite target for this primary row. */
+    favoriteTarget?: FavoriteTarget;
+    /** Record identity the host must authorize before rendering a favorite control. */
+    favoriteCandidate?: Extract<FavoriteTarget, {
+        kind: "record";
+    }>;
+    /** Set false when this cell links to a related record, not the row record. */
+    favoriteable?: boolean;
+}
+export interface ResourceTextCellProps {
+    primary: ReactNode;
+    secondary?: ReactNode;
+    resource?: WorkTabRef;
+    onActivate?: (resource: WorkTabRef) => void;
+    testId?: string;
+    primaryClassName?: string;
+    secondaryClassName?: string;
+}
+export interface ResourceRowActionsMenuProps {
+    label: string;
+    items: readonly ResourceActionDescriptor[];
+    testId?: string;
+    className?: string;
+}
+export interface ResourceStatusBadgeProps {
+    status: string | boolean | null | undefined;
+    resourceKey?: string;
+    field?: string;
+    keyPrefix?: string;
+    children?: ReactNode;
+    className?: string;
+}
+export type NxActionKind = "view" | "edit" | "create" | "save" | "claim" | "complete" | "unassign" | "reassign" | "retry" | "submit" | "send" | "invite" | "saveDraft" | "cancel" | "close" | "back" | "delete";
+export type NxActionVariant = "primary" | "accent" | "secondary" | "ghost" | "success" | "warning" | "danger" | "dangerGhost";
+export type NxButtonRadius = "full" | "control";
+export interface NxActionButtonProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, "aria-label" | "children" | "size"> {
+    kind: NxActionKind;
+    label?: string;
+    loading?: boolean;
+    size?: "xs" | "sm" | "md";
+    variant?: NxActionVariant;
+}
+export interface NxButtonProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, "size"> {
+    variant?: NxActionVariant;
+    size?: "xs" | "sm" | "md";
+    radius?: NxButtonRadius;
+    selected?: boolean;
+    fullWidth?: boolean;
+    selectTrigger?: boolean;
+    loading?: boolean;
+    leadingIcon?: ReactNode;
+    trailingIcon?: ReactNode;
+    tooltip?: ReactNode;
+    asChild?: boolean;
+    truncate?: boolean;
+}
+/** Anchor navigation with the shared NxButton visual contract. */
+export interface NxLinkButtonProps extends Omit<AnchorHTMLAttributes<HTMLAnchorElement>, "children" | "href" | "onClick">, Pick<NxButtonProps, "variant" | "size" | "radius" | "selected" | "fullWidth" | "loading" | "leadingIcon" | "trailingIcon" | "truncate"> {
+    href: string;
+    children: ReactNode;
+    onNavigate?: (href: string) => void;
+}
+export interface NxIconButtonProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, "aria-label" | "children" | "size"> {
+    "aria-label": string;
+    children: ReactNode;
+    variant?: NxActionVariant;
+    size?: "2xs" | "xs" | "sm" | "md";
+    radius?: NxButtonRadius;
+    selected?: boolean;
+    className?: string;
+}
+export interface NxIconLinkProps extends Omit<AnchorHTMLAttributes<HTMLAnchorElement>, "aria-label" | "children" | "href" | "onClick" | "size"> {
+    href: string;
+    "aria-label": string;
+    children: ReactNode;
+    variant?: NxActionVariant;
+    size?: "2xs" | "xs" | "sm" | "md";
+    radius?: NxButtonRadius;
+    selected?: boolean;
+    className?: string;
+}
+export interface NxCheckboxProps extends Omit<InputHTMLAttributes<HTMLInputElement>, "size" | "type"> {
+    inputSize?: "sm" | "md";
+    indeterminate?: boolean;
+    label?: string;
+}
+export interface NxRadioGroupProps {
+    name?: string;
+    value?: string;
+    onChange?: (value: string) => void;
+    disabled?: boolean;
+    "aria-label"?: string;
+    "aria-labelledby"?: string;
+    orientation?: "vertical" | "horizontal";
+    children: ReactNode;
+    className?: string;
+}
+export interface NxRadioProps extends Omit<InputHTMLAttributes<HTMLInputElement>, "size" | "type" | "value" | "onChange"> {
+    /** Card presentation retains the native radio and group selection behavior. */
+    variant?: "default" | "card";
+    inputSize?: "sm" | "md";
+    label?: ReactNode;
+    value: string;
+}
+export interface NxDetailRowProps {
+    label: ReactNode;
+    children: ReactNode;
+    className?: string;
+    testId?: string;
+}
+export type NxAdaptiveSplitDensity = "compact" | "default";
+export type NxAdaptiveSplitAsideWidth = "narrow" | "default" | "wide";
+export type NxAdaptiveSplitBreakpoint = "compact" | "default" | "wide";
+export interface NxResponsiveRegionProps extends HTMLAttributes<HTMLDivElement> {
+    children: ReactNode;
+}
+export interface NxAdaptiveSplitProps extends Omit<HTMLAttributes<HTMLDivElement>, "children"> {
+    children: ReactNode;
+    containerClassName?: string;
+    density?: NxAdaptiveSplitDensity;
+    asideWidth?: NxAdaptiveSplitAsideWidth;
+    twoColumnAt?: NxAdaptiveSplitBreakpoint;
+}
+export interface NxEmptyViewProps {
+    kind: "permission" | "empty" | "noResults" | "notFound" | "error";
+    icon?: ReactNode;
+    title?: ReactNode;
+    description?: ReactNode;
+    children?: ReactNode;
+    "data-testid"?: string;
+    className?: string;
+}
+export type NxFieldGroupProps = HTMLAttributes<HTMLDivElement>;
+export type NxFieldsetProps = FieldsetHTMLAttributes<HTMLFieldSetElement>;
+export type NxFieldLegendProps = HTMLAttributes<HTMLLegendElement>;
+export interface NxFileDropzoneProps {
+    accept?: string;
+    disabled?: boolean;
+    onFile: (file: File) => void;
+    prompt: ReactNode;
+    browseLabel: string;
+    hint?: ReactNode;
+    selectedFileName?: string | null;
+    inputLabel: string;
+    "data-testid"?: string;
+}
+export interface NxOrgChartMember {
+    id: string;
+    label: string;
+    description?: string | null;
+}
+export interface NxOrgChartItem {
+    id: string;
+    parentId: string | null;
+    label: string;
+    description?: string | null;
+    classification?: string | null;
+    meta?: string | null;
+    secondaryMeta?: string | null;
+    accentColor?: string | null;
+    members?: readonly NxOrgChartMember[] | null;
+    membersExpanded?: boolean;
+    selectable?: boolean;
+}
+export interface NxOrgChartLabels {
+    canvas: string;
+    focusNode: (label: string) => string;
+    clearFocus: string;
+    expandSubtree: (label: string) => string;
+    collapseSubtree: (label: string) => string;
+    showAllMembers: string;
+    hideAllMembers: string;
+    showMembers: (label: string, count: number) => string;
+    hideMembers: (label: string, count: number) => string;
+    memberList: (label: string) => string;
+    arrangeCards: string;
+    resetLayout: string;
+    moveCard: (label: string) => string;
+    addChild: (label: string) => string;
+    addMember: (label: string) => string;
+    editColor: (label: string) => string;
+    visibleCount: (visible: number, total: number) => string;
+    truncated: (limit: number, total: number) => string;
+    root: string;
+    moveNode: (label: string) => string;
+    moveKeyboardHint: string;
+    movePreview: (movingLabel: string, parentLabel: string, position: number, total: number) => string;
+}
+/** Read-only App boundary for the host-owned organization chart renderer. */
+export interface NxOrgChartProps {
+    items: readonly NxOrgChartItem[];
+    searchQuery?: string;
+    selectedId?: string | null;
+    onSelect?: (id: string) => void;
+    labels: NxOrgChartLabels;
+    nodeLimit?: number;
+    className?: string;
+    testId?: string;
+}
+export interface NxFormFieldProps {
+    label: ReactNode;
+    labelTooltip?: ReactNode;
+    children: (context: {
+        id: string;
+        describedBy?: string;
+        invalid: boolean;
+    }) => ReactNode;
+    help?: ReactNode;
+    error?: ReactNode;
+    /** Blocks persistence when the owning form enforces the same constraint. */
+    required?: boolean;
+    /** Does not block Save; marks information needed before the resource is ready to use. */
+    readinessRequired?: boolean;
+    compact?: boolean;
+    className?: string;
+}
+export interface NxFormSectionProps {
+    id?: string;
+    children: ReactNode;
+    onSubmit?: (event: FormEvent<HTMLFormElement>) => void;
+    error?: ReactNode;
+    actions?: ReactNode;
+    destructiveSlot?: ReactNode;
+    actionsVariant?: "default" | "wizard";
+    placement?: "footer" | "header";
+    mirrorBottom?: boolean;
+    testId?: string;
+    className?: string;
+    /**
+     * Use `stack` for fields within one section and `section` when the direct
+     * children are independent top-level section cards.
+     */
+    spacing: "stack" | "section";
+    contentClassName?: string;
+    actionsClassName?: string;
+}
+export interface NxLoadingBlockProps {
+    shape: "text" | "members" | "tree";
+    label: string;
+    lines?: number;
+    "data-testid"?: string;
+}
+export interface NxPageFrameProps {
+    title?: ReactNode;
+    subtitle?: ReactNode;
+    showHeader?: boolean;
+    actions?: ReactNode;
+    /** Compact controls for the current breadcrumb destination. */
+    breadcrumbActions?: ReactNode;
+    /** Page-owned organization read scope, rendered separately from command actions. */
+    organizationScope?: ReactNode;
+    breadcrumb?: ReactNode | false;
+    currentLabel?: ReactNode;
+    sidebar?: ReactNode;
+    sidebarLabel?: string;
+    maxWidth?: "3xl" | "5xl" | "7xl" | "none";
+    children: ReactNode;
+    beforeContent?: ReactNode;
+    testId?: string;
+}
+export interface NxTabNavItem {
+    id: string;
+    label: ReactNode;
+    badge?: ReactNode;
+    testId?: string;
+    disabled?: boolean;
+}
+/** Shared underline tab navigation for in-place App workspace sections. */
+export interface NxTabNavProps {
+    items: NxTabNavItem[];
+    value: string;
+    onChange: (id: string) => void;
+    "aria-label"?: string;
+    className?: string;
+    scrollable?: boolean;
+}
+export interface NxSearchFieldProps {
+    id?: string;
+    name?: string;
+    value: string;
+    onChange: (value: string) => void;
+    placeholder?: string;
+    autoFocus?: boolean;
+    disabled?: boolean;
+    className?: string;
+    "aria-label"?: string;
+    "data-testid"?: string;
+}
+export interface NxSectionCardProps {
+    title?: ReactNode;
+    description?: ReactNode;
+    actions?: ReactNode;
+    headerTestId?: string;
+    bodyTestId?: string;
+    children: ReactNode;
+    className?: string;
+    layout?: "default" | "rows" | "fullBleed";
+    as?: "section" | "div" | "article";
+    bordered?: boolean;
+}
+/** Canonical vertical rhythm for sibling sections outside a route frame. */
+export type NxSectionStackProps = HTMLAttributes<HTMLDivElement>;
+export interface NxSelectOption<TValue extends string | number> {
+    value: TValue;
+    label: ReactNode;
+    disabled?: boolean;
+}
+export interface NxSelectProps<TValue extends string | number> {
+    value: TValue | null;
+    options: readonly NxSelectOption<TValue>[];
+    onChange: (value: TValue) => void;
+    placeholder: ReactNode;
+    ariaLabel: string;
+    id?: string;
+    describedBy?: string;
+    invalid?: boolean;
+    disabled?: boolean;
+    fullWidth?: boolean;
+    size?: "xs" | "sm" | "md";
+    align?: "start" | "end";
+    side?: "top" | "bottom" | "left" | "right";
+    className?: string;
+    contentClassName?: string;
+}
+/** Arrow glyph for a period-over-period change. */
+export type NxStatDeltaDirection = "up" | "down" | "flat";
+/**
+ * Whether the change is good, bad, or neither *for this metric*. Kept
+ * independent of the direction: a rising defect count is `up`/`negative`.
+ */
+export type NxStatDeltaTone = "positive" | "negative" | "neutral";
+export interface NxStatDelta {
+    /** Already-formatted change, e.g. `+12`. The caller owns the unit. */
+    value: ReactNode;
+    direction: NxStatDeltaDirection;
+    tone: NxStatDeltaTone;
+    /** Sentence for assistive tech, e.g. "12 more than the previous 30 days". */
+    srLabel?: string;
+}
+export interface NxOverviewBandCard {
+    key: string;
+    label: ReactNode;
+    /**
+     * Raw count; the band applies locale formatting. `undefined` means the
+     * figure could not be counted — the band prints the shared empty-cell
+     * text rather than a `0`, and an attention card gets no verdict glyph.
+     */
+    value: number | undefined;
+    hint?: ReactNode;
+    /** Period-over-period change, where one genuinely exists. */
+    delta?: NxStatDelta;
+    /** First load only — a figure already on screen must not re-shimmer. */
+    loading?: boolean;
+    /** Canonical route for the list the card counts. */
+    href?: string;
+    testId?: string;
+}
+export interface NxOverviewBandProps {
+    title: ReactNode;
+    description?: ReactNode;
+    /**
+     * Effective date or timestamp exactly as the API returned it; the band
+     * formats it in the reader's locale and the tenant's business timezone.
+     * A date-only value prints as a date, a timestamp as a date and time.
+     */
+    asOf?: Date | string | null;
+    /**
+     * `attention` bands carry the 0-is-good state glyph on each card:
+     * a check when clear, a warning triangle when someone has to act.
+     */
+    variant?: "attention" | "default";
+    /** Band-level control right of the heading — typically a retry. */
+    actions?: ReactNode;
+    /** An empty list renders nothing — no aspirational empty bands. */
+    cards: NxOverviewBandCard[];
+    testId?: string;
+}
+export interface NxStatCardProps {
+    label: ReactNode;
+    value: ReactNode;
+    hint?: ReactNode;
+    icon?: ReactNode;
+    /** Optional — a card counting rows has no previous period to compare. */
+    delta?: NxStatDelta;
+    /**
+     * Data freshness, rendered last so a stale figure cannot read as live.
+     * A free slot on this primitive: it takes already-rendered content.
+     * Apps should reach for `NxOverviewBand`, which takes the API's raw
+     * value and formats it for them.
+     */
+    asOf?: ReactNode;
+    /** Optional canonical route. A static card omits it. */
+    href?: string;
+    /** Swaps the value for a same-height skeleton (no layout shift). */
+    loading?: boolean;
+    bordered?: boolean;
+    className?: string;
+    testId?: string;
+}
+/** Ranges the shell resolves itself. `custom` defers to explicit dates. */
+export type InsightRangePreset = "7d" | "30d" | "90d" | "qtd" | "ytd" | "custom";
+export interface InsightFilterState {
+    range: InsightRangePreset;
+    /** Resolved inclusive start, `YYYY-MM-DD` — ready to send as a param. */
+    from: string;
+    /** Resolved inclusive end, `YYYY-MM-DD`. */
+    through: string;
+    isCustom: boolean;
+}
+export interface InsightFilterControls extends InsightFilterState {
+    setRange: (preset: InsightRangePreset) => void;
+    /** Switches to `custom` and writes both dates in one URL update. */
+    setCustomRange: (from: string, through: string) => void;
+    reset: () => void;
+}
+export interface UseInsightFilterStateOptions {
+    /** Preset used when the URL says nothing. Default `30d`. */
+    defaultRange?: InsightRangePreset;
+    /** Query-param namespace for pages holding more than one range. */
+    scope?: string;
+    /** Reference "today" as `YYYY-MM-DD`; pins the window in tests. */
+    today?: string;
+}
+export interface NxInsightFilterBarProps {
+    filter: InsightFilterControls;
+    /** Presets to offer, in order. Trim when a window makes no sense. */
+    presets?: readonly InsightRangePreset[];
+    /** App-specific dimension filters. */
+    children?: ReactNode;
+    testId?: string;
+}
+/** The subset of a react-query result `NxInsightSurface` reads. */
+export interface InsightQueryLike {
+    isLoading: boolean;
+    isError: boolean;
+    isFetching?: boolean;
+    refetch?: () => unknown;
+}
+export interface NxInsightSurfaceProps {
+    appKey: string;
+    title: string;
+    subtitle: string;
+    context: {
+        isLoading: boolean;
+        isError: boolean;
+        legalEntityPublicId: string | null;
+    };
+    /** False for a missing permission or a 401/403; neither offers retry. */
+    canRead: boolean;
+    query: InsightQueryLike;
+    /** True when the query succeeded but the window holds nothing. */
+    isEmpty?: boolean;
+    /** Override the normal-state refresh when one insight owns multiple queries. */
+    refresh?: {
+        onRefresh: () => void | Promise<void>;
+        isRefreshing?: boolean;
+    };
+    /**
+     * Freshness as the API returned it (typically `generated_at`); the
+     * surface formats it, so a raw ISO instant never reaches the screen.
+     */
+    asOf?: ReactNode;
+    /** App-owned content rendered before the standard date filter. */
+    beforeFilter?: ReactNode;
+    filter?: ReactNode;
+    stats?: ReactNode;
+    chart?: ReactNode;
+    chartTitle?: string;
+    chartDescription?: string;
+    /** A compact `ResourceTable`; omit toolbar and footer for an embedded view. */
+    table?: ReactNode;
+    tableTitle?: string;
+    tableDescription?: string;
+    children?: ReactNode;
+    actions?: ReactNode;
+    organizationScope?: ReactNode;
+    testId?: string;
+}
+export interface NxStatusBadgeProps {
+    variant?: "neutral" | "muted" | "accent" | "info" | "success" | "warning" | "error";
+    children: ReactNode;
+    className?: string;
+    testId?: string;
+}
+export interface NxTextAreaProps extends Omit<TextareaHTMLAttributes<HTMLTextAreaElement>, "size"> {
+    inputSize?: "md" | "lg";
+    mono?: boolean;
+    invalid?: boolean;
+    autoResize?: boolean;
+    resizable?: boolean;
+}
+export interface NxTextInputProps extends Omit<InputHTMLAttributes<HTMLInputElement>, "size"> {
+    inputSize?: "md" | "lg";
+    appearance?: "field" | "title";
+    mono?: boolean;
+    invalid?: boolean;
+}
+export interface NxDatePickerLabels {
+    calendar: string;
+    clear: string;
+    nextMonth: string;
+    openCalendar: string;
+    previousMonth: string;
+    today: string;
+}
+export interface NxDatePickerProps {
+    value: string | null;
+    onChange: (value: string | null) => void;
+    label?: ReactNode;
+    labelTooltip?: ReactNode;
+    "aria-label"?: string;
+    "aria-describedby"?: string;
+    placeholder?: string;
+    min?: string;
+    max?: string;
+    disabled?: boolean;
+    required?: boolean;
+    clearable?: boolean;
+    help?: ReactNode;
+    error?: ReactNode;
+    /** Invalid state supplied by a surrounding form field. */
+    invalid?: boolean;
+    locale?: string;
+    labels?: Partial<NxDatePickerLabels>;
+    id?: string;
+    name?: string;
+    className?: string;
+    "data-testid"?: string;
+}
+export interface NxDateRangeValue {
+    start: string | null;
+    end: string | null;
+}
+export interface NxDateRangePickerProps {
+    value: NxDateRangeValue;
+    onChange: (value: NxDateRangeValue) => void;
+    label?: ReactNode;
+    labelTooltip?: ReactNode;
+    "aria-label"?: string;
+    "aria-describedby"?: string;
+    invalid?: boolean;
+    placeholder?: string;
+    min?: string;
+    max?: string;
+    disabled?: boolean;
+    required?: boolean;
+    clearable?: boolean;
+    help?: ReactNode;
+    error?: ReactNode;
+    locale?: string;
+    labels?: Partial<NxDatePickerLabels>;
+    id?: string;
+    startName?: string;
+    endName?: string;
+    className?: string;
+    "data-testid"?: string;
+}
+export type NxTooltipSide = "top" | "bottom" | "left" | "right";
+export type NxTooltipAlign = "start" | "center" | "end";
+export interface NxTooltipProps {
+    content: ReactNode;
+    children: ReactElement;
+    side?: NxTooltipSide;
+    align?: NxTooltipAlign;
+    delay?: number;
+    disabled?: boolean;
+    className?: string;
+}
+export interface NxHelpTooltipProps {
+    content: ReactNode;
+    label?: string;
+    side?: NxTooltipSide;
+    align?: NxTooltipAlign;
+    className?: string;
+}
+export interface AppRouteFrameProps {
+    appKey: string;
+    title: string;
+    subtitle: string;
+    actions?: ReactNode;
+    /** Page-owned organization read scope, rendered separately from command actions. */
+    organizationScope?: ReactNode;
+    breadcrumbs?: Array<{
+        label: ReactNode;
+        href?: string;
+        current?: boolean;
+    }>;
+    currentLabel?: ReactNode;
+    maxWidth?: "3xl" | "5xl" | "7xl" | "none";
+    testId?: string;
+    children: ReactNode;
+}
+/** Host-rendered canonical route inside a management workspace side pane. */
+export interface NxCanonicalRoutePaneProps {
+    open: boolean;
+    route: string;
+    closeRoute?: string;
+    title: string;
+    onOpenChange: (open: boolean) => void;
+    testId?: string;
+}
+export interface WorkSurfaceProps {
+    primary: ReactNode;
+    primaryLabel?: string;
+    inspector?: ReactNode;
+    inspectorTestId?: string;
+    inspectorLabel?: string;
+    resizeLabel?: string;
+}
+export interface WorkSectionProps {
+    title?: ReactNode;
+    description?: ReactNode;
+    actions?: ReactNode;
+    children: ReactNode;
+    testId?: string;
+    headerTestId?: string;
+    bodyTestId?: string;
+    className?: string;
+    bodyClassName?: string;
+    layout?: "default" | "rows" | "fullBleed";
+}
+export type WorkSurfaceAction = "list" | "show" | "create" | "edit";
+export interface TabContextActionResult {
+    ok: boolean;
+    message: string;
+    data?: Record<string, unknown>;
+    issues?: string[];
+}
+export interface TabContextActionContext {
+    tabId: string;
+    signal?: AbortSignal;
+}
+export interface TabContextActionRegistration {
+    type: string;
+    label: string;
+    description?: string;
+    inputSchema?: Record<string, unknown>;
+    run: (payload: Record<string, unknown>, context: TabContextActionContext) => TabContextActionResult | Promise<TabContextActionResult>;
+}
+export interface WorkSurfaceLabelInput {
+    action: WorkSurfaceAction;
+    resourceLabel: string;
+    recordLabel?: string | null;
+}
+export interface WorkSurfaceLabels {
+    title: string;
+    breadcrumbLabel: string;
+    tabLabel: string;
+    createButtonLabel: string;
+    submitLabel: string | null;
+}
+export type ToastSource = "local" | "operation" | "notification" | "agent" | "background" | "system";
+export interface ToastOptions {
+    description?: string;
+    duration?: number;
+    action?: {
+        label: string;
+        onAction: () => void;
+    };
+    /** Stable, namespaced identity used to refresh instead of duplicate. */
+    dedupeKey?: string;
+    source?: ToastSource;
+}
+export interface MessageApi {
+    toast: Record<"info" | "success" | "warning" | "error", (title: string, options?: ToastOptions) => void>;
+    banner: Record<"info" | "success" | "warning" | "error", (title: string, options?: {
+        description?: string;
+        dismissible?: boolean;
+    }) => void>;
+    confirm: (title: string, options?: {
+        description?: string;
+        confirmLabel?: string;
+        cancelLabel?: string;
+        variant?: "default" | "destructive";
+    }) => Promise<boolean>;
+    prompt: (title: string, options?: {
+        description?: string;
+        label?: string;
+        placeholder?: string;
+        defaultValue?: string;
+        inputType?: "text" | "password";
+        maxLength?: number;
+        submitLabel?: string;
+        cancelLabel?: string;
+        required?: boolean;
+        normalizeValue?: (value: string) => string;
+        validate?: (value: string) => string | null;
+    }) => Promise<string | null>;
+}
+export interface ListLocateRecord {
+    id: string;
+    label?: string;
+    hint?: string;
+    showUrl?: string;
+    editUrl?: string;
+}
+export interface UseRegisterListLocateActionOptions<Row> {
+    actionType: string;
+    label: string;
+    description?: string;
+    enabled: boolean;
+    schema: ResourceListSchema | undefined;
+    params: Pick<ResourceListParamsControls, "setParams" | "perPage">;
+    fetchPage: (params: ResourceListParams) => Promise<{
+        rows: Row[];
+        total: number | null;
+    }>;
+    resolveRow: (row: Row) => ListLocateRecord;
+    onMatch: (row: Row) => void;
+}
+export interface OpenResourceWorkTabOptions {
+    route?: string;
+    label?: string;
+    icon?: string;
+    resourceType?: string;
+    resourceId?: string;
+    openInNewTab?: boolean;
+    contextualCreate?: ResourceCreateContinuationTarget;
+}
+export type OpenResourceWorkTab = (resource: WorkTabRef, options?: OpenResourceWorkTabOptions) => void;
+export type PackageSurfaceLoader = () => Promise<{
+    default: ComponentType<Record<never, never>>;
+}>;
+/**
+ * Explicit override registration that also carries a *synchronous* route
+ * prefetcher, i.e. one that seeds its queries without first awaiting the
+ * surface chunk.
+ *
+ * A bare loader override still works and stays the default: its module-level
+ * `prefetch` export runs after the chunk resolves, so data loading serializes
+ * behind the chunk download. Supplying `routePrefetcher` moves the data
+ * request onto the same tick as the chunk request.
+ *
+ * Returning `true` marks the route as handled and suppresses the module-level
+ * `prefetch` fallback. Returning `false` — e.g. when the actor lacks the
+ * Permission or a required route param is missing — falls back to the
+ * module-level `prefetch`.
+ *
+ * The prefetcher must not import the surface component module eagerly, or the
+ * surface is pulled into the package entry chunk and code-splitting is lost.
+ */
+export interface PackageSurfaceOverrideRegistration {
+    load: PackageSurfaceLoader;
+    routePrefetcher?: AppRoutePrefetcher;
+}
+export type PackageSurfaceOverride = PackageSurfaceLoader | PackageSurfaceOverrideRegistration;
+export interface AutoRegisterPackageSurfacesOptions {
+    appPrefix: string;
+    appKey?: string;
+    overview?: PackageSurfaceLoader;
+    surfaces: Record<string, () => Promise<unknown>>;
+    overrides?: Record<string, PackageSurfaceOverride>;
+}
+export interface AppRoutePrefetchContext {
+    queryClient: QueryClient;
+    tenantId: string;
+    legalEntityPublicId: string | null;
+    permissions: PermissionsResponse;
+    pathname: string;
+    searchParams: URLSearchParams;
+    routePattern: string;
+    params: Readonly<Record<string, string | undefined>>;
+}
+/**
+ * Route-level prefetcher. Resolves to `true` when the route was handled and
+ * the module-level `prefetch` fallback should be skipped.
+ */
+export type AppRoutePrefetcher = (context: AppRoutePrefetchContext) => Promise<boolean> | boolean;
+export type FormFieldErrors = Record<string, string>;
+export interface MutationFormError {
+    formError: string | null;
+    fieldErrors: FormFieldErrors;
+}
+export {};