@lotics/ui 47.13.0 → 47.14.0

package/src/timetable.tsx

@@ -0,0 +1,167 @@
+import { type ReactNode } from "react";
+import { View } from "react-native";
+import { colors } from "./colors";
+import { useLoticsLocale } from "./locale";
+import { Table, TableCell, TableRow, type TableColumn } from "./table";
+import { Text } from "./text";
+import { TOGGLE_STRIP_CELL_GAP, TOGGLE_STRIP_CELL_WIDTH, ToggleStrip, toggleStripWidth } from "./toggle_strip";
+
+export interface TimetableLabels {
+  /** Header of the time column. */
+  time: string;
+  /** Header of the column naming what is scheduled — a vehicle, a person, a room. */
+  subject: string;
+  /** Header of the optional state column. */
+  status: string;
+}
+
+/** One FIXED position on the repeating axis — a weekday, an hour band. */
+export interface TimetableSlot<T extends string> {
+  value: T;
+  /** One or two characters, shown ONCE in the header. */
+  label: string;
+  /** What a screen reader says for a cell in this column. */
+  name: string;
+}
+
+export interface TimetableRow<T extends string> {
+  id: string;
+  /** The row's identity on the time axis — "07:30". Text, never an editor:
+   *  the subject of a row is read, and edits in the row's `detail`. */
+  time: string;
+  /** The positions this row is ON. */
+  active: T[];
+  /** What runs in this slot. A node, so an identity mark rides it. */
+  subject: ReactNode;
+  /** A state worth a word — "withdrawn". The column exists only when some row has one. */
+  status?: ReactNode;
+  disabled?: boolean;
+  /** The row's verbs — an `ActionMenu`. Rendered in the trailing gutter. */
+  trailing?: ReactNode;
+  /** Expands under the row: where the time and the subject are EDITED. */
+  detail?: ReactNode;
+  expanded?: boolean;
+  onPress?: () => void;
+  accessibilityLabel?: string;
+}
+
+export interface TimetableProps<T extends string> {
+  slots: TimetableSlot<T>[];
+  /** The position the reader is standing in — today's weekday. Its column is
+   *  tinted down the whole grid and its header carries `aria-current`. */
+  current?: T;
+  rows: TimetableRow<T>[];
+  onToggle: (rowId: string, next: T[]) => void;
+  /** Refuse to turn a row's LAST position off — see `ToggleStrip`. */
+  minOne?: boolean;
+  labels?: Partial<TimetableLabels>;
+}
+
+const TIME_WIDTH = 92;
+const STATUS_WIDTH = 120;
+const TRAILING = 40;
+
+/**
+ * A TIMETABLE: slots down the side, a fixed repeating axis across the top, and
+ * a mark wherever a slot is on — a departure board, a shift roster, a lane's
+ * opening hours.
+ *
+ * It is not `CalendarView`: nothing here has a DATE, so there is no week to
+ * page to and no duration to draw; the whole subject is a pattern across fixed
+ * positions, and a column of rows lets the eye run down position 3 and see the
+ * shape of the week. It is not a plain `Table` of `ToggleStrip`s either — that
+ * was the first draft, and it labelled every cell: seven letters per row, the
+ * same seven on every row, twenty-eight labels for four facts. Here the axis is
+ * named ONCE in the header and the cells are marks under it.
+ *
+ * The row's time and subject are TEXT. A column of always-open editors makes a
+ * list look like a form (composition.md § Master-detail), and a timetable is
+ * read every day and changed a few times a month — so a row's edits live in its
+ * `detail`, opened by pressing the row. The pattern is the one thing edited in
+ * place, because a mark IS its own editor.
+ */
+export function Timetable<T extends string>(props: TimetableProps<T>) {
+  const { slots, current, rows, onToggle, minOne = false, labels } = props;
+  const pack = useLoticsLocale().timetable;
+  const l = { ...pack, ...labels };
+  const coStatus = rows.some((r) => r.status != null);
+  const coTrailing = rows.some((r) => r.trailing != null);
+
+  const columns: TableColumn[] = [
+    { key: "time", label: l.time, width: TIME_WIDTH, priority: 1 },
+    {
+      key: "pattern",
+      header: <SlotHeader slots={slots} current={current} />,
+      width: toggleStripWidth(slots.length),
+      priority: 2,
+    },
+    { key: "subject", label: l.subject, flex: 1, priority: 3 },
+    ...(coStatus ? [{ key: "status", label: l.status, width: STATUS_WIDTH, priority: 4 }] : []),
+  ];
+
+  return (
+    <Table columns={columns} trailing={coTrailing ? TRAILING : 0} align={coTrailing ? "top" : "center"}>
+      {rows.map((r) => {
+        // An ARRAY, never a fragment or a conditional child: `Table` hands each
+        // cell its column by POSITION.
+        const cells = [
+          <TableCell key="time">
+            <Text size="sm" weight="medium" tabular numberOfLines={1}>
+              {r.time}
+            </Text>
+          </TableCell>,
+          <TableCell key="pattern">
+            <ToggleStrip
+              variant="mark"
+              current={current}
+              accessibilityLabel={r.time}
+              options={slots}
+              value={r.active}
+              onValueChange={(next) => onToggle(r.id, next)}
+              minOne={minOne}
+              disabled={r.disabled}
+            />
+          </TableCell>,
+          <TableCell key="subject">{r.subject}</TableCell>,
+        ];
+        if (coStatus) cells.push(<TableCell key="status">{r.status ?? null}</TableCell>);
+        // A door and its name come together, or not at all — `TableRow`'s own contract.
+        const door = r.onPress === undefined ? {} : { onPress: r.onPress, accessibilityLabel: r.accessibilityLabel ?? r.time };
+        return (
+          <TableRow key={r.id} expanded={r.expanded} detail={r.detail} trailing={r.trailing} {...door}>
+            {cells}
+          </TableRow>
+        );
+      })}
+    </Table>
+  );
+}
+
+/** The axis, named once. Cells sit on `ToggleStrip`'s own geometry so the
+ *  labels land over the marks they name. */
+function SlotHeader<T extends string>({ slots, current }: { slots: TimetableSlot<T>[]; current?: T }) {
+  return (
+    <View style={{ flexDirection: "row", gap: TOGGLE_STRIP_CELL_GAP }}>
+      {slots.map((s) => {
+        const now = s.value === current;
+        return (
+          <View
+            key={s.value}
+            aria-current={now ? "date" : undefined}
+            style={{
+              width: TOGGLE_STRIP_CELL_WIDTH,
+              alignItems: "center",
+              paddingVertical: 2,
+              borderRadius: 6,
+              backgroundColor: now ? colors.zinc[100] : undefined,
+            }}
+          >
+            <Text size="sm" weight="medium" color={now ? "default" : "muted"} numberOfLines={1}>
+              {s.label}
+            </Text>
+          </View>
+        );
+      })}
+    </View>
+  );
+}

package/src/toggle_strip.tsx

@@ -0,0 +1,259 @@
+import { Pressable, View, type StyleProp, type ViewStyle } from "react-native";
+import { colors } from "./colors";
+import { Text } from "./text";
+import {
+  CONTROL_CONTENT_HEIGHT,
+  CONTROL_TRANSITION,
+  CURSOR_DEFAULT,
+  FOCUS_RING,
+  ROW_CONTROL_HOVER,
+  ROW_CONTROL_PRESS,
+  chipSurfaceStyle,
+  proportionalRadius,
+} from "./control_surface";
+import { useFocusRing } from "./use_focus_ring";
+
+/** The default cell width — two characters at `xs` with air, which is what a
+ *  weekday initial, an hour band or a channel letter actually needs. */
+const CELL_WIDTH = 30;
+
+/** The gap between cells. Tight on purpose: the cells are ONE object — a week, a
+ *  band, a set — and a chip-row gap would read them as separate controls. */
+const CELL_GAP = 2;
+
+/** The strip's geometry, for a header that names the positions ONCE above a
+ *  column of strips (`Timetable`): its labels must land over the cells. */
+export const TOGGLE_STRIP_CELL_WIDTH = CELL_WIDTH;
+export const TOGGLE_STRIP_CELL_GAP = CELL_GAP;
+
+/** The mark a `mark` cell draws — a filled square when on, a hollow one when off. */
+const MARK = 14;
+
+export interface ToggleStripOption<T extends string> {
+  value: T;
+  /** What the cell SHOWS — one or two characters ("T2", "CN", "08"). */
+  label: string;
+  /** What a screen reader says instead. Required, because a two-letter cell
+   *  announces as nonsense: seven "T2" switches in a table are told apart only
+   *  by voice, and the label is not a name. */
+  name: string;
+}
+
+export interface ToggleStripProps<T extends string> {
+  /** Names the SET — "Ngày chạy của nốt 05:30". Every cell's own name is
+   *  prefixed with it, so a register of these strips is navigable by voice. */
+  accessibilityLabel: string;
+  /** The fixed positions, in reading order. They do not move with the data —
+   *  the whole point is that position N means the same thing on every row. */
+  options: ToggleStripOption<T>[];
+  /** The values that are ON. */
+  value: T[];
+  onValueChange: (next: T[]) => void;
+  /**
+   * Refuse to turn the LAST cell off.
+   *
+   * For a set where empty is not a neutral state but a DIFFERENT reading — a
+   * schedule with no day is not a schedule, and where the empty set already
+   * means "every day" the two readings would silently swap. The held cell wears
+   * the disabled treatment so the floor is visible rather than a press that
+   * does nothing.
+   */
+  minOne?: boolean;
+  disabled?: boolean;
+  /**
+   * `label` (default) prints each option's one or two letters in a chip — the
+   * strip stands alone, in a field or a lone row, and names its own positions.
+   * `mark` draws a bare square instead, for a COLUMN of strips whose positions
+   * a header names once (`Timetable`): the same seven letters on every row were
+   * twenty-eight labels for four facts.
+   */
+  variant?: "label" | "mark";
+  /** The position the reader is standing in — today's weekday. Its cell is
+   *  tinted so a column of strips shows the day as a band. */
+  current?: T;
+  /** Cell width. Raise it for three-character labels; the strip's own width is
+   *  {@link toggleStripWidth}, which a table column budgets against. */
+  cellWidth?: number;
+  style?: StyleProp<ViewStyle>;
+  testID?: string;
+}
+
+/**
+ * A COMPACT MULTI-TOGGLE — N fixed cells, each independently on or off, sized
+ * to sit inside a register row rather than on a control band.
+ *
+ * The subject is a PATTERN across fixed positions: which days a departure runs,
+ * which hours a gate is open, which channels a notice goes out on. What makes it
+ * its own component rather than a `ChipGroup` is that the positions are fixed and
+ * the reading is VERTICAL — a column of these strips has to let the eye run down
+ * position 3 and see the shape of the week. Chips wrap and re-flow, which is
+ * right for a filter band and destroys exactly that.
+ *
+ * It is also not `SegmentedControl`: that is one choice among peers (a
+ * radiogroup); this is N independent booleans, so each cell is a `checkbox`.
+ *
+ * **The selected treatment is `chipSurfaceStyle`'s**, not a ground of its own.
+ * A filled brand ground was the obvious answer and is the wrong one twice over:
+ * a ground is the ROW's language and these are controls, so the two altitudes
+ * end up saying the same thing in the same paint; and it spends the brand on a
+ * selection, which then has to be walked back everywhere at once. Seven ON cells
+ * per row also made the primary button on the same screen the twenty-third copy
+ * of its own ground. The doubled zinc-900 edge is the kit's one answer to "which
+ * one is on", and it survives the hover wash instead of being replaced by it.
+ *
+ * Height is {@link CONTROL_CONTENT_HEIGHT}, not `CONTROL_HEIGHT`: this rides
+ * inside a row or a field, where 40 is the box and 28 is what the box may seat.
+ */
+export function ToggleStrip<T extends string>(props: ToggleStripProps<T>) {
+  const {
+    accessibilityLabel,
+    options,
+    value,
+    onValueChange,
+    minOne = false,
+    disabled = false,
+    variant = "label",
+    current,
+    cellWidth = CELL_WIDTH,
+    style,
+    testID,
+  } = props;
+  const on = new Set(value);
+
+  return (
+    <View
+      testID={testID}
+      role="group"
+      aria-label={accessibilityLabel}
+      style={[{ flexDirection: "row", gap: CELL_GAP }, style]}
+    >
+      {options.map((o) => {
+        const bat = on.has(o.value);
+        const khoa = disabled || (minOne && bat && on.size === 1);
+        return (
+          <ToggleCell
+            key={o.value}
+            label={o.label}
+            name={`${accessibilityLabel} — ${o.name}`}
+            on={bat}
+            disabled={khoa}
+            width={cellWidth}
+            variant={variant}
+            current={o.value === current}
+            // The result keeps the OPTIONS' order, never press order: the set is
+            // a pattern across fixed positions, and a caller comparing it against
+            // a stored one must not see a diff because two days were toggled in
+            // the other sequence.
+            onPress={() =>
+              onValueChange(
+                options.filter((x) => (x.value === o.value ? !bat : on.has(x.value))).map((x) => x.value),
+              )
+            }
+          />
+        );
+      })}
+    </View>
+  );
+}
+
+/** The width the strip occupies, so a table column can be budgeted for it
+ *  EXACTLY. A column guessed at is a column the fit sheds for the wrong reason. */
+export function toggleStripWidth(count: number, cellWidth: number = CELL_WIDTH): number {
+  return count * cellWidth + Math.max(0, count - 1) * CELL_GAP;
+}
+
+function ToggleCell(props: {
+  label: string;
+  name: string;
+  on: boolean;
+  disabled: boolean;
+  width: number;
+  variant: "label" | "mark";
+  current: boolean;
+  onPress: () => void;
+}) {
+  const { label, name, on, disabled, width, variant, current, onPress } = props;
+  const { focusVisible, focusProps } = useFocusRing();
+  if (variant === "mark") {
+    return (
+      <Pressable
+        {...focusProps}
+        disabled={disabled}
+        onPress={onPress}
+        role="checkbox"
+        aria-label={name}
+        aria-checked={on}
+        aria-disabled={disabled || undefined}
+        style={(state) => [
+          {
+            height: CONTROL_CONTENT_HEIGHT,
+            width,
+            borderRadius: proportionalRadius(CONTROL_CONTENT_HEIGHT),
+            alignItems: "center",
+            justifyContent: "center",
+            cursor: CURSOR_DEFAULT,
+            opacity: disabled ? 0.55 : 1,
+            // The cell has no chrome of its own — the MARK is the state. Today's
+            // column rests on a tint, and the pointer deepens whatever the cell
+            // rests on, so the wash never vanishes on the tinted column.
+            backgroundColor: state.pressed
+              ? ROW_CONTROL_PRESS
+              : state.hovered
+                ? ROW_CONTROL_HOVER
+                : current
+                  ? colors.zinc[100]
+                  : "transparent",
+            ...CONTROL_TRANSITION,
+          },
+          focusVisible ? { boxShadow: FOCUS_RING } : null,
+        ]}
+      >
+        <View
+          style={{
+            width: MARK,
+            height: MARK,
+            borderRadius: 4,
+            backgroundColor: on ? colors.zinc[900] : "transparent",
+            borderWidth: on ? 0 : 1.5,
+            borderColor: colors.zinc[300],
+          }}
+        />
+      </Pressable>
+    );
+  }
+  return (
+    <Pressable
+      {...focusProps}
+      disabled={disabled}
+      onPress={onPress}
+      role="checkbox"
+      aria-label={name}
+      aria-checked={on}
+      aria-disabled={disabled || undefined}
+      style={(state) => [
+        chipSurfaceStyle(state, { selected: on }),
+        {
+          // The chip surface is a BAND control at 40; inside a row it seats at
+          // the content rung, and its corner scales with the height so a strip
+          // and a chip read as one family rather than two radii.
+          height: CONTROL_CONTENT_HEIGHT,
+          borderRadius: proportionalRadius(CONTROL_CONTENT_HEIGHT),
+          width,
+          alignItems: "center",
+          justifyContent: "center",
+          // Setting a VALUE is not acting on its own — see CURSOR_DEFAULT.
+          // react-native-web's Pressable ships `cursor: pointer` in its base
+          // style, so this has to be asked for.
+          cursor: CURSOR_DEFAULT,
+          opacity: disabled ? 0.55 : 1,
+          ...CONTROL_TRANSITION,
+        },
+        focusVisible ? { boxShadow: FOCUS_RING } : null,
+      ]}
+    >
+      <Text size="xs" weight="medium" color={on ? "default" : "muted"}>
+        {label}
+      </Text>
+    </Pressable>
+  );
+}