@jxsuite/studio 4.0.0 → 5.0.0

package/src/surfaces/grid-views.json

@@ -0,0 +1,446 @@
+{
+  "$schema": "https://jxsuite.com/schema/v1",
+  "$id": "StudioGridViews",
+  "$description": "The grid's View panel: the saved views, and the four facets one of them is made of — columns, sort, grouping, and the filter the toolbar box holds. ONE control rather than four, because the chrome budget caps what may stand in a toolbar (§12.2) and these four are only ever adjusted together. There is no Apply button: every edit writes the working layout and applies immediately, so the panel is never showing something the grid is not already doing.",
+  "tagName": "jx-popover",
+  "attributes": {
+    "part": "views-panel"
+  },
+  "$props": {
+    "label": "Grid view",
+    "x": {
+      "$ref": "#/state/x"
+    },
+    "y": {
+      "$ref": "#/state/y"
+    }
+  },
+  "children": [
+    {
+      "tagName": "div",
+      "attributes": {
+        "part": "body"
+      },
+      "style": {
+        "display": "flex",
+        "flexDirection": "column",
+        "gap": "var(--jx-space-2)",
+        "padding": "var(--jx-space-3)",
+        "minWidth": "280px",
+        "fontFamily": "var(--jx-font-sans)",
+        "fontSize": "var(--jx-text-md)",
+        "color": "var(--fg)",
+        "maxHeight": "60vh",
+        "overflowY": "auto",
+        "& [part=\"title\"]": {
+          "fontWeight": "600",
+          "fontSize": "var(--jx-text-sm)",
+          "margin": "0"
+        },
+        "& [part=\"empty\"]": {
+          "margin": "0",
+          "color": "var(--fg-dim)",
+          "fontSize": "var(--jx-text-xs)"
+        },
+        "& [part=\"views\"]": {
+          "display": "flex",
+          "flexDirection": "column",
+          "gap": "2px"
+        },
+        "& [part=\"view-row\"]": {
+          "display": "flex",
+          "alignItems": "center",
+          "gap": "var(--jx-space-1)"
+        },
+        "& [part=\"view-name\"]": {
+          "flex": "1",
+          "textAlign": "left",
+          "background": "none",
+          "border": "none",
+          "color": "var(--fg)",
+          "font": "inherit",
+          "padding": "3px 6px",
+          "borderRadius": "var(--jx-radius-sm)",
+          "cursor": "pointer"
+        },
+        "& [part=\"view-name\"]:hover": {
+          "background": "var(--bg-hover)"
+        },
+        "& [part=\"view-name\"][data-active=\"true\"]": {
+          "fontWeight": "600",
+          "background": "var(--bg-selected)"
+        },
+        "& [part=\"view-name\"]:focus-visible": {
+          "outline": "var(--jx-focus-ring)",
+          "outlineOffset": "-2px"
+        },
+        "& [part=\"actions\"]": {
+          "display": "flex",
+          "gap": "var(--jx-space-2)"
+        },
+        "& [part=\"columns\"]": {
+          "display": "flex",
+          "flexDirection": "column",
+          "gap": "var(--jx-space-1)"
+        }
+      },
+      "children": [
+        {
+          "tagName": "p",
+          "attributes": {
+            "part": "title"
+          },
+          "textContent": "Saved views"
+        },
+        {
+          "tagName": "div",
+          "attributes": {
+            "part": "views-slot",
+            "role": "none"
+          },
+          "style": {
+            "display": "contents"
+          },
+          "$switch": {
+            "$ref": "#/state/viewsState"
+          },
+          "cases": {
+            "empty": {
+              "tagName": "p",
+              "attributes": {
+                "part": "empty"
+              },
+              "textContent": "No saved views yet. Arrange the grid, then save it under a name."
+            },
+            "listed": {
+              "tagName": "div",
+              "attributes": {
+                "part": "views"
+              },
+              "children": [
+                {
+                  "$prototype": "Array",
+                  "items": {
+                    "$ref": "#/state/views"
+                  },
+                  "key": {
+                    "$ref": "$map/item/key"
+                  },
+                  "map": {
+                    "$description": "One saved view: its name applies it, and the cross beside it asks before forgetting it. `$map/item` is the view, so the row hands its own name back rather than an index.",
+                    "tagName": "div",
+                    "attributes": {
+                      "part": "view-row",
+                      "data-view": "${$map.item.name}"
+                    },
+                    "children": [
+                      {
+                        "tagName": "button",
+                        "attributes": {
+                          "part": "view-name",
+                          "type": "button",
+                          "data-active": "${$map.item.active}",
+                          "aria-current": "${$map.item.current}"
+                        },
+                        "onclick": {
+                          "$prototype": "Function",
+                          "body": [
+                            {
+                              "operator": "call",
+                              "target": {
+                                "$ref": "#/state/applyView"
+                              },
+                              "value": [
+                                {
+                                  "$ref": "$map/item/name"
+                                }
+                              ]
+                            }
+                          ]
+                        },
+                        "textContent": "${$map.item.name}"
+                      },
+                      {
+                        "tagName": "jx-action-button",
+                        "attributes": {
+                          "part": "view-delete"
+                        },
+                        "$props": {
+                          "size": "sm",
+                          "quiet": true,
+                          "icon": "x",
+                          "label": "${$map.item.deleteLabel}",
+                          "hint": "Delete this view"
+                        },
+                        "onclick": {
+                          "$prototype": "Function",
+                          "body": [
+                            {
+                              "operator": "call",
+                              "target": {
+                                "$ref": "#/state/deleteView"
+                              },
+                              "value": [
+                                {
+                                  "$ref": "$map/item/name"
+                                }
+                              ]
+                            }
+                          ]
+                        }
+                      }
+                    ]
+                  }
+                }
+              ]
+            }
+          }
+        },
+        {
+          "tagName": "div",
+          "attributes": {
+            "part": "actions"
+          },
+          "children": [
+            {
+              "tagName": "jx-button",
+              "attributes": {
+                "part": "save-view"
+              },
+              "$props": {
+                "variant": "accent",
+                "size": "sm"
+              },
+              "onclick": {
+                "$prototype": "Function",
+                "body": [
+                  {
+                    "operator": "call",
+                    "target": {
+                      "$ref": "#/state/saveView"
+                    },
+                    "value": []
+                  }
+                ]
+              },
+              "children": [
+                {
+                  "tagName": "span",
+                  "textContent": "${state.saveLabel}"
+                }
+              ]
+            },
+            {
+              "tagName": "jx-button",
+              "attributes": {
+                "part": "reset"
+              },
+              "$props": {
+                "variant": "secondary",
+                "size": "sm",
+                "label": "Forget this grid's saved columns, sort, grouping and filter. Named views are kept."
+              },
+              "onclick": {
+                "$prototype": "Function",
+                "body": [
+                  {
+                    "operator": "call",
+                    "target": {
+                      "$ref": "#/state/reset"
+                    },
+                    "value": []
+                  }
+                ]
+              },
+              "children": [
+                {
+                  "tagName": "span",
+                  "textContent": "Reset"
+                }
+              ]
+            }
+          ]
+        },
+        {
+          "tagName": "p",
+          "attributes": {
+            "part": "title",
+            "data-title": "columns"
+          },
+          "textContent": "Columns"
+        },
+        {
+          "tagName": "div",
+          "attributes": {
+            "part": "columns"
+          },
+          "children": [
+            {
+              "$prototype": "Array",
+              "items": {
+                "$ref": "#/state/columns"
+              },
+              "key": {
+                "$ref": "$map/item/field"
+              },
+              "map": {
+                "$description": "One column's visibility. The title is SLOTTED rather than passed as `label`: an empty `label` removes the aria-label, so the wrapping label's own text names the box instead of naming it twice — and the reader can see which column the box is for.",
+                "tagName": "jx-checkbox",
+                "attributes": {
+                  "part": "column",
+                  "data-field": "${$map.item.field}"
+                },
+                "$props": {
+                  "size": "sm",
+                  "checked": {
+                    "$ref": "$map/item/visible"
+                  }
+                },
+                "onchange": {
+                  "$prototype": "Function",
+                  "body": [
+                    {
+                      "operator": "call",
+                      "target": {
+                        "$ref": "#/state/toggleColumn"
+                      },
+                      "value": [
+                        {
+                          "$ref": "$map/item/field"
+                        },
+                        {
+                          "$ref": "event#/target/checked"
+                        }
+                      ]
+                    }
+                  ]
+                },
+                "children": [
+                  {
+                    "tagName": "span",
+                    "textContent": "${$map.item.title}"
+                  }
+                ]
+              }
+            }
+          ]
+        },
+        {
+          "tagName": "p",
+          "attributes": {
+            "part": "title",
+            "data-title": "sort"
+          },
+          "textContent": "Sort"
+        },
+        {
+          "tagName": "jx-select",
+          "attributes": {
+            "part": "sort-field"
+          },
+          "$props": {
+            "label": "Sort by",
+            "size": "sm",
+            "options": {
+              "$ref": "#/state/fieldOptions"
+            },
+            "value": {
+              "$ref": "#/state/sortField"
+            }
+          },
+          "onchange": {
+            "$prototype": "Function",
+            "body": [
+              {
+                "operator": "call",
+                "target": {
+                  "$ref": "#/state/setSortField"
+                },
+                "value": [
+                  {
+                    "$ref": "event#/target/value"
+                  }
+                ]
+              }
+            ]
+          }
+        },
+        {
+          "tagName": "jx-select",
+          "attributes": {
+            "part": "sort-dir"
+          },
+          "$props": {
+            "label": "Sort direction",
+            "size": "sm",
+            "disabled": {
+              "$ref": "#/state/sortDirDisabled"
+            },
+            "options": {
+              "$ref": "#/state/dirOptions"
+            },
+            "value": {
+              "$ref": "#/state/sortDir"
+            }
+          },
+          "onchange": {
+            "$prototype": "Function",
+            "body": [
+              {
+                "operator": "call",
+                "target": {
+                  "$ref": "#/state/setSortDir"
+                },
+                "value": [
+                  {
+                    "$ref": "event#/target/value"
+                  }
+                ]
+              }
+            ]
+          }
+        },
+        {
+          "tagName": "p",
+          "attributes": {
+            "part": "title",
+            "data-title": "group"
+          },
+          "textContent": "Group by"
+        },
+        {
+          "tagName": "jx-select",
+          "attributes": {
+            "part": "group-field"
+          },
+          "$props": {
+            "label": "Group by",
+            "size": "sm",
+            "options": {
+              "$ref": "#/state/groupOptions"
+            },
+            "value": {
+              "$ref": "#/state/groupField"
+            }
+          },
+          "onchange": {
+            "$prototype": "Function",
+            "body": [
+              {
+                "operator": "call",
+                "target": {
+                  "$ref": "#/state/setGroup"
+                },
+                "value": [
+                  {
+                    "$ref": "event#/target/value"
+                  }
+                ]
+              }
+            ]
+          }
+        }
+      ]
+    }
+  ]
+}

package/src/surfaces/grid-views.ts

@@ -0,0 +1,172 @@
+/// <reference lib="dom" />
+/**
+ * The grid's View panel, as a mounted document.
+ *
+ * This is the adapter. `grid/grid-panel.ts` is the flow — what a saved view is, what storage holds,
+ * what applying one does to four surfaces at once — and this is the panel it draws into. Every
+ * field arrives already decided: the flow never hands over a `GridColumn`, a `GridSortSpec` or a
+ * `SavedView`, only strings and booleans, so nothing here knows what a facet means.
+ *
+ * **It re-projects rather than re-opens.** `localStorage` is not reactive and neither is the
+ * engine, so a column drag saved by `grid-view.ts` and a Save-as done from the palette both reach
+ * the panel the same way: the flow calls {@link GridViewsSurfaceHandle.update} and the open panel
+ * reconciles. The lit version rebuilt its whole template on every one of those, which is why
+ * deleting a view moved the focus back to the top of the list.
+ *
+ * @docs studio/editing/grid
+ */
+
+import { reactive } from "../reactivity";
+import { openPopoverSurface } from "../ui/popover-surface";
+import { registerSurface } from "../ui/surface";
+import gridViewsDoc from "./grid-views.json";
+import type { JxDocument } from "@jxsuite/schema/types";
+import type { PopoverSurfaceHandle } from "../ui/popover-surface";
+
+registerSurface("grid-views", gridViewsDoc as unknown as JxDocument);
+
+/** The slot id, and so the panel's region: `overlay.popover:grid/views`. */
+const SLOT = "grid/views";
+
+/** One row of the saved-view list. */
+export interface GridSavedViewRow {
+  /** The view's name: its identity across repaints, and what every button hands back. */
+  key: string;
+  name: string;
+  /** `"true"` for the view currently applied. A string, because a document switches on words. */
+  active: string;
+  /** `"true"` or `"false"` for `aria-current`. */
+  current: string;
+  /** The delete button's accessible name, which says which view it forgets. */
+  deleteLabel: string;
+}
+
+/** A closed list of choices, in the shape the kit's select reads. */
+export interface GridSelectOption {
+  value: string;
+  label: string;
+}
+
+/** One column's visibility. */
+export interface GridColumnToggle {
+  field: string;
+  title: string;
+  visible: boolean;
+}
+
+/** Everything the panel draws, as one value. */
+export interface GridViewsView {
+  /** Where the panel opens, in viewport pixels. */
+  x: number;
+  y: number;
+  viewsState: "empty" | "listed";
+  views: GridSavedViewRow[];
+  /** "Save view…" until one is applied, then "Save as…". */
+  saveLabel: string;
+  columns: GridColumnToggle[];
+  /** Every column, plus the "Source order" row that clears the sort. */
+  fieldOptions: GridSelectOption[];
+  dirOptions: GridSelectOption[];
+  groupOptions: GridSelectOption[];
+  sortField: string;
+  sortDir: string;
+  /** There is no sort to redirect, so the direction control is off rather than lying. */
+  sortDirDisabled: boolean;
+  groupField: string;
+}
+
+/** What a control asks the flow to do. */
+export interface GridViewsActions {
+  applyView: (name: string) => void;
+  deleteView: (name: string) => void;
+  saveView: () => void;
+  reset: () => void;
+  toggleColumn: (field: string, visible: boolean) => void;
+  setSortField: (field: string) => void;
+  setSortDir: (dir: string) => void;
+  setGroup: (field: string) => void;
+  /** The platform closed the panel: clicked outside, Escape, or a second press on the button. */
+  dismissed?: () => void;
+}
+
+export interface GridViewsSurfaceHandle extends PopoverSurfaceHandle {
+  update: (view: GridViewsView) => void;
+}
+
+interface GridViewsScope extends Record<string, unknown>, GridViewsView, GridViewsActions {}
+
+/** Write a projection into the scope. */
+function project(scope: GridViewsScope, view: GridViewsView): void {
+  scope.x = view.x;
+  scope.y = view.y;
+  scope.viewsState = view.viewsState;
+  scope.views = view.views;
+  scope.saveLabel = view.saveLabel;
+  scope.columns = view.columns;
+  scope.fieldOptions = view.fieldOptions;
+  scope.dirOptions = view.dirOptions;
+  scope.groupOptions = view.groupOptions;
+  scope.sortField = view.sortField;
+  scope.sortDir = view.sortDir;
+  scope.sortDirDisabled = view.sortDirDisabled;
+  scope.groupField = view.groupField;
+}
+
+/**
+ * Open the View panel under `anchor`.
+ *
+ * @param {GridViewsView} view - What it shows to begin with
+ * @param {GridViewsActions} actions - What each control does
+ * @param {HTMLElement | null} anchor - The toolbar button it hangs from
+ * @returns {GridViewsSurfaceHandle}
+ */
+export function openGridViewsSurface(
+  view: GridViewsView,
+  actions: GridViewsActions,
+  anchor: HTMLElement | null,
+): GridViewsSurfaceHandle {
+  const scope = reactive<GridViewsScope>({
+    applyView: actions.applyView,
+    columns: [],
+    deleteView: actions.deleteView,
+    dirOptions: [],
+    fieldOptions: [],
+    groupField: "",
+    groupOptions: [],
+    reset: actions.reset,
+    saveLabel: "Save view…",
+    saveView: actions.saveView,
+    setGroup: actions.setGroup,
+    setSortDir: actions.setSortDir,
+    setSortField: actions.setSortField,
+    sortDir: "asc",
+    sortDirDisabled: true,
+    sortField: "",
+    toggleColumn: actions.toggleColumn,
+    views: [],
+    viewsState: "empty",
+    x: 0,
+    y: 0,
+  }) as GridViewsScope;
+  project(scope, view);
+
+  const handle = openPopoverSurface({
+    anchor,
+    name: "grid-views",
+    scope,
+    slot: SLOT,
+    ...(actions.dismissed ? { onDismissed: actions.dismissed } : {}),
+  });
+
+  return {
+    close: handle.close,
+    host: handle.host,
+    isOpen: handle.isOpen,
+    ready: handle.ready,
+    update: (next) => {
+      if (handle.isOpen()) {
+        project(scope, next);
+      }
+    },
+  };
+}