Blocks / Timeline

Timeline

Records as bars between two dates, in sections, a sticky column of names. Drag or Alt+arrows to move.

import { Timeline } from "@forgeron/ui";
/01 → Projects
Lyon depot
Q4 closing
Carrier rates
Safety audit
import { Timeline } from "@forgeron/ui";

const projects = [
  {
    id: "lyon",
    name: "Lyon depot",
    color: "var(--accent)",
    start: "2026-10-12",
    end: "2027-01-15",
    milestones: [
      { id: "lease", label: "Lease signed", date: "2026-10-15", done: true },
      { id: "racks", label: "Dock and racks", date: "2026-12-05" },
    ],
  },
  {
    id: "q4",
    name: "Q4 closing",
    color: "var(--success)",
    start: "2026-11-02",
    end: "2026-12-31",
    milestones: [{ id: "pack", label: "Auditor pack", date: "2026-12-15" }],
  },
  {
    id: "rates",
    name: "Carrier rates",
    color: "var(--warning)",
    start: "2026-11-16",
    end: "2026-12-04",
  },
  { id: "audit", name: "Safety audit", end: "2026-12-10" },
];

export default function Projects() {
  return (
    <div style={{ width: "100%", height: 230, display: "flex", border: "1px solid var(--line)" }}>
      <Timeline records={projects} today="2026-11-18" toolbar={false} labelWidth={120} />
    </div>
  );
}
/02 → Editable issues
Alt and the arrows move the dates, by a day; add Shift to move the end alone.
Supplier invoices arrive twice
Carrier rates: import the new grid
Dock schedule for Lyon
Fire exit signage audit
Quarterly safety walk
Drag a bar, or Alt and the arrows on a row
// Issues from useListView, grouped by status, as they would sit in a list view. Drag a bar, its
// edges, or press Alt and the arrows on a row to change its dates.
import {
  STATUS_NAMES,
  StatusGlyph,
  Timeline,
  useListView,
  type IssueItem,
  type StatusKind,
  type ViewSpec,
} from "@forgeron/ui";
import { useState } from "react";

type Planned = IssueItem & { start?: string };

const STATUSES: StatusKind[] = ["progress", "todo", "backlog"];
const COLORS: Partial<Record<StatusKind, string>> = {
  progress: "var(--accent)",
  todo: "var(--ink-muted)",
};

const initial: Planned[] = [
  {
    id: "OPS-40",
    title: "Supplier invoices arrive twice",
    status: "progress",
    start: "2026-11-10",
    due: "2026-11-20",
  },
  {
    id: "OPS-37",
    title: "Carrier rates: import the new grid",
    status: "progress",
    start: "2026-11-16",
    due: "2026-11-27",
  },
  {
    id: "OPS-41",
    title: "Dock schedule for Lyon",
    status: "todo",
    start: "2026-11-23",
    due: "2026-12-04",
  },
  { id: "OPS-38", title: "Fire exit signage audit", status: "todo", due: "2026-11-19" },
  { id: "OPS-35", title: "Quarterly safety walk", status: "backlog", due: "2026-12-02" },
];

const spec: ViewSpec<Planned> = {
  read: (issue, field) => (field === "status" ? issue.status : null),
  groupings: {
    status: { key: (i) => i.status, order: STATUSES, name: (k) => STATUS_NAMES[k as StatusKind] },
  },
};

export default function EditableIssues() {
  const [issues, setIssues] = useState(initial);
  const [last, setLast] = useState("Drag a bar, or Alt and the arrows on a row");
  const view = useListView(issues, spec, {
    defaultDisplay: {
      layout: "timeline",
      grouping: "status",
      ordering: "",
      toggles: {},
      properties: [],
    },
  });
  return (
    <div style={{ width: "100%", display: "grid", gap: 12 }}>
      <div style={{ height: 340, display: "flex", border: "1px solid var(--line)" }}>
        <Timeline
          groups={view.groups.map((g) => ({
            ...g,
            glyph: <StatusGlyph status={g.key as StatusKind} />,
          }))}
          getColor={(i) => COLORS[i.status]}
          today="2026-11-18"
          defaultZoom="weeks"
          onOpen={(id) => setLast(`Open ${id}`)}
          onChange={(id, { start, end }) => {
            setIssues((all) =>
              all.map((i) =>
                i.id === id ? { ...i, start: start ?? undefined, due: end ?? undefined } : i,
              ),
            );
            setLast(`${id}: ${start ?? "no start"} → ${end ?? "no end"}`);
          }}
        />
      </div>
      <span style={{ font: "400 11px/1 var(--font-mono)", color: "var(--ink-dim)" }}>{last}</span>
    </div>
  );
}
/03 → Roadmap
Second warehouse
Books in Odoo
Electric fleet
ISO 9001 audit
// A roadmap by quarters, with the zoom and Today held outside the block (a display menu, a
// toolbar of your own) through `zoom` and the `scrollToToday` handle.
import { Button, Segmented, Timeline, type TimelineHandle, type TimelineZoom } from "@forgeron/ui";
import { useRef, useState } from "react";

const initiatives = [
  {
    id: "eu",
    name: "Second warehouse",
    color: "var(--accent)",
    start: "2026-07-01",
    end: "2027-03-31",
  },
  {
    id: "books",
    name: "Books in Odoo",
    color: "var(--success)",
    start: "2026-09-14",
    end: "2026-12-31",
  },
  {
    id: "fleet",
    name: "Electric fleet",
    color: "var(--warning)",
    start: "2027-01-04",
    end: "2027-06-30",
  },
  { id: "iso", name: "ISO 9001 audit", end: "2027-02-15" },
];

export default function Roadmap() {
  const [zoom, setZoom] = useState<TimelineZoom>("quarters");
  const timeline = useRef<TimelineHandle>(null);
  return (
    <div style={{ width: "100%", display: "grid", gap: 8 }}>
      <div style={{ display: "flex", gap: 8, justifyContent: "flex-end" }}>
        <Button size="sm" onClick={() => timeline.current?.scrollToToday()}>
          Today
        </Button>
        <Segmented
          label="Zoom"
          value={zoom}
          onChange={(z) => setZoom(z as TimelineZoom)}
          options={[
            { value: "months", label: "Months" },
            { value: "quarters", label: "Quarters" },
          ]}
        />
      </div>
      <div style={{ height: 220, display: "flex", border: "1px solid var(--line)" }}>
        <Timeline
          ref={timeline}
          records={initiatives}
          zoom={zoom}
          onZoomChange={setZoom}
          weekNumbers
          today="2026-11-18"
          toolbar={false}
        />
      </div>
    </div>
  );
}
API → Props
PropTypeDefaultDescription
groups{ key, name, glyph?, records }[]—The rows in sections: useListView's groups as they are.
recordsT[]—The rows without sections, when there are no groups.
getId(record) => stringrecord.idThe key of a record.
getLabel(record) => stringtitle, else nameIts name, also said to assistive technology.
getStart(record) => string | nullrecord.startThe first day, YYYY-MM-DD.
getEnd(record) => string | nullend, else due, else targetThe last day. With no start, the record is a point: a due date.
getColor(record) => string | undefinedrecord.colorA CSS colour for its mark, e.g. var(--accent). Grey without one.
getMilestones(record) => { id, label, date, done? }[]record.milestonesDiamonds on the row; filled in ember once reached.
renderLabel / renderBar(record) => ReactNode—The name cell and the inside of a bar. An issue's id and title by default.
zoom / defaultZoom"weeks" | "months" | "quarters""months"A day is 28, 6 or 2 px. Controlled or not.
onZoomChange(zoom) => void—When the zoom changes.
todaystringthe device's dateYYYY-MM-DD: marked in ember.
selected / defaultSelectedstring | null—The current record, marked. Controlled or not.
onSelectedChange(id: string) => void—When the arrows or a click move the current record.
onOpen(id: string) => void—A click or Enter on a record.
onChange(id, { start, end }) => void—Makes dates editable: drag a bar or its edges; Alt+arrows on a row move it (a day by weeks, a week otherwise), Shift for the end alone.
collapsed / defaultCollapsedstring[]—The keys of the folded sections. Controlled or not.
onCollapsedChange(keys: string[]) => void—When a section is folded or opened.
toolbarbooleantrueToday and the zoom or mode above. Off when a display menu holds them.
weekNumbersbooleanfalseW47 instead of the date of each Monday, by months.
labelWidthnumber240The width of the name column, in px.
refRef<{ scrollToToday }>—Scrolls today into view, for a Today button of your own.
classNamestring—Extra classes.