From b3356afa88cbbce56f4c813480f2bfe55dc6da10 Mon Sep 17 00:00:00 2001 From: Jan Andrle Date: Thu, 6 Mar 2025 14:33:47 +0100 Subject: [PATCH] :abc: improvemens --- docs/components/code.html.js | 2 +- .../examples/debugging/consoleLog.js | 1 + docs/global.css.js | 64 ++++++++++--------- docs/layout/head.html.js | 17 +++-- docs/p03-events.html.js | 4 +- docs/p07-debugging.html.js | 62 ++++++++++-------- 6 files changed, 84 insertions(+), 66 deletions(-) diff --git a/docs/components/code.html.js b/docs/components/code.html.js index d736a5d..9a697d1 100644 --- a/docs/components/code.html.js +++ b/docs/components/code.html.js @@ -35,7 +35,7 @@ ${host} { line-height: 1.5; position: relative; margin-block: 1rem; - width: 100%; + max-width: 100%; } /* Light mode overrides to match GitHub-like theme */ diff --git a/docs/components/examples/debugging/consoleLog.js b/docs/components/examples/debugging/consoleLog.js index 5484b24..216e0b9 100644 --- a/docs/components/examples/debugging/consoleLog.js +++ b/docs/components/examples/debugging/consoleLog.js @@ -5,6 +5,7 @@ const greeting = S(() => { // log derived signals const log = "Hello, " + name.get(); console.log(log); + console.log(name.valueOf()); return log; }); diff --git a/docs/global.css.js b/docs/global.css.js index 78bb203..6371f2e 100644 --- a/docs/global.css.js +++ b/docs/global.css.js @@ -121,27 +121,11 @@ html { transform: translateX(0); } -body { - font-family: var(--font-main); - background-color: var(--bg); - color: var(--text); - line-height: 1.6; - font-size: 1.05rem; - display: grid; - grid-template-columns: 100%; - grid-template-areas: - "header" - "sidebar" - "content"; - min-height: 100vh; - margin: 0; -} - +/* Typography */ ::selection { background-color: var(--selection); } -/* Typography */ h1, h2, h3, h4, h5, h6 { margin-bottom: 1rem; margin-top: 2rem; @@ -194,6 +178,7 @@ code { background-color: var(--code-bg); color: var(--code-text); padding: 0.2em 0.4em; + word-wrap: break-word; } pre { @@ -210,6 +195,24 @@ pre code { } /* Layout */ +body { + font-family: var(--font-main); + background-color: var(--bg); + color: var(--text); + line-height: 1.6; + font-size: 1.05rem; + display: grid; + grid-template-columns: 100%; + grid-template-areas: + "header" + "sidebar" + "content"; + min-height: 100vh; + margin: 0; + --_gap: .75em; + gap: var(--_gap); + padding: var(--_gap); +} @media (min-width: 768px) { body { grid-template-rows: var(--header-height) 1fr; @@ -219,11 +222,8 @@ pre code { "sidebar content"; } } - -/* Main content */ body > main { grid-area: content; - padding-block: 2rem; max-width: 100%; overflow-x: hidden; display: grid; @@ -232,7 +232,6 @@ body > main { [main-start] min(var(--body-max-width), 90%) [main-end] 1fr [full-main-end]; } - body > main > *, body > main slot > * { width: 100%; max-width: 100%; @@ -270,11 +269,15 @@ body > main h3, body > main h4 { grid-column: full-main; width: calc(100% - .75em); } -.illustration:not(:has( .comparison)) pre { - background: none; - border-style: dashed !important; - width: fit-content; - padding: 1em 2em; +.illustration:not(:has( .comparison)){ + grid-column: main; + + pre { + background: none; + border-style: dashed !important; + width: fit-content; + padding: 1em 2em; + } } .comparison { @@ -415,18 +418,21 @@ body > main h3, body > main h4 { @media (min-width: 768px) { .tabs { display: flex; - flex-wrap: wrap; + flex-flow: row wrap; } .tab { flex: 1; min-width: 50%; border-top: none; - border-left: 1px solid var(--border); + display: flex; + flex-flow: column nowrap; + align-items: center; + text-align: justify; } .tab:first-child { - border-left: none; + border-inline-end: 1px solid var(--border); } } diff --git a/docs/layout/head.html.js b/docs/layout/head.html.js index fc24808..6eb9a3c 100644 --- a/docs/layout/head.html.js +++ b/docs/layout/head.html.js @@ -14,9 +14,7 @@ ${host} { background-color: var(--primary); color: white; box-shadow: var(--shadow); - min-height: calc(var(--header-height) - 1em); - --_m: .75em; - margin: var(--_m) var(--_m) 0 var(--_m); + height: fit-content; border-radius: var(--border-radius); } @@ -60,8 +58,9 @@ ${host_nav} .github-link { ${host_nav} { grid-area: sidebar; background-color: var(--bg-sidebar); - border-right: 1px solid var(--border); - padding: 1.5rem 1rem; + border: 1px solid var(--border); + border-radius: var(--border-radius); + padding: 1rem; overflow-y: auto; display: flex; flex-direction: column; @@ -97,7 +96,13 @@ ${host_nav} a .nav-number { color: rgb(from currentColor r g b / .75); } -/* Mobile navigation */ +@media (min-width: 768px) { + ${host_nav} { + height: fit-content; + position: sticky; + top: .5rem; + } +} @media (max-width: 767px) { ${host_nav} { padding: 0.75rem; diff --git a/docs/p03-events.html.js b/docs/p03-events.html.js index 40fa67b..5de5d53 100644 --- a/docs/p03-events.html.js +++ b/docs/p03-events.html.js @@ -82,11 +82,11 @@ export function page({ pkg, info }){ ) ) ), - el(example, { src: fileURL("./components/examples/events/compare.js"), page_id }), el("p").append(...T` The main benefit of DDE's approach is that it works as an Addon, making it easy to integrate directly into element declarations. `), + el(example, { src: fileURL("./components/examples/events/compare.js"), page_id }), el(h3, t`Removing Event Listeners`), el("div", { className: "note" }).append( @@ -200,12 +200,12 @@ export function page({ pkg, info }){ ), el(h3, t`Dispatching Custom Events`), - el(example, { src: fileURL("./components/examples/events/compareDispatch.js"), page_id }), el("p").append(...T` This makes it easy to implement component communication through events, following standard web platform patterns. The curried approach allows for easy reuse of event dispatchers throughout your application. `), + el(example, { src: fileURL("./components/examples/events/compareDispatch.js"), page_id }), el(h3, t`Best Practices`), el("ol").append( diff --git a/docs/p07-debugging.html.js b/docs/p07-debugging.html.js index e07ed7a..c9b442e 100644 --- a/docs/p07-debugging.html.js +++ b/docs/p07-debugging.html.js @@ -32,7 +32,12 @@ export function page({ pkg, info }){ el("p").append(...T` The simplest way to debug a signal is to log its current value by calling the get method: `), - el(code, { content: "const signal = S(0);\nconsole.log('Current value:', signal.get());", page_id }), + el(code, { content: ` +const signal = S(0); +console.log('Current value:', signal.get()); +// without triggering updates +console.log('Current value:', signal.valueOf()); + `, page_id }), el("p").append(...T` You can also monitor signal changes by adding a listener: `), @@ -43,7 +48,7 @@ export function page({ pkg, info }){ el("h4", t`Debugging derived signals`), el("p").append(...T` - With derived signals (created with S(() => computation)), debugging is a bit more complex + With derived signals (created with ${el("code", "S(() => computation))")}), debugging is a bit more complex because the value depends on other signals. To understand why a derived signal isn't updating correctly: `), el("ol").append( @@ -117,30 +122,15 @@ export function page({ pkg, info }){ el("p").append(...T` Elements created with the deka-dom-el library have special properties to aid in debugging: `), + el("p").append(...T` + ${el("code", ".__dde_reactive")} - An array property on DOM elements that tracks signal-to-element + relationships. This allows you to quickly identify which elements are reactive and what signals they're + bound to. Each entry in the array contains: + `), el("ul").append( - el("li").append(...T` - ${el("code", "__dde_reactive")} - An array property on DOM elements that tracks signal-to-element relationships. - This allows you to quickly identify which elements are reactive and what signals they're bound to. - Each entry in the array contains: - `), - el("ul").append( - el("li", "A pair of signal and listener function: [signal, listener]"), - el("li", "Additional context information about the element or attribute"), - el("li", "Automatically managed by signal.el(), signal.observedAttributes(), and processReactiveAttribute()") - ), - el("li").append(...T` - ${el("code", "__dde_signal")} - A Symbol property used to identify and store the internal state of signal objects. - It contains the following information: - `), - el("ul").append( - el("li", "value: The current value of the signal"), - el("li", "listeners: A Set of functions called when the signal value changes"), - el("li", "actions: Custom actions that can be performed on the signal"), - el("li", "onclear: Functions to run when the signal is cleared"), - el("li", "host: Reference to the host element or scope"), - el("li", "defined: Stack trace information for debugging"), - el("li", "readonly: Boolean flag indicating if the signal is read-only") - ), + el("li", "A pair of signal and listener function: [signal, listener]"), + el("li", "Additional context information about the element or attribute"), + el("li", "Automatically managed by signal.el(), signal.observedAttributes(), and processReactiveAttribute()") ), el("p").append(...T` These properties make it easier to understand the reactive structure of your application when inspecting elements. @@ -149,8 +139,24 @@ export function page({ pkg, info }){ el("h4", t`Examining signal connections`), el("p").append(...T` - You can inspect signal relationships and bindings in the DevTools console using ${el("code", "$0.__dde_reactive")}. - In the console you will see a list of ${el("code", "[ [ signal, listener ], element, property ]")}, where: + ${el("code", ".__dde_signal")} - A Symbol property used to identify and store the internal state of + signal objects. It contains the following information: + `), + el("ul").append( + el("li", "listeners: A Set of functions called when the signal value changes"), + el("li", "actions: Custom actions that can be performed on the signal"), + el("li", "onclear: Functions to run when the signal is cleared"), + el("li", "host: Reference to the host element/scope"), + el("li", "defined: Stack trace information for debugging"), + el("li", "readonly: Boolean flag indicating if the signal is read-only") + ), + el("p").append(...T` + …to determine the current value of the signal, call ${el("code", "signal.valueOf()")}. + `), + el("p").append(...T` + You can inspect (host) element relationships and bindings with signals in the DevTools console using + ${el("code", "$0.__dde_reactive")} (for currently selected element). In the console you will see a list of + ${el("code", "[ [ signal, listener ], element, property ]")}, where: `), el("ul").append( el("li", "signal — the signal triggering the changes"), @@ -160,7 +166,7 @@ export function page({ pkg, info }){ ), el("p").append(...T` …the structure of \`__dde_reactive\` utilizes the browser's behavior of packing the first field, - so you can see the element and property that changes in the console right away + so you can see the element and property that changes in the console right away. `), el("h4", t`Debugging with breakpoints`),