@tailor-platform/app-shell 0.33.0 → 0.35.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();
@@ -417,7 +427,11 @@ declare type AuthProviderProps = {
     /**
      * Guard UI component to show when loading or unauthenticated.
      *
-     * If not provided, children will be just rendered in any auth state.
+     * When provided, AuthProvider renders this component directly while auth
+     * is not ready or the user is not authenticated. Children are hidden until
+     * auth resolves to an authenticated state.
+     *
+     * If not provided, children are rendered regardless of auth state.
      */
     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) */
@@ -685,6 +703,11 @@ export declare const buttonVariants: (props?: ({
     size?: "default" | "xs" | "sm" | "lg" | "icon" | null | undefined;
 } & ClassProp) | undefined) => string;
 
+/**
+ * Internal type for tracking OAuth callback handling status.
+ */
+declare type CallbackStatus = "idle" | "pending" | "resolved" | "rejected";
+
 /** A table caption element. */
 declare function Caption({ className, ...props }: React_2.ComponentProps<"caption">): JSX.Element;
 
@@ -788,10 +811,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 +865,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 +926,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> {
@@ -972,10 +999,52 @@ declare namespace ComboboxValue {
 }
 
 /**
- * CommandPalette component that uses navigation items with access control.
- * Renders a searchable command palette UI triggered by Cmd+K / Ctrl+K.
+ * @deprecated CommandPalette is now built into AppShell and rendered automatically.
+ * Remove `<CommandPalette>` from your JSX.
+ */
+export declare function CommandPalette(): React.ReactNode;
+
+/**
+ * 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>;
+};
+
+/**
+ * A single search result returned by a `SearchSource`.
+ *
+ * Selecting a result navigates to `path`.
  */
-export declare function CommandPalette(): JSX.Element;
+export declare type CommandPaletteSearchResult = {
+    /** Unique key for React reconciliation */
+    key: string;
+    /** Visible label shown in the palette (e.g. "Order #ORD-1234") */
+    label: string;
+    /** Optional secondary text (e.g. "山田太郎 - 2024/01/15") */
+    description?: string;
+    /** Optional icon for this specific result */
+    icon?: ReactNode;
+    /** Resolved navigation path (e.g. "/orders/abc-123") */
+    path: string;
+};
 
 declare type CommonModuleProps = {
     /**
@@ -1122,6 +1191,11 @@ declare interface CreatableProps<T extends object> {
  * This wrapper around the original createAuthClient adds convenience methods
  * to reduce duplication of the appUri across your application.
  *
+ * **Side effect on call**: If the current URL contains OAuth callback parameters
+ * (`code` or `error`), this function immediately starts `handleCallback()` to
+ * exchange the authorization code. This happens at call time — before any React
+ * render — so it is safe to call at module scope.
+ *
  * @example
  * ```tsx
  * import { createAuthClient, AuthProvider } from '@tailor-platform/app-shell';
@@ -1179,6 +1253,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
  */
@@ -1187,6 +1390,9 @@ declare type DateFormat = "short" | "medium" | "long" | "relative";
 /**
  * Default sidebar component with auto-generated navigation items.
  *
+ * Must be rendered inside `AppShell` (or a `CommandPaletteProvider`) — the
+ * built-in Search button requires the palette context.
+ *
  * It works in both auto-generation mode and composition mode.
  * - Auto-generation mode: when no children are provided, it automatically generates sidebar items based on the application's resource definitions.
  * - Composition mode: when children are provided, it allows developers to manually define the sidebar structure using SidebarItem, SidebarGroup, and other components.
@@ -1543,6 +1749,8 @@ export declare interface EnhancedAuthClient extends AuthClient {
      * Same signature as the standard `fetch` API.
      */
     fetch: AuthClient["fetch"];
+    /* Excluded from this release type: getCallbackStatusSnapshot */
+    /* Excluded from this release type: subscribeCallbackStatus */
 }
 
 /**
@@ -2054,6 +2262,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 +2602,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.
  *
@@ -2726,6 +2953,26 @@ declare namespace Row {
     var displayName: string;
 }
 
+/**
+ * An async search source that can be plugged into the CommandPalette.
+ *
+ * Each source is activated by typing its `prefix` followed by `:` in the
+ * search input (e.g. `PO:` for Purchase Orders). The prefix match is
+ * case-sensitive.
+ */
+export declare type SearchSource = {
+    /** Mode-switching prefix (e.g. "PO"). Case-sensitive, alphanumeric only. */
+    prefix: string;
+    /** Heading shown above search results (e.g. "Purchase Orders") */
+    title: string;
+    /** Optional icon shown next to each result that lacks its own icon */
+    icon?: ReactNode;
+    /** Async search function. Receives the query after the prefix and an AbortSignal. */
+    search: (query: string, options: {
+        signal: AbortSignal;
+    }) => Promise<CommandPaletteSearchResult[]>;
+};
+
 export declare const Select: typeof SelectStandalone & {
     Async: typeof SelectAsyncStandalone;
     Parts: {
@@ -2738,6 +2985,7 @@ export declare const Select: typeof SelectStandalone & {
         GroupLabel: typeof SelectGroupLabel;
         Separator: SelectSeparator;
     };
+    useAsync: typeof useAsync;
 };
 
 /**
@@ -2777,7 +3025,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 +3060,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> {
@@ -2986,6 +3238,39 @@ declare type SharedAppShellProps = React.PropsWithChildren<{
      * ```
      */
     contextData?: ContextData;
+    /**
+     * Async search sources for the built-in CommandPalette.
+     *
+     * The CommandPalette (opened via Cmd+K / Ctrl+K, or the sidebar Search
+     * button) always searches pages and contextual actions. When
+     * `searchSources` is also provided, those async sources are available
+     * as prefix-activated search modes.
+     *
+     * Note: `DefaultSidebar` always renders a Search entry at the top of
+     * the navigation menu, regardless of whether this prop is supplied.
+     *
+     * @example
+     * ```tsx
+     * <AppShell
+     *   modules={modules}
+     *   searchSources={[
+     *     {
+     *       prefix: "PO",
+     *       title: "Purchase Orders",
+     *       search: async (query, { signal }) => {
+     *         const results = await api.searchOrders(query, { signal });
+     *         return results.map((o) => ({
+     *           key: o.id,
+     *           label: o.number,
+     *           path: `/orders/${o.id}`,
+     *         }));
+     *       },
+     *     },
+     *   ]}
+     * />
+     * ```
+     */
+    searchSources?: readonly SearchSource[];
 }>;
 
 export declare const Sheet: {
@@ -3328,6 +3613,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 +3688,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 +3732,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 +4008,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 +4061,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;