giteadmin/datatools-dev
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(gui): inline Help popover next to every tool's title

Browse Source 
Adds a contextual Help button on each detail page, right of the title.
Clicking it opens a Streamlit popover with a one-shot how-to: when to
use, numbered steps, before→after examples, and an optional one-line
tip. Designed to be scannable — no paragraph prose.

Implementation:
- New ``render_tool_header(tool_id)`` helper in components replaces the
  bare ``st.title(...) + st.caption(...)`` block on each of the 11 tool
  pages. Title in the wide column, popover in a narrow right column;
  caption sits on its own line beneath.
- Help content is one markdown blob per tool stored in i18n under
  ``tools.<id>.help_md`` (en + es). Editors can tweak copy without
  touching Python.
- ``help.button_label`` and ``help.missing_body`` keys added to both
  packs for the popover trigger and the empty-tool fallback.

All 11 tool pages now use the same header pattern — including the
PDF Extractor and Reconciler which previously had hardcoded title/
caption pairs.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Michael
2026-06-02 17:21:47 +00:00
parent 7203a81af7
commit 904356f4e8
15 changed files with 119 additions and 49 deletions
Download Patch File Download Diff File Expand all files Collapse all files

41
src/i18n/packs/en.json
View File

@@ -15,6 +15,10 @@
"ready": "Ready",
"coming_soon": "Coming Soon"
},
"help": {
"button_label": "Help",
"missing_body": "No help written yet for this tool."
},
"upload": {
"heading": "Import one or more files to start",
"intro": "Optional: scan an imported file for data quality issues and see which tools can fix each one. Skip if you already know what you need.",
@@ -109,61 +113,78 @@
"name": "Find Duplicates",
"description": "Find rows that repeat — exact and similar — and remove the extras.",
"page_title": "Find Duplicates",
"page_caption": "Find rows that repeat, then keep one and remove the extras."
"page_caption": "Find rows that repeat, then keep one and remove the extras.",
"help_md": "**When to use**\n- Customer or contact lists\n- Mailing lists from multiple sources\n- Product catalogs that may overlap\n\n**Steps**\n1. Upload your file\n2. Pick the column(s) that identify a row (email, phone, name+zip)\n3. Choose **Exact** or **Similar** matching\n4. Pick which row to keep (newest, longest, first)\n5. Preview, then export\n\n**Examples**\n- `John Smith` + `JOHN SMITH` → same person\n- `jane@co.com` + `jane@co.com ` → same email (trailing space)\n- `555-1234` + `(555) 1234` → same phone\n\n**Tip** Start with Exact; add Similar if you suspect typos."
},
"02_text_cleaner": {
"name": "Clean Text",
"description": "Trim extra spaces and strip out odd characters that copy-paste leaves behind.",
"page_title": "Clean Text",
"page_caption": "Trim extra spaces and strip out odd characters."
"page_caption": "Trim extra spaces and strip out odd characters.",
"help_md": "**When to use**\n- Text copied from web pages, PDFs, or older systems\n- Files with inconsistent spacing\n- Data with hidden or special characters\n\n**Steps**\n1. Upload your file\n2. Pick the text columns to clean\n3. Choose options: trim spaces, remove invisible characters, normalize quotes\n4. Preview the changes\n5. Export\n\n**Examples**\n- ` hello world ` → `hello world`\n- `“smart quotes”` → `\"normal quotes\"`\n- `data​with​hidden` → `datawithhidden`\n\n**Tip** Always preview — text changes can affect later steps like duplicate detection."
},
"03_format_standardizer": {
"name": "Standardize Formats",
"description": "Make dates, phone numbers, currency, names, and addresses look the same throughout.",
"page_title": "Standardize Formats",
"page_caption": "Make dates, phones, currency, and names look the same throughout."
"page_caption": "Make dates, phones, currency, and names look the same throughout.",
"help_md": "**When to use**\n- Data from multiple sources that wrote dates/phones differently\n- Before sending to a system that wants one format\n- Preparing data for analysis or charts\n\n**Steps**\n1. Upload your file\n2. Pick a column (date, phone, currency, etc.)\n3. Choose the target format\n4. Preview\n5. Repeat for other columns, then export\n\n**Examples**\n- `Jan 5, 2025` / `01/05/2025` / `5-Jan-25` → `2025-01-05`\n- `(555) 123-4567` / `555.123.4567` → `+1 555-123-4567`\n- `$1,234.50` / `1234.5 USD` → `1234.50`\n\n**Tip** Run on several columns in one session — each column remembers its chosen format."
},
"04_missing_handler": {
"name": "Fix Missing Values",
"description": "Find blank cells (even ones written as 'N/A' or '?') and fill them in or remove them.",
"page_title": "Fix Missing Values",
"page_caption": "Find blank cells (even hidden ones) and fill them in or remove them."
"page_caption": "Find blank cells (even hidden ones) and fill them in or remove them.",
"help_md": "**When to use**\n- Spreadsheets with gaps\n- Files where someone typed `N/A` or `-` instead of leaving a cell blank\n- Before importing into a system that rejects blanks\n\n**Steps**\n1. Upload your file\n2. Review which columns have blanks\n3. Pick a strategy per column: **fill**, **drop the row**, or **leave alone**\n4. For numbers, pick a fill value: average, median, zero, or your own\n5. Preview, then export\n\n**Examples**\n- `N/A`, `-`, ` ` → treated as blank\n- Blank salary → filled with the column average\n- Row with no email → dropped\n\n**Tip** Don't fill the row's identifier (email, ID) — drop the row instead."
},
"05_column_mapper": {
"name": "Map Columns",
"description": "Rename columns, change their order, and set each one as text, number, or date.",
"page_title": "Map Columns",
"page_caption": "Rename columns, change their order, and set each one as text, number, or date."
"page_caption": "Rename columns, change their order, and set each one as text, number, or date.",
"help_md": "**When to use**\n- Combining files from vendors with different column names\n- Forcing the layout your system expects\n- Cleaning up exports with extra or weirdly-named columns\n\n**Steps**\n1. Upload your file\n2. Match each incoming column to your standard name\n3. Set each column's type: text, number, or date\n4. Reorder or drop columns\n5. Export with the new layout\n\n**Examples**\n- `cust_email` → `Customer Email`\n- `amt` → `Amount` (set as number)\n- `notes_internal` → drop\n\n**Tip** Save the mapping if you'll get the same file format again next month."
},
"06_outlier_detector": {
"name": "Find Unusual Values",
"description": "Spot values that look wrong — way too high, way too low, or breaking your rules.",
"page_title": "Find Unusual Values",
"page_caption": "Spot values that look wrong — way too high, too low, or breaking your rules."
"page_caption": "Spot values that look wrong — way too high, too low, or breaking your rules.",
"help_md": "**When to use**\n- Spotting typos, fraud, or bad imports in numeric data\n- Cleaning sensor or transaction data\n- Before reporting numbers to leadership\n\n**Steps**\n1. Upload your file\n2. Pick the numeric column to check\n3. Set a normal range (or use auto-detect)\n4. Review the flagged rows\n5. Choose: keep, remove, or cap to the limit\n\n**Examples**\n- Salary column with one row at `$9,999,999` → flagged\n- Age column with `250` → flagged\n- Rule: `price must be > 0` → flags negatives\n\n**Tip** Review flagged rows by hand — a real outlier is sometimes the most important data point."
},
"07_multi_file_merger": {
"name": "Combine Files",
"description": "Combine several CSV or Excel files into one — even if their columns don't match.",
"page_title": "Combine Files",
"page_caption": "Combine several CSV or Excel files into one — even if columns differ."
"page_caption": "Combine several CSV or Excel files into one — even if columns differ.",
"help_md": "**When to use**\n- Monthly reports across the year\n- Exports from different stores or branches\n- Multi-system data that needs to be in one file\n\n**Steps**\n1. Upload two or more files\n2. Confirm column matches (auto-detected; override if needed)\n3. Pick how to handle missing columns (skip, blank, default value)\n4. Preview the combined result\n5. Export the single file\n\n**Examples**\n- `January.csv` + `February.csv` → `2025.csv`\n- `NY-store.xlsx` + `LA-store.xlsx` → `all-stores.csv`\n- File A has `Email`, file B has `email_addr` → matched automatically\n\n**Tip** Add a `source` column so you can tell which file each row came from."
},
"08_validator_reporter": {
"name": "Quality Check",
"description": "Check your file against rules you set, and export a PDF or Excel report.",
"page_title": "Quality Check",
"page_caption": "Check your file against rules and export a PDF or Excel report."
"page_caption": "Check your file against rules and export a PDF or Excel report.",
"help_md": "**When to use**\n- Before handing data off to a client or partner\n- Before a strict system import\n- Routine quality audits\n\n**Steps**\n1. Upload your file\n2. Pick the rules to check (required columns, valid emails, no duplicates)\n3. Run the check\n4. Review the score and findings\n5. Export the report as PDF or Excel\n\n**Examples**\n- Rule: `email column must look like an email` → 12 rows fail\n- Rule: `amount must be > 0` → 3 rows fail\n- Rule: `no duplicate customer IDs` → 5 duplicates found\n\n**Tip** Run this last in your cleanup, then keep the PDF as proof of quality."
},
"09_pipeline_runner": {
"name": "Automated Workflows",
"description": "Run several tools in a row — save the steps once, reuse them anytime.",
"page_title": "Automated Workflows",
"page_caption": "Run several tools in a row — save the steps and reuse them anytime."
"page_caption": "Run several tools in a row — save the steps and reuse them anytime.",
"help_md": "**When to use**\n- A cleanup you do every week or month\n- Multi-step processes you keep repeating\n- Onboarding teammates to your data routine\n\n**Steps**\n1. Pick the tools you want to run, in order\n2. Configure each step\n3. Save the workflow as a JSON file\n4. Next time, load the workflow and upload a fresh file\n5. Get the cleaned output in one click\n\n**Examples**\n- `Clean Text` → `Standardize Formats` → `Find Duplicates` → export\n- Saved as `weekly-customer-cleanup.json`\n- Shared with a teammate so they get the same result\n\n**Tip** Start with two or three tools. You can always edit and add more later."
},
"10_pdf_extractor": {
"name": "PDF to CSV",
"description": "Pull transactions out of bank-statement PDFs into a clean CSV file.",
"page_title": "PDF to CSV",
"page_caption": "Pull transactions out of bank-statement PDFs into a clean CSV file."
"page_caption": "Pull transactions out of bank-statement PDFs into a clean CSV file.",
"help_md": "**When to use**\n- Bank or credit-card statements\n- Vendor invoices with line-item tables\n- Any PDF with a transaction table\n\n**Steps**\n1. Upload a PDF\n2. Draw a box around the table (once per source)\n3. Save the template (e.g. `Chase Checking`)\n4. Reuse the template on every future statement of that type\n5. Export the CSV\n\n**Examples**\n- Chase March statement → 87 transactions extracted\n- Same template auto-runs on April, May, June\n- Batch mode: process 12 months at once\n\n**Tip** Templates are per source (Chase, Wells Fargo, …). Build one per source you receive regularly."
},
"11_reconciler": {
"name": "Reconcile Two Files",
"description": "Compare two lists of transactions (e.g. bank vs. ledger) and flag what doesn't match.",
"page_title": "Reconcile Two Files",
"page_caption": "Compare two lists of transactions (e.g. bank vs. ledger) and flag what doesn't match.",
"help_md": "**When to use**\n- Matching your bank statement to your books\n- Vendor invoices vs. payments sent\n- Inventory receipts vs. orders placed\n\n**Steps**\n1. Upload both files (e.g. bank export + accounting export)\n2. Pick the columns to match on (date, amount, reference)\n3. Set tolerances (e.g. date ±2 days, amount exact)\n4. Review four buckets: **matched**, **only in left**, **only in right**, **needs review**\n5. Export the results\n\n**Examples**\n- Bank `2025-03-15 $99.50` ↔ Books `2025-03-16 $99.50` → matched\n- Bank charge with no books entry → only in left\n- Same amount on the same day twice → flagged for review\n\n**Tip** Tighten the date tolerance once you trust the match — fewer ambiguous cases to review."
}
},
"nav": {