@factorialco/f0-react 1.453.0 → 1.455.0

package/dist/ai.d.ts

@@ -1,22 +1,41 @@
 import { AgentState } from '@livekit/components-react';
 import { AIMessage } from '@copilotkit/shared';
 import * as AvatarPrimitive from '@radix-ui/react-avatar';
+import { baseColors } from '@factorialco/f0-core';
 import { ClassValue } from 'cva';
+import { CompanyItemProps } from './types';
 import { ComponentProps } from 'react';
 import { CopilotKitProps } from '@copilotkit/react-core';
+import { EmployeeItemProps } from './types';
+import { F0TagBalanceProps as F0TagBalanceProps_2 } from './types';
+import { F0TagCompanyProps } from './types';
+import { F0TagPersonProps } from './types';
+import { F0TagTeamProps } from './types';
 import { f1Colors } from '@factorialco/f0-core';
+import { ForwardedRef } from 'react';
 import { ForwardRefExoticComponent } from 'react';
 import { InputProps } from '@copilotkit/react-ui';
+import { ItemProps } from './types';
 import { JSX as JSX_2 } from 'react';
 import { LocalAudioTrack } from 'livekit-client';
 import { Message } from '@copilotkit/shared';
+import { Props as Props_3 } from './types';
 import * as React_2 from 'react';
 import { ReactElement } from 'react';
 import { ReactNode } from 'react';
+import { Ref } from 'react';
 import { RefAttributes } from 'react';
 import { RemoteAudioTrack } from 'livekit-client';
 import { SVGProps } from 'react';
 import * as SwitchPrimitive from '@radix-ui/react-switch';
+import { TagAlertProps } from '../../../f0';
+import { TagBalanceProps } from '../../../f0';
+import { TagDotProps } from '../../../f0';
+import { TagListProps } from '../../../f0';
+import { TagRawProps } from '../../../f0';
+import { TagStatusProps } from '../../../f0';
+import { TagType } from '../../../f0';
+import { TeamItemProps } from './types';
 import { TrackReferenceOrPlaceholder } from '@livekit/components-react';
 import { VariantProps } from 'cva';
 import { WithDataTestIdReturnType } from '../../../lib/data-testid';
@@ -548,6 +567,8 @@ export declare const aiTranslations: {
     };
 };
 
+declare type AlertTagProps = ComponentProps<typeof F0TagAlert>;
+
 /**
  * A message to inject via appendMessages.
  * IDs are generated internally — callers only provide role, content, and
@@ -570,6 +591,12 @@ export declare type AppendToolCall = {
     };
 };
 
+declare const Avatar: React_2.ForwardRefExoticComponent<Omit<AvatarPrimitive.AvatarProps & React_2.RefAttributes<HTMLSpanElement>, "ref"> & {
+    size?: (typeof internalAvatarSizes)[number];
+    type?: (typeof internalAvatarTypes)[number];
+    color?: (typeof internalAvatarColors)[number];
+} & React_2.RefAttributes<HTMLSpanElement>>;
+
 declare type AvatarBadge = ({
     type: "module";
     module: ModuleId;
@@ -580,10 +607,38 @@ declare type AvatarBadge = ({
     tooltip?: string;
 };
 
+declare const avatarEmojiSizes: readonly ["sm", "md", "lg", "xl"];
+
+declare type AvatarFileSize = (typeof avatarFileSizes)[number];
+
+declare const avatarFileSizes: readonly ["xs", "sm", "md", "lg"];
+
+declare const avatarIconSizes: readonly ["sm", "md", "lg"];
+
+declare type AvatarListSize = (typeof avatarListSizes)[number];
+
+declare const avatarListSizes: readonly ["xs", "sm", "md"];
+
 declare type AvatarSize = (typeof avatarSizes)[number];
 
 declare const avatarSizes: readonly ["xs", "sm", "md", "lg", "xl", "2xl"];
 
+declare type AvatarVariant = DistributiveOmit<({
+    type: "person";
+} & F0AvatarPersonProps) | ({
+    type: "emoji";
+} & F0AvatarEmojiProps) | ({
+    type: "team";
+} & F0AvatarTeamProps) | ({
+    type: "company";
+} & F0AvatarCompanyProps) | ({
+    type: "file";
+} & F0AvatarFileProps) | ({
+    type: "flag";
+} & F0AvatarFlagProps) | ({
+    type: "icon";
+} & F0AvatarIconProps), "size">;
+
 declare interface BadgeProps extends VariantProps<typeof badgeVariants> {
     icon: IconType;
     type?: VariantProps<typeof badgeVariants>["type"];
@@ -610,6 +665,8 @@ export declare type BalanceConfig = {
     hint?: string;
 };
 
+declare type BalanceTagProps = ComponentProps<typeof F0TagBalance>;
+
 declare type BaseAvatarProps = {
     /**
      * The type of the avatar.
@@ -652,6 +709,12 @@ declare type BaseAvatarProps = {
     size: InternalAvatarProps["size"];
 });
 
+declare type BaseColor = keyof typeof baseColors;
+
+declare type BaseTag<T extends {
+    type: string;
+}> = T & WithTooltipDescription;
+
 /**
  * Profile data for a candidate entity (ATS applicant), resolved asynchronously
  * and displayed in the entity reference hover card.
@@ -1017,10 +1080,18 @@ declare interface CollectionComputation {
     limit?: number;
 }
 
+declare type CompanyAvatarVariant = Extract<AvatarVariant, {
+    type: "company";
+}>;
+
+declare type CompanyTagProps = ComponentProps<typeof F0TagCompany>;
+
 export declare type ContentType = (typeof contentTypes)[number];
 
 export declare const contentTypes: readonly ["text", "person", "people", "team", "company", "alert", "balance", "sparkline"];
 
+declare type CountryCode = keyof TranslationsType["countries"];
+
 /**
  * Credits usage data returned by the host app
  */
@@ -1096,6 +1167,27 @@ declare type DataDownloadDataset = {
     columnLabels?: Record<string, string>;
 };
 
+declare const DataList: ForwardRefExoticComponent<DataListProps & RefAttributes<HTMLUListElement>> & {
+    Item: ForwardRefExoticComponent<ItemProps & RefAttributes<HTMLLIElement>>;
+    CompanyItem: ForwardRefExoticComponent<CompanyItemProps & RefAttributes<HTMLLIElement>>;
+    PersonItem: ForwardRefExoticComponent<EmployeeItemProps & RefAttributes<HTMLLIElement>>;
+    TeamItem: ForwardRefExoticComponent<TeamItemProps & RefAttributes<HTMLLIElement>>;
+    DotTagItem: ForwardRefExoticComponent<TagDotProps & RefAttributes<HTMLLIElement>>;
+    AlertTagItem: ForwardRefExoticComponent<TagAlertProps & RefAttributes<HTMLLIElement>>;
+    BalanceTagItem: ForwardRefExoticComponent<TagBalanceProps & RefAttributes<HTMLLIElement>>;
+    StatusTagItem: ForwardRefExoticComponent<TagStatusProps & RefAttributes<HTMLLIElement>>;
+    RawTagItem: ForwardRefExoticComponent<TagRawProps & RefAttributes<HTMLLIElement>>;
+    TagListItem: <T extends TagType>(props: TagListProps<T> & {
+        ref?: Ref<HTMLLIElement>;
+    }) => ReturnType<(<T_1 extends TagType>(props: TagListProps<T_1>, ref: ForwardedRef<HTMLLIElement>) => JSX_2.Element)>;
+};
+
+declare type DataListProps = {
+    children: ReactElement | ReactElement[];
+    label?: string;
+    isHorizontal?: boolean;
+};
+
 export declare const defaultTranslations: {
     readonly countries: {
         ad: string;
@@ -1758,6 +1850,8 @@ export declare const defaultTranslations: {
         };
     };
     readonly forms: {
+        readonly yes: "Yes";
+        readonly no: "No";
         readonly actionBar: {
             readonly unsavedChanges: "You have changes pending to be saved";
             readonly saving: "Saving...";
@@ -1819,6 +1913,52 @@ export declare const defaultTranslations: {
     };
 };
 
+declare type DetailsItemContent = (ComponentProps<typeof DataList.Item> & {
+    type: "item";
+}) | (ComponentProps<typeof DataList.PersonItem> & {
+    type: "person";
+}) | (ComponentProps<typeof DataList.CompanyItem> & {
+    type: "company";
+}) | (ComponentProps<typeof DataList.TeamItem> & {
+    type: "team";
+}) | (ComponentProps<typeof Weekdays> & {
+    type: "weekdays";
+}) | (ComponentProps<typeof DataList.DotTagItem> & {
+    type: "dot-tag";
+}) | (Props & {
+    type: "alert-tag";
+}) | (F0TagBalanceProps & {
+    type: "balance-tag";
+}) | (F0TagStatusProps & {
+    type: "status-tag";
+}) | (F0TagRawProps & {
+    type: "raw-tag";
+}) | {
+    [T in TagType_2]: {
+        type: "tag-list";
+        tagList: F0TagListProps<T>;
+    };
+}[TagType_2] | {
+    type: "avatar-list";
+    avatarList: F0AvatarListProps;
+};
+
+/**
+ * Remove a property from a union of objects.
+ * @example
+ * type Person = {
+ *   name: string
+ *   age: number
+ * } | {
+ *   name: string
+ *   height: number
+ * }
+ *
+ * type PersonWithoutName = DistributiveOmit<Person, "name">
+ * // { age: number } | { height: number }
+ */
+declare type DistributiveOmit<T, K extends PropertyKey> = T extends unknown ? Omit<T, K> : never;
+
 /**
  * Grouped configuration for entity references in the AI chat.
  * Combines resolver functions (data fetching) with URL builders (navigation).
@@ -1973,6 +2113,75 @@ declare type F0AvatarCompanyProps = {
     badge?: AvatarBadge;
 } & Pick<BaseAvatarProps, "aria-label" | "aria-labelledby">;
 
+declare type F0AvatarEmojiProps = {
+    emoji: string;
+    size?: (typeof avatarEmojiSizes)[number];
+} & Partial<Pick<BaseAvatarProps, "aria-label" | "aria-labelledby">>;
+
+declare type F0AvatarFileProps = Omit<React.ComponentPropsWithoutRef<typeof Avatar>, "type" | "size"> & {
+    file: FileDef;
+    size?: AvatarFileSize;
+    badge?: AvatarBadge;
+} & Pick<BaseAvatarProps, "aria-label" | "aria-labelledby"> & WithDataTestIdProps;
+
+declare type F0AvatarFlagProps = {
+    flag: CountryCode | (string & {});
+    size?: BaseAvatarProps["size"];
+    badge?: AvatarBadge;
+} & Pick<BaseAvatarProps, "aria-label" | "aria-labelledby">;
+
+declare type F0AvatarIconProps = {
+    icon: IconType;
+    size?: (typeof avatarIconSizes)[number];
+    state?: F0IconProps["state"];
+} & Partial<Pick<BaseAvatarProps, "aria-label" | "aria-labelledby">>;
+
+declare type F0AvatarListProps = {
+    /**
+     * The size of the avatars in the list.
+     * @default "md"
+     */
+    size?: AvatarListSize;
+    /**
+     * Whether to hide tooltips in each avatar.
+     * @default false
+     */
+    noTooltip?: boolean;
+    /**
+     * The maximum number of avatars to display.
+     * @default 3
+     */
+    max?: number;
+    /**
+     * The remaining number to display.
+     */
+    remainingCount?: number;
+    /**
+     * The layout of the avatar list.
+     * - "fill" - Avatars will expand to fill the available width, with overflow items shown in a counter
+     * - "compact" - Avatars will be stacked tightly together up to the max limit, with remaining shown in counter
+     * @default "compact"
+     */
+    layout?: "fill" | "compact";
+} & F0AvatarListPropsAvatars;
+
+declare type F0AvatarListPropsAvatars = {
+    type: "person";
+    avatars: (Omit<PersonAvatarVariant, "type"> & Record<string, unknown>)[];
+} | {
+    type: "team";
+    avatars: (Omit<TeamAvatarVariant, "type"> & Record<string, unknown>)[];
+} | {
+    type: "company";
+    avatars: (Omit<CompanyAvatarVariant, "type"> & Record<string, unknown>)[];
+} | {
+    type: "flag";
+    avatars: (Omit<FlagAvatarVariant, "type"> & Record<string, unknown>)[];
+} | {
+    type: "file";
+    avatars: (Omit<FileAvatarVariant, "type"> & Record<string, unknown>)[];
+};
+
 declare type F0AvatarPersonProps = {
     /**
      * The first name of the person.
@@ -2097,6 +2306,110 @@ export declare type F0OneSwitchProps = React.ComponentPropsWithoutRef<typeof Swi
     autoOpen?: boolean;
 };
 
+declare const F0TagAlert: WithDataTestIdReturnType<ForwardRefExoticComponent<Props_3 & RefAttributes<HTMLDivElement>>>;
+
+declare const F0TagBalance: WithDataTestIdReturnType<ForwardRefExoticComponent<F0TagBalanceProps_2 & RefAttributes<HTMLDivElement>>>;
+
+declare type F0TagBalanceProps = {
+    /**
+     * Inverts the balance status color. Is useful when a negative percent mean something positive.
+     */
+    invertStatus?: boolean;
+    /**
+     * Hint text to display next to the tag (This text is not displayed when the balance is null or undefined)
+     */
+    hint?: string;
+    /**
+     * Info text to display an i icon and a tooltip next to the tag
+     */
+    info?: string;
+    /**
+     * Text to display when the balance is null or undefined
+     */
+    nullText?: string;
+    /**
+     * Value to display next to the tag can be a number, a Numeric or a NumericWithFormatter
+     */
+    amount: RelaxedNumericWithFormatter | Numeric;
+} & ({
+    percentage: (Omit<RelaxedNumericWithFormatter, "value"> & {
+        value: Omit<Numeric, "units" | "unitsPosition">;
+    }) | Omit<Numeric, "units" | "unitsPosition">;
+} | {
+    percentage?: null;
+    formatterOptions?: undefined;
+});
+
+declare const F0TagCompany: WithDataTestIdReturnType<ForwardRefExoticComponent<F0TagCompanyProps & RefAttributes<HTMLDivElement>>>;
+
+declare type F0TagListProps<T extends TagType_2> = {
+    /**
+     * The type of tags to display. Only one type can be used at a time.
+     */
+    type: T;
+    /**
+     * Array of tag data corresponding to the specified type.
+     */
+    tags: Array<TagTypeMapping[T]>;
+    /**
+     * The maximum number of tags to display.
+     * @default 4
+     */
+    max?: number;
+    /**
+     * The remaining number to display.
+     */
+    remainingCount?: number;
+};
+
+declare const F0TagPerson: WithDataTestIdReturnType<ForwardRefExoticComponent<F0TagPersonProps & RefAttributes<HTMLDivElement>>>;
+
+declare type F0TagRawProps = {
+    /**
+     * The label to display in the tag or used for accessible text
+     */
+    text: string;
+    /**
+     * Additional accessible text to display in the tag
+     */
+    additionalAccessibleText?: string;
+    /**
+     * Info text to display an i icon and a tooltip next to the tag
+     */
+    info?: string;
+} & ({
+    icon: IconType;
+    onlyIcon: true;
+} | {
+    icon?: IconType;
+    onlyIcon?: boolean;
+});
+
+declare interface F0TagStatusProps {
+    text: string;
+    variant: Variant;
+    /**
+     * Sometimes you need to clarify the status for screen reader users
+     * E.g., when showing a tooltip for sighted user, provide the tootip text to this prop because tooltips aren't accessible
+     */
+    additionalAccessibleText?: string;
+}
+
+declare const F0TagTeam: WithDataTestIdReturnType<ForwardRefExoticComponent<F0TagTeamProps & RefAttributes<HTMLDivElement>>>;
+
+declare type FileAvatarVariant = Extract<AvatarVariant, {
+    type: "file";
+}>;
+
+declare type FileDef = {
+    name: string;
+    type: string;
+};
+
+declare type FlagAvatarVariant = Extract<AvatarVariant, {
+    type: "flag";
+}>;
+
 /**
  * A preset formatting instruction the LLM can specify instead of a
  * real formatter function. The wrapper component maps these to actual
@@ -2123,6 +2436,23 @@ declare type FormCanvasContent = CanvasContentBase & {
     formModule?: ModuleId;
 };
 
+export declare interface FormCardValueFormatterEntry<T = unknown> {
+    /** Scope to a specific form. Omit to apply to all forms. */
+    formName?: string;
+    /** Scope to a specific custom field name. Omit to apply to all fields. */
+    customFieldName?: string;
+    /** Format function. Return `undefined` to fall back to built-in formatting. */
+    format: (value: T, meta: {
+        key: string;
+        fieldType?: string;
+        customFieldName?: string;
+    }) => DetailsItemContent | DetailsItemContent[] | undefined;
+}
+
+export declare function FormCardValueFormatterProvider({ children, }: {
+    children: ReactNode;
+}): JSX_2.Element;
+
 declare interface GaugeComputation {
     datasetId: string;
     aggregation: AggregationType;
@@ -2349,6 +2679,8 @@ declare type NestedKeyOf<T> = {
     } ? `${K}` | `${K}-${NestedKeyOf<T[K]>}` : `${K}-${NestedKeyOf<T[K]>}` : K extends "DEFAULT" ? never : `${K}`;
 }[keyof T & string];
 
+declare type NewColor = Extract<BaseColor, (typeof tagDotColors)[number]>;
+
 declare type Numeric = NumericValue | number | undefined | null;
 
 /**
@@ -2476,6 +2808,10 @@ declare type PathsToStringProps<T> = T extends string ? [] : {
     [K in Extract<keyof T, string>]: [K, ...PathsToStringProps<T[K]>];
 }[Extract<keyof T, string>];
 
+declare type PersonAvatarVariant = Extract<AvatarVariant, {
+    type: "person";
+}>;
+
 /**
  * Profile data for a person entity (employee), resolved asynchronously
  * and displayed in the entity reference hover card.
@@ -2488,6 +2824,8 @@ export declare type PersonProfile = {
     jobTitle?: string;
 };
 
+declare type PersonTagProps = ComponentProps<typeof F0TagPerson>;
+
 declare interface PieComputation {
     datasetId: string;
     nameColumn: string;
@@ -2500,6 +2838,27 @@ declare interface PieComputation {
 
 declare const privateProps: readonly ["className"];
 
+declare type Props<Text extends string = string> = {
+    text: Text extends "" ? never : Text;
+    level: Level;
+    /**
+     * Info text to display an i icon and a tooltip next to the tag
+     */
+    info?: string;
+};
+
+declare type Props_2 = {
+    text: string;
+    /**
+     * Info text to display an i icon and a tooltip next to the tag
+     */
+    info?: string;
+} & ({
+    color: NewColor;
+} | {
+    customColor: string;
+});
+
 declare interface RadarComputation {
     datasetId: string;
     seriesColumn: string;
@@ -2532,10 +2891,59 @@ export declare type RequisitionProfile = {
     reason?: string;
 };
 
+declare type SetFormCardValueFormatter = <T = unknown>(entry: FormCardValueFormatterEntry<T>) => void;
+
 export declare type SparklineDataPoint = {
     value: number;
 };
 
+declare const statuses: readonly ["neutral", "info", "positive", "warning", "critical"];
+
+declare type TagDataType<T extends string> = Omit<Extract<TagVariant, {
+    type: T;
+}>, "type" | "description">;
+
+declare const tagDotColors: ["viridian", "malibu", "yellow", "purple", "lilac", "barbie", "smoke", "army", "flubber", "indigo", "camel"];
+
+declare type TagType_2 = (typeof tagTypes)[number];
+
+declare type TagTypeMapping = {
+    dot: TagDataType<"dot">;
+    person: TagDataType<"person">;
+    team: TagDataType<"team">;
+    company: TagDataType<"company">;
+    alert: TagDataType<"alert">;
+    status: TagDataType<"status">;
+    balance: TagDataType<"balance">;
+    raw: TagDataType<"raw">;
+};
+
+declare const tagTypes: readonly ["dot", "person", "team", "company", "alert", "status", "balance", "raw"];
+
+declare type TagVariant = BaseTag<{
+    type: "dot";
+} & Props_2> | BaseTag<{
+    type: "person";
+} & PersonTagProps> | BaseTag<{
+    type: "team";
+} & TeamTagProps> | BaseTag<{
+    type: "company";
+} & CompanyTagProps> | BaseTag<{
+    type: "alert";
+} & AlertTagProps> | BaseTag<{
+    type: "status";
+} & F0TagStatusProps> | BaseTag<{
+    type: "balance";
+} & BalanceTagProps> | BaseTag<{
+    type: "raw";
+} & F0TagRawProps>;
+
+declare type TeamAvatarVariant = Extract<AvatarVariant, {
+    type: "team";
+}>;
+
+declare type TeamTagProps = ComponentProps<typeof F0TagTeam>;
+
 declare type TranslationKey = Join<PathsToStringProps<typeof defaultTranslations>, ".">;
 
 declare type TranslationShape<T> = {
@@ -2570,6 +2978,17 @@ export declare function useAiChatTranslations(): AiChatTranslations;
  */
 export declare function useDefaultCopilotActions(): void;
 
+/**
+ * Returns a resolved formatter for the given `formName`.
+ * Matches registered formatters by specificity:
+ *   formName + customFieldName > formName only > customFieldName only > global
+ * Returns `null` when no provider is present or no formatters are registered.
+ */
+export declare function useFormCardValueFormatter(formName: string): ((key: string, value: unknown, meta: {
+    fieldType?: string;
+    customFieldName?: string;
+}) => DetailsItemContent | DetailsItemContent[] | undefined) | null;
+
 export declare function useI18n(): TranslationsType & {
     t: (key: TranslationKey, args?: Record<string, string | number>) => string;
 };
@@ -2586,6 +3005,27 @@ export declare const useMessageSourcesAction: () => void;
  */
 export declare const useOrchestratorThinkingAction: () => void;
 
+/**
+ * Returns a setter to register value formatters used by FormCard.
+ *
+ * ```ts
+ * const setFormatter = useSetFormCardValueFormatter()
+ *
+ * // Global formatter (all forms, all fields)
+ * setFormatter({ format: (value) => ({ type: "item", text: String(value) }) })
+ *
+ * // Scoped to a form
+ * setFormatter({ formName: "create-task", format: (value) => ... })
+ *
+ * // Scoped to a custom field name (across all forms)
+ * setFormatter({ customFieldName: "assignees_selector", format: (value) => ... })
+ *
+ * // Scoped to both
+ * setFormatter({ formName: "create-task", customFieldName: "assignees_selector", format: (value) => ... })
+ * ```
+ */
+export declare function useSetFormCardValueFormatter(): SetFormCardValueFormatter;
+
 /**
  * Profile data for a vacancy entity (ATS vacancy/position), resolved asynchronously
  * and displayed in the entity reference hover card.
@@ -2597,11 +3037,20 @@ export declare type VacancyProfile = {
     vacancyType?: string;
 };
 
+declare type Variant = (typeof statuses)[number];
+
 /**
  * Visualization mode for the AI chat
  */
 export declare type VisualizationMode = "sidepanel" | "fullscreen" | "canvas";
 
+declare const Weekdays: ForwardRefExoticComponent<WeekdaysProps & RefAttributes<HTMLDivElement>>;
+
+declare interface WeekdaysProps {
+    activatedDays?: number[];
+    daysOfTheWeek?: string[];
+}
+
 /**
  * Welcome screen suggestion item
  */
@@ -2611,6 +3060,17 @@ export declare type WelcomeScreenSuggestion = {
     prompt?: string;
 };
 
+declare type WithDataTestIdProps = {
+    dataTestId?: string;
+};
+
+declare interface WithTooltipDescription {
+    /**
+     * Optional description to show in the tooltip
+     */
+    description?: string;
+}
+
 export { }
 
 
@@ -2651,11 +3111,6 @@ declare module "gridstack" {
 }
 
 
-declare namespace Calendar {
-    var displayName: string;
-}
-
-
 declare module "@tiptap/core" {
     interface Commands<ReturnType> {
         aiBlock: {
@@ -2703,3 +3158,8 @@ declare module "@tiptap/core" {
         };
     }
 }
+
+
+declare namespace Calendar {
+    var displayName: string;
+}