@qyu/reactcmp-dropdown 1.2.0 → 2.0.0

package/README.md

@@ -2,34 +2,123 @@
 
 React Component Library for solving dropdown positioning problems
 
+## Purpose
+
+Library is intended as minimalistic solution for dropdown rendering
+
+It supportas:
+- Nested Dropdpowns
+- List is rendered in Portal (no issues with overflow)
+- Basic focus management (for complex cases you would need external library)
+- Basic animations with css transitions (for complex animations you would need external library)
+
 ## First include styles
 
 ```typescript
 // import styles with your bundler or copy them by hand and reference in your html
-import "@qyu/reactcmp-dropdown/style/index.global"
+import "@qyu/reactcmp-dropdown/style/index"
 // or import module and insert them directly to the component
-import stylemodule from "@qyu/reactcmp-dropdown/stlye/index.module"
+import clmap from "@qyu/reactcmp-dropdown/stlye/index"
+```
+
+## Basic usage
+
+```tsx
+import * as ddn from "qyu/reactcmp-dropdown"
+
+// will render dropdown
+function DDN(props: { children: r.Children }) {
+    // virtual container will not render any dom element, only create necessary contexts
+    // there also a Component that renders a real one
+    return <ddn.CmpContainerVirtual>
+        <ddn.CmpButton>
+            Press
+        </ddn.CmpButton>
+
+        <ddn.CmpListPortal
+            gap={5}
+            // find by id, you can pass HTLMElement directly alternatively
+            portal={"ddnportal"}
+
+            // optional
+            direction={"ver"}
+            // optional
+            align={"start"}
+            // optional
+            justify={"end"}
+        >
+            {/* Used to measure content. Required for any list */}
+            <ddn.Content>
+                {props.children}
+            </ddn.Content>
+        </ddn.CmpListPortal>
+    </ddn.CmpContainer>
+}
+
+// nested dropdowns
+function App() {
+    // if you want to render nested dropdown 
+    // - it will need its own context with <ddn.CmpContainerVirtual>
+    // therefore - this works
+    return <DDN>
+        <DDN>
+            List Content
+        </DDN>
+    </DDN>
+}
+```
+
+## Change Transition time and z-index
+
+```css
+:root {
+    --qyuddn-z-index: 3;
+    --qyuddn-trtime: 0.2s;
+}
+```
+
+## Making your custom button
+
+```tsx
+const CustomButton = function () {
+    const ref = r.useRef<HTMLButtonElement | null>(null)
+    const ctxstate_open = ddn.useCtxStateOpen()
+
+    // this will give you calculated value of wether your dropdown is open or not
+    const open = ddn.useOpenInfer({})
+
+    // this wrapper is required, it necessary events and stuff
+    return <ddn.ButtonVirtual target={ref}>
+        <button 
+            ref={ref} 
+            onClick={() => ctxstate_open.open_set(o => !o)}
+        >
+            MyButton
+        </button>
+    </ddn.ButtonVirtual>
+}
 ```
 
-## Use Dropdown
+## Usage with all properties
 
 ```tsx
 import * as ddn from "qyu/reactcmp-dropdown"
 
 function App() {
+    // it is generally recomended to use local state instead of declaring it here
     const [open, open_set] = r.useState(false)
 
     return <ddn.CmpContainer 
         // optional, will be added to other styles
         className={""}
         // here you can insert styles in modular form
-        stylemodule={stylemodule}
+        clmap={clmap}
 
         // optional, will use local state if not provided
         open={open}
         open_set={open_set}
 
-        // on which events should close the dropdown
+        // on which events should close the dropdown {CloseEvt_ConfigFull}
         // optional, all true by default
         closeevents={{ 
             // focus going outside the container
@@ -43,49 +132,53 @@ function App() {
             // press escape
             escape: true,
         }}
+
+        // focus controls {Focus_Config}
+        // optional, default values below
+        focus={{
+            // should capture focus
+            capture: true,
+            // focus options
+            capture_options: { preventScroll: true },
+            // should restore focus
+            restore: true,
+            // focus options
+            restore_options: { preventScroll: true },
+        }}
+
+        // customize rendered element
+        render_view={props => <div {...props} />}
     >
-        {/* You would often want to imlement you own button. See futher */}
-        <ddn.CmpButton className={""}>
+        <ddn.CmpButton 
+            className={""}
+            disabled={false}
+            render_view={props => <button {...props} />}
+
+            // if it should be the element list position is based around
+            // if unset - applies automatically depending on the context (true for virtual container, false otherwise)
+            isroot={false}
+        >
             Press
         </ddn.CmpButton>
 
-        <ddn.CmpListAbs
-            tabIndex={0}
+        {/* ListPortal renders inside a portal with position: fixed */}
+        {/* There also ListAbs and ListFix. They share most of the properties. */}
+        <ddn.CmpListPortal
             className={""}
-            stylemodule={stylemodule}
-
-            // do not render children when hidden, default if false
-            lazy
-
-            // add gap between button and list, in pixels
-            gap={5}
-
-            // inverse direction default if "ver"
-            direction
-            // set direction directly
-            direction={"hor" || "ver"}
+            clmap={clmap}
+            clmap_content={clmap}
+            render_view={props => <div {...props} />}
 
-            // inverse align default is "start"
-            align
-            // set align directly
-            align={"start" || "end" || "center"}
-
-            // inverse justify default is "end"
-            justify
-            // set justify directly
-            jystify={"end" || "start"}
-        >
-            Your Content Here
-        </ddn.CmpListAbs>
+            // specify the portal
+            portal={"domid"}
+            portal={document.getElementById("domid")}
 
-        {/* Same as CmpListAbs, but uses fixed positioning */}
-        <ddn.CmpListFix
-            tabIndex={0}
-            className={""}
-            stylemodule={stylemodule}
+            // disable types of transitions, default is false
+            transition_nopos={false}
+            transition_nosize={false}
 
-            // do not render children when hidden, default if false
-            lazy
+            // do not render children when hidden, default is true
+            lazy={true}
 
             // add gap between button and list, in pixels
             gap={5}
@@ -103,42 +196,47 @@ function App() {
             // inverse justify default is "end"
             justify
             // set justify directly
-            jystify={"end" || "start"}
-
-            // when string - finds portal by id
-            // when HTMLElement - uses element for portal
-            portal={"dropdowns" || document.getElementById("dropdowns")}
+            justify={"end" || "start"}
+
+            // recalculate position on, optional
+            // default values shown below
+            rearrange={{
+                // {any[] | undefined}
+                deps: undefined,
+                // rearrange when list is opened
+                open: true,
+                // rearrange on scroll
+                scroll: true,
+                // rearrange on window resize
+                resize: true,
+                // rearrange every animation frame
+                // if you need to use it - you are probably doing something wrong
+                polling: false,
+            }}
+
+            // when visibility changes
+            event_visibility_chage={(visible: boolean) => {}}
+            // when transition status changes
+            event_transition_change={(property: string, active: true) => {}}
         >
-            Your Content Here
-        </ddn.CmpListFix>
+            {/* Used to measure content. Required for any list */}
+            <ddn.Content
+                clmap={clmap}
+                className={""}
+                render_view={props => <div {...props} />}
+
+                // dont render focusguards, false by default
+                focus_noguards={false}
+            >
+                Your Content Here
+            </ddn.Content>
+
+            {() => {
+                return <ddn.Content>
+                    Your Content Here
+                </ddn.Content>
+            }}
+        </ddn.CmpListPortal>
     </ddn.CmpContainer>
 }
 ```
-
-## Making your custom button
-
-```tsx
-export const CmpButton = () => {
-    // just listen to the context state
-    const ctxstate = r.useContext(CmpCtxState_Open)
-
-    if (!ctxstate) { throw new Error(`Using DropdownStateOpen dependend component outside of DropdownStateOpen Context`) }
-
-    return <button
-        onClick={() => {
-            ctxstate.open_set(t => !t)
-        }}
-    >
-        Press
-    </button>
-}
-```
-
-## Change Transition time and z-index
-
-```css
-:root {
-    --qyuddn-z-index: 3;
-    --qyuddn-trtime: 0.2s;
-}
-```