DifferenceModal

<caos-difference-modal>

one item’s two versions side by side, with the comparison engine behind a seam

May be placed on a page inside an app and a record page.

Inputs

Name	Attribute	Description	Type	Default	Required
`item`	`item`, markup only	What is being compared — shown as the heading and named in the “not in …” sentence.	text	none declared	Optional
`sourceText`	property only	The source side’s text.	text	none declared	Optional
`targetText`	property only	The target side’s text.	text	none declared	Optional
`sourceName`	`source-name`, markup only	What to call the source side.	text	Source	Optional
`targetName`	`target-name`, markup only	What to call the target side.	text	Target	Optional
`missing`	`missing`, markup only	The side the item is NOT on. One column is then drawn, and the other is replaced by a sentence — an empty column would claim the other side has a blank version of it.	text — recognises source, target; anything else reads as `both sides, when the attribute is absent or is neither word`	none declared	Optional
`closable`	`closable`, markup only	Show a close control. Off by default, for a difference shown in place rather than over something.	boolean	false	Optional

Events

Name	When it fires	What it carries
`caos-difference-close`	The close control is pressed.	nothing

Slots

Not documented yet — this piece has not said.

Styling hooks

Not documented yet — this piece has not said.

Methods

Not documented yet — this piece has not said.

Readable state

Name	Type	What it tells you
`rows`	DiffRow[]	The comparison as the installed engine produced it. Empty for a one-sided item.
`tally`	{ added, removed, equal }	Computed FROM the rows, so the line at the top cannot disagree with the lines under it.
`identical`	boolean	Whether the two sides match. A one-sided item is not identical — it is one-sided.
`engine`	string	The name of the installed comparison engine.

Styling parts

Part	Which piece of it	When it is there
`::part(difference)`	The outer column.	Always
`::part(header)`	The heading row.	Always
`::part(title)`	The item’s name.	Always
`::part(tally)`	The added/removed line, or the “only in …” / “identical” statement.	Always
`::part(close)`	The close control.	`closable` is set.
`::part(sides)`	The two-column area.	Always
`::part(side)`	One side.	Always
`::part(side-name)`	A side’s heading.	Always
`::part(rows)`	A side’s scrolling lines.	That side has content.
`::part(row)`	One line.	Always
`::part(gutter)`	A line’s number.	Always
`::part(text)`	A line’s text.	Always
`::part(absent)`	The “not in …” sentence.	The item is on only one side.

When to use it

When one item has been chosen out of a comparison and the question is HOW it differs.

What to use instead

CompareView — the question is WHICH items differ rather than how one of them does.
CodeEditor — the text is being edited rather than compared.

Accessibility

Added and removed lines carry an aria-label naming what happened to them, so the change is spoken rather than conveyed only by the tint. The spacer rows that keep the two columns in step are aria-hidden, so a screen reader is not read a column of blanks. The tally is a role="status" live region, and for the two cases with no rows to read it states the answer in words — “Only in Target”, “The two versions are identical” — rather than leaving somebody to infer it from an absence.

Examples

Two versions that differ

Side by side, with spacer rows keeping the columns in step — without them the sides drift apart by one line per change and after four changes nothing lines up.

{
  "id": "example",
  "section": "Two versions that differ",
  "columns": 1,
  "items": [
    {
      "id": "difference_modal_1",
      "type": "component",
      "key": "difference_modal",
      "inputs": {
        "item": "BillingService",
        "source_name": "UAT",
        "target_name": "Production",
        "source_text": "public class BillingService {\n  private static final Integer SCALE = 2;\n  public static Decimal round(Decimal v) {\n    return v.setScale(SCALE);\n  }\n}",
        "target_text": "public class BillingService {\n  private static final Integer SCALE = 4;\n  public static Decimal round(Decimal v) {\n    if (v == null) return null;\n    return v.setScale(SCALE);\n  }\n}"
      }
    }
  ]
}

<caos-difference-modal item="BillingService" source-name="UAT" target-name="Production" source-text="public class BillingService {
  private static final Integer SCALE = 2;
  public static Decimal round(Decimal v) {
    return v.setScale(SCALE);
  }
}" target-text="public class BillingService {
  private static final Integer SCALE = 4;
  public static Decimal round(Decimal v) {
    if (v == null) return null;
    return v.setScale(SCALE);
  }
}"></caos-difference-modal>

An item on only one side

One column and a sentence. An empty second column would say the other side has a blank version of it, which is a different and wronger fact.

{
  "id": "example",
  "section": "An item on only one side",
  "columns": 1,
  "items": [
    {
      "id": "difference_modal_1",
      "type": "component",
      "key": "difference_modal",
      "inputs": {
        "item": "LegacyImporter",
        "source_name": "UAT",
        "target_name": "Production",
        "missing": "target",
        "source_text": "public class LegacyImporter {\n  // retired, but still in UAT\n}"
      }
    }
  ]
}

<caos-difference-modal item="LegacyImporter" source-name="UAT" target-name="Production" missing="target" source-text="public class LegacyImporter {
  // retired, but still in UAT
}"></caos-difference-modal>

Two versions that match

Said, rather than drawn as two columns with nothing highlighted — which leaves somebody hunting for a change that is not there.

{
  "id": "example",
  "section": "Two versions that match",
  "columns": 1,
  "items": [
    {
      "id": "difference_modal_1",
      "type": "component",
      "key": "difference_modal",
      "inputs": {
        "item": "QuoteCalculator",
        "source_name": "UAT",
        "target_name": "Production",
        "source_text": "public class QuoteCalculator {\n  // unchanged\n}",
        "target_text": "public class QuoteCalculator {\n  // unchanged\n}"
      }
    }
  ]
}

<caos-difference-modal item="QuoteCalculator" source-name="UAT" target-name="Production" source-text="public class QuoteCalculator {
  // unchanged
}" target-text="public class QuoteCalculator {
  // unchanged
}"></caos-difference-modal>