Add defaultStyling.json support for persistent per-type vertex and edge styling

Adds an optional defaultStyling.json file that can be mounted into the
Docker container to provide per-type vertex and edge styling defaults.
This addresses the need for persistent styling in environments where
browser storage is cleared between sessions (e.g., AWS WorkSpaces Web).

On startup, file values are merged into the user's per-type styling
preferences (IndexedDB). Default values fill in properties the user
hasn't explicitly set; existing user overrides are preserved. The file
also serves as a reference for per-type "Reset to Default" in the
Node/Edge Style dialogs.

The Settings page adds Export/Import/Reset All styling controls:
- Export: saves current styling as defaultStyling.json for sharing or
  Docker-mounting as team defaults
- Import: merges a defaultStyling.json into user styling and updates
  the reset reference so reset-after-import restores imported values
- Reset All: reverts all styling to defaults (from file or hardcoded)

Supports lucide icon names (resolved to SVG data URIs at runtime via
dynamic imports), custom icon URLs, colors, shapes, border styles, edge
line styles, and arrow styles. Includes Zod validation with strict type
checking for shapes and arrow styles.

Includes 58 new tests with 100% line coverage on new modules, example
file, and documentation.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: jkemmererupgrade

Changelog.md

@@ -1,5 +1,10 @@
 # Graph Explorer Change Log
 
+## Unreleased
+
+- Add defaultStyling.json support for persistent per-type vertex and edge
+  styling (#1265, #112, #173, #573, #689)
+
 ## Release 3.0.0
 
 Graph Explorer 3.0 is here! This release brings one of the most requested features — the ability to visualize your graph database schema — along with a fresh navigation experience and a handful of quality-of-life improvements.

docs/references/README.md

@@ -7,3 +7,4 @@ Technical reference documentation for Graph Explorer covering configuration, sec
 - [Health Check](./health-check.md) - Proxy server health and readiness endpoint
 - [Logging](./logging.md) - Log levels, output, and proxy server logging modules
 - [Default Connection](./default-connection.md) - Configure a default connection via environment variables or JSON
+- [Default Styling](./default-styling.md) - Configure default vertex and edge styling via a JSON file

docs/references/default-styling.md

@@ -0,0 +1,163 @@
+# Default Styling Configuration
+
+Graph Explorer supports an optional `defaultStyling.json` file that provides
+default vertex and edge styling for all users. This is useful for:
+
+- Non-persistent browser environments (e.g., AWS WorkSpaces Web) where IndexedDB
+  is cleared between sessions
+- Pre-configuring a shared visual style for teams
+- Providing a consistent starting point for new users
+
+## How It Works
+
+On startup, Graph Explorer fetches `defaultStyling.json` and merges its values
+into the user's per-type styling preferences (stored in IndexedDB). Default
+values fill in any properties the user hasn't explicitly set — existing user
+overrides are preserved.
+
+When no `defaultStyling.json` is mounted, behavior is identical to the default
+Graph Explorer experience. When mounted, it populates the per-type styling that
+users can then customize. Resetting a vertex or edge style in the UI will revert
+to the `defaultStyling.json` values (or the hardcoded application defaults if no
+entry exists for that type).
+
+## Setup
+
+### Docker
+
+Mount the file into the container's configuration folder:
+
+```bash
+docker run \
+  -v /path/to/defaultStyling.json:/graph-explorer/packages/graph-explorer/defaultStyling.json \
+  public.ecr.aws/neptune/graph-explorer
+```
+
+### Custom Icons
+
+To serve custom icon files (referenced by URL in the config), mount an icons
+directory:
+
+```bash
+docker run \
+  -v /path/to/defaultStyling.json:/graph-explorer/packages/graph-explorer/defaultStyling.json \
+  -v /path/to/icons:/graph-explorer/packages/graph-explorer/custom-icons \
+  public.ecr.aws/neptune/graph-explorer
+```
+
+Icons in the `custom-icons` directory are served at `/custom-icons/<filename>`.
+
+## JSON Schema
+
+```json
+{
+  "vertices": {
+    "<VertexTypeLabel>": {
+      "color": "#hex",
+      "icon": "lucide-icon-name",
+      "iconUrl": "url-or-base64",
+      "iconImageType": "image/svg+xml",
+      "shape": "ellipse",
+      "displayLabel": "Custom Label",
+      "displayNameAttribute": "name",
+      "longDisplayNameAttribute": "description",
+      "backgroundOpacity": 0.4,
+      "borderWidth": 0,
+      "borderColor": "#hex",
+      "borderStyle": "solid"
+    }
+  },
+  "edges": {
+    "<EdgeTypeLabel>": {
+      "displayLabel": "Custom Label",
+      "displayNameAttribute": "name",
+      "labelColor": "#hex",
+      "labelBackgroundOpacity": 0.7,
+      "labelBorderColor": "#hex",
+      "labelBorderStyle": "solid",
+      "labelBorderWidth": 0,
+      "lineColor": "#hex",
+      "lineThickness": 2,
+      "lineStyle": "solid",
+      "sourceArrowStyle": "none",
+      "targetArrowStyle": "triangle"
+    }
+  }
+}
+```
+
+All properties are optional — only specify what you want to override. Type
+labels must exactly match the vertex/edge type names in your graph database.
+
+### Icons
+
+There are two ways to specify vertex icons:
+
+- **`icon`** — A [Lucide](https://lucide.dev/icons) icon name in kebab-case
+  (e.g., `"user"`, `"log-in"`, `"landmark"`). Resolved to an SVG at runtime. No
+  additional files needed.
+- **`iconUrl`** — A URL or base64 data URI for a custom icon. Use this for
+  non-Lucide icons. If both `icon` and `iconUrl` are specified, `iconUrl` takes
+  precedence.
+
+### Vertex Shapes
+
+Available shapes: `ellipse`, `rectangle`, `diamond`, `triangle`, `pentagon`,
+`hexagon`, `heptagon`, `octagon`, `star`, `barrel`, `vee`, `rhomboid`, `tag`,
+`round-rectangle`, `round-triangle`, `round-diamond`, `round-pentagon`,
+`round-hexagon`, `round-heptagon`, `round-octagon`, `round-tag`,
+`cut-rectangle`, `concave-hexagon`.
+
+### Line Styles
+
+Available for edges and borders: `solid`, `dashed`, `dotted`.
+
+### Arrow Styles
+
+Available for `sourceArrowStyle` and `targetArrowStyle`: `triangle`,
+`triangle-tee`, `circle-triangle`, `triangle-cross`, `triangle-backcurve`,
+`tee`, `vee`, `square`, `circle`, `diamond`, `none`.
+
+## Common Lucide Icons for Graph Use Cases
+
+| Use Case             | Icon Name                         |
+| -------------------- | --------------------------------- |
+| Person / User        | `user`                            |
+| Account / Bank       | `landmark`                        |
+| Email                | `mail`                            |
+| Phone                | `phone`                           |
+| Login / Auth         | `log-in`                          |
+| Device               | `monitor`, `laptop`, `smartphone` |
+| IP Address / Network | `globe`, `network`                |
+| Transaction          | `arrow-left-right`                |
+| Location             | `map-pin`                         |
+| Organization         | `building`                        |
+| Alert                | `shield-alert`, `triangle-alert`  |
+| Document             | `file-text`                       |
+| Calendar / Date      | `calendar`                        |
+| Lock / Security      | `lock`, `shield`                  |
+| Database             | `database`                        |
+| Server               | `server`                          |
+| Link / Relationship  | `link`                            |
+
+See the full list at [lucide.dev/icons](https://lucide.dev/icons).
+
+## Import / Export / Reset
+
+The Settings page provides styling management:
+
+- **Export Styling** — exports the current per-type styling as a
+  `defaultStyling.json` file, for sharing or Docker-mounting as team defaults.
+- **Import Styling** — imports a `defaultStyling.json` file. This is an
+  alternative to mounting the file in Docker.
+- **Reset All Styling** — resets all styling to defaults. If a
+  `defaultStyling.json` is mounted, those values are restored; otherwise,
+  styling reverts to the application defaults.
+
+Per-type reset is also available in the Node/Edge Style dialogs via the "Reset
+to Default" button.
+
+## Example
+
+See [`example/defaultStyling.json`](../example/defaultStyling.json) for a
+complete example with banking-oriented vertex and edge types.

example/defaultStyling.json

@@ -0,0 +1,86 @@
+{
+  "vertices": {
+    "User": {
+      "color": "#1565C0",
+      "icon": "user",
+      "shape": "ellipse"
+    },
+    "Account": {
+      "color": "#2E7D32",
+      "icon": "landmark",
+      "shape": "ellipse"
+    },
+    "Login": {
+      "color": "#EF6C00",
+      "icon": "log-in",
+      "shape": "ellipse"
+    },
+    "EmailAddress": {
+      "color": "#C62828",
+      "icon": "mail",
+      "shape": "ellipse"
+    },
+    "PhoneNumber": {
+      "color": "#6A1B9A",
+      "icon": "phone",
+      "shape": "ellipse"
+    },
+    "Device": {
+      "color": "#00838F",
+      "icon": "monitor",
+      "shape": "rectangle"
+    },
+    "IPAddress": {
+      "color": "#4E342E",
+      "icon": "globe",
+      "shape": "diamond"
+    },
+    "Transaction": {
+      "color": "#1B5E20",
+      "icon": "arrow-left-right",
+      "shape": "ellipse"
+    },
+    "Location": {
+      "color": "#E65100",
+      "icon": "map-pin",
+      "shape": "ellipse"
+    },
+    "Organization": {
+      "color": "#283593",
+      "icon": "building",
+      "shape": "rectangle"
+    }
+  },
+  "edges": {
+    "OWNS": {
+      "lineColor": "#2E7D32",
+      "lineThickness": 2,
+      "lineStyle": "solid"
+    },
+    "TRANSFERRED_TO": {
+      "lineColor": "#1B5E20",
+      "lineThickness": 3,
+      "lineStyle": "solid"
+    },
+    "HAS_EMAIL": {
+      "lineColor": "#9E9E9E",
+      "lineThickness": 1,
+      "lineStyle": "dashed"
+    },
+    "HAS_PHONE": {
+      "lineColor": "#9E9E9E",
+      "lineThickness": 1,
+      "lineStyle": "dashed"
+    },
+    "LOGGED_IN_FROM": {
+      "lineColor": "#EF6C00",
+      "lineThickness": 2,
+      "lineStyle": "solid"
+    },
+    "LOCATED_AT": {
+      "lineColor": "#E65100",
+      "lineThickness": 1,
+      "lineStyle": "dotted"
+    }
+  }
+}

packages/graph-explorer-proxy-server/src/node-server.ts

@@ -180,6 +180,14 @@ app.use(
     path.join(defaultConnectionFolderPath, "defaultConnection.json"),
   ),
 );
+app.use(
+  "/defaultStyling",
+  express.static(path.join(defaultConnectionFolderPath, "defaultStyling.json")),
+);
+app.use(
+  "/custom-icons",
+  express.static(path.join(defaultConnectionFolderPath, "custom-icons")),
+);
 
 // Host the Graph Explorer UI static files
 const staticFilesVirtualPath = "/explorer";

packages/graph-explorer/src/core/AppStatusLoader.tsx

@@ -1,5 +1,5 @@
 import { useQuery } from "@tanstack/react-query";
-import { useAtom } from "jotai";
+import { useAtom, useSetAtom } from "jotai";
 import {
   type PropsWithChildren,
   startTransition,
@@ -11,7 +11,14 @@ import { PanelEmptyState, Spinner } from "@/components";
 import { logger } from "@/utils";
 
 import { fetchDefaultConnection } from "./defaultConnection";
-import { activeConfigurationAtom, configurationAtom } from "./StateProvider";
+import { fetchDefaultStyling, resolveDefaultStyling } from "./defaultStyling";
+import {
+  activeConfigurationAtom,
+  configurationAtom,
+  defaultStylingAtom,
+  mergeDefaultsIntoUserStyling,
+  userStylingAtom,
+} from "./StateProvider";
 
 function AppStatusLoader({ children }: PropsWithChildren) {
   return (
@@ -24,6 +31,8 @@ function AppStatusLoader({ children }: PropsWithChildren) {
 function LoadDefaultConfig({ children }: PropsWithChildren) {
   const [activeConfig, setActiveConfig] = useAtom(activeConfigurationAtom);
   const [configuration, setConfiguration] = useAtom(configurationAtom);
+  const setDefaultStyling = useSetAtom(defaultStylingAtom);
+  const setUserStyling = useSetAtom(userStylingAtom);
 
   const defaultConfigQuery = useQuery({
     queryKey: ["default-connection"],
@@ -33,6 +42,39 @@ function LoadDefaultConfig({ children }: PropsWithChildren) {
     enabled: configuration.size === 0,
   });
 
+  // Fetch default styling on every session start
+  const defaultStylingQuery = useQuery({
+    queryKey: ["default-styling"],
+    queryFn: fetchDefaultStyling,
+    staleTime: Infinity,
+  });
+
+  useEffect(() => {
+    const data = defaultStylingQuery.data;
+    if (!data) {
+      return;
+    }
+    let cancelled = false;
+    logger.debug("Applying default styling", data);
+    resolveDefaultStyling(data)
+      .then(resolved => {
+        if (!cancelled) {
+          // Store reference copy for per-type "Reset to Default"
+          setDefaultStyling(resolved);
+
+          // Merge file values into user styling. Default values fill in
+          // properties the user hasn't explicitly set; user overrides win.
+          setUserStyling(prev => mergeDefaultsIntoUserStyling(prev, resolved));
+        }
+      })
+      .catch(err => {
+        logger.warn("Failed to resolve default styling", err);
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [defaultStylingQuery.data, setDefaultStyling, setUserStyling]);
+
   const defaultConnectionConfigs = defaultConfigQuery.data;
 
   useEffect(() => {

packages/graph-explorer/src/core/StateProvider/configuration.test.ts

@@ -257,6 +257,37 @@ describe("mergedConfiguration", () => {
     expect(actualEtConfig?.displayLabel).toEqual(customDisplayLabel);
   });
 
+  it("should apply styling from userStyling (which includes merged defaults)", () => {
+    const config = createRandomRawConfiguration();
+    const schema = createRandomSchema();
+    // In the new architecture, defaults from defaultStyling.json are
+    // merged into userStyling at load time
+    const styling: UserStyling = {
+      vertices: schema.vertices.map(v => ({
+        type: v.type,
+        color: "#FF0000",
+      })),
+      edges: schema.edges.map(e => ({
+        type: e.type,
+        lineColor: "#00FF00",
+      })),
+    };
+    const result = mergeConfiguration(schema, config, styling);
+
+    for (const v of result.schema?.vertices ?? []) {
+      const style = styling.vertices?.find(s => s.type === v.type);
+      if (style) {
+        expect(v.color).toBe("#FF0000");
+      }
+    }
+    for (const e of result.schema?.edges ?? []) {
+      const style = styling.edges?.find(s => s.type === e.type);
+      if (style) {
+        expect(e.lineColor).toBe("#00FF00");
+      }
+    }
+  });
+
   it("should patch displayNameAttribute to be 'types' when it was 'type'", () => {
     const etConfig = createRandomEdgeTypeConfig();