structured-context-map-views 0.0.0-stage → 0.2.0

package/dist/styles.css

@@ -0,0 +1,528 @@
+/*! tailwindcss v4.3.3 | MIT License | https://tailwindcss.com */
+@layer properties;
+@layer theme {
+  :root, :host {
+    --mv-color-white: #fff;
+    --mv-spacing: 0.25rem;
+    --mv-text-xs: 0.75rem;
+    --mv-text-xs--line-height: calc(1 / 0.75);
+    --mv-text-sm: 0.875rem;
+    --mv-text-sm--line-height: calc(1.25 / 0.875);
+    --mv-font-weight-semibold: 600;
+    --mv-tracking-wide: 0.025em;
+    --mv-leading-tight: 1.25;
+    --mv-leading-snug: 1.375;
+    --mv-radius-md: 0.375rem;
+    --mv-radius-lg: 0.5rem;
+    --mv-color-surface: #f8f8f7;
+    --mv-color-card: #ffffff;
+    --mv-color-ink: #1f2328;
+    --mv-color-muted: #59636e;
+    --mv-color-edge: #d1d9e0;
+    --mv-color-accent: #0969da;
+    --mv-color-error: #cf222e;
+    --mv-color-warning: #9a6700;
+    --mv-color-info: #0969da;
+  }
+}
+.mv\:pointer-events-none {
+  pointer-events: none;
+}
+.mv\:absolute {
+  position: absolute;
+}
+.mv\:relative {
+  position: relative;
+}
+.mv\:inset-0 {
+  inset: 0px;
+}
+.mv\:inset-8 {
+  inset: calc(var(--mv-spacing) * 8);
+}
+.mv\:-top-1\.5 {
+  top: calc(var(--mv-spacing) * -1.5);
+}
+.mv\:-right-1\.5 {
+  right: calc(var(--mv-spacing) * -1.5);
+}
+.mv\:float-left {
+  float: left;
+}
+.mv\:m-0 {
+  margin: 0px;
+}
+.mv\:mt-1 {
+  margin-top: var(--mv-spacing);
+}
+.mv\:mr-1\.5 {
+  margin-right: calc(var(--mv-spacing) * 1.5);
+}
+.mv\:box-border {
+  box-sizing: border-box;
+}
+.mv\:block {
+  display: block;
+}
+.mv\:flex {
+  display: flex;
+}
+.mv\:grid {
+  display: grid;
+}
+.mv\:size-6 {
+  width: calc(var(--mv-spacing) * 6);
+  height: calc(var(--mv-spacing) * 6);
+}
+.mv\:h-4 {
+  height: calc(var(--mv-spacing) * 4);
+}
+.mv\:h-full {
+  height: 100%;
+}
+.mv\:min-h-0 {
+  min-height: 0px;
+}
+.mv\:min-h-\[28rem\] {
+  min-height: 28rem;
+}
+.mv\:w-44 {
+  width: calc(var(--mv-spacing) * 44);
+}
+.mv\:w-full {
+  width: 100%;
+}
+.mv\:w-max {
+  width: max-content;
+}
+.mv\:max-w-44 {
+  max-width: calc(var(--mv-spacing) * 44);
+}
+.mv\:max-w-\[36rem\] {
+  max-width: 36rem;
+}
+.mv\:min-w-4 {
+  min-width: calc(var(--mv-spacing) * 4);
+}
+.mv\:min-w-\[36rem\] {
+  min-width: 36rem;
+}
+.mv\:min-w-full {
+  min-width: 100%;
+}
+.mv\:flex-1 {
+  flex: 1;
+}
+.mv\:shrink-0 {
+  flex-shrink: 0;
+}
+.mv\:-translate-x-1\/2 {
+  --tw-translate-x: calc(calc(1 / 2 * 100%) * -1);
+  translate: var(--tw-translate-x) var(--tw-translate-y);
+}
+.mv\:-translate-x-3 {
+  --tw-translate-x: calc(var(--mv-spacing) * -3);
+  translate: var(--tw-translate-x) var(--tw-translate-y);
+}
+.mv\:translate-y-1\/2 {
+  --tw-translate-y: calc(1 / 2 * 100%);
+  translate: var(--tw-translate-x) var(--tw-translate-y);
+}
+.mv\:translate-y-3 {
+  --tw-translate-y: calc(var(--mv-spacing) * 3);
+  translate: var(--tw-translate-x) var(--tw-translate-y);
+}
+.mv\:rotate-180 {
+  rotate: 180deg;
+}
+.mv\:cursor-pointer {
+  cursor: pointer;
+}
+.mv\:list-none {
+  list-style-type: none;
+}
+.mv\:grid-cols-\[auto_1fr\] {
+  grid-template-columns: auto 1fr;
+}
+.mv\:grid-rows-\[1fr_auto\] {
+  grid-template-rows: 1fr auto;
+}
+.mv\:flex-col {
+  flex-direction: column;
+}
+.mv\:flex-col-reverse {
+  flex-direction: column-reverse;
+}
+.mv\:flex-row {
+  flex-direction: row;
+}
+.mv\:flex-wrap {
+  flex-wrap: wrap;
+}
+.mv\:items-center {
+  align-items: center;
+}
+.mv\:items-start {
+  align-items: flex-start;
+}
+.mv\:items-stretch {
+  align-items: stretch;
+}
+.mv\:justify-between {
+  justify-content: space-between;
+}
+.mv\:justify-center {
+  justify-content: center;
+}
+.mv\:gap-0\.5 {
+  gap: calc(var(--mv-spacing) * 0.5);
+}
+.mv\:gap-1 {
+  gap: var(--mv-spacing);
+}
+.mv\:gap-1\.5 {
+  gap: calc(var(--mv-spacing) * 1.5);
+}
+.mv\:gap-2 {
+  gap: calc(var(--mv-spacing) * 2);
+}
+.mv\:gap-3 {
+  gap: calc(var(--mv-spacing) * 3);
+}
+.mv\:gap-4 {
+  gap: calc(var(--mv-spacing) * 4);
+}
+.mv\:gap-x-4 {
+  column-gap: calc(var(--mv-spacing) * 4);
+}
+.mv\:gap-y-2 {
+  row-gap: calc(var(--mv-spacing) * 2);
+}
+.mv\:truncate {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+.mv\:overflow-auto {
+  overflow: auto;
+}
+.mv\:overflow-visible {
+  overflow: visible;
+}
+.mv\:rounded {
+  border-radius: 0.25rem;
+}
+.mv\:rounded-full {
+  border-radius: calc(infinity * 1px);
+}
+.mv\:rounded-lg {
+  border-radius: var(--mv-radius-lg);
+}
+.mv\:rounded-md {
+  border-radius: var(--mv-radius-md);
+}
+.mv\:border {
+  border-style: var(--tw-border-style);
+  border-width: 1px;
+}
+.mv\:border-0 {
+  border-style: var(--tw-border-style);
+  border-width: 0px;
+}
+.mv\:border-2 {
+  border-style: var(--tw-border-style);
+  border-width: 2px;
+}
+.mv\:border-b {
+  border-bottom-style: var(--tw-border-style);
+  border-bottom-width: 1px;
+}
+.mv\:border-l {
+  border-left-style: var(--tw-border-style);
+  border-left-width: 1px;
+}
+.mv\:border-dashed {
+  --tw-border-style: dashed;
+  border-style: dashed;
+}
+.mv\:border-edge {
+  border-color: var(--mv-color-edge);
+}
+.mv\:border-muted\/60 {
+  border-color: var(--mv-color-muted);
+  @supports (color: color-mix(in lab, red, red)) {
+    border-color: color-mix(in oklab, var(--mv-color-muted) 60%, transparent);
+  }
+}
+.mv\:bg-card {
+  background-color: var(--mv-color-card);
+}
+.mv\:bg-error {
+  background-color: var(--mv-color-error);
+}
+.mv\:bg-info {
+  background-color: var(--mv-color-info);
+}
+.mv\:bg-surface {
+  background-color: var(--mv-color-surface);
+}
+.mv\:bg-surface\/80 {
+  background-color: var(--mv-color-surface);
+  @supports (color: color-mix(in lab, red, red)) {
+    background-color: color-mix(in oklab, var(--mv-color-surface) 80%, transparent);
+  }
+}
+.mv\:bg-warning {
+  background-color: var(--mv-color-warning);
+}
+.mv\:fill-none {
+  fill: none;
+}
+.mv\:stroke-accent\/60 {
+  stroke: var(--mv-color-accent);
+  @supports (color: color-mix(in lab, red, red)) {
+    stroke: color-mix(in oklab, var(--mv-color-accent) 60%, transparent);
+  }
+}
+.mv\:stroke-muted\/50 {
+  stroke: var(--mv-color-muted);
+  @supports (color: color-mix(in lab, red, red)) {
+    stroke: color-mix(in oklab, var(--mv-color-muted) 50%, transparent);
+  }
+}
+.mv\:p-0 {
+  padding: 0px;
+}
+.mv\:p-2 {
+  padding: calc(var(--mv-spacing) * 2);
+}
+.mv\:p-4 {
+  padding: calc(var(--mv-spacing) * 4);
+}
+.mv\:px-0\.5 {
+  padding-inline: calc(var(--mv-spacing) * 0.5);
+}
+.mv\:px-1 {
+  padding-inline: var(--mv-spacing);
+}
+.mv\:px-2\.5 {
+  padding-inline: calc(var(--mv-spacing) * 2.5);
+}
+.mv\:px-8 {
+  padding-inline: calc(var(--mv-spacing) * 8);
+}
+.mv\:py-1\.5 {
+  padding-block: calc(var(--mv-spacing) * 1.5);
+}
+.mv\:py-8 {
+  padding-block: calc(var(--mv-spacing) * 8);
+}
+.mv\:pt-10 {
+  padding-top: calc(var(--mv-spacing) * 10);
+}
+.mv\:pl-14 {
+  padding-left: calc(var(--mv-spacing) * 14);
+}
+.mv\:text-left {
+  text-align: left;
+}
+.mv\:text-sm {
+  font-size: var(--mv-text-sm);
+  line-height: var(--tw-leading, var(--mv-text-sm--line-height));
+}
+.mv\:text-xs {
+  font-size: var(--mv-text-xs);
+  line-height: var(--tw-leading, var(--mv-text-xs--line-height));
+}
+.mv\:text-\[0\.6rem\] {
+  font-size: 0.6rem;
+}
+.mv\:text-\[0\.65rem\] {
+  font-size: 0.65rem;
+}
+.mv\:leading-snug {
+  --tw-leading: var(--mv-leading-snug);
+  line-height: var(--mv-leading-snug);
+}
+.mv\:leading-tight {
+  --tw-leading: var(--mv-leading-tight);
+  line-height: var(--mv-leading-tight);
+}
+.mv\:font-semibold {
+  --tw-font-weight: var(--mv-font-weight-semibold);
+  font-weight: var(--mv-font-weight-semibold);
+}
+.mv\:tracking-wide {
+  --tw-tracking: var(--mv-tracking-wide);
+  letter-spacing: var(--mv-tracking-wide);
+}
+.mv\:whitespace-nowrap {
+  white-space: nowrap;
+}
+.mv\:text-ink {
+  color: var(--mv-color-ink);
+}
+.mv\:text-muted {
+  color: var(--mv-color-muted);
+}
+.mv\:text-white {
+  color: var(--mv-color-white);
+}
+.mv\:uppercase {
+  text-transform: uppercase;
+}
+.mv\:opacity-75 {
+  opacity: 75%;
+}
+.mv\:shadow-sm {
+  --tw-shadow: 0 1px 3px 0 var(--tw-shadow-color, rgb(0 0 0 / 0.1)), 0 1px 2px -1px var(--tw-shadow-color, rgb(0 0 0 / 0.1));
+  box-shadow: var(--tw-inset-shadow), var(--tw-inset-ring-shadow), var(--tw-ring-offset-shadow), var(--tw-ring-shadow), var(--tw-shadow);
+}
+.mv\:\[writing-mode\:vertical-rl\] {
+  writing-mode: vertical-rl;
+}
+@media (hover: hover) {
+  .mv\:hover\:border-accent:hover {
+    border-color: var(--mv-color-accent);
+  }
+  .mv\:hover\:text-accent:hover {
+    color: var(--mv-color-accent);
+  }
+}
+.mv\:focus-visible\:outline-2:focus-visible {
+  outline-style: var(--tw-outline-style);
+  outline-width: 2px;
+}
+.mv\:focus-visible\:outline-accent:focus-visible {
+  outline-color: var(--mv-color-accent);
+}
+@property --tw-translate-x {
+  syntax: "*";
+  inherits: false;
+  initial-value: 0;
+}
+@property --tw-translate-y {
+  syntax: "*";
+  inherits: false;
+  initial-value: 0;
+}
+@property --tw-translate-z {
+  syntax: "*";
+  inherits: false;
+  initial-value: 0;
+}
+@property --tw-border-style {
+  syntax: "*";
+  inherits: false;
+  initial-value: solid;
+}
+@property --tw-leading {
+  syntax: "*";
+  inherits: false;
+}
+@property --tw-font-weight {
+  syntax: "*";
+  inherits: false;
+}
+@property --tw-tracking {
+  syntax: "*";
+  inherits: false;
+}
+@property --tw-shadow {
+  syntax: "*";
+  inherits: false;
+  initial-value: 0 0 #0000;
+}
+@property --tw-shadow-color {
+  syntax: "*";
+  inherits: false;
+}
+@property --tw-shadow-alpha {
+  syntax: "<percentage>";
+  inherits: false;
+  initial-value: 100%;
+}
+@property --tw-inset-shadow {
+  syntax: "*";
+  inherits: false;
+  initial-value: 0 0 #0000;
+}
+@property --tw-inset-shadow-color {
+  syntax: "*";
+  inherits: false;
+}
+@property --tw-inset-shadow-alpha {
+  syntax: "<percentage>";
+  inherits: false;
+  initial-value: 100%;
+}
+@property --tw-ring-color {
+  syntax: "*";
+  inherits: false;
+}
+@property --tw-ring-shadow {
+  syntax: "*";
+  inherits: false;
+  initial-value: 0 0 #0000;
+}
+@property --tw-inset-ring-color {
+  syntax: "*";
+  inherits: false;
+}
+@property --tw-inset-ring-shadow {
+  syntax: "*";
+  inherits: false;
+  initial-value: 0 0 #0000;
+}
+@property --tw-ring-inset {
+  syntax: "*";
+  inherits: false;
+}
+@property --tw-ring-offset-width {
+  syntax: "<length>";
+  inherits: false;
+  initial-value: 0px;
+}
+@property --tw-ring-offset-color {
+  syntax: "*";
+  inherits: false;
+  initial-value: #fff;
+}
+@property --tw-ring-offset-shadow {
+  syntax: "*";
+  inherits: false;
+  initial-value: 0 0 #0000;
+}
+@property --tw-outline-style {
+  syntax: "*";
+  inherits: false;
+  initial-value: solid;
+}
+@layer properties {
+  @supports ((-webkit-hyphens: none) and (not (margin-trim: inline))) or ((-moz-orient: inline) and (not (color:rgb(from red r g b)))) {
+    *, ::before, ::after, ::backdrop {
+      --tw-translate-x: 0;
+      --tw-translate-y: 0;
+      --tw-translate-z: 0;
+      --tw-border-style: solid;
+      --tw-leading: initial;
+      --tw-font-weight: initial;
+      --tw-tracking: initial;
+      --tw-shadow: 0 0 #0000;
+      --tw-shadow-color: initial;
+      --tw-shadow-alpha: 100%;
+      --tw-inset-shadow: 0 0 #0000;
+      --tw-inset-shadow-color: initial;
+      --tw-inset-shadow-alpha: 100%;
+      --tw-ring-color: initial;
+      --tw-ring-shadow: 0 0 #0000;
+      --tw-inset-ring-color: initial;
+      --tw-inset-ring-shadow: 0 0 #0000;
+      --tw-ring-inset: initial;
+      --tw-ring-offset-width: 0px;
+      --tw-ring-offset-color: #fff;
+      --tw-ring-offset-shadow: 0 0 #0000;
+      --tw-outline-style: solid;
+    }
+  }
+}

package/dist/types/core/annotations.d.ts

@@ -0,0 +1,47 @@
+import type { RuleSeverity, SourceLocation, SpaceGraph, SpaceNode, ValidationResult } from 'structured-context/api';
+type NodeId = SpaceNode['id'];
+/** How serious a result is: structured-context's rule severity. Schema and hierarchy failures are errors. */
+export type Severity = RuleSeverity;
+/** The kind of check a result came from. */
+export type AnnotationSource = 'schema' | 'hierarchy' | 'rule';
+/** One validation result attached to a node. */
+export type NodeAnnotation = {
+    severity: Severity;
+    source: AnnotationSource;
+    message: string;
+    /** The violated rule, for `rule` results. */
+    ruleId?: string;
+};
+/** A validation result with no node on the map to attach to. */
+export type UnattachedAnnotation = NodeAnnotation & {
+    /** The node it concerns. Absent for a global-scope rule. A node that failed its schema isn't in the graph. */
+    nodeId?: NodeId;
+    /** Where that node is defined, if known. */
+    location?: SourceLocation;
+};
+/** Annotations by the id of the node they apply to. */
+export type AnnotationIndex = ReadonlyMap<NodeId, readonly NodeAnnotation[]>;
+/**
+ * The parts of structured-context's `ValidationResult` that attach to a node. Every part is optional:
+ * a host that only runs some checks (the Obsidian plugin runs no AI-judged rules, say) passes what it has.
+ */
+export type ValidationInput = Partial<Pick<ValidationResult, 'ruleViolations' | 'hierarchyViolations'> & {
+    nodeErrors: ReadonlyArray<Pick<ValidationResult['nodeErrors'][number], 'nodeId' | 'source' | 'issues'>>;
+}>;
+/**
+ * Attach validation results to the nodes of `graph`, by node id. Results that can't be attached are
+ * returned in `unattached` for the host to surface: global-scope rules (no node), and nodes that
+ * aren't in the graph, which includes every node that failed its schema.
+ */
+export declare function annotationsFrom(input: ValidationInput, graph: SpaceGraph): {
+    annotations: AnnotationIndex;
+    unattached: UnattachedAnnotation[];
+};
+/** The most serious severity among annotations, or undefined if there are none. */
+export declare function worstSeverity(annotations: readonly NodeAnnotation[]): Severity | undefined;
+/**
+ * The annotations a map view shows: those at `level` or more serious, from `sources`. `off` shows none.
+ * Nodes left with no annotations are dropped from the index.
+ */
+export declare function filterAnnotations(index: AnnotationIndex, level: Severity | 'off', sources: readonly AnnotationSource[]): AnnotationIndex;
+export {};

package/dist/types/core/definition.d.ts

@@ -0,0 +1,117 @@
+import type { FromSchema } from 'json-schema-to-ts';
+import { definitionSchema, type landscapeLayoutSchema, MAP_VIEW_SCHEMAS, type settingsSchema, type treeLayoutSchema, type xyLayoutSchema } from './format';
+export { MAP_VIEW_SCHEMAS };
+type References = {
+    references: [
+        typeof settingsSchema,
+        typeof treeLayoutSchema,
+        typeof landscapeLayoutSchema,
+        typeof xyLayoutSchema,
+        typeof definitionSchema
+    ];
+    parseIfThenElseKeywords: true;
+};
+type ParamRef = {
+    $param: string;
+};
+/** Drop `{ $param }` bindings from every setting's type: what remains after resolution. */
+type Resolved<T> = T extends ParamRef ? never : T extends readonly (infer U)[] ? Resolved<U>[] : T extends object ? {
+    [K in keyof T]: Resolved<T[K]>;
+} : T;
+/** A definition as authored: settings may be `{ $param }` bindings, defaulted properties may be absent. */
+export type AuthoredDefinition = FromSchema<typeof definitionSchema, References & {
+    keepDefaultedPropertiesOptional: true;
+}>;
+type FilledDefinition = FromSchema<typeof definitionSchema, References>;
+/** A region with parameters applied and defaults filled in: what layouts receive. */
+export type Region = Resolved<FilledDefinition['regions'][number]>;
+export type LayoutConfig = Region['layout'];
+export type TreeLayoutConfig = Extract<LayoutConfig, {
+    type: 'tree';
+}>;
+export type LandscapeLayoutConfig = Extract<LayoutConfig, {
+    type: 'landscape';
+}>;
+export type XYLayoutConfig = Extract<LayoutConfig, {
+    type: 'xy';
+}>;
+export type AxisConfig = XYLayoutConfig['x'];
+export type GroupLevel = LandscapeLayoutConfig['group'][number];
+export type IntermediateDisplay = Extract<GroupLevel, {
+    type: string;
+}>['intermediate'];
+export type NodesConfig = Region['nodes'];
+export type EdgesConfig = Region['edges'];
+export type Orientation = TreeLayoutConfig['orientation'];
+export type DagMode = TreeLayoutConfig['dag'];
+export type NodeStyle = NodesConfig['style'];
+/**
+ * A validated map view definition. Plain data, so hosts can pass it across a server/browser
+ * boundary. Settings in `source` may still be `{ $param }` bindings; {@link resolveRegions}
+ * replaces them with parameter values.
+ */
+export type MapViewDefinition = {
+    /** The definition's `$id`. */
+    id: string;
+    title: string;
+    description?: string;
+    /** `$id` of the schema whose spaces this map view applies to. */
+    schema: string;
+    parameters: Parameter[];
+    /** The definition as authored. */
+    source: AuthoredDefinition;
+};
+/** A setting the reader can change, with the control generated from its schema. */
+export type Parameter = {
+    name: string;
+    title: string;
+    description?: string;
+    default: unknown;
+    control: ParameterControl;
+};
+/** Options are JSON primitives, so they can be labelled and compared directly. */
+export type ParameterControl = {
+    kind: 'select';
+    options: readonly Primitive[];
+} | {
+    kind: 'multiselect';
+    options: readonly Primitive[];
+} | {
+    kind: 'toggle';
+};
+type Primitive = string | number | boolean | null;
+export type ParameterValues = Readonly<Record<string, unknown>>;
+export declare class MapViewDefinitionError extends Error {
+    constructor(name: string, message: string);
+}
+/**
+ * Parse a JSON5 map view definition and check it against the bundled schemas. `name` labels
+ * error messages (hosts pass where the definition came from).
+ *
+ * Beyond schema validation: every parameter needs a control derivable from its schema, and
+ * every value that control can produce must satisfy the parameter's schema; every `$param`
+ * must name a declared parameter; and each parameter's values must be valid wherever it's
+ * bound, checked by substituting them and re-validating.
+ */
+export declare function parseMapViewDefinition(name: string, text: string): MapViewDefinition;
+/**
+ * The value each parameter takes: the given value if its control could produce it, otherwise
+ * (missing, or stale saved state) the default. Hosts' controls and rendering both use this.
+ */
+export declare function resolveParameterValues(definition: MapViewDefinition, values?: ParameterValues): ParameterValues;
+/** Apply parameter values to a definition's regions and fill in setting defaults. */
+export declare function resolveRegions(definition: MapViewDefinition, values?: ParameterValues): Region[];
+/**
+ * The filter selecting the nodes a map view shows, if any. Hosts apply it when loading the space.
+ * PROTOTYPE: filters are evaluated by the host, not per region in the browser, because
+ * structured-context's filter evaluator can't yet be bundled for a browser (its only entry point,
+ * `structured-context/api`, imports Node built-ins). That's fine while only the first region renders.
+ */
+export declare function selectionFilter(definition: MapViewDefinition, values?: ParameterValues): string | undefined;
+/**
+ * The lowest severity of validation result the map view shows on nodes, or `off`. Hosts check it to
+ * decide whether to run validation at all, since results are only drawn when this isn't `off`.
+ */
+export declare function viewValidationLevel(definition: MapViewDefinition, values?: ParameterValues): NodesConfig['validation'];
+/** Map view definitions that apply to a space with the given schema. */
+export declare function mapViewsForSchema(definitions: readonly MapViewDefinition[], schemaId: string | undefined): MapViewDefinition[];