@keboola/design 1.0.0

package/src/components/MergeEditor/MergeEditor.stories.tsx

@@ -0,0 +1,211 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import { ConflictStatusIndicator } from './ConflictStatus/ConflictStatusIndicator';
+import { MergeEditor } from './MergeEditor';
+import { PaneHeader } from './PaneHeader';
+import { useMergeDiff } from './useMergeDiff';
+
+const baseText = `{
+  "name": "My Configuration",
+  "description": "Extracts data from API",
+  "configuration": {
+    "endpoint": "/api/v1/data",
+    "method": "GET",
+    "timeout": 30
+  },
+  "rows": [
+    {
+      "id": "row-1",
+      "name": "Users",
+      "enabled": true
+    },
+    {
+      "id": "row-2",
+      "name": "Orders",
+      "enabled": true
+    }
+  ]
+}`;
+
+const productionText = `{
+  "name": "My Configuration",
+  "description": "Extracts data from REST API",
+  "configuration": {
+    "endpoint": "/api/v2/data",
+    "method": "GET",
+    "timeout": 60,
+    "retries": 3
+  },
+  "rows": [
+    {
+      "id": "row-1",
+      "name": "Users",
+      "enabled": true
+    },
+    {
+      "id": "row-2",
+      "name": "Orders",
+      "enabled": false
+    }
+  ]
+}`;
+
+const branchText = `{
+  "name": "My Updated Configuration",
+  "description": "Extracts data from API",
+  "configuration": {
+    "endpoint": "/api/v1/data",
+    "method": "POST",
+    "timeout": 30,
+    "headers": {
+      "Content-Type": "application/json"
+    }
+  },
+  "rows": [
+    {
+      "id": "row-1",
+      "name": "Active Users",
+      "enabled": true
+    },
+    {
+      "id": "row-2",
+      "name": "Orders",
+      "enabled": true
+    },
+    {
+      "id": "row-3",
+      "name": "Products",
+      "enabled": true
+    }
+  ]
+}`;
+
+type MergeEditorHookProps = {
+  base: string;
+  left: string;
+  right: string;
+  leftLabel?: string;
+  rightLabel?: string;
+};
+
+const MergeEditorWithHook = ({
+  base = baseText,
+  left = productionText,
+  right = branchText,
+  leftLabel = 'Production',
+  rightLabel = 'Branch',
+}: Partial<MergeEditorHookProps>) => {
+  const {
+    mergeValue,
+    handleMergeChange,
+    leftConflicts,
+    rightConflicts,
+    leftHighlightedLines,
+    rightHighlightedLines,
+    leftClassification,
+    rightClassification,
+    mergeHighlightedLines,
+    mergeClassification,
+    acceptLeft,
+    acceptRight,
+    dismissLeft,
+    dismissRight,
+    totalConflicts,
+    resolvedConflicts,
+    remainingSafeChanges,
+  } = useMergeDiff(base, left, right);
+
+  const remaining = totalConflicts - resolvedConflicts;
+
+  return (
+    <div className="tw-flex tw-h-[600px] tw-flex-col tw-gap-4">
+      <div className="tw-flex tw-items-center tw-gap-4">
+        <ConflictStatusIndicator
+          remainingConflicts={remaining}
+          remainingSafeChanges={remainingSafeChanges}
+        />
+      </div>
+      <MergeEditor
+        mergeValue={mergeValue}
+        handleMergeChange={handleMergeChange}
+        leftText={left}
+        rightText={right}
+        leftConflicts={leftConflicts}
+        rightConflicts={rightConflicts}
+        leftHighlightedLines={leftHighlightedLines}
+        rightHighlightedLines={rightHighlightedLines}
+        leftClassification={leftClassification}
+        rightClassification={rightClassification}
+        mergeHighlightedLines={mergeHighlightedLines}
+        mergeClassification={mergeClassification}
+        acceptLeft={acceptLeft}
+        acceptRight={acceptRight}
+        dismissLeft={dismissLeft}
+        dismissRight={dismissRight}
+        leftHeader={<PaneHeader label={leftLabel} sublabel="Version #5" />}
+        middleHeader={<PaneHeader label="Merge Result" sublabel="Editable" />}
+        middleHeaderClassName="tw-bg-secondary-100"
+        middleClassName="tw-border-blue-400"
+        rightHeader={<PaneHeader label={rightLabel} sublabel="Version #3" />}
+        className="tw-flex-1"
+      />
+    </div>
+  );
+};
+
+const meta: Meta<typeof MergeEditor> = {
+  component: MergeEditor,
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: {
+        component:
+          'Three-pane merge editor for resolving conflicts between two versions of a text. Left pane shows the production version, right pane shows the branch version, and the center pane is the editable merge result. Use `useMergeDiff` hook to compute all diff state from base/production/branch texts.',
+      },
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof MergeEditor>;
+
+export const WithConflicts: Story = {
+  render: () => <MergeEditorWithHook />,
+};
+
+// Both sides independently add new rows to the same JSON region. diff3Merge
+// classifies the affected lines as CONFLICT, so they render with amber (not red)
+// highlighting — this verifies the visual fix for "everything looks red even when
+// nothing was deleted" reported on canary-orion.
+const baseTextForRowAdditions = `{
+  "name": "Configuration",
+  "rows": [
+    { "id": "row-1", "name": "Users" }
+  ]
+}`;
+
+const productionTextWithAddedRow = `{
+  "name": "Configuration",
+  "rows": [
+    { "id": "row-1", "name": "Users" },
+    { "id": "row-prod", "name": "Production-only row" }
+  ]
+}`;
+
+const branchTextWithAddedRow = `{
+  "name": "Configuration",
+  "rows": [
+    { "id": "row-1", "name": "Users" },
+    { "id": "row-branch", "name": "Branch-only row" }
+  ]
+}`;
+
+export const BothSidesAddRows: Story = {
+  render: () => (
+    <MergeEditorWithHook
+      base={baseTextForRowAdditions}
+      left={productionTextWithAddedRow}
+      right={branchTextWithAddedRow}
+    />
+  ),
+};

package/src/components/MergeEditor/MergeEditor.tsx

@@ -0,0 +1,116 @@
+import type { ReactNode } from 'react';
+
+import { cn } from '../../utils';
+
+import { AcceptControls } from './AcceptControls/AcceptControls';
+import type { ChangeClassification, MergeConflict } from './constants';
+import { MergePane } from './MergePane';
+import { useScrollSync } from './useScrollSync';
+
+type Props = {
+  mergeValue: string;
+  handleMergeChange: (value: string) => void;
+  leftText: string;
+  rightText: string;
+  leftConflicts: MergeConflict[];
+  rightConflicts: MergeConflict[];
+  leftHighlightedLines: Set<number>;
+  rightHighlightedLines: Set<number>;
+  leftClassification: Map<number, ChangeClassification>;
+  rightClassification: Map<number, ChangeClassification>;
+  mergeHighlightedLines: Set<number>;
+  mergeClassification: Map<number, ChangeClassification>;
+  acceptLeft: (conflict: MergeConflict) => void;
+  acceptRight: (conflict: MergeConflict) => void;
+  dismissLeft: (conflict: MergeConflict) => void;
+  dismissRight: (conflict: MergeConflict) => void;
+  leftHeader?: ReactNode;
+  middleHeader?: ReactNode;
+  middleHeaderClassName?: string;
+  middleClassName?: string;
+  rightHeader?: ReactNode;
+  className?: string;
+};
+
+export const MergeEditor = ({
+  mergeValue,
+  handleMergeChange,
+  leftText,
+  rightText,
+  leftConflicts,
+  rightConflicts,
+  leftHighlightedLines,
+  rightHighlightedLines,
+  leftClassification,
+  rightClassification,
+  mergeHighlightedLines,
+  mergeClassification,
+  acceptLeft,
+  acceptRight,
+  dismissLeft,
+  dismissRight,
+  leftHeader,
+  middleHeader,
+  middleHeaderClassName,
+  middleClassName,
+  rightHeader,
+  className,
+}: Props) => {
+  const { registerScroller, registerFollower } = useScrollSync();
+
+  return (
+    <div
+      className={cn(
+        'tw-flex tw-h-full tw-min-h-0 tw-overflow-hidden tw-bg-white tw-gap-3',
+        className,
+      )}
+    >
+      <MergePane
+        value={leftText}
+        highlightedLines={leftHighlightedLines}
+        lineClassification={leftClassification}
+        readOnly
+        header={leftHeader}
+        className="tw-rounded-r-lg tw-border tw-border-neutral-200"
+        onScrollDOMReady={registerScroller(0)}
+      />
+
+      <AcceptControls
+        conflicts={leftConflicts}
+        side="left"
+        onAccept={acceptLeft}
+        onDismiss={dismissLeft}
+        contentRef={registerFollower(0, 'left-controls')}
+      />
+
+      <MergePane
+        value={mergeValue}
+        highlightedLines={mergeHighlightedLines}
+        lineClassification={mergeClassification}
+        onChange={handleMergeChange}
+        header={middleHeader}
+        headerClassName={middleHeaderClassName}
+        className={cn('tw-border tw-border-neutral-200 tw-rounded-lg', middleClassName)}
+        onScrollDOMReady={registerScroller(1)}
+      />
+
+      <AcceptControls
+        conflicts={rightConflicts}
+        side="right"
+        onAccept={acceptRight}
+        onDismiss={dismissRight}
+        contentRef={registerFollower(2, 'right-controls')}
+      />
+
+      <MergePane
+        value={rightText}
+        highlightedLines={rightHighlightedLines}
+        lineClassification={rightClassification}
+        readOnly
+        header={rightHeader}
+        className="tw-rounded-l-lg tw-border tw-border-neutral-200"
+        onScrollDOMReady={registerScroller(2)}
+      />
+    </div>
+  );
+};

package/src/components/MergeEditor/MergePane.tsx

@@ -0,0 +1,95 @@
+import { type ReactNode, useCallback, useEffect, useMemo, useRef } from 'react';
+import { type Extension } from '@codemirror/state';
+import { EditorView } from '@codemirror/view';
+import CodeMirror, { type ReactCodeMirrorRef } from '@uiw/react-codemirror';
+
+import colors from '@keboola/tailwind-config/colors';
+
+import { cn } from '../../utils';
+
+import { type ChangeClassification, LINE_HEIGHT_PX } from './constants';
+import { createDiffHighlightExtension, updateHighlightedLines } from './decorations';
+
+type Props = {
+  value: string;
+  highlightedLines: Set<number>;
+  lineClassification: Map<number, ChangeClassification>;
+  readOnly?: boolean;
+  onChange?: (value: string) => void;
+  header?: ReactNode;
+  headerClassName?: string;
+  className?: string;
+  onScrollDOMReady?: (el: HTMLElement | null) => void;
+};
+
+export const MergePane = ({
+  value,
+  highlightedLines,
+  lineClassification,
+  readOnly = false,
+  onChange,
+  header,
+  headerClassName,
+  className,
+  onScrollDOMReady,
+}: Props) => {
+  const editorRef = useRef<ReactCodeMirrorRef>(null);
+
+  const extensions = useMemo(
+    (): Extension[] => [
+      createDiffHighlightExtension(),
+      EditorView.theme({
+        '&.cm-editor': {
+          height: '100%',
+          backgroundColor: colors.neutral[50],
+          outline: 'none',
+        },
+        '&.cm-editor .cm-scroller': {
+          alignItems: 'stretch !important',
+        },
+        '.cm-gutters': {
+          backgroundColor: colors.neutral[100],
+        },
+        '*': { lineHeight: `${LINE_HEIGHT_PX}px` },
+        '.cm-lineNumbers .cm-gutterElement': { padding: '0 0 0 25px' },
+      }),
+    ],
+    [],
+  );
+
+  useEffect(() => {
+    const view = editorRef.current?.view;
+    if (view) {
+      updateHighlightedLines(view, highlightedLines, lineClassification);
+    }
+  }, [highlightedLines, lineClassification]);
+
+  const handleCreateEditor = useCallback(
+    (view: EditorView) => {
+      updateHighlightedLines(view, highlightedLines, lineClassification);
+      onScrollDOMReady?.(view.scrollDOM);
+    },
+    [highlightedLines, lineClassification, onScrollDOMReady],
+  );
+
+  useEffect(() => {
+    return () => onScrollDOMReady?.(null);
+  }, [onScrollDOMReady]);
+
+  return (
+    <div className={cn('tw-flex tw-min-w-0 tw-flex-1 tw-flex-col tw-overflow-hidden', className)}>
+      {header && <div className={cn('tw-bg-white tw-px-4 tw-py-3', headerClassName)}>{header}</div>}
+      <div className="tw-flex tw-h-0 tw-flex-1 tw-flex-col [&_>div]:tw-h-full [&_>div]:tw-overflow-auto">
+        <CodeMirror
+          ref={editorRef}
+          value={value}
+          onChange={onChange}
+          extensions={extensions}
+          readOnly={readOnly}
+          onCreateEditor={handleCreateEditor}
+          basicSetup={{ lineNumbers: true, drawSelection: false }}
+        />
+      </div>
+    </div>
+  );
+};

package/src/components/MergeEditor/PaneHeader.tsx

@@ -0,0 +1,11 @@
+type Props = {
+  label: string;
+  sublabel?: string;
+};
+
+export const PaneHeader = ({ label, sublabel }: Props) => (
+  <div>
+    <p className="tw-m-0 tw-text-sm tw-font-medium tw-text-neutral-900">{label}</p>
+    {sublabel && <p className="tw-m-0 tw-text-xs tw-text-neutral-400">{sublabel}</p>}
+  </div>
+);

package/src/components/MergeEditor/constants.ts

@@ -0,0 +1,48 @@
+export const CHUNK_TYPE = {
+  UNCHANGED: 'unchanged',
+  ADDED: 'added',
+  REMOVED: 'removed',
+} as const;
+
+type ChunkType = (typeof CHUNK_TYPE)[keyof typeof CHUNK_TYPE];
+
+export type DiffChunk = {
+  type: ChunkType;
+  value: string;
+  /** 1-indexed start line in the old (left) text */
+  oldStart: number;
+  /** 1-indexed end line in the old (left) text */
+  oldEnd: number;
+  /** 1-indexed start line in the new (right) text */
+  newStart: number;
+  /** 1-indexed end line in the new (right) text */
+  newEnd: number;
+};
+
+/**
+ * A paired conflict: adjacent REMOVED + ADDED chunks from diffLines,
+ * representing a section that was modified. If only one side exists,
+ * the other is empty (pure insertion or deletion).
+ */
+export type MergeConflict = {
+  id: string;
+  oldValue: string;
+  oldStartLine: number;
+  oldEndLine: number;
+  newValue: string;
+  newStartLine: number;
+  newEndLine: number;
+};
+
+export const CHANGE_CLASS = {
+  SAFE: 'safe',
+  CONFLICT: 'conflict',
+} as const;
+
+export type ChangeClassification = (typeof CHANGE_CLASS)[keyof typeof CHANGE_CLASS];
+
+/** Must match the CodeMirror line-height set in MergePane */
+export const LINE_HEIGHT_PX = 20;
+
+/** Must match the rendered header height in MergePane (py-3 + content + border) */
+export const PANE_HEADER_HEIGHT_PX = 58;

package/src/components/MergeEditor/decorations.ts

@@ -0,0 +1,126 @@
+import {
+  type Extension,
+  RangeSet,
+  RangeSetBuilder,
+  StateEffect,
+  StateField,
+} from '@codemirror/state';
+import {
+  Decoration,
+  type DecorationSet,
+  EditorView,
+  gutterLineClass,
+  GutterMarker,
+} from '@codemirror/view';
+
+import colors from '@keboola/tailwind-config/colors';
+
+import type { ChangeClassification } from './constants';
+import { CHANGE_CLASS } from './constants';
+
+type HighlightPayload = {
+  lines: Set<number>;
+  classification: Map<number, ChangeClassification>;
+};
+
+const setHighlightedLines = StateEffect.define<HighlightPayload>();
+
+const safeDecoration = Decoration.line({ class: 'cm-merge-safe-line' });
+const conflictDecoration = Decoration.line({ class: 'cm-merge-conflict-line' });
+
+class SafeGutterMarker extends GutterMarker {
+  elementClass = 'cm-merge-safe-gutter';
+}
+
+class ConflictGutterMarker extends GutterMarker {
+  elementClass = 'cm-merge-conflict-gutter';
+}
+
+const safeGutterMarker = new SafeGutterMarker();
+const conflictGutterMarker = new ConflictGutterMarker();
+
+type FieldValue = {
+  decorations: DecorationSet;
+  gutterMarkers: RangeSet<GutterMarker>;
+};
+
+export const createDiffHighlightExtension = (): Extension => {
+  const field = StateField.define<FieldValue>({
+    create: () => ({ decorations: Decoration.none, gutterMarkers: RangeSet.empty }),
+    update(value, tr) {
+      // Use the last effect if multiple are dispatched in a single transaction
+      let payload: HighlightPayload | null = null;
+      for (const effect of tr.effects) {
+        if (effect.is(setHighlightedLines)) {
+          payload = effect.value;
+        }
+      }
+
+      if (!payload) {
+        return {
+          decorations: value.decorations.map(tr.changes),
+          gutterMarkers: value.gutterMarkers.map(tr.changes),
+        };
+      }
+
+      const decoBuilder = new RangeSetBuilder<Decoration>();
+      const gutterBuilder = new RangeSetBuilder<GutterMarker>();
+      const doc = tr.state.doc;
+      const { lines, classification } = payload;
+
+      // Iterate the (typically small) highlighted set instead of all doc lines.
+      // RangeSetBuilder requires positions in order, so sort first.
+      const sorted = [...lines].filter((l) => l >= 1 && l <= doc.lines).sort((a, b) => a - b);
+      for (const i of sorted) {
+        const cls = classification.get(i);
+        if (!cls) continue;
+
+        const isSafe = cls === CHANGE_CLASS.SAFE;
+        const line = doc.line(i);
+        decoBuilder.add(line.from, line.from, isSafe ? safeDecoration : conflictDecoration);
+        gutterBuilder.add(line.from, line.from, isSafe ? safeGutterMarker : conflictGutterMarker);
+      }
+
+      return {
+        decorations: decoBuilder.finish(),
+        gutterMarkers: gutterBuilder.finish(),
+      };
+    },
+    provide: (f) => [
+      EditorView.decorations.from(f, (val) => val.decorations),
+      gutterLineClass.from(f, (val: FieldValue) => val.gutterMarkers),
+    ],
+  });
+
+  // !important needed to override CodeMirror's built-in active-line and selection backgrounds.
+  // SAFE = change present on one side only (green). CONFLICT = both sides edited this region
+  // (amber/warning — NOT red, since red reads as "deletion" and the 3-pane editor only ever
+  // displays additions in each side pane). The colored left border doubles as a scan-lane so
+  // changes are easy to spot when zoomed out.
+  const theme = EditorView.theme({
+    '.cm-merge-safe-line': {
+      backgroundColor: `${colors.primary[100]} !important`,
+      boxShadow: `inset 3px 0 0 ${colors.primary[500]}`,
+    },
+    '.cm-merge-conflict-line': {
+      backgroundColor: `${colors.warning[100]} !important`,
+      boxShadow: `inset 3px 0 0 ${colors.warning[500]}`,
+    },
+    '.cm-merge-safe-gutter': {
+      backgroundColor: `${colors.primary[200]} !important`,
+    },
+    '.cm-merge-conflict-gutter': {
+      backgroundColor: `${colors.warning[200]} !important`,
+    },
+  });
+
+  return [field, theme];
+};
+
+export const updateHighlightedLines = (
+  view: EditorView,
+  lines: Set<number>,
+  classification: Map<number, ChangeClassification>,
+) => {
+  view.dispatch({ effects: setHighlightedLines.of({ lines, classification }) });
+};