@jxsuite/studio 6.0.0 → 6.1.1

package/src/surfaces/add-repo.ts

@@ -3,29 +3,36 @@
  * The repository picker as a mounted document.
  *
  * `new-project/add-repo-modal.ts` is the flow — it asks the platform which repositories the account
- * link reaches, decides which of them Open Project may offer, adopts the one that was chosen and
+ * link reaches, which projects a chosen repository holds, adopts the one that was confirmed and
  * resolves the promise its two entry points return — and this is the surface it draws into: the
- * reactive scope the document reads, the one discriminant it branches on, and the mount that lives
- * in the dialog layer until the flow takes it down.
+ * reactive scope the document reads, the discriminants it branches on, and the mount that lives in
+ * the dialog layer until the flow takes it down.
+ *
+ * **Two fields, each with the list it drives.** The filter drives the repository list and the
+ * project-folder field drives the list of folders that repository holds a `project.json` in. A
+ * `jx-listbox` never takes focus (ui.md §5.3), so a list a reader can only click is a list a
+ * keyboard cannot reach; pairing each list with a field is what makes both of them operable from
+ * the keys — the palette's shape, twice. The folder field is also the answer when a list cannot be:
+ * a repository too large to scan, or a platform with no way to scan one.
  *
  * **The flow states facts; the surface derives what the document branches on.** Which repositories
- * are visible, what each row says and whether the listing has landed are the flow's; whether that
- * adds up to a list, a spinner or one of four different absences is {@link derive}'s, so neither
- * the flow nor the document has to know that "nothing matched your filter" and "the App cannot see
- * anything" are two sentences with two different remedies.
+ * are visible, which one is chosen and which folders it holds are the flow's; whether that adds up
+ * to a list, a spinner or one of four different absences, which row id each listbox is told is
+ * active, and whether the dialog can be answered yet are {@link derive}'s.
  *
  * **Await the ELEMENT, not just the mount.** `mountSurface` resolving means the DOCUMENT rendered;
  * a `jx-dialog`'s own template is one `connectedCallback` later, and `showModal` in between finds
  * no `<dialog>` to open — the body is all there, correctly styled, and never shows. `whenReady` is
  * shared with `surfaces/dialog.ts` and `surfaces/cf-account-picker.ts` rather than reimplemented.
  *
- * @docs studio/projects/create
+ * @docs studio/interface/welcome-screen
  */
 
 import { reactive } from "../reactivity";
 import { mountSurface, registerSurface } from "../ui/surface";
 import { overlayRegion, REGION_ATTR } from "../ui/regions";
 import { close as closeDialog, showModal } from "@jxsuite/ui/behaviors/dialog";
+import { focusField } from "@jxsuite/ui/behaviors/textfield";
 import { whenReady } from "./dialog";
 import addRepoDoc from "./add-repo.json";
 import type { SurfaceHandle } from "../ui/surface";
@@ -35,17 +42,23 @@ registerSurface("add-repo", addRepoDoc as unknown as JxDocument);
 
 /** One repository, as the list draws it. Every field is already a string or a flag. */
 export interface AddRepoRow {
-  /** `owner/name`, which is the row's key, its title and the text it leads with. */
+  /** `owner/name`, which is the row's key, its value, its title and the text it leads with. */
   fullName: string;
-  /** The branch and permission line beside the name. */
+  /** The default branch, beside the name. */
   meta: string;
   /** The repository already carries the Jx topic, so it gets the badge. */
   isJx: boolean;
   isPrivate: boolean;
-  /** This row is the one being adopted, so it says so. */
-  importing: boolean;
-  /** Any adoption is in flight, so no row may start another. */
-  disabled: boolean;
+}
+
+/** One folder of the chosen repository that holds a `project.json`. */
+export interface AddRepoLocation {
+  /** The folder, repository-relative and canonical; `""` is the root. The row's value. */
+  dir: string;
+  /** What the row says: the project's own name, else the folder's. */
+  label: string;
+  /** Where it is: `/` for the root, `sites/blog/` for a folder. */
+  path: string;
 }
 
 /** One way to widen what the GitHub App can reach. */
@@ -55,24 +68,50 @@ export interface AddRepoAccessLink {
   title: string;
 }
 
+/** One entry of the account filter. `""` is every account. */
+export interface AddRepoOwner {
+  value: string;
+  label: string;
+}
+
 /**
- * Why the list is empty, when it is.
+ * Why the repository list is empty, when it is.
  *
  * Four, not one, because only two of them are the reader's to fix and each is fixed differently: a
  * filter is cleared, write access is asked for, and an App that was never installed is installed.
  */
 export type AddRepoEmptyState = "filter" | "write" | "install" | "none";
 
+/**
+ * What the detail pane knows about the chosen repository's projects.
+ *
+ * - `none`: no repository is chosen yet.
+ * - `loading`: the platform is looking.
+ * - `listed`: it found at least one folder with a `project.json`.
+ * - `empty`: it looked and found none.
+ * - `unlisted`: the platform cannot look, so the folder is the reader's to name.
+ * - `failed`: the look itself failed; the folder field still works.
+ */
+export type AddRepoDetailState = "none" | "loading" | "listed" | "empty" | "unlisted" | "failed";
+
 /** What the flow knows. Every one of these may change while the dialog is up. */
 export interface AddRepoView {
   /** The headline, which is also the dialog's accessible name: the two flows name themselves. */
   title: string;
+  /** The primary answer: Open or Add, and the progressive form while an adoption runs. */
+  confirmLabel: string;
   /** The filter text, held by the flow so a repaint cannot lose what the reader typed. */
   filter: string;
+  /** The account the list is narrowed to; `""` is every account. */
+  owner: string;
+  /** The account filter's entries, "All accounts" first; empty hides it (one account, or none). */
+  owners: AddRepoOwner[];
   /** The listing is in flight. Its own state, because "not yet asked" is not "reaches nothing". */
   loading: boolean;
   /** The repositories to draw, already filtered and ordered. */
   rows: AddRepoRow[];
+  /** The chosen repository's full name; `""` when none is. It may be filtered out of `rows`. */
+  selected: string;
   /** Which absence to say, read only when `rows` is empty and the listing has landed. */
   emptyState: AddRepoEmptyState;
   /** Where the GitHub App is installed from, for the sentence that offers to install it. */
@@ -81,6 +120,30 @@ export interface AddRepoView {
   failure: string;
   /** The access footer's links; empty for a platform with no account status to widen. */
   access: AddRepoAccessLink[];
+  /** The chosen repository's projects, as far as the platform has looked. */
+  detailState: AddRepoDetailState;
+  /** The chosen repository's full name and the line beside it, for the pane's heading. */
+  detailName: string;
+  detailMeta: string;
+  /** The folders the chosen repository holds a `project.json` in. */
+  locations: AddRepoLocation[];
+  /** The folder field's text: the folder the dialog will open, `""` for the repository root. */
+  folder: string;
+  /**
+   * The same folder in its canonical spelling (`utils/project-dir.ts`), which is what a folder row
+   * is matched against: `sites/blog/` typed by hand is the `sites/blog` row.
+   */
+  chosenFolder: string;
+  /** Why the folder field's text cannot be opened; `""` when it can. */
+  folderError: string;
+  /** The sentence under the folder field. */
+  folderHelp: string;
+  /** What confirming will do, said in one line; `""` when nothing is chosen. */
+  summary: string;
+  /** The dialog can be answered: a repository is chosen, its folder is usable, nothing is running. */
+  canConfirm: boolean;
+  /** An adoption is in flight. */
+  busy: boolean;
 }
 
 export interface AddRepoSurfaceOptions {
@@ -90,8 +153,22 @@ export interface AddRepoSurfaceOptions {
   view: AddRepoView;
   /** The reader typed in the filter field. The flow decides what it hides. */
   onFilter: (value: string) => void;
-  /** A row was pressed: this repository, please. */
-  onChoose: (fullName: string) => void;
+  /** The reader narrowed the list to one account, or widened it to all of them (`""`). */
+  onOwner: (value: string) => void;
+  /** A repository row was chosen, by pointer or by the filter's arrows. */
+  onSelect: (fullName: string) => void;
+  /** The caret moved by `delta` rows through the visible repositories. */
+  onMove: (delta: number) => void;
+  /** The reader typed in the folder field. */
+  onFolder: (value: string) => void;
+  /** A folder row was chosen. */
+  onLocation: (dir: string) => void;
+  /** The caret moved by `delta` rows through the chosen repository's folders. */
+  onMoveLocation: (delta: number) => void;
+  /** Open what is chosen: the confirm button, Enter in either field, or a double-click on a row. */
+  onConfirm: () => void;
+  /** A repository row was double-clicked: choose it and open it as soon as that is unambiguous. */
+  onOpenRepo: (fullName: string) => void;
   /** Read the listing again, after access was granted in another tab. */
   onRefresh: () => void;
   /** The dialog closed, for any reason the platform owns as well as this module's `close`. */
@@ -109,43 +186,101 @@ export interface AddRepoSurfaceHandle {
   close: () => void;
 }
 
+/** A repository row with the id its listbox addresses it by. */
+interface DrawnRow extends AddRepoRow {
+  id: string;
+}
+
+/** A folder row with the id its listbox addresses it by. */
+interface DrawnLocation extends AddRepoLocation {
+  id: string;
+}
+
 /** What the document discriminates on, and the flags it reads. Derived, never handed in. */
 interface AddRepoFlags {
   /**
-   * Which body to draw.
+   * Which body the repository pane draws.
    *
    * Six, because a spinner, a list and four absences are six different things to say and only one
    * of them is fixed by looking again.
    */
   listState: "loading" | "listed" | "empty-filter" | "empty-write" | "empty-install" | "empty-none";
-  /** Whether a refusal sits above the list that survived it. */
+  rows: DrawnRow[];
+  locations: DrawnLocation[];
+  /** The id each listbox is told is active: one string per list (ui.md §5.3); `""` for none. */
+  activeRepoId: string;
+  activeLocationId: string;
+  /** Whether there is more than one account to narrow by. */
+  hasOwners: boolean;
+  /** Whether a refusal sits above the panes that survived it. */
   hasFailure: boolean;
   /** Whether there is anything to offer in the access footer. */
   hasAccess: boolean;
-  /** Refresh cannot re-ask while the answer is still coming, or while a row is being adopted. */
+  /** Whether a repository is chosen, so the folder field has something to name a folder of. */
+  hasDetail: boolean;
+  /** Whether the folder field's text is refused. */
+  folderInvalid: boolean;
+  /** Refresh cannot re-ask while the answer is still coming, or while an adoption runs. */
   refreshDisabled: boolean;
+  /** The confirm button's state, the inverse of `canConfirm`. */
+  confirmDisabled: boolean;
 }
 
-interface AddRepoScope extends Record<string, unknown>, AddRepoView, AddRepoFlags {
+interface AddRepoScope
+  extends Record<string, unknown>, Omit<AddRepoView, "rows" | "locations">, AddRepoFlags {
   setFilter: (value: string) => void;
-  choose: (fullName: string) => void;
+  setOwner: (value: string) => void;
+  select: (fullName: string) => void;
+  move: (delta: number) => void;
+  setFolder: (value: string) => void;
+  pickLocation: (dir: string) => void;
+  moveLocation: (delta: number) => void;
+  confirm: () => void;
+  openRepo: (fullName: string) => void;
   refresh: () => void;
   closed: () => void;
 }
 
+/** The id the repository list addresses row `index` by. */
+export function repoRowId(index: number): string {
+  return `add-repo-repo-${index}`;
+}
+
+/** The id the folder list addresses row `index` by. */
+export function locationRowId(index: number): string {
+  return `add-repo-location-${index}`;
+}
+
 /** The view plus the flags the document renders from. */
-function derive(view: AddRepoView): AddRepoView & AddRepoFlags {
-  const importing = view.rows.some((row) => row.importing);
+function derive(view: AddRepoView): Omit<AddRepoView, "rows" | "locations"> & AddRepoFlags {
+  const rows = view.rows.map((row, index) => ({ ...row, id: repoRowId(index) }));
+  const locations = view.locations.map((location, index) => ({
+    ...location,
+    id: locationRowId(index),
+  }));
+  const activeRow = rows.find((row) => row.fullName === view.selected);
+  const activeLocation =
+    view.folderError === ""
+      ? locations.find((location) => location.dir === view.chosenFolder)
+      : undefined;
   return {
     ...view,
+    activeLocationId: activeLocation?.id ?? "",
+    activeRepoId: activeRow?.id ?? "",
+    confirmDisabled: !view.canConfirm,
+    folderInvalid: view.folderError !== "",
     hasAccess: view.access.length > 0,
+    hasDetail: view.detailState !== "none",
     hasFailure: view.failure !== "",
+    hasOwners: view.owners.length > 0,
     listState: view.loading
       ? "loading"
-      : view.rows.length > 0
+      : rows.length > 0
         ? "listed"
         : (`empty-${view.emptyState}` as AddRepoFlags["listState"]),
-    refreshDisabled: view.loading || importing,
+    locations,
+    refreshDisabled: view.loading || view.busy,
+    rows,
   };
 }
 
@@ -177,21 +312,44 @@ export function openAddRepoSurface(options: AddRepoSurfaceOptions): AddRepoSurfa
 
   const scope = reactive({
     ...derive(options.view),
-    choose: (fullName: string) => {
-      options.onChoose(fullName);
-    },
     closed: finish,
+    confirm: () => {
+      options.onConfirm();
+    },
+    move: (delta: number) => {
+      options.onMove(delta);
+    },
+    moveLocation: (delta: number) => {
+      options.onMoveLocation(delta);
+    },
+    openRepo: (fullName: string) => {
+      options.onOpenRepo(fullName);
+    },
+    pickLocation: (dir: string) => {
+      options.onLocation(dir);
+    },
     refresh: () => {
       options.onRefresh();
     },
+    select: (fullName: string) => {
+      options.onSelect(fullName);
+    },
     setFilter: (value: string) => {
       /* What the control holds, first and unconditionally. A binding only writes when the scope
          CHANGES, so a surface that decided a value without announcing the raw one would leave the
-         field showing text the scope does not have (`studio-ui-guidelines.md` §9.3). Nothing
-         refuses a filter today; the echo is what makes a refusal possible at all. */
+         field showing text the scope does not have (`studio-ui-guidelines.md` §9.3). */
       scope.filter = value;
       options.onFilter(value);
     },
+    setFolder: (value: string) => {
+      // The same echo as the filter's, for the same reason.
+      scope.folder = value;
+      options.onFolder(value);
+    },
+    setOwner: (value: string) => {
+      scope.owner = value;
+      options.onOwner(value);
+    },
   }) as AddRepoScope;
 
   let mounted: SurfaceHandle | null = null;
@@ -207,6 +365,13 @@ export function openAddRepoSurface(options: AddRepoSurfaceOptions): AddRepoSurfa
       return element;
     }
     showModal(element);
+    /* The body claims focus (studio-ui-guidelines.md §8.7): the filter is where every way of
+       choosing starts, and the confirm button that would otherwise take it is disabled until a
+       repository is chosen, which leaves the platform nothing to land on. */
+    const filter = element.querySelector<HTMLElement>('[part="filter"]');
+    if (filter) {
+      focusField(filter);
+    }
     return element;
   });
 

package/src/surfaces/library-pane.ts

@@ -30,6 +30,7 @@
 
 import { reactive } from "../reactivity";
 import { mountSurface, registerSurface } from "../ui/surface";
+import { placeholderBrokenImages } from "../utils/edit-display";
 import libraryDoc from "./library-pane.json";
 import type { JxDocument, JxElement } from "@jxsuite/schema/types";
 import type { JxScope } from "@jxsuite/runtime/types";
@@ -267,6 +268,10 @@ export function mountLibrarySurface(
   actions: LibraryActions,
 ): LibrarySurfaceHandle {
   host.replaceChildren();
+  // A file that will not load, or a preview image with nothing to bind, draws a placeholder rather
+  // Than the browser's broken-image glyph.
+  const listening = new AbortController();
+  placeholderBrokenImages(host, listening.signal);
   const scope = reactive<LibraryScope>({
     bannerState: "hidden",
     bannerText: "",
@@ -355,6 +360,7 @@ export function mountLibrarySurface(
     },
     dispose() {
       disposed = true;
+      listening.abort();
       mounted?.dispose();
       mounted = null;
     },

package/src/surfaces/rail.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://jxsuite.com/schema/v1",
   "$id": "StudioRail",
-  "$description": "The Navigator rail: a rendering of the panel registry. The adapter hands in `groups`, every rail-able panel grouped by level with its selected state and badge, and `settingsVisible`/`settingsOpen` for the foot's gear. Nothing here is a list of panels. Each button prints its record's short `railLabel` under the glyph, falling back to `title`, and carries the full `title` as its accessible name and tooltip: the visible words lead the name a reader hears (WCAG 2.5.3), and the tooltip restores what a short label leaves out.",
+  "$description": "The Navigator rail: a rendering of the panel registry. The adapter hands in `groups`, every rail-able panel grouped by level with its selected state and badge, and, for the foot, `libraryVisible`/`libraryOpen` for the Library button and `settingsVisible`/`settingsOpen` for the gear. Nothing here is a list of panels. Each button prints its record's short `railLabel` under the glyph, falling back to `title`, and carries the full `title` as its accessible name and tooltip: the visible words lead the name a reader hears (WCAG 2.5.3), and the tooltip restores what a short label leaves out.",
   "tagName": "div",
   "attributes": {
     "part": "rail"
@@ -162,94 +162,147 @@
       "attributes": {
         "part": "foot"
       },
-      "$switch": {
-        "$ref": "#/state/settingsVisible"
-      },
-      "cases": {
-        "true": {
-          "tagName": "jx-action-button",
-          "$props": {
-            "label": "Settings",
-            "hint": "Settings",
-            "icon": "gear",
-            "stacked": true,
-            "haspopup": "menu",
-            "expanded": {
-              "$ref": "#/state/settingsOpen"
-            }
+      "children": [
+        {
+          "$switch": {
+            "$ref": "#/state/libraryVisible"
           },
+          "tagName": "div",
           "attributes": {
-            "data-rail-menu": "settings",
-            "data-expanded": "${state.settingsOpen ? '' : null}"
+            "part": "foot-library"
           },
-          "onclick": {
-            "$prototype": "Function",
-            "body": [
-              {
-                "operator": "call",
-                "target": {
-                  "$ref": "#/state/openSettings"
-                },
-                "value": [
+          "cases": {
+            "true": {
+              "tagName": "jx-action-button",
+              "$props": {
+                "label": "Library",
+                "hint": "Library",
+                "icon": "books",
+                "stacked": true,
+                "selected": {
+                  "$ref": "#/state/libraryOpen"
+                }
+              },
+              "attributes": {
+                "data-rail-action": "library.open"
+              },
+              "onclick": {
+                "$prototype": "Function",
+                "body": [
                   {
-                    "$ref": "event#/currentTarget"
+                    "operator": "call",
+                    "target": {
+                      "$ref": "#/state/openLibrary"
+                    },
+                    "value": []
                   }
                 ]
-              }
-            ]
+              },
+              "children": [
+                {
+                  "tagName": "span",
+                  "textContent": "Library"
+                }
+              ]
+            }
+          }
+        },
+        {
+          "tagName": "div",
+          "attributes": {
+            "part": "foot-settings"
           },
-          "onkeydown": {
-            "$prototype": "Function",
-            "body": [
-              {
-                "$switch": {
-                  "$ref": "event#/key"
-                },
-                "cases": {
-                  "ArrowUp": [
-                    {
-                      "operator": "call",
-                      "target": {
-                        "$ref": "#/state/openSettings"
-                      },
-                      "value": [
+          "$switch": {
+            "$ref": "#/state/settingsVisible"
+          },
+          "cases": {
+            "true": {
+              "tagName": "jx-action-button",
+              "$props": {
+                "label": "Settings",
+                "hint": "Settings",
+                "icon": "gear",
+                "stacked": true,
+                "haspopup": "menu",
+                "expanded": {
+                  "$ref": "#/state/settingsOpen"
+                }
+              },
+              "attributes": {
+                "data-rail-menu": "settings",
+                "data-expanded": "${state.settingsOpen ? '' : null}"
+              },
+              "onclick": {
+                "$prototype": "Function",
+                "body": [
+                  {
+                    "operator": "call",
+                    "target": {
+                      "$ref": "#/state/openSettings"
+                    },
+                    "value": [
+                      {
+                        "$ref": "event#/currentTarget"
+                      }
+                    ]
+                  }
+                ]
+              },
+              "onkeydown": {
+                "$prototype": "Function",
+                "body": [
+                  {
+                    "$switch": {
+                      "$ref": "event#/key"
+                    },
+                    "cases": {
+                      "ArrowUp": [
+                        {
+                          "operator": "call",
+                          "target": {
+                            "$ref": "#/state/openSettings"
+                          },
+                          "value": [
+                            {
+                              "$ref": "event#/currentTarget"
+                            }
+                          ]
+                        },
                         {
-                          "$ref": "event#/currentTarget"
+                          "preventDefault": true
                         }
-                      ]
-                    },
-                    {
-                      "preventDefault": true
-                    }
-                  ],
-                  "ArrowDown": [
-                    {
-                      "operator": "call",
-                      "target": {
-                        "$ref": "#/state/openSettings"
-                      },
-                      "value": [
+                      ],
+                      "ArrowDown": [
+                        {
+                          "operator": "call",
+                          "target": {
+                            "$ref": "#/state/openSettings"
+                          },
+                          "value": [
+                            {
+                              "$ref": "event#/currentTarget"
+                            }
+                          ]
+                        },
                         {
-                          "$ref": "event#/currentTarget"
+                          "preventDefault": true
                         }
                       ]
-                    },
-                    {
-                      "preventDefault": true
                     }
-                  ]
+                  }
+                ]
+              },
+              "children": [
+                {
+                  "tagName": "span",
+                  "textContent": "Settings"
                 }
-              }
-            ]
-          },
-          "children": [
-            {
-              "tagName": "span",
-              "textContent": "Settings"
+              ]
             }
-          ]
+          }
         }
-      }
+      ],
+      "$description": "The two rail buttons that open no Navigator panel: the Library, which is a canvas tab rather than a panel and so sits with the other exception, above the gear."
     }
   ]
 }