@12-apps/ui 1.7.0 → 1.8.0

package/src/components/data-display/DataViews/data-views-drag.tsx

@@ -0,0 +1,135 @@
+"use client";
+
+import { createContext, useContext, type ReactNode } from "react";
+
+import { Box } from "../../../mui/Box";
+
+/**
+ * DRAGGING, OWNED BY THE CONTAINER AND NOT BY THE CARD.
+ *
+ * A card cannot know whether it is draggable. The same `BaseListCard` renders
+ * inside a reorderable queue, a read-only report and a board column that moves
+ * items between columns — and only the thing holding them knows which. So the
+ * container publishes a drag context and every card inside it becomes
+ * draggable; a card with no container above it renders exactly as before, with
+ * no handle and no listeners.
+ *
+ * This is a SEAM, not a drag implementation. It carries whatever props the
+ * host's library hands out — dnd-kit's `attributes`/`listeners`, react-dnd's
+ * connector output, or plain HTML5 `draggable` + `onDragStart` — because
+ * picking one of those for every consumer of `@12-apps/ui` is a decision this
+ * package has no business making. There is no drag dependency here, and adding
+ * one would force it on every app that installs the library.
+ */
+
+/** The props a container hands to one item. Deliberately untyped-ish: each DnD library has its own shape. */
+export type DragItemProps = Record<string, unknown>;
+
+export interface DragContainerValue {
+  /**
+   * Props for the item's ROOT — the element that moves. dnd-kit wants its
+   * `setNodeRef` and transform style here; HTML5 wants `draggable` and
+   * `onDragStart`.
+   */
+  itemProps: (id: string | number) => DragItemProps;
+  /**
+   * Props for the HANDLE alone, when the container wants drags to start only
+   * from the grip.
+   *
+   * Whole-card dragging breaks the two things a card must still do: selecting
+   * text in it, and hitting the checkbox without the row sliding away. When a
+   * container returns handle props, the card puts them on the grip and leaves
+   * the rest of itself alone.
+   */
+  handleProps?: (id: string | number) => DragItemProps;
+  /** The id currently being dragged, so its card can dim itself. */
+  activeId?: string | number | null;
+}
+
+const DragContainerContext = createContext<DragContainerValue | null>(null);
+
+/**
+ * Marks everything inside as draggable. Cards read this; nothing else does.
+ */
+export function DragContainerProvider({
+  value,
+  children,
+}: {
+  value: DragContainerValue;
+  children: ReactNode;
+}): React.JSX.Element {
+  return <DragContainerContext.Provider value={value}>{children}</DragContainerContext.Provider>;
+}
+
+/**
+ * What one card needs to know about dragging.
+ *
+ * Returns the inert answer when there is no container OR no `dragId` — a card
+ * that forgot its id must not render a handle that does nothing, which is worse
+ * than no handle at all.
+ */
+export function useDragItem(dragId: string | number | undefined): {
+  draggable: boolean;
+  itemProps: DragItemProps;
+  handleProps: DragItemProps | undefined;
+  dragging: boolean;
+} {
+  const container = useContext(DragContainerContext);
+  if (!container || dragId === undefined) {
+    return { draggable: false, itemProps: {}, handleProps: undefined, dragging: false };
+  }
+  return {
+    draggable: true,
+    itemProps: container.itemProps(dragId),
+    handleProps: container.handleProps?.(dragId),
+    dragging: container.activeId === dragId,
+  };
+}
+
+/**
+ * The grip. Six dots, the convention everywhere, drawn rather than imported so
+ * this costs no icon dependency.
+ *
+ * `cursor: grab` on the handle only when the container gates drags to it —
+ * otherwise the whole card carries the cursor and the handle is just an
+ * affordance saying so.
+ */
+export function DragHandle({
+  handleProps,
+  gated,
+  testId,
+}: {
+  handleProps: DragItemProps | undefined;
+  gated: boolean;
+  testId?: string;
+}): React.JSX.Element {
+  return (
+    <Box
+      component="span"
+      aria-hidden={handleProps ? undefined : true}
+      data-testid={testId}
+      {...handleProps}
+      sx={{
+        display: "inline-grid",
+        gridTemplateColumns: "repeat(2, 3px)",
+        gap: "2px",
+        flexShrink: 0,
+        p: 0.5,
+        borderRadius: 1,
+        color: "text.disabled",
+        cursor: gated ? "grab" : "inherit",
+        touchAction: "none",
+        "&:active": { cursor: gated ? "grabbing" : "inherit" },
+        "&:hover": { color: "text.secondary" },
+      }}
+    >
+      {Array.from({ length: 6 }).map((_, index) => (
+        <Box
+          key={index}
+          component="span"
+          sx={{ width: 3, height: 3, borderRadius: "50%", bgcolor: "currentColor" }}
+        />
+      ))}
+    </Box>
+  );
+}

package/src/components/data-display/DataViews/index.ts

@@ -6,6 +6,13 @@
  * wires them to its backend and framework router.
  */
 export { BaseCard } from "./base-card";
+export { BaseListCard, type BaseListCardProps } from "./base-list-card";
+export {
+  DragContainerProvider,
+  useDragItem,
+  type DragContainerValue,
+  type DragItemProps,
+} from "./data-views-drag";
 export { DataViewsGrid } from "./DataViewsGrid";
 export { DataViewsTableBase, type DataViewsTableBaseProps } from "./DataViewsTableBase";
 export { toSavedViewSummary, CARD_ASPECT_RATIOS, DATA_VIEWS_LAYOUTS } from "./data-views-types";

package/src/components/data-display/DataViews/list-card-rails.tsx

@@ -0,0 +1,141 @@
+"use client";
+
+import { createContext, useContext, type ReactNode } from "react";
+
+import { Box } from "../../../mui/Box";
+import { DENSITY_ROW_PADDING, type DataViewsDensity } from "./data-views-layout-context";
+
+/**
+ * THE LIST OWNS THE COLUMNS, NOT THE ROW.
+ *
+ * Every row laying itself out with flex produces a list where nothing lines up.
+ * The caption takes `flex: 1` and shoves the rest right; the value sits after
+ * the meta cluster with the same gap as any other pair, so `MÉTODO PIX
+ * R$ 13,90` reads as one continuous run and the only unlabelled thing in the
+ * row is the number that matters most; and because the status chip's width
+ * varies with its text (`Pago` vs `Em aberto` vs `Cancelado`), the money jitters
+ * left and right on every row down the page.
+ *
+ * So the rails are declared ONCE, here, and each card is `grid-template-columns:
+ * subgrid` spanning them. One set of edges for the whole list, the value on its
+ * own rail, the status in a slot wide enough for the longest label it will ever
+ * hold. Adding a row cannot move the column.
+ *
+ * Subgrid needs the card to be a DIRECT child of this grid — no wrapper element
+ * between them, which is why the group renders its children bare.
+ */
+
+/** One rail. Fixed where alignment matters, flexible where it does not. */
+export interface ListRails {
+  /** Reserved even when nothing drags: toggling drag mode must not shift the list. */
+  drag: string;
+  /** Reserved even when nothing is selectable, for the same reason. */
+  select: string;
+  leading: string;
+  /** The one column that absorbs spare width. */
+  caption: string;
+  meta: string;
+  /** The value's own rail, with a fixed right edge. */
+  value: string;
+  /** Wide enough for the longest status this list holds. */
+  status: string;
+  actions: string;
+}
+
+const DEFAULT_RAILS: ListRails = {
+  drag: "auto",
+  select: "auto",
+  leading: "auto",
+  caption: "minmax(0, 1fr)",
+  meta: "auto",
+  // `max-content` on the value, so the rail is as wide as the widest amount in
+  // the list and no wider — a fixed px guess is either clipping or dead space.
+  value: "max-content",
+  status: "max-content",
+  actions: "auto",
+};
+
+interface ListRailsValue {
+  density: DataViewsDensity;
+  /** Whether the gutters are held open even when empty. */
+  reserveGutters: boolean;
+}
+
+const ListRailsContext = createContext<ListRailsValue | null>(null);
+
+/** Is this card inside a group that owns the rails? */
+export function useListRails(): ListRailsValue | null {
+  return useContext(ListRailsContext);
+}
+
+/** The column template, as one `grid-template-columns` value. */
+export function railsTemplate(rails: ListRails): string {
+  return [
+    rails.drag,
+    rails.select,
+    rails.leading,
+    rails.caption,
+    rails.meta,
+    rails.value,
+    rails.status,
+    rails.actions,
+  ].join(" ");
+}
+
+/** How many rails there are — the span a card claims. */
+export const RAIL_COUNT = 8;
+
+/**
+ * A list of {@link BaseListCard}s that share one set of columns.
+ *
+ * Also the natural home for the things a review pointed out belong to the list
+ * rather than the card: the density every row answers, and — when it lands —
+ * shift-click range selection and the single `aria-live` region a list needs
+ * (fifty polite live regions is a screen-reader nightmare, which is why the
+ * card no longer takes one).
+ */
+export function ListCardGroup({
+  children,
+  density = "cozy",
+  rails,
+  reserveGutters = true,
+  gap,
+  dataTestId,
+}: {
+  children: ReactNode;
+  density?: DataViewsDensity;
+  /** Override individual rails; anything omitted keeps its default. */
+  rails?: Partial<ListRails>;
+  /**
+   * Hold the drag and select gutters open even when nothing uses them.
+   *
+   * On by default: a selectable list and a read-only one should line up, and
+   * turning drag mode on should not shift every row sideways.
+   */
+  reserveGutters?: boolean;
+  /** Row gap. Defaults to the density's own spacing. */
+  gap?: number;
+  dataTestId?: string;
+}): React.JSX.Element {
+  const resolved = { ...DEFAULT_RAILS, ...rails };
+  return (
+    <ListRailsContext.Provider value={{ density, reserveGutters }}>
+      <Box
+        data-testid={dataTestId}
+        sx={{
+          // The query container for every row inside it — a row cannot be one
+          // itself and a subgrid at the same time (containment drops subgrid).
+          // Every row in a list is the same width anyway, so the group is the
+          // honest place to ask the question.
+          containerType: "inline-size",
+          display: "grid",
+          gridTemplateColumns: railsTemplate(resolved),
+          alignItems: "center",
+          rowGap: gap ?? DENSITY_ROW_PADDING[density],
+        }}
+      >
+        {children}
+      </Box>
+    </ListRailsContext.Provider>
+  );
+}

package/src/components/data-display/DescriptionItem/DescriptionItem.tsx

@@ -21,6 +21,21 @@ export interface DescriptionItemProps {
    */
   orientation?: 'vertical' | 'horizontal';
 
+  /**
+   * Which edge the label and value line up on.
+   *
+   * - `start` (default): both flush left, the reading order for a form or a
+   *   description list.
+   * - `center`: both centred over each other — for a pair sitting in a column
+   *   of its own, where a left-flush label over a shorter value looks unhinged
+   *   from it.
+   * - `end`: both flush right, which is what a numeric column wants so its
+   *   digits line up with the value above and below.
+   *
+   * Applies to `vertical`; a `horizontal` pair is already a single line.
+   */
+  align?: 'start' | 'center' | 'end';
+
   /**
    * Optional CSS class name
    */
@@ -54,13 +69,20 @@ export interface DescriptionItemProps {
  * />
  * ```
  */
+/** `align` in the terms flexbox and CSS each want it. */
+const FLEX_ALIGN = { start: 'flex-start', center: 'center', end: 'flex-end' } as const;
+
 // Vertical stacks the label above the value; horizontal sets them side by side
 // with the label sized to its content.
-const containerSx = (isHorizontal: boolean) => ({
+const containerSx = (isHorizontal: boolean, align: 'start' | 'center' | 'end') => ({
   display: 'flex',
   flexDirection: isHorizontal ? ('row' as const) : ('column' as const),
-  alignItems: isHorizontal ? 'center' : 'flex-start',
+  alignItems: isHorizontal ? 'center' : FLEX_ALIGN[align],
   gap: isHorizontal ? 1 : 0,
+  // `alignItems` places the two boxes; `textAlign` handles a label or value
+  // that WRAPS, whose second line would otherwise fall back to flush-left
+  // inside a box the alignment had already centred.
+  textAlign: align,
 });
 
 const labelStyle = (isHorizontal: boolean) => ({
@@ -79,6 +101,7 @@ export const DescriptionItem: React.FC<DescriptionItemProps> = ({
   label,
   value,
   orientation = 'vertical',
+  align = 'start',
   className,
   'data-testid': dataTestId,
 }) => {
@@ -88,7 +111,7 @@ export const DescriptionItem: React.FC<DescriptionItemProps> = ({
   return (
     <Box
       className={className}
-      sx={containerSx(isHorizontal)}
+      sx={containerSx(isHorizontal, align)}
       data-testid={dataTestId || 'description-item'}
     >
       <Text