Labs Feedback: @lit-labs/preact-signals

[justinfagnani]

The @lit-labs/preact-signals package is a set utilities for using Preact Signals in Lit.

• SignalWatcher: a class mixin that makes an element watch all signal accesses during the element's reactive update lifecycle, and triggers an element update when signals change.
• watch(): a lit-html directive that accepts a single Signal and renders its value, subscribing to updates and updating the DOM when the signal changes.
• html, svg, and withWatch(): html and svg template tags that can be used in place of Lit's default template tags which automatically wraps any signals in watch(). withWatch() applies the auto-watching behavior to any lit-html compatible template tag.

We want to collect your feedback on your experiences with @lit-labs/preact-signals as we iterate on it according to our Lit Labs process and move the package towards possible graduation or retirement.

• Status: Prototyping
• Major known issues: None yet
• Issues: [labs/preact-signals]
• Docs: README
• npm: @lit-labs/preact-signals

Please try @lit-labs/preact-signals and tell us about your experience. Leave comments with your thoughts; highlight what issues or missing features you're blocked on; give a link to a project that uses it; etc.

And so we can have some numbers to look at, you can add reactions to this comment to indicate your experience with this package:

🚀 I have tried this package and it works great. I need it. Ship it!
👍 I have tried this package and it seems like a good idea.
😕 I have tried this package and would use it, but it has serious bugs or missing features.
👀 I am interested, but haven't tried the package yet.
👎 I'm not interested in this package.

Note: other reactions like 😄, 🎉, and ❤️ don't mean anything as part of this scheme. You probably mean, and please use, 🚀, 👍, or 👀.

[andyjessop]

I'm getting a 404 on the docs link.

[marcomuser]

It's part of the 3.0 branch: https://github.com/lit/lit/tree/3.0/packages/labs/preact-signals

[AndrewJakubowicz]

@lit-labs/preact-signals has not been published yet. Will update the discussion once a pre-release has been published.

[AndrewJakubowicz]

It has been published in a pre-release! Blog post announcement!

You can now try the package with: npm i @lit-labs/preact-signals

[danielquintero]

Thanks for putting this together, looks promising. I just have one question, are there any plans to support deepSignals too? For reference (preactjs/signals#4)

[redfox-mx]

Hi @danielquintero watch directive and Signals Watcher uses preact tracking system (subscription and effects), in that sense any new feature with those approaches must be supported. Don't worry about.

[jogibear9988]

Is the source anywhere available?

[redfox-mx]

Yes! You can see source code here https://github.com/lit/lit/tree/main/packages/labs/preact-signals

PD: Hi @jogibear9988 n.n

[herrKlein]

Yes, really cool, we already use it in production! we did a combination of litlabs context, where the context is the signal

[marcomuser]

What's the benefit of combining signals with a context? You can already freely import the signal wherever you need to.

[redfox-mx]

Ooooh sounds really interesting. So, when you call a context, are you subscribing to an effect? Or how did you design signal/context pattern?

Maybe you pass a signal into context subscription or emit a value on response to a signal change?

[herrKlein]

haha, good question.. made me think. Maybe its not necessary, but we started out with a state object and using litcontext, children could consumer this context. Later on we tried signals, and copied the signal value to the context. After that we thought it was simpler to just made the signal be the context. Just learning signals, what is a logic place for the signal to live? outside a webcomponent?

[marcomuser]

I would put signals outside of components into the module scope. From there you can import them wherever you want to and then subscribe to their value from within components. But I guess there are many ways to rome. 😀

[klauss194]

@marcomuser can you share a bit of how did you do that ? we're struggling to share signals from one module to another ( we have vaadin router mounting routes as well )

[louwers]

When passing a signal to a component you need to use

<my-component .someProp=${mySignal}

instead of

<my-component .someProp=${mySignal.value}

this should be clearer in the documentation.

[justinfagnani]

Then you need to make the function take a signal and not a string. That header(text) call doesn't involve Lit at all, it's just JS. There is nothing Lit can do to make that work.

[tbroyer]

Or use a computed()?

import { signal, computed, html } from "@lit-labs/preact-signals";

export function wrapper() {
  const text = signal("My header");
  setTimeout(() => {
    text.value = "Timeout reached";
  }, 3000);

  const h = computed(() => header(text.value));

  return html`
    ${h}
  `;
}

function header(header: string) {
  return html`
    <h1>${header}</h1>
  `;
}

[louwers]

It would be great if all template literal parameters that are functions were automatically wrapped in computed.

This is essentially what ArrowJS does (framework inspired by Lit and Vue).

The above would simplify to:

html`${() => header(text.value)}`

[louwers]

Thanks for your suggestion @tbroyer.

I would still like to see some kind of automatic computed wrapping. Maybe it is even possible to do this yourself with a custom directive? You'd need to differentiate between functions that are passed to a click handler and those that are passed for the template they return.

In any case, I love writing 'templates' like this over the class-based syntax.

export function exercisesOverviewPage() {
  const exercises = getDocsSignal("exercise");

  return html`
    ${computed(
      () => html`
        <div class="flex flex-col items-center text-center">
          ${exercises.value.map(
            ({ name, _id }) => html`
              <a
                class="bg-light w-sm m-2 p-3 rounded-8 select-none"
                @click=${() => goToURL(`/exercise/${_id}`)}
              >
                ${name}
              </a>
            `
          )}
        </div>
      `
    )}
  `;
}

[tidemann]

Would be nice to see an actual example that demonstrates how to use withWatch. I looked in README, but withWatch doesn't seem to be used in the provided example.

Update: My bad. Just noticed html was imported from preact-signals, and not from lit in that example.

[krazylek]

Hi, when using the watch directive, I find quite difficult to work with signals that are Array or Object.

Simple operations like the following example aren't obvious:

const list = signal(['a', 'b']);

return html`<p>The list values are ${watch(list).value.join(', ')}</p>`; // doesn't work as `watch()` returns a directive

Especially true when compared to the other SignalWatcher or signals' html methods:

return html`<p>The list values are ${list.value.join(', ')}</p>`; // very straightforward!

Reading more, I discovered that using computed would make it work as expected:

const listToString = computed(() => list.value.join(', '));

return html`<p>The list values are ${watch(listToString)}</p>`; // does work!

But do I need to create a computed each time I want to use a nested value in a watch?
Did I miss another method?

[sorvell]

Here's a todo example that uses signals with arrays.

You're not explicitly hitting this here, but we always need to start with: Objects and Arrays are tricky because mutating them (e.g. list.push(...)) doesn't change their identify and libraries like Lit and signals detect changes via identify.

You have a couple of options with watch/SignalWather, depending on your needs.

• Using watch ensures you get a super granular sub-component update that can maximize performance. Typically this isn't needed since Lit by default is very fast at updates. And as you note, you must give watch a signal and return its output to the part and this means you might need to create a computed signal... fwiw re-creating the computed signal is probably fine in this case)
• However, just to render correctly, accessing the value in the render method while using SignalWatcher is all you need (i.e. just remove the use of watch).

Now, again, this only works if you actually change the referenced value (e.g. list.value.push(...) bad, list.value = [...list.value, newItem] good).

Hopefully that's clear, but happy to give more info if needed.

[krazylek]

Thank you for your answer. Yes a very granular update was what I was looking.

The other options are nice as well, but I kept exploring a way to achieve this "granular transformation"

First I noticed that a computed does not need to be attached to a property or variable.
This make this alright:

const list = signal(['a', 'b']);
html`<p>The list values are ${watch(computed(() => list.value.join(', ')))}</p>`; 

Looks very close to what I was looking! Just wondering is that could lead to some leak, for example if a LitElement having such syntax is removed from the DOM, will that clear the computed signal?

Also is adding some sugar to watch, to allow a compute function as parameter, something that could be considered?
Eg.

html`<p>The list values are ${watch(() => list.value.join(', '))}</p>`; 

I know I could create my own watch function to do that, but it would be nice to have a standard way of doing it!

[e111077]

Problem

Working with control flow with the watch() directive needs a helper. Playing around with Preact Signals + Lit I found something similar to what other people have been mentioning about dealing with arrays. e.g. consider the following case:

const list = signal([{val: 'a', id: 0}, {val: 'b', id: 1}, {val: 'c', id: 2}]);

export class MyElement extends LitElement {
  render() {
    return html`
      <div>
        Things in the list: ${
          watch(computed(() => repeat(list.value, item => item.id, (item, index) => html`
            <div>${item.val}</div>
            <!-- this is inside a computed function, so this does not need another `watch()` to trigger -->
           ${index !== item.length - 1 ? html`<div class="divider"></div>` : nothing}
          `))
        }
      </div>
      <div>
        <!-- this ternary needs a computed to trigger recalculation --> 
        The number of items is ${watch(computed(() => (list.value.length % 1 === 0 ? 'even' : 'odd')))}
      </div>
    `;
  }
}

watch() only accepts a Signal value. Therefore your expression needs to return a Signal value in order for the control flow to be recalculated whenever the value changes. In the case above, I wrapped everything in a computed() wrapper to return a single signal.

Proposed Solution

I've got two approaches off the top of my head:

Vend a flow() helper

Maybe just have a flow() (or whatever bikeshedded name) helper to handle things like control flow or things that use Signals but don't return a Signal which just does the following:

export function flow(val: () => unknown) {
  return watch(computed(val));
}

This would result in the following code:

const list = signal([{val: 'a', id: 0}, {val: 'b', id: 1}, {val: 'c', id: 2}]);

export class MyElement extends LitElement {
  render() {
    return html`
      <div>
        Things in the list: ${
          flow(() => repeat(list.value, item => item.id, (item, index) => html`
            <div>${item.val}</div>
            <!-- this is inside a computed function, so this does not need another `watch()` to trigger -->
           ${index !== item.length - 1 ? html`<div class="divider"></div>` : nothing}
          `)
        }
      </div>
      <div>
        <!-- this ternary needs a computed to trigger recalculation --> 
        The number of items is ${flow(() => (list.value.length % 1 === 0 ? 'even' : 'odd'))}
      </div>
    `;
  }
}

Pros

• Simple implementation
• Named for the cases for which it is used
• watch() calls inside the flow() become unnecessary

Cons

• You have to think about when to use watch() and when to use flow()
• You have to be aware that the entire flow(fn) fn value is going to be recalculated whenever a signal inside of it is changed which may lead to some unnecessary recalcs that could have been solved with a watch()
• watch() calls inside the flow() are superfluous so it's inconsistent (perhaps watch() should also support functions to prevent whole template recalc?)

Enhance the watch() directive

Perhaps allow watch() to accept a Signal|()=>unknown, check if it's a signal. If so, subscribe to it. Otherwise, wrap it in a computed()

Pros

• Same API
• Generally don't have to think about it

Cons

• A bit leaky as you need to know when to wrap in a function or not

[e111077]

@justinfagnani
The difference that I see here is that they have the potential to replace the reactive element lifecycle with something in the platform just as we do with the custom element lifecycle to handle attributes. A watch() directive approach would give people an easier upgrade path.

@sorvell
Please tell me this is not pain watch(computed(() => repeat(

[justinfagnani]

@e111077 Signals would not replace the reactive element lifecycle. They specifically leave scheduling up to "frameworks" and all signal-based frameworks now implement batching not to dissimilar from our lifecycle.

The intention is for a library to use primitive to watch signals, then schedule an update, then read the signals. The whole tension with the signals primitive for us is that they don't allow reading a signal during notification, so you have to read them async. Their examples show doing this by enqueing a microtask, which is more or less what we do already.

See their example here: https://github.com/proposal-signals/proposal-signals?tab=readme-ov-file#implementing-effects

// This function would usually live in a library/framework, not application code
// NOTE: This scheduling logic is too basic to be useful. Do not copy/paste.
let pending = false;

let w = new Signal.subtle.Watcher(self => {
    if (!pending) {
        pending = true;
        queueMicrotask(() => {
            pending = false;
            for (let s of self.getPending()) s.get();
            self.watch();
        });
    }
});

// An effect effect Signal which evaluates to cb, which schedules a read of
// itself on the microtask queue whenever one of its dependencies might change
export function effect(cb) {
    let destructor;
    let c = new Signal.Computed(() => { destructor.?(); destructor = cb(); });
    w.watch(c);
    c.get();
    return () => { destructor.?(); w.unwatch(c) };
}

[e111077]

I mean perhaps we can have a future where the RE lifecycle heavily relies on signals in a way that reduces bytes and relies more on the platform for reactivity rather than our current approach.

There would definitely need to be some work to convert attributes to signals / update signals as well as integrate reactive controllers, and we’d definitely need to weigh the performance and size. But a standardization here could mean that this is what developers might eventually expect to interact with reactivity, so we should consider what a deeper integration would look like and send feedback to make sure we have that option open in the future.

[sorvell]

@justinfagnani Unless I'm mistaken, it doesn't seem computationally similar to me. If I have an element with N parts and 1 signal changes, if I use 'watch', it will avoid ~N dirty checks. If N is say, 100k, that could be significant. Is that wrong?

@e111077 Ack the DX issue, just trying to find the best solution. I wonder if maybe the auto-function thing + a signal/directive wrapper of some sort might be good... so you could just do repeat (signal version) and it'd work (somehow)?

[sorvell]

Explored some of these ideas in this playground.

@justinfagnani Ack the issue with uncoordinated async updates. Perhaps this can be addressed. This would need more thought but here's a sketch. In the example above...

1. signal effects are queued and there's a signalEffectsComplete() helper.
2. updateComplete awaits this helper.
3. the element's own updated is pushed off by this helper as well (hacked this in via _$didUpdate atm).

We'd need to determine how to auto-integrate this better but then, (1) the element itself (e.g. updated) wouldn't have to do anything special to understand when it rendered, (2) anyone using updateComplete would also get the expected element update state.

@e111077 Also in the example above, the special signal html always wraps functions and directives in addition to signals. Functions that aren't mapped to event parts become computed. I didn't do anything yet with directives.