@jjlmoya/utils-civic 1.1.0 → 1.3.0

package/src/tool/coalition-majority-calculator/logic.ts

@@ -0,0 +1,146 @@
+export interface PartyInput {
+  name: string;
+  seats: number;
+}
+
+export interface CoalitionRecord {
+  mask: number;
+  members: string[];
+  seats: number;
+  surplus: number;
+  minimal: boolean;
+  redundantMembers: string[];
+}
+
+export interface CoalitionAnalysis {
+  valid: boolean;
+  error?: string;
+  parties: PartyInput[];
+  totalSeats: number;
+  threshold: number;
+  totalCoalitions: number;
+  winningCoalitions: number;
+  minimalWinningCoalitions: number;
+  pivotTotal: number;
+  displayedCoalitions: CoalitionRecord[];
+  pivotCounts: Record<string, number>;
+  pivotShares: Record<string, number>;
+  warnings: string[];
+}
+
+interface PreparedInput {
+  parties: PartyInput[];
+  threshold: number;
+  totalSeats: number;
+  warnings: string[];
+}
+
+interface EnumerationState {
+  winning: number;
+  minimal: number;
+  rows: CoalitionRecord[];
+  pivotCounts: Record<string, number>;
+}
+
+interface CoalitionInspection {
+  record: CoalitionRecord;
+  criticalIndexes: number[];
+}
+
+const MAX_PARTIES = 20;
+const DISPLAY_LIMIT = 120;
+
+function normalizeName(name: string, index: number, seen: Map<string, number>): string {
+  const base = name.trim() || `Party ${index + 1}`;
+  const count = seen.get(base) ?? 0;
+  seen.set(base, count + 1);
+  return count === 0 ? base : `${base} ${count + 1}`;
+}
+
+function prepareInput(inputs: PartyInput[], threshold: number): PreparedInput | string {
+  if (inputs.length === 0) return 'Add at least one party.';
+  if (inputs.length > MAX_PARTIES) return `The model supports at most ${MAX_PARTIES} parties.`;
+  const seen = new Map<string, number>();
+  const parties = inputs.map((party, index) => ({ name: normalizeName(party.name, index, seen), seats: party.seats }));
+  if (parties.some((party) => !Number.isSafeInteger(party.seats) || party.seats < 0)) return 'Seats must be whole numbers greater than or equal to zero.';
+  if (!Number.isSafeInteger(threshold) || threshold < 1) return 'The threshold must be a whole number above zero.';
+  const totalSeats = parties.reduce((sum, party) => sum + party.seats, 0);
+  const warnings = inputs.some((party, index) => party.name.trim() !== parties[index]?.name)
+    ? ['Duplicate or blank names were made unique for the calculation.']
+    : [];
+  if (threshold > totalSeats) warnings.push('The threshold is above the chamber total, so no coalition can win.');
+  return { parties, threshold, totalSeats, warnings };
+}
+
+function buildSeatTotals(parties: PartyInput[]): Float64Array {
+  const totals = new Float64Array(2 ** parties.length);
+  for (let mask = 1; mask < totals.length; mask += 1) {
+    const bit = mask & -mask;
+    const index = Math.log2(bit);
+    totals[mask] = (totals[mask ^ bit] ?? 0) + (parties[index]?.seats ?? 0);
+  }
+  return totals;
+}
+
+function inspectCoalition(mask: number, parties: PartyInput[], seats: number, threshold: number): CoalitionInspection {
+  const members: string[] = [];
+  const memberIndexes: number[] = [];
+  const criticalIndexes: number[] = [];
+  for (let index = 0; index < parties.length; index += 1) {
+    if ((mask & (1 << index)) === 0) continue;
+    memberIndexes.push(index);
+    members.push(parties[index]?.name ?? '');
+    if (seats - (parties[index]?.seats ?? 0) < threshold) criticalIndexes.push(index);
+  }
+  const criticalSet = new Set(criticalIndexes);
+  return {
+    record: { mask, members, seats, surplus: seats - threshold, minimal: criticalIndexes.length === members.length, redundantMembers: memberIndexes.filter((index) => !criticalSet.has(index)).map((index) => parties[index]?.name ?? '') },
+    criticalIndexes,
+  };
+}
+
+function createState(parties: PartyInput[]): EnumerationState {
+  return { winning: 0, minimal: 0, rows: [], pivotCounts: Object.fromEntries(parties.map((party) => [party.name, 0])) };
+}
+
+function addRow(rows: CoalitionRecord[], record: CoalitionRecord): void {
+  if (rows.length < DISPLAY_LIMIT) rows.push(record);
+  else if (record.minimal && rows.some((row) => !row.minimal)) {
+    const index = rows.findIndex((row) => !row.minimal);
+    if (index >= 0) rows[index] = record;
+  }
+}
+
+function enumerate(parties: PartyInput[], threshold: number, totals: Float64Array): EnumerationState {
+  const state = createState(parties);
+  for (let mask = 1; mask < totals.length; mask += 1) {
+    const seats = totals[mask] ?? 0;
+    if (seats < threshold) continue;
+    const inspection = inspectCoalition(mask, parties, seats, threshold);
+    state.winning += 1;
+    if (inspection.record.minimal) state.minimal += 1;
+    inspection.criticalIndexes.forEach((index) => {
+      const name = parties[index]?.name;
+      if (name) state.pivotCounts[name] = (state.pivotCounts[name] ?? 0) + 1;
+    });
+    addRow(state.rows, inspection.record);
+  }
+  return state;
+}
+
+function sortRows(rows: CoalitionRecord[]): CoalitionRecord[] {
+  return [...rows].sort((left, right) => Number(right.minimal) - Number(left.minimal) || left.surplus - right.surplus || left.members.length - right.members.length || left.mask - right.mask);
+}
+
+function createAnalysis(prepared: PreparedInput, state: EnumerationState): CoalitionAnalysis {
+  const pivotTotal = Object.values(state.pivotCounts).reduce((sum, count) => sum + count, 0);
+  const pivotShares = Object.fromEntries(Object.entries(state.pivotCounts).map(([name, count]) => [name, pivotTotal === 0 ? 0 : count / pivotTotal]));
+  return { valid: true, parties: prepared.parties, totalSeats: prepared.totalSeats, threshold: prepared.threshold, totalCoalitions: 2 ** prepared.parties.length - 1, winningCoalitions: state.winning, minimalWinningCoalitions: state.minimal, pivotTotal, displayedCoalitions: sortRows(state.rows), pivotCounts: state.pivotCounts, pivotShares, warnings: prepared.warnings };
+}
+
+export function analyzeCoalitions(inputs: PartyInput[], threshold: number): CoalitionAnalysis {
+  const prepared = prepareInput(inputs, threshold);
+  if (typeof prepared === 'string') return { valid: false, error: prepared, parties: inputs, totalSeats: 0, threshold, totalCoalitions: 0, winningCoalitions: 0, minimalWinningCoalitions: 0, pivotTotal: 0, displayedCoalitions: [], pivotCounts: {}, pivotShares: {}, warnings: [] };
+  const totals = buildSeatTotals(prepared.parties);
+  return createAnalysis(prepared, enumerate(prepared.parties, prepared.threshold, totals));
+}

package/src/tool/coalition-majority-calculator/seo.astro

@@ -0,0 +1,12 @@
+---
+import { SEORenderer } from '@jjlmoya/utils-shared';
+import { coalitionMajorityCalculator } from './index';
+import type { KnownLocale } from '../../types';
+
+interface Props { locale?: KnownLocale; }
+
+const { locale = 'en' } = Astro.props as Props;
+const content = await coalitionMajorityCalculator.i18n[locale]?.();
+---
+
+{content && <SEORenderer content={{ locale, sections: content.seo }} />}

package/src/tool/coalition-majority-calculator/storage.ts

@@ -0,0 +1,32 @@
+import type { PartyInput } from './logic';
+
+export interface CoalitionSavedState {
+  parties: PartyInput[];
+  threshold: number;
+}
+
+const STORAGE_KEY = 'jjlmoya-civic-coalition-majority';
+
+export function saveCoalitionState(state: CoalitionSavedState): void {
+  try {
+    localStorage.setItem(STORAGE_KEY, JSON.stringify(state));
+  } catch {}
+}
+
+export function loadCoalitionState(): CoalitionSavedState | null {
+  try {
+    const raw = localStorage.getItem(STORAGE_KEY);
+    if (!raw) return null;
+    const parsed = JSON.parse(raw) as CoalitionSavedState;
+    if (!Array.isArray(parsed.parties) || typeof parsed.threshold !== 'number') return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+export function clearCoalitionState(): void {
+  try {
+    localStorage.removeItem(STORAGE_KEY);
+  } catch {}
+}

package/src/tool/coalition-majority-calculator/ui.ts

@@ -0,0 +1,80 @@
+export interface CoalitionMajorityUI {
+  [key: string]: string;
+  addParty: string;
+  allCoalitions: string;
+  calculate: string;
+  chamberSeats: string;
+  coalitionSceneLabel: string;
+  criticalDefections: string;
+  emptyState: string;
+  explanation: string;
+  edgeCasesText: string;
+  edgeCasesTitle: string;
+  filterCoalitions: string;
+  maximumParties: string;
+  majorityThreshold: string;
+  methodTitle: string;
+  methodText: string;
+  minimalCoalition: string;
+  noPivots: string;
+  noMatchingCoalitions: string;
+  none: string;
+  notDoText: string;
+  notDoTitle: string;
+  partyName: string;
+  partySeats: string;
+  partyTable: string;
+  pivotal: string;
+  pivotalParty: string;
+  redundantMembers: string;
+  removeParty: string;
+  reset: string;
+  resultTitle: string;
+  seats: string;
+  surplus: string;
+  surplusCoalition: string;
+  threshold: string;
+  thresholdHint: string;
+  totalCoalitions: string;
+  winningCoalitions: string;
+}
+
+export const ui: CoalitionMajorityUI = {
+  addParty: 'Add party',
+  allCoalitions: 'All winning coalitions',
+  calculate: 'Calculate coalitions',
+  chamberSeats: 'Total seats',
+  coalitionSceneLabel: 'Coalition constellation',
+  criticalDefections: 'Critical defections',
+  emptyState: 'Add at least two parties and enter their seats to see the coalition constellation.',
+  explanation: 'This model treats every listed party as willing to join any combination. It measures seat arithmetic, not political compatibility.',
+  edgeCasesText: 'Blank or duplicate names are made unique. Zero seat parties can never be critical. Above 20 parties the exact search is stopped.',
+  edgeCasesTitle: 'Edge cases and warnings',
+  filterCoalitions: 'Show',
+  maximumParties: 'Maximum 20 parties because exhaustive enumeration grows as 2 to the power of N.',
+  majorityThreshold: 'Majority threshold',
+  methodTitle: 'Model applied',
+  methodText: 'Every non empty subset is checked. A coalition wins at or above the declared threshold. A party is pivotal when removing it makes a winning coalition lose.',
+  minimalCoalition: 'Minimal winning coalition',
+  noMatchingCoalitions: 'No coalitions match this filter.',
+  noPivots: 'No party is pivotal under this threshold.',
+  none: 'None',
+  notDoText: 'It does not assess ideology, policy compatibility, bargaining, legitimacy, stability, or whether a government will form.',
+  notDoTitle: 'What this tool does not do',
+  partyName: 'Party name',
+  partySeats: 'Seats',
+  partyTable: 'Coalition details',
+  pivotal: 'pivotal',
+  pivotalParty: 'Pivotal party',
+  redundantMembers: 'Redundant members',
+  removeParty: 'Remove party',
+  reset: 'Reset example',
+  resultTitle: 'Coalition map',
+  seats: 'seats',
+  surplus: 'surplus',
+  surplusCoalition: 'Surplus coalition',
+  threshold: 'Threshold',
+  thresholdHint: 'A coalition wins when its seats meet or exceed this threshold.',
+  totalCoalitions: 'Possible non-empty coalitions',
+  winningCoalitions: 'Winning coalitions',
+};

package/src/tool/vote-seat-disproportionality-analyzer/bibliography.astro

@@ -0,0 +1,6 @@
+---
+import { Bibliography } from '@jjlmoya/utils-shared';
+import { bibliography } from './bibliography';
+---
+
+<Bibliography links={bibliography} />

package/src/tool/vote-seat-disproportionality-analyzer/bibliography.ts

@@ -0,0 +1,16 @@
+import type { BibliographyEntry } from '../../types';
+
+export const bibliography: BibliographyEntry[] = [
+  {
+    name: 'Michael Gallagher, Proportionality, Disproportionality and Electoral Systems',
+    url: 'https://www.tcd.ie/Political_Science/about/people/michael_gallagher/ElectoralStudies1991.pdf',
+  },
+  {
+    name: 'John Loosemore and Victor J. Hanby, The Theoretical Limits of Maximum Distortion',
+    url: 'https://www.cambridge.org/core/services/aop-cambridge-core/content/view/77CE5C85BDDDE59036B7E91D81FBF87E/S000712340000925Xa.pdf/div-class-title-the-theoretical-limits-of-maximum-distortion-some-analytic-expressions-for-electoral-systems-div.pdf',
+  },
+  {
+    name: 'Universidad de Valladolid, Índices de desproporcionalidad electoral',
+    url: 'https://uvadoc.uva.es/bitstream/handle/10324/71724/TFG-E-2023.pdf?sequence=1',
+  },
+];

package/src/tool/vote-seat-disproportionality-analyzer/component.astro

@@ -0,0 +1,48 @@
+---
+import type { VoteSeatUI } from './ui';
+import './vote-seat-disproportionality-analyzer.css';
+
+interface Props {
+  ui: VoteSeatUI;
+}
+
+const { ui } = Astro.props as Props;
+const initialRows = [
+  { name: 'Cedar', votes: 42000, seats: 8 },
+  { name: 'River', votes: 31000, seats: 5 },
+  { name: 'Lantern', votes: 17000, seats: 2 },
+  { name: 'Common', votes: 10000, seats: 1 },
+];
+---
+
+<div class="vote-seat-tool" data-vote-seat-tool>
+  <div class="comparison-surface">
+    <form class="input-surface" data-vote-seat-form>
+      <section class="input-section" aria-labelledby="vote-seat-input-heading">
+        <div class="section-label"><span class="section-glyph">01</span><h2 id="vote-seat-input-heading">{ui.rowsLabel}</h2></div>
+        <p class="field-help">{ui.rowsHelp}</p>
+        <div class="party-input-list" data-party-list></div>
+        <button class="add-row" type="button" data-add-row>+ {ui.addRow}</button>
+      </section>
+      <div class="form-actions">
+        <button class="primary-action" type="submit">{ui.calculate}</button>
+        <button class="secondary-action" type="button" data-reset>{ui.reset}</button>
+      </div>
+      <p class="tool-status" data-status role="status"></p>
+    </form>
+    <section class="result-surface" aria-live="polite" aria-labelledby="vote-seat-result-heading">
+      <div class="result-heading"><span class="section-glyph">02</span><h2 id="vote-seat-result-heading">{ui.resultLabel}</h2></div>
+      <p class="model-notice">{ui.modelNotice}</p>
+      <div class="empty-result" data-empty-result>{ui.emptyState}</div>
+      <div class="result-content" data-result hidden></div>
+    </section>
+  </div>
+  <script is:inline type="application/json" data-vote-seat-config set:html={JSON.stringify({ ui, initialRows })}></script>
+</div>
+
+<script>
+  import { mountVoteSeatTool } from './controller';
+
+  const root = document.querySelector<HTMLElement>('[data-vote-seat-tool]');
+  if (root) mountVoteSeatTool(root);
+</script>

package/src/tool/vote-seat-disproportionality-analyzer/controller.ts

@@ -0,0 +1,165 @@
+import { calculateDisproportionality, type VoteSeatInput, type VoteSeatRow } from './logic';
+import { renderDisproportionalityResult } from './dom-views';
+import { evaluateDisproportionality } from './evaluator';
+import { clearVoteSeatInput, loadVoteSeatInput, saveVoteSeatInput } from './storage';
+import type { VoteSeatUI } from './ui';
+
+interface Config {
+  ui: VoteSeatUI;
+  initialRows: VoteSeatRow[];
+}
+
+interface InputSpec {
+  label: string;
+  field: string;
+  value: string;
+  type: string;
+  maxLength?: number;
+}
+
+interface Elements {
+  form: HTMLFormElement;
+  list: HTMLElement;
+  result: HTMLElement;
+  empty: HTMLElement;
+  status: HTMLElement;
+}
+
+const readConfig = (root: HTMLElement): Config => {
+  const script = root.querySelector<HTMLScriptElement>('[data-vote-seat-config]');
+  return JSON.parse(script?.textContent ?? '{}') as Config;
+};
+
+const isInput = (value: VoteSeatInput | null): value is VoteSeatInput => Boolean(value?.rows?.length);
+
+const renderRows = (list: HTMLElement, rows: VoteSeatRow[], ui: VoteSeatUI): void => {
+  list.replaceChildren();
+  rows.forEach((row, index) => {
+    const wrapper = document.createElement('div');
+    wrapper.className = 'party-input-row';
+    wrapper.dataset.rowIndex = String(index);
+    const number = document.createElement('span');
+    number.className = 'row-number';
+    number.textContent = String(index + 1).padStart(2, '0');
+    const nameLabel = createInputLabel({ label: ui.partyNameLabel, field: 'name', value: row.name, type: 'text', maxLength: 32 });
+    const votesLabel = createInputLabel({ label: ui.votesLabel, field: 'votes', value: String(row.votes), type: 'number' });
+    const seatsLabel = createInputLabel({ label: ui.seatsLabel, field: 'seats', value: String(row.seats), type: 'number' });
+    const remove = document.createElement('button');
+    remove.type = 'button';
+    remove.className = 'remove-row';
+    remove.dataset.removeRow = 'true';
+    remove.ariaLabel = ui.removeRow;
+    remove.textContent = '×';
+    wrapper.append(number, nameLabel, votesLabel, seatsLabel, remove);
+    list.append(wrapper);
+  });
+};
+
+const createInputLabel = ({ label, field, value, type, maxLength }: InputSpec): HTMLLabelElement => {
+  const wrapper = document.createElement('label');
+  wrapper.className = `input-label input-${field}`;
+  const caption = document.createElement('span');
+  caption.textContent = label;
+  const input = document.createElement('input');
+  input.type = type;
+  input.dataset.field = field;
+  input.value = value;
+  if (maxLength) input.maxLength = maxLength;
+  if (type === 'number') {
+    input.min = '0';
+    input.step = 'any';
+    input.inputMode = 'decimal';
+  }
+  wrapper.append(caption, input);
+  return wrapper;
+};
+
+const readRows = (list: HTMLElement): VoteSeatRow[] => Array.from(list.querySelectorAll<HTMLElement>('[data-row-index]')).map((row) => {
+  const input = (field: string) => row.querySelector<HTMLInputElement>(`[data-field="${field}"]`);
+  return {
+    name: input('name')?.value ?? '',
+    votes: Number(input('votes')?.value ?? Number.NaN),
+    seats: Number(input('seats')?.value ?? Number.NaN),
+  };
+});
+
+const setStatus = (status: HTMLElement, tone: string, message: string): void => {
+  status.className = `tool-status status-${tone}`;
+  status.textContent = message;
+};
+
+const getElements = (root: HTMLElement): Elements | null => {
+  const form = root.querySelector<HTMLFormElement>('[data-vote-seat-form]');
+  const list = root.querySelector<HTMLElement>('[data-party-list]');
+  const result = root.querySelector<HTMLElement>('[data-result]');
+  const empty = root.querySelector<HTMLElement>('[data-empty-result]');
+  const status = root.querySelector<HTMLElement>('[data-status]');
+  return form && list && result && empty && status ? { form, list, result, empty, status } : null;
+};
+
+const renderError = (elements: Elements, ui: VoteSeatUI, error: unknown): void => {
+  elements.result.hidden = true;
+  elements.empty.hidden = false;
+  const message = error instanceof Error ? error.message : 'Enter valid values.';
+  setStatus(elements.status, 'error', `${ui.errorPrefix}: ${message}`);
+};
+
+const createUpdater = (config: Config, elements: Elements): (() => void) => {
+  const update = (): void => {
+    const rows = readRows(elements.list);
+    try {
+      const calculated = calculateDisproportionality({ rows });
+      renderDisproportionalityResult(elements.result, calculated, config.ui, document.documentElement.lang || 'en');
+      elements.result.hidden = false;
+      elements.empty.hidden = true;
+      const state = evaluateDisproportionality(calculated, config.ui);
+      setStatus(elements.status, state.tone, state.text);
+      saveVoteSeatInput({ rows });
+    } catch (error) {
+      renderError(elements, config.ui, error);
+    }
+  };
+  return update;
+};
+
+const bindRowActions = (elements: Elements, ui: VoteSeatUI, update: () => void): void => {
+  elements.list.addEventListener('click', (event) => {
+    const target = event.target as HTMLElement;
+    if (!target.closest('[data-remove-row]')) return;
+    const rows = readRows(elements.list);
+    const row = target.closest<HTMLElement>('[data-row-index]');
+    const index = Number(row?.dataset.rowIndex ?? -1);
+    if (index >= 0 && rows.length > 1) rows.splice(index, 1);
+    renderRows(elements.list, rows, ui);
+    update();
+  });
+};
+
+const bindFormActions = (root: HTMLElement, config: Config, elements: Elements, update: () => void): void => {
+  elements.form.addEventListener('input', update);
+  elements.form.addEventListener('submit', (event) => { event.preventDefault(); update(); });
+  root.querySelector('[data-add-row]')?.addEventListener('click', () => {
+    const rows = readRows(elements.list);
+    rows.push({ name: `List ${rows.length + 1}`, votes: 0, seats: 0 });
+    renderRows(elements.list, rows, config.ui);
+    update();
+  });
+  root.querySelector('[data-reset]')?.addEventListener('click', () => {
+    clearVoteSeatInput();
+    renderRows(elements.list, config.initialRows, config.ui);
+    update();
+  });
+};
+
+export const mountVoteSeatTool = (root: HTMLElement): void => {
+  const config = readConfig(root);
+  const elements = getElements(root);
+  if (!elements) return;
+  const stored = loadVoteSeatInput();
+  const rows = isInput(stored) ? stored.rows : config.initialRows;
+  const update = createUpdater(config, elements);
+  renderRows(elements.list, rows, config.ui);
+  bindFormActions(root, config, elements, update);
+  bindRowActions(elements, config.ui, update);
+  update();
+};

package/src/tool/vote-seat-disproportionality-analyzer/dom-views.ts

@@ -0,0 +1,123 @@
+import type { DisproportionalityResult, PartyDisproportionality } from './logic';
+import type { VoteSeatUI } from './ui';
+
+const make = <K extends keyof HTMLElementTagNameMap>(tag: K, className?: string): HTMLElementTagNameMap[K] => {
+  const element = document.createElement(tag);
+  if (className) element.className = className;
+  return element;
+};
+
+const text = (value: string): Text => document.createTextNode(value);
+
+const addMetric = (parent: HTMLElement, label: string, value: string, accent: string): void => {
+  const metric = make('div', `metric metric-${accent}`);
+  const metricLabel = make('span', 'metric-label');
+  metricLabel.append(text(label));
+  const metricValue = make('strong', 'metric-value');
+  metricValue.append(text(value));
+  metric.append(metricLabel, metricValue);
+  parent.append(metric);
+};
+
+const formatNumber = (value: number, locale: string, maximumFractionDigits = 2): string => new Intl.NumberFormat(locale, {
+  maximumFractionDigits,
+}).format(value);
+
+const formatRatio = (value: number | null, locale: string): string => {
+  if (value === null) return 'n/a';
+  if (value === Infinity) return '∞';
+  return formatNumber(value, locale, 3);
+};
+
+const addRibbon = (parent: HTMLElement, party: PartyDisproportionality, ui: VoteSeatUI, locale: string): void => {
+  const row = make('div', 'share-strip');
+  const name = make('div', 'share-name');
+  name.append(text(party.name));
+  const shares = make('div', 'share-ribbons');
+  const voteRibbon = make('span', 'share-ribbon vote-ribbon');
+  voteRibbon.style.width = `${party.voteSharePercent}%`;
+  voteRibbon.title = `${ui.voteShareLabel}: ${formatNumber(party.voteSharePercent, locale)}%`;
+  const seatRibbon = make('span', 'share-ribbon seat-ribbon');
+  seatRibbon.style.width = `${party.seatSharePercent}%`;
+  seatRibbon.title = `${ui.seatShareLabel}: ${formatNumber(party.seatSharePercent, locale)}%`;
+  shares.append(voteRibbon, seatRibbon);
+  const gap = make('span', 'share-gap');
+  gap.append(text(`${party.differencePercent > 0 ? '+' : ''}${formatNumber(party.differencePercent, locale)} pp`));
+  row.append(name, shares, gap);
+  parent.append(row);
+};
+
+const buildScene = (result: DisproportionalityResult, ui: VoteSeatUI, locale: string): HTMLElement => {
+  const scene = make('div', 'press-scene');
+  const sceneLegend = make('div', 'scene-legend');
+  sceneLegend.append(text(`${ui.voteShareLabel}  /  ${ui.seatShareLabel}`));
+  scene.append(sceneLegend);
+  result.parties.forEach((party) => addRibbon(scene, party, ui, locale));
+  return scene;
+};
+
+const buildHeaders = (ui: VoteSeatUI): HTMLTableRowElement => {
+  const row = make('tr');
+  [ui.partyNameLabel, ui.voteShareLabel, ui.seatShareLabel, ui.differenceLabel, ui.ratioLabel, ui.directionLabel].forEach((label) => {
+    const cell = make('th');
+    cell.scope = 'col';
+    cell.append(text(label));
+    row.append(cell);
+  });
+  return row;
+};
+
+const buildBody = (result: DisproportionalityResult, ui: VoteSeatUI, locale: string): HTMLTableSectionElement => {
+  const body = make('tbody');
+  result.parties.forEach((party) => {
+    const row = make('tr');
+    [
+      party.name,
+      `${formatNumber(party.voteSharePercent, locale)}%`,
+      `${formatNumber(party.seatSharePercent, locale)}%`,
+      `${party.differencePercent > 0 ? '+' : ''}${formatNumber(party.differencePercent, locale)} pp`,
+      formatRatio(party.voteToSeatRatio, locale),
+      ui[party.direction],
+    ].forEach((value) => {
+      const cell = make('td');
+      cell.append(text(value));
+      row.append(cell);
+    });
+    body.append(row);
+  });
+  return body;
+};
+
+const buildDetail = (result: DisproportionalityResult, ui: VoteSeatUI, locale: string): HTMLElement => {
+  const section = make('section', 'detail-section');
+  const heading = make('h3', 'detail-heading');
+  heading.append(text(ui.detailLabel));
+  const table = make('table', 'detail-table');
+  const head = make('thead');
+  head.append(buildHeaders(ui));
+  table.append(head, buildBody(result, ui, locale));
+  section.append(heading, table);
+  return section;
+};
+
+export const renderDisproportionalityResult = (element: HTMLElement, result: DisproportionalityResult, ui: VoteSeatUI, locale: string): void => {
+  const wrapper = make('div', 'result-stack');
+  const metrics = make('div', 'metrics-grid');
+  addMetric(metrics, ui.gallagherLabel, formatNumber(result.gallagherIndex, locale, 2), 'gallagher');
+  addMetric(metrics, ui.loosemoreHanbyLabel, formatNumber(result.loosemoreHanbyIndex, locale, 2), 'loosemore');
+  addMetric(metrics, ui.sainteLagueLabel, formatNumber(result.sainteLagueIndex, locale, 3), 'sainte');
+  addMetric(metrics, ui.maxGapLabel, `${formatNumber(result.maxAbsoluteDifferencePercent, locale, 2)} pp`, 'gap');
+  const totals = make('p', 'totals-line');
+  totals.append(text(`${ui.totalVotesLabel}: ${formatNumber(result.totalVotes, locale)}  ·  ${ui.totalSeatsLabel}: ${formatNumber(result.totalSeats, locale)}`));
+  const guide = make('p', 'result-guide');
+  guide.append(text(ui.resultGuide));
+  const scene = buildScene(result, ui, locale);
+  const note = make('p', 'model-note');
+  note.append(text(ui.proportionNote));
+  const zeroVote = result.sainteLagueRows < result.parties.length ? make('p', 'model-note model-note-caution') : null;
+  zeroVote?.append(text(ui.zeroVoteNote));
+  wrapper.append(metrics, totals, guide, scene, note);
+  if (zeroVote) wrapper.append(zeroVote);
+  wrapper.append(buildDetail(result, ui, locale));
+  element.replaceChildren(wrapper);
+};

package/src/tool/vote-seat-disproportionality-analyzer/entry.ts

@@ -0,0 +1,29 @@
+import type { CivicToolEntry, ToolLocaleContent } from '../../types';
+import type { VoteSeatUI } from './ui';
+
+export type { VoteSeatUI } from './ui';
+
+export type VoteSeatLocaleContent = ToolLocaleContent<VoteSeatUI>;
+
+export const voteSeatDisproportionalityAnalyzer: CivicToolEntry<VoteSeatUI> = {
+  id: 'vote-seat-disproportionality-analyzer',
+  phase: 'localized',
+  icons: { bg: 'mdi:chart-box-outline', fg: 'mdi:scale-balance' },
+  i18n: {
+    de: () => import('./i18n/de').then((module) => module.content),
+    en: () => import('./i18n/en').then((module) => module.content),
+    es: () => import('./i18n/es').then((module) => module.content),
+    fr: () => import('./i18n/fr').then((module) => module.content),
+    id: () => import('./i18n/id').then((module) => module.content),
+    it: () => import('./i18n/it').then((module) => module.content),
+    ja: () => import('./i18n/ja').then((module) => module.content),
+    ko: () => import('./i18n/ko').then((module) => module.content),
+    nl: () => import('./i18n/nl').then((module) => module.content),
+    pl: () => import('./i18n/pl').then((module) => module.content),
+    pt: () => import('./i18n/pt').then((module) => module.content),
+    ru: () => import('./i18n/ru').then((module) => module.content),
+    sv: () => import('./i18n/sv').then((module) => module.content),
+    tr: () => import('./i18n/tr').then((module) => module.content),
+    zh: () => import('./i18n/zh').then((module) => module.content),
+  },
+};