docs(core): primary Angular Signals documentation #50053

alxhub · 2023-04-27T21:25:55Z

Adds the developer preview signals guide to AIO, under the preview section. This guide explains signals, computed properties, and effects.

github-actions · 2023-04-27T21:34:15Z

Deployed aio for b110e65 to: https://ng-dev-previews-fw--pr-angular-angular-50053-3lmpdflu.web.app

Note: As new commits are pushed to this pull request, this link is updated after the preview is rebuilt.

jelbourn

Got about halfway through before running out of steam for the night, will finish tomorrow

aio/content/guide/signals.md

jelbourn · 2023-04-28T03:40:14Z

aio/content/guide/signals.md

Suggested change

A signal is a wrapper around a value, which is capable of notifying interested consumers when that value changes. There are different kinds of signals.

Some signals can have their value directly updated via a mutation API. In our implementation, these are known as "writable" signals. Updates to the model are always done by changing one or more writable signals.

Because reading a signal is done through a getter, signals are able to keep track of where they're being read. And because mutations are always done with the mutation API, signals know when they're mutated and inform previous readers about the change.

A **signal** is a wrapper around a value that can notify interested consumers when that value changes. Signals can contain any value, from simple primitives to complex data structures.

A signal's value is always read through a getter function. When you use this getter function in certain contexts, Angular automatically creates a consumer that receives updates whenever the signal's value changes.

Signals may be either _writable_ or _read-only_.

Suggestion here to simplify this section a bit. I would also pair this with changing Writable signals and Computed signals to h3 (so that the last section is a bridge to the subsequent subsection)

jelbourn · 2023-04-28T03:42:21Z

aio/content/guide/signals.md

Suggested change

Writable signals are created via the `signal` function, and always start with an initial value:

You create writable signals by calling the `signal` function with the signal's initial value.

suggestion for passive voice, slightly simplified sentence structure

jelbourn · 2023-04-28T04:01:18Z

aio/content/guide/signals.md

Suggested change

Values inside writable signals can be simple primitives or complex nested objects. In the latter case, sometimes we want to mutate those objects without needing to produce entirely new values, such as pushing new data to an array. To do that, we can use the `.mutate` operation:

If your signals contains an object, you may want to mutate that object directly without creating a new instance. One common example is pushing a new value into an array. To update an object, use the `.mutate` method:

I grabbed the first sentence here and snuck a slightly modified version of it into the introductory paragraph on signals since it seems more foundational.

We'd generally also want to avoid first-person in docs ("I" and "we"), preferring "you". Even better, though, if we can make the "you" implicit as an imperative.

aio/content/guide/signals.md

JeanMeche

2 nit !

JeanMeche · 2023-04-28T14:02:07Z

aio/content/guide/signals.md

We can keep the link relative :

Suggested change

Angular signals are available for [developer preview](https://angular.io/guide/releases#developer-preview). They're ready for you to try, but may change before they are stable.

Angular signals are available for [developer preview](/guide/releases#developer-preview). They're ready for you to try, but may change before they are stable.

JeanMeche · 2023-04-28T14:02:31Z

aio/content/guide/signals.md

Same as above 👍

Suggested change

When a signal is read in the template of an `OnPush` component, that component becomes a tracked consumer of the signal. When that signal is updated and notifies its consumers, Angular will automatically mark the component for check and it will be updated the next time change detection runs. Refer to the [Skipping component subtrees](https://angular.io/guide/change-detection-skipping-subtrees) guide for more information about `OnPush` components.

When a signal is read in the template of an `OnPush` component, that component becomes a tracked consumer of the signal. When that signal is updated and notifies its consumers, Angular will automatically mark the component for check and it will be updated the next time change detection runs. Refer to the [Skipping component subtrees](/guide/change-detection-skipping-subtrees) guide for more information about `OnPush` components.

I did a little poking around other places where we reference e.g. the developer preview guide, and they all use an absolute link.

aio/content/guide/signals.md

jelbourn

Finished! Feel free to tweak these suggestions if they're not totally capture what you're trying to say; I tried to keep the concepts largely the same, just making edits for tech writing best practices.

aio/content/guide/signals.md

jelbourn · 2023-04-28T19:02:10Z

aio/content/guide/signals.md

Suggested change

Signals are useful because they can notify interested consumers when they change. An operation that's performed when the signals it depends on are changed is called an "effect". For example, Angular uses an effect to mark an `OnPush` component for check whenever any signals used within that component's template are changed.

Using the `effect` function, you can create your own effects:

Signals are useful because they can notify interested consumers when they change. An **effect** is an operation that runs whenever one or more signal values change. You can create an effect with the `effect` function.

I would move the part here about OnPush to later in this section, as something like

Internally, Angular uses `effects` for its own behaviors. For example, the framework uses an effect to mark `OnPush` components for change detection whenever any signal values read within that component's template change.

I disagree about moving the OnPush section.

Using signals to mark OnPush components for check is the primary use case (in v16), which doesn't require understanding or creating effects.

jelbourn · 2023-04-28T19:07:53Z

aio/content/guide/signals.md

Suggested change

Effects execute once initially, and then whenever one or more of the signals they read are updated. Like with computed signals, effects keep track of their dependencies dynamically, so signals inside conditionals that don't execute are not considered dependencies.

**Effects always run at least once.** During this first run, the effect tracks any signal value reads. Whenever any of these signal values change, the effect runs again. Similar to computed signals, effects keep track of their dependencies dynamically, so the effect does not track any signal values that are not read.

aio/content/guide/signals.md

jelbourn · 2023-04-28T19:24:32Z

aio/content/guide/signals.md

Suggested change

For writable signals, `.mutate()` always bypasses the equality check, because it mutates the current value and doesn't produce a new one.

For writable signals, `.mutate()` always ignores the equality check because it mutates the current value without producing a new reference.

Changed to "does not check for equality"

aio/content/guide/signals.md

Addressed

Adds the developer preview signals guide to AIO, under the preview section. This guide explains signals, computed properties, and effects.

jelbourn

LGTM

alxhub · 2023-04-28T23:36:40Z

This PR was merged into the repository by commit 73c6126.

Adds the developer preview signals guide to AIO, under the preview section. This guide explains signals, computed properties, and effects. PR Close #50053

Adds the developer preview signals guide to AIO, under the preview section. This guide explains signals, computed properties, and effects. PR Close angular#50053

angular-automatic-lock-bot · 2023-05-29T00:09:01Z

This issue has been automatically locked due to inactivity.
Please file a new issue if you are encountering a similar or related problem.

Read more about our automatic conversation locking policy.

_{This action has been performed automatically by a bot.}

alxhub added the aio: preview label Apr 27, 2023

pullapprove bot requested a review from MarkTechson April 27, 2023 21:26

angular-robot bot added the area: docs label Apr 27, 2023

alxhub added target: rc This PR is targeted for the next release-candidate and removed area: docs labels Apr 27, 2023

ngbot bot modified the milestone: Backlog Apr 27, 2023

jelbourn reviewed Apr 28, 2023

View reviewed changes

pkozlowski-opensource added area: docs area: core Issues related to the framework runtime labels Apr 28, 2023

ngbot bot added this to the Backlog milestone Apr 28, 2023

JeanMeche reviewed Apr 28, 2023

View reviewed changes

alxhub modified the milestones: Backlog, v16-final Apr 28, 2023

dylhunn self-requested a review April 28, 2023 17:07

dylhunn previously requested changes Apr 28, 2023

View reviewed changes

aio/content/guide/signals.md Outdated Show resolved Hide resolved

aio/content/guide/signals.md Outdated Show resolved Hide resolved

aio/content/guide/signals.md Outdated Show resolved Hide resolved

alxhub force-pushed the v16/signal-docs branch from bef2307 to 86f5276 Compare April 28, 2023 19:25

jelbourn reviewed Apr 28, 2023

View reviewed changes

alxhub force-pushed the v16/signal-docs branch 2 times, most recently from 0593bbd to 928f76e Compare April 28, 2023 21:02

alxhub added the action: merge The PR is ready for merge by the caretaker label Apr 28, 2023

docs(core): primary Angular Signals documentation

b110e65

Adds the developer preview signals guide to AIO, under the preview section. This guide explains signals, computed properties, and effects.

alxhub force-pushed the v16/signal-docs branch from 928f76e to b110e65 Compare April 28, 2023 23:33

jelbourn approved these changes Apr 28, 2023

View reviewed changes

alxhub closed this in 73c6126 Apr 28, 2023

alxhub added a commit that referenced this pull request Apr 28, 2023

docs(core): primary Angular Signals documentation (#50053)

6dc3add

Adds the developer preview signals guide to AIO, under the preview section. This guide explains signals, computed properties, and effects. PR Close #50053

angular-automatic-lock-bot bot locked and limited conversation to collaborators May 29, 2023

-A signal is a wrapper around a value, which is capable of notifying interested consumers when that value changes. There are different kinds of signals.
-Some signals can have their value directly updated via a mutation API. In our implementation, these are known as "writable" signals. Updates to the model are always done by changing one or more writable signals.
-Because reading a signal is done through a getter, signals are able to keep track of where they're being read. And because mutations are always done with the mutation API, signals know when they're mutated and inform previous readers about the change.
+A **signal** is a wrapper around a value that can notify interested consumers when that value changes. Signals can contain any value, from simple primitives to complex data structures.
+A signal's value is always read through a getter function. When you use this getter function in certain contexts, Angular automatically creates a consumer that receives updates whenever the signal's value changes.
+Signals may be either _writable_ or _read-only_.

	Writable signals are created via the `signal` function, and always start with an initial value:
	You create writable signals by calling the `signal` function with the signal's initial value.

	Values inside writable signals can be simple primitives or complex nested objects. In the latter case, sometimes we want to mutate those objects without needing to produce entirely new values, such as pushing new data to an array. To do that, we can use the `.mutate` operation:
	If your signals contains an object, you may want to mutate that object directly without creating a new instance. One common example is pushing a new value into an array. To update an object, use the `.mutate` method:

	Angular signals are available for [developer preview](https://angular.io/guide/releases#developer-preview). They're ready for you to try, but may change before they are stable.
	Angular signals are available for [developer preview](/guide/releases#developer-preview). They're ready for you to try, but may change before they are stable.

-Signals are useful because they can notify interested consumers when they change. An operation that's performed when the signals it depends on are changed is called an "effect". For example, Angular uses an effect to mark an `OnPush` component for check whenever any signals used within that component's template are changed.
-Using the `effect` function, you can create your own effects:
+Signals are useful because they can notify interested consumers when they change. An **effect** is an operation that runs whenever one or more signal values change. You can create an effect with the `effect` function.

	Effects execute once initially, and then whenever one or more of the signals they read are updated. Like with computed signals, effects keep track of their dependencies dynamically, so signals inside conditionals that don't execute are not considered dependencies.
	Effects always run at least once. During this first run, the effect tracks any signal value reads. Whenever any of these signal values change, the effect runs again. Similar to computed signals, effects keep track of their dependencies dynamically, so the effect does not track any signal values that are not read.

	For writable signals, `.mutate()` always bypasses the equality check, because it mutates the current value and doesn't produce a new one.
	For writable signals, `.mutate()` always ignores the equality check because it mutates the current value without producing a new reference.

docs(core): primary Angular Signals documentation #50053

docs(core): primary Angular Signals documentation #50053

Uh oh!

Conversation

alxhub commented Apr 27, 2023

Uh oh!

github-actions bot commented Apr 27, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jelbourn left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jelbourn Apr 28, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

JeanMeche left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jelbourn left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jelbourn left a comment

Choose a reason for hiding this comment

Uh oh!

alxhub commented Apr 28, 2023

Uh oh!

angular-automatic-lock-bot bot commented May 29, 2023

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

github-actions bot commented Apr 27, 2023 •

edited

Loading

jelbourn Apr 28, 2023 •

edited

Loading