@factorialco/f0-react 6.8.4 → 6.9.0

package/dist/experimental.d.ts

@@ -766,6 +766,8 @@ declare const alertAvatarVariants: (props?: ({
 
 declare type AlertTagProps = ComponentProps<typeof F0TagAlert>;
 
+declare type AlertType = Parameters<typeof F0AvatarAlert>[0]["type"];
+
 declare type AlertVariant = (typeof alertVariantOptions)[number];
 
 declare const alertVariantOptions: readonly ["info", "warning", "critical", "neutral", "positive"];
@@ -867,6 +869,10 @@ declare type AvatarBadge = ({
     tooltip?: string;
 };
 
+declare type AvatarData<T extends AvatarVariant["type"]> = Omit<Extract<AvatarVariant, {
+    type: T;
+}>, "type">;
+
 declare const avatarEmojiSizes: readonly ["sm", "md", "lg", "xl"];
 
 declare type AvatarFileSize = (typeof avatarFileSizes)[number];
@@ -3180,6 +3186,15 @@ declare const daytimePageVariants: (props?: ({
     className?: ClassValue;
 })) | undefined) => string;
 
+/**
+ * Built-in renderers for the standard visualizations. `list` covers every
+ * row-based slot through its schema; `event-list` and `indicators` spread
+ * their params onto the matching f0 content component. Bespoke visualizations
+ * (e.g. `clock-in`, `carousel`) are intentionally absent — supply them via
+ * `slotRenderers`.
+ */
+export declare const defaultSlotRenderers: SlotRenderers;
+
 declare const defaultTranslations: {
     readonly common: {
         readonly selectPlaceholder: "Select";
@@ -4890,6 +4905,15 @@ declare interface ErrorMessageProps {
     description: string;
 }
 
+/** The gap between rows of the `event-list` slot. */
+export declare const EVENT_LIST_GAP = "gap-2";
+
+/** `event-list` params: f0 calendar-event rows (color band + date avatars). */
+export declare interface EventListParams {
+    events: CalendarEventProps[];
+    showAllItems?: boolean;
+}
+
 /**
  * Profile data for an expense entity, resolved asynchronously
  * and displayed in the entity reference hover card.
@@ -7296,6 +7320,16 @@ export declare const getSecondaryActions: (secondaryActions: SecondaryActionsDef
 
 export declare const getUpsellAction: (upsellAction: UpsellActionDefinitionFn | undefined) => UpsellActionDefinition | undefined;
 
+/**
+ * The DaytimePage gradient wash, by period — the same stops and the same 8%
+ * opacity, so Home and the daytime header read as one surface.
+ */
+declare const GRADIENTS: {
+    readonly morning: "bg-gradient-to-bl from-[#E51943] from-20% via-[#F97316] via-35% to-transparent to-50%";
+    readonly afternoon: "bg-gradient-to-bl from-[#5596F6] from-20% via-[#10B881] via-35% to-transparent to-50%";
+    readonly evening: "bg-gradient-to-bl from-[#3739A8] from-20% via-[#CB6687] via-35% to-transparent to-50%";
+};
+
 export declare interface GranularityDefinition {
     calendarMode?: CalendarMode;
     calendarView: CalendarView;
@@ -7675,6 +7709,83 @@ declare type HighlightBannerProps = {
     onClick?: () => void;
 };
 
+export declare type HomePeriod = keyof typeof GRADIENTS;
+
+/**
+ * The Home kit's slot vocabulary and how each slot is drawn. `SlotWidget`
+ * renders a widget from these; the layout (`NewHomeLayout`) stays pure
+ * placement.
+ */
+/** Context threaded into every slot renderer. */
+export declare interface HomeRenderCtx {
+    /**
+     * Whether this slot is the LAST one in its widget. `SlotWidget` sets it per
+     * slot; row-based slots use it to keep their bottom bleed (see
+     * { slotRowBleed}).
+     */
+    isLastSlot?: boolean;
+}
+
+/**
+ * Builds a slot with its params CHECKED against its visualization.
+ * `HomeWidgetSlot`'s `params` is `unknown` (bespoke slots need it to be), so a
+ * plain `{ visualization, params }` literal gets no checking — use this for
+ * the built-in vocabulary (and {@link listSlot} for `list` slots), keeping
+ * literals for bespoke visualizations.
+ */
+export declare const homeSlot: <V extends keyof HomeSlotParamsMap>(visualization: V, params: HomeSlotParamsMap[V]) => HomeWidgetSlot;
+
+/** The built-in slot vocabulary: each visualization and its params shape. */
+export declare interface HomeSlotParamsMap {
+    "event-list": EventListParams;
+    indicators: IndicatorsListProps;
+}
+
+/**
+ * The `Widget` chrome a Home widget may carry beyond its header, passed straight
+ * through to the frame.
+ *
+ * `alert` and `status` are EXCLUSIVE — `Widget` throws when given both — so the
+ * type says so rather than leaving it to blow up at runtime.
+ */
+export declare type HomeWidgetChrome = Pick<WidgetProps, "action" | "summaries"> & ({
+    alert?: WidgetProps["alert"];
+    status?: never;
+} | {
+    status?: WidgetProps["status"];
+    alert?: never;
+});
+
+/** A widget as handed to the layout: header + an ordered list of slots. */
+export declare type HomeWidgetItem = HomeWidgetChrome & {
+    id: string;
+    header?: WidgetProps["header"];
+    fullHeight?: boolean;
+    /**
+     * The widget's catalog glyph — shown for it in the collapsed rail and in the
+     * "Add widget" picker, so the strip can never drift from the catalog.
+     */
+    icon?: IconType;
+    /**
+     * PINNED: the widget stays put. In edit mode it shows no remove control and
+     * does not wiggle (nor drag, once dragging lands) — for widgets a user must
+     * always have, like Clock in.
+     */
+    locked?: boolean;
+    /**
+     * Something new since the user last looked (unread messages, a pending
+     * request). The collapsed rail badges the widget's glyph with an accent dot.
+     */
+    hasUpdates?: boolean;
+    slots: HomeWidgetSlot[];
+};
+
+/** One slot of a widget: a visualization tag + its params (opaque to the layout). */
+export declare interface HomeWidgetSlot {
+    visualization: string;
+    params: unknown;
+}
+
 declare type HTMLString = string;
 
 declare type I18nContextType = TranslationsType & {
@@ -8130,13 +8241,118 @@ declare type LinkProps = AnchorHTMLAttributes<HTMLAnchorElement> & {
     disabled?: boolean;
 };
 
+/**
+ * Past this many rows a list auto-compacts: every row's second line folds into
+ * a tooltip on the row, and the glyphs drop to `sm`.
+ */
+export declare const LIST_COMPACT_AFTER = 6;
+
+declare type ListClickData<C> = C extends "link" ? {
+    href: string;
+} : object;
+
 /**
  * Group List: Renders the list for a group
  */
 declare type ListCollectionProps<Record extends RecordType, Filters extends FiltersDefinition, Sortings extends SortingsDefinition, Summaries extends SummariesDefinition, ItemActions extends ItemActionsDefinition<Record>, NavigationFilters extends NavigationFiltersDefinition, Grouping extends GroupingDefinition<Record>> = CollectionProps<Record, Filters, Sortings, Summaries, ItemActions, NavigationFilters, Grouping, ListVisualizationOptions<Record, Filters, Sortings>>;
 
+/** One row of a `list` slot — its shape FOLLOWS from the slot's schema. */
+export declare type ListItem<S extends ListSchema = ListSchema> = {
+    id: string | number;
+    /** An accent dot on the left glyph — unseen/pending. */
+    unread?: boolean;
+} & ListTextData<S> & ListLeftData<S["left"]> & ListRightData<S["right"]> & ListClickData<S["clickBehavior"]>;
+
+declare type ListLeftData<L> = L extends "module" ? {
+    module: ModuleId;
+} : L extends "alert" ? {
+    alert: AlertType;
+} : L extends AvatarVariant["type"] ? {
+    avatar: AvatarData<L>;
+} : object;
+
+/** What every row of a `list` slot draws on its LEFT. */
+export declare type ListLeftKind = AvatarVariant["type"] | "module" | "alert";
+
+/** `list` params: the schema, then items shaped by it. Build with {@link listSlot}. */
+export declare interface ListParams<S extends ListSchema = ListSchema> {
+    schema: S;
+    items: Array<ListItem<S>>;
+}
+
 declare type ListPropertyDefinition<R, Sortings extends SortingsDefinition> = WithOptionalSorting_2<R, Sortings> & PropertyDefinition_2<R>;
 
+declare type ListRightData<R> = R extends "counter" ? {
+    count: number;
+} : R extends `${infer T extends F0AvatarListProps["type"]}-list` ? {
+    avatars: Array<AvatarData<T>>;
+    remainingCount?: number;
+} : R extends AvatarVariant["type"] ? {
+    rightAvatar: AvatarData<R>;
+} : object;
+
+/**
+ * What every row draws on its RIGHT: a counter, one avatar (e.g. the sender),
+ * or a compact strip of avatars with an optional `remainingCount`.
+ */
+export declare type ListRightKind = "counter" | AvatarVariant["type"] | `${F0AvatarListProps["type"]}-list`;
+
+/**
+ * A `list` slot's SCHEMA: declared once for the whole slot, it decides what
+ * every row looks like — the rows are CONSISTENT by construction, and the item
+ * type follows from it (see {@link ListItem}). Sizing is prescriptive, not
+ * configurable: two text lines (a required `description`) draw an `md` glyph,
+ * one line draws `sm`.
+ */
+export declare interface ListSchema {
+    /** The one left treatment every row draws. Omit for plain text rows. */
+    left?: ListLeftKind;
+    /** The one right treatment every row draws. Omit for none. */
+    right?: ListRightKind;
+    /** Every row carries an inline subtitle (on the title's line, after a dot). */
+    subtitleRequired?: boolean;
+    /** Every row carries a second line — this is what makes rows two-line. */
+    descriptionRequired?: boolean;
+    /**
+     * `"link"` rows each carry an `href` and render as REAL anchors (role
+     * `link`, routed through the app's `LinkProvider`) — never an onClick;
+     * that's the only click behavior rows have. Omit for inert rows.
+     * Same-tab for relative and `#` hrefs, `target="_blank"` for other domains.
+     */
+    clickBehavior?: "link";
+    /**
+     * How many rows show before the rest fold behind a "View more (n)" button at
+     * the list's bottom (which turns into "View less" once expanded). Omit to
+     * always show every row.
+     */
+    maxVisibleItems?: number;
+    /**
+     * Forces the COMPACT presentation at any count: every row's `description`
+     * folds into a tooltip on the row and the glyphs draw `sm`. Without it,
+     * lists compact on their own past `LIST_COMPACT_AFTER` visible rows.
+     */
+    compact?: boolean;
+}
+
+/**
+ * Builds a `list` slot: the schema is declared once, and the items' shape is
+ * CHECKED against it — a `left: "person"` slot only takes person data, a
+ * `clickBehavior: "link"` slot demands an `href` on every row.
+ */
+export declare const listSlot: <const S extends ListSchema>(schema: S, items: Array<ListItem<S>>) => HomeWidgetSlot;
+
+declare type ListTextData<S extends ListSchema> = {
+    title: string;
+} & (S["subtitleRequired"] extends true ? {
+    subtitle: string;
+} : {
+    subtitle?: never;
+}) & (S["descriptionRequired"] extends true ? {
+    description: string;
+} : {
+    description?: never;
+});
+
 declare type ListVisualizationOptions<R extends RecordType, _Filters extends FiltersDefinition, Sortings extends SortingsDefinition> = {
     itemDefinition: (record: R) => ItemDefinition;
     fields: ReadonlyArray<ListPropertyDefinition<R, Sortings>>;
@@ -8555,6 +8771,77 @@ declare type NestedVariant = "basic" | "detailed";
 
 declare type NewColor = Extract<BaseColor, (typeof tagDotColors)[number]>;
 
+/**
+ * NewHomeLayout — the shell for the redesigned Home, modelled on the custom-home
+ * prototype's Feed page.
+ *
+ * A growing MAIN column (content capped to a centered `mainWidth`) next to a
+ * FIXED-width side rail, separated only by a gap — no divider. The WHOLE page
+ * sits on one full-bleed DaytimePage gradient (`period`): neither column paints
+ * a background, so the wash runs under both and across the gap, out to the
+ * window's edges. Below `md` everything stacks into one column, main first.
+ *
+ * WHEN THE LAYOUT IS TOO NARROW for both columns at full width (but still two
+ * columns), the rail COLLAPSES: one `lg` avatar per widget carrying that
+ * widget's own catalog `icon`. Hovering (or clicking) an avatar floats the SAME
+ * widget render out over the feed at the rail's expanded width — one render,
+ * two states, exactly like the prototype.
+ */
+export declare const NewHomeLayout: ForwardRefExoticComponent<NewHomeLayoutProps & RefAttributes<HTMLDivElement>>;
+
+export declare interface NewHomeLayoutProps {
+    /** Freeform main-column content on top (greeting, shortcut cards, ranked feed…). */
+    children?: ReactNode;
+    /** Main column: widget slots stacked below `children`. */
+    leftWidgets?: HomeWidgetItem[];
+    /** Side rail: spec-conforming widgets. */
+    rightWidgets?: HomeWidgetItem[];
+    /** Freeform side-rail content, rendered above `rightWidgets` (expanded rail only). */
+    aside?: ReactNode;
+    /** Per-visualization renderers, MERGED OVER the kit's `defaultSlotRenderers`. */
+    slotRenderers?: SlotRenderers;
+    /** Full override of how a whole widget is drawn. Defaults to `SlotWidget`. */
+    renderWidget?: (widget: HomeWidgetItem, ctx: HomeRenderCtx) => ReactNode;
+    /**
+     * Edit mode. Omit it and the layout owns the state itself, toggled by its own
+     * edit button; pass it to drive edit mode from outside.
+     */
+    editing?: boolean;
+    /** Called when the layout's edit button is pressed. */
+    onEditingChange?: (editing: boolean) => void;
+    /**
+     * Which containers a user may actually edit. In edit mode only these show
+     * remove controls and the add placeholder; the others stay put. Both by default.
+     */
+    editableWidgetContainers?: WidgetContainerSide[];
+    /** Called with a widget id when its remove control is clicked (edit mode only). */
+    onRemoveWidget?: (id: string) => void;
+    /** When set, renders a "+ Add widget" affordance at the bottom of each column. */
+    onClickAddNewWidget?: (side: WidgetContainerSide) => void;
+    /** Called with a side and its widget ids in their new order after a drag. */
+    onReorderWidgets?: (side: WidgetContainerSide, ids: string[]) => void;
+    /** The daytime gradient period for the page surface. */
+    period?: HomePeriod;
+    /** Fixed px width of the side rail. */
+    asideWidth?: number;
+    /** Max px width of the (centered) main-column content. */
+    mainWidth?: number;
+    /**
+     * How far the page surface reaches past this layout's box, in px — set it to
+     * the page's own gutter so the gradient runs to the window's edges instead of
+     * stopping at that padding.
+     */
+    bleed?: number;
+    /**
+     * When the layout stacks (below `md` there is no rail), how many leading
+     * blocks of `children` come before the pinned widgets folded in from it.
+     * Defaults to 2 — a greeting and the shortcuts under it.
+     */
+    stackedPinsAfter?: number;
+    ctx?: HomeRenderCtx;
+    className?: string;
+}
+
 declare type NextDepth<T> = T extends 1 ? 2 : T extends 2 ? 3 : T extends 3 ? 4 : never;
 
 declare interface NextStepsProps {
@@ -10560,6 +10847,26 @@ declare const skeletonVariants: (props?: ({
     className?: ClassValue;
 })) | undefined) => string;
 
+/**
+ * Row-based slots cancel their rows' own padding so the rows sit flush with the
+ * widget's content box — every list-like slot carries this. `indicators`
+ * doesn't: it isn't rows and has no padding to cancel.
+ */
+export declare const SLOT_ROW_BLEED = "-m-2";
+
+/** Draws ONE slot from its params. Keyed by `visualization` in a renderer map. */
+export declare type SlotRenderer<P = unknown> = (params: P, ctx: HomeRenderCtx) => ReactNode;
+
+export declare type SlotRenderers = Record<string, SlotRenderer>;
+
+/**
+ * The bleed a row-based slot applies to itself: `SLOT_ROW_BLEED` with its
+ * VERTICAL halves put back — `mt-0` always (the widget header already spaces
+ * the first slot, and a divider spaces the rest), and `mb-0` unless this is the
+ * widget's last slot, where the bleed should reach the card's bottom edge.
+ */
+export declare const slotRowBleed: (ctx: HomeRenderCtx) => string;
+
 /**
  * Type helper to extract keys from a SortingsDefinition
  */
@@ -12007,6 +12314,49 @@ export declare type WidgetAvatarsListItemProps = {
     alert: ComponentProps<typeof F0AvatarAlert>["type"];
 });
 
+/**
+ * WidgetCatalog — the "Add widget" dialog, mirroring the custom-home prototype:
+ * a searchable picker on the left (icon + title rows, the selected row tinted),
+ * a LIVE preview of the highlighted widget on the right at the width it will
+ * really get, and the "Add widget" CTA in the dialog footer. `width="xl"`
+ * rather than fullscreen.
+ *
+ * Selection follows the filter: if the selected row is filtered out, the first
+ * remaining row takes over, so the preview always shows something the CTA can
+ * actually add.
+ */
+export declare function WidgetCatalog({ isOpen, onClose, widgets, onAdd, previewWidth, title, }: WidgetCatalogProps): JSX_2.Element;
+
+/** One entry in the widget catalog dialog. */
+export declare interface WidgetCatalogItem {
+    id: string;
+    title: string;
+    icon: IconType;
+    /**
+     * The LIVE PREVIEW of the widget — the same node the Home renders (e.g. a
+     * `SlotWidget`), so the preview can't drift from what gets added.
+     */
+    preview: ReactNode;
+}
+
+export declare interface WidgetCatalogProps {
+    isOpen: boolean;
+    onClose: () => void;
+    /** The widgets that can be added, in the order to list them. */
+    widgets: WidgetCatalogItem[];
+    /** Called with the chosen widget id when the CTA is pressed. */
+    onAdd: (id: string) => void;
+    /**
+     * Content width of the column this was opened from — the preview is capped
+     * to it, so a rail-bound widget previews at rail width.
+     */
+    previewWidth?: number;
+    title?: string;
+}
+
+/** Which column a container is: the growing main one, or the fixed side rail. */
+export declare type WidgetContainerSide = "main" | "right";
+
 /**
  * @experimental This is an experimental component use it at your own risk
  */
@@ -12059,6 +12409,21 @@ export declare interface WidgetProps {
         variant: StatusVariant;
     };
     fullHeight?: boolean;
+    /**
+     * Shows a drag handle to the left of the title. The handle carries
+     * `data-gs-handle`, so a gridstack board picks it up as its handle.
+     */
+    draggable?: boolean;
+    onDragStart?: () => void;
+    onDragEnd?: () => void;
+    /** Lifts the card while it is being dragged. */
+    isDragging?: boolean;
+    /** Marks the card as picked out — a selected tile on an editable board. */
+    selected?: boolean;
+    /** An "Ask One" AI button in the header. */
+    AIButton?: () => void;
+    /** An overflow menu at the header's right, beside `link`. */
+    actions?: DropdownItem[];
 }
 
 /**