@lotics/ui 46.2.0 → 46.8.0

package/src/board.tsx

@@ -0,0 +1,611 @@
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  type ReactNode,
+} from "react";
+import { Platform, ScrollView, StyleSheet, View } from "react-native";
+import { colors, tint } from "./colors";
+import { CONTROL_RADIUS, MIN_CONTROL_WIDTH } from "./control_surface";
+import { EmptyState } from "./empty_state";
+import { Icon } from "./icon";
+import { IconButton } from "./icon_button";
+import { useLoticsLocale } from "./locale";
+import { MenuButton } from "./menu_button";
+import { Popover, PopoverContent, PopoverTrigger } from "./popover";
+import { PressableRow } from "./pressable_row";
+import { PressDoor } from "./press_door";
+import { SPACE } from "./spacing";
+import { Text } from "./text";
+import { usePointerDrag } from "./use_pointer_drag";
+
+/**
+ * THE COLUMN WIDTH, owned by the kit.
+ *
+ * A board's columns are all the same width — they hold the same kind of card, and
+ * a column that sized to its content would make "which pile is this" a question of
+ * width rather than of heading. So the number belongs to ONE place: every app that
+ * picked its own landed on a hand-typed 280 inside a `View`, which is the defect
+ * this component exists to remove.
+ *
+ * 280 is `MIN_CONTROL_WIDTH` (160) plus room for a title that wraps twice and a
+ * footer row of a member chip beside a date — the narrowest a card stays READABLE.
+ * It also leaves the next column visibly peeking at 375, which is the only thing
+ * telling a phone reader the board continues sideways.
+ */
+/** A card is a container, so it sits on the container rung of the radius ladder
+ *  — the same 16 a `Card` takes. Kept here rather than imported so the two
+ *  cannot drift apart silently; if the ladder moves, both move. */
+const CARD_RADIUS = 16;
+
+/** Half the difference between an `sm` IconButton's box (24) and its glyph (14).
+ *  It exists so a control cluster can be pulled out by exactly the amount that
+ *  puts its INK on the same edge as the text above it. */
+const CONTROL_INK_INSET = 5;
+
+export const BOARD_COLUMN_WIDTH = 280;
+
+/** One place a card may be sent — a value of the field the board's columns are. */
+export interface BoardMove {
+  /** The destination column's `columnKey`. */
+  key: string;
+  /** What the destination is CALLED, in the reader's language. This is the whole
+   *  point of the control: a move names where the card lands. */
+  label: string;
+  disabled?: boolean;
+}
+
+interface BoardCardEntry {
+  moves: BoardMove[];
+  onMove: (columnKey: string) => void;
+}
+
+interface BoardCtx {
+  /** A column publishes its DOM box so a pointer drop can be hit-tested against it. */
+  registerColumn: (key: string, node: unknown) => void;
+  /** …and its heading, so a card's move MENU can name each destination in the
+   *  destination's own vocabulary — the same node the pile is titled with,
+   *  rather than a lookalike a caller has to keep in step. */
+  columnHeadings: Record<string, ReactNode>;
+  publishHeading: (key: string, heading: ReactNode) => void;
+  /** A card publishes where it may LEGALLY go, so the pointer path and the keyboard
+   *  path resolve the same destinations and can never disagree. */
+  registerCard: (id: string, entry: BoardCardEntry | null) => void;
+  bindDrag: (id: string) => (node: unknown) => void;
+  draggingId: string | null;
+  dragDelta: { dx: number; dy: number } | null;
+  overColumn: string | null;
+  /** True for the tick after a drop, so the click that ends the drag does not
+   *  also open the record. */
+  justDragged: { current: boolean };
+}
+
+const BoardContext = createContext<BoardCtx | null>(null);
+
+/** A column hands its own heading down so a card's move control can WEAR it.
+ *  Passing the node rather than asking the caller to repeat it is what makes the
+ *  two identical by construction instead of by discipline. */
+const BoardColumnContext = createContext<ReactNode>(null);
+
+export interface BoardProps {
+  /** `BoardColumn`s, in the order the field's values are read. */
+  children: ReactNode;
+}
+
+/**
+ * THE COLUMN BOARD — records as cards, columns as the values of ONE field, and the
+ * act the shape exists for: MOVING a card from one column to another.
+ *
+ * Reach for it when the reader's job is to advance work between named places and the
+ * pile sizes are themselves the report. When the reader's job is to compare a row's
+ * measures, that is `DataGrid`; when it is to browse thousands, `Table`. Grouped rows
+ * answer "what is in each pile" and stop there — a board answers it AND hands over the
+ * move, which is why a view labelled Kanban over bands of rows is the wrong form
+ * rather than a smaller version of the right one.
+ *
+ * **The move is keyboard-first.** Every card carries a menu naming its destinations
+ * (`moves`), so the act is reachable by Tab and operable by a screen reader. Pointer
+ * drag is layered on top of that same list — the grip drags, the drop hit-tests the
+ * column under the pointer, and the drop is refused unless the destination is one the
+ * card already declared. On native, where there are no pointer events, the menu is
+ * simply the only path and nothing is lost.
+ *
+ * **The board owns its horizontal scroll.** Columns overflow sideways INSIDE the
+ * board; the page body never scrolls horizontally, which is what makes the shape
+ * usable at 375 rather than a desktop-only pattern.
+ *
+ * **Columns grow; the page scrolls.** A board with independently scrolling columns
+ * needs a bounded height, and a height nobody can derive gets hand-picked — that is
+ * how `height: 560` ends up in an app. So a column is as tall as its cards and the
+ * page's own scroller carries the overflow.
+ *
+ * ```tsx
+ * <Board>
+ *   {stages.map((s) => (
+ *     <BoardColumn key={s.key} heading={<OptionBadge variant="dot" value={s} />} count={s.items.length}>
+ *       {s.items.map((t) => (
+ *         <BoardCard
+ *           key={t.id} id={t.id} title={t.title}
+ *           onPress={() => open(t.id)}
+ *           openLabel={`Mở ${t.title}`} moveLabel={`Chuyển ${t.title}`}
+ *           moves={destinations(s.key)} onMove={(to) => setStage(t.id, to)}
+ *         />
+ *       ))}
+ *     </BoardColumn>
+ *   ))}
+ * </Board>
+ * ```
+ */
+export function Board(props: BoardProps) {
+  const { children } = props;
+
+  const columns = useRef(new Map<string, HTMLElement>());
+  const cards = useRef(new Map<string, BoardCardEntry>());
+  const [overColumn, setOverColumn] = useState<string | null>(null);
+
+  const [columnHeadings, setColumnHeadings] = useState<Record<string, ReactNode>>({});
+  const publishHeading = useCallback((key: string, heading: ReactNode) => {
+    setColumnHeadings((prev) => (prev[key] === heading ? prev : { ...prev, [key]: heading }));
+  }, []);
+
+  const registerColumn = useCallback((key: string, node: unknown) => {
+    const el = node as HTMLElement | null;
+    if (el) columns.current.set(key, el);
+    else columns.current.delete(key);
+  }, []);
+
+  const registerCard = useCallback((id: string, entry: BoardCardEntry | null) => {
+    if (entry) cards.current.set(id, entry);
+    else cards.current.delete(id);
+  }, []);
+
+  /** Which column's box the pointer is inside — the only geometry this shape needs. */
+  const columnAt = useCallback((x: number, y: number): string | null => {
+    for (const [key, el] of columns.current) {
+      const r = el.getBoundingClientRect();
+      if (x >= r.left && x <= r.right && y >= r.top && y <= r.bottom) return key;
+    }
+    return null;
+  }, []);
+
+  /** A drop ends with a click on the row the grip sits in, and that row opens the
+   *  record — so a drag would dump the reader into a drawer they never asked for.
+   *  The same shape PressableRow already guards for text selection. */
+  const justDragged = useRef(false);
+  const { live, bind } = usePointerDrag((id, pointer) => {
+    setOverColumn(null);
+    justDragged.current = true;
+    setTimeout(() => {
+      justDragged.current = false;
+    }, 0);
+    const target = columnAt(pointer.x, pointer.y);
+    const card = cards.current.get(id);
+    if (!target || !card) return;
+    // The drop is resolved against the card's OWN declared destinations, the same
+    // list the menu renders. A column the keyboard path refuses is refused here too.
+    const move = card.moves.find((m) => m.key === target);
+    if (!move || move.disabled) return;
+    card.onMove(target);
+  });
+
+  // The live drop target. `usePointerDrag` reports the delta, not the pointer, so the
+  // highlight needs its own listener — mounted only while a drag is in flight.
+  //
+  // Keyed on WHETHER a drag is running, never on `live` itself. `live` is a fresh
+  // object every pointermove, so depending on it re-ran this effect on every move and
+  // its cleanup cleared `overColumn` immediately after the listener had set it: the
+  // drop still landed (the drop reads the pointer directly) and the highlight simply
+  // never appeared, which is the kind of defect only a rendered drag shows.
+  const dragging = live != null;
+  useEffect(() => {
+    if (Platform.OS !== "web" || !dragging) return;
+    const move = (e: PointerEvent) => setOverColumn(columnAt(e.clientX, e.clientY));
+    window.addEventListener("pointermove", move);
+    return () => {
+      window.removeEventListener("pointermove", move);
+      setOverColumn(null);
+    };
+  }, [dragging, columnAt]);
+
+  const ctx = useMemo<BoardCtx>(
+    () => ({
+      registerColumn,
+      columnHeadings,
+      publishHeading,
+      registerCard,
+      bindDrag: (id: string) => bind(id, "grab"),
+      justDragged,
+      draggingId: live?.id ?? null,
+      dragDelta: live ? { dx: live.dx, dy: live.dy } : null,
+      overColumn,
+    }),
+    [registerColumn, columnHeadings, publishHeading, registerCard, bind, live, overColumn],
+  );
+
+  return (
+    <BoardContext.Provider value={ctx}>
+      <ScrollView
+        horizontal
+        showsHorizontalScrollIndicator
+        contentContainerStyle={styles.track}
+      >
+        {children}
+      </ScrollView>
+    </BoardContext.Provider>
+  );
+}
+
+export interface BoardColumnProps {
+  /** The value this column IS, drawn by the component its data role owns — an
+   *  `OptionBadge` for a select, a `MemberChip` for a person, a plain `Text`
+   *  otherwise. The board never renders the identity itself, so a column heading and
+   *  the same value in a cell cannot look like two different things. */
+  heading: ReactNode;
+  /** The column's key — what a `BoardMove` names and what a drop resolves to. */
+  columnKey: string;
+  /**
+   * How many cards are in this pile — and what decides whether the column shows its
+   * cards or its empty state, so the number beside the heading and the pile under it
+   * are one statement rather than two that can disagree.
+   *
+   * A PROP, never formatted into `heading`: the count is the board's own report and
+   * it changes with every filter, so folding it into the identity makes the name of
+   * the column and its size one string that a screen reader reads as a name and that
+   * no caller can restyle. It also guarantees the number beside a heading is the
+   * number of cards under it.
+   */
+  count: number;
+  /** This column's own act, on the heading row's right edge — an Add that pre-sets
+   *  the column's value. Renders whether or not the column has cards. */
+  action?: ReactNode;
+  /** What to say when the column is empty. Falls back to the locale's own line. */
+  emptyMessage?: string;
+  /** The `BoardCard`s. */
+  children?: ReactNode;
+}
+
+/** One pile — a heading that states its value and its size, and the cards under it. */
+export function BoardColumn(props: BoardColumnProps) {
+  const { heading, columnKey, count, action, emptyMessage, children } = props;
+  const board = useContext(BoardContext);
+  const locale = useLoticsLocale().board;
+  const register = board?.registerColumn;
+
+  const ref = useCallback(
+    (node: unknown) => register?.(columnKey, node),
+    [register, columnKey],
+  );
+
+  const publish = board?.publishHeading;
+  useEffect(() => {
+    publish?.(columnKey, heading);
+  }, [publish, columnKey, heading]);
+
+  const over = board?.draggingId != null && board.overColumn === columnKey;
+
+  return (
+    <View ref={ref} style={[styles.column, over && styles.columnOver]}>
+      <View style={styles.columnHeading}>
+        <View style={styles.columnIdentity}>{heading}</View>
+        <Text size="sm" color="zinc-500" tabular>
+          {count}
+        </Text>
+        <View style={styles.columnAction}>{action}</View>
+      </View>
+      <View style={styles.columnBody}>
+        {count === 0 ? (
+          <EmptyState message={emptyMessage ?? locale.empty} />
+        ) : (
+          <BoardColumnContext.Provider value={heading}>{children}</BoardColumnContext.Provider>
+        )}
+      </View>
+    </View>
+  );
+}
+
+export interface BoardCardProps {
+  /** The record's id — what `onMove` is about, and what a drag carries. */
+  id: string;
+  /** The record's identity. Rendered as the card's own first line. */
+  title: string;
+  /** The facts under the title — a member, a date, a badge. Keep it to what the
+   *  reader sorts the pile by; everything else is what opening the card is for. */
+  children?: ReactNode;
+  /** Opens the record. */
+  onPress: () => void;
+  /** The keyboard door's accessible name — name the record ("Open ORD-1042").
+   *  Falls back to the locale's "Open <title>". */
+  openLabel?: string;
+  /** This record is the one currently open. */
+  selected?: boolean;
+  /** Where this card may go — every column but its own. Empty or omitted and the
+   *  card carries no move control at all, which is the honest rendering of a card
+   *  that cannot be moved. */
+  moves?: BoardMove[];
+  /** Called with the destination `columnKey`, by the menu AND by a pointer drop. */
+  onMove?: (columnKey: string) => void;
+  /** The move control's accessible name — name the record ("Move ORD-1042").
+   *  Falls back to the locale's "Move <title>". */
+  moveLabel?: string;
+}
+
+/**
+ * One record on the board: a press that opens it, and the control that moves it.
+ *
+ * The card is a `PressableRow` + `PressDoor` pair, not a button wrapping its content
+ * — it carries its own controls, and a button must not contain a button.
+ */
+export function BoardCard(props: BoardCardProps) {
+  const {
+    id,
+    title,
+    children,
+    onPress,
+    openLabel,
+    selected = false,
+    moves,
+    onMove,
+    moveLabel,
+  } = props;
+  const board = useContext(BoardContext);
+  const locale = useLoticsLocale().board;
+  const [menuOpen, setMenuOpen] = useState(false);
+  const [hovered, setHovered] = useState(false);
+  const openCard = useCallback(() => {
+    if (board?.justDragged.current) return;
+    onPress();
+  }, [board, onPress]);
+
+  const canMove = moves != null && moves.length > 0 && onMove != null;
+
+  const registerCard = board?.registerCard;
+  useEffect(() => {
+    if (!registerCard || !canMove) return;
+    registerCard(id, { moves: moves!, onMove: onMove! });
+    return () => registerCard(id, null);
+  }, [registerCard, canMove, id, moves, onMove]);
+
+  const dragging = board?.draggingId === id;
+  const delta = dragging ? board?.dragDelta : null;
+
+  return (
+    /* PressableRow keeps its own hover and does not hand it back, so the mouse is
+       caught one level out — a card that never lit up under the pointer was the
+       row swallowing the events, not the wash being too faint. */
+    <View
+      {...({
+        onMouseEnter: () => setHovered(true),
+        onMouseLeave: () => setHovered(false),
+      } as object)}
+    >
+    <PressableRow
+      onPress={openCard}
+      selected={selected}
+      variant="inset"
+      style={[
+        styles.card,
+        /* One neutral step darker. PressableRow paints its own hover through the
+           same property, so the card's resting wash silently overrode it and the
+           row that knows how to light up went quiet. */
+        hovered && styles.cardHovered,
+        dragging && styles.cardDragging,
+        delta ? { transform: [{ translateX: delta.dx }, { translateY: delta.dy }] } : null,
+      ]}
+    >
+      <PressDoor
+        onPress={openCard}
+        accessibilityLabel={openLabel ?? locale.open(title)}
+        radius={CARD_RADIUS}
+      />
+      <View style={styles.cardBody}>
+        <View style={styles.cardTitleRow}>
+          <Text size="sm" weight="medium" numberOfLines={3} style={styles.cardTitle}>
+            {title}
+          </Text>
+          {canMove ? (
+            <View style={styles.cardControls}>
+              {/* The grip is the POINTER path and nothing else: it is not a tab stop
+                  and not in the a11y tree, because the menu beside it performs the
+                  same act and is reachable by every input. An affordance that only a
+                  pointer can use must not advertise itself to a keyboard. */}
+              <Popover open={menuOpen} onOpenChange={setMenuOpen} side="bottom" align="end">
+                <PopoverTrigger>
+                  <IconButton
+                    icon="arrow-right-left"
+                    size="sm"
+                    accessibilityLabel={moveLabel ?? locale.move(title)}
+                  />
+                </PopoverTrigger>
+                <PopoverContent style={styles.menu} disableBodyScroll>
+                  <View style={styles.menuList}>
+                    {moves!.map((m) => (
+                      <MenuButton
+                        key={m.key}
+                        /* The destination named in ITS OWN vocabulary — the dot
+                           and colour the pile itself is titled with, taken from
+                           that column rather than re-declared here, so the menu
+                           and the board cannot describe one stage two ways. */
+                        title={board?.columnHeadings[m.key] ?? m.label}
+                        // Visibly the destination's own name — the menu is short and
+                        // its trigger already says what it does. ANNOUNCED as the whole
+                        // sentence, because a screen reader reads an item without the
+                        // trigger beside it.
+                        accessibilityLabel={locale.moveTo(m.label)}
+                        disabled={m.disabled}
+                        onPress={() => {
+                          setMenuOpen(false);
+                          onMove!(m.key);
+                        }}
+                      />
+                    ))}
+                  </View>
+                </PopoverContent>
+              </Popover>
+              {Platform.OS === "web" ? (
+                <View
+                  ref={board?.bindDrag(id) ?? null}
+                  aria-hidden
+                  tabIndex={-1}
+                  style={styles.grip}
+                >
+                  <Icon name="grip-vertical" size={14} color={colors.zinc[400]} />
+                </View>
+              ) : null}
+            </View>
+          ) : null}
+        </View>
+        {children}
+      </View>
+    </PressableRow>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  // The columns sit on AIR, the way a `TableGroup` band separates itself — no rules,
+  // no per-column ground. `alignItems: flex-start` keeps each column as tall as its
+  // own cards instead of stretching every one to the tallest.
+  track: {
+    flexDirection: "row",
+    alignItems: "flex-start",
+    gap: SPACE.md,
+    // The track is padded on EVERY side, not just the bottom: a column paints a
+    // ring when it is the drop target, and a ring drawn at the scroller's own
+    // edge is clipped by it — so the one moment the board most needs to say
+    // "here" is the one where its signal is half missing. The padding is the
+    // room that ring needs to exist in.
+    padding: SPACE.xs,
+    paddingBottom: SPACE.md,
+  },
+  column: {
+    width: BOARD_COLUMN_WIDTH,
+    gap: SPACE.sm,
+    borderRadius: CONTROL_RADIUS,
+    borderWidth: 1,
+    borderColor: "transparent",
+    padding: SPACE.sm,
+    margin: -1,
+  },
+  // The drop target, in the kit's own attention language — the tint `FileDropTarget`
+  // paints, not a colour picked here.
+  columnOver: {
+    backgroundColor: colors.accent_wash,
+    borderColor: colors.accent,
+  },
+  columnHeading: {
+    flexDirection: "row",
+    alignItems: "center",
+    gap: SPACE.sm,
+    minHeight: 28,
+  },
+  columnIdentity: {
+    flexShrink: 1,
+    minWidth: 0,
+  },
+  // The column's act rides the right edge, and holds its slot whether or not there
+  // is one, so headings across the board keep one baseline.
+  columnAction: {
+    marginLeft: "auto",
+  },
+  // The gap INSIDE the column (between its cards) is half the gap BETWEEN columns.
+  columnBody: {
+    gap: SPACE.sm,
+  },
+  card: {
+    flexDirection: "column",
+    alignItems: "stretch",
+    // `PressableRow`'s inset variant bleeds its wash 8px each way, which is right on a
+    // register sitting on a page edge and wrong here: the card IS the object, and its
+    // border must land where its box does.
+    marginHorizontal: 0,
+    paddingHorizontal: SPACE.md,
+    paddingVertical: SPACE.md,
+    // A card HOLDS content, so it takes the container rung of the radius ladder
+    // (16), not CONTROL_RADIUS (10) — that one is for things you press directly.
+    // The whole card being pressable does not make it a control; a Card is
+    // pressable on plenty of surfaces and still reads as a container.
+    borderRadius: CARD_RADIUS,
+    // A transparent card on a white canvas is a BORDER, not an object. The wash
+    // gives it a body — which is what the eye follows while it is being dragged,
+    // and what tells a full column from an empty one at a glance. It also does
+    // the whole job on its own: a border on top would be a second assertion of
+    // the same edge, on a surface already full of vertical rules — the columns.
+    backgroundColor: tint("zinc", 0.05),
+    minWidth: 0,
+  },
+  cardHovered: { backgroundColor: tint("zinc", 0.1) },
+  cardDragging: {
+    opacity: 0.9,
+    zIndex: 2,
+    boxShadow: colors.shadow,
+  },
+  cardBody: {
+    zIndex: 1,
+    // The title, the owner and the date are three separate FACTS, not one block
+    // of text. At the tighter step they read as a paragraph; at this one the eye
+    // takes them one at a time — and it stays below the gap BETWEEN cards, so
+    // within-card is still tighter than between-card.
+    gap: SPACE.sm,
+    minWidth: 0,
+    width: "100%",
+  },
+  cardTitleRow: {
+    flexDirection: "row",
+    alignItems: "flex-start",
+    gap: SPACE.xs,
+    minWidth: 0,
+  },
+  cardTitle: {
+    flex: 1,
+    minWidth: 0,
+    // The room the pinned controls occupy. Without it a long title runs under
+    // them and the last word is unreadable — absolute positioning takes an
+    // element out of the flow, so the flow has to be told it is still there.
+    paddingRight: 56,
+  },
+  cardControls: {
+    // Pinned to the card's own corner, not carried by the title row: a title that
+    // wraps to two lines would otherwise push the controls down, and a control
+    // that moves with the length of the text beside it is one the reader has to
+    // find again on every card.
+    position: "absolute",
+    // Measured from the card's CONTENT box, which already begins one padding in
+    // — so the offset here is zero, not another padding. Setting SPACE.md again
+    // put the cluster twice as far down as the title it lines up with.
+    top: 0,
+    // A control's BOX carries its hit area, and its glyph sits inset within it.
+    // Align the boxes and the INK lands further in than the title's — five
+    // pixels here, which reads as a lopsided card and is invisible until
+    // measured. Pull the cluster out by that inset so the glyph shares the
+    // title's edge; the hit target simply reaches nearer the corner, which
+    // costs nothing.
+    right: -CONTROL_INK_INSET,
+    zIndex: 2,
+    flexDirection: "row",
+    alignItems: "center",
+    gap: 2,
+    flexShrink: 0,
+  },
+  // `usePointerDrag`'s bind sets this node's `cursor: grab` and `touch-action: none`
+  // on the DOM element itself — restating them here would be a second owner of the
+  // same two properties, and RN's `CursorValue` has no `grab` to state them with.
+  grip: {
+    // The SAME box as the sm IconButton beside it. Two control sizes in one
+    // cluster leave their glyphs on two different edges, and then the inset that
+    // aligns the cluster's ink is right for one of them and wrong for the other.
+    width: 24,
+    height: 24,
+    alignItems: "center",
+    justifyContent: "center",
+  },
+  menu: {
+    minWidth: MIN_CONTROL_WIDTH + SPACE.md,
+  },
+  menuList: {
+    gap: 2,
+  },
+});

package/src/card.tsx

@@ -169,10 +169,16 @@ const styles = StyleSheet.create({
     paddingVertical: 14,
     flexDirection: "row",
     alignItems: "center",
-    gap: 12,
+    flexWrap: "wrap",
+    rowGap: 4,
+    columnGap: 12,
   },
   headerTitle: {
     flex: 1,
+    // flex:1 một mình KHÔNG co lại dưới nội dung: bề rộng tối thiểu mặc định là
+    // "vừa đủ chứa", nên một tiêu đề dài đẩy hàng rộng hơn cả thẻ. minWidth:0
+    // cho phép nó nhường, còn flexWrap ở trên là lối thoát khi đã hết chỗ.
+    minWidth: 0,
     gap: 2,
   },
   headerTitleRow: {