iAPI Docs: The first three Core Concepts guides #63759

luisherranz · 2024-07-19T16:26:01Z

EDIT: Initially, in this pull request, I only included the guide "the reactive and declarative mindset". But now, I have included the three guides to merge and review them simultaneously to ensure they are consistent with each other.

What?

These are the first guides of the Core Concepts section of the Interactivity API, which aims to explain the concepts of:

The reactive and declarative mindset.
Understanding global state, local context, and derived state.
Server-side rendering: How directives are processed on the server.

Why?

The Interactivity API would benefit from some guides that explain the concepts and mental models, not just from the API references.

How?

I added a file to a new folder called core-concepts, but I'm not really sure how to structure this.

@juanmaguitar, can you give me a hand? 🙂

On the other hand, I would still like to add a section to the guide with examples of what people should not do (such as mutating the DOM within an action) and the exceptions (such as removing or adding a class to the body element).

I think I've also used we in some places, and I shouldn't have. @juanmaguitar, can you confirm this for me as well?

juanmaguitar · 2024-07-23T05:37:11Z

I think I've also used we in some places, and I shouldn't have. @juanmaguitar, can you confirm this for me as well?

@luisherranz "we" is not explicitly forbidden, but its use is discouraged. In the case we want to use it, we should specify who "we" means ("the group of contributors that worked on this feature" for example)

At Style Guide / Language and grammar / Grammatical person, it states

Second person
In general, use second person in your documentation. Second person depicts a friendly tone, with a perfect focus on the reader. In addition to this, directly addressing the reader helps avoid passive voice; thereby preventing unwanted confusion.

First person
Use first person (I, we) only when absolutely needed. First person may be used in quotes, direct references, and personifications. First person plurals such as we and our may intimidate the reader in some cases. Try to avoid first person plurals, but be cautious if you’re using them.

Also at Core Handbook / Best Practices / Post & Comment Guidelines > Style and Substance it states

Similarly, the word “we” should be avoided in posts, unless its made very clear which group is speaking. An example of this is listing attendees of a meeting and, in the summary post, noting that “we, those present at the meeting” made a decision or agreed on a plan of action.

juanmaguitar · 2024-07-23T05:38:42Z

I added a file to a new folder called core-concepts, but I'm not really sure how to structure this.
@juanmaguitar, can you give me a hand? 🙂

Sure! I'll have a look at it this week.

juanmaguitar · 2024-07-24T07:53:03Z

I think this PR tackles this issue #63524
cc: @WPLake

juanmaguitar · 2024-07-24T08:14:50Z

I added a file to a new folder called core-concepts, but I'm not really sure how to structure this.
@juanmaguitar, can you give me a hand?

@luisherranz I have committed some changes to this PR to properly add a new subsection in the docs. Basically, we need to add the new structure to docs/toc.json and then run npm run docs:gen to generate an updated version of docs/manifest.json. I also included a README.md to introduce this new Core Concepts section

github-actions · 2024-07-24T08:32:57Z

Flaky tests detected in 9f59f16.
Some tests passed with failed attempts. The failures may not be related to this commit but are still reported for visibility. See the documentation for more information.

🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/10367917253
📝 Reported issues:

[Flaky Test] Should insert content using the global inserter #57525 in /test/e2e/specs/widgets/editing-widgets.spec.js

juanmaguitar · 2024-07-24T08:34:06Z

docs/reference-guides/interactivity-api/core-concepts/the-reactive-and-declarative-mindset.md

+
+### Can you spot the bug?
+
+In the imperative example, we intentionally introduced a bug. Can you find it? It's not easy!


I think it's fine as it is, but to avoid the use of "we" in the docs, maybe we can say here:

In the imperative example, a bug has been intentionally introduced for didactical purposes. Can you find it? It's not easy!

juanmaguitar · 2024-07-24T08:35:24Z

docs/reference-guides/interactivity-api/core-concepts/the-reactive-and-declarative-mindset.md

+<details>
+<summary>Show me the answer!</summary>
+
+In the case that the Show button is pressed first, then the Activate button, and finally the Hide button, we forgot to add the `inactive` class using `statusParagraph.classList.add('inactive');`. Therefore, the next time the user presses Show, the paragraph will not appear in red.


Again, nothing critical, but to avoid the use of "we" in the docs, maybe we can say here:

In the case that the Show button is pressed first, then the Activate button, and finally the Hide button, there's a missing step in the previous code for adding the inactive class using statusParagraph.classList.add('inactive');. Therefore, the next time the user presses Show, the paragraph will not appear in red.

juanmaguitar · 2024-07-24T08:36:58Z

docs/reference-guides/interactivity-api/core-concepts/the-reactive-and-declarative-mindset.md

+
+5. **Automatic Updates**: When the state or context changes (through actions), the Interactivity API automatically updates all parts of the DOM that depend on that state (or derived state).
+
+Let's break down these concepts with an example from the code we've seen:


Another suggestion to avoid the use of "we"

Let's break down these concepts with an example (adapted from the declarative code example above):

juanmaguitar · 2024-07-24T08:40:39Z

docs/reference-guides/interactivity-api/core-concepts/the-reactive-and-declarative-mindset.md

+
+## Understanding Reactivity
+
+The Interactivity API is a declarative framework thanks to its leverage of reactivity. In a reactive system, changes to the data automatically trigger updates in the user interface, ensuring that the view always reflects the current state of the application.


Maybe we can link this concept to the Block Editor, which uses central Stores to manage state: The Block Editor dynamically responds to state changes, updating the DOM through React components that represent individual blocks.

juanmaguitar · 2024-07-24T08:46:57Z

Great job @luisherranz! I enjoyed reading this guide 🙌
I think it addresses Reactivity and Declarative code very well, two essential ideas to really understand the iAPI approach for adding interactivity in the Frontend (and why it's a good approach).
I left some minor comments, but I think it is not far from being ready to be published as this PR will "inaugurate" this new section and will provide value to iAPI users already.

…derived-state' into iapi-docs-the-reactive-and-declarative-mindset

…ctive-and-declarative-mindset

luisherranz · 2024-08-09T16:11:41Z

I have merged the guide for "Understanding Global State, Local Context, and Derived State" into this pull request, and I have also added the guide for "Server-Side Rendering". This way we can review all three to ensure they are consistent with each other and merge them together once they are ready.

juanmaguitar · 2024-08-13T08:17:02Z

@luisherranz I have added the manifest data (required to have this new structure of docs properly reflected on the BEH sidebar). I also added an introduction to these new guides at core-concepts/README

…rative-mindset' into iapi-docs-the-reactive-and-declarative-mindset

github-actions · 2024-08-13T10:18:40Z

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: luisherranz <[email protected]>
Co-authored-by: juanmaguitar <[email protected]>
Co-authored-by: colorful-tones <[email protected]>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

luisherranz · 2024-08-13T10:18:55Z

The three guides are ready for review.

colorful-tones

This will help a lot of folks, including myself. Well written. Honestly, I'm not sure I'll ever feel confident explaining the differences between imperative and declarative, but it makes sense when I read about it (mostly).

I left one small suggestion. Thanks!

docs/reference-guides/interactivity-api/core-concepts/README.md

colorful-tones

I overlooked expanding some diffs to read in my first review, and took another pass with a few more suggestions.

This is so helpful, well written, and will help many developers understand these core concepts. Thank you!

docs/reference-guides/interactivity-api/core-concepts/server-side-rendering.md

colorful-tones · 2024-08-16T21:07:48Z

docs/reference-guides/interactivity-api/core-concepts/server-side-rendering.md

+} );
+```
+
+To fix this issue, you can use the `wp_interactivity_state` function to serialize the translated mango string and then access that value in your action.


Love this! Amazing! 👏

...interactivity-api/core-concepts/undestanding-global-state-local-context-and-derived-state.md

colorful-tones · 2024-08-16T21:27:49Z

...interactivity-api/core-concepts/undestanding-global-state-local-context-and-derived-state.md

+
+    This lack of distinction is intentional, allowing developers to consume both derived and global state uniformly, and making them interchangeable in practice.
+
+    You can also access the derived state from another derived state and, thus, create multiple levels of computed values.


This made my head explode 🤯 Not your fault though and just because you're blowing my mind. 😆

Co-authored-by: Damon Cook <[email protected]>

luisherranz · 2024-08-19T10:07:03Z

Thank you @colorful-tones for the review and corrections! And thanks @juanmaguitar for the review and approval!

Let's merge this now so that we can publish the guides and if we need to improve them, we can do so in subsequent PRs 🙂

* Initial version * Convert all tabs to spaces (except in non-PHP code snippets) * Initial SSR guide version * Initial version * Changes to properly add a subsection in the docs * Reorganize headers a bit * Add titles (are they necessary?) * Reorganize SSR sections * Use async handlers and update state/context guide * Finish review of the Declarative/reactive guide * Remove last "we's" * added manifest and toc data and intro to guides * Final revision * Fix typos Co-authored-by: Damon Cook <[email protected]> --------- Co-authored-by: luisherranz <[email protected]> Co-authored-by: juanmaguitar <[email protected]> Co-authored-by: colorful-tones <[email protected]>

luisherranz added [Type] Developer Documentation Documentation for developers [Feature] Interactivity API API to add frontend interactivity to blocks. labels Jul 19, 2024

luisherranz self-assigned this Jul 19, 2024

luisherranz mentioned this pull request Jul 23, 2024

Docs: Interactivity API - Create a Core Concepts section for the iAPI #62921

Open

9 tasks

juanmaguitar reviewed Jul 24, 2024

View reviewed changes

Initial version

ace2388

luisherranz mentioned this pull request Jul 25, 2024

iAPI Docs: Understanding global state, local context and derived state #63930

Closed

Convert all tabs to spaces (except in non-PHP code snippets)

b4ebf25

luisherranz mentioned this pull request Aug 6, 2024

Adds tabs block behind block experiments flag #63689

Closed

luisherranz added 4 commits August 9, 2024 16:26

Initial SSR guide version

6d61af1

Initial version

0663878

Merge branch 'iapi-docs-understanding-global-state-local-context-and-…

181b58c

…derived-state' into iapi-docs-the-reactive-and-declarative-mindset

Merge branch 'iapi-docs-server-side-rendering' into iapi-docs-the-rea…

5e7d70c

…ctive-and-declarative-mindset

luisherranz force-pushed the iapi-docs-the-reactive-and-declarative-mindset branch from 7daf260 to 5e7d70c Compare August 9, 2024 14:28

luisherranz changed the title ~~iAPI Docs: The Reactive and Declarative Mindset~~ iAPI Docs: The first three Core Concepts guides Aug 9, 2024

juanmaguitar and others added 2 commits August 9, 2024 16:46

Changes to properly add a subsection in the docs

df2df97

Reorganize headers a bit

d3fc42a

luisherranz mentioned this pull request Aug 12, 2024

Docs: Interactivity API - TypeScript snippet is used in the sample. #64418

Closed

2 tasks

luisherranz added 2 commits August 12, 2024 12:08

Add titles (are they necessary?)

c984cdd

Reorganize SSR sections

829329c

luisherranz and others added 4 commits August 12, 2024 15:21

Use async handlers and update state/context guide

8c9c0b8

Finish review of the Declarative/reactive guide

3eb16f0

Remove last "we's"

2d33606

added manifest and toc data and intro to guides

f9074e6

luisherranz added 2 commits August 13, 2024 12:17

Final revision

f98ad5b

Merge remote-tracking branch 'origin/iapi-docs-the-reactive-and-decla…

9f59f16

…rative-mindset' into iapi-docs-the-reactive-and-declarative-mindset

luisherranz marked this pull request as ready for review August 13, 2024 10:18

luisherranz requested review from ajitbohra, ryanwelcher, fabiankaegy and ndiego as code owners August 13, 2024 10:18

luisherranz mentioned this pull request Aug 16, 2024

iAPI: Refactor types and add a "Core Concepts - Using TypeScript" guide #64577

Merged

colorful-tones approved these changes Aug 16, 2024

View reviewed changes

docs/reference-guides/interactivity-api/core-concepts/README.md Outdated Show resolved Hide resolved

colorful-tones approved these changes Aug 16, 2024

View reviewed changes

juanmaguitar self-requested a review August 17, 2024 09:18

juanmaguitar approved these changes Aug 17, 2024

View reviewed changes

Fix typos

86586b4

Co-authored-by: Damon Cook <[email protected]>

luisherranz enabled auto-merge (squash) August 19, 2024 10:07

luisherranz merged commit ade27ac into trunk Aug 19, 2024
60 checks passed

luisherranz deleted the iapi-docs-the-reactive-and-declarative-mindset branch August 19, 2024 10:40

github-actions bot added this to the Gutenberg 19.1 milestone Aug 19, 2024

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

iAPI Docs: The first three Core Concepts guides #63759

iAPI Docs: The first three Core Concepts guides #63759

luisherranz commented Jul 19, 2024 •

edited

Loading

juanmaguitar commented Jul 23, 2024 •

edited

Loading

juanmaguitar commented Jul 23, 2024

juanmaguitar commented Jul 24, 2024

juanmaguitar commented Jul 24, 2024

github-actions bot commented Jul 24, 2024 •

edited

Loading

juanmaguitar Jul 24, 2024 •

edited

Loading

juanmaguitar Jul 24, 2024 •

edited

Loading

juanmaguitar Jul 24, 2024

juanmaguitar Jul 24, 2024

juanmaguitar commented Jul 24, 2024 •

edited

Loading

luisherranz commented Aug 9, 2024

juanmaguitar commented Aug 13, 2024

github-actions bot commented Aug 13, 2024 •

edited

Loading

luisherranz commented Aug 13, 2024

colorful-tones left a comment

colorful-tones left a comment

colorful-tones Aug 16, 2024

colorful-tones Aug 16, 2024

luisherranz commented Aug 19, 2024


		### Can you spot the bug?

		In the imperative example, we intentionally introduced a bug. Can you find it? It's not easy!


		5. Automatic Updates: When the state or context changes (through actions), the Interactivity API automatically updates all parts of the DOM that depend on that state (or derived state).

		Let's break down these concepts with an example from the code we've seen:


		## Understanding Reactivity

		The Interactivity API is a declarative framework thanks to its leverage of reactivity. In a reactive system, changes to the data automatically trigger updates in the user interface, ensuring that the view always reflects the current state of the application.


		This lack of distinction is intentional, allowing developers to consume both derived and global state uniformly, and making them interchangeable in practice.

		You can also access the derived state from another derived state and, thus, create multiple levels of computed values.

iAPI Docs: The first three Core Concepts guides #63759

iAPI Docs: The first three Core Concepts guides #63759

Conversation

luisherranz commented Jul 19, 2024 • edited Loading

What?

Why?

How?

juanmaguitar commented Jul 23, 2024 • edited Loading

juanmaguitar commented Jul 23, 2024

juanmaguitar commented Jul 24, 2024

juanmaguitar commented Jul 24, 2024

github-actions bot commented Jul 24, 2024 • edited Loading

juanmaguitar Jul 24, 2024 • edited Loading

Choose a reason for hiding this comment

juanmaguitar Jul 24, 2024 • edited Loading

Choose a reason for hiding this comment

juanmaguitar Jul 24, 2024

Choose a reason for hiding this comment

juanmaguitar Jul 24, 2024

Choose a reason for hiding this comment

juanmaguitar commented Jul 24, 2024 • edited Loading

luisherranz commented Aug 9, 2024

juanmaguitar commented Aug 13, 2024

github-actions bot commented Aug 13, 2024 • edited Loading

luisherranz commented Aug 13, 2024

colorful-tones left a comment

Choose a reason for hiding this comment

colorful-tones left a comment

Choose a reason for hiding this comment

colorful-tones Aug 16, 2024

Choose a reason for hiding this comment

colorful-tones Aug 16, 2024

Choose a reason for hiding this comment

luisherranz commented Aug 19, 2024

luisherranz commented Jul 19, 2024 •

edited

Loading

juanmaguitar commented Jul 23, 2024 •

edited

Loading

github-actions bot commented Jul 24, 2024 •

edited

Loading

juanmaguitar Jul 24, 2024 •

edited

Loading

juanmaguitar Jul 24, 2024 •

edited

Loading

juanmaguitar commented Jul 24, 2024 •

edited

Loading

github-actions bot commented Aug 13, 2024 •

edited

Loading