Skip to content

Track and clear initial applied params on slotted child views - #987

Merged
schultek merged 29 commits into
mainfrom
fix/slotted-child-view-applied-params
Nov 18, 2026
Merged

schultek merged 29 commits into
mainfrom
fix/slotted-child-view-applied-params

Conversation

@schultek

@schultek schultek commented Nov 12, 2026 •

Copy link
Copy Markdown
Owner

Description

This PR fixes two related issues when using Component.apply across server and client boundaries:

  1. Component.apply above a @client component was lost on the client after hydration.
  2. Server components slotted inside a @client component couldn't clean up initial server-applied params when toggled off on the client.

Case 1: Component.apply Above a @client Component

The Problem

When Component.apply wrapped a @client component on the server:

Component.apply(
  classes: 'btn-primary',
  child: MyClientButton(), // client component
)

The server rendered <button class="btn-primary"> into the initial HTML, but the client marker comment was just <!--@my_client_button-->. During client hydration, MyClientButton was mounted without Component.apply in its context. Upon hydration or the first client-side setState(), the button rebuilt without btn-primary, causing the applied classes/styles to disappear!

The Fix

  • The server now inspects active ancestor Component.apply components and serializes them into the client boundary marker:
    <!--@my_client_button apply<[{"c":"btn-primary"}]>-->
    <button class="btn-primary" data-app="1">Click me</button>
    <!--/@my_client_button-->
  • During client-side hydration, Jaspr reads apply<...> and wraps the client component in Component.apply(...), ensuring inherited DOM params remain active across client-side state changes and rebuilds.

Case 2: Server Component Slotted Into a @client Component

The Problem

When a server component is passed as a child/slot into a @client component:

Component.apply(
  target: const ApplyTarget.descendantWith(tag: 'span'),
  classes: 'highlight',
  child: MyClientCard(
    child: span(classes: 'label', [text('Hello')]), // server component slotted inside
  ),
)

The server baked class="label highlight" into the server-rendered HTML. On the client, SlottedChildView mounts the server-rendered DOM nodes, but had no record of what params were initially applied by the server versus originally owned by the child. If client-side state later toggled Component.apply off:

  • SlottedChildView couldn't distinguish applied values from child-owned values.
  • It either failed to remove highlight or risked removing child-owned classes/properties like label.

The Fix

  • Server-Side Tracking (data-j-apply):
    • For server components slotted into client components, ServerComponentAdapter attaches a compact data-j-apply attribute tracking the server-applied diff:
      <!--@my_client_card data<{"child":"s@1"}> apply<[{"t":{"d":true},"c":"highlight"}]>-->
      <div class="card">
        <!--s@1-->
        <span class="label highlight" data-j-apply="c:highlight">Hello</span>
        <!--/s@1-->
      </div>
      <!--/@my_client_card-->
    • Compact format: Uses key prefixes (i:<id>;c:<classes>;s:<styles>;a:<attributes>) with lightweight percent-escaping for %, ;, , to avoid verbose JSON &quot; escaping in HTML attributes.
    • Only server components: Client-owned elements do not receive data-j-apply because they rebuild in Dart and inherit from the apply<...> marker (Case 1).
  • Client-Side Hydration & Cleanup:
    • SlottedChildView hydrates initial applied parameters from data-j-apply, registers them in _appliedParams, and strips the attribute from the DOM.
    • When Component.apply is toggled off or updated on the client, _resetElementParams cleanly reverts only the applied values while safely preserving child-owned values (e.g. removing highlight while leaving label).

Type of Change

  • 🛠️ Bug fix

Ready Checklist

  • I've read the Contribution Guide.
  • In case this PR changes one of the core packages, I've modified the respective CHANGELOG.md file using the semantic_changelog format.
  • I updated/added relevant documentation (doc comments with ///).
  • I added myself to the AUTHORS file (optional, if you want to).

Copilot AI balanced review requested due to automatic review settings November 12, 2026 16:15
@github-actions

github-actions Bot commented Nov 12, 2026 •

Copy link
Copy Markdown

Package Version Report

The following packages have been updated:
jaspr_test : 0.24.0-beta.1 -> 0.24.0-beta.2
jaspr : 0.24.0-beta.1 -> 0.24.0-beta.2
jaspr_builder : 0.24.0-beta.1 -> 0.24.0-beta.2
jaspr_cli : 0.24.0-beta.1 -> 0.24.0-beta.2
jaspr_content : 0.6.0-beta.0 -> 0.6.0-beta.1

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Component.apply cleanup can remove child-owned DOM values and leave applied styles behind because ownership tracking and CSS value comparisons are incorrect.

2 open issues
What changed in this PR

This PR updates Jaspr’s slotted child views to track Component.apply parameters already present in server-rendered HTML, allowing client updates to remove them when toggled off.

Changes:

  • Records existing applied classes and matching IDs, styles, and attributes for cleanup.
  • Adds a browser regression test covering removal of initially rendered parameters.
  • Documents the fix in the changelog.
File Description
packages/​jaspr/​test/​client/​slotted_child_view_test.dart Tests cleanup of applied parameters initially present in HTML.
packages/​jaspr/​lib/​src/​client/​slotted_child_view.dart Updates tracking of existing DOM values for later cleanup.
packages/​jaspr/​CHANGELOG.md Records the applied-parameter cleanup fix.

Review effort: Balanced

@schultek
schultek force-pushed the fix/slotted-child-view-applied-params branch from b60f237 to 5e509f4 Compare November 13, 2026 11:17

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Unresolved apply-ownership and boundary-handling bugs can remove server-owned classes during hydration or leave applied properties behind after disabling an apply or unmounting a view.

6 open issues
2 resolved since last review

Review effort: Balanced

@schultek
schultek requested a balanced review from Copilot November 13, 2026 14:56

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Two unresolved ownership issues can corrupt nested-slot IDs during hydration and delete child-owned inline styles when an apply is disabled.

2 open issues
4 resolved since last review

Review effort: Balanced

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Inherited-parameter updates can corrupt child-owned styles by splitting valid semicolon-containing CSS values and lowercasing case-sensitive custom-property names.

2 open issues
2 resolved since last review

Review effort: Balanced

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Unresolved class and style merging defects cause duplicate class attributes, styling changes during hydration, and loss of child-owned margins during apply cleanup.

3 open issues
2 resolved since last review

Review effort: Balanced

parlough
parlough previously approved these changes Nov 18, 2026

@parlough parlough left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for this @schultek! After the following adjustments, I say let's land and continue to iterate on top of this.

@schultek
schultek requested review from parlough and a balanced review from Copilot November 18, 2026 15:46
@schultek

Copy link
Copy Markdown
Owner Author

I agree with landing this. The more I dive into it the more edge cases pop up, but most of them are from uses of .apply that I never intended. I added a few skipped test cases that test edge cases that are not yet fully supported (maybe never will) just to keep track.

parlough
parlough previously approved these changes Nov 18, 2026

@parlough parlough left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for those adjustments and additional definition of the merging rules! Still looks good to me :)

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Slotted children with raw class attributes gain apply-added classes during hydration, violating raw-class ownership and leaving server and client behavior inconsistent.

1 open issue
3 resolved since last review

Review effort: Balanced

@schultek
schultek merged commit e929214 into main Nov 18, 2026
10 checks passed
@schultek
schultek deleted the fix/slotted-child-view-applied-params branch November 18, 2026 17:57
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants