aberdeen 1.18.1 → 1.19.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (156) hide show
  1. package/README.md +9 -0
  2. package/dist/src/aberdeen.d.ts +29 -0
  3. package/{dist-docs/assets/aberdeen/aberdeen.js → dist/src/aberdeen.dev.js} +796 -21
  4. package/dist/src/aberdeen.dev.js.map +12 -0
  5. package/dist/src/aberdeen.js +79 -19
  6. package/dist/src/aberdeen.js.map +3 -3
  7. package/dist/src/devtools.d.ts +26 -0
  8. package/dist/tests/fakedom.js +20 -3
  9. package/dist/tests/fakedom.js.map +3 -3
  10. package/dist/tests/helpers.js +20 -3
  11. package/dist/tests/helpers.js.map +3 -3
  12. package/html-to-aberdeen +9 -5
  13. package/package.json +17 -10
  14. package/skill/A.md +127 -0
  15. package/skill/Dispatcher.md +51 -0
  16. package/skill/OPAQUE.md +15 -0
  17. package/skill/PromiseProxy.md +25 -0
  18. package/skill/Route.md +50 -0
  19. package/skill/SKILL.md +272 -156
  20. package/skill/applyCanon.md +20 -0
  21. package/skill/applyPrediction.md +15 -0
  22. package/skill/back.md +11 -0
  23. package/skill/clean.md +43 -0
  24. package/skill/clone.md +15 -0
  25. package/skill/copy.md +40 -0
  26. package/skill/count.md +32 -0
  27. package/skill/cssVars.md +15 -0
  28. package/skill/darkMode.md +26 -0
  29. package/skill/derive.md +56 -0
  30. package/skill/developer-tools.md +23 -0
  31. package/skill/disableCreateDestroy.md +11 -0
  32. package/skill/dump.md +37 -0
  33. package/skill/freeze.md +20 -0
  34. package/skill/full-example-multi-page-app.md +146 -0
  35. package/skill/go.md +25 -0
  36. package/skill/grow.md +13 -0
  37. package/skill/html-to-aberdeen.md +9 -0
  38. package/skill/insertCss.md +79 -0
  39. package/skill/insertGlobalCss.md +68 -0
  40. package/skill/interceptLinks.md +19 -0
  41. package/skill/invertString.md +32 -0
  42. package/skill/isEmpty.md +38 -0
  43. package/skill/map.md +16 -0
  44. package/skill/matchCurrent.md +27 -0
  45. package/skill/merge.md +27 -0
  46. package/skill/mount.md +48 -0
  47. package/skill/multiMap.md +15 -0
  48. package/skill/onEach.md +14 -0
  49. package/skill/partition.md +15 -0
  50. package/skill/peek.md +36 -0
  51. package/skill/persistScroll.md +13 -0
  52. package/skill/proxy.md +11 -0
  53. package/skill/push.md +13 -0
  54. package/skill/ref.md +39 -0
  55. package/skill/runQueue.md +34 -0
  56. package/skill/setErrorHandler.md +48 -0
  57. package/skill/setLog.md +9 -0
  58. package/skill/setSpacingCssVars.md +31 -0
  59. package/skill/shrink.md +13 -0
  60. package/skill/unmountAll.md +9 -0
  61. package/skill/unproxy.md +43 -0
  62. package/skill/up.md +13 -0
  63. package/src/aberdeen.ts +220 -82
  64. package/src/devtools.ts +685 -0
  65. package/dist-docs/.nojekyll +0 -1
  66. package/dist-docs/Tutorial/index.html +0 -305
  67. package/dist-docs/aberdeen/A/index.html +0 -115
  68. package/dist-docs/aberdeen/CUSTOM_DUMP/index.html +0 -7
  69. package/dist-docs/aberdeen/NO_COPY/index.html +0 -2
  70. package/dist-docs/aberdeen/OPAQUE/index.html +0 -12
  71. package/dist-docs/aberdeen/PromiseProxy/index.html +0 -8
  72. package/dist-docs/aberdeen/clean/index.html +0 -11
  73. package/dist-docs/aberdeen/clone/index.html +0 -5
  74. package/dist-docs/aberdeen/copy/index.html +0 -22
  75. package/dist-docs/aberdeen/count/index.html +0 -7
  76. package/dist-docs/aberdeen/cssVars/index.html +0 -11
  77. package/dist-docs/aberdeen/darkMode/index.html +0 -9
  78. package/dist-docs/aberdeen/default/index.html +0 -341
  79. package/dist-docs/aberdeen/derive/index.html +0 -18
  80. package/dist-docs/aberdeen/disableCreateDestroy/index.html +0 -6
  81. package/dist-docs/aberdeen/dump/index.html +0 -11
  82. package/dist-docs/aberdeen/index.html +0 -54
  83. package/dist-docs/aberdeen/insertCss/index.html +0 -30
  84. package/dist-docs/aberdeen/insertGlobalCss/index.html +0 -19
  85. package/dist-docs/aberdeen/invertString/index.html +0 -13
  86. package/dist-docs/aberdeen/isEmpty/index.html +0 -12
  87. package/dist-docs/aberdeen/map/index.html +0 -26
  88. package/dist-docs/aberdeen/merge/index.html +0 -11
  89. package/dist-docs/aberdeen/mount/index.html +0 -17
  90. package/dist-docs/aberdeen/multiMap/index.html +0 -28
  91. package/dist-docs/aberdeen/onEach/index.html +0 -19
  92. package/dist-docs/aberdeen/partition/index.html +0 -36
  93. package/dist-docs/aberdeen/peek/index.html +0 -40
  94. package/dist-docs/aberdeen/proxy/index.html +0 -35
  95. package/dist-docs/aberdeen/ref/index.html +0 -13
  96. package/dist-docs/aberdeen/runQueue/index.html +0 -13
  97. package/dist-docs/aberdeen/setErrorHandler/index.html +0 -16
  98. package/dist-docs/aberdeen/setSpacingCssVars/index.html +0 -8
  99. package/dist-docs/aberdeen/unmountAll/index.html +0 -5
  100. package/dist-docs/aberdeen/unproxy/index.html +0 -11
  101. package/dist-docs/assets/aberdeen/aberdeen.d.ts +0 -961
  102. package/dist-docs/assets/aberdeen/aberdeen.js.map +0 -11
  103. package/dist-docs/assets/aberdeen/dispatcher.d.ts +0 -57
  104. package/dist-docs/assets/aberdeen/dispatcher.js +0 -66
  105. package/dist-docs/assets/aberdeen/dispatcher.js.map +0 -10
  106. package/dist-docs/assets/aberdeen/helpers/reverseSortedSet.d.ts +0 -96
  107. package/dist-docs/assets/aberdeen/prediction.d.ts +0 -33
  108. package/dist-docs/assets/aberdeen/prediction.js +0 -112
  109. package/dist-docs/assets/aberdeen/prediction.js.map +0 -10
  110. package/dist-docs/assets/aberdeen/route.d.ts +0 -137
  111. package/dist-docs/assets/aberdeen/route.js +0 -287
  112. package/dist-docs/assets/aberdeen/route.js.map +0 -10
  113. package/dist-docs/assets/aberdeen/transitions.d.ts +0 -18
  114. package/dist-docs/assets/aberdeen/transitions.js +0 -47
  115. package/dist-docs/assets/aberdeen/transitions.js.map +0 -10
  116. package/dist-docs/assets/custom.js +0 -573
  117. package/dist-docs/assets/favicon.png +0 -0
  118. package/dist-docs/assets/hierarchy.js +0 -1
  119. package/dist-docs/assets/highlight.css +0 -134
  120. package/dist-docs/assets/icons.js +0 -18
  121. package/dist-docs/assets/icons.svg +0 -1
  122. package/dist-docs/assets/main.js +0 -60
  123. package/dist-docs/assets/navigation.js +0 -1
  124. package/dist-docs/assets/search.js +0 -1
  125. package/dist-docs/assets/style.css +0 -1640
  126. package/dist-docs/dispatcher/Dispatcher/index.html +0 -21
  127. package/dist-docs/dispatcher/MATCH_FAILED/index.html +0 -2
  128. package/dist-docs/dispatcher/MATCH_REST/index.html +0 -2
  129. package/dist-docs/dispatcher/index.html +0 -4
  130. package/dist-docs/hierarchy.html +0 -1
  131. package/dist-docs/index.html +0 -61
  132. package/dist-docs/media/CHANGELOG.md +0 -260
  133. package/dist-docs/modules.html +0 -1
  134. package/dist-docs/prediction/applyCanon/index.html +0 -13
  135. package/dist-docs/prediction/applyPrediction/index.html +0 -8
  136. package/dist-docs/prediction/index.html +0 -9
  137. package/dist-docs/route/Route/index.html +0 -23
  138. package/dist-docs/route/back/index.html +0 -4
  139. package/dist-docs/route/current/index.html +0 -2
  140. package/dist-docs/route/go/index.html +0 -14
  141. package/dist-docs/route/index.html +0 -15
  142. package/dist-docs/route/interceptLinks/index.html +0 -8
  143. package/dist-docs/route/matchCurrent/index.html +0 -10
  144. package/dist-docs/route/persistScroll/index.html +0 -6
  145. package/dist-docs/route/push/index.html +0 -6
  146. package/dist-docs/route/setLog/index.html +0 -3
  147. package/dist-docs/route/up/index.html +0 -5
  148. package/dist-docs/sitemap.xml +0 -239
  149. package/dist-docs/transitions/grow/index.html +0 -6
  150. package/dist-docs/transitions/index.html +0 -5
  151. package/dist-docs/transitions/shrink/index.html +0 -6
  152. package/skill/aberdeen.md +0 -4584
  153. package/skill/dispatcher.md +0 -129
  154. package/skill/prediction.md +0 -73
  155. package/skill/route.md +0 -322
  156. package/skill/transitions.md +0 -59
package/README.md CHANGED
@@ -19,6 +19,7 @@ Aberdeen wraps your state in ES6 `Proxy` objects for fine-grained property acces
19
19
  - SVG support
20
20
  - Helper functions for transforming reactive data (mapping, partitioning, filtering, etc)
21
21
  - Hide/unhide transition effects
22
+ - Developer tools
22
23
 
23
24
  ## Why *not* use Aberdeen?
24
25
 
@@ -178,6 +179,14 @@ mkdir -p .claude/skills
178
179
  ln -s ../../node_modules/aberdeen/skill .claude/skills/aberdeen
179
180
  ```
180
181
 
182
+ ## Developer tools
183
+
184
+ Aberdeen ships with an in-browser inspector for its reactive scope tree: see what (re)rendered, when, which proxy change triggered it, and the `file:line` in your code where each scope was created. Hold `Alt` and hover any element to jump to the scope that drew it.
185
+
186
+ Open it with **`Ctrl/Cmd+Alt+A`**, or by adding **`?abdev=1`** to the URL (which also captures the initial render). It lives in the development build of Aberdeen, selected automatically by the `development` export condition (e.g. by Vite's dev server), and is completely stripped from production bundles.
187
+
188
+ ![The Aberdeen developer tools inspecting an app](docs/devtools-screenshot.png)
189
+
181
190
  ## Changelog
182
191
 
183
192
  See [CHANGELOG.md](CHANGELOG.md) for a full history of changes.
package/dist/src/aberdeen.d.ts CHANGED
@@ -30,6 +30,24 @@
30
30
  * ```
31
31
  */
32
32
  export declare function runQueue(): void;
33
+ /**
34
+ * Pause processing of reactive updates until the returned *thaw* function is called.
35
+ *
36
+ * While frozen, changes to observed data still accumulate, but no re-renders run. Freezes
37
+ * stack: if there are multiple outstanding freezes, redraws resume only once the last one is
38
+ * thawed. This is useful to batch an async burst of changes into a single update pass, or to
39
+ * hold the UI steady (e.g. the dev tools use it for "freeze redraws").
40
+ *
41
+ * @returns A function that releases this freeze. Calling it more than once has no effect.
42
+ *
43
+ * @example
44
+ * ```typescript
45
+ * const thaw = A.freeze();
46
+ * // ...make many changes without intermediate redraws...
47
+ * thaw(); // redraws run now (if no other freezes remain)
48
+ * ```
49
+ */
50
+ export declare function freeze(): () => void;
33
51
  /**
34
52
  * Creates a new string that has the opposite sort order compared to the input string.
35
53
  *
@@ -449,6 +467,8 @@ export declare function disableCreateDestroy(): void;
449
467
  *
450
468
  * Also, when the value is a string starting with `$`, it is treated as a reference to a CSS variable, expanding to `var(--variableName)`. For numeric variable names (which can't be used directly as CSS custom property names), Aberdeen prefixes them with `m`, so `$3` expands to `var(--m3)`. This is primarily intended for use with {@link setSpacingCssVars}, which initializes spacing variables named `0` through `12` with an exponential spacing scale.
451
469
  *
470
+ * To *set* a CSS custom property inline on an element, use a `--name` or (symmetrically with the `$`-reference syntax above) a `$name` key. For example `A('div --primary:red')` and `A('div $primary:red')` both set `--primary` to `red`.
471
+ *
452
472
  * @returns The most inner DOM element that was created (not counting text nodes nor elements created by content functions), or the current element if no new element was created. You should normally not need to use the return value - use this function's DOM manipulation abilities instead. One valid use case is when integrating with non-Aberdeen code that requires a reference to a DOM element.
453
473
  *
454
474
  * @example Create Element
@@ -527,6 +547,10 @@ export declare function A(...args: any[]): undefined | Element;
527
547
  *
528
548
  * Supports the same CSS shortcuts as {@link A | A} and CSS variable references with `$` (e.g., `$primary`, `$3`).
529
549
  *
550
+ * CSS is inserted into the <head> in an order relative to other insert(Global)Css items that is consistent
551
+ * based on when the containing Aberdeen scope was first defined. This allows changing styles without changing
552
+ * order-based precedence.
553
+ *
530
554
  * @param style - A concise style string or a style object.
531
555
  * @returns The unique class name prefix used for scoping (e.g., `.AbdStl1`).
532
556
  * Use this prefix with {@link A | A} to apply the styles.
@@ -586,6 +610,10 @@ export declare function insertCss(style: string | object): string;
586
610
  *
587
611
  * @param style - Object with selectors as keys and concise CSS strings as values.
588
612
  *
613
+ * CSS is inserted into the <head> in an order relative to other insert(Global)Css items that is consistent
614
+ * based on when the containing Aberdeen scope was first defined. This allows changing styles without changing
615
+ * order-based precedence.
616
+ *
589
617
  * @example Global Reset and Base Styles
590
618
  * ```typescript
591
619
  * // Set up global styles using CSS shortcuts
@@ -937,6 +965,7 @@ declare const _default: typeof A & {
937
965
  /** {@inheritDoc derive} */ derive: typeof derive;
938
966
  /** {@inheritDoc disableCreateDestroy} */ disableCreateDestroy: typeof disableCreateDestroy;
939
967
  /** {@inheritDoc dump} */ dump: typeof dump;
968
+ /** {@inheritDoc freeze} */ freeze: typeof freeze;
940
969
  /** {@inheritDoc insertCss} */ insertCss: typeof insertCss;
941
970
  /** {@inheritDoc insertGlobalCss} */ insertGlobalCss: typeof insertGlobalCss;
942
971
  /** {@inheritDoc invertString} */ invertString: typeof invertString;