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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gogitcms/design-system",
-  "version": "0.16.0-next.11",
+  "version": "0.16.0-next.13",
   "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.media.test.tsx

@@ -68,6 +68,7 @@ const galleryField: EntryField = {
   type: "array",
   of: "string",
   component: "list",
+  itemComponent: "media",
   media: "uploads",
   storeAs: "public",
   value: ["/uploads/hero.png"],
@@ -89,7 +90,7 @@ test("array items render media pickers when the array names a media set", async
 });
 
 test("a list with no media set stays a plain list of inputs", () => {
-  renderWith([{ ...galleryField, media: undefined, storeAs: undefined, value: ["x"] }]);
+  renderWith([{ ...galleryField, itemComponent: undefined, media: undefined, storeAs: undefined, value: ["x"] }]);
   expect(screen.queryByTestId("media-choose")).not.toBeInTheDocument();
 });
 

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>,
   );
@@ -123,12 +129,87 @@ test("an object reference shows its embedded copies read-only and picks by key c
 
 test("an array of references renders a picker per item", async () => {
   renderWith([
-    { name: "related", label: "Related", type: "array", of: "string", component: "list", reference: authorDef, value: [ada.key, bob.key] },
+    { name: "related", label: "Related", type: "array", of: "string", component: "list", itemComponent: "reference", reference: authorDef, value: [ada.key, bob.key] },
   ]);
   expect(await screen.findAllByTestId("reference-choose")).toHaveLength(2);
   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", itemComponent: "reference", 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", itemComponent: "reference", 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";
@@ -73,21 +74,26 @@ export type EntryField = {
   source?: string;
   format?: string;
   flavor?: string;
-  // For a media picker (`component: "media"`): which configured media set to
-  // browse, and — on a string field — which form of the path to write. `media`
-  // comes from display.media, `storeAs` from display.store_as. On an array
-  // field these describe its *items*, making each one a media picker.
+  // For a media picker (`component: "media"`, or an array whose items are —
+  // `itemComponent: "media"`): which configured media set to browse, and —
+  // for a string value — which form of the path to write. Both come from the
+  // field's `media:` block; on an array they describe its *items*.
   media?: string;
   storeAs?: string;
   // For a document picker (`component: "reference"`, or an array whose items
-  // are references): what the field points at and stores. An object-shaped
-  // reference's `fields` are the derived children — the key child and the
-  // embedded copies — which the server recomputes on every save and the
-  // editor shows read-only (docs/references.md).
+  // are — `itemComponent: "reference"`): what the field points at and stores.
+  // An object-shaped reference declares its `fields` — the key child and the
+  // embedded copies — and the copies are the server's: recomputed on every
+  // save and shown read-only here (docs/references.md).
   reference?: ReferenceDef;
   value: unknown;
   // Item type for an array field (string | number | boolean | object).
   of?: string;
+  // The control each item of an array renders, from display.item.component.
+  // `list` describes the array; what an item is — a text input, a media
+  // picker, a document picker — is declared here, never inferred from the
+  // array's media or reference block. Absent means the default for `of`.
+  itemComponent?: string;
   // Child fields for an object field (or an array whose `of` is object).
   fields?: EntryField[];
   // Object shapes a mixed-list array (component: "mixedList") can hold.
@@ -373,6 +379,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,22 +1716,44 @@ 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. "Reference list" is the
+  // item's declared control, not the presence of a block: an array whose
+  // items are not declared pickers is a plain list whatever else it carries.
+  const reference = field.itemComponent === "reference" ? field.reference : undefined;
+  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
-  // render. An array that names a media set makes each item a media picker;
-  // everything else falls back to the default control for the item type.
+  // Items render the array's *declared* item control (display.item.component),
+  // not the array's own component — `list` describes the array, and is not a
+  // control an item could render. The media and reference blocks describe the
+  // items too, so they travel with the item; they never pick its control. An
+  // array that declares nothing falls back to the default control for `of`.
   const itemField: EntryField = {
     name: field.name,
     type: itemType,
     of: undefined,
     fields: field.fields,
     value: null,
-    ...(field.media ? { component: "media", media: field.media, storeAs: field.storeAs } : {}),
-    // An array that declares a reference makes each item a document picker, the
-    // same way an array naming a media set makes each item a media picker.
-    ...(field.reference ? { component: "reference", reference: field.reference } : {}),
+    component: field.itemComponent,
+    media: field.media,
+    storeAs: field.storeAs,
+    reference: field.reference,
   };
 
   // The list's own path, from the FieldControl wrapping this control; an item
@@ -1734,9 +1768,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 +5525,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/components/MediaField.tsx

@@ -61,7 +61,7 @@ export type MediaFieldProps = {
   // object field and an empty string field look identical at runtime — and
   // guessing would write the wrong shape into the document on first pick.
   shape: "string" | "object";
-  // The media set this field browses, from the config's display.media.
+  // The media set this field browses, from the config's media block.
   set?: string;
   // Which form a string field writes. Ignored for the object form, which stores
   // the asset id.
@@ -388,7 +388,7 @@ function AmbiguousNotice({
 // for an image without knowing anything about the picker UI.
 //
 // `set` defaults to the first configured set when the field names none (a body
-// field has no display.media), and the picker's own switcher covers the rest.
+// field has no media block), and the picker's own switcher covers the rest.
 export function useFieldMedia(opts: { set?: string; storeAs?: string }): {
   media: FieldMediaApi | undefined;
   picker: React.ReactNode;

package/src/components/Notifications.tsx

@@ -127,10 +127,16 @@ function NotificationRow({
   item,
   divided,
   onPress,
+  // How much of the body a row shows. Two lines suits the bell's menu, which is
+  // a glance at what happened; the full-screen list gives it more, because the
+  // body of an error notification is the error itself and a reader who opened
+  // the list to find out what went wrong has nowhere else to read it.
+  bodyLines = 2,
 }: {
   item: NotificationItem;
   divided?: boolean;
   onPress?: () => void;
+  bodyLines?: number;
 }) {
   const t = useTheme();
   const titleColor = item.level === "error" ? t.color.diffDelFg : t.color.textPrimary;
@@ -199,7 +205,9 @@ function NotificationRow({
           </View>
           <Text variant="monoSm" color="tertiary">{relativeTime(item.createdAt)}</Text>
         </View>
-        {item.body ? <InlineCode text={item.body} variant="monoSm" color={t.color.textSecondary} numberOfLines={2} /> : null}
+        {item.body ? (
+          <InlineCode text={item.body} variant="monoSm" color={t.color.textSecondary} numberOfLines={bodyLines} />
+        ) : null}
         {meta ? (
           <Text variant="monoSm" color="tertiary" numberOfLines={1}>{meta}</Text>
         ) : null}
@@ -412,6 +420,7 @@ export function NotificationList({
           item={n}
           divided={i < notifications.length - 1}
           onPress={onPressItem ? () => onPressItem(n) : undefined}
+          bodyLines={8}
         />
       ))}
     </ScrollView>

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

@@ -17,7 +17,7 @@ export interface ReferenceDef {
   key: string;
   // For the object shape, the child that holds the key ("ref" unless renamed).
   keyName: string;
-  // The embedded copies, in the order the derived children appear.
+  // The embedded copies, in the order their children are listed.
   embed: ReferenceEmbed[];
   // What deleting a referenced document does: restrict | unset.
   onDelete: string;
@@ -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.