diff --git a/docs-src/documentation/state-values.page.ts b/docs-src/documentation/state-values.page.ts index 7e01aa06..34bc2a90 100644 --- a/docs-src/documentation/state-values.page.ts +++ b/docs-src/documentation/state-values.page.ts @@ -141,8 +141,9 @@ export default ({ page, nextPage, prevPage, docsMenu }: PageComponentProps) => 'typescript' )}

- Simply wrap your calculation in effect and comma - separate all the states it depends on before your side effect. + Simply wrap a state or dynamic value in effect and + comma separate all the states it depends on before your "side + effect".

effect(...STATE, SIDE_EFFECT_ACTION_OR_STATE)

diff --git a/docs-src/documentation/what-is-a-helper.page.ts b/docs-src/documentation/what-is-a-helper.page.ts index 193f6f14..75b4fa0f 100644 --- a/docs-src/documentation/what-is-a-helper.page.ts +++ b/docs-src/documentation/what-is-a-helper.page.ts @@ -14,15 +14,15 @@ export default ({ page, nextPage, prevPage, docsMenu }: PageComponentProps) => html` ${Heading(page.name)}

- A helper is simply a function. A function that main purpose is - to help with some logic in the template. + A Markup helper is simply a function, which the main purpose is + to help with some render logic or value in the template.

It can be used to check data, wrap or render templates, manipulate data, etc. You can create simple functions and use the template update method to trigger them all or wrap functions - in Helper call to make it work with template + in helper call to make it work with template states.

${Heading('Simple helper', 'h3')} @@ -35,6 +35,7 @@ export default ({ page, nextPage, prevPage, docsMenu }: PageComponentProps) => ${CodeSnippet( 'let count = 0;\n' + '\n' + + '// simple count helper function to display "even" or "odd" \n' + "const evenOddCountLabel = () => count % 2 === 0 ? 'even' : 'odd';\n" + '\n' + 'const counter = html`\n' + @@ -58,7 +59,7 @@ export default ({ page, nextPage, prevPage, docsMenu }: PageComponentProps) =>

For contrast, this is how it would look like if I was using - state instead. + state count instead.

${CodeSnippet( 'let [count, setCount] = state(0);\n' + @@ -87,16 +88,28 @@ export default ({ page, nextPage, prevPage, docsMenu }: PageComponentProps) => ${Heading('Helper wrapper', 'h3')}

We can simplify the helper above with the - helper wrapper. + helper wrapper and remove the need for the + effect helper when using it in the + template.

-

To use the helper wrapper, all you need to do is - wrap a function with it. If that function takes as - StateGetter directly as argument, the template will - know to recalculate the result of that helper when the states it - depends on changes. + wrap a function with it. +

+ ${CodeSnippet( + 'const evenOddLabel = helper((x: StateGetter) => x() % 2 === 0 \n' + + " ? 'even' \n" + + " : 'odd');", + 'typescript' + )} +

+ Notice that now it is a pure function that takes the + x input which must be a StateGetter. + What this mean is that, whenever the state changes, the helper + will tell the template to update that specific part of the DOM + where it is used.

+

Here is the full result:

${CodeSnippet( 'let [count, setCount] = state(0);\n' + '\n' + @@ -117,13 +130,25 @@ export default ({ page, nextPage, prevPage, docsMenu }: PageComponentProps) => 'counter.render(document.body)', 'typescript' )} - ${Heading('Helper value', 'h4')} +

+ You can learn to improve it further by checking + how to create your custom helpers. +

+ ${Heading('Helper value and arguments', 'h4')}

The helper wrapper returns an instance of - Helper which the template itself knows how to - handle. All it does is call it and get the value. + Helper that the template itself knows how to handle + by accessing the value and + args properties. +

+ ${CodeSnippet( + 'evenOddLabel(count).value;\nevenOddLabel(count).args;\n', + 'typescript' + )} +

+ By knowing these two properties, you can use them anywhere in + your code for any type of functionality you want to create.

- ${CodeSnippet('evenOddLabel(() => 12).value', 'typescript')} ${Heading('Working with helpers', 'h4')}

Helpers are just functions, and you can do anything you would @@ -142,24 +167,27 @@ export default ({ page, nextPage, prevPage, docsMenu }: PageComponentProps) => 'typescript' )}

- Ofcourse you can simplify this by moving them into a new helper - altogether to make it easier to read, but it should give you - enough idea of what is possible. + What this is illustrating is the + functional oriented + nature of Markup, specifically the ability to compose simple + functions to create complex renders and logic handlers.

${Heading('Helper scope state', 'h3')}

- The best way to introduce internal state to the helper functions - is to use + Helpers can also keep internal state through JavaScript closure - and the helper would still work just fine. + >JavaScript closures, and it should not be a problem. Your helper function can be + up to one level nested function.

The following filter use the outer function to "cache" the - condition and the filtered list results, so it can save - unnecessary computation. + condition, and the filtered list results, so it can save + unnecessary computation. The inner returned function is used as + the handler.

${CodeSnippet( 'const filterList = helper((list, filterer, condition = () => null) => {\n' + @@ -178,14 +206,13 @@ export default ({ page, nextPage, prevPage, docsMenu }: PageComponentProps) => 'typescript' )}

- This is just an example and not something you will need with - this library if using state, but it shows that you can freely - nest functions up to one two levels (outer and inner) and the - helper would still function well. + This is just a simple example, but it shows that you can nest + functions up to one level (outer and inner) and the helper would + still function well.

- This capability will allow helpers to keep data in between - calculations and you to build more powerful helpers to support + This capability will allow helpers to keep data between + calculations, and you to build more powerful helpers to support your project.

${DocPrevNextNav({