Skip to content

Commit 5933d25

Browse files
jaandrlejaandrle
committed
🔤
1 parent a5e9bb9 commit 5933d25

File tree

3 files changed

+183
-51
lines changed

3 files changed

+183
-51
lines changed

‎docs/components/examples/introducing/helloWorld.js‎

Lines changed: 13 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -7,20 +7,20 @@ function HelloWorld({ emoji = "🚀" }) {
77
const clicks = S(0);
88

99
return el().append(
10-
// PART 2: Bind state to UI elements
11-
el("p", {
12-
className: "greeting",
13-
// This paragraph automatically updates when clicks changes
14-
textContent: S(() => `Hello World ${emoji.repeat(clicks.get())}`)
15-
}),
10+
// PART 2: Bind state to UI elements
11+
el("p", {
12+
className: "greeting",
13+
// This paragraph automatically updates when clicks changes
14+
textContent: S(() => `Hello World ${emoji.repeat(clicks.get())}`)
15+
}),
1616

17-
// PART 3: Update state in response to events
18-
el("button", {
19-
type: "button",
20-
textContent: "Add emoji",
21-
// When clicked, update the state
22-
onclick: () => clicks.set(clicks.get() + 1)
23-
})
17+
// PART 3: Update state in response to events
18+
el("button", {
19+
type: "button",
20+
textContent: "Add emoji",
21+
// When clicked, update the state
22+
onclick: () => clicks.set(clicks.get() + 1)
23+
})
2424
);
2525
}
2626

‎docs/components/examples/ireland-test/counter.js‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ document.body.append(
99
padding: 1em;
1010
margin: 1em;
1111
}
12-
`.trim())
12+
`.trim())
1313
);
1414

1515
export function CounterStandard() {

‎docs/p13-appendix.html.js‎

Lines changed: 169 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@ import { T, t } from "./utils/index.js";
22
export const info= {
33
title: t`Appendix & Summary`,
44
fullTitle: t`dd<el> Comprehensive Reference`,
5-
description: t`A final overview, case studies, key concepts, and best practices for working with deka-dom-el.`,
5+
description: t`A final overview, case studies, key concepts, and best practices for working with deka-dom-el.`,
66
};
77

88
import { el } from "deka-dom-el";
@@ -25,6 +25,16 @@ const references= {
2525
performance: {
2626
title: t`Performance Optimization Guide`,
2727
href: "p09-optimization.html",
28+
},
29+
/** Examples gallery */
30+
examples: {
31+
title: t`Examples Gallery`,
32+
href: "p15-examples.html",
33+
},
34+
/** Converter */
35+
converter: {
36+
title: t`HTML to dd<el> Converter`,
37+
href: "p14-converter.html",
2838
}
2939
};
3040

@@ -33,8 +43,8 @@ export function page({ pkg, info }){
3343
const page_id= info.id;
3444
return el(simplePage, { info, pkg }).append(
3545
el("p").append(T`
36-
This reference guide provides a comprehensive summary of dd<el>'s key concepts, best practices,
37-
case studies, and advanced techniques. Use it as a quick reference when working with the library
46+
This reference guide provides a comprehensive summary of dd<el>’s key concepts, best practices,
47+
case studies, and advanced techniques. Use it as a quick reference when working with the library
3848
or to deepen your understanding of its design principles and patterns.
3949
`),
4050

@@ -61,14 +71,18 @@ export function page({ pkg, info }){
6171
${el("strong", "Progressive Enhancement:")} Starting simple and adding complexity only when needed
6272
`),
6373
el("li").append(T`
64-
${el("strong", "Functional Composition:")} Building UIs through function composition rather than
65-
inheritance
74+
${el("strong", "Flexibility:")} Using what you need, whether that’s plain DOM elements, event
75+
handling, or signals for reactivity
76+
`),
77+
el("li").append(T`
78+
${el("strong", "Functional Composition:")} Building UIs through function composition
6679
`),
6780
el("li").append(T`
6881
${el("strong", "Clear Patterns:")} Promoting maintainable code organization with the 3PS pattern
6982
`),
7083
el("li").append(T`
71-
${el("strong", "Targeted Reactivity:")} Using signals for efficient, fine-grained updates
84+
${el("strong", "Targeted Reactivity:")} Using signals for efficient, fine-grained updates only when
85+
needed
7286
`),
7387
el("li").append(T`
7488
${el("strong", "Unix Philosophy:")} Doing one thing well and allowing composability with other tools
@@ -77,11 +91,15 @@ export function page({ pkg, info }){
7791
),
7892

7993
el(h3, t`Case Studies & Real-World Applications`),
94+
el("p").append(T`
95+
Explore our ${el("a", references.examples).append("Examples Gallery")} to see how dd<el> can be used to build
96+
various real-world applications, from simple components to complex interactive UIs.
97+
`),
8098

8199
el("h4", t`TodoMVC Implementation`),
82100
el("p").append(T`
83-
The ${el("a", references.todomvc).append("TodoMVC implementation")} showcases how dd<el> handles a complete,
84-
real-world application with all standard features of a modern web app:
101+
The ${el("a", references.todomvc).append("TodoMVC implementation")} showcases how dd<el> handles a complete,
102+
real-world application with all standard features of a modern web app:
85103
`),
86104
el("ul").append(
87105
el("li", t`Persistent storage with localStorage`),
@@ -111,22 +129,93 @@ export function page({ pkg, info }){
111129
`)
112130
),
113131

132+
el("h4", t`Using Signals Appropriately`),
133+
el("p").append(T`
134+
While signals provide powerful reactivity for complex UI interactions, they’re not always necessary.
135+
`),
136+
137+
el("div", { className: "tabs" }).append(
138+
el("div", { className: "tab", dataTab: "events" }).append(
139+
el("h4", t`We can process form events without signals`),
140+
el("p", t`This can be used when the form data doesn’t need to be reactive and we just waiting for
141+
results.`),
142+
el(code, { page_id, content: `
143+
const onFormSubmit = on("submit", e => {
144+
e.preventDefault();
145+
const formData = new FormData(e.currentTarget);
146+
// this can be sent to a server
147+
// or processed locally
148+
// e.g.: console.log(Object.fromEntries(formData))
149+
});
150+
// …
151+
return el("form", null, onFormSubmit).append(
152+
// …
153+
);
154+
` })
155+
),
156+
157+
el("div", { className: "tab", dataTab: "variables" }).append(
158+
el("h4", t`We can use variables without signals`),
159+
el("p", t`We use this when we dont’t need to reflect changes in the elsewhere (UI).`),
160+
el(code, { page_id, content: `
161+
let canSubmit = false;
162+
163+
const onFormSubmit = on("submit", e => {
164+
e.preventDefault();
165+
if(!canSubmit) return; // some message
166+
// …
167+
});
168+
const onAllowSubmit = on("click", e => {
169+
canSubmit = true;
170+
});
171+
`}),
172+
),
173+
174+
el("div", { className: "tab", dataTab: "state" }).append(
175+
el("h4", t`Using signals`),
176+
el("p", t`We use this when we need to reflect changes for example in the UI (e.g. enable/disable
177+
buttons).`),
178+
el(code, { page_id, content: `
179+
const canSubmit = S(false);
180+
181+
const onFormSubmit = on("submit", e => {
182+
e.preventDefault();
183+
// …
184+
});
185+
const onAllowSubmit = on("click", e => {
186+
canSubmit.set(true);
187+
});
188+
189+
return el("form", null, onFormSubmit).append(
190+
// ...
191+
el("button", { textContent: "Allow Submit", type: "button" }, onAllowSubmit),
192+
el("button", { disabled: S(()=> !canSubmit), textContent: "Submit" })
193+
);
194+
`}),
195+
),
196+
el("p").append(T`
197+
A good approach is to started with variables/constants and when necessary, convert them to signals.
198+
`),
199+
),
200+
114201
el("h4", t`Migrating from Traditional Approaches`),
115202
el("p").append(T`
116203
When migrating from traditional DOM manipulation or other frameworks to dd<el>:
117204
`),
118205
el("ol").append(
119206
el("li").append(T`
120-
${el("strong", "Start with state:")}: Convert global variables or ad-hoc state to signals
207+
${el("strong", "Start with state")}: Convert global variables or ad-hoc state to signals
121208
`),
122209
el("li").append(T`
123-
${el("strong", "Replace query selectors:")}: Replace getElementById/querySelector with direct references to elements
210+
${el("strong", "Replace query selectors")}: Replace getElementById/querySelector with direct references
211+
to elements
124212
`),
125213
el("li").append(T`
126-
${el("strong", "Convert imperative updates:")}: Replace manual DOM updates with declarative signal bindings
214+
${el("strong", "Convert imperative updates")}: Replace manual DOM updates with declarative signal
215+
bindings
127216
`),
128217
el("li").append(T`
129-
${el("strong", "Refactor into components:")}: Organize related UI elements into component functions
218+
${el("strong", "Refactor into components")}: Organize related UI elements into component functions
130219
`)
131220
),
132221
el(code, { content: `
@@ -157,7 +246,7 @@ export function page({ pkg, info }){
157246
el("dd", t`Core function for creating DOM elements with declarative properties`),
158247

159248
el("dt", t`el().append(...children)`),
160-
el("dd", t`Add child elements to a parent element`),
249+
el("dd", t`Add child elements to a parent element`),
161250

162251
el("dt", t`memo(key, () => element)`),
163252
el("dd", t`Cache and reuse DOM elements for performance optimization`),
@@ -171,22 +260,22 @@ export function page({ pkg, info }){
171260
el("h4", t`Signals & Reactivity`),
172261
el("dl").append(
173262
el("dt", t`S(initialValue)`),
174-
el("dd", t`Create a signal with an initial value`),
263+
el("dd", t`Create a signal with an initial value`),
175264

176265
el("dt", t`S(() => computation)`),
177-
el("dd", t`Create a derived signal that updates when dependencies change`),
266+
el("dd", t`Create a derived signal that updates when dependencies change`),
178267

179268
el("dt", t`S.el(signal, data => element)`),
180-
el("dd", t`Create reactive elements that update when a signal changes`),
269+
el("dd", t`Create reactive elements that update when a signal changes`),
181270

182271
el("dt", t`S.action(signal, "method", ...args)`),
183-
el("dd", t`Call custom methods defined on a signal`),
272+
el("dd", t`Call custom methods defined on a signal`),
184273

185274
el("dt", t`signal.get()`),
186-
el("dd", t`Get the current value of a signal`),
275+
el("dd", t`Get the current value of a signal`),
187276

188277
el("dt", t`signal.set(newValue)`),
189-
el("dd", t`Update a signal's value and trigger reactive updates`)
278+
el("dd", t`Update a signal’s value and trigger reactive updates`)
190279
)
191280
),
192281

@@ -200,7 +289,7 @@ export function page({ pkg, info }){
200289
el("dd", t`Provides access to component context, signal, host element`),
201290

202291
el("dt", t`dispatchEvent(type, element)`),
203-
el("dd", t`Creates a function for dispatching custom events`),
292+
el("dd", t`Creates a function for dispatching custom events`),
204293

205294
el("dt", t`Signal Factories`),
206295
el("dd", t`Functions that create and configure signals with domain-specific behavior`)
@@ -212,19 +301,45 @@ export function page({ pkg, info }){
212301
el("h4", t`Code Organization`),
213302
el("ul").append(
214303
el("li").append(T`
215-
${el("strong", "Follow the 3PS pattern:")}: Separate state creation, binding to elements, and state updates
304+
${el("strong", "Follow the 3PS pattern")}: Separate state creation, binding to elements, and state updates
305+
`),
306+
el("li").append(T`
307+
${el("strong", "Use component functions")}: Create reusable UI components as functions
308+
`),
309+
el("li").append(T`
310+
${el("strong", "Create signal factories")}: Extract reusable signal patterns into factory functions
311+
`),
312+
el("li").append(T`
313+
${el("strong", "Leverage scopes")}: Use scope for component context and clean resource management
314+
`),
315+
el("li").append(T`
316+
${el("strong", "Event delegation")}: Prefer component-level event handlers over many individual handlers
317+
`)
318+
)
319+
),
320+
321+
el("div").append(
322+
el("h4", t`When to Use Signals vs. Plain DOM`),
323+
el("ul").append(
324+
el("li").append(T`
325+
${el("strong", "Use signals for")}: Data that changes frequently, multiple elements that need to
326+
stay in sync, computed values dependent on other state
216327
`),
217328
el("li").append(T`
218-
${el("strong", "Use component functions:")}: Create reusable UI components as functions
329+
${el("strong", "Use plain DOM for")}: Static content, one-time DOM operations, simple toggling of
330+
elements, single-element updates
219331
`),
220332
el("li").append(T`
221-
${el("strong", "Create signal factories:")}: Extract reusable signal patterns into factory functions
333+
${el("strong", "Mixed approach")}: Start with plain DOM and events, then add signals only where
334+
needed for reactivity
222335
`),
223336
el("li").append(T`
224-
${el("strong", "Leverage scopes:")}: Use scope for component context and clean resource management
337+
${el("strong", "Consider derived signals")}: For complex transformations of data rather than manual
338+
updates
225339
`),
226340
el("li").append(T`
227-
${el("strong", "Event delegation:")}: Prefer component-level event handlers over many individual handlers
341+
${el("strong", "Use event delegation")}: For handling multiple similar interactions without
342+
individual signal bindings
228343
`)
229344
)
230345
),
@@ -233,19 +348,19 @@ export function page({ pkg, info }){
233348
el("h4", t`Performance Optimization`),
234349
el("ul").append(
235350
el("li").append(T`
236-
${el("strong", "Memoize list items:")}: Use ${el("code", "memo")} for items in frequently-updated lists
351+
${el("strong", "Memoize list items")}: Use ${el("code", "memo")} for items in frequently-updated lists
237352
`),
238353
el("li").append(T`
239-
${el("strong", "Avoid unnecessary signal updates:")}: Only update signals when values actually change
354+
${el("strong", "Avoid unnecessary signal updates")}: Only update signals when values actually change
240355
`),
241356
el("li").append(T`
242-
${el("strong", "Use AbortSignals:")}: Clean up resources when components are removed
357+
${el("strong", "Use AbortSignals")}: Clean up resources when components are removed
243358
`),
244359
el("li").append(T`
245-
${el("strong", "Prefer derived signals:")}: Use computed values instead of manual updates
360+
${el("strong", "Prefer derived signals")}: Use computed values instead of manual updates
246361
`),
247362
el("li").append(T`
248-
${el("strong", "Avoid memoizing fragments:")}: Never memoize DocumentFragments, only individual elements
363+
${el("strong", "Avoid memoizing fragments")}: Never memoize DocumentFragments, only individual elements
249364
`)
250365
),
251366
el("p").append(T`
@@ -263,7 +378,7 @@ export function page({ pkg, info }){
263378
el("dd", t`Use scope.signal or AbortSignals to handle resource cleanup when elements are removed`),
264379

265380
el("dt", t`Circular Signal Dependencies`),
266-
el("dd", t`Avoid signals that depend on each other in a circular way, which can cause infinite update loops`),
381+
el("dd", t`Avoid signals that depend on each other in a circular way, which can cause infinite update loops`),
267382

268383
el("dt", t`Memoizing with Unstable Keys`),
269384
el("dd", t`Always use stable, unique identifiers as memo keys, not array indices or objects`),
@@ -347,7 +462,7 @@ export function page({ pkg, info }){
347462

348463
el(h3, t`Contribution and Community`),
349464
el("p").append(T`
350-
dd<el> is an open-source project that welcomes contributions from the community:
465+
dd<el> is an open-source project that welcomes contributions from the community:
351466
`),
352467
el("ul").append(
353468
el("li").append(T`
@@ -367,16 +482,33 @@ export function page({ pkg, info }){
367482
el("div", { className: "callout" }).append(
368483
el("h4", t`Final Thoughts`),
369484
el("p").append(T`
370-
dd<el> provides a lightweight yet powerful approach to building modern web interfaces
485+
dd<el> provides a lightweight yet powerful approach to building modern web interfaces
371486
with minimal overhead and maximal flexibility. By embracing standard web technologies
372-
rather than abstracting them away, it offers a development experience that scales
487+
rather than abstracting them away, it offers a development experience that scales
373488
from simple interactive elements to complex applications while remaining close
374489
to what makes the web platform powerful.
375490
`),
376491
el("p").append(T`
377-
Whether you're building a small interactive component or a full-featured application,
378-
dd<el>'s combination of declarative syntax, targeted reactivity, and pragmatic design
379-
provides the tools you need without the complexity you don't.
492+
Whether you’re building a small interactive component or a full-featured application,
493+
dd<el>’s combination of declarative syntax, targeted reactivity, and pragmatic design
494+
provides the tools you need without the complexity you don’t.
495+
`)
496+
),
497+
498+
el(h3, t`Tools and Resources`),
499+
el("p").append(T`
500+
To help you get started with dd<el>, we provide several tools and resources:
501+
`),
502+
el("ul").append(
503+
el("li").append(T`
504+
${el("a", references.converter).append("HTML to dd<el> Converter")}: Easily convert existing HTML markup
505+
to dd<el> JavaScript code
506+
`),
507+
el("li").append(T`
508+
${el("a", references.examples).append("Examples Gallery")}: Browse real-world examples and code snippets
509+
`),
510+
el("li").append(T`
511+
${el("a", references.github).append("Documentation")}: Comprehensive guides and API reference
380512
`)
381513
),
382514
);

0 commit comments

Comments
 (0)