@multiplatform.one/forms 7.4.0 → 7.5.0

package/src/DescriptionList/index.tsx

@@ -0,0 +1,503 @@
+/**
+ * DescriptionList — the READ half of SchemaForm (MPO-53 AC-6).
+ *
+ * A schema-driven label–value record summary. Values compose FieldDisplay's
+ * 31-face union (never a parallel formatter — LC-12). Terms share one
+ * column capped at the widest `fieldDefaults` purpose width (24ch) so the
+ * read/edit flip moves no label (LC-44). Chromeless by default (LC-39);
+ * the framed variant paints, so it earns the Card inset.
+ *
+ * House Text (14/25 + body fragment + textAccent) and house Separator
+ * (1px `$borderColor`, quiet = opacity 0.5) own the term and the row rule.
+ * Forms cannot import `@multiplatform.one/components` (that package depends
+ * on forms); the recipes are the same measured law.
+ */
+
+import {
+  Children,
+  isValidElement,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useState,
+  type CSSProperties,
+  type ReactElement,
+  type ReactNode,
+  type Ref,
+} from "react";
+import { useResolvedKnobs } from "@multiplatform.one/theme";
+import { Text, View, XStack, YStack, isWeb } from "tamagui";
+import { Button } from "../Button";
+import { FORM_GRID_COLLAPSE_WIDTH } from "../FormGrid";
+import { LABEL_COLUMN_MAX_CH, LABEL_COLUMN_WIDTH } from "../fieldDefaults";
+import { formReadableMaxWidth } from "../formSpacing";
+import { DescriptionListSlotProvider, FieldDisplay, type FieldDisplayType } from "../FieldDisplay";
+import { t } from "../shared/t";
+
+export type DescriptionListPlacement = "side" | "top";
+
+export interface DescriptionListItem {
+  term: ReactNode;
+  /** FieldDisplay type — every typed value mounts FieldDisplay (LC-12). */
+  field?: FieldDisplayType;
+  value?: any;
+  fieldProps?: Record<string, any>;
+  linkedValue?: any;
+  /** Opt-in ellipsis for identifier-class values (DG-OVF). */
+  truncate?: boolean;
+  /** Optional per-row Change action. */
+  onChange?: () => void;
+  changeLabel?: string;
+  /**
+   * Escape hatch for a value that is not a FieldDisplay face (CopyField
+   * slot). Typed rows must still pass `field` — this is not a formatter.
+   */
+  children?: ReactNode;
+  hidden?: boolean;
+}
+
+export type DescriptionListRowProps = DescriptionListItem;
+
+export interface DescriptionListProps {
+  items?: DescriptionListItem[];
+  children?: ReactNode;
+  /**
+   * Term placement. Default **side** (the record register). Rides
+   * `fieldLabelPlacement` when the knob is `top` | `side`; `floating` does
+   * not apply to a read face. Explicit prop ejects.
+   */
+  placement?: DescriptionListPlacement;
+  /** Nested scale (LC-73 / LC-76) — space one stop; type and the 32 action stay. */
+  compact?: boolean;
+  /** Card frame (paints, so it earns the inset — LC-39). */
+  framed?: boolean;
+  /** Same 1px `$borderColor` rule at opacity 0.5 — never a lighter colour. */
+  quiet?: boolean;
+  /**
+   * Cap readable width (DG-FORM-08). Pass `"fluid"` to opt out.
+   * Default: {@link formReadableMaxWidth} (560).
+   */
+  maxWidth?: number | "fluid";
+  /** Eject the shared term column track. Default {@link LABEL_COLUMN_WIDTH}. */
+  labelColumnWidth?: string;
+  testID?: string;
+}
+
+function purposeMaxCh(): number {
+  return LABEL_COLUMN_MAX_CH;
+}
+
+function listItemRhythm(density: string) {
+  const compact = density === "compact";
+  return {
+    compact,
+    padV: compact ? "$2" : "$2.5",
+    columnGap: compact ? "$2" : "$3",
+    stackGap: compact ? 4 : "$2",
+    minHeight: compact ? 39 : 45,
+  } as const;
+}
+
+function resolvePlacement(
+  prop: DescriptionListPlacement | undefined,
+  knobPlacement: string,
+): DescriptionListPlacement {
+  if (prop === "side" || prop === "top") return prop;
+  if (knobPlacement === "top" || knobPlacement === "side") {
+    return knobPlacement;
+  }
+  return "side";
+}
+
+function rowHasAction(row: DescriptionListItem): boolean {
+  return typeof row.onChange === "function";
+}
+
+function itemsFromChildren(children: ReactNode | undefined): DescriptionListItem[] {
+  if (children == null) return [];
+  return Children.toArray(children).flatMap((child) => {
+    if (!isValidElement(child)) return [];
+    const props = child.props as DescriptionListItem;
+    if (props.hidden) return [];
+    if (props.term == null) return [];
+    return [props];
+  });
+}
+
+/** House Separator recipe — 1px filled `$borderColor` (MPO-47 / §7.3). */
+function ListRule({ quiet }: { quiet?: boolean }) {
+  return (
+    <View
+      role="separator"
+      data-mpo-description-list-rule=""
+      height={1}
+      backgroundColor="$borderColor"
+      opacity={quiet ? 0.5 : 1}
+      alignSelf="stretch"
+      flexGrow={0}
+      flexShrink={0}
+      width="100%"
+      {...(isWeb ? { style: { gridColumn: "1 / -1" } as CSSProperties } : undefined)}
+    />
+  );
+}
+
+function TermText({ children }: { children: ReactNode }) {
+  const { knobProps } = useResolvedKnobs();
+  return (
+    <Text
+      data-mpo-description-list-term=""
+      fontSize={14}
+      lineHeight={25}
+      {...knobProps.body}
+      color="$color11"
+      minWidth={0}
+      {...(isWeb ? ({ overflowWrap: "break-word" } as Record<string, unknown>) : undefined)}
+    >
+      {children}
+    </Text>
+  );
+}
+
+function ChangeAction({ onChange, label }: { onChange: () => void; label?: string }) {
+  return (
+    <View data-mpo-description-list-action="" alignItems="flex-start" justifyContent="flex-end">
+      <Button nested outlined onPress={onChange}>
+        {label ?? t("Change")}
+      </Button>
+    </View>
+  );
+}
+
+function ValueSlot({ row }: { row: DescriptionListItem }) {
+  return (
+    <View data-mpo-description-list-value="" minWidth={0} width="100%">
+      {row.children != null ? (
+        row.children
+      ) : (
+        <FieldDisplay
+          field={row.field ?? "input"}
+          value={row.value}
+          fieldProps={row.fieldProps}
+          linkedValue={row.linkedValue}
+          chromeless
+          align="left"
+          truncate={row.truncate}
+        />
+      )}
+    </View>
+  );
+}
+
+function DescriptionListRowView({
+  row,
+  stacked,
+  hasActionColumn,
+  rhythm,
+  showRule,
+  quiet,
+}: {
+  row: DescriptionListItem;
+  stacked: boolean;
+  hasActionColumn: boolean;
+  rhythm: ReturnType<typeof listItemRhythm>;
+  showRule: boolean;
+  quiet?: boolean;
+}) {
+  const action = rowHasAction(row) ? (
+    <ChangeAction onChange={row.onChange!} label={row.changeLabel} />
+  ) : hasActionColumn && isWeb && !stacked ? (
+    <View data-mpo-description-list-action="" />
+  ) : null;
+
+  const rowStyle: CSSProperties | undefined = isWeb
+    ? stacked
+      ? {
+          display: "grid",
+          gridTemplateColumns: hasActionColumn ? "minmax(0,1fr) max-content" : "minmax(0,1fr)",
+          columnGap: undefined,
+          rowGap: undefined,
+        }
+      : {
+          display: "grid",
+          gridTemplateColumns: "subgrid",
+          gridColumn: "1 / -1",
+        }
+    : undefined;
+
+  const termStyle: CSSProperties | undefined = isWeb
+    ? stacked
+      ? { gridColumn: "1", gridRow: "1" }
+      : undefined
+    : undefined;
+  const valueStyle: CSSProperties | undefined = isWeb
+    ? stacked
+      ? { gridColumn: "1 / -1", gridRow: "2" }
+      : undefined
+    : undefined;
+  const actionStyle: CSSProperties | undefined = isWeb
+    ? stacked
+      ? { gridColumn: "2", gridRow: "1", justifySelf: "end" }
+      : { justifySelf: "end" }
+    : undefined;
+
+  const body = stacked ? (
+    <>
+      <View style={termStyle}>
+        <TermText>{row.term}</TermText>
+      </View>
+      {action ? <View style={actionStyle}>{action}</View> : null}
+      <View style={valueStyle} marginTop={rhythm.stackGap as never}>
+        <ValueSlot row={row} />
+      </View>
+    </>
+  ) : isWeb ? (
+    <>
+      <View style={termStyle}>
+        <TermText>{row.term}</TermText>
+      </View>
+      <View style={valueStyle}>
+        <ValueSlot row={row} />
+      </View>
+      {action ? <View style={actionStyle}>{action}</View> : null}
+    </>
+  ) : (
+    <XStack alignItems="flex-start" width="100%" gap={rhythm.columnGap as never}>
+      <View
+        minWidth={0}
+        maxWidth={`${purposeMaxCh()}ch` as never}
+        flexShrink={0}
+        width={`${purposeMaxCh()}ch` as never}
+      >
+        <TermText>{row.term}</TermText>
+      </View>
+      <View flex={1} minWidth={0}>
+        <ValueSlot row={row} />
+      </View>
+      {action}
+    </XStack>
+  );
+
+  return (
+    <>
+      {showRule ? <ListRule quiet={quiet} /> : null}
+      <YStack
+        data-mpo-description-list-row=""
+        data-has-change={rowHasAction(row) ? "true" : "false"}
+        paddingVertical={rhythm.padV as never}
+        minHeight={rhythm.minHeight}
+        columnGap={rhythm.columnGap as never}
+        width="100%"
+        minWidth={0}
+        style={rowStyle}
+      >
+        {body}
+      </YStack>
+    </>
+  );
+}
+
+function DescriptionListWeb({
+  rows,
+  stacked,
+  hasAction,
+  rhythm,
+  quiet,
+  labelColumnWidth,
+  density,
+  size,
+  placement,
+  framed,
+}: {
+  rows: DescriptionListItem[];
+  stacked: boolean;
+  hasAction: boolean;
+  rhythm: ReturnType<typeof listItemRhythm>;
+  quiet?: boolean;
+  labelColumnWidth: string;
+  density: string;
+  size: string;
+  placement: DescriptionListPlacement;
+  framed: boolean;
+}) {
+  const style: CSSProperties = stacked
+    ? { display: "block", width: "100%" }
+    : {
+        display: "grid",
+        gridTemplateColumns: hasAction
+          ? `${labelColumnWidth} minmax(0, 1fr) max-content`
+          : `${labelColumnWidth} minmax(0, 1fr)`,
+        width: "100%",
+      };
+
+  return (
+    <YStack
+      data-mpo-description-list=""
+      data-placement={placement}
+      data-stacked={stacked ? "true" : "false"}
+      data-compact={rhythm.compact ? "true" : "false"}
+      data-framed={framed ? "true" : "false"}
+      data-quiet={quiet ? "true" : "false"}
+      data-has-action={hasAction ? "true" : "false"}
+      data-label-column-width={labelColumnWidth}
+      data-density={density}
+      data-size={size}
+      width="100%"
+      minWidth={0}
+      style={style}
+    >
+      {rows.map((row, index) => (
+        <DescriptionListRowView
+          key={index}
+          row={row}
+          stacked={stacked}
+          hasActionColumn={hasAction}
+          rhythm={rhythm}
+          showRule={index > 0}
+          quiet={quiet}
+        />
+      ))}
+    </YStack>
+  );
+}
+
+function useContainerWide(enabled: boolean): { ref: Ref<unknown>; wide: boolean } {
+  const ref = useRef<HTMLDivElement>(null);
+  const [wide, setWide] = useState(true);
+
+  useLayoutEffect(() => {
+    const el = ref.current;
+    if (!el || !enabled) {
+      setWide(true);
+      return;
+    }
+
+    const update = (width: number) => {
+      setWide(width >= FORM_GRID_COLLAPSE_WIDTH);
+    };
+
+    update(el.getBoundingClientRect().width);
+
+    if (typeof ResizeObserver === "undefined") {
+      const onResize = () => update(el.getBoundingClientRect().width);
+      window.addEventListener("resize", onResize);
+      return () => window.removeEventListener("resize", onResize);
+    }
+
+    const ro = new ResizeObserver((entries) => {
+      const width = entries[0]?.contentRect.width ?? el.getBoundingClientRect().width;
+      update(width);
+    });
+    ro.observe(el);
+    return () => ro.disconnect();
+  }, [enabled]);
+
+  return { ref, wide };
+}
+
+export function DescriptionList({
+  items,
+  children,
+  placement: placementProp,
+  compact,
+  framed = false,
+  quiet = false,
+  maxWidth = formReadableMaxWidth,
+  labelColumnWidth = LABEL_COLUMN_WIDTH,
+  testID,
+}: DescriptionListProps) {
+  const { knobProps } = useResolvedKnobs(compact === undefined ? undefined : { compact });
+  const placement = resolvePlacement(placementProp, knobProps.fieldLabelPlacement);
+  const rhythm = listItemRhythm(knobProps.density);
+  const rows = useMemo(() => {
+    const fromItems = (items ?? []).filter((row) => !row.hidden);
+    if (fromItems.length) return fromItems;
+    return itemsFromChildren(children);
+  }, [items, children]);
+  const hasAction = rows.some(rowHasAction);
+  const measureCollapse = placement === "side" && isWeb;
+  const { ref, wide } = useContainerWide(measureCollapse);
+  const stacked = placement === "top" || (placement === "side" && !wide);
+
+  const list = (
+    <DescriptionListSlotProvider>
+      {isWeb ? (
+        <DescriptionListWeb
+          rows={rows}
+          stacked={stacked}
+          hasAction={hasAction}
+          rhythm={rhythm}
+          quiet={quiet}
+          labelColumnWidth={labelColumnWidth}
+          density={knobProps.density}
+          size={knobProps.size}
+          placement={placement}
+          framed={framed}
+        />
+      ) : (
+        <YStack
+          data-mpo-description-list=""
+          data-placement={placement}
+          data-stacked={stacked ? "true" : "false"}
+          data-compact={rhythm.compact ? "true" : "false"}
+          data-framed={framed ? "true" : "false"}
+          data-quiet={quiet ? "true" : "false"}
+          data-has-action={hasAction ? "true" : "false"}
+          data-label-column-width={labelColumnWidth}
+          data-density={knobProps.density}
+          data-size={knobProps.size}
+          width="100%"
+          minWidth={0}
+        >
+          {rows.map((row, index) => (
+            <DescriptionListRowView
+              key={index}
+              row={row}
+              stacked={true}
+              hasActionColumn={hasAction}
+              rhythm={rhythm}
+              showRule={index > 0}
+              quiet={quiet}
+            />
+          ))}
+        </YStack>
+      )}
+    </DescriptionListSlotProvider>
+  );
+
+  const widthProps = {
+    width: "100%" as const,
+    maxWidth: maxWidth === "fluid" ? undefined : maxWidth,
+    alignSelf: maxWidth === "fluid" ? undefined : ("flex-start" as const),
+  };
+
+  return (
+    <YStack
+      ref={ref as never}
+      data-mpo-description-list-host=""
+      data-testid={testID}
+      minWidth={0}
+      {...widthProps}
+      {...(framed
+        ? {
+            backgroundColor: "$color3",
+            borderWidth: 1,
+            borderColor: "$color5",
+            ...knobProps.containerRadius,
+            ...knobProps.panelPadding,
+          }
+        : undefined)}
+    >
+      {list}
+    </YStack>
+  );
+}
+
+export function DescriptionListRow(_props: DescriptionListRowProps): ReactElement | null {
+  return null;
+}
+
+DescriptionList.Row = DescriptionListRow;
+
+/** Alias — Ant / Cloudscape "PropertyList" name. */
+export const PropertyList = DescriptionList;

package/src/FieldDisplay/FieldDisplay.spec.tsx

@@ -118,4 +118,12 @@ describe("FieldDisplay", () => {
     expect(root).not.toBeNull();
     expect(root?.getAttribute("data-field")).toBe("datepicker");
   });
+
+  it("draws a QR matrix when barcode fieldProps.formats starts with qr", () => {
+    const result = renderWithProviders(
+      <FieldDisplay field="barcode" value="SKU-001234" fieldProps={{ formats: ["qr"] }} />,
+    );
+    expect(result.container.querySelector('[data-testid="barcode-preview-qr"]')).not.toBeNull();
+    expect(result.container.querySelector("canvas")).toBeNull();
+  });
 });