docs: cover help popover, +/- nav indicators, render_tool_header
User-facing docs (USER-GUIDE en+es, README en+es): - New short paragraph under §3.1 GUI noting the in-tool Help button on every detail page, what it contains (When to use / Steps / Examples / Tip), and that content lives in tools.<id>.help_md. - One-line note in the README tool tables pointing at the same. - Mention the sidebar +/- nav indicators replacing Streamlit's default Material Symbols chevron. Developer docs: - DEVELOPER: new "Tool page header" subsection documenting render_tool_header(tool_id), the help_md markdown skeleton, and the fallback to help.missing_body when a tool's help is absent. Update i18n authoring rules to list help.* keys and the per-tool help_md field alongside name/description/page_title/page_caption. - TECHNICAL: new §10c documenting the sidebar nav indicator swap — CSS in _HIDE_CHROME_CSS plus _SWAP_NAV_SECTION_INDICATOR_JS injected through the hide_streamlit_chrome() iframe bundle. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -18,6 +18,8 @@ Limpieza local de CSV / Excel. CLI + GUI en el navegador, sin nube, sin ceremoni
|
||||
| 08 | Verificación de calidad | Próximamente |
|
||||
| 09 | **Flujos automatizados** — encadena herramientas en un orden recomendado (no forzado), guarda/carga JSON, automatiza limpiezas semanales | Listo |
|
||||
|
||||
Cada página de herramienta incluye una ventana emergente de **Help** (a la derecha del título) con una guía compacta de Cuándo usarla / Pasos / Ejemplos / Consejo. El texto vive en los paquetes de idioma (`tools.<id>.help_md`).
|
||||
|
||||
## Descarga (usuarios no técnicos)
|
||||
|
||||
Paquetes precompilados — sin instalar Python, sin permisos de administrador, sin internet en ejecución. Cada versión ofrece dos formatos por sistema operativo: un **instalador** que crea accesos directos en el escritorio + menú Inicio / Launchpad, y un **.zip portable** que descomprimes y haces doble clic. Elige el que te permita tu política de TI.
|
||||
|
||||
@@ -18,6 +18,8 @@ Local CSV / Excel cleaning. CLI + browser GUI, no cloud, no install ceremony. GU
|
||||
| 08 | Quality Check | Coming Soon |
|
||||
| 09 | **Automated Workflows** — chain tools with recommended (not forced) order, save/load JSON, automate weekly cleanups | Ready |
|
||||
|
||||
Every tool page has an in-tool **Help** popover (right of the title) with a compact When-to-use / Steps / Examples / Tip card. Copy lives in the language packs (`tools.<id>.help_md`).
|
||||
|
||||
## Download (non-technical users)
|
||||
|
||||
Pre-built bundles — no Python install, no admin rights, no internet at runtime. Each release ships two flavors per OS: an **installer** that wires up Desktop + Start Menu / Launchpad shortcuts, and a **portable .zip** you unzip and double-click. Pick whichever your IT policy allows.
|
||||
|
||||
@@ -96,6 +96,36 @@ DeduplicationResult # deduplicated_df, removed_df, match_groups, l
|
||||
|
||||
No other call sites change. Gate auto-discovers it via the registry.
|
||||
|
||||
### Tool page header — `render_tool_header(tool_id)`
|
||||
|
||||
Every tool page renders its title block via `render_tool_header(tool_id)` in `src/gui/components/_legacy.py` — do not call `st.title()` + `st.caption()` directly. The helper renders:
|
||||
|
||||
- `tools.<id>.page_title` as the page title (left column).
|
||||
- A **Help** popover button right of the title (icon `:material/help_outline:`, label from `help.button_label`). Clicking opens an `st.popover` containing the markdown body.
|
||||
- `tools.<id>.page_caption` as the caption below.
|
||||
|
||||
All copy is i18n-driven; editors can tweak help text without touching Python. If a tool is missing its `help_md` key, the popover falls back to `help.missing_body`.
|
||||
|
||||
**`help_md` structure** (markdown, stored as a single string with `\n` line breaks in JSON):
|
||||
|
||||
```
|
||||
**When to use**
|
||||
- bullet 1
|
||||
- bullet 2
|
||||
|
||||
**Steps**
|
||||
1. numbered step
|
||||
2. numbered step
|
||||
|
||||
**Examples**
|
||||
- example 1
|
||||
- example 2
|
||||
|
||||
**Tip** one-sentence pro tip.
|
||||
```
|
||||
|
||||
Keep it short — the popover is intentionally compact. Mirror the structure across every tool so the muscle memory transfers.
|
||||
|
||||
### i18n — language packs
|
||||
|
||||
The GUI's user-facing strings live in `src/i18n/packs/<code>.json`, keyed by ISO-639-1 code. English (`en.json`) is canonical; missing keys in other packs fall back to English, and missing keys in English fall back to the literal dotted key so a typo is visible rather than silent.
|
||||
@@ -120,7 +150,8 @@ st.warning(t("gate.warning", name=filename)) # {name} interpolated via str.for
|
||||
3. Use the dotted key at the call site: `t("section.subsection.key")` or `t("section.key", name=value)` for placeholder interpolation.
|
||||
|
||||
**Authoring rules:**
|
||||
- Keys live under semantic sections (`home.*`, `upload.*`, `findings.*`, `tools.<id>.name`). Don't nest by language or by tool unless the string is genuinely tool-specific.
|
||||
- Keys live under semantic sections (`home.*`, `upload.*`, `findings.*`, `help.*`, `tools.<id>.name`). Don't nest by language or by tool unless the string is genuinely tool-specific.
|
||||
- Per-tool header copy lives under `tools.<id>.{page_title, page_caption, help_md}`. `page_caption` is the one-line subtitle under the title; `help_md` is the popover body (see *Tool page header* above). Top-level `help.button_label` / `help.missing_body` are shared across every tool.
|
||||
- Use `{named}` placeholders (not positional `{0}`) so translators see what's being interpolated.
|
||||
- Strings can contain Streamlit markdown (`**bold**`) — pass through `st.markdown` / `st.caption` as usual.
|
||||
- Do **not** put strings inside the farewell-overlay JS payload without going through `_js_html_safe()` in `src/gui/components/_legacy.py`; the helper escapes both the JS string terminator and HTML special chars. The test `TestFarewellEscape` pins that contract.
|
||||
|
||||
@@ -242,6 +242,15 @@ The GUI uses an in-house, JSON-backed translation layer at `src/i18n/`. **No** `
|
||||
|
||||
**Why not gettext**: zero compiled artifacts in the PyInstaller bundle, no build step before tests run, no `.po`/`.mo` round-trip for translators (anyone can edit JSON), and the same lookup works in unit tests without process state. Locked in because the surface won't grow large enough to need the alternative, and the alternative breaks the "drop a file, run pytest, ship" loop.
|
||||
|
||||
## 10c. GUI chrome — sidebar nav indicator swap
|
||||
|
||||
Streamlit's `st.Page`-driven sidebar renders section headers with a Material Symbols ligature (`expand_more` / `expand_less`). The header element is not a button and carries no `aria-expanded`, so a pure-CSS swap can't follow open/closed state. We replace the glyph with plain typographic `+` / `−` (U+2212) via JS:
|
||||
|
||||
- **CSS** (`components/_legacy.py`, `_HIDE_CHROME_CSS`) drops the Material Symbols font on `[data-testid="stIconMaterial"]` inside `[data-testid="stNavSectionHeader"]` so the rewritten character renders as normal text rather than re-resolving as an icon name.
|
||||
- **JS** (`_SWAP_NAV_SECTION_INDICATOR_JS`) walks each section header, reads the icon's text node, and rewrites `expand_more` → `+` / `expand_less` → `−`. A MutationObserver re-runs the swap when Streamlit re-renders the sidebar (RAF-throttled so a burst of mutations is one swap).
|
||||
|
||||
The script ships through the same component-iframe bundle as the brand injector and upload-button rename inside `hide_streamlit_chrome()` — one iframe per page, three DOM mutations.
|
||||
|
||||
## 11. Per-script functional specs
|
||||
|
||||
Specs live in this section as scripts enter active build. Each follows the Tier 1/2/3 structure with explicit strategic framing (what's the market gap given some of this is free elsewhere).
|
||||
|
||||
@@ -135,6 +135,10 @@ Matriz de soporte completa: [REQUIREMENTS.md](REQUIREMENTS.md) (solo en inglés)
|
||||
|
||||
Las opciones avanzadas se encuentran en paneles desplegables. El archivo original nunca se modifica.
|
||||
|
||||
**Ayuda en la herramienta**: cada página tiene un botón **Help** a la derecha del título. Al pulsarlo se abre una ventana emergente con una guía compacta (Cuándo usarla · Pasos · Ejemplos · Consejo). Úsala como recordatorio a media tarea — la ventana se cierra al hacer clic fuera y tus datos no se ven afectados.
|
||||
|
||||
**Navegación lateral**: la barra lateral agrupa las herramientas en secciones (Análisis, Limpiadores de datos, Transformaciones, Automatizaciones). Cada cabecera muestra `+` cuando está plegada y `−` cuando está desplegada — pulsa la cabecera para alternar.
|
||||
|
||||
### 3.2 CLI
|
||||
|
||||
```bash
|
||||
|
||||
@@ -135,6 +135,10 @@ Full numbered support matrix: [REQUIREMENTS.md](REQUIREMENTS.md).
|
||||
|
||||
Advanced options are tucked in expander panes. The original file is never modified.
|
||||
|
||||
**In-tool Help**: every tool page has a **Help** button right of the title. Click it to open a popover with a compact how-to (When to use · Steps · Examples · Tip). Use it as a refresher mid-task — the popover closes when you click outside, your inputs are untouched.
|
||||
|
||||
**Sidebar nav**: the sidebar groups tools into sections (Analysis, Data Cleaners, Transformations, Automations). Each section header shows `+` when collapsed and `−` when expanded — click the header to toggle.
|
||||
|
||||
### 3.2 CLI
|
||||
|
||||
```bash
|
||||
|
||||
Reference in New Issue
Block a user