       :as args}]
   {:pre [(validate-args-macro popover-border-args-desc args "popover-border")]}
   (let [pop-id                  (gensym "popover-")
-        rendered-once           (reagent/atom false)
+        rendered-once           (reagent/atom false)        ;; The initial render is off screen because rendering it in place does not render at final width, and we need to measure it to be able to place it properly
+        ready-to-show?          (reagent/atom false)        ;; This is used by the optimal position code to avoid briefly seeing it in its intended position before quickly moving to the optimal position
         p-width                 (reagent/atom 0)
         p-height                (reagent/atom 0)
         pop-offset              (reagent/atom 0)

                              :border        "none"})

                           ;; The popover point is zero width, therefore its absolute children will consider this width when deciding their
                           ;; natural size and in particular, how they natually wrap text. The right hand size of the popover is used as a
                           ;; text wrapping point so it will wrap, depending on where the child is positioned. The margin is also taken into
                           ;; consideration for this point so below, we set the margins to negative a lot to prevent
                           ;; this annoying wrapping phenomenon.

    :left   (if p-width (- (- p-width 25) position-offset) p-width)
    :above  (if p-height (- (- p-height 25) position-offset) p-height)))

(defn popover-clipping
  [node]
  (let [viewport-width  (.-innerWidth   js/window)    ;; Width  (in pixels) of the browser window viewport including, if rendered, the vertical   scrollbar.
        viewport-height (.-innerHeight  js/window)    ;; Height (in pixels) of the browser window viewport including, if rendered, the horizontal scrollbar.
        bounding-rect   (.getBoundingClientRect node)
        left            (.-left   bounding-rect)
        right           (.-right  bounding-rect)
        top             (.-top    bounding-rect)
        bottom          (.-bottom bounding-rect)
        clip-left       (when (< left 0) (- left))
        clip-right      (when (> right viewport-width) (- right viewport-width))
        clip-top        (when (< top 0) (- top))
        clip-bottom     (when (> bottom viewport-height) (- bottom viewport-height))]
    #_(when (or (some? clip-left) (some? clip-right) (some? clip-top) (some? clip-bottom))  ;; Return full clipping details (or nil if not clipped)
        {:left clip-left :right clip-right :top clip-top :bottom clip-bottom})
    (or (some? clip-left) (some? clip-right) (some? clip-top) (some? clip-bottom))))        ;; Return boolean

(def popover-border-args-desc
  [{:name :children        :required true                        :type "vector"           :validate-fn sequential?       :description "a vector of component markups"}
   {:name :position        :required true                        :type "keyword atom"     :validate-fn position?         :description [:span "relative to this anchor. One of " position-options-list]}
