@jjlmoya/utils-civic 1.3.0 → 1.5.0

package/src/tool/referendum-threshold-calculator/i18n/zh.ts

@@ -0,0 +1,56 @@
+import type { FAQPage, HowTo, SoftwareApplication } from 'schema-dts';
+import type { ToolLocaleContent } from '../../../types';
+import { bibliography } from '../bibliography';
+import type { ReferendumThresholdLocaleContent } from '../entry';
+import type { ReferendumThresholdUI } from '../ui';
+
+const ui: ReferendumThresholdUI = {
+  countsHeading: '输入公布的票数', eligibleLabel: '有投票资格或已登记的选民', eligibleHelp: '使用所检查规则中指定的选民范围。', yesLabel: '赞成票', noLabel: '反对票', blankLabel: '空白票', invalidLabel: '无效票', participationHeading: '参与门槛', participationHelp: '选择哪些票计入参与，以及必须达到的门槛。', approvalHeading: '赞成门槛', approvalHelp: '选择赞成票的分母。每条规则都会显示在结果中。', thresholdModeLabel: '门槛类型', comparisonLabel: '比较方式', atLeastOption: '至少', moreThanOption: '超过', percentageOption: '百分比', absoluteOption: '绝对数量', thresholdValueLabel: '门槛数值', denominatorLabel: '使用的计数', allBallotsOption: '所有选票', validVotesOption: '仅有效票', eligibleVotersOption: '有投票资格的选民', presetsLabel: '赞成预设', simpleMajorityPreset: '简单多数', electorateMajorityPreset: '选民多数', qualified55Preset: '55%特别多数', qualified60Preset: '60%特别多数', loadExample: '加载示例', shareAction: '复制永久链接', shareSuccess: '永久链接已复制，包含票数和两条规则。', shareFailure: '永久链接已显示在地址栏中。', resultHeading: '按照公布规则作出判断', emptyResult: '输入票数和门槛即可查看两项检验。', passed: '两项门槛都已达到', participationFailed: '未达到参与门槛', approvalFailed: '未达到赞成门槛', bothFailed: '两项门槛都未达到', invalidResult: '请检查公布的票数', participationMetric: '参与检验', approvalMetric: '赞成检验', observedLabel: '实际值', thresholdLabel: '要求值', decisionPathLabel: '判断路径', methodHeading: '采用的方法', methodText: '参与率是所选参与数量除以选民数量。赞成率是赞成票除以所选分母。比较方式决定相等是否足够，还是必须超过门槛。绝对门槛直接比较数量。', limitsHeading: '本工具不会做什么', limitsText: '它不会确定主管机关、认证计票结果、判断法定期限或提供法律建议。结果取决于输入的前提。', warningsHeading: '边界情况和数据提示', warningsText: '请确认空白票和无效票是否计入参与，选民数量是否为最新，以及赞成规则使用有效票、所有选票还是选民作为分母。', invalidInput: '请输入非负整数。选民数必须大于零，选票数不能超过选民数。', ballotsExceedEligible: '公布的选票数超过选民数。', noValidVotes: '没有赞成票或反对票，因此不存在有效票分母。', noBallots: '尚未公布选票数。', peopleSuffix: '人', yesShareLabel: '赞成票比例', allBallotsLabel: '所有选票', validVotesLabel: '有效票', eligibleVotersLabel: '选民', whatNextLabel: '使用结果前', whatNextText: '复制适用规则的准确文字，并与页面显示的配置进行比较。',
+};
+
+const softwareApplication: SoftwareApplication = { '@type': 'SoftwareApplication', name: '公投门槛计算器', applicationCategory: 'EducationalApplication', operatingSystem: 'Any', description: '显示分子和分母，检查参与和赞成门槛。', url: 'https://gamebob.dev/zh/vote-referendum-threshold-calculator', offers: { '@type': 'Offer', price: '0', priceCurrency: 'CNY' } };
+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: '它们可能计入参与，却被排除在有效票之外。工具会分别显示每个分母。' } },
+  { '@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<ReferendumThresholdLocaleContent['ui']> = {
+  slug: 'referendum-threshold-calculator', title: '公投门槛计算器', description: '清楚显示每个分子、分母和规则，检查公投的参与及赞成门槛。', ui, seo: [
+    { type: 'title', text: '用可见分母检查公投规则', level: 2 },
+    { type: 'paragraph', html: '公投结果看似简单，但分母会改变它的含义。本计算器把选民数、选票类别以及参与和赞成两项门槛放在同一份可核查的结果中。' },
+    { type: 'paragraph', html: '参与和赞成是不同的检验。空白票和无效票可能增加参与数量，却不属于有效票。工具不会默默替你选择这种定义。' },
+    { type: 'title', text: '两项门槛如何运作', level: 2 },
+    { type: 'paragraph', html: '参与率用所选参与票数除以选民数。赞成率用赞成票除以所选分母。比较方式可以接受相等，也可以要求实际值超过门槛。' },
+    { type: 'table', headers: ['检验', '实际值', '需要回答的问题'], rows: [['参与', '所选选票 / 选民', '是否有足够比例的选民参加？'], ['赞成', '赞成 / 所选分母', '赞成票是否达到规定门槛？']] },
+    { type: 'title', text: '准备票数时不要混淆定义', level: 2 },
+    { type: 'paragraph', html: '请使用同一次投票和同一版本选民名册中的数字。选择分母之前，把赞成、反对、空白和无效票分开记录，这样每个数字都能追溯。' },
+    { type: 'list', items: ['确认规则指的是登记选民还是有投票资格的选民。', '分别记录四类选票。', '确认选票总数没有超过选民数。', '记录每个百分比使用的分母。', '把官方规则原文与计算结果一起保存。'] },
+    { type: 'tip', title: '分母是规则的一部分', html: '有效票中的50%与所有选票或全部选民中的50%不是同一项检验。空白票和无效票可能改变判断。' },
+    { type: 'title', text: '理解通过和失败状态', level: 2 },
+    { type: 'paragraph', html: '结果会区分参与失败和赞成失败。如果参与通过而赞成失败，请检查赞成票及其分母。如果相反，则参与条件尚未满足。' },
+    { type: 'paragraph', html: '计算通过不等于法律结论。不同法域可能有特殊条件、地区条件，或对空白票和无效票采用不同的官方处理方式。工具只评估输入的配置。' },
+    { type: 'tip', title: '把结果当作核对表', html: '发布结论前，把每个分子、分母、模式和比较方式与现行规则逐项核对。如果定义不清，请保留提示，不要给出过度确定的结论。' },
+    { type: 'title', text: '资料和限制', level: 2 },
+    { type: 'paragraph', html: 'International IDEA 说明参与和赞成规则为何应当预先明确。威尼斯委员会讨论门槛设计的影响。这些资料支持核查方法，但不提供适用于所有国家的统一门槛。' },
+  ], faq: [
+    { question: '这个计算器判断什么？', answer: '它把票数与输入的参与和赞成门槛进行比较，但不会判断哪项法律规则适用。' },
+    { question: '参与和赞成有什么区别？', answer: '参与检验是否有足够的人或选票达到门槛。赞成检验赞成票是否达到规定的数量或比例。' },
+    { question: '为什么空白票和无效票会改变结果？', answer: '它们可能计入参与，却被排除在有效票之外。工具会分别显示每个分母。' },
+    { question: '通过结果能证明法律有效吗？', answer: '不能。请查看宪法、法律、官方指引、选票定义和计票机关。' },
+  ], bibliography, howTo: [
+    { name: '输入选民数', text: '输入规则所使用的登记选民或有投票资格的选民数。' },
+    { name: '分开票数', text: '输入同一公投中的赞成、反对、空白和无效票。' },
+    { name: '设定参与规则', text: '选择计数方式以及百分比或绝对参与门槛。' },
+    { name: '设定赞成规则', text: '选择分母和赞成票的要求。' },
+    { name: '阅读两项检验', text: '检查分子、分母、比例、门槛和数据提示。' },
+  ], schemas: [softwareApplication, faqPage, howTo] as unknown as Record<string, unknown>[]
+};

package/src/tool/referendum-threshold-calculator/index.ts

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

package/src/tool/referendum-threshold-calculator/logic.test.ts

@@ -0,0 +1,69 @@
+import { describe, expect, it } from 'vitest';
+import { evaluateReferendum, getExampleInput, type ReferendumInput } from './logic';
+
+const withChanges = (changes: Partial<ReferendumInput['counts']>): ReferendumInput => ({ ...getExampleInput(), counts: { ...getExampleInput().counts, ...changes } });
+
+describe('referendum threshold logic', () => {
+  it('passes the documented example with inclusive percentage thresholds', () => {
+    const result = evaluateReferendum(getExampleInput());
+    expect(result.status).toBe('passed');
+    expect(result.participation).toMatchObject({ numerator: 850, denominator: 1000, rate: 85, passed: true });
+    expect(result.approval).toMatchObject({ numerator: 520, denominator: 820, passed: true });
+  });
+
+  it('keeps blank and invalid ballots in all ballots but not valid votes', () => {
+    const result = evaluateReferendum(withChanges({ yes: 10, no: 10, blank: 30, invalid: 50 }));
+    expect(result.totals).toEqual({ allBallots: 100, validVotes: 20, participationCount: 100 });
+    expect(result.approval.denominator).toBe(20);
+  });
+
+  it('distinguishes participation failure from approval failure', () => {
+    const participation = evaluateReferendum(withChanges({ yes: 200, no: 100, blank: 10, invalid: 0 }));
+    expect(participation.status).toBe('participation-failed');
+    const approval = evaluateReferendum({ ...withChanges({ yes: 300, no: 500, blank: 20, invalid: 10 }), rules: { ...getExampleInput().rules, approval: { mode: 'percentage', value: 50, denominator: 'valid-votes' } } });
+    expect(approval.status).toBe('approval-failed');
+  });
+
+  it('supports absolute participation and approval thresholds', () => {
+    const input = getExampleInput();
+    input.rules = { participation: { mode: 'absolute', value: 800, denominator: 'all-ballots' }, approval: { mode: 'absolute', value: 500, denominator: 'valid-votes' } };
+    const result = evaluateReferendum(input);
+    expect(result.status).toBe('passed');
+  });
+
+  it('supports approval thresholds over the electorate and strict majorities', () => {
+    const input = getExampleInput();
+    input.rules.approval = { mode: 'percentage', value: 50, denominator: 'eligible-voters', comparison: 'more-than' };
+    const result = evaluateReferendum(input);
+    expect(result.approval).toMatchObject({ numerator: 520, denominator: 1000, rate: 52, passed: true });
+    input.counts.yes = 500;
+    input.counts.no = 300;
+    expect(evaluateReferendum(input).approval.passed).toBe(false);
+  });
+
+  it('fails safely when approval has no denominator', () => {
+    const result = evaluateReferendum(withChanges({ yes: 0, no: 0, blank: 20, invalid: 5 }));
+    expect(result.valid).toBe(true);
+    expect(result.approval.rate).toBe(0);
+    expect(result.approval.passed).toBe(false);
+    expect(result.warnings).toContain('no-valid-votes');
+  });
+
+  it('rejects impossible totals and invalid threshold values', () => {
+    const impossible = evaluateReferendum(withChanges({ eligibleVoters: 10, yes: 20 }));
+    expect(impossible.status).toBe('invalid');
+    expect(impossible.errors).toContain('ballots-exceed-eligible');
+    const invalidThreshold = evaluateReferendum({ ...getExampleInput(), rules: { ...getExampleInput().rules, approval: { mode: 'percentage', value: 101, denominator: 'valid-votes' } } });
+    expect(invalidThreshold.errors).toContain('invalid-percentage');
+  });
+
+  it('treats zero thresholds as valid only when the required denominator exists', () => {
+    const input = getExampleInput();
+    input.rules = { participation: { mode: 'percentage', value: 0, denominator: 'all-ballots' }, approval: { mode: 'percentage', value: 0, denominator: 'valid-votes' } };
+    const result = evaluateReferendum(input);
+    expect(result.participation.passed).toBe(true);
+    expect(result.approval.passed).toBe(true);
+    const empty = evaluateReferendum({ ...input, counts: { eligibleVoters: 100, yes: 0, no: 0, blank: 0, invalid: 0 } });
+    expect(empty.approval.passed).toBe(false);
+  });
+});

package/src/tool/referendum-threshold-calculator/logic.ts

@@ -0,0 +1,120 @@
+export type ThresholdMode = 'percentage' | 'absolute';
+export type DenominatorMode = 'all-ballots' | 'valid-votes' | 'eligible-voters';
+export type ThresholdComparison = 'at-least' | 'more-than';
+
+export interface BallotCounts {
+  eligibleVoters: number;
+  yes: number;
+  no: number;
+  blank: number;
+  invalid: number;
+}
+
+export interface ThresholdRule {
+  mode: ThresholdMode;
+  value: number;
+  denominator: DenominatorMode;
+  comparison?: ThresholdComparison;
+}
+
+export interface RuleSet {
+  participation: ThresholdRule;
+  approval: ThresholdRule;
+}
+
+export interface ReferendumInput {
+  counts: BallotCounts;
+  rules: RuleSet;
+}
+
+export interface Totals {
+  allBallots: number;
+  validVotes: number;
+  participationCount: number;
+}
+
+export interface RuleEvaluation {
+  numerator: number;
+  denominator: number;
+  rate: number;
+  mode: ThresholdMode;
+  comparison: ThresholdComparison;
+  threshold: number;
+  passed: boolean;
+  denominatorMode: DenominatorMode;
+}
+
+export type ReferendumStatus = 'passed' | 'participation-failed' | 'approval-failed' | 'both-failed' | 'invalid';
+
+export interface ReferendumEvaluation {
+  valid: boolean;
+  errors: string[];
+  warnings: string[];
+  totals: Totals;
+  participation: RuleEvaluation;
+  approval: RuleEvaluation;
+  status: ReferendumStatus;
+}
+
+const emptyRule: RuleEvaluation = { numerator: 0, denominator: 0, rate: 0, mode: 'percentage', comparison: 'at-least', threshold: 0, passed: false, denominatorMode: 'valid-votes' };
+
+function isWholeNonnegative(value: number): boolean {
+  return Number.isFinite(value) && Number.isInteger(value) && value >= 0;
+}
+
+function validateCounts(counts: BallotCounts): string[] {
+  if (!Object.values(counts).every(isWholeNonnegative) || counts.eligibleVoters === 0) return ['invalid-counts'];
+  if (counts.yes + counts.no + counts.blank + counts.invalid > counts.eligibleVoters) return ['ballots-exceed-eligible'];
+  return [];
+}
+
+function validateRule(rule: ThresholdRule): string[] {
+  if (!Number.isFinite(rule.value) || rule.value < 0) return ['invalid-threshold'];
+  if (rule.mode === 'percentage' && rule.value > 100) return ['invalid-percentage'];
+  if (rule.mode === 'absolute' && !Number.isInteger(rule.value)) return ['invalid-absolute-threshold'];
+  return [];
+}
+
+function getDenominator(counts: BallotCounts, mode: DenominatorMode): number {
+  if (mode === 'all-ballots') return counts.yes + counts.no + counts.blank + counts.invalid;
+  if (mode === 'valid-votes') return counts.yes + counts.no;
+  return counts.eligibleVoters;
+}
+
+function meetsThreshold(observed: number, threshold: number, comparison: ThresholdComparison): boolean {
+  return comparison === 'more-than' ? observed > threshold : observed >= threshold;
+}
+
+function evaluateRule(rule: ThresholdRule, numerator: number, denominator: number): RuleEvaluation {
+  const comparison = rule.comparison ?? 'at-least';
+  const rate = denominator > 0 ? (numerator / denominator) * 100 : 0;
+  const passed = rule.mode === 'percentage' ? denominator > 0 && meetsThreshold(rate, rule.value, comparison) : meetsThreshold(numerator, rule.value, comparison);
+  return { numerator, denominator, rate, mode: rule.mode, comparison, threshold: rule.value, passed, denominatorMode: rule.denominator };
+}
+
+function getStatus(participation: RuleEvaluation, approval: RuleEvaluation): ReferendumStatus {
+  if (participation.passed && approval.passed) return 'passed';
+  if (!participation.passed && !approval.passed) return 'both-failed';
+  return participation.passed ? 'approval-failed' : 'participation-failed';
+}
+
+export function evaluateReferendum(input: ReferendumInput): ReferendumEvaluation {
+  const errors = [...new Set([...validateCounts(input.counts), ...validateRule(input.rules.participation), ...validateRule(input.rules.approval)])];
+  const allBallots = input.counts.yes + input.counts.no + input.counts.blank + input.counts.invalid;
+  const validVotes = input.counts.yes + input.counts.no;
+  const participationCount = getDenominator(input.counts, input.rules.participation.denominator);
+  const totals: Totals = { allBallots, validVotes, participationCount };
+  const participation = evaluateRule(input.rules.participation, participationCount, input.counts.eligibleVoters);
+  const approval = evaluateRule(input.rules.approval, input.counts.yes, getDenominator(input.counts, input.rules.approval.denominator));
+  const warnings: string[] = [];
+  if (allBallots === 0) warnings.push('no-ballots');
+  if (validVotes === 0) warnings.push('no-valid-votes');
+  if (errors.length > 0) return { valid: false, errors, warnings, totals, participation, approval, status: 'invalid' };
+  return { valid: true, errors: [], warnings, totals, participation, approval, status: getStatus(participation, approval) };
+}
+
+export function getExampleInput(): ReferendumInput {
+  return { counts: { eligibleVoters: 1000, yes: 520, no: 300, blank: 20, invalid: 10 }, rules: { participation: { mode: 'percentage', value: 50, denominator: 'all-ballots', comparison: 'at-least' }, approval: { mode: 'percentage', value: 50, denominator: 'valid-votes', comparison: 'at-least' } } };
+}
+
+export const EMPTY_RULE_EVALUATION = emptyRule;