@mercurjs/dashboard-shared 2.2.0-rc.0 → 2.2.0-rc.2

package/dist/index.d.ts

@@ -5,15 +5,16 @@ import * as React$1 from 'react';
 import React__default, { ReactNode, PropsWithChildren, ComponentPropsWithoutRef, CSSProperties, ComponentType, Ref, RefCallback } from 'react';
 import { Tooltip, Heading, Text, DataTableColumnDef, DataTableFilter, DataTableCommand, DataTableEmptyStateProps, DataTableRowSelectionState, DataTableRow, Drawer, FocusModal, ProgressStatus } from '@medusajs/ui';
 import * as react_hook_form from 'react-hook-form';
-import { FieldValues, FieldPath, ControllerProps, UseFormReturn, Control } from 'react-hook-form';
-import { Label, Slot } from 'radix-ui';
+import { FieldValues, FieldPath, ControllerProps, UseFormReturn, Control, UseFormProps } from 'react-hook-form';
+import { Label } from 'radix-ui';
 import { Link, Path } from 'react-router-dom';
 import { UniqueIdentifier } from '@dnd-kit/core';
 import * as _tanstack_react_table from '@tanstack/react-table';
 import { CellContext, Row, ColumnDef, ColumnDefTemplate, HeaderContext, Table, RowSelectionState, OnChangeFn } from '@tanstack/react-table';
 import { TFunction } from 'i18next';
-import { z } from 'zod';
+import { z, ZodObject } from 'zod';
 import { ClientError } from '@mercurjs/client';
+import { CustomFieldsConfig, NavItemOverride, CustomFormField, CustomDisplayField, SectionAction, CustomListExtension } from '@mercurjs/dashboard-sdk';
 
 type TQueryKey<TKey, TListQuery = any, TDetailQuery = string> = {
     all: readonly [TKey];
@@ -284,7 +285,9 @@ declare const Form: (<TFieldValues extends FieldValues, TContext = any, TTransfo
         tooltip?: ReactNode;
         icon?: ReactNode;
     } & React__default.RefAttributes<HTMLLabelElement>>;
-    Control: React__default.ForwardRefExoticComponent<Omit<Slot.SlotProps & React__default.RefAttributes<HTMLElement>, "ref"> & React__default.RefAttributes<HTMLElement>>;
+    Control: React__default.ForwardRefExoticComponent<Omit<React__default.HTMLAttributes<HTMLElement> & {
+        children?: React__default.ReactNode;
+    } & React__default.RefAttributes<HTMLElement>, "ref"> & React__default.RefAttributes<HTMLElement>>;
     Hint: React__default.ForwardRefExoticComponent<React__default.HTMLAttributes<HTMLParagraphElement> & React__default.RefAttributes<HTMLParagraphElement>>;
     ErrorMessage: React__default.ForwardRefExoticComponent<React__default.HTMLAttributes<HTMLParagraphElement> & React__default.RefAttributes<HTMLParagraphElement>>;
     Field: <TFieldValues extends FieldValues = FieldValues, TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>>({ ...props }: ControllerProps<TFieldValues, TName>) => react_jsx_runtime.JSX.Element;
@@ -1023,6 +1026,8 @@ type TabbedFormProps<T extends FieldValues> = {
     isLoading?: boolean;
     footer?: (props: FooterRenderProps) => ReactNode;
     transformTabs?: (tabs: TabDefinition<T>[]) => TabDefinition<T>[];
+    model?: string;
+    zone?: string;
 };
 declare function Root<T extends FieldValues>({ form, onSubmit, children, isLoading, footer, transformTabs, }: TabbedFormProps<T>): react_jsx_runtime.JSX.Element;
 declare const TabbedForm: typeof Root & {
@@ -1264,4 +1269,308 @@ type QueryParams<T extends string> = {
 };
 declare function useQueryParams<T extends string>(keys: T[], prefix?: string): QueryParams<T>;
 
-export { type Action, type ActionGroup, ActionMenu, AddressForm, type AttributeChange, type AttributeChangeKind, BadgeListSummary, ChipGroup, CodeCell, CodeHeader, type Command, ConditionalTooltip, ConfirmPrompt, type ConfirmPromptProps, CreatedAtCell, CreatedAtHeader, CustomerInfo, DataGrid, DataTable, DateCell, DateHeader, DateRangeDisplay, EmailCell, EmailForm, EmailHeader, type FieldDiff, FilePreview, type FileType, FileUpload, type FileUploadProps, type Filter, FilterGroup, Form, GeneralSectionSkeleton, HeadingSkeleton, IconAvatar, IconButtonSkeleton, ImageAvatar, type ImageRef, IncludesTaxTooltip, InfiniteList, JsonViewSection, JsonViewSectionSkeleton, LinkButton, ListBadge, ListSummary, Listicle, type ListicleProps, type MediaDiff, MetadataForm, MetadataSection, MoneyAmountCell, NameCell, NameHeader, NoRecords, NoResults, type NoResultsProps, OrderBy, PlaceholderCell, type ProductChangeAttribute, ProductChangePanel, type ProductChangePanelProps, type ProductChangeProduct, type ProductChangeResolvers, type ProductChangeVariant, type ProductChangeView, ProgressBar, Query, REFERENCE_FIELDS, type ReferenceField, type ResolvedAttribute, RouteDrawer, RouteFocusModal, SectionRow, type SectionRowProps, SegmentedControl, type SegmentedControlOption, SidebarLink, type SidebarLinkProps, SingleColumnPage, SingleColumnPageSkeleton, Skeleton, SortableList, SortableTree, StackedDrawer, StackedFocusModal, StatusCell, SwitchBox, type TQueryKey, type TabDefinition, TabbedForm, TableFooterSkeleton, TableSectionSkeleton, TableSkeleton, TextCell, TextHeader, TextSkeleton, Thumbnail, TwoColumnPage, TwoColumnPageSkeleton, type UseQueryOptionsWrapper, type VariantGroup, _DataTable, buildProductChangeView, createDataGridHelper, createDataGridPriceColumns, extractReferenceIds, formatFieldValue, humanizeFieldName, isImageList, isReferenceField, productChangeViewHasContent, queryKeysFactory, useCombinedRefs, useCommandHistory, useDataTable, useDate, useDocumentDirection, useQueryParams, useRouteModal, useStackedModal, useTabManagement, useTabbedForm };
+type WidgetPlacement = "before" | "after";
+type Widget = {
+    Component: ComponentType<{
+        data?: unknown;
+    }>;
+    zone: string[];
+    widgetId: string;
+};
+type WidgetModule = {
+    widgets?: Widget[];
+};
+type NavigationModule = {
+    items?: NavItemOverride[];
+};
+type CustomFieldsModule = {
+    configs?: CustomFieldsConfig[];
+};
+type ResolvedFormField = {
+    name: string;
+    field: CustomFormField;
+};
+type ResolvedDisplays = {
+    fields: CustomDisplayField[];
+    actions: SectionAction[];
+};
+type ResolvedWidget = {
+    Component: Widget["Component"];
+    widgetId: string;
+};
+type ZoneWidgets = {
+    before: ResolvedWidget[];
+    after: ResolvedWidget[];
+};
+/**
+ * Per-panel singleton mirroring Medusa's `DashboardApp`. Built once at app root
+ * from the aggregated `virtual:mercur/{widgets,navigation}` modules; the zone
+ * hosts read from it via `useExtension()`.
+ */
+declare class ExtensionRegistry {
+    private widgets;
+    private navOverrides;
+    private customFields;
+    constructor(input?: {
+        widgets?: WidgetModule;
+        navigation?: NavigationModule;
+        customFields?: CustomFieldsModule;
+    });
+    private ensureSlot;
+    private populateWidgets;
+    getWidgets(slot: string): ZoneWidgets;
+    getNavOverrides(): NavItemOverride[];
+    private configsFor;
+    /** Distinct module links declared across a model's configs. */
+    getLinks(model: string): string[];
+    /** Custom form fields for a model's form zone (and optional tab). */
+    getFormFields(model: string, zone: string, tab?: string): ResolvedFormField[];
+    /** All custom form fields for a model, keyed for schema/default building. */
+    getAllFormFields(model: string): ResolvedFormField[];
+    /** Section display contributions (field add/replace/remove + actions). */
+    getDisplays(model: string, zone: string): ResolvedDisplays;
+    /** Merged list-table extension for a model. */
+    getListExtension(model: string): CustomListExtension;
+}
+
+type ExtensionProviderProps = {
+    widgets?: WidgetModule;
+    navigation?: NavigationModule;
+    customFields?: CustomFieldsModule;
+    children: ReactNode;
+};
+/**
+ * Reads the panel's extension registry outside React (e.g. in a react-router
+ * `loader`, which can't call hooks). Returns null until `ExtensionProvider` has
+ * mounted; callers should fall back to built-in behavior when null.
+ */
+declare const getExtensionRegistry: () => ExtensionRegistry | null;
+declare const ExtensionProvider: ({ widgets, navigation, customFields, children, }: ExtensionProviderProps) => react_jsx_runtime.JSX.Element;
+/**
+ * Reads the panel's extension registry. Returns an empty registry when no
+ * provider is mounted so hosts render their built-in content untouched.
+ */
+declare const useExtension: () => ExtensionRegistry;
+
+type WidgetZoneProps = {
+    /** Stable slot id, e.g. `product.list` or `product.detail`. Placement suffixes
+     * (`before | after | replace`) are matched against it at render time. */
+    id: string;
+    /** Optional data passed to each widget component (e.g. the detail entity). */
+    data?: unknown;
+    /** The built-in content, rendered between `before` and `after` widgets. */
+    children?: ReactNode;
+};
+/**
+ * Injection-zone host. Renders `before` widgets → the built-in child →
+ * `after` widgets. A zone that no page renders as a host can never be targeted.
+ */
+declare const WidgetZone: ({ id, data, children }: WidgetZoneProps) => react_jsx_runtime.JSX.Element;
+
+type CoreNavItem = {
+    id: string;
+    label: string;
+    to: string;
+    icon?: ReactNode;
+    items?: CoreNavItem[];
+};
+/**
+ * Applies host-owned `_navigation.ts` overrides to a panel's built-in core
+ * routes: reorder (`rank`), hide (`hidden`), relabel (`label`/`icon`), and
+ * re-parent (`nested`). Operates on the two-level `useCoreRoutes()` shape;
+ * items without a matching override are preserved in their original order.
+ */
+declare function applyNavOverrides(coreRoutes: CoreNavItem[], overrides?: NavItemOverride[]): CoreNavItem[];
+
+type FormExtensionZoneProps = {
+    model: string;
+    zone: string;
+    tab?: string;
+    control: Control<any>;
+    data?: unknown;
+};
+/**
+ * Renders a model's custom form fields for a given zone/tab under the
+ * `additional_data.<field>` RHF namespace (Medusa's convention), through the
+ * mandated `Form.Field → Form.Item` primitive chain.
+ */
+declare const FormExtensionZone: ({ model, zone, tab, control, data, }: FormExtensionZoneProps) => react_jsx_runtime.JSX.Element | null;
+
+type DisplayExtensionZoneProps = {
+    model: string;
+    zone: string;
+    data?: unknown;
+    /**
+     * Ids of the section's built-in fields — those are overridden inline by
+     * `<DisplayField>`, so the zone skips them and only renders genuinely added
+     * fields (unknown ids). Defaults to none.
+     */
+    builtInFieldIds?: string[];
+};
+/**
+ * Renders a model's ADDED section fields (non-null component, id not a built-in
+ * field) plus the section's custom `ActionMenu` contributions. Built-in fields
+ * are overridden in place by `<DisplayField>` / `useDisplayFieldOverride`.
+ */
+declare const DisplayExtensionZone: ({ model, zone, data, builtInFieldIds, }: DisplayExtensionZoneProps) => react_jsx_runtime.JSX.Element | null;
+type DisplayFieldProps = {
+    model: string;
+    zone: string;
+    /** Stable id of this built-in field (e.g. `title`, `description`). */
+    id: string;
+    data?: unknown;
+    /** The built-in default rendering, shown when there is no override. */
+    children?: ReactNode;
+};
+/**
+ * Wraps a single built-in detail field so a `displays[].fields` entry can
+ * override its render (a different `component`) or remove it (`component: null`).
+ * With no matching override, renders the built-in `children` unchanged. This is
+ * the host the panel codegen scans to type `displayFieldIds`.
+ */
+declare const DisplayField: ({ model, zone, id, data, children, }: DisplayFieldProps) => react_jsx_runtime.JSX.Element | null;
+type DisplaySectionField = {
+    /** Stable id of the built-in field (matches a `displays[].fields[].id`). */
+    id: string;
+    /** The built-in default rendering (e.g. a `<SectionRow />`). */
+    render: ReactNode;
+};
+type DisplaySectionProps = {
+    model: string;
+    zone: string;
+    data?: unknown;
+    /** Built-in fields of this section, each overridable/removable by id. */
+    fields: DisplaySectionField[];
+};
+/**
+ * One-line helper for a row-style detail section: renders each built-in field
+ * through `<DisplayField>` (so `displays[].fields` can replace/remove it) and
+ * appends the section's added fields + actions via `<DisplayExtensionZone>`,
+ * deriving `builtInFieldIds` from `fields`.
+ */
+declare const DisplaySection: ({ model, zone, data, fields, }: DisplaySectionProps) => react_jsx_runtime.JSX.Element;
+/**
+ * For a built-in detail section to honor a `displays[].fields` override of one
+ * of its own fields: returns `{ overridden, Component }`. `overridden && !
+ * Component` means remove (render nothing); `Component` means replace.
+ */
+declare function useDisplayFieldOverride(model: string, zone: string, id: string): {
+    overridden: boolean;
+    Component: ComponentType<{
+        data?: unknown;
+    }> | null;
+};
+
+type UseExtendableTableProps<TData> = {
+    /** Model whose custom-fields `list` block extends this table (e.g. `product`). */
+    model: string;
+    /** Base columns to extend. */
+    columns: ColumnDef<TData, unknown>[];
+};
+type ExtendableTable<TData> = {
+    /** Base columns with custom override/add/hide/order applied. */
+    columns: ColumnDef<TData, unknown>[];
+    /** Extra list filters contributed by custom-fields configs. */
+    filters: unknown[];
+    /** Extra multi-select bulk actions (rank-sorted). */
+    bulkActions: SectionAction[];
+};
+/**
+ * Applies a model's custom-fields `list` block to a table's base columns —
+ * mirrors `useExtendableForm` for tables. A `columns[]` entry whose `id` matches
+ * a base column **overrides** it (custom header/cell), an unknown `id` **adds** a
+ * column, `viewDefaults.columnVisibility[id] === false` **hides** it, and
+ * `viewDefaults.columnOrder` reorders. Also surfaces the config's `filters` and
+ * `bulkActions` for the caller to render.
+ */
+declare function useExtendableTable<TData>({ model, columns: baseColumns, }: UseExtendableTableProps<TData>): ExtendableTable<TData>;
+
+/** Turn a model's `link` relations into `+link.*` merge tokens. */
+declare const linkFields: (links: string[]) => string;
+/**
+ * Merge a model's custom-fields `link` relations into a curated fields string
+ * using the `+` merge convention (`+link.*`), so linked-module data is fetched
+ * alongside the entity without replacing the route's default fields. Returns the
+ * base `fields` unchanged when there are no links.
+ */
+declare const withLinkFields: (fields: string, links: string[]) => string;
+/**
+ * Build a spreadable `{ fields }` query fragment that adds a model's custom-fields
+ * `link` relations. Pass `base` to merge onto a curated field set (list/detail
+ * queries); omit it to merge purely onto the route defaults (`+link.*` only), so
+ * unprefixed base fields never replace the route defaults. Returns `{}` (or
+ * `{ fields: base }`) when the model declares no links, leaving the fetch
+ * unchanged. Non-hook variant for react-router loaders.
+ */
+declare const getLinkQuery: (model: string, base?: string) => {
+    fields?: string;
+};
+/** Hook variant of {@link getLinkQuery} for use inside components. */
+declare const useLinkQuery: (model: string, base?: string) => {
+    fields?: string;
+};
+
+/**
+ * Zod-backed form surface (mirrors Medusa's `createFormHelper`, no `unstable_`).
+ * Lives here rather than in `@mercurjs/dashboard-sdk` because the SDK is a
+ * zod-free build-time package; re-exported from `@mercurjs/dashboard-sdk` for
+ * authoring parity is a docs concern only.
+ */
+declare function createFormHelper<TData>(): {
+    define: (field: CustomFormField<TData>) => CustomFormField<TData>;
+    string: () => z.ZodString;
+    number: () => z.ZodNumber;
+    boolean: () => z.ZodBoolean;
+    date: () => z.ZodDate;
+    array: <El extends z.ZodTypeAny>(schema: El, params?: z.RawCreateParams) => z.ZodArray<El>;
+    object: <Shape extends z.ZodRawShape>(shape: Shape, params?: z.RawCreateParams) => z.ZodObject<Shape, "strip", z.ZodTypeAny, z.objectOutputType<Shape, z.ZodTypeAny, "strip">, z.objectInputType<Shape, z.ZodTypeAny, "strip">>;
+    null: () => z.ZodNull;
+    nullable: <Inner extends z.ZodTypeAny>(type: Inner, params?: z.RawCreateParams) => z.ZodNullable<Inner>;
+    coerce: {
+        string: (typeof z.ZodString)["create"];
+        number: (typeof z.ZodNumber)["create"];
+        boolean: (typeof z.ZodBoolean)["create"];
+        bigint: (typeof z.ZodBigInt)["create"];
+        date: (typeof z.ZodDate)["create"];
+    };
+};
+/**
+ * Build the `additional_data` zod object for a model's custom fields, to merge
+ * into a form's base schema. Custom-field values live under `additional_data`
+ * so the built-in create/edit validators never see them.
+ */
+declare function buildAdditionalDataSchema(registry: ExtensionRegistry, model: string, zone?: string, tab?: string): z.ZodObject<Record<string, z.ZodTypeAny>>;
+/** Resolve default values for a model's custom fields from the loaded entity. */
+declare function buildAdditionalDataDefaults(registry: ExtensionRegistry, model: string, data?: unknown, zone?: string, tab?: string): Record<string, unknown>;
+
+type WithAdditionalData<T> = T & {
+    additional_data?: Record<string, unknown>;
+};
+interface UseExtendableFormProps<TSchema extends ZodObject<Record<string, z.ZodTypeAny>>, TContext = unknown, TData = unknown> extends Omit<UseFormProps<z.infer<TSchema>, TContext>, "resolver" | "defaultValues"> {
+    /** Base schema for the built-in fields. */
+    schema: TSchema;
+    /** Base default values for the built-in fields. */
+    defaultValues: z.infer<TSchema>;
+    /** Custom-field model whose fields extend this form (e.g. `"product"`). */
+    model: string;
+    /** Loaded entity, used to resolve custom-field default values. */
+    data?: TData;
+    /**
+     * Form zone (and optional tab) this form renders. When set, only custom
+     * fields registered for that zone extend the schema/defaults — so a required
+     * field defined for another zone (e.g. onboarding) doesn't block this form.
+     * Omit to include every field for the model (legacy behaviour).
+     */
+    zone?: string;
+    tab?: string;
+}
+/**
+ * `useForm` that merges a model's registered custom fields into the base
+ * schema and defaults under an `additional_data` key — mirrors Medusa's
+ * `useExtendableForm`. Custom-field values live under `additional_data` so the
+ * built-in validators never see them; the extension registry provides the
+ * per-field zod validation and default values.
+ */
+declare const useExtendableForm: <TSchema extends ZodObject<Record<string, z.ZodTypeAny>>, TContext = unknown, TTransformedValues extends FieldValues | undefined = undefined>({ schema: baseSchema, defaultValues: baseDefaultValues, model, data, zone, tab, ...props }: UseExtendableFormProps<TSchema, TContext>) => react_hook_form.UseFormReturn<WithAdditionalData<z.TypeOf<TSchema>>, TContext, TTransformedValues>;
+
+export { type Action, type ActionGroup, ActionMenu, AddressForm, type AttributeChange, type AttributeChangeKind, BadgeListSummary, ChipGroup, CodeCell, CodeHeader, type Command, ConditionalTooltip, ConfirmPrompt, type ConfirmPromptProps, type CoreNavItem, CreatedAtCell, CreatedAtHeader, type CustomFieldsModule, CustomerInfo, DataGrid, DataTable, DateCell, DateHeader, DateRangeDisplay, DisplayExtensionZone, type DisplayExtensionZoneProps, DisplayField, type DisplayFieldProps, DisplaySection, type DisplaySectionField, type DisplaySectionProps, EmailCell, EmailForm, EmailHeader, type ExtendableTable, ExtensionProvider, type ExtensionProviderProps, ExtensionRegistry, type FieldDiff, FilePreview, type FileType, FileUpload, type FileUploadProps, type Filter, FilterGroup, Form, FormExtensionZone, type FormExtensionZoneProps, GeneralSectionSkeleton, HeadingSkeleton, IconAvatar, IconButtonSkeleton, ImageAvatar, type ImageRef, IncludesTaxTooltip, InfiniteList, JsonViewSection, JsonViewSectionSkeleton, LinkButton, ListBadge, ListSummary, Listicle, type ListicleProps, type MediaDiff, MetadataForm, MetadataSection, MoneyAmountCell, NameCell, NameHeader, type NavigationModule, NoRecords, NoResults, type NoResultsProps, OrderBy, PlaceholderCell, type ProductChangeAttribute, ProductChangePanel, type ProductChangePanelProps, type ProductChangeProduct, type ProductChangeResolvers, type ProductChangeVariant, type ProductChangeView, ProgressBar, Query, REFERENCE_FIELDS, type ReferenceField, type ResolvedAttribute, type ResolvedDisplays, type ResolvedFormField, RouteDrawer, RouteFocusModal, SectionRow, type SectionRowProps, SegmentedControl, type SegmentedControlOption, SidebarLink, type SidebarLinkProps, SingleColumnPage, SingleColumnPageSkeleton, Skeleton, SortableList, SortableTree, StackedDrawer, StackedFocusModal, StatusCell, SwitchBox, type TQueryKey, type TabDefinition, TabbedForm, TableFooterSkeleton, TableSectionSkeleton, TableSkeleton, TextCell, TextHeader, TextSkeleton, Thumbnail, TwoColumnPage, TwoColumnPageSkeleton, type UseExtendableFormProps, type UseExtendableTableProps, type UseQueryOptionsWrapper, type VariantGroup, type Widget, type WidgetModule, type WidgetPlacement, WidgetZone, type WidgetZoneProps, type ZoneWidgets, _DataTable, applyNavOverrides, buildAdditionalDataDefaults, buildAdditionalDataSchema, buildProductChangeView, createDataGridHelper, createDataGridPriceColumns, createFormHelper, extractReferenceIds, formatFieldValue, getExtensionRegistry, getLinkQuery, humanizeFieldName, isImageList, isReferenceField, linkFields, productChangeViewHasContent, queryKeysFactory, useCombinedRefs, useCommandHistory, useDataTable, useDate, useDisplayFieldOverride, useDocumentDirection, useExtendableForm, useExtendableTable, useExtension, useLinkQuery, useQueryParams, useRouteModal, useStackedModal, useTabManagement, useTabbedForm, withLinkFields };