@yanqirenshi/model.deployment 0.0.0-stage → 0.1.0

package/src/patch.ts

@@ -0,0 +1,317 @@
+// UI の操作(ドラッグ・インスペクタの適用)を、保存する patch(JSON Merge Patch)に変換する。
+//
+// 戻り値は { collection, id, patch }。利用側(iHub など)は図の種類を知らずにこれを保存すればよい。
+// 入力の検証に失敗したときは ModelError を投げる(メッセージは利用者にそのまま見せられる日本語)。
+// model.sitemap の patch.ts を元にしている(ラベルは label.text、種類は NODE / COMPONENT、線に矢印の有無がある)。
+
+import { NODE_TYPES, isEdge, withDefaults } from './defaults.js';
+import { fieldsOf } from './fields.js';
+import type {
+  MergePatch, DeploymentChange, DeploymentCollection, DeploymentEdgeRecord, DeploymentMove, DeploymentNodeRecord,
+  DeploymentRecord, DeploymentValues,
+} from './types.js';
+
+/** 入力の検証エラー。message は利用者向け */
+export class ModelError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'ModelError';
+  }
+}
+
+/** レコードを置くコレクション */
+export function collectionOf(record: DeploymentRecord): DeploymentCollection {
+  return isEdge(record) ? 'edges' : 'nodes';
+}
+
+/** インスペクタの見出し。ラベルの文字、無ければ「種類 id」(線は「接続元 → 接続先」) */
+export function titleOf(record: DeploymentRecord): string {
+  if (isEdge(record))
+    return `${String(record.from.id)} → ${String(record.to.id)}`;
+
+  const text = record.label && typeof record.label === 'object' ? record.label.text : null;
+
+  if (typeof text === 'string' && text !== '')
+    return text;
+
+  return `${record.type || ''} ${String(record.id)}`.trim();
+}
+
+/** ドット区切りの path で値を取り出す */
+export function getByPath(obj: unknown, path: string): unknown {
+  return path.split('.').reduce<unknown>(
+    (acc, key) => (acc == null ? acc : (acc as Record<string, unknown>)[key]),
+    obj,
+  );
+}
+
+/**
+ * JSON Merge Patch をレコードに重ねたものを返す(入力は書き換えない)。
+ * null の項目は除く。保存したあと、表示を先に更新するときに使う。
+ */
+export function mergePatch<T extends object>(record: T, patch: MergePatch): T {
+  const out: Record<string, unknown> = { ...(record as Record<string, unknown>) };
+
+  for (const [key, value] of Object.entries(patch)) {
+    if (value === null) {
+      delete out[key];
+    } else if (typeof value === 'object' && !Array.isArray(value)) {
+      const base = out[key];
+
+      out[key] = mergePatch(
+        base && typeof base === 'object' && !Array.isArray(base) ? (base as object) : {},
+        value as MergePatch,
+      );
+    } else {
+      out[key] = value;
+    }
+  }
+
+  return out as T;
+}
+
+/**
+ * ドラッグで動かしたノードの位置を保存する patch。
+ * 保存してある position に移動量を足し、整数に丸める(position が無いときは 0, 0 から)。
+ * 子のノード(COMPONENT を含む)の position は親の中での位置なので、親を動かしても子の patch は要らない。
+ */
+export function movePatch(node: DeploymentNodeRecord, move: DeploymentMove): DeploymentChange {
+  const base = node.position || { x: 0, y: 0 };
+
+  return {
+    collection: 'nodes',
+    id: node.id,
+    patch: {
+      position: {
+        x: Math.round(base.x + move.dx),
+        y: Math.round(base.y + move.dy),
+      },
+    },
+  };
+}
+
+// ---- 入力の読み取り ------------------------------------------------------------
+
+function toNumber(value: string): number | null {
+  const n = Number(value);
+
+  return value !== '' && Number.isFinite(n) ? n : null;
+}
+
+/**
+ * 色として読める文字列か。
+ * ブラウザでは CSS.supports('color', v) で判定する。Node など CSS の無い環境では、
+ * #rgb / #rrggbb / #rrggbbaa・rgb() などの関数表記・英字だけの色名、を通す緩い判定にする。
+ */
+export function isColor(value: string): boolean {
+  if (value === '')
+    return false;
+
+  const css = (globalThis as { CSS?: { supports?: (p: string, v: string) => boolean } }).CSS;
+
+  if (css && typeof css.supports === 'function')
+    return css.supports('color', value);
+
+  return /^#([0-9a-f]{3,4}|[0-9a-f]{6}|[0-9a-f]{8})$/i.test(value)
+    || /^(rgb|rgba|hsl|hsla|hwb|lab|lch|oklab|oklch|color)\(.+\)$/i.test(value)
+    || /^[a-z]+$/i.test(value);
+}
+
+function toColor(value: string, label: string): string {
+  if (!isColor(value))
+    throw new ModelError(`${label}は、色 (#ff0000 や red など) で入力してください。`);
+
+  return value;
+}
+
+// 0 より大きい数(枠線・線の太さ。d3.deployment は 0 を「書いていない」と見て既定に倒すので、0 は入れられない)
+function toWidth(value: string, label: string): number {
+  const n = toNumber(value);
+
+  if (n === null || n <= 0)
+    throw new ModelError(`${label}は、0 より大きい数で入力してください。`);
+
+  return n;
+}
+
+// 0 以上の整数(幅・高さ。0 は「子に合わせる」)
+function toLength(value: string, label: string): number {
+  const n = toNumber(value);
+
+  if (n === null || n < 0)
+    throw new ModelError(`${label}は 0 以上の数で入力してください。(0 で子に合わせる)`);
+
+  return Math.round(n);
+}
+
+// 角度(0 以上 360 未満の整数に正規化)
+function toDegree(value: string, label: string): number {
+  const n = toNumber(value);
+
+  if (n === null)
+    throw new ModelError(`${label}は、角度 (数) で入力してください。`);
+
+  return ((Math.round(n) % 360) + 360) % 360;
+}
+
+function toOption(value: string, options: readonly string[], label: string): string {
+  if (!options.includes(value))
+    throw new ModelError(`${label}は、${options.join(' / ')} のどれかで入力してください。`);
+
+  return value;
+}
+
+// true / false
+function toBoolean(value: string, label: string): boolean {
+  if (value !== 'true' && value !== 'false')
+    throw new ModelError(`${label}は、true / false のどちらかで入力してください。`);
+
+  return value === 'true';
+}
+
+// 空にできる文字列。空なら null(JSON Merge Patch で項目を除く)
+function toOptionalText(value: string): string | null {
+  return value === '' ? null : value;
+}
+
+// patch の入れ子に値を置く(patch.border.color = v のように)
+function put(patch: MergePatch, path: string, value: unknown): void {
+  const keys = path.split('.');
+  let cur = patch;
+
+  for (const key of keys.slice(0, -1)) {
+    if (!cur[key] || typeof cur[key] !== 'object')
+      cur[key] = {};
+
+    cur = cur[key] as MergePatch;
+  }
+
+  cur[keys[keys.length - 1]] = value;
+}
+
+/**
+ * インスペクタの入力のうち、図に描いている値(withDefaults で埋めた値)から変わった項目だけを返す。
+ * 前後の空白は除く。読み取り専用の項目と、values に無い項目は含めない。
+ */
+function changedValues(record: DeploymentRecord, values: DeploymentValues): Map<string, string> {
+  const effective = withDefaults(record);
+  const out = new Map<string, string>();
+
+  for (const field of fieldsOf(record)) {
+    if (field.type === 'readonly')
+      continue;
+
+    const value = values[field.path];
+
+    if (value === undefined)
+      continue;
+
+    const current = getByPath(effective, field.path);
+
+    if (value.trim() !== String(current ?? ''))
+      out.set(field.path, value.trim());
+  }
+
+  return out;
+}
+
+// ノードの入力 → patch(label.text / type / description / link.url / size / background / border)
+function nodePatch(node: DeploymentNodeRecord, values: DeploymentValues): MergePatch {
+  const patch: MergePatch = {};
+
+  for (const [path, value] of changedValues(node, values)) {
+    switch (path) {
+      case 'label.text':
+        // 名称は空にできない(d3.deployment は名称の無いノードに '????????' を描く)
+        if (value === '')
+          throw new ModelError('名称を入力してください。');
+
+        put(patch, path, value);
+        break;
+      case 'type':
+        put(patch, path, toOption(value, NODE_TYPES, '種類'));
+        break;
+      case 'description':
+        put(patch, path, toOptionalText(value));
+        break;
+      case 'link.url':
+        // URL を空にするとリンクごと除く(d3.deployment は url の無い link を描かない)
+        if (value === '')
+          patch.link = null;
+        else
+          put(patch, path, value);
+        break;
+      case 'size.w':
+        put(patch, path, toLength(value, '幅'));
+        break;
+      case 'size.h':
+        put(patch, path, toLength(value, '高さ'));
+        break;
+      case 'background.color':
+        put(patch, path, toColor(value, '背景色'));
+        break;
+      case 'border.color':
+        put(patch, path, toColor(value, '枠線の色'));
+        break;
+      case 'border.width':
+        put(patch, path, toWidth(value, '枠線の太さ'));
+        break;
+    }
+  }
+
+  return patch;
+}
+
+const END_LABELS: Record<string, string> = { from: '接続元', to: '接続先' };
+
+// 線の入力 → patch(from / to の角度・stroke・矢印)
+function edgePatch(edge: DeploymentEdgeRecord, values: DeploymentValues): MergePatch {
+  const patch: MergePatch = {};
+
+  for (const [path, value] of changedValues(edge, values)) {
+    switch (path) {
+      case 'from.position':
+      case 'to.position':
+        put(patch, path, toDegree(value, `${END_LABELS[path.split('.')[0]]}の位置`));
+        break;
+      case 'stroke.color':
+        put(patch, path, toColor(value, '線の色'));
+        break;
+      case 'stroke.width':
+        put(patch, path, toWidth(value, '線の太さ'));
+        break;
+      case 'stroke.marker.start':
+        put(patch, path, toBoolean(value, '始点の矢印'));
+        break;
+      case 'stroke.marker.end':
+        put(patch, path, toBoolean(value, '終点の矢印'));
+        break;
+    }
+  }
+
+  // 矢印を片方だけ書くと d3.deployment の Edge.normalize は marker を丸ごと入力で置き換える(無い側は undefined =
+  // start は偽、end は truthy 判定で偽)ので、片方を変えたときはもう片方も描いている値で埋める
+  const marker = (patch.stroke as MergePatch | undefined)?.marker as MergePatch | undefined;
+
+  if (marker) {
+    const effective = withDefaults(edge).stroke!.marker!;
+
+    if (marker.start === undefined) marker.start = effective.start;
+    if (marker.end === undefined) marker.end = effective.end;
+  }
+
+  return patch;
+}
+
+/**
+ * インスペクタの「適用」の値を、保存する patch に変換する。
+ * 図に描いている値から変えた項目だけを patch に入れる(変えていない既定の値まで書き込まないため)。
+ * 変更が無ければ patch は {}。
+ */
+export function applyPatch(record: DeploymentRecord, values: DeploymentValues): DeploymentChange {
+  return {
+    collection: collectionOf(record),
+    id: record.id,
+    patch: isEdge(record) ? edgePatch(record, values) : nodePatch(record as DeploymentNodeRecord, values),
+  };
+}

package/src/schema.ts

@@ -0,0 +1,100 @@
+// d3.deployment の入力データの JSON Schema(2020-12)。
+//
+// iHub の server/schemas/deployment/{nodes,edges}.schema.json を移したもの。
+// 検査するのは、図の構造にかかわる項目(id・type・size・position・children・link、線の from / to)だけで、
+// 見た目の項目(label・border・background・padding・description)は d3.deployment の入力の形のまま書けるよう
+// additionalProperties を閉じていない(iHub 版は閉じていた)。
+//
+// x-id-start はスキーマの検証には使わない注釈(コレクションが空のときに最初に振る id)。
+// Ajv で使うときは addKeyword({ keyword: 'x-id-start', schemaType: 'number' }) を足す。
+
+import { NODE_TYPES } from './defaults.js';
+
+const ID = { type: ['integer', 'string'] } as const;
+
+const POINT = {
+  type: 'object',
+  properties: { x: { type: 'number' }, y: { type: 'number' } },
+  required: ['x', 'y'],
+} as const;
+
+export const NODES_SCHEMA = {
+  $schema: 'https://json-schema.org/draft/2020-12/schema',
+  title: 'システム構成図のノード',
+  description: 'd3.deployment に渡すノード。children に子のノードを入れ子で持つ。id は子のノードも含めて一意にする。position は親の中での位置で、ドラッグで動かすと書き換わる。link を付けると、ノードの左下にリンクを出す。見た目の項目 (label・padding・border・background・description) は d3.deployment の入力の形のまま書ける。',
+  'x-id-start': 1,
+  type: 'array',
+  items: { $ref: '#/$defs/node' },
+  $defs: {
+    node: {
+      type: 'object',
+      properties: {
+        id: ID,
+        type: { enum: [...NODE_TYPES] },
+        label: {
+          type: 'object',
+          properties: { text: { type: ['string', 'null'] } },
+        },
+        description: { type: ['string', 'null'] },
+        size: {
+          type: 'object',
+          properties: { w: { type: 'number', minimum: 0 }, h: { type: 'number', minimum: 0 } },
+          required: ['w', 'h'],
+        },
+        position: POINT,
+        link: {
+          type: ['object', 'null'],
+          properties: { url: { type: ['string', 'null'] } },
+        },
+        children: { type: 'array', items: { $ref: '#/$defs/node' } },
+      },
+      required: ['id'],
+      additionalProperties: true,
+    },
+  },
+} as const;
+
+export const EDGES_SCHEMA = {
+  $schema: 'https://json-schema.org/draft/2020-12/schema',
+  title: 'システム構成図の線',
+  description: 'ノードの間の線。from.id / to.id はノード (子を含む) の id。position は接続位置の角度 (0=真下・時計回り。省略すると 90=左)。stroke.marker は両端の矢印の有無 (既定: 終点だけ)。',
+  'x-id-start': 100,
+  type: 'array',
+  items: {
+    type: 'object',
+    properties: {
+      id: ID,
+      from: { $ref: '#/$defs/end' },
+      to: { $ref: '#/$defs/end' },
+      stroke: {
+        type: 'object',
+        properties: {
+          color: { type: 'string' },
+          width: { type: 'number' },
+          marker: {
+            type: 'object',
+            properties: { start: { type: 'boolean' }, end: { type: 'boolean' } },
+          },
+        },
+      },
+    },
+    required: ['id', 'from', 'to'],
+    additionalProperties: true,
+  },
+  $defs: {
+    end: {
+      type: 'object',
+      properties: {
+        id: ID,
+        position: { type: 'number' },
+      },
+      required: ['id'],
+    },
+  },
+} as const;
+
+/** コレクション名 → スキーマ */
+export const SCHEMAS = {
+  nodes: NODES_SCHEMA,
+  edges: EDGES_SCHEMA,
+} as const;

package/src/types.ts

@@ -0,0 +1,102 @@
+// model.deployment の公開型。
+//
+// ここで言う「レコード」は、d3.deployment の data() に渡す入力そのもの({ nodes, edges })の 1 要素。
+// iHub では data/deployment/{nodes,edges}.json の 1 要素。d3.deployment が正規化したあとの datum(_id / _core / _position を持つもの)ではない。
+// ノードと線の図なので model.unchi / model.sitemap と形が近い。ラベルは label.text(unchi と同じ。sitemap は label.contents)。
+
+import type { Background, Border, Font, Position, Size, Stroke } from '@yanqirenshi/types';
+
+/** レコードの id(nodes / edges とも。ノードは子も含めて一意) */
+export type DeploymentId = number | string;
+
+/** ノードの種類。NODE(通常のノード)か COMPONENT */
+export type DeploymentNodeType = 'NODE' | 'COMPONENT';
+
+/** ノードのラベル */
+export interface DeploymentNodeLabel {
+  text?: string | null;
+  position?: Position;
+  font?: Font;
+}
+
+/** ノードのレコード(入れ子可)。ライブラリが解釈しない項目も持てる(index signature) */
+export interface DeploymentNodeRecord {
+  id: DeploymentId;
+  type?: DeploymentNodeType | string;
+  label?: DeploymentNodeLabel | null;
+  /** ホバーのツールチップ(SVG title) */
+  description?: string | null;
+  size?: Size;
+  position?: Position;
+  padding?: number;
+  border?: Border;
+  background?: Background;
+  /** ノードの左下に出すリンク */
+  link?: { url?: string | null; [key: string]: unknown } | null;
+  children?: DeploymentNodeRecord[];
+  [key: string]: unknown;
+}
+
+/** 線の端点。position はノードの中心から見た角度(0=真下・時計回り。90=左 / 180=真上 / 270=右) */
+export interface DeploymentEdgeEnd {
+  id: DeploymentId;
+  position?: number;
+}
+
+/** 線の見た目。marker は両端の矢印の有無 */
+export interface DeploymentEdgeStroke extends Stroke {
+  marker?: { start?: boolean; end?: boolean };
+}
+
+/** 線のレコード */
+export interface DeploymentEdgeRecord {
+  id: DeploymentId;
+  from: DeploymentEdgeEnd;
+  to: DeploymentEdgeEnd;
+  stroke?: DeploymentEdgeStroke;
+  [key: string]: unknown;
+}
+
+export type DeploymentRecord = DeploymentNodeRecord | DeploymentEdgeRecord;
+
+/** 図全体(d3.deployment の data() に渡すもの) */
+export interface DeploymentGraph {
+  nodes?: DeploymentNodeRecord[];
+  edges?: DeploymentEdgeRecord[];
+}
+
+/** レコードを置くコレクション */
+export type DeploymentCollection = 'nodes' | 'edges';
+
+/** JSON Merge Patch(RFC 7386)。null は「その項目を除く」 */
+export type MergePatch = { [key: string]: unknown };
+
+/** 保存する変更。利用側は図の種類を知らずにこれを保存すればよい */
+export interface DeploymentChange {
+  collection: DeploymentCollection;
+  id: DeploymentId;
+  patch: MergePatch;
+}
+
+/** ドラッグの移動量(世界座標。d3.deployment の callbacks.node.dragend が渡す move と同じ) */
+export interface DeploymentMove {
+  dx: number;
+  dy: number;
+}
+
+/**
+ * 編集できる項目。colonoscope の ColonoscopeField(path / label / type)と同じ形で、
+ * 取りうる値の一覧 options だけ足している(型は構造的に互換。colonoscope には依存しない)。
+ */
+export type DeploymentFieldType = 'text' | 'textarea' | 'number' | 'readonly';
+
+export interface DeploymentField {
+  /** レコードの項目のパス(ドット区切り。例: 'border.color')。写し先ではなく実際の項目を指す */
+  path: string;
+  label: string;
+  type: DeploymentFieldType;
+  options?: readonly string[];
+}
+
+/** インスペクタの「適用」が渡す値(path → 入力した文字列) */
+export type DeploymentValues = Record<string, string>;