Skip to content

Commit 9a47ba8

Browse files
kimo-kkimo-k
committed
[nested-grid] Document some props
1 parent 723db57 commit 9a47ba8

File tree

3 files changed

+167
-7
lines changed

3 files changed

+167
-7
lines changed

‎src/re_com/nested_grid.cljs

+159-5
Original file line numberDiff line numberDiff line change
@@ -3,13 +3,164 @@
33
[clojure.string :as str]
44
[re-com.util :as u :refer [px deref-or-value]]
55
[reagent.core :as r]
6+
[re-com.config :refer [debug? include-args-desc?]]
7+
[re-com.validate :refer [vector-atom? ifn-or-nil? map-atom? parts? part?]]
68
[re-com.theme :as theme]
79
[re-com.box :as box]
810
[re-com.buttons :as buttons]))
911

10-
(def nested-grid-args-desc {})
1112
(def nested-grid-parts-desc {})
1213

14+
(def nested-grid-parts
15+
(when include-args-desc?
16+
(-> (map :name nested-grid-parts-desc) set)))
17+
18+
(def nested-grid-args-desc
19+
(when include-args-desc?
20+
[{:name :cell
21+
:default "constantly nil"
22+
:type "part"
23+
:validate-fn part?
24+
:description
25+
[:span "String, hiccup or function. When a function, acceps keyword args "
26+
[:code ":column-path"] " and " [:code ":row-path"]
27+
". Returns either a string or hiccup, which will appear within a single grid cell."]}
28+
{:name :column-tree
29+
:default "[]"
30+
:type "vector or seq of column-specs or column-trees"
31+
:validate-fn seq?
32+
:description
33+
[:span "Describes a nested arrangement of " [:code ":column-spec"] "s. "
34+
"A spec's path derives from its depth within the hierarchy of vectors or seqs. "
35+
" When a non-vector A precedes a vector B, then the items of B are children of A."
36+
" When a non-vector C follows B, then C is a sibling of A."
37+
" This nesting can be arbitrarily deep."]}
38+
{:name :row-tree
39+
:default "[]"
40+
:type "vector or seq of row-specs or row-trees"
41+
:validate-fn seq?
42+
:description
43+
[:span "Describes a nested arrangement of " [:code ":row-spec"] "s. "
44+
"A spec's path derives from its depth within the hierarchy of vectors or seqs. "
45+
" When a non-vector A precedes a vector B, then the items of B are children of A."
46+
" When a non-vector C follows B, then C is a sibling of A."
47+
" This nesting can be arbitrarily deep."]}
48+
{:name :column-header
49+
:type "part"
50+
:validate-fn part?
51+
:description
52+
[:span "A string, hiccup, or function of " [:code "{:keys [column-path]}"] "."
53+
" By default, returns the " [:code ":label"] ", " [:code ":id"]
54+
", or else a string of the entire value of the last item in "
55+
[:code ":column-path"] "."]}
56+
{:name :row-header
57+
:type "part"
58+
:validate-fn part?
59+
:description
60+
[:span "A string, hiccup, or function of " [:code "{:keys [row-path]}"] "."
61+
" By default, returns the " [:code ":label"] ", " [:code ":id"]
62+
", or else a string of the entire value of the last item in "
63+
[:code ":row-path"] "."]}
64+
{:name :cell-wrapper
65+
:type "part"
66+
:validate-fn part?
67+
:description
68+
[:span "A wrapper div, responsible for positioning one " [:code ":cell"]
69+
" within the css grid."]}
70+
{:name :column-header-wrapper
71+
:type "part"
72+
:validate-fn part?
73+
:description
74+
[:span "A wrapper div, responsible for positioning one " [:code ":column-header"]
75+
" within the css grid."]}
76+
{:name :row-header-wrapper
77+
:type "part"
78+
:validate-fn part?
79+
:description
80+
[:span "A wrapper div, responsible for positioning one " [:code ":row-header"]
81+
" within the css grid."]}
82+
{:name :header-spacer-wrapper
83+
:type "part"
84+
:validate-fn part?
85+
:description
86+
[:span "A wrapper responsible for positioning one " [:code ":header-spacer"]
87+
" within the css grid."]}
88+
{:name :show-branch-paths?
89+
:type "boolean"
90+
:default "false"
91+
:validate-fn boolean?
92+
:description
93+
[:span "When " [:code "true"] ", displays cells and headers for all "
94+
[:code ":column-paths"] " and " [:code ":row-paths"] ", not just the leaf paths."]}
95+
{:name :max-height
96+
:required false
97+
:type "string"
98+
:validate-fn string?
99+
:description "standard CSS max-height setting of the entire grid. Literally constrains the grid to the given width so that if the grid is taller than this it will add scrollbars. Ignored if value is larger than the combined width of all the rendered grid rows."}
100+
{:name :max-width
101+
:required false
102+
:type "string"
103+
:validate-fn string?
104+
:description
105+
[:span "standard CSS max-width setting of the entire grid. "
106+
"Literally constrains the grid to the given width so that "
107+
"if the grid is wider than this it will add scrollbars."
108+
" Ignored if value is larger than the combined width of all the rendered grid columns."]}
109+
{:name :column-header-height
110+
:default 30
111+
:type "number"
112+
:validate-fn number?
113+
:description
114+
[:span "The default height that a column-header will use. "
115+
"Can be overridden by a " [:code ":height"] "key in the "
116+
[:code ":column-spec"] ", or by component-local state."]}
117+
{:name :column-width
118+
:default 30
119+
:type "number"
120+
:validate-fn number?
121+
:description
122+
[:span "The default width that a column of grid cells will use. "
123+
"Can be overridden by a " [:code ":height"] "key in the "
124+
[:code ":column-spec"] ", or by component-local state."]}
125+
{:name :row-header-width
126+
:default 30
127+
:type "number"
128+
:validate-fn number?
129+
:description
130+
[:span "The default width that a row-header will use. "
131+
"Can be overridden by a " [:code ":width"] "key in the "
132+
[:code ":row-spec"] ", or by component-local state."]}
133+
{:name :row-width
134+
:default 30
135+
:type "number"
136+
:validate-fn number?
137+
:description
138+
[:span "The default width that a row of grid cells will use. "
139+
"Can be overridden by a " [:code ":width"]
140+
"key in the " [:code ":row-spec"] ", or by component-local state."]}
141+
{:name :show-export-button?
142+
:required false
143+
:default false
144+
:type "boolean"
145+
:description
146+
[:span "When non-nil, adds a hiccup of " [:code ":export-button-render"]
147+
" to the component tree."]}
148+
{:name :show-export-button?
149+
:required false
150+
:default false
151+
:type "boolean"
152+
:description
153+
[:span "When non-nil, adds a hiccup of " [:code ":export-button-render"]
154+
" to the component tree."]}
155+
{:name :on-export
156+
:required false
157+
:type "function"
158+
:validate-fn ifn?
159+
:description
160+
[:span "Called whenever the export button is clicked."
161+
" Expects keyword arguments "
162+
[:code ":header-rows"] " and " [:code ":main-rows"] "."]}]))
163+
13164
(defn descendant? [path-a path-b]
14165
(and (not= path-a path-b)
15166
(= path-a (vec (take (count path-a) path-b)))))
@@ -321,8 +472,9 @@
321472
on-resize-cell (fn [{:keys [distance path]}]
322473
(swap! column-state update-in [path :width]
323474
#(+ distance (or % (column-header-prop path :width column-width)))))]
324-
(fn [& {:keys [column-tree row-tree cell
325-
cell-wrapper column-header-wrapper column-header row-header row-header-wrapper header-spacer-wrapper header-spacer
475+
(fn [& {:keys [column-tree row-tree
476+
cell column-header row-header header-spacer
477+
cell-wrapper column-header-wrapper row-header-wrapper header-spacer-wrapper
326478
show-branch-paths?
327479
max-height column-width column-header-height row-header-width row-height
328480
show-export-button? on-export on-export-success on-export-failure
@@ -408,7 +560,7 @@
408560
(map add-padding)
409561
(map add-cell-values)
410562
(map render-row-headers))))
411-
default-on-export (fn default-on-export [header-rows main-rows]
563+
default-on-export (fn default-on-export [{:keys [header-rows main-rows]}]
412564
(->> (concat header-rows main-rows)
413565
(map u/tsv-line)
414566
str/join
@@ -430,7 +582,9 @@
430582
:on-export
431583
(fn [_] (let [header-rows (get-header-rows)
432584
main-rows (get-main-rows)]
433-
((or on-export default-on-export) header-rows main-rows)
585+
((or on-export default-on-export)
586+
{:header-rows header-rows
587+
:main-rows main-rows})
434588
(when on-export-success (on-export-success header-rows main-rows))))}]
435589
grid-container
436590
[:div {:on-scroll #(do (reset! scroll-top (.-scrollTop (.-target %)))

‎src/re_com/validate.cljs

+7
Original file line numberDiff line numberDiff line change
@@ -485,6 +485,13 @@
485485
[arg]
486486
(or (nil? arg) (ifn? arg)))
487487

488+
(def hiccup? vector?)
489+
490+
(defn part?
491+
"Returns true if the passed argument is a part, otherwise false/error"
492+
[arg]
493+
(or (string-or-hiccup? arg) (ifn-or-nil? arg)))
494+
488495
;; Test for atoms containing specific data types
489496
;; NOTE: These "test for atom" validation functions use the 2-arity option where the validation mechanism passes the value
490497
;; 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

+1-2
Original file line numberDiff line numberDiff line change
@@ -118,7 +118,7 @@
118118
[:li "Uses" " " [:a {:href "https://www.w3schools.com/css/css_grid.asp"} "css grid"]
119119
" " "for layout."]
120120
[:li "Has adjustible column & row widths."]
121-
[:li "Is optimized for tens or hundreds of rows, not millions."]
121+
[:li "Is optimized for hundreds of cells, not millions."]
122122
[:li "Does not virtualize rows (" [:span {:style {:color "red"}} "...yet"] ")."
123123
" It renders everything in a single pass."]
124124
[:li "Does not re-render when you scroll or click. Even if that first render is expensive, "
@@ -534,7 +534,6 @@
534534
"), we only store a " [:code ":width"] " key. "
535535
"Each column header has a draggable button, allowing you to update a column's width by hand."]]])
536536

537-
;; core holds a reference to panel, so need one level of indirection to get figwheel updates
538537
(defn panel
539538
[]
540539
(let [tabs [{:id :intro :label "Introduction" :view intro-column}

0 commit comments

Comments
 (0)