@jjlmoya/utils-civic 1.6.0 → 1.7.0

package/src/tool/public-budget-analyzer/public-budget-analyzer.css

@@ -0,0 +1,461 @@
+:root {
+  --n-paper: #f8f6ef;
+  --n-surface: #fffdf8;
+  --n-ink: #1d252c;
+  --n-muted: #5b6870;
+  --n-line: #cbd5d2;
+  --n-accent: #a6442f;
+  --n-accent-strong: #7d2f27;
+  --n-segment-a: #1e6870;
+  --n-segment-b: #c97943;
+  --n-good: #286c4a;
+  --n-warn-bg: #fff1d2;
+  --n-warn-ink: #704b0b;
+  --n-error-bg: #f9dfdb;
+  --n-error-ink: #7d2f27;
+  --n-shadow: rgba(29, 37, 44, 0.12);
+}
+
+.theme-dark {
+  --n-paper: #15171b;
+  --n-surface: #20242a;
+  --n-ink: #f3eee3;
+  --n-muted: #bcc3c5;
+  --n-line: #4b555b;
+  --n-accent: #e48663;
+  --n-accent-strong: #ffad86;
+  --n-segment-a: #63bcc0;
+  --n-segment-b: #e5a068;
+  --n-good: #7ad49e;
+  --n-warn-bg: #473818;
+  --n-warn-ink: #ffe09b;
+  --n-error-bg: #512923;
+  --n-error-ink: #ffb5a5;
+  --n-shadow: rgba(0, 0, 0, 0.3);
+}
+
+.public-budget-analyzer {
+  --n-paper: #f8f6ef;
+  --n-surface: #fffdf8;
+  --n-ink: #1d252c;
+  --n-muted: #5b6870;
+  --n-line: #cbd5d2;
+  --n-accent: #a6442f;
+  --n-accent-strong: #7d2f27;
+  --n-segment-a: #1e6870;
+  --n-segment-b: #c97943;
+  --n-good: #286c4a;
+  --n-warn-bg: #fff1d2;
+  --n-warn-ink: #704b0b;
+  --n-error-bg: #f9dfdb;
+  --n-error-ink: #7d2f27;
+  --n-shadow: rgba(29, 37, 44, 0.12);
+
+  background: var(--n-paper);
+  border: 1px solid var(--n-line);
+  border-radius: 1.25rem;
+  box-shadow: 0 1rem 2rem var(--n-shadow);
+  color: var(--n-ink);
+  min-width: 0;
+  overflow: hidden;
+}
+
+.theme-dark .public-budget-analyzer {
+  --n-paper: #15171b;
+  --n-surface: #20242a;
+  --n-ink: #f3eee3;
+  --n-muted: #bcc3c5;
+  --n-line: #4b555b;
+  --n-accent: #e48663;
+  --n-accent-strong: #ffad86;
+  --n-segment-a: #63bcc0;
+  --n-segment-b: #e5a068;
+  --n-good: #7ad49e;
+  --n-warn-bg: #473818;
+  --n-warn-ink: #ffe09b;
+  --n-error-bg: #512923;
+  --n-error-ink: #ffb5a5;
+  --n-shadow: rgba(0, 0, 0, 0.3);
+}
+
+main:has(.public-budget-analyzer) {
+  min-width: 0;
+}
+
+.budget-command-bar,
+.budget-result,
+.budget-guidance {
+  padding: 1.5rem;
+}
+
+.budget-command-bar {
+  align-items: stretch;
+  border-bottom: 1px solid var(--n-line);
+  display: grid;
+  gap: 1rem;
+  grid-template-columns: minmax(0, 1fr);
+  min-width: 0;
+}
+
+.budget-dropzone {
+  border: 1px dashed var(--n-accent);
+  border-radius: 0.75rem;
+  padding: 1rem;
+  position: relative;
+  min-width: 0;
+}
+
+.budget-dropzone.is-dragging {
+  background: var(--n-warn-bg);
+}
+
+.budget-dropzone input {
+  block-size: 100%;
+  cursor: pointer;
+  inline-size: 100%;
+  inset: 0;
+  opacity: 0;
+  position: absolute;
+}
+
+.budget-dropzone label {
+  color: var(--n-accent-strong);
+  display: block;
+  font-size: 1rem;
+  font-weight: 800;
+}
+
+.budget-dropzone p,
+.budget-dropzone small {
+  color: var(--n-muted);
+  display: block;
+  line-height: 1.5;
+  margin: 0.35rem 0 0;
+  overflow-wrap: anywhere;
+}
+
+.budget-actions {
+  align-items: center;
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.5rem;
+  justify-content: flex-start;
+  min-width: 0;
+}
+
+.budget-actions button {
+  background: var(--n-surface);
+  border: 1px solid var(--n-line);
+  border-radius: 999px;
+  color: var(--n-ink);
+  cursor: pointer;
+  flex: 1 1 8rem;
+  font: inherit;
+  font-size: 0.82rem;
+  min-width: 0;
+  max-width: 16rem;
+  padding: 0.65rem 0.85rem;
+  white-space: normal;
+}
+
+.budget-actions button:first-child {
+  background: var(--n-accent);
+  border-color: var(--n-accent);
+  color: var(--n-surface);
+}
+
+.budget-actions button:hover,
+.budget-actions button:focus-visible {
+  border-color: var(--n-accent-strong);
+  outline: 2px solid var(--n-accent);
+  outline-offset: 2px;
+}
+
+.budget-result {
+  background: var(--n-surface);
+  min-height: 16rem;
+  min-width: 0;
+}
+
+.budget-result-head,
+.budget-detail-heading,
+.budget-landscape-axis,
+.budget-category-label,
+.budget-facts {
+  align-items: baseline;
+  display: flex;
+  gap: 1rem;
+  justify-content: space-between;
+}
+
+.budget-result-head h2,
+.budget-detail-heading h3,
+.budget-guidance h2,
+.budget-notice h3 {
+  color: var(--n-ink);
+  margin: 0;
+}
+
+.budget-result-head > p,
+.budget-detail-heading > span,
+.budget-category-row small,
+.budget-landscape-axis,
+.budget-facts span {
+  color: var(--n-muted);
+  font-size: 0.78rem;
+}
+
+.budget-status {
+  border: 1px solid var(--n-line);
+  border-radius: 999px;
+  display: inline-block;
+  font-size: 0.7rem;
+  font-weight: 800;
+  letter-spacing: 0.04em;
+  margin-bottom: 0.55rem;
+  padding: 0.25rem 0.55rem;
+  text-transform: uppercase;
+}
+
+.budget-status-ready { color: var(--n-good); }
+.budget-status-review { color: var(--n-warn-ink); }
+.budget-status-empty { color: var(--n-muted); }
+
+.budget-metrics {
+  display: grid;
+  gap: 0.6rem;
+  grid-template-columns: repeat(4, minmax(0, 1fr));
+  margin: 1.5rem 0;
+}
+
+.budget-metric {
+  border-left: 3px solid var(--n-accent);
+  min-width: 0;
+  padding: 0.25rem 0 0.25rem 0.75rem;
+}
+
+.budget-metric span,
+.budget-metric strong,
+.budget-facts strong,
+.budget-facts span {
+  display: block;
+}
+
+.budget-metric span {
+  color: var(--n-muted);
+  font-size: 0.75rem;
+}
+
+.budget-metric strong {
+  font-size: 1.08rem;
+  margin-top: 0.25rem;
+  overflow-wrap: anywhere;
+}
+
+.budget-landscape {
+  border-top: 1px solid var(--n-line);
+  padding-top: 0.8rem;
+}
+
+.budget-category-row {
+  margin-top: 0.9rem;
+}
+
+.budget-category-label strong {
+  font-size: 0.86rem;
+  overflow-wrap: anywhere;
+  white-space: normal;
+}
+
+.budget-category-label span {
+  overflow-wrap: anywhere;
+  min-width: 0;
+}
+
+.budget-bar {
+  background: var(--n-paper);
+  border: 1px solid var(--n-line);
+  height: 1rem;
+  margin-top: 0.35rem;
+  overflow: hidden;
+}
+
+.budget-bar span {
+  background: var(--n-segment-a);
+  display: block;
+  height: 100%;
+  width: var(--segment-width);
+}
+
+.budget-bar .budget-segment-b {
+  background: var(--n-segment-b);
+}
+
+.budget-category-row small {
+  display: block;
+  margin-top: 0.3rem;
+}
+
+.budget-detail {
+  border-top: 1px solid var(--n-line);
+  margin-top: 1.5rem;
+  min-width: 0;
+  padding-top: 1.25rem;
+}
+
+.budget-table-wrap {
+  min-width: 0;
+  overflow-x: auto;
+}
+
+.budget-table-wrap table {
+  border-collapse: collapse;
+  margin-top: 0.8rem;
+  min-width: 42rem;
+  width: 100%;
+}
+
+.budget-table-wrap th,
+.budget-table-wrap td {
+  border-bottom: 1px solid var(--n-line);
+  padding: 0.65rem 0.5rem;
+  text-align: left;
+  vertical-align: top;
+}
+
+.budget-table-wrap th {
+  color: var(--n-muted);
+  font-size: 0.72rem;
+  text-transform: uppercase;
+}
+
+.budget-table-wrap td {
+  font-size: 0.84rem;
+}
+
+.budget-notice {
+  border-left: 4px solid var(--n-accent);
+  margin-top: 1.25rem;
+  padding: 0.8rem 1rem;
+}
+
+.budget-notice-warning {
+  background: var(--n-warn-bg);
+  border-color: var(--n-warn-ink);
+  color: var(--n-warn-ink);
+}
+
+.budget-notice-error {
+  background: var(--n-error-bg);
+  border-color: var(--n-error-ink);
+  color: var(--n-error-ink);
+}
+
+.budget-notice h3 {
+  color: var(--n-ink);
+  font-size: 0.95rem;
+}
+
+.budget-notice ul {
+  line-height: 1.5;
+  margin: 0.5rem 0 0;
+  padding-left: 1.15rem;
+}
+
+.budget-facts {
+  border-top: 1px solid var(--n-line);
+  flex-wrap: wrap;
+  margin-top: 1.5rem;
+  padding-top: 1rem;
+}
+
+.budget-facts div {
+  min-width: 10rem;
+}
+
+.budget-facts strong {
+  margin-top: 0.25rem;
+  overflow-wrap: anywhere;
+}
+
+.budget-empty-note,
+.budget-inline-message {
+  border: 1px solid var(--n-line);
+  color: var(--n-muted);
+  margin: 0;
+  padding: 1rem;
+}
+
+.budget-inline-error {
+  background: var(--n-error-bg);
+  border-color: var(--n-error-ink);
+  color: var(--n-error-ink);
+}
+
+.budget-guidance {
+  border-top: 1px solid var(--n-line);
+  display: grid;
+  gap: 1rem;
+  grid-template-columns: repeat(3, minmax(0, 1fr));
+}
+
+.budget-guidance section {
+  border-left: 2px solid var(--n-accent);
+  padding-left: 0.8rem;
+}
+
+.budget-guidance h2 {
+  font-size: 0.92rem;
+}
+
+.budget-guidance p {
+  color: var(--n-muted);
+  font-size: 0.83rem;
+  line-height: 1.55;
+  margin: 0.5rem 0 0;
+}
+
+@media (max-width: 800px) {
+  .budget-command-bar,
+  .budget-guidance {
+    grid-template-columns: 1fr;
+  }
+
+  .budget-actions {
+    justify-content: flex-start;
+  }
+
+  .budget-metrics {
+    grid-template-columns: repeat(2, minmax(0, 1fr));
+  }
+}
+
+@media (max-width: 480px) {
+  .budget-command-bar,
+  .budget-result,
+  .budget-guidance {
+    padding: 1rem;
+  }
+
+  .budget-metrics {
+    grid-template-columns: 1fr;
+  }
+
+  .budget-result-head,
+  .budget-detail-heading,
+  .budget-category-label {
+    align-items: flex-start;
+    flex-direction: column;
+    gap: 0.25rem;
+  }
+}
+
+@media print {
+  .public-budget-analyzer {
+    box-shadow: none;
+  }
+
+  .budget-command-bar {
+    display: none;
+  }
+}

package/src/tool/public-budget-analyzer/seo.astro

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

package/src/tool/public-budget-analyzer/storage.ts

@@ -0,0 +1,28 @@
+const storageKey = 'jjlmoya-public-budget-analyzer';
+
+export interface SavedBudgetState {
+  format: 'csv' | 'json';
+  text: string;
+}
+
+export function loadSavedBudget(): SavedBudgetState | undefined {
+  try {
+    const value = window.localStorage.getItem(storageKey);
+    if (!value) return undefined;
+    const parsed: unknown = JSON.parse(value);
+    if (!parsed || typeof parsed !== 'object') return undefined;
+    const candidate = parsed as Record<string, unknown>;
+    if ((candidate.format !== 'csv' && candidate.format !== 'json') || typeof candidate.text !== 'string') return undefined;
+    return { format: candidate.format, text: candidate.text };
+  } catch {
+    return undefined;
+  }
+}
+
+export function saveBudgetState(state: SavedBudgetState): void {
+  try {
+    window.localStorage.setItem(storageKey, JSON.stringify(state));
+  } catch {
+    return;
+  }
+}

package/src/tool/public-budget-analyzer/ui.ts

@@ -0,0 +1,78 @@
+export interface PublicBudgetUI {
+  [key: string]: string;
+  uploadLabel: string;
+  uploadHelp: string;
+  loadExample: string;
+  supportedFormat: string;
+  tableHeading: string;
+  categoryLabel: string;
+  amountLabel: string;
+  populationLabel: string;
+  sourceRowsLabel: string;
+  analyzeEmpty: string;
+  resultHeading: string;
+  totalLabel: string;
+  perCapitaLabel: string;
+  variationLabel: string;
+  topCategoryLabel: string;
+  shareLabel: string;
+  sourceLabel: string;
+  noData: string;
+  warningsHeading: string;
+  errorsHeading: string;
+  methodHeading: string;
+  methodText: string;
+  limitsHeading: string;
+  limitsText: string;
+  edgeCasesHeading: string;
+  edgeCasesText: string;
+  downloadCsv: string;
+  printAction: string;
+  rowsLabel: string;
+  categoriesLabel: string;
+  positiveTotalLabel: string;
+  previousTotalLabel: string;
+  invalidFile: string;
+  fileReadError: string;
+  exampleName: string;
+  noPreviousData: string;
+}
+
+export const ui: PublicBudgetUI = {
+  uploadLabel: 'Drop a budget CSV or JSON file here',
+  uploadHelp: 'Required fields: category and amount. Optional fields: population, period, priorAmount, currency, and parentCategory.',
+  loadExample: 'Load example budget',
+  supportedFormat: 'CSV or JSON, processed only in this browser',
+  tableHeading: 'Source rows and category totals',
+  categoryLabel: 'Category',
+  amountLabel: 'Amount',
+  populationLabel: 'Population',
+  sourceRowsLabel: 'Source rows',
+  analyzeEmpty: 'Choose a file or load the example to inspect a budget.',
+  resultHeading: 'Budget landscape',
+  totalLabel: 'Total spending',
+  perCapitaLabel: 'Spending per person',
+  variationLabel: 'Change from prior period',
+  topCategoryLabel: 'Largest category',
+  shareLabel: 'Share of total',
+  sourceLabel: 'Source rows',
+  noData: 'No valid budget rows are available yet.',
+  warningsHeading: 'Warnings to review',
+  errorsHeading: 'Rows not included',
+  methodHeading: 'Method applied',
+  methodText: 'The tool validates the required fields, preserves each source row, groups exact category paths, and calculates totals from the normalized amounts. Category share is amount divided by the total when the total is positive. Per capita spending divides the total by the first consistent positive population denominator. Period change is (current minus prior) divided by prior, and is omitted when the prior amount is zero.',
+  limitsHeading: 'What this tool does not do',
+  limitsText: 'It does not prove that a budget is complete, comparable, legal, efficient, fair, unbiased, or correctly classified. It does not audit the source, infer policy quality, reconcile currencies, or identify whether a row is an appropriation, obligation, payment, or forecast.',
+  edgeCasesHeading: 'Edge cases and data warnings',
+  edgeCasesText: 'Mixed currencies, changing populations, duplicate categories, negative adjustments, parent rows beside child rows, locale-specific number formats, and zero prior amounts need human review. The browser keeps the original row number so every aggregate can be traced back to its input.',
+  downloadCsv: 'Download reviewed table',
+  printAction: 'Print analysis',
+  rowsLabel: 'valid rows',
+  categoriesLabel: 'categories',
+  positiveTotalLabel: 'positive amounts visualized',
+  previousTotalLabel: 'Previous total',
+  invalidFile: 'The file could not be understood as a non-empty CSV or JSON table.',
+  fileReadError: 'The file could not be read in this browser.',
+  exampleName: 'Community budget sample',
+  noPreviousData: 'No comparable prior-period amount was supplied.',
+};

package/src/tools.ts

@@ -6,6 +6,7 @@ import { ELECTION_SEAT_APPORTIONMENT_CALCULATOR_TOOL } from './tool/election-sea
 import { REFERENDUM_THRESHOLD_CALCULATOR_TOOL } from './tool/referendum-threshold-calculator';
 import { VOTE_SEAT_DISPROPORTIONALITY_ANALYZER_TOOL } from './tool/vote-seat-disproportionality-analyzer';
 import { PARTICIPATORY_BUDGET_ALLOCATOR_TOOL } from './tool/participatory-budget-allocator';
+import { PUBLIC_BUDGET_ANALYZER_TOOL } from './tool/public-budget-analyzer';
 
 export const ALL_TOOLS: ToolDefinition[] = [
   COALITION_MAJORITY_CALCULATOR_TOOL,
@@ -14,4 +15,5 @@ export const ALL_TOOLS: ToolDefinition[] = [
   REFERENDUM_THRESHOLD_CALCULATOR_TOOL,
   VOTE_SEAT_DISPROPORTIONALITY_ANALYZER_TOOL,
   PARTICIPATORY_BUDGET_ALLOCATOR_TOOL,
+  PUBLIC_BUDGET_ANALYZER_TOOL,
 ];