Implement distinction between clear, reset, and future null actions

[Copilot]

The library conflated "clearing" and "resetting" into a single action. This PR separates them: clear now removes all values (ignoring defaults), reset restores configured defaults, and null (future) will set forms to null state.

Changes

Core Implementation

• Added emptyValue property to SmarkField for type-level empty states
• Refactored clear() to use emptyValue instead of undefined
• Implemented reset() action that restores defaultValue
• Added placeholder comments for future null action

Field Types Updated

• form: emptyValue = {}, defaultValue = {}
• list: emptyValue = [], defaultValue = [] (or prepopulated)
• input: emptyValue = "", defaultValue = "" (or configured)
• color: emptyValue = null, defaultValue = null

Behavioral Change

• Initialization now calls reset() instead of clear() when options.value is provided

Usage Example

// Form with defaults
const form = new SmarkForm(node, {
  value: { name: "John", age: 30 }
});

// User modifies values
await form.import({ name: "Jane", age: 25 });

// Clear removes everything
await form.clear();
await form.export(); // { name: "", age: "" }

// Reset restores defaults
await form.reset();
await form.export(); // { name: "John", age: 30 }

Testing

• Added 27 test cases covering simple fields, nested forms, lists, and edge cases
• All existing tests pass (no regressions)

Documentation

• Updated type_form.md, type_list.md, type_input.md with action descriptions
• Added interactive example demonstrating both actions
• Documented future null action behavior

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• aus5.mozilla.org
  • Triggering command: /home/REDACTED/.cache/ms-playwright/firefox-1497/firefox/firefox /home/REDACTED/.cache/ms-playwright/firefox-1497/firefox/firefox -no-remote -headless -profile /tmp/playwright_firefoxdev_profile-W2EfhH -juggler-pipe -silent che/ms-playwright/firefox-1497/firefox/glxtest stall-Z5LaUC/000git 6.1+dfsg1-2ubuntls-files /usr/bin/dpkg che/ms-playwrigh--others s/li�� -f - ndor/bin/ldd u3.2_amd64.deb .2 eb dpkg-deb (dns block)
• esm.ubuntu.com
  • Triggering command: /usr/lib/apt/methods/https /usr/lib/apt/methods/https (dns block)
• https://storage.googleapis.com/chrome-for-testing-public/143.0.7499.4/linux64/chrome-headless-shell-linux64.zip
  • Triggering command: /usr/local/bin/node /usr/local/bin/node /home/REDACTED/work/SmarkForm/SmarkForm/node_modules/playwright-core/lib/server/registry/oopDownloadBrowserMain.js (http block)
• https://storage.googleapis.com/chrome-for-testing-public/143.0.7499.4/linux64/chrome-linux64.zip
  • Triggering command: /usr/local/bin/node /usr/local/bin/node /home/REDACTED/work/SmarkForm/SmarkForm/node_modules/playwright-core/lib/server/registry/oopDownloadBrowserMain.js (http block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

Original prompt

Implement the proposed distinction between clear, reset, and future null actions in the SmarkForm library.

Specifically:

1. Refactor clear: Maintain the existing behavior where the clear action removes user-provided values, recursively applying to subforms and lists if present.

2. Introduce reset: Add a new reset action that reverts the entire form (including subforms and lists) to their default values.

   • Ensure this behavior is recursive, applying to nested forms.
   • For lists, reset them to their default structure, whether empty or prepopulated.

3. Prepare for null: While this is a future action, comment and document where its logic may fit into nested forms and lists. This action would explicitly set the entire form (and its subforms) to null.

4. Tests: Write comprehensive unit tests:

   • Verify the distinction between clear and reset.
   • Check edge cases like forms with partial defaults, nested forms, deeply nested lists, and no defaults defined.
   • Validate behavior for fields, subforms, and lists.

5. Documentation: Update the documentation to reflect these changes:

   • Clearly explain clear (retaining its current utility) and reset (highlight its reverting-to-default-values functionality).
   • Mention the future null action with planned functionality.
   • Update examples to showcase reset and clear, with nested form scenarios included.

This pull request was created from Copilot chat.

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.