@lapismd/design-core 0.1.0

package/src/shared/forms/core/path-utils.ts

@@ -0,0 +1,102 @@
+export type FormPathPart = string | number;
+
+export function formPathParts(path: string): FormPathPart[] {
+  if (!path) return [];
+  return path
+    .split(".")
+    .map((part) => (/^\d+$/.test(part) ? Number.parseInt(part, 10) : part));
+}
+
+export function getFormValueAtPath(root: unknown, path: string): unknown {
+  return formPathParts(path).reduce<unknown>((value, part) => {
+    if (typeof part === "number" && Array.isArray(value)) return value[part];
+    if (
+      typeof part === "string" &&
+      value !== null &&
+      typeof value === "object" &&
+      !Array.isArray(value)
+    ) {
+      return (value as Record<string, unknown>)[part];
+    }
+    return undefined;
+  }, root);
+}
+
+/** Immutably writes a value while retaining unknown sibling keys. */
+export function setFormValueAtPath<TValues>(
+  root: TValues,
+  path: string,
+  value: unknown,
+): TValues {
+  return setFormValueAtParts(root, formPathParts(path), value);
+}
+
+function setFormValueAtParts<TValues>(
+  root: TValues,
+  parts: FormPathPart[],
+  value: unknown,
+): TValues {
+  if (parts.length === 0) return value as TValues;
+  const [head, ...tail] = parts;
+
+  if (typeof head === "number") {
+    const next = Array.isArray(root) ? [...root] : [];
+    next[head] = setFormValueAtParts(next[head], tail, value);
+    return next as TValues;
+  }
+
+  const record =
+    root !== null && typeof root === "object" && !Array.isArray(root)
+      ? (root as Record<string, unknown>)
+      : {};
+  return {
+    ...record,
+    [head]: setFormValueAtParts(record[head], tail, value),
+  } as TValues;
+}
+
+/** Materializes a missing default branch before applying a leaf update. */
+export function setFormValueWithDefault<TValues>(
+  root: TValues,
+  path: string,
+  value: unknown,
+  defaults?: Partial<TValues>,
+  materializeDefaultFrom?: string,
+): TValues {
+  const seeded =
+    materializeDefaultFrom &&
+    getFormValueAtPath(root, materializeDefaultFrom) === undefined
+      ? setFormValueAtPath(
+          root,
+          materializeDefaultFrom,
+          structuredClone(getFormValueAtPath(defaults, materializeDefaultFrom)),
+        )
+      : root;
+  return setFormValueAtPath(seeded, path, value);
+}
+
+export function moveFormArrayItem<TItem>(
+  items: readonly TItem[],
+  index: number,
+  direction: -1 | 1,
+): TItem[] {
+  const target = index + direction;
+  if (
+    index < 0 ||
+    index >= items.length ||
+    target < 0 ||
+    target >= items.length
+  ) {
+    return items as TItem[];
+  }
+  const next = [...items];
+  [next[index], next[target]] = [next[target], next[index]];
+  return next;
+}
+
+export function removeFormArrayItem<TItem>(
+  items: readonly TItem[],
+  index: number,
+): TItem[] {
+  return items.filter((_, itemIndex) => itemIndex !== index);
+}

package/src/shared/forms/core/reference-utils.ts

@@ -0,0 +1,168 @@
+export type ReferenceKind = "cv_marker" | "story" | "cv_story" | "task";
+
+export type ParsedReference = {
+  ref: string;
+  target: string;
+  kind: ReferenceKind;
+  segments: string[];
+};
+
+export type ReferenceTarget = {
+  id: string;
+  ref: string;
+  marker: string;
+  path: string;
+  type: string;
+  label: string;
+  excerpt: string;
+  duplicate: boolean;
+  kind?: string;
+  selectable?: boolean;
+  href?: string;
+  optionNotes?: string;
+  optionStatus?: "todo" | "waiting";
+  preview?: ReferencePreview;
+};
+
+export type ReferenceIndex<T extends ReferenceTarget = ReferenceTarget> = {
+  references: T[];
+  duplicates: Record<string, T[]>;
+};
+
+export type ReferenceSelectedSlotProps = {
+  ref: string;
+  reference: ReferenceTarget | null;
+  duplicates: number;
+  expanded: boolean;
+  onToggleExpand: () => void;
+};
+
+export type ReferencePreviewItem =
+  | {
+      kind: "row";
+      label: string;
+      value?: string;
+      highlighted?: boolean;
+    }
+  | {
+      kind: "list";
+      label: string;
+      items?: string[];
+      highlightedIndexes?: number[];
+    };
+
+export type ReferencePreview = {
+  title?: string;
+  meta?: string;
+  items: ReferencePreviewItem[];
+};
+
+const REFERENCE_SEGMENT = /^[A-Za-z0-9_-]+$/;
+const REFERENCE_MARKER = /^\[\^([A-Za-z0-9_/-]+)\]$/;
+
+function validSegments(segments: string[]) {
+  return (
+    segments.length > 0 &&
+    segments.every((segment) => REFERENCE_SEGMENT.test(segment))
+  );
+}
+
+export function parseReferenceRef(value: unknown): ParsedReference | null {
+  if (typeof value !== "string") return null;
+  const trimmed = value.trim();
+  const match = REFERENCE_MARKER.exec(trimmed);
+  if (!match) return null;
+  const target = match[1];
+  const segments = target.split("/");
+  if (!validSegments(segments)) return null;
+
+  if (segments.length === 1) {
+    return { ref: trimmed, target, kind: "cv_marker", segments };
+  }
+  if (segments.length === 2 && segments[0] === "stories") {
+    return { ref: trimmed, target, kind: "story", segments };
+  }
+  if (
+    segments.length === 4 &&
+    segments[0] === "cv" &&
+    segments[2] === "stories"
+  ) {
+    return { ref: trimmed, target, kind: "cv_story", segments };
+  }
+  if (segments.length === 3 && segments[0] === "tasks") {
+    return { ref: trimmed, target, kind: "task", segments };
+  }
+  return null;
+}
+
+export function normalizeReferenceRef(value: unknown) {
+  return parseReferenceRef(value)?.ref ?? null;
+}
+
+export function normalizeReferenceList(value: unknown) {
+  const rawValues = Array.isArray(value)
+    ? value
+    : value && typeof value === "object"
+      ? Object.values(value).flatMap((item) =>
+          Array.isArray(item) ? item : [],
+        )
+      : [];
+  const refs = rawValues
+    .map((item) => (typeof item === "string" ? item.trim() : ""))
+    .filter(Boolean);
+  return Array.from(new Set(refs));
+}
+
+export function formatCvMarkerReference(id: string) {
+  return `[^${id}]`;
+}
+
+export function formatStoryReference(storyId: string, cvId?: string) {
+  return cvId ? `[^cv/${cvId}/stories/${storyId}]` : `[^stories/${storyId}]`;
+}
+
+export function formatTaskReference(jobId: string, taskId: string) {
+  return `[^tasks/${jobId}/${taskId}]`;
+}
+
+export function referenceAnchorId(value: string) {
+  const parsed = parseReferenceRef(value);
+  const target = parsed?.target ?? value;
+  const slug =
+    target
+      .trim()
+      .replace(/[^A-Za-z0-9_-]+/g, "-")
+      .replace(/^-+|-+$/g, "") || "reference";
+  return `cvstudio-reference-${slug}`;
+}
+
+export function markDuplicateReferenceTargets<T extends ReferenceTarget>(
+  references: T[],
+): ReferenceIndex<T> {
+  const byRef = new Map<string, T[]>();
+  for (const reference of references) {
+    byRef.set(reference.ref, [...(byRef.get(reference.ref) ?? []), reference]);
+  }
+  const duplicates = Object.fromEntries(
+    [...byRef.entries()].filter(([, items]) => items.length > 1),
+  ) as Record<string, T[]>;
+  for (const reference of references) {
+    reference.duplicate = Boolean(duplicates[reference.ref]);
+  }
+  return { references, duplicates };
+}
+
+export function duplicateReferenceCount(index: ReferenceIndex, value: string) {
+  const ref = normalizeReferenceRef(value);
+  return ref ? (index.duplicates[ref]?.length ?? 0) : 0;
+}
+
+export function resolveReferenceTarget<T extends ReferenceTarget>(
+  index: ReferenceIndex<T>,
+  value: string,
+) {
+  const ref = normalizeReferenceRef(value);
+  if (!ref) return null;
+  const matches = index.references.filter((reference) => reference.ref === ref);
+  return matches.length === 1 ? matches[0] : null;
+}

package/src/shared/forms/core/registry.ts

@@ -0,0 +1,101 @@
+import type {
+  FormFieldAlign,
+  FormFieldConfig,
+  FormFieldKind,
+  FormFieldRenderArgs,
+  FormFieldWrapper,
+  FormRendererDescriptor,
+  FormValidationIssue,
+  FormViewName,
+} from "./types";
+
+export function fieldIssuesFor<TRoot, TContext, TValue>(
+  issues: FormValidationIssue[],
+  field: Pick<FormFieldConfig<TRoot, TContext, TValue>, "id" | "path">,
+) {
+  return issues.filter((issue) => {
+    if (issue.fieldId && issue.fieldId === field.id) return true;
+    if (issue.path && field.path && issue.path === field.path) return true;
+    return false;
+  });
+}
+
+export function defaultFieldAlign(kind: FormFieldKind): FormFieldAlign {
+  if (
+    kind === "boolean" ||
+    kind === "color" ||
+    kind === "options" ||
+    kind === "segmented" ||
+    kind === "choice"
+  ) {
+    return "center";
+  }
+  if (kind === "textarea") return "start";
+  return "middle";
+}
+
+export function defaultFieldWrapper(kind: FormFieldKind): FormFieldWrapper {
+  return kind === "boolean" ||
+    kind === "color" ||
+    kind === "options" ||
+    kind === "segmented" ||
+    kind === "choice" ||
+    kind === "time" ||
+    kind === "tag-list" ||
+    kind === "chip-list" ||
+    kind === "string-list" ||
+    kind === "ordered-string-list" ||
+    kind === "reference-list" ||
+    kind === "custom"
+    ? "div"
+    : "label";
+}
+
+export function viewFallbacks(view: FormViewName, readonly: boolean) {
+  const fallbacks = [view];
+  if (readonly && view !== "readonly") fallbacks.push("readonly");
+  if (view !== "preview") fallbacks.push("preview");
+  if (view !== "edit" && !readonly) fallbacks.push("edit");
+  fallbacks.push("default");
+  return [...new Set(fallbacks)];
+}
+
+export function resolveFieldRenderer<TRoot, TContext, TValue>(
+  field: FormFieldConfig<TRoot, TContext, TValue>,
+  view: FormViewName,
+  readonly: boolean,
+): FormRendererDescriptor<TRoot, TContext, TValue> | null {
+  if (!field.renderers) return null;
+  for (const fallback of viewFallbacks(view, readonly)) {
+    const renderer = field.renderers[fallback];
+    if (renderer) return renderer;
+  }
+  return null;
+}
+
+export function formatFieldValue<TRoot, TContext, TValue>(
+  field: FormFieldConfig<TRoot, TContext, TValue>,
+  value: TValue,
+  root: TRoot,
+  context: TContext,
+) {
+  if (field.format) return field.format(value, root, context);
+  if (value === null || value === undefined || value === "") return "";
+  if (Array.isArray(value)) return value.filter(Boolean).join(", ");
+  if (typeof value === "boolean") return value ? "Yes" : "No";
+  return String(value);
+}
+
+export function rendererPropsFor<TRoot, TContext, TValue>(
+  descriptor: FormRendererDescriptor<TRoot, TContext, TValue>,
+  args: FormFieldRenderArgs<TRoot, TContext, TValue>,
+) {
+  const extra =
+    typeof descriptor.props === "function"
+      ? descriptor.props(args)
+      : descriptor.props;
+  return {
+    ...(extra ?? {}),
+    ...args,
+  };
+}

package/src/shared/forms/core/review-diff.ts

@@ -0,0 +1,199 @@
+/** A small, dependency-free diff model used by AI proposal review surfaces. */
+export type UnifiedDiffSegmentType = "equal" | "removed" | "added";
+
+export type UnifiedDiffSegment = {
+  type: UnifiedDiffSegmentType;
+  text: string;
+};
+
+export type UnifiedDiffLine = {
+  type: UnifiedDiffSegmentType;
+  text: string;
+  segments: UnifiedDiffSegment[];
+};
+
+export type UnifiedDiffPart = {
+  type: "equal" | "changed";
+  lines: UnifiedDiffLine[];
+};
+
+type DiffInput = string | readonly string[];
+type SequencePart = {
+  type: UnifiedDiffSegmentType;
+  values: string[];
+};
+
+const MAX_DIFF_MATRIX_CELLS = 250_000;
+
+function asLines(value: DiffInput) {
+  if (typeof value !== "string") return [...value];
+  return value ? value.split("\n") : [];
+}
+
+function pushSequencePart(
+  parts: SequencePart[],
+  type: UnifiedDiffSegmentType,
+  value: string,
+) {
+  const last = parts.at(-1);
+  if (last?.type === type) {
+    last.values.push(value);
+    return;
+  }
+  parts.push({ type, values: [value] });
+}
+
+function diffSequence(before: readonly string[], after: readonly string[]) {
+  if (before.length * after.length > MAX_DIFF_MATRIX_CELLS) {
+    const parts: SequencePart[] = [];
+    for (const value of before) pushSequencePart(parts, "removed", value);
+    for (const value of after) pushSequencePart(parts, "added", value);
+    return parts;
+  }
+
+  const table = Array.from({ length: before.length + 1 }, () =>
+    Array(after.length + 1).fill(0),
+  ) as number[][];
+  for (
+    let beforeIndex = before.length - 1;
+    beforeIndex >= 0;
+    beforeIndex -= 1
+  ) {
+    for (let afterIndex = after.length - 1; afterIndex >= 0; afterIndex -= 1) {
+      table[beforeIndex][afterIndex] =
+        before[beforeIndex] === after[afterIndex]
+          ? table[beforeIndex + 1][afterIndex + 1] + 1
+          : Math.max(
+              table[beforeIndex + 1][afterIndex],
+              table[beforeIndex][afterIndex + 1],
+            );
+    }
+  }
+
+  const parts: SequencePart[] = [];
+  let beforeIndex = 0;
+  let afterIndex = 0;
+  while (beforeIndex < before.length && afterIndex < after.length) {
+    if (before[beforeIndex] === after[afterIndex]) {
+      pushSequencePart(parts, "equal", after[afterIndex]);
+      beforeIndex += 1;
+      afterIndex += 1;
+    } else if (
+      table[beforeIndex + 1][afterIndex] >= table[beforeIndex][afterIndex + 1]
+    ) {
+      pushSequencePart(parts, "removed", before[beforeIndex]);
+      beforeIndex += 1;
+    } else {
+      pushSequencePart(parts, "added", after[afterIndex]);
+      afterIndex += 1;
+    }
+  }
+  while (beforeIndex < before.length) {
+    pushSequencePart(parts, "removed", before[beforeIndex]);
+    beforeIndex += 1;
+  }
+  while (afterIndex < after.length) {
+    pushSequencePart(parts, "added", after[afterIndex]);
+    afterIndex += 1;
+  }
+  return parts;
+}
+
+function wordSegments(before: string, after: string) {
+  const beforeWords = before.match(/\s+|[^\s]+/g) ?? [];
+  const afterWords = after.match(/\s+|[^\s]+/g) ?? [];
+  return diffSequence(beforeWords, afterWords).map((part) => ({
+    type: part.type,
+    text: part.values.join(""),
+  }));
+}
+
+function lineFromSegments(
+  type: UnifiedDiffSegmentType,
+  text: string,
+  segments: UnifiedDiffSegment[],
+): UnifiedDiffLine {
+  return { type, text, segments };
+}
+
+function enrichChangedLines(parts: SequencePart[]) {
+  const removed = parts
+    .filter((part) => part.type === "removed")
+    .flatMap((part) => part.values);
+  const added = parts
+    .filter((part) => part.type === "added")
+    .flatMap((part) => part.values);
+  const lines: UnifiedDiffLine[] = [];
+  const pairedLength = Math.min(removed.length, added.length);
+
+  for (let index = 0; index < pairedLength; index += 1) {
+    const before = removed[index];
+    const after = added[index];
+    const segments = wordSegments(before, after);
+    lines.push(
+      lineFromSegments(
+        "removed",
+        before,
+        segments
+          .filter((segment) => segment.type !== "added")
+          .map((segment) => ({
+            type: segment.type === "equal" ? "equal" : "removed",
+            text: segment.text,
+          })),
+      ),
+      lineFromSegments(
+        "added",
+        after,
+        segments
+          .filter((segment) => segment.type !== "removed")
+          .map((segment) => ({
+            type: segment.type === "equal" ? "equal" : "added",
+            text: segment.text,
+          })),
+      ),
+    );
+  }
+  for (const text of removed.slice(pairedLength)) {
+    lines.push(lineFromSegments("removed", text, [{ type: "removed", text }]));
+  }
+  for (const text of added.slice(pairedLength)) {
+    lines.push(lineFromSegments("added", text, [{ type: "added", text }]));
+  }
+  return lines;
+}
+
+/**
+ * Produces a unified, line-aware diff. Adjacent changed lines are paired and
+ * tokenised so replacement words remain visibly distinct from their context.
+ */
+export function unifiedDiff(
+  before: DiffInput,
+  after: DiffInput,
+): UnifiedDiffPart[] {
+  const parts = diffSequence(asLines(before), asLines(after));
+  const result: UnifiedDiffPart[] = [];
+  let partIndex = 0;
+
+  while (partIndex < parts.length) {
+    const part = parts[partIndex];
+    if (part.type === "equal") {
+      result.push({
+        type: "equal",
+        lines: part.values.map((text) =>
+          lineFromSegments("equal", text, [{ type: "equal", text }]),
+        ),
+      });
+      partIndex += 1;
+      continue;
+    }
+
+    const changedParts: SequencePart[] = [];
+    while (partIndex < parts.length && parts[partIndex].type !== "equal") {
+      changedParts.push(parts[partIndex]);
+      partIndex += 1;
+    }
+    const lines = enrichChangedLines(changedParts);
+    result.push({ type: "changed", lines });
+  }
+  return result;
+}

package/src/shared/forms/core/types.ts

@@ -0,0 +1,135 @@
+import type { Component } from "svelte";
+import type { HTMLInputAttributes } from "svelte/elements";
+import type { ColorPickerFormat } from "../color-picker/color-value";
+import type { CyclePickerPreview } from "../cycle-picker/CyclePicker.svelte";
+import type { InlineOptionPickerOption } from "../inline-option-picker/InlineOptionPicker.svelte";
+import type { ReferenceIndex } from "./reference-utils";
+import type { RegisteredFormFieldKind } from "./path-config";
+import type { FieldPath } from "./path-types";
+
+export type FormViewName = "edit" | "preview" | "readonly" | (string & {});
+
+export type FormFieldKind = RegisteredFormFieldKind;
+
+/** `middle` = vertically center label with control; `start` = top (multiline); `center` = pill controls. */
+export type FormFieldAlign = "start" | "center" | "middle";
+export type FormFieldWrapper = "label" | "div";
+
+export type FormValidationIssue<TValues = unknown> = {
+  fieldId?: string;
+  path?: TValues extends object ? FieldPath<TValues> : string;
+  message: string;
+  severity?: "error" | "warning" | "info";
+};
+
+export type FormFieldRenderArgs<TRoot, TContext, TValue> = {
+  root: TRoot;
+  value: TValue;
+  field: FormFieldConfig<TRoot, TContext, TValue>;
+  view: FormViewName;
+  context: TContext;
+  issues: FormValidationIssue[];
+  readonly: boolean;
+  update: (value: TValue) => void | Promise<void>;
+  updateRoot: (value: TRoot) => void | Promise<void>;
+};
+
+export type FormRendererProps<TRoot, TContext, TValue> = FormFieldRenderArgs<
+  TRoot,
+  TContext,
+  TValue
+> &
+  Record<string, unknown>;
+
+export type FormCustomRenderer<TRoot, TContext, TValue> = Component<
+  FormRendererProps<TRoot, TContext, TValue>
+>;
+
+export type FormRendererDescriptor<TRoot, TContext, TValue> = {
+  component: FormCustomRenderer<TRoot, TContext, TValue>;
+  wrapper?: "field" | "none";
+  interactive?: boolean;
+  align?: FormFieldAlign;
+  as?: FormFieldWrapper;
+  props?:
+    | Record<string, unknown>
+    | ((
+        args: FormFieldRenderArgs<TRoot, TContext, TValue>,
+      ) => Record<string, unknown>);
+};
+
+export type FormRendererMap<TRoot, TContext, TValue> = Partial<
+  Record<
+    FormViewName | "default",
+    FormRendererDescriptor<TRoot, TContext, TValue>
+  >
+>;
+
+export type FormFieldOptionsSource<TRoot, TContext, TValue> =
+  | InlineOptionPickerOption[]
+  | ((
+      args: Pick<
+        FormFieldRenderArgs<TRoot, TContext, TValue>,
+        "root" | "value" | "field" | "context"
+      >,
+    ) => InlineOptionPickerOption[]);
+
+export type FormFieldStringSource<TRoot, TContext, TValue> =
+  | string[]
+  | ((
+      args: Pick<
+        FormFieldRenderArgs<TRoot, TContext, TValue>,
+        "root" | "value" | "field" | "context"
+      >,
+    ) => string[]);
+
+export type FormFieldReferenceIndexSource<TRoot, TContext, TValue> =
+  | ReferenceIndex
+  | ((
+      args: Pick<
+        FormFieldRenderArgs<TRoot, TContext, TValue>,
+        "root" | "value" | "field" | "context"
+      >,
+    ) => ReferenceIndex);
+
+export type FormFieldConfig<TRoot, TContext = undefined, TValue = unknown> = {
+  id: string;
+  label: string;
+  kind: FormFieldKind;
+  path?: string;
+  description?: string;
+  placeholder?: string;
+  ariaLabel?: string;
+  align?: FormFieldAlign;
+  as?: FormFieldWrapper;
+  inputType?: string;
+  autocomplete?: HTMLInputAttributes["autocomplete"];
+  presentation?: "menu" | "swap" | "cycle";
+  optionPreview?: CyclePickerPreview;
+  colorFormat?: ColorPickerFormat;
+  rows?: number;
+  readonly?: boolean;
+  get: (root: TRoot, context: TContext) => TValue;
+  set?: (root: TRoot, value: TValue, context: TContext) => TRoot;
+  format?: (value: TValue, root: TRoot, context: TContext) => string;
+  options?: FormFieldOptionsSource<TRoot, TContext, TValue>;
+  suggestions?: FormFieldStringSource<TRoot, TContext, TValue>;
+  referenceIndex?: FormFieldReferenceIndexSource<TRoot, TContext, TValue>;
+  addLabel?: string;
+  addHeading?: string;
+  searchPlaceholder?: string;
+  renderers?: FormRendererMap<TRoot, TContext, TValue>;
+};
+
+export type FormConfig<TRoot, TContext = undefined> = {
+  id: string;
+  fields: Array<FormFieldConfig<TRoot, TContext, any>>;
+  defaultView?: FormViewName;
+};
+
+export type YamlBackedFormConfig<TRoot, TContext = undefined> = FormConfig<
+  TRoot,
+  TContext
+> & {
+  yamlLabel?: string;
+};