@jjlmoya/utils-civic 1.4.0 → 1.6.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/participatory-budget-allocator/bibliography.astro

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

package/src/tool/participatory-budget-allocator/bibliography.ts

@@ -0,0 +1,8 @@
+import type { BibliographyEntry } from '../../types';
+
+const bibliographyTrace = [
+  { name: 'Northeastern University, Lecture 35 Dynamic Programming', url: 'https://course.khoury.northeastern.edu/cs2510a/lecture35.html', region: 'United States', originalLanguage: 'English', supports: 'The 0/1 knapsack model and dynamic programming search.' },
+  { name: 'Ville de Paris, Budget participatif 2022 Guide du dépôt de projets', url: 'https://cdn.paris.fr/paris/2022/01/04/86f0051197c40fe872c29bac1e98c335.pdf', region: 'France', originalLanguage: 'French', supports: 'The practical context of submitting and costing participatory budget projects.' },
+];
+
+export const bibliography: BibliographyEntry[] = bibliographyTrace.map(({ name, url }) => ({ name, url }));

package/src/tool/participatory-budget-allocator/component.astro

@@ -0,0 +1,61 @@
+---
+import type { ParticipatoryBudgetUI } from './ui';
+import './participatory-budget-allocator.css';
+
+interface Props {
+  ui: ParticipatoryBudgetUI;
+}
+
+const { ui } = Astro.props as Props;
+---
+
+<div class="participatory-budget-tool" data-participatory-budget-tool>
+  <div class="allocation-layout">
+    <form class="allocation-form" data-allocation-form>
+      <label class="budget-field">{ui.budgetLabel}<input name="budget" type="number" min="0" max="20000" step="0.01" value="12000" required /><span class="field-help">{ui.budgetHelp}</span></label>
+      <div class="proposal-heading"><h2>{ui.proposalsHeading}</h2><button class="add-proposal" type="button" data-add-proposal>{ui.addProposal}</button></div>
+      <div class="proposal-rows" data-proposal-rows>
+        <div class="proposal-row" data-proposal-row>
+          <label class="proposal-name">{ui.proposalNameLabel}<input data-proposal-name type="text" value="Pocket park seating" required /></label>
+          <label>{ui.proposalCostLabel}<input data-proposal-cost type="number" min="0" step="0.01" value="3500" required /></label>
+          <label>{ui.proposalScoreLabel}<input data-proposal-score type="number" min="0" step="1" value="86" required /></label>
+          <button class="remove-proposal" type="button" data-remove-proposal>{ui.removeProposal}</button>
+        </div>
+        <div class="proposal-row" data-proposal-row>
+          <label class="proposal-name">{ui.proposalNameLabel}<input data-proposal-name type="text" value="Safer school crossing" required /></label>
+          <label>{ui.proposalCostLabel}<input data-proposal-cost type="number" min="0" step="0.01" value="6200" required /></label>
+          <label>{ui.proposalScoreLabel}<input data-proposal-score type="number" min="0" step="1" value="100" required /></label>
+          <button class="remove-proposal" type="button" data-remove-proposal>{ui.removeProposal}</button>
+        </div>
+        <div class="proposal-row" data-proposal-row>
+          <label class="proposal-name">{ui.proposalNameLabel}<input data-proposal-name type="text" value="Community tool library" required /></label>
+          <label>{ui.proposalCostLabel}<input data-proposal-cost type="number" min="0" step="0.01" value="4200" required /></label>
+          <label>{ui.proposalScoreLabel}<input data-proposal-score type="number" min="0" step="1" value="74" required /></label>
+          <button class="remove-proposal" type="button" data-remove-proposal>{ui.removeProposal}</button>
+        </div>
+      </div>
+      <p class="calculate-note">{ui.calculateNote}</p>
+      <div class="form-actions"><button class="secondary-action" type="button" data-load-example>{ui.loadExample}</button><button class="print-action" type="button" data-print>{ui.printAction}</button></div>
+      <p class="tool-status" data-status role="status"></p>
+    </form>
+    <section class="allocation-result" aria-live="polite" aria-labelledby="allocation-result-heading">
+      <div class="result-heading"><h2 id="allocation-result-heading">{ui.resultHeading}</h2></div>
+      <div data-scene></div>
+      <div data-result></div>
+    </section>
+  </div>
+  <div class="guardrails" aria-label="Method and limits">
+    <article class="guardrail"><span class="guardrail-index">01</span><h2>{ui.methodHeading}</h2><p>{ui.methodText}</p></article>
+    <article class="guardrail"><span class="guardrail-index">02</span><h2>{ui.limitsHeading}</h2><p>{ui.limitsText}</p></article>
+    <article class="guardrail"><span class="guardrail-index">03</span><h2>{ui.warningsHeading}</h2><p>{ui.warningsText}</p></article>
+  </div>
+  <script is:inline type="application/json" data-participatory-budget-config set:html={JSON.stringify({ ui })}></script>
+</div>
+
+<script>
+  import { mountParticipatoryBudgetTool } from './controller';
+
+  const root = document.querySelector<HTMLElement>('[data-participatory-budget-tool]');
+  const config = root?.querySelector<HTMLScriptElement>('[data-participatory-budget-config]');
+  if (root && config) mountParticipatoryBudgetTool(root, JSON.parse(config.textContent || '{}').ui);
+</script>

package/src/tool/participatory-budget-allocator/contract.test.ts

@@ -0,0 +1,13 @@
+import { describe, expect, it } from 'vitest';
+import { PARTICIPATORY_BUDGET_ALLOCATOR_TOOL, participatoryBudgetAllocator } from './index';
+
+describe('participatory budget allocator runtime contract', () => {
+  it('exposes all locale loaders and the three page component loaders', async () => {
+    const content = await participatoryBudgetAllocator.i18n.en?.();
+    expect(content?.slug).toBe('participatory-budget-allocator');
+    expect(Object.keys(participatoryBudgetAllocator.i18n)).toEqual(['en', 'de', 'es', 'fr', 'id', 'it', 'ja', 'ko', 'nl', 'pl', 'pt', 'ru', 'sv', 'tr', 'zh']);
+    expect(typeof PARTICIPATORY_BUDGET_ALLOCATOR_TOOL.Component).toBe('function');
+    expect(typeof PARTICIPATORY_BUDGET_ALLOCATOR_TOOL.SEOComponent).toBe('function');
+    expect(typeof PARTICIPATORY_BUDGET_ALLOCATOR_TOOL.BibliographyComponent).toBe('function');
+  });
+});

package/src/tool/participatory-budget-allocator/controller.ts

@@ -0,0 +1,108 @@
+import { allocateBudget, getExampleInput, type AllocationInput, type ProposalInput } from './logic';
+import { renderAllocationResult, renderAllocationScene } from './dom-views';
+import { loadSavedInput, saveInput } from './storage';
+import type { ParticipatoryBudgetUI } from './ui';
+
+function numberValue(form: HTMLFormElement, name: string): number {
+  const field = form.elements.namedItem(name) as HTMLInputElement | null;
+  return parseNumber(field?.value ?? '');
+}
+
+function parseNumber(value: string): number {
+  return value.trim() ? Number(value) : Number.NaN;
+}
+
+function fieldValue(value: string): string {
+  return value === 'NaN' ? '' : value;
+}
+
+function readRows(form: HTMLFormElement): ProposalInput[] {
+  return [...form.querySelectorAll<HTMLElement>('[data-proposal-row]')].map((row) => ({
+    name: (row.querySelector('[data-proposal-name]') as HTMLInputElement)?.value ?? '',
+    cost: parseNumber((row.querySelector('[data-proposal-cost]') as HTMLInputElement)?.value ?? ''),
+    score: parseNumber((row.querySelector('[data-proposal-score]') as HTMLInputElement)?.value ?? ''),
+  }));
+}
+
+function readInput(form: HTMLFormElement): AllocationInput {
+  return { budget: numberValue(form, 'budget'), proposals: readRows(form) };
+}
+
+function createField(label: string, value: string, className: string, marker: string): HTMLLabelElement {
+  const labelNode = document.createElement('label');
+  labelNode.className = className;
+  labelNode.innerHTML = `${label}<input data-${marker} type="${marker === 'proposal-name' ? 'text' : 'number'}" ${marker === 'proposal-name' ? '' : 'min="0" step="0.01"'} value="${fieldValue(value).replace(/"/g, '&quot;')}" required>`;
+  return labelNode;
+}
+
+function addRow(container: HTMLElement, proposal: ProposalInput, ui: ParticipatoryBudgetUI): void {
+  const row = document.createElement('div');
+  row.className = 'proposal-row';
+  row.dataset.proposalRow = 'true';
+  row.append(createField(ui.proposalNameLabel, proposal.name, 'proposal-name', 'proposal-name'), createField(ui.proposalCostLabel, String(proposal.cost), 'proposal-cost', 'proposal-cost'), createField(ui.proposalScoreLabel, String(proposal.score), 'proposal-score', 'proposal-score'));
+  const remove = document.createElement('button');
+  remove.type = 'button';
+  remove.className = 'remove-proposal';
+  remove.dataset.removeProposal = 'true';
+  remove.textContent = ui.removeProposal;
+  row.append(remove);
+  container.append(row);
+}
+
+function setRows(container: HTMLElement, proposals: ProposalInput[], ui: ParticipatoryBudgetUI): void {
+  container.replaceChildren();
+  proposals.forEach((proposal) => addRow(container, proposal, ui));
+}
+
+function setInput(form: HTMLFormElement, input: AllocationInput, container: HTMLElement, ui: ParticipatoryBudgetUI): void {
+  (form.elements.namedItem('budget') as HTMLInputElement).value = String(input.budget);
+  setRows(container, input.proposals, ui);
+}
+
+function markFormFeedback(form: HTMLFormElement, input: AllocationInput, ui: ParticipatoryBudgetUI): void {
+  [...form.querySelectorAll<HTMLElement>('[data-proposal-row]')].forEach((row, index) => {
+    row.classList.remove('proposal-over-budget', 'proposal-invalid');
+    row.querySelector('[data-row-warning]')?.remove();
+    const proposal = input.proposals[index];
+    if (!proposal) return;
+    const message = getRowWarning(proposal, input.budget, ui);
+    if (!message) return;
+    row.classList.add(Number.isFinite(proposal.cost) && proposal.cost > input.budget ? 'proposal-over-budget' : 'proposal-invalid');
+    const warning = document.createElement('span');
+    warning.className = 'row-warning';
+    warning.dataset.rowWarning = 'true';
+    warning.textContent = message;
+    row.append(warning);
+  });
+}
+
+function getRowWarning(proposal: ProposalInput, budget: number, ui: ParticipatoryBudgetUI): string {
+  if (!Number.isFinite(proposal.cost) || !Number.isFinite(proposal.score) || !proposal.name.trim()) return ui.invalidProposal;
+  if (Number.isFinite(budget) && proposal.cost > budget) return ui.costExceedsBudget;
+  return '';
+}
+
+function update(root: HTMLElement, form: HTMLFormElement, ui: ParticipatoryBudgetUI): void {
+  const input = readInput(form);
+  markFormFeedback(form, input, ui);
+  const result = allocateBudget(input);
+  saveInput(input);
+  root.querySelector<HTMLElement>('[data-scene]')!.innerHTML = renderAllocationScene(result, ui);
+  root.querySelector<HTMLElement>('[data-result]')!.innerHTML = renderAllocationResult(result, ui);
+  root.querySelector<HTMLElement>('[data-status]')!.textContent = ui.statusSaved;
+}
+
+export function mountParticipatoryBudgetTool(root: HTMLElement, ui: ParticipatoryBudgetUI): void {
+  const form = root.querySelector<HTMLFormElement>('[data-allocation-form]');
+  const rows = root.querySelector<HTMLElement>('[data-proposal-rows]');
+  if (!form || !rows) return;
+  const saved = loadSavedInput();
+  if (saved) setInput(form, saved, rows, ui);
+  const refresh = () => update(root, form, ui);
+  form.addEventListener('input', refresh);
+  root.querySelector('[data-add-proposal]')?.addEventListener('click', () => { addRow(rows, { name: '', cost: Number.NaN, score: Number.NaN }, ui); refresh(); });
+  root.addEventListener('click', (event) => { const target = event.target as HTMLElement; if (target.matches('[data-remove-proposal]')) { target.closest('[data-proposal-row]')?.remove(); refresh(); } });
+  root.querySelector('[data-load-example]')?.addEventListener('click', () => { setInput(form, getExampleInput(), rows, ui); refresh(); });
+  root.querySelector('[data-print]')?.addEventListener('click', () => window.print());
+  refresh();
+}

package/src/tool/participatory-budget-allocator/dom-views.test.ts

@@ -0,0 +1,14 @@
+import { describe, expect, it } from 'vitest';
+import { renderAllocationScene } from './dom-views';
+import { allocateBudget } from './logic';
+import { ui } from './ui';
+
+describe('participatory budget visual scene', () => {
+  it('renders one funded segment and the exact remaining percentage', () => {
+    const result = allocateBudget({ budget: 5000, proposals: [{ name: 'Community tool library', cost: 4200, score: 74 }, { name: 'Library ramp', cost: 1000, score: 20 }] });
+    const scene = renderAllocationScene(result, ui);
+    expect(scene.match(/class="scene-tile"/g)).toHaveLength(1);
+    expect(scene).toContain('--tile-width:84%');
+    expect(scene).toContain('--tile-width:16%');
+  });
+});

package/src/tool/participatory-budget-allocator/dom-views.ts

@@ -0,0 +1,58 @@
+import { getAllocationStatus, getProposalStatusDetail } from './evaluator';
+import type { ParticipatoryBudgetUI } from './ui';
+import type { AllocationResult, ProposalResult } from './logic';
+
+function escapeHtml(value: string): string {
+  return value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;').replace(/'/g, '&#39;');
+}
+
+function formatMoney(value: number): string {
+  return new Intl.NumberFormat('en-US', { minimumFractionDigits: 2, maximumFractionDigits: 2 }).format(value);
+}
+
+function statusLabel(status: ProposalResult['status'], ui: ParticipatoryBudgetUI): string {
+  if (status === 'selected') return ui.selectedStatus;
+  if (status === 'too-expensive') return ui.tooExpensiveStatus;
+  if (status === 'invalid') return ui.invalidStatus;
+  return ui.notSelectedStatus;
+}
+
+function renderTile(proposal: ProposalResult, ui: ParticipatoryBudgetUI): string {
+  return `<li class="mosaic-tile ${proposal.status}"><div class="tile-top"><strong>${escapeHtml(proposal.name)}</strong><span class="tile-status">${escapeHtml(statusLabel(proposal.status, ui))}</span></div><div class="tile-data"><span>${formatMoney(proposal.cost)}</span><span>${escapeHtml(ui.scoreLabel)} ${proposal.score}</span></div><p><b>${escapeHtml(ui.reasonLabel)}:</b> ${escapeHtml(proposal.reason || getProposalStatusDetail(proposal.status))}</p></li>`;
+}
+
+function renderScene(result: AllocationResult, ui: ParticipatoryBudgetUI): string {
+  const percentage = result.totals.budget > 0 ? Math.min(100, Math.max(0, result.totals.spent / result.totals.budget * 100)) : 0;
+  const tiles = result.selected.map((proposal) => `<span class="scene-tile" style="--tile-width:${proposal.cost / Math.max(result.totals.budget, 1) * 100}%" title="${escapeHtml(proposal.name)}"></span>`).join('');
+  const remainder = `<span class="scene-remainder" style="--tile-width:${Math.max(0, result.totals.remaining) / Math.max(result.totals.budget, 1) * 100}%" title="${escapeHtml(ui.remainingLabel)}"></span>`;
+  return `<div class="capacity-scene"><div class="scene-caption"><span>${escapeHtml(ui.allocationLabel)}</span><b>${percentage.toFixed(0)}%</b></div><div class="capacity-track"><div class="capacity-segments">${tiles}${remainder}</div></div><div class="scene-caption scene-footer"><span>${escapeHtml(ui.budgetUsedLabel)} ${formatMoney(result.totals.spent)}</span><span>${escapeHtml(ui.budgetLeftLabel)} ${formatMoney(result.totals.remaining)}</span></div></div>`;
+}
+
+function renderMetrics(result: AllocationResult, ui: ParticipatoryBudgetUI): string {
+  return `<div class="result-metrics"><div><span>${escapeHtml(ui.spentLabel)}</span><strong>${formatMoney(result.totals.spent)}</strong></div><div><span>${escapeHtml(ui.remainingLabel)}</span><strong>${formatMoney(result.totals.remaining)}</strong></div><div><span>${escapeHtml(ui.scoreLabel)}</span><strong>${result.totals.score}</strong></div><div><span>${escapeHtml(ui.proposalCountLabel)}</span><strong>${result.totals.selectedCount}</strong></div></div>`;
+}
+
+function renderWarnings(result: AllocationResult, ui: ParticipatoryBudgetUI): string {
+  const messages = result.errors.map((error) => getErrorMessage(error, ui));
+  if (result.warnings.includes('no-proposals')) messages.push(ui.noProposalsWarning);
+  if (result.warnings.includes('no-feasible-proposal')) messages.push(ui.noFeasibleWarning);
+  return messages.length ? `<div class="result-warning" role="alert">${messages.map((message) => `<p>${escapeHtml(message)}</p>`).join('')}</div>` : '';
+}
+
+function getErrorMessage(error: string, ui: ParticipatoryBudgetUI): string {
+  if (error === 'invalid-budget') return ui.invalidBudget;
+  if (error === 'budget-too-large') return ui.budgetTooLarge;
+  return ui.invalidProposal;
+}
+
+export function renderAllocationResult(result: AllocationResult, ui: ParticipatoryBudgetUI): string {
+  const status = getAllocationStatus(result);
+  const statusClass = `status-${status.tone}`;
+  const selected = result.selected.length ? result.selected.map((proposal) => renderTile(proposal, ui)).join('') : `<li class="empty-list">${escapeHtml(ui.emptyResult)}</li>`;
+  const excluded = result.excluded.map((proposal) => renderTile(proposal, ui)).join('');
+  return `<div class="result-summary ${statusClass}"><div class="status-line"><span class="status-dot"></span><strong>${escapeHtml(status.title)}</strong></div><p>${escapeHtml(status.detail)}</p></div>${renderWarnings(result, ui)}${renderMetrics(result, ui)}<div class="result-section"><h3>${escapeHtml(ui.selectedTilesLabel)}</h3><ul class="mosaic-list">${selected}</ul></div><div class="result-section excluded-section"><h3>${escapeHtml(ui.excludedLabel)}</h3><ul class="mosaic-list">${excluded || `<li class="empty-list">${escapeHtml(ui.emptyResult)}</li>`}</ul></div><p class="tie-break"><b>${escapeHtml(ui.tieBreakLabel)}:</b> ${escapeHtml(result.tieBreak)}</p>`;
+}
+
+export function renderAllocationScene(result: AllocationResult, ui: ParticipatoryBudgetUI): string {
+  return renderScene(result, ui);
+}

package/src/tool/participatory-budget-allocator/entry.ts

@@ -0,0 +1,27 @@
+import type { CivicToolEntry, ToolLocaleContent } from '../../types';
+import type { ParticipatoryBudgetUI } from './ui';
+
+export type ParticipatoryBudgetLocaleContent = ToolLocaleContent<ParticipatoryBudgetUI>;
+
+export const participatoryBudgetAllocator: CivicToolEntry<ParticipatoryBudgetUI> = {
+  id: 'participatory-budget-allocator',
+  phase: 'localized',
+  icons: { bg: 'mdi:bank-outline', fg: 'mdi:shape-outline' },
+  i18n: {
+    en: () => import('./i18n/en').then((module) => module.content),
+    de: () => import('./i18n/de').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/participatory-budget-allocator/evaluator.ts

@@ -0,0 +1,24 @@
+import type { AllocationResult, ProposalStatus } from './logic';
+
+export interface AllocationStatus {
+  tone: 'positive' | 'warning' | 'danger' | 'neutral';
+  title: string;
+  detail: string;
+}
+const statusCopy: Record<ProposalStatus, string> = {
+  selected: 'This proposal belongs to the selected best feasible combination.',
+  'too-expensive': 'This proposal cannot fit within the budget by itself.',
+  'not-selected': 'This proposal was left out because another feasible combination scores better.',
+  invalid: 'Correct this row before reading an allocation.',
+};
+
+export function getProposalStatusDetail(status: ProposalStatus): string {
+  return statusCopy[status];
+}
+
+export function getAllocationStatus(result: AllocationResult): AllocationStatus {
+  if (!result.valid) return { tone: 'danger', title: 'Check the allocation inputs', detail: 'The model cannot compare proposals until the budget and every row are valid.' };
+  if (result.warnings.includes('no-proposals')) return { tone: 'neutral', title: 'Waiting for proposals', detail: 'Add complete proposals to build the allocation mosaic.' };
+  if (result.warnings.includes('no-feasible-proposal')) return { tone: 'warning', title: 'Nothing fits yet', detail: 'Increase the budget or review proposal costs before interpreting the score.' };
+  return { tone: 'positive', title: 'Feasible allocation found', detail: 'The funded set stays within the ceiling and follows the visible tie-break rule.' };
+}

package/src/tool/participatory-budget-allocator/i18n/de.ts

@@ -0,0 +1,44 @@
+import type { FAQPage, HowTo, SoftwareApplication } from 'schema-dts';
+import { bibliography } from '../bibliography';
+import type { ParticipatoryBudgetLocaleContent } from '../entry';
+import type { ParticipatoryBudgetUI } from '../ui';
+
+const ui: ParticipatoryBudgetUI = {
+  budgetLabel: 'Verfügbares Budget', budgetHelp: 'Verwende eine Währung und gib die Obergrenze ein, die nicht überschritten werden darf.', proposalsHeading: 'Vorschläge mit vergleichbarer Punktzahl hinzufügen', proposalNameLabel: 'Name des Vorschlags', proposalCostLabel: 'Kosten', proposalScoreLabel: 'Stimmen oder Nutzwert', addProposal: 'Vorschlag hinzufügen', removeProposal: 'Entfernen', calculateNote: 'Die Auswahl wird beim Bearbeiten aktualisiert. Jeder Vorschlag wird vollständig finanziert oder ausgeschlossen.', loadExample: 'Beispiel laden', printAction: 'Prüfblatt drucken', resultHeading: 'Budgetmosaik', emptyResult: 'Füge Vorschläge hinzu, um eine passende vollständige Auswahl zu sehen.', excludedLabel: 'Nicht finanziert', spentLabel: 'Gesamtkosten', remainingLabel: 'Übriges Budget', scoreLabel: 'Gesamtpunktzahl', proposalCountLabel: 'Vorschläge', selectedStatus: 'Finanziert', tooExpensiveStatus: 'Passt nicht', notSelectedStatus: 'Ausgeschlossen', invalidStatus: 'Korrektur nötig', reasonLabel: 'Warum', methodHeading: 'Angewandte Methode', methodText: 'Das Tool löst ein 0/1-Rucksackproblem. Jeder Vorschlag hat Kosten und eine vergleichbare Punktzahl. Es prüft zulässige Kombinationen, maximiert die Punktzahl und verwendet danach niedrigere Kosten, weniger Vorschläge und die Eingabereihenfolge als eindeutige Gleichstandsregeln.', limitsHeading: 'Was dieses Tool nicht tut', limitsText: 'Es entscheidet nicht, ob ein Vorschlag gerecht, legal, förderfähig, umsetzbar oder gesellschaftlich vorzuziehen ist. Es ersetzt weder Beteiligungsregeln noch eine Abstimmung.', warningsHeading: 'Sonderfälle und Datenwarnungen', warningsText: 'Halte Punktzahlen vergleichbar und verwende dieselbe Kostenbasis. Nullwerte, doppelte Namen, unvollständige Schätzungen, Abhängigkeiten und teilbare Vorteile brauchen eine menschliche Prüfung.', noProposalsWarning: 'Es wurden keine Vorschläge eingegeben.', noFeasibleWarning: 'Kein Vorschlag passt in das verfügbare Budget.', invalidBudget: 'Gib ein nicht negatives Budget ein. Das Browsermodell akzeptiert bis zu 20.000,00 in der gewählten Währung.', budgetTooLarge: 'Das Budget überschreitet die Modellgrenze von 20.000,00. Verringere die Obergrenze oder teile die Runde.', invalidProposal: 'Jede Zeile braucht einen Namen, nicht negative Kosten und eine nicht negative Punktzahl.', costExceedsBudget: 'Diese Kosten überschreiten das verfügbare Budget. Der Vorschlag kann nicht ausgewählt werden.', tieBreakLabel: 'Eindeutige Regel', budgetUsedLabel: 'verwendet', budgetLeftLabel: 'übrig', selectedTilesLabel: 'Ausgewählte Felder', allocationLabel: 'Budgetkapazität', statusSaved: 'Entwurf lokal in diesem Browser gespeichert.',
+};
+
+const faq = [
+  { question: 'Was optimiert dieser Verteiler?', answer: 'Er wählt eine zulässige Menge vollständiger Vorschläge, die die von dir angegebene Gesamtpunktzahl maximiert, ohne die Obergrenze zu überschreiten. Ob diese Punktzahl fair oder sinnvoll ist, entscheidet das Tool nicht.' },
+  { question: 'Warum sind Vorschläge ganz oder gar nicht ausgewählt?', answer: 'Das Modell ist ein 0/1-Modell. Jeder Vorschlag wird zu seinen vollen Kosten umgesetzt oder ausgeschlossen, was für Projekte passt, deren Nutzen von einer vollständigen Umsetzung abhängt.' },
+  { question: 'Was passiert bei gleicher Punktzahl?', answer: 'Dann werden zuerst die niedrigeren Gesamtkosten, danach weniger Vorschläge und schließlich die frühere Eingabereihenfolge gewählt. Die Regel bleibt nachvollziehbar.' },
+  { question: 'Kann das Ergebnis ein echtes Budget entscheiden?', answer: 'Nein. Es ist ein transparentes Szenario. Prüfe Förderfähigkeit, Abhängigkeiten, Umsetzungskapazität, Kostenbasis und das offizielle Verfahren.' },
+];
+const howTo = [
+  { name: 'Obergrenze festlegen', text: 'Gib den verfügbaren Betrag für diese Runde ein und halte die Währungsbasis einheitlich.' },
+  { name: 'Vollständige Vorschläge ergänzen', text: 'Gib jeden Vorschlag einmal mit vollständigen Kosten und einer vergleichbaren Stimmen- oder Nutzwertzahl ein.' },
+  { name: 'Mosaik prüfen', text: 'Prüfe finanzierte Vorschläge, Punktzahl, Kosten und Restbudget beim Aktualisieren der Zeilen.' },
+  { name: 'Ausschlüsse lesen', text: 'Unterscheide Vorschläge, die allein zu teuer sind, von solchen, die gegen eine bessere zulässige Kombination verloren haben.' },
+  { name: 'Menschliche Prüfung anwenden', text: 'Vergleiche das Szenario vor einer Sitzung mit Regeln, Abhängigkeiten, Kapazität und Betroffenen.' },
+];
+const softwareApplication: SoftwareApplication = { '@type': 'SoftwareApplication', name: 'Verteiler für partizipative Budgets', applicationCategory: 'EducationalApplication', operatingSystem: 'Any', description: 'Wähle vollständige öffentliche Vorschläge unter einer festen Budgetgrenze mit einer transparenten Optimierungsregel.', url: 'https://gamebob.dev/de/partizipative-budgetvergabe', offers: { '@type': 'Offer', price: '0', priceCurrency: 'USD' } };
+const faqSchema: FAQPage = { '@type': 'FAQPage', mainEntity: faq.map((item) => ({ '@type': 'Question', name: item.question, acceptedAnswer: { '@type': 'Answer', text: item.answer } })) };
+const howToSchema: HowTo = { '@type': 'HowTo', name: 'Ein partizipatives Budget verteilen', step: howTo.map((step) => ({ '@type': 'HowToStep', name: step.name, text: step.text })) };
+
+export const content: ParticipatoryBudgetLocaleContent = { slug: 'partizipative-budgetvergabe', title: 'Verteiler für partizipative Budgets', description: 'Wähle vollständige Vorschläge unter einer festen Budgetgrenze, maximiere eine erklärte Punktzahl und sieh Kosten und Grund jedes Ausschlusses.', ui, seo: [
+  { type: 'title', text: 'Eine Budgetgrenze in ein nachvollziehbares Szenario verwandeln', level: 2 },
+  { type: 'paragraph', html: 'Bei einer öffentlichen Budgetrunde gibt es oft mehr sinnvolle Vorschläge als verfügbares Geld. Dieser Verteiler macht den Zielkonflikt sichtbar: Grenze eingeben, vollständige Vorschläge ergänzen und eine vergleichbare Stimmen- oder Nutzwertzahl vergeben. Das Ergebnis zeigt eine zulässige Auswahl statt eine undurchsichtige Einzelentscheidung.' },
+  { type: 'title', text: 'So wird die Auswahl berechnet', level: 2 },
+  { type: 'paragraph', html: 'Das Modell ist ein 0/1-Rucksackproblem. Der Browser vergleicht Kombinationen bis zur Obergrenze und behält die mit der höchsten Punktzahl. Bei Gleichstand gelten niedrigere Kosten, weniger Vorschläge und frühere Eingabereihenfolge. Die Punktzahl ist dein erklärtes Ziel, keine unabhängige Messung des öffentlichen Werts.' },
+  { type: 'table', headers: ['Feld', 'Bedeutung', 'Prüffrage'], rows: [['Kosten', 'Voller Betrag für die Umsetzung', 'Sind alle Zeilen gleich kalkuliert?'], ['Punktzahl', 'Eingegebene Stimmen oder Nutzwert', 'Sind die Werte zwischen Vorschlägen vergleichbar?'], ['Budget', 'Maximale Summe der Auswahl', 'Enthält die Grenze dieselben Kosten wie jede Zeile?'], ['Ausschluss', 'Allein zu teuer oder von einer besseren Kombination geschlagen', 'Ist der Grund mathematisch oder politisch zu prüfen?']] },
+  { type: 'title', text: 'Eingaben vorbereiten, die nicht irreführen', level: 2 },
+  { type: 'list', items: ['Prüfe die Förderfähigkeit aller Vorschläge für dieselbe Runde.', 'Nutze vollständige Umsetzungskosten oder echte unabhängige Projektstufen.', 'Dokumentiere, wie Stimmen oder Nutzwerte entstanden sind.', 'Prüfe Abhängigkeiten, Wartung, rechtliche Fragen und Kapazität getrennt.', 'Bewahre Auswahl und Ausschlussgründe als Beratungsprotokoll auf.'] },
+  { type: 'tip', title: 'Eine Punktzahl ist ein gewähltes Ziel', html: 'Bei Stimmen maximiert das Ergebnis die Gesamtstimmen. Bei einer Nutzwertbewertung maximiert es diese Bewertung. Eine andere Punktzahl stellt eine andere Frage, daher sollte ihre Methode mit dem Ergebnis gespeichert werden.' },
+  { type: 'title', text: 'Finanzierte und ausgeschlossene Mengen lesen', level: 2 },
+  { type: 'paragraph', html: 'Finanzierte Vorschläge zeigen Gesamtkosten, Punktzahl und Restbudget. Ein Vorschlag, der nicht passt, ist allein teurer als die Obergrenze. Ein ausgeschlossener Vorschlag könnte allein passen, gehört aber unter dem gewählten Ziel und der Gleichstandsregel nicht zur besten Kombination. Das sind unterschiedliche Gespräche.' },
+  { type: 'title', text: 'Grenzen und nächste Prüfungen', level: 2 },
+  { type: 'paragraph', html: 'Der Verteiler bewertet weder Gerechtigkeit zwischen Stadtteilen noch Lieferrisiko, Abhängigkeiten oder rechtliche Zulässigkeit. Das Browsermodell ist auf 20.000,00 in der gewählten Währung begrenzt, damit die exakte Suche reaktionsfähig bleibt.' },
+  { type: 'paragraph', html: 'Eine Kombination mit hohem Score ist nur so belastbar wie ihre Kostenannahmen und die Regeln für die Score-Erhebung.' },
+  { type: 'title', text: 'Restbudget als Gesprächsanlass nutzen', level: 2 },
+  { type: 'paragraph', html: 'Ein Restbetrag kann bedeuten, dass kein weiterer Vorschlag verbessert, was bereits ausgewählt wurde. Er kann aber auch auf einen fehlenden Vorschlag oder ein bewusst reserviertes Budget hinweisen.' },
+  { type: 'tip', title: 'Vor der Entscheidung prüfen', html: 'Lies die mathematische Auswahl zusammen mit den offiziellen Teilnahmebedingungen und den Stimmen der betroffenen Menschen.' },
+], faq, bibliography, howTo, schemas: [softwareApplication, faqSchema, howToSchema] as unknown as Record<string, unknown>[] };