@jxsuite/studio 4.0.0 → 5.0.0

package/src/surfaces/panel-problems.json

@@ -0,0 +1,497 @@
+{
+  "$schema": "https://jxsuite.com/schema/v1",
+  "$id": "StudioPanelProblems",
+  "$description": "The Bottom dock's Problems tab: everything that must be fixed, listed until it is. The adapter hands in one projection per row — its severity glyph, its message, the file it names, the captured log, and, where a recovery command exists, that command's own title and gate — grouped under the source that raised them in first-seen order. Nothing here reads the notification store or the command registry; a row asks the host to open, to run, or to dismiss, by the id it was given.",
+  "tagName": "div",
+  "attributes": {
+    "part": "panel"
+  },
+  "style": {
+    "$description": "What `.problems-panel`, `.problems-clear`, `.problem-group`, `.problem-group-title`, `.problem-list`, `.problem-row`, `.problem-icon`, `.problem-body`, `.problem-message`, `.problem-path`, `.problem-detail`, `.problem-action` and `.problem-dismiss` said in `styles/panels.css`, keyed on `part` and re-pointed at the studio token layer. Six of those rules are SHARED SELECTORS — `.problems-clear, .activity-clear` and five `.problem-*, .activity-*` pairs — so this document carries its own copy rather than moving one: the `.problem-*` half of each pair is dead the moment this lands, and the stylesheet rule itself can only go when the Activity panel has moved too. Nothing is deleted from `styles/panels.css` here. Three token names could not come with the declarations: `var(--spectrum-font-size-50, 11px)` (the Clear button, the group heading, the path and the log), `var(--spectrum-font-size-75, 12px)` (the row) and `var(--spectrum-corner-radius-75, 2px)` (three rules). Every one of them resolves only inside `<sp-theme>`, and a document mounted in the dock body would have taken the hard-coded fallback every time, so they are the kit's `--jx-text-sm`, `--jx-text-md` and `--jx-radius-xs` instead.",
+    "display": "flex",
+    "flexDirection": "column",
+    "minHeight": "0",
+    "fontFamily": "var(--jx-font-sans)",
+    "color": "var(--fg)",
+    "& [part=\"body\"]": {
+      "display": "flex",
+      "flexDirection": "column",
+      "gap": "var(--jx-space-3)",
+      "padding": "var(--jx-space-3)"
+    },
+    "& [part=\"actions\"]": {
+      "display": "flex",
+      "justifyContent": "flex-end"
+    },
+    "& [part=\"clear\"] > [part=\"control\"]": {
+      "$description": "Bordered but unfilled, and dimmed until it is wanted: emptying the list is the one destructive control on this surface and it sits above rows the reader has not finished reading yet.",
+      "padding": "0 var(--jx-space-3)",
+      "border": "1px solid var(--border)",
+      "borderRadius": "var(--jx-radius-xs)",
+      "background": "transparent",
+      "color": "var(--fg-dim)",
+      "fontSize": "var(--jx-text-sm)",
+      ":hover": {
+        "color": "var(--fg)",
+        "background": "var(--hover-bg)"
+      }
+    },
+    "& [part=\"group\"]": {
+      "$description": "One source's rows, under its heading. A section rather than a run of rows so the heading and the problems it names cannot be separated by a scroll position.",
+      "display": "flex",
+      "flexDirection": "column",
+      "gap": "var(--jx-space-2)"
+    },
+    "& [part=\"group-title\"]": {
+      "margin": "0 0 var(--jx-space-1)",
+      "color": "var(--fg-dim)",
+      "fontSize": "var(--jx-text-sm)",
+      "fontWeight": "700",
+      "textTransform": "uppercase",
+      "letterSpacing": "0.04em"
+    },
+    "& [part=\"list\"]": {
+      "display": "flex",
+      "flexDirection": "column",
+      "gap": "var(--jx-space-2)",
+      "margin": "0",
+      "padding": "0",
+      "listStyle": "none"
+    },
+    "& [part=\"row\"]": {
+      "display": "flex",
+      "alignItems": "flex-start",
+      "gap": "var(--jx-space-3)",
+      "padding": "6px var(--jx-space-3)",
+      "border": "1px solid var(--border)",
+      "borderLeft": "3px solid var(--fg-dim)",
+      "borderRadius": "var(--radius)",
+      "background": "var(--bg-panel)",
+      "color": "var(--fg)",
+      "fontSize": "var(--jx-text-md)"
+    },
+    "& [part=\"row\"][data-severity=\"success\"]": {
+      "borderLeftColor": "var(--success)"
+    },
+    "& [part=\"row\"][data-severity=\"info\"]": {
+      "borderLeftColor": "var(--accent)"
+    },
+    "& [part=\"row\"][data-severity=\"warn\"]": {
+      "borderLeftColor": "var(--warning)"
+    },
+    "& [part=\"row\"][data-severity=\"error\"]": {
+      "borderLeftColor": "var(--danger)"
+    },
+    "& [part=\"row\"] > [part=\"icon\"]": {
+      "$description": "The severity, twice: as the glyph and as the row's left edge. Colour is never the only encoding here, which is what keeps the row readable in the forced-colours block below, where every author colour is replaced by the user's palette.",
+      "flex": "none",
+      "width": "14px",
+      "textAlign": "center",
+      "fontWeight": "700",
+      "lineHeight": "1.5"
+    },
+    "& [part=\"row\"][data-severity=\"success\"] > [part=\"icon\"]": {
+      "color": "var(--success)"
+    },
+    "& [part=\"row\"][data-severity=\"info\"] > [part=\"icon\"]": {
+      "color": "var(--accent)"
+    },
+    "& [part=\"row\"][data-severity=\"warn\"] > [part=\"icon\"]": {
+      "color": "var(--warning)"
+    },
+    "& [part=\"row\"][data-severity=\"error\"] > [part=\"icon\"]": {
+      "color": "var(--danger)"
+    },
+    "& [part=\"row-body\"]": {
+      "flex": "1",
+      "minWidth": "0",
+      "display": "flex",
+      "flexDirection": "column",
+      "gap": "var(--jx-space-1)"
+    },
+    "& [part=\"message\"]": {
+      "overflowWrap": "anywhere"
+    },
+    "& [part=\"file-path\"]": {
+      "$description": "The path is a control, not a label: it opens the file the problem is about, which is the click-through §7.1 asks for. Underlined on hover only — a permanently underlined path in a dense list reads as a paragraph of links. A plain button rather than a `jx-button`, for the reason the status bar's items are: what it has to look like is a line of text, and every fill, border and control height the kit draws would have to be taken back off again. Named `file-path` and not `path` because `jx-icon` puts `part=\"path\"` on the `<path>` of every glyph it draws, so `[part=\"path\"]` inside a row selects this button and both SVG paths beside it — a styling rule that reaches into the kit's own drawing, and a test or a devtools query that cannot tell them apart.",
+      "alignSelf": "flex-start",
+      "maxWidth": "100%",
+      "overflow": "hidden",
+      "margin": "0",
+      "padding": "0",
+      "border": "none",
+      "borderRadius": "var(--jx-radius-xs)",
+      "background": "none",
+      "color": "var(--accent)",
+      "font": "inherit",
+      "fontFamily": "var(--font-mono)",
+      "fontSize": "var(--jx-text-sm)",
+      "textOverflow": "ellipsis",
+      "whiteSpace": "nowrap",
+      "textAlign": "left",
+      "cursor": "pointer",
+      ":hover": {
+        "textDecoration": "underline"
+      },
+      ":focus-visible": {
+        "outline": "var(--jx-focus-ring)",
+        "outlineOffset": "2px"
+      }
+    },
+    "& [part=\"detail\"]": {
+      "$description": "The captured log the progress modal used to own. It scrolls inside the row rather than growing it, so one 400-line `bun install` failure does not become the whole panel.",
+      "maxHeight": "180px",
+      "margin": "var(--jx-space-1) 0 0",
+      "padding": "6px",
+      "overflow": "auto",
+      "borderRadius": "var(--jx-radius-xs)",
+      "background": "var(--bg)",
+      "color": "var(--fg-dim)",
+      "fontFamily": "var(--font-mono)",
+      "fontSize": "var(--jx-text-sm)",
+      "whiteSpace": "pre-wrap"
+    },
+    "& [part=\"action\"]": {
+      "flex": "none"
+    },
+    "& [part=\"action\"] > [part=\"control\"]": {
+      "$description": "The recovery button wears the command's own title, so it is read as a verb and not as a decoration: the accent says it acts, and a refused command is dimmed with the reason it names in its tooltip.",
+      "border": "1px solid var(--border)",
+      "borderRadius": "var(--jx-radius-xs)",
+      "background": "transparent",
+      "color": "var(--accent)",
+      ":hover:not(:disabled)": {
+        "background": "var(--hover-bg)"
+      },
+      ":disabled": {
+        "color": "var(--fg-dim)"
+      }
+    },
+    "& [part=\"dismiss\"]": {
+      "flex": "none"
+    },
+    "& [part=\"empty\"]": {
+      "$description": "The teaching empty state, drawn here rather than borrowed from `panels/empty-state.ts`: that helper is a lit template, and a document cannot call one. What is kept is the pattern's rules (§11) — one sentence saying what the region is FOR, then where its content comes from. It offers no action, because the action that fills this region is a failure and nothing here should invite one.",
+      "display": "flex",
+      "flexDirection": "column",
+      "alignItems": "center",
+      "gap": "var(--jx-space-3)",
+      "padding": "var(--jx-space-6)",
+      "textAlign": "center",
+      "color": "var(--fg-dim)",
+      "fontSize": "13px"
+    },
+    "& [part=\"empty-message\"], & [part=\"empty-detail\"]": {
+      "margin": "0",
+      "maxWidth": "34ch",
+      "lineHeight": "1.5"
+    },
+    "& [part=\"empty-detail\"]": {
+      "fontSize": "var(--jx-text-sm)",
+      "opacity": "0.8"
+    },
+    "@(forced-colors: active)": {
+      "& [part=\"row\"]": {
+        "$description": "The severity bar, redrawn. In forced colours every author colour is replaced by one from the user's palette, so the four left-edge colours collapse into one and the row loses the marker `styles/forced-colors.css` restored for `.problem-row` while this surface was lit.",
+        "borderLeft": "2px solid Highlight"
+      }
+    }
+  },
+  "children": [
+    {
+      "tagName": "div",
+      "attributes": {
+        "part": "body-slot",
+        "role": "none"
+      },
+      "style": {
+        "display": "contents"
+      },
+      "$switch": {
+        "$ref": "#/state/hasProblems"
+      },
+      "cases": {
+        "false": {
+          "tagName": "div",
+          "attributes": {
+            "part": "empty"
+          },
+          "children": [
+            {
+              "tagName": "p",
+              "attributes": {
+                "part": "empty-message"
+              },
+              "textContent": "Nothing needs fixing."
+            },
+            {
+              "tagName": "p",
+              "attributes": {
+                "part": "empty-detail"
+              },
+              "textContent": "Failed writes, validation errors and render failures are listed here until fixed."
+            }
+          ]
+        },
+        "true": {
+          "tagName": "div",
+          "attributes": {
+            "part": "body"
+          },
+          "children": [
+            {
+              "tagName": "div",
+              "attributes": {
+                "part": "actions"
+              },
+              "children": [
+                {
+                  "tagName": "jx-button",
+                  "$props": {
+                    "size": "sm"
+                  },
+                  "attributes": {
+                    "part": "clear"
+                  },
+                  "onclick": {
+                    "$prototype": "Function",
+                    "body": [
+                      {
+                        "operator": "call",
+                        "target": {
+                          "$ref": "#/state/clearAll"
+                        }
+                      }
+                    ]
+                  },
+                  "children": [
+                    {
+                      "tagName": "span",
+                      "textContent": "${state.clearLabel}"
+                    }
+                  ]
+                }
+              ]
+            },
+            {
+              "$prototype": "Array",
+              "items": {
+                "$ref": "#/state/groups"
+              },
+              "key": {
+                "$ref": "$map/item/source"
+              },
+              "map": {
+                "tagName": "section",
+                "attributes": {
+                  "part": "group",
+                  "data-source": "${$map.item.source}"
+                },
+                "children": [
+                  {
+                    "tagName": "h3",
+                    "attributes": {
+                      "part": "group-title"
+                    },
+                    "textContent": "${$map.item.source}"
+                  },
+                  {
+                    "tagName": "ul",
+                    "attributes": {
+                      "part": "list"
+                    },
+                    "children": [
+                      {
+                        "$prototype": "Array",
+                        "items": {
+                          "$ref": "$map/item/rows"
+                        },
+                        "key": {
+                          "$ref": "$map/item/id"
+                        },
+                        "map": {
+                          "tagName": "li",
+                          "attributes": {
+                            "part": "row",
+                            "data-severity": "${$map.item.severity}"
+                          },
+                          "children": [
+                            {
+                              "tagName": "span",
+                              "attributes": {
+                                "part": "icon",
+                                "aria-hidden": "true"
+                              },
+                              "textContent": "${$map.item.icon}"
+                            },
+                            {
+                              "tagName": "div",
+                              "attributes": {
+                                "part": "row-body"
+                              },
+                              "children": [
+                                {
+                                  "tagName": "div",
+                                  "attributes": {
+                                    "part": "message"
+                                  },
+                                  "textContent": "${$map.item.message}"
+                                },
+                                {
+                                  "tagName": "span",
+                                  "attributes": {
+                                    "part": "file-path-slot",
+                                    "role": "none"
+                                  },
+                                  "style": {
+                                    "display": "contents"
+                                  },
+                                  "$switch": {
+                                    "$ref": "$map/item/hasPath"
+                                  },
+                                  "cases": {
+                                    "true": {
+                                      "tagName": "button",
+                                      "attributes": {
+                                        "part": "file-path",
+                                        "type": "button",
+                                        "title": "${$map.item.pathTitle}"
+                                      },
+                                      "textContent": "${$map.item.path}",
+                                      "onclick": {
+                                        "$prototype": "Function",
+                                        "body": [
+                                          {
+                                            "operator": "call",
+                                            "target": {
+                                              "$ref": "#/state/openPath"
+                                            },
+                                            "value": [
+                                              {
+                                                "$ref": "$map/item/path"
+                                              }
+                                            ]
+                                          }
+                                        ]
+                                      }
+                                    }
+                                  }
+                                },
+                                {
+                                  "tagName": "span",
+                                  "attributes": {
+                                    "part": "detail-slot",
+                                    "role": "none"
+                                  },
+                                  "style": {
+                                    "display": "contents"
+                                  },
+                                  "$switch": {
+                                    "$ref": "$map/item/hasDetail"
+                                  },
+                                  "cases": {
+                                    "true": {
+                                      "tagName": "pre",
+                                      "attributes": {
+                                        "part": "detail"
+                                      },
+                                      "textContent": "${$map.item.detail}"
+                                    }
+                                  }
+                                }
+                              ]
+                            },
+                            {
+                              "tagName": "span",
+                              "attributes": {
+                                "part": "action-slot",
+                                "role": "none"
+                              },
+                              "style": {
+                                "display": "contents"
+                              },
+                              "$switch": {
+                                "$ref": "$map/item/hasAction"
+                              },
+                              "cases": {
+                                "true": {
+                                  "tagName": "jx-button",
+                                  "$props": {
+                                    "size": "sm",
+                                    "disabled": {
+                                      "$ref": "$map/item/actionDisabled"
+                                    }
+                                  },
+                                  "attributes": {
+                                    "part": "action",
+                                    "title": "${$map.item.actionTitle}"
+                                  },
+                                  "onclick": {
+                                    "$prototype": "Function",
+                                    "body": [
+                                      {
+                                        "operator": "call",
+                                        "target": {
+                                          "$ref": "#/state/runAction"
+                                        },
+                                        "value": [
+                                          {
+                                            "$ref": "$map/item/id"
+                                          }
+                                        ]
+                                      }
+                                    ]
+                                  },
+                                  "children": [
+                                    {
+                                      "tagName": "span",
+                                      "textContent": "${$map.item.actionLabel}"
+                                    }
+                                  ]
+                                }
+                              }
+                            },
+                            {
+                              "tagName": "jx-action-button",
+                              "$props": {
+                                "size": "sm",
+                                "icon": "x",
+                                "hint": "Dismiss",
+                                "label": {
+                                  "$ref": "$map/item/dismissLabel"
+                                }
+                              },
+                              "attributes": {
+                                "part": "dismiss"
+                              },
+                              "onclick": {
+                                "$prototype": "Function",
+                                "body": [
+                                  {
+                                    "operator": "call",
+                                    "target": {
+                                      "$ref": "#/state/dismissRow"
+                                    },
+                                    "value": [
+                                      {
+                                        "$ref": "$map/item/id"
+                                      }
+                                    ]
+                                  }
+                                ]
+                              }
+                            }
+                          ]
+                        }
+                      }
+                    ]
+                  }
+                ]
+              }
+            }
+          ]
+        }
+      }
+    }
+  ]
+}

package/src/surfaces/panel-problems.ts

@@ -0,0 +1,157 @@
+/// <reference lib="dom" />
+/**
+ * The Problems surface: the Bottom dock's first tab, as a Jx document over the kit.
+ *
+ * This is the adapter. `panels/problems-panel.ts` keeps the panel — what a problem IS, how the list
+ * is grouped, which command a row's recovery button carries and what a click does — and hands this
+ * module a projection: whether there is anything to show, the Clear button's label, and the groups
+ * with their rows already flattened. The document renders that.
+ *
+ * The flattening happens on the panel's side rather than here for the reason
+ * `surfaces/settings-overview.ts` gives: a document has no conditional beyond `$switch` over a
+ * value, and "does the registry have this command, and is it enabled" is three questions. The panel
+ * answers them and the surface reads booleans.
+ *
+ * **The container is not cleared, and that is the one line where a panel differs from a settings
+ * section.** A section is handed the pane's whole content area and starts by emptying it; a panel
+ * body is a node lit renders into, and its comment markers are how lit finds its own content again.
+ * Removing them leaves lit inserting into a range that is no longer in the document, silently. So
+ * the document is APPENDED, and it is the panel's business (not this module's) to take it down
+ * again when the dock paints another tab into the same host.
+ *
+ * @docs studio/interface/problems-and-progress
+ */
+
+import { reactive } from "../reactivity";
+import { mountSurface, registerSurface } from "../ui/surface";
+import problemsDoc from "./panel-problems.json";
+import type { JxDocument } from "@jxsuite/schema/types";
+import type { SurfaceHandle } from "../ui/surface";
+
+registerSurface("panel-problems", problemsDoc as unknown as JxDocument);
+
+/** One problem, as the document draws it. Every field is a value: no records, no closures. */
+export interface ProblemRowView {
+  /** The notification's id — the row's reconcile key, and what every button hands back. */
+  id: string;
+  /** `error` | `warn` | `info` | `success`: the glyph's colour and the row's left edge. */
+  severity: string;
+  /** The severity glyph itself, one character. */
+  icon: string;
+  message: string;
+  hasPath: boolean;
+  path: string;
+  /** The path button's tooltip — "Open project.json". */
+  pathTitle: string;
+  hasDetail: boolean;
+  detail: string;
+  hasAction: boolean;
+  /** The recovery command's title, so the button says what it does rather than "Retry". */
+  actionLabel: string;
+  actionDisabled: boolean;
+  /** The command's tooltip: its title, or its title with the reason it is refused. */
+  actionTitle: string;
+  /** The dismiss button's accessible name, which has to name the row it dismisses. */
+  dismissLabel: string;
+}
+
+/** One heading and the rows under it. */
+export interface ProblemGroupView {
+  source: string;
+  rows: ProblemRowView[];
+}
+
+/** What the panel says the surface should be showing right now. */
+export interface ProblemsValues {
+  hasProblems: boolean;
+  /** "Clear 3" — the count is part of the label, so the button says how much it takes. */
+  clearLabel: string;
+  groups: ProblemGroupView[];
+}
+
+/** What a control can ask the panel to do. Every one of them is a decision the panel owns. */
+export interface ProblemsActions {
+  clearAll: () => void;
+  dismissRow: (id: string) => void;
+  openPath: (path: string) => void;
+  runAction: (id: string) => void;
+}
+
+export interface ProblemsSurfaceHandle {
+  /** Bring the mounted document up to date with a whole projection. */
+  update: (values: ProblemsValues) => void;
+  /** Whether the document this mounted is still standing in the container it was given. */
+  connected: () => boolean;
+  /** Take the document down. Idempotent. */
+  dispose: () => void;
+}
+
+/** The scope the document reads: the projection, and the four things a row can ask for. */
+interface ProblemsScope extends Record<string, unknown> {
+  hasProblems: boolean;
+  clearLabel: string;
+  groups: ProblemGroupView[];
+  clearAll: () => void;
+  dismissRow: (id: string) => void;
+  openPath: (path: string) => void;
+  runAction: (id: string) => void;
+}
+
+/** Write a projection into the scope. */
+function project(scope: ProblemsScope, values: ProblemsValues): void {
+  scope.hasProblems = values.hasProblems;
+  scope.clearLabel = values.clearLabel;
+  scope.groups = values.groups;
+}
+
+/**
+ * Mount the Problems document into `container`, which is the panel body the dock just painted.
+ *
+ * Nothing is called on the elements, so the mount is all this has to wait for: the DOCUMENT is what
+ * this surface renders, and the kit elements inside it settle their own templates one
+ * `connectedCallback` later without anybody here asking them to (guidelines §1.1, "await the
+ * element").
+ */
+export function mountProblemsSurface(
+  container: HTMLElement,
+  values: ProblemsValues,
+  actions: ProblemsActions,
+): ProblemsSurfaceHandle {
+  const scope = reactive<ProblemsScope>({
+    clearAll: actions.clearAll,
+    clearLabel: "",
+    dismissRow: actions.dismissRow,
+    groups: [],
+    hasProblems: false,
+    openPath: actions.openPath,
+    runAction: actions.runAction,
+  }) as ProblemsScope;
+  project(scope, values);
+
+  let mounted: SurfaceHandle | null = null;
+  let disposed = false;
+  void mountSurface("panel-problems", scope, container).then((surface) => {
+    if (disposed) {
+      surface.dispose();
+      return;
+    }
+    mounted = surface;
+  });
+
+  return {
+    /* While the mount is still in flight there is nothing in the container to ask about, so the
+       answer is simply whether this handle is still wanted. Once mounted, the question is whether
+       the root is still where it was put: a dock that repainted with another tab selected, or one
+       that collapsed, had the panel body emptied out from under it. */
+    connected: () =>
+      !disposed && (mounted === null || (mounted.root as Node).parentNode === container),
+    dispose() {
+      disposed = true;
+      mounted?.dispose();
+      mounted = null;
+    },
+    update: (values_) => {
+      project(scope, values_);
+    },
+  };
+}