@tailor-platform/app-shell 1.7.0 → 1.8.0

package/dist/app-shell.d.ts

@@ -2,9 +2,12 @@ import { AuthClient } from '@tailor-platform/auth-public-client';
 import { Autocomplete as Autocomplete_2 } from '@base-ui/react/autocomplete';
 import { AutocompleteRootProps } from '@base-ui/react/autocomplete';
 import { Avatar as Avatar_2 } from '@base-ui/react/avatar';
+import { CalendarDate } from '@internationalized/date';
+import { CalendarDateTime } from '@internationalized/date';
 import { ClassProp } from 'class-variance-authority/types';
 import { Combobox as Combobox_2 } from '@base-ui/react/combobox';
 import { CSSProperties } from 'react';
+import { DateValue } from '@internationalized/date';
 import { Dialog as Dialog_2 } from '@base-ui/react/dialog';
 import { Drawer } from '@base-ui/react/drawer';
 import { FC } from 'react';
@@ -12,15 +15,22 @@ 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 { getFilter } from '@base-ui/react/internals/filter';
+import { getLocalTimeZone } from '@internationalized/date';
 import { JSX } from 'react/jsx-runtime';
 import { Link } from 'react-router';
 import { LoaderFunctionArgs } from 'react-router';
 import { Menu as Menu_2 } from '@base-ui/react/menu';
+import { parseAbsolute } from '@internationalized/date';
+import { parseDate } from '@internationalized/date';
+import { parseDateTime } from '@internationalized/date';
+import { parseZonedDateTime } from '@internationalized/date';
 import * as React_2 from 'react';
 import { ReactNode } from 'react';
+import { RefObject } from 'react';
 import { Select as Select_2 } from '@base-ui/react/select';
 import { StandardSchemaV1 } from '@standard-schema/spec';
 import { Tabs as Tabs_2 } from '@base-ui/react/tabs';
+import { Time } from '@internationalized/date';
 import { toast } from 'sonner';
 import { Tooltip as Tooltip_2 } from '@base-ui/react/tooltip';
 import { useLocation } from 'react-router';
@@ -29,6 +39,7 @@ import { useParams } from 'react-router';
 import { useRouteError } from 'react-router';
 import { useSearchParams } from 'react-router';
 import { VariantProps } from 'class-variance-authority';
+import { ZonedDateTime } from '@internationalized/date';
 
 /**
  * A single action row in the ActionPanel (icon + label, triggered by onClick).
@@ -215,7 +226,6 @@ export declare type AIGatewayChatMessage = {
 export declare interface AIGatewayChatRequest {
     model: string;
     messages: AIGatewayChatMessage[];
-    stream?: boolean;
     signal?: AbortSignal;
 }
 
@@ -876,6 +886,49 @@ export declare const buttonVariants: (props?: ({
     size?: "default" | "xs" | "sm" | "lg" | "icon" | null | undefined;
 } & ClassProp) | undefined) => string;
 
+/**
+ * A standalone inline calendar — no popover, suitable for reporting filters
+ * or date selection within a larger layout.
+ *
+ * @example
+ * ```tsx
+ * import { Calendar } from "@tailor-platform/app-shell";
+ *
+ * <Calendar aria-label="Select date" value={value} onChange={setValue} />
+ * ```
+ */
+export declare function Calendar<T extends DateValue = DateValue>({ value, defaultValue, onChange, minValue, maxValue, isDateUnavailable, isDisabled, isReadOnly, focusedValue, defaultFocusedValue, onFocusChange, firstDayOfWeek, timeZone: timeZoneProp, locale: localeProp, className, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, }: CalendarProps<T>): JSX.Element;
+
+export { CalendarDate }
+
+export { CalendarDateTime }
+
+/**
+ * Public, closed-API standalone calendar — the @internationalized/date + Base UI
+ * implementation. Same surface as the react-aria variant; only the internals
+ * differ. Consumers never see Base UI or the calendar engine.
+ */
+export declare interface CalendarProps<T extends DateValue = DateValue> {
+    value?: T | null;
+    defaultValue?: T | null;
+    onChange?: (value: T) => void;
+    minValue?: DateValue;
+    maxValue?: DateValue;
+    isDateUnavailable?: (date: DateValue) => boolean;
+    isDisabled?: boolean;
+    isReadOnly?: boolean;
+    focusedValue?: DateValue;
+    defaultFocusedValue?: DateValue;
+    onFocusChange?: (date: CalendarDate) => void;
+    firstDayOfWeek?: FirstDayOfWeek;
+    "aria-label"?: string;
+    "aria-labelledby"?: string;
+    timeZone?: string;
+    className?: string;
+    /** BCP-47 locale override; defaults to the AppShell formatting locale. */
+    locale?: string;
+}
+
 /**
  * Internal type for tracking OAuth callback handling status.
  */
@@ -2091,6 +2144,29 @@ declare namespace DataTableToolbar {
     var displayName: string;
 }
 
+declare interface DateBehaviorProps<T extends DateValue> {
+    value?: T | null;
+    defaultValue?: T | null;
+    onChange?: (value: T | null) => void;
+    granularity?: Granularity;
+    minValue?: DateValue;
+    maxValue?: DateValue;
+    isDateUnavailable?: (date: DateValue) => boolean;
+    isDisabled?: boolean;
+    isReadOnly?: boolean;
+    isRequired?: boolean;
+    isInvalid?: boolean;
+    autoFocus?: boolean;
+    hourCycle?: HourCycle;
+    hideTimeZone?: boolean;
+    placeholderValue?: DateValue;
+    name?: string;
+    /** Accessible name when no visible `label` is provided (e.g. a compact filter input). */
+    "aria-label"?: string;
+    /** BCP-47 locale override; defaults to the AppShell formatting locale. */
+    locale?: string;
+}
+
 /** Options for `type: "date"` cells. */
 declare interface DateCellOptions {
     /**
@@ -2102,11 +2178,107 @@ declare interface DateCellOptions {
     locale?: string;
 }
 
+/**
+ * A segmented date/time input field with no popover.
+ *
+ * @example
+ * ```tsx
+ * import { DateField } from "@tailor-platform/app-shell";
+ *
+ * <DateField label="Invoice date" />
+ * <DateField label="Created at" granularity="minute" />
+ * ```
+ */
+export declare function DateField<T extends DateValue = DateValue>({ label, description, errorMessage, className, locale: localeProp, value, defaultValue, onChange, granularity, hourCycle, placeholderValue, isDisabled, isReadOnly, isInvalid, isRequired, autoFocus, name, "aria-label": ariaLabel, }: DateFieldProps<T>): JSX.Element;
+
+declare interface DateFieldMetaProps {
+    label?: LocalizedString;
+    description?: LocalizedString;
+    errorMessage?: LocalizedString;
+    className?: string;
+}
+
+export declare type DateFieldProps<T extends DateValue = DateValue> = DateFieldMetaProps & DateBehaviorProps<T>;
+
 /**
  * Date format options
  */
 declare type DateFormat = "short" | "medium" | "long" | "relative";
 
+/**
+ * A date/time input with a popover calendar.
+ *
+ * Value type is driven by `granularity`:
+ * - `"day"` (default) → `CalendarDate`
+ * - `"hour" | "minute" | "second"` → `CalendarDateTime` (or `ZonedDateTime` when a `timeZone` is set)
+ *
+ * @example
+ * ```tsx
+ * import { DatePicker, today, getLocalTimeZone, type CalendarDate } from "@tailor-platform/app-shell";
+ *
+ * const [date, setDate] = useState<CalendarDate | null>(null);
+ * <DatePicker label="Ship date" value={date} onChange={setDate} />
+ * ```
+ */
+export declare function DatePicker<T extends DateValue = DateValue>({ label, description, errorMessage, className, locale: localeProp, timeZone: timeZoneProp, value, defaultValue, onChange, granularity, hourCycle, placeholderValue, minValue, maxValue, isDateUnavailable, isDisabled, isReadOnly, isInvalid, isRequired, autoFocus, firstDayOfWeek, name, "aria-label": ariaLabel, }: DatePickerProps<T>): JSX.Element;
+
+export declare type DatePickerProps<T extends DateValue = DateValue> = DateFieldProps<T> & {
+    firstDayOfWeek?: FirstDayOfWeek;
+    /** IANA timezone; defaults to the AppShell `timeZone`. */
+    timeZone?: string;
+};
+
+export { DateValue }
+
+/**
+ * DefaultHeader — the built-in `SidebarLayout` top bar.
+ *
+ * Renders the sidebar trigger and breadcrumb trail on the left, and the
+ * `actions` cluster (defaulting to the appearance switcher) on the right.
+ *
+ * Use it via the `SidebarLayout.DefaultHeader` namespace to slightly extend the
+ * built-in header without reconstructing it:
+ *
+ * @example
+ * ```tsx
+ * <SidebarLayout
+ *   header={
+ *     <SidebarLayout.DefaultHeader
+ *       actions={[<NotificationBell key="bell" />, <AppearanceSwitcher key="appearance" />]}
+ *     />
+ *   }
+ * />
+ * ```
+ */
+export declare const DefaultHeader: {
+    ({ actions }: DefaultHeaderProps): JSX.Element;
+    displayName: string;
+};
+
+export declare type DefaultHeaderProps = {
+    /**
+     * The right-hand cluster of the header. Rendered in a horizontal,
+     * vertically-centered row with consistent spacing — you don't wrap it
+     * yourself. Accepts a single node or an array of nodes.
+     *
+     * **`actions` replaces the entire right-hand cluster, including the
+     * appearance switcher.** When omitted, it defaults to just the
+     * `<AppearanceSwitcher />`. If you pass your own actions and still want the
+     * switcher, include `<AppearanceSwitcher />` in the array (it is a public
+     * export). Passing `actions={[]}` renders an empty right side.
+     *
+     * @default [<AppearanceSwitcher />]
+     * @example
+     * ```tsx
+     * // Add a notification bell, keeping the appearance switcher:
+     * <SidebarLayout.DefaultHeader
+     *   actions={[<NotificationBell key="bell" />, <AppearanceSwitcher key="appearance" />]}
+     * />
+     * ```
+     */
+    actions?: React.ReactNode | React.ReactNode[];
+};
+
 /**
  * Default sidebar component with auto-generated navigation items.
  *
@@ -2914,6 +3086,14 @@ declare type FilterInputForFieldType<TFilterConfigType extends FilterConfig["typ
  */
 export declare type FilterOperator = OperatorForFilterType[FilterConfig["type"]];
 
+/**
+ * Hand-rolled calendar-grid state — the logic react-aria's `useCalendarState`
+ * would otherwise provide. We own: month/week computation (locale + first-day-
+ * of-week aware), selection, roving focus, and full APG keyboard navigation
+ * (arrows, Home/End, PageUp/Down, Shift+PageUp/Down).
+ */
+declare type FirstDayOfWeek = "sun" | "mon" | "tue" | "wed" | "thu" | "fri" | "sat";
+
 /** The table footer section (`<tfoot>`). */
 declare function Footer({ className, ...props }: React_2.ComponentProps<"tfoot">): JSX.Element;
 
@@ -3025,6 +3205,20 @@ 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 { getLocalTimeZone }
+
+/**
+ * Hand-rolled segmented-date-field state.
+ *
+ * This is the logic react-aria's `useDateFieldState` would otherwise provide.
+ * We own it here: locale-driven segment ordering (via `DateFormatter`), per-
+ * segment spinbutton semantics (increment/decrement with context-aware limits),
+ * numeric type-to-fill with auto-advance, and value-type discrimination by
+ * `granularity`. No `Date` ever escapes — `onChange` emits `@internationalized/date`
+ * values (or `null`).
+ */
+declare type Granularity = "day" | "hour" | "minute" | "second";
+
 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>>;
 };
@@ -3237,6 +3431,8 @@ declare type HeadProps = React_2.ComponentProps<"th"> & {
  */
 export declare const hidden: () => GuardResult;
 
+declare type HourCycle = 12 | 24;
+
 export declare type I18nLabels<Def extends Record<string, LabelValue> = Record<string, LabelValue>, L extends string = never> = {
     en: Def;
 } & {
@@ -3388,7 +3584,7 @@ declare type LabelValue = string | ((props: any) => string);
  * </Layout>
  * ```
  */
-export declare function Layout({ columns, className, style, gap, title, actions, children }: LayoutProps): JSX.Element;
+export declare function Layout({ columns, className, style, gap, title, actions, fill, children, }: LayoutProps): JSX.Element;
 
 export declare namespace Layout {
     var Column: React_2.ForwardRefExoticComponent<ColumnProps & React_2.RefAttributes<HTMLDivElement>>;
@@ -3439,6 +3635,24 @@ export declare interface LayoutProps {
      * @deprecated Use `<Layout.Header actions={...}>` instead.
      */
     actions?: ReactNode[];
+    /**
+     * Fill the available height instead of growing with content.
+     *
+     * When set, the layout stretches to the height of its container
+     * (`flex-1 min-h-0`) and bounds its column row (`minmax(0, 1fr)`), so
+     * children such as `DataTable` can scroll internally while the
+     * `Layout.Header` stays pinned. Without it, the layout grows naturally
+     * and the surrounding content area scrolls.
+     *
+     * Intended for single-row (one `Layout.Column` per breakpoint row) pages;
+     * on stacked mobile layouts with multiple columns the content area
+     * scrolls as usual.
+     *
+     * A `fill` layout also renders a `data-layout-fill` attribute on its root,
+     * which the AppShell content area targets via `:has([data-layout-fill])` to
+     * disable its own scrolling (the fill layout bounds everything internally).
+     */
+    fill?: boolean;
     /** Child elements - Layout.Header and/or Layout.Column components */
     children: ReactNode;
 }
@@ -3740,6 +3954,12 @@ declare namespace Panel {
     var displayName: string;
 }
 
+export { parseAbsolute }
+
+export { parseDate }
+
+export { parseDateTime }
+
 /** The row data passed to `onValidate`, after transforms have been applied. */
 export declare type ParsedRow = {
     /** 0-based row index, stable across edits. */
@@ -3748,6 +3968,8 @@ export declare type ParsedRow = {
     data: Record<string, unknown>;
 };
 
+export { parseZonedDateTime }
+
 /**
  * Allow access to the route. Continue to next guard or render component.
  *
@@ -3916,7 +4138,7 @@ declare namespace Root_10 {
  * </Tabs.Root>
  * ```
  */
-declare function Root_11({ className, children, variant, ...props }: RootProps_3): JSX.Element;
+declare function Root_11({ className, children, variant, size, ...props }: RootProps_3): JSX.Element;
 
 declare namespace Root_11 {
     var displayName: string;
@@ -4116,6 +4338,10 @@ declare type RootConfiguration = {
     basePath?: string;
     errorBoundary: ErrorBoundaryComponent;
     locale: string;
+    /** Full BCP-47 tag (e.g. "en-GB") for Intl / date formatting. Falls back to `locale`. */
+    resolvedLocale?: string;
+    /** IANA timezone (e.g. "America/Los_Angeles"). Used by date/time components. */
+    timeZone?: string;
 };
 
 declare type RootProps = React_2.ComponentProps<"div"> & VariantProps<typeof alertVariants> & {
@@ -4133,6 +4359,12 @@ declare type RootProps_3 = Pick<React_2.ComponentProps<typeof Tabs_2.Root>, "def
     children: React_2.ReactNode;
     className?: string;
     variant?: TabsVariant;
+    /**
+     * Minimum size of the tabs, mirroring Button's height tiers. Only affects the
+     * `capsule` variant, keeping its track aligned with a sibling Button and its
+     * icon-only tabs square.
+     */
+    size?: TabsSize;
 };
 
 /**
@@ -4470,6 +4702,13 @@ declare type SharedAppShellProps = React.PropsWithChildren<{
      * No browser locale information avilable, "en" used as default.
      */
     locale?: string;
+    /**
+     * IANA timezone (e.g. "America/Los_Angeles") used by date/time components
+     * as the default for resolving "today" and for `ZonedDateTime` values.
+     *
+     * If not provided, date/time components fall back to the user's local timezone.
+     */
+    timeZone?: string;
     /**
      * Global error boundary component applied to all routes.
      *
@@ -4728,7 +4967,15 @@ declare type SidebarItemRenderProps = {
     isActive: boolean;
 };
 
-export declare const SidebarLayout: (props: SidebarLayoutProps) => JSX.Element;
+export declare function SidebarLayout(props: SidebarLayoutProps): JSX.Element;
+
+export declare namespace SidebarLayout {
+    var DefaultSidebar: (props: DefaultSidebarProps) => JSX.Element;
+    var DefaultHeader: {
+        ({ actions }: DefaultHeaderProps): JSX.Element;
+        displayName: string;
+    };
+}
 
 export declare type SidebarLayoutProps = {
     /**
@@ -4751,15 +4998,39 @@ export declare type SidebarLayoutProps = {
         Outlet: () => React.ReactNode;
     }) => React.ReactNode;
     /**
-     * Custom sidebar content.
+     * Custom sidebar content. Replaces the whole sidebar region.
      *
-     * @default DefaultSidebar
+     * @default <SidebarLayout.DefaultSidebar />
      * @example
      * ```tsx
      * <SidebarLayout sidebar={<MyCustomSidebar />} />
      * ```
      */
     sidebar?: React.ReactNode;
+    /**
+     * Custom header content. Replaces the whole top-bar region.
+     *
+     * Omit it for the built-in header. To slightly extend the built-in header
+     * (e.g. add a notification bell), pass `<SidebarLayout.DefaultHeader />` with
+     * its `actions` slot rather than reconstructing the header from scratch.
+     *
+     * @default <SidebarLayout.DefaultHeader />
+     * @example
+     * ```tsx
+     * // Extend the built-in header:
+     * <SidebarLayout
+     *   header={
+     *     <SidebarLayout.DefaultHeader
+     *       actions={[<NotificationBell key="bell" />, <AppearanceSwitcher key="appearance" />]}
+     *     />
+     *   }
+     * />
+     *
+     * // Or replace it entirely:
+     * <SidebarLayout header={<MyCustomHeader />} />
+     * ```
+     */
+    header?: React.ReactNode;
     /**
      * Whether the sidebar is open by default on desktop.
      *
@@ -4914,8 +5185,24 @@ export declare const Tabs: {
     Panel: typeof Panel;
 };
 
+declare type TabsSize = "xs" | "sm" | "default" | "lg";
+
 declare type TabsVariant = "default" | "line" | "capsule";
 
+export { Time }
+
+/**
+ * Resolved timezone object with helpers bound to the configured timezone.
+ */
+export declare interface TimeZone {
+    /** Raw IANA timezone string (e.g. "America/Los_Angeles"). */
+    value: string;
+    /** Today's date in this timezone. */
+    today: () => CalendarDate;
+    /** Current instant in this timezone. */
+    now: () => ZonedDateTime;
+}
+
 declare function Title({ className, ...props }: React_2.ComponentProps<"div">): JSX.Element;
 
 declare namespace Title {
@@ -5018,7 +5305,6 @@ declare type TypedPaths<TRoutes extends Record<string, Record<string, string>>>
 export declare function useAIChat(config: {
     client: AIGatewayClient;
     model: string;
-    stream?: boolean;
 }): {
     messages: AIChatMessage[];
     status: AIChatStatus;
@@ -5056,6 +5342,41 @@ export declare const useAppShellConfig: () => AppShellConfigContextType;
  */
 export declare const useAppShellData: () => AppShellDataContextType;
 
+/**
+ * Ref to the AppShell **content scroll container** — the element that owns
+ * vertical scrolling for page content.
+ *
+ * The shell is viewport-bounded (`h-svh`), so the document itself no longer
+ * scrolls; the content area does. Use this wherever you would previously have
+ * reached for `window`/document scroll — reading `scrollTop`, calling
+ * `scrollTo`, attaching a `scroll` listener, or passing `root` to an
+ * `IntersectionObserver`:
+ *
+ * ```tsx
+ * const scrollRef = useAppShellScrollContainer();
+ * useEffect(() => {
+ *   const el = scrollRef.current;
+ *   if (!el) return;
+ *   const onScroll = () =>
+ *     setProgress(el.scrollTop / (el.scrollHeight - el.clientHeight));
+ *   el.addEventListener("scroll", onScroll, { passive: true });
+ *   return () => el.removeEventListener("scroll", onScroll);
+ * }, [scrollRef]);
+ * ```
+ *
+ * The element mounts with the layout, above your page, so read `ref.current`
+ * inside an effect (it is populated by the time effects run), not during
+ * render.
+ *
+ * Notes:
+ * - On a `<Layout fill>` page this element does not scroll — its children
+ *   (e.g. a `DataTable`) manage their own scrolling.
+ * - Outside a `SidebarLayout` the returned ref's `current` is always `null`.
+ * - The same element carries a `data-appshell-scroll-container` attribute for
+ *   non-React access (CSS, tests, `document.querySelector`).
+ */
+export declare function useAppShellScrollContainer(): RefObject<HTMLElement | null>;
+
 /**
  * Hook that encapsulates the async select pattern — fetching on open,
  * request cancellation via `AbortController`, and loading/error state.
@@ -5829,6 +6150,17 @@ export { useParams }
  */
 export declare function useRegisterCommandPaletteActions(group: string, actions: CommandPaletteAction[]): void;
 
+/**
+ * Returns the full BCP-47 locale (e.g. "en-GB") for Intl / date formatting.
+ * Also returns the language code (e.g. "en") used for label resolution.
+ *
+ * Falls back to browser detection when used outside an AppShell.
+ */
+export declare const useResolvedLocale: () => {
+    locale: string;
+    language: string;
+};
+
 export { useRouteError }
 
 export { useSearchParams }
@@ -5856,6 +6188,12 @@ export declare const useTheme: () => {
     setTheme: (colorTheme: ColorTheme) => void;
 };
 
+/**
+ * Returns the configured timezone with bound `today()` and `now()` helpers.
+ * Falls back to the user's local timezone when not configured.
+ */
+export declare const useTimeZone: () => TimeZone;
+
 export declare const useToast: () => typeof toast;
 
 /**
@@ -6019,4 +6357,6 @@ export declare function withURLCollectionState(options: UseCollectionOptions & {
     tableMetadata?: never;
 }, [searchParams, setSearchParams]: SearchParamsBinding): UseCollectionOptions;
 
+export { ZonedDateTime }
+
 export { }