Skip to content

Commit cb9aac5

Browse files
committed
List each layout once in core
core/layouts/schemas.ts holds the layout schemas and the checks a schema can't express. The schema list, the definition types and the layout branch of the definition schema are derived from it, and the per-layout config aliases give way to LayoutConfig<'name'>.
1 parent 3b6a6e6 commit cb9aac5

20 files changed

Lines changed: 93 additions & 82 deletions

‎AGENTS.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,7 @@ Work and open questions are tracked as GitHub issues on this repo.
3030

3131
## Adding a layout
3232

33-
A layout is a folder in `packages/map-views/src/core/layouts/<name>/` (`schema.ts`, and `projection.ts` only when deciding what is shown takes logic of its own) and a component in `src/components/`. It is registered in `core/definition.ts` (the schema list and the settings type), `core/schema/definition-schema.ts` (the `layout` branch) and `components/MapView.tsx`. It is documented in `docs/layouts.md` only. A projection decides what is shown; positions, sizes and anything a layout library computes belong in the component.
33+
A layout is a folder in `packages/map-views/src/core/layouts/<name>/` (`schema.ts`, and `projection.ts` only when deciding what is shown takes logic of its own) and a component in `src/components/`. It is registered in two lists: `core/layouts/schemas.ts` (its schema, and a check for any rule the schema can't express) and `LAYOUTS` in `components/MapView.tsx`. The definition format and the `LayoutConfig<'name'>` type follow from the first. It is documented in `docs/layouts.md` only. A projection decides what is shown; positions, sizes and anything a layout library computes belong in the component.
3434

3535
## Generated files
3636

‎packages/map-views/src/components/GraphLayout.tsx‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
import { forceCollide, forceLink, forceManyBody, forceSimulation, forceX, forceY } from 'd3-force';
22
import { useMemo } from 'react';
33
import type { SpaceGraph } from 'structured-context/api';
4-
import type { GraphLayoutConfig } from '../core/definition';
4+
import type { LayoutConfig } from '../core/definition';
55
import { assignLanes, type Connector, edgesWithin, isHierarchyEdge, occurrenceKey } from '../core/layouts/helpers';
66
import { ConnectorOverlay } from './ConnectorOverlay';
77
import { type LayoutProps, useOccurrenceElements } from './layout';
@@ -23,7 +23,7 @@ const LOOSE_PER_ROW = 4;
2323
* hierarchy edges hold their nodes close and each level settles below the one above, while
2424
* relationship edges pull weakly and are drawn dashed.
2525
*/
26-
export function GraphLayout({ graph, region, instanceId, onNodeSelect }: LayoutProps<GraphLayoutConfig>) {
26+
export function GraphLayout({ graph, region, instanceId, onNodeSelect }: LayoutProps<LayoutConfig<'graph'>>) {
2727
const shape = region.nodes.style === 'shape';
2828
const plot = useMemo(
2929
() => settle(graph, region.id, region.layout.edgeFields, shape ? SHAPE_ROOM : CARD_ROOM),

‎packages/map-views/src/components/LandscapeLayout.tsx‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
import { useMemo } from 'react';
22
import type { SpaceNode } from 'structured-context/api';
3-
import type { LandscapeLayoutConfig, Orientation } from '../core/definition';
3+
import type { LayoutConfig, Orientation } from '../core/definition';
44
import { buildLandscape, type LandscapeOccurrence } from '../core/layouts/landscape/projection';
55
import type { LayoutProps } from './layout';
66
import { NodeCard } from './NodeCard';
@@ -10,7 +10,7 @@ import { NodeCard } from './NodeCard';
1010
* Flexbox does the nesting and wrapping. Containment shows the grouping edges, so no connectors
1111
* are drawn. PROTOTYPE: `edges.show` has no effect here; other edges aren't drawn yet.
1212
*/
13-
export function LandscapeLayout({ graph, region, instanceId, onNodeSelect }: LayoutProps<LandscapeLayoutConfig>) {
13+
export function LandscapeLayout({ graph, region, instanceId, onNodeSelect }: LayoutProps<LayoutConfig<'landscape'>>) {
1414
const { layout } = region;
1515
const landscape = useMemo(() => buildLandscape(graph, region.id, layout), [graph, region.id, layout]);
1616
const last = layout.group.length - 1;

‎packages/map-views/src/components/MapView.tsx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,7 @@ type Props = {
2727

2828
const EMPTY: AnnotationIndex = new Map();
2929

30-
const LAYOUTS: { [T in LayoutConfig['type']]: ComponentType<LayoutProps<Extract<LayoutConfig, { type: T }>>> } = {
30+
const LAYOUTS: { [T in LayoutConfig['type']]: ComponentType<LayoutProps<LayoutConfig<T>>> } = {
3131
tree: TreeLayout,
3232
landscape: LandscapeLayout,
3333
xy: XYLayout,

‎packages/map-views/src/components/NeighbourhoodLayout.tsx‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
import { useMemo, useState } from 'react';
22
import type { SpaceNode } from 'structured-context/api';
3-
import type { NeighbourhoodLayoutConfig } from '../core/definition';
3+
import type { LayoutConfig } from '../core/definition';
44
import { buildNeighbourhood, type Neighbour } from '../core/layouts/neighbourhood/projection';
55
import { ConnectorOverlay } from './ConnectorOverlay';
66
import { type LayoutProps, useOccurrenceElements } from './layout';
@@ -21,7 +21,7 @@ export function NeighbourhoodLayout({
2121
onNodeSelect,
2222
focus,
2323
onFocusChange,
24-
}: LayoutProps<NeighbourhoodLayoutConfig>) {
24+
}: LayoutProps<LayoutConfig<'neighbourhood'>>) {
2525
const [picked, setPicked] = useState<{ from: SpaceNode['id'] | undefined; id: SpaceNode['id'] }>();
2626
// A focus the host sets later wins over the reader's earlier pick.
2727
const focusId = picked && picked.from === focus ? picked.id : focus;

‎packages/map-views/src/components/TreeLayout.tsx‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
import { useMemo } from 'react';
2-
import type { Orientation, TreeLayoutConfig } from '../core/definition';
2+
import type { LayoutConfig, Orientation } from '../core/definition';
33
import { buildTree, type TreeOccurrence, treeConnectors } from '../core/layouts/tree/projection';
44
import { ConnectorOverlay } from './ConnectorOverlay';
55
import { type LayoutProps, useOccurrenceElements } from './layout';
@@ -8,7 +8,7 @@ import { NodeCard } from './NodeCard';
88
/**
99
* Tree over the schema's hierarchy. Flexbox does the branching; the SVG overlay draws connectors.
1010
*/
11-
export function TreeLayout({ graph, region, instanceId, onNodeSelect }: LayoutProps<TreeLayoutConfig>) {
11+
export function TreeLayout({ graph, region, instanceId, onNodeSelect }: LayoutProps<LayoutConfig<'tree'>>) {
1212
const { orientation, dag } = region.layout;
1313
const tree = useMemo(() => buildTree(graph, region.id, dag), [graph, region.id, dag]);
1414
const connectors = useMemo(() => treeConnectors(tree), [tree]);

‎packages/map-views/src/components/XYLayout.tsx‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
import { useMemo } from 'react';
2-
import type { AxisConfig, XYLayoutConfig } from '../core/definition';
2+
import type { LayoutConfig } from '../core/definition';
33
import { buildXYPlot } from '../core/layouts/xy/projection';
44
import { ConnectorOverlay } from './ConnectorOverlay';
55
import { type LayoutProps, useOccurrenceElements } from './layout';
@@ -11,7 +11,7 @@ import { NodeCard } from './NodeCard';
1111
* placed are listed under the plot with the reason.
1212
* PROTOTYPE: labels may overlap where nodes sit close together; no collision handling.
1313
*/
14-
export function XYLayout({ graph, region, instanceId, onNodeSelect }: LayoutProps<XYLayoutConfig>) {
14+
export function XYLayout({ graph, region, instanceId, onNodeSelect }: LayoutProps<LayoutConfig<'xy'>>) {
1515
const { layout } = region;
1616
const plot = useMemo(() => buildXYPlot(graph, region.id, layout), [graph, region.id, layout]);
1717
const shape = region.nodes.style === 'shape';
@@ -82,7 +82,7 @@ function AxisTitle({
8282
domain: [min, max],
8383
vertical = false,
8484
}: {
85-
axis: AxisConfig;
85+
axis: LayoutConfig<'xy'>['x'];
8686
domain: readonly [number, number];
8787
vertical?: boolean;
8888
}) {

‎packages/map-views/src/core/definition.ts‎

Lines changed: 15 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -1,36 +1,16 @@
11
import Ajv2020, { type AnySchemaObject, type ErrorObject } from 'ajv/dist/2020';
22
import type { FromSchema } from 'json-schema-to-ts';
33
import JSON5 from 'json5';
4-
import { graphLayoutSchema } from './layouts/graph/schema';
5-
import { landscapeLayoutSchema } from './layouts/landscape/schema';
6-
import { neighbourhoodLayoutSchema } from './layouts/neighbourhood/schema';
7-
import { treeLayoutSchema } from './layouts/tree/schema';
8-
import { xyLayoutSchema } from './layouts/xy/schema';
4+
import { layoutChecks, layoutSchemas } from './layouts/schemas';
95
import { definitionSchema } from './schema/definition-schema';
106
import { SCHEMA_URL } from './schema/schema-url';
117
import { settingsSchema } from './schema/settings';
128

139
/** The bundled schemas describing the map view definition format. */
14-
export const MAP_VIEW_SCHEMAS = [
15-
definitionSchema,
16-
settingsSchema,
17-
treeLayoutSchema,
18-
landscapeLayoutSchema,
19-
xyLayoutSchema,
20-
neighbourhoodLayoutSchema,
21-
graphLayoutSchema,
22-
] as const;
10+
export const MAP_VIEW_SCHEMAS = [definitionSchema, settingsSchema, ...layoutSchemas] as const;
2311

2412
type References = {
25-
references: [
26-
typeof settingsSchema,
27-
typeof treeLayoutSchema,
28-
typeof landscapeLayoutSchema,
29-
typeof xyLayoutSchema,
30-
typeof neighbourhoodLayoutSchema,
31-
typeof graphLayoutSchema,
32-
typeof definitionSchema,
33-
];
13+
references: [typeof settingsSchema, ...typeof layoutSchemas, typeof definitionSchema];
3414
// Grouping levels dispatch with if/then/else (see the landscape layout schema).
3515
parseIfThenElseKeywords: true;
3616
};
@@ -50,21 +30,20 @@ export type AuthoredDefinition = FromSchema<
5030
References & { keepDefaultedPropertiesOptional: true }
5131
>;
5232
type FilledDefinition = FromSchema<typeof definitionSchema, References>;
33+
type LayoutOf<L extends { type: string }, T extends L['type']> = Extract<L, { type: T }>;
34+
/** One layout's settings as authored. */
35+
export type AuthoredLayout<
36+
T extends
37+
AuthoredDefinition['regions'][number]['layout']['type'] = AuthoredDefinition['regions'][number]['layout']['type'],
38+
> = LayoutOf<AuthoredDefinition['regions'][number]['layout'], T>;
5339

5440
/** A region with parameters applied and defaults filled in: what layouts receive. */
5541
export type Region = Resolved<FilledDefinition['regions'][number]>;
56-
export type LayoutConfig = Region['layout'];
57-
export type TreeLayoutConfig = Extract<LayoutConfig, { type: 'tree' }>;
58-
export type LandscapeLayoutConfig = Extract<LayoutConfig, { type: 'landscape' }>;
59-
export type XYLayoutConfig = Extract<LayoutConfig, { type: 'xy' }>;
60-
export type NeighbourhoodLayoutConfig = Extract<LayoutConfig, { type: 'neighbourhood' }>;
61-
export type GraphLayoutConfig = Extract<LayoutConfig, { type: 'graph' }>;
62-
export type AxisConfig = XYLayoutConfig['x'];
63-
export type GroupLevel = LandscapeLayoutConfig['group'][number];
42+
/** A layout's settings, resolved: every layout's, or those of the layout `T` names. */
43+
export type LayoutConfig<T extends Region['layout']['type'] = Region['layout']['type']> = LayoutOf<Region['layout'], T>;
6444
export type NodesConfig = Region['nodes'];
6545
export type EdgesConfig = Region['edges'];
66-
export type Orientation = TreeLayoutConfig['orientation'];
67-
export type DagMode = TreeLayoutConfig['dag'];
46+
export type Orientation = LayoutConfig<'tree'>['orientation'];
6847

6948
/**
7049
* A validated map view definition. Plain data, so hosts can pass it across a server/browser
@@ -162,18 +141,9 @@ export function parseMapViewDefinition(name: string, text: string): MapViewDefin
162141
for (const region of source.regions) {
163142
if (regionIds.has(region.id)) fail(`duplicate region id "${region.id}"`);
164143
regionIds.add(region.id);
165-
// A field level labels the nodes of a later level, so a node level must come last.
166-
if (region.layout.type === 'landscape' && !('type' in region.layout.group.at(-1)!)) {
167-
fail(`region "${region.id}": the last grouping level must be a node type, not a field`);
168-
}
169-
if (region.layout.type === 'xy') {
170-
for (const axis of ['x', 'y'] as const) {
171-
const { domain } = region.layout[axis];
172-
if (Array.isArray(domain) && !(domain[0]! < domain[1]!)) {
173-
fail(`region "${region.id}": ${axis} domain must be [min, max] with min < max`);
174-
}
175-
}
176-
}
144+
// The check is the one for this layout's type, which TypeScript can't relate to the settings.
145+
const broken = layoutChecks[region.layout.type]?.(region.layout as never);
146+
if (broken) fail(`region "${region.id}": ${broken}`);
177147
}
178148

179149
return {

‎packages/map-views/src/core/layouts/landscape/projection.ts‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
import type { SpaceGraph, SpaceNode } from 'structured-context/api';
2-
import type { GroupLevel, LandscapeLayoutConfig } from '../../definition';
2+
import type { LayoutConfig } from '../../definition';
33
import { childEdges, occurrenceKey, type PathSegment, parentEdges } from '../helpers';
44

55
/** One rendered container or node in a landscape. */
@@ -39,7 +39,7 @@ type FieldFilter = { field: string; value: string | null };
3939
* splits the next node level by that field's values. A node reached from several containers
4040
* appears in each, in full: the levels are finite, so repeating contents can't recurse.
4141
*/
42-
export function buildLandscape(graph: SpaceGraph, regionId: string, layout: LandscapeLayoutConfig): Landscape {
42+
export function buildLandscape(graph: SpaceGraph, regionId: string, layout: LayoutConfig<'landscape'>): Landscape {
4343
const levels = layout.group;
4444
const order = new Map([...graph.nodes.keys()].map((title, i) => [title, i]));
4545
const first = new Map<string, string>();
@@ -160,6 +160,7 @@ export function buildLandscape(graph: SpaceGraph, regionId: string, layout: Land
160160
return { groups, ungrouped };
161161
}
162162

163+
type GroupLevel = LayoutConfig<'landscape'>['group'][number];
163164
type TypeLevel = Extract<GroupLevel, { type: string }>;
164165

165166
function isTypeLevel(level: GroupLevel): level is TypeLevel {

‎packages/map-views/src/core/layouts/landscape/schema.ts‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
import type { AuthoredLayout } from '../../definition';
12
import { PARAM_REF, parameterisable } from '../../schema/param-ref';
23
import { SCHEMA_URL } from '../../schema/schema-url';
34

@@ -79,3 +80,8 @@ export const landscapeLayoutSchema = {
7980
},
8081
},
8182
} as const;
83+
84+
export function checkLandscapeLayout(layout: AuthoredLayout<'landscape'>) {
85+
// A field level labels the nodes of a later level, so a node level must come last.
86+
if (!('type' in layout.group.at(-1)!)) return 'the last grouping level must be a node type, not a field';
87+
}

0 commit comments

Comments
 (0)