docs: add Dropdown samples

apps/docs/src/components/code/Live.tsx

@@ -13,6 +13,7 @@ import * as HvIcons from "@hitachivantara/uikit-react-icons";
 import { Toolbar } from "./Toolbar";
 
 interface LiveProps {
+  collapsed?: boolean;
   children: string;
 }
 
@@ -46,10 +47,10 @@ const generateScope = (hvComponents: string[], hvIcons: string[]) => {
   return { ...components, ...icons, theme: HvCore.theme };
 };
 
-export const Live = ({ children }: LiveProps) => {
+export const Live = ({ collapsed = false, children }: LiveProps) => {
   const [initialCode] = useState(children?.trimEnd());
   const [code, setCode] = useState(initialCode);
-  const [isExpanded, setIsExpanded] = useState(false);
+  const [isCollapsed, setIsCollapsed] = useState(collapsed);
   const editorTheme = useEditorTheme();
 
   // Extract components and icons from the code
@@ -72,19 +73,19 @@ export const Live = ({ children }: LiveProps) => {
 
       {/* Toolbar */}
       <Toolbar
-        onToggle={() => setIsExpanded(!isExpanded)}
-        isExpanded={isExpanded}
+        onToggle={() => setIsCollapsed(!isCollapsed)}
+        isCollapsed={isCollapsed}
         code={code}
         onReset={() => setCode(initialCode)}
       />
 
       {/* Code Editor */}
       <div
         className={`overflow-auto border-x-1 border-[var(--uikit-colors-atmo4)] rounded-b-round ${
-          isExpanded ? "border-b-transparent" : "border-b-1"
+          isCollapsed ? "border-b-transparent" : "border-b-1"
         }`}
         style={{
-          maxHeight: isExpanded ? "0px" : "250px",
+          maxHeight: isCollapsed ? "0px" : "250px",
           transition: "max-height 0.2s ease-in-out",
         }}
       >

apps/docs/src/components/code/Pre.tsx

@@ -5,12 +5,13 @@ import { Live } from "./Live";
 
 interface PreProps extends React.HTMLAttributes<HTMLElement> {
   live?: boolean;
+  collapsed?: boolean;
   children?: React.ReactNode;
 }
 
-export const Pre = ({ live, children, ...props }: PreProps) => {
+export const Pre = ({ live, collapsed, children, ...props }: PreProps) => {
   if (live && isValidElement(children)) {
-    return <Live {...children.props} />;
+    return <Live collapsed={collapsed} {...children.props} />;
   }
 
   return <NextraPre {...props}>{children}</NextraPre>;

apps/docs/src/components/code/Toolbar.tsx

@@ -10,14 +10,14 @@ import { HvButton, HvTooltip } from "@hitachivantara/uikit-react-core";
 
 type ToolbarProps = {
   onToggle: () => void;
-  isExpanded: boolean;
+  isCollapsed: boolean;
   code: string;
   onReset: () => void;
 };
 
 export const Toolbar = ({
   onToggle,
-  isExpanded,
+  isCollapsed,
   code,
   onReset,
 }: ToolbarProps) => {
@@ -39,7 +39,7 @@ export const Toolbar = ({
       {/* Code Toggle Button */}
       <div className="flex flex-1 justify-center items-center">
         <HvButton size="xs" variant="secondaryGhost" onClick={onToggle}>
-          {isExpanded ? (
+          {isCollapsed ? (
             <>
               Show Code <ArrowDown />
             </>

apps/docs/src/pages/components/dropdown.mdx

@@ -1,3 +1,4 @@
+import { Callout } from "nextra/components";
 import { dropdownClasses, HvDropdown } from "@hitachivantara/uikit-react-core";
 
 import Playground from "@docs/components/code/Playground";
@@ -54,6 +55,93 @@ The items in the `values` prop can be can be customized, namely with an icon or
 />
 ```
 
+### Custom dropdown
+
+<Callout type="info">
+  Please check out the [examples section](/examples/dropdowns) for more samples
+  of custom dropdowns.
+</Callout>
+
+You might need to customize the dropdown content entirely. To do this use the `HvBaseDropdown` component.
+
+```tsx live collapsed
+<HvBaseDropdown placeholder="Click to open">
+  <HvPanel>
+    <HvTypography>Your dropdown content</HvTypography>
+  </HvPanel>
+</HvBaseDropdown>
+```
+
+You might want to control yourself the dropdown and its state. In that case you should use the props `expanded` and `onToggle`.
+
+```tsx live collapsed
+import { forwardRef, useState } from "react";
+
+export default function Demo() {
+  const [popperOpen, setPopperOpen] = useState(false);
+
+  return (
+    <>
+      <HvButton onClick={() => setPopperOpen((p) => !p)}>
+        {popperOpen ? "Close" : "Open"}
+      </HvButton>
+      <HvBaseDropdown
+        variableWidth
+        expanded={popperOpen}
+        placeholder="Click to open"
+        onToggle={() => setPopperOpen((p) => !p)}
+      >
+        <HvPanel id={"myPanelId"}>
+          <HvTypography>Your dropdown content</HvTypography>
+        </HvPanel>
+      </HvBaseDropdown>
+    </>
+  );
+}
+```
+
+If you want to customize the header of the dropdown, you can use the `headerComponent` prop.
+Don't forget to forward the ref to the component. The `onToggle` callback will be called on the `onClick` event of the header component.
+
+```tsx live collapsed
+import { forwardRef, useState } from "react";
+
+const HeaderComponent = forwardRef<HTMLButtonElement, HvDropdownButtonProps>(
+  function HeaderComponent(props, ref) {
+    const { open, ...others } = props;
+    return (
+      <HvIconButton
+        ref={ref}
+        variant="primarySubtle"
+        title="Settings"
+        {...others}
+      >
+        <Settings />
+      </HvIconButton>
+    );
+  },
+);
+
+export default function Demo() {
+  const [popperOpen, setPopperOpen] = useState(false);
+
+  return (
+    <HvBaseDropdown
+      variableWidth
+      expanded={popperOpen}
+      open={popperOpen}
+      headerComponent={HeaderComponent}
+      onToggle={() => setPopperOpen((p) => !p)}
+      classes={{ panel: "rounded-round" }}
+    >
+      <HvPanel id={"myPanelId"}>
+        <HvTypography>Your dropdown content</HvTypography>
+      </HvPanel>
+    </HvBaseDropdown>
+  );
+}
+```
+
 ### Related components
 
 - [`HvFormElement`](/components/form-element)