Skip to content

Commit 2eecafe

Browse files
tbranyentbranyen
committed
More docs updates
1 parent 517b9db commit 2eecafe

5 files changed

Lines changed: 92 additions & 30 deletions

File tree

‎docs/components.html‎

Lines changed: 13 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -303,7 +303,7 @@ <h2 id="a-hreffunction-componentfunction-componenta"><a href="#function-componen
303303
}
304304

305305
innerHTML(document.body, html`&lt;${MyComponent} someProp=&quot;value&quot; /&gt;`);</code></pre>
306-
<p><a name="class component"></a></p>
306+
<p><a name="class-component"></a></p>
307307
<hr></hr>
308308
<h2 id="a-hrefclass-componentclass-componenta"><a href="#class-component">Class Component</a></h2>
309309
<p>The stateful class component, which is used by importing the <code>Component</code> class.</p>
@@ -334,14 +334,21 @@ <h2 id="a-hrefclass-componentclass-componenta"><a href="#class-component">Class
334334
Components.</p>
335335
<p><a name="component-props"></a></p>
336336
<h3 id="a-hrefcomponent-propsupropsua"><a href="#component-props"><u>Props</u></a></h3>
337-
<p>These are incoming values that map to the props you set using the element
338-
attributes. Like in React, there will be a <code>children</code> prop automatically added
339-
which maps to the passed in child elements. You can access props on
340-
<code>this.props</code> or in the <code>render(props) {}</code> method.</p>
337+
<p>Incoming attribute values which are mapped into a <code>props</code> object, <code>children</code> is
338+
a special property which is provided that maps to the VTree <code>childNodes</code>. You
339+
can access props on <code>this.props</code> or in the <code>render(props) {}</code> method.</p>
341340
<p><a name="component-state"></a></p>
342341
<h3 id="a-hrefcomponent-stateustateua"><a href="#component-state"><u>State</u></a></h3>
343-
<h4 id="forceupdate">forceUpdate</h4>
342+
<p>A mutable object that can be updated with <code>setState</code>. You can also manually
343+
modify this object and call <code>forceUpdate</code> to simulate what <code>setState</code> does.
344+
This notion of state is what makes a component reactive. Without it, components
345+
only re-render when their parent has rendered.</p>
344346
<h4 id="setstate">setState</h4>
347+
<p>This is the most common way of updating state that is local to a component. You
348+
use it to update the <code>state</code> object and trigger a re-render.</p>
349+
<h4 id="forceupdate">forceUpdate</h4>
350+
<p>Calling this function schedules a re-render of the current component. It is
351+
useful to call this when you know the state has changed and want it reflected.</p>
345352
<p><a name="lifecycle-hooks"></a></p>
346353
<h3 id="a-hreflifecycle-hooksulifecycle-hooksua"><a href="#lifecycle-hooks"><u>Lifecycle hooks</u></a></h3>
347354
<p>The following hooks will be called during the respective mounting and

‎packages/diffhtml-website/config.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@
1919
"release": "#release",
2020
"Internals": "#internals",
2121
"VERSION": "#version",
22-
"Config options": "#config-options"
22+
"Options": "#options"
2323
}],
2424

2525
"Parser": ["parser.html", {

‎packages/diffhtml-website/pages/api.md‎

Lines changed: 27 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -36,7 +36,7 @@ Transaction, invokes [middleware](/middleware.html), compares old and new markup
3636
| ----------- | -----------
3737
| **mount** | DOM Node or VTree to sync or patch the **childNodes** of.
3838
| **input** | New markup to replace into **mount**.
39-
| **options** | **[Config options](#config-options)**, `inner` is always `true`
39+
| **options** | **[Config options](#options)**, `inner` is always `true`
4040

4141
<a name="inner-html-examples"></a>
4242

@@ -72,7 +72,7 @@ but this can sometimes result in unexpected behavior.
7272
| ----------- | -----------
7373
| **mount** | DOM Node or VTree to sync or patch.
7474
| **input** | New markup to replace into **mount**.
75-
| **options** | **[Config options](#config-options)**, `inner` is always `false`
75+
| **options** | **[Config options](#options)**, `inner` is always `false`
7676

7777
<a name="outer-html-examples"></a>
7878

@@ -105,7 +105,7 @@ All middleware run during this, so features like components and logging work.
105105
| Name | Description
106106
| ----------- | -----------
107107
| **input** | New markup to replace into **mount**.
108-
| **options** | **[Config options](#config-options)**, `inner` and `executeScripts` have no effect
108+
| **options** | **[Config options](#options)**, `inner` and `executeScripts` have no effect
109109

110110
<a name="to-string-examples"></a>
111111

@@ -548,30 +548,40 @@ Property which indicates the current running version of diffHTML.
548548
console.log(VERSION);
549549
```
550550

551-
<a name="config-options"></a>
551+
<a name="options"></a>
552552

553553
---
554554

555-
## <a href="#config-options">Config options</a>
555+
## <a href="#options">Options</a>
556556

557-
- [`inner`](#config-options-inner)
558-
- [`tasks`](#config-options-tasks)
559-
- [`executeScripts`](#config-options-execute-scripts)
560-
- [`parser`](#config-options-parser)
557+
Allows configuring runtime rendering behavior. These options are accessible via
558+
`transaction.config` and can be set via query string, environment variables, or
559+
passing a config object to `innerHTML`, `outerHTML`, and `toString`.
561560

562-
<a name="config-options-inner" />
561+
In the case of query string and environment variables, uppercase the variables
562+
and prefix with `DIFF_`. So `inner` becomes `DIFF_INNER`. For `parser` use a
563+
JSON string: `JSON.stringify({ parser: { strict: true } })`.
563564

564-
### <a href="#config-options-inner">inner `Boolean`</a>
565+
- [`inner`](#options-inner)
566+
- [`tasks`](#options-tasks)
567+
- [`executeScripts`](#options-execute-scripts)
568+
- [`parser`](#options-parser)
569+
570+
<a name="options-inner" />
571+
572+
---
573+
574+
### <a href="#options-inner">inner `Boolean`</a>
565575

566576
Determines if the Transaction should update the DOM Node or just its children.
567577
Setting this to `true` will emulate the behavior of `innerHTML` and setting it
568578
to `false` emulates `outerHTML`. You cannot set this using `innerHTML` or
569579
`outerHTML`, and it has no effect with `toString` so it is only useful if you
570580
manually create Transactions which is an advanced use case.
571581

572-
<a name="config-options-tasks" />
582+
<a name="options-tasks" />
573583

574-
### <a href="#config-options-tasks">tasks `Function[]`</a>
584+
### <a href="#options-tasks">tasks `Function[]`</a>
575585

576586
Manipulate the tasks which run. This can allow you to do interesting things
577587
with the core API. You can do API changes like providing a stream or generator
@@ -621,9 +631,9 @@ innerHTML(document.body, `<h1>Hello world</h1>`, {
621631
});
622632
```
623633

624-
<a name="config-options-execute-scripts" />
634+
<a name="options-execute-scripts" />
625635

626-
### <a href="#config-options-execute-scripts">executeScripts `Boolean`</a>
636+
### <a href="#options-execute-scripts">executeScripts `Boolean`</a>
627637

628638
Control whether or not newly appended scripts are executed or not. When
629639
enabled, tricks the browser by setting the `type` property to `no-execute` when
@@ -644,9 +654,9 @@ innerHTML(document.body, `<script>window.alert('here')</script>`, {
644654

645655
```
646656

647-
<a name="config-options-parser" />
657+
<a name="options-parser" />
648658

649-
### <a href="#config-options-parser">parser `Object`</a>
659+
### <a href="#options-parser">parser `Object`</a>
650660

651661
These options modify the parser by making it more strict or changing which
652662
elements are treated as block or self closing.

‎packages/diffhtml-website/pages/components.md‎

Lines changed: 16 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -37,7 +37,7 @@ function MyComponent(props) {
3737
innerHTML(document.body, html`<${MyComponent} someProp="value" />`);
3838
```
3939

40-
<a name="class component"></a>
40+
<a name="class-component"></a>
4141

4242
---
4343

@@ -82,19 +82,29 @@ Components.
8282

8383
### <a href="#component-props"><u>Props</u></a>
8484

85-
These are incoming values that map to the props you set using the element
86-
attributes. Like in React, there will be a `children` prop automatically added
87-
which maps to the passed in child elements. You can access props on
88-
`this.props` or in the `render(props) {}` method.
85+
Incoming attribute values which are mapped into a `props` object, `children` is
86+
a special property which is provided that maps to the VTree `childNodes`. You
87+
can access props on `this.props` or in the `render(props) {}` method.
8988

9089
<a name="component-state"></a>
9190

9291
### <a href="#component-state"><u>State</u></a>
9392

94-
#### forceUpdate
93+
A mutable object that can be updated with `setState`. You can also manually
94+
modify this object and call `forceUpdate` to simulate what `setState` does.
95+
This notion of state is what makes a component reactive. Without it, components
96+
only re-render when their parent has rendered.
9597

9698
#### setState
9799

100+
This is the most common way of updating state that is local to a component. You
101+
use it to update the `state` object and trigger a re-render.
102+
103+
#### forceUpdate
104+
105+
Calling this function schedules a re-render of the current component. It is
106+
useful to call this when you know the state has changed and want it reflected.
107+
98108
<a name="lifecycle-hooks"></a>
99109

100110
### <a href="#lifecycle-hooks"><u>Lifecycle hooks</u></a>

‎packages/diffhtml-website/public/scripts/promises-keyframe.js‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
import { html, innerHTML, addTransitionState } from 'https://diffhtml.org/core';
2+
3+
const duration = 3000;
4+
5+
addTransitionState('attributeChanged', (domNode, attrName, oldValue, newValue) => {
6+
if (attrName !== 'id') {
7+
return;
8+
}
9+
10+
const frames = [
11+
{ transform: 'translateX(0)' },
12+
{ transform: 'translateX(-50%)' },
13+
];
14+
15+
domNode.animate(frames, { duration }).finished;
16+
});
17+
18+
const promisesKeyframe = document.querySelector('#promises-keyframe');
19+
20+
let frame = 0;
21+
22+
function renderFrame(number) {
23+
innerHTML(promisesKeyframe, html`
24+
<div id="frame-${number}">
25+
<span>${String(number)}</span>
26+
</div>
27+
`);
28+
}
29+
30+
setInterval(() => {
31+
frame++;
32+
renderFrame(frame);
33+
}, duration);
34+
35+
renderFrame(frame);

0 commit comments

Comments
 (0)