diff --git a/GOALS.md b/GOALS.md index 93138939..d1b9a0c4 100644 --- a/GOALS.md +++ b/GOALS.md @@ -329,3 +329,7 @@ Detail: goals/G-086-light-project-layout.md ### G-087 [active] Thin project layouts: injected infrastructure, fauxlink layout refs, working overlay merge Scope: src/project_layouts/ (payload store restructure), src/decktemplates/ (layout_refs migration to fauxlink), src/modules/punk/mix/commandset/project-999999.0a1.0.tm (project.new generation path), src/modules/punk/mix/commandset/layout-999999.0a1.0.tm, src/modules/punk/cap/handlers/templates-999999.0a1.0.tm (ref resolution), src/modules/punk/mix/#modpod-templates-999999.0a1.0/ (module-shipped refs/layouts), src/make.tcl (layout sync steps) Detail: goals/G-087-thin-project-layouts.md + +### G-088 [proposed] textblock table footer block + bottom-edge subtitle (arg_error examples marker) +Scope: src/modules/textblock-999999.0a1.0.tm (class::table options and bottom border assembly), src/modules/punk/args-999999.0a1.0.tm (arg_error usage-table examples marker), src/tests/modules/punk/args/testsuites/args/examples.test + textblock table coverage +Detail: goals/G-088-textblock-table-footer-subtitle.md diff --git a/goals/G-088-textblock-table-footer-subtitle.md b/goals/G-088-textblock-table-footer-subtitle.md new file mode 100644 index 00000000..f90f8a76 --- /dev/null +++ b/goals/G-088-textblock-table-footer-subtitle.md @@ -0,0 +1,49 @@ +# G-088 textblock table footer block + bottom-edge subtitle (arg_error examples marker) + +Status: proposed +Scope: src/modules/textblock-999999.0a1.0.tm (class::table options and bottom border assembly), src/modules/punk/args-999999.0a1.0.tm (arg_error usage-table examples marker), src/tests/modules/punk/args/testsuites/args/examples.test + textblock table coverage +Goal: The usage/error table can carry a short marker embedded in its bottom frame edge (a bottom-right examples indicator, the counterpart of the top 'Usage' title), backed by textblock::class::table gaining frame-parity -subtitle/-subtitlealign and footer row support with column spans independent of the body, as the header already has. +Acceptance: textblock::class::table renders -subtitle with -subtitlealign left|centre|right in its bottom border whether or not footer rows are present; footer rows with independent colspans render via a configure_footer/footer_colspans API mirroring configure_header; arg_error embeds its @examples marker bottom-right through the subtitle and retires the interim 'Example:' header row - all pinned by tests. + +## Context + +When a punk::args definition carries an @examples block, the usage/error table should +advertise it without displaying the examples text itself. As of punk::args 0.12.5 this is +an interim 'Example: eg ' header row (scheme colour CLR(check)). The desired display +is a short marker embedded at the bottom-right of the table frame - the visual counterpart +of the 'Usage' title embedded at the top - which the table class cannot currently render. + +State of the table class (textblock::class::table, defined in the punk built-shell +environment via textblock): +- No -subtitle/-subtitlealign options. textblock::frame already has both (subtitle + overtyped onto the bottombar via overtype::block with -blockalign, gx0-aware - + see textblock frame implementation around the opt_subtitle bottombar handling). +- Footer exists only as latent styling knobs (-show_footer, -ansibase_footer, + -ansiborder_footer in opts_table_defaults); there are no footer-row methods - + configure_header/header_colspans have no footer counterparts. + +## Approach + +Two deliverables, deliberately severable: + +1. Bottom-edge subtitle (the near-term need). Add -subtitle/-subtitlealign to + class::table with the same semantics as textblock::frame, overtyping the table's + bottom border line the way frame treats its bottombar. This must work whether or not + footer rows exist - the examples marker embedding must not depend on deliverable 2. + arg_error then replaces the interim 'Example:' header row with + -subtitle "eg " -subtitlealign right (scheme-coloured; raw id, not @cmd -name, + which is display text and not always invocable). + +2. Footer block with independent spans (the fuller feature). configure_footer + + footer_colspans mirroring the header API, so renderers can put row-structured content + below the body with its own spans. The latent -*_footer styling options become live. + When footer rows are present the subtitle embeds in the frame edge below them. + +## Notes + +- Origin: user direction 2026-07-17 during the @examples usage-table indication work + (punk::args 0.12.5). The interim header row ships in 0.12.5 and is pinned by + examples.test atexamples_eg_and_usage_row - that pin flips when this goal lands. +- An alternative interim considered and rejected: post-processing the rendered table in + arg_error by overtyping the last border line - workable but puts frame-drawing + knowledge in a consumer; the table class is the right owner.