@tailor-platform/app-shell 0.31.1 → 0.33.0

package/dist/app-shell.d.ts

@@ -3,12 +3,16 @@ import { Autocomplete as Autocomplete_2 } from '@base-ui/react/autocomplete';
 import { AutocompleteFilter } from '@base-ui/react';
 import { AutocompleteFilterOptions } from '@base-ui/react';
 import { AutocompleteRootProps } from '@base-ui/react/autocomplete';
+import { Avatar as Avatar_2 } from '@base-ui/react/avatar';
 import { ClassProp } from 'class-variance-authority/types';
 import { Combobox as Combobox_2 } from '@base-ui/react/combobox';
 import { CSSProperties } from 'react';
 import { Dialog as Dialog_2 } from '@base-ui/react/dialog';
 import { Drawer } from '@base-ui/react/drawer';
 import { FC } from 'react';
+import { Field as Field_2 } from '@base-ui/react/field';
+import { Fieldset as Fieldset_2 } from '@base-ui/react/fieldset';
+import { Form as Form_2 } from '@base-ui/react/form';
 import { JSX } from 'react/jsx-runtime';
 import { Link } from 'react-router';
 import { LoaderFunctionArgs } from 'react-router';
@@ -82,9 +86,100 @@ export declare interface ActionPanelProps {
     className?: string;
 }
 
+export declare const ActivityCard: typeof ActivityCardStandalone & {
+    Root: typeof Root;
+    Items: typeof Items;
+    Item: typeof Item;
+};
+
+/**
+ * Minimum shape required for items passed to ActivityCard.
+ * Consumers can extend this with any additional fields.
+ */
+export declare interface ActivityCardBaseItem {
+    id: string;
+    timestamp: Date | string;
+}
+
+/**
+ * A single activity entry used by the standalone ActivityCard component.
+ */
+export declare interface ActivityCardItem extends ActivityCardBaseItem {
+    /**
+     * The subject of the activity. Optional — omit for system events with no specific actor
+     * (e.g. "Status automatically changed to EXPIRED").
+     */
+    actor?: {
+        /** Display name of the actor (user, bot, service account, etc.). */
+        name: string;
+        /** Avatar image URL. Falls back to initials derived from `name`. */
+        avatarUrl?: string;
+    };
+    description: string;
+}
+
+/**
+ * Props for ActivityCard.Item — a single row in the timeline.
+ */
+export declare interface ActivityCardItemProps {
+    /** Element rendered in the left column (e.g. Avatar, Icon). The timeline connector line
+     *  passes through the center of this element. Omit for rows without a connector. */
+    indicator?: React_2.ReactNode;
+    children: React_2.ReactNode;
+    className?: string;
+}
+
+/**
+ * Props for ActivityCard.Items — iterates over items and renders each via children render function.
+ */
+export declare interface ActivityCardItemsProps<T extends ActivityCardBaseItem> {
+    children: (item: T) => React_2.ReactNode;
+}
+
+/**
+ * Props for the standalone (pre-assembled) ActivityCard component.
+ */
+export declare interface ActivityCardProps {
+    /** List of items (newest first). */
+    items: ActivityCardItem[];
+    /** Card title, e.g. "Updates". */
+    title?: string;
+    /** Max number of activities shown in the card before overflow. Default 6. */
+    maxVisible?: number;
+    /** Overflow label style: "more" = "N more activities", "count" = "+N". Default "more". */
+    overflowLabel?: "more" | "count";
+    /** Optional grouping by day (TODAY / YESTERDAY / date). */
+    groupBy?: "none" | "day";
+    className?: string;
+}
+
+/**
+ * Props for ActivityCard.Root — the outermost card container.
+ */
+export declare interface ActivityCardRootProps<T extends ActivityCardBaseItem> {
+    /** List of items (newest first). */
+    items: T[];
+    /** Card title, e.g. "Updates". */
+    title?: string;
+    /** Max number of activities shown in the card before overflow. Default 6. */
+    maxVisible?: number;
+    /** Overflow label style: "more" = "N more activities", "count" = "+N". Default "more". */
+    overflowLabel?: "more" | "count";
+    /** Optional grouping by day (TODAY / YESTERDAY / date). */
+    groupBy?: "none" | "day";
+    className?: string;
+    children: React_2.ReactNode;
+}
+
+/**
+ * Pre-assembled ActivityCard that renders activities with avatars, descriptions,
+ * and timestamps. For custom item rendering, use ActivityCard.Root / .Items / .Item.
+ */
+declare function ActivityCardStandalone({ items, title, maxVisible, overflowLabel, groupBy, className, }: ActivityCardProps): JSX.Element;
+
 export declare const AppShell: {
     (props: AppShellProps): JSX.Element | null;
-    /* Excluded from this release type: WithPages */
+    WithPages(pages: PageEntry[]): FC<AppShellProps>;
 };
 
 /**
@@ -134,6 +229,11 @@ export declare type AppShellPageProps = {
          * Icon displayed alongside the title in navigation.
          */
         icon?: ReactNode;
+        /**
+         * Custom breadcrumb segment title for this page.
+         * Can be a static string or a function that receives the URL segment.
+         */
+        breadcrumbTitle?: string | ((segment: string) => string);
     };
     /**
      * Guards to control access to this page.
@@ -224,14 +324,14 @@ export declare interface AppShellRegister {
  * ```tsx
  * // Plain function (default 300ms debounce)
  * fetcher: async (query, { signal }) => {
- *   const res = await fetch(`/api/search?q=${query}`, { signal });
+ *   const res = await fetch(`/api/search?q=${query ?? ""}`, { signal });
  *   return res.json();
  * }
  *
  * // Object with custom debounce
  * fetcher: {
  *   fn: async (query, { signal }) => {
- *     const res = await fetch(`/api/search?q=${query}`, { signal });
+ *     const res = await fetch(`/api/search?q=${query ?? ""}`, { signal });
  *     return res.json();
  *   },
  *   debounceMs: 500,
@@ -254,8 +354,13 @@ declare type AsyncFetcher<T> = AsyncFetcherFn<T> | {
  * If the fetcher throws, the component silently falls back to an empty
  * item list — there is no `onError` callback. Catch errors in the
  * fetcher to show toasts, log to error tracking, or return fallback data.
+ *
+ * The `query` parameter is `null` when the user has not typed anything
+ * (e.g. the dropdown was just opened). Return initial / default items
+ * for `null`, or return an empty array to show nothing until the user
+ * starts typing.
  */
-declare type AsyncFetcherFn<T> = (query: string, options: {
+declare type AsyncFetcherFn<T> = (query: string | null, options: {
     signal: AbortSignal;
 }) => Promise<T[]>;
 
@@ -498,6 +603,13 @@ declare namespace AutocompleteTrigger {
     var displayName: string;
 }
 
+/**
+ * Return type of `Autocomplete.useAsync`.
+ *
+ * Unlike `Combobox.useAsync`, this does **not** include `onOpenChange`.
+ * Autocomplete is driven by focus and typing — not by an explicit open/close
+ * toggle — so `onOpenChange` is intentionally omitted.
+ */
 declare interface AutocompleteUseAsyncReturn<T> {
     /** Fetched items — pass to the Root `items` prop */
     items: T[];
@@ -517,6 +629,18 @@ declare namespace AutocompleteValue {
     var displayName: string;
 }
 
+export declare const Avatar: {
+    Root: typeof Root_2;
+    Image: typeof Image_2;
+    Fallback: typeof Fallback;
+};
+
+export declare type AvatarProps = React_2.ComponentProps<typeof Avatar_2.Root> & VariantProps<typeof avatarVariants>;
+
+export declare const avatarVariants: (props?: ({
+    size?: "default" | "sm" | "lg" | null | undefined;
+} & ClassProp) | undefined) => string;
+
 export declare function Badge({ className, variant, children, ...props }: BadgeProps): JSX.Element;
 
 export declare interface BadgeProps extends React_2.HTMLAttributes<HTMLDivElement>, VariantProps<typeof badgeVariants> {
@@ -558,7 +682,7 @@ export declare type ButtonProps = React_2.ComponentProps<"button"> & VariantProp
 
 export declare const buttonVariants: (props?: ({
     variant?: "default" | "destructive" | "outline" | "secondary" | "ghost" | "link" | null | undefined;
-    size?: "default" | "sm" | "lg" | "icon" | null | undefined;
+    size?: "default" | "xs" | "sm" | "lg" | "icon" | null | undefined;
 } & ClassProp) | undefined) => string;
 
 /** A table caption element. */
@@ -568,6 +692,12 @@ declare namespace Caption {
     var displayName: string;
 }
 
+export declare const Card: {
+    Root: typeof Root_4;
+    Header: typeof Header_3;
+    Content: typeof Content;
+};
+
 /** A table data cell (`<td>`). */
 declare function Cell({ className, ...props }: React_2.ComponentProps<"td">): JSX.Element;
 
@@ -799,7 +929,7 @@ declare namespace ComboboxRoot {
     var displayName: string;
 }
 
-declare type ComboboxRootProps<Value, Multiple extends boolean | undefined = false> = Pick<React_2.ComponentProps<typeof Combobox_2.Root<Value, Multiple>>, "items" | "value" | "defaultValue" | "onValueChange" | "multiple" | "filter" | "inputValue" | "onInputValueChange" | "itemToStringLabel" | "itemToStringValue" | "disabled" | "children">;
+declare type ComboboxRootProps<Value, Multiple extends boolean | undefined = false> = Pick<React_2.ComponentProps<typeof Combobox_2.Root<Value, Multiple>>, "items" | "value" | "defaultValue" | "onValueChange" | "multiple" | "filter" | "inputValue" | "onInputValueChange" | "onOpenChange" | "itemToStringLabel" | "itemToStringValue" | "disabled" | "children">;
 
 declare function ComboboxStandalone<T extends object>(props: ComboboxStaticCreatableProps<T>): React_2.JSX.Element;
 
@@ -863,6 +993,7 @@ declare type CommonPageResource = {
     meta: {
         title: LocalizedString;
         icon?: ReactNode;
+        breadcrumbTitle?: string | ((segment: string) => string);
     };
 };
 
@@ -894,31 +1025,37 @@ declare type CommonProps = {
     guards?: Guard[];
 };
 
-/** The main dialog panel that contains the dialog content. Automatically includes a close button and overlay. */
-declare function Content({ className, children, ...props }: React_2.ComponentProps<typeof Dialog_2.Popup>): JSX.Element;
+declare function Content({ className, ...props }: React_2.ComponentProps<"div">): JSX.Element;
 
 declare namespace Content {
     var displayName: string;
 }
 
+/** The main dialog panel that contains the dialog content. Automatically includes a close button and overlay. */
+declare function Content_2({ className, children, ...props }: React_2.ComponentProps<typeof Dialog_2.Popup>): JSX.Element;
+
+declare namespace Content_2 {
+    var displayName: string;
+}
+
 /** The menu popup that displays menu items. */
-declare function Content_2({ className, position, children, ...restProps }: React_2.ComponentProps<typeof Menu_2.Popup> & {
+declare function Content_3({ className, position, children, ...restProps }: React_2.ComponentProps<typeof Menu_2.Popup> & {
     position?: PositionProps;
 }): JSX.Element;
 
-declare namespace Content_2 {
+declare namespace Content_3 {
     var displayName: string;
 }
 
 /** The main sheet panel. The `side` is inherited from `Sheet.Root` via context. */
-declare function Content_3({ className, children, ...props }: React_2.ComponentProps<typeof Drawer.Popup>): JSX.Element;
+declare function Content_4({ className, children, ...props }: React_2.ComponentProps<typeof Drawer.Popup>): JSX.Element;
 
-declare namespace Content_3 {
+declare namespace Content_4 {
     var displayName: string;
 }
 
 /** The tooltip popup that displays additional information. */
-declare function Content_4({ className, position, side: _side, align: _align, sideOffset: _sideOffset, children, ...restProps }: React_2.ComponentProps<typeof Tooltip_2.Popup> & {
+declare function Content_5({ className, position, side: _side, align: _align, sideOffset: _sideOffset, children, ...restProps }: React_2.ComponentProps<typeof Tooltip_2.Popup> & {
     position?: PositionProps;
     /** @deprecated Use `position={{ side }}` instead. */
     side?: PositionProps["side"];
@@ -928,7 +1065,7 @@ declare function Content_4({ className, position, side: _side, align: _align, si
     sideOffset?: PositionProps["sideOffset"];
 }): JSX.Element;
 
-declare namespace Content_4 {
+declare namespace Content_5 {
     var displayName: string;
 }
 
@@ -940,6 +1077,19 @@ export declare type ContextData = AppShellRegister extends {
     contextData: infer T;
 } ? T : Record<string, unknown>;
 
+/**
+ * A styled input control for the field.
+ *
+ * Can be omitted when using another Base UI-backed AppShell input component
+ * (e.g. Select, Combobox, Autocomplete) as a sibling — those components
+ * register themselves with the Field context automatically.
+ */
+declare function Control({ className, ...props }: React_2.ComponentProps<typeof Field_2.Control>): JSX.Element;
+
+declare namespace Control {
+    var displayName: string;
+}
+
 /**
  * Creatable opt-in props. When `onCreateItem` is provided, the combobox allows
  * users to create new items on-the-fly.
@@ -1295,13 +1445,25 @@ declare namespace Description {
     var displayName: string;
 }
 
-/** A description that provides additional context for the sheet. */
-declare function Description_2({ className, ...props }: React_2.ComponentProps<typeof Drawer.Description>): JSX.Element;
+/**
+ * A paragraph with additional information about the field.
+ *
+ * Its ID is registered with the Field context so that the control
+ * automatically receives a matching `aria-describedby` attribute.
+ */
+declare function Description_2({ className, ...props }: React_2.ComponentProps<typeof Field_2.Description>): JSX.Element;
 
 declare namespace Description_2 {
     var displayName: string;
 }
 
+/** A description that provides additional context for the sheet. */
+declare function Description_3({ className, ...props }: React_2.ComponentProps<typeof Drawer.Description>): JSX.Element;
+
+declare namespace Description_3 {
+    var displayName: string;
+}
+
 /**
  * DescriptionCard - ERP document display component
  *
@@ -1345,12 +1507,12 @@ export declare interface DescriptionCardProps {
 }
 
 export declare const Dialog: {
-    Root: typeof Root_2;
+    Root: typeof Root_5;
     Close: typeof Close;
-    Content: typeof Content;
+    Content: typeof Content_2;
     Description: typeof Description;
     Footer: typeof Footer_2;
-    Header: typeof Header_3;
+    Header: typeof Header_4;
     Title: typeof Title;
     Trigger: typeof Trigger;
 };
@@ -1383,6 +1545,62 @@ export declare interface EnhancedAuthClient extends AuthClient {
     fetch: AuthClient["fetch"];
 }
 
+/**
+ * An error message displayed if the field control fails validation.
+ *
+ * Its ID is registered with the Field context and appended to the control's
+ * `aria-describedby`. Use the `match` prop to show the message only for a
+ * specific `ValidityState` key (e.g. `"valueMissing"`, `"typeMismatch"`).
+ * Omitting `match` shows the browser's default validation message.
+ *
+ * Multiple `Field.Error` elements can be placed in the same `Field.Root` to
+ * handle different validation failures independently.
+ *
+ * @example
+ * ### Single catch-all error
+ * ```tsx
+ * <Field.Root name="name">
+ *   <Field.Label>Name</Field.Label>
+ *   <Field.Control required />
+ *   <Field.Error>This field is required.</Field.Error>
+ * </Field.Root>
+ * ```
+ *
+ * @example
+ * ### Multiple errors for different validity states
+ * ```tsx
+ * <Field.Root name="email">
+ *   <Field.Label>Email</Field.Label>
+ *   <Field.Control type="email" required />
+ *   <Field.Error match="valueMissing">Email is required.</Field.Error>
+ *   <Field.Error match="typeMismatch">Please enter a valid email address.</Field.Error>
+ * </Field.Root>
+ * ```
+ *
+ * @example
+ * ### With React Hook Form error
+ * ```tsx
+ * <Controller
+ *   name="email"
+ *   control={control}
+ *   render={({ field, fieldState }) => (
+ *     <Field.Root {...fieldState}>
+ *       <Field.Label>Email</Field.Label>
+ *       <Field.Control {...field} />
+ *       <Field.Error match={!!fieldState.error}>
+ *         {fieldState.error?.message}
+ *       </Field.Error>
+ *     </Field.Root>
+ *   )}
+ * />
+ * ```
+ */
+declare function Error_2({ className, ...props }: React_2.ComponentProps<typeof Field_2.Error>): JSX.Element;
+
+declare namespace Error_2 {
+    var displayName: string;
+}
+
 /**
  * Error boundary element type for route error handling.
  *
@@ -1448,6 +1666,22 @@ declare type ExtractBasePath<T extends string> = T extends `${infer Base}?${stri
 /** Extracts the item type from a possibly-grouped items array element. */
 declare type ExtractItem<I> = I extends ItemGroup<infer T> ? T : I;
 
+/** Shown when there is no image or the image failed to load. */
+declare function Fallback({ className, ...props }: React_2.ComponentProps<typeof Avatar_2.Fallback>): JSX.Element;
+
+declare namespace Fallback {
+    var displayName: string;
+}
+
+export declare const Field: {
+    Root: typeof Root_6;
+    Label: typeof Label;
+    Control: typeof Control;
+    Description: typeof Description_2;
+    Error: typeof Error_2;
+    Validity: typeof Validity;
+};
+
 /**
  * A field configuration - either a divider or a field definition
  */
@@ -1502,6 +1736,50 @@ declare interface FieldMeta {
     truncateLines?: number;
 }
 
+declare type FieldRootProps = Pick<React_2.ComponentProps<typeof Field_2.Root>, "name" | "disabled" | "validate" | "validationMode" | "validationDebounceTime" | "className" | "style"> & {
+    children: React_2.ReactNode;
+    /** Whether the field has been blurred. Maps to Base UI's `touched`. */
+    isTouched?: boolean;
+    /** Whether the field value differs from the default. Maps to Base UI's `dirty`. */
+    isDirty?: boolean;
+    /** When true, marks the field as invalid. Also set automatically when `error` is provided. */
+    invalid?: boolean;
+    /**
+     * An error object (e.g. from React Hook Form's `fieldState.error`).
+     * When provided, the field is marked invalid (`invalid={!!error}`).
+     */
+    error?: {
+        message?: string;
+    };
+};
+
+export declare const Fieldset: {
+    Root: typeof Root_7;
+    Legend: typeof Legend;
+};
+
+/**
+ * Groups related fields with a shared legend for accessible form sectioning.
+ *
+ * @example
+ * ```tsx
+ * <Fieldset.Root>
+ *   <Fieldset.Legend>Billing details</Fieldset.Legend>
+ *   <Field.Root name="company">
+ *     <Field.Label>Company</Field.Label>
+ *     <Field.Control />
+ *   </Field.Root>
+ *   <Field.Root name="taxId">
+ *     <Field.Label>Tax ID</Field.Label>
+ *     <Field.Control />
+ *   </Field.Root>
+ * </Fieldset.Root>
+ * ```
+ */
+declare type FieldsetRootProps = Pick<React_2.ComponentProps<typeof Fieldset_2.Root>, "disabled" | "className" | "style"> & {
+    children: React_2.ReactNode;
+};
+
 /**
  * Supported field types for DescriptionCard
  */
@@ -1528,6 +1806,96 @@ declare namespace Footer_3 {
     var displayName: string;
 }
 
+/**
+ * A form element with consolidated error handling and validation.
+ *
+ * Wraps every child `Field.Root` in a shared validation / error context.
+ * External errors passed via `errors` are automatically routed to matching
+ * `Field.Error` components by field `name`, and cleared when the user edits
+ * the corresponding field.
+ *
+ * ## Validation flow
+ *
+ * Each `Field.Root` can declare its own `validate` function and/or rely on
+ * native HTML constraint attributes (`required`, `type="email"`, `pattern`,
+ * etc.). The moment validation fires is controlled by `validationMode`
+ * (default `"onSubmit"`).
+ *
+ * External errors (e.g. from an API response) can be fed back via `errors`.
+ * Errors are keyed by the field's `name` attribute and rendered by any
+ * `Field.Error` with a matching `match` or a catch-all `Field.Error`
+ * (no `match`).
+ *
+ * ## Programmatic validation
+ *
+ * Use `actionsRef` to imperatively trigger validation from outside the
+ * normal submit flow (e.g. a "Validate" button or a multi-step wizard).
+ *
+ * ```tsx
+ * const actions = React.useRef<{ validate: () => void }>(null);
+ * <Form actionsRef={actions}>…</Form>
+ * <button onClick={() => actions.current?.validate()}>Check</button>
+ * ```
+ *
+ * @example
+ * ### Basic usage
+ * ```tsx
+ * <Form onFormSubmit={(values) => save(values)}>
+ *   <Field.Root name="email">
+ *     <Field.Label>Email</Field.Label>
+ *     <Field.Control type="email" required />
+ *     <Field.Error match="typeMismatch">Enter a valid email.</Field.Error>
+ *   </Field.Root>
+ *   <button type="submit">Save</button>
+ * </Form>
+ * ```
+ *
+ * @example
+ * ### External errors (e.g. API validation)
+ * ```tsx
+ * const [errors, setErrors] = React.useState({});
+ *
+ * async function handleSubmit(values) {
+ *   const res = await api.save(values);
+ *   if (res.errors) setErrors(res.errors);
+ * }
+ *
+ * <Form errors={errors} onFormSubmit={handleSubmit}>
+ *   <Field.Root name="url">
+ *     <Field.Label>Homepage</Field.Label>
+ *     <Field.Control type="url" required />
+ *     <Field.Error />
+ *   </Field.Root>
+ *   <button type="submit">Submit</button>
+ * </Form>
+ * ```
+ */
+export declare function Form<FormValues extends Record<string, any> = Record<string, any>>({ className, children, ...props }: FormProps<FormValues>): JSX.Element;
+
+export declare namespace Form {
+    var displayName: string;
+}
+
+export declare type FormProps<FormValues extends Record<string, any> = Record<string, any>> = Pick<React_2.ComponentProps<typeof Form_2>, "errors" | "actionsRef" | "validationMode" | "noValidate" | "ref" | "className" | "style"> & {
+    children: React_2.ReactNode;
+    /**
+     * Low-level submit handler that receives the native `FormEvent`.
+     * Use this when you need direct access to the event (e.g. integrating
+     * with React Hook Form's `handleSubmit`). For type-safe parsed form
+     * values, prefer `onFormSubmit` instead.
+     */
+    onSubmit?: React_2.ComponentProps<typeof Form_2>["onSubmit"];
+    /**
+     * Called after successful validation with the parsed form values as a
+     * typed object. Prefer this for simple forms that don't use an external
+     * form library. When integrating with React Hook Form, use `onSubmit`
+     * instead.
+     */
+    onFormSubmit?: ((formValues: FormValues, eventDetails: FormSubmitEventDetails) => void) | undefined;
+};
+
+declare type FormSubmitEventDetails = NonNullable<React_2.ComponentProps<typeof Form_2>["onFormSubmit"]> extends (values: any, details: infer D) => any ? D : never;
+
 /** Groups related menu items with the corresponding label. */
 declare function Group({ ...props }: React_2.ComponentProps<typeof Menu_2.Group>): JSX.Element;
 
@@ -1633,20 +2001,31 @@ declare namespace Header_2 {
     var displayName: string;
 }
 
-/** A layout wrapper for the dialog title and description. */
-declare function Header_3({ className, ...props }: React_2.ComponentProps<"div">): JSX.Element;
+declare function Header_3({ className, title, description, children, ...props }: HeaderProps): JSX.Element;
 
 declare namespace Header_3 {
     var displayName: string;
 }
 
-/** A layout wrapper for the sheet title and description. */
+/** A layout wrapper for the dialog title and description. */
 declare function Header_4({ className, ...props }: React_2.ComponentProps<"div">): JSX.Element;
 
 declare namespace Header_4 {
     var displayName: string;
 }
 
+/** A layout wrapper for the sheet title and description. */
+declare function Header_5({ className, ...props }: React_2.ComponentProps<"div">): JSX.Element;
+
+declare namespace Header_5 {
+    var displayName: string;
+}
+
+declare type HeaderProps = Omit<React_2.ComponentProps<"div">, "title"> & {
+    title?: React_2.ReactNode;
+    description?: React_2.ReactNode;
+};
+
 /**
  * Deny access and show 404 Not Found.
  *
@@ -1668,6 +2047,13 @@ export declare type I18nLabels<Def extends Record<string, LabelValue> = Record<s
     [K in L]: LabelDefinition<Def>;
 } & DynamicLocales<Def>;
 
+/** Profile image; hidden when missing or failed to load. */
+declare function Image_2({ className, ...props }: React_2.ComponentProps<typeof Avatar_2.Image>): JSX.Element;
+
+declare namespace Image_2 {
+    var displayName: string;
+}
+
 /**
  * A styled input component.
  *
@@ -1688,13 +2074,19 @@ export declare type InputProps = React_2.ComponentProps<"input">;
  */
 declare type IsEmptyObject<T> = keyof T extends never ? true : false;
 
-/** An individual interactive item in the menu. */
-declare function Item({ className, ...props }: React_2.ComponentProps<typeof Menu_2.Item>): JSX.Element;
+declare function Item({ indicator, children, className }: ActivityCardItemProps): JSX.Element;
 
 declare namespace Item {
     var displayName: string;
 }
 
+/** An individual interactive item in the menu. */
+declare function Item_2({ className, ...props }: React_2.ComponentProps<typeof Menu_2.Item>): JSX.Element;
+
+declare namespace Item_2 {
+    var displayName: string;
+}
+
 /**
  * A group of items with a label, used by Select, Combobox, and Autocomplete standalone components.
  *
@@ -1707,6 +2099,26 @@ export declare interface ItemGroup<T> {
     items: T[];
 }
 
+declare function Items<T extends ActivityCardBaseItem>({ children }: ActivityCardItemsProps<T>): JSX.Element;
+
+declare namespace Items {
+    var displayName: string;
+}
+
+/**
+ * An accessible label that is automatically associated with the field control.
+ *
+ * Uses the `LabelableContext` provided by `Field.Root` to resolve `htmlFor`.
+ * Any Base UI control inside the same `Field.Root` (Field.Control, Select,
+ * Combobox, Autocomplete) registers its ID with the context, so clicking
+ * this label will focus the correct control.
+ */
+declare function Label({ className, ...props }: React_2.ComponentProps<typeof Field_2.Label>): JSX.Element;
+
+declare namespace Label {
+    var displayName: string;
+}
+
 /**
  * Ensures that other locales have the same label structure as the base definition.
  * For dynamic labels (functions), the props type must match.
@@ -1814,6 +2226,13 @@ export declare interface LayoutProps {
     children: ReactNode;
 }
 
+/** An accessible legend that is automatically associated with the fieldset. */
+declare function Legend({ className, ...props }: React_2.ComponentProps<typeof Fieldset_2.Legend>): JSX.Element;
+
+declare namespace Legend {
+    var displayName: string;
+}
+
 export { Link }
 
 /** A link item in the menu that can be used to navigate to a different page. */
@@ -1838,10 +2257,10 @@ export declare interface MappedItem {
 }
 
 export declare const Menu: {
-    Root: typeof Root_3;
+    Root: typeof Root_8;
     Trigger: typeof Trigger_2;
-    Content: typeof Content_2;
-    Item: typeof Item;
+    Content: typeof Content_3;
+    Item: typeof Item_2;
     LinkItem: typeof LinkItem;
     CheckboxItem: typeof CheckboxItem;
     CheckboxItemIndicator: typeof CheckboxItemIndicator;
@@ -1866,6 +2285,57 @@ declare namespace MenuSeparator {
     var displayName: string;
 }
 
+/**
+ * MetricCard — Compact card for dashboard KPI display (title, value, optional trend and description).
+ *
+ * Static display only in v1. Use for summary metrics (e.g. net total, discount total).
+ * Styling follows existing card conventions (bg-card, border, rounded-xl).
+ *
+ * @example
+ * ```tsx
+ * <MetricCard
+ *   title="Net total payment"
+ *   value="$1,500.00"
+ *   trend={{ direction: "up", value: "+5%" }}
+ *   description="vs last month"
+ * />
+ * ```
+ */
+export declare function MetricCard({ title, value, trend, description, icon, className }: MetricCardProps): JSX.Element;
+
+/**
+ * Props for the MetricCard component.
+ */
+export declare interface MetricCardProps {
+    /** Metric title / header (e.g. "Net total payment") */
+    title: string;
+    /** Primary value (e.g. formatted currency or number) */
+    value: ReactNode;
+    /** Optional trend indicator */
+    trend?: MetricCardTrend;
+    /**
+     * Optional supplementary description (e.g. "vs last period", "this week").
+     * Empty strings are treated as absent and the description is not rendered in the meta row.
+     */
+    description?: string;
+    /** Optional leading icon */
+    icon?: ReactNode;
+    /** Additional CSS classes for the card container */
+    className?: string;
+}
+
+declare interface MetricCardTrend {
+    /** Visual and semantic direction */
+    direction: MetricCardTrendDirection;
+    /** Display value (e.g. "+12%", "-5%") */
+    value: string;
+}
+
+/**
+ * Trend direction for metric display (e.g. up = positive, down = negative).
+ */
+declare type MetricCardTrendDirection = "up" | "down" | "neutral";
+
 /**
  * A resource that can be included in the root-level content in the navigation.
  */
@@ -2013,6 +2483,50 @@ declare type ResourceMeta = {
     breadcrumbTitle?: string | ((segment: string) => string);
 };
 
+declare function Root<T extends ActivityCardBaseItem>({ items, title, maxVisible, overflowLabel, groupBy, className, children, }: ActivityCardRootProps<T>): JSX.Element;
+
+declare namespace Root {
+    var displayName: string;
+}
+
+/**
+ * The root component that manages tooltip open/close state.
+ *
+ * @example
+ * ```tsx
+ * <Tooltip.Root>
+ *   <Tooltip.Trigger render={<Button variant="outline" />}>
+ *     Hover me
+ *   </Tooltip.Trigger>
+ *   <Tooltip.Content>Helpful information</Tooltip.Content>
+ * </Tooltip.Root>
+ * ```
+ */
+declare function Root_10({ children, ...props }: TooltipRootProps): JSX.Element;
+
+declare namespace Root_10 {
+    var displayName: string;
+}
+
+/**
+ * Root container for an avatar (image with optional fallback).
+ *
+ * @example
+ * ```tsx
+ * import { Avatar } from "@tailor-platform/app-shell";
+ *
+ * <Avatar.Root>
+ *   <Avatar.Image src="/user.png" alt="User" />
+ *   <Avatar.Fallback>AB</Avatar.Fallback>
+ * </Avatar.Root>
+ * ```
+ */
+declare function Root_2({ className, size, ...props }: AvatarProps): JSX.Element;
+
+declare namespace Root_2 {
+    var displayName: string;
+}
+
 /**
  * The root table element with a horizontally scrollable container.
  *
@@ -2036,9 +2550,15 @@ declare type ResourceMeta = {
  * </Table.Root>
  * ```
  */
-declare function Root({ className, containerClassName, ...props }: RootProps): JSX.Element;
+declare function Root_3({ className, containerClassName, ...props }: RootProps): JSX.Element;
 
-declare namespace Root {
+declare namespace Root_3 {
+    var displayName: string;
+}
+
+declare function Root_4({ className, ...props }: React_2.ComponentProps<"div">): JSX.Element;
+
+declare namespace Root_4 {
     var displayName: string;
 }
 
@@ -2062,9 +2582,70 @@ declare namespace Root {
  * </Dialog.Root>
  * ```
  */
-declare function Root_2({ ...props }: DialogRootProps): JSX.Element;
+declare function Root_5({ ...props }: DialogRootProps): JSX.Element;
 
-declare namespace Root_2 {
+declare namespace Root_5 {
+    var displayName: string;
+}
+
+/**
+ * Groups all parts of a form field and manages its validation state.
+ *
+ * Provides a `LabelableContext` and `FieldRootContext` that Base UI controls
+ * automatically connect to. Any Base UI-backed control placed as a child
+ * (e.g. Select, Combobox, Autocomplete, Field.Control) will:
+ *
+ * - Register its ID so that `Field.Label` receives the correct `htmlFor`
+ * - Receive `aria-describedby` linking to `Field.Description` and `Field.Error`
+ * - Inherit the `disabled` state from this root
+ * - Participate in the validation system (`invalid`, `dirty`, `touched`)
+ *
+ * This means `Field.Control` can be omitted when using another AppShell input
+ * component — the wiring happens automatically through Base UI's context.
+ *
+ * @example
+ * ### With Field.Control (plain input)
+ * ```tsx
+ * <Field.Root name="email">
+ *   <Field.Label>Email</Field.Label>
+ *   <Field.Control type="email" required />
+ *   <Field.Description>We'll never share your email.</Field.Description>
+ *   <Field.Error match="typeMismatch">Please enter a valid email.</Field.Error>
+ * </Field.Root>
+ * ```
+ *
+ * @example
+ * ### With React Hook Form (Controller spread)
+ * ```tsx
+ * <Controller
+ *   name="email"
+ *   control={control}
+ *   rules={{ required: "Required" }}
+ *   render={({ field, fieldState }) => (
+ *     <Field.Root {...fieldState}>
+ *       <Field.Label>Email</Field.Label>
+ *       <Field.Control {...field} type="email" />
+ *       <Field.Error match={fieldState.invalid}>{fieldState.error?.message}</Field.Error>
+ *     </Field.Root>
+ *   )}
+ * />
+ * ```
+ *
+ * > **Note:** When combining RHF with `Form`'s `errors` prop for server-side
+ * > error routing, add `name={field.name}` to `Field.Root` so errors can be
+ * > matched by field name.
+ */
+declare function Root_6({ className, children, isTouched, isDirty, invalid, error, isValidating: _isValidating, ...props }: FieldRootProps & {
+    isValidating?: unknown;
+}): JSX.Element;
+
+declare namespace Root_6 {
+    var displayName: string;
+}
+
+declare function Root_7({ className, ...props }: FieldsetRootProps): JSX.Element;
+
+declare namespace Root_7 {
     var displayName: string;
 }
 
@@ -2084,9 +2665,9 @@ declare namespace Root_2 {
  * </Menu.Root>
  * ```
  */
-declare function Root_3({ children, ...props }: MenuRootProps): JSX.Element;
+declare function Root_8({ children, ...props }: MenuRootProps): JSX.Element;
 
-declare namespace Root_3 {
+declare namespace Root_8 {
     var displayName: string;
 }
 
@@ -2110,28 +2691,9 @@ declare namespace Root_3 {
  * </Sheet.Root>
  * ```
  */
-declare function Root_4({ side, ...props }: SheetRootProps): JSX.Element;
+declare function Root_9({ side, ...props }: SheetRootProps): JSX.Element;
 
-declare namespace Root_4 {
-    var displayName: string;
-}
-
-/**
- * The root component that manages tooltip open/close state.
- *
- * @example
- * ```tsx
- * <Tooltip.Root>
- *   <Tooltip.Trigger render={<Button variant="outline" />}>
- *     Hover me
- *   </Tooltip.Trigger>
- *   <Tooltip.Content>Helpful information</Tooltip.Content>
- * </Tooltip.Root>
- * ```
- */
-declare function Root_5({ children, ...props }: TooltipRootProps): JSX.Element;
-
-declare namespace Root_5 {
+declare namespace Root_9 {
     var displayName: string;
 }
 
@@ -2314,6 +2876,12 @@ declare namespace SelectValue {
     var displayName: string;
 }
 
+/**
+ * Shared props between `AppShellProps` and the internal `WithPages` wrapper.
+ *
+ * These props are available regardless of whether routes are configured
+ * automatically (via vite-plugin) or manually (via `modules` prop).
+ */
 declare type SharedAppShellProps = React.PropsWithChildren<{
     /**
      * App shell title
@@ -2337,6 +2905,23 @@ declare type SharedAppShellProps = React.PropsWithChildren<{
      * ```
      */
     rootComponent?: () => React.ReactNode;
+    /**
+     * Guards for the root route.
+     *
+     * When using file-based routing, this is automatically set from
+     * the root page's guards via `AppShell.WithPages()`.
+     *
+     * @example
+     * ```tsx
+     * import { redirectTo } from "@tailor-platform/app-shell";
+     *
+     * <AppShell
+     *   modules={[...]}
+     *   rootGuards={[() => redirectTo("/dashboard")]}
+     * />
+     * ```
+     */
+    rootGuards?: Guard[];
     /**
      * Settings resources to be included in the settings menu
      */
@@ -2404,14 +2989,14 @@ declare type SharedAppShellProps = React.PropsWithChildren<{
 }>;
 
 export declare const Sheet: {
-    Root: typeof Root_4;
+    Root: typeof Root_9;
     Trigger: typeof Trigger_3;
     Close: typeof Close_2;
-    Content: typeof Content_3;
-    Header: typeof Header_4;
+    Content: typeof Content_4;
+    Header: typeof Header_5;
     Footer: typeof Footer_3;
     Title: typeof Title_2;
-    Description: typeof Description_2;
+    Description: typeof Description_3;
 };
 
 declare type SheetRootProps = Pick<React_2.ComponentProps<typeof Drawer.Root>, "open" | "defaultOpen" | "onOpenChange" | "modal"> & {
@@ -2620,7 +3205,7 @@ declare namespace SubmenuTrigger {
 }
 
 export declare const Table: {
-    Root: typeof Root;
+    Root: typeof Root_3;
     Header: typeof Header_2;
     Body: typeof Body_2;
     Footer: typeof Footer;
@@ -2653,9 +3238,9 @@ declare namespace Title_2 {
 }
 
 export declare const Tooltip: {
-    Root: typeof Root_5;
+    Root: typeof Root_10;
     Trigger: typeof Trigger_4;
-    Content: typeof Content_4;
+    Content: typeof Content_5;
     Provider: typeof Provider;
 };
 
@@ -2800,7 +3385,7 @@ declare function useAsync<T>(options: UseAsyncItemsOptions<T>): UseAsyncItemsRet
  * ```tsx
  * const movies = Autocomplete.useAsync({
  *   fetcher: async (query, { signal }) => {
- *     const res = await fetch(`/api/movies?q=${query}`, { signal });
+ *     const res = await fetch(`/api/movies?q=${query ?? ""}`, { signal });
  *     if (!res.ok) return [];
  *     return res.json();
  *   },
@@ -2840,7 +3425,7 @@ declare interface UseAsyncItemsOptions<T> {
      * ```tsx
      * // Plain function
      * fetcher: async (query, { signal }) => {
-     *   const res = await fetch(`/api/search?q=${query}`, { signal });
+     *   const res = await fetch(`/api/search?q=${query ?? ""}`, { signal });
      *   return res.json();
      * }
      *
@@ -2865,6 +3450,8 @@ declare interface UseAsyncItemsReturn<T> {
     error: unknown;
     /** Input change handler — pass to the Root `onInputValueChange` prop */
     onInputValueChange: (value: string) => void;
+    /** Open change handler — pass to the Root `onOpenChange` prop to fetch initial items on open */
+    onOpenChange: (open: boolean) => void;
 }
 
 /**
@@ -3105,6 +3692,32 @@ export { useLocation }
 
 export { useNavigate }
 
+/**
+ * Override the breadcrumb title for the current page.
+ *
+ * When `title` is a string, the breadcrumb segment matching the current path
+ * is replaced with that value. When `title` is `undefined`, any previous
+ * override is removed and the default title (from `defineResource`) is used.
+ *
+ * This hook is designed to work seamlessly with async data fetching — pass
+ * the result of a query directly and the breadcrumb will update reactively.
+ *
+ * @example
+ * ```tsx
+ * defineResource({
+ *   path: ":id",
+ *   meta: { breadcrumbTitle: (segment) => `#${segment}` },
+ *   component: () => {
+ *     const { id } = useParams();
+ *     const { data } = useQuery(GET_ORDER, { variables: { id } });
+ *     useOverrideBreadcrumb(data?.order?.name);
+ *     return <OrderDetail />;
+ *   },
+ * });
+ * ```
+ */
+export declare function useOverrideBreadcrumb(title: string | undefined): void;
+
 /**
  * Find page meta (title, icon) for a given URL path.
  * Searches through modules and their resources recursively.
@@ -3124,6 +3737,57 @@ export declare const useTheme: () => ThemeProviderState;
 
 export declare const useToast: () => typeof toast;
 
+/**
+ * Used to display a custom message based on the field's validity state.
+ *
+ * Requires `children` to be a render function that receives a
+ * `FieldValidityState` object. The `validity` property within it mirrors the
+ * browser's `ValidityState` (e.g. `valueMissing`, `tooShort`, `valid`),
+ * enabling fully custom validation UI.
+ *
+ * @example
+ * ### Checklist-style password requirements
+ * ```tsx
+ * <Field.Root name="password">
+ *   <Field.Label>Password</Field.Label>
+ *   <Field.Control type="password" required minLength={8} />
+ *   <Field.Validity>
+ *     {(state) => (
+ *       <ul>
+ *         <li>{state.validity.valueMissing ? "NG" : "OK"} Required</li>
+ *         <li>{state.validity.tooShort ? "NG" : "OK"} At least 8 characters</li>
+ *       </ul>
+ *     )}
+ *   </Field.Validity>
+ * </Field.Root>
+ * ```
+ *
+ * @example
+ * ### Conditional styling based on validity
+ * ```tsx
+ * <Field.Root name="url">
+ *   <Field.Label>Website</Field.Label>
+ *   <Field.Control type="url" required />
+ *   <Field.Validity>
+ *     {(state) =>
+ *       state.validity.valid === false && (
+ *         <p className="text-destructive text-sm">
+ *           {state.validity.typeMismatch
+ *             ? "Please enter a valid URL (e.g. https://example.com)"
+ *             : "This field is required."}
+ *         </p>
+ *       )
+ *     }
+ *   </Field.Validity>
+ * </Field.Root>
+ * ```
+ */
+declare function Validity({ ...props }: React_2.ComponentProps<typeof Field_2.Validity>): JSX.Element;
+
+declare namespace Validity {
+    var displayName: string;
+}
+
 /**
  * Conditionally render children based on guard evaluation.
  *
@@ -3190,6 +3854,4 @@ export declare type WithGuardProps = {
     loading?: ReactNode;
 };
 
-declare function withPages(pages: PageEntry[]): FC<AppShellProps>;
-
 export { }