@agregio-solutions/design-system 1.97.1 → 1.99.0

package/dist/packages/components/Timeline/Timeline.d.ts

@@ -1,4 +1,4 @@
-import { Line } from './utils/Timeline.types';
+import { ExpandedGroups, Line } from './utils/Timeline.types';
 import { CSSProperties, ReactNode } from 'react';
 export type TimelineProps = {
     /**
@@ -17,6 +17,18 @@ export type TimelineProps = {
      * The configuration of the timeline to display in this line
      */
     emptyPlaceholder?: ReactNode;
+    /**
+     * Expanded state of the group lines, keyed by group name (controlled mode).
+     * When provided, every group line is controlled and a name missing from the
+     * map reads as collapsed. Leave it out to let each group keep its own
+     * internal state. Group names must be unique for this to be unambiguous.
+     */
+    expandedGroups?: ExpandedGroups;
+    /**
+     * Called with the complete next map when a group line is expanded or
+     * collapsed, so it can be passed straight to a state setter.
+     */
+    onExpandedGroupsChange?: (expandedGroups: ExpandedGroups) => void;
     /**
      * The class name of the timeline
      */
@@ -26,4 +38,4 @@ export type TimelineProps = {
      */
     style?: CSSProperties;
 };
-export default function Timeline({ emptyPlaceholder, lines, startDate, endDate, ...props }: TimelineProps): import("react").JSX.Element;
+export default function Timeline({ emptyPlaceholder, lines, startDate, endDate, expandedGroups, onExpandedGroupsChange, ...props }: TimelineProps): import("react").JSX.Element;

package/dist/packages/components/Timeline/components/BlockLineContainer/BlockLineContainer.styled.d.ts

@@ -10,6 +10,14 @@ export declare const GroupContainer: import('@emotion/styled').StyledComponent<{
     theme?: import('@emotion/react').Theme;
     as?: React.ElementType;
 }, import('react').DetailedHTMLProps<import('react').HTMLAttributes<HTMLDivElement>, HTMLDivElement>, {}>;
+/**
+ * One visual row of an overlap group. Its blocks are absolutely positioned
+ * inside it, so blocks that don't overlap can share a row.
+ */
+export declare const LaneContainer: import('@emotion/styled').StyledComponent<{
+    theme?: import('@emotion/react').Theme;
+    as?: React.ElementType;
+}, import('react').DetailedHTMLProps<import('react').HTMLAttributes<HTMLDivElement>, HTMLDivElement>, {}>;
 export declare const Overlay: import('@emotion/styled').StyledComponent<{
     theme?: import('@emotion/react').Theme;
     as?: React.ElementType;

package/dist/packages/components/Timeline/components/BlockLineContainer/utils/assignBlocksToLanes/assignBlocksToLanes.d.ts

@@ -0,0 +1,18 @@
+import { Block } from '../../../../utils/Timeline.types';
+type Lane = Array<Block>;
+/**
+ * Packs the blocks of one overlap group into lanes (the visual rows of a line).
+ *
+ * Blocks sharing a color share a lane as long as they don't overlap each other.
+ * The color carries the entity identity in a Timeline, so an entity reads as a
+ * single row instead of being spread over several rows by an unrelated block
+ * that happens to bridge two of its periods. A color that overlaps itself
+ * consumes as many lanes as needed, so a block is never hidden behind another.
+ *
+ * Lane order is derived from the data alone — earliest start of the color, then
+ * the color string — never from the input order: consumers refetch on an
+ * interval, and an insertion-ordered layout would make the rows jump on every
+ * refresh.
+ */
+export declare function assignBlocksToLanes(blocks: Array<Block>): Array<Lane>;
+export {};

package/dist/packages/components/Timeline/components/BlockLineContainer/utils/assignBlocksToLanes/assignBlocksToLanes.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/packages/components/Timeline/components/BlockLineContainer/utils/getLineHeight/getLineHeight.d.ts

@@ -1,7 +1,7 @@
 type GetLineHeightParams = {
-    nbOfBlocks: number;
+    nbOfLanes: number;
     isCollapsed: boolean;
     indentLevel: number;
 };
-export default function getLineHeight({ nbOfBlocks, isCollapsed, indentLevel, }: GetLineHeightParams): number;
+export default function getLineHeight({ nbOfLanes, isCollapsed, indentLevel, }: GetLineHeightParams): number;
 export {};

package/dist/packages/components/Timeline/components/GroupLineContainer/GroupLineContainer.d.ts

@@ -1,9 +1,19 @@
-import { Block, SubLine } from '../../utils/Timeline.types';
+import { Block, GroupHoverTextFormatter, SubLine } from '../../utils/Timeline.types';
 interface Props {
     name: string;
     subLines: Array<SubLine>;
     lineStartDate: Block["startDate"];
     lineEndDate: Block["endDate"];
+    groupHoverText?: GroupHoverTextFormatter;
+    /**
+     * Whether the group is expanded (controlled). Leave it undefined to let the
+     * group keep its own internal state.
+     */
+    isExpanded?: boolean;
+    /**
+     * Called with the next expanded state whenever the group name is clicked.
+     */
+    onExpandedChange?: (isExpanded: boolean) => void;
 }
-export default function GroupLineContainer({ name, subLines, lineStartDate, lineEndDate, }: Props): import("react").JSX.Element;
+export default function GroupLineContainer({ name, subLines, lineStartDate, lineEndDate, groupHoverText, isExpanded: controlledIsExpanded, onExpandedChange, }: Props): import("react").JSX.Element;
 export {};

package/dist/packages/components/Timeline/doc.md

@@ -15,7 +15,8 @@ Base stories:
 ```tsx
 import { Meta, StoryObj } from "@storybook/react-vite";
 import Timeline from "./Timeline";
-import { within, userEvent, fn } from "storybook/test";
+import { Block } from "./utils/Timeline.types";
+import { within, userEvent, expect, fn } from "storybook/test";
 import MockDate from "mockdate";
 import {
   expectNotPresent,
@@ -505,6 +506,11 @@ export const GroupSimple: Story = {
     await canvas.findByText("Installation 1 PRM_1");
     await canvas.findByTestId("Installation 1 PRM_1 - Indisponibilité 1");
     await canvas.findByTestId("Installation 1 PRM_1 - Activation 1");
+
+    // Clicking again collapses it back: the group holds its own state when the
+    // consumer doesn't control it.
+    await user.click(canvas.getByText("Installation 1"));
+    await expectNotPresent(() => canvas.queryByText("Installation 1 PRM_1"));
   },
 };
 
@@ -704,6 +710,52 @@ export const GroupWithOverflow: Story = {
   },
 };
 
+export const GroupCustomHoverText: Story = {
+  args: {
+    startDate: new Date("2024-01-01T00:00:00.000Z"),
+    endDate: new Date("2024-01-08T00:00:00.000Z"),
+    lines: [
+      {
+        type: "group",
+        name: "Installation 5",
+        groupHoverText: ({ blocks }) => `${blocks.length} indisponibilité(s)`,
+        subLines: [
+          {
+            name: "Installation 5 PRM_1",
+            blocks: [
+              {
+                id: "unavailability-1",
+                startDate: new Date("2024-01-01T00:00:00.000Z"),
+                endDate: new Date("2024-01-03T00:00:00.000Z"),
+                color: "var(--color-content-dataviz-pink-3)",
+                hoverText: "Installation 5 PRM_1 - Indisponibilité 1",
+              },
+            ],
+          },
+          {
+            name: "Installation 5 PRM_2",
+            blocks: [
+              {
+                id: "unavailability-1",
+                startDate: new Date("2024-01-02T00:00:00.000Z"),
+                endDate: new Date("2024-01-04T00:00:00.000Z"),
+                color: "var(--color-content-dataviz-pink-3)",
+                hoverText: "Installation 5 PRM_2 - Indisponibilité 1",
+              },
+            ],
+          },
+        ],
+      },
+    ],
+  },
+  play: async ({ canvasElement, mount }) => {
+    MockDate.set("2024-01-05T12:00:00.000Z");
+    await mount();
+    const canvas = within(canvasElement);
+    await canvas.findByTestId("2 indisponibilité(s)");
+  },
+};
+
 export const MixedSimpleAndGroup: Story = {
   args: {
     startDate: new Date("2024-01-01T00:00:00.000Z"),
@@ -924,6 +976,449 @@ export const GroupFullOverlap: Story = {
     await user.click(canvas.getByText("Maison Dieu - PRM[50014414454079]"));
   },
 };
+
+const DAY_START = new Date("2024-01-01T00:00:00.000Z");
+const DAY_END = new Date("2024-01-02T00:00:00.000Z");
+
+/**
+ * Names the merged blocks of a collapsed group row after the block they were
+ * merged from, so the stories can target them by `data-testid`. Using the id
+ * rather than a formatted date keeps the testids timezone-independent.
+ */
+const groupHoverTextFromFirstBlockId = ({ blocks }: { blocks: Array<Block> }) =>
+  blocks[0].id;
+
+export const GroupCollapsedSameAggregateTwice: Story = {
+  args: {
+    startDate: DAY_START,
+    endDate: DAY_END,
+    lines: [
+      {
+        type: "group",
+        name: "PSN",
+        groupHoverText: groupHoverTextFromFirstBlockId,
+        subLines: [
+          {
+            // The reported bug: one aggregate, two solicitations separated by a
+            // 1h30 gap. They must read as a single row.
+            name: "Agrégat A",
+            blocks: [
+              {
+                id: "agregat-a-matin",
+                startDate: new Date("2024-01-01T11:20:00.000Z"),
+                endDate: new Date("2024-01-01T13:00:00.000Z"),
+                color: "var(--color-content-dataviz-purple-3)",
+                hoverText: "Agrégat A - matin",
+              },
+              {
+                id: "agregat-a-apres-midi",
+                startDate: new Date("2024-01-01T14:30:00.000Z"),
+                endDate: new Date("2024-01-01T16:25:00.000Z"),
+                color: "var(--color-content-dataviz-purple-3)",
+                hoverText: "Agrégat A - après-midi",
+              },
+            ],
+          },
+          {
+            // Long blocks that bridge the two purple ones into a single overlap
+            // group — the actual cause of the bug.
+            name: "Agrégat B",
+            blocks: [
+              {
+                id: "agregat-b",
+                startDate: new Date("2024-01-01T10:45:00.000Z"),
+                endDate: new Date("2024-01-01T16:20:00.000Z"),
+                color: "var(--color-content-dataviz-azure-3)",
+                hoverText: "Agrégat B",
+              },
+            ],
+          },
+          {
+            name: "Agrégat C",
+            blocks: [
+              {
+                id: "agregat-c",
+                startDate: new Date("2024-01-01T11:00:00.000Z"),
+                endDate: new Date("2024-01-01T16:20:00.000Z"),
+                color: "var(--color-content-dataviz-pink-3)",
+                hoverText: "Agrégat C",
+              },
+            ],
+          },
+          {
+            name: "Agrégat D",
+            blocks: [
+              {
+                id: "agregat-d",
+                startDate: new Date("2024-01-01T10:45:00.000Z"),
+                endDate: new Date("2024-01-01T16:35:00.000Z"),
+                color: "var(--color-content-dataviz-ocean-3)",
+                hoverText: "Agrégat D",
+              },
+            ],
+          },
+        ],
+      },
+    ],
+  },
+  play: async ({ canvasElement, mount }) => {
+    MockDate.set("2024-01-01T12:00:00.000Z");
+    await mount();
+    const canvas = within(canvasElement);
+
+    const morning = canvas.getByTestId("agregat-a-matin");
+    const afternoon = canvas.getByTestId("agregat-a-apres-midi");
+
+    // Both belong to the same overlap group, bridged by the long blocks…
+    await expect(morning).toHaveAttribute("data-group-index", "0");
+    await expect(afternoon).toHaveAttribute("data-group-index", "0");
+
+    // …and they are two distinct blocks, not a single merged one: the 1h30 gap
+    // between 13:00 and 14:30 stays visible.
+    await expect(morning.getAttribute("data-start")).not.toBe(
+      afternoon.getAttribute("data-start"),
+    );
+
+    // The fix: one lane for the aggregate, instead of one row per solicitation.
+    await expect(morning).toHaveAttribute("data-lane-index", "3");
+    await expect(afternoon).toHaveAttribute("data-lane-index", "3");
+
+    // Lanes are ordered by the earliest start of their color, then by the color
+    // string: azure and ocean both start at 10:45, azure wins the tie.
+    await expect(canvas.getByTestId("agregat-b")).toHaveAttribute(
+      "data-lane-index",
+      "0",
+    );
+    await expect(canvas.getByTestId("agregat-d")).toHaveAttribute(
+      "data-lane-index",
+      "1",
+    );
+    await expect(canvas.getByTestId("agregat-c")).toHaveAttribute(
+      "data-lane-index",
+      "2",
+    );
+  },
+};
+
+export const GroupExpandedLanePacking: Story = {
+  args: {
+    startDate: DAY_START,
+    endDate: DAY_END,
+    lines: [
+      {
+        type: "group",
+        name: "PSN",
+        groupHoverText: groupHoverTextFromFirstBlockId,
+        subLines: [
+          {
+            name: "Agrégat A",
+            blocks: [
+              // Same color, disjoint: they share a lane even on a sub-line.
+              {
+                id: "purple-matin",
+                startDate: new Date("2024-01-01T10:00:00.000Z"),
+                endDate: new Date("2024-01-01T12:00:00.000Z"),
+                color: "var(--color-content-dataviz-purple-3)",
+                hoverText: "Sub-line - purple matin",
+              },
+              {
+                id: "purple-apres-midi",
+                startDate: new Date("2024-01-01T12:30:00.000Z"),
+                endDate: new Date("2024-01-01T14:00:00.000Z"),
+                color: "var(--color-content-dataviz-purple-3)",
+                hoverText: "Sub-line - purple après-midi",
+              },
+              // Three more colors, so the sub-line needs four lanes and crosses
+              // its own threshold of three.
+              {
+                id: "azure",
+                startDate: new Date("2024-01-01T10:00:00.000Z"),
+                endDate: new Date("2024-01-01T14:00:00.000Z"),
+                color: "var(--color-content-dataviz-azure-3)",
+                hoverText: "Sub-line - azure",
+              },
+              {
+                id: "ocean",
+                startDate: new Date("2024-01-01T10:00:00.000Z"),
+                endDate: new Date("2024-01-01T14:00:00.000Z"),
+                color: "var(--color-content-dataviz-ocean-3)",
+                hoverText: "Sub-line - ocean",
+              },
+              {
+                id: "pink",
+                startDate: new Date("2024-01-01T10:00:00.000Z"),
+                endDate: new Date("2024-01-01T14:00:00.000Z"),
+                color: "var(--color-content-dataviz-pink-3)",
+                hoverText: "Sub-line - pink",
+              },
+            ],
+          },
+          {
+            name: "Agrégat B",
+            blocks: [
+              {
+                id: "brown",
+                startDate: new Date("2024-01-01T11:00:00.000Z"),
+                endDate: new Date("2024-01-01T13:00:00.000Z"),
+                color: "var(--color-content-dataviz-brown-3)",
+                hoverText: "Sub-line - brown",
+              },
+            ],
+          },
+        ],
+      },
+    ],
+  },
+  play: async ({ canvasElement, mount }) => {
+    MockDate.set("2024-01-01T12:00:00.000Z");
+    await mount();
+    const canvas = within(canvasElement);
+    const user = userEvent.setup();
+
+    await user.click(canvas.getByText("PSN"));
+    await canvas.findByText("Agrégat A");
+
+    // A sub-line collapses at three lanes, not five. Purple sorts last, so it
+    // is the lane that gets hidden.
+    await expect(canvas.getByTestId("Sub-line - azure")).toHaveAttribute(
+      "data-lane-index",
+      "0",
+    );
+    await expect(canvas.getByTestId("Sub-line - ocean")).toHaveAttribute(
+      "data-lane-index",
+      "1",
+    );
+    await expect(canvas.getByTestId("Sub-line - pink")).toHaveAttribute(
+      "data-lane-index",
+      "2",
+    );
+    await expectNotPresent(() =>
+      canvas.queryByTestId("Sub-line - purple matin"),
+    );
+
+    await user.click(canvas.getByRole("button", { name: "Afficher plus" }));
+
+    // Once expanded, the two purple blocks share the fourth lane.
+    await expect(canvas.getByTestId("Sub-line - purple matin")).toHaveAttribute(
+      "data-lane-index",
+      "3",
+    );
+    await expect(
+      canvas.getByTestId("Sub-line - purple après-midi"),
+    ).toHaveAttribute("data-lane-index", "3");
+  },
+};
+
+const TWO_PERIODS = [
+  {
+    startDate: new Date("2024-01-01T10:00:00.000Z"),
+    endDate: new Date("2024-01-01T14:00:00.000Z"),
+  },
+  {
+    startDate: new Date("2024-01-01T15:00:00.000Z"),
+    endDate: new Date("2024-01-01T19:00:00.000Z"),
+  },
+];
+
+export const GroupCollapsedExpandButtonCountsLanes: Story = {
+  args: {
+    startDate: DAY_START,
+    endDate: DAY_END,
+    lines: [
+      {
+        type: "group",
+        name: "PSN",
+        groupHoverText: groupHoverTextFromFirstBlockId,
+        subLines: [
+          // Seven blocks, but only five lanes: two aggregates are active over
+          // two disjoint periods each. The collapse threshold is five at this
+          // indent level, so counting blocks would truncate and show the expand
+          // button, while counting lanes shows everything.
+          {
+            name: "Agrégat azure",
+            blocks: [
+              {
+                id: "azure",
+                startDate: new Date("2024-01-01T10:00:00.000Z"),
+                endDate: new Date("2024-01-01T20:00:00.000Z"),
+                color: "var(--color-content-dataviz-azure-3)",
+                hoverText: "Agrégat azure",
+              },
+            ],
+          },
+          {
+            name: "Agrégat brown",
+            blocks: TWO_PERIODS.map((period, index) => ({
+              ...period,
+              id: `brown-${index + 1}`,
+              color: "var(--color-content-dataviz-brown-3)",
+              hoverText: `Agrégat brown ${index + 1}`,
+            })),
+          },
+          {
+            name: "Agrégat negative",
+            blocks: TWO_PERIODS.map((period, index) => ({
+              ...period,
+              id: `negative-${index + 1}`,
+              color: "var(--color-content-dataviz-negative-3)",
+              hoverText: `Agrégat negative ${index + 1}`,
+            })),
+          },
+          {
+            name: "Agrégat neutral",
+            blocks: [
+              {
+                id: "neutral",
+                startDate: new Date("2024-01-01T10:00:00.000Z"),
+                endDate: new Date("2024-01-01T20:00:00.000Z"),
+                color: "var(--color-content-dataviz-neutral-3)",
+                hoverText: "Agrégat neutral",
+              },
+            ],
+          },
+          {
+            name: "Agrégat ocean",
+            blocks: [
+              {
+                id: "ocean",
+                startDate: new Date("2024-01-01T10:00:00.000Z"),
+                endDate: new Date("2024-01-01T20:00:00.000Z"),
+                color: "var(--color-content-dataviz-ocean-3)",
+                hoverText: "Agrégat ocean",
+              },
+            ],
+          },
+        ],
+      },
+    ],
+  },
+  play: async ({ canvasElement, mount }) => {
+    MockDate.set("2024-01-01T12:00:00.000Z");
+    await mount();
+    const canvas = within(canvasElement);
+
+    // Five lanes for seven blocks: nothing is truncated, so no expand button.
+    await expectNotPresent(() =>
+      canvas.queryByRole("button", { name: "Afficher plus" }),
+    );
+
+    // Every block stays visible, including the second period of each of the two
+    // aggregates that have one.
+    for (const id of [
+      "azure",
+      "brown-1",
+      "brown-2",
+      "negative-1",
+      "negative-2",
+      "neutral",
+      "ocean",
+    ]) {
+      await canvas.findByTestId(id);
+    }
+
+    // All five colors start at 10:00, so the color string orders the lanes, and
+    // each aggregate's two periods share its lane.
+    await expect(canvas.getByTestId("azure")).toHaveAttribute(
+      "data-lane-index",
+      "0",
+    );
+    await expect(canvas.getByTestId("brown-1")).toHaveAttribute(
+      "data-lane-index",
+      "1",
+    );
+    await expect(canvas.getByTestId("brown-2")).toHaveAttribute(
+      "data-lane-index",
+      "1",
+    );
+    await expect(canvas.getByTestId("negative-1")).toHaveAttribute(
+      "data-lane-index",
+      "2",
+    );
+    await expect(canvas.getByTestId("negative-2")).toHaveAttribute(
+      "data-lane-index",
+      "2",
+    );
+    await expect(canvas.getByTestId("neutral")).toHaveAttribute(
+      "data-lane-index",
+      "3",
+    );
+    await expect(canvas.getByTestId("ocean")).toHaveAttribute(
+      "data-lane-index",
+      "4",
+    );
+  },
+};
+
+export const GroupControlledExpansion: Story = {
+  args: {
+    startDate: new Date("2024-01-01T00:00:00.000Z"),
+    endDate: new Date("2024-01-08T00:00:00.000Z"),
+    // MA is expanded and PSN collapsed from the outside: the consumer owns the state
+    // (e.g. to keep it across data changes that would otherwise remount the group).
+    expandedGroups: { MA: true, PSN: false },
+    onExpandedGroupsChange: fn(),
+    lines: [
+      {
+        type: "group",
+        name: "MA",
+        subLines: [
+          {
+            name: "Agrégat MA 1",
+            blocks: [
+              {
+                id: "ma-1",
+                startDate: new Date("2024-01-02T00:00:00.000Z"),
+                endDate: new Date("2024-01-04T00:00:00.000Z"),
+                color: "var(--color-content-dataviz-azure-3)",
+                hoverText: "Agrégat MA 1 - Sollicitation 1",
+              },
+            ],
+          },
+        ],
+      },
+      {
+        type: "group",
+        name: "PSN",
+        subLines: [
+          {
+            name: "Agrégat PSN 1",
+            blocks: [
+              {
+                id: "psn-1",
+                startDate: new Date("2024-01-05T00:00:00.000Z"),
+                endDate: new Date("2024-01-07T00:00:00.000Z"),
+                color: "var(--color-content-dataviz-purple-3)",
+                hoverText: "Agrégat PSN 1 - Sollicitation 1",
+              },
+            ],
+          },
+        ],
+      },
+    ],
+  },
+  play: async ({ args, canvasElement, mount }) => {
+    MockDate.set("2024-01-05T12:00:00.000Z");
+    await mount();
+    const canvas = within(canvasElement);
+    const user = userEvent.setup();
+
+    // Expanded state comes from the prop only: no click needed for MA, and PSN stays
+    // collapsed even though both groups render the exact same way.
+    await canvas.findByText("Agrégat MA 1");
+    await expectNotPresent(() => canvas.queryByText("Agrégat PSN 1"));
+
+    await user.click(canvas.getByText("MA"));
+
+    // The callback hands back the whole next map, ready for a state setter.
+    expect(args.onExpandedGroupsChange).toHaveBeenCalledWith({
+      MA: false,
+      PSN: false,
+    });
+    // The story's args are static, so the row must stay expanded: the prop is the
+    // single source of truth, the internal state never shadows it.
+    expect(canvas.getByText("Agrégat MA 1")).toBeInTheDocument();
+  },
+};
 ```
 
 ## Developer notes
@@ -1018,10 +1513,44 @@ Use `type: "group"` with a `subLines` array instead of a `blocks` array.
 
 When collapsed, the group displays a **merged view** of all sub-lines' blocks. Blocks sharing the same color are merged into a single block spanning their combined range. This gives a quick overview of activity across all sub-lines.
 
+By default, hovering a merged block shows its date range. Provide a `groupHoverText` function on the group line to customize this text. It receives the merged interval's `startDate`, `endDate`, `color`, and the original `blocks` that were merged into it:
+
+```ts
+{
+  type: "group",
+  name: "Installation 3",
+  groupHoverText: ({ startDate, endDate, blocks }) =>
+    `${blocks.length} events between ${startDate} and ${endDate}`,
+  subLines: [ /* ... */ ],
+}
+```
+
+Give `groupHoverText` a stable identity (`useCallback`, or defined outside the component) — it's used as a dependency to memoize the merge computation, so a new function on every render defeats that memoization.
+
+<Canvas of={Timeline.GroupCustomHoverText} />
+
 ### Expanded state
 
 Clicking the group name **expands** it, revealing each sub-line on its own indented row. Clicking again collapses it back.
 
+By default each group owns that state internally. It is therefore lost whenever the group unmounts — which happens more often than it looks, since removing a line shifts its siblings' React keys. Pass `expandedGroups` (a `Record<groupName, boolean>`) and `onExpandedGroupsChange` to hold it yourself instead:
+
+```tsx
+const [expandedGroups, setExpandedGroups] = useState({ MA: true });
+
+<Timeline
+  lines={lines}
+  startDate={startDate}
+  endDate={endDate}
+  expandedGroups={expandedGroups}
+  onExpandedGroupsChange={setExpandedGroups}
+/>;
+```
+
+`onExpandedGroupsChange` receives the complete next map, so it can be handed straight to a state setter. A group name missing from the map reads as collapsed, and the two props go together: providing `expandedGroups` without `onExpandedGroupsChange` freezes every group. Since the map is keyed by name, **group names must be unique**.
+
+<Canvas of={Timeline.GroupControlledExpansion} />
+
 ### Simple group (one sub-line)
 
 <Canvas of={Timeline.GroupSimple} />