docs: Write "Importing and Exporting Data" chapter and rewrite "Form Traversing" chapter

[Copilot]

The docs/_advanced_concepts/data_import_and_export.md page was a stub with only a "Work in Progress" placeholder. This PR fills it with a complete chapter documenting SmarkForm's core data I/O system. It also rewrites the existing form_traversing.md chapter to fix factual errors discovered during this work, and updates the AGENTS knowledge files.

Coverage — Importing and Exporting Data

• export action — return value shape by component type (form→object, list→array, input→scalar); exportEmpties option with inheritance semantics and a concrete nested-list override example
• import action — accepted formats (plain object, JSON string, array, scalar); setDefault full behaviour table; focus option
• Default values, clear, and reset — value initialization, how import updates defaultValue, clear vs reset comparison table
• Piping between components (target option) — declarative billing→shipping address copy with zero JS; target semantics on both export and import triggers; hint showing the equivalent import-based alternative (reversing context and target)
• Programmatic API — .actions.export/import() (full event lifecycle) vs direct prototype calls (bypass); await myForm.rendered requirement
• Common patterns — load from server, submit to backend, interactive localStorage draft save/restore playground

Interactive examples

Five embedded playgrounds (using the existing sampletabs_tpl.md template):

ID	Demonstrates
export_structure	Nested form+list export shape
import_example	Basic import with JSON editor
clear_vs_reset	value-initialized defaults, clear vs reset
pipe_example	Billing→shipping address copy via target
draft_example	Auto-save to localStorage on export; auto-restore on page load

All examples are picked up by the docs collector and pass co-located Playwright validation.

Rewrite — Form Traversing chapter

• Removed AI-generated warning at the top of the document
• Rewrote "Understanding Context" — clarified that explicit context paths are resolved via triggerParent.find(contextPath), i.e. relative to the trigger's parent component
• Rewrote "Understanding Target" — removed the misleading "specific child component within the context" description; target is resolved via context.find(targetPath), starting from the resolved context. Added a prominent rule box with the billing→shipping example explaining why "shipping" silently fails and "../shipping" is correct. Absolute paths shown as the unambiguous alternative.
• Fixed wrong button action in the "Dynamic List Navigation UI" example: action:"export" with target:".-1" was labeled "← Copy from Previous" — that actually writes the current item into the previous. Fixed to action:"import" (reads from previous, imports into current) with an explanatory paragraph.
• Removed stale "newly implemented" language from the List Item Sibling Navigation intro
• Fixed typo .-N (was .--N) in the Navigation Direction list

AGENTS knowledge files updated

Added a new "Action Target Resolution" section to both AGENTS/SmarkForm-Usage.md and docs/_resources/AGENTS/SmarkForm-Usage.md covering:

• The context.find(targetPath) rule and why it differs from context resolution
• The billing→shipping gotcha (../shipping vs broken shipping)
• Absolute paths as the safe alternative
• Export-vs-import target semantics (copy direction)

Bug fixes

• pipe_example target path: Fixed "target":"shipping" → "target":"../shipping". The target option is resolved via context.find(targetPath), so from a billing context "shipping" incorrectly looked for a child of billing. "../shipping" correctly navigates up to billing's parent and finds the shipping sibling.
• Corrected target-path hint: The previous hint incorrectly stated target paths are resolved relative to "the context component's parent". Corrected to reflect that they are resolved relative to the context component itself.

Original prompt

Using the knowledge you already have in the AGENTS.md, etc… I want to develop the "Importing and exporting" data chapter (under the "Advanced concepts" section) of the documentation.

Check the source code, existing examples and ask me whatever you need to get the whole picture beforehand.

After that I want you to create a new PR with the changes for me to review and merge it.

---

🔒 GitHub Advanced Security automatically protects Copilot coding agent pull requests. You can protect all pull requests by enabling Advanced Security for your repositories. Learn more about Advanced Security.

[bitifet]

Here you have my revison, @copilot

Can you handle it, please?

Small bug in the "Copy to shipping" button in the "Chaining export and import" example

The fix:

diff --git docs/_advanced_concepts/data_import_and_export.md docs/_advanced_concepts/data_import_and_export.md
index 95c8a6f..9945096 100644
--- docs/_advanced_concepts/data_import_and_export.md
+++ docs/_advanced_concepts/data_import_and_export.md
@@ -445,7 +445,7 @@ into the shipping address section:
     <button data-smark='{
         "action":"export",
         "context":"billing",
-        "target":"shipping"
+        "target":"../shipping"
     }'>📋 Copy to shipping</button>
 </p>
 <fieldset data-smark='{"type":"form","name":"shipping"}'>

Explanation:

1. The context was correctly set (relative path from the "natural context" -where it is placed- to the billing address form).
2. But the path to the target should be relative to the actual context of the component which now is the billing address form (since we set so) so we need to go one level up to reach the shipping form.

Note:

Alternatively, the following would had also the same effect:

<button data-smark='{
    "action":"import",
    "context":"shipping",
    "target":"../billing"
}'>📋 Copy to shipping</button>

...it is the reverse operation also reversing context and target.

That is: It imports, into the shipping address the data from the billing address instead of exporting the data from the billing address to the shipping address.

I reckon it worth to mention in a "hint" box because it could be illustrative and help to understand better the concepts.

Also, we could have added an addigional button to the example for the reverse operation (Copy from shipping) by just switching the action from export to import and keeping context and target the same.

Moreover, if we also add a Clear button to both subforms (and maybe add preloaded -different- data for the shipping address), it could be an excellent example to add to the Showcase section.

In this section, though, that would be excessively bloated from my point of view.

But I think adding the beforementioned hint, including the former snippet and then linking to the more bloated example if we add it to the Showcase section, it would be perfect.

Don't you think so, @copilot?

Question about the "Save and restore draft data"

Wouldn't the example in this sectio be a perfect fit for using a "sampletabs" enhanced example to allow the reader play with it?

[Copilot]

Here you have my revison, @copilot

Can you handle it, please?
...

Done in commit 031cf99. Here's a summary of what was addressed:

Bug fix: Changed "target":"shipping" to "target":"../shipping". The target is resolved via context.find(targetPath) — so from the billing context, "shipping" looked for a child of billing named "shipping" (which doesn't exist). "../shipping" correctly navigates up to billing's parent, then finds the shipping sibling.

Corrected hint: The previous hint incorrectly said target paths are resolved relative to "the context component's parent". Updated to say they're resolved relative to the context component itself (matching the actual context.find(targetPath) call).

Added the import-based alternative hint: Included the snippet you suggested showing the reverse approach (action:"import", context:"shipping", target:"../billing") with an explanation that reversing context and target switches the data-flow direction while achieving the same result.

Interactive "Save and restore draft data" example: Converted the code-only section into a full sampletabs playground. The jsHead uses localStorage (auto-saves on every Export, auto-restores on page load). The myForm.find("/demo") || myForm fallback makes it work both in the docs playground (with the demo subform wrapper) and in the automated tests (no wrapper). The JS tab comment flags the playground-specific adapter so it's clear what real-app code would look like.

[bitifet]

Hey, @copilot

Can you now review the existing "Form traversing" section?

Keep in mind the bug we've just fixed: I won't be surprised if it were originated from an error or not so well explained detail in this document.

I want you to:

1. Fully understand which was the error and why the correct way to do that is which it is.
2. Review the implementaton to double check your understanding is correct. Ask me everything you need if something is unclear or you need guidance in any way.
3. Fix or completely rewrite the existing chapter using what you know now and remove the warnings about it being generated from AI.
4. Also review the documentation under the AGENTS directory to ensure this is correctly explained and add or modify whatever is needed.

[Copilot]

Hey, @copilot

Can you now review the existing "Form traversing" section?
...

Done in commit aafd6ce. Here's what was changed across the three files:

docs/_advanced_concepts/form_traversing.md

• Removed the AI-generated warning block
• Rewrote "Understanding Context" — added the critical detail that explicit context paths are resolved via triggerParent.find(contextPath), i.e. relative to the trigger's parent component
• Rewrote "Understanding Target" — removed the misleading "specific child component" description. Added a prominent rule box explaining that target paths are resolved via context.find(targetPath) (starting from the resolved context), showing the billing→shipping example with "../shipping", explaining why "shipping" alone silently fails, and offering the absolute-path alternative
• Rewrote "Explicit Context and Target Specification" — added a relative-path example (../businessData) alongside the absolute one
• Removed the stale "newly implemented" label from the List Item Sibling Navigation intro
• Fixed typo .-N (was .--N) in the Navigation Direction list
• Fixed wrong button action in the "Dynamic List Navigation UI" example: action:"export" with target:".-1" was labeled "← Copy from Previous" — that actually copies current → previous. Fixed to action:"import" (reads from previous, imports into current), which is what the label says. Added a short explanation after the snippet

AGENTS/SmarkForm-Usage.md and docs/_resources/AGENTS/SmarkForm-Usage.md

• Added a new "Action Target Resolution" section (the root cause of the pipe_example bug) covering: context.find(targetPath) rule, the billing→shipping gotcha with ../shipping, absolute paths as the safe alternative, and the export-vs-import target semantics table with copy-direction examples