pixelize-native-library 1.0.7 → 1.2.1

package/lib/module/modules/gantt/Gantt.js

@@ -0,0 +1,239 @@
+"use strict";
+
+/**
+ * Gantt — lightweight horizontal timeline chart (ported from tickets/mobile EpicTimeline).
+ *
+ * The lane-label column is hidden from assistive tech: it is a second, parallel column of the same
+ * names the bars already carry inside their composed labels ("<sublabel> <label>, <range>, <n>%
+ * complete"), and nothing associates a name in one column with a bar in the other (WCAG 1.3.1). One
+ * accessible node per lane, holding the whole relationship, is what a screen reader can act on.
+ */
+
+import { memo, useCallback, useMemo, useState } from "react";
+import { Platform, Pressable, ScrollView, StyleSheet, Text, useWindowDimensions, View } from "react-native";
+import { useDeviceTier } from "../../core/device/index.js";
+import { useTheme } from "../../theme/hooks.js";
+import { rippleColor } from "../../theme/platform/stateLayer.native.js";
+import { Button } from "../button/Button.js";
+import { computeGanttModel, resolveGanttColors, resolveVisibleGanttLanes, GANTT_BAR_H, GANTT_BAR_HIT_SLOP, GANTT_LABEL_W, GANTT_ROW_H, MAX_RENDERED_LANES } from "./Gantt.variants.js";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+const BAR_TOP = (GANTT_ROW_H - GANTT_BAR_H) / 2;
+const BAR_RADIUS = 5;
+const GanttLaneLabel = /*#__PURE__*/memo(function GanttLaneLabel({
+  label,
+  sublabel,
+  labelStyle,
+  sublabelStyle
+}) {
+  return /*#__PURE__*/_jsxs(View, {
+    style: styles.labelCell,
+    children: [sublabel ? /*#__PURE__*/_jsx(Text, {
+      numberOfLines: 1,
+      style: sublabelStyle,
+      children: sublabel
+    }) : null, /*#__PURE__*/_jsx(Text, {
+      numberOfLines: 1,
+      style: labelStyle,
+      children: label
+    })]
+  });
+});
+const GanttLaneBar = /*#__PURE__*/memo(function GanttLaneBar({
+  id,
+  leftPx,
+  widthPx,
+  fillPx,
+  isMarker,
+  complete,
+  ariaLabel,
+  colors,
+  mode,
+  onPress
+}) {
+  const handlePress = useCallback(() => onPress?.(id), [onPress, id]);
+  const androidRipple = useMemo(() => Platform.OS === "android" ? {
+    color: rippleColor(mode),
+    borderless: false
+  } : undefined, [mode]);
+  const barColor = complete ? colors.barComplete : colors.bar;
+  const barStyle = useMemo(() => ({
+    position: "absolute",
+    left: leftPx,
+    width: widthPx,
+    top: BAR_TOP,
+    height: GANTT_BAR_H,
+    borderRadius: BAR_RADIUS,
+    borderWidth: StyleSheet.hairlineWidth,
+    borderColor: colors.border,
+    backgroundColor: isMarker ? barColor : colors.track,
+    overflow: "hidden"
+  }), [leftPx, widthPx, isMarker, barColor, colors.border, colors.track]);
+  const fillStyle = useMemo(() => ({
+    width: fillPx,
+    height: "100%",
+    backgroundColor: barColor,
+    borderRadius: BAR_RADIUS
+  }), [fillPx, barColor]);
+  return /*#__PURE__*/_jsx(View, {
+    style: styles.barRow,
+    children: /*#__PURE__*/_jsx(Pressable, {
+      accessibilityRole: "button",
+      accessibilityLabel: ariaLabel,
+      onPress: onPress === undefined ? undefined : handlePress,
+      hitSlop: GANTT_BAR_HIT_SLOP,
+      android_ripple: androidRipple,
+      style: barStyle,
+      children: !isMarker ? /*#__PURE__*/_jsx(View, {
+        pointerEvents: "none",
+        style: fillStyle
+      }) : null
+    })
+  });
+});
+export const Gantt = /*#__PURE__*/memo(function Gantt({
+  lanes,
+  onLanePress,
+  style,
+  testID
+}) {
+  const theme = useTheme();
+  const {
+    width: winW
+  } = useWindowDimensions();
+  const [now] = useState(() => Date.now());
+  const tier = useDeviceTier();
+  const [expanded, setExpanded] = useState(false);
+  const model = useMemo(() => computeGanttModel(lanes, winW, now), [lanes, winW, now]);
+  const colors = useMemo(() => resolveGanttColors(theme.colors), [theme.colors]);
+  const maxLanes = MAX_RENDERED_LANES[tier];
+  const visible = useMemo(() => resolveVisibleGanttLanes(model, maxLanes, expanded), [model, maxLanes, expanded]);
+  const handleShowAll = useCallback(() => setExpanded(true), []);
+  const rootStyle = useMemo(() => [{
+    gap: theme.space[2]
+  }, style], [theme, style]);
+  const titleStyle = useMemo(() => [theme.fontStyleForWeight(theme.fontWeights.bold), {
+    fontSize: theme.fontSizes.md,
+    color: colors.label
+  }], [theme, colors]);
+  const captionStyle = useMemo(() => [theme.fontStyleForWeight(theme.fontWeights.regular), {
+    fontSize: theme.fontSizes.xs,
+    color: colors.caption
+  }], [theme, colors]);
+  const labelStyle = useMemo(() => [theme.fontStyleForWeight(theme.fontWeights.medium), {
+    fontSize: theme.fontSizes.sm,
+    color: colors.label
+  }], [theme, colors]);
+  const sublabelStyle = useMemo(() => [theme.fontStyleForWeight(theme.fontWeights.semibold), {
+    fontSize: 11,
+    color: colors.sublabel
+  }], [theme, colors]);
+  const emptyStyle = useMemo(() => [theme.fontStyleForWeight(theme.fontWeights.regular), {
+    fontSize: theme.fontSizes.sm,
+    color: colors.sublabel
+  }], [theme, colors]);
+  const chartBodyStyle = useMemo(() => ({
+    width: model.chartWidth,
+    height: visible.bodyHeight
+  }), [model.chartWidth, visible.bodyHeight]);
+  const todayStyle = useMemo(() => ({
+    left: model.todayX,
+    height: visible.bodyHeight,
+    backgroundColor: colors.today
+  }), [model.todayX, visible.bodyHeight, colors.today]);
+  if (model.empty) {
+    return /*#__PURE__*/_jsx(View, {
+      testID: testID,
+      style: style,
+      children: /*#__PURE__*/_jsx(Text, {
+        style: emptyStyle,
+        children: "No dated items to chart."
+      })
+    });
+  }
+  return /*#__PURE__*/_jsxs(View, {
+    testID: testID,
+    style: rootStyle,
+    children: [/*#__PURE__*/_jsxs(View, {
+      style: styles.header,
+      children: [/*#__PURE__*/_jsx(Text, {
+        accessibilityRole: "header",
+        style: titleStyle,
+        children: "Timeline"
+      }), /*#__PURE__*/_jsx(Text, {
+        style: captionStyle,
+        children: model.rangeLabel
+      })]
+    }), /*#__PURE__*/_jsxs(View, {
+      style: styles.body,
+      children: [/*#__PURE__*/_jsx(View, {
+        "aria-hidden": true,
+        style: styles.labelColumn,
+        children: visible.lanes.map(lane => /*#__PURE__*/_jsx(GanttLaneLabel, {
+          label: lane.label,
+          sublabel: lane.sublabel,
+          labelStyle: labelStyle,
+          sublabelStyle: sublabelStyle
+        }, lane.id))
+      }), /*#__PURE__*/_jsx(ScrollView, {
+        horizontal: true,
+        showsHorizontalScrollIndicator: true,
+        style: styles.chart,
+        children: /*#__PURE__*/_jsxs(View, {
+          style: chartBodyStyle,
+          children: [visible.lanes.map(lane => /*#__PURE__*/_jsx(GanttLaneBar, {
+            id: lane.id,
+            leftPx: lane.leftPx,
+            widthPx: lane.widthPx,
+            fillPx: lane.fillPx,
+            isMarker: lane.isMarker,
+            complete: lane.complete,
+            ariaLabel: lane.ariaLabel,
+            colors: colors,
+            mode: theme.mode,
+            onPress: onLanePress
+          }, lane.id)), model.showToday ? /*#__PURE__*/_jsx(View, {
+            pointerEvents: "none",
+            style: [styles.todayLine, todayStyle]
+          }) : null]
+        })
+      })]
+    }), visible.hiddenCount > 0 ? /*#__PURE__*/_jsx(Button, {
+      variant: "link",
+      size: "sm",
+      label: `Show all ${visible.totalCount} lanes`,
+      onPress: handleShowAll,
+      testID: testID ? `${testID}-show-all` : undefined
+    }) : null]
+  });
+});
+const styles = StyleSheet.create({
+  header: {
+    flexDirection: "row",
+    justifyContent: "space-between"
+  },
+  body: {
+    flexDirection: "row"
+  },
+  labelColumn: {
+    width: GANTT_LABEL_W
+  },
+  labelCell: {
+    height: GANTT_ROW_H,
+    justifyContent: "center",
+    paddingRight: 8
+  },
+  chart: {
+    flex: 1
+  },
+  barRow: {
+    height: GANTT_ROW_H,
+    justifyContent: "center"
+  },
+  todayLine: {
+    position: "absolute",
+    top: 0,
+    width: 2,
+    opacity: 0.7
+  }
+});
+//# sourceMappingURL=Gantt.js.map

package/lib/module/modules/gantt/Gantt.variants.js

@@ -0,0 +1,177 @@
+"use strict";
+
+/**
+ * Gantt layout math — ported from tickets/mobile EpicTimeline. Pure, testable.
+ */
+
+export const MS_PER_DAY = 86_400_000;
+export const GANTT_LABEL_W = 108;
+export const GANTT_ROW_H = 46;
+export const GANTT_BAR_H = 18;
+export const GANTT_MIN_BAR_W = 14;
+export const GANTT_MARKER_W = 12;
+export const GANTT_BASE_PX_PER_DAY = 4;
+export const GANTT_MIN_SPAN_MS = 14 * MS_PER_DAY;
+export const GANTT_PAD_MS = 2 * MS_PER_DAY;
+
+/** WCAG 2.5.5 target size, the library-wide floor (`Tabs`/`Pagination`/`Reorder` all pin the same 44). */
+export const MIN_TOUCH_TARGET = 44;
+
+/**
+ * Lanes rendered before the "show all" affordance takes over — the same worst-case safety valve as
+ * `MAX_RENDERED_POINTS` in `Charts.variants.ts`, tier-scaled because a lane count this large comes
+ * from real ticket/epic data (this component's own documented origin), not a series a caller could
+ * decimate without losing rows a reader actually needs.
+ */
+export const MAX_RENDERED_LANES = {
+  low: 40,
+  mid: 80,
+  high: 150
+};
+const slopFor = dimension => Math.max(0, Math.ceil((MIN_TOUCH_TARGET - dimension) / 2));
+
+/**
+ * A bar is a *data mark* — its 18dp height encodes nothing but the chart's row rhythm, and its width
+ * encodes the lane's duration, so neither can be grown to 44dp without lying about the data. When
+ * `onLanePress` is given the bar IS the press target, so the target is widened with `hitSlop`
+ * instead — the `Reorder`/`CopyButton` idiom for a mark whose drawn size is fixed by its meaning.
+ * Sized off the NARROWEST bar the layout can produce (`GANTT_MARKER_W`, a same-day lane) so every
+ * bar clears the floor, not just the wide ones. Vertical slop stays inside `GANTT_ROW_H`, so
+ * neighbouring rows' targets never overlap.
+ */
+export const GANTT_BAR_HIT_SLOP = {
+  top: slopFor(GANTT_BAR_H),
+  bottom: slopFor(GANTT_BAR_H),
+  left: slopFor(GANTT_MARKER_W),
+  right: slopFor(GANTT_MARKER_W)
+};
+/**
+ * Bar/track/label roles. Two bindings are deliberate and measured, not the obvious pick:
+ *
+ *  - `barComplete` is the success ramp's `text` rung, NOT `solid` — the same choice (and the same
+ *    reason) `ProgressBar.variants.ts` documents: `success.solid` is a pale semantic green that
+ *    measures 2.19:1 against the `accent.subtle` track and 2.38:1 against the canvas in light mode,
+ *    failing WCAG 1.4.11 for the progress fill it draws. The `text` rung clears both (≥5.40 / ≥6.56).
+ *  - `caption` is `fg.muted`, NOT `fg.subtle` — the range label renders at `fontSize.xs`, and
+ *    `fg.subtle` (a flat `gray[500]`) falls to 3.19:1 on emerald light. Same defect as `Text`'s
+ *    `overline` and `Timeline`'s timestamp.
+ */
+export function resolveGanttColors(colors) {
+  return {
+    bar: colors.accent.solid,
+    barComplete: colors.status.success.text,
+    track: colors.accent.subtle,
+    border: colors.border.default,
+    today: colors.status.danger.solid,
+    label: colors.fg.default,
+    sublabel: colors.fg.muted,
+    caption: colors.fg.muted
+  };
+}
+const MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
+function monthYear(ms) {
+  const d = new Date(ms);
+  return `${MONTHS[d.getMonth()]} ${d.getFullYear()}`;
+}
+function shortDate(ms) {
+  const d = new Date(ms);
+  return `${MONTHS[d.getMonth()]} ${d.getDate()}, ${d.getFullYear()}`;
+}
+export function computeGanttModel(lanes, windowWidth, nowMs) {
+  const placed = [];
+  for (const lane of lanes) {
+    const s = lane.startMs;
+    const e = lane.endMs ?? lane.startMs;
+    const start = Math.min(s, e);
+    let end = Math.max(s, e);
+    const isMarker = end - start < MS_PER_DAY;
+    if (isMarker) end = start;
+    const pct = Math.max(0, Math.min(100, lane.progress ?? 0));
+    const complete = pct >= 100;
+    placed.push({
+      lane,
+      start,
+      end,
+      isMarker,
+      pct,
+      complete
+    });
+  }
+  if (placed.length === 0) {
+    return {
+      empty: true,
+      lanes: [],
+      chartWidth: 0,
+      bodyHeight: 0,
+      showToday: false,
+      todayX: 0,
+      rangeLabel: ""
+    };
+  }
+  let domainStart = placed.reduce((m, p) => Math.min(m, p.start), Number.POSITIVE_INFINITY);
+  let domainEnd = placed.reduce((m, p) => Math.max(m, p.end), Number.NEGATIVE_INFINITY);
+  domainStart -= GANTT_PAD_MS;
+  domainEnd += GANTT_PAD_MS;
+  if (domainEnd - domainStart < GANTT_MIN_SPAN_MS) {
+    const mid = (domainStart + domainEnd) / 2;
+    domainStart = mid - GANTT_MIN_SPAN_MS / 2;
+    domainEnd = mid + GANTT_MIN_SPAN_MS / 2;
+  }
+  const spanDays = (domainEnd - domainStart) / MS_PER_DAY;
+  const viewport = Math.max(220, windowWidth - 24 - GANTT_LABEL_W);
+  const chartWidth = Math.max(viewport, Math.ceil(spanDays * GANTT_BASE_PX_PER_DAY));
+  const pxPerDay = chartWidth / spanDays;
+  const xOf = ms => (ms - domainStart) / MS_PER_DAY * pxPerDay;
+  const layouts = placed.map(p => {
+    const leftPx = xOf(p.start);
+    const widthPx = p.isMarker ? GANTT_MARKER_W : Math.max(GANTT_MIN_BAR_W, xOf(p.end) - leftPx);
+    const fillPx = p.isMarker ? 0 : widthPx * p.pct / 100;
+    const rangeText = p.isMarker ? shortDate(p.start) : `${shortDate(p.start)} to ${shortDate(p.end)}`;
+    const ariaLabel = `${p.lane.sublabel ? `${p.lane.sublabel} ` : ""}${p.lane.label}, ${rangeText}, ${p.pct}% complete`;
+    return {
+      id: p.lane.id,
+      label: p.lane.label,
+      sublabel: p.lane.sublabel,
+      leftPx,
+      widthPx,
+      fillPx,
+      isMarker: p.isMarker,
+      complete: p.complete,
+      ariaLabel
+    };
+  });
+  return {
+    empty: false,
+    lanes: layouts,
+    chartWidth,
+    bodyHeight: GANTT_ROW_H * layouts.length,
+    showToday: nowMs >= domainStart && nowMs <= domainEnd,
+    todayX: xOf(nowMs),
+    rangeLabel: `${monthYear(domainStart)} – ${monthYear(domainEnd)}`
+  };
+}
+/**
+ * Slices the already-laid-out lanes to `maxLanes` unless `expanded`. Safe to slice AFTER
+ * `computeGanttModel`: each lane's `leftPx`/`widthPx` is derived from the shared time domain, not
+ * from its position in the array, so dropping trailing lanes never shifts the ones kept. `bodyHeight`
+ * is recomputed for the slice so the chart body and the "today" line never overshoot the rendered rows.
+ */
+export function resolveVisibleGanttLanes(model, maxLanes, expanded) {
+  const total = model.lanes.length;
+  if (expanded || total <= maxLanes) {
+    return {
+      lanes: model.lanes,
+      bodyHeight: model.bodyHeight,
+      totalCount: total,
+      hiddenCount: 0
+    };
+  }
+  const lanes = model.lanes.slice(0, maxLanes);
+  return {
+    lanes,
+    bodyHeight: GANTT_ROW_H * lanes.length,
+    totalCount: total,
+    hiddenCount: total - lanes.length
+  };
+}
+//# sourceMappingURL=Gantt.variants.js.map

package/lib/module/modules/gantt/MODULE.md

@@ -0,0 +1,81 @@
+# gantt/
+
+Horizontal Gantt chart — ported from tickets/mobile `EpicTimeline`. Pure layout in `Gantt.variants.ts`.
+
+## Files
+
+| File | Role |
+|------|------|
+| `Gantt.variants.ts` | `computeGanttModel(lanes, windowWidth, nowMs)` → bar offsets/widths/fills, chart width, today X, range label. Plus `resolveGanttColors(RoleColors)`. Plain, hook-free, testable. |
+| `Gantt.tsx` | Renders a pinned label column beside a horizontally scrolling bar area. |
+
+## Props
+
+`lanes` (`GanttLaneInput[]`: id, label, sublabel, startMs, endMs, progress) · `onLanePress(id)` ·
+`style` (layout-only, outermost, once, last) · `testID`. A lane shorter than a day renders as a marker.
+
+## Colour & accessibility
+
+Every pair below is MEASURED in `__tests__/Gantt.test.ts` across all 9 brands × both modes — the minimum
+observed ratio is in brackets.
+
+| Pair | Floor | Min |
+|------|-------|-----|
+| `label` / `sublabel` / `caption` on `bg.canvas` | 4.5 (1.4.3) | 6.10 / 6.52 / 6.52 |
+| `bar` (`accent.solid`) on `track` — the in-progress fill inside its own trough | 3 (1.4.11) | 3.06 |
+| `barComplete` (`success.text`) on `track` | 3 | 5.40 |
+| `bar` / `barComplete` on `bg.canvas` — a marker lane paints the bar colour with no track behind it | 3 | 3.24 / 6.56 |
+
+- **`barComplete` is the success `text` rung, not `solid`.** `success.solid` is a pale semantic green
+  measuring 2.19:1 against the track and 2.38:1 on the canvas — the same WCAG 1.4.11 defect
+  `ProgressBar.variants.ts` documents for this ramp. `text` is `readableOn()`-derived and clears both.
+- **`caption` is `fg.muted`, not `fg.subtle`.** The range label renders at `fontSize.xs`, so no
+  large-text exemption applies; `fg.subtle` is a flat `gray[500]` tuned to the 3:1 non-text tier and
+  falls to 3.19:1 on emerald light.
+- **`border` and `today` carry no ratio assertion, by design.** The bar's hairline is decorative
+  (1.08–1.43:1) and is pinned to `border.default` with a guard against escalation to
+  `border.interactive`/`border.focus`. The today rule draws at `opacity: 0.7`, so its composited
+  on-screen ratio (2.47–3.13:1) is below the raw token pair — it is `pointerEvents="none"`, unlabelled,
+  and redundant with the dated bars, the decorative carve-out `Timeline` documents.
+
+**Touch targets.** A bar is a data mark: its 18dp height is the row rhythm and its width is the lane's
+duration, so growing it to 44dp would lie about the data. `GANTT_BAR_HIT_SLOP` widens the press target
+instead — sized off the narrowest bar the layout can produce (`GANTT_MARKER_W`, 12dp), so every bar
+clears `MIN_TOUCH_TARGET`. Vertical slop is capped so `GANTT_BAR_H + 2×top ≤ GANTT_ROW_H` and adjacent
+rows' targets never overlap. On Android the bar's `Pressable` also carries `android_ripple`
+(`rippleColor(theme.mode)`, `borderless: false`) — `GanttLaneBar` takes a `mode: ColorScheme` prop
+from `Gantt` to resolve it. This is unrelated to the bar's decorative hairline (see above), which is
+untouched.
+
+**1.3.1 — the pinned label column is decorative.** It used to be a second, un-hidden column of
+`Text` nodes reading the same names the bars already carry inside their own composed
+`ariaLabel` ("`<sublabel> <label>, <range>, <n>% complete`"). Nothing associated a name in that
+column with a bar in the other, so a screen reader read every lane name, then every bar label, with
+no relationship between them. The label column now carries `aria-hidden`; the bar's own `Pressable`
+is the single accessible node per lane, and the "Timeline" chart title is
+`accessibilityRole="header"`.
+
+## Performance
+
+- **All geometry is computed once** in `computeGanttModel`, `useMemo`'d on `(lanes, windowWidth, now)` at
+  the component boundary — the resolver itself stays plain and hook-free (CLAUDE.md).
+- Colors resolve through `resolveGanttColors`, `useMemo`'d on `theme.colors`; every text style
+  (`title`, `caption`, `label`, `sublabel`, `empty`) and the chart-body / today-line view styles are
+  `useMemo`'d, so no style object is reallocated per render.
+- Rows are `React.memo`'d components — `GanttLaneLabel` and `GanttLaneBar` — and `GanttLaneBar` takes the
+  lane **id** as an argument to a `useCallback`'d press handler rather than a per-row closure. Static
+  layout lives in a module-level `StyleSheet`.
+
+**Not virtualized, deliberately.** The label column and the bar column are two parallel `.map()`s in
+different parents (one pinned, one inside the horizontal `ScrollView`); virtualizing them independently
+desyncs their vertical alignment, and the full-height "today" rule is absolutely positioned against
+`bodyHeight`. The chart also has no bounded height of its own — it renders inside a consumer `ScrollView`,
+where a nested `VirtualizedList` warns and windows nothing. Rows are cheap (one `Pressable` + one fill
+`View`) and memo'd instead.
+
+**`MAX_RENDERED_LANES` — a safety cap, not virtualization.** A `useDeviceTier()`-scaled cap (40/80/150
+lanes, low/mid/high — same worst-case valve as `Charts.variants.ts`'s `MAX_RENDERED_POINTS`) slices the
+already-laid-out lanes identically in both `.map()`s via `resolveVisibleGanttLanes`, so the two columns
+stay in sync; past the cap a "Show all N lanes" `Button` reveals the rest on press. This bounds the
+unbounded worst case (a large ticket/epic timeline on a low-end device) without windowing the common
+case, so it doesn't reintroduce the desync problem above.

package/lib/module/modules/gantt/index.js

@@ -0,0 +1,5 @@
+"use strict";
+
+export { Gantt } from "./Gantt.js";
+export { computeGanttModel } from "./Gantt.variants.js";
+//# sourceMappingURL=index.js.map