@jjlmoya/utils-civic 1.1.0 → 1.2.0

package/src/tool/vote-seat-disproportionality-analyzer/i18n/zh.ts

@@ -0,0 +1,10 @@
+import type { FAQPage, HowTo, SoftwareApplication } from 'schema-dts';
+import type { ToolLocaleContent } from '../../../types';
+import { bibliography } from '../bibliography';
+import type { VoteSeatLocaleContent } from '../entry';
+const ui = { rowsLabel: '按政党或名单查看选票和席位', rowsHelp: '为相同的政党输入获得的选票和赢得的席位。每一列分别进行标准化。', partyNameLabel: '政党或名单', votesLabel: '选票', seatsLabel: '席位', addRow: '添加政党或名单', removeRow: '删除政党或名单', calculate: '测量差距', reset: '加载示例', resultLabel: '比例性压力', emptyState: '输入选票和席位，然后测量差距。', modelNotice: '模型比较得票率和席位率，不判断公平性、意识形态、合法性或选举质量。', totalVotesLabel: '选票总数', totalSeatsLabel: '席位总数', gallagherLabel: '加拉格尔指数', loosemoreHanbyLabel: '卢斯莫尔-汉比指数', sainteLagueLabel: '圣拉古指数', maxGapLabel: '最大份额差距', voteShareLabel: '得票率', seatShareLabel: '席位率', differenceLabel: '席位率减得票率', ratioLabel: '得票率与席位率之比', directionLabel: '解读', overrepresented: '席位率高于得票率', underrepresented: '席位率低于得票率', aligned: '份额一致', detailLabel: '政党详情', zeroVoteNote: '圣拉古指数的分母只使用至少有一票的行。没有选票的行仍会显示在其他指标中。', proportionNote: '指数越低，两个分布越接近。这些是描述性指标，不是法律阈值。', errorPrefix: '检查输入', exactParity: '完全一致: 每个得票率都等于对应的席位率。', resultGuide: '逐行阅读色带: 选票标记和席位标记之间的距离就是该政党的差距。' };
+const softwareApplication: SoftwareApplication = { '@type': 'SoftwareApplication', name: '选票与席位不均衡分析器', applicationCategory: 'EducationalApplication', operatingSystem: 'Any', description: '使用透明的选举数据测量得票率和席位率之间的差距。', url: 'https://gamebob.dev/zh/piao-shu-xi-shu-bili-shi-fenxi', offers: { '@type': 'Offer', price: '0', priceCurrency: 'USD' } };
+const faqPage: FAQPage = { '@type': 'FAQPage', mainEntity: [{ '@type': 'Question', name: '这个分析测量什么？', acceptedAnswer: { '@type': 'Answer', text: '它比较每个政党的得票率和席位率，并用加拉格尔、卢斯莫尔-汉比和圣拉古指数概括差距。它不判断结果是否公平或合法。' } }, { '@type': 'Question', name: '为什么选票和席位的总数可以不同？', acceptedAnswer: { '@type': 'Answer', text: '它们是不同的单位。选票按选票总数标准化，席位按席位总数标准化。' } }, { '@type': 'Question', name: '如何解读得票率与席位率之比？', acceptedAnswer: { '@type': 'Answer', text: '这是得票率除以席位率。1表示一致，大于1表示席位率相对较低。' } }, { '@type': 'Question', name: '结果能证明选举制度不公平吗？', acceptedAnswer: { '@type': 'Answer', text: '不能。指数只描述两个分布之间的距离，还需要结合选区、门槛和分母来理解。' } }] };
+const howTo: HowTo = { '@type': 'HowTo', name: '测量选票与席位的不均衡', step: [{ '@type': 'HowToStep', name: '输入政党', text: '为每个政党或名单添加一行。' }, { '@type': 'HowToStep', name: '输入选票和席位', text: '使用相同的选举范围并输入观测到的总数。' }, { '@type': 'HowToStep', name: '测量差距', text: '运行分析，标准化两列并计算指数。' }, { '@type': 'HowToStep', name: '阅读色带', text: '比较每一行的份额、差距和比率。' }, { '@type': 'HowToStep', name: '检查背景', text: '阅读公式并核对适用的选举规则。' }] };
+export const content: ToolLocaleContent<VoteSeatLocaleContent['ui']> = { slug: 'vote-seat-disproportionality-analyzer', title: '选票与席位不均衡分析器', description: '根据透明的选举数据，使用加拉格尔、卢斯莫尔-汉比和圣拉古指数比较得票率与席位率。', ui, seo: [{ type: 'title', text: '测量选票与席位之间的差距', level: 2 }, { type: 'paragraph', html: '一次选举可能让某个政党的席位率与得票率大不相同。本分析把两个观测到的分布变得可比较，并显示哪些政党相对于所得选票获得了更多或更少的代表性。选票和席位分别标准化。' }, { type: 'paragraph', html: '结果不是裁决。正差距表示席位率更高，负差距表示席位率更低。色带会先显示方向，再展示汇总指数。' }, { type: 'title', text: '三个指数分别说明什么', level: 2 }, { type: 'paragraph', html: '加拉格尔指数是百分点差距平方和一半的平方根，因此较大的偏差权重更高。卢斯莫尔-汉比指数把绝对差距相加后除以二。' }, { type: 'paragraph', html: '圣拉古指数使用各项份额，并将差距平方除以每个有选票行的得票率。没有选票的行无法提供这个分母，因此只保留在另外两个指标中。' }, { type: 'table', headers: ['指标', '计算方式', '有用的问题'], rows: [['加拉格尔', '百分点差距平方和一半的平方根。', '哪些大差距主导整体距离？'], ['卢斯莫尔-汉比', '绝对百分点差距总和的一半。', '整体分布相差多少？'], ['圣拉古', '份额差距平方除以得票率。', '分母如何影响小党？']] }, { type: 'title', text: '准备可比较的选举数据', level: 2 }, { type: 'paragraph', html: '使用相同的选举范围，不要把全国选票与地区席位混在一起。总数不必相同，但每一行必须描述同一个政党和同一个结果。' }, { type: 'list', items: ['在两列中清楚标出同一个对象。', '包含有选票但没有席位的政党。', '只有在数据中有记录时才使用零。', '确认有效票、无效票或排除票哪些应进入分母。', '将指数和数据来源一起保存，以便复现结果。'] }, { type: 'tip', title: '比率不是原因', html: '大于1表示席位率低于得票率。选区规模、门槛、地域集中度、投票率和席位分配公式都可能造成差距。' }, { type: 'title', text: '比较前了解限制', level: 2 }, { type: 'paragraph', html: '较低的数值只表示输入的分布更加接近，并不自动表示选举制度更好。只比较对选票、席位、政党、地区和分母有兼容定义的数据。' }, { type: 'paragraph', html: '本分析不推断意识形态、意图、协议、法律合规性或民主合法性，也不会修正官方结果或重建某个地区的计票过程。' }, { type: 'tip', title: '从距离最远的色带开始', html: '先检查差距最大的政党，比较原始数值，然后确认每一行都按相同方式处理。' }], faq: [{ question: '分析测量什么？', answer: '它比较得票率和席位率，并用三个指数概括距离。' }, { question: '为什么总数不同？', answer: '选票和席位是不同单位，各自使用自己的总数标准化。' }, { question: '如何阅读比率？', answer: '得票率除以席位率，1表示一致。' }, { question: '这是不公平的证据吗？', answer: '不是。它描述距离，需要结合选举规则来解释。' }], bibliography, howTo: [{ name: '输入政党', text: '为每个政党或名单添加一行。' }, { name: '输入数值', text: '输入相同范围内的选票和席位。' }, { name: '测量差距', text: '运行分析并计算指数。' }, { name: '阅读色带', text: '比较份额和差距。' }, { name: '检查背景', text: '核对适用的选举规则。' }], schemas: [softwareApplication, faqPage, howTo] as unknown as Record<string, unknown>[] };
+export const chineseContent: VoteSeatLocaleContent = content;

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

@@ -0,0 +1,11 @@
+import type { ToolDefinition } from '../../types';
+import { voteSeatDisproportionalityAnalyzer } from './entry';
+
+export * from './entry';
+export * from './logic';
+export const VOTE_SEAT_DISPROPORTIONALITY_ANALYZER_TOOL: ToolDefinition = {
+  entry: voteSeatDisproportionalityAnalyzer,
+  Component: () => import('./component.astro'),
+  SEOComponent: () => import('./seo.astro'),
+  BibliographyComponent: () => import('./bibliography.astro'),
+};

package/src/tool/vote-seat-disproportionality-analyzer/logic.test.ts

@@ -0,0 +1,61 @@
+import { describe, expect, it } from 'vitest';
+import { calculateDisproportionality } from './logic';
+
+describe('calculateDisproportionality', () => {
+  it('returns zero indices for a proportional result', () => {
+    const result = calculateDisproportionality({ rows: [
+      { name: 'North', votes: 60, seats: 6 },
+      { name: 'South', votes: 40, seats: 4 },
+    ] });
+    expect(result.gallagherIndex).toBe(0);
+    expect(result.loosemoreHanbyIndex).toBe(0);
+    expect(result.sainteLagueIndex).toBe(0);
+    expect(result.parties[0]?.voteToSeatRatio).toBe(1);
+  });
+
+  it('normalizes votes and seats with their own totals', () => {
+    const result = calculateDisproportionality({ rows: [
+      { name: 'Alpha', votes: 600, seats: 2 },
+      { name: 'Beta', votes: 400, seats: 8 },
+    ] });
+    expect(result.totalVotes).toBe(1000);
+    expect(result.totalSeats).toBe(10);
+    expect(result.parties[0]?.voteSharePercent).toBe(60);
+    expect(result.parties[0]?.seatSharePercent).toBe(20);
+    expect(result.parties[0]?.differencePercent).toBe(-40);
+    expect(result.parties[0]?.direction).toBe('underrepresented');
+    expect(result.gallagherIndex).toBe(40);
+    expect(result.loosemoreHanbyIndex).toBe(40);
+  });
+
+  it('handles zero votes and zero seats explicitly', () => {
+    const result = calculateDisproportionality({ rows: [
+      { name: 'Absent', votes: 0, seats: 0 },
+      { name: 'Winner', votes: 100, seats: 10 },
+    ] });
+    expect(result.parties[0]?.voteToSeatRatio).toBeNull();
+    expect(result.parties[1]?.voteToSeatRatio).toBe(1);
+    expect(result.sainteLagueRows).toBe(1);
+  });
+
+  it('shows infinite vote to seat ratio for a vote-only row', () => {
+    const result = calculateDisproportionality({ rows: [
+      { name: 'Unseated', votes: 25, seats: 0 },
+      { name: 'Seated', votes: 75, seats: 10 },
+    ] });
+    expect(result.parties[0]?.voteToSeatRatio).toBe(Infinity);
+    expect(result.parties[0]?.direction).toBe('underrepresented');
+  });
+
+  it('rejects empty, invalid, duplicate and zero-total input', () => {
+    expect(() => calculateDisproportionality({ rows: [] })).toThrow('at least one party');
+    expect(() => calculateDisproportionality({ rows: [{ name: 'A', votes: 1, seats: 0 }] })).toThrow('at least one seat');
+    expect(() => calculateDisproportionality({ rows: [{ name: 'A', votes: 0, seats: 1 }] })).toThrow('at least one vote');
+    expect(() => calculateDisproportionality({ rows: [
+      { name: 'A', votes: -1, seats: 1 }, { name: 'a', votes: 1, seats: 1 },
+    ] })).toThrow('positive number');
+    expect(() => calculateDisproportionality({ rows: [
+      { name: 'A', votes: 1, seats: 1 }, { name: ' a ', votes: 1, seats: 1 },
+    ] })).toThrow('unique');
+  });
+});

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

@@ -0,0 +1,119 @@
+export interface VoteSeatRow {
+  name: string;
+  votes: number;
+  seats: number;
+}
+
+export interface VoteSeatInput {
+  rows: VoteSeatRow[];
+}
+
+export type RepresentationDirection = 'overrepresented' | 'underrepresented' | 'aligned';
+
+export interface PartyDisproportionality {
+  name: string;
+  votes: number;
+  seats: number;
+  voteSharePercent: number;
+  seatSharePercent: number;
+  differencePercent: number;
+  voteToSeatRatio: number | null;
+  direction: RepresentationDirection;
+}
+
+export interface DisproportionalityResult {
+  totalVotes: number;
+  totalSeats: number;
+  parties: PartyDisproportionality[];
+  gallagherIndex: number;
+  loosemoreHanbyIndex: number;
+  sainteLagueIndex: number;
+  sainteLagueRows: number;
+  maxAbsoluteDifferencePercent: number;
+  largestGapParty: string;
+}
+
+const EPSILON = 1e-9;
+
+const roundValue = (value: number, digits = 6): number => {
+  const factor = 10 ** digits;
+  return Math.round(value * factor) / factor;
+};
+
+const assertRows = (rows: VoteSeatRow[]): void => {
+  if (!Array.isArray(rows) || rows.length === 0) throw new RangeError('Enter at least one party or list.');
+  const names = new Set<string>();
+  rows.forEach((row) => {
+    const name = row.name.trim();
+    if (!name) throw new RangeError('Each row needs a party or list name.');
+    const key = name.toLocaleLowerCase();
+    if (names.has(key)) throw new RangeError('Party or list names must be unique.');
+    if (!Number.isFinite(row.votes) || row.votes < 0) throw new RangeError('Votes must be zero or a positive number.');
+    if (!Number.isFinite(row.seats) || row.seats < 0) throw new RangeError('Seats must be zero or a positive number.');
+    names.add(key);
+  });
+};
+
+const assertTotals = (rows: VoteSeatRow[]): { totalVotes: number; totalSeats: number } => {
+  const totalVotes = rows.reduce((sum, row) => sum + row.votes, 0);
+  const totalSeats = rows.reduce((sum, row) => sum + row.seats, 0);
+  if (totalVotes <= 0) throw new RangeError('Enter at least one vote before calculating.');
+  if (totalSeats <= 0) throw new RangeError('Enter at least one seat before calculating.');
+  return { totalVotes, totalSeats };
+};
+
+const getDirection = (differencePercent: number): RepresentationDirection => {
+  if (Math.abs(differencePercent) < EPSILON) return 'aligned';
+  return differencePercent > 0 ? 'overrepresented' : 'underrepresented';
+};
+
+const getRatio = (voteShare: number, seatShare: number): number | null => {
+  if (voteShare === 0 && seatShare === 0) return null;
+  if (seatShare === 0) return Infinity;
+  return roundValue(voteShare / seatShare, 6);
+};
+
+const buildParty = (row: VoteSeatRow, totalVotes: number, totalSeats: number): PartyDisproportionality => {
+  const voteShare = row.votes / totalVotes;
+  const seatShare = row.seats / totalSeats;
+  const differencePercent = roundValue((seatShare - voteShare) * 100, 6);
+  return {
+    name: row.name.trim(),
+    votes: row.votes,
+    seats: row.seats,
+    voteSharePercent: roundValue(voteShare * 100, 6),
+    seatSharePercent: roundValue(seatShare * 100, 6),
+    differencePercent,
+    voteToSeatRatio: getRatio(voteShare, seatShare),
+    direction: getDirection(differencePercent),
+  };
+};
+
+const getSainteLagueIndex = (parties: PartyDisproportionality[], totalVotes: number, totalSeats: number): number => parties.reduce((sum, party) => {
+  if (party.votes === 0) return sum;
+  const voteShare = party.votes / totalVotes;
+  const seatShare = party.seats / totalSeats;
+  return sum + ((seatShare - voteShare) ** 2) / voteShare;
+}, 0);
+
+export const calculateDisproportionality = (input: VoteSeatInput): DisproportionalityResult => {
+  assertRows(input.rows);
+  const { totalVotes, totalSeats } = assertTotals(input.rows);
+  const parties = input.rows.map((row) => buildParty(row, totalVotes, totalSeats));
+  const gaps = parties.map((party) => Math.abs(party.differencePercent));
+  const maxAbsoluteDifferencePercent = Math.max(...gaps);
+  const largestGapParty = parties.find((party) => Math.abs(party.differencePercent) === maxAbsoluteDifferencePercent)?.name ?? '';
+  const gallagherIndex = Math.sqrt(0.5 * parties.reduce((sum, party) => sum + party.differencePercent ** 2, 0));
+  const loosemoreHanbyIndex = 0.5 * parties.reduce((sum, party) => sum + Math.abs(party.differencePercent), 0);
+  return {
+    totalVotes,
+    totalSeats,
+    parties,
+    gallagherIndex: roundValue(gallagherIndex),
+    loosemoreHanbyIndex: roundValue(loosemoreHanbyIndex),
+    sainteLagueIndex: roundValue(getSainteLagueIndex(parties, totalVotes, totalSeats)),
+    sainteLagueRows: parties.filter((party) => party.votes > 0).length,
+    maxAbsoluteDifferencePercent: roundValue(maxAbsoluteDifferencePercent),
+    largestGapParty,
+  };
+};

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

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

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

@@ -0,0 +1,28 @@
+import type { VoteSeatInput } from './logic';
+
+const STORAGE_KEY = 'civic-vote-seat-disproportionality';
+
+export const loadVoteSeatInput = (): VoteSeatInput | null => {
+  try {
+    const raw = localStorage.getItem(STORAGE_KEY);
+    return raw ? JSON.parse(raw) as VoteSeatInput : null;
+  } catch {
+    return null;
+  }
+};
+
+export const saveVoteSeatInput = (input: VoteSeatInput): void => {
+  try {
+    localStorage.setItem(STORAGE_KEY, JSON.stringify(input));
+  } catch {
+    return;
+  }
+};
+
+export const clearVoteSeatInput = (): void => {
+  try {
+    localStorage.removeItem(STORAGE_KEY);
+  } catch {
+    return;
+  }
+};

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

@@ -0,0 +1,70 @@
+export interface VoteSeatUI {
+  [key: string]: string;
+  rowsLabel: string;
+  rowsHelp: string;
+  partyNameLabel: string;
+  votesLabel: string;
+  seatsLabel: string;
+  addRow: string;
+  removeRow: string;
+  calculate: string;
+  reset: string;
+  resultLabel: string;
+  emptyState: string;
+  modelNotice: string;
+  totalVotesLabel: string;
+  totalSeatsLabel: string;
+  gallagherLabel: string;
+  loosemoreHanbyLabel: string;
+  sainteLagueLabel: string;
+  maxGapLabel: string;
+  voteShareLabel: string;
+  seatShareLabel: string;
+  differenceLabel: string;
+  ratioLabel: string;
+  directionLabel: string;
+  overrepresented: string;
+  underrepresented: string;
+  aligned: string;
+  detailLabel: string;
+  zeroVoteNote: string;
+  proportionNote: string;
+  errorPrefix: string;
+  exactParity: string;
+  resultGuide: string;
+}
+
+export const ui: VoteSeatUI = {
+  rowsLabel: 'Votes and seats by party or list',
+  rowsHelp: 'Enter the votes received and seats won for the same set of parties. Each column is normalized separately.',
+  partyNameLabel: 'Party or list',
+  votesLabel: 'Votes',
+  seatsLabel: 'Seats',
+  addRow: 'Add party or list',
+  removeRow: 'Remove party or list',
+  calculate: 'Measure the gap',
+  reset: 'Load example',
+  resultLabel: 'Proportionality press',
+  emptyState: 'Enter votes and seats, then measure the gap.',
+  modelNotice: 'The model compares vote share with seat share. It does not judge fairness, ideology, legality, or election quality.',
+  totalVotesLabel: 'Total votes',
+  totalSeatsLabel: 'Total seats',
+  gallagherLabel: 'Gallagher index',
+  loosemoreHanbyLabel: 'Loosemore-Hanby',
+  sainteLagueLabel: 'Sainte-Lague index',
+  maxGapLabel: 'Largest share gap',
+  voteShareLabel: 'Vote share',
+  seatShareLabel: 'Seat share',
+  differenceLabel: 'Seat share minus vote share',
+  ratioLabel: 'Vote to seat ratio',
+  directionLabel: 'Reading',
+  overrepresented: 'More seats than vote share',
+  underrepresented: 'Fewer seats than vote share',
+  aligned: 'Shares align',
+  detailLabel: 'Party detail',
+  zeroVoteNote: 'Sainte-Lague uses only rows with at least one vote in its denominator. Zero-vote rows remain visible in the other measures.',
+  proportionNote: 'Lower index values mean the two distributions are closer. The values are descriptive measures, not a legal threshold.',
+  errorPrefix: 'Check the input',
+  exactParity: 'Exact parity: every vote share matches its seat share.',
+  resultGuide: 'Read the ribbons row by row: the distance between the vote and seat marks is the party-level gap.',
+};