@factorialco/f0-react 6.17.0 → 6.19.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.
      */
@@ -2332,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 */
@@ -2356,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;
@@ -2378,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
@@ -2387,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";
 
 /**
@@ -6972,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;