@jxsuite/studio 2.0.0 → 2.1.0

package/src/panels/welcome-screen.ts

@@ -1,16 +1,28 @@
 /// <reference lib="dom" />
 /**
- * Welcome screen — shown when no project is loaded and no document tabs are open. Mimics VS Code's
- * welcome tab with start actions and recent projects.
+ * Start pane — the pane-grid surface shown when no project is loaded and no document tabs are open.
+ *
+ * Three regions, in the order a first run needs them: **Start** (the ways to get a project in front
+ * of you), **Recent** (projects you have opened, identified by name + the folder that tells two
+ * same-named projects apart + when you last opened them), and **Projects** (the catalogue a cloud
+ * platform enumerates). A repository-access prompt sits above them when the account has no GitHub
+ * App installation yet, because nothing else on the pane can succeed until it does.
+ *
+ * Recents never render a raw absolute path: `recentLocations()` gives every row the shortest
+ * trailing path that distinguishes it from the other rows sharing its name.
+ *
+ * @docs studio/interface/welcome-screen
  */
 
 import { html, render as litRender, nothing } from "lit-html";
 import { getAccountStatus, needsAppInstall } from "../account-status";
 import { platformSupportsAddRepo } from "../new-project/add-repo-modal";
 import { getProjectList } from "../project-list";
+import { now } from "../services/clock";
 import { clearRecentProjects, getRecentProjects, removeRecentProject } from "../recent-projects";
 import { renderOnly } from "../store";
 import { platformSupportsClone } from "./git-panel";
+import type { TemplateResult } from "lit-html";
 
 interface WelcomeCtx {
   openProject: () => void;
@@ -27,217 +39,308 @@ export function initWelcome(ctx: WelcomeCtx) {
   _ctx = ctx;
 }
 
+// ─── Location labels ──────────────────────────────────────────────────────────
+
+/** Home-relative form of an absolute path (`/home/you/x` → `~/x`); other paths are unchanged. */
+export function shortenPath(path: string): string {
+  const match = /^\/(?:home|Users)\/[^/]+(?=\/|$)/.exec(path);
+  return match ? `~${path.slice(match[0].length)}` : path;
+}
+
+/** The ancestor segments of a root, home-shortened — everything above the project folder itself. */
+function ancestorSegments(root: string): string[] {
+  const segments = shortenPath(root).split("/").filter(Boolean);
+  return segments.slice(0, -1);
+}
+
+/**
+ * The last `depth` ancestor folders of a root, as a path. Truncated labels lead with `…/`; a
+ * complete absolute one keeps its leading `/`, so the string always says how much it is showing.
+ */
+function ancestorLabel(root: string, depth: number): string {
+  const segments = ancestorSegments(root);
+  if (segments.length === 0) {
+    return shortenPath(root);
+  }
+  const tail = segments.slice(Math.max(0, segments.length - depth));
+  if (tail.length < segments.length) {
+    return `…/${tail.join("/")}`;
+  }
+  return tail[0] === "~" || !root.startsWith("/") ? tail.join("/") : `/${tail.join("/")}`;
+}
+
+/**
+ * The location line for each entry: the shortest trailing path that tells apart the entries sharing
+ * a display name. One folder deep is enough for almost every list; same-named projects under the
+ * same parent fall back to their whole home-shortened root, which is unique because roots are.
+ *
+ * @param entries Projects to label, in any order.
+ * @returns Root → location label, one entry per distinct root.
+ */
+export function recentLocations(
+  entries: readonly { name: string; root: string }[],
+): Map<string, string> {
+  const groups = new Map<string, { name: string; root: string }[]>();
+  for (const entry of entries) {
+    const group = groups.get(entry.name);
+    if (group) {
+      group.push(entry);
+    } else {
+      groups.set(entry.name, [entry]);
+    }
+  }
+
+  const labels = new Map<string, string>();
+  for (const group of groups.values()) {
+    const maxDepth = Math.max(...group.map((e) => ancestorSegments(e.root).length), 1);
+    let chosen = group.map((e) => ancestorLabel(e.root, maxDepth));
+    for (let depth = 1; depth <= maxDepth; depth++) {
+      const candidate = group.map((e) => ancestorLabel(e.root, depth));
+      if (new Set(candidate).size === group.length) {
+        chosen = candidate;
+        break;
+      }
+    }
+    if (new Set(chosen).size !== group.length) {
+      chosen = group.map((e) => shortenPath(e.root));
+    }
+    for (const [index, entry] of group.entries()) {
+      labels.set(entry.root, chosen[index]!);
+    }
+  }
+  return labels;
+}
+
+const MINUTE = 60_000;
+const HOUR = 60 * MINUTE;
+const DAY = 24 * HOUR;
+
+/**
+ * "When you last opened it", in the coarse units a project list is read in. Deliberately vague past
+ * a week — the exact timestamp is in the row's tooltip.
+ *
+ * @param timestamp Epoch milliseconds.
+ * @param at Epoch milliseconds to measure against. Defaults to the {@link now} seam, so a pinned
+ *   clock makes "last opened" answer the same on every read.
+ */
+export function lastOpenedLabel(timestamp: number, at: number = now()): string {
+  const elapsed = Math.max(0, at - timestamp);
+  if (elapsed < MINUTE) {
+    return "just now";
+  }
+  if (elapsed < HOUR) {
+    const minutes = Math.floor(elapsed / MINUTE);
+    return `${minutes} minute${minutes === 1 ? "" : "s"} ago`;
+  }
+  if (elapsed < DAY) {
+    const hours = Math.floor(elapsed / HOUR);
+    return `${hours} hour${hours === 1 ? "" : "s"} ago`;
+  }
+  const days = Math.floor(elapsed / DAY);
+  if (days === 1) {
+    return "yesterday";
+  }
+  if (days < 30) {
+    return `${days} days ago`;
+  }
+  const months = Math.floor(days / 30);
+  return months < 12 ? `${months} month${months === 1 ? "" : "s"} ago` : "over a year ago";
+}
+
+// ─── Templates ────────────────────────────────────────────────────────────────
+
+/** One Start-list command: a labelled, icon-led action button. */
+function startActionTpl(label: string, icon: TemplateResult, run: () => void): TemplateResult {
+  return html`
+    <sp-action-button class="welcome-action" quiet size="m" @click=${run}>
+      ${icon} ${label}
+    </sp-action-button>
+  `;
+}
+
+function startSectionTpl(ctx: WelcomeCtx): TemplateResult {
+  return html`
+    <section class="welcome-section">
+      <h2 class="welcome-section-title">Start</h2>
+      <div class="welcome-actions">
+        ${
+          // One entry, not two: the starter gallery IS the first step of New Project now, so the
+          // Separate "Start from an Example…" button it used to hide behind is gone.
+          startActionTpl("New Project…", html`<sp-icon-add slot="icon"></sp-icon-add>`, () =>
+            ctx.openNewProject(),
+          )
+        }
+        ${startActionTpl(
+          "Open Project…",
+          html`<sp-icon-folder-open slot="icon"></sp-icon-folder-open>`,
+          () => ctx.openProject(),
+        )}
+        ${
+          platformSupportsClone()
+            ? startActionTpl(
+                "Clone Git Repository…",
+                html`<sp-icon-download slot="icon"></sp-icon-download>`,
+                () => ctx.cloneRepository(),
+              )
+            : nothing
+        }
+        ${
+          platformSupportsAddRepo()
+            ? startActionTpl(
+                "Add Existing Repository…",
+                html`<sp-icon-box slot="icon"></sp-icon-box>`,
+                () => ctx.addExistingRepo(),
+              )
+            : nothing
+        }
+      </div>
+    </section>
+  `;
+}
+
+/**
+ * The GitHub-App install prompt. Gated on `needsAppInstall()`: the account is connected, reports
+ * zero installations, and told us where to fix that — the recovery path for the structured
+ * needs-installation 403 that `platform-errors.ts` decodes.
+ */
+function appInstallTpl(): TemplateResult {
+  return html`
+    <section class="welcome-section">
+      <h2 class="welcome-section-title">Repository access</h2>
+      <div class="welcome-actions">
+        <sp-action-button
+          class="welcome-action"
+          quiet
+          size="m"
+          href=${getAccountStatus()?.appInstallUrl ?? "#"}
+          target="_blank"
+          rel="noreferrer"
+        >
+          <sp-icon-link slot="icon"></sp-icon-link>
+          Install the Jx Suite GitHub App
+        </sp-action-button>
+      </div>
+      <p class="welcome-install-note">
+        Grants repository access so you can create and open projects — choose “All repositories”.
+      </p>
+    </section>
+  `;
+}
+
+/** One row of the Recent list: the project, its distinguishing folder, and when it was last open. */
+function recentRowTpl(
+  ctx: WelcomeCtx,
+  entry: { name: string; root: string; timestamp: number },
+  location: string,
+): TemplateResult {
+  return html`
+    <li class="welcome-recent-row">
+      <button
+        class="welcome-recent"
+        title=${entry.root}
+        @click=${() => ctx.openRecentProject(entry.root)}
+      >
+        <span class="welcome-recent-name">${entry.name}</span>
+        <span class="welcome-recent-path">${location}</span>
+        <span class="welcome-recent-when">${lastOpenedLabel(entry.timestamp)}</span>
+      </button>
+      <sp-action-button
+        class="welcome-recent-remove"
+        quiet
+        size="s"
+        label="Remove ${entry.name} from Recent"
+        @click=${() => {
+          removeRecentProject(entry.root);
+          renderOnly("canvas");
+        }}
+      >
+        <sp-icon-close slot="icon"></sp-icon-close>
+      </sp-action-button>
+    </li>
+  `;
+}
+
+function recentSectionTpl(
+  ctx: WelcomeCtx,
+  recent: readonly { name: string; root: string; timestamp: number }[],
+): TemplateResult {
+  const locations = recentLocations(recent);
+  return html`
+    <section class="welcome-section">
+      <div class="welcome-section-header">
+        <h2 class="welcome-section-title">Recent</h2>
+        <sp-action-button
+          class="welcome-clear"
+          quiet
+          size="s"
+          @click=${() => {
+            clearRecentProjects();
+            renderOnly("canvas");
+          }}
+        >
+          Clear all
+        </sp-action-button>
+      </div>
+      <ul class="welcome-list">
+        ${recent.map((entry) => recentRowTpl(ctx, entry, locations.get(entry.root) ?? entry.root))}
+      </ul>
+    </section>
+  `;
+}
+
+/**
+ * Projects the platform enumerates that are not already in Recent. Cloud catalogues carry their own
+ * one-line description; anything else gets the same location treatment the recents get.
+ */
+function catalogueSectionTpl(
+  ctx: WelcomeCtx,
+  catalogue: readonly { name: string; root: string; description?: string | undefined }[],
+): TemplateResult {
+  const locations = recentLocations(catalogue);
+  return html`
+    <section class="welcome-section">
+      <h2 class="welcome-section-title">Projects</h2>
+      <ul class="welcome-list">
+        ${catalogue.map(
+          (project) => html`
+            <li class="welcome-recent-row">
+              <button
+                class="welcome-recent welcome-catalogue"
+                title=${project.root}
+                @click=${() => ctx.openRecentProject(project.root)}
+              >
+                <span class="welcome-recent-name">${project.name}</span>
+                <span class="welcome-recent-path">
+                  ${project.description ?? locations.get(project.root) ?? project.root}
+                </span>
+              </button>
+            </li>
+          `,
+        )}
+      </ul>
+    </section>
+  `;
+}
+
 /** @param {HTMLElement} host */
 export function renderWelcome(host: HTMLElement) {
   const ctx = _ctx as WelcomeCtx;
   const recent = getRecentProjects();
   // Catalogue entries already in Recent stay in that section only.
   const catalogue = getProjectList().filter((p) => !recent.some((r) => r.root === p.root));
-  const showClone = platformSupportsClone();
-  const showAddRepo = platformSupportsAddRepo();
 
   litRender(
     html`
       <div class="welcome-screen">
         <div class="welcome-content">
           <h1 class="welcome-title">Jx Studio</h1>
-          <p class="welcome-subtitle">Visual component builder</p>
-
-          <div class="welcome-section">
-            <h2 class="welcome-section-title">Start</h2>
-            <button class="welcome-action" @click=${() => ctx.openNewProject()}>
-              <svg
-                class="welcome-action-icon"
-                width="16"
-                height="16"
-                viewBox="0 0 16 16"
-                fill="currentColor"
-              >
-                <path
-                  d="M9.5 1.1l3.4 3.5.1.4v2h-1V6H8.5L8 5.5V2H3.5l-.5.5v11l.5.5H6v1H3.5l-1.5-1.5v-11l1.5-1.5h5.7l.3.1zM9 2v3h2.9L9 2zm4 14h-1v-3H9v-1h3V9h1v3h3v1h-3v3z"
-                />
-              </svg>
-              New Project...
-            </button>
-            <button class="welcome-action" @click=${() => ctx.openNewProject({ tab: "starter" })}>
-              <svg
-                class="welcome-action-icon"
-                width="16"
-                height="16"
-                viewBox="0 0 16 16"
-                fill="currentColor"
-              >
-                <path
-                  d="M1 1h6v6H1V1zm1 1v4h4V2H2zm7-1h6v6H9V1zm1 1v4h4V2h-4zM1 9h6v6H1V9zm1 1v4h4v-4H2zm7-1h6v6H9V9zm1 1v4h4v-4h-4z"
-                />
-              </svg>
-              Start from an Example...
-            </button>
-            <button class="welcome-action" @click=${() => ctx.openProject()}>
-              <svg
-                class="welcome-action-icon"
-                width="16"
-                height="16"
-                viewBox="0 0 16 16"
-                fill="currentColor"
-              >
-                <path
-                  d="M14.5 3H7.71l-.85-.85L6.51 2h-5l-.5.5v11l.5.5h13l.5-.5v-10L14.5 3zm-.51 8.49V13h-12V7h4.49l.35-.15.86-.86H14v5.5zM6.51 6l-.35.15-.86.86H2v-3h4.29l.85.85.36.15H14V6H6.51z"
-                />
-              </svg>
-              Open Project...
-            </button>
-            ${
-              showClone
-                ? html`<button class="welcome-action" @click=${() => ctx.cloneRepository()}>
-                    <svg
-                      class="welcome-action-icon"
-                      width="16"
-                      height="16"
-                      viewBox="0 0 16 16"
-                      fill="currentColor"
-                    >
-                      <path
-                        d="M4.7 12.3a4.2 4.2 0 0 1-1.2-1.7A4.4 4.4 0 0 1 3 8.9a4 4 0 0 1 .3-1.5 3.8 3.8 0 0 1 .8-1.3c.4-.4.8-.7 1.3-.9.5-.2 1-.4 1.6-.4V3l3.5 2.5L7 8V6.2c-.9.1-1.6.5-2.1 1.1a3 3 0 0 0-.8 2.1c0 .4.1.8.2 1.2.1.3.3.7.5 1l-.1.7zM11 6.9c.9-.1 1.6-.5 2.1-1.1a3 3 0 0 0 .8-2.1 3 3 0 0 0-.2-1.2 3.5 3.5 0 0 0-.5-1l.1-.7a4.2 4.2 0 0 1 1.2 1.7c.3.5.4 1.1.4 1.7a4 4 0 0 1-.3 1.5 3.8 3.8 0 0 1-.8 1.3c-.4.4-.8.7-1.3.9-.5.2-1 .4-1.6.4V11L7.5 8.5 11 6v.9z"
-                      />
-                    </svg>
-                    Clone Git Repository...
-                  </button>`
-                : nothing
-            }
-            ${
-              showAddRepo
-                ? html`<button class="welcome-action" @click=${() => ctx.addExistingRepo()}>
-                    <svg
-                      class="welcome-action-icon"
-                      width="16"
-                      height="16"
-                      viewBox="0 0 16 16"
-                      fill="currentColor"
-                    >
-                      <path
-                        d="M2 2.5A2.5 2.5 0 0 1 4.5 0h8.75a.75.75 0 0 1 .75.75v12.5a.75.75 0 0 1-.75.75h-2.5a.75.75 0 0 1 0-1.5h1.75v-2h-8a1 1 0 0 0-.714 1.7.75.75 0 1 1-1.072 1.05A2.495 2.495 0 0 1 2 11.5Zm10.5-1h-8a1 1 0 0 0-1 1v6.708A2.5 2.5 0 0 1 4.5 9h8ZM5 12.25a.25.25 0 0 1 .25-.25h3.5a.25.25 0 0 1 .25.25v3.25a.25.25 0 0 1-.4.2l-1.45-1.087a.25.25 0 0 0-.3 0L5.4 15.7a.25.25 0 0 1-.4-.2Z"
-                      />
-                    </svg>
-                    Add Existing Repository...
-                  </button>`
-                : nothing
-            }
-          </div>
-
-          ${
-            needsAppInstall()
-              ? html`
-                  <div class="welcome-section">
-                    <h2 class="welcome-section-title">Repository access</h2>
-                    <a
-                      class="welcome-action"
-                      href=${getAccountStatus()?.appInstallUrl ?? "#"}
-                      target="_blank"
-                      rel="noreferrer"
-                    >
-                      <svg
-                        class="welcome-action-icon"
-                        width="16"
-                        height="16"
-                        viewBox="0 0 16 16"
-                        fill="currentColor"
-                      >
-                        <path
-                          d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27s1.36.09 2 .27c1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.01 8.01 0 0 0 16 8c0-4.42-3.58-8-8-8z"
-                        />
-                      </svg>
-                      Install the Jx Suite GitHub App
-                    </a>
-                    <p class="welcome-install-note">
-                      Grants repository access so you can create and open projects — choose “All
-                      repositories”.
-                    </p>
-                  </div>
-                `
-              : nothing
-          }
-          ${
-            catalogue.length > 0
-              ? html`
-                  <div class="welcome-section">
-                    <h2 class="welcome-section-title">Projects</h2>
-                    ${catalogue.map(
-                      (p) => html`
-                        <div class="welcome-recent-row">
-                          <button
-                            class="welcome-recent welcome-catalogue"
-                            @click=${() => ctx.openRecentProject(p.root)}
-                            title=${p.root}
-                          >
-                            <span class="welcome-recent-name">${p.name}</span>
-                            <span class="welcome-recent-path">
-                              ${p.description ?? shortenPath(p.root)}
-                            </span>
-                          </button>
-                        </div>
-                      `,
-                    )}
-                  </div>
-                `
-              : nothing
-          }
-          ${
-            recent.length > 0
-              ? html`
-                  <div class="welcome-section">
-                    <div class="welcome-section-header">
-                      <h2 class="welcome-section-title">Recent</h2>
-                      <button
-                        class="welcome-clear"
-                        @click=${() => {
-                          clearRecentProjects();
-                          renderOnly("canvas");
-                        }}
-                      >
-                        Clear
-                      </button>
-                    </div>
-                    ${recent.map(
-                      (p) => html`
-                        <div class="welcome-recent-row">
-                          <button
-                            class="welcome-recent"
-                            @click=${() => ctx.openRecentProject(p.root)}
-                            title=${p.root}
-                          >
-                            <span class="welcome-recent-name">${p.name}</span>
-                            <span class="welcome-recent-path">${shortenPath(p.root)}</span>
-                          </button>
-                          <button
-                            class="welcome-recent-remove"
-                            title="Remove from recent"
-                            @click=${() => {
-                              removeRecentProject(p.root);
-                              renderOnly("canvas");
-                            }}
-                          >
-                            ✕
-                          </button>
-                        </div>
-                      `,
-                    )}
-                  </div>
-                `
-              : nothing
-          }
+          <p class="welcome-subtitle">Design, build, and publish websites</p>
+          ${startSectionTpl(ctx)} ${needsAppInstall() ? appInstallTpl() : nothing}
+          ${recent.length > 0 ? recentSectionTpl(ctx, recent) : nothing}
+          ${catalogue.length > 0 ? catalogueSectionTpl(ctx, catalogue) : nothing}
         </div>
       </div>
     `,
     host,
   );
 }
-
-/** @param {string} path */
-function shortenPath(path: string) {
-  if (path.startsWith("/home/")) {
-    const parts = path.split("/");
-    return `~/${parts.slice(3).join("/")}`;
-  }
-  return path;
-}

package/src/platform-errors.ts

@@ -4,21 +4,44 @@
  * "needs_installation_access"` + `installUrl`); adapters preserve them on the thrown Error via
  * `Object.assign`, and UI surfaces recover them here to render actions (an install link) instead of
  * plain text.
+ *
+ * **RFC 9457 reconciles cleanly with this, because a problem's `type` IS the code.** A backend
+ * answering `type: "https://jxsuite.com/problems/needs-installation-access"` is saying exactly what
+ * `code: "needs_installation_access"` said; `problemSlug` derives the one from the other, and
+ * `installUrl` is the extension member (§3.2) that type documents. So this module reads both, and
+ * every surface above it keeps branching on `code` without knowing which shape arrived.
  */
 
+import { problemSlug } from "@jxsuite/protocol";
+
 export interface PlatformErrorInfo {
   code?: string;
   installUrl?: string;
 }
 
+/**
+ * The slug spelling of a code, so a hyphenated problem type and an underscored legacy code compare
+ * equal. The two spellings exist because the type is a URI path segment and the code was a JS-ish
+ * identifier; neither is worth migrating the other to while both are on the wire.
+ */
+function normalizeCode(value: string): string {
+  return value.replaceAll("_", "-");
+}
+
 /** Machine-readable fields carried by a thrown platform error (empty object when none). */
 export function platformErrorInfo(error: unknown): PlatformErrorInfo {
   if (!error || typeof error !== "object") {
     return {};
   }
-  const { code, installUrl } = error as { code?: unknown; installUrl?: unknown };
+  const { code, installUrl, type } = error as {
+    code?: unknown;
+    installUrl?: unknown;
+    type?: unknown;
+  };
+  // A problem type wins over a legacy code: it is the shape the backend is migrating toward.
+  const derived = problemSlug(type) ?? (typeof code === "string" ? normalizeCode(code) : null);
   return {
-    ...(typeof code === "string" ? { code } : {}),
+    ...(derived === null ? {} : { code: derived }),
     ...(typeof installUrl === "string" ? { installUrl } : {}),
   };
 }
@@ -26,5 +49,5 @@ export function platformErrorInfo(error: unknown): PlatformErrorInfo {
 /** The GitHub-App install link when the error is the structured needs-installation 403. */
 export function installUrlOf(error: unknown): string | null {
   const info = platformErrorInfo(error);
-  return info.code === "needs_installation_access" && info.installUrl ? info.installUrl : null;
+  return info.code === "needs-installation-access" && info.installUrl ? info.installUrl : null;
 }