Skip to content

feat: edge labels, neighbourhood and graph layouts, map views for any schema - #40

Draft
mindsocket wants to merge 6 commits into
mainfrom
claude/project-thread-iv62tw
Draft

mindsocket wants to merge 6 commits into
mainfrom
claude/project-thread-iv62tw

Conversation

@mindsocket

@mindsocket mindsocket commented Nov 15, 2026 •

Copy link
Copy Markdown
Owner

Requested by Rog · project thread

What

  1. edges.labels (parameterisable boolean, default false): tree, XY, neighbourhood and graph connectors show the field the relationship is declared in.
  2. neighbourhood layout: one focus node with its neighbours placed by role (above, below, left, right, around). Each role lists the fields that put a node there; with none listed, parents go above and children below. Selecting a neighbour moves the focus; selecting the focus is a normal selection. MapView takes focus and onFocusChange so a host can set and follow it.
  3. graph layout: every node and edge as a network, positioned by a seeded d3-force simulation, so the same graph gives the same positions. It needs no hierarchy.
  4. A definition's schema is optional. Without one it applies to every schema, and mapViewsForSchema includes it.
  5. Bundled views for any schema: graph, neighbourhood and tree. The tree shows a message for a schema with no hierarchy. strategy-tree stays as the view for the strategy schema.

Also

  • assignLanes moved from core/xy.ts to core/lanes.ts, as it has three users.
  • d3-force is a dependency, external to the library build like ajv.
  • Docs: definitions.md, concepts.md, architecture.md, api.md, CLAUDE.md. Regenerated latest schemas and bundled definitions.

Checks

  • bun test, typecheck and biome pass.
  • Rendered in Chromium from the launch-playbook fixture: neighbourhood (labels, refocus on click) and graph (42 nodes, 56 edges, shape style).
  • Not run: test:package, which needs network access that this environment lacks. It matters here because of the new d3-force dependency.
  • Not covered: the Obsidian plugin and the navigator don't set focus; the navigator doesn't keep it in the query string. Edge labels can overlap where connectors cross.

🤖 Generated with Claude Code

https://claude.ai/code/session_019XphpcKhuNyHcNArHFELR4

Tree and XY connectors can show the field the relationship is declared in,
so typed relationships read at a glance.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019XphpcKhuNyHcNArHFELR4
@mindsocket mindsocket self-assigned this Nov 15, 2026
Adds the compass layout with a bundled knowledge wiki neighbourhood view.
Selecting a neighbour moves the focus; hosts can set it with focus.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019XphpcKhuNyHcNArHFELR4
@mindsocket mindsocket changed the title feat: edges.labels draws each connector's relationship field feat: edge labels and a compass layout Nov 15, 2026
Adds the graph layout (d3-force) and makes a definition's schema optional;
without one it applies to every schema. Bundles graph, neighbourhood and tree
views for any schema. Renames compass to neighbourhood.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019XphpcKhuNyHcNArHFELR4
@mindsocket mindsocket changed the title feat: edge labels and a compass layout feat: edge labels, neighbourhood and graph layouts, map views for any schema Nov 15, 2026
Comment thread apps/navigator/src/useUrlState.ts Outdated

/**
* The chosen space, map view and parameter values, mirrored in the query string so a reload (or a
* The chosen space, map view, focus node and parameter values, mirrored in the query string so a reload (or a

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Don't list things the method signature lists. Totally redundant. Find and destroy similar examples in existing code

Comment thread docs/api.md Outdated
```

`graph` is a structured-context `SpaceGraph` (see [Data](#data)); `values` and the controls' `onChange` belong to the host. Pass `annotations` to show validation results (see [Validation results](#validation-results)).
`graph` is a structured-context `SpaceGraph` (see [Data](#data)); `values` and the controls' `onChange` belong to the host. Pass `annotations` to show validation results (see [Validation results](#validation-results)). `focus` and `onFocusChange` set and follow the node a [neighbourhood](definitions.md#neighbourhood) layout centres on.

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's not assume neighbourhood is the only layout that will care about this and create document maintenance overhead

Comment thread docs/architecture.md Outdated
space[structured-context space] -->|host assembles| graph[SpaceGraph]
def[definition .json5] -->|parseMapViewDefinition| mvd[MapViewDefinition]
graph --> proj[projection<br>tree · landscape · xy]
graph --> proj[projection<br>tree · landscape · xy · neighbourhood · graph]

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Enumerating every layout doesn't keep making sense here

Comment thread docs/architecture.md Outdated
| Module | Holds | May import |
|---|---|---|
| `packages/map-views/src/core` | Definition parsing and validation, parameter resolution, graph helpers, and the projections (`buildTree`, `buildLandscape`, `buildXYPlot`) | Types from structured-context only. No React, DOM or Node |
| `packages/map-views/src/core` | Definition parsing and validation, parameter resolution, graph helpers, and the projections (`buildTree`, `buildLandscape`, `buildXYPlot`, `buildNeighbourhood`, `buildForceGraph`) | Types from structured-context only. No React, DOM or Node |

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Don't enumerate the code

Comment thread docs/architecture.md Outdated
## Hosts

- **Navigator** (`apps/navigator`): dev-server middleware serves spaces (from the structured-context config), the definitions `loadMapViewDefinitions` finds, and, when a map view asks for them, validation results (`validateSpace`, expression rules only), as JSON. The chosen space, map view and parameter values live in the query string, so a reload restores them. Selecting a node opens a side panel with its fields, content and validation results.
- **Navigator** (`apps/navigator`): dev-server middleware serves spaces (from the structured-context config), the definitions `loadMapViewDefinitions` finds, and, when a map view asks for them, validation results (`validateSpace`, expression rules only), as JSON. The chosen space, map view, focus node and parameter values live in the query string, so a reload restores them. Selecting a node opens a side panel with its fields, content and validation results.

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Guess what I'm about to say... Stop enumerating stuff from the code

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Format seems like a strange name for what this is and it looks like a barrel index file which is not the convention we use. I feel like the word format is also contributing to my confusion about what's what. Let's revisit what the concepts doc says and whether this is the right word, and if so, whether I just need to be reading the right part of that document to understand

return <LandscapeLayout {...props} region={{ ...region, layout }} />;
case 'xy':
return <XYLayout {...props} region={{ ...region, layout }} />;
case 'graph':

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This boilerplate and hard-coded lines with each added layout suggests refactoring opp.

const { orientation, dag } = region.layout;
const tree = useMemo(() => buildTree(graph, region.id, dag), [graph, region.id, dag]);
const links = useMemo(() => (region.edges.show ? treeLinks(tree) : []), [tree, region.edges.show]);
const { show, labels } = region.edges;

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This looks similar in other layouts too

const definition = (id: string) =>
`{ $id: '${id}', schema: 'sctx://x', regions: [{ id: 'main', layout: { type: 'tree' } }] }`;
const BUNDLED = [
'sctx-map-view://core/graph',

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

More hardcoding for no clear reason

expect(snapshot!.definitions.map((d) => d.id)).toEqual(['sctx-map-view://mine']);
const ids = snapshot!.definitions.map((d) => d.id);
expect(ids).toContain('sctx-map-view://mine');
expect(ids).toContain('sctx-map-view://core/graph');

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this a useful test or just asserting orthogonal stuff that happens to be true beyond the scope of the test? If the latter, drop it and hunt down similar existing cases with prejudice

…md, trimmed docs and tests

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019XphpcKhuNyHcNArHFELR4
…a/ for the shared format, no barrel

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019XphpcKhuNyHcNArHFELR4

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants