[nested-grid] Document some props

src/re_com/nested_grid.cljs

@@ -3,13 +3,121 @@
    [clojure.string :as str]
    [re-com.util :as u :refer [px deref-or-value]]
    [reagent.core :as r]
+   [re-com.config      :refer [debug? include-args-desc?]]
+   [re-com.validate    :refer [vector-atom? ifn-or-nil? map-atom? parts? part?]]
    [re-com.theme :as theme]
    [re-com.box :as box]
    [re-com.buttons :as buttons]))
 
-(def nested-grid-args-desc {})
 (def nested-grid-parts-desc {})
 
+(def nested-grid-parts
+  (when include-args-desc?
+    (-> (map :name nested-grid-parts-desc) set)))
+
+(def nested-grid-args-desc
+  (when include-args-desc?
+    [{:name :cell
+      :default "constantly nil"
+      :type "part"
+      :validate-fn part?
+      :description
+      [:span "String, hiccup or function. When a function, acceps keyword args "
+       [:code ":column-path"] " and " [:code ":row-path"]
+       ". Returns either a string or hiccup, which will appear within a single grid cell."]}
+     {:name :column-tree
+      :default "[]"
+      :type "vector or seq of column-specs or column-trees"
+      :validate-fn seq?
+      :description
+      [:span "Describes a nested arrangement of " [:code ":column-spec"] "s. "
+       "A spec's path derives from its depth within the hierarchy of vectors or seqs. "
+       " When a non-vector A precedes a vector B, then the items of B are children of A."
+       " When a non-vector C follows B, then C is a sibling of A."
+       " This nesting can be arbitrarily deep."]}
+     {:name :row-tree
+      :default "[]"
+      :type "vector or seq of row-specs or row-trees"
+      :validate-fn seq?
+      :description
+      [:span "Describes a nested arrangement of " [:code ":row-spec"] "s. "
+       "A spec's path derives from its depth within the hierarchy of vectors or seqs. "
+       " When a non-vector A precedes a vector B, then the items of B are children of A."
+       " When a non-vector C follows B, then C is a sibling of A."
+       " This nesting can be arbitrarily deep."]}
+     {:name :column-header
+      :type "part"
+      :validate-fn part?
+      :description
+      [:span "A string, hiccup, or function of " [:code "{:keys [column-path]}"] "."
+       " By default, returns the " [:code ":label"] ", " [:code ":id"]
+       ", or else a string of the entire value of the last item in "
+       [:code ":column-path"] "."]}
+     {:name :row-header
+      :type "part"
+      :validate-fn part?
+      :description
+      [:span "A string, hiccup, or function of " [:code "{:keys [row-path]}"] "."
+       " By default, returns the " [:code ":label"] ", " [:code ":id"]
+       ", or else a string of the entire value of the last item in "
+       [:code ":row-path"] "."]}
+     {:name :cell-wrapper
+      :type "part"
+      :validate-fn part?
+      :description
+      [:span "A wrapper div, responsible for positioning one " [:code ":cell"]
+       " within the css grid."]}
+     {:name :column-header-wrapper
+      :type "part"
+      :validate-fn part?
+      :description
+      [:span "A wrapper div, responsible for positioning one " [:code ":column-header"]
+       " within the css grid."]}
+     {:name :row-header-wrapper
+      :type "part"
+      :validate-fn part?
+      :description
+      [:span "A wrapper div, responsible for positioning one " [:code ":row-header"]
+       " within the css grid."]}
+     {:name :header-spacer-wrapper
+      :type "part"
+      :validate-fn part?
+      :description
+      [:span "A wrapper responsible for positioning one " [:code ":header-spacer"]
+       " within the css grid."]}
+
+     {:name :row-height                 :required true                 :type "integer"                     :validate-fn number?                :description "px height of each row, in sections 2, 5 and 8."}
+     {:name :row-height                 :required true                 :type "integer"                     :validate-fn number?                :description "px height of each row, in sections 2, 5 and 8."}
+     {:name :column-header-height       :required false                :type "integer"                     :validate-fn number?                :description "px height of the column header. Impacts the upper sections 1, 4 and 7. If not provided, defaults to 0, meaning these three sections will not be visible."}
+     {:name :column-footer-height       :required false                :type "integer"                     :validate-fn number?                :description "px height of the column footer. Impacts the lower sections 3, 6 and 9. If not provided, defaults to 0, meaning these three sections will not be visible."}
+     {:name :row-content-width          :required true                 :type "integer"                     :validate-fn number?                :description [:span "px width of sections 4, 5, 6. The renderers for these sections are expected to return hiccup to fill these spaces."]}
+     {:name :max-width                  :required false                :type "string"                      :validate-fn string?                :description "Standard CSS max-width setting of the entire table. If not provided, table will fill available space"}
+
+     {:name :top-left-renderer          :required false                :type "-> hiccup"                   :validate-fn fn?                    :description [:span "A function taking no args which returns the hiccup for the top left (section 1). The hiccup should fill the height specified via "  [:code ":column-header-height"] ". The width of the three left sections is self-determined as the maximum of their own content."]}
+     {:name :row-header-renderer        :required false                :type "row-index, row -> hiccup"    :validate-fn fn?                    :description [:span "A function. Given the 0-based row-index and an element of " [:code ":model"] ", it will return the hiccup for the row header (section 2)."]}
+     {:name :bottom-left-renderer       :required false                :type "-> hiccup"                   :validate-fn fn?                    :description "A function taking no args which returns the hiccup for the bottom left (section 3)"}
+     {:name :column-header-renderer     :required false                :type "-> hiccup"                   :validate-fn fn?                    :description "A function taking no args which returns the hiccup for the column header (section 4)."}
+     {:name :row-renderer               :required true                 :type "row-index, row -> hiccup"    :validate-fn fn?                    :description [:span "A function. Given the 0-based row-index and an element of " [:code ":model"] ", it will return the hiccup for a single content row (section 5). This renderer is called once for each displayed row. As vertical scrolling occurs, more calls will be made."]}
+     {:name :column-footer-renderer     :required false                :type "-> hiccup"                   :validate-fn fn?                    :description "A function taking no args which returns the hiccup for the entire column footer (section 6)."}
+     {:name :top-right-renderer         :required false                :type "-> hiccup"                   :validate-fn fn?                    :description "A function taking no args which returns the hiccup for the top right (section 7)"}
+     {:name :row-footer-renderer        :required false                :type "row-index, row -> hiccup"    :validate-fn fn?                    :description [:span "A function. Given the 0-based row-index and an element of " [:code ":model"] ", it will return the hiccup for the row footer (section 8)."]}
+     {:name :bottom-right-renderer      :required false                :type "-> hiccup"                   :validate-fn fn?                    :description "A function taking no args which returns the hiccup for the bottom right (section 9)."}
+
+     {:name :row-header-selection-fn    :required false                :type "(5 args) -> "                :validate-fn fn?                    :description "See v-table docstring for arg details. If present, this function will be called on mouse-down, mouse-move and mouse-up events, allowing you to capture user selection of cells, columns or rows in section 2."}
+     {:name :column-header-selection-fn :required false                :type "(5 args) -> "                :validate-fn fn?                    :description "See v-table docstring for arg details. If present, this function will be called on mouse-down, mouse-move and mouse-up events, allowing you to capture user selection of cells, columns or rows in section 4."}
+     {:name :row-selection-fn           :required false                :type "(5 args) -> "                :validate-fn fn?                    :description "See v-table docstring for arg details. If present, this function will be called on mouse-down, mouse-move and mouse-up events, allowing you to capture user selection of cells, columns or rows in section 5."}
+
+     {:name :row-viewport-width         :required false                :type "integer"                     :validate-fn number?                :description "px width of the row viewport area (section 5). If not specified, the component takes all the horizontal space available."}
+     {:name :row-viewport-height        :required false                :type "integer"                     :validate-fn number?                :description "px height of the row viewport area (section 5). If not specified,the component takes all the vertical space available."}
+     {:name :max-row-viewport-height    :required false                :type "integer"                     :validate-fn number?                :description [:span "The " [:b [:i "maximum"]] " px height of the row viewport area (section 5), excluding height of sections 4 and 6 (and horizontal scrollbar). If not specified, value determined by parent height and number of rows"]}
+     {:name :scroll-rows-into-view      :required false                :type "atom containing map"         :validate-fn map-atom?              :description [:span "Scrolls the table to a particular row range. Must be an atom. The map contains the keys " [:code ":start-row"] " and " [:code ":end-row"] " (row indexes)."]}
+     {:name :scroll-columns-into-view   :required false                :type "atom containing map"         :validate-fn map-atom?              :description [:span "Scrolls the table of a particular column range. Must be an atom. Map that contains the keys " [:code ":start-col"] " and " [:code ":end-col"]  " in pixel units."]}
+     {:name :remove-empty-row-space?    :required false :default true  :type "boolean"                                                         :description "If true, removes whitespace between the last row and the horizontal scrollbar. Useful for tables without many rows where otherwise there would be a big gap between the last row and the horizontal scrollbar at the bottom of the available space."}
+     {:name :class                      :required false                :type "string"                      :validate-fn string?                :description "CSS class names, space separated (these are applied to the table's outer container)"}
+     {:name :parts                      :required false                :type "map"                         :validate-fn (parts? nested-grid-parts) :description "See Parts section below."}
+     {:name :src                        :required false                :type "map"                         :validate-fn map?                   :description [:span "Used in dev builds to assist with debugging. Source code coordinates map containing keys" [:code ":file"] "and" [:code ":line"]  ". See 'Debugging'."]}
+     {:name :debug-as                   :required false                :type "map"                         :validate-fn map?                   :description [:span "Used in dev builds to assist with debugging, when one component is used implement another component, and we want the implementation component to masquerade as the original component in debug output, such as component stacks. A map optionally containing keys" [:code ":component"] "and" [:code ":args"] "."]}]))
+
 (defn descendant? [path-a path-b]
   (and (not= path-a path-b)
        (= path-a (vec (take (count path-a) path-b)))))

src/re_com/validate.cljs

@@ -485,6 +485,13 @@
   [arg]
   (or (nil? arg) (ifn? arg)))
 
+(def hiccup? vector?)
+
+(defn part?
+  "Returns true if the passed argument is a part, otherwise false/error"
+  [arg]
+  (or (string-or-hiccup? arg) (ifn-or-nil? arg)))
+
 ;; Test for atoms containing specific data types
 ;; NOTE: These "test for atom" validation functions use the 2-arity option where the validation mechanism passes the value
 ;;       of the arg as with the 1-arity version (derefed with peek) but also a boolean (arg-is-atom?) showing whether

src/re_demo/nested_grid.cljs

@@ -118,7 +118,7 @@
       [:li "Uses" " " [:a {:href "https://www.w3schools.com/css/css_grid.asp"} "css grid"]
        " " "for layout."]
       [:li "Has adjustible column & row widths."]
-      [:li "Is optimized for tens or hundreds of rows, not millions."]
+      [:li "Is optimized for hundreds of cells, not millions."]
       [:li "Does not virtualize rows (" [:span {:style {:color "red"}} "...yet"] ")."
        " It renders everything in a single pass."]
       [:li "Does not re-render when you scroll or click. Even if that first render is expensive, "
@@ -534,7 +534,6 @@
      "), we only store a " [:code ":width"] " key. "
      "Each column header has a draggable button, allowing you to update a column's width by hand."]]])
 
-;; core holds a reference to panel, so need one level of indirection to get figwheel updates
 (defn panel
   []
   (let [tabs [{:id :intro :label "Introduction" :view intro-column}