@tailor-platform/app-shell 1.4.1 → 1.6.0

package/dist/app-shell.d.ts

@@ -188,6 +188,44 @@ export declare interface ActivityCardRootProps<T extends ActivityCardBaseItem> {
  */
 declare function ActivityCardStandalone({ items, title, maxVisible, overflowLabel, groupBy, className, }: ActivityCardProps): JSX.Element;
 
+export declare type AIChatCompletionEvent = {
+    type: "text-delta";
+    text: string;
+} | {
+    type: "done";
+    finishReason?: string;
+};
+
+export declare interface AIChatMessage {
+    id: string;
+    role: "user" | "assistant";
+    content: string;
+}
+
+export declare type AIChatStatus = "ready" | "submitted" | "streaming" | "error";
+
+export declare type AIGatewayChatMessage = {
+    role: "system" | "user";
+    content: string;
+} | {
+    role: "assistant";
+    content?: string;
+};
+
+export declare interface AIGatewayChatRequest {
+    model: string;
+    messages: AIGatewayChatMessage[];
+    stream?: boolean;
+    signal?: AbortSignal;
+}
+
+export declare interface AIGatewayClient {
+    /**
+     * Honor request.signal when possible so callers can stop work early.
+     */
+    streamChatCompletion(request: AIGatewayChatRequest): AsyncIterable<AIChatCompletionEvent>;
+}
+
 export declare const Alert: {
     Root: typeof Root;
     Title: typeof Title;
@@ -200,6 +238,12 @@ export declare const alertVariants: (props?: ({
     variant?: "error" | "neutral" | "success" | "warning" | "info" | null | undefined;
 } & ClassProp) | undefined) => string;
 
+/**
+ * Appearance menu. The end-user controls **color theme** (light / dark / system);
+ * the color palette/brand is a developer configuration, so it is not shown here.
+ */
+export declare function AppearanceSwitcher(): JSX.Element;
+
 export declare const AppShell: {
     (props: AppShellProps): JSX.Element | null;
     WithPages(pages: PageEntry[]): FC<AppShellProps>;
@@ -212,6 +256,7 @@ export declare const AppShell: {
 declare type AppShellConfigContextType = {
     title?: string;
     icon?: ReactNode;
+    favicon?: string;
     configurations: RootConfiguration;
 };
 
@@ -268,10 +313,6 @@ export declare type AppShellPageProps = {
      * ```
      */
     guards?: Guard[];
-    /**
-     * Loader function to fetch data before rendering the page.
-     */
-    loader?: LoaderHandler;
 };
 
 /**
@@ -781,6 +822,12 @@ declare namespace Body_2 {
     var displayName: string;
 }
 
+/**
+ * Responsive breakpoints, aligned with Tailwind's default breakpoints.
+ * `initial` is the base (mobile-first) value applied below the `sm` breakpoint.
+ */
+declare type Breakpoint = "initial" | "sm" | "md" | "lg" | "xl" | "2xl";
+
 /**
  * Builds a Tailor Platform QueryInput-compatible type from table metadata.
  */
@@ -835,12 +882,18 @@ export declare const Card: {
 };
 
 /** A table data cell (`<td>`). */
-declare function Cell({ className, ...props }: React_2.ComponentProps<"td">): JSX.Element;
+declare function Cell({ className, align, ...props }: CellProps): JSX.Element;
 
 declare namespace Cell {
     var displayName: string;
 }
 
+declare type CellAlign = "left" | "center" | "right";
+
+declare type CellProps = React_2.ComponentProps<"td"> & {
+    align?: CellAlign;
+};
+
 /** A menu item that toggles a setting on or off. */
 declare function CheckboxItem({ className, ...props }: React_2.ComponentProps<typeof Menu_2.CheckboxItem>): JSX.Element;
 
@@ -946,6 +999,35 @@ export declare function CollectionControlProvider({ value, children, }: {
     children: ReactNode;
 }): JSX.Element;
 
+/**
+ * Partial initial state used to seed `useCollectionVariables`.
+ */
+export declare type CollectionInitialState<TFieldName extends string = string, TFilter extends Filter<TFieldName> = Filter<TFieldName>> = Partial<CollectionPersistedState<TFieldName, TFilter>>;
+
+/**
+ * Initial and change payload shape for `useCollectionVariables`.
+ */
+export declare interface CollectionParams<TFieldName extends string = string, TFilter extends Filter<TFieldName> = Filter<TFieldName>> {
+    initialFilters?: TFilter[];
+    initialSort?: {
+        field: TFieldName;
+        direction: "Asc" | "Desc";
+    }[];
+    pageSize?: number;
+}
+
+/**
+ * Serializable subset of collection state used for initialization and persistence.
+ */
+export declare interface CollectionPersistedState<TFieldName extends string = string, TFilter extends Filter<TFieldName> = Filter<TFieldName>> {
+    filters: TFilter[];
+    sortStates: {
+        field: TFieldName;
+        direction: "Asc" | "Desc";
+    }[];
+    pageSize: number;
+}
+
 /**
  * GraphQL collection result format (Tailor Platform standard).
  */
@@ -969,6 +1051,12 @@ export declare interface CollectionVariables {
     pagination: PaginationVariables;
 }
 
+/**
+ * Color theme — the end-user accessibility preference. `system` follows the OS
+ * light/dark setting. Applied to `<html>` as the `.light` / `.dark` class.
+ */
+export declare type ColorTheme = "light" | "dark" | "system";
+
 /**
  * A column definition for DataTable. Use one of the built-in `type` values
  * (`text`, `number`, `money`, `date`, `badge`, `link`) for automatic
@@ -1583,6 +1671,11 @@ declare interface CreatableProps<T extends object> {
     formatCreateLabel?: (value: string) => string;
 }
 
+export declare function createAIGatewayClient(config: {
+    gatewayUri: string;
+    authClient: AuthClient;
+}): AIGatewayClient;
+
 /**
  * Create an enhanced authentication client.
  *
@@ -2334,6 +2427,76 @@ declare type DialogRootProps = Pick<React_2.ComponentProps<typeof Dialog_2.Root>
     children: React_2.ReactNode;
 };
 
+/**
+ * DocumentProgressCard — a generic, presentational card for a document's
+ * lifecycle/fulfilment state: an optional headline percentage, a stacked
+ * progress bar, and a status legend.
+ *
+ * View-only and domain-agnostic — pass an arbitrary set of `segments` (e.g.
+ * shipped / returned / pending, or cancelled / blocked / …) plus an explicit
+ * `percent`. Derive the percentage and, where buckets overlap, the bar
+ * breakdown in the consumer (see the docs for a purchase-order example).
+ *
+ * @example
+ * ```tsx
+ * <DocumentProgressCard
+ *   title="Shipment status"
+ *   percent={60}
+ *   segments={[
+ *     { label: "Shipped", value: 30, color: "green" },
+ *     { label: "Returned", value: 3, color: "red" },
+ *     { label: "Pending", value: 17, color: "neutral" },
+ *   ]}
+ * />
+ * ```
+ */
+export declare function DocumentProgressCard({ title, percent, segments, legend, total, className, }: DocumentProgressCardProps): JSX.Element;
+
+/**
+ * Props for the generic DocumentProgressCard.
+ */
+export declare interface DocumentProgressCardProps {
+    /** Optional card title shown top-left. */
+    title?: ReactNode;
+    /**
+     * Headline percentage shown top-right (0–100). Optional and explicit — the
+     * generic card has no notion of "complete", so the consumer supplies it.
+     */
+    percent?: number;
+    /** Status segments rendered as a single stacked bar (and, by default, the legend). */
+    segments: DocumentProgressSegment[];
+    /**
+     * Legend rows. Defaults to `segments`. Provide this only when the legend
+     * should differ from the bar (e.g. overlapping buckets shown distinctly).
+     */
+    legend?: DocumentProgressSegment[];
+    /**
+     * Denominator used to size the bar. Defaults to the sum of segment values
+     * (the bar is fully tiled). A larger value leaves an unfilled track remainder.
+     */
+    total?: number;
+    /** Additional CSS classes for the card root. */
+    className?: string;
+}
+
+/**
+ * Curated palette for progress segments. Each value maps to a fixed fill used
+ * for both the stacked bar and the legend marker.
+ */
+declare type DocumentProgressColor = "indigo" | "pink" | "green" | "amber" | "red" | "blue" | "neutral";
+
+/**
+ * A single status segment: its amount, a legend label, and a color.
+ */
+declare interface DocumentProgressSegment {
+    /** Legend label (e.g. "Shipped"). */
+    label: string;
+    /** Amount — shown in the legend and used to size the bar. */
+    value: number;
+    /** Bar / legend-marker color. */
+    color: DocumentProgressColor;
+}
+
 declare type DynamicLocales<Def extends Record<string, LabelValue>> = {
     [locale: string]: Partial<LabelDefinition<Def>> | undefined;
 };
@@ -2836,6 +2999,69 @@ export declare type FormProps<FormValues extends Record<string, any> = Record<st
 
 declare type FormSubmitEventDetails = NonNullable<React_2.ComponentProps<typeof Form_2>["onFormSubmit"]> extends (values: any, details: infer D) => any ? D : never;
 
+export declare const Grid: React_2.ForwardRefExoticComponent<Omit<GridProps, "ref"> & React_2.RefAttributes<HTMLDivElement>> & {
+    Item: React_2.ForwardRefExoticComponent<Omit<GridItemProps, "ref"> & React_2.RefAttributes<HTMLDivElement>>;
+};
+
+/**
+ * Props for {@link Grid.Item} — a grid cell that spans or is placed explicitly.
+ *
+ * Only needed when a child must span multiple tracks or be positioned; plain
+ * children render in a single cell without it.
+ */
+export declare interface GridItemProps extends React_2.ComponentProps<"div"> {
+    /** Number of columns to span, or `"full"` to span all columns. Responsive. */
+    colSpan?: Responsive<number | "full">;
+    /** Number of rows to span, or `"full"` to span all rows. Responsive. */
+    rowSpan?: Responsive<number | "full">;
+    /** 1-based column line to start at (`grid-column-start`). Responsive. */
+    colStart?: Responsive<number>;
+    /** 1-based column line to end at (`grid-column-end`). Responsive. */
+    colEnd?: Responsive<number>;
+}
+
+/**
+ * Props for the {@link Grid} component.
+ *
+ * `Grid` is a generic, presentational CSS-Grid container. It does not assume
+ * any data shape — children flow into the tracks defined by `columns`/`rows`.
+ */
+export declare interface GridProps extends React_2.ComponentProps<"div"> {
+    /**
+     * Column tracks. A number creates that many equal columns
+     * (`repeat(n, minmax(0, 1fr))`); a string is used verbatim as a
+     * `grid-template-columns` value (e.g. `"280px 1fr"`). Responsive.
+     */
+    columns?: Responsive<number | string>;
+    /**
+     * Row tracks. A number creates that many equal rows
+     * (`repeat(n, minmax(0, 1fr))`); a string is used verbatim as a
+     * `grid-template-rows` value. Responsive.
+     */
+    rows?: Responsive<number | string>;
+    /**
+     * Gap between rows and columns, in spacing-scale units (`4` = `1rem`).
+     * Defaults to `3` (12px). Responsive.
+     */
+    gap?: Responsive<number>;
+    /** Horizontal (column) gap override, in spacing-scale units. Responsive. */
+    gapX?: Responsive<number>;
+    /** Vertical (row) gap override, in spacing-scale units. Responsive. */
+    gapY?: Responsive<number>;
+    /**
+     * Auto-fit columns: each child is at least this wide and as many as fit are
+     * placed per row (`repeat(auto-fit, minmax(w, 1fr))`). A number is treated as
+     * pixels. **Overrides `columns`** when set.
+     */
+    minChildWidth?: number | string;
+    /** `grid-auto-flow` direction. */
+    flow?: "row" | "column" | "dense" | "row-dense" | "column-dense";
+    /** `align-items` — block-axis alignment of children within their tracks. */
+    align?: "start" | "center" | "end" | "stretch" | "baseline";
+    /** `justify-content` — inline-axis distribution of tracks within the grid. */
+    justify?: "start" | "center" | "end" | "between" | "around" | "evenly";
+}
+
 /** Groups related menu items with the corresponding label. */
 declare function Group({ ...props }: React_2.ComponentProps<typeof Menu_2.Group>): JSX.Element;
 
@@ -2883,7 +3109,7 @@ export declare type GuardResult =
 };
 
 /** A table header cell (`<th>`). */
-declare function Head({ className, ...props }: React_2.ComponentProps<"th">): JSX.Element;
+declare function Head({ className, align, ...props }: HeadProps): JSX.Element;
 
 declare namespace Head {
     var displayName: string;
@@ -2966,6 +3192,10 @@ declare type HeaderProps = Omit<React_2.ComponentProps<"div">, "title"> & {
     description?: React_2.ReactNode;
 };
 
+declare type HeadProps = React_2.ComponentProps<"th"> & {
+    align?: CellAlign;
+};
+
 /**
  * Deny access and show 404 Not Found.
  *
@@ -3432,7 +3662,7 @@ declare type OrderableFieldType = "string" | "number" | "boolean" | "datetime" |
  * A React component that can be used as a page in file-based routing.
  *
  * The component can optionally have an `appShellPageProps` static field
- * for configuring navigation metadata, guards, and loaders.
+ * for configuring navigation metadata and guards.
  */
 export declare type PageComponent = FC & {
     appShellPageProps?: AppShellPageProps;
@@ -3558,6 +3788,9 @@ declare namespace RadioItemIndicator {
  */
 export declare const redirectTo: (to: string) => GuardResult;
 
+/** Color theme after resolving `system` to a concrete value. */
+export declare type ResolvedColorTheme = "light" | "dark";
+
 declare type ResolveFieldValueType<F, T extends keyof FieldTypeToTSType> = T extends "enum" ? F extends {
     readonly enumValues: readonly (infer V extends string)[];
 } ? V : string : FieldTypeToTSType[T];
@@ -3596,6 +3829,18 @@ declare type ResourceMeta = {
     breadcrumbTitle?: string | ((segment: string) => string);
 };
 
+/**
+ * A value that can either be a single value applied at all breakpoints, or an
+ * object keyed by breakpoint for responsive behavior.
+ *
+ * @example
+ * ```tsx
+ * columns={4}                          // same at every breakpoint
+ * columns={{ initial: 1, md: 2, xl: 4 }} // responsive
+ * ```
+ */
+declare type Responsive<T> = T | Partial<Record<Breakpoint, T>>;
+
 declare function Root({ className, variant, action, dismissible, onDismiss, children, ...props }: RootProps): JSX.Element | null;
 
 declare namespace Root {
@@ -3892,6 +4137,16 @@ export declare interface RowAction<TRow extends Record<string, unknown>> {
     onClick: (row: TRow) => void;
 }
 
+/**
+ * Setter shape compatible with `useSearchParams()`.
+ */
+declare type SearchParamsBinding = readonly [
+URLSearchParams,
+(next: URLSearchParams | ((prev: URLSearchParams) => URLSearchParams), options?: {
+    replace?: boolean;
+}) => void
+];
+
 /**
  * An async search source that can be plugged into the CommandPalette.
  *
@@ -4110,13 +4365,30 @@ declare namespace SelectValue {
  */
 declare type SharedAppShellProps = React.PropsWithChildren<{
     /**
-     * App shell title
+     * App shell title.
+     *
+     * Also used as the suffix of the browser tab title: AppShell keeps
+     * `document.title` in sync with the active page as `"<page> · <title>"`
+     * (the page part is the current breadcrumb leaf, including any
+     * {@link useOverrideBreadcrumb} override). When omitted, the tab shows just
+     * the page title.
      */
     title?: string;
     /**
      * App shell icon
      */
     icon?: React.ReactNode;
+    /**
+     * Browser-tab favicon href. Accepts anything valid on `<link rel="icon">` —
+     * a public-path URL (e.g. `/favicon.ico`) or a data URI. AppShell renders the
+     * `<link rel="icon">` for you (React hoists it into `<head>`). When omitted,
+     * AppShell preserves any favicon link already declared by the host page and
+     * only falls back to the bundled Tailor favicon when none exists.
+     *
+     * If you pass this prop, prefer not to also declare a static
+     * `<link rel="icon">` in `index.html`.
+     */
+    favicon?: string;
     /**
      * Base path for the app shell
      */
@@ -4245,6 +4517,15 @@ declare type SharedAppShellProps = React.PropsWithChildren<{
      * ```
      */
     searchSources?: readonly SearchSource[];
+    /**
+     * Initial color mode before any value is loaded from localStorage (`appshell-ui-theme`).
+     * This is the end-user accessibility preference; does not replace a stored preference.
+     *
+     * One of **`light`**, **`dark`**, or **`system`** (follows the OS).
+     *
+     * @default "system"
+     */
+    defaultColorTheme?: ColorTheme;
 }>;
 
 export declare const Sheet: {
@@ -4596,14 +4877,6 @@ export declare const Tabs: {
 
 declare type TabsVariant = "default" | "line" | "capsule";
 
-declare type Theme = "dark" | "light" | "system";
-
-declare type ThemeProviderState = {
-    theme: Theme;
-    resolvedTheme: Omit<Theme, "system">;
-    setTheme: (theme: Theme) => void;
-};
-
 declare function Title({ className, ...props }: React_2.ComponentProps<"div">): JSX.Element;
 
 declare namespace Title {
@@ -4663,6 +4936,18 @@ declare namespace Trigger_4 {
     var displayName: string;
 }
 
+/**
+ * Metadata-aware collection variables that remain assignable to the broad
+ * `CollectionVariables` shape expected by GraphQL clients.
+ */
+declare type TypedCollectionVariables<TTable extends TableMetadata> = CollectionVariables & {
+    query: BuildQueryVariables<TTable> | undefined;
+    order: {
+        field: TableOrderableFieldName<TTable>;
+        direction: "Asc" | "Desc";
+    }[] | undefined;
+};
+
 /**
  * Type-safe path builder interface.
  *
@@ -4691,6 +4976,22 @@ declare type TypedPaths<TRoutes extends Record<string, Record<string, string>>>
     for<T extends (keyof TRoutes & string) | `${keyof TRoutes & string}?${string}`>(path: T, ...params: ExtractBasePath<T> extends keyof TRoutes ? IsEmptyObject<TRoutes[ExtractBasePath<T>]> extends true ? [] : [TRoutes[ExtractBasePath<T>]] : never): string;
 };
 
+export declare function useAIChat(config: {
+    client: AIGatewayClient;
+    model: string;
+    stream?: boolean;
+}): {
+    messages: AIChatMessage[];
+    status: AIChatStatus;
+    error?: Error;
+    /**
+     * Returns true when the message is sent and the stream finishes successfully.
+     * Returns false when the call is ignored, aborted, or the request fails.
+     */
+    sendMessage: (message: string) => Promise<boolean>;
+    stop: () => void;
+};
+
 /**
  * Hook to access the full AppShell context (both config and data).
  * For better performance, prefer useAppShellConfig() or useAppShellData()
@@ -4700,6 +5001,7 @@ export declare const useAppShell: () => {
     contextData: ContextData;
     title?: string;
     icon?: ReactNode;
+    favicon?: string;
     configurations: RootConfiguration;
 };
 
@@ -5003,14 +5305,8 @@ export declare function useCollectionControl<TFieldName extends string = string>
  * Options for `useCollectionVariables` hook.
  */
 export declare interface UseCollectionOptions<TFieldName extends string = string, TFilter extends Filter<TFieldName> = Filter<TFieldName>> {
-    params?: {
-        initialFilters?: TFilter[];
-        initialSort?: {
-            field: TFieldName;
-            direction: "Asc" | "Desc";
-        }[];
-        pageSize?: number;
-    };
+    params?: CollectionParams<TFieldName, TFilter>;
+    onParamsChange?(params: CollectionParams<TFieldName, TFilter>): void;
 }
 
 /**
@@ -5045,14 +5341,7 @@ export declare interface UseCollectionReturn<TFieldName extends string = string,
  */
 export declare function useCollectionVariables<const TTable extends TableMetadata>(options: UseCollectionOptions<TableFieldName<TTable>, TableMetadataFilter<TTable>> & {
     tableMetadata: TTable;
-}): UseCollectionReturn<TableFieldName<TTable>, {
-    query: BuildQueryVariables<TTable> | undefined;
-    order: {
-        field: TableOrderableFieldName<TTable>;
-        direction: "Asc" | "Desc";
-    }[] | undefined;
-    pagination: PaginationVariables;
-}, TableMetadataFilter<TTable>>;
+}): UseCollectionReturn<TableFieldName<TTable>, TypedCollectionVariables<TTable>, TableMetadataFilter<TTable>>;
 
 /**
  * Hook for managing collection query parameters (filters, sort, pagination).
@@ -5521,10 +5810,46 @@ declare interface UseSelectAsyncReturn<T> {
     onOpenChange: (open: boolean) => void;
 }
 
-export declare const useTheme: () => ThemeProviderState;
+/** Color theme hook — returns the current color theme and a setter. */
+export declare const useTheme: () => {
+    theme: ColorTheme;
+    resolvedTheme: ResolvedColorTheme;
+    setTheme: (colorTheme: ColorTheme) => void;
+};
 
 export declare const useToast: () => typeof toast;
 
+/**
+ * Hook for managing collection query parameters (filters, sort, pagination)
+ * with state persisted to the URL query string.
+ *
+ * This is the one-call convenience over {@link useCollectionVariables}: it seeds
+ * the initial filter/sort/page-size state from the current router search params
+ * and writes changes back as the user filters, sorts, or pages (using `replace`
+ * so each change doesn't push a new history entry).
+ *
+ * Reach for the bare {@link useCollectionVariables} when you don't want URL
+ * persistence, or the pure {@link withURLCollectionState} decorator when you
+ * need to supply a non-react-router search-params binding.
+ *
+ * @example
+ * ```tsx
+ * import { tableMetadata } from "./generated/data-viewer-metadata.generated";
+ *
+ * const { variables, control } = useURLCollectionVariables({
+ *   tableMetadata: tableMetadata.task,
+ *   params: { pageSize: 20 },
+ * });
+ * ```
+ */
+export declare function useURLCollectionVariables<const TTable extends TableMetadata>(options: UseCollectionOptions<TableFieldName<TTable>, TableMetadataFilter<TTable>> & {
+    tableMetadata: TTable;
+}): UseCollectionReturn<TableFieldName<TTable>, TypedCollectionVariables<TTable>, TableMetadataFilter<TTable>>;
+
+export declare function useURLCollectionVariables(options: UseCollectionOptions & {
+    tableMetadata?: never;
+}): UseCollectionReturn<string, CollectionVariables>;
+
 /**
  * Used to display a custom message based on the field's validity state.
  *
@@ -5642,4 +5967,17 @@ export declare type WithGuardProps = {
     loading?: ReactNode;
 };
 
+/**
+ * Decorate `useCollectionVariables` options with URL-backed collection state.
+ */
+export declare function withURLCollectionState<const TTable extends TableMetadata>(options: UseCollectionOptions<TableFieldName<TTable>, TableMetadataFilter<TTable>> & {
+    tableMetadata: TTable;
+}, [searchParams, setSearchParams]: SearchParamsBinding): UseCollectionOptions<TableFieldName<TTable>, TableMetadataFilter<TTable>> & {
+    tableMetadata: TTable;
+};
+
+export declare function withURLCollectionState(options: UseCollectionOptions & {
+    tableMetadata?: never;
+}, [searchParams, setSearchParams]: SearchParamsBinding): UseCollectionOptions;
+
 export { }