diff --git a/AGENTS.md b/AGENTS.md index 57a86cd..991bd83 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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 diff --git a/docs/architecture.md b/docs/architecture.md index c7b5a78..c0579cd 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -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//`). 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 | @@ -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 diff --git a/docs/concepts.md b/docs/concepts.md index a124ada..d26f249 100644 --- a/docs/concepts.md +++ b/docs/concepts.md @@ -16,7 +16,7 @@ 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 @@ -24,15 +24,19 @@ The step some layouts need to decide what is shown: it turns a space graph and t ## 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 @@ -40,7 +44,7 @@ A setting the reader can change. A definition declares each parameter once, as a ## 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 diff --git a/packages/map-views/src/components/GraphLayout.tsx b/packages/map-views/src/components/GraphLayout.tsx index 21ea133..5073f91 100644 --- a/packages/map-views/src/components/GraphLayout.tsx +++ b/packages/map-views/src/components/GraphLayout.tsx @@ -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 }; @@ -54,7 +54,7 @@ export function GraphLayout({ graph, region, instanceId, onNodeSelect }: LayoutP style={{ left: x, top: y }} >
- +
{shape && ( {node.title} diff --git a/packages/map-views/src/components/LandscapeLayout.tsx b/packages/map-views/src/components/LandscapeLayout.tsx index 1567ab2..dfa9c07 100644 --- a/packages/map-views/src/components/LandscapeLayout.tsx +++ b/packages/map-views/src/components/LandscapeLayout.tsx @@ -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]; @@ -58,7 +58,7 @@ export function LandscapeLayout({ graph, region, instanceId, onNodeSelect }: Lay if (occurrence.item.kind === 'node' && isLeaf(occurrence.level)) { return (
  • - + {breadcrumb(occurrence, levels)}
  • ); diff --git a/packages/map-views/src/components/NeighbourhoodLayout.tsx b/packages/map-views/src/components/NeighbourhoodLayout.tsx index cd2ea9f..3254129 100644 --- a/packages/map-views/src/components/NeighbourhoodLayout.tsx +++ b/packages/map-views/src/components/NeighbourhoodLayout.tsx @@ -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; @@ -46,7 +46,7 @@ export function NeighbourhoodLayout({ className="mv:relative mv:z-10" data-occurrence={`${instanceId}${item.key}`} > - + ); // A zone wraps into a few rows or columns, so a large one doesn't push the focus off screen. diff --git a/packages/map-views/src/components/NodeCard.tsx b/packages/map-views/src/components/NodeComponent.tsx similarity index 98% rename from packages/map-views/src/components/NodeCard.tsx rename to packages/map-views/src/components/NodeComponent.tsx index 2640f52..3f0c73f 100644 --- a/packages/map-views/src/components/NodeCard.tsx +++ b/packages/map-views/src/components/NodeComponent.tsx @@ -16,7 +16,7 @@ type Props = { * tooltip. Deliberately a `div` with button semantics rather than a `