@gogitcms/design-system 0.16.0-next.11 → 0.16.0-next.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gogitcms/design-system",
-  "version": "0.16.0-next.11",
+  "version": "0.16.0-next.12",
   "main": "src/index.ts",
   "types": "src/index.ts",
   "// exports": "The root entry is the react-native source the SPAs, desktop app and mobile app consume. ./web is the plain-DOM build for server-rendered surfaces (the Astro docs site) that don't run react-native-web, and ./css ships the tokens as custom properties. The trailing wildcard keeps deep paths resolvable — plugin bundling and the Vite aliases reach into src/ directly.",

package/src/__tests__/ContentBrowser.references.test.tsx

@@ -44,8 +44,13 @@ const embedDef: ReferenceDef = {
 
 // `null` renders without a references seam; the default is a working one.
 // (A default parameter also fires for an explicit `undefined`, so the no-seam
-// case has to be spelled `null`.)
-function renderWith(fields: EntryField[], api: ReferenceApi | null = makeApi()) {
+// case has to be spelled `null`.) `extra` is spread over the browser's props —
+// the host's open-document callback, for the tests that need one.
+function renderWith(
+  fields: EntryField[],
+  api: ReferenceApi | null = makeApi(),
+  extra: Partial<React.ComponentProps<typeof ContentBrowser>> = {},
+) {
   const onSave = jest.fn();
   const entry: CmsEntry = { id: "a", path: "content/articles/a.md", title: "Alpha", body: "", fields };
   render(
@@ -59,6 +64,7 @@ function renderWith(fields: EntryField[], api: ReferenceApi | null = makeApi())
         userInitials="ED"
         references={api ?? undefined}
         onSaveEntry={onSave}
+        {...extra}
       />
     </ThemeProvider>,
   );
@@ -129,6 +135,81 @@ test("an array of references renders a picker per item", async () => {
   expect(await screen.findByText("Bob")).toBeInTheDocument();
 });
 
+test("Add item on a reference list opens the picker and appends the pick", async () => {
+  renderWith([
+    { name: "related", label: "Related", type: "array", of: "string", component: "list", reference: authorDef, value: [ada.key] },
+  ]);
+  expect(await screen.findByText("Ada Lovelace")).toBeInTheDocument();
+
+  fireEvent.click(screen.getByTestId("list-add"));
+  // No empty slot appeared — the picker did — and the pick becomes the item.
+  expect(screen.getAllByTestId("reference-choose")).toHaveLength(1);
+  fireEvent.click(await screen.findByTestId(`reference-row-${bob.id}`));
+
+  expect(await screen.findByText("Bob")).toBeInTheDocument();
+  expect(screen.getAllByTestId("reference-choose")).toHaveLength(2);
+  expect(screen.getAllByTestId("reference-key").map((el) => el.textContent)).toEqual([ada.key, bob.key]);
+});
+
+test("Add item on a reference list without a seam is disabled rather than adding a slot", async () => {
+  renderWith(
+    [{ name: "related", label: "Related", type: "array", of: "string", component: "list", reference: authorDef, value: [] }],
+    null,
+  );
+  fireEvent.click(await screen.findByTestId("list-add"));
+  await new Promise((r) => setTimeout(r, 50));
+  expect(screen.queryByTestId("reference-choose")).not.toBeInTheDocument();
+  expect(screen.queryByText("Choose a document")).not.toBeInTheDocument();
+});
+
+test("a resolved target can be opened in a new pane, handing the document to the host", async () => {
+  const onOpenReference = jest.fn();
+  renderWith(
+    [{ name: "author", label: "Author", type: "string", component: "reference", reference: authorDef, value: ada.key }],
+    makeApi(),
+    { onOpenReference },
+  );
+  expect(await screen.findByText("Ada Lovelace")).toBeInTheDocument();
+  fireEvent.click(screen.getByTestId("reference-open"));
+  expect(onOpenReference).toHaveBeenCalledWith(
+    expect.objectContaining({ id: ada.id, collection: "authors", path: ada.path, label: "Ada Lovelace" }),
+  );
+});
+
+test("without a host that opens documents the Open action is not offered", async () => {
+  renderWith([{ name: "author", label: "Author", type: "string", component: "reference", reference: authorDef, value: ada.key }]);
+  expect(await screen.findByText("Ada Lovelace")).toBeInTheDocument();
+  expect(screen.queryByTestId("reference-open")).not.toBeInTheDocument();
+});
+
+test("the Details modal opens a reference or a referrer in a new pane and closes itself", async () => {
+  const onOpenReference = jest.fn();
+  renderWith(
+    [{ name: "author", label: "Author", type: "string", component: "reference", reference: authorDef, value: ada.key }],
+    makeApi(),
+    { onOpenReference },
+  );
+  await screen.findByText("Ada Lovelace");
+
+  fireEvent.click(screen.getByTestId("detail-menu"));
+  fireEvent.click(screen.getByTestId("detail-details"));
+  const refs = await screen.findByTestId("details-references");
+  await waitFor(() => expect(refs).toHaveTextContent("Ada Lovelace"));
+  fireEvent.click(screen.getByTestId(`details-open-${ada.id}`));
+  expect(onOpenReference).toHaveBeenLastCalledWith(expect.objectContaining({ id: ada.id, collection: "authors" }));
+  expect(screen.queryByTestId("document-details")).not.toBeInTheDocument();
+
+  fireEvent.click(screen.getByTestId("detail-menu"));
+  fireEvent.click(screen.getByTestId("detail-details"));
+  const referrers = await screen.findByTestId("details-referrers");
+  await waitFor(() => expect(referrers).toHaveTextContent("Other"));
+  fireEvent.click(screen.getByTestId("details-open-d2"));
+  expect(onOpenReference).toHaveBeenLastCalledWith(
+    expect.objectContaining({ id: "d2", collection: "articles", path: "content/articles/other.md", label: "Other" }),
+  );
+  expect(screen.queryByTestId("document-details")).not.toBeInTheDocument();
+});
+
 test("the Details modal shows the document's metadata and its references both ways", async () => {
   renderWith([
     { name: "title", label: "Title", type: "string", value: "Alpha" },

package/src/components/ContentBrowser.tsx

@@ -32,9 +32,10 @@ import {
 } from "./CollabField";
 import { clamp, reorder, slotAtX } from "./reorder";
 import { MediaField, MediaProvider, DocumentPathProvider, useFieldMedia } from "./MediaField";
-import { ReferenceField, ReferenceProvider } from "./ReferenceField";
+import { ReferenceField, ReferencePicker, ReferenceProvider, useReferenceApi } from "./ReferenceField";
 import { DocumentDetails } from "./DocumentDetails";
-import type { ReferenceApi, ReferenceDef } from "../references";
+import type { ReferenceApi, ReferenceDef, ReferenceDocument, ReferenceTarget } from "../references";
+import { referenceValue } from "../references";
 import { MediaBrowser } from "./MediaBrowser";
 import { FormsBrowser } from "./FormsBrowser";
 import { FORMS_NAV_KEY, formsNavKey, isFormsNavKey, parseFormsNavKey, type FormsApi } from "../forms";
@@ -373,6 +374,12 @@ export type ContentBrowserProps = {
   // the document picker and the "Referenced by" list, the host owns fetching.
   // Omitted → reference fields render read-only.
   references?: ReferenceApi;
+  // Open a referenced document — the Open action on a reference field's target
+  // and on the rows of the Details modal. The document may belong to any
+  // collection, so the host, which owns the open columns and the URL, does the
+  // opening (a new column on desktop, in place on mobile). Omitted, the action
+  // is not offered.
+  onOpenReference?: (doc: ReferenceDocument) => void;
 
   // Forms data seam, the same split (docs/forms.md §10.2). Omitted → the Forms
   // surface never renders, which is what a config declaring no forms looks like.
@@ -1704,7 +1711,26 @@ function ListControl({
     [next[i], next[j]] = [next[j], next[i]];
     onChange(next);
   };
-  const addItem = () => onChange([...items, isObject ? {} : ""]);
+  // A reference list's "Add item" opens the picker straight away and appends
+  // what was picked: the only thing such an item can hold is a picked
+  // document, so an empty slot to fill in afterwards is a step nobody wants.
+  // Without a host seam there is nothing to pick from, and the button is
+  // disabled as the field's own Choose button is.
+  const reference = field.reference;
+  const referenceApi = useReferenceApi();
+  const [pickingNew, setPickingNew] = React.useState(false);
+  const addItem = () => {
+    if (reference) {
+      if (referenceApi) setPickingNew(true);
+      return;
+    }
+    onChange([...items, isObject ? {} : ""]);
+  };
+  const addPicked = (target: ReferenceTarget) => {
+    setPickingNew(false);
+    if (!reference) return;
+    onChange([...items, referenceValue(target, isObject ? "object" : "string", reference, undefined)]);
+  };
 
   // Items inherit the array's *item-level* display config, not the array's own
   // component — `list` describes the array, and is not a control an item could
@@ -1734,9 +1760,20 @@ function ListControl({
       ))}
       {!readOnly && canAdd ? (
         <View style={{ alignSelf: "flex-start" }}>
-          <Button title="Add item" variant="default" size="sm" iconLeft="plus" onPress={addItem} testID="list-add" />
+          <Button
+            title="Add item"
+            variant="default"
+            size="sm"
+            iconLeft="plus"
+            onPress={addItem}
+            disabled={!!reference && !referenceApi}
+            testID="list-add"
+          />
         </View>
       ) : null}
+      {reference ? (
+        <ReferencePicker visible={pickingNew} onClose={() => setPickingNew(false)} onSelect={addPicked} def={reference} />
+      ) : null}
     </View>
   );
 }
@@ -5480,7 +5517,7 @@ export function ContentBrowser(props: ContentBrowserProps) {
   // object store) renders media fields read-only.
   return (
     <MediaProvider api={props.media}>
-      <ReferenceProvider api={props.references}>
+      <ReferenceProvider api={props.references} onOpen={props.onOpenReference}>
         {isDesktop ? <DesktopBrowser {...withSections} /> : <MobileBrowser {...withSections} />}
       </ReferenceProvider>
     </MediaProvider>

package/src/index.ts

@@ -173,14 +173,15 @@ export type {
 } from "./media";
 
 // References: the document picker, "referenced by", and the host data seam
-export { ReferenceField, ReferencePicker, ReferenceProvider, useReferenceApi } from "./components/ReferenceField";
-export type { ReferenceFieldProps, ReferencePickerProps } from "./components/ReferenceField";
+export { ReferenceField, ReferencePicker, ReferenceProvider, useReferenceApi, useOpenReference } from "./components/ReferenceField";
+export type { ReferenceFieldProps, ReferencePickerProps, OpenReference } from "./components/ReferenceField";
 export { DocumentDetails, collectSites } from "./components/DocumentDetails";
 export type { DocumentDetailsProps, DetailsField } from "./components/DocumentDetails";
 export { DEFAULT_REFERENCE_KEY_NAME, referenceKey, referenceValue } from "./references";
 export type {
   ReferenceApi,
   ReferenceDef,
+  ReferenceDocument,
   ReferenceEmbed,
   ReferenceTarget,
   ReferenceResolution,

package/src/references.ts

@@ -38,6 +38,16 @@ export interface ReferenceTarget {
   label: string;
 }
 
+// ReferenceDocument is what opening a document needs: enough to name it, the
+// collection it belongs to (an open column's context), and its path (its
+// address). A ReferenceTarget and a Referrer both satisfy it.
+export interface ReferenceDocument {
+  id: string;
+  collection: string;
+  path: string;
+  label: string;
+}
+
 // ReferenceResolution is the answer to "what does this stored key name?".
 // `target` null with `ambiguous` false is a dangling reference; `ambiguous`
 // means a field key several documents share, and `candidates` holds them.