ketatlas 0.1.0

package/schema.json

@@ -0,0 +1,187 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "KetAtlas configuration",
+  "type": "object",
+  "properties": {
+    "$schema": {
+      "type": "string"
+    },
+    "version": {
+      "const": 1
+    },
+    "title": {
+      "type": "string",
+      "pattern": "\\S"
+    },
+    "description": {
+      "type": "string"
+    },
+    "viewport": {
+      "type": "object",
+      "properties": {
+        "width": {
+          "type": "integer",
+          "minimum": 160,
+          "maximum": 4096
+        },
+        "height": {
+          "type": "integer",
+          "minimum": 160,
+          "maximum": 4096
+        }
+      },
+      "required": ["width", "height"],
+      "additionalProperties": false
+    },
+    "screens": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string",
+            "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_.-]*$"
+          },
+          "title": {
+            "type": "string",
+            "pattern": "\\S"
+          },
+          "url": {
+            "type": "string",
+            "pattern": "\\S"
+          },
+          "viewport": {
+            "type": "object",
+            "properties": {
+              "width": {
+                "type": "integer",
+                "minimum": 160,
+                "maximum": 4096
+              },
+              "height": {
+                "type": "integer",
+                "minimum": 160,
+                "maximum": 4096
+              }
+            },
+            "required": ["width", "height"],
+            "additionalProperties": false
+          },
+          "description": {
+            "type": "string"
+          },
+          "badge": {
+            "type": "string"
+          }
+        },
+        "required": ["id", "title", "url"],
+        "additionalProperties": false
+      }
+    },
+    "flows": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string",
+            "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_.-]*$"
+          },
+          "title": {
+            "type": "string",
+            "pattern": "\\S"
+          },
+          "group": {
+            "type": "string"
+          },
+          "description": {
+            "type": "string"
+          },
+          "start": {
+            "type": "string",
+            "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_.-]*$"
+          },
+          "ends": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_.-]*$"
+            }
+          },
+          "nodes": {
+            "type": "array",
+            "minItems": 1,
+            "items": {
+              "type": "object",
+              "properties": {
+                "id": {
+                  "type": "string",
+                  "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_.-]*$"
+                },
+                "screen": {
+                  "type": "string",
+                  "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_.-]*$"
+                },
+                "type": {
+                  "enum": ["screen", "note", "external"]
+                },
+                "title": {
+                  "type": "string"
+                },
+                "description": {
+                  "type": "string"
+                },
+                "url": {
+                  "type": "string",
+                  "pattern": "\\S"
+                },
+                "column": {
+                  "type": "integer",
+                  "minimum": 0,
+                  "maximum": 100
+                },
+                "row": {
+                  "type": "integer",
+                  "minimum": 0,
+                  "maximum": 100
+                }
+              },
+              "required": ["id"],
+              "additionalProperties": false
+            }
+          },
+          "edges": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "from": {
+                  "type": "string",
+                  "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_.-]*$"
+                },
+                "to": {
+                  "type": "string",
+                  "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_.-]*$"
+                },
+                "label": {
+                  "type": "string",
+                  "pattern": "\\S"
+                },
+                "kind": {
+                  "enum": ["primary", "conditional", "recovery"]
+                }
+              },
+              "required": ["from", "to", "label"],
+              "additionalProperties": false
+            }
+          }
+        },
+        "required": ["id", "title", "nodes", "edges"],
+        "additionalProperties": false
+      }
+    }
+  },
+  "required": ["version", "title", "flows"],
+  "additionalProperties": false
+}

package/src/config.js

@@ -0,0 +1,196 @@
+/** Validate project data without a DOM, build tool, or runtime dependency. */
+const ID = /^[a-zA-Z0-9][a-zA-Z0-9_.-]*$/;
+const object = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+const string = (value) => typeof value === "string" && value.trim().length > 0;
+export function safeURL(value, baseURL = "https://ketatlas.invalid/") {
+  if (!string(value)) throw new TypeError("Expected a non-empty URL");
+  const url = new URL(value, baseURL);
+  if (!["http:", "https:"].includes(url.protocol))
+    throw new TypeError("Use an HTTP(S) or relative URL");
+  if (url.username || url.password) throw new TypeError("URLs must not contain credentials");
+  return url.href;
+}
+export function validateAtlas(input) {
+  const errors = [],
+    warnings = [];
+  const error = (path, message) => errors.push({ path, message });
+  const keys = (value, allowed, path) => {
+    for (const key of Object.keys(value))
+      if (!allowed.includes(key)) error(path ? `${path}.${key}` : key, "Unknown property.");
+  };
+  const id = (value, path) => {
+    if (!string(value) || !ID.test(value))
+      error(
+        path,
+        "Use letters, numbers, dots, underscores or hyphens; start with a letter or number.",
+      );
+  };
+  const text = (value, path, required = false) => {
+    if ((required && !string(value)) || (value !== undefined && typeof value !== "string"))
+      error(path, "Expected text.");
+  };
+  const url = (value, path) => {
+    try {
+      safeURL(value);
+    } catch (e) {
+      error(path, e.message);
+    }
+  };
+  const viewport = (value, path) => {
+    if (value === undefined) return;
+    if (!object(value)) return error(path, "Expected { width, height }.");
+    keys(value, ["width", "height"], path);
+    for (const key of ["width", "height"])
+      if (!Number.isInteger(value[key]) || value[key] < 160 || value[key] > 4096)
+        error(`${path}.${key}`, "Expected an integer from 160 to 4096.");
+  };
+  if (!object(input))
+    return {
+      valid: false,
+      errors: [{ path: "$", message: "Expected an atlas object." }],
+      warnings,
+    };
+  keys(input, ["$schema", "version", "title", "description", "viewport", "screens", "flows"], "");
+  if (input.version !== 1) error("version", "Expected version: 1.");
+  text(input.title, "title", true);
+  text(input.description, "description");
+  text(input.$schema, "$schema");
+  viewport(input.viewport, "viewport");
+  const screens = new Set();
+  if (input.screens !== undefined && !Array.isArray(input.screens))
+    error("screens", "Expected an array.");
+  for (const [i, s] of (Array.isArray(input.screens) ? input.screens : []).entries()) {
+    const p = `screens[${i}]`;
+    if (!object(s)) {
+      error(p, "Expected a screen object.");
+      continue;
+    }
+    keys(s, ["id", "title", "url", "viewport", "description", "badge"], p);
+    id(s.id, `${p}.id`);
+    text(s.title, `${p}.title`, true);
+    url(s.url, `${p}.url`);
+    viewport(s.viewport, `${p}.viewport`);
+    text(s.description, `${p}.description`);
+    text(s.badge, `${p}.badge`);
+    if (screens.has(s.id)) error(`${p}.id`, `Duplicate screen "${s.id}".`);
+    screens.add(s.id);
+  }
+  if (!Array.isArray(input.flows) || !input.flows.length) error("flows", "Add at least one flow.");
+  const flowIds = new Set();
+  for (const [i, f] of (Array.isArray(input.flows) ? input.flows : []).entries()) {
+    const p = `flows[${i}]`;
+    if (!object(f)) {
+      error(p, "Expected a flow object.");
+      continue;
+    }
+    keys(f, ["id", "title", "group", "description", "start", "ends", "nodes", "edges"], p);
+    id(f.id, `${p}.id`);
+    text(f.title, `${p}.title`, true);
+    text(f.group, `${p}.group`);
+    text(f.description, `${p}.description`);
+    if (flowIds.has(f.id)) error(`${p}.id`, `Duplicate flow "${f.id}".`);
+    flowIds.add(f.id);
+    if (!Array.isArray(f.nodes) || !f.nodes.length) error(`${p}.nodes`, "Add at least one node.");
+    const nodeIds = new Set(),
+      cells = new Set();
+    for (const [j, n] of (Array.isArray(f.nodes) ? f.nodes : []).entries()) {
+      const q = `${p}.nodes[${j}]`;
+      if (!object(n)) {
+        error(q, "Expected a node object.");
+        continue;
+      }
+      keys(n, ["id", "screen", "type", "title", "description", "url", "column", "row"], q);
+      id(n.id, `${q}.id`);
+      if (nodeIds.has(n.id)) error(`${q}.id`, `Duplicate node "${n.id}".`);
+      nodeIds.add(n.id);
+      if (n.screen !== undefined && !screens.has(n.screen))
+        error(`${q}.screen`, `Unknown screen "${n.screen}".`);
+      const type = n.type || (n.screen ? "screen" : "note");
+      if (!["screen", "note", "external"].includes(type))
+        error(`${q}.type`, "Use screen, note or external.");
+      if (type === "screen" && !n.screen)
+        error(`${q}.screen`, "A screen node needs a screen reference.");
+      if (type !== "screen" && n.screen !== undefined)
+        error(`${q}.screen`, "Only screen nodes may reference a screen.");
+      text(n.title, `${q}.title`, type !== "screen");
+      text(n.description, `${q}.description`);
+      if (n.url !== undefined) url(n.url, `${q}.url`);
+      for (const key of ["column", "row"])
+        if (n[key] !== undefined && (!Number.isInteger(n[key]) || n[key] < 0 || n[key] > 100))
+          error(`${q}.${key}`, "Expected an integer from 0 to 100.");
+      const cell = `${n.column ?? j}:${n.row ?? 0}`;
+      if (cells.has(cell)) error(q, `Two nodes occupy grid cell ${cell}.`);
+      cells.add(cell);
+    }
+    const start = f.start ?? f.nodes?.[0]?.id;
+    if (!nodeIds.has(start)) error(`${p}.start`, "Start must reference a node in this flow.");
+    if (f.ends !== undefined && !Array.isArray(f.ends))
+      error(`${p}.ends`, "Expected an array of node IDs.");
+    for (const key of Array.isArray(f.ends) ? f.ends : [])
+      if (!nodeIds.has(key)) error(`${p}.ends`, `Unknown node "${key}".`);
+    if (!Array.isArray(f.edges))
+      error(`${p}.edges`, "Expected an array (use [] for a single step).");
+    for (const [j, edge] of (Array.isArray(f.edges) ? f.edges : []).entries()) {
+      const q = `${p}.edges[${j}]`;
+      if (!object(edge)) {
+        error(q, "Expected an edge object.");
+        continue;
+      }
+      keys(edge, ["from", "to", "label", "kind"], q);
+      for (const key of ["from", "to"])
+        if (!nodeIds.has(edge[key])) error(`${q}.${key}`, `Unknown node "${edge[key]}".`);
+      text(edge.label, `${q}.label`, true);
+      if (edge.kind !== undefined && !["primary", "conditional", "recovery"].includes(edge.kind))
+        error(`${q}.kind`, "Use primary, conditional or recovery.");
+    }
+    const reached = new Set([start]);
+    let size = -1;
+    while (size !== reached.size) {
+      size = reached.size;
+      for (const edge of Array.isArray(f.edges) ? f.edges : [])
+        if (object(edge) && reached.has(edge.from)) reached.add(edge.to);
+    }
+    for (const key of nodeIds)
+      if (!reached.has(key))
+        warnings.push({
+          path: `${p}.nodes`,
+          message: `Node "${key}" is not reachable from "${start}".`,
+        });
+  }
+  return { valid: errors.length === 0, errors, warnings };
+}
+export class AtlasValidationError extends Error {
+  constructor(result) {
+    super(result.errors.map((e) => `${e.path}: ${e.message}`).join("\n"));
+    this.name = "AtlasValidationError";
+    this.errors = result.errors;
+  }
+}
+export function normalizeAtlas(input, baseURL) {
+  const result = validateAtlas(input);
+  if (!result.valid) throw new AtlasValidationError(result);
+  const data = structuredClone(input);
+  data.description ??= "";
+  data.viewport ??= { width: 390, height: 844 };
+  data.screens ??= [];
+  for (const s of data.screens) {
+    s.url = safeURL(s.url, baseURL);
+    s.viewport ??= { ...data.viewport };
+  }
+  for (const f of data.flows) {
+    f.group ??= "";
+    f.description ??= "";
+    f.start ??= f.nodes[0].id;
+    f.ends ??= f.nodes.filter((n) => !f.edges.some((edge) => edge.from === n.id)).map((n) => n.id);
+    f.nodes.forEach((n, i) => {
+      n.column ??= i;
+      n.row ??= 0;
+      n.type ??= n.screen ? "screen" : "note";
+      if (n.url) n.url = safeURL(n.url, baseURL);
+    });
+    f.edges.forEach((edge) => {
+      edge.kind ??= "primary";
+    });
+  }
+  return data;
+}

package/src/icons.js

@@ -0,0 +1,23 @@
+/* Generated from lucide-static 1.40.0; see assets/LUCIDE-LICENSE. */
+export const icons = {
+  circle:
+    '<!-- @license lucide-static v1.40.0 - ISC -->\n<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">\n  <circle cx="12" cy="12" r="10" />\n</svg>\n',
+  "circle-dot":
+    '<!-- @license lucide-static v1.40.0 - ISC -->\n<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">\n  <circle cx="12" cy="12" r="1" />\n  <circle cx="12" cy="12" r="10" />\n</svg>\n',
+  "circle-check":
+    '<!-- @license lucide-static v1.40.0 - ISC -->\n<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">\n  <circle cx="12" cy="12" r="10" />\n  <path d="m16 9-5.5 5.5L8 12" />\n</svg>\n',
+  "arrow-up-right":
+    '<!-- @license lucide-static v1.40.0 - ISC -->\n<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">\n  <path d="M7 7h10v10" />\n  <path d="M7 17 17 7" />\n</svg>\n',
+  "layout-grid":
+    '<!-- @license lucide-static v1.40.0 - ISC -->\n<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">\n  <rect width="7" height="7" x="3" y="3" rx="1" />\n  <rect width="7" height="7" x="14" y="3" rx="1" />\n  <rect width="7" height="7" x="14" y="14" rx="1" />\n  <rect width="7" height="7" x="3" y="14" rx="1" />\n</svg>\n',
+  "circle-help":
+    '<!-- @license lucide-static v1.40.0 - ISC -->\n<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">\n  <circle cx="12" cy="12" r="10" />\n  <path d="M9.09 9a3 3 0 0 1 5.83 1c0 2-3 3-3 3" />\n  <path d="M12 17h.01" />\n</svg>\n',
+  plus: '<!-- @license lucide-static v1.40.0 - ISC -->\n<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">\n  <path d="M5 12h14" />\n  <path d="M12 5v14" />\n</svg>\n',
+  minus:
+    '<!-- @license lucide-static v1.40.0 - ISC -->\n<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">\n  <path d="M5 12h14" />\n</svg>\n',
+  expand:
+    '<!-- @license lucide-static v1.40.0 - ISC -->\n<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">\n  <path d="m15 15 6 6" />\n  <path d="m15 9 6-6" />\n  <path d="M21 16v5h-5" />\n  <path d="M21 8V3h-5" />\n  <path d="M3 16v5h5" />\n  <path d="m3 21 6-6" />\n  <path d="M3 8V3h5" />\n  <path d="M9 9 3 3" />\n</svg>\n',
+  x: '<!-- @license lucide-static v1.40.0 - ISC -->\n<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">\n  <path d="M18 6 6 18" />\n  <path d="m6 6 12 12" />\n</svg>\n',
+  "file-text":
+    '<!-- @license lucide-static v1.40.0 - ISC -->\n<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">\n  <path d="M6 22a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h8a2.4 2.4 0 0 1 1.704.706l3.588 3.588A2.4 2.4 0 0 1 20 8v12a2 2 0 0 1-2 2z" />\n  <path d="M14 2v5a1 1 0 0 0 1 1h5" />\n  <path d="M10 9H8" />\n  <path d="M16 13H8" />\n  <path d="M16 17H8" />\n</svg>\n',
+};

package/src/index.d.ts

@@ -0,0 +1,106 @@
+export interface Viewport {
+  width: number;
+  height: number;
+}
+export interface AtlasScreen {
+  id: string;
+  title: string;
+  url: string;
+  viewport?: Viewport;
+  description?: string;
+  badge?: string;
+}
+export interface AtlasNode {
+  id: string;
+  screen?: string;
+  type?: "screen" | "note" | "external";
+  title?: string;
+  description?: string;
+  url?: string;
+  column?: number;
+  row?: number;
+}
+export interface AtlasEdge {
+  from: string;
+  to: string;
+  label: string;
+  kind?: "primary" | "conditional" | "recovery";
+}
+export interface AtlasFlow {
+  id: string;
+  title: string;
+  group?: string;
+  description?: string;
+  start?: string;
+  ends?: string[];
+  nodes: AtlasNode[];
+  edges: AtlasEdge[];
+}
+export interface AtlasConfig {
+  $schema?: string;
+  version: 1;
+  title: string;
+  description?: string;
+  viewport?: Viewport;
+  screens?: AtlasScreen[];
+  flows: AtlasFlow[];
+}
+export interface AtlasOptions {
+  /** Relative screen URLs resolve against this URL. loadAtlas uses the JSON URL by default. */
+  baseURL?: string;
+  /** Public directory containing styles/ and assets/, ending in /. Needed when bundling the JS. */
+  assetBaseURL?: string;
+  initialFlow?: string;
+  theme?: "light" | "dark";
+  /** Opt in only for one viewer per page; preserves unrelated URL parameters. */
+  syncUrl?: boolean;
+  maxPreviews?: number;
+  previewThreshold?: number;
+  /** Defaults to "allow-scripts allow-forms". Only add permissions for trusted content. */
+  sandbox?: string;
+  signal?: AbortSignal;
+}
+export interface AtlasState {
+  flowId: string;
+  selectedNodeId: string | null;
+  zoom: number;
+  pan: { x: number; y: number };
+  flowCount: number;
+  nodeCount: number;
+  screenCount: number;
+  destroyed: boolean;
+}
+export interface AtlasInstance {
+  element: HTMLDivElement;
+  ready: Promise<void>;
+  goToFlow(id: string): void;
+  focusNode(flowId: string, nodeId: string): void;
+  openNode(flowId: string, nodeId: string): void;
+  fit(): void;
+  zoomTo(value: number): void;
+  getState(): AtlasState;
+  destroy(): void;
+}
+export interface ValidationIssue {
+  path: string;
+  message: string;
+}
+export interface ValidationResult {
+  valid: boolean;
+  errors: ValidationIssue[];
+  warnings: ValidationIssue[];
+}
+export class AtlasValidationError extends Error {
+  errors: ValidationIssue[];
+}
+export function validateAtlas(input: unknown): ValidationResult;
+export function createAtlas(
+  container: HTMLElement,
+  config: AtlasConfig,
+  options?: AtlasOptions,
+): AtlasInstance;
+export function loadAtlas(
+  container: HTMLElement,
+  url: string | URL,
+  options?: AtlasOptions,
+): Promise<AtlasInstance>;