@art-tools/react-gantt 0.1.0 → 0.2.1

package/dist/index.d.cts

@@ -4,6 +4,7 @@ import { default as default_2 } from 'react';
 import { ElementType } from 'react';
 import { JSX } from 'react/jsx-runtime';
 import { ReactNode } from 'react';
+import { RefObject } from 'react';
 
 /**
  * Key of the built-in edit/add/delete column, dropped when `readOnly` is set.
@@ -19,7 +20,12 @@ declare interface BarA11yProps {
     "aria-colspan": number;
     "aria-label": string;
     "aria-selected": boolean | undefined;
-    title: string;
+    /**
+     * The native browser tooltip. Optional because a chart with a tooltip slot
+     * suppresses it — two tooltips would stack. `aria-label` is unaffected, so
+     * the accessible name survives either way.
+     */
+    title?: string;
 }
 
 /** State passed to the function form of each BarProgress slotProps. */
@@ -58,6 +64,113 @@ export declare interface BarProgressSlots {
     root?: ElementType;
 }
 
+/**
+ * Open state shared *within one tooltip slot*, owned by `BarTooltipRoot` and read
+ * by `BarTooltipTrigger` and the popup.
+ *
+ * It sits inside the slot rather than in `BarTooltipConsumer` so that nothing
+ * outside the slot has an opinion about open state (ADR-022).
+ *
+ * `null` means there is no root above, which is why `BarTooltipTrigger` is a
+ * no-op rather than an error: `TaskBar`/`ProjectBar`/`MilestoneBar` are public
+ * exports that render standalone.
+ */
+export declare interface BarTooltipContextValue {
+    open: boolean;
+    setOpen: (open: boolean) => void;
+    /** The bar's DOM node, used to verify the pointer really did leave it. */
+    anchorRef: RefObject<HTMLDivElement | null>;
+}
+
+/**
+ * State passed to the function form of the tooltip slotProps, and to the slot
+ * component itself.
+ *
+ * `displayEnd` is resolved by `Row` rather than left to the consumer because
+ * `task.endDate` is an *exclusive* instant (ADR-014): a Mon–Fri task stores
+ * Saturday midnight, so rendering it raw reads as ending on Saturday. Handing
+ * over the already-inclusive date is what stops every tooltip from reintroducing
+ * that bug.
+ */
+export declare interface BarTooltipOwnerState {
+    task: GanttTask;
+    /** Resolved progress, override-aware during a drag — not `task.progress`. */
+    progress: number;
+    /** Inclusive, user-facing end date. `undefined` for an instant (a milestone). */
+    displayEnd: Date | undefined;
+    /**
+     * The bar itself. The slot is a *wrapper*: it has to render this, and has to
+     * decide for itself when to show a popup beside it — there is no `open` prop,
+     * because the chart holds no open state (ADR-022). Use `BarTooltipRoot` +
+     * `BarTooltipTrigger` for the built-in hover behaviour, or a third-party
+     * tooltip's own root and trigger.
+     */
+    children?: ReactNode;
+}
+
+export declare interface BarTooltipProps extends BarTooltipOwnerState {
+    /**
+     * The bar's DOM node, for a custom tooltip that wants to position against the
+     * bar rather than the cursor. `null` until the bar mounts, and also when a
+     * consumer has replaced `slots.root` with a component that does not forward
+     * refs.
+     *
+     * The built-in tooltip ignores it — it places from the cursor (ADR-022).
+     */
+    anchorRef: RefObject<HTMLDivElement | null>;
+}
+
+/**
+ * Owns one bar tooltip's open state and publishes it to `BarTooltipTrigger` and
+ * whatever renders the popup.
+ *
+ * Belongs *inside* the tooltip slot, and a slot is free to skip it entirely and
+ * use a third-party tooltip's root instead (ADR-022).
+ *
+ * Exported for the middle case: a custom tooltip that wants the library's hover
+ * and closing behaviour with different markup. Compose it with
+ * `BarTooltipTrigger` and `useBarTooltip`.
+ */
+export declare function BarTooltipRoot({ anchorRef, children, }: {
+    anchorRef: RefObject<HTMLDivElement | null>;
+    children: ReactNode;
+}): JSX.Element;
+
+/** Slot config for the bar tooltip. */
+export declare type BarTooltipSlotConfig = SlotConfig<BarTooltipSlots, BarTooltipSlotProps>;
+
+export declare interface BarTooltipSlotProps {
+    tooltip?: SlotPropsInput<ComponentProps<"div">, BarTooltipOwnerState>;
+}
+
+export declare interface BarTooltipSlots {
+    /**
+     * The tooltip. Default: none — nothing is rendered and the bar keeps its
+     * native `title`. Pass `GanttBarTooltip` for the built-in one, or any component
+     * accepting {@link BarTooltipProps}.
+     */
+    tooltip?: ElementType;
+}
+
+/**
+ * Turns the element it is given into the tooltip's trigger. Belongs inside the
+ * tooltip slot, under a `BarTooltipRoot` and wrapped around the slot's
+ * `children`: that is what makes hover behaviour the slot's own business rather
+ * than the bar's.
+ *
+ * It **merges** onto that element rather than wrapping it, which is not a style
+ * preference: the bar contains `<button>` resize and connector handles, so a
+ * wrapping trigger — Base UI's default renders a `<button>` — would nest buttons
+ * and produce invalid HTML that breaks those controls. `cloneElement` adds no DOM
+ * at all.
+ *
+ * Handlers are composed with whatever the element already has, so a consumer's
+ * `slotProps.root` handlers and the a11y payload keep firing.
+ */
+export declare function BarTooltipTrigger({ children }: {
+    children: ReactNode;
+}): ReactNode;
+
 /** Axis-aligned pixel bounds. */
 export declare interface Bounds {
     minX: number;
@@ -356,8 +469,30 @@ export declare interface GanttBarsSlots {
     barProgressResizeHandle?: BarProgressResizeHandleSlotConfig;
     taskResizer?: TaskResizerSlotConfig;
     connectorHandles?: ConnectorHandlesSlotConfig;
+    /**
+     * One slot for all three bar types, rendered by `DraggableBar` so it is
+     * scoped to the bar's own hover. Empty by default: no tooltip is rendered and
+     * the bar keeps its native `title`. Note it is lost if `slots.root` is
+     * replaced, since `DraggableBar` is only the default root (ADR-022).
+     */
+    tooltip?: BarTooltipSlotConfig;
 }
 
+/**
+ * The built-in bar tooltip. Opt in with `slots={{ tooltip: GanttBarTooltip }}`;
+ * it is never rendered by default.
+ *
+ * A wrapper, not a sibling: it renders the bar it is handed and mounts its own
+ * root and trigger around it, so it holds no privileged position over any other
+ * slot (ADR-022).
+ *
+ * Placed from the cursor in JS, not with CSS anchor positioning: anchoring to the
+ * bar puts the tooltip at the midpoint of a bar that can be wider than the
+ * viewport. It follows the pointer for as long as it is open; there is no dwell
+ * delay.
+ */
+export declare function GanttBarTooltip({ task, progress, displayEnd, anchorRef, className, style, children, ...divProps }: BarTooltipProps & ComponentProps<"div">): JSX.Element;
+
 /**
  * The chart's working-time calendar. Three scopes resolve in the order
  * `dates` → `days` → `hours`, so a specific date beats a weekday rule, which
@@ -732,7 +867,7 @@ export declare function mergeSlotProps<Props extends {
     style?: CSSProperties;
 }, OwnerState>(internalProps: Props, slotProps: SlotPropsInput<Props, OwnerState> | undefined, ownerState: OwnerState): Props;
 
-export declare function MilestoneBar({ size, centerLeft, top, colWidth, title, a11y, onMove, onMoveEnd, slots: slotsProp, slotProps: slotPropsProp, }: MilestoneBarProps): JSX.Element;
+export declare function MilestoneBar({ size, centerLeft, top, colWidth, title, a11y, onMove, onMoveEnd, tooltip, slots: slotsProp, slotProps: slotPropsProp, }: MilestoneBarProps): JSX.Element;
 
 export declare interface MilestoneBarOwnerState {
     size: number;
@@ -749,6 +884,11 @@ declare interface MilestoneBarProps {
     /** Editing handlers; omitted on a read-only chart (see `TaskBar`). */
     onMove?: (newCenterLeft: number) => void;
     onMoveEnd?: (newCenterLeft: number) => void;
+    /**
+     * Task data handed to the root so it can render the tooltip slot. Forwarded
+     * verbatim; a replaced `slots.root` that ignores it simply shows no tooltip.
+     */
+    tooltip?: BarTooltipOwnerState;
     slots?: MilestoneBarSlots;
     slotProps?: MilestoneBarSlotProps;
 }
@@ -775,7 +915,7 @@ export declare interface Point {
     y: number;
 }
 
-export declare function ProjectBar({ width, height, left, top, colWidth, title, a11y, progress, onProgressChange, onProgressEnd, onMove, onMoveEnd, slots: slotsProp, slotProps: slotPropsProp, }: ProjectBarProps): JSX.Element;
+export declare function ProjectBar({ width, height, left, top, colWidth, title, a11y, progress, onProgressChange, onProgressEnd, onMove, onMoveEnd, tooltip, slots: slotsProp, slotProps: slotPropsProp, }: ProjectBarProps): JSX.Element;
 
 /** State passed to the function form of each ProjectBar slotProps. */
 export declare interface ProjectBarOwnerState {
@@ -799,6 +939,11 @@ declare interface ProjectBarProps {
     onProgressEnd?: (newProgress: number) => void;
     onMove?: (newLeft: number) => void;
     onMoveEnd?: (newLeft: number) => void;
+    /**
+     * Task data handed to the root so it can render the tooltip slot. Forwarded
+     * verbatim; a replaced `slots.root` that ignores it simply shows no tooltip.
+     */
+    tooltip?: BarTooltipOwnerState;
     slots?: ProjectBarSlots;
     slotProps?: ProjectBarSlotProps;
 }
@@ -859,7 +1004,7 @@ export declare interface SlotConfig<Slots, SlotProps> {
  */
 export declare type SlotPropsInput<P, OwnerState> = Partial<P> | ((ownerState: OwnerState) => Partial<P>);
 
-export declare function TaskBar({ width, height, left, top, colWidth, title, a11y, progress, onProgressChange, onProgressEnd, onResize, onResizeEnd, onMove, onMoveEnd, slots: slotsProp, slotProps: slotPropsProp, }: TaskBarProps): JSX.Element;
+export declare function TaskBar({ width, height, left, top, colWidth, title, a11y, progress, onProgressChange, onProgressEnd, onResize, onResizeEnd, onMove, onMoveEnd, tooltip, slots: slotsProp, slotProps: slotPropsProp, }: TaskBarProps): JSX.Element;
 
 /** State passed to the function form of each TaskBar slotProps. */
 export declare interface TaskBarOwnerState {
@@ -888,6 +1033,11 @@ declare interface TaskBarProps {
     onResizeEnd?: (edge: "start" | "end", edgePx: number) => void;
     onMove?: (newLeft: number) => void;
     onMoveEnd?: (newLeft: number) => void;
+    /**
+     * Task data handed to the root so it can render the tooltip slot. Forwarded
+     * verbatim; a replaced `slots.root` that ignores it simply shows no tooltip.
+     */
+    tooltip?: BarTooltipOwnerState;
     slots?: TaskBarSlots;
     slotProps?: TaskBarSlotProps;
 }
@@ -1015,6 +1165,9 @@ export declare interface TreeCellSlots {
     placeholder?: ElementType;
 }
 
+/** The enclosing `BarTooltipRoot`'s state, or `null` when there is none. */
+export declare const useBarTooltip: () => BarTooltipContextValue | null;
+
 export declare function useGanttReadOnly(): boolean;
 
 /** Read the grid-side slot groups. Returns `{}` outside a provider. */

package/dist/index.d.ts

@@ -4,6 +4,7 @@ import { default as default_2 } from 'react';
 import { ElementType } from 'react';
 import { JSX } from 'react/jsx-runtime';
 import { ReactNode } from 'react';
+import { RefObject } from 'react';
 
 /**
  * Key of the built-in edit/add/delete column, dropped when `readOnly` is set.
@@ -19,7 +20,12 @@ declare interface BarA11yProps {
     "aria-colspan": number;
     "aria-label": string;
     "aria-selected": boolean | undefined;
-    title: string;
+    /**
+     * The native browser tooltip. Optional because a chart with a tooltip slot
+     * suppresses it — two tooltips would stack. `aria-label` is unaffected, so
+     * the accessible name survives either way.
+     */
+    title?: string;
 }
 
 /** State passed to the function form of each BarProgress slotProps. */
@@ -58,6 +64,113 @@ export declare interface BarProgressSlots {
     root?: ElementType;
 }
 
+/**
+ * Open state shared *within one tooltip slot*, owned by `BarTooltipRoot` and read
+ * by `BarTooltipTrigger` and the popup.
+ *
+ * It sits inside the slot rather than in `BarTooltipConsumer` so that nothing
+ * outside the slot has an opinion about open state (ADR-022).
+ *
+ * `null` means there is no root above, which is why `BarTooltipTrigger` is a
+ * no-op rather than an error: `TaskBar`/`ProjectBar`/`MilestoneBar` are public
+ * exports that render standalone.
+ */
+export declare interface BarTooltipContextValue {
+    open: boolean;
+    setOpen: (open: boolean) => void;
+    /** The bar's DOM node, used to verify the pointer really did leave it. */
+    anchorRef: RefObject<HTMLDivElement | null>;
+}
+
+/**
+ * State passed to the function form of the tooltip slotProps, and to the slot
+ * component itself.
+ *
+ * `displayEnd` is resolved by `Row` rather than left to the consumer because
+ * `task.endDate` is an *exclusive* instant (ADR-014): a Mon–Fri task stores
+ * Saturday midnight, so rendering it raw reads as ending on Saturday. Handing
+ * over the already-inclusive date is what stops every tooltip from reintroducing
+ * that bug.
+ */
+export declare interface BarTooltipOwnerState {
+    task: GanttTask;
+    /** Resolved progress, override-aware during a drag — not `task.progress`. */
+    progress: number;
+    /** Inclusive, user-facing end date. `undefined` for an instant (a milestone). */
+    displayEnd: Date | undefined;
+    /**
+     * The bar itself. The slot is a *wrapper*: it has to render this, and has to
+     * decide for itself when to show a popup beside it — there is no `open` prop,
+     * because the chart holds no open state (ADR-022). Use `BarTooltipRoot` +
+     * `BarTooltipTrigger` for the built-in hover behaviour, or a third-party
+     * tooltip's own root and trigger.
+     */
+    children?: ReactNode;
+}
+
+export declare interface BarTooltipProps extends BarTooltipOwnerState {
+    /**
+     * The bar's DOM node, for a custom tooltip that wants to position against the
+     * bar rather than the cursor. `null` until the bar mounts, and also when a
+     * consumer has replaced `slots.root` with a component that does not forward
+     * refs.
+     *
+     * The built-in tooltip ignores it — it places from the cursor (ADR-022).
+     */
+    anchorRef: RefObject<HTMLDivElement | null>;
+}
+
+/**
+ * Owns one bar tooltip's open state and publishes it to `BarTooltipTrigger` and
+ * whatever renders the popup.
+ *
+ * Belongs *inside* the tooltip slot, and a slot is free to skip it entirely and
+ * use a third-party tooltip's root instead (ADR-022).
+ *
+ * Exported for the middle case: a custom tooltip that wants the library's hover
+ * and closing behaviour with different markup. Compose it with
+ * `BarTooltipTrigger` and `useBarTooltip`.
+ */
+export declare function BarTooltipRoot({ anchorRef, children, }: {
+    anchorRef: RefObject<HTMLDivElement | null>;
+    children: ReactNode;
+}): JSX.Element;
+
+/** Slot config for the bar tooltip. */
+export declare type BarTooltipSlotConfig = SlotConfig<BarTooltipSlots, BarTooltipSlotProps>;
+
+export declare interface BarTooltipSlotProps {
+    tooltip?: SlotPropsInput<ComponentProps<"div">, BarTooltipOwnerState>;
+}
+
+export declare interface BarTooltipSlots {
+    /**
+     * The tooltip. Default: none — nothing is rendered and the bar keeps its
+     * native `title`. Pass `GanttBarTooltip` for the built-in one, or any component
+     * accepting {@link BarTooltipProps}.
+     */
+    tooltip?: ElementType;
+}
+
+/**
+ * Turns the element it is given into the tooltip's trigger. Belongs inside the
+ * tooltip slot, under a `BarTooltipRoot` and wrapped around the slot's
+ * `children`: that is what makes hover behaviour the slot's own business rather
+ * than the bar's.
+ *
+ * It **merges** onto that element rather than wrapping it, which is not a style
+ * preference: the bar contains `<button>` resize and connector handles, so a
+ * wrapping trigger — Base UI's default renders a `<button>` — would nest buttons
+ * and produce invalid HTML that breaks those controls. `cloneElement` adds no DOM
+ * at all.
+ *
+ * Handlers are composed with whatever the element already has, so a consumer's
+ * `slotProps.root` handlers and the a11y payload keep firing.
+ */
+export declare function BarTooltipTrigger({ children }: {
+    children: ReactNode;
+}): ReactNode;
+
 /** Axis-aligned pixel bounds. */
 export declare interface Bounds {
     minX: number;
@@ -356,8 +469,30 @@ export declare interface GanttBarsSlots {
     barProgressResizeHandle?: BarProgressResizeHandleSlotConfig;
     taskResizer?: TaskResizerSlotConfig;
     connectorHandles?: ConnectorHandlesSlotConfig;
+    /**
+     * One slot for all three bar types, rendered by `DraggableBar` so it is
+     * scoped to the bar's own hover. Empty by default: no tooltip is rendered and
+     * the bar keeps its native `title`. Note it is lost if `slots.root` is
+     * replaced, since `DraggableBar` is only the default root (ADR-022).
+     */
+    tooltip?: BarTooltipSlotConfig;
 }
 
+/**
+ * The built-in bar tooltip. Opt in with `slots={{ tooltip: GanttBarTooltip }}`;
+ * it is never rendered by default.
+ *
+ * A wrapper, not a sibling: it renders the bar it is handed and mounts its own
+ * root and trigger around it, so it holds no privileged position over any other
+ * slot (ADR-022).
+ *
+ * Placed from the cursor in JS, not with CSS anchor positioning: anchoring to the
+ * bar puts the tooltip at the midpoint of a bar that can be wider than the
+ * viewport. It follows the pointer for as long as it is open; there is no dwell
+ * delay.
+ */
+export declare function GanttBarTooltip({ task, progress, displayEnd, anchorRef, className, style, children, ...divProps }: BarTooltipProps & ComponentProps<"div">): JSX.Element;
+
 /**
  * The chart's working-time calendar. Three scopes resolve in the order
  * `dates` → `days` → `hours`, so a specific date beats a weekday rule, which
@@ -732,7 +867,7 @@ export declare function mergeSlotProps<Props extends {
     style?: CSSProperties;
 }, OwnerState>(internalProps: Props, slotProps: SlotPropsInput<Props, OwnerState> | undefined, ownerState: OwnerState): Props;
 
-export declare function MilestoneBar({ size, centerLeft, top, colWidth, title, a11y, onMove, onMoveEnd, slots: slotsProp, slotProps: slotPropsProp, }: MilestoneBarProps): JSX.Element;
+export declare function MilestoneBar({ size, centerLeft, top, colWidth, title, a11y, onMove, onMoveEnd, tooltip, slots: slotsProp, slotProps: slotPropsProp, }: MilestoneBarProps): JSX.Element;
 
 export declare interface MilestoneBarOwnerState {
     size: number;
@@ -749,6 +884,11 @@ declare interface MilestoneBarProps {
     /** Editing handlers; omitted on a read-only chart (see `TaskBar`). */
     onMove?: (newCenterLeft: number) => void;
     onMoveEnd?: (newCenterLeft: number) => void;
+    /**
+     * Task data handed to the root so it can render the tooltip slot. Forwarded
+     * verbatim; a replaced `slots.root` that ignores it simply shows no tooltip.
+     */
+    tooltip?: BarTooltipOwnerState;
     slots?: MilestoneBarSlots;
     slotProps?: MilestoneBarSlotProps;
 }
@@ -775,7 +915,7 @@ export declare interface Point {
     y: number;
 }
 
-export declare function ProjectBar({ width, height, left, top, colWidth, title, a11y, progress, onProgressChange, onProgressEnd, onMove, onMoveEnd, slots: slotsProp, slotProps: slotPropsProp, }: ProjectBarProps): JSX.Element;
+export declare function ProjectBar({ width, height, left, top, colWidth, title, a11y, progress, onProgressChange, onProgressEnd, onMove, onMoveEnd, tooltip, slots: slotsProp, slotProps: slotPropsProp, }: ProjectBarProps): JSX.Element;
 
 /** State passed to the function form of each ProjectBar slotProps. */
 export declare interface ProjectBarOwnerState {
@@ -799,6 +939,11 @@ declare interface ProjectBarProps {
     onProgressEnd?: (newProgress: number) => void;
     onMove?: (newLeft: number) => void;
     onMoveEnd?: (newLeft: number) => void;
+    /**
+     * Task data handed to the root so it can render the tooltip slot. Forwarded
+     * verbatim; a replaced `slots.root` that ignores it simply shows no tooltip.
+     */
+    tooltip?: BarTooltipOwnerState;
     slots?: ProjectBarSlots;
     slotProps?: ProjectBarSlotProps;
 }
@@ -859,7 +1004,7 @@ export declare interface SlotConfig<Slots, SlotProps> {
  */
 export declare type SlotPropsInput<P, OwnerState> = Partial<P> | ((ownerState: OwnerState) => Partial<P>);
 
-export declare function TaskBar({ width, height, left, top, colWidth, title, a11y, progress, onProgressChange, onProgressEnd, onResize, onResizeEnd, onMove, onMoveEnd, slots: slotsProp, slotProps: slotPropsProp, }: TaskBarProps): JSX.Element;
+export declare function TaskBar({ width, height, left, top, colWidth, title, a11y, progress, onProgressChange, onProgressEnd, onResize, onResizeEnd, onMove, onMoveEnd, tooltip, slots: slotsProp, slotProps: slotPropsProp, }: TaskBarProps): JSX.Element;
 
 /** State passed to the function form of each TaskBar slotProps. */
 export declare interface TaskBarOwnerState {
@@ -888,6 +1033,11 @@ declare interface TaskBarProps {
     onResizeEnd?: (edge: "start" | "end", edgePx: number) => void;
     onMove?: (newLeft: number) => void;
     onMoveEnd?: (newLeft: number) => void;
+    /**
+     * Task data handed to the root so it can render the tooltip slot. Forwarded
+     * verbatim; a replaced `slots.root` that ignores it simply shows no tooltip.
+     */
+    tooltip?: BarTooltipOwnerState;
     slots?: TaskBarSlots;
     slotProps?: TaskBarSlotProps;
 }
@@ -1015,6 +1165,9 @@ export declare interface TreeCellSlots {
     placeholder?: ElementType;
 }
 
+/** The enclosing `BarTooltipRoot`'s state, or `null` when there is none. */
+export declare const useBarTooltip: () => BarTooltipContextValue | null;
+
 export declare function useGanttReadOnly(): boolean;
 
 /** Read the grid-side slot groups. Returns `{}` outside a provider. */