@bendyline/squisq 2.1.0 → 2.2.0

package/src/jsonForm/pointer.ts

@@ -1,154 +0,0 @@
-/**
- * JSON Pointer helpers (RFC 6901) plus immutable get/set, plus a tiny
- * dotted-path normalizer so hosts can write `user.role` instead of
- * `/user/role`. `$ref` resolution is local-only (`#/$defs/Foo`).
- */
-
-import type { SquisqAnnotatedSchema } from './types.js';
-
-/** Escape one object-member name for use as an RFC 6901 pointer segment. */
-export function escapePointerSegment(segment: string): string {
-  return segment.replace(/~/g, '~0').replace(/\//g, '~1');
-}
-
-/** Normalize a path to a JSON Pointer string. Accepts both forms. */
-export function toPointer(path: string): string {
-  if (path === '') return '';
-  if (path.startsWith('/')) return path;
-  // Dotted form: split on `.` and escape per RFC 6901.
-  return '/' + path.split('.').map(escapePointerSegment).join('/');
-}
-
-/** Append one member name to a dotted path or validated JSON Pointer. */
-export function appendPointer(base: string, segment: string): string {
-  const pointer = toPointer(base);
-  pointerSegments(pointer); // validate explicit pointer syntax before composing
-  return `${pointer}/${escapePointerSegment(segment)}`;
-}
-
-/** Split a JSON Pointer into decoded segments. Empty string → []. */
-export function pointerSegments(pointer: string): string[] {
-  if (pointer === '') return [];
-  if (!pointer.startsWith('/')) {
-    throw new TypeError(`Invalid JSON Pointer ${JSON.stringify(pointer)}: expected "" or "/..."`);
-  }
-  return pointer
-    .slice(1)
-    .split('/')
-    .map((seg) => {
-      if (/~(?:[^01]|$)/.test(seg)) {
-        throw new TypeError(
-          `Invalid JSON Pointer ${JSON.stringify(pointer)}: "~" must be escaped as "~0"`,
-        );
-      }
-      return seg.replace(/~1/g, '/').replace(/~0/g, '~');
-    });
-}
-
-/** Parse the canonical array-index spelling used by JSON Pointer consumers. */
-function arrayIndex(segment: string): number | undefined {
-  if (!/^(?:0|[1-9]\d*)$/.test(segment)) return undefined;
-  const index = Number(segment);
-  // 2^32 - 1 is the Array length sentinel, not an element index.
-  return Number.isSafeInteger(index) && index <= 0xffff_fffe ? index : undefined;
-}
-
-function ownValue(object: object, key: string): unknown {
-  return Object.prototype.hasOwnProperty.call(object, key)
-    ? (object as Record<string, unknown>)[key]
-    : undefined;
-}
-
-/** Define a data member without invoking Object.prototype.__proto__'s setter. */
-function setOwn(object: Record<string, unknown>, key: string, value: unknown): void {
-  Object.defineProperty(object, key, {
-    value,
-    enumerable: true,
-    configurable: true,
-    writable: true,
-  });
-}
-
-/** Read a value from data by path (dotted or pointer). Returns undefined if missing. */
-export function getByPointer(data: unknown, path: string): unknown {
-  const segments = pointerSegments(toPointer(path));
-  let cur: unknown = data;
-  for (const seg of segments) {
-    if (cur === null || cur === undefined) return undefined;
-    if (Array.isArray(cur)) {
-      const idx = arrayIndex(seg);
-      if (idx === undefined || idx >= cur.length) return undefined;
-      cur = cur[idx];
-    } else if (typeof cur === 'object') {
-      cur = ownValue(cur, seg);
-    } else {
-      return undefined;
-    }
-  }
-  return cur;
-}
-
-/**
- * Return a structurally-shared copy of `data` with the value at `path`
- * replaced. Intermediate objects/arrays are cloned along the path; the
- * rest is shared by reference. Creates intermediate objects if missing.
- */
-export function setByPointer<T>(data: T, path: string, value: unknown): T {
-  const segments = pointerSegments(toPointer(path));
-  if (segments.length === 0) return value as T;
-  return setRec(data, segments, 0, value) as T;
-}
-
-function setRec(node: unknown, segments: string[], i: number, value: unknown): unknown {
-  const seg = segments[i];
-  const isLast = i === segments.length - 1;
-
-  // Decide whether the slot we're about to write into is an array index.
-  const nextSeg = isLast ? undefined : segments[i + 1];
-  const writingArrayChild = nextSeg !== undefined && arrayIndex(nextSeg) !== undefined;
-
-  if (Array.isArray(node)) {
-    const idx = arrayIndex(seg);
-    if (idx === undefined) {
-      throw new TypeError(`Invalid array index ${JSON.stringify(seg)} in JSON Pointer`);
-    }
-    const next = node.slice();
-    next[idx] = isLast
-      ? value
-      : setRec(node[idx] ?? (writingArrayChild ? [] : {}), segments, i + 1, value);
-    return next;
-  }
-
-  const obj = (node && typeof node === 'object' ? { ...(node as object) } : {}) as Record<
-    string,
-    unknown
-  >;
-  const previous = ownValue(obj, seg);
-  setOwn(
-    obj,
-    seg,
-    isLast ? value : setRec(previous ?? (writingArrayChild ? [] : {}), segments, i + 1, value),
-  );
-  return obj;
-}
-
-/**
- * Resolve a local `$ref` (e.g. `#/$defs/Foo`) against the root schema.
- * Returns the original schema if no `$ref` is present, or `undefined`
- * if the reference cannot be resolved. Cross-document refs are not
- * supported.
- */
-export function resolveRef(
-  schema: SquisqAnnotatedSchema,
-  root: SquisqAnnotatedSchema,
-): SquisqAnnotatedSchema | undefined {
-  if (!schema.$ref) return schema;
-  const ref = schema.$ref;
-  if (ref === '#') return root;
-  if (!ref.startsWith('#/')) return undefined;
-  try {
-    return getByPointer(root, ref.slice(1)) as SquisqAnnotatedSchema | undefined;
-  } catch {
-    return undefined;
-  }
-}

package/src/jsonForm/tokens.ts

@@ -1,78 +0,0 @@
-/**
- * Pure CSS-custom-property builder shared by `<JsonView>` (read-only, in
- * `@bendyline/squisq-react`) and `<JsonEditor>` (editable, in
- * `@bendyline/squisq-editor-react`).
- *
- * Both components derive an identical token bag from a Theme + resolved
- * Surface; they differ only in the CSS-var prefix (`--squisq-json` vs
- * `--squisq-jsonform`) so the viewer and editor can coexist on one page.
- * This function is the single source of that derivation. It is pure and
- * framework-free: it performs no `window` / `matchMedia` access — the
- * surface must already be resolved to a concrete `SurfaceScheme` (or left
- * `undefined` to skip surface application) by the calling React hook.
- */
-
-import { applySurface, DEFAULT_THEME, resolveFontFamily } from '../schemas/index.js';
-import type { SurfaceScheme, Theme } from '../schemas/index.js';
-
-export interface BuildJsonFormTokensOptions {
-  /**
-   * CSS-var prefix WITHOUT the trailing dash, e.g. `--squisq-json` or
-   * `--squisq-jsonform`. Each token key is `${prefix}-${name}`.
-   */
-  prefix: string;
-}
-
-/**
- * Build the CSS custom-property map for a JSON form/view surface.
- *
- * @param theme   The theme to render with (falls back to `DEFAULT_THEME`).
- * @param surface Already-resolved concrete surface, or `undefined` to leave
- *                the theme un-surfaced. (The `'auto'` → concrete resolution
- *                is the React hook's job, so this stays pure.)
- * @param options `{ prefix }` — the CSS-var namespace.
- */
-export function buildJsonFormTokens(
-  theme: Theme | undefined,
-  surface: SurfaceScheme | undefined,
-  options: BuildJsonFormTokensOptions,
-): Record<string, string> {
-  const { prefix } = options;
-  const baseTheme = theme ?? DEFAULT_THEME;
-  const finalTheme = surface ? applySurface(baseTheme, surface) : baseTheme;
-
-  const titleFont = resolveFontFamily(finalTheme.typography.titleFont, 'system-ui, sans-serif');
-  const bodyFont = resolveFontFamily(finalTheme.typography.bodyFont, 'system-ui, sans-serif');
-  const monoFont = resolveFontFamily(
-    finalTheme.typography.monoFont,
-    'ui-monospace, Consolas, monospace',
-  );
-
-  return {
-    [`${prefix}-bg`]: finalTheme.colors.background,
-    [`${prefix}-text`]: finalTheme.colors.text,
-    [`${prefix}-muted`]: finalTheme.colors.textMuted,
-    [`${prefix}-primary`]: finalTheme.colors.primary,
-    [`${prefix}-accent`]: finalTheme.colors.secondary,
-    [`${prefix}-warning`]: finalTheme.colors.warning,
-    [`${prefix}-border`]: `color-mix(in srgb, ${finalTheme.colors.textMuted} 35%, transparent)`,
-    [`${prefix}-input-bg`]: finalTheme.colors.backgroundLight,
-    [`${prefix}-title-font`]: titleFont,
-    [`${prefix}-body-font`]: bodyFont,
-    [`${prefix}-mono-font`]: monoFont,
-    [`${prefix}-radius`]: `${finalTheme.style.borderRadius ?? 8}px`,
-  };
-}
-
-/**
- * Resolve the effective theme after surface application — the companion to
- * `buildJsonFormTokens` for callers that also need the `Theme` object (both
- * hooks return it alongside the style bag).
- */
-export function resolveJsonFormTheme(
-  theme: Theme | undefined,
-  surface: SurfaceScheme | undefined,
-): Theme {
-  const baseTheme = theme ?? DEFAULT_THEME;
-  return surface ? applySurface(baseTheme, surface) : baseTheme;
-}

package/src/jsonForm/types.ts

@@ -1,167 +0,0 @@
-/**
- * JSON Form types — Squisq's hint vocabulary layered on JSON Schema.
- *
- * Hints live inline on a JSON Schema under a single `squisq` key. The
- * schema remains a valid JSON Schema; the extra key is ignored by
- * standard validators. Renderers consult the hints to pick a control
- * and tune its presentation.
- */
-
-/**
- * Every concrete control rendered by `<JsonView>` and `<JsonEditor>`.
- *
- * Auto-defaults pick one based on schema shape; hosts override via
- * `squisq.control` when they want something specific (e.g. radio over
- * segmented for a long, descriptive enum).
- */
-export type ControlKind =
-  | 'text'
-  | 'multiline'
-  | 'richtext'
-  | 'color'
-  | 'date'
-  | 'time'
-  | 'datetime'
-  | 'slider'
-  | 'stepper'
-  | 'segmented'
-  | 'radio'
-  | 'combobox'
-  | 'toggle'
-  | 'checkbox'
-  | 'card'
-  | 'card-stack'
-  | 'chip-bin'
-  | 'tabs'
-  | 'group';
-
-/**
- * Conditional rule: looked up by field path against the root data and
- * compared with one of the operators. The first defined operator wins
- * (in declaration order: equals, oneOf, matches, truthy).
- */
-export interface SquisqWhen {
-  /**
-   * Path to the controlling field, relative to the root data.
-   * Accepts dotted-path (`user.role`) or JSON Pointer (`/user/role`).
-   */
-  field: string;
-  equals?: unknown;
-  oneOf?: readonly unknown[];
-  /** ECMAScript regex source; matched against the string value. */
-  matches?: string;
-  /** When true, condition holds if value is truthy; when false, if falsy. */
-  truthy?: boolean;
-}
-
-/**
- * Hints for a single schema node. Attach via `squisq` on any JSON
- * Schema object — properties, items, the root, or sub-schemas inside
- * `oneOf`/`anyOf`.
- */
-export interface SquisqHints {
-  /** Force a specific control. If omitted, picked from type/format/enum cardinality. */
-  control?: ControlKind;
-
-  /** Override schema `title` for display. */
-  label?: string;
-  /** Override schema `description` for the inline helper text. */
-  help?: string;
-  /** Placeholder text for empty fields. */
-  placeholder?: string;
-
-  /** Suggested layout sizing in a parent grid. Renderers may ignore on narrow viewports. */
-  width?: 'full' | 'half' | 'third' | 'auto';
-
-  /** Hide the field — literal, or a `SquisqWhen` evaluated against root data. */
-  hidden?: boolean | SquisqWhen;
-  /** Disable the field — literal, or a `SquisqWhen` evaluated against root data. */
-  disabled?: boolean | SquisqWhen;
-
-  /** Override schema's required-ness for the UI only. */
-  required?: boolean;
-
-  /** For arrays of objects: how to label each card in a `card-stack`. */
-  itemLabel?: string | { fromField: string };
-  /** Label for the "+ Add" button on arrays. */
-  addLabel?: string;
-  /** Label for the remove button on arrays. */
-  removeLabel?: string;
-
-  /** Slider/stepper visual step. Falls back to schema `multipleOf`. */
-  step?: number;
-
-  /** Optional human-readable labels for enum values. */
-  enumLabels?: Record<string, string>;
-}
-
-/**
- * The subset of JSON Schema we understand, with an optional `squisq`
- * key. We deliberately keep this as a structural type so any JSON
- * Schema authored elsewhere can be passed in without conversion.
- */
-export interface SquisqAnnotatedSchema {
-  type?: string | readonly string[];
-  format?: string;
-  title?: string;
-  description?: string;
-  default?: unknown;
-  examples?: readonly unknown[];
-
-  enum?: readonly unknown[];
-  const?: unknown;
-
-  // Object
-  properties?: Record<string, SquisqAnnotatedSchema>;
-  required?: readonly string[];
-  additionalProperties?: boolean | SquisqAnnotatedSchema;
-
-  // Array
-  items?: SquisqAnnotatedSchema | readonly SquisqAnnotatedSchema[];
-  minItems?: number;
-  maxItems?: number;
-
-  // Number
-  minimum?: number;
-  maximum?: number;
-  exclusiveMinimum?: number;
-  exclusiveMaximum?: number;
-  multipleOf?: number;
-
-  // String
-  minLength?: number;
-  maxLength?: number;
-  pattern?: string;
-
-  // Combinators
-  oneOf?: readonly SquisqAnnotatedSchema[];
-  anyOf?: readonly SquisqAnnotatedSchema[];
-  allOf?: readonly SquisqAnnotatedSchema[];
-
-  // References
-  $ref?: string;
-  $defs?: Record<string, SquisqAnnotatedSchema>;
-  definitions?: Record<string, SquisqAnnotatedSchema>;
-
-  // Squisq-native UI hints
-  squisq?: SquisqHints;
-}
-
-/**
- * A validation error reported by the consumer-supplied `validate` prop.
- * Matches the shape of common validators (ajv, etc.) without depending
- * on any specific one.
- */
-export interface JsonFormValidationError {
-  /** JSON Pointer to the failing value, e.g. `/sections/0/heading`. */
-  path: string;
-  /** Human-readable message. */
-  message: string;
-  /** Optional schema keyword that failed (e.g. "required", "minimum"). */
-  keyword?: string;
-}
-
-export type JsonFormValidator = (
-  value: unknown,
-  schema: SquisqAnnotatedSchema,
-) => readonly JsonFormValidationError[];

package/src/markdown/annotationCoercion.ts

@@ -1,295 +0,0 @@
-/**
- * Heading-attribute value coercion.
- *
- * The Pandoc-style heading attribute block `{#id .class key=value}` parses
- * to a flat `Record<string, string>` of `key → raw value`. This module
- * coerces a known subset of keys to typed values (numbers, time-in-seconds,
- * `BlockConnection[]`) so downstream consumers don't have to re-parse them.
- *
- * Unknown keys are returned in `metadata` as raw strings. Malformed known-key
- * values are dropped from the typed result and reported via `warnings` (the
- * raw string is preserved in `params` upstream for lossless round-tripping —
- * coercion failures do not corrupt the source).
- */
-
-import type { BlockConnection } from './types.js';
-import type { TransitionDirection, TransitionType } from '../schemas/Transitions.js';
-import {
-  normalizeTransitionDirection,
-  normalizeTransitionType,
-  TRANSITION_TYPES,
-  TRANSITION_DIRECTIONS,
-} from '../schemas/Transitions.js';
-
-/**
- * Registry of known block-meta keys and their coercion strategies.
- *
- * Adding a new typed key: add an entry here, add the typed field to
- * `HeadingAttributes.blockMeta` in `types.ts`, and apply the coerced value
- * in `markdownToDoc.ts`.
- */
-export const KNOWN_BLOCK_META_KEYS = {
-  x: 'number',
-  y: 'number',
-  startTime: 'time',
-  duration: 'time',
-  connectsTo: 'connectionList',
-  transition: 'transition',
-  transitionDuration: 'time',
-  transitionDirection: 'transitionDirection',
-} as const;
-
-export type KnownBlockMetaKey = keyof typeof KNOWN_BLOCK_META_KEYS;
-
-/**
- * Editor-facing description of a known block-meta key: what it does, and
- * either its closed set of valid values or a free-form format hint. This is
- * the single source the markdown editor's `{[name key=value]}` attribute
- * autocomplete reads from, so the suggestion list stays in lockstep with
- * `KNOWN_BLOCK_META_KEYS` and the transition vocabulary rather than drifting
- * in a hand-maintained copy. `values`/`valueHint` are mutually exclusive: a
- * key has a closed enum (`values`) or a format hint (`valueHint`), not both.
- */
-export interface BlockMetaKeyDescriptor {
-  key: KnownBlockMetaKey;
-  /** One-line description, shown as the completion item's detail. */
-  description: string;
-  /** Closed set of valid values, for keys backed by an enum. */
-  values?: readonly string[];
-  /** Format hint shown when the value is free-form (no closed set). */
-  valueHint?: string;
-}
-
-/**
- * Ordered descriptors for every key in `KNOWN_BLOCK_META_KEYS`. Order is the
- * suggestion display order: the transition family first (the most common
- * authoring case), then timeline timing, then diagram geometry/links.
- */
-export const BLOCK_META_KEY_DESCRIPTORS: readonly BlockMetaKeyDescriptor[] = [
-  {
-    key: 'transition',
-    description: 'Block-to-block transition effect',
-    values: TRANSITION_TYPES,
-  },
-  {
-    key: 'transitionDuration',
-    description: 'How long the transition lasts',
-    valueHint: 'seconds — e.g. 0.7, 700ms',
-  },
-  {
-    key: 'transitionDirection',
-    description: 'Directional variant for the transition',
-    values: TRANSITION_DIRECTIONS,
-  },
-  {
-    key: 'startTime',
-    description: 'Timeline start time of this block',
-    valueHint: 'mm:ss or seconds — e.g. 01:30, 5, 1500ms',
-  },
-  {
-    key: 'duration',
-    description: 'How long this block lasts',
-    valueHint: 'mm:ss or seconds — e.g. 45, 1500ms',
-  },
-  {
-    key: 'x',
-    description: 'Horizontal position on the diagram canvas',
-    valueHint: 'number — e.g. 600',
-  },
-  {
-    key: 'y',
-    description: 'Vertical position on the diagram canvas',
-    valueHint: 'number — e.g. 300',
-  },
-  {
-    key: 'connectsTo',
-    description: 'Diagram connections to other blocks',
-    valueHint: 'comma-separated target or target:type — e.g. foo,bar:flow',
-  },
-];
-
-/**
- * The shape of the typed values produced by coercion. Mirrors
- * `HeadingAttributes.blockMeta` in `types.ts`.
- */
-export interface CoercedBlockMeta {
-  x?: number;
-  y?: number;
-  startTime?: number;
-  duration?: number;
-  connectsTo?: BlockConnection[];
-  transition?: {
-    type: TransitionType;
-    duration?: number;
-    direction?: TransitionDirection;
-  };
-}
-
-export interface CoerceResult {
-  /** Typed values for known keys whose coercion succeeded. */
-  blockMeta: CoercedBlockMeta;
-  /** Raw string values for keys not in the known-key registry. */
-  metadata: Record<string, string>;
-  /** Human-readable diagnostics — currently emitted for coercion failures. */
-  warnings: string[];
-}
-
-/**
- * Coerce a flat `key → raw string` map into typed block-meta + an
- * untyped metadata bag, per the `KNOWN_BLOCK_META_KEYS` registry.
- */
-export function coerceAnnotationValues(params: Record<string, string>): CoerceResult {
-  const blockMeta: CoercedBlockMeta = {};
-  const metadata: Record<string, string> = {};
-  const warnings: string[] = [];
-  let transitionType: TransitionType | null = null;
-  let transitionDuration: number | undefined;
-  let transitionDirection: TransitionDirection | undefined;
-
-  for (const [key, raw] of Object.entries(params)) {
-    const kind = (KNOWN_BLOCK_META_KEYS as Record<string, string>)[key];
-    if (!kind) {
-      metadata[key] = raw;
-      continue;
-    }
-    if (kind === 'number') {
-      const n = parseNumber(raw);
-      if (n == null) {
-        warnings.push(`Invalid number for "${key}": ${JSON.stringify(raw)}`);
-      } else {
-        (blockMeta as Record<string, unknown>)[key] = n;
-      }
-    } else if (kind === 'time') {
-      const s = parseTimeSeconds(raw);
-      if (s == null) {
-        warnings.push(`Invalid time for "${key}": ${JSON.stringify(raw)}`);
-      } else if (key === 'transitionDuration') {
-        transitionDuration = s;
-      } else {
-        (blockMeta as Record<string, unknown>)[key] = s;
-      }
-    } else if (kind === 'connectionList') {
-      const { list, warning } = parseConnectionList(raw);
-      if (warning) warnings.push(`"${key}": ${warning}`);
-      blockMeta.connectsTo = list;
-    } else if (kind === 'transition') {
-      const transition = normalizeTransitionType(raw);
-      if (transition == null) {
-        warnings.push(`Invalid transition for "${key}": ${JSON.stringify(raw)}`);
-      } else {
-        transitionType = transition;
-      }
-    } else if (kind === 'transitionDirection') {
-      const direction = normalizeTransitionDirection(raw);
-      if (direction == null) {
-        warnings.push(`Invalid transition direction for "${key}": ${JSON.stringify(raw)}`);
-      } else {
-        transitionDirection = direction;
-      }
-    }
-  }
-
-  if (transitionType) {
-    blockMeta.transition = {
-      type: transitionType,
-      ...(transitionDuration !== undefined ? { duration: transitionDuration } : {}),
-      ...(transitionDirection !== undefined ? { direction: transitionDirection } : {}),
-    };
-  }
-
-  return { blockMeta, metadata, warnings };
-}
-
-// ============================================
-// Coercers
-// ============================================
-
-/** Parse a finite number from a string. Returns null on failure. */
-export function parseNumber(raw: string): number | null {
-  if (raw.trim() === '') return null;
-  const n = Number(raw);
-  return Number.isFinite(n) ? n : null;
-}
-
-const TIME_BARE_RE = /^\d+(?:\.\d+)?$/;
-const TIME_MS_RE = /^(\d+(?:\.\d+)?)ms$/;
-const TIME_MMSS_RE = /^(\d+):(\d{1,2})(?:\.(\d+))?$/;
-
-/**
- * Parse a time value to seconds. Accepts:
- * - bare number: `5` → 5, `5.5` → 5.5
- * - `mm:ss`: `01:30` → 90
- * - `mm:ss.ms`: `01:30.500` → 90.5
- * - `1500ms` → 1.5
- *
- * Returns null on malformed input.
- */
-export function parseTimeSeconds(raw: string): number | null {
-  const trimmed = raw.trim();
-  if (!trimmed) return null;
-
-  if (TIME_BARE_RE.test(trimmed)) {
-    const n = Number(trimmed);
-    return Number.isFinite(n) ? n : null;
-  }
-
-  const msMatch = trimmed.match(TIME_MS_RE);
-  if (msMatch) {
-    const n = Number(msMatch[1]);
-    return Number.isFinite(n) ? n / 1000 : null;
-  }
-
-  const mmssMatch = trimmed.match(TIME_MMSS_RE);
-  if (mmssMatch) {
-    const mins = Number(mmssMatch[1]);
-    const secs = Number(mmssMatch[2]);
-    const frac = mmssMatch[3] ? Number(`0.${mmssMatch[3]}`) : 0;
-    if (!Number.isFinite(mins) || !Number.isFinite(secs) || !Number.isFinite(frac)) {
-      return null;
-    }
-    if (secs >= 60) return null;
-    return mins * 60 + secs + frac;
-  }
-
-  return null;
-}
-
-/**
- * Parse a comma-separated connection list. Each entry is `target` or
- * `target:type`. Empty entries (`a,,b`) are filtered with a warning; an
- * entirely empty input yields an empty list with no warning.
- */
-export function parseConnectionList(raw: string): {
-  list: BlockConnection[];
-  warning: string | null;
-} {
-  const trimmed = raw.trim();
-  if (!trimmed) return { list: [], warning: null };
-
-  const list: BlockConnection[] = [];
-  let droppedEmpty = false;
-  for (const part of trimmed.split(',')) {
-    const entry = part.trim();
-    if (!entry) {
-      droppedEmpty = true;
-      continue;
-    }
-    const colonIdx = entry.indexOf(':');
-    if (colonIdx < 0) {
-      list.push({ target: entry });
-    } else {
-      const target = entry.slice(0, colonIdx).trim();
-      const type = entry.slice(colonIdx + 1).trim();
-      if (!target) {
-        droppedEmpty = true;
-        continue;
-      }
-      list.push(type ? { target, type } : { target });
-    }
-  }
-
-  return {
-    list,
-    warning: droppedEmpty ? 'dropped empty connection entries' : null,
-  };
-}