@factorialco/f0-react 3.5.1 → 3.7.0

package/dist/f0.d.ts

@@ -44,6 +44,8 @@ import type * as echarts_2 from 'echarts';
 import { EmployeeItemProps } from './types';
 import { F0AccordionSkeletonProps } from './F0AccordionSkeleton';
 import { F0AnalyticsDashboardProps as F0AnalyticsDashboardProps_2 } from './types';
+import { F0AudioPlayerCardProps as F0AudioPlayerCardProps_2 } from './types';
+import { F0AudioPlayerProps as F0AudioPlayerProps_2 } from './types';
 import { F0AvatarCompanyProps as F0AvatarCompanyProps_2 } from './types';
 import { F0AvatarDateProps } from './F0AvatarDate';
 import { F0AvatarEmojiProps as F0AvatarEmojiProps_2 } from './F0AvatarEmoji';
@@ -1163,6 +1165,33 @@ export declare type AttachedFile = {
     errorMessage?: string;
 };
 
+export declare interface AudioPlayerControls extends AudioPlayerState {
+    play: () => void;
+    pause: () => void;
+    toggle: () => void;
+    seek: (seconds: number) => void;
+    setPlaybackRate: (rate: number) => void;
+}
+
+export declare interface AudioPlayerMenuAction {
+    label: string;
+    icon?: IconType;
+    onClick: () => void;
+    critical?: boolean;
+}
+
+export declare const audioPlayerSizes: readonly ["sm", "md"];
+
+export declare interface AudioPlayerState {
+    isPlaying: boolean;
+    currentTime: number;
+    duration: number;
+    buffered: number;
+    playbackRate: number;
+    isLoading: boolean;
+    error: MediaError | null;
+}
+
 /**
  * An item that can be passed in the `availableFormDefinitions` array.
  * Accepts either a plain {@link F0AiAvailableFormDefinition} or the result
@@ -1757,6 +1786,16 @@ declare type ButtonInternalProps = Pick<ActionProps, "size" | "disabled" | "clas
      * The aria-label of the button if not provided title or label will be used.
      */
     "aria-label"?: string;
+    /**
+     * Forwarded to the underlying button. Useful for buttons that toggle an
+     * expandable region (e.g. a tree/graph expander).
+     */
+    "aria-expanded"?: boolean;
+    /**
+     * Forwarded to the underlying button. Use `-1` to take the button out of the
+     * tab order (e.g. when a parent manages focus via roving tabindex).
+     */
+    tabIndex?: number;
     /**
      * The variant of the button.
      */
@@ -2236,7 +2275,8 @@ declare type CardInternalProps_2 = F0AiInsightCardProps & {
 };
 
 declare type CardMetadata = {
-    icon: IconType;
+    /** Leading icon. Optional — when omitted the row renders just the value. */
+    icon?: IconType;
     property: Exclude<CardMetadataProperty, {
         type: "file";
     }>;
@@ -3026,6 +3066,7 @@ declare type CollectionVisualizations<Record extends RecordType, Filters extends
     list: VisualizacionTypeDefinition<ListCollectionProps<Record, Filters, Sortings, Summaries, ItemActions, NavigationFilters, Grouping>>;
     card: VisualizacionTypeDefinition<CardCollectionProps<Record, Filters, Sortings, Summaries, ItemActions, NavigationFilters, Grouping>>;
     kanban: VisualizacionTypeDefinition<KanbanCollectionProps<Record, Filters, Sortings, Summaries, ItemActions, NavigationFilters, Grouping>>;
+    graph: VisualizacionTypeDefinition<GraphCollectionProps<Record, Filters, Sortings, Summaries, ItemActions, NavigationFilters, Grouping>, GraphVisualizationSettings>;
 };
 
 declare const collectionVisualizations: CollectionVisualizations<RecordType, FiltersDefinition, SortingsDefinition, SummariesDefinition, ItemActionsDefinition<RecordType>, NavigationFiltersDefinition, GroupingDefinition<RecordType>>;
@@ -3721,6 +3762,8 @@ declare type DataCollectionSourceDefinition<R extends RecordType = RecordType, F
     itemPreFilter?: (item: R) => boolean;
     /** Lanes configuration */
     lanes?: ReadonlyArray<Lane<Filters>>;
+    /** Rich search preview shown in the shared header search (all visualizations). */
+    searchPreview?: SearchPreview<R>;
 };
 
 /**
@@ -4298,6 +4341,15 @@ export declare const defaultTranslations: {
     readonly link: {
         readonly opensInNewTab: "opens in new tab";
     };
+    readonly audioPlayer: {
+        readonly label: "Audio player";
+        readonly play: "Play";
+        readonly pause: "Pause";
+        readonly seek: "Seek";
+        readonly options: "Recording options";
+        readonly playbackSpeed: "Playback speed";
+        readonly position: "{{current}} of {{total}}";
+    };
     readonly actions: {
         readonly add: "Add";
         readonly edit: "Edit";
@@ -4421,16 +4473,18 @@ export declare const defaultTranslations: {
             readonly cancel: "Cancel";
         };
         readonly visualizations: {
-            readonly table: "Table view";
-            readonly editableTable: "Editable table view";
-            readonly card: "Card view";
-            readonly list: "List view";
-            readonly kanban: "Kanban view";
+            readonly table: "Table";
+            readonly editableTable: "Editable table";
+            readonly card: "Card";
+            readonly list: "List";
+            readonly kanban: "Kanban";
+            readonly graph: "Graph";
             readonly pagination: {
                 readonly of: "of";
             };
             readonly settings: "{{visualizationName}} settings";
             readonly reset: "Reset to default";
+            readonly viewSelectorLabel: "Select view";
         };
         readonly table: {
             readonly settings: {
@@ -4941,33 +4995,6 @@ export declare const defaultTranslations: {
             readonly zoomIn: "Zoom in";
             readonly zoomOut: "Zoom out";
             readonly navigation: "Graph navigation";
-            readonly metadataSettings: "Metadata visibility";
-            readonly tagTypeLabels: {
-                readonly person: "People";
-                readonly team: "Teams";
-                readonly company: "Companies";
-                readonly status: "Statuses";
-                readonly alert: "Alerts";
-                readonly balance: "Balances";
-                readonly dot: "Tags";
-                readonly raw: "Tags";
-            };
-        };
-        readonly search: {
-            readonly noResults: "No results";
-        };
-        readonly detailPanel: {
-            readonly details: "Details";
-            readonly moreActions: "More actions";
-            readonly resize: "Resize detail panel";
-        };
-        readonly expander: {
-            readonly collapse: "Collapse {{count}} items";
-            readonly expand: "Expand {{count}} items";
-            readonly expandWithParentSingular: "Expand {{parent}}, {{count}} child";
-            readonly expandWithParentPlural: "Expand {{parent}}, {{count}} children";
-            readonly collapseWithParent: "Collapse {{parent}}";
-            readonly collapseDefault: "Collapse children";
         };
     };
     readonly wizard: {
@@ -6552,6 +6579,110 @@ declare type F0AssistantMessageExtraProps = {
     renderMarkdown?: (content: string) => ReactNode;
 };
 
+/**
+ * @experimental This is an experimental component, use it at your own risk.
+ */
+export declare const F0AudioPlayer: WithDataTestIdReturnType_3<ForwardRefExoticComponent<F0AudioPlayerProps_2 & RefAttributes<HTMLDivElement>>>;
+
+/**
+ * @experimental This is an experimental component, use it at your own risk.
+ */
+export declare const F0AudioPlayerCard: WithDataTestIdReturnType_3<ForwardRefExoticComponent<F0AudioPlayerCardProps_2 & RefAttributes<HTMLDivElement>>>;
+
+export declare interface F0AudioPlayerCardProps extends F0AudioPlayerProps {
+    /**
+     * The title shown in the card header (e.g. "AI Call with Alex Williams").
+     */
+    title: string;
+    /**
+     * An optional subtitle shown under the title (e.g. "May 9, 2025 - 10:00am").
+     */
+    subtitle?: string;
+    /**
+     * Extra actions appended to the kebab menu below the playback-speed options
+     * (after a separator) — e.g. a download or copy-link action. The kebab itself
+     * is always rendered by the card.
+     */
+    actions?: AudioPlayerMenuAction[];
+}
+
+export declare interface F0AudioPlayerProps extends WithDataTestIdProps, DataAttributes_2 {
+    /**
+     * The audio source URL.
+     */
+    src: string;
+    /**
+     * How much of the audio to preload.
+     * @default "metadata"
+     */
+    preload?: "none" | "metadata" | "auto";
+    /**
+     * Start playing as soon as the audio is ready.
+     * @default false
+     */
+    autoPlay?: boolean;
+    /**
+     * Controlled playing state. Pair with `onPlayingChange`.
+     */
+    playing?: boolean;
+    /**
+     * Initial playing state when uncontrolled.
+     * @default false
+     */
+    defaultPlaying?: boolean;
+    /**
+     * Fired when the playing state changes (play or pause).
+     */
+    onPlayingChange?: (playing: boolean) => void;
+    /**
+     * Playback rates offered in the speed menu. Pass an empty array to hide the
+     * speed options.
+     * @default [1, 1.5, 2]
+     */
+    playbackRates?: number[];
+    /**
+     * Fired when playback starts.
+     */
+    onPlay?: () => void;
+    /**
+     * Fired when playback pauses.
+     */
+    onPause?: () => void;
+    /**
+     * Fired when the user seeks, with the target position in seconds.
+     */
+    onSeek?: (seconds: number) => void;
+    /**
+     * Fired on every time update, with the current position in seconds.
+     */
+    onTimeUpdate?: (seconds: number) => void;
+    /**
+     * Fired when playback reaches the end.
+     */
+    onEnded?: () => void;
+    /**
+     * Fired when the audio fails to load or play.
+     */
+    onError?: (error: MediaError | null) => void;
+    /**
+     * Disables all controls.
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * Accessible label for the player region.
+     */
+    ariaLabel?: string;
+    /**
+     * The size of the player.
+     * @default "md"
+     */
+    size?: F0AudioPlayerSize;
+    className?: string;
+}
+
+export declare type F0AudioPlayerSize = (typeof audioPlayerSizes)[number];
+
 export declare function F0AuraVoiceAnimation({ size, state, color, colorShift, audioTrack, themeMode, className, ref, ...props }: F0AuraVoiceAnimationProps & ComponentProps<"div"> & VariantProps<typeof F0AuraVoiceAnimationVariants>): JSX_2.Element;
 
 export declare interface F0AuraVoiceAnimationProps {
@@ -9305,6 +9436,9 @@ export declare interface F0FormValidationResult {
     rootError?: string;
 }
 
+/** Tag types that can be rendered in a node's metadata row. */
+declare type F0GraphNodeTagType = TagVariant["type"];
+
 export declare const F0GridStack: WithDataTestIdReturnType_7<    {
 ({ options, widgets, onChange, className, static: isStatic, forcePositionSync, }: F0GridStackProps_2): JSX_2.Element;
 displayName: string;
@@ -11048,6 +11182,8 @@ declare type FontSize = (typeof fontSizes)[number];
 
 declare const fontSizes: readonly ["sm", "md", "lg"];
 
+export declare const formatPlaybackTime: (seconds: number) => string;
+
 /**
  * A preset formatting instruction the LLM can specify instead of a
  * real formatter function. The wrapper component maps these to actual
@@ -11339,6 +11475,97 @@ export declare const granularityDefinitions: {
 
 export declare type GranularityDefinitionSimple = Pick<GranularityDefinition, "toRangeString" | "toString">;
 
+declare type GraphCollectionProps<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, GraphVisualizationOptions<Record, Filters, Sortings>>;
+
+/**
+ * Configuration for the "graph" visualization (org-chart style).
+ *
+ * The hierarchy is fetched on demand from the same `dataAdapter` of the source:
+ * `childrenFilters(parentId)` returns the filter that the adapter understands as
+ * "the direct children of parentId" (`null` = the roots). Children are loaded
+ * when a node is expanded.
+ */
+declare type GraphVisualizationOptions<R extends RecordType, Filters extends FiltersDefinition, _Sortings extends SortingsDefinition> = {
+    /** Primary line of text for a node. */
+    title: (record: R) => string;
+    /** Secondary line of text for a node. */
+    subtitle?: (record: R) => string;
+    /** Avatar shown on the leading side of the node pill. */
+    avatar?: (record: R) => AvatarVariant;
+    /** Tags rendered in the node metadata row. */
+    tags?: (record: R) => TagVariant[];
+    /**
+     * Tag types present on the nodes. When provided, the controls bar gains a
+     * toggle to show/hide each metadata type (like configuring table columns).
+     */
+    nodeTagTypes?: ReadonlyArray<F0GraphNodeTagType>;
+    /** Friendly labels per tag type, shown in the metadata visibility toggle. */
+    nodeTagTypeLabels?: Partial<Record<F0GraphNodeTagType, string>>;
+    /** Tag types visible by default. Defaults to all of `nodeTagTypes`. */
+    defaultVisibleTagTypes?: ReadonlyArray<F0GraphNodeTagType>;
+    /** Tag types that are always visible and cannot be hidden in the settings. */
+    pinnedTagTypes?: ReadonlyArray<F0GraphNodeTagType>;
+    /**
+     * Floating toolbar shown above a node while it is selected. Provide the
+     * action buttons (e.g. `<F0Button size="sm" … />`) for the given record.
+     */
+    nodeActions?: (record: R) => ReactNode;
+    /** Resolves a stable node id from a record. Defaults to `String(record.id)`. */
+    getNodeId?: (record: R) => string;
+    /** Number of children a node has. A node is expandable when this is `> 0`. */
+    getChildrenCount: (record: R) => number;
+    /**
+     * Returns the filters that, applied to the source `dataAdapter`, fetch the
+     * direct children of `parentId`. `parentId === null` must return the roots.
+     */
+    childrenFilters: (parentId: string | null) => Partial<FiltersState<Filters>>;
+    /**
+     * How many levels to load and expand on the initial render.
+     * - `0`: show only the roots; every level below loads on click.
+     * - `1` (default): also show the roots' direct children.
+     * - `2`: also pre-load the grandchildren for a fuller first view.
+     */
+    defaultExpandDepth?: number;
+    /**
+     * Id of a node to reveal: loads its ancestor path, expands the branch and
+     * centers/highlights it. Driven by the shared Data Collection search — set it
+     * from `searchPreview.onSelect`.
+     */
+    revealNodeId?: string;
+    /**
+     * Resolves the ancestor path (root → … → matched node) for a node so it can
+     * be revealed, returning the records in root-first order. Required for
+     * revealing nodes in branches that have not been expanded yet.
+     */
+    loadNodePath?: (nodeId: string) => Promise<R[]>;
+    /** Optional parent accessor used when linking the revealed ancestor path. */
+    getParentId?: (record: R) => string | null;
+    /**
+     * Id of the node representing the current user. When set, a "Find me" button
+     * is shown in the controls that centers the viewport on that node.
+     */
+    currentUserNodeId?: string;
+    /** Initial zoom preset passed through to F0Graph. */
+    zoomPreset?: ZoomPreset;
+    /**
+     * Smallest zoom the user can pan to (the zoom-out limit), passed through to
+     * F0Graph. Defaults to F0Graph's own default. Raise it (e.g. `0.3`) to keep
+     * the tree readable and avoid the most zoomed-out "dot" level.
+     */
+    minZoom?: number;
+    /** Largest zoom the user can pan to (the zoom-in limit), passed through to F0Graph. */
+    maxZoom?: number;
+    /** Whether to render the zoom/fit controls. Defaults to `true`. */
+    showControls?: boolean;
+};
+
+declare type GraphVisualizationSettings = {
+    /** Metadata order (tag-type ids), matching the table column settings shape. */
+    order?: string[];
+    /** Hidden metadata (tag-type ids). */
+    hidden?: string[];
+};
+
 export declare type GridStackReactOptions = Omit<GridStackOptions, "children">;
 
 export declare type GridStackReactSize = {
@@ -14132,6 +14359,26 @@ declare type SearchOptions = {
     debounceTime?: number;
 };
 
+/**
+ * Optional rich search preview shown in the shared Data Collection search.
+ * When provided, typing in the header search renders a results dropdown with
+ * avatar + title + subtitle, consistent across every visualization. Selecting a
+ * result calls `onSelect` (e.g. the graph view reveals/centers the node).
+ */
+declare type SearchPreview<R extends RecordType> = {
+    search: (query: string) => Promise<R[]>;
+    getId: (record: R) => string;
+    render: (record: R) => SearchPreviewResultData;
+    onSelect: (record: R) => void;
+};
+
+/** Data shown for a single row of the search preview dropdown. */
+declare type SearchPreviewResultData = {
+    avatar?: AvatarVariant;
+    title: string;
+    subtitle?: string;
+};
+
 declare interface SecondaryAction extends PrimaryActionButton {
     variant?: "outline" | "critical" | "outlinePromote" | "promote";
 }
@@ -15391,6 +15638,17 @@ export declare function useAiChat(): AiChatProviderReturnValue;
 
 export declare function useAiChatTranslations(): AiChatTranslations;
 
+export declare const useAudioPlayer: (audioRef: RefObject<HTMLAudioElement>, callbacks?: UseAudioPlayerCallbacks) => AudioPlayerControls;
+
+declare interface UseAudioPlayerCallbacks {
+    onPlay?: () => void;
+    onPause?: () => void;
+    onSeek?: (seconds: number) => void;
+    onTimeUpdate?: (seconds: number) => void;
+    onEnded?: () => void;
+    onError?: (error: MediaError | null) => void;
+}
+
 /**
  * Hook returning the canvas entity definition for `type` from the registry
  * supplied to `F0AiChatProvider.canvasEntities`. Returns `undefined` when no
@@ -16372,6 +16630,26 @@ export declare type ZIndexToken = "auto" | "0" | "10" | "20" | "30" | "40" | "50
  */
 declare type ZodTypeName = "ZodString" | "ZodNumber" | "ZodBoolean" | "ZodDate" | "ZodEnum" | "ZodArray" | "ZodObject" | "ZodOptional" | "ZodNullable" | "ZodDefault" | "ZodLiteral" | "ZodEffects";
 
+declare type ZoomPreset = keyof typeof zoomPresets;
+
+declare const zoomPresets: {
+    readonly default: {
+        readonly detail: 0.56;
+        readonly compact: 0.3;
+        readonly dot: 0.18;
+    };
+    readonly dense: {
+        readonly detail: 0.5;
+        readonly compact: 0.2;
+        readonly dot: 0.08;
+    };
+    readonly sparse: {
+        readonly detail: 0.85;
+        readonly compact: 0.45;
+        readonly dot: 0.15;
+    };
+};
+
 export { }