✨ Add documentation to select on storybook

frontend/src/app/main/ui/ds/_sizes.scss

@@ -9,5 +9,6 @@
 // TODO: create actual tokens once we have them from design
 $sz-16: px2rem(16);
 $sz-32: px2rem(32);
+$sz-36: px2rem(36);
 $sz-224: px2rem(224);
 $sz-400: px2rem(400);

frontend/src/app/main/ui/ds/controls/select.cljs

@@ -19,7 +19,7 @@
 (mf/defc option*
   {::mf/props :obj
    ::mf/private true}
-  [{:keys [id label icon aria-label on-click selected on-ref focused] :rest props}]
+  [{:keys [id label icon aria-label on-click selected set-ref focused] :rest props}]
   [:> :li {:value id
            :class (stl/css-case :option true
                                 :option-with-icon (some? icon)
@@ -27,7 +27,7 @@
            :aria-selected selected
 
            :ref (fn [node]
-                  (on-ref node id))
+                  (set-ref node id))
            :role "option"
            :id id
            :on-click on-click
@@ -52,7 +52,7 @@
 (mf/defc options-dropdown*
   {::mf/props :obj
    ::mf/private true}
-  [{:keys [on-ref on-click options selected focused] :rest props}]
+  [{:keys [set-ref on-click options selected focused] :rest props}]
   (let [props (mf/spread-props props
                                {:class (stl/css :option-list)
                                 :tab-index "-1"
@@ -69,7 +69,7 @@
                       :label label
                       :icon icon
                       :aria-label aria-label
-                      :on-ref on-ref
+                      :set-ref set-ref
                       :focused (= id focused)
                       :on-click on-click}]))]))
 
@@ -158,7 +158,7 @@
         options-nodes-refs  (mf/use-ref nil)
         options-ref         (mf/use-ref nil)
 
-        on-ref
+        set-ref
         (mf/use-fn
          (fn [node id]
            (let [refs (or (mf/ref-val options-nodes-refs) #js {})
@@ -225,8 +225,8 @@
 
     [:div {:class (stl/css :select-wrapper)}
      [:> :button props
-      [:div {:class (stl/css-case :select-header true
-                                  :header-icon (some? icon))}
+      [:span {:class (stl/css-case :select-header true
+                                   :header-icon (some? icon))}
        (when icon
          [:> icon* {:id icon
                     :size "s"
@@ -242,4 +242,4 @@
                               :options options
                               :selected selected
                               :focused focused
-                              :on-ref on-ref}])]))
+                              :set-ref set-ref}])]))

frontend/src/app/main/ui/ds/controls/select.mdx

@@ -0,0 +1,63 @@
+import { Canvas, Meta } from '@storybook/blocks';
+import * as SelectStories from "./select.stories";
+
+<Meta title="Controls/Select" />
+
+# Select
+
+Select lets users choose one option from an options menu.
+
+## Variants
+
+**Text**: We will use this variant when there are enough space and icons don't add any useful context.
+
+<Canvas of={SelectStories.Default} />
+
+**Icon and text**: We will use this variant when there are enough space and icons add any useful context.
+<Canvas of={SelectStories.WithIcons} />
+
+## Technical notes
+
+### Icons
+
+Each option of `select*` may accept an `icon`, which must contain an [icon ID](../foundations/assets/icon.mdx).
+These are available in the `app.main.ds.foundations.assets.icon` namespace.
+
+
+```clj
+(ns app.main.ui.foo
+  (:require
+   [app.main.ui.ds.foundations.assets.icon :as i]))
+```
+
+```clj
+[:> select*       
+    {:options [{ :label "Code"
+                 :id "option-code"
+                 :icon i/fill-content }
+               { :label "Design"
+                 :id "option-design"
+                 :icon i/pentool }
+               { :label "Menu"
+                 :id "option-menu" } 
+               ]}]
+```
+
+<Canvas of={SelectStories.WithIcons} />
+
+## Usage guidelines (design)
+
+### Where to use
+
+Used in a wide range of applications in the app, 
+to select among available text-based options, 
+sometimes with icons that offers additional context.
+
+### When to use
+
+Consider using select when you have 5 or more options to choose from.
+
+### Interaction / Behavior
+
+When the user clicks on the clickable area, a list of 
+options appears. When an option is chosen, the list is closed.

frontend/src/app/main/ui/ds/controls/select.scss

@@ -21,6 +21,7 @@
   }
 
   @include use-typography("body-small");
+  position: relative;
   display: grid;
   grid-template-rows: auto;
   gap: var(--sp-xxs);
@@ -83,6 +84,10 @@
 
 .option-list {
   --options-dropdown-bg-color: var(--color-background-tertiary);
+  position: absolute;
+  right: 0;
+  top: $sz-36;
+  width: 100%;
   background-color: var(--options-dropdown-bg-color);
   border-radius: $br-8;
   border: $b-1 solid var(--select-dropdown-border-color);

frontend/src/app/main/ui/ds/controls/select.stories.jsx

@@ -59,7 +59,6 @@ export const WithIcons = {
       {
         label: "Menu",
         id: "option-menu",
-        icon: "mask",
       },
     ],
   },

frontend/src/app/main/ui/workspace.cljs

@@ -81,8 +81,6 @@
            (reset! palete-size size)))
 
         node-ref (use-resize-observer on-resize)]
-
-
     [:*
      (when (not hide-ui?)
        [:& palette {:layout layout