@factorialco/f0-react 6.16.4 → 6.18.0

package/dist/experimental.d.ts

@@ -172,9 +172,14 @@ declare const actionButtonVariants: readonly ["default", "outline", "critical",
 
 declare interface ActionCommonProps {
     /**
-     * Tooltip
+     * Tooltip. A string is the description on its own; the object form adds a
+     * bold first line above it — for "which control this is" over "what it holds",
+     * the same two-line shape `F0Select`'s trigger tooltip uses.
      */
-    tooltip?: string | false;
+    tooltip?: string | false | {
+        label?: string;
+        description: string;
+    };
     /**
      * The variant of the action.
      */
@@ -1389,6 +1394,8 @@ declare type ButtonDropdownItem<T = string> = {
 };
 
 declare type ButtonInternalProps = Pick<ActionProps, "size" | "disabled" | "className" | "pressed" | "compact" | "tooltip" | "fontSize"> & DataAttributes & {
+    /** Native button behavior. */
+    type?: ButtonType;
     /**
      * The aria-label of the button if not provided title or label will be used.
      */
@@ -2330,9 +2337,10 @@ export declare const chipVariants: (props?: ({
     className?: ClassValue;
 })) | undefined) => string;
 
-export declare function ClockInControls({ trackedMinutes, remainingMinutes, data, labels, locationId, locations, canShowLocation, locationSelectorDisabled, onClockIn, onClockOut, onBreak, breakTypes, onChangeBreakTypeId, canShowBreakButton, canSeeGraph, canSeeRemainingTime, onChangeLocationId, canShowProject, projectSelectorElement, locationSelectorElement, breakTypeName, }: ClockInControlsProps): JSX_2.Element;
+export declare function ClockInControls({ trackedMinutes, remainingMinutes, data, labels, locationId, locations, canShowLocation, locationSelectorDisabled, onClockIn, onClockOut, onBreak, breakTypes, onChangeBreakTypeId, canShowBreakButton, canSeeGraph, canSeeRemainingTime, onChangeLocationId, canShowProject, projectSelectorElement, locationSelectorElement, projects, projectId, onChangeProjectId, projectSelectorDisabled, projectRequired, locationRequired, breakTypeName, onBreakPromote, variant, loading, }: ClockInControlsProps): JSX_2.Element;
 
-export declare interface ClockInControlsProps {
+/** Everything both variants take, on the same terms. */
+declare interface ClockInControlsBaseProps {
     /** Optional remaining time in minutes */
     remainingMinutes?: number;
     /** Clock in entries data */
@@ -2354,14 +2362,26 @@ export declare interface ClockInControlsProps {
         selectProject: string;
         paid: string;
         unpaid: string;
+        /**
+         * Placeholders for the pickers' search boxes (`horizontal-bar` only).
+         * Optional: without them the pickers fall back to F0Select's own wording.
+         */
+        searchProject?: string;
+        searchLocation?: string;
     };
+    /** The selected location — a leaf, when the list nests. */
     locationId?: string;
     onChangeLocationId: Dispatch<string>;
-    locations: {
-        id: string;
-        name: string;
-        icon: IconType;
-    }[];
+    /**
+     * The locations to offer. Each may carry `sublocations`, two or three levels
+     * deep (location → workplace → work area), and selection is then a leaf.
+     *
+     * Nesting is drawn by the `horizontal-bar` variant, which owns its picker. The
+     * `default` variant's built-in select is flat and offers only the top level — it
+     * has `locationSelectorElement` for a consumer's own drill-in instead — though
+     * it still DISPLAYS a selected leaf wherever it sits in the tree.
+     */
+    locations: ClockInLocation[];
     breakTypes?: BreakType[];
     onChangeBreakTypeId?: Dispatch<string>;
     canShowLocation?: boolean;
@@ -2376,7 +2396,36 @@ export declare interface ClockInControlsProps {
     /** Callback when Break button is clicked */
     onBreak?: (breakTypeId?: string) => void;
     canShowProject?: boolean;
-    projectSelectorElement?: React.ReactNode;
+    breakTypeName?: string;
+    /**
+     * On a break, which action gets the primary button — the other becomes an
+     * icon-only outline beside it.
+     *
+     * Unset, it follows the day: `"clock-out"` once you're into overtime (the hours
+     * are done, so ending them is the useful move), `"resume"` while there are hours
+     * left. Set it to pin one regardless.
+     */
+    onBreakPromote?: "resume" | "clock-out";
+    /**
+     * Draws a placeholder shaped like the chosen `variant` instead of the
+     * controls — for when the day itself hasn't arrived yet. Prefer it over
+     * rendering a zeroed-out day: `trackedMinutes={0}` with no `data` is a real
+     * state ("clocked out, nothing tracked"), not a missing one.
+     */
+    loading?: boolean;
+}
+
+/**
+ * The `default` variant, where the consumer may bring its OWN location and
+ * project controls as nodes: this is the arrangement Factorial already ships,
+ * and both slots are in use (e.g. a drill-in location selector).
+ */
+declare interface ClockInControlsDefaultProps extends ClockInControlsBaseProps {
+    /**
+     * The status and its controls beside the circular `ClockInGraph`, with the
+     * location/project row underneath.
+     */
+    variant?: "default";
     /**
      * Optional custom location control. When provided, it replaces the built-in
      * flat location `F0Select` (in both the editable clocked-out state and the
@@ -2385,19 +2434,130 @@ export declare interface ClockInControlsProps {
      * owns its data and editable/disabled state, mirroring `projectSelectorElement`.
      */
     locationSelectorElement?: React.ReactNode;
-    breakTypeName?: string;
+    projectSelectorElement?: React.ReactNode;
+    projects?: never;
+    projectId?: never;
+    onChangeProjectId?: never;
+    projectSelectorDisabled?: never;
+    /** Only the `horizontal-bar` variant owns the pickers, so only it can relax them. */
+    projectRequired?: never;
+    locationRequired?: never;
+}
+
+/**
+ * The `horizontal-bar` variant, which owns BOTH selectors.
+ *
+ * The custom-render slots are typed away here (`never`) on purpose: this
+ * arrangement puts the two pickers on one line with the day's controls, and a
+ * consumer-supplied node in either slot is what would break that line — so it
+ * takes DATA instead and renders the pickers itself. Location becomes an
+ * `F0ButtonDropdown`, projects an `F0Select` whose groups are the subprojects.
+ */
+declare interface ClockInControlsHorizontalBarProps extends ClockInControlsBaseProps {
+    /**
+     * The Home-widget shape from the custom-home prototype: four full-width rows,
+     * each pinning its two halves to the tile's ends — status + running total on
+     * one line, the day as a horizontal bar, when it started and what is left of
+     * it, then the location and the controls. Fits a narrow rail, where the 160px
+     * ring does not.
+     */
+    variant: "horizontal-bar";
+    /** Not available in this variant — pass `locations` and let it render them. */
+    locationSelectorElement?: never;
+    /** Not available in this variant — pass `projects` and let it render them. */
+    projectSelectorElement?: never;
+    /** The projects to offer, each optionally with its own subprojects. */
+    projects?: ClockInProject[];
+    /** The selected project — or subproject, since selection is always a leaf. */
+    projectId?: string;
+    onChangeProjectId?: Dispatch<string>;
+    projectSelectorDisabled?: boolean;
+    /**
+     * Whether a project must be chosen to clock in. When it isn't, the picker
+     * offers a clear affordance and reports the empty string once cleared.
+     * Defaults to `true` — the stricter reading, and the behaviour before there
+     * was any way to clear.
+     */
+    projectRequired?: boolean;
+    /** The same for the location. Defaults to `true`. */
+    locationRequired?: boolean;
 }
 
+export declare type ClockInControlsProps = ClockInControlsDefaultProps | ClockInControlsHorizontalBarProps;
+
+/**
+ * How the pieces are laid out. Both variants show the same day, run the same
+ * state machine and use the same controls — only their arrangement differs.
+ */
+export declare type ClockInControlsVariant = "default" | "horizontal-bar";
+
 declare interface ClockInGraphProps {
     trackedMinutes?: number;
     data?: {
         from: Date;
         to: Date;
         variant: ClockInStatus;
+        /**
+         * EXTRA context for this stretch of the day, beyond its state — which break,
+         * which task.
+         *
+         * The `horizontal-bar` geometry already tells you when a stretch ran and how
+         * long it lasted when you hover it; this is appended after a `•`, so pass only
+         * what that doesn't already say. The ring has nowhere to put either and
+         * ignores them.
+         */
+        label?: string;
     }[];
     remainingMinutes?: number;
+    /**
+     * - `ring` — the 160px dial, with the running total and the day's two ends
+     *   inside it.
+     * - `horizontal-bar` — the same day as a full-width 6px rail, and nothing
+     *   else: a line that thin has nowhere to put the numbers, so in this variant
+     *   the layout around it carries them (see `ClockInControls`).
+     */
+    variant?: ClockInGraphVariant;
 }
 
+/**
+ * The geometry the day is drawn in. Same segments, same colours, same
+ * `normalizeData` either way — only the shape differs.
+ */
+declare type ClockInGraphVariant = "ring" | "horizontal-bar";
+
+/**
+ * A place you can clock in from, and — optionally — the places INSIDE it.
+ *
+ * Up to two or three levels is what this is for: location → workplace → work
+ * area (Office → Barcelona → Llucuna A-3). Selection is always a LEAF: a location
+ * with `sublocations` is clocked into through one of them, one without is clocked
+ * into directly. The icon is usually only worth setting at the top (Office, Home,
+ * Business trip) — deeper levels inherit the nearest one above them.
+ */
+export declare type ClockInLocation = {
+    id: string;
+    name: string;
+    icon?: IconType;
+    /** The level below. When present, this location itself is not selectable. */
+    sublocations?: ClockInLocation[];
+};
+
+/**
+ * A project as the `horizontal-bar` variant takes it, and — optionally — the work
+ * inside it.
+ *
+ * Selection is always a LEAF: a project with `subprojects` is booked through one
+ * of them, a project without them is booked directly. That rule is what lets the
+ * picker show the hierarchy with F0Select's own group headings rather than an
+ * invented indent — a parent is a heading, not an option.
+ */
+export declare type ClockInProject = {
+    id: string;
+    name: string;
+    /** The level below. When present, the parent itself is not selectable. */
+    subprojects?: ClockInProject[];
+};
+
 declare type ClockInStatus = "clocked-in" | "break" | "clocked-out";
 
 /**
@@ -4152,6 +4312,7 @@ declare const defaultTranslations: {
         readonly closeSearch: "Close search";
         readonly noResults: "No chats found";
         readonly backToLatest: "Jump to latest";
+        readonly online: "Online";
         readonly muted: "Muted";
         readonly mute: "Mute";
         readonly unmute: "Unmute";
@@ -4254,6 +4415,14 @@ declare const defaultTranslations: {
             readonly one: "{{count}} unread";
             readonly other: "{{count}} unread";
         };
+        readonly unreadChatsAbove: {
+            readonly one: "{{count}} unread chat above";
+            readonly other: "{{count}} unread chats above";
+        };
+        readonly unreadChatsBelow: {
+            readonly one: "{{count}} unread chat below";
+            readonly other: "{{count}} unread chats below";
+        };
         readonly emptyConversation: "No messages yet";
         readonly emptyConversationDescription: "Send a message to start the conversation.";
         readonly error: "Couldn't load this conversation";
@@ -5619,7 +5788,6 @@ export declare type F0ChatChannel = {
     avatar: AvatarVariant;
     /** DM only — the other person's presence. */
     presence?: "online" | "offline";
-    muted?: boolean;
     /**
      * Whether the conversation is pinned (favourited) by the current user. Drives
      * the header pin toggle and lets the host surface a "Pinned" group in the
@@ -6060,8 +6228,8 @@ export declare type F0ChatRuntime = {
     /**
      * Toggle the conversation's muted state for the current user. Transport
      * capability only — the header no longer auto-renders a Mute action; the
-     * host surfaces one via {@link F0ChatHeaderAction} (the header still shows
-     * the `channel.muted` status icon either way). factorial →
+     * host surfaces one via {@link F0ChatHeaderAction}. The current muted state
+     * is represented like any other entry in `channel.statuses`. factorial →
      * `channel.mute()` / `channel.unmute()`.
      */
     toggleMute?: () => void | Promise<void>;
@@ -6086,6 +6254,10 @@ export declare type F0ChatSearchResult = {
     id: string;
 };
 
+export declare type F0ChatSenderColor = (typeof f0ChatSenderColors)[number];
+
+export declare const f0ChatSenderColors: readonly ["viridian", "malibu", "yellow", "purple", "lilac", "barbie", "smoke", "army", "flubber", "indigo", "camel", "radical", "orange", "red", "grass"];
+
 export declare type F0ChatSendInput = {
     body: string;
     attachments?: F0ChatAttachment[];
@@ -6159,6 +6331,12 @@ export declare type F0ChatUser = {
     id: string;
     name: string;
     avatar?: AvatarVariant;
+    /**
+     * Stable sender accent. For photo avatars, choose the palette hue closest to
+     * the image's dominant colour so the name and incoming bubble feel related.
+     * When omitted, F0 uses the same name hash as a generated person avatar.
+     */
+    avatarColor?: F0ChatSenderColor;
     /** Secondary line for the hover card (e.g. job title). */
     subtitle?: string;
     /** Link to the person's profile, shown as "View profile" in the hover card. */
@@ -6952,6 +7130,15 @@ declare type F0SelectItemObject<T, R = unknown> = {
     type?: "item";
     value: T;
     label: string;
+    /**
+     * What the TRIGGER shows once this item is selected, when that has to differ
+     * from the row's own `label`. The row is read in the context the list gives it
+     * — under a group header, beside its siblings — and the trigger has none of
+     * that, so a label that is clear in the list can be ambiguous on its own
+     * ("Tokens", once the "Design system" header is gone). Give the trigger the
+     * full path there and leave the row short. Defaults to `label`.
+     */
+    selectedLabel?: string;
     description?: string;
     /** Short token shown next to the label (e.g. a dial code) */
     metadata?: F0SelectItemMetadata;
@@ -10718,8 +10905,10 @@ export declare type SidebarChat = {
     /** When true, the name is replaced by a live "Writing…" label. */
     typing?: boolean;
     presence?: SidebarChatPresence;
-    /** Status icon shown to the right of the name. People only. */
+    /** Single status icon shown to the right of the conversation name. */
     status?: SidebarChatStatus;
+    /** Multiple status icons. Takes precedence over `status` when provided. */
+    statuses?: SidebarChatStatus[];
     /** Epoch ms of the last activity; used for ordering. */
     lastActivityAt?: number;
     /** Whether the chat is pinned (favourited) — selects the solid pin icon. */
@@ -10858,9 +11047,9 @@ export declare type SidebarChatProviderProps = {
 };
 
 /**
- * Status shown as a small icon avatar to the right of a person's name (people
- * only). The consumer fully controls it — pass any icon with an accessible
- * label. F0 does not hardcode any set of statuses.
+ * Status shown as a small icon to the right of a conversation name. The
+ * consumer fully controls it — pass any icon with an accessible label. F0
+ * does not hardcode any set of statuses.
  */
 export declare type SidebarChatStatus = {
     icon: IconType;
@@ -12964,10 +13153,8 @@ declare module "@tiptap/core" {
 
 declare module "@tiptap/core" {
     interface Commands<ReturnType> {
-        indent: {
-            setIndent: (level: number) => ReturnType;
-            unsetIndent: () => ReturnType;
-            outdent: () => ReturnType;
+        moodTracker: {
+            insertMoodTracker: (data: MoodTrackerData) => ReturnType;
         };
     }
 }
@@ -12975,8 +13162,10 @@ declare module "@tiptap/core" {
 
 declare module "@tiptap/core" {
     interface Commands<ReturnType> {
-        moodTracker: {
-            insertMoodTracker: (data: MoodTrackerData) => ReturnType;
+        indent: {
+            setIndent: (level: number) => ReturnType;
+            unsetIndent: () => ReturnType;
+            outdent: () => ReturnType;
         };
     }
 }