#414 - docs: descendantsComplete behavior and migration guidance for TKO

[phillipc]

Documentation for a breaking change in TKO: descendantsComplete no longer waits for async descendants

See: #414

Summary by CodeRabbit

• Documentation
  • Updated the 3-to-4 migration guide with clearer descendantsComplete behavior details.
  • Explained the new per-node, synchronous timing and how async bindings affect completion.
  • Documented the edge case for nested if/template content that may render later without re-triggering.
  • Advised switching to childrenComplete when waiting for descendants is required, with updated example snippets.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 091fb7ef-56c9-418f-afa2-0d10a635bc4e

📥 Commits

Reviewing files that changed from the base of the PR and between 87d2baa and 3b3eb79.

📒 Files selected for processing (1)

• tko.io/src/content/docs/3to4.md

🚧 Files skipped from review as they are similar to previous changes (1)

• tko.io/src/content/docs/3to4.md

---

📝 Walkthrough

Walkthrough

Adds migration documentation explaining the changed descendantsComplete behavior for asynchronously rendered descendants and recommends childrenComplete with updated examples.

Changes

Descendants completion documentation

Layer / File(s)	Summary
Completion behavior and migration guidance tko.io/src/content/docs/3to4.md	Documents synchronous per-node completion decisions, nested rendering effects, and migration from descendantsComplete to childrenComplete with before/after HTML examples.

Estimated code review effort: 1 (Trivial) | ~3 minutes

Possibly related PRs

• knockout/tko#227: Introduced the migrated 3to4.md documentation that this PR updates.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly matches the doc-focused breaking change and migration guidance for descendantsComplete.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch doc/descendantsComplete_TKO_BC

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@tko.io/src/content/docs/3to4.md`:
- Line 61: Clarify the descendantsComplete description so it states that the
callback may run during the node’s initial binding, but is not invoked again
when descendant if/template content renders later. Update the final sentence of
the documented behavior without changing the surrounding per-node or
asynchronous-binding semantics.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: f6661b4c-ee81-44f6-a37f-99ee542f100c

📥 Commits

Reviewing files that changed from the base of the PR and between f396518 and 87d2baa.

📒 Files selected for processing (1)

• tko.io/src/content/docs/3to4.md

[phillipc]

@coderabbitai approve

[coderabbitai]

✅ Action performed

Comments resolved. Approval is disabled; enable reviews.request_changes_workflow to allow explicit top-level @coderabbitai resolve or @coderabbitai approve commands.