@lotics/ui 46.14.1 → 47.1.0

package/src/deadline.ts

@@ -120,6 +120,16 @@ export function countdownLabel(days: number, labels: DeadlineLabels): string {
  * same thing in a vocabulary the rest of the field grid does not speak.
  *
  *     <DetailRow label="SI cut-off" {...deadlineAnnotation(days, words.deadline)}>
+ *
+ * **Spread it BEFORE the row's own `description`, never after.** Outside the
+ * warning window this returns `{ description }`, so spreading it last silently
+ * overwrites a `description=` the caller wrote — and only on the rows that are
+ * NOT urgent, which is most of them. Nothing renders empty and nothing throws;
+ * the field's standing rule sentence simply stops appearing, and the screen
+ * that lost it looks finished. Put the spread first and a caller's own
+ * `description` wins, which is the order a reader expects anyway:
+ *
+ *     <DetailRow label="Đến ngày" {...deadlineAnnotation(d, w)} description="…">
  */
 export function deadlineAnnotation(
   days: number,

package/src/file_row.tsx

@@ -172,7 +172,16 @@ export function FileRow({
   const body = (
     <>
       <View style={styles.text}>
-        <Text size="sm" weight="medium" numberOfLines={1}>
+        {/* HAI dòng, không một. Ở một hàng chật không cách sắp xếp nào nhét vừa
+            một cái tên 280px vào 79px trên một dòng — nên lựa chọn thật sự là
+            cắt nó hay cho nó xuống dòng, và cái bị cắt ở đây là thứ NHẬN DIỆN
+            cả hàng. Chiều dọc thì không mất gì: tên ngắn vẫn một dòng, chỉ tên
+            dài mới cao thêm.
+
+            Cho khe `status` `flexShrink` là chưa đủ và đã thử: cái nút bên trong
+            khe ấy do người gọi dựng, nó cứng, nên co cái vỏ không làm nội dung
+            hẹp lại. */}
+        <Text size="sm" weight="medium" numberOfLines={2}>
           {name}
         </Text>
         {/* A STRING keeps the muted single-line treatment; a node renders as
@@ -294,6 +303,20 @@ const styles = StyleSheet.create({
   rowPressed: { backgroundColor: colors.zinc["100"] },
   // The accessible "Open" door — fills the row left of the trailing sibling.
   door: { flex: 1, flexDirection: "row", alignItems: "center", gap: 12, cursor: CURSOR_DEFAULT },
-  status: { marginLeft: "auto", paddingLeft: 12 },
-  text: { flex: 1, gap: 1 },
+  // TRẠNG THÁI là bên nhường chỗ, không phải tên tệp.
+  //
+  // `flexShrink` trong React Native mặc định là 0 — khác web — nên ô trạng thái
+  // giữ nguyên bề ngang tự nhiên của nó mãi mãi, còn `text` (flex: 1, tức basis
+  // 0) nuốt trọn phần bị ép. Kết quả ở màn hẹp: một huy hiệu "Còn hiệu lực"
+  // chiếm 137 trên 202 pixel và cái bị cắt là TÊN TỆP — thứ nhận diện cả hàng.
+  // Hai đợt rà soát ứng dụng độc lập đều đâm vào chỗ này và đều phải lách ở
+  // phía ứng dụng.
+  //
+  // Bộ giao diện có sẵn luật cho việc này: một hàng phải nói rõ bên nào GIỮ.
+  // Bên giữ là tên; trạng thái co lại trước. Ở bề ngang rộng không có gì co cả
+  // — chỉ khi hàng chật thì thứ tự nhường mới có ý nghĩa.
+  status: { marginLeft: "auto", paddingLeft: 12, flexShrink: 1, minWidth: 0 },
+  // `minWidth: 0` là thứ cho một con flex thật sự nhỏ hơn nội dung của nó; thiếu
+  // nó thì `numberOfLines` không bao giờ có cơ hội cắt vì hộp không chịu hẹp lại.
+  text: { flex: 1, gap: 1, minWidth: 0 },
 });

package/src/finding.tsx

@@ -220,7 +220,7 @@ const styles = StyleSheet.create({
   // being read aloud, the same defect `CommentsButton` was fixed for. It also
   // wrapped: at phone width a line could BEGIN with the separator. Stacking pairs
   // each source with its own value at every width and needs no separator at all.
-  readings: { flexDirection: "column", alignItems: "flex-start", gap: 4 },
+  readings: { flexDirection: "column", alignItems: "stretch", gap: 4 },
   reading: { flexDirection: "row", alignItems: "baseline", gap: 5, minWidth: 0 },
   // The same split as `title`/`delta` one row up, for the same reason: the SOURCE
   // is a label and gives way, the VALUE is the figure and never does. Both halves

package/src/form_text_input.tsx

@@ -7,10 +7,17 @@ export interface FormTextInputProps extends Omit<FormFieldProps, "style">, TextI
 /** `FormField` (label / description / warning / error / optional) wrapping a `TextInputField` — one
  *  labeled text field. For a 2-col grid cell, prefer a bare `FormField style={half}` around the input. */
 export function FormTextInput(props: FormTextInputProps) {
-  const { label, description, warning, optional, error, ...textInputProps } = props;
+  const { label, description, warning, optional, optionalLabel, error, ...textInputProps } = props;
 
   return (
-    <FormField label={label} description={description} warning={warning} error={error} optional={optional}>
+    <FormField
+      label={label}
+      description={description}
+      warning={warning}
+      error={error}
+      optional={optional}
+      optionalLabel={optionalLabel}
+    >
       <TextInputField {...textInputProps} />
     </FormField>
   );

package/src/gantt/gantt_view.tsx

@@ -1,176 +1,160 @@
-import { useEffect, useMemo, useRef, useState, type ReactNode } from "react";
-import { View, ScrollView, StyleSheet, type StyleProp, type ViewStyle } from "react-native";
+import { useEffect, useMemo, useRef, useState } from "react";
+import { View, ScrollView, StyleSheet } from "react-native";
 import { Text } from "../text";
-import { colors } from "../colors";
+import { colors, solid } from "../colors";
+import { proportionalRadius } from "../control_surface";
 import { FocusRingPressable } from "../focus_ring_pressable";
-
-function GanttButton(props: {
-  onPress?: () => void;
-  accessibilityLabel?: string;
-  style: StyleProp<ViewStyle>;
-  children: ReactNode;
-}) {
-  return (
-    <FocusRingPressable
-      onPress={props.onPress}
-      accessibilityRole={props.onPress ? "button" : undefined}
-      accessibilityLabel={props.accessibilityLabel}
-      style={props.style}
-    >
-      {props.children}
-    </FocusRingPressable>
-  );
-}
-import { addDays, dayDiff } from "../calendar/dates";
-import { usePointerDrag } from "../use_pointer_drag";
-import { axisRange, barGeometry, buildTicks, pxPerDay } from "./scale";
-import { DEFAULT_GANTT_LABELS } from "./types";
+import { SegmentedControl, type SegmentOption } from "../segmented_control";
+import { useLoticsLocale } from "../locale";
+import { dayDiff } from "../calendar/dates";
+import { axisRange, barGeometry, buildRows, buildTicks, pxPerDay } from "./scale";
 import type { GanttLabels, GanttScale, GanttTask } from "./types";
 
 const LABEL_W = 188;
 const HEADER_H = 38;
 const ROW_H = 40;
+const GROUP_H = 30;
 const BAR_H = 22;
-const HANDLE_W = 8;
-const MIN_BAR = 8;
+const MILESTONE = 14;
 const SCALES: GanttScale[] = ["day", "week", "month"];
 
 export interface GanttViewProps<T = unknown> {
   tasks: GanttTask<T>[];
   defaultScale?: GanttScale;
+  /** What counts as today for the marker and the opening scroll position. */
   today?: Date;
   locale?: string;
   /** Optional toolbar caption shown left of the zoom switch. */
   title?: string;
-  /** User-facing chrome strings; defaults to English. */
+  /** Per-instance overrides; the rest resolve from `LoticsLocale.gantt`. */
   labels?: Partial<GanttLabels>;
   onTaskPress?: (task: GanttTask<T>) => void;
-  /** When set, each bar gets a right-edge resize handle; dragging it adjusts the
-   *  task's end. Receives the task + the new inclusive end day (clamped ≥ start). */
-  onTaskResize?: (task: GanttTask<T>, newEnd: Date) => void;
 }
 
 /**
- * Timeline / gantt: a frozen task-label column beside a horizontally-scrollable
- * zoomable axis. Bars are positioned by {@link barGeometry}; month boundaries get
- * a heavier gridline; a red line marks today. The axis opens scrolled to today
- * so a long history doesn't bury the active range. Renders at its natural height
- * — wrap in a ScrollView for very long task lists.
+ * A Gantt chart: a frozen label column beside a zoomable, horizontally
+ * scrollable axis, with tasks in lanes and dependency arrows between them.
+ *
+ * **Reach for this over `CalendarView` when the ROWS are the subject** — a
+ * phase, an owner, a vehicle, a channel — and dates are the horizontal axis. A
+ * calendar answers "what happens on the 14th"; this answers "what is this team
+ * doing, and what is waiting on what".
+ *
+ * **Lanes** come from `group`, **milestones** render as diamonds, and `progress`
+ * fills a portion of the bar. There are deliberately no dependency connectors:
+ * lane order and bar position already carry the sequence, and elbow arrows over
+ * a ruled grid add line noise to say it a second time.
+ *
+ * Renders at its natural height — wrap in a `ScrollView` for very long lists.
  */
 export function GanttView<T = unknown>(props: GanttViewProps<T>) {
-  const { tasks, defaultScale = "week", today = new Date(), locale, title, onTaskPress, onTaskResize } = props;
-  const L = { ...DEFAULT_GANTT_LABELS, ...props.labels };
+  const { tasks, defaultScale = "week", today = new Date(), locale, title, onTaskPress } = props;
+  const pack = useLoticsLocale();
+  const L: GanttLabels = { ...pack.gantt, ...props.labels };
   const [scale, setScale] = useState<GanttScale>(defaultScale);
 
-  const taskById = useMemo(() => new Map(tasks.map((t) => [t.id, t])), [tasks]);
-  const { live, bind } = usePointerDrag((id, _pointer, delta) => {
-    const t = taskById.get(id);
-    if (!t || !onTaskResize) return;
-    const days = Math.round(delta.dx / pxPerDay(scale));
-    if (days === 0) return;
-    const newEnd = addDays(t.end ?? t.start, days);
-    onTaskResize(t, newEnd < t.start ? t.start : newEnd);
-  });
-
+  const rows = useMemo(() => buildRows(tasks), [tasks]);
   const { start: axisStart, end: axisEnd } = useMemo(() => axisRange(tasks, today), [tasks, today]);
-  const ticks = useMemo(() => buildTicks(axisStart, axisEnd, scale, locale), [axisStart, axisEnd, scale, locale]);
-  const axisWidth = useMemo(() => (dayDiff(axisStart, axisEnd) + 1) * pxPerDay(scale), [axisStart, axisEnd, scale]);
+  const ticks = useMemo(
+    () => buildTicks(axisStart, axisEnd, scale, locale),
+    [axisStart, axisEnd, scale, locale],
+  );
+  const axisWidth = useMemo(
+    () => (dayDiff(axisStart, axisEnd) + 1) * pxPerDay(scale),
+    [axisStart, axisEnd, scale],
+  );
   const todayLeft = dayDiff(axisStart, today) * pxPerDay(scale);
   const todayInRange = today >= axisStart && today <= axisEnd;
 
-  // Open scrolled to today (a margin of recent past visible), like the time-grid
-  // scrolls to "now" — keeps the active range in view when history is long.
   const scrollRef = useRef<ScrollView>(null);
   useEffect(() => {
-    const id = setTimeout(() => scrollRef.current?.scrollTo({ x: Math.max(0, todayLeft - 96), animated: false }), 0);
+    const id = setTimeout(
+      () => scrollRef.current?.scrollTo({ x: Math.max(0, todayLeft - 96), animated: false }),
+      0,
+    );
     return () => clearTimeout(id);
   }, [scale, todayLeft]);
 
+  const options: SegmentOption<GanttScale>[] = SCALES.map((s) => ({ label: L[s], value: s }));
+
+  if (tasks.length === 0) {
+    return (
+      <View style={styles.empty}>
+        <Text size="sm" color="muted">{L.empty}</Text>
+      </View>
+    );
+  }
+
   return (
     <View style={styles.root}>
-      {/* Toolbar: zoom */}
       <View style={styles.toolbar}>
         {title ? <Text size="sm" color="muted">{title}</Text> : <View />}
-        <View style={styles.zoomSwitch}>
-          {SCALES.map((s) => (
-            <GanttButton key={s} onPress={() => setScale(s)} style={[styles.zoomBtn, scale === s && styles.zoomBtnActive]}>
-              <Text size="sm" weight={scale === s ? "medium" : "regular"} color={scale === s ? "default" : "muted"}>
-                {L[s]}
-              </Text>
-            </GanttButton>
-          ))}
-        </View>
+        <SegmentedControl<GanttScale>
+          accessibilityLabel={L.task}
+          options={options}
+          value={scale}
+          onValueChange={setScale}
+        />
       </View>
 
       <View style={{ flexDirection: "row", flex: 1 }}>
         {/* Frozen label column */}
-        <View style={{ width: LABEL_W, borderRightWidth: 1, borderRightColor: colors.border }}>
-          <View style={[styles.headerCell, { height: HEADER_H, paddingLeft: 12, justifyContent: "center" }]}>
-            <Text size="xs" color="muted" style={{ textTransform: "uppercase" }}>{L.task}</Text>
+        <View style={styles.labelColumn}>
+          <View style={styles.labelHeader}>
+            <Text size="xs" color="muted" style={styles.uppercase}>{L.task}</Text>
           </View>
-          {tasks.map((t) => (
-            <View key={t.id} style={[styles.labelRow, { height: ROW_H }]}>
-              <View style={{ width: 8, height: 8, borderRadius: 2, backgroundColor: t.color || colors.teal[600] }} />
-              <Text size="sm" numberOfLines={1} style={{ flex: 1 }}>{t.label}</Text>
-            </View>
-          ))}
+          {rows.map((row) =>
+            row.kind === "group" ? (
+              <View key={`g${row.group}`} style={styles.groupLabel}>
+                <Text size="xs" weight="semibold" color="muted" numberOfLines={1} style={styles.uppercase}>
+                  {row.group}
+                </Text>
+              </View>
+            ) : (
+              <View key={row.task.id} style={styles.labelRow}>
+                <View style={[styles.swatch, { backgroundColor: solid(row.task.color ?? "teal") }]} />
+                <Text size="sm" numberOfLines={1} style={styles.labelText}>{row.task.label}</Text>
+              </View>
+            ),
+          )}
         </View>
 
         {/* Scrollable timeline */}
         <ScrollView ref={scrollRef} horizontal style={{ flex: 1 }} showsHorizontalScrollIndicator>
           <View style={{ width: axisWidth }}>
-            {/* Header ticks */}
-            <View style={{ height: HEADER_H, flexDirection: "row", borderBottomWidth: 1, borderBottomColor: colors.border }}>
+            <View style={styles.tickHeader}>
               {ticks.map((tk) => (
                 <View
                   key={tk.date.toISOString()}
-                  style={{ position: "absolute", left: tk.left, top: 0, bottom: 0, justifyContent: "center", paddingLeft: 4, borderLeftWidth: tk.monthStart ? 1 : 0, borderLeftColor: colors.zinc[300] }}
+                  style={[styles.tick, { left: tk.left, borderLeftWidth: tk.monthStart ? 1 : 0 }]}
                 >
-                  <Text size="xs" weight={tk.monthStart ? "medium" : "regular"} color={tk.monthStart ? "default" : "muted"}>
+                  <Text
+                    size="xs"
+                    weight={tk.monthStart ? "medium" : "regular"}
+                    color={tk.monthStart ? "default" : "muted"}
+                  >
                     {tk.label}
                   </Text>
                 </View>
               ))}
             </View>
 
-            {/* Task rows */}
-            {tasks.map((t) => {
-              const base = barGeometry(t, axisStart, scale);
-              const dragging = live && live.id === t.id ? live : null;
-              const width = dragging ? Math.max(MIN_BAR, base.width + dragging.dx) : base.width;
-              const accent = t.color || colors.teal[600];
-              return (
-                <View key={t.id} style={{ height: ROW_H, borderBottomWidth: 1, borderBottomColor: colors.zinc[100] }}>
-                  {ticks.map((tk) =>
-                    tk.monthStart ? (
-                      <View key={tk.date.toISOString()} style={{ position: "absolute", left: tk.left, top: 0, bottom: 0, borderLeftWidth: 1, borderLeftColor: colors.zinc[200] }} />
-                    ) : null,
-                  )}
-                  <GanttButton
-                    onPress={onTaskPress ? () => onTaskPress(t) : undefined}
-                    accessibilityLabel={t.label}
-                    style={{ position: "absolute", left: base.left, width, top: (ROW_H - BAR_H) / 2, height: BAR_H }}
-                  >
-                    <View style={{ flex: 1, borderRadius: 5, backgroundColor: accent, justifyContent: "center", paddingHorizontal: 8, opacity: dragging ? 0.85 : 1 }}>
-                      <Text size="xs" weight="medium" numberOfLines={1} style={{ color: colors.white }}>{t.label}</Text>
-                    </View>
-                  </GanttButton>
-                  {onTaskResize ? (
-                    <View
-                      ref={bind(t.id, "ew-resize")}
-                      style={{ position: "absolute", left: base.left + width - HANDLE_W, width: HANDLE_W + 6, top: (ROW_H - BAR_H) / 2, height: BAR_H, alignItems: "center", justifyContent: "center", zIndex: 2 }}
-                    >
-                      <View style={{ width: 3, height: 11, borderRadius: 2, backgroundColor: "rgba(255,255,255,0.75)" }} />
-                    </View>
-                  ) : null}
-                </View>
-              );
-            })}
+            {rows.map((row) =>
+              row.kind === "group" ? (
+                <View key={`g${row.group}`} style={styles.groupBand} />
+              ) : (
+                <TaskRow
+                  key={row.task.id}
+                  task={row.task}
+                  axisStart={axisStart}
+                  scale={scale}
+                  monthTicks={ticks}
+                  onPress={onTaskPress ? () => onTaskPress(row.task) : undefined}
+                />
+              ),
+            )}
 
-            {/* Today marker */}
-            {todayInRange ? (
-              <View style={{ position: "absolute", left: todayLeft, top: 0, bottom: 0, width: 2, backgroundColor: colors.red[500] }} />
-            ) : null}
+            {todayInRange ? <View style={[styles.todayLine, { left: todayLeft }]} /> : null}
           </View>
         </ScrollView>
       </View>
@@ -178,12 +162,121 @@ export function GanttView<T = unknown>(props: GanttViewProps<T>) {
   );
 }
 
+function TaskRow<T>(props: {
+  task: GanttTask<T>;
+  axisStart: Date;
+  scale: GanttScale;
+  monthTicks: { date: Date; left: number; monthStart: boolean }[];
+  onPress?: () => void;
+}) {
+  const { task, axisStart, scale, monthTicks, onPress } = props;
+  const bar = barGeometry(task, axisStart, scale);
+  const hue = colors[task.color ?? "teal"];
+  // The same wash-and-ink discipline the calendar's chips use: the track is the
+  // family's lightest ground and the progress a step up from it, never the
+  // saturated 500 — a row of solid bars is the paint chart this moved away from.
+  // The milestone keeps the solid shade: it is 14px and carries identity.
+  const accent = solid(task.color ?? "teal");
+  // Same rule as the calendar's chips: the corner is a proportion of the box,
+  // so a 22px bar is not rendered as a pill.
+  const radius = proportionalRadius(BAR_H);
+
+  return (
+    <View style={styles.taskRow}>
+      {monthTicks.map((tk) =>
+        tk.monthStart ? (
+          <View key={tk.date.toISOString()} style={[styles.monthRule, { left: tk.left }]} />
+        ) : null,
+      )}
+      {task.milestone ? (
+        <FocusRingPressable
+          onPress={onPress}
+          accessibilityRole={onPress ? "button" : undefined}
+          accessibilityLabel={task.label}
+          style={[styles.milestoneHit, { left: bar.left - MILESTONE / 2 }]}
+        >
+          {/* A rotated square: a moment has no duration, and drawing it as a
+              one-day bar reads as a day of work that was never scheduled. */}
+          <View style={[styles.milestone, { backgroundColor: accent }]} />
+        </FocusRingPressable>
+      ) : (
+        <FocusRingPressable
+          onPress={onPress}
+          accessibilityRole={onPress ? "button" : undefined}
+          accessibilityLabel={task.label}
+          style={[styles.barHit, { left: bar.left, width: bar.width }]}
+        >
+          {({ hovered }) => (
+          <View style={[styles.bar, { backgroundColor: onPress && hovered ? hue[200] : hue[100], borderRadius: radius }]}>
+            {task.progress != null ? (
+              <View
+                style={[
+                  styles.progress,
+                  { backgroundColor: hue[400], width: `${Math.max(0, Math.min(1, task.progress)) * 100}%` },
+                ]}
+              />
+            ) : (
+              <View style={[styles.progress, { backgroundColor: hue[300], width: "100%" }]} />
+            )}
+          </View>
+          )}
+        </FocusRingPressable>
+      )}
+    </View>
+  );
+}
+
 const styles = StyleSheet.create({
   root: { flex: 1, backgroundColor: colors.white },
-  toolbar: { flexDirection: "row", alignItems: "center", justifyContent: "space-between", paddingHorizontal: 14, paddingVertical: 10, borderBottomWidth: 1, borderBottomColor: colors.border },
-  zoomSwitch: { flexDirection: "row", backgroundColor: colors.zinc[100], borderRadius: 10, padding: 2 },
-  zoomBtn: { paddingHorizontal: 12, paddingVertical: 5, borderRadius: 8 },
-  zoomBtnActive: { backgroundColor: colors.white },
-  headerCell: { borderBottomWidth: 1, borderBottomColor: colors.border },
-  labelRow: { flexDirection: "row", alignItems: "center", gap: 8, paddingHorizontal: 12, borderBottomWidth: 1, borderBottomColor: colors.zinc[100] },
+  empty: { flex: 1, alignItems: "center", justifyContent: "center", padding: 24, backgroundColor: colors.white },
+  toolbar: {
+    flexDirection: "row",
+    alignItems: "center",
+    justifyContent: "space-between",
+    paddingHorizontal: 14,
+    paddingVertical: 10,
+    gap: 12,
+  },
+  // No rule down the column: the frozen half is set off by the axis content
+  // beginning, and a border here is one more line on a surface already ruled
+  // horizontally by every row.
+  labelColumn: { width: LABEL_W },
+  labelHeader: { height: HEADER_H, paddingLeft: 12, justifyContent: "center" },
+  uppercase: { textTransform: "uppercase" },
+  groupLabel: {
+    height: GROUP_H,
+    justifyContent: "flex-end",
+    paddingHorizontal: 12,
+    paddingBottom: 6,
+  },
+  labelRow: { height: ROW_H, flexDirection: "row", alignItems: "center", gap: 8, paddingHorizontal: 12 },
+  swatch: { width: 8, height: 8, borderRadius: 2, flexShrink: 0 },
+  labelText: { flexShrink: 1, minWidth: 0 },
+  tickHeader: { height: HEADER_H, flexDirection: "row" },
+  tick: {
+    position: "absolute",
+    top: 0,
+    bottom: 0,
+    justifyContent: "center",
+    paddingLeft: 4,
+    borderLeftColor: colors.zinc[300],
+  },
+  groupBand: { height: GROUP_H },
+  taskRow: { height: ROW_H },
+  monthRule: { position: "absolute", top: 0, bottom: 0, borderLeftWidth: 1, borderLeftColor: colors.zinc[200] },
+  // The bar carries no label: the frozen column beside it already names the
+  // task, and repeating it inside every bar is the same string twice on one line.
+  barHit: { position: "absolute", top: (ROW_H - BAR_H) / 2, height: BAR_H },
+  bar: { flex: 1, overflow: "hidden" },
+  progress: { position: "absolute", left: 0, top: 0, bottom: 0 },
+  milestoneHit: {
+    position: "absolute",
+    top: (ROW_H - MILESTONE) / 2 - 3,
+    width: MILESTONE + 6,
+    height: MILESTONE + 6,
+    alignItems: "center",
+    justifyContent: "center",
+  },
+  milestone: { width: MILESTONE, height: MILESTONE, transform: [{ rotate: "45deg" }], borderRadius: 4 },
+  todayLine: { position: "absolute", top: 0, bottom: 0, width: 2, backgroundColor: colors.red[500] },
 });

package/src/gantt/index.ts

@@ -1,5 +1,5 @@
 export { GanttView } from "./gantt_view";
 export type { GanttViewProps } from "./gantt_view";
-export { barGeometry, axisRange, buildTicks, pxPerDay } from "./scale";
+export { barGeometry, axisRange, buildTicks, buildRows, pxPerDay } from "./scale";
 export { DEFAULT_GANTT_LABELS } from "./types";
-export type { GanttTask, GanttScale, GanttTick, GanttBar, GanttLabels } from "./types";
+export type { GanttTask, GanttScale, GanttTick, GanttBar, GanttRow, GanttLabels } from "./types";

package/src/gantt/scale.ts

@@ -1,6 +1,6 @@
 import { addDays, dayDiff, startOfDay, startOfMonth, startOfWeek } from "../calendar/dates";
 import type { Weekday } from "../calendar/types";
-import type { GanttBar, GanttScale, GanttTask, GanttTick } from "./types";
+import type { GanttBar, GanttRow, GanttScale, GanttTask, GanttTick } from "./types";
 
 const MIN_BAR_PX = 8;
 
@@ -32,15 +32,51 @@ export function axisRange(tasks: GanttTask[], today: Date = new Date(), padDays
   return { start: addDays(startOfDay(min), -padDays), end: addDays(startOfDay(max), padDays) };
 }
 
-/** Bar geometry: left = days from axis start; width spans the inclusive end. */
+/** Bar geometry: left = days from axis start; width spans the inclusive end.
+ *  A milestone has no span — it is a marker centred on its day. */
 export function barGeometry<T>(task: GanttTask<T>, axisStart: Date, scale: GanttScale): GanttBar<T> {
   const ppd = pxPerDay(scale);
   const left = dayDiff(axisStart, task.start) * ppd;
+  if (task.milestone) return { task, left, width: 0 };
   const endDay = task.end ?? task.start;
   const days = Math.max(1, dayDiff(task.start, endDay) + 1); // inclusive
   return { task, left, width: Math.max(MIN_BAR_PX, days * ppd) };
 }
 
+/**
+ * The chart's lines, in render order: each lane's heading followed by its tasks.
+ *
+ * `group` was declared on `GanttTask` and read by NOTHING — the type documented
+ * lanes, the gallery passed them, and every task rendered in one flat list. This
+ * is what makes the promise real. Ungrouped tasks lead, so a chart that uses no
+ * groups is unchanged; lanes then appear in the order they are first seen,
+ * which keeps the order the caller's own array states rather than sorting
+ * alphabetically behind their back.
+ */
+export function buildRows<T>(tasks: GanttTask<T>[]): GanttRow<T>[] {
+  const ungrouped = tasks.filter((t) => !t.group);
+  const order: string[] = [];
+  const byGroup = new Map<string, GanttTask<T>[]>();
+  for (const t of tasks) {
+    if (!t.group) continue;
+    const existing = byGroup.get(t.group);
+    if (existing) existing.push(t);
+    else {
+      order.push(t.group);
+      byGroup.set(t.group, [t]);
+    }
+  }
+
+  const rows: GanttRow<T>[] = [];
+  let index = 0;
+  for (const task of ungrouped) rows.push({ kind: "task", task, index: index++ });
+  for (const group of order) {
+    rows.push({ kind: "group", group, index: index++ });
+    for (const task of byGroup.get(group) ?? []) rows.push({ kind: "task", task, index: index++ });
+  }
+  return rows;
+}
+
 /**
  * Header ticks across [start, end]. Granularity follows the zoom: a tick per day
  * (day), per week (week), or per month (month). Each tick flags a month start so

package/src/gantt/types.ts

@@ -1,3 +1,5 @@
+import type { ColorName } from "../color_tokens";
+
 /**
  * Gantt / timeline primitive — data model. A task is a labelled bar spanning
  * [start, end] (end inclusive — a one-day task has start === end's day). `data`
@@ -7,11 +9,23 @@ export interface GanttTask<T = unknown> {
   id: string;
   label: string;
   start: Date;
-  /** Inclusive end day. Null/undefined → a single-day (milestone-ish) bar. */
+  /** Inclusive end day. Null/undefined → a single-day bar. */
   end?: Date | null;
-  color?: string | null;
-  /** Optional grouping lane label (e.g. project / assignee). */
+  /**
+   * Design-token colour, matching `CalendarEvent.color`. A TOKEN, not a hex:
+   * the bar derives a fill, a progress overlay and a swatch from it.
+   */
+  color?: ColorName;
+  /**
+   * Lane this task belongs to — a phase, an owner, a vehicle. Tasks sharing a
+   * `group` render under one heading, in the order first seen; tasks without
+   * one lead, ungrouped.
+   */
   group?: string;
+  /** A moment rather than a span — drawn as a diamond, no width. `end` is ignored. */
+  milestone?: boolean;
+  /** 0–1. Draws a solid portion inside the bar; omit for no progress overlay. */
+  progress?: number;
   data?: T;
 }
 
@@ -19,9 +33,9 @@ export interface GanttTask<T = unknown> {
 export type GanttScale = "day" | "week" | "month";
 
 /**
- * User-facing chrome strings. Defaults to English and taken as a prop — i18n is
- * the consumer's responsibility (see the @lotics/ui convention in
- * grid/data_grid.tsx). Axis tick labels come from `locale` via Intl.
+ * User-facing chrome strings. Resolution is **prop → `LoticsLocale.gantt` →
+ * English default**, the kit-wide rule; `labels` overrides one instance.
+ * Axis tick labels come from `locale` via Intl.
  */
 export interface GanttLabels {
   day: string;
@@ -29,9 +43,17 @@ export interface GanttLabels {
   month: string;
   /** Frozen task-column header. */
   task: string;
+  /** Shown when there is nothing to chart. */
+  empty: string;
 }
 
-export const DEFAULT_GANTT_LABELS: GanttLabels = { day: "Day", week: "Week", month: "Month", task: "Task" };
+export const DEFAULT_GANTT_LABELS: GanttLabels = {
+  day: "Day",
+  week: "Week",
+  month: "Month",
+  task: "Task",
+  empty: "Nothing scheduled",
+};
 
 /** A header tick on the time axis. */
 export interface GanttTick {
@@ -49,3 +71,8 @@ export interface GanttBar<T = unknown> {
   left: number;
   width: number;
 }
+
+/** One rendered line of the chart: a lane heading, or a task at a row index. */
+export type GanttRow<T = unknown> =
+  | { kind: "group"; group: string; index: number }
+  | { kind: "task"; task: GanttTask<T>; index: number };