@jjlmoya/utils-civic 1.3.0 → 1.5.0

package/src/tool/civic-priority-matrix/seo.astro

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

package/src/tool/civic-priority-matrix/storage.ts

@@ -0,0 +1,50 @@
+import type { InitiativeInput } from './logic';
+
+export interface CivicPriorityState {
+  initiatives: InitiativeInput[];
+}
+
+const STORAGE_KEY = 'jjlmoya-civic-priority-matrix';
+
+export const defaultInitiatives: InitiativeInput[] = [
+  { id: 'accessible-bus-stops', name: 'Accessible bus stops', impact: 5, urgency: 4, effort: 2 },
+  { id: 'cooling-centres', name: 'Cooling centres', impact: 4, urgency: 5, effort: 3 },
+  { id: 'meeting-transcripts', name: 'Public meeting transcripts', impact: 3, urgency: 2, effort: 1 },
+  { id: 'park-lighting', name: 'Park lighting repair', impact: 4, urgency: 3, effort: 4 },
+];
+
+function isInitiative(value: unknown): value is InitiativeInput {
+  if (!value || typeof value !== 'object') return false;
+  const item = value as Record<string, unknown>;
+  return typeof item.id === 'string'
+    && typeof item.name === 'string'
+    && typeof item.impact === 'number'
+    && typeof item.urgency === 'number'
+    && typeof item.effort === 'number';
+}
+
+function isState(value: unknown): value is CivicPriorityState {
+  if (!value || typeof value !== 'object') return false;
+  const state = value as Record<string, unknown>;
+  return Array.isArray(state.initiatives) && state.initiatives.every(isInitiative);
+}
+
+export function loadCivicPriorityState(): CivicPriorityState | null {
+  try {
+    if (typeof window === 'undefined') return null;
+    const raw = window.localStorage.getItem(STORAGE_KEY);
+    if (!raw) return null;
+    const parsed: unknown = JSON.parse(raw);
+    return isState(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+export function saveCivicPriorityState(state: CivicPriorityState): void {
+  try {
+    if (typeof window !== 'undefined') window.localStorage.setItem(STORAGE_KEY, JSON.stringify(state));
+  } catch {
+    return;
+  }
+}

package/src/tool/civic-priority-matrix/ui.ts

@@ -0,0 +1,96 @@
+export interface CivicPriorityUI {
+  [key: string]: string;
+  addInitiative: string;
+  initiativeList: string;
+  inputHint: string;
+  initiative: string;
+  impact: string;
+  urgency: string;
+  effort: string;
+  scoreScale: string;
+  scoreHint: string;
+  removeInitiative: string;
+  reset: string;
+  resultTitle: string;
+  rankingTitle: string;
+  matrixLabel: string;
+  summaryPrefix: string;
+  summarySuffix: string;
+  rank: string;
+  priorityScore: string;
+  denominator: string;
+  quadrant: string;
+  emptyState: string;
+  invalidState: string;
+  nameRequired: string;
+  impactInvalid: string;
+  urgencyInvalid: string;
+  effortInvalid: string;
+  actNow: string;
+  plan: string;
+  quickResponse: string;
+  defer: string;
+  highImpact: string;
+  lowImpact: string;
+  highUrgency: string;
+  lowUrgency: string;
+  methodTitle: string;
+  methodText: string;
+  notDoTitle: string;
+  notDoText: string;
+  edgeCasesTitle: string;
+  edgeCasesText: string;
+  warningTitle: string;
+  zeroEffortWarning: string;
+  invalidRowsWarning: string;
+  noInitiatives: string;
+  scoreOutOf: string;
+}
+
+export const ui: CivicPriorityUI = {
+  addInitiative: 'Add initiative',
+  initiativeList: 'Initiatives to score',
+  inputHint: 'Give every proposal the same 1 to 5 scale before comparing them.',
+  initiative: 'Initiative',
+  impact: 'Impact',
+  urgency: 'Urgency',
+  effort: 'Effort',
+  scoreScale: 'Score from 1 to 5',
+  scoreHint: 'Higher means more impact, more urgency, or more effort.',
+  removeInitiative: 'Remove initiative',
+  reset: 'Reset example',
+  resultTitle: 'Decision field',
+  rankingTitle: 'Explainable order',
+  matrixLabel: 'Initiatives placed by impact and urgency',
+  summaryPrefix: 'Showing',
+  summarySuffix: 'scored initiatives',
+  rank: 'Rank',
+  priorityScore: 'Priority score',
+  denominator: 'Effort denominator',
+  quadrant: 'Quadrant',
+  emptyState: 'Add an initiative to open the decision field.',
+  invalidState: 'Fix the highlighted values to calculate a priority order.',
+  nameRequired: 'Name is required.',
+  impactInvalid: 'Impact must be a whole number from 1 to 5.',
+  urgencyInvalid: 'Urgency must be a whole number from 1 to 5.',
+  effortInvalid: 'Effort must be a whole number from 0 to 5.',
+  actNow: 'Act now',
+  plan: 'Plan',
+  quickResponse: 'Quick response',
+  defer: 'Defer',
+  highImpact: 'High impact',
+  lowImpact: 'Low impact',
+  highUrgency: 'High urgency',
+  lowUrgency: 'Low urgency',
+  methodTitle: 'Method applied',
+  methodText: 'The priority score is impact multiplied by urgency, divided by effort. Impact, urgency, and effort use a visible 1 to 5 scale. Effort 0 is treated as 1 so a free or already-resourced action remains finite rather than becoming an infinite score. The ranking breaks ties by impact, urgency, lower effort, then input order.',
+  notDoTitle: 'What this tool does not do',
+  notDoText: 'It does not establish objective social value, measure outcomes automatically, or replace deliberation. A high score is a transparent scenario under your assumptions, not a mandate or a prediction of public benefit.',
+  edgeCasesTitle: 'Edge cases and warnings',
+  edgeCasesText: 'Keep the same interpretation of each score across every row. A missing or non-integer score excludes that row until fixed. Score 3 is the dividing line in the field. Equal scores remain in stable input order after the documented tie-breakers. Change one assessment at a time when discussing a result with a group.',
+  warningTitle: 'Review before deciding',
+  zeroEffortWarning: 'An effort score of 0 uses a denominator of 1 to keep the score finite and comparable.',
+  invalidRowsWarning: 'Some rows are excluded until their highlighted values are fixed.',
+  noInitiatives: 'No initiatives entered yet.',
+  scoreOutOf: 'of 25 maximum',
+};

package/src/tool/referendum-threshold-calculator/bibliography.astro

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

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

@@ -0,0 +1,6 @@
+import type { BibliographyEntry } from '../../types';
+
+export const bibliography: BibliographyEntry[] = [
+  { name: 'International IDEA, Direct Democracy Handbook, chapter on referendum rules', url: 'https://www.idea.int/sites/default/files/publications/direct-democracy-the-international-idea-handbook.pdf' },
+  { name: 'Commission de Venise, Code de bonne conduite en matière référendaire révisé', url: 'https://www.venice.coe.int/webforms/documents/?pdf=CDL-AD%282022%29015-f' },
+];

package/src/tool/referendum-threshold-calculator/component.astro

@@ -0,0 +1,117 @@
+---
+import type { ReferendumThresholdUI } from './ui';
+import './referendum-threshold-calculator.css';
+
+interface Props {
+  ui: ReferendumThresholdUI;
+}
+
+const { ui } = Astro.props as Props;
+---
+
+<div class="referendum-tool" data-referendum-threshold-tool>
+  <div class="rule-workbench">
+    <form class="rule-form" data-referendum-form>
+      <fieldset class="count-block">
+        <legend>{ui.countsHeading}</legend>
+        <label class="wide-field">{ui.eligibleLabel}<input name="eligibleVoters" type="number" min="0" step="1" value="1000" required /><small>{ui.eligibleHelp}</small></label>
+        <div class="count-grid">
+          <label>{ui.yesLabel}<input name="yes" type="number" min="0" step="1" value="520" required /></label>
+          <label>{ui.noLabel}<input name="no" type="number" min="0" step="1" value="300" required /></label>
+          <label>{ui.blankLabel}<input name="blank" type="number" min="0" step="1" value="20" required /></label>
+          <label>{ui.invalidLabel}<input name="invalid" type="number" min="0" step="1" value="10" required /></label>
+        </div>
+      </fieldset>
+
+      <fieldset class="quorum-block participation-block">
+        <legend>{ui.participationHeading}</legend>
+        <p>{ui.participationHelp}</p>
+        <div class="mode-switch" role="group" aria-label={ui.thresholdModeLabel}>
+          <button type="button" class="active" data-mode-prefix="participation" data-mode="percentage" aria-pressed="true">{ui.percentageOption}</button>
+          <button type="button" data-mode-prefix="participation" data-mode="absolute" aria-pressed="false">{ui.absoluteOption}</button>
+        </div>
+        <div class="comparison-row" role="group" aria-label={ui.comparisonLabel}>
+          <span>{ui.comparisonLabel}</span>
+          <input name="participationComparison" type="hidden" value="at-least" />
+          <button type="button" class="active" data-comparison-prefix="participation" data-comparison="at-least" aria-pressed="true">{ui.atLeastOption}</button>
+          <button type="button" data-comparison-prefix="participation" data-comparison="more-than" aria-pressed="false">{ui.moreThanOption}</button>
+        </div>
+        <div class="quorum-fields">
+          <input name="participationMode" type="hidden" value="percentage" />
+          <label>{ui.thresholdValueLabel}<input name="participationThreshold" type="number" min="0" max="100" step="0.1" value="50" required /></label>
+          <div class="custom-select" data-select>
+            <span class="field-label">{ui.denominatorLabel}</span>
+            <input name="participationDenominator" type="hidden" value="all-ballots" />
+            <button type="button" data-select-trigger aria-expanded="false">{ui.allBallotsOption}</button>
+            <div class="select-menu" data-select-menu hidden role="listbox">
+              <button type="button" data-option="all-ballots" role="option">{ui.allBallotsOption}</button>
+              <button type="button" data-option="valid-votes" role="option">{ui.validVotesOption}</button>
+            </div>
+          </div>
+        </div>
+      </fieldset>
+
+      <fieldset class="quorum-block approval-block">
+        <legend>{ui.approvalHeading}</legend>
+        <p>{ui.approvalHelp}</p>
+        <div class="mode-switch" role="group" aria-label={ui.thresholdModeLabel}>
+          <button type="button" class="active" data-mode-prefix="approval" data-mode="percentage" aria-pressed="true">{ui.percentageOption}</button>
+          <button type="button" data-mode-prefix="approval" data-mode="absolute" aria-pressed="false">{ui.absoluteOption}</button>
+        </div>
+        <div class="comparison-row" role="group" aria-label={ui.comparisonLabel}>
+          <span>{ui.comparisonLabel}</span>
+          <input name="approvalComparison" type="hidden" value="at-least" />
+          <button type="button" class="active" data-comparison-prefix="approval" data-comparison="at-least" aria-pressed="true">{ui.atLeastOption}</button>
+          <button type="button" data-comparison-prefix="approval" data-comparison="more-than" aria-pressed="false">{ui.moreThanOption}</button>
+        </div>
+        <div class="preset-row" role="group" aria-label={ui.presetsLabel}>
+          <span>{ui.presetsLabel}</span>
+          <button type="button" data-preset="simple-majority">{ui.simpleMajorityPreset}</button>
+          <button type="button" data-preset="electorate-majority">{ui.electorateMajorityPreset}</button>
+          <button type="button" data-preset="qualified-55">{ui.qualified55Preset}</button>
+          <button type="button" data-preset="qualified-60">{ui.qualified60Preset}</button>
+        </div>
+        <div class="quorum-fields">
+          <input name="approvalMode" type="hidden" value="percentage" />
+          <label>{ui.thresholdValueLabel}<input name="approvalThreshold" type="number" min="0" max="100" step="0.1" value="50" required /></label>
+          <div class="custom-select" data-select>
+            <span class="field-label">{ui.denominatorLabel}</span>
+            <input name="approvalDenominator" type="hidden" value="valid-votes" />
+            <button type="button" data-select-trigger aria-expanded="false">{ui.validVotesOption}</button>
+            <div class="select-menu" data-select-menu hidden role="listbox">
+              <button type="button" data-option="all-ballots" role="option">{ui.allBallotsOption}</button>
+              <button type="button" data-option="valid-votes" role="option">{ui.validVotesOption}</button>
+              <button type="button" data-option="eligible-voters" role="option">{ui.eligibleVotersOption}</button>
+            </div>
+          </div>
+        </div>
+      </fieldset>
+
+      <div class="form-actions"><button class="secondary-action" type="button" data-reset>{ui.loadExample}</button><button class="share-action" type="button" data-share>{ui.shareAction}</button></div>
+      <p class="tool-status" data-status role="status"></p>
+    </form>
+
+    <section class="decision-panel" aria-live="polite" aria-labelledby="referendum-result-heading">
+      <div class="panel-heading"><span class="panel-index">02</span><h2 id="referendum-result-heading">{ui.resultHeading}</h2></div>
+      <div class="decision-scene" data-scene></div>
+      <div class="empty-result" data-empty-result>{ui.emptyResult}</div>
+      <div class="result-content" data-result hidden></div>
+    </section>
+  </div>
+
+  <section class="guardrails" aria-label="Method and limits">
+    <article><span class="guardrail-mark">01</span><h2>{ui.methodHeading}</h2><p>{ui.methodText}</p></article>
+    <article><span class="guardrail-mark">02</span><h2>{ui.limitsHeading}</h2><p>{ui.limitsText}</p></article>
+    <article><span class="guardrail-mark">03</span><h2>{ui.warningsHeading}</h2><p>{ui.warningsText}</p></article>
+  </section>
+
+  <script is:inline type="application/json" data-referendum-threshold-config set:html={JSON.stringify({ ui })}></script>
+</div>
+
+<script>
+  import { mountReferendumThresholdTool } from './controller';
+
+  const root = document.querySelector<HTMLElement>('[data-referendum-threshold-tool]');
+  const config = root?.querySelector<HTMLScriptElement>('[data-referendum-threshold-config]');
+  if (root && config) mountReferendumThresholdTool(root, JSON.parse(config.textContent || '{}').ui);
+</script>

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

@@ -0,0 +1,141 @@
+import { evaluateReferendum, getExampleInput, type DenominatorMode, type ReferendumInput, type ThresholdComparison, type ThresholdMode, type ThresholdRule } from './logic';
+import { renderDecision, renderDecisionScene, formatInputValue } from './dom-views';
+import { loadSavedInput, saveInput } from './storage';
+import { buildShareUrl, readShareUrl } from './sharing';
+import type { ReferendumThresholdUI } from './ui';
+
+function getInput(root: HTMLElement, name: string): HTMLInputElement {
+  return root.querySelector<HTMLInputElement>(`[name="${name}"]`)!;
+}
+
+function numericValue(root: HTMLElement, name: string): number {
+  return Number(getInput(root, name).value);
+}
+
+function selectedValue(root: HTMLElement, name: string): string {
+  return getInput(root, name).value;
+}
+
+function readRule(root: HTMLElement, prefix: string): ThresholdRule {
+  return { mode: selectedValue(root, `${prefix}Mode`) as ThresholdMode, value: numericValue(root, `${prefix}Threshold`), denominator: selectedValue(root, `${prefix}Denominator`) as DenominatorMode, comparison: selectedValue(root, `${prefix}Comparison`) as ThresholdComparison };
+}
+
+function readInput(root: HTMLElement): ReferendumInput {
+  return { counts: { eligibleVoters: numericValue(root, 'eligibleVoters'), yes: numericValue(root, 'yes'), no: numericValue(root, 'no'), blank: numericValue(root, 'blank'), invalid: numericValue(root, 'invalid') }, rules: { participation: readRule(root, 'participation'), approval: readRule(root, 'approval') } };
+}
+
+function updateSelectLabel(root: HTMLElement, name: string): void {
+  const field = getInput(root, name);
+  const select = field.closest<HTMLElement>('[data-select]');
+  const active = select?.querySelector<HTMLElement>(`[data-option="${field.value}"]`);
+  const trigger = select?.querySelector<HTMLButtonElement>('[data-select-trigger]');
+  if (trigger && active) trigger.textContent = active.textContent;
+}
+
+function updateModeButtons(root: HTMLElement, prefix: string, mode: ThresholdMode): void {
+  const threshold = getInput(root, `${prefix}Threshold`);
+  threshold.max = mode === 'percentage' ? '100' : '';
+  root.querySelectorAll<HTMLButtonElement>(`[data-mode-prefix="${prefix}"]`).forEach((button) => { const active = button.dataset.mode === mode; button.classList.toggle('active', active); button.setAttribute('aria-pressed', String(active)); });
+}
+
+function updateComparisonButtons(root: HTMLElement, prefix: string, comparison: ThresholdComparison): void {
+  root.querySelectorAll<HTMLButtonElement>(`[data-comparison-prefix="${prefix}"]`).forEach((button) => { const active = button.dataset.comparison === comparison; button.classList.toggle('active', active); button.setAttribute('aria-pressed', String(active)); });
+}
+
+function updateRule(root: HTMLElement, prefix: string, rule: ThresholdRule): void {
+  getInput(root, `${prefix}Mode`).value = rule.mode;
+  getInput(root, `${prefix}Threshold`).value = formatInputValue(rule.value);
+  getInput(root, `${prefix}Denominator`).value = rule.denominator;
+  getInput(root, `${prefix}Comparison`).value = rule.comparison ?? 'at-least';
+  updateSelectLabel(root, `${prefix}Denominator`);
+  updateModeButtons(root, prefix, rule.mode);
+  updateComparisonButtons(root, prefix, rule.comparison ?? 'at-least');
+}
+
+function emitChange(field: HTMLInputElement): void {
+  field.dispatchEvent(new Event('change', { bubbles: true }));
+}
+
+function writeInput(root: HTMLElement, input: ReferendumInput): void {
+  Object.entries(input.counts).forEach(([name, value]) => { getInput(root, name).value = formatInputValue(value); });
+  ['participation', 'approval'].forEach((prefix) => { updateRule(root, prefix, input.rules[prefix as 'participation' | 'approval'] as ThresholdRule); });
+}
+
+function wireSelect(root: HTMLElement, select: HTMLElement): void {
+  const trigger = select.querySelector<HTMLButtonElement>('[data-select-trigger]');
+  const menu = select.querySelector<HTMLElement>('[data-select-menu]');
+  const field = select.querySelector<HTMLInputElement>('input[type="hidden"]');
+  if (!trigger || !menu || !field) return;
+  trigger.addEventListener('click', () => { const open = menu.hidden; root.querySelectorAll<HTMLElement>('[data-select-menu]').forEach((item) => { item.hidden = true; }); menu.hidden = !open; trigger.setAttribute('aria-expanded', String(open)); });
+  menu.querySelectorAll<HTMLButtonElement>('[data-option]').forEach((option) => option.addEventListener('click', () => { field.value = option.dataset.option ?? ''; updateSelectLabel(root, field.name); menu.hidden = true; trigger.setAttribute('aria-expanded', 'false'); emitChange(field); }));
+}
+
+function wireModeButtons(root: HTMLElement): void {
+  root.querySelectorAll<HTMLButtonElement>('[data-mode-prefix]').forEach((button) => button.addEventListener('click', () => { const prefix = button.dataset.modePrefix!; const mode = button.dataset.mode as ThresholdMode; const field = getInput(root, `${prefix}Mode`); field.value = mode; updateModeButtons(root, prefix, mode); emitChange(field); }));
+}
+
+function wireComparisonButtons(root: HTMLElement): void {
+  root.querySelectorAll<HTMLButtonElement>('[data-comparison-prefix]').forEach((button) => button.addEventListener('click', () => { const prefix = button.dataset.comparisonPrefix!; const comparison = button.dataset.comparison as ThresholdComparison; const field = getInput(root, `${prefix}Comparison`); field.value = comparison; updateComparisonButtons(root, prefix, comparison); emitChange(field); }));
+}
+
+function wirePresets(root: HTMLElement): void {
+  const presets: Record<string, ThresholdRule> = {
+    'simple-majority': { mode: 'percentage', value: 50, denominator: 'valid-votes', comparison: 'more-than' },
+    'electorate-majority': { mode: 'percentage', value: 50, denominator: 'eligible-voters', comparison: 'more-than' },
+    'qualified-55': { mode: 'percentage', value: 55, denominator: 'valid-votes', comparison: 'at-least' },
+    'qualified-60': { mode: 'percentage', value: 60, denominator: 'valid-votes', comparison: 'at-least' },
+  };
+  root.querySelectorAll<HTMLButtonElement>('[data-preset]').forEach((button) => button.addEventListener('click', () => { const preset = presets[button.dataset.preset ?? '']; if (preset) { updateRule(root, 'approval', preset); emitChange(getInput(root, 'approvalThreshold')); } }));
+}
+
+function wireOutsideSelectClose(root: HTMLElement): void {
+  root.addEventListener('click', (event) => {
+    if ((event.target as Element).closest('[data-select]')) return;
+    root.querySelectorAll<HTMLElement>('[data-select-menu]').forEach((menu) => { menu.hidden = true; });
+    root.querySelectorAll<HTMLButtonElement>('[data-select-trigger]').forEach((trigger) => { trigger.setAttribute('aria-expanded', 'false'); });
+  });
+}
+
+function wireShare(root: HTMLElement, ui: ReferendumThresholdUI): void {
+  root.querySelector<HTMLButtonElement>('[data-share]')!.addEventListener('click', async () => {
+    const url = buildShareUrl(window.location.href, readInput(root));
+    window.history.replaceState({}, '', url);
+    try { if (!navigator.clipboard) throw new Error('clipboard-unavailable'); await navigator.clipboard.writeText(url); root.querySelector<HTMLElement>('[data-status]')!.textContent = ui.shareSuccess; } catch { root.querySelector<HTMLElement>('[data-status]')!.textContent = ui.shareFailure; }
+  });
+}
+
+function showEvaluation(root: HTMLElement, input: ReferendumInput, ui: ReferendumThresholdUI): void {
+  const evaluation = evaluateReferendum(input);
+  root.querySelector<HTMLElement>('[data-empty-result]')!.hidden = true;
+  root.querySelector<HTMLElement>('[data-result]')!.hidden = false;
+  renderDecisionScene(root.querySelector<HTMLElement>('[data-scene]')!, evaluation, ui);
+  renderDecision(root.querySelector<HTMLElement>('[data-result]')!, evaluation, ui);
+  root.querySelector<HTMLElement>('[data-status]')!.textContent = evaluation.errors.includes('ballots-exceed-eligible') ? ui.ballotsExceedEligible : '';
+}
+
+function refreshEvaluation(root: HTMLElement, ui: ReferendumThresholdUI): void {
+  const input = readInput(root);
+  saveInput(input);
+  showEvaluation(root, input, ui);
+}
+
+function wireForm(root: HTMLElement, ui: ReferendumThresholdUI): void {
+  const form = root.querySelector<HTMLFormElement>('[data-referendum-form]')!;
+  form.addEventListener('input', () => refreshEvaluation(root, ui));
+  form.addEventListener('change', () => refreshEvaluation(root, ui));
+  form.addEventListener('submit', (event) => { event.preventDefault(); refreshEvaluation(root, ui); });
+  root.querySelector<HTMLButtonElement>('[data-reset]')!.addEventListener('click', () => { writeInput(root, getExampleInput()); refreshEvaluation(root, ui); });
+}
+
+export function mountReferendumThresholdTool(root: HTMLElement, ui: ReferendumThresholdUI): void {
+  root.querySelectorAll<HTMLElement>('[data-select]').forEach((select) => wireSelect(root, select));
+  wireOutsideSelectClose(root);
+  wireModeButtons(root);
+  wireComparisonButtons(root);
+  wirePresets(root);
+  wireForm(root, ui);
+  wireShare(root, ui);
+  const initial = readShareUrl(window.location.href) ?? loadSavedInput() ?? getExampleInput();
+  writeInput(root, initial);
+  showEvaluation(root, initial, ui);
+}

package/src/tool/referendum-threshold-calculator/dom-views.ts

@@ -0,0 +1,71 @@
+import type { ReferendumEvaluation, ThresholdRule } from './logic';
+import { getStatusPresentation } from './evaluator';
+import type { ReferendumThresholdUI } from './ui';
+
+const numberFormatter = new Intl.NumberFormat('en-US', { maximumFractionDigits: 0 });
+const percentFormatter = new Intl.NumberFormat('en-US', { maximumFractionDigits: 1 });
+
+function formatNumber(value: number): string {
+  return numberFormatter.format(value);
+}
+
+function formatPercent(value: number): string {
+  return `${percentFormatter.format(value)}%`;
+}
+
+function thresholdText(rule: ThresholdRule, ui: ReferendumThresholdUI): string {
+  const operator = rule.comparison === 'more-than' ? '> ' : '>= ';
+  if (rule.mode === 'absolute') return `${operator}${formatNumber(rule.value)} ${ui.peopleSuffix}`;
+  const denominator = denominatorText(rule.denominator, ui);
+  return `${operator}${formatNumber(rule.value)}% of ${denominator}`;
+}
+
+function denominatorText(mode: ThresholdRule['denominator'], ui: ReferendumThresholdUI): string {
+  if (mode === 'eligible-voters') return ui.eligibleVotersLabel;
+  if (mode === 'valid-votes') return ui.validVotesLabel;
+  return ui.allBallotsLabel;
+}
+
+function markerPosition(rule: ThresholdRule, denominator: number): number {
+  if (rule.mode === 'percentage') return rule.value;
+  if (denominator <= 0) return 100;
+  return (rule.value / denominator) * 100;
+}
+
+function statusTitle(evaluation: ReferendumEvaluation, ui: ReferendumThresholdUI): string {
+  if (!evaluation.valid) return ui.invalidResult;
+  if (evaluation.status === 'passed') return ui.passed;
+  if (evaluation.status === 'participation-failed') return ui.participationFailed;
+  if (evaluation.status === 'approval-failed') return ui.approvalFailed;
+  return ui.bothFailed;
+}
+
+function gateMarkup(label: string, rule: ThresholdRule, value: ReferendumEvaluation['participation'], ui: ReferendumThresholdUI): string {
+  const fill = Math.min(100, Math.max(0, value.rate));
+  const marker = markerPosition(rule, value.denominator);
+  const state = value.passed ? 'pass' : 'fail';
+  return `<div class="quorum-gate ${state}"><div class="gate-top"><span>${label}</span><strong>${formatPercent(value.rate)}</strong></div><div class="gate-track"><span style="width:${fill}%"></span><i style="left:${Math.min(100, Math.max(0, marker))}%"></i></div><div class="gate-bottom"><span>${formatNumber(value.numerator)} / ${formatNumber(value.denominator)}</span><span>required ${thresholdText(rule, ui)}</span></div></div>`;
+}
+
+export function renderDecisionScene(target: HTMLElement, evaluation: ReferendumEvaluation, ui: ReferendumThresholdUI): void {
+  const allBallotsRule: ThresholdRule = { mode: evaluation.participation.mode, value: evaluation.participation.threshold, denominator: evaluation.participation.denominatorMode, comparison: evaluation.participation.comparison };
+  const validVotesRule: ThresholdRule = { mode: evaluation.approval.mode, value: evaluation.approval.threshold, denominator: evaluation.approval.denominatorMode, comparison: evaluation.approval.comparison };
+  target.innerHTML = `<div class="ballot-path" aria-label="${ui.decisionPathLabel}"><div class="ballot-mark"><span class="ballot-check">O</span><span>${formatNumber(evaluation.totals.allBallots)} ${ui.allBallotsLabel}</span></div><div class="path-line"></div><div class="gate-stack">${gateMarkup(ui.participationMetric, allBallotsRule, evaluation.participation, ui)}${gateMarkup(ui.approvalMetric, validVotesRule, evaluation.approval, ui)}</div></div>`;
+}
+
+function ruleCard(title: string, evaluation: ReferendumEvaluation['participation'] | ReferendumEvaluation['approval'], rule: ThresholdRule, ui: ReferendumThresholdUI): string {
+  return `<article class="metric-card"><div class="metric-card-head"><span>${title}</span><b class="metric-state ${evaluation.passed ? 'pass' : 'fail'}">${evaluation.passed ? 'PASS' : 'FAIL'}</b></div><strong>${formatPercent(evaluation.rate)}</strong><dl><div><dt>${ui.observedLabel}</dt><dd>${formatNumber(evaluation.numerator)} / ${formatNumber(evaluation.denominator)}</dd></div><div><dt>${ui.thresholdLabel}</dt><dd>${thresholdText(rule, ui)}</dd></div></dl></article>`;
+}
+
+export function renderDecision(target: HTMLElement, evaluation: ReferendumEvaluation, ui: ReferendumThresholdUI): void {
+  const presentation = getStatusPresentation(evaluation);
+  const errors = evaluation.errors.length > 0 ? `<div class="inline-message danger" role="alert">${ui.invalidInput}</div>` : '';
+  const warnings = evaluation.warnings.map((warning) => warning === 'no-valid-votes' ? ui.noValidVotes : ui.noBallots).map((text) => `<li>${text}</li>`).join('');
+  const participationRule: ThresholdRule = { mode: evaluation.participation.mode, value: evaluation.participation.threshold, denominator: evaluation.participation.denominatorMode, comparison: evaluation.participation.comparison };
+  const approvalRule: ThresholdRule = { mode: evaluation.approval.mode, value: evaluation.approval.threshold, denominator: evaluation.approval.denominatorMode, comparison: evaluation.approval.comparison };
+  target.innerHTML = `<div class="decision-banner ${presentation.tone}"><span class="decision-seal">${evaluation.valid ? 'O' : '!'}</span><div><strong>${statusTitle(evaluation, ui)}</strong><p>${presentation.detail}</p></div></div>${errors}<div class="metric-grid">${ruleCard(ui.participationMetric, evaluation.participation, participationRule, ui)}${ruleCard(ui.approvalMetric, evaluation.approval, approvalRule, ui)}</div><div class="totals-strip"><span>${ui.yesShareLabel} <b>${formatNumber(evaluation.approval.numerator)}</b></span><span>${ui.allBallotsLabel} <b>${formatNumber(evaluation.totals.allBallots)}</b></span><span>${ui.validVotesLabel} <b>${formatNumber(evaluation.totals.validVotes)}</b></span><span>${ui.eligibleVotersLabel} <b>${formatNumber(evaluation.participation.denominator)}</b></span></div>${warnings ? `<div class="warning-list"><strong>${ui.warningsHeading}</strong><ul>${warnings}</ul></div>` : ''}<div class="next-step"><strong>${ui.whatNextLabel}</strong><p>${ui.whatNextText}</p></div>`;
+}
+
+export function formatInputValue(value: number): string {
+  return Number.isFinite(value) ? String(value) : '';
+}

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

@@ -0,0 +1,27 @@
+import type { CivicToolEntry, ToolLocaleContent } from '../../types';
+import type { ReferendumThresholdUI } from './ui';
+
+export type ReferendumThresholdLocaleContent = ToolLocaleContent<ReferendumThresholdUI>;
+
+export const referendumThresholdCalculator: CivicToolEntry<ReferendumThresholdUI> = {
+  id: 'referendum-threshold-calculator',
+  phase: 'localized',
+  icons: { bg: 'mdi:vote-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),
+  },
+};

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

@@ -0,0 +1,19 @@
+import type { ReferendumEvaluation, ReferendumStatus } from './logic';
+
+export interface StatusPresentation {
+  tone: 'positive' | 'warning' | 'danger' | 'neutral';
+  title: string;
+  detail: string;
+}
+
+const statusDetails: Record<ReferendumStatus, StatusPresentation> = {
+  passed: { tone: 'positive', title: 'Both thresholds pass', detail: 'The declared rule accepts the result because participation and approval tests pass.' },
+  'participation-failed': { tone: 'warning', title: 'Participation quorum fails', detail: 'The approval test may pass, but the declared participation threshold is not reached.' },
+  'approval-failed': { tone: 'warning', title: 'Approval quorum fails', detail: 'Participation reaches its threshold, but the Yes count does not meet the declared approval rule.' },
+  'both-failed': { tone: 'danger', title: 'Both thresholds fail', detail: 'Neither declared quorum is reached with the supplied counts.' },
+  invalid: { tone: 'danger', title: 'Check the declared counts', detail: 'The inputs contain a structural error, so no decision should be read from the result.' },
+};
+
+export function getStatusPresentation(evaluation: ReferendumEvaluation): StatusPresentation {
+  return statusDetails[evaluation.status];
+}