blixify-ui-web-mcp 0.1.19 → 0.1.21

package/lib/components/data/dataWrapper/dataWrapper.bareHooks.stories.tsx

@@ -0,0 +1,951 @@
+import axios from "axios";
+import MockAdapter from "axios-mock-adapter";
+import React, { ReactElement, useMemo, useState } from "react";
+import { Button } from "../../action/button";
+import { ButtonGroup } from "../../action/buttonGroup";
+import { Tag } from "../../display/tag";
+import { DataStructure } from "../dataTemplate/model";
+import { DataTemplateWrapper } from "./index";
+
+/**
+ * INFO: a how-to for DataTemplateWrapper, one story per question someone
+ * actually asks — change the list, add under the read view, replace the read
+ * view, add under the update form, replace a field, replace the buttons, wire a
+ * full page, filter the list, create with fixed values, format a value,
+ * validate before save, and merge a second collection into the list.
+ *
+ * Each story opens straight on the view it is about and mocks its own API, so
+ * it works with no server. The descriptions state what each hook DOES, checked
+ * against DataTemplate's render code — several of these are easy to guess wrong
+ * from the prop name alone (bareUpdateComponent adds, it does not replace;
+ * bareUpdateActionComponent replaces, it does not add).
+ */
+const meta = {
+  title: "Data/Data Wrapper/Bare Hooks",
+  parameters: { layout: "fullscreen" },
+  decorators: [
+    (Story: () => ReactElement) => (
+      <div className="bg-gray-100 min-h-screen p-4">
+        <Story />
+      </div>
+    ),
+  ],
+};
+export default meta;
+
+const ENDPOINT = "https://bare-hooks.blixify.invalid/api/data";
+const COLLECTION = "bare-orders";
+
+const ORDER_SCHEMA: DataStructure[] = [
+  { id: "orderNo", name: "Order No", type: "string" },
+  { id: "customer", name: "Customer", type: "string" },
+  {
+    id: "status",
+    name: "Status",
+    type: "list",
+    listSelection: ["Draft", "Submitted", "Approved"],
+  },
+  { id: "amount", name: "Amount (RM)", type: "number" },
+  { id: "notes", name: "Notes", type: "textArea", optional: true },
+];
+
+const handleSeedOrders = () => [
+  {
+    _id: "o1",
+    orderNo: "ORD-1001",
+    customer: "Northwind Trading",
+    status: "Submitted",
+    amount: 1250,
+    notes: "Deliver before Friday",
+  },
+  {
+    _id: "o2",
+    orderNo: "ORD-1002",
+    customer: "Contoso Supplies",
+    status: "Draft",
+    amount: 480,
+  },
+  {
+    _id: "o3",
+    orderNo: "ORD-1003",
+    customer: "Fabrikam Works",
+    status: "Approved",
+    amount: 3920,
+  },
+  {
+    _id: "o4",
+    orderNo: "ORD-1004",
+    customer: "Tailspin Toys",
+    status: "Submitted",
+    amount: 760,
+  },
+];
+
+const RETURN_COLLECTION = "bare-returns";
+
+const handleSeedReturns = () => [
+  {
+    _id: "r1",
+    orderNo: "RET-2001",
+    customer: "Northwind Trading",
+    status: "Submitted",
+    amount: 150,
+  },
+  {
+    _id: "r2",
+    orderNo: "RET-2002",
+    customer: "Fabrikam Works",
+    status: "Approved",
+    amount: 320,
+  },
+];
+
+const handleClone = (value: any) =>
+  value === null || value === undefined
+    ? value
+    : JSON.parse(JSON.stringify(value));
+
+// INFO: the two query types these stories send; anything else (the search
+// box's own conditions) is let through rather than guessed at
+const handleMatchQuery = (row: any, query?: any[]) =>
+  (query ?? []).every((eachQuery) => {
+    if (eachQuery?.type === "=")
+      return row[eachQuery.queryId] === eachQuery.value;
+    if (eachQuery?.type === "in")
+      return (eachQuery.value ?? []).includes(row[eachQuery.queryId]);
+    return true;
+  });
+
+/**
+ * INFO: answers every call a story makes against its own in-memory store, so
+ * an update really changes what the next read returns. It follows the server
+ * where the stories depend on it: the list query filters every collection,
+ * and each unionCollections entry adds its rows with its own `source` label.
+ */
+const handleInstallMock = (store: any[]) => {
+  const mock = new MockAdapter(axios, {
+    onNoMatch: "passthrough",
+    delayResponse: 50,
+  });
+  const returns = handleSeedReturns();
+  const handleParseBody = (config: any) => {
+    try {
+      return JSON.parse(config?.data ?? "{}");
+    } catch (err) {
+      return {};
+    }
+  };
+  const handleListRows = (body: any) => {
+    const rows = store.filter((eachRow) =>
+      handleMatchQuery(eachRow, body.query),
+    );
+    const unionRows = (body.unionCollections ?? []).flatMap((eachUnion: any) =>
+      eachUnion.collection === RETURN_COLLECTION
+        ? returns
+            .filter(
+              (eachRow) =>
+                handleMatchQuery(eachRow, eachUnion.query) &&
+                handleMatchQuery(eachRow, body.query),
+            )
+            .map((eachRow) => ({ ...eachRow, source: eachUnion.source }))
+        : [],
+    );
+    return [...rows, ...unionRows];
+  };
+  const renderUrl = (type: string) => `${ENDPOINT}/${COLLECTION}/${type}`;
+  mock.onPost(renderUrl("list")).reply((config) => {
+    const rows = handleListRows(handleParseBody(config));
+    return [200, { data: handleClone(rows), count: rows.length }];
+  });
+  mock.onPost(renderUrl("count")).reply((config) => {
+    const rows = handleListRows(handleParseBody(config));
+    return [200, { data: rows.length, count: rows.length }];
+  });
+  mock.onPost(renderUrl("get")).reply((config) => {
+    const body = handleParseBody(config);
+    return [
+      200,
+      {
+        data: handleClone(
+          store.find((eachRow) => eachRow._id === body.id) ?? null,
+        ),
+      },
+    ];
+  });
+  mock.onPost(renderUrl("create")).reply((config) => {
+    const body = handleParseBody(config);
+    store.push({ ...(body.data ?? {}) });
+    return [200, { success: true }];
+  });
+  mock.onPost(renderUrl("update")).reply((config) => {
+    const body = handleParseBody(config);
+    const index = store.findIndex((eachRow) => eachRow._id === body.id);
+    if (index >= 0) store[index] = { ...store[index], ...(body.data ?? {}) };
+    return [200, { success: true }];
+  });
+  mock.onPost(renderUrl("delete")).reply((config) => {
+    const body = handleParseBody(config);
+    const index = store.findIndex((eachRow) => eachRow._id === body.id);
+    if (index >= 0) store.splice(index, 1);
+    return [200, { success: true }];
+  });
+  return mock;
+};
+
+const useOrderMock = () => {
+  const store = useMemo(() => handleSeedOrders(), []);
+  useMemo(() => handleInstallMock(store), [store]);
+  return store;
+};
+
+const workspace = {
+  apiEndpointType: "mongoDB" as const,
+  apiEndpoint: ENDPOINT,
+  apiEndpointToken: "",
+  apiUserToken: "",
+  assetEndpoint: "",
+  assetUploadEndpoint: "",
+};
+
+const renderIntro = (title: string, description: ReactElement) => (
+  <div className="mb-4 max-w-3xl">
+    <div className="font-semibold text-gray-900">{title}</div>
+    <div className="mt-1 text-sm text-gray-600">{description}</div>
+  </div>
+);
+
+// ---------------------------------------------------------------------------
+// Components the hooks return. They live at module level on purpose: a hook
+// runs INSIDE DataTemplate's render, so React hooks written directly in the
+// arrow function would belong to DataTemplate and break the rules of hooks.
+// Return a component instead and its state is its own.
+// ---------------------------------------------------------------------------
+
+const OrderCards = (props: { rows: any[]; loading: boolean }) => {
+  if (props.loading)
+    return <div className="text-sm text-gray-500">Loading…</div>;
+  return (
+    <div
+      id="bare-order-cards"
+      className="grid grid-cols-1 gap-3 sm:grid-cols-3"
+    >
+      {props.rows.map((eachRow: any) => (
+        <div
+          key={eachRow._id ?? eachRow.orderNo}
+          className="rounded-lg border border-gray-200 bg-white p-4"
+        >
+          <div className="text-xs text-gray-500">{eachRow.orderNo}</div>
+          <div className="mt-1 font-medium text-gray-900">
+            {eachRow.customer}
+          </div>
+          <div className="mt-2 text-sm text-gray-700">RM {eachRow.amount}</div>
+        </div>
+      ))}
+    </div>
+  );
+};
+
+const OrderSummary = (props: { data: any }) => (
+  <div className="mt-4 rounded-lg border border-primary-200 bg-primary-50 p-4 text-sm">
+    <div className="font-medium text-gray-900">Summary</div>
+    <div className="mt-1 text-gray-700">
+      {props.data?.customer} owes RM {props.data?.amount} on{" "}
+      {props.data?.orderNo}.
+    </div>
+  </div>
+);
+
+const OrderReceipt = (props: { data: any }) => (
+  <div className="rounded-lg border border-gray-200 bg-white p-6">
+    <div className="text-xs uppercase tracking-wide text-gray-500">Receipt</div>
+    <div className="mt-2 text-2xl font-semibold text-gray-900">
+      RM {props.data?.amount}
+    </div>
+    <div className="mt-1 text-sm text-gray-700">
+      {props.data?.orderNo} · {props.data?.customer}
+    </div>
+    <div className="mt-3">
+      <Tag size="small" tagText={props.data?.status ?? ""} color="default" />
+    </div>
+  </div>
+);
+
+const LivePanel = (props: { data: any }) => {
+  // 1. State
+  const [checked, setChecked] = useState(0);
+
+  // 7. return
+  return (
+    <div
+      id="bare-live-panel"
+      className="mt-4 rounded-lg border border-gray-200 bg-white p-4 text-sm"
+    >
+      <div className="font-medium text-gray-900">Live preview</div>
+      <div id="bare-live-values" className="mt-1 text-gray-700">
+        {props.data?.customer || "—"} · RM {props.data?.amount ?? 0}
+      </div>
+      <div className="mt-3 flex items-center gap-3">
+        <Button
+          text="Mark checked"
+          size="small"
+          type="light"
+          onClick={() => setChecked((current) => current + 1)}
+        />
+        <span id="bare-live-checked" className="text-gray-600">
+          checked {checked}×
+        </span>
+      </div>
+    </div>
+  );
+};
+
+const StatusPicker = (props: {
+  value: string;
+  onChange: (value: string) => void;
+}) => (
+  <div id="bare-status-picker" className="col-span-12 sm:col-span-6">
+    <div className="mb-2 text-sm font-medium text-gray-700">
+      Status (custom input)
+    </div>
+    <ButtonGroup
+      selection={["Draft", "Submitted", "Approved"].map((eachStatus) => ({
+        id: eachStatus,
+        name: eachStatus,
+      }))}
+      selectedId={props.value}
+      variant="tag"
+      size="small"
+      onClick={props.onChange}
+    />
+  </div>
+);
+
+const STATUS_COLOUR: { [status: string]: "yellow" | "blue" | "green" } = {
+  Draft: "yellow",
+  Submitted: "blue",
+  Approved: "green",
+};
+
+const STATUS_SELECTION = ["Draft", "Submitted", "Approved"].map(
+  (eachStatus) => ({ id: eachStatus, name: eachStatus }),
+);
+
+const handleFormatValue = (key: string, value: any) => {
+  if (key === "amount" && value !== undefined && value !== null && value !== "")
+    return `RM ${Number(value).toLocaleString("en-MY", {
+      minimumFractionDigits: 2,
+    })}`;
+  if (key === "status" && value)
+    return (
+      <Tag
+        size="small"
+        tagText={value}
+        color={STATUS_COLOUR[value] ?? "default"}
+      />
+    );
+  return undefined;
+};
+
+const UNION_SCHEMA: DataStructure[] = [
+  ...ORDER_SCHEMA,
+  { id: "source", name: "Source", type: "string", hideForm: true },
+];
+
+// ---------------------------------------------------------------------------
+// Stories
+// ---------------------------------------------------------------------------
+
+export const ListOverride = () => {
+  useOrderMock();
+  return (
+    <div>
+      {renderIntro(
+        "Change the list — bareListComponent",
+        <>
+          <code>bareListComponent(rows, prettierRows, loading, pageIndex)</code>{" "}
+          replaces the list body with your own rendering; the data, search and
+          paging stay DataTemplate&apos;s. It only applies inside a list{" "}
+          <b>view tab</b> — declare one in <code>organise.extendedTabs</code>{" "}
+          and select it with <code>organise.viewId</code> (the tab name,
+          lowercased, spaces as underscores). On the default table view it is
+          ignored and the normal table renders.
+        </>,
+      )}
+      <DataTemplateWrapper
+        title="Orders"
+        type="list"
+        collectionId={COLLECTION}
+        schema={ORDER_SCHEMA}
+        workspace={workspace}
+        organise={{
+          breadcrumbType: "hidden",
+          viewId: "cards",
+          extendedTabs: [{ name: "Cards", type: "list", viewType: "list" }],
+        }}
+        bareSettings={{
+          bareNewDTW: true,
+          bareListComponent: (
+            rows: any[],
+            _prettierRows: any,
+            loading: boolean,
+          ) => <OrderCards rows={rows ?? []} loading={loading} />,
+        }}
+      />
+    </div>
+  );
+};
+
+export const ReadAddBelow = () => {
+  useOrderMock();
+  const [position, setPosition] = useState<"below" | "top">("below");
+  return (
+    <div>
+      {renderIntro(
+        "Add under the read view — bareReadComponent",
+        <>
+          <code>bareReadComponent(record, rawRecord)</code> renders <b>below</b>{" "}
+          the record&apos;s fields by default. Set{" "}
+          <code>bareReadComponentPos: &quot;top&quot;</code> to put it above
+          them. The default fields stay.
+        </>,
+      )}
+      <div className="mb-3">
+        <ButtonGroup
+          selection={[
+            { id: "below", name: "Below (default)" },
+            { id: "top", name: 'bareReadComponentPos: "top"' },
+          ]}
+          selectedId={position}
+          variant="tag"
+          size="small"
+          onClick={(id) => setPosition(id as "below" | "top")}
+        />
+      </div>
+      <DataTemplateWrapper
+        title="Order"
+        type="read"
+        id="o1"
+        collectionId={COLLECTION}
+        schema={ORDER_SCHEMA}
+        workspace={workspace}
+        organise={{ breadcrumbType: "hidden" }}
+        bareSettings={{
+          bareNewDTW: true,
+          bareReadComponent: (record: any) => <OrderSummary data={record} />,
+          bareReadComponentPos: position === "top" ? "top" : undefined,
+        }}
+      />
+    </div>
+  );
+};
+
+export const ReadReplace = () => {
+  useOrderMock();
+  return (
+    <div>
+      {renderIntro(
+        "Replace the read view — bareReadComponent + bareReadComponentHide",
+        <>
+          Add <code>bareReadComponentHide: true</code> and the default field
+          list is not drawn — only what <code>bareReadComponent</code> returns.
+          The action buttons are still DataTemplate&apos;s.
+        </>,
+      )}
+      <DataTemplateWrapper
+        title="Order"
+        type="read"
+        id="o3"
+        collectionId={COLLECTION}
+        schema={ORDER_SCHEMA}
+        workspace={workspace}
+        organise={{ breadcrumbType: "hidden" }}
+        bareSettings={{
+          bareNewDTW: true,
+          bareReadComponent: (record: any) => <OrderReceipt data={record} />,
+          bareReadComponentHide: true,
+        }}
+      />
+    </div>
+  );
+};
+
+export const UpdateAddBelow = () => {
+  useOrderMock();
+  const [above, setAbove] = useState(false);
+  return (
+    <div>
+      {renderIntro(
+        "Add under the update form — bareUpdateComponent",
+        <>
+          <code>bareUpdateComponent(liveData)</code> renders{" "}
+          <b>inside the form, below the fields</b> (
+          <code>bareUpdateComponentAbove</code> for above). The fields still
+          render — it adds, it does not replace. It re-runs with the <b>live</b>{" "}
+          values as you type, and the component you return keeps its own state:
+          type in Customer, press Mark checked, type again. It gets no setter —
+          to write into the form, use <code>bareUpdateIndividualComponent</code>
+          .
+        </>,
+      )}
+      <div className="mb-3">
+        <ButtonGroup
+          selection={[
+            { id: "below", name: "Below (default)" },
+            { id: "above", name: "bareUpdateComponentAbove" },
+          ]}
+          selectedId={above ? "above" : "below"}
+          variant="tag"
+          size="small"
+          onClick={(id) => setAbove(id === "above")}
+        />
+      </div>
+      <DataTemplateWrapper
+        title="Order"
+        type="update"
+        id="o1"
+        collectionId={COLLECTION}
+        schema={ORDER_SCHEMA}
+        workspace={workspace}
+        edit={{ allEditable: true }}
+        organise={{ breadcrumbType: "hidden" }}
+        bareSettings={{
+          bareNewDTW: true,
+          bareUpdateComponent: (liveData: any) => <LivePanel data={liveData} />,
+          bareUpdateComponentAbove: above,
+        }}
+        handleComplete={() => {}}
+      />
+    </div>
+  );
+};
+
+export const UpdateReplaceField = () => {
+  useOrderMock();
+  return (
+    <div>
+      {renderIntro(
+        "Replace one field — bareUpdateIndividualComponent",
+        <>
+          <code>
+            bareUpdateIndividualComponent(columnId, ref, data, setData)
+          </code>{" "}
+          is asked for every field. Return an element to replace that
+          field&apos;s input, or <code>null</code> to keep the default. It is
+          the only hook that can write into the form — here the Status list is
+          swapped for buttons that call <code>setData</code>. There is no single
+          prop that replaces the whole update form.
+        </>,
+      )}
+      <DataTemplateWrapper
+        title="Order"
+        type="update"
+        id="o2"
+        collectionId={COLLECTION}
+        schema={ORDER_SCHEMA}
+        workspace={workspace}
+        edit={{ allEditable: true }}
+        organise={{ breadcrumbType: "hidden" }}
+        bareSettings={{
+          bareNewDTW: true,
+          bareUpdateIndividualComponent: (
+            columnId: string,
+            _ref: any,
+            data: any,
+            setData: (value: any) => void,
+          ) =>
+            columnId === "status" ? (
+              <StatusPicker
+                key="status-picker"
+                value={data?.status ?? ""}
+                onChange={(value) => setData({ ...data, status: value })}
+              />
+            ) : null,
+        }}
+        handleComplete={() => {}}
+      />
+    </div>
+  );
+};
+
+export const ActionButtons = () => {
+  useOrderMock();
+  return (
+    <div>
+      {renderIntro(
+        "Replace the action buttons — bareUpdateActionComponent",
+        <>
+          <code>bareUpdateActionComponent(data, formRef)</code> <b>replaces</b>{" "}
+          the default buttons — Save and Submit in the update view, Update in
+          the read view. Call <code>formRef.current.handleSubmit()</code> to
+          submit. Return an empty fragment to remove the bar altogether. Delete
+          is controlled separately.
+        </>,
+      )}
+      <DataTemplateWrapper
+        title="Order"
+        type="update"
+        id="o1"
+        collectionId={COLLECTION}
+        schema={ORDER_SCHEMA}
+        workspace={workspace}
+        edit={{ allEditable: true }}
+        organise={{ breadcrumbType: "hidden" }}
+        bareSettings={{
+          bareNewDTW: true,
+          bareUpdateActionComponent: (_data: any, formRef: any) => (
+            <div className="flex gap-2">
+              <Button
+                text="Discard"
+                size="small"
+                type="light"
+                onClick={() => {}}
+              />
+              <Button
+                text="Submit order"
+                size="small"
+                type="normal"
+                onClick={() => formRef?.current?.handleSubmit?.()}
+              />
+            </div>
+          ),
+        }}
+        handleComplete={() => {}}
+      />
+    </div>
+  );
+};
+
+export const FullPage = () => {
+  // 1. State
+  const [viewType, setViewType] = useState<"list" | "read" | "update">("list");
+  const [selectedId, setSelectedId] = useState("");
+
+  // 2. Refs & mocks
+  useOrderMock();
+
+  // 5. handle functions
+  const handleNavigate = (type: "list" | "read" | "update", id?: string) => {
+    setViewType(type);
+    if (id !== undefined) setSelectedId(id);
+  };
+
+  // 7. return
+  return (
+    <div>
+      {renderIntro(
+        "Wire a full page — handleNavigate",
+        <>
+          DataTemplate never switches its own view. It calls{" "}
+          <code>handleNavigate(type, id)</code> and you pass the new{" "}
+          <code>type</code> and <code>id</code> back in. A row opens{" "}
+          <code>(&quot;read&quot;, id)</code>, Update is{" "}
+          <code>(&quot;update&quot;, id)</code>, Create is{" "}
+          <code>(&quot;update&quot;, &quot;new&quot;)</code>, a save lands on{" "}
+          <code>(&quot;read&quot;, id)</code> and a delete on{" "}
+          <code>(&quot;list&quot;, &quot;&quot;)</code>. Passing{" "}
+          <code>handleComplete</code> replaces the jump to read after a save.
+          The wrapper defaults <code>edit</code> to{" "}
+          <code>disabledUpdate: true</code>, so pass{" "}
+          <code>disabledUpdate: false</code> to get the Update button.
+        </>,
+      )}
+      <div id="bare-nav-state" className="mb-3 font-mono text-xs text-gray-500">
+        type={viewType} · id={selectedId || "—"}
+      </div>
+      <DataTemplateWrapper
+        title="Orders"
+        type={viewType}
+        id={selectedId}
+        collectionId={COLLECTION}
+        schema={ORDER_SCHEMA}
+        workspace={workspace}
+        edit={{ allEditable: true, disabledUpdate: false, deleteBtn: true }}
+        organise={{ breadcrumbType: "button" }}
+        bareSettings={{ bareNewDTW: true }}
+        handleNavigate={handleNavigate}
+      />
+    </div>
+  );
+};
+
+export const FilterList = () => {
+  // 1. State
+  const [status, setStatus] = useState("Submitted");
+
+  // 2. Refs & mocks
+  useOrderMock();
+
+  // 7. return
+  return (
+    <div>
+      {renderIntro(
+        "Filter the list — bareListFilterQuery",
+        <>
+          <code>
+            bareListFilterQuery: [{"{"} type: &quot;=&quot;, queryId, value{" "}
+            {"}"}]
+          </code>{" "}
+          is added to every list request, so the list only ever holds matching
+          rows and search, tabs and paging work inside them. The user cannot see
+          or clear it, and its columns are left out of the flex filter picker.
+          If the user filters the same field, their condition replaces yours.
+          The list here is keyed on the status so a change refetches.
+        </>,
+      )}
+      <div className="mb-3">
+        <ButtonGroup
+          selection={STATUS_SELECTION}
+          selectedId={status}
+          variant="tag"
+          size="small"
+          onClick={(id) => setStatus(id)}
+        />
+      </div>
+      <DataTemplateWrapper
+        key={status}
+        title="Orders"
+        type="list"
+        collectionId={COLLECTION}
+        schema={ORDER_SCHEMA}
+        workspace={workspace}
+        organise={{ breadcrumbType: "hidden" }}
+        bareSettings={{
+          bareNewDTW: true,
+          bareListFilterQuery: [
+            { type: "=", queryId: "status", value: status },
+          ],
+        }}
+      />
+    </div>
+  );
+};
+
+export const CreateWithPrefill = () => {
+  // 1. State
+  const [savedId, setSavedId] = useState("");
+
+  // 2. Refs & mocks
+  const store = useOrderMock();
+
+  // 3. Computed
+  const savedRecord = store.find((eachRow) => eachRow._id === savedId);
+
+  // 7. return
+  return (
+    <div>
+      {renderIntro(
+        "Create with fixed values — bareUpdatePrefill",
+        <>
+          Open the form on <code>type=&quot;update&quot;</code> and{" "}
+          <code>id=&quot;new&quot;</code> to create.{" "}
+          <code>bareUpdatePrefill(formData)</code> returns{" "}
+          <code>
+            [{"{"} key, value {"}"}]
+          </code>
+          : those fields are <b>taken out of the form</b> and the values are
+          written on save, so use it for values the user should not choose — a
+          status, an owner, a parent id. It is not a default the user can edit,
+          and it applies to every save from the form, not only the first. Status
+          is set to Draft here; fill the rest and save.
+        </>,
+      )}
+      <DataTemplateWrapper
+        title="New order"
+        type="update"
+        id="new"
+        collectionId={COLLECTION}
+        schema={ORDER_SCHEMA}
+        workspace={workspace}
+        edit={{ allEditable: true }}
+        organise={{ breadcrumbType: "hidden" }}
+        bareSettings={{
+          bareNewDTW: true,
+          bareUpdatePrefill: () => [{ key: "status", value: "Draft" }],
+        }}
+        handleComplete={(id) => setSavedId(id)}
+      />
+      {savedRecord && (
+        <div className="mt-4 rounded-lg border border-gray-200 bg-white p-4 text-sm">
+          <div className="font-medium text-gray-900">Saved record</div>
+          <pre
+            id="bare-saved-record"
+            className="mt-2 overflow-x-auto text-xs text-gray-700"
+          >
+            {JSON.stringify(savedRecord, null, 2)}
+          </pre>
+        </div>
+      )}
+    </div>
+  );
+};
+
+export const FormatValue = () => {
+  useOrderMock();
+  return (
+    <div>
+      {renderIntro(
+        "Format a value — bareListDescription / bareReadDescription",
+        <>
+          <code>bareListDescription(fieldId, value)</code> (table cells) and{" "}
+          <code>bareReadDescription(fieldId, value)</code> (read view) are asked
+          for every value. Return a string or an element to show instead, or{" "}
+          <code>undefined</code> to keep the default. Only a truthy return
+          replaces it, so an empty string or <code>0</code> falls back. The
+          stored value is untouched. The list version needs{" "}
+          <code>bareNewDTW</code>.
+        </>,
+      )}
+      <DataTemplateWrapper
+        title="Orders"
+        type="list"
+        collectionId={COLLECTION}
+        schema={ORDER_SCHEMA}
+        workspace={workspace}
+        organise={{ breadcrumbType: "hidden" }}
+        bareSettings={{
+          bareNewDTW: true,
+          bareListDescription: handleFormatValue,
+        }}
+      />
+      <div id="bare-format-read" className="mt-6">
+        <DataTemplateWrapper
+          title="Order"
+          type="read"
+          id="o1"
+          collectionId={COLLECTION}
+          schema={ORDER_SCHEMA}
+          workspace={workspace}
+          organise={{ breadcrumbType: "hidden" }}
+          bareSettings={{
+            bareNewDTW: true,
+            bareReadDescription: handleFormatValue,
+          }}
+        />
+      </div>
+    </div>
+  );
+};
+
+export const ValidateAndAfterSave = () => {
+  // 1. State
+  const [error, setError] = useState("");
+  const [log, setLog] = useState<string[]>([]);
+
+  // 2. Refs & mocks
+  useOrderMock();
+
+  // 5. handle functions
+  const handleCheckBeforeSave = async (data: any) => {
+    if (!(Number(data?.amount) > 0)) {
+      setError("Amount must be more than 0 — nothing was saved.");
+      return false;
+    }
+    setError("");
+    return true;
+  };
+
+  const handleAfterSave = async (data: any) => {
+    setLog((current) => [
+      ...current,
+      `Saved ${data?.orderNo} at RM ${data?.amount}`,
+    ]);
+  };
+
+  // 7. return
+  return (
+    <div>
+      {renderIntro(
+        "Check before save, act after — bareUpdateHandlePreComplete / PostComplete",
+        <>
+          <code>bareUpdateHandlePreComplete(formData)</code> runs before the
+          write. Return <code>false</code> to stop it — the saving modal just
+          closes, with <b>no message</b>, so show your own (as here). It also
+          gates delete. <code>bareUpdateHandlePostComplete(savedData)</code>{" "}
+          runs after a successful save, create or delete — use it for emails,
+          audit rows or refreshing something else. Set Amount to 0 and save,
+          then set it back and save.
+        </>,
+      )}
+      {error && (
+        <div
+          id="bare-precomplete-error"
+          className="mb-3 rounded-md border border-red-200 bg-red-50 p-3 text-sm text-red-700"
+        >
+          {error}
+        </div>
+      )}
+      <DataTemplateWrapper
+        title="Order"
+        type="update"
+        id="o2"
+        collectionId={COLLECTION}
+        schema={ORDER_SCHEMA}
+        workspace={workspace}
+        edit={{ allEditable: true }}
+        organise={{ breadcrumbType: "hidden" }}
+        bareSettings={{
+          bareNewDTW: true,
+          bareUpdateHandlePreComplete: handleCheckBeforeSave,
+          bareUpdateHandlePostComplete: handleAfterSave,
+        }}
+        handleComplete={() => {}}
+      />
+      <div className="mt-4 rounded-lg border border-gray-200 bg-white p-4 text-sm">
+        <div className="font-medium text-gray-900">After-save log</div>
+        <ul id="bare-postcomplete-log" className="mt-1 text-gray-700">
+          {log.length === 0 ? (
+            <li className="text-gray-400">Nothing saved yet</li>
+          ) : (
+            log.map((eachLine, index) => <li key={index}>{eachLine}</li>)
+          )}
+        </ul>
+      </div>
+    </div>
+  );
+};
+
+export const UnionCollections = () => {
+  useOrderMock();
+  return (
+    <div>
+      {renderIntro(
+        "Merge another collection into the list — organise.unionCollections",
+        <>
+          Each <code>unionCollections</code> entry names a second collection,
+          its own <code>query</code> and a <code>projection</code>; its rows
+          come back in the same list with a <code>source</code> field set to the
+          entry&apos;s label (or computed per row with{" "}
+          <code>source: &quot;dynamic&quot;</code> + <code>sourceLogic</code>).
+          Add a <code>source</code> column with <code>hideForm: true</code> to
+          show it. The list&apos;s own search and filters only see projected
+          fields. MongoDB workspaces only (<code>mongoServer</code>).
+        </>,
+      )}
+      <DataTemplateWrapper
+        title="Orders and returns"
+        type="list"
+        collectionId={COLLECTION}
+        schema={UNION_SCHEMA}
+        workspace={workspace}
+        organise={{
+          breadcrumbType: "hidden",
+          unionCollections: [
+            {
+              collection: RETURN_COLLECTION,
+              source: "Return",
+              query: [],
+              projection: {
+                _id: 1,
+                orderNo: 1,
+                customer: 1,
+                status: 1,
+                amount: 1,
+              },
+            },
+          ],
+        }}
+        bareSettings={{ bareNewDTW: true }}
+      />
+    </div>
+  );
+};