Bridge — Let two things change

01 / The idea

A chart should not need to know its pixels.

A function that ranks ticket categories and returns a small SVG string is a reasonable first implementation. Its data rules and its geometry live together because there is only one thing to draw.

Now add a text version for the digest, then a weekly trend. Separate functions for each pairing can repeat the ranking in two places and the escaping in two others. A change to how many categories count as “top” can drift between the dashboard and the digest. The pressure comes from two kinds of change crossing the same code.

Bridge separates a higher-level abstraction from the implementation it uses, so the two can vary independently. Here, each chart composes meaningful rows through a surface interface. Each surface turns those operations into one kind of drawing. The caller connects a chart to a surface.

The traditional names are abstraction for the chart side and implementor for the surface side. Both sides contain real implementation code. These names describe their relationship: the chart expresses higher-level behavior using a smaller set of drawing operations.

02 / See the shape

The chart decides. The surface draws.

The Basic form retains a surface and delegates a title and figure operation to it. It shows the connection before adding data rules or validation.

In the wild is a dashboard chart. TopCategories validates points, ranks them by value, and shows three bars unless asked for every category. WeeklyTrend validates weeks, keeps their order, and notes the change from first to last. Neither branches on SVG versus text.

Responsibilities in the chart
Decision	Owner	Reason
Which categories appear, in what order?	TopCategories	The answer should agree across surfaces.
What does the trend note say?	WeeklyTrend	The change from first to last week is part of the chart’s meaning.
How long is a bar?	The selected surface	Two hundred SVG units and twenty block characters are different drawings of the same ratio.
Which pair is requested?	The caller	It supplies a surface to the chosen chart.

Read in

Compare with

A chart retains a surface and builds a figure through its operations. This small form shows the connection; the next form adds two chart policies, two surfaces, and validation.

TypeScriptReading

chart.ts

export interface Surface {
	title(text: string): string;
	bar(row: number, label: string, value: number, max: number): string;
	note(row: number, text: string): string;
	figure(parts: readonly string[], rows: number): string;
}
export class BasicChart {
	#surface: Surface;
	constructor(surface: Surface) {
		this.#surface = surface;
	}
	draw(title: string): string {
		return this.#surface.figure([this.#surface.title(`Top categories — ${title}`)], 0);
	}
}

GoAlongside

chart.go

type Surface interface {
	Title(text string) string
	Bar(row int, label string, value, maxValue int) string
	Note(row int, text string) string
	Figure(parts []string, rows int) string
}
type BasicChart struct{ surface Surface }

func (c BasicChart) Draw(title string) string {
	return c.surface.Figure([]string{c.surface.Title("Top categories — " + title)}, 0)
}

Read the complete sources without JavaScript

TypeScript source

chart.ts

export type Point = { label: string; value: number };
export type ChartData = {
	title: string;
	categories: readonly Point[];
	weeks: readonly Point[];
};
export type ChartKind = 'top' | 'trend';
export type SurfaceKind = 'svg' | 'text';

export interface Surface {
	title(text: string): string;
	bar(row: number, label: string, value: number, max: number): string;
	note(row: number, text: string): string;
	figure(parts: readonly string[], rows: number): string;
}
export class BasicChart {
	#surface: Surface;
	constructor(surface: Surface) {
		this.#surface = surface;
	}
	draw(title: string): string {
		return this.#surface.figure([this.#surface.title(`Top categories — ${title}`)], 0);
	}
}

function escapeText(text: string): string {
	return text
		.replace(/&/g, '&amp;')
		.replace(/</g, '&lt;')
		.replace(/>/g, '&gt;')
		.replace(/"/g, '&quot;')
		.replace(/'/g, '&#39;');
}
function scaled(value: number, max: number, width: number): number {
	return max > 0 ? Math.floor((value * width) / max) : 0;
}
export class SvgSurface implements Surface {
	title(text: string): string {
		return `<text x="0" y="16" class="title">${escapeText(text)}</text>`;
	}
	bar(row: number, label: string, value: number, max: number): string {
		const width = scaled(value, max, 200);
		return `<g transform="translate(0 ${32 + row * 24})"><text x="0" y="12">${escapeText(label)}</text><rect x="100" y="0" width="${width}" height="16"/><text x="${104 + width}" y="12">${value}</text></g>`;
	}
	note(row: number, text: string): string {
		return `<text x="0" y="${44 + row * 24}" class="note">${escapeText(text)}</text>`;
	}
	figure(parts: readonly string[], rows: number): string {
		return `<svg viewBox="0 0 320 ${48 + rows * 24}" role="img">${parts.join('')}</svg>`;
	}
}
export class TextSurface implements Surface {
	title(text: string): string {
		return text;
	}
	bar(row: number, label: string, value: number, max: number): string {
		void row;
		return `${label}: ${'█'.repeat(scaled(value, max, 20))} ${value}`;
	}
	note(row: number, text: string): string {
		void row;
		return text;
	}
	figure(parts: readonly string[], rows: number): string {
		void rows;
		return parts.join('\n');
	}
}
function singleLine(text: string): boolean {
	return text.length > 0 && !text.includes('\n') && !text.includes('\r');
}
function validPoint(point: Point): boolean {
	return singleLine(point.label) && Number.isInteger(point.value) && point.value >= 0;
}
export interface Chart {
	draw(data: ChartData): string;
}
export class TopCategories implements Chart {
	#surface: Surface;
	#showAll: boolean;
	constructor(surface: Surface, showAll = false) {
		this.#surface = surface;
		this.#showAll = showAll;
	}
	draw(data: ChartData): string {
		if (!singleLine(data.title)) throw new Error('invalid-title');
		if (!data.categories.every(validPoint)) throw new Error('invalid-category');
		const ranked = [...data.categories].sort((a, b) => b.value - a.value);
		const shown = this.#showAll ? ranked : ranked.slice(0, 3);
		const max = shown[0]?.value ?? 0;
		const s = this.#surface;
		const parts = [s.title(`Top categories — ${data.title}`)];
		shown.forEach((point, row) => parts.push(s.bar(row, point.label, point.value, max)));
		const total = data.categories.length;
		parts.push(
			s.note(
				shown.length,
				total === 0
					? 'No categories to show.'
					: `${shown.length} of ${total} categor${total === 1 ? 'y' : 'ies'} shown.`
			)
		);
		return s.figure(parts, shown.length + 1);
	}
}
export class WeeklyTrend implements Chart {
	#surface: Surface;
	constructor(surface: Surface) {
		this.#surface = surface;
	}
	draw(data: ChartData): string {
		if (!singleLine(data.title)) throw new Error('invalid-title');
		if (!data.weeks.every(validPoint)) throw new Error('invalid-week');
		const max = data.weeks.reduce((top, point) => Math.max(top, point.value), 0);
		const s = this.#surface;
		const parts = [s.title(`Weekly trend — ${data.title}`)];
		data.weeks.forEach((point, row) => parts.push(s.bar(row, point.label, point.value, max)));
		const count = data.weeks.length;
		const change = count ? data.weeks[count - 1].value - data.weeks[0].value : 0;
		parts.push(
			s.note(
				count,
				count === 0
					? 'No weeks to show.'
					: `Change over ${count} week${count === 1 ? '' : 's'}: ${change >= 0 ? '+' : ''}${change}.`
			)
		);
		return s.figure(parts, count + 1);
	}
}

export class RecordingSurface implements Surface {
	#inner: Surface;
	#calls: string[] = [];
	constructor(inner: Surface) {
		this.#inner = inner;
	}
	title(text: string): string {
		this.#calls.push(`title: ${text}`);
		return this.#inner.title(text);
	}
	bar(row: number, label: string, value: number, max: number): string {
		this.#calls.push(`bar ${row}: ${label} = ${value} of ${max}`);
		return this.#inner.bar(row, label, value, max);
	}
	note(row: number, text: string): string {
		this.#calls.push(`note ${row}: ${text}`);
		return this.#inner.note(row, text);
	}
	figure(parts: readonly string[], rows: number): string {
		this.#calls.push(`figure: ${parts.length} parts, ${rows} rows`);
		return this.#inner.figure(parts, rows);
	}
	calls(): string[] {
		return [...this.#calls];
	}
}
export function surfaceFor(kind: string): Surface {
	if (kind === 'svg') return new SvgSurface();
	if (kind === 'text') return new TextSurface();
	throw new Error('unknown-surface');
}
export function chartFor(kind: string, surface: Surface, showAll = false): Chart {
	if (kind === 'top') return new TopCategories(surface, showAll);
	if (kind === 'trend') return new WeeklyTrend(surface);
	throw new Error('unknown-chart');
}
export function exampleData(): ChartData {
	return {
		title: 'Support tickets',
		categories: [
			{ label: 'Billing', value: 12 },
			{ label: 'Login', value: 30 },
			{ label: 'Exports', value: 7 },
			{ label: 'Mobile', value: 18 }
		],
		weeks: [
			{ label: 'W1', value: 20 },
			{ label: 'W2', value: 26 },
			{ label: 'W3', value: 21 }
		]
	};
}
export function runExample(): void {
	const data = exampleData();
	for (const chart of ['top', 'trend']) {
		for (const surface of ['text', 'svg']) {
			const drawn = chartFor(chart, surfaceFor(surface));
			console.log(`[${chart} / ${surface}]`);
			console.log(drawn.draw(data));
		}
	}
}

runExample();

Go source

chart.go

package main

import (
	"errors"
	"fmt"
	"strings"
)

type Point struct {
	Label string
	Value int
}
type ChartData struct {
	Title      string
	Categories []Point
	Weeks      []Point
}

type Surface interface {
	Title(text string) string
	Bar(row int, label string, value, maxValue int) string
	Note(row int, text string) string
	Figure(parts []string, rows int) string
}
type BasicChart struct{ surface Surface }

func (c BasicChart) Draw(title string) string {
	return c.surface.Figure([]string{c.surface.Title("Top categories — " + title)}, 0)
}


var textEscaper = strings.NewReplacer("&", "&amp;", "<", "&lt;", ">", "&gt;", `"`, "&quot;", "'", "&#39;")

func escapeText(text string) string { return textEscaper.Replace(text) }
func scaled(value, maxValue, width int) int {
	if maxValue > 0 {
		return value * width / maxValue
	}
	return 0
}

type SVGSurface struct{}

func (SVGSurface) Title(text string) string {
	return `<text x="0" y="16" class="title">` + escapeText(text) + `</text>`
}
func (SVGSurface) Bar(row int, label string, value, maxValue int) string {
	width := scaled(value, maxValue, 200)
	return fmt.Sprintf(`<g transform="translate(0 %d)"><text x="0" y="12">%s</text><rect x="100" y="0" width="%d" height="16"/><text x="%d" y="12">%d</text></g>`,
		32+row*24, escapeText(label), width, 104+width, value)
}
func (SVGSurface) Note(row int, text string) string {
	return fmt.Sprintf(`<text x="0" y="%d" class="note">%s</text>`, 44+row*24, escapeText(text))
}
func (SVGSurface) Figure(parts []string, rows int) string {
	return fmt.Sprintf(`<svg viewBox="0 0 320 %d" role="img">%s</svg>`, 48+rows*24, strings.Join(parts, ""))
}

type TextSurface struct{}

func (TextSurface) Title(text string) string { return text }
func (TextSurface) Bar(_ int, label string, value, maxValue int) string {
	return fmt.Sprintf("%s: %s %d", label, strings.Repeat("█", scaled(value, maxValue, 20)), value)
}
func (TextSurface) Note(_ int, text string) string      { return text }
func (TextSurface) Figure(parts []string, _ int) string { return strings.Join(parts, "\n") }

func singleLine(text string) bool {
	return text != "" && !strings.ContainsAny(text, "\n\r")
}
func validPoint(point Point) bool { return singleLine(point.Label) && point.Value >= 0 }

type Chart interface {
	Draw(data ChartData) (string, error)
}
type TopCategories struct {
	surface Surface
	showAll bool
}

func (c TopCategories) Draw(data ChartData) (string, error) {
	if !singleLine(data.Title) {
		return "", errors.New("invalid-title")
	}
	for _, point := range data.Categories {
		if !validPoint(point) {
			return "", errors.New("invalid-category")
		}
	}
	ranked := append([]Point{}, data.Categories...)
	// Stable insertion sort by descending value keeps input order for ties.
	for i := 1; i < len(ranked); i++ {
		for j := i; j > 0 && ranked[j].Value > ranked[j-1].Value; j-- {
			ranked[j], ranked[j-1] = ranked[j-1], ranked[j]
		}
	}
	shown := ranked
	if !c.showAll && len(shown) > 3 {
		shown = shown[:3]
	}
	maxValue := 0
	if len(shown) > 0 {
		maxValue = shown[0].Value
	}
	parts := []string{c.surface.Title("Top categories — " + data.Title)}
	for row, point := range shown {
		parts = append(parts, c.surface.Bar(row, point.Label, point.Value, maxValue))
	}
	total := len(data.Categories)
	note := "No categories to show."
	if total == 1 {
		note = fmt.Sprintf("%d of %d category shown.", len(shown), total)
	} else if total > 1 {
		note = fmt.Sprintf("%d of %d categories shown.", len(shown), total)
	}
	parts = append(parts, c.surface.Note(len(shown), note))
	return c.surface.Figure(parts, len(shown)+1), nil
}

type WeeklyTrend struct{ surface Surface }

func (c WeeklyTrend) Draw(data ChartData) (string, error) {
	if !singleLine(data.Title) {
		return "", errors.New("invalid-title")
	}
	maxValue := 0
	for _, point := range data.Weeks {
		if !validPoint(point) {
			return "", errors.New("invalid-week")
		}
		if point.Value > maxValue {
			maxValue = point.Value
		}
	}
	parts := []string{c.surface.Title("Weekly trend — " + data.Title)}
	for row, point := range data.Weeks {
		parts = append(parts, c.surface.Bar(row, point.Label, point.Value, maxValue))
	}
	count := len(data.Weeks)
	note := "No weeks to show."
	if count > 0 {
		change := data.Weeks[count-1].Value - data.Weeks[0].Value
		unit := "weeks"
		if count == 1 {
			unit = "week"
		}
		note = fmt.Sprintf("Change over %d %s: %+d.", count, unit, change)
	}
	parts = append(parts, c.surface.Note(count, note))
	return c.surface.Figure(parts, count+1), nil
}


type RecordingSurface struct {
	inner Surface
	calls []string
}

func (r *RecordingSurface) Title(text string) string {
	r.calls = append(r.calls, "title: "+text)
	return r.inner.Title(text)
}
func (r *RecordingSurface) Bar(row int, label string, value, maxValue int) string {
	r.calls = append(r.calls, fmt.Sprintf("bar %d: %s = %d of %d", row, label, value, maxValue))
	return r.inner.Bar(row, label, value, maxValue)
}
func (r *RecordingSurface) Note(row int, text string) string {
	r.calls = append(r.calls, fmt.Sprintf("note %d: %s", row, text))
	return r.inner.Note(row, text)
}
func (r *RecordingSurface) Figure(parts []string, rows int) string {
	r.calls = append(r.calls, fmt.Sprintf("figure: %d parts, %d rows", len(parts), rows))
	return r.inner.Figure(parts, rows)
}
func (r *RecordingSurface) Calls() []string { return append([]string{}, r.calls...) }

func SurfaceFor(kind string) (Surface, error) {
	switch kind {
	case "svg":
		return SVGSurface{}, nil
	case "text":
		return TextSurface{}, nil
	}
	return nil, errors.New("unknown-surface")
}
func ChartFor(kind string, surface Surface, showAll bool) (Chart, error) {
	switch kind {
	case "top":
		return TopCategories{surface, showAll}, nil
	case "trend":
		return WeeklyTrend{surface}, nil
	}
	return nil, errors.New("unknown-chart")
}
func ExampleData() ChartData {
	return ChartData{
		Title:      "Support tickets",
		Categories: []Point{{"Billing", 12}, {"Login", 30}, {"Exports", 7}, {"Mobile", 18}},
		Weeks:      []Point{{"W1", 20}, {"W2", 26}, {"W3", 21}},
	}
}

func main() {
	data := ExampleData()
	for _, kind := range []string{"top", "trend"} {
		for _, name := range []string{"text", "svg"} {
			surface, err := SurfaceFor(name)
			if err != nil {
				fmt.Println("error:", err)
				continue
			}
			chart, err := ChartFor(kind, surface, false)
			if err != nil {
				fmt.Println("error:", err)
				continue
			}
			fmt.Printf("[%s / %s]\n", kind, name)
			output, err := chart.Draw(data)
			if err != nil {
				fmt.Println("error:", err)
				continue
			}
			fmt.Println(output)
		}
	}
}

Python source

chart.py

"""Keep chart meaning independent from the surface that draws it."""

from __future__ import annotations

from dataclasses import dataclass
from typing import Protocol


@dataclass(frozen=True, slots=True)
class Point:
    label: str
    value: int


@dataclass(frozen=True, slots=True)
class ChartData:
    title: str
    categories: tuple[Point, ...]
    weeks: tuple[Point, ...]


class Surface(Protocol):
    def title(self, text: str) -> str: ...

    def bar(self, row: int, label: str, value: int, maximum: int) -> str: ...

    def note(self, row: int, text: str) -> str: ...

    def figure(self, parts: list[str], rows: int) -> str: ...


class BasicChart:
    def __init__(self, surface: Surface) -> None:
        self._surface = surface

    def draw(self, title: str) -> str:
        return self._surface.figure([self._surface.title(f"Top categories — {title}")], 0)



def escape_text(text: str) -> str:
    return (
        text.replace("&", "&amp;")
        .replace("<", "&lt;")
        .replace(">", "&gt;")
        .replace('"', "&quot;")
        .replace("'", "&#39;")
    )


def scaled(value: int, maximum: int, width: int) -> int:
    return (value * width) // maximum if maximum > 0 else 0


class SvgSurface:
    def title(self, text: str) -> str:
        return f'<text x="0" y="16" class="title">{escape_text(text)}</text>'

    def bar(self, row: int, label: str, value: int, maximum: int) -> str:
        width = scaled(value, maximum, 200)
        return f'<g transform="translate(0 {32 + row * 24})"><text x="0" y="12">{escape_text(label)}</text><rect x="100" y="0" width="{width}" height="16"/><text x="{104 + width}" y="12">{value}</text></g>'

    def note(self, row: int, text: str) -> str:
        return f'<text x="0" y="{44 + row * 24}" class="note">{escape_text(text)}</text>'

    def figure(self, parts: list[str], rows: int) -> str:
        return f'<svg viewBox="0 0 320 {48 + rows * 24}" role="img">{"".join(parts)}</svg>'


class TextSurface:
    def title(self, text: str) -> str:
        return text

    def bar(self, row: int, label: str, value: int, maximum: int) -> str:
        del row
        return f"{label}: {'█' * scaled(value, maximum, 20)} {value}"

    def note(self, row: int, text: str) -> str:
        del row
        return text

    def figure(self, parts: list[str], rows: int) -> str:
        del rows
        return "\n".join(parts)


def single_line(text: str) -> bool:
    return bool(text) and "\n" not in text and "\r" not in text


def valid_point(point: Point) -> bool:
    return (
        single_line(point.label)
        and isinstance(point.value, int)
        and not isinstance(point.value, bool)
        and point.value >= 0
    )


class TopCategories:
    def __init__(self, surface: Surface, show_all: bool = False) -> None:
        self._surface = surface
        self._show_all = show_all

    def draw(self, data: ChartData) -> str:
        if not single_line(data.title):
            raise ValueError("invalid-title")
        if not all(valid_point(point) for point in data.categories):
            raise ValueError("invalid-category")
        ranked = sorted(data.categories, key=lambda point: point.value, reverse=True)
        shown = ranked if self._show_all else ranked[:3]
        maximum = shown[0].value if shown else 0
        surface = self._surface
        parts = [surface.title(f"Top categories — {data.title}")]
        parts.extend(surface.bar(row, point.label, point.value, maximum) for row, point in enumerate(shown))
        total = len(data.categories)
        note = (
            "No categories to show."
            if total == 0
            else f"{len(shown)} of {total} {'category' if total == 1 else 'categories'} shown."
        )
        parts.append(surface.note(len(shown), note))
        return surface.figure(parts, len(shown) + 1)


class WeeklyTrend:
    def __init__(self, surface: Surface) -> None:
        self._surface = surface

    def draw(self, data: ChartData) -> str:
        if not single_line(data.title):
            raise ValueError("invalid-title")
        if not all(valid_point(point) for point in data.weeks):
            raise ValueError("invalid-week")
        maximum = max((point.value for point in data.weeks), default=0)
        surface = self._surface
        parts = [surface.title(f"Weekly trend — {data.title}")]
        parts.extend(surface.bar(row, point.label, point.value, maximum) for row, point in enumerate(data.weeks))
        count = len(data.weeks)
        if count == 0:
            note = "No weeks to show."
        else:
            change = data.weeks[-1].value - data.weeks[0].value
            sign = "+" if change >= 0 else ""
            note = f"Change over {count} {'week' if count == 1 else 'weeks'}: {sign}{change}."
        parts.append(surface.note(count, note))
        return surface.figure(parts, count + 1)



class RecordingSurface:
    def __init__(self, inner: Surface) -> None:
        self._inner = inner
        self._calls: list[str] = []

    def title(self, text: str) -> str:
        self._calls.append(f"title: {text}")
        return self._inner.title(text)

    def bar(self, row: int, label: str, value: int, maximum: int) -> str:
        self._calls.append(f"bar {row}: {label} = {value} of {maximum}")
        return self._inner.bar(row, label, value, maximum)

    def note(self, row: int, text: str) -> str:
        self._calls.append(f"note {row}: {text}")
        return self._inner.note(row, text)

    def figure(self, parts: list[str], rows: int) -> str:
        self._calls.append(f"figure: {len(parts)} parts, {rows} rows")
        return self._inner.figure(parts, rows)

    def calls(self) -> list[str]:
        return list(self._calls)


def surface_for(kind: str) -> Surface:
    if kind == "svg":
        return SvgSurface()
    if kind == "text":
        return TextSurface()
    raise ValueError("unknown-surface")


def chart_for(kind: str, surface: Surface, show_all: bool = False) -> TopCategories | WeeklyTrend:
    if kind == "top":
        return TopCategories(surface, show_all)
    if kind == "trend":
        return WeeklyTrend(surface)
    raise ValueError("unknown-chart")


def example_data() -> ChartData:
    return ChartData(
        "Support tickets",
        (
            Point("Billing", 12),
            Point("Login", 30),
            Point("Exports", 7),
            Point("Mobile", 18),
        ),
        (Point("W1", 20), Point("W2", 26), Point("W3", 21)),
    )


def run_example() -> None:
    data = example_data()
    for kind in ("top", "trend"):
        for surface_kind in ("text", "svg"):
            drawn = chart_for(kind, surface_for(surface_kind))
            print(f"[{kind} / {surface_kind}]")
            print(drawn.draw(data))


if __name__ == "__main__":
    run_example()

Java source

BridgeExample.java

import java.util.ArrayList;
import java.util.List;

record Point(String label, int value) {}

record ChartData(String title, List<Point> categories, List<Point> weeks) {
    ChartData {
        categories = List.copyOf(categories);
        weeks = List.copyOf(weeks);
    }
}

interface Surface {
    String title(String text);

    String bar(int row, String label, int value, int maximum);

    String note(int row, String text);

    String figure(List<String> parts, int rows);
}

final class BasicChart {
    private final Surface surface;

    BasicChart(Surface surface) {
        this.surface = surface;
    }

    String draw(String title) {
        return surface.figure(List.of(surface.title("Top categories — " + title)), 0);
    }
}

final class SvgSurface implements Surface {
    private static String escapeText(String text) {
        return text
            .replace("&", "&amp;")
            .replace("<", "&lt;")
            .replace(">", "&gt;")
            .replace("\"", "&quot;")
            .replace("'", "&#39;");
    }

    private static int scaled(int value, int maximum, int width) {
        return maximum > 0 ? value * width / maximum : 0;
    }

    @Override
    public String title(String text) {
        return "<text x=\"0\" y=\"16\" class=\"title\">" + escapeText(text) + "</text>";
    }

    @Override
    public String bar(int row, String label, int value, int maximum) {
        int width = scaled(value, maximum, 200);
        return "<g transform=\"translate(0 " + (32 + row * 24) + ")\"><text x=\"0\" y=\"12\">"
            + escapeText(label)
            + "</text><rect x=\"100\" y=\"0\" width=\""
            + width
            + "\" height=\"16\"/><text x=\""
            + (104 + width)
            + "\" y=\"12\">"
            + value
            + "</text></g>";
    }

    @Override
    public String note(int row, String text) {
        return "<text x=\"0\" y=\"" + (44 + row * 24) + "\" class=\"note\">"
            + escapeText(text)
            + "</text>";
    }

    @Override
    public String figure(List<String> parts, int rows) {
        return "<svg viewBox=\"0 0 320 " + (48 + rows * 24) + "\" role=\"img\">"
            + String.join("", parts)
            + "</svg>";
    }
}

final class TextSurface implements Surface {
    private static int scaled(int value, int maximum, int width) {
        return maximum > 0 ? value * width / maximum : 0;
    }

    @Override
    public String title(String text) {
        return text;
    }

    @Override
    public String bar(int row, String label, int value, int maximum) {
        int width = scaled(value, maximum, 20);
        return label + ": " + "█".repeat(width) + " " + value;
    }

    @Override
    public String note(int row, String text) {
        return text;
    }

    @Override
    public String figure(List<String> parts, int rows) {
        return String.join("\n", parts);
    }
}

final class BridgeRules {
    private BridgeRules() {}

    static boolean singleLine(String text) {
        return text != null && !text.isEmpty() && !text.contains("\n") && !text.contains("\r");
    }

    static boolean validPoint(Point point) {
        return point != null && singleLine(point.label()) && point.value() >= 0;
    }
}

interface Chart {
    String draw(ChartData data);
}

final class TopCategories implements Chart {
    private final Surface surface;
    private final boolean showAll;

    TopCategories(Surface surface, boolean showAll) {
        this.surface = surface;
        this.showAll = showAll;
    }

    @Override
    public String draw(ChartData data) {
        if (!BridgeRules.singleLine(data.title())) throw new IllegalArgumentException("invalid-title");
        for (Point point : data.categories()) {
            if (!BridgeRules.validPoint(point)) throw new IllegalArgumentException("invalid-category");
        }
        List<Point> ranked = new ArrayList<>(data.categories());
        ranked.sort((left, right) -> Integer.compare(right.value(), left.value()));
        List<Point> shown = showAll ? ranked : ranked.subList(0, Math.min(3, ranked.size()));
        int maximum = shown.isEmpty() ? 0 : shown.get(0).value();
        List<String> parts = new ArrayList<>();
        parts.add(surface.title("Top categories — " + data.title()));
        for (int row = 0; row < shown.size(); row++) {
            Point point = shown.get(row);
            parts.add(surface.bar(row, point.label(), point.value(), maximum));
        }
        int total = data.categories().size();
        String note = total == 0
            ? "No categories to show."
            : shown.size() + " of " + total + " " + (total == 1 ? "category" : "categories") + " shown.";
        parts.add(surface.note(shown.size(), note));
        return surface.figure(parts, shown.size() + 1);
    }
}

final class WeeklyTrend implements Chart {
    private final Surface surface;

    WeeklyTrend(Surface surface) {
        this.surface = surface;
    }

    @Override
    public String draw(ChartData data) {
        if (!BridgeRules.singleLine(data.title())) throw new IllegalArgumentException("invalid-title");
        for (Point point : data.weeks()) {
            if (!BridgeRules.validPoint(point)) throw new IllegalArgumentException("invalid-week");
        }
        int maximum = 0;
        for (Point point : data.weeks()) maximum = Math.max(maximum, point.value());
        List<String> parts = new ArrayList<>();
        parts.add(surface.title("Weekly trend — " + data.title()));
        for (int row = 0; row < data.weeks().size(); row++) {
            Point point = data.weeks().get(row);
            parts.add(surface.bar(row, point.label(), point.value(), maximum));
        }
        int count = data.weeks().size();
        String note;
        if (count == 0) {
            note = "No weeks to show.";
        } else {
            int change = data.weeks().get(count - 1).value() - data.weeks().get(0).value();
            note = "Change over " + count + " " + (count == 1 ? "week" : "weeks") + ": "
                + (change >= 0 ? "+" : "") + change + ".";
        }
        parts.add(surface.note(count, note));
        return surface.figure(parts, count + 1);
    }
}


final class RecordingSurface implements Surface {
    private final Surface inner;
    private final List<String> calls = new ArrayList<>();

    RecordingSurface(Surface inner) {
        this.inner = inner;
    }

    @Override
    public String title(String text) {
        calls.add("title: " + text);
        return inner.title(text);
    }

    @Override
    public String bar(int row, String label, int value, int maximum) {
        calls.add("bar " + row + ": " + label + " = " + value + " of " + maximum);
        return inner.bar(row, label, value, maximum);
    }

    @Override
    public String note(int row, String text) {
        calls.add("note " + row + ": " + text);
        return inner.note(row, text);
    }

    @Override
    public String figure(List<String> parts, int rows) {
        calls.add("figure: " + parts.size() + " parts, " + rows + " rows");
        return inner.figure(parts, rows);
    }

    List<String> calls() {
        return new ArrayList<>(calls);
    }
}

public final class BridgeExample {
    private BridgeExample() {}

    static Surface surfaceFor(String kind) {
        return switch (kind) {
            case "svg" -> new SvgSurface();
            case "text" -> new TextSurface();
            default -> throw new IllegalArgumentException("unknown-surface");
        };
    }

    static Chart chartFor(String kind, Surface surface, boolean showAll) {
        return switch (kind) {
            case "top" -> new TopCategories(surface, showAll);
            case "trend" -> new WeeklyTrend(surface);
            default -> throw new IllegalArgumentException("unknown-chart");
        };
    }

    static ChartData exampleData() {
        return new ChartData(
            "Support tickets",
            List.of(new Point("Billing", 12), new Point("Login", 30), new Point("Exports", 7), new Point("Mobile", 18)),
            List.of(new Point("W1", 20), new Point("W2", 26), new Point("W3", 21))
        );
    }

    static List<String> runExample() {
        ChartData data = exampleData();
        List<String> output = new ArrayList<>();
        for (String kind : List.of("top", "trend")) {
            for (String surfaceKind : List.of("text", "svg")) {
                output.add("[" + kind + " / " + surfaceKind + "]");
                output.add(chartFor(kind, surfaceFor(surfaceKind), false).draw(data));
            }
        }
        return output;
    }

    public static void main(String[] args) {
        for (String line : runExample()) System.out.println(line);
    }
}

Rust source

chart.rs

use std::cell::RefCell;
#[derive(Clone, Debug, PartialEq)]
struct Point {
    label: String,
    value: i64,
}
#[derive(Clone, Debug, PartialEq)]
struct ChartData {
    title: String,
    categories: Vec<Point>,
    weeks: Vec<Point>,
}

trait Surface {
    fn title(&self, text: &str) -> String;
    fn bar(&self, row: usize, label: &str, value: i64, max: i64) -> String;
    fn note(&self, row: usize, text: &str) -> String;
    fn figure(&self, parts: &[String], rows: usize) -> String;
}
struct BasicChart<'a> {
    surface: &'a dyn Surface,
}
impl BasicChart<'_> {
    fn draw(&self, title: &str) -> String {
        self.surface.figure(
            &[self.surface.title(&format!("Top categories — {title}"))],
            0,
        )
    }
}

fn escape_text(text: &str) -> String {
    let mut result = String::new();
    for ch in text.chars() {
        match ch {
            '&' => result.push_str("&amp;"),
            '<' => result.push_str("&lt;"),
            '>' => result.push_str("&gt;"),
            '"' => result.push_str("&quot;"),
            '\'' => result.push_str("&#39;"),
            _ => result.push(ch),
        }
    }
    result
}
fn scaled(value: i64, max: i64, width: i64) -> i64 {
    if max > 0 {
        value * width / max
    } else {
        0
    }
}
struct SvgSurface;
impl Surface for SvgSurface {
    fn title(&self, text: &str) -> String {
        format!(
            r#"<text x="0" y="16" class="title">{}</text>"#,
            escape_text(text)
        )
    }
    fn bar(&self, row: usize, label: &str, value: i64, max: i64) -> String {
        let width = scaled(value, max, 200);
        format!(
            r#"<g transform="translate(0 {})"><text x="0" y="12">{}</text><rect x="100" y="0" width="{width}" height="16"/><text x="{}" y="12">{value}</text></g>"#,
            32 + row * 24,
            escape_text(label),
            104 + width
        )
    }
    fn note(&self, row: usize, text: &str) -> String {
        format!(
            r#"<text x="0" y="{}" class="note">{}</text>"#,
            44 + row * 24,
            escape_text(text)
        )
    }
    fn figure(&self, parts: &[String], rows: usize) -> String {
        format!(
            r#"<svg viewBox="0 0 320 {}" role="img">{}</svg>"#,
            48 + rows * 24,
            parts.concat()
        )
    }
}
struct TextSurface;
impl Surface for TextSurface {
    fn title(&self, text: &str) -> String {
        text.to_string()
    }
    fn bar(&self, _row: usize, label: &str, value: i64, max: i64) -> String {
        format!(
            "{label}: {} {value}",
            "█".repeat(scaled(value, max, 20) as usize)
        )
    }
    fn note(&self, _row: usize, text: &str) -> String {
        text.to_string()
    }
    fn figure(&self, parts: &[String], _rows: usize) -> String {
        parts.join("\n")
    }
}
fn single_line(text: &str) -> bool {
    !text.is_empty() && !text.contains('\n') && !text.contains('\r')
}
fn valid_point(point: &Point) -> bool {
    single_line(&point.label) && point.value >= 0
}
trait Chart {
    fn draw(&self, data: &ChartData) -> Result<String, String>;
}
struct TopCategories<'a> {
    surface: &'a dyn Surface,
    show_all: bool,
}
impl Chart for TopCategories<'_> {
    fn draw(&self, data: &ChartData) -> Result<String, String> {
        if !single_line(&data.title) {
            return Err("invalid-title".into());
        }
        if !data.categories.iter().all(valid_point) {
            return Err("invalid-category".into());
        }
        let mut ranked = data.categories.clone();
        ranked.sort_by(|a, b| b.value.cmp(&a.value)); // stable: ties keep input order
        let shown: &[Point] = if self.show_all {
            &ranked
        } else {
            &ranked[..ranked.len().min(3)]
        };
        let max = shown.first().map_or(0, |point| point.value);
        let s = self.surface;
        let mut parts = vec![s.title(&format!("Top categories — {}", data.title))];
        for (row, point) in shown.iter().enumerate() {
            parts.push(s.bar(row, &point.label, point.value, max));
        }
        let total = data.categories.len();
        let note = match total {
            0 => "No categories to show.".to_string(),
            1 => format!("{} of {total} category shown.", shown.len()),
            _ => format!("{} of {total} categories shown.", shown.len()),
        };
        parts.push(s.note(shown.len(), &note));
        Ok(s.figure(&parts, shown.len() + 1))
    }
}
struct WeeklyTrend<'a> {
    surface: &'a dyn Surface,
}
impl Chart for WeeklyTrend<'_> {
    fn draw(&self, data: &ChartData) -> Result<String, String> {
        if !single_line(&data.title) {
            return Err("invalid-title".into());
        }
        if !data.weeks.iter().all(valid_point) {
            return Err("invalid-week".into());
        }
        let max = data
            .weeks
            .iter()
            .map(|point| point.value)
            .max()
            .unwrap_or(0);
        let s = self.surface;
        let mut parts = vec![s.title(&format!("Weekly trend — {}", data.title))];
        for (row, point) in data.weeks.iter().enumerate() {
            parts.push(s.bar(row, &point.label, point.value, max));
        }
        let count = data.weeks.len();
        let note = match (data.weeks.first(), data.weeks.last()) {
            (Some(first), Some(last)) => {
                let change = last.value - first.value;
                let unit = if count == 1 { "week" } else { "weeks" };
                format!("Change over {count} {unit}: {change:+}.")
            }
            _ => "No weeks to show.".to_string(),
        };
        parts.push(s.note(count, &note));
        Ok(s.figure(&parts, count + 1))
    }
}

struct RecordingSurface<'a> {
    inner: &'a dyn Surface,
    calls: RefCell<Vec<String>>,
}
impl<'a> RecordingSurface<'a> {
    fn new(inner: &'a dyn Surface) -> Self {
        Self {
            inner,
            calls: RefCell::new(Vec::new()),
        }
    }
    fn calls(&self) -> Vec<String> {
        self.calls.borrow().clone()
    }
}
impl Surface for RecordingSurface<'_> {
    fn title(&self, text: &str) -> String {
        self.calls.borrow_mut().push(format!("title: {text}"));
        self.inner.title(text)
    }
    fn bar(&self, row: usize, label: &str, value: i64, max: i64) -> String {
        self.calls
            .borrow_mut()
            .push(format!("bar {row}: {label} = {value} of {max}"));
        self.inner.bar(row, label, value, max)
    }
    fn note(&self, row: usize, text: &str) -> String {
        self.calls.borrow_mut().push(format!("note {row}: {text}"));
        self.inner.note(row, text)
    }
    fn figure(&self, parts: &[String], rows: usize) -> String {
        self.calls
            .borrow_mut()
            .push(format!("figure: {} parts, {rows} rows", parts.len()));
        self.inner.figure(parts, rows)
    }
}
fn surface_for(kind: &str) -> Result<Box<dyn Surface>, String> {
    match kind {
        "svg" => Ok(Box::new(SvgSurface)),
        "text" => Ok(Box::new(TextSurface)),
        _ => Err("unknown-surface".into()),
    }
}
fn chart_for<'a>(
    kind: &str,
    surface: &'a dyn Surface,
    show_all: bool,
) -> Result<Box<dyn Chart + 'a>, String> {
    match kind {
        "top" => Ok(Box::new(TopCategories { surface, show_all })),
        "trend" => Ok(Box::new(WeeklyTrend { surface })),
        _ => Err("unknown-chart".into()),
    }
}
fn point(label: &str, value: i64) -> Point {
    Point {
        label: label.into(),
        value,
    }
}
fn example_data() -> ChartData {
    ChartData {
        title: "Support tickets".into(),
        categories: vec![
            point("Billing", 12),
            point("Login", 30),
            point("Exports", 7),
            point("Mobile", 18),
        ],
        weeks: vec![point("W1", 20), point("W2", 26), point("W3", 21)],
    }
}
fn run_example() {
    let data = example_data();
    for kind in ["top", "trend"] {
        for name in ["text", "svg"] {
            let surface = surface_for(name).expect("known surface");
            let chart = chart_for(kind, surface.as_ref(), false).expect("known chart");
            println!("[{kind} / {name}]");
            match chart.draw(&data) {
                Ok(output) => println!("{output}"),
                Err(error) => println!("error: {error}"),
            }
        }
    }
}
fn main() {
    run_example();
    // Silent checks keep the basic chart and recorder exercised in the standalone binary.
    let recorder = RecordingSurface::new(&TextSurface);
    let basic = BasicChart { surface: &recorder };
    assert_eq!(basic.draw("Acme"), "Top categories — Acme");
    assert_eq!(recorder.calls().len(), 2);
}

The call site runs all four pairings. On either surface, Login leads the top categories and only three of four appear by default. On either surface, the trend runs W1 to W3 and notes a change of +1. Switching the surface changes the drawing while preserving those content decisions.

The shared contract and its boundariesRaw text and numbers in, drawn fragments out

The title and every label a chart uses must be nonempty strings without carriage returns or line feeds; values are whole numbers of zero or more. Accepted text is preserved exactly, including spaces and Unicode. The model has no length limit. A production input policy can be stricter.

TopCategories validates every category, then sorts by value with ties keeping input order, and caps the list at three unless the caller asks for every category. The longest shown bar sets the scale. WeeklyTrend validates every week, keeps their order, scales to the largest week, and notes the signed change from the first week to the last. Each chart checks the title first, ignores the other chart’s collection, and completes validation before calling any surface operation.

Title, bar, and note receive raw text and numbers, with the row index the chart assigned. The figure operation receives fragments already produced by that surface and the number of rows to reserve. SvgSurface escapes ampersands, angle brackets, and both quote characters in text nodes and scales bars to 200 units; TextSurface scales to 20 block characters. Neither is an HTML sanitizer or a layout engine.

Both surfaces return a complete string without mutating the input. SVG is one svg element with a viewBox sized from the row count; text joins rows with line breaks and has no trailing newline. Empty collections produce a title and an explanatory note. Validation errors produce no output and no surface calls.

Reading the TypeScriptStructural interfaces and retained collaborators

Surface describes four methods. A class with those methods fits the interface. A chart keeps its surface in a private field and uses it for each drawing. TypeScript’s interface is a compile-time agreement, while the explicit data checks handle the model’s runtime validation.

The surface returns strings for each row. The chart pushes title, bars, and note into an array before calling figure, so those operations happen first. The recording wrapper makes that order visible.

Reading the GoImplicit interfaces and explicit errors

SVGSurface and TextSurface satisfy the Surface interface through their methods. A chart struct retains that interface value. Changing its concrete implementation does not change the chart’s data code.

Draw returns (string, error). Invalid points return an empty string and an error before building rows. The ranking uses a small stable insertion sort so ties keep input order, matching the other languages. These built-in surfaces have no mutable fields; the diagnostic recorder does, so give each drawing its own recorder or add a concurrency policy before sharing it.

Reading the PythonProtocols, dataclasses, and stable sorting

Python’s Surface Protocol describes the same four operations without requiring inheritance. Frozen, slotted dataclasses keep points and chart data value-like, while tuple fields and copied traces make the example’s ownership boundary visible.

sorted(..., reverse=True) creates a ranked list without changing the caller’s data; Python’s sort is stable, so equal values keep input order. ValueError carries the same validation failures before any surface call.

03 / Follow the calls

Change one choice. Keep the other.

Start with Top categories on SVG. Before moving to text, predict which strings and numbers will cross the surface boundary. The title, the ranked labels, their values, and the note should remain the same. Only their drawing changes.

Now choose Weekly trend on text. The surface stays the same, but the chart supplies different rows. Return to top categories and show every category: the list grows to four, while Login still leads. Try labels containing markup, then invalid points, and explain why escaping happens on one side and validation on the other.

One chart choice. One surface choice.

Choose a cell, then move across its row or down its column. Watch which responsibility changes and which surface calls stay the same.

Chart ↓
Surface →

SVG

Text

Top categories

Weekly trend

01 / Chart owns meaning

Top categories

Validate categories, rank them by value, and decide how many bars to show.

02 / Surface owns drawing

SVG surface

Escape text, place each row at a y offset, and scale bars to 200 units inside one svg element.

Sample data

Show every categoryChart policy; kept while viewing the trend.

Apply the title with Draw. Pair and policy changes use the last applied title. A sample selection replaces it; Reset restores typical tickets and keeps the selected pair.

Inspect the sample points

{
  "categories": [
    {
      "label": "Billing",
      "value": 12
    },
    {
      "label": "Login",
      "value": 30
    },
    {
      "label": "Exports",
      "value": 7
    },
    {
      "label": "Mobile",
      "value": 18
    }
  ],
  "weeks": [
    {
      "label": "W1",
      "value": 20
    },
    {
      "label": "W2",
      "value": 26
    },
    {
      "label": "W3",
      "value": 21
    }
  ]
}

Top categories / SVG · Drew “Support tickets” through 6 surface calls.

Generated chart

Show raw output

The generated svg element, displayed with fixed preview-only styles inside a sandboxed frame.

Across the surface boundary

Raw text and numbers enter title, bar, and note. Their generated fragments enter figure.

title: Top categories — Support tickets
bar 0: Login = 30 of 30
bar 1: Mobile = 18 of 30
bar 2: Billing = 12 of 30
note 3: 3 of 4 categories shown.
figure: 5 parts, 4 rows

The browser runs the TypeScript chart model from the examples above, through a recording wrapper.

How the call trace is recordedA Decorator around either surface

chart.ts · call recorder

export class RecordingSurface implements Surface {
	#inner: Surface;
	#calls: string[] = [];
	constructor(inner: Surface) {
		this.#inner = inner;
	}
	title(text: string): string {
		this.#calls.push(`title: ${text}`);
		return this.#inner.title(text);
	}
	bar(row: number, label: string, value: number, max: number): string {
		this.#calls.push(`bar ${row}: ${label} = ${value} of ${max}`);
		return this.#inner.bar(row, label, value, max);
	}
	note(row: number, text: string): string {
		this.#calls.push(`note ${row}: ${text}`);
		return this.#inner.note(row, text);
	}
	figure(parts: readonly string[], rows: number): string {
		this.#calls.push(`figure: ${parts.length} parts, ${rows} rows`);
		return this.#inner.figure(parts, rows);
	}
	calls(): string[] {
		return [...this.#calls];
	}
}

RecordingSurface implements the same surface interface, records each call, then forwards it to an inner surface. The lab creates a fresh wrapper for every drawing and reads a copy of its trace. A failed validation leaves that trace empty because the chart never reaches the surface.

This wrapper is a concrete Decorator used alongside Bridge. The chart still sees a Surface. The wrapper adds observation around the chosen drawing implementation without taking over chart policy.

04 / Try a decision

Independent change has a boundary.

A third chart can use the operations we already have. A new kind of drawing may need a richer vocabulary. Decide what happens when that distinction becomes visible.

Reason through the alternatives

Build the paired bars as SVG markup inside ComparisonChart and pass it to note. The chart would now know one surface. SvgSurface would escape that markup as text, while TextSurface would print the tags. Passing raw markup also violates note’s text contract.

Define a paired-bar operation and its behavior on each supported surface before using it in the new chart. The requirement exceeds the current vocabulary. The chart can own which two values sit together and in what order; the surfaces can own side-by-side rectangles and an agreed text arrangement. Updating both surfaces is an honest shared-contract change. If text cannot show the pairing legibly, make that limitation explicit.

Make each surface inspect the chart kind and lay out the comparison itself. Now adding or changing a chart requires editing every surface. The drawing side has absorbed chart policy, which is the coupling this boundary was meant to remove.

Two separate rows may be enough when the comparison is incidental. This question makes the pairing part of the requirement, so a new operation needs an explicit meaning on every supported surface.

Explain two independent changes and one shared change.

Where would you add a share-of-total chart? Where would you add a Canvas surface? Which new requirement would force you to revisit the surface contract?

This note stays on this page; nothing is saved or graded.

05 / Give it a real job

Build the pair at the dashboard boundary.

A dashboard controller receives a chart kind and a surface, authorizes access, and loads the relevant numbers. It chooses a surface, supplies it to the requested chart, and asks for a complete figure. The page, the digest message, or the image endpoint then handles display. The chart does not need to know who opened the dashboard or where the drawing will go.

A share-of-total chart can become another chart using the existing operations. A Canvas or terminal-color surface can become another surface implementing those operations for both current charts. If a future chart needs paired bars, a legend, or a second axis, define how those capabilities should work on every supported surface before promising that every pairing remains valid.

The built-in surfaces are stateless and reusable. A surface that owns a canvas context, a file, or a GPU resource introduces lifetimes and failures of its own. Streaming also changes the contract: an error after emitting some rows cannot retract those bytes. Buffering, cancellation, cleanup, retries, and partial-drawing reporting need deliberate ownership.

Build UIs?Hooks work in every React renderer, and a div does not. Tracking events for more than one analytics destination makes that split your design.

Where it already is in your components

If you have written a React Three Fiber scene or an Ink command-line app, you already follow a rule that comes from this split: useState and useEffect work there exactly as they do in the browser, and <div> does not. React’s core is the abstraction, and each renderer supplies the implementor. The react-reconciler README calls that implementor a host config: an object describing how to make things happen in the host environment, whether that is the DOM, a canvas, or a console. Its createInstance receives the element type, and for the DOM renderer the README’s example is document.createElement(type).

Hooks sit on the abstraction’s side. In React 19.1.0, useState in the react package only looks up the current dispatcher and calls its useState; the reconciler inside whichever renderer is rendering sets that dispatcher. A lowercase tag sits on the other side. React passes the string "div" to the renderer and leaves its meaning to the host config.

We checked both halves. In a renderer built on react-reconciler 0.32.0 whose host config knows a single element type, a counter using useState and useEffect committed 0, 1, then 2 with no DOM anywhere, and a <div> reached createInstance as the string "div". In React Three Fiber 9.7.0 on Chromium 153, a counter with the same hooks ran inside <Canvas>, and a <div> placed there threw “R3F: Div is not part of the THREE namespace! Did you forget to extend?” Component behavior crosses renderers unchanged, while the element vocabulary belongs to each renderer, as drawing a bar belongs to each of our surfaces.

When you have to own it

Now your checkout needs product analytics. The product team wants checkoutStarted and couponApplied with the properties each one carries, growth wants the same events in a vendor tool, and in development you want them in the console. Events and destinations change for different reasons, so give each its own side. Components call event functions, and those functions build each event from a small destination interface, say send(name, properties) and identify(userId). Each destination implements that interface. A new event touches no destination, and a new vendor touches no component.

Keep delivery details in the destination. Sending while the page goes away is a transport question: MDN recommends navigator.sendBeacon from a visibilitychange listener, and fetch with keepalive when you need the response. Event code that checks which vendor it is talking to has pulled a destination back onto the event side. Decide what a failing destination does to the page, too: a vendor script that never loads should not break the checkout button that recorded the click. And widen the interface on purpose. If one vendor offers something the others cannot, such as session replay, that is a new capability to define for every destination, like the paired bars in section 04.

Each vendor destination is usually an Adapter around that vendor’s SDK. The Bridge is the split you choose before the second vendor arrives: which operations the event side may use.

06 / Already in your toolbox

A common surface can have different backends.

These documented APIs show the same separation at their public boundaries.

Qt · paint operations and device engines

QPainter exposes drawing operations. QPaintDevice represents a surface, and QPaintEngine supplies the interface used to draw on different devices. Qt normally hides the engine from application code. It is the same shape as our chart and surface, at library scale.

Read Qt’s paint system overview ↗

Go · database/sql and drivers

database/sql provides a common SQL API and requires a database driver. The separation lets application-facing operations use different database implementations. Backend differences still matter: the documentation explicitly notes that a driver without cancellation support may finish the query before returning.

Read the SQL package contract ↗

07 / When it earns its place

Choose operations that carry enough meaning.

Bridge is useful when chart behavior and drawing behavior have separate reasons to change, and a shared operation vocabulary can support their combinations. Four pairings make the separation easy to see here. Counting classes is not the test: functions and tables can express the same choices without a class for every pair.

Keep the direct drawing function when one small chart is the actual requirement. If several charts already produce the same structured row data, a data model followed by a renderer may be clearer than having chart objects call surface methods. The responsibility split can remain useful even when the handoff changes.

A surface contract that accepts only an arbitrary drawn string can be too weak to preserve meaning. A contract containing every possible visual feature can become difficult to implement. Start with operations demanded by real charts. Review new capabilities against accessibility, drawing fidelity, and each surface’s limits.

The interface adds a place to navigate and a contract to maintain. The implementations still need tests for every supported pairing: here, exact output, call order, escaping, validation, and input preservation in every implementation.

08 / Take the idea with you

Name the two reasons for change.

Explain it without the pattern name: “The chart selects and orders meaningful rows. It holds a surface that draws those rows through a shared set of operations. The caller can choose either side independently, as long as the operations support the requested drawing.” Then name one change that belongs on each side.

Connections to follow nextRelated lessons

Strategy also uses composition to replace behavior. Its usual focus is choosing a policy for a context. Bridge emphasizes the relationship between two independently varying dimensions. Similar code shapes can support different design explanations; a constructor taking an interface does not settle the name.

Adapter makes an existing interface fit a caller’s expectation, usually after both sides already exist. Bridge is a split you choose up front, before the implementations multiply. A surface adapter could connect a third-party drawing library to this Bridge. Abstract factory constructs related product families whose members should agree. Here, chart and surface are intentionally independent choices.

Ports and adapters applies a related dependency boundary at application scale. Naming a port helps express what the application needs; deciding which responsibilities vary independently still takes domain reasoning.