@factorialco/f0-react 9.6.0 → 9.7.0

package/dist/experimental.d.ts

@@ -12744,6 +12744,156 @@ export declare type F0TextInputProps = F0TextInputBaseProps & {
     onDismiss?: never;
 };
 
+/**
+ * A sequence of steps, each an `F0TimelineRow`, joined by its connector. It
+ * owns what a list of rows has to agree on — which one is last — so a host
+ * passes the steps and nothing else.
+ *
+ * @experimental This is an experimental component use it at your own risk
+ */
+export declare const F0Timeline: WithDataTestIdReturnType_6<ForwardRefExoticComponent<F0TimelineProps & RefAttributes<HTMLOListElement>>>;
+
+/** One step of a timeline: an `F0TimelineRow`'s props, with an id to key it. */
+export declare type F0TimelineItem = DistributiveOmit<F0TimelineRowProps, "isLast"> & {
+    id: string;
+};
+
+export declare interface F0TimelineProps {
+    /** The steps, top to bottom. The last one draws no connector below it. */
+    items: F0TimelineItem[];
+}
+
+declare interface F0TimelineRowAction {
+    /** Button label */
+    label: string;
+    /** Optional icon for the button */
+    icon?: IconType;
+    /** Click handler */
+    onClick: () => void;
+    /** Whether the button is disabled */
+    disabled?: boolean;
+    /** Whether the button is in a loading state */
+    loading?: boolean;
+}
+
+declare interface F0TimelineRowBaseProps {
+    /** The current status of this timeline entry */
+    status: TimelineRowStatus;
+    /** The title of the timeline entry (e.g., "Tasks") */
+    title: string;
+    /** Whether this is the last row in the timeline (hides the bottom connector line) */
+    isLast?: boolean;
+    /** Hide the status indicator column (used for subtasks inside multitask rows) */
+    hideStatus?: boolean;
+}
+
+/** Item types that can be rendered inside a multitask row */
+declare type F0TimelineRowMultitaskItemProps = F0TimelineRowTaskProps | F0TimelineRowNestedtaskProps;
+
+/** Props for a multitask (collapsible group) timeline row */
+declare interface F0TimelineRowMultitaskProps extends F0TimelineRowBaseProps {
+    /** Number of grouped tasks */
+    taskCount: number;
+    /** Number of completed tasks in the group (shows a progress pill) */
+    completedCount?: number;
+    /** Whether the multitask row is expanded (controlled) */
+    expanded: boolean;
+    /** Callback when multitask row expand/collapse is toggled */
+    onExpandToggle: () => void;
+    /** The subtask items to render when expanded. Can be single tasks or nestedtask groups */
+    items: F0TimelineRowMultitaskItemProps[];
+}
+
+/**
+ * Shared shape for nestedtask rows. The collapsible behaviour is layered on
+ * top via a discriminated union (`F0TimelineRowNestedtaskProps`) so callers
+ * either provide both `expanded` and `onExpandToggle` (collapsible) or
+ * neither (non-collapsible).
+ */
+declare interface F0TimelineRowNestedtaskBaseProps extends F0TimelineRowBaseProps {
+    /** The icon representing the task type */
+    icon: IconType;
+    /** Description text (e.g., "Estimated on 18/07/2025") */
+    description?: string;
+    /**
+     * Number of nested items (displayed in the progress pill alongside
+     * `completedCount`). Omit when the row body conveys progress on its own
+     * (e.g. an embedded info card or table) and a pill would be redundant.
+     */
+    taskCount?: number;
+    /** Number of completed items (displayed in the progress pill) */
+    completedCount?: number;
+    /** Metadata items displayed below the header (e.g., assignees, file chips). Always visible regardless of expand/collapse */
+    metadata?: (MetadataItem | undefined | boolean)[];
+    /** The nested task items to render when expanded. Ignored when `content` is provided. */
+    items?: F0TimelineRowTaskProps[];
+    /**
+     * Custom content to render in the expanded body of the row. When provided,
+     * `items` is ignored and this React node is rendered instead. Use this to
+     * embed richer UI (callout cards, tables, custom panels) inside a nested
+     * timeline row.
+     */
+    content?: React.ReactNode;
+    /** Primary action button (displayed on the right after a divider) */
+    primaryAction?: F0TimelineRowAction;
+    /** Secondary action buttons (displayed on the left) */
+    secondaryActions?: F0TimelineRowAction[];
+    /** Overflow menu items (displayed as a dropdown via ellipsis button) */
+    otherActions?: F0TimelineRowOtherAction[];
+}
+
+/**
+ * Props for a nestedtask timeline row.
+ * Renders a task-style header (custom icon, title, description, chevron toggle)
+ * with collapsible nested items and optional group-level metadata (assignees, file chips, etc.).
+ * Unlike multitask, the header looks like a regular task row with expand/collapse capability.
+ *
+ * Discriminated by `collapsible`:
+ * - default / `collapsible: true` — both `expanded` and `onExpandToggle` are required.
+ * - `collapsible: false` — the row is always expanded, the header has no toggle affordance,
+ *   and `expanded`/`onExpandToggle` are not accepted.
+ */
+declare type F0TimelineRowNestedtaskProps = (F0TimelineRowNestedtaskBaseProps & {
+    /**
+     * Whether the header chevron toggles the body.
+     * @default true
+     */
+    collapsible?: true;
+    /** Whether the row is expanded (controlled) */
+    expanded: boolean;
+    /** Callback when expand/collapse is toggled */
+    onExpandToggle: () => void;
+}) | (F0TimelineRowNestedtaskBaseProps & {
+    /**
+     * When false, the row is always expanded and the header has no toggle
+     * affordance — useful when the body controls its own expansion
+     * (e.g. a collapsible callout card).
+     */
+    collapsible: false;
+    expanded?: never;
+    onExpandToggle?: never;
+});
+
+declare type F0TimelineRowOtherAction = DropdownItem;
+
+declare type F0TimelineRowProps = F0TimelineRowTaskProps | F0TimelineRowMultitaskProps | F0TimelineRowNestedtaskProps;
+
+/** Props for a single-task timeline row */
+declare interface F0TimelineRowTaskProps extends F0TimelineRowBaseProps {
+    /** The icon representing the task type (defaults to Marker) */
+    icon?: IconType;
+    /** Description text (e.g., "Completed on 20/2025") */
+    description?: string;
+    /** Metadata items to display (assignees, tags, dates, etc.) using the same pattern as F0ResourceHeader */
+    metadata?: (MetadataItem | undefined | boolean)[];
+    /** Primary action button (displayed on the right after a divider) */
+    primaryAction?: F0TimelineRowAction;
+    /** Secondary action buttons (displayed on the left) */
+    secondaryActions?: F0TimelineRowAction[];
+    /** Overflow menu items (displayed as a dropdown via ellipsis button) */
+    otherActions?: F0TimelineRowOtherAction[];
+}
+
 /**
  * Loose message shape used inside f0. Mirrors the CopilotKit `Message`
  * shape so adapters (factorial, mock runtime) can map back and forth
@@ -19394,6 +19544,10 @@ export declare const tileAspectRatio: (tile: F0MeetingTile, fallback: number) =>
 
 export declare const tileKey: (participantId: string, kind: string) => string;
 
+declare type TimelineRowStatus = (typeof timelineRowStatuses)[number];
+
+declare const timelineRowStatuses: readonly ["completed", "in-progress", "not-started"];
+
 /** A button rendered in the footer at the bottom of the table of contents */
 export declare type TOCAction = {
     label: string;
@@ -21258,9 +21412,8 @@ declare namespace Calendar {
 
 declare module "@tiptap/core" {
     interface Commands<ReturnType> {
-        aiBlock: {
-            insertAIBlock: (data: AIBlockData, config: AIBlockConfig) => ReturnType;
-            executeAIAction: (actionType: string, config: AIBlockConfig) => ReturnType;
+        transcript: {
+            insertTranscript: (data: TranscriptData) => ReturnType;
         };
     }
 }
@@ -21268,11 +21421,10 @@ declare module "@tiptap/core" {
 
 declare module "@tiptap/core" {
     interface Commands<ReturnType> {
-        enhanceHighlight: {
-            setEnhanceHighlight: (from: number, to: number, options?: {
-                placeholder?: string;
+        videoEmbed: {
+            setVideoEmbed: (options: {
+                src: string;
             }) => ReturnType;
-            clearEnhanceHighlight: () => ReturnType;
         };
     }
 }
@@ -21291,9 +21443,9 @@ declare module "@tiptap/core" {
 
 declare module "@tiptap/core" {
     interface Commands<ReturnType> {
-        fontSize: {
-            setFontSize: (fontSize: string) => ReturnType;
-            unsetFontSize: () => ReturnType;
+        aiBlock: {
+            insertAIBlock: (data: AIBlockData, config: AIBlockConfig) => ReturnType;
+            executeAIAction: (actionType: string, config: AIBlockConfig) => ReturnType;
         };
     }
 }
@@ -21301,8 +21453,11 @@ declare module "@tiptap/core" {
 
 declare module "@tiptap/core" {
     interface Commands<ReturnType> {
-        moodTracker: {
-            insertMoodTracker: (data: MoodTrackerData) => ReturnType;
+        enhanceHighlight: {
+            setEnhanceHighlight: (from: number, to: number, options?: {
+                placeholder?: string;
+            }) => ReturnType;
+            clearEnhanceHighlight: () => ReturnType;
         };
     }
 }
@@ -21310,10 +21465,9 @@ declare module "@tiptap/core" {
 
 declare module "@tiptap/core" {
     interface Commands<ReturnType> {
-        videoEmbed: {
-            setVideoEmbed: (options: {
-                src: string;
-            }) => ReturnType;
+        fontSize: {
+            setFontSize: (fontSize: string) => ReturnType;
+            unsetFontSize: () => ReturnType;
         };
     }
 }
@@ -21321,8 +21475,8 @@ declare module "@tiptap/core" {
 
 declare module "@tiptap/core" {
     interface Commands<ReturnType> {
-        transcript: {
-            insertTranscript: (data: TranscriptData) => ReturnType;
+        moodTracker: {
+            insertMoodTracker: (data: MoodTrackerData) => ReturnType;
         };
     }
 }