@kairotic/app 0.0.0-stage → 0.2.2

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 (96) hide show
  1. package/README.md +9 -2
  2. package/index.html +1101 -0
  3. package/kairotic/api.cljs +362 -0
  4. package/kairotic/assistant.cljs +505 -0
  5. package/kairotic/backends/gun-backend.js +371 -0
  6. package/kairotic/canvas.cljs +751 -0
  7. package/kairotic/code.cljs +108 -0
  8. package/kairotic/components.cljs +838 -0
  9. package/kairotic/core.cljs +96 -0
  10. package/kairotic/corefns.cljs +473 -0
  11. package/kairotic/docs.mjs +2 -0
  12. package/kairotic/engine.cljs +482 -0
  13. package/kairotic/examples.mjs +96 -0
  14. package/kairotic/faust.cljs +225 -0
  15. package/kairotic/help.cljs +1036 -0
  16. package/kairotic/hiccup.cljs +566 -0
  17. package/kairotic/input.cljs +271 -0
  18. package/kairotic/kfile.mjs +138 -0
  19. package/kairotic/library.cljs +214 -0
  20. package/kairotic/links.cljs +41 -0
  21. package/kairotic/mt.cljs +1604 -0
  22. package/kairotic/mtboxes.cljs +276 -0
  23. package/kairotic/packages/analysis.mjs +64 -0
  24. package/kairotic/packages/controls.mjs +28 -0
  25. package/kairotic/packages/data.mjs +22 -0
  26. package/kairotic/packages/faust-units/cmaes.mjs +82 -0
  27. package/kairotic/packages/faust-units/graph.mjs +212 -0
  28. package/kairotic/packages/faust-units/listen.mjs +125 -0
  29. package/kairotic/packages/faust-units/notation.mjs +139 -0
  30. package/kairotic/packages/faust-units/parse.mjs +439 -0
  31. package/kairotic/packages/faust-units/recipe.mjs +195 -0
  32. package/kairotic/packages/faust-units/render.mjs +69 -0
  33. package/kairotic/packages/faust-units/units.mjs +130 -0
  34. package/kairotic/packages/faust-units/view.mjs +353 -0
  35. package/kairotic/packages/faust-units.mjs +9 -0
  36. package/kairotic/packages/io.mjs +58 -0
  37. package/kairotic/packages/net.mjs +28 -0
  38. package/kairotic/packages/patterns.mjs +34 -0
  39. package/kairotic/packages/spatial.mjs +22 -0
  40. package/kairotic/packages/spectral/shift.mjs +169 -0
  41. package/kairotic/packages/spectral.mjs +16 -0
  42. package/kairotic/packages/synth.mjs +28 -0
  43. package/kairotic/packages/theory/counterpoint.mjs +798 -0
  44. package/kairotic/packages/theory/mirror.mjs +221 -0
  45. package/kairotic/packages/theory.mjs +46 -0
  46. package/kairotic/patterns.cljs +538 -0
  47. package/kairotic/presets.cljs +227 -0
  48. package/kairotic/quantize.cljs +782 -0
  49. package/kairotic/record.cljs +169 -0
  50. package/kairotic/release.cljs +90 -0
  51. package/kairotic/ring.cljs +129 -0
  52. package/kairotic/ringaudio.cljs +232 -0
  53. package/kairotic/ringcore.mjs +270 -0
  54. package/kairotic/score.cljs +176 -0
  55. package/kairotic/shapes.cljs +283 -0
  56. package/kairotic/signal.cljs +327 -0
  57. package/kairotic/sounds.cljs +565 -0
  58. package/kairotic/sounds.mjs +108 -0
  59. package/kairotic/span.cljs +129 -0
  60. package/kairotic/spell.cljs +281 -0
  61. package/kairotic/structure.cljs +145 -0
  62. package/kairotic/talk.cljs +115 -0
  63. package/kairotic/tempo.cljs +226 -0
  64. package/kairotic/treecanvas.cljs +299 -0
  65. package/kairotic/tutorials.mjs +1283 -0
  66. package/kairotic/vendor/codemirror.mjs +23 -0
  67. package/package.json +23 -4
  68. package/page/00-work.cljs +862 -0
  69. package/page/01-commands.cljs +1219 -0
  70. package/page/02-patch-view.cljs +1051 -0
  71. package/page/03-history-view.cljs +481 -0
  72. package/page/04-panels.cljs +448 -0
  73. package/page/05-gestures.cljs +1247 -0
  74. package/page/06-connection.cljs +219 -0
  75. package/page/07-claude.cljs +430 -0
  76. package/page/08-sessions.cljs +423 -0
  77. package/page/09-learn.cljs +602 -0
  78. package/page/10-embed.cljs +469 -0
  79. package/page/11-startup.cljs +61 -0
  80. package/page/12-feedback.cljs +172 -0
  81. package/page/13-perform.cljs +325 -0
  82. package/page/14-editor.cljs +656 -0
  83. package/page/15-presets.cljs +230 -0
  84. package/page/16-release.cljs +242 -0
  85. package/page/17-sounds.cljs +147 -0
  86. package/page/18-lines.cljs +594 -0
  87. package/page/19-files.cljs +247 -0
  88. package/page/19-html.cljs +152 -0
  89. package/page/20-talk.cljs +527 -0
  90. package/page/21-net.cljs +110 -0
  91. package/page/22-learn.cljs +303 -0
  92. package/page/23-ids.cljs +233 -0
  93. package/page/24-clipboard.cljs +136 -0
  94. package/page/25-tidy.cljs +74 -0
  95. package/page/26-probes.cljs +111 -0
  96. package/sources.mjs +2 -0
@@ -0,0 +1,602 @@
1
+ ;; SPDX-License-Identifier: MPL-2.0
2
+ ;; Kairotic · the page, part 10 of 12: learn
3
+ ;; The page's ClojureScript, in the order it is evaluated (app/index.html lists the files).
4
+
5
+ (in-ns 'user)
6
+
7
+ ;; ───────────────────────── learning: help and lessons ─────────────────────────
8
+ ;; The Help tab shows what each class does, port by port (its :help, or kairotic.help), with a help
9
+ ;; patch. A lesson (a tutorial, or a help patch) opens as a local work built step by step: each step
10
+ ;; leaves a point in the history, the lesson bar shows the note of the step you are at, ◀ ▶ travel
11
+ ;; between them, and changing something at any step simply starts a branch of your own.
12
+
13
+ (defonce lang (atom (let [saved (try (.getItem js/localStorage "kairotic.lang") (catch :default _ nil))]
14
+ (cond (#{"es" "en"} saved) (keyword saved)
15
+ (str/starts-with? (str (.-language js/navigator)) "es") :es
16
+ :else :en))))
17
+
18
+ (defn tr "A text in the chosen language (or the other one)." [m]
19
+ (cond (string? m) m
20
+ (map? m) (or (not-empty (get m @lang)) (not-empty (get m :en)) (not-empty (get m :es)) "")
21
+ :else ""))
22
+
23
+ (defn es? [] (= @lang :es))
24
+
25
+ (defn rich
26
+ "Note text to HTML: paragraphs (blank lines), **bold**, `code` (a click puts it in the REPL)."
27
+ [t]
28
+ (->> (str/split (str t) #"\n\s*\n")
29
+ (remove str/blank?)
30
+ (map (fn [para]
31
+ (str "<p>"
32
+ (-> (esc (str/trim para))
33
+ (str/replace #"\*\*([^*]+)\*\*" "<b>$1</b>")
34
+ (str/replace #"`([^`]+)`"
35
+ (fn [[_ c]] (str "<code class=\"run\" data-code=\"" c "\" title=\"Click: into the REPL\">" c "</code>"))))
36
+ "</p>")))
37
+ (apply str)))
38
+
39
+ (defn select-tab! [tab] (when-let [t ($ (str "tab-" tab))] (.click t)))
40
+
41
+ (defn to-repl! [code]
42
+ (set-repl-text! code) (focus-repl!))
43
+
44
+ ;; ───── tutorials (kairotic/tutorials.mjs, built from docs/tutorials) ─────
45
+
46
+ (def tracks [["patch-code" {:en "Patch ⇄ code" :es "Patch ⇄ código"}]
47
+ ["theory" {:en "Notation and theory" :es "Notación y teoría"}]
48
+ ["composition" {:en "Composition and CAC" :es "Composición y CAC"}]
49
+ ["dsp" {:en "Electroacoustics and DSP" :es "Electroacústica y DSP"}]
50
+ ["faust" {:en "Faust" :es "Faust"}]])
51
+
52
+ (defonce tutorials (atom nil)) ; nil · :loading · [{:id :track :order :title :steps} …]
53
+
54
+ (defn load-tutorials! []
55
+ (when (nil? @tutorials)
56
+ (reset! tutorials :loading)
57
+ (-> ((.-kairoticImport js/window) (str "kairotic/tutorials.mjs?v=" (js/Date.now)))
58
+ (.then (fn [m] (reset! tutorials (vec (js->clj (.-tutorials m) :keywordize-keys true)))))
59
+ (.catch (fn [e] (reset! tutorials [])
60
+ (repl-print! "err" (esc (str "Could not read the tutorials: " (or (.-message e) e)))))))))
61
+
62
+ ;; ───── the Help tab ─────
63
+
64
+ (defonce help-cls (atom nil)) ; nil = the index
65
+
66
+ (defn help-ports [label n names]
67
+ (when (pos? n)
68
+ (str "<h4>" label "</h4>"
69
+ (if (= n (count names))
70
+ (str "<ol start=\"0\">" (apply str (for [x names] (str "<li>" (esc x) "</li>"))) "</ol>")
71
+ (str "<p>" n (if (= label "Inlets") " (numbered from 0, left to right)" " (numbered from 0)")
72
+ (when (seq names) (str ": " (esc (str/join " · " names)))) "</p>")))))
73
+
74
+ (defn help-word [w]
75
+ (if (str/starts-with? (str w) "(")
76
+ (str "<code class=\"run\" data-code=\"" (esc w) "\">" (esc w) "</code>")
77
+ (str "<code>" (esc w) "</code>")))
78
+
79
+ (defn help-refs
80
+ "Links to the outer documentation of a class ([[label url] …]: clojuredocs.org and clojure.org for the
81
+ boxes of clojure.core), opened in a new tab; empty when it has none."
82
+ [refs]
83
+ (when (seq refs)
84
+ (str "<p class=\"refs\"><small>" (if (es?) "Referencia: " "Reference: ")
85
+ (str/join " · " (for [[label url] refs]
86
+ (str "<a href=\"" (esc url) "\" target=\"_blank\" rel=\"noopener\">" (esc label) "</a>")))
87
+ "</small></p>")))
88
+
89
+ (defn help-page [cls]
90
+ (let [d (comp/lookup cls) h (hlp/of cls)
91
+ doc (or (:doc d) (:doc h)) usage (or (:usage d) (:usage h))
92
+ [ins outs] (if d (try (io cls) (catch :default _ [0 0])) [(count (:inlets h)) (count (:outlets h))])
93
+ spec (when d (spec-of d))]
94
+ (str "<p class=\"back\"><a href=\"#\" data-help-index=\"1\">◀ Help</a></p>"
95
+ "<h3>" (esc cls)
96
+ (when-let [p (:package h)] (str "<span class=\"pkg\" title=\"Writing it in a box brings this package into the work\">" (esc p) "</span>"))
97
+ (when (= :work (:origin d)) "<span class=\"pkg\">defined in this work</span>")
98
+ "</h3>"
99
+ (when usage (str "<div class=\"usage\">" (esc usage) "</div>"))
100
+ ;; an introduction in short paragraphs (:about), with everything it does folded below it; or the doc
101
+ (if-let [about (:about h)]
102
+ (str "<div class=\"about\">" (rich about) "</div>"
103
+ (when doc (str "<details class=\"all-doc\"><summary>Everything it does</summary><p>" (esc doc) "</p></details>")))
104
+ (when doc (str "<p>" (esc doc) "</p>")))
105
+ (help-refs (or (:ref d) (:ref h)))
106
+ (when (and (nil? d) (empty? h)) "<p>There is no class with this name.</p>")
107
+ (when (or spec (seq (:args h)))
108
+ ;; what each argument is, and (from the help's :args, [[:k "what it does"] …]) what it does; without the
109
+ ;; component loaded, its arguments as the help lists them
110
+ (str "<h4>Arguments</h4><table>"
111
+ (apply str (for [[a v] (or spec (map (fn [[a]] [a nil]) (:args h))) :let [what (get (into {} (:args h)) a)]]
112
+ (str "<tr><td>" (esc (name a)) "</td><td>"
113
+ (esc (cond (nil? v) ""
114
+ (boolean? v) "a flag: on when its name is written"
115
+ (keyword? v) (str "a number (by default, the value of " (name v) ")")
116
+ (number? v) (str "a number, " (cv/fmt v) " by default")
117
+ :else "a word"))
118
+ "</td>" (when (seq (:args h)) (str "<td>" (when what (esc what)) "</td>")) "</tr>")))
119
+ "</table>"))
120
+ (help-ports "Inlets" ins (:inlets h))
121
+ (help-ports "Outlets" outs (:outlets h))
122
+ (when (seq (:messages h))
123
+ (str "<h4>Messages and gestures</h4><table>"
124
+ (apply str (for [[w x] (:messages h)] (str "<tr><td>" (help-word w) "</td><td>" (esc x) "</td></tr>")))
125
+ "</table>"))
126
+ (when-let [steps (seq (hlp/patch-steps cls))]
127
+ (str "<h4>Help patch</h4><p><button class=\"act primary\" data-help-open=\"" (esc cls) "\">Open the help patch</button> "
128
+ "<small>a local work you can play and change; Close (in the lesson bar) brings back what you had open</small></p>"
129
+ (when (seq (:try h)) (str "<div class=\"try\">" (esc (:try h)) "</div>"))
130
+ (when (> (count steps) 1)
131
+ (str "<p><small>" (count steps) " steps, each one a use of " (esc cls) " (◀ ▶ in the lesson bar):</small></p>"
132
+ "<ol class=\"help-steps\">"
133
+ (apply str (map-indexed (fn [i st] (str "<li><a href=\"#\" data-help-open=\"" (esc cls) "\" data-help-step=\"" i "\">"
134
+ (esc (tr (:title st))) "</a></li>"))
135
+ steps))
136
+ "</ol>"))))
137
+ (when (and d (empty? h) (#{:work :user} (:origin d)))
138
+ "<p><small>No help written yet: a component can carry its own, as <code>:help {:inlets […] :outlets […] :example \"…\"}</code> in its definition.</small></p>")
139
+ (when (seq (:see h))
140
+ (str "<h4>See also</h4><div class=\"chips\">"
141
+ (apply str (for [c (:see h)] (str "<span class=\"chip\" data-help=\"" (esc c) "\">" (esc c) "</span>")))
142
+ "</div>")))))
143
+
144
+ (declare docs-index)
145
+
146
+ (defn help-index []
147
+ (let [ts @tutorials]
148
+ (str "<input class=\"help-find\" id=\"help-find\" list=\"help-classes\" placeholder=\""
149
+ (if (es?) "Una clase: osc~, ramp, reader~…" "A class: osc~, ramp, reader~…") "\" spellcheck=\"false\">"
150
+ "<datalist id=\"help-classes\">" (apply str (for [c (hlp/known)] (str "<option value=\"" (esc c) "\">"))) "</datalist>"
151
+ "<p><small>" (if (es?) "Selecciona una caja y pulsa <b>?</b> para ver aquí su ayuda." "Select a box and press <b>?</b> to see its help here.") "</small></p>"
152
+ (docs-index)
153
+ "<h4>" (if (es?) "Tutoriales" "Tutorials") "</h4>"
154
+ (cond
155
+ (= :loading ts) "<p>…</p>"
156
+ (empty? ts) "<p><small>None.</small></p>"
157
+ :else
158
+ (apply str
159
+ (for [[tk tname] tracks
160
+ :let [ls (sort-by :order (filter (fn [t] (= tk (:track t))) ts))]
161
+ :when (seq ls)]
162
+ (str "<p><b>" (esc (tr tname)) "</b></p><ul class=\"tuts\">"
163
+ (apply str (for [t ls]
164
+ (str "<li class=\"tut\" data-tut=\"" (esc (:id t)) "\"><span>" (esc (tr (:title t))) "</span>"
165
+ "<small>" (count (:steps t)) (if (es?) " pasos" " steps") "</small></li>")))
166
+ "</ul>"))))
167
+ "<h4>" (if (es?) "Componentes" "Components") "</h4><div class=\"chips\">"
168
+ (apply str (for [c (hlp/known)] (str "<span class=\"chip\" data-help=\"" (esc c) "\">" (esc c) "</span>")))
169
+ "</div>")))
170
+
171
+ ;; ───── the documentation in the Help tab (kairotic/docs.mjs, built from docs/) ─────
172
+
173
+ (declare link-code open-link-work! render-help! show-help!)
174
+
175
+ (defonce doc-pages (atom nil)) ; nil · :loading · {"id" {"en" text "es" text}}
176
+ (defonce help-doc (atom nil)) ; the page of the documentation on screen, or nil
177
+
178
+ (def doc-groups
179
+ [[{:en "Start here" :es "Para empezar"} ["guide" "concepts"]]
180
+ [{:en "Topics" :es "Temas"} ["mt" "flow" "ask" "embed" "pages"]]
181
+ [{:en "Extending" :es "Ampliarlo"} ["writing-a-component"]]
182
+ [{:en "Reference" :es "Referencia"} ["reference"]]])
183
+
184
+ (defn load-docs! []
185
+ (when (nil? @doc-pages)
186
+ (reset! doc-pages :loading)
187
+ (-> ((.-kairoticImport js/window) (str "kairotic/docs.mjs?v=" (js/Date.now)))
188
+ (.then (fn [m] (reset! doc-pages (get (js->clj m) "pages"))))
189
+ (.catch (fn [e] (reset! doc-pages {})
190
+ (repl-print! "err" (esc (str "Could not read the documentation: " (or (.-message e) e)))))))))
191
+
192
+ (defn doc-text [id]
193
+ (let [p (when (map? @doc-pages) (get @doc-pages id))]
194
+ (or (when (es?) (get p "es")) (get p "en"))))
195
+
196
+ (defn doc-title [id]
197
+ (or (some->> (doc-text id) (re-find #"(?m)^# (.+)$") second) id))
198
+
199
+ (def docs-base "https://github.com/bonuoq/kairotic/blob/main/docs/")
200
+
201
+ (defn md-link
202
+ "A link of the documentation: to another page (shown here, in its language), to the web (a new tab),
203
+ or to a file of the repository (on GitHub)."
204
+ [label href]
205
+ (let [[_ id es] (re-matches #"(?:\./)?(?:tutorials/)?([A-Za-z-]+?)(\.es)?\.md(?:#.*)?" href)]
206
+ (cond
207
+ (and id (contains? (set (mapcat second doc-groups)) id))
208
+ (str "<a href=\"#\" data-doc=\"" id "\" data-lang=\"" (if es "es" "en") "\">" label "</a>")
209
+ (and id (= id "README")) (str "<a href=\"#\" data-help-index=\"1\">" label "</a>")
210
+ (str/starts-with? href "#") label
211
+ :else (let [u (if (re-find #"^https?:" href) href (.-href (js/URL. href docs-base)))]
212
+ (str "<a href=\"" u "\" target=\"_blank\" rel=\"noopener\">" label "</a>")))))
213
+
214
+ (defn md-inline
215
+ "Inline Markdown: `code`, [links](…), **bold**, *italic*."
216
+ [s]
217
+ (let [parts (str/split (str s) #"`" -1)]
218
+ (apply str
219
+ (map-indexed
220
+ (fn [i p]
221
+ (if (odd? i)
222
+ (str "<code>" (esc p) "</code>")
223
+ (-> (esc p)
224
+ (str/replace #"\[([^\]]+)\]\(([^)\s]+)\)" (fn [[_ l h]] (md-link l (str/replace h "&amp;" "&"))))
225
+ (str/replace #"\*\*([^*]+)\*\*" "<b>$1</b>")
226
+ (str/replace #"(^|[\s(])\*([^*\s][^*]*)\*" "$1<i>$2</i>"))))
227
+ parts))))
228
+
229
+ (defn md-code [lang code]
230
+ (let [patch? (and (#{"clojure" "clj" ""} lang) (str/includes? code "(box ")
231
+ (try (link-code code) true (catch :default _ false)))]
232
+ (str "<pre>" (esc code) "</pre>"
233
+ (when patch?
234
+ (str "<p class=\"doc-try\"><button class=\"act\" data-doc-patch=\"" (esc code) "\">"
235
+ (if (es?) "Abrir como patch local" "Open as a local patch") "</button></p>")))))
236
+
237
+ (defn md-block-start? [l]
238
+ (or (str/starts-with? l "```") (re-matches #"#{1,6} .*" l) (str/starts-with? l "|") (str/starts-with? l "> ")
239
+ (re-matches #"([-*]|\d+\.) .*" l)))
240
+
241
+ (defn md->html
242
+ "The Markdown of docs/ as HTML: headings, paragraphs, lists, tables, quotes, code blocks."
243
+ [text]
244
+ (let [ls (vec (str/split-lines (str text))) n (count ls)
245
+ take-while-from (fn [i pred] (loop [j i] (if (and (< j n) (pred (nth ls j))) (recur (inc j)) j)))]
246
+ (loop [i 0 out []]
247
+ (if (>= i n)
248
+ (apply str out)
249
+ (let [l (nth ls i)]
250
+ (cond
251
+ (str/starts-with? l "```")
252
+ (let [j (take-while-from (inc i) #(not (str/starts-with? % "```")))]
253
+ (recur (inc j) (conj out (md-code (str/trim (clojure.core/subs l 3)) (str/join "\n" (subvec ls (inc i) (min j n)))))))
254
+ (str/blank? l) (recur (inc i) out)
255
+ (re-matches #"#{1,6} .*" l)
256
+ (let [k (count (re-find #"^#+" l))]
257
+ (recur (inc i) (conj out (str "<h" (min 6 (inc k)) " class=\"dh\">" (md-inline (str/trim (clojure.core/subs l k))) "</h" (min 6 (inc k)) ">"))))
258
+ (str/starts-with? l "|")
259
+ (let [j (take-while-from i #(str/starts-with? % "|"))
260
+ rows (remove #(re-matches #"\|[\s:|-]+\|?" %) (subvec ls i j))
261
+ cells (fn [r] (map str/trim (butlast (rest (str/split r #"\|" -1)))))]
262
+ (recur j (conj out (str "<table class=\"dt\">"
263
+ (apply str (map-indexed (fn [k r] (str "<tr>" (apply str (for [c (cells r)] (str (if (zero? k) "<th>" "<td>") (md-inline c) (if (zero? k) "</th>" "</td>")))) "</tr>")) rows))
264
+ "</table>"))))
265
+ (str/starts-with? l "> ")
266
+ (let [j (take-while-from i #(str/starts-with? % ">"))]
267
+ (recur j (conj out (str "<blockquote>" (md-inline (str/join " " (map #(str/trim (clojure.core/subs % 1)) (subvec ls i j)))) "</blockquote>"))))
268
+ (re-matches #"([-*]|\d+\.) .*" l)
269
+ (let [ordered (re-matches #"\d+\. .*" l)
270
+ j (take-while-from i #(or (re-matches #"\s*([-*]|\d+\.) .*" %) (re-matches #"\s+\S.*" %)))
271
+ items (reduce (fn [acc x]
272
+ (if-let [[_ t] (re-matches #"\s*(?:[-*]|\d+\.) (.*)" x)]
273
+ (conj acc t)
274
+ (conj (pop acc) (str (peek acc) " " (str/trim x)))))
275
+ [] (subvec ls i j))]
276
+ (recur j (conj out (str (if ordered "<ol>" "<ul>") (apply str (for [t items] (str "<li>" (md-inline t) "</li>"))) (if ordered "</ol>" "</ul>")))))
277
+ :else
278
+ (let [j (take-while-from (inc i) #(not (or (str/blank? %) (md-block-start? %))))]
279
+ (recur j (conj out (str "<p>" (md-inline (str/join " " (subvec ls i j))) "</p>"))))))))))
280
+
281
+ (defn doc-page [id]
282
+ (str "<p class=\"back\"><a href=\"#\" data-help-index=\"1\">◀ Help</a></p>"
283
+ (cond
284
+ (= :loading @doc-pages) "<p>…</p>"
285
+ (doc-text id) (str "<div class=\"doc\">" (md->html (doc-text id)) "</div>")
286
+ :else (str "<p>" (esc (str "No page " id)) "</p>"))))
287
+
288
+ (defn docs-index []
289
+ (str "<h4>" (if (es?) "Documentación" "Documentation") "</h4>"
290
+ (if (map? @doc-pages)
291
+ (apply str (for [[g ids] doc-groups]
292
+ (str "<p><b>" (esc (tr g)) "</b></p><ul class=\"tuts\">"
293
+ (apply str (for [id ids :when (doc-text id)]
294
+ (str "<li class=\"tut\" data-doc=\"" id "\"><span>" (esc (doc-title id)) "</span></li>")))
295
+ "</ul>")))
296
+ "<p>…</p>")))
297
+
298
+ (defn show-doc!
299
+ "Opens a page of the documentation in the Help tab."
300
+ [id]
301
+ (load-docs!)
302
+ (reset! help-cls nil)
303
+ (reset! help-doc id)
304
+ (render-help!)
305
+ (select-tab! "help")
306
+ (set! (.-scrollTop ($ "help-view")) 0))
307
+
308
+ (defn docs
309
+ "The documentation in the Help tab: (docs) its index, (docs \"guide\") a page — guide, concepts, mt,
310
+ flow, ask, embed, pages, writing-a-component, reference."
311
+ ([] (show-help! nil) (mapv first (mapcat (fn [[_ ids]] (map vector ids)) doc-groups)))
312
+ ([id] (show-doc! (str id)) (str id)))
313
+
314
+ (add-watch doc-pages ::help (fn [_ _ _ _] (render-help!)))
315
+
316
+ (defn reference-md
317
+ "The reference of every class with a help page, as Markdown (docs/reference.md is made with it):
318
+ (reference-md)."
319
+ []
320
+ (let [md-ports (fn [label n names]
321
+ (when (pos? n)
322
+ (str "**" label "** " (if (= n (count names))
323
+ (str "\n" (apply str (map-indexed (fn [i x] (str "\n" i ". " x)) names)) "\n")
324
+ (str n (when (seq names) (str ": " (str/join " · " names))) "\n"))
325
+ "\n")))
326
+ page (fn [cls]
327
+ (let [d (comp/lookup cls) h (hlp/of cls)
328
+ doc (or (:doc d) (:doc h)) usage (or (:usage d) (:usage h))
329
+ [ins outs] (if d (try (io cls) (catch :default _ [0 0])) [(count (:inlets h)) (count (:outlets h))])]
330
+ (when (and doc (not (str/starts-with? (str doc) "Kairotic class with no semantics")))
331
+ (str "### " cls (when-let [p (:package h)] (str " · `" p "`")) "\n\n"
332
+ (when usage (str "`" usage "`\n\n"))
333
+ (when-let [a (:about h)] (str a "\n\n"))
334
+ doc "\n\n"
335
+ (when (seq (:args h))
336
+ (str "**Arguments**\n\n"
337
+ (apply str (for [[a v] (if d (spec-of d) (map (fn [[a]] [a nil]) (:args h))) :let [what (get (into {} (:args h)) a)]]
338
+ (str "- `" (name a) "`"
339
+ (cond (boolean? v) " (a flag)" (number? v) (str " (" (cv/fmt v) ")") :else "")
340
+ (when what (str ": " what)) "\n")))
341
+ "\n"))
342
+ (md-ports "Inlets" ins (:inlets h))
343
+ (md-ports "Outlets" outs (:outlets h))
344
+ (when (seq (:messages h))
345
+ (str "**Messages and gestures**\n\n" (apply str (for [[w x] (:messages h)] (str "- `" (if (string? w) w (pr-str w)) "`: " x "\n"))) "\n"))
346
+ (when-let [t (:try h)] (str "**Try:** " t "\n\n"))
347
+ (when-let [e (:example h)] (str "```clojure\n" (str/trim e) "\n```\n\n"))
348
+ (apply str (for [st (:steps h)]
349
+ (str "**" (tr (:title st)) "**" (when (seq (tr (:note st))) (str " — " (tr (:note st)))) "\n\n"
350
+ (when (seq (tr (:try st))) (str "*Try:* " (tr (:try st)) "\n\n"))
351
+ "```clojure\n" (str/trim (:example st)) "\n```\n\n")))
352
+ (when (seq (:see h)) (str "See also: " (str/join ", " (map #(str "`" % "`") (:see h))) "\n\n"))
353
+ (when-let [refs (seq (or (:ref d) (:ref h)))]
354
+ (str "Reference: " (str/join " · " (for [[label url] refs] (str "[" label "](" url ")"))) "\n\n"))))))]
355
+ (str "# Class reference\n\n"
356
+ "*Made from the help of Kairotic " version " (the Help tab shows the same, and the help of classes a work defines). "
357
+ "Generated: do not edit by hand — `(reference-md)` in the REPL writes it.*\n\n"
358
+ (str/join "" (keep page (hlp/known))))))
359
+
360
+ (defn render-help! []
361
+ (when-let [el ($ "help-view")]
362
+ (set! (.-innerHTML el) (cond @help-doc (doc-page @help-doc)
363
+ @help-cls (help-page @help-cls)
364
+ :else (help-index)))))
365
+
366
+ (defn show-help!
367
+ "Opens the Help tab: the page of a class, or the index (nil)."
368
+ [cls]
369
+ (load-tutorials!)
370
+ (load-docs!)
371
+ (reset! help-doc nil)
372
+ (reset! help-cls (when (seq cls) cls))
373
+ (render-help!)
374
+ (select-tab! "help")
375
+ (set! (.-scrollTop ($ "help-view")) 0))
376
+
377
+ (defn refresh-help!
378
+ "Draws the Help tab as it is (the index, or the page it was on), loading the tutorials if needed."
379
+ [] (load-tutorials!) (load-docs!) (render-help!))
380
+
381
+ (add-watch tutorials ::help (fn [_ _ _ _] (render-help!)))
382
+
383
+ ;; ───── lessons ─────
384
+
385
+ (defonce lesson-back (atom nil)) ; what was open before the first lesson
386
+
387
+ (defn render-lesson! []
388
+ (let [el ($ "lesson") l @lesson]
389
+ (set! (.-hidden el) (nil? l))
390
+ (when l
391
+ (let [steps (:steps l) n (count steps) i (min (:at l) (dec n)) st (nth steps i nil)
392
+ here (norm (:pos @world))
393
+ last-pos (some :pos (reverse steps))
394
+ away? (and here last-pos (not (some (fn [s] (= here (:pos s))) steps)) (not (reaches? here last-pos)))]
395
+ (set! (.-textContent ($ "lesson-title")) (tr (:title l)))
396
+ (set! (.-textContent ($ "lesson-n")) (str (inc i) " / " n))
397
+ (set! (.-disabled ($ "lesson-prev")) (zero? i))
398
+ (set! (.-disabled ($ "lesson-next")) (>= i (dec n)))
399
+ (set! (.-textContent ($ "lesson-back")) (if (es?) "Cerrar" "Close"))
400
+ (doseq [b (array-seq (.querySelectorAll el "[data-lang]"))]
401
+ (.setAttribute b "aria-pressed" (str (= (name @lang) (.. b -dataset -lang)))))
402
+ (set! (.-innerHTML ($ "lesson-note"))
403
+ (str (let [t (tr (:title st))] (when (seq t) (str "<p class=\"step-t\">" (esc t) "</p>")))
404
+ (rich (tr (:note st)))
405
+ (let [t (tr (:try st))]
406
+ (when (seq t) (str "<div class=\"try\">" (rich (str (if (es?) "**Prueba:** " "**Try:** ") t)) "</div>")))
407
+ (when away?
408
+ (str "<p class=\"away\">"
409
+ (if (es?) "Estás en una rama tuya: la lección sigue en la historia. ◀ ▶ te devuelven a ella."
410
+ "You are on a branch of your own: the lesson is still in the history. ◀ ▶ take you back to it.")
411
+ "</p>"))))))))
412
+
413
+ (defn lesson-sync!
414
+ "After moving in the history by other means, the step you are at."
415
+ []
416
+ (when-let [l @lesson]
417
+ (let [here (norm (:pos @world)) steps (:steps l)]
418
+ (when-not (= (:pos (nth steps (:at l) nil)) here)
419
+ (let [i (last (keep-indexed (fn [i s] (when (and (:pos s) here (reaches? (:pos s) here)) i)) steps))]
420
+ (swap! lesson assoc :at (or i 0)))))
421
+ (render-lesson!)))
422
+
423
+ (add-watch world ::lesson (fn [_ _ o n] (when (and @lesson (not= (:pos o) (:pos n))) (lesson-sync!))))
424
+
425
+ (defn lesson-go! [i]
426
+ (when-let [l @lesson]
427
+ (let [i (max 0 (min (dec (count (:steps l))) i)) p (:pos (nth (:steps l) i))]
428
+ (swap! lesson assoc :at i)
429
+ (if p
430
+ (goto (first p) (second p))
431
+ (swap! world assoc :pos nil :auto false :prev-pos nil))
432
+ (swap! lesson assoc :at i)
433
+ (render-lesson!))))
434
+
435
+ (def box-class-re #"\(box\s+(?::\S+\s+)?\"([^\"\s]+)")
436
+
437
+ (defn lesson-definitions
438
+ "Promise of [[name classes source] …]: the official packages a lesson's boxes
439
+ need and the work does not define yet, fetched before the lesson is built (so that their
440
+ definitions are part of its history, in order, and not late arrivals on a branch of their own)."
441
+ [l]
442
+ (let [ks (distinct (for [st (:steps l) c (:code st) [_ k] (re-seq box-class-re c)] k))
443
+ ;; a lesson starts from an empty history: every class of a package is needed, even if the
444
+ ;; work open before it had defined it
445
+ pkgs (distinct (keep (fn [k] (first (lib/package-of k))) ks))]
446
+ (if (empty? pkgs)
447
+ (js/Promise.resolve [])
448
+ (-> (js/Promise.all
449
+ (into-array
450
+ (for [p pkgs] (.then (lib/import-package p) (fn [[m origin]] [p (set (map :class (:components m))) (lib/package-source m origin)])))))
451
+ (.then (fn [arr] (vec arr)))))))
452
+
453
+ (declare build-lesson!)
454
+
455
+ (defn compiled-components
456
+ "Promise: the sources of these component boxes compiled (or failed), so that the classes they define
457
+ can be registered at once while a lesson is built, and its next gestures (the code of a pbind) find them."
458
+ [srcs]
459
+ (js/Promise.
460
+ (fn [res _]
461
+ (let [t0 (js/Date.now)]
462
+ (letfn [(check []
463
+ (if (or (every? #(not= :compiling (:status (cbox/compiled "component" %))) srcs)
464
+ (> (- (js/Date.now) t0) 15000))
465
+ (res nil)
466
+ (js/setTimeout check 30)))]
467
+ (check))))))
468
+
469
+ (defn open-lesson!
470
+ "Opens a lesson: first the packages its boxes need, then the lesson itself (build-lesson!)."
471
+ [l]
472
+ (repl-print! "out" (esc (str "; " (if (es?) "Preparando la lección" "Preparing the lesson") "…")))
473
+ (-> (lesson-definitions l)
474
+ ;; a lesson is a local work, run as trusted (build-lesson!): its packages compile first
475
+ (.then (fn [defs]
476
+ (reset! cbox/trust true)
477
+ (.then (compiled-components (map #(nth % 2) defs)) (fn [_] (build-lesson! (assoc l :defs defs))))))
478
+ (.catch (fn [e]
479
+ (repl-print! "err" (esc (str "; " (or (.-message e) e) " · " (if (es?) "la lección se abre sin ese paquete" "the lesson opens without that package"))))
480
+ (build-lesson! l)))))
481
+
482
+ (defn build-lesson!
483
+ "Builds a lesson as a local work, step by step: the gestures of each step are made in order
484
+ (they appear in the REPL) and each step remembers its point in the history."
485
+ [l]
486
+ (when-not @lesson (reset! lesson-back {:work @work :hist @hist :world @world :settings @settings :lines @line-state}))
487
+ (reset! lesson nil)
488
+ (eng/stop!)
489
+ (reset! cbox/trust true)
490
+ (cbox/forget-language! "clojurescript")
491
+ (reset! work {:kind :local :id "lesson" :name (tr (:title l))})
492
+ (reset-work-state! :local)
493
+ (swap! mgr assoc :open false :confirm nil :invite nil)
494
+ (set-hash! "")
495
+ (lobby-presence!)
496
+ (swap! hist assoc :mode :local :loaded true)
497
+ (repl-print! "out" (esc (str "; " (if (es?) "Lección" "Lesson") ": «" (tr (:title l)) "»")))
498
+ (let [defs (atom (:defs l)) ; [[name classes source] …] of packages not yet in the work
499
+ ;; definition boxes get ids beyond any the lesson writes (lessons name their boxes)
500
+ free-id (atom (inc (reduce max 0 (for [st (:steps l) c (:code st) [_ n] (re-seq #":b(\d+)" c)] (js/parseInt n 10)))))
501
+ steps (reduce (fn [acc st]
502
+ (doseq [c (:code st)]
503
+ ;; a class from a package: its definition goes in just before the box that uses it
504
+ (let [used (set (map second (re-seq box-class-re c)))]
505
+ (doseq [[nm cls src :as d] @defs :when (some used cls)]
506
+ (let [id (keyword (str "b" @free-id)) [x y] (component-slot)]
507
+ (swap! free-id inc)
508
+ (gesture! (str "(box " id " \"component\" " x " " y ")"))
509
+ (gesture! (str "(code " id " " (pr-str src) ")"))
510
+ ;; its classes now, not at the next render: the gestures after it use them
511
+ (lib/sync! (eng/flat (root-patch))))
512
+ (swap! defs (fn [ds] (vec (remove #{d} ds))))))
513
+ (gesture! c))
514
+ (conj acc (assoc st :pos (norm (:pos @world)))))
515
+ [] (:steps l))]
516
+ (reset! lesson (assoc l :steps steps :at 0))
517
+ (lesson-go! (or (:start l) 0))
518
+ (render-all!)
519
+ (render-lesson!)))
520
+
521
+ (defn close-lesson!
522
+ "Closes the lesson and brings back what was open before it."
523
+ []
524
+ (let [b @lesson-back w (:work b)]
525
+ (reset! lesson nil)
526
+ (reset! lesson-back nil)
527
+ (eng/stop!)
528
+ (cond
529
+ (#{:room :solo} (:kind w)) (open-work! (:kind w) (:id w) (:name w))
530
+ (= :local (:kind w)) (do (reset! work w)
531
+ (reset-work-state! :local)
532
+ (reset! hist (:hist b))
533
+ (reset! settings (:settings b))
534
+ (reset! world (:world b))
535
+ (when (:lines b) (reset! line-state (:lines b)))
536
+ (render-all!))
537
+ :else (close-work!))
538
+ (render-lesson!)))
539
+
540
+ (defn open-help-patch!
541
+ "Opens the help patch of a class as a lesson (one step per use, when it has several), at step i."
542
+ ([cls] (open-help-patch! cls 0))
543
+ ([cls i]
544
+ (let [steps (hlp/patch-steps cls)]
545
+ (when (seq steps)
546
+ (open-lesson! {:help cls
547
+ :title {:en (str "Help · " cls) :es (str "Ayuda · " cls)}
548
+ :start i
549
+ :steps steps})))))
550
+
551
+ (defn open-tutorial! [id]
552
+ (when-let [t (first (filter (fn [t] (= id (:id t))) (when (sequential? @tutorials) @tutorials)))]
553
+ (open-lesson! t)))
554
+
555
+ (defn tutorial
556
+ "Opens a tutorial by id: (tutorial \"patch-to-code\"). Without an id, the list."
557
+ ([] (show-help! nil) (if (sequential? @tutorials) (mapv :id @tutorials) :loading))
558
+ ([id] (if (sequential? @tutorials) (do (open-tutorial! id) id) (do (load-tutorials!) :loading))))
559
+
560
+ (defn set-lang! [l]
561
+ (reset! lang l)
562
+ (try (.setItem js/localStorage "kairotic.lang" (name l)) (catch :default _ nil))
563
+ (render-lesson!)
564
+ (render-help!))
565
+
566
+ (.addEventListener ($ "help-view") "click"
567
+ (fn [e]
568
+ (let [t (.-target e)]
569
+ (cond
570
+ (.closest t "[data-help-index]") (do (.preventDefault e) (show-help! nil))
571
+ (.closest t "[data-doc]")
572
+ (let [el (.closest t "[data-doc]") l (.getAttribute el "data-lang")]
573
+ (.preventDefault e)
574
+ (when (and l (not= l (name @lang))) (reset! lang (keyword l)) (render-lesson!))
575
+ (show-doc! (.getAttribute el "data-doc")))
576
+ (.closest t "[data-doc-patch]")
577
+ (try (open-link-work! (if (es?) "Documentación" "Documentation")
578
+ (link-code (.getAttribute (.closest t "[data-doc-patch]") "data-doc-patch")))
579
+ (catch :default x (repl-print! "err" (esc (str "; " (or (.-message x) x))))))
580
+ (.closest t "[data-help-open]")
581
+ (let [el (.closest t "[data-help-open]")]
582
+ (.preventDefault e)
583
+ (open-help-patch! (.getAttribute el "data-help-open") (js/parseInt (or (.getAttribute el "data-help-step") "0") 10)))
584
+ (.closest t "[data-help]") (show-help! (.getAttribute (.closest t "[data-help]") "data-help"))
585
+ (.closest t "[data-tut]") (open-tutorial! (.getAttribute (.closest t "[data-tut]") "data-tut"))
586
+ (.closest t "code.run") (to-repl! (.getAttribute (.closest t "code.run") "data-code"))))))
587
+
588
+ (.addEventListener ($ "help-view") "change"
589
+ (fn [e]
590
+ (when (= "help-find" (.. e -target -id))
591
+ (let [v (str/trim (.. e -target -value))]
592
+ (when (or (comp/lookup v) (seq (hlp/of v))) (show-help! v))))))
593
+
594
+ (.addEventListener ($ "lesson") "click"
595
+ (fn [e]
596
+ (let [t (.-target e)]
597
+ (cond
598
+ (.closest t "#lesson-prev") (lesson-go! (dec (:at @lesson)))
599
+ (.closest t "#lesson-next") (lesson-go! (inc (:at @lesson)))
600
+ (.closest t "#lesson-back") (close-lesson!)
601
+ (.closest t "[data-lang]") (set-lang! (keyword (.. (.closest t "[data-lang]") -dataset -lang)))
602
+ (.closest t "code.run") (to-repl! (.getAttribute (.closest t "code.run") "data-code"))))))