Improve readability of interactive examples in documentation

[Copilot]

• Analyze sampletabs pipeline — whitespace IS preserved via jsonify; root cause is poor indentation in the source captures themselves
• Fix HTML indentation in all 21 affected doc files (88 examples collected, build passes)
  • Applied consistent 2-space-per-level indentation to all HTML {% capture %} blocks
  • showcase.md: fixed inconsistent █ usage in simple_list_singleton, simple_list_autodisable; fixed schedule_list, nested_forms_with_load_save, calculator, supercalculator missing outer indent
  • All other doc pages: <p>, <fieldset>, <ul>, etc. direct children of root <div> now properly indented
• Remove █ trick from all non-composable direct captures — replaced with plain spaces
  • index.md: event_planner_html — fixed bug introduced by previous script (spaces before █ broke replace logic), now uses clean 2-space indentation
  • showcase.md: event_planner_html, simple_list, simple_list_singleton, simple_list_autodisable, schedule_table, submit_form_example — all use proper 2-space indentation directly
  • showcase.md: basic_form_fields and nested_forms converted to direct 4-space indentation; their embedding captures no longer need replace: "█", " "
  • █ is retained only where multi-level Liquid composition genuinely requires it: schedule_row_form (used at 0-space and 8-space depth), simple_list_hotkeys / simple_list_hotkeys_with_context / 2nd_level_hotkeys_html (deep nesting via chained replace)
• Fix Ace editor indentation in playground editor mode
  • Added smarkformReindentHtml(content, spaces) helper in sampletabs_ctrl.md
  • smarkformBuildEditorHtml now re-indents p.inner by 8 spaces to align with its context inside the two additional wrapper <div> elements
• Build passes (npm run build)
• Example collector passes (88 examples in manifest)

Original prompt

Repo: bitifet/SmarkForm
Ref: 7ef2b6c
Scope: Documentation interactive examples under docs/ that use the liquid/sampletabs component.

Goal

• Review the source code/content used by all interactive documentation examples implemented via the liquid/sampletabs component.
• Improve readability and presentation of those example sources by:
  1. Improving indentation (use a consistent style; add automated lint/format where reasonable for docs sources).
  2. Ensuring indentation is preserved when the example source is injected into the Ace editor (currently indentation is lost or minimal). Fix the pipeline so leading whitespace is preserved in rendered examples.
  3. Adding comments and/or blank lines within the example sources wherever it improves readability and clarifies intent.

Constraints / requirements

• Follow any existing repo conventions and instructions in AGENTS.md and files under AGENTS/ (review them first and comply).
• Only change what is needed for the interactive examples and their rendering/formatting. Avoid unrelated refactors.
• Prefer deterministic formatting so future edits stay consistent.
• Update any affected docs pages so they render correctly after indentation-preservation changes.
• If there is a build/test/check for docs, run/ensure it passes.

What to do

1. Identify every interactive example in docs/ that uses liquid/sampletabs.
2. For each example, find the source snippet(s) fed into the component (Liquid, Markdown, HTML, JS, JSON, etc.).
3. Reformat those source snippets:
   • Normalize indentation (consistent spaces, align nested structures).
   • Insert blank lines between logical sections.
   • Add short comments explaining non-obvious parts.
4. Fix indentation preservation in the Ace editor injection path:
   • Determine where the snippet text is extracted/encoded/embedded.
   • Ensure leading whitespace is preserved (avoid Liquid whitespace-trimming, HTML collapsing, or JSON encoding issues).
   • If needed, adjust the Liquid component template to wrap code in a tag that preserves whitespace (e.g., <pre>), or encode snippet text safely (e.g., HTML entities or JSON string) before passing to Ace.
   • Ensure tabs/spaces are handled predictably.
5. Validate output by checking at least a few example pages and confirming indentation appears correctly in the editor.

Deliverable

• Open a PR with the improvements.
• PR should include a concise description of:
  • Which pages/examples were updated.
  • What indentation-preservation fix was applied.
  • Any formatter/linting changes introduced (if any).

Notes

• Work from the given ref; create a new branch from the default base branch in the repo.
• Keep changes limited to docs and the Liquid component(s) involved in sampletabs and their supporting scripts/styles.

The following is the prior conversation context from the user's chat exploration (may be truncated):

User: I wonder if we culd improve documentation examples with a little review. Say:

1. Improving indentation (maybe using some linting tool).
2. Making the indentation to be respected when the source is injected to the ace editor (now it has little or no indentation).
3. Adding comments and/or blank lines (to the source) wherever needed to improve readability or provide clarification.

Can you review the sources of all interactive examples (those implemented using the liquid/sampletabs component) and make the necessary changes according to your own criterion in a new pull request so that I can later review them?

Rememeber to review your previous knowledge in the AGENTS.md and the files under the AGENTS directory.

As usual, if you have any question, please ask me beforehand. Otherwise you can proceed with the PR.

Assistant: I’ve queued up the pull request creation, and we’re now waiting for you to accept or reject the pending action in the dialog so I can proceed with the documentation review and updates.

This pull request was created from Copilot chat.

[bitifet]

@copilot , can you try to continue, please?

[Copilot]

@copilot , can you try to continue, please?

Done! All HTML indentation fixes are now pushed in commit 7f29901.

The previous session's work was lost (commits were local but never pushed due to a 403). I've redone everything:

• 21 doc files updated — all HTML {% capture %} blocks now use consistent 2-space-per-level indentation
• showcase.md separately handled (uses █ = 4-space convention): fixed inconsistent depth in simple_list_singleton/simple_list_autodisable, fixed missing outer indent in schedule_list, nested_forms_with_load_save, calculator, and supercalculator
• Build passes, example collector processes all 88 examples successfully

[bitifet]

Good job @copilot

Two details still to look at:

1. Is the '█' character trick still needed? I did it to overcome the lack of support for regular expressions in liquid. But in JS we can just prepend the beginning of each line with the required number of spaces every time it is needed.

2. Inside the ace editor, most of indentation is still gone. Don't know if it could be a ace editor issue itself but, at least manually, I can prepend spaces wherever they are needed.

Can you please review those two points and, if possible, fix them (remove the tricky character if it is really not necessary at all and/or fix the indentatiion of the code inside the ACE editor)?

[Copilot]

Good job @copilot

Two details still to look at:
...

Done in commit bd8b6b9. Here's what was done for each point:

1. Is █ still needed?
Removed █ from all non-composable direct captures: event_planner_html (both files), simple_list, simple_list_singleton, simple_list_autodisable, schedule_table, submit_form_example, and converted basic_form_fields/nested_forms to direct 4-space indentation (removing the replace: "█", " " filter from their embedding captures).

█ is kept only where multi-level Liquid composition genuinely requires it: schedule_row_form (used at both 0-space and 8-space depth), simple_list_hotkeys/simple_list_hotkeys_with_context/2nd_level_hotkeys_html (deep nesting via replace: "█", "█ "). Moving this to JS would require redesigning the Liquid composition mechanism; for now these captures are correct and █ is transparent to the Ace editor (replaced by partial_htmlSource before reaching JS).

2. Ace editor indentation fix
Two issues were causing wrong indentation in the Ace editor:

• Bug introduced by the previous commit: my Python reindenter incorrectly added spaces before █ in index.md's event_planner_html (producing █<div> instead of █<div>), which after replace: "█", " " gave 6-space indent instead of 4. Now fixed by removing █ and using proper 2-space indentation directly.
• smarkformBuildEditorHtml not re-indenting inner content: added smarkformReindentHtml(p.inner, 8) so that when the playground editor wraps the form's inner content in two additional <div> layers (8-space context), the content is properly re-indented to match.

[bitifet]

@copilot I still see the code unindented in the ace editor.

Can you review it, please?

[Copilot]

@copilot I still see the code unindented in the ace editor.

Can you review it, please?

Fixed in commit f1b6575. The root cause was that several captures had direct children of <div id="myForm$$"> at column 0 — these don't use the █ trick, so partial_htmlSource's replace filter was a no-op and the col-0 content flowed unchanged into data.htmlSource and then into the Ace editor.

Fixed captures across 5 files:

• showcase.md: schedule_mixin_html (was replace: "█", "" — now replace: "█", " "), nested_schedule_table, nested_schedule_table_duplicable, period_mixin_duplicable
• quick_start.md: html_phone_list
• form_traversing.md: form_trav_navigation_ui_html, form_trav_practical_copy_html
• core_concepts.md: context_comparsion_example_simple
• mixin_types.md: mixin_snippet_params_html

All direct children of root divs now use consistent 2-space indentation, so the Ace editor shows properly indented code.