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
7 changes: 4 additions & 3 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

Declarative map views of structured-context spaces: the definition format, the rendering library and the navigator app.

Before new work, read [docs/concepts.md](docs/concepts.md) for the terms and [docs/architecture.md](docs/architecture.md#modules) for the modules and what each may import. Use the terms in code, tests, comments and docs.
Before new work, read [docs/concepts.md](docs/concepts.md) for the terms (and the layout's section of [docs/layouts.md](docs/layouts.md) when working on one layout) and [docs/architecture.md](docs/architecture.md#modules) for the modules and what each may import.

## Checks

Expand All @@ -15,8 +15,9 @@ bun run build # the library, then the navigator
## Principles

- **Simple, not sloppy.** Prefer the smallest design that does the job. Don't add structures, grammars, limits or presets until a concrete need forces them.
- **One word per concept.** A thing has the same name in the definition format, the docs and the code. Add or rename a term in `docs/concepts.md` first, then use it. Don't rename another package's term: use structured-context's own word and type.
- **One term per concept.** A thing has the same name in the definition format, the docs, comments and code. Add, rename or refine common terms (when they're unclear or new requirements go beyond existing definitions) in `docs/concepts.md`, and do the same in `docs/layouts.md` for a term only one layout uses. Don't rename another package's term: use structured-context's own word and type.
- **One home per fact.** Decide which doc owns a fact, state it there once, and link from elsewhere. Docs don't list what the code already lists (layouts, exports, props, files, variables): a list like that goes stale with the next change.
- **A setting's type says how many behaviours it has.** A boolean for on or off, when no third option is expected. An enum when there are two or more behaviours, each value naming one (`dag: 'repeat' | 'cross-edge'`).
- **Export only what another module imports.** A type used in one place is written inline. A type used in one file isn't exported. Derive types (from the schemas, `Parameters`, `ReturnType`, `Pick`) instead of restating a shape. When two modules need the same shape, they share one type.
- **The public surface is `src/index.ts`, `src/node/index.ts` and `src/node/html.ts`.** Add an export there only when a host needs it, and say which host.
- **Comments say what the code can't.** A reason, a constraint, a trap. Never the signature, the parameter list or the next line.
Expand Down Expand Up @@ -51,7 +52,7 @@ Review and update with any change:
| Change | Check |
|---|---|
| Definition format (`core/schema`, `core/layouts/*/schema.ts`) | `docs/definitions.md`, or `docs/layouts.md` for layout settings; regenerated `schemas/generated/latest/`; definitions in `map-views/` |
| New or renamed term | `docs/concepts.md` |
| New or renamed term | `docs/concepts.md`; and `docs/layouts.md` for a term of one layout |
| Exports or component props | `docs/api.md` |
| Module structure, rendering, styling | `docs/architecture.md` |
| Anything user-visible | `README.md` (kept short; detail goes in `docs/`) |
Expand Down
2 changes: 1 addition & 1 deletion docs/concepts.md
Original file line number Diff line number Diff line change
Expand Up @@ -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, with the terms that belong to it alone.
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.

## Projection

Expand Down
28 changes: 23 additions & 5 deletions docs/layouts.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,22 +15,40 @@ A tree over the schema's hierarchy: nodes of the root type at the top, children

## landscape

Nested containers. `group` lists grouping levels, outermost first. The last level is drawn as nodes and the others as containers.
Strips of nested containers. A **strip** is a list of grouping levels, outermost first: the last level is drawn as nodes and the others as containers. A plain landscape is one strip. Several strips are drawn one after the other, each with its own levels.

A **dimension** divides strips into **cells**, one for each of its groups. The layout's dimension divides every strip alike, so the strips line up; a strip's own dimension divides that strip further. With both, a strip has a cell for every pair of groups.

| Setting | Values | Default |
|---|---|---|
| `orientation` | `horizontal`: top-level containers, or the layout dimension's groups, side by side, and strips stacked. `vertical`: the reverse | `horizontal` |
| `dimension` | A dimension (below) dividing every strip | none |
| `strips` | One or more strips | required |

A strip has:

| Setting | Values | Default |
|---|---|---|
| `orientation` | `horizontal` (top-level containers as columns), `vertical` (as rows) | `horizontal` |
| `group` | Grouping levels (below) | required |
| `group` | Grouping levels, outermost first | required |
| `dimension` | A dimension dividing this strip | none |
| `showUngrouped` | `true` draws the strip's ungrouped nodes in a box of their own, `false` leaves them out | `true` |

A grouping level is one of:
A level is one of:

- `{ type: 'Activities' }`: a level of nodes of one type. Adjacent node levels are joined by any edge between their types, in either direction, so `Outcomes` can group `Activities` even when the edge is declared from `Activities`.
- `edge: { field: 'phase' }` restricts the join to edges from that field.
- `via: ['Capabilities']` joins through a chain of edges across the listed types, in order.
- `intermediate`: how the skipped nodes of a `via` chain are shown. `hidden` (default) or `breadcrumb` (listed on each node reached through them).
- `{ field: 'status' }`: containers labelled by the values of a field on the next node level. A node with several values appears under each.

A node that occurs in several containers is repeated in each. Nodes of a grouped type that no container reaches are shown as ungrouped, not dropped.
A dimension is one of:

- `{ type: 'Stages' }`: a group for every node of the type, in space order, so a cell exists even when it holds nothing. `edge: { field: 'stage' }` restricts the join to edges from that field, and takes the place of the first level's own `edge`.
- `{ field: 'stage' }`: a group for every value the strip's first node level has in that field. A value no node has is not a group.

A strip's first level is joined to a dimension's nodes the way a level is joined to the node level above, so `via` applies there: a strip of `{ type: 'Capabilities', via: ['Activities'] }` under a `Stages` dimension holds each stage's capabilities once, beside a strip of its activities. Under two dimensions, a node must be joined to both.

A node that occurs in several containers or cells is repeated in each. Nodes of a strip's levels that no container or cell reaches are ungrouped. Each strip is named by its first level.

## xy

Expand Down
202 changes: 173 additions & 29 deletions packages/map-views/src/components/LandscapeLayout.tsx
Original file line number Diff line number Diff line change
@@ -1,22 +1,24 @@
import { useMemo } from 'react';
import type { SpaceNode } from 'structured-context/api';
import type { LayoutConfig, Orientation } from '../core/definition';
import { buildLandscape, type LandscapeOccurrence } from '../core/layouts/landscape/projection';
import { buildLandscape, type LandscapeGroup, type LandscapeOccurrence } from '../core/layouts/landscape/projection';
import type { LayoutProps } from './layout';
import { NodeCard } from './NodeCard';

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

/**
* Nested containers following the layout's grouping levels; the last level is drawn as nodes.
* Flexbox does the nesting and wrapping. Containment shows the grouping edges, so no connectors
* are drawn. PROTOTYPE: `edges.show` has no effect here; other edges aren't drawn yet.
* Strips of nested containers following each strip's grouping levels; the last level is drawn as
* nodes. Flexbox does the nesting and wrapping, and CSS grid lays out strips divided into cells.
* Containment shows the grouping edges, so no connectors are drawn. PROTOTYPE: `edges.show` has no
* effect here; other edges aren't drawn yet.
*/
export function LandscapeLayout({ graph, region, instanceId, onNodeSelect }: LayoutProps<LayoutConfig<'landscape'>>) {
const { layout } = region;
const landscape = useMemo(() => buildLandscape(graph, region.id, layout), [graph, region.id, layout]);
const last = layout.group.length - 1;

const breadcrumb = (occurrence: LandscapeOccurrence) => {
const level = layout.group[occurrence.level];
const breadcrumb = (occurrence: LandscapeOccurrence, levels: readonly Level[]) => {
const level = levels[occurrence.level];
if (!level || !('type' in level) || level.intermediate !== 'breadcrumb') return null;
const steps = occurrence.via.filter((step) => step.nodes.length > 0);
if (steps.length === 0) return null;
Expand All @@ -27,60 +29,202 @@ export function LandscapeLayout({ graph, region, instanceId, onNodeSelect }: Lay
);
};

const render = (occurrence: LandscapeOccurrence, direction: Orientation): React.ReactNode => {
/** The label of a container or a dimension's group: its node, or its field value. */
const heading = (occurrence: LandscapeGroup | LandscapeOccurrence, levels: readonly Level[] = []) =>
occurrence.item.kind === 'node' ? (
<ContainerHeading
node={occurrence.item.node}
repeat={'repeatOf' in occurrence && occurrence.repeatOf !== undefined}
onSelect={onNodeSelect}
>
{'level' in occurrence && breadcrumb(occurrence, levels)}
</ContainerHeading>
) : (
<span className="mv:text-xs mv:font-semibold mv:text-muted">
{occurrence.item.field}: {occurrence.item.value === null ? '(none)' : displayValue(occurrence.item.value)}
</span>
);

const render = (
occurrence: LandscapeOccurrence,
direction: Orientation,
levels: readonly Level[],
): React.ReactNode => {
const repeat = occurrence.repeatOf !== undefined;
const marker = { 'data-occurrence': `${instanceId}${occurrence.key}` };
// A level is drawn as nodes when it is the strip's last.
const isLeaf = (level: number) => level === levels.length - 1;

if (occurrence.item.kind === 'node' && occurrence.level === last) {
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} />
{breadcrumb(occurrence)}
{breadcrumb(occurrence, levels)}
</li>
);
}

// Containers alternate direction with depth; a container of nodes wraps them.
const inner: Orientation = direction === 'horizontal' ? 'vertical' : 'horizontal';
const holdsNodes = occurrence.level + 1 === last;
const holdsNodes = isLeaf(occurrence.level + 1);
return (
<li
key={occurrence.key}
{...marker}
className={`mv:flex mv:flex-col mv:gap-2 mv:rounded-lg mv:border mv:bg-surface mv:p-2 ${repeat ? 'mv:border-dashed mv:border-muted/60' : 'mv:border-edge'}`}
>
{occurrence.item.kind === 'node' ? (
<ContainerHeading node={occurrence.item.node} repeat={repeat} onSelect={onNodeSelect}>
{breadcrumb(occurrence)}
</ContainerHeading>
) : (
<span className="mv:text-xs mv:font-semibold mv:text-muted">
{occurrence.item.field}: {occurrence.item.value === null ? '(none)' : displayValue(occurrence.item.value)}
</span>
)}
{heading(occurrence, levels)}
<Items direction={holdsNodes ? 'wrap' : inner}>
{occurrence.children.map((child) => render(child, inner))}
{occurrence.children.map((child) => render(child, inner, levels))}
</Items>
</li>
);
};

const top = layout.orientation;
const ungroupedClass = 'mv:flex mv:flex-col mv:gap-2 mv:rounded-lg mv:border mv:border-dashed mv:border-edge mv:p-2';
const ungroupedItems = (ungrouped: LandscapeOccurrence[], levels: readonly Level[]) => (
<>
<span className="mv:text-xs mv:font-semibold mv:text-muted">Ungrouped</span>
<Items direction="wrap">{ungrouped.map((o) => render(o, top, levels))}</Items>
</>
);

const [only] = landscape.strips;
// One strip with no dimension of either kind is plain nested containers, with no grid.
const plain = only && landscape.strips.length === 1 && !landscape.dimension && !only.dimension;
if (!plain) {
const anyOwn = landscape.strips.some((strip) => strip.dimension);
// A strip takes a position for each group of its own dimension (one without), and one for its ungrouped nodes.
const sizes = landscape.strips.map(
(strip) => (strip.dimension?.length ?? 1) + (strip.ungrouped.length > 0 ? 1 : 0),
);
const starts = sizes.map(
(_, s) => 1 + (landscape.dimension ? 1 : 0) + sizes.slice(0, s).reduce((a, b) => a + b, 0),
);
const place = gridPlacement(top, {
lead: anyOwn ? 2 : 1,
dimensionSize: landscape.dimension?.length ?? 1,
leadStrips: landscape.dimension ? 1 : 0,
strips: sizes.reduce((a, b) => a + b, 0),
});
return (
<div className="mv:w-max mv:min-w-full mv:p-4">
<div data-grid className="mv:grid mv:gap-2" style={place.container}>
{landscape.dimension?.map((group, i) => (
<div
key={group.key}
data-dimension="layout"
{...{ 'data-occurrence': `${instanceId}${group.key}` }}
className="mv:self-center mv:px-1"
style={place.heading(i)}
>
{heading(group)}
</div>
))}
{landscape.strips.map((strip, s) => {
const levels = layout.strips[s]!.group;
const start = starts[s]!;
return (
// biome-ignore lint/suspicious/noArrayIndexKey: strips are positional, fixed by the definition.
<div key={s} className="mv:contents" data-strip={s}>
<div
data-strip-name
className="mv:self-center mv:px-1 mv:text-xs mv:font-semibold mv:uppercase mv:tracking-wide mv:text-muted"
style={place.name(start, Math.max(sizes[s]!, 1))}
>
{levelLabel(levels[0]!)}
</div>
{strip.dimension?.map((group, j) => (
<div
key={group.key}
data-dimension="strip"
{...{ 'data-occurrence': `${instanceId}${group.key}` }}
className="mv:self-center mv:px-1"
style={place.stripHeading(start + j)}
>
{heading(group)}
</div>
))}
{strip.cells.map((cell) => (
<div
key={cell.key}
data-cell
data-strip-cell={s}
className="mv:min-h-12 mv:rounded-lg mv:border mv:border-edge mv:bg-surface mv:p-2"
style={place.cell(cell.at[0], start + cell.at[1])}
>
<Items direction="vertical">{cell.children.map((child) => render(child, top, levels))}</Items>
</div>
))}
{strip.ungrouped.length > 0 && (
<div
data-ungrouped
className={ungroupedClass}
style={place.ungrouped(start + (strip.dimension?.length ?? 1))}
>
{ungroupedItems(strip.ungrouped, levels)}
</div>
)}
</div>
);
})}
</div>
</div>
);
}

const levels = layout.strips[0]!.group;
return (
<div className="mv:w-max mv:min-w-full mv:p-4">
<Items direction={last === 0 ? 'wrap' : top}>
{landscape.groups.map((group) => render(group, top))}
{landscape.ungrouped.length > 0 && (
<li className="mv:flex mv:flex-col mv:gap-2 mv:rounded-lg mv:border mv:border-dashed mv:border-edge mv:p-2">
<span className="mv:text-xs mv:font-semibold mv:text-muted">Ungrouped</span>
<Items direction="wrap">{landscape.ungrouped.map((o) => render(o, top))}</Items>
</li>
)}
<Items direction={levels.length === 1 ? 'wrap' : top}>
{only.cells[0]!.children.map((group) => render(group, top, levels))}
{only.ungrouped.length > 0 && <li className={ungroupedClass}>{ungroupedItems(only.ungrouped, levels)}</li>}
</Items>
</div>
);
}

const levelLabel = (level: Level) => ('type' in level ? level.type : level.field);

/**
* Where the grid's labels, headings and cells go. The only place that decides which way the layout
* dimension runs: with `horizontal` its groups sit side by side, like top-level containers elsewhere
* in this layout, and strips stack; with `vertical` its groups stack and strips sit side by side.
* Along the layout dimension's axis, the leading positions hold the strip names and, if any strip
* has its own dimension, that dimension's headings. Along the strips' axis, the first holds the
* layout dimension's headings.
* PROTOTYPE: track sizes are fixed guesses, headings scroll away with the grid, and a grid has no
* connectors or highlights.
*/
function gridPlacement(
orientation: Orientation,
shape: { lead: number; dimensionSize: number; leadStrips: number; strips: number },
) {
const dimensionAcross = orientation === 'horizontal';
/** A start line, and how many lines it spans. */
const lines = (start: number, span = 1) => (span === 1 ? start : `${start} / span ${span}`);
/** `onDimension` runs along the layout dimension's axis, `onStrips` along the strips'. */
const at = (onDimension: number, onStrips: number, dimensionSpan = 1, stripsSpan = 1) =>
dimensionAcross
? { gridColumn: lines(onDimension, dimensionSpan), gridRow: lines(onStrips, stripsSpan) }
: { gridColumn: lines(onStrips, stripsSpan), gridRow: lines(onDimension, dimensionSpan) };
const groupsStart = shape.lead + 1;
return {
// Only the columns are given tracks; the rows size to their content.
container: {
gridTemplateColumns: dimensionAcross
? `${'max-content '.repeat(shape.lead)}repeat(${shape.dimensionSize}, minmax(9rem, 1fr))`
: `${'max-content '.repeat(shape.leadStrips)}repeat(${shape.strips}, minmax(9rem, 1fr))`,
},
heading: (index: number) => at(groupsStart + index, 1),
name: (start: number, span: number) => at(1, start, 1, span),
stripHeading: (line: number) => at(2, line),
cell: (index: number, line: number) => at(groupsStart + index, line),
ungrouped: (line: number) => at(groupsStart, line, shape.dimensionSize),
};
}

function Items({ direction, children }: { direction: Orientation | 'wrap'; children: React.ReactNode }) {
const layout = {
horizontal: 'mv:flex-row mv:items-start mv:gap-3',
Expand Down
Loading
Loading