@the-package-labs/idocs-core 0.4.0 → 0.6.0

package/dist/placeholders.d.ts

@@ -0,0 +1,40 @@
+export type PlaceholderSegment = {
+    kind: 'text';
+    text: string;
+} | {
+    kind: 'var';
+    /** As written, braces or angle brackets included: `{yourname}`. */
+    raw: string;
+    /** As written, without them: `yourname`. */
+    name: string;
+    /** What `{Token}`, `<token>` and `<TOKEN>` share, so one value fills them all. */
+    key: string;
+};
+export interface Placeholder {
+    key: string;
+    /** The first spelling in the text. */
+    name: string;
+    raw: string;
+    /** A token or a password: kept in memory, never stored, masked on the page. */
+    secret: boolean;
+}
+export declare function varKey(name: string): string;
+export declare function isSecretKey(key: string): boolean;
+export declare function splitPlaceholders(text: string): PlaceholderSegment[];
+/** Each distinct placeholder once, in the order the text first uses it. */
+export declare function placeholdersOf(segments: PlaceholderSegment[]): Placeholder[];
+/** The text to copy: values where the reader set them, the placeholder as written where not. */
+export declare function fillSegments(segments: PlaceholderSegment[], values: Record<string, string>): string;
+export declare function fillPlaceholders(text: string, values: Record<string, string>): string;
+/** Placeholders in `segments` the reader has not set. */
+export declare function unsetPlaceholders(segments: PlaceholderSegment[], values: Record<string, string>): Placeholder[];
+export interface Shown {
+    text: string;
+    state: 'unset' | 'set' | 'secret';
+}
+/** What the page shows in place of a placeholder: the value, a mask for a secret, or the placeholder. */
+export declare function shownPlaceholder(segment: Extract<PlaceholderSegment, {
+    kind: 'var';
+}>, values: Record<string, string>): Shown;
+/** Whether a code block takes placeholders: by language, and `vars` / `novars` in the fence info decide otherwise. */
+export declare function takesPlaceholders(lang: string | undefined, meta: string | undefined): boolean;

package/dist/schema.d.ts

@@ -28,10 +28,24 @@ export declare const DirectionSchema: z.ZodEnum<{
     RIGHT: "RIGHT";
     UP: "UP";
 }>;
+/** One field per list item: `- name`, `- name: type` or `- name: { type, key, ref, note }`. */
+declare const FieldSchema: z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNull, z.ZodObject<{
+    type: z.ZodOptional<z.ZodString>;
+    key: z.ZodOptional<z.ZodBoolean>;
+    ref: z.ZodOptional<z.ZodString>;
+    note: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>]>>]>;
 export declare const NodeSchema: z.ZodObject<{
     title: z.ZodOptional<z.ZodString>;
     sub: z.ZodOptional<z.ZodString>;
+    pill: z.ZodOptional<z.ZodString>;
     lines: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    fields: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNull, z.ZodObject<{
+        type: z.ZodOptional<z.ZodString>;
+        key: z.ZodOptional<z.ZodBoolean>;
+        ref: z.ZodOptional<z.ZodString>;
+        note: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>]>>]>>>;
     icon: z.ZodOptional<z.ZodString>;
     kind: z.ZodOptional<z.ZodString>;
     family: z.ZodOptional<z.ZodEnum<{
@@ -440,10 +454,34 @@ export declare const ScenarioSchema: z.ZodObject<{
         }, z.core.$strict>], "type">>;
     }, z.core.$strict>], "type">>>;
 }, z.core.$strict>;
+export declare const DefaultsSchema: z.ZodObject<{
+    view: z.ZodOptional<z.ZodString>;
+    scenario: z.ZodOptional<z.ZodString>;
+    mode: z.ZodOptional<z.ZodEnum<{
+        flow: "flow";
+        sequence: "sequence";
+        story: "story";
+    }>>;
+    sidebar: z.ZodOptional<z.ZodBoolean>;
+    subtitles: z.ZodOptional<z.ZodBoolean>;
+    autoplay: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
 export declare const RootSchema: z.ZodObject<{
     $schema: z.ZodOptional<z.ZodString>;
     title: z.ZodString;
     description: z.ZodOptional<z.ZodString>;
+    defaults: z.ZodOptional<z.ZodObject<{
+        view: z.ZodOptional<z.ZodString>;
+        scenario: z.ZodOptional<z.ZodString>;
+        mode: z.ZodOptional<z.ZodEnum<{
+            flow: "flow";
+            sequence: "sequence";
+            story: "story";
+        }>>;
+        sidebar: z.ZodOptional<z.ZodBoolean>;
+        subtitles: z.ZodOptional<z.ZodBoolean>;
+        autoplay: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>>;
     kinds: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
         icon: z.ZodOptional<z.ZodString>;
         family: z.ZodOptional<z.ZodEnum<{
@@ -498,7 +536,14 @@ export declare const RootSchema: z.ZodObject<{
     nodes: z.ZodRecord<z.ZodString, z.ZodObject<{
         title: z.ZodOptional<z.ZodString>;
         sub: z.ZodOptional<z.ZodString>;
+        pill: z.ZodOptional<z.ZodString>;
         lines: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        fields: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNull, z.ZodObject<{
+            type: z.ZodOptional<z.ZodString>;
+            key: z.ZodOptional<z.ZodBoolean>;
+            ref: z.ZodOptional<z.ZodString>;
+            note: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>]>>]>>>;
         icon: z.ZodOptional<z.ZodString>;
         kind: z.ZodOptional<z.ZodString>;
         family: z.ZodOptional<z.ZodEnum<{
@@ -784,6 +829,7 @@ export declare const RootSchema: z.ZodObject<{
     }, z.core.$strict>>>;
 }, z.core.$strict>;
 export type RootInput = z.infer<typeof RootSchema>;
+export type FieldInput = z.infer<typeof FieldSchema>;
 export type Step = z.infer<typeof StepSchema>;
 export declare const KNOWN_KEYS: {
     readonly root: string[];
@@ -792,6 +838,7 @@ export declare const KNOWN_KEYS: {
     readonly edge: string[];
     readonly view: string[];
     readonly scenario: string[];
+    readonly defaults: string[];
 };
 type Json = Record<string, unknown>;
 /**

package/dist/scrubber.d.ts

@@ -0,0 +1,34 @@
+import type { Timeline } from './timeline';
+/** One stop of the slider: a step, or the steps of a `par` block that start together. */
+export interface Slot {
+    /** First and last step of the slot, as indexes into `scenario.steps`. */
+    from: number;
+    to: number;
+    /** The time it covers. A slot runs until the next one starts, so pauses belong to the step before. */
+    t0: number;
+    t1: number;
+}
+/** A run of slots under one phase. A scenario without named phases is one section with no title. */
+export interface Section {
+    /** Index in `scenario.phases`. */
+    phase: number;
+    title: string;
+    caption?: string;
+    /** First and last slot. */
+    from: number;
+    to: number;
+}
+export interface Scrubber {
+    slots: Slot[];
+    sections: Section[];
+    duration: number;
+}
+export declare function buildScrubber(tl: Timeline): Scrubber;
+/** Where on the slider, 0 to 1, the moment `t` falls. */
+export declare function positionAt(s: Scrubber, t: number): number;
+/** The moment a place on the slider stands for. The inverse of `positionAt`. */
+export declare function timeAt(s: Scrubber, position: number): number;
+/** The slot a place on the slider falls in. */
+export declare function slotAt(s: Scrubber, position: number): number;
+/** The slot that holds step `index`, or -1. */
+export declare function slotOfStep(s: Scrubber, index: number): number;

package/dist/start.d.ts

@@ -0,0 +1,22 @@
+import type { CompiledDiagram, ScenarioMode } from './types';
+/** What the page that shows a diagram asked for, if anything. Its choices win over the diagram's. */
+export interface StartWant {
+    view?: string;
+    scenario?: string;
+    mode?: ScenarioMode;
+}
+export interface Start {
+    /** Always one of the diagram's views. */
+    view: string;
+    /** The scenario selected first, or null for the overview. */
+    scenario: string | null;
+    mode: ScenarioMode;
+}
+/** The mode a scenario is drawn in when neither it nor the page says: the diagram's, then `flow`. */
+export declare const defaultMode: (diagram: CompiledDiagram) => ScenarioMode;
+/**
+ * Where a diagram opens. The page's props come first, then what the diagram's author wrote under
+ * `defaults`, then the first view with nothing selected. The page choosing a scenario takes its
+ * view along, and one choosing a view leaves the default scenario out unless it plays there.
+ */
+export declare function startOf(diagram: CompiledDiagram, want?: StartWant): Start;

package/dist/types.d.ts

@@ -29,11 +29,27 @@ export interface NodeDiagram {
     /** Starts shown in place. */
     expanded?: boolean;
 }
+/** A row of an entity card: one column, property or attribute of what the node stores. */
+export interface CompiledField {
+    name: string;
+    type?: string;
+    /** Part of the primary key. */
+    key?: boolean;
+    /** The node (and field) this one points at, like a foreign key. Each one draws a relation. */
+    ref?: {
+        node: string;
+        field?: string;
+    };
+    note?: string;
+}
 export interface CompiledNode {
     id: string;
     title: string;
     sub?: string;
+    /** A short label in the card header, like `TABLE` or `ES INDEX`. */
+    pill?: string;
     lines: string[];
+    fields: CompiledField[];
     icon?: IconData;
     kind?: string;
     family?: Family;
@@ -76,6 +92,9 @@ export interface CompiledEdge {
     id: string;
     from: string;
     to: string;
+    /** Set when the edge starts or ends on one field of an entity card. */
+    fromField?: string;
+    toField?: string;
     label?: string;
     kind: string;
     both: boolean;
@@ -147,10 +166,23 @@ export interface CompiledScenario {
     phases: CompiledPhase[];
     steps: CompiledStep[];
 }
+/**
+ * How a diagram opens, as its author wrote it. A page's own choices (the props of `<Diagram>`) win
+ * over these. Validated by the compiler: the view and the scenario exist, and agree.
+ */
+export interface DiagramDefaults {
+    view?: string;
+    scenario?: string;
+    mode?: ScenarioMode;
+    sidebar?: boolean;
+    subtitles?: boolean;
+    autoplay?: boolean;
+}
 export interface CompiledDiagram {
     name: string;
     title: string;
     descriptionHtml?: string;
+    defaults?: DiagramDefaults;
     nodes: Record<string, CompiledNode>;
     groups: Record<string, CompiledGroup>;
     edges: Record<string, CompiledEdge>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@the-package-labs/idocs-core",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "type": "module",
   "exports": {
     ".": {

package/dist/chunk-ITBBPZE6.js

@@ -1,145 +0,0 @@
-// src/defaults.ts
-var BUILTIN_KINDS = {
-  client: { icon: "lucide:monitor", family: "slate" },
-  user: { icon: "lucide:user", family: "slate" },
-  ui: { icon: "lucide:layout-dashboard", family: "slate" },
-  external: { icon: "lucide:cloud", family: "slate" },
-  service: { icon: "lucide:server", family: "blue" },
-  gateway: { icon: "lucide:route", family: "blue" },
-  worker: { icon: "lucide:cog", family: "blue" },
-  container: { icon: "lucide:container", family: "blue" },
-  function: { icon: "lucide:square-function", family: "blue" },
-  database: { icon: "lucide:database", family: "green" },
-  cache: { icon: "lucide:zap", family: "green" },
-  storage: { icon: "lucide:hard-drive", family: "green" },
-  queue: { icon: "lucide:list-ordered", family: "amber" },
-  agent: { icon: "lucide:bot", family: "violet" },
-  network: { icon: "lucide:network", family: "violet" },
-  vm: { icon: "lucide:box", family: "violet" },
-  auth: { icon: "lucide:key-round", family: "teal" },
-  monitor: { icon: "lucide:activity", family: "teal" }
-};
-var BUILTIN_EDGE_KINDS = {
-  http: { label: "HTTP request / response", color: "ink", width: 1.5 },
-  channel: { label: "Persistent channel (websocket, gRPC)", color: "accent", width: 2.4 },
-  tunnel: { label: "Overlay tunnel", color: "tunnel", width: 5 },
-  queue: { label: "Queue / broker", color: "ok", width: 2, dash: "2 4" },
-  ws: { label: "WebSocket", color: "ink", width: 1.6, dash: "7 4" },
-  data: { label: "Data access", color: "muted", width: 1.3 }
-};
-var STEP_KIND_COLORS = {
-  request: "accent",
-  response: "ok",
-  error: "bad",
-  lookup: "muted",
-  event: "warn"
-};
-var DEFAULT_NODE_WIDTH = 178;
-
-// src/geometry.ts
-function polylineLength(points) {
-  let total = 0;
-  for (let i = 1; i < points.length; i++) total += dist(points[i - 1], points[i]);
-  return total;
-}
-function dist(a, b) {
-  return Math.hypot(b.x - a.x, b.y - a.y);
-}
-function pointAt(points, d) {
-  if (points.length === 0) return { x: 0, y: 0 };
-  let left = Math.max(0, d);
-  for (let i = 1; i < points.length; i++) {
-    const a = points[i - 1];
-    const b = points[i];
-    const len = dist(a, b);
-    if (left <= len || i === points.length - 1) {
-      const t = len === 0 ? 0 : Math.min(1, left / len);
-      return { x: a.x + (b.x - a.x) * t, y: a.y + (b.y - a.y) * t };
-    }
-    left -= len;
-  }
-  return points[points.length - 1];
-}
-function roundedPath(points, radius = 8) {
-  if (points.length === 0) return "";
-  const first = points[0];
-  let d = `M${r(first.x)} ${r(first.y)}`;
-  for (let i = 1; i < points.length - 1; i++) {
-    const prev = points[i - 1];
-    const cur = points[i];
-    const next = points[i + 1];
-    const inLen = dist(prev, cur);
-    const outLen = dist(cur, next);
-    const rad = Math.min(radius, inLen / 2, outLen / 2);
-    if (rad < 0.5) {
-      d += `L${r(cur.x)} ${r(cur.y)}`;
-      continue;
-    }
-    const a = {
-      x: cur.x + (prev.x - cur.x) / inLen * rad,
-      y: cur.y + (prev.y - cur.y) / inLen * rad
-    };
-    const b = {
-      x: cur.x + (next.x - cur.x) / outLen * rad,
-      y: cur.y + (next.y - cur.y) / outLen * rad
-    };
-    d += `L${r(a.x)} ${r(a.y)}Q${r(cur.x)} ${r(cur.y)} ${r(b.x)} ${r(b.y)}`;
-  }
-  if (points.length > 1) {
-    const last = points[points.length - 1];
-    d += `L${r(last.x)} ${r(last.y)}`;
-  }
-  return d;
-}
-function r(n) {
-  return Math.round(n * 10) / 10;
-}
-function letterKey(index) {
-  let n = index;
-  let out = "";
-  do {
-    out = String.fromCharCode(65 + n % 26) + out;
-    n = Math.floor(n / 26) - 1;
-  } while (n >= 0);
-  return out;
-}
-
-// src/suggest.ts
-function didYouMean(word, options) {
-  let best;
-  let bestDist = Math.max(2, Math.floor(word.length / 3)) + 1;
-  for (const o of options) {
-    const d = levenshtein(word.toLowerCase(), o.toLowerCase());
-    if (d < bestDist) {
-      best = o;
-      bestDist = d;
-    }
-  }
-  return best ? `Did you mean "${best}"?` : void 0;
-}
-function levenshtein(a, b) {
-  const row = Array.from({ length: b.length + 1 }, (_, i) => i);
-  for (let i = 1; i <= a.length; i++) {
-    let prev = row[0];
-    row[0] = i;
-    for (let j = 1; j <= b.length; j++) {
-      const tmp = row[j];
-      row[j] = Math.min(row[j] + 1, row[j - 1] + 1, prev + (a[i - 1] === b[j - 1] ? 0 : 1));
-      prev = tmp;
-    }
-  }
-  return row[b.length];
-}
-
-export {
-  BUILTIN_KINDS,
-  BUILTIN_EDGE_KINDS,
-  STEP_KIND_COLORS,
-  DEFAULT_NODE_WIDTH,
-  polylineLength,
-  dist,
-  pointAt,
-  roundedPath,
-  letterKey,
-  didYouMean
-};