explico 0.5.0 → 0.7.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 (88) hide show
  1. package/CHANGELOG.md +295 -7
  2. package/README.md +16 -2
  3. package/dist/compiler/astro.d.ts +13 -2
  4. package/dist/compiler/astro.js +39 -0
  5. package/dist/compiler/cli.d.ts +22 -3
  6. package/dist/compiler/cli.js +71 -10
  7. package/dist/compiler/course-config.d.ts +31 -1
  8. package/dist/compiler/course-config.js +7 -0
  9. package/dist/compiler/exports/standalone-html.js +13 -0
  10. package/dist/compiler/logging.d.ts +109 -0
  11. package/dist/compiler/logging.js +107 -0
  12. package/dist/compiler/manifest.d.ts +16 -4
  13. package/dist/compiler/manifest.js +7 -3
  14. package/dist/reference/base-abbreviations.mjs +8 -2
  15. package/dist/reference/consistency.d.ts +8 -10
  16. package/dist/reference/consistency.js +3 -47
  17. package/dist/reference/delimiter-size.d.ts +39 -0
  18. package/dist/reference/delimiter-size.js +177 -0
  19. package/dist/reference/diagrams-validate.d.ts +1 -1
  20. package/dist/reference/equations-validate.d.ts +2 -2
  21. package/dist/reference/equations-validate.js +1 -1
  22. package/dist/reference/figures-validate.d.ts +1 -1
  23. package/dist/reference/gate-heading-length.d.ts +12 -0
  24. package/dist/reference/gate-heading-length.js +79 -0
  25. package/dist/reference/gate-math.d.ts +8 -2
  26. package/dist/reference/gate-math.js +30 -7
  27. package/dist/reference/keyed-float-validate.d.ts +2 -2
  28. package/dist/reference/keyed-float-validate.js +1 -1
  29. package/dist/reference/math-glyphs.d.mts +12 -0
  30. package/dist/reference/math-glyphs.mjs +183 -42
  31. package/dist/reference/references.js +2 -1
  32. package/dist/reference/registry.js +1 -1
  33. package/dist/reference/rehype-base-links.d.mts +23 -0
  34. package/dist/reference/rehype-base-links.mjs +40 -0
  35. package/dist/reference/remark-abbreviations.mjs +10 -12
  36. package/dist/reference/remark-citation.d.mts +5 -1
  37. package/dist/reference/remark-citation.mjs +0 -0
  38. package/dist/reference/render-lab-math.d.ts +18 -1
  39. package/dist/reference/render-lab-math.js +10 -3
  40. package/dist/reference/tables-validate.d.ts +1 -1
  41. package/dist/reference/types.d.ts +1 -1
  42. package/docs/VERSIONING.md +24 -4
  43. package/docs/authoring/README.md +14 -2
  44. package/docs/authoring/agents.md +7 -3
  45. package/docs/authoring/components.md +4 -1
  46. package/docs/authoring/migrating.md +477 -8
  47. package/docs/authoring/notation.md +194 -7
  48. package/docs/authoring/prose.md +64 -0
  49. package/docs/authoring/structure-rules.md +69 -0
  50. package/docs/authoring/visualizations.md +2 -2
  51. package/package.json +1 -1
  52. package/src/compiler/astro.ts +89 -0
  53. package/src/compiler/cli.ts +144 -12
  54. package/src/compiler/course-config.ts +40 -0
  55. package/src/compiler/exports/standalone-html.ts +15 -0
  56. package/src/compiler/logging.ts +248 -0
  57. package/src/compiler/manifest.ts +20 -3
  58. package/src/components/diagram/Diagram.astro +0 -55
  59. package/src/components/memo/Memo.astro +2 -5
  60. package/src/components/memo/ShortNote.astro +2 -5
  61. package/src/components/notation/NotationFormula.astro +199 -10
  62. package/src/components/notation/NotationGlossary.astro +89 -58
  63. package/src/components/notation/NotationLayer.astro +238 -156
  64. package/src/components/scroll-animation.ts +160 -0
  65. package/src/components/starlight/AnchorScrollEnhancer.astro +102 -0
  66. package/src/components/starlight/HeadingAnchorEnhancer.astro +2 -4
  67. package/src/components/starlight/KeyedFloatEnhancer.astro +17 -16
  68. package/src/components/starlight/LessonFooter.astro +5 -1
  69. package/src/content-config.ts +16 -1
  70. package/src/reference/base-abbreviations.mjs +8 -2
  71. package/src/reference/consistency.ts +10 -66
  72. package/src/reference/delimiter-size.ts +301 -0
  73. package/src/reference/diagrams-validate.ts +1 -1
  74. package/src/reference/equations-validate.ts +3 -3
  75. package/src/reference/figures-validate.ts +1 -1
  76. package/src/reference/gate-heading-length.ts +131 -0
  77. package/src/reference/gate-math.ts +48 -8
  78. package/src/reference/keyed-float-validate.ts +3 -3
  79. package/src/reference/math-glyphs.mjs +183 -42
  80. package/src/reference/references.ts +2 -1
  81. package/src/reference/registry.ts +1 -1
  82. package/src/reference/rehype-base-links.mjs +40 -0
  83. package/src/reference/remark-abbreviations.mjs +10 -12
  84. package/src/reference/remark-citation.mjs +0 -0
  85. package/src/reference/render-lab-math.ts +24 -1
  86. package/src/reference/tables-validate.ts +1 -1
  87. package/src/reference/types.ts +1 -1
  88. package/src/styles/global.css +120 -15
@@ -891,15 +891,30 @@ body {
891
891
 
892
892
  /* Native browser tooltips: `<span title="…">` in Markdown content. A dotted
893
893
  underline and hover highlight — same visual treatment as abbreviation terms
894
- (N14), distinguishing them from plain text and signalling a hover event. */
895
- .sl-markdown-content span[title] {
894
+ (N14), distinguishing them from plain text and signalling a hover event.
895
+ Excludes anything inside — or, for `.inline-equation`, that is — a rendered
896
+ equation: a `title` there is the equation's own dynamic "Copy LaTeX" hint
897
+ (`KeyedFloatEnhancer.astro`, `NotationLayer.astro`), which needs that
898
+ gesture's own `copy`/`help` cursor language below, not this feature's
899
+ term-tooltip styling — `[title]` on a leaf glyph would otherwise win that
900
+ cursor over the equation's inherited one, since a rule matching the
901
+ element itself always beats one only inherited from an ancestor. This has
902
+ to name the equation's own containers (`.keyed-equation`,
903
+ `.inline-equation`, `[data-notation-formula]`), not just `.katex-html`: a
904
+ *display* equation's KaTeX output is wrapped in an outer `.katex-display`
905
+ span first, which sits outside `.katex-html` and is exactly what a reader
906
+ hovers in the gutter between the equation and its number. */
907
+ .sl-markdown-content
908
+ span[title]:not(.keyed-equation *, .inline-equation, .inline-equation *, [data-notation-formula] *) {
896
909
  text-decoration: underline dotted;
897
910
  text-underline-offset: 0.2em;
898
911
  cursor: help;
899
912
  }
900
913
 
901
- .sl-markdown-content span[title]:hover,
902
- .sl-markdown-content span[title]:focus-visible {
914
+ .sl-markdown-content
915
+ span[title]:not(.keyed-equation *, .inline-equation, .inline-equation *, [data-notation-formula] *):hover,
916
+ .sl-markdown-content
917
+ span[title]:not(.keyed-equation *, .inline-equation, .inline-equation *, [data-notation-formula] *):focus-visible {
903
918
  background: var(--sl-color-accent-low);
904
919
  color: var(--sl-color-text-accent);
905
920
  }
@@ -1013,21 +1028,29 @@ body {
1013
1028
  }
1014
1029
 
1015
1030
  /* The click-to-copy gesture (`KeyedFloatEnhancer.astro`) works on any part of
1016
- the equation that isn't a symbol with its own notation card — signal that
1017
- with a "copy" cursor there, while an explained symbol keeps its existing
1018
- "help" cursor (`NotationLayer.astro`). The second rule must out-specificity
1019
- the first regardless of which stylesheet loads later, so it repeats the
1020
- `.katex-html` step rather than relying on cascade order between files. */
1021
- .sl-markdown-content .keyed-equation .katex-html,
1022
- .sl-markdown-content .inline-equation .katex-html {
1031
+ the box — including the reserved gutter between the equation and its
1032
+ number/button, not just the rendered `.katex-html` — that isn't a symbol
1033
+ with its own notation card or the number link itself: signal that with a
1034
+ "copy" cursor there, inherited from the whole container rather than only
1035
+ `.katex-html`, while an explained symbol keeps its existing "help" cursor
1036
+ (`NotationLayer.astro`) and the number link its own `pointer`. The second
1037
+ rule must out-specificity the first regardless of which stylesheet loads
1038
+ later, so it repeats the container step rather than relying on cascade
1039
+ order between files. */
1040
+ .sl-markdown-content .keyed-equation,
1041
+ .sl-markdown-content .inline-equation {
1023
1042
  cursor: copy;
1024
1043
  }
1025
1044
 
1026
- .sl-markdown-content .keyed-equation .katex-html [data-notation-key],
1027
- .sl-markdown-content .inline-equation .katex-html [data-notation-key] {
1045
+ .sl-markdown-content .keyed-equation [data-notation-key],
1046
+ .sl-markdown-content .inline-equation [data-notation-key] {
1028
1047
  cursor: help;
1029
1048
  }
1030
1049
 
1050
+ .sl-markdown-content a.keyed-equation__number {
1051
+ cursor: pointer;
1052
+ }
1053
+
1031
1054
  /* Hovering specifically an unexplained part (not a notation symbol) of a
1032
1055
  display equation highlights its copy button, so a reader can tell what
1033
1056
  clicking there will do before they click. `:has()` is well-supported by
@@ -1040,6 +1063,32 @@ body {
1040
1063
  color: var(--sl-color-text-accent);
1041
1064
  }
1042
1065
 
1066
+ /* Hovering the equation itself (anywhere along its line, not just its copy
1067
+ button) highlights the whole box — the same `accent-low` background + ring
1068
+ every other interactive notation surface uses (`[data-notation-key]:hover`
1069
+ below, a glossary formula's own equivalent in `NotationFormula.astro`), so
1070
+ a reader can tell the equation, not just its controls corner, is what
1071
+ they're about to act on. Suppressed while hovering an explained symbol,
1072
+ which already has its own distinct highlight and a different action. */
1073
+ .sl-markdown-content
1074
+ .keyed-equation:hover:not(:has([data-notation-key]:hover)),
1075
+ .sl-markdown-content
1076
+ .inline-equation:hover:not(:has([data-notation-key]:hover)) {
1077
+ background: var(--sl-color-accent-low);
1078
+ box-shadow: 0 0 0 0.12em var(--sl-color-accent-low);
1079
+ }
1080
+
1081
+ @media (forced-colors: active) {
1082
+ .sl-markdown-content
1083
+ .keyed-equation:hover:not(:has([data-notation-key]:hover)),
1084
+ .sl-markdown-content
1085
+ .inline-equation:hover:not(:has([data-notation-key]:hover)) {
1086
+ outline: 2px solid Highlight;
1087
+ background: none;
1088
+ box-shadow: none;
1089
+ }
1090
+ }
1091
+
1043
1092
  /* `data-copied` is set briefly by the click handler in `KeyedFloatEnhancer.astro`,
1044
1093
  the same "flash a tooltip, then remove the attribute" pattern as the
1045
1094
  glossary's copy-link button (`NotationGlossary.astro`) and the notation
@@ -1068,9 +1117,12 @@ body {
1068
1117
  here would break the reading line, which is the whole reason this exists
1069
1118
  instead of just reusing `.keyed-equation__copy`. `position: relative` only
1070
1119
  so its own "Copied!" flash (the click handler has no button to flash
1071
- instead) has something to anchor to. */
1120
+ instead) has something to anchor to; `border-radius` matches the hover
1121
+ highlight above and the `[data-notation-key]` glyph highlight it can
1122
+ contain. */
1072
1123
  .sl-markdown-content .inline-equation {
1073
1124
  position: relative;
1125
+ border-radius: 0.16em;
1074
1126
  }
1075
1127
 
1076
1128
  .sl-markdown-content .inline-equation[data-copied]::after {
@@ -1103,6 +1155,59 @@ body {
1103
1155
  }
1104
1156
  }
1105
1157
 
1158
+ /* The same "click anywhere in this box to copy its LaTeX" gesture as
1159
+ `.keyed-equation`/`.inline-equation` above, generalized to any element
1160
+ marked `[data-notation-formula]` regardless of which component rendered
1161
+ it: a glossary entry's own formula and the notation popup's cloned copy
1162
+ (`NotationFormula.astro`, `NotationLayer.astro`), or a lab's live
1163
+ interactive equation (`render-lab-math.ts`, e.g.
1164
+ `ProjectileRangeExplorer.tsx`). One canonical implementation here, instead
1165
+ of duplicating it in every producer's own scoped styles, is what keeps
1166
+ every current and future one consistent for free — the click handling
1167
+ that sets `data-copied` (`NotationLayer.astro`) and the exclusion from the
1168
+ native-tooltip styling above both already key off this same attribute. */
1169
+ [data-notation-formula] {
1170
+ position: relative;
1171
+ border-radius: 0.3rem;
1172
+ cursor: copy;
1173
+ }
1174
+
1175
+ [data-notation-formula] [data-notation-key] {
1176
+ cursor: help;
1177
+ }
1178
+
1179
+ [data-notation-formula]:hover:not(:has([data-notation-key]:hover)) {
1180
+ background: var(--sl-color-accent-low);
1181
+ box-shadow: 0 0 0 0.12em var(--sl-color-accent-low);
1182
+ }
1183
+
1184
+ @media (forced-colors: active) {
1185
+ [data-notation-formula]:hover:not(:has([data-notation-key]:hover)) {
1186
+ outline: 2px solid Highlight;
1187
+ background: none;
1188
+ box-shadow: none;
1189
+ }
1190
+ }
1191
+
1192
+ /* Only fires when there's no dedicated copy button to flash instead — a
1193
+ glossary entry's numbered formula has one
1194
+ (`.notation-formula-copy[data-copied]` in `NotationFormula.astro`'s own
1195
+ styles), and the click handler only ever sets `data-copied` directly on
1196
+ this element when no such button exists, so the two never double up. */
1197
+ [data-notation-formula][data-copied]::after {
1198
+ content: 'Copied!';
1199
+ position: absolute;
1200
+ inset-block-end: calc(100% + 0.3rem);
1201
+ inset-inline-start: 0;
1202
+ padding: 0.15rem 0.45rem;
1203
+ border-radius: 0.35rem;
1204
+ background: var(--sl-color-accent-low);
1205
+ color: var(--sl-color-text-accent);
1206
+ font-size: var(--sl-text-xs);
1207
+ white-space: nowrap;
1208
+ pointer-events: none;
1209
+ }
1210
+
1106
1211
  /* Once a reader has actually arrived at (or clicked through to) an equation —
1107
1212
  a deep-link on load, an in-page `[[eq:key]]` navigation, or pinning its
1108
1213
  preview card (`FloatRefLayer.astro`) — its number stays fully visible
@@ -1813,7 +1918,7 @@ body {
1813
1918
  .assessment-actions,
1814
1919
  .assessment-chevron,
1815
1920
  .assessment-feedback.is-idle,
1816
- .notation-pin,
1921
+ .notation-list-anchor,
1817
1922
  .notation-enhancement-help,
1818
1923
  .lab-controls {
1819
1924
  display: none !important;