@tailor-platform/app-shell 0.33.0 → 0.34.0

package/dist/app-shell.d.ts

@@ -20,6 +20,7 @@ import { Menu as Menu_2 } from '@base-ui/react/menu';
 import * as React_2 from 'react';
 import { ReactNode } from 'react';
 import { Select as Select_2 } from '@base-ui/react/select';
+import { StandardSchemaV1 } from '@standard-schema/spec';
 import { toast } from 'sonner';
 import { Tooltip as Tooltip_2 } from '@base-ui/react/tooltip';
 import { useFilter } from 'node_modules/@base-ui/react/esm/combobox/index.parts';
@@ -59,6 +60,15 @@ declare interface ActionItem {
  * When an action has `loading: true`, the row shows a spinner in the icon slot and is
  * non-interactive (useful for backend-driven actions: parent sets loading from mutation/request state).
  *
+ * **CommandPalette integration** — Actions that are enabled (not `disabled`,
+ * not `loading`, and have an `onClick` handler) are automatically registered
+ * to the CommandPalette so users can discover and trigger them via keyboard
+ * shortcut. The actions are grouped under the panel's `title`. Registration
+ * is cleaned up when the ActionPanel unmounts.
+ *
+ * NOTE: This component must be rendered inside `AppShell` (which provides
+ * `CommandPaletteProvider`). Rendering it outside that tree will throw.
+ *
  * @example
  * ```tsx
  * const navigate = useNavigate();
@@ -418,6 +428,10 @@ declare type AuthProviderProps = {
      * Guard UI component to show when loading or unauthenticated.
      *
      * If not provided, children will be just rendered in any auth state.
+     *
+     * Note: This prop only takes effect when AuthProvider wraps an AppShell
+     * component. The guard is rendered by the router's root route element,
+     * so it requires RouterContainer to be present in the component tree.
      */
     guardComponent?: () => React.ReactNode;
 };
@@ -459,9 +473,9 @@ export declare const Autocomplete: typeof AutocompleteStandalone & {
         GroupLabel: typeof AutocompleteGroupLabel;
         Collection: typeof AutocompleteCollection;
         Status: AutocompleteStatus;
-        useFilter: (options?: AutocompleteFilterOptions) => AutocompleteFilter;
-        useAsync: typeof useAsync_2;
     };
+    useAsync: typeof useAsync_3;
+    useFilter: (options?: AutocompleteFilterOptions) => AutocompleteFilter;
 };
 
 /** Fetcher type for `Autocomplete.Async`. */
@@ -492,7 +506,9 @@ declare namespace AutocompleteCollection {
     var displayName: string;
 }
 
-declare function AutocompleteContent({ className, ...props }: React_2.ComponentProps<typeof Autocomplete_2.Popup>): JSX.Element;
+declare function AutocompleteContent({ className, container, ...props }: React_2.ComponentProps<typeof Autocomplete_2.Popup> & {
+    container?: React_2.ComponentProps<typeof Autocomplete_2.Portal>["container"];
+}): JSX.Element;
 
 declare namespace AutocompleteContent {
     var displayName: string;
@@ -561,6 +577,8 @@ declare interface AutocompletePropsBase<T> {
     className?: string;
     /** Whether the autocomplete is disabled */
     disabled?: boolean;
+    /** A parent element to render the portal into (e.g. a modal/drawer ref). */
+    container?: React_2.ComponentProps<typeof AutocompleteContent>["container"];
     /** Current value (controlled) */
     value?: string;
     /** Default value (uncontrolled) */
@@ -788,10 +806,10 @@ export declare const Combobox: typeof ComboboxStandalone & {
         Value: typeof ComboboxValue;
         Collection: typeof ComboboxCollection;
         Status: ComboboxStatus;
-        useFilter: useFilter;
-        useCreatable: typeof useCreatable;
-        useAsync: typeof useAsync;
     };
+    useAsync: typeof useAsync_2;
+    useFilter: useFilter;
+    useCreatable: typeof useCreatable;
 };
 
 declare type ComboboxAsyncCreatableProps<T extends object> = (ComboboxAsyncOwnProps<T> & CreatableProps<T> & Omit<ComboboxPropsSingle<T>, "mapItem">) | (ComboboxAsyncOwnProps<T> & CreatableProps<T> & Omit<ComboboxPropsMultiple<T>, "mapItem">);
@@ -842,7 +860,9 @@ declare namespace ComboboxCollection {
     var displayName: string;
 }
 
-declare function ComboboxContent({ className, ...props }: React_2.ComponentProps<typeof Combobox_2.Popup>): JSX.Element;
+declare function ComboboxContent({ className, container, ...props }: React_2.ComponentProps<typeof Combobox_2.Popup> & {
+    container?: React_2.ComponentProps<typeof Combobox_2.Portal>["container"];
+}): JSX.Element;
 
 declare namespace ComboboxContent {
     var displayName: string;
@@ -901,6 +921,8 @@ declare interface ComboboxPropsBase<T> {
     className?: string;
     /** Whether the combobox is disabled */
     disabled?: boolean;
+    /** A parent element to render the portal into (e.g. a modal/drawer ref). */
+    container?: React_2.ComponentProps<typeof ComboboxContent>["container"];
 }
 
 declare interface ComboboxPropsMultiple<T> extends ComboboxPropsBase<T> {
@@ -977,6 +999,30 @@ declare namespace ComboboxValue {
  */
 export declare function CommandPalette(): JSX.Element;
 
+/**
+ * An action entry displayed in the CommandPalette.
+ *
+ * Actions registered via `useRegisterCommandPaletteActions` (or implicitly
+ * through `ActionPanel`) appear in the "Actions" section of the palette and
+ * are searchable by `label`.
+ */
+export declare type CommandPaletteAction = {
+    /** Unique key for React reconciliation */
+    key: string;
+    /** Visible label shown in the palette (also used for search matching) */
+    label: string;
+    /** Optional icon rendered next to the label */
+    icon?: ReactNode;
+    /**
+     * Group name used to categorise the action (e.g. the ActionPanel title).
+     * When using `useRegisterCommandPaletteActions`, the hook fills this from
+     * its `group` parameter if not already set.
+     */
+    group?: string;
+    /** Callback invoked when the action is selected */
+    onSelect: () => void | Promise<void>;
+};
+
 declare type CommonModuleProps = {
     /**
      * Resource associated to the module.
@@ -1179,6 +1225,135 @@ export declare function createAuthClient(config: AuthClientConfig): EnhancedAuth
  */
 export declare function createTypedPaths<TRoutes extends Record<string, Record<string, string>>>(): TypedPaths<TRoutes>;
 
+/** Built-in Standard Schema helpers for common CSV column types. */
+export declare const csv: {
+    /** Pass-through with optional length constraints. `min: 1` serves as a required check. */
+    string(options?: {
+        min?: number;
+        max?: number;
+    }): StandardSchemaV1<string, string>;
+    /** Coerces the raw CSV string to a number. Rejects `NaN`. */
+    number(options?: {
+        min?: number;
+        max?: number;
+        integer?: boolean;
+    }): StandardSchemaV1<string, number>;
+    /** Coerces common CSV boolean representations to `true`/`false`. Case-insensitive. */
+    boolean(options?: {
+        truthy?: string[];
+        falsy?: string[];
+    }): StandardSchemaV1<string, boolean>;
+    /** Coerces the raw CSV string to a `Date` object. Rejects unparseable values. */
+    date(): StandardSchemaV1<string, Date>;
+    /** Validates the value is one of the allowed strings. Case-sensitive. */
+    enum<T extends string>(values: T[]): StandardSchemaV1<string, T>;
+};
+
+/** A single cell-level issue found during validation. */
+export declare type CsvCellIssue = {
+    /** 0-based row index. */
+    rowIndex: number;
+    /** The schema column key. */
+    columnKey: string;
+    /** "error" blocks import; "warning" allows import but shows a warning. */
+    level: "error" | "warning";
+    /** Human-readable message. */
+    message: string;
+};
+
+/** Schema definition for a single column in the CSV. */
+export declare type CsvColumn = {
+    /** Internal key — becomes the object key in import results. */
+    key: string;
+    /** Display label shown in the mapping UI. */
+    label: string;
+    /** Optional description shown as a hint in the mapping UI. */
+    description?: string;
+    /** Whether this column must be mapped (default: false). */
+    required?: boolean;
+    /** Alternative CSV header names for automatic matching. */
+    aliases?: readonly string[];
+    /**
+     * A Standard Schema-compatible validator for this column.
+     * Handles both coercion (transform) and validation in a single declaration.
+     * The raw CSV string is passed to `schema["~standard"].validate(value)`.
+     * On success, the output value is used for the parsed row.
+     * On failure, each issue is rendered as a cell error in the Review table.
+     *
+     * @see https://github.com/standard-schema/standard-schema
+     */
+    schema?: StandardSchemaV1;
+};
+
+/** A mapping from a CSV header to a schema column key. */
+export declare type CsvColumnMapping = {
+    /** The header name from the CSV file. */
+    csvHeader: string;
+    /** The schema column key to map to, or null to skip this column. */
+    columnKey: string | null;
+};
+
+/** A single correction made by the user in the review step. */
+export declare type CsvCorrection = {
+    /** 0-based row index. */
+    row: number;
+    /** The schema column key. */
+    columnKey: string;
+    /** The value before correction. */
+    oldValue: unknown;
+    /** The value after correction. */
+    newValue: unknown;
+};
+
+export declare function CsvImporter<T extends CsvSchema>({ open, onOpenChange, schema, maxFileSize, onImport, onValidate, }: CsvImporterProps<T>): JSX.Element;
+
+/** Internal props for the CsvImporter component (managed by useCsvImporter). */
+declare type CsvImporterProps<T extends CsvSchema = CsvSchema> = {
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+    schema: T;
+    maxFileSize: number;
+    onImport: (event: CsvImportEvent<T>) => void | Promise<void>;
+    onValidate?: (rows: ParsedRow[]) => Promise<CsvCellIssue[]>;
+};
+
+/** The event payload passed to the onImport callback. */
+export declare type CsvImportEvent<T extends CsvSchema = CsvSchema> = {
+    /** The original file selected by the user. */
+    file: File;
+    /** The confirmed column mappings. */
+    mappings: CsvColumnMapping[];
+    /** The corrections made by the user in the review step. */
+    corrections: CsvCorrection[];
+    /** Any remaining issues (warnings only — errors are resolved before import). */
+    issues: CsvCellIssue[];
+    /** Summary statistics. */
+    summary: {
+        /** Total number of data rows in the CSV (excluding the header row). */
+        totalRows: number;
+        /** Rows with no warning-level issues. */
+        validRows: number;
+        /** Distinct rows where the user made at least one correction. */
+        correctedRows: number;
+        /** Rows that were skipped during import. */
+        skippedRows: number;
+        /** Rows that have at least one warning-level issue. */
+        warningRows: number;
+    };
+    /**
+     * Reconstruct parsed rows from the original file, applying mappings,
+     * schema coercion, and user corrections.
+     *
+     * The return type is inferred from the schema definition.
+     */
+    buildRows: () => Promise<InferCsvRow<T>[]>;
+};
+
+/** The full schema definition for a CSV import. */
+export declare type CsvSchema = {
+    columns: readonly CsvColumn[];
+};
+
 /**
  * Date format options
  */
@@ -2054,6 +2229,17 @@ declare namespace Image_2 {
     var displayName: string;
 }
 
+/**
+ * Infer the row object type from a CsvSchema definition.
+ * Each column key becomes a property; the value type is derived from the
+ * column's Standard Schema output type (falls back to `unknown`).
+ */
+export declare type InferCsvRow<T extends CsvSchema> = {
+    [C in T["columns"][number] as C["key"]]: C extends {
+        schema: StandardSchemaV1<infer _I, infer O>;
+    } ? O : unknown;
+};
+
 /**
  * A styled input component.
  *
@@ -2383,6 +2569,14 @@ export declare type PageMeta = {
     icon?: ReactNode;
 };
 
+/** The row data passed to `onValidate`, after transforms have been applied. */
+export declare type ParsedRow = {
+    /** 0-based row index, stable across edits. */
+    rowIndex: number;
+    /** Column key → transformed value. Only mapped columns are included. */
+    data: Record<string, unknown>;
+};
+
 /**
  * Allow access to the route. Continue to next guard or render component.
  *
@@ -2738,6 +2932,7 @@ export declare const Select: typeof SelectStandalone & {
         GroupLabel: typeof SelectGroupLabel;
         Separator: SelectSeparator;
     };
+    useAsync: typeof useAsync;
 };
 
 /**
@@ -2777,7 +2972,9 @@ declare type SelectAsyncProps<T> = (SelectAsyncOwnProps<T> & SelectPropsSingle<T
 
 declare function SelectAsyncStandalone<T>(props: SelectAsyncProps<T>): JSX.Element;
 
-declare function SelectContent({ className, ...props }: React_2.ComponentProps<typeof Select_2.Popup>): JSX.Element;
+declare function SelectContent({ className, container, ...props }: React_2.ComponentProps<typeof Select_2.Popup> & {
+    container?: React_2.ComponentProps<typeof Select_2.Portal>["container"];
+}): JSX.Element;
 
 declare namespace SelectContent {
     var displayName: string;
@@ -2810,6 +3007,8 @@ declare interface SelectPropsBase<T> {
     className?: string;
     /** Whether the select is disabled */
     disabled?: boolean;
+    /** A parent element to render the portal into (e.g. a modal/drawer ref). */
+    container?: React_2.ComponentProps<typeof SelectContent>["container"];
 }
 
 declare interface SelectPropsMultiple<T> extends SelectPropsBase<T> {
@@ -3328,6 +3527,41 @@ export declare const useAppShellConfig: () => AppShellConfigContextType;
  */
 export declare const useAppShellData: () => AppShellDataContextType;
 
+/**
+ * Hook that encapsulates the async select pattern — fetching on open,
+ * request cancellation via `AbortController`, and loading/error state.
+ *
+ * Unlike `Combobox.useAsync`, this does **not** involve a search query
+ * or debouncing — Select has no text input. The fetcher is called each
+ * time the dropdown opens.
+ *
+ * @example
+ * ```tsx
+ * const countries = Select.useAsync({
+ *   fetcher: async ({ signal }) => {
+ *     const res = await fetch("/api/countries", { signal });
+ *     return res.json();
+ *   },
+ * });
+ *
+ * <Select.Parts.Root
+ *   onOpenChange={countries.onOpenChange}
+ * >
+ *   <Select.Parts.Trigger>
+ *     <Select.Parts.Value placeholder="Select a country" />
+ *   </Select.Parts.Trigger>
+ *   <Select.Parts.Content>
+ *     {countries.loading
+ *       ? "Loading..."
+ *       : countries.items.map((c) => (
+ *           <Select.Parts.Item key={c.id} value={c}>{c.name}</Select.Parts.Item>
+ *         ))}
+ *   </Select.Parts.Content>
+ * </Select.Parts.Root>
+ * ```
+ */
+declare function useAsync<T>({ fetcher }: UseSelectAsyncOptions<T>): UseSelectAsyncReturn<T>;
+
 /**
  * Hook that encapsulates the async combobox pattern — debounced fetching,
  * request cancellation via `AbortController`, and loading state.
@@ -3368,7 +3602,7 @@ export declare const useAppShellData: () => AppShellDataContextType;
  * </Combobox.Root>
  * ```
  */
-declare function useAsync<T>(options: UseAsyncItemsOptions<T>): UseAsyncItemsReturn<T>;
+declare function useAsync_2<T>(options: UseAsyncItemsOptions<T>): UseAsyncItemsReturn<T>;
 
 /**
  * Hook that encapsulates the async autocomplete pattern — debounced fetching,
@@ -3412,7 +3646,7 @@ declare function useAsync<T>(options: UseAsyncItemsOptions<T>): UseAsyncItemsRet
  * </Autocomplete.Root>
  * ```
  */
-declare function useAsync_2<T>(options: UseAsyncItemsOptions<T>): AutocompleteUseAsyncReturn<T>;
+declare function useAsync_3<T>(options: UseAsyncItemsOptions<T>): AutocompleteUseAsyncReturn<T>;
 
 declare interface UseAsyncItemsOptions<T> {
     /**
@@ -3688,6 +3922,18 @@ declare interface UseCreatableReturnSingle<T> extends UseCreatableReturnBase<T>
     multiple: false;
 }
 
+export declare function useCsvImporter<const T extends CsvSchema>(options: UseCsvImporterOptions<T>): {
+    open: () => void;
+    props: CsvImporterProps<T>;
+};
+
+declare type UseCsvImporterOptions<T extends CsvSchema> = {
+    schema: T;
+    onImport: (event: CsvImportEvent<T>) => void | Promise<void>;
+    onValidate?: (rows: ParsedRow[]) => Promise<CsvCellIssue[]>;
+    maxFileSize?: number;
+};
+
 export { useLocation }
 
 export { useNavigate }
@@ -3729,10 +3975,49 @@ export declare const usePageMeta: (path: string) => PageMeta | null;
 
 export { useParams }
 
+/**
+ * Declaratively register contextual actions to the CommandPalette.
+ *
+ * Actions are registered while the calling component is mounted and
+ * automatically unregistered on unmount. Re-registering with new actions
+ * replaces the previous set.
+ *
+ * Note: `icon` changes alone do not trigger re-registration. If you need
+ * dynamic icons, also change the action's `key` or `label`.
+ *
+ * @example
+ * ```tsx
+ * import { useRegisterCommandPaletteActions } from "@tailor-platform/app-shell";
+ *
+ * function MyComponent() {
+ *   useRegisterCommandPaletteActions("My Page", [
+ *     { key: "refresh", label: "Refresh data", onSelect: () => refetch() },
+ *   ]);
+ * }
+ * ```
+ */
+export declare function useRegisterCommandPaletteActions(group: string, actions: CommandPaletteAction[]): void;
+
 export { useRouteError }
 
 export { useSearchParams }
 
+declare interface UseSelectAsyncOptions<T> {
+    /** Fetcher for async item loading. Called each time the dropdown is opened. */
+    fetcher: SelectAsyncFetcher<T>;
+}
+
+declare interface UseSelectAsyncReturn<T> {
+    /** Fetched items — pass to the Root `items` prop or render manually */
+    items: T[];
+    /** Whether a fetch is currently in-flight */
+    loading: boolean;
+    /** The error thrown by the last fetch, if any */
+    error: unknown;
+    /** Open change handler — pass to the Root `onOpenChange` prop */
+    onOpenChange: (open: boolean) => void;
+}
+
 export declare const useTheme: () => ThemeProviderState;
 
 export declare const useToast: () => typeof toast;