enhance(ux): flashcards (#12299)

Enhances the flashcard user experience by adding automatic query property management, fixing critical bugs, and improving the UI for managing card sets.

Key changes:

1. Automatic creation of query property blocks when tagging with #Query or subclasses via pipeline
2. Fixed critical bug in api-insert-new-block! where the end? parameter had inverted conditional logic
3. Added ability to create new #Cards blocks directly from the flashcard modal with a plus button

Author: tiensonqin

clj-e2e/dev/user.clj

@@ -6,6 +6,7 @@
             [logseq.e2e.config :as config]
             [logseq.e2e.editor-basic-test]
             [logseq.e2e.fixtures :as fixtures]
+            [logseq.e2e.flashcards-basic-test]
             [logseq.e2e.graph :as graph]
             [logseq.e2e.keyboard :as k]
             [logseq.e2e.locator :as loc]
@@ -46,6 +47,11 @@
   (->> (future (run-tests 'logseq.e2e.property-basic-test))
        (swap! *futures assoc :property-test)))
 
+(defn run-flashcards-basic-test
+  []
+  (->> (future (run-tests 'logseq.e2e.flashcards-basic-test))
+       (swap! *futures assoc :flashcards-test)))
+
 (defn run-property-scoped-choices-test
   []
   (->> (future (run-tests 'logseq.e2e.property-scoped-choices-test))
@@ -111,7 +117,8 @@
              'logseq.e2e.plugins-basic-test
              'logseq.e2e.reference-basic-test
              'logseq.e2e.property-basic-test
-             'logseq.e2e.tag-basic-test)
+             'logseq.e2e.tag-basic-test
+             'logseq.e2e.flashcards-basic-test)
   (System/exit 0))
 
 (defn start

clj-e2e/src/logseq/e2e/api.clj

@@ -0,0 +1,39 @@
+(ns logseq.e2e.api
+  (:require
+   [clojure.string :as string]
+   [jsonista.core :as json]
+   [wally.main :as w]))
+
+(defn- to-snake-case
+  "Converts a string to snake_case. Handles camelCase, PascalCase, spaces, hyphens, and existing underscores.
+   Examples:
+     'HelloWorld' -> 'hello_world'
+     'Hello World' -> 'hello_world'
+     'hello-world' -> 'hello_world'
+     'Hello__World' -> 'hello_world'"
+  [s]
+  (when (string? s)
+    (-> s
+      ;; Normalize input: replace hyphens/spaces with underscores, collapse multiple underscores
+        (string/replace #"[-\s]+" "_")
+      ;; Split on uppercase letters (except at start) and join with underscore
+        (string/replace #"(?<!^)([A-Z])" "_$1")
+      ;; Remove redundant underscores and trim
+        (string/replace #"_+" "_")
+        (string/trim)
+        ;; Convert to lowercase
+        (string/lower-case))))
+
+(defn ls-api-call!
+  [api-keyword & args]
+  (let [tag (name api-keyword)
+        ns' (string/split tag #"\.")
+        ns? (and (seq ns') (= (count ns') 2))
+        inbuilt? (contains? #{"app" "editor"} (first ns'))
+        ns1 (string/lower-case (if (and ns? (not inbuilt?))
+                                 (str "sdk." (first ns')) "api"))
+        name1 (if ns? (to-snake-case (last ns')) tag)
+        estr (format "s => { const args = JSON.parse(s);const o=logseq.%1$s; return o['%2$s']?.apply(null, args || []); }" ns1 name1)
+        args (json/write-value-as-string (vec args))]
+    ;; (prn "Debug: eval-js #" estr args)
+    (w/eval-js estr args)))

clj-e2e/src/logseq/e2e/keyboard.clj

@@ -17,6 +17,8 @@
 
 (def arrow-up #(press "ArrowUp"))
 (def arrow-down #(press "ArrowDown"))
+(def arrow-left #(press "ArrowLeft"))
+(def arrow-right #(press "ArrowRight"))
 
 (def meta+shift+arrow-up #(press (str (if mac? "Meta" "Alt") "+Shift+ArrowUp")))
 (def meta+shift+arrow-down #(press (str (if mac? "Meta" "Alt") "+Shift+ArrowDown")))

clj-e2e/test/logseq/e2e/flashcards_basic_test.clj

@@ -0,0 +1,83 @@
+(ns logseq.e2e.flashcards-basic-test
+  (:require [clojure.test :refer [deftest testing use-fixtures]]
+            [logseq.e2e.api :refer [ls-api-call!]]
+            [logseq.e2e.assert :as assert]
+            [logseq.e2e.fixtures :as fixtures]
+            [logseq.e2e.keyboard :as k]
+            [logseq.e2e.locator :as loc]
+            [logseq.e2e.util :as util]
+            [wally.main :as w]
+            [wally.repl :as repl]))
+
+(use-fixtures :once fixtures/open-page)
+
+(use-fixtures :each
+  fixtures/validate-graph)
+
+(defn- open-flashcards
+  []
+  (util/double-esc)
+  (k/press ["t" "c"])
+  (assert/assert-is-visible "#cards-modal"))
+
+(defn- select-cards-option
+  [label]
+  (w/click "#cards-modal [role='combobox']")
+  (w/click (loc/filter "[role='option']" :has-text label)))
+
+(defn- click-flashcards-plus
+  []
+  (w/click "#ls-cards-add"))
+
+(defn- setup-flashcards-data!
+  [{:keys [page-name tag-a tag-b card-a card-b query-a query-b]}]
+  (ls-api-call! :editor.appendBlockInPage page-name (str card-a " #Card #" tag-a))
+  (ls-api-call! :editor.appendBlockInPage page-name (str card-b " #Card #" tag-b))
+  (let [cards (ls-api-call! :editor.getTag "logseq.class/Cards")
+        cards-id (get cards "id")
+        cards-a (ls-api-call! :editor.appendBlockInPage page-name "Cards A"
+                              {:properties {:block/tags #{cards-id}}})
+        cards-b (ls-api-call! :editor.appendBlockInPage page-name "Cards B"
+                              {:properties {:block/tags #{cards-id}}})
+        query-a-id (get cards-a ":logseq.property/query")
+        query-b-id (get cards-b ":logseq.property/query")]
+    (ls-api-call! :editor.updateBlock query-a-id query-a)
+    (ls-api-call! :editor.updateBlock query-b-id query-b)))
+
+(deftest flashcards-plus-and-switching-test
+  (testing "create #Cards blocks from flashcards dialog and switch card sets"
+    (let [tag-a "fc-tag-a"
+          tag-b "fc-tag-b"
+          card-a "Card A"
+          card-b "Card B"
+          query-a (str "[[" tag-a "]]")
+          query-b (str "[[" tag-b "]]")]
+      (util/goto-journals)
+      (let [page (ls-api-call! :editor.getCurrentPage)
+            page-name (get page "name")]
+        (setup-flashcards-data!
+         {:page-name page-name
+          :tag-a tag-a
+          :tag-b tag-b
+          :card-a card-a
+          :card-b card-b
+          :query-a query-a
+          :query-b query-b}))
+
+      (open-flashcards)
+      (click-flashcards-plus)
+      (w/wait-for ".ls-block .tag:has-text('Cards')")
+
+      (open-flashcards)
+      (select-cards-option "Cards A")
+      (assert/assert-is-visible (format "#cards-modal .ls-card :text('%s')" card-a))
+      (assert/assert-have-count (format "#cards-modal .ls-card :text('%s')" card-b) 0)
+      (assert/assert-is-visible (loc/filter "#cards-modal .text-sm.opacity-50" :has-text "1/1"))
+
+      (select-cards-option "Cards B")
+      (assert/assert-is-visible (format "#cards-modal .ls-card :text('%s')" card-b))
+      (assert/assert-have-count (format "#cards-modal .ls-card :text('%s')" card-a) 0)
+      (assert/assert-is-visible (loc/filter "#cards-modal .text-sm.opacity-50" :has-text "1/1"))
+
+      (select-cards-option "All cards")
+      (assert/assert-is-visible (loc/filter "#cards-modal .text-sm.opacity-50" :has-text "1/2")))))

clj-e2e/test/logseq/e2e/plugins_basic_test.clj

@@ -1,9 +1,8 @@
 (ns logseq.e2e.plugins-basic-test
   (:require
    [clojure.set :as set]
-   [clojure.string :as string]
    [clojure.test :refer [deftest testing is use-fixtures]]
-   [jsonista.core :as json]
+   [logseq.e2e.api :refer [ls-api-call!]]
    [logseq.e2e.assert :as assert]
    [logseq.e2e.fixtures :as fixtures]
    [logseq.e2e.keyboard :as k]
@@ -19,45 +18,11 @@
   [property-name]
   (str ":plugin.property._test_plugin/" property-name))
 
-(defn- to-snake-case
-  "Converts a string to snake_case. Handles camelCase, PascalCase, spaces, hyphens, and existing underscores.
-   Examples:
-     'HelloWorld' -> 'hello_world'
-     'Hello World' -> 'hello_world'
-     'hello-world' -> 'hello_world'
-     'Hello__World' -> 'hello_world'"
-  [s]
-  (when (string? s)
-    (-> s
-      ;; Normalize input: replace hyphens/spaces with underscores, collapse multiple underscores
-        (clojure.string/replace #"[-\s]+" "_")
-      ;; Split on uppercase letters (except at start) and join with underscore
-        (clojure.string/replace #"(?<!^)([A-Z])" "_$1")
-      ;; Remove redundant underscores and trim
-        (clojure.string/replace #"_+" "_")
-        (clojure.string/trim)
-        ;; Convert to lowercase
-        (clojure.string/lower-case))))
-
 (defonce ^:private *property-idx (atom 0))
 (defn- new-property
   []
   (str "p" (swap! *property-idx inc)))
 
-(defn- ls-api-call!
-  [tag & args]
-  (let [tag (name tag)
-        ns' (string/split tag #"\.")
-        ns? (and (seq ns') (= (count ns') 2))
-        inbuilt? (contains? #{"app" "editor"} (first ns'))
-        ns1 (string/lower-case (if (and ns? (not inbuilt?))
-                                 (str "sdk." (first ns')) "api"))
-        name1 (if ns? (to-snake-case (last ns')) tag)
-        estr (format "s => { const args = JSON.parse(s);const o=logseq.%1$s; return o['%2$s']?.apply(null, args || []); }" ns1 name1)
-        args (json/write-value-as-string (vec args))]
-    ;; (prn "Debug: eval-js #" estr args)
-    (w/eval-js estr args)))
-
 (defn- assert-api-ls-block!
   ([ret] (assert-api-ls-block! ret 1))
   ([ret-or-uuid count]

src/main/frontend/components/block.cljs

@@ -1947,21 +1947,7 @@
                               (= 1 (count block-ast-title))
                               (= "Link" (ffirst block-ast-title)))
                          (assoc :node-ref-link-only? true))]
-           (map-inline config' block-ast-title))
-
-         (when (and (seq block-ast-title) (ldb/class-instance?
-                                           (entity-plus/entity-memoized (db/get-db) :logseq.class/Cards)
-                                           block))
-           [(ui/tooltip
-             (shui/button
-              {:variant :ghost
-               :size :sm
-               :class "ml-2 !px-1 !h-5 text-xs text-muted-foreground"
-               :on-click (fn [e]
-                           (util/stop e)
-                           (state/pub-event! [:modal/show-cards (:db/id block)]))}
-              "Practice")
-             [:div "Practice cards"])])))))))
+           (map-inline config' block-ast-title))))))))
 
 (rum/defc block-title-aux
   [config block {:keys [query? *show-query?]}]
@@ -1995,13 +1981,26 @@
         (when (fn? on-title-click)
           {:on-click on-title-click})))
      (cond
-       (and query? (and blank? (or advanced-query? show-query?)))
+       (and query? blank? (or advanced-query? show-query?))
        [:span.opacity-75.hover:opacity-100 "Untitled query"]
        (and query? blank?)
        (query-builder-component/builder query {})
        :else
        (text-block-title config block))
      query-setting
+     (when (ldb/class-instance?
+            (entity-plus/entity-memoized (db/get-db) :logseq.class/Cards)
+            block)
+       [(ui/tooltip
+         (shui/button
+          {:variant :ghost
+           :size :sm
+           :class "!px-1 text-xs text-muted-foreground"
+           :on-click (fn [e]
+                       (util/stop e)
+                       (state/pub-event! [:modal/show-cards (:db/id block)]))}
+          "Practice")
+         [:div "Practice cards"])])
      (when-let [property (:logseq.property/created-from-property block)]
        (when-let [message (when (= :url (:logseq.property/type property))
                             (first (outliner-property/validate-property-value (db/get-db) property (:db/id block))))]