Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -57,7 +57,7 @@ Review and update with any change:
| Module structure, rendering, styling | `docs/architecture.md` |
| Anything user-visible | `README.md` (kept short; detail goes in `docs/`) |

Docs describe what the code does now. Decision history and plans don't go in docs.
Docs describe what the code does now. Decision history, plans and how things used to work don't go in docs: git history records changes, and release notes record the breaking ones.

## Running and verifying in a browser

Expand Down
4 changes: 2 additions & 2 deletions docs/architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ All but the last two rows are folders of `packages/map-views/src`.
| Module | Holds | May import |
|---|---|---|
| `core` | Definitions and parameters, annotations, and each layout's settings schema and projection, if it has one (`core/layouts/<name>/`). Runs in a browser, Node or a worker | Types from structured-context. No React, DOM or Node |
| `components` | `MapView` and what it draws with: a component per layout, node cards, the connector overlay, parameter controls | core, React |
| `components` | `MapView` and what it draws with: a component per layout, node components, the connector overlay, parameter controls | core, React |
| `viewer` | The page-filling UI that hosts share. What is specific to a host comes in as an option | core, components, React, `structured-context/browser` |
| `node` | What needs a filesystem: finding definitions, snapshotting a space, filling the self-contained page | core, Node, structured-context |
| `artifact`, `page` | The two hosts the library ships. Nothing imports them | Anything above |
Expand All @@ -35,7 +35,7 @@ Core is tested without a DOM, against fixtures captured from spaces (`tests/fixt

Hosts pass the library structured-context's `SpaceGraph`: nodes keyed by id, the main hierarchy, and every hierarchy and relationship edge with its metadata, readable in both directions (`parentEdges`, `childEdges`). The Obsidian plugin assembles it in-process; the navigator's server sends the wire format (`exportSpaceGraph`) and its browser rebuilds the graph (`spaceGraphFrom`). The graph keeps edges to nodes outside it; the helpers in `core/layouts/helpers.ts` drop them, so a filtered space stays consistent.

Hosts can also pass validation results as an `AnnotationIndex` (`core/annotations.ts`): results by node id, built by `annotationsFrom` from structured-context's validation issues. `MapView` narrows it by the region's `nodes.validation` and `nodes.validationSources` and provides the result to node cards through React context, so layouts don't thread it through. Every layout draws nodes with `NodeCard`, which draws the badge.
Hosts can also pass validation results as an `AnnotationIndex` (`core/annotations.ts`): results by node id, built by `annotationsFrom` from structured-context's validation issues. `MapView` narrows it by the region's `nodes.validation` and `nodes.validationSources` and provides the result to node components through React context, so layouts don't thread it through. Every layout draws nodes with `NodeComponent`, which draws the badge.

## Projections

Expand Down
14 changes: 9 additions & 5 deletions docs/concepts.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,31 +16,35 @@ A part of a map view with its own node selection, layout, node style and edge se

## Layout

The arrangement a region uses, chosen from a fixed catalogue. Each layout carries its own opinions (spacing, card sizes, colours). Definitions choose and configure a layout; they don't compose one. [Layouts](layouts.md) describes each one.
The arrangement a region uses, chosen from a fixed catalogue. Each layout carries its own opinions (spacing, sizes, colours). Definitions choose and configure a layout; they don't compose one. [Layouts](layouts.md) describes each one.

## Projection

The step some layouts need to decide what is shown: it turns a space graph and the region's settings into occurrences and connectors, for example placing a node with several parents in a tree. Arranging and drawing is the layout component's work.

## Occurrence

One rendered appearance of a space node. A node can occur more than once, for example under each of its parents in a tree; the later occurrences are repeats. Every occurrence has a key built from its path (region, then ancestors, then the node), so repeats stay distinct.
One rendered appearance of a space node. A node can occur more than once, for example under each of its parents in a tree; the later occurrences are repeats. Every occurrence has a key built from its path, so repeats stay distinct.

## Node component

What a layout draws for an occurrence, in the region's node style.

## Connector

The line drawn for an edge of the space graph, between two occurrences. "Edge" is the hierarchy or relationship reference in the data; "link" is left for structured-context's links between notes.
What is drawn for an edge of the space graph, between two occurrences. "Edge" is the hierarchy or relationship reference in the data; "link" is left for structured-context's links between notes.

## Focus

The node a layout centres on. Hosts can set it; otherwise the reader's picks move it.
The node a layout is arranged around. Hosts can set it; otherwise the reader's picks move it.

## Parameter

A setting the reader can change. A definition declares each parameter once, as a JSON Schema with a default, and binds it to settings with `{ "$param": "<name>" }`. Hosts generate controls from the declared parameters and own the current values.

## Annotation

A validation result attached to a node: a severity, a source (the kind of check, such as `schema`, `hierarchy` or `rule`) and a message. Hosts supply annotations; a region's `nodes.validation` and `nodes.validationSources` settings choose which are drawn.
A validation result attached to a node: a severity, a source (the kind of check, such as `schema`, `hierarchy` or `rule`) and a message. Hosts supply annotations.

## Host

Expand Down
4 changes: 2 additions & 2 deletions packages/map-views/src/components/GraphLayout.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ import type { LayoutConfig } from '../core/definition';
import { assignLanes, type Connector, edgesWithin, isHierarchyEdge, occurrenceKey } from '../core/layouts/helpers';
import { ConnectorOverlay } from './ConnectorOverlay';
import { type LayoutProps, useOccurrenceElements } from './layout';
import { NodeCard } from './NodeCard';
import { NodeComponent } from './NodeComponent';

// Room each node needs. A card is a wide box; a shape is a marker with a label beside it.
const CARD_ROOM = { width: 230, height: 110 };
Expand Down Expand Up @@ -54,7 +54,7 @@ export function GraphLayout({ graph, region, instanceId, onNodeSelect }: LayoutP
style={{ left: x, top: y }}
>
<div ref={register(key)}>
<NodeCard node={node} repeat={false} nodes={region.nodes} onSelect={onNodeSelect} />
<NodeComponent node={node} repeat={false} nodes={region.nodes} onSelect={onNodeSelect} />
</div>
{shape && (
<span className="mv:whitespace-nowrap mv:rounded mv:bg-surface/80 mv:px-0.5 mv:text-xs">{node.title}</span>
Expand Down
4 changes: 2 additions & 2 deletions packages/map-views/src/components/LandscapeLayout.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ import type { SpaceNode } from 'structured-context/api';
import type { LayoutConfig, Orientation } from '../core/definition';
import { buildLandscape, type LandscapeGroup, type LandscapeOccurrence } from '../core/layouts/landscape/projection';
import type { LayoutProps } from './layout';
import { NodeCard } from './NodeCard';
import { NodeComponent } from './NodeComponent';

type Level = LayoutConfig<'landscape'>['strips'][number]['group'][number];

Expand Down Expand Up @@ -58,7 +58,7 @@ export function LandscapeLayout({ graph, region, instanceId, onNodeSelect }: Lay
if (occurrence.item.kind === 'node' && isLeaf(occurrence.level)) {
return (
<li key={occurrence.key} {...marker} className="mv:flex mv:flex-col mv:gap-0.5">
<NodeCard node={occurrence.item.node} repeat={repeat} nodes={region.nodes} onSelect={onNodeSelect} />
<NodeComponent node={occurrence.item.node} repeat={repeat} nodes={region.nodes} onSelect={onNodeSelect} />
{breadcrumb(occurrence, levels)}
</li>
);
Expand Down
4 changes: 2 additions & 2 deletions packages/map-views/src/components/NeighbourhoodLayout.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ import type { LayoutConfig } from '../core/definition';
import { buildNeighbourhood, type Neighbour } from '../core/layouts/neighbourhood/projection';
import { ConnectorOverlay } from './ConnectorOverlay';
import { type LayoutProps, useOccurrenceElements } from './layout';
import { NodeCard } from './NodeCard';
import { NodeComponent } from './NodeComponent';

// The most nodes across in the zones above and below, and down in the zones at the sides.
const ACROSS = 3;
Expand Down Expand Up @@ -46,7 +46,7 @@ export function NeighbourhoodLayout({
className="mv:relative mv:z-10"
data-occurrence={`${instanceId}${item.key}`}
>
<NodeCard node={item.node} repeat={false} nodes={region.nodes} onSelect={select} />
<NodeComponent node={item.node} repeat={false} nodes={region.nodes} onSelect={select} />
</div>
);
// A zone wraps into a few rows or columns, so a large one doesn't push the focus off screen.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ type Props = {
* tooltip. Deliberately a `div` with button semantics rather than a `<button>`: hosts style
* native form controls globally (Obsidian fixes button height and disables wrapping).
*/
export function NodeCard({ node, repeat, nodes, onSelect }: Props) {
export function NodeComponent({ node, repeat, nodes, onSelect }: Props) {
const select = () => onSelect?.(node);
const annotations = useAnnotations().get(node.id);
const label = `${node.resolvedType}: ${node.title}${repeat ? ' (shown in full elsewhere)' : ''}${annotationsLabel(annotations)}`;
Expand Down
4 changes: 2 additions & 2 deletions packages/map-views/src/components/TreeLayout.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ import type { LayoutConfig, Orientation } from '../core/definition';
import { buildTree, type TreeOccurrence, treeConnectors } from '../core/layouts/tree/projection';
import { ConnectorOverlay } from './ConnectorOverlay';
import { type LayoutProps, useOccurrenceElements } from './layout';
import { NodeCard } from './NodeCard';
import { NodeComponent } from './NodeComponent';

/**
* Tree over the schema's hierarchy. Flexbox does the branching; the SVG overlay draws connectors.
Expand All @@ -21,7 +21,7 @@ export function TreeLayout({ graph, region, instanceId, onNodeSelect }: LayoutPr
className={`mv:flex mv:items-center ${orientation === 'vertical' ? 'mv:flex-col' : 'mv:flex-row'}`}
>
<div ref={register(occurrence.key)} data-occurrence={`${instanceId}${occurrence.key}`}>
<NodeCard
<NodeComponent
node={occurrence.node}
repeat={occurrence.repeatOf !== undefined}
nodes={region.nodes}
Expand Down
6 changes: 3 additions & 3 deletions packages/map-views/src/components/XYLayout.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ import type { LayoutConfig } from '../core/definition';
import { buildXYPlot } from '../core/layouts/xy/projection';
import { ConnectorOverlay } from './ConnectorOverlay';
import { type LayoutProps, useOccurrenceElements } from './layout';
import { NodeCard } from './NodeCard';
import { NodeComponent } from './NodeComponent';

/**
* Nodes positioned by two numeric fields, with straight connectors between them. Positions are
Expand Down Expand Up @@ -41,7 +41,7 @@ export function XYLayout({ graph, region, instanceId, onNodeSelect }: LayoutProp
style={{ left: `${point.x * 100}%`, bottom: `${point.y * 100}%` }}
>
<div ref={register(point.key)}>
<NodeCard node={point.node} repeat={false} nodes={region.nodes} onSelect={onNodeSelect} />
<NodeComponent node={point.node} repeat={false} nodes={region.nodes} onSelect={onNodeSelect} />
</div>
{shape && (
<span className="mv:whitespace-nowrap mv:rounded mv:bg-surface/80 mv:px-0.5 mv:text-xs">
Expand All @@ -62,7 +62,7 @@ export function XYLayout({ graph, region, instanceId, onNodeSelect }: LayoutProp
<ul className="mv:m-0 mv:flex mv:list-none mv:flex-wrap mv:gap-3 mv:p-0">
{plot.unplaced.map(({ key, node, reasons }) => (
<li key={key} data-occurrence={`${instanceId}${key}`} className="mv:flex mv:items-center mv:gap-1">
<NodeCard node={node} repeat={false} nodes={region.nodes} onSelect={onNodeSelect} />
<NodeComponent node={node} repeat={false} nodes={region.nodes} onSelect={onNodeSelect} />
<span className="mv:text-xs">
{shape && `${node.title} `}
<span className="mv:text-muted">({reasons.join('; ')})</span>
Expand Down
2 changes: 1 addition & 1 deletion packages/map-views/src/components/annotations-context.ts
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ import type { AnnotationIndex } from '../core/annotations';

const NONE: AnnotationIndex = new Map();

/** The annotations a map view shows, already narrowed by its validation settings. Read by node cards. */
/** The annotations a map view shows, already narrowed by its validation settings. Read by node components. */
export const AnnotationsContext = createContext<AnnotationIndex>(NONE);

export const useAnnotations = () => useContext(AnnotationsContext);
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ import sample from './fixtures/launch-playbook.json';
const graph = fixtureGraph(sample);
const [definition] = loadMapViewDefinitions({ spaces: [] }, { configDir: '/nonexistent' });

describe('node cards', () => {
describe('node components', () => {
test('every card carries the id of a node in the graph, repeats included', () => {
const html = renderToStaticMarkup(createElement(MapView, { definition: definition!, graph, values: {} }));
const ids = [...html.matchAll(/data-node-id="([^"]*)"/g)].map((m) => m[1]!.replaceAll('&amp;', '&'));
Expand Down
Loading