@bronzelabs/oakma-ui 0.0.1

package/src/components/Dropdown/Dropdown.stories.tsx

@@ -0,0 +1,419 @@
+import React from "react"
+
+// Components
+import Dropdown, { type DropdownProps } from "./Dropdown"
+import AsyncDropdown from "./AsyncDropdown"
+
+// Types
+import type { Meta, StoryFn } from "@storybook/react-webpack5"
+import { TEXT_FIELD_SIZES } from "../TextField"
+
+// Utils
+import { DummyPhoneIcon, StorybookActionButton } from "../../../.storybook/components"
+import extraDocs from "./Dropdown.docs.md"
+import { renderDocsWithProps } from "../../../.storybook/utils"
+
+const mockOptions = {
+  default: [
+    {
+      label: "Apple 🍎",
+      value: "apple",
+    },
+    {
+      label: "Banana 🍌",
+      value: "banana",
+    },
+    {
+      label: "Watermelon 🍉",
+      value: "watermelon",
+    },
+  ],
+  grouped: [
+    {
+      label: "Sweets",
+      options: [
+        {
+          label: "Chocolate 🍫",
+          value: "chocolate",
+        },
+      ],
+    },
+    {
+      label: "Fruit",
+      options: [
+        {
+          label: "Banana 🍌",
+          value: "banana",
+        },
+        {
+          label: "Watermelon 🍉",
+          value: "watermelon",
+        },
+      ],
+    },
+  ],
+  reset: [
+    {
+      label: "None",
+      value: null,
+    },
+    {
+      label: "Apple 🍎",
+      value: "apple",
+    },
+    {
+      label: "Banana 🍌",
+      value: "banana",
+    },
+    {
+      label: "Watermelon 🍉",
+      value: "watermelon",
+    },
+  ],
+  long: [
+    {
+      label: "Germany 🇩🇪",
+      value: "de",
+    },
+    {
+      label: "The United Kingdom Of Great Britain And Northern Ireland 🇬🇧 ",
+      value: "uk",
+    },
+    {
+      label: "France 🇫🇷",
+      value: "fr",
+    },
+  ],
+  subTitle: [
+    {
+      label: "Photo ID",
+      value: "photo-id",
+      subTitle: "Passport, driver's license, or national ID card",
+    },
+    {
+      label: "Proof of Address",
+      value: "proof-of-address",
+      subTitle: "Utility bill, bank statement, or government correspondence",
+    },
+  ],
+  users: [
+    {
+      label: "John Doe",
+      value: "john-doe",
+    },
+    {
+      label: "Jane Smith",
+      value: "jane-smith",
+    },
+    {
+      label: "Bob Johnson",
+      value: "bob-johnson",
+    },
+  ],
+}
+
+/*
+
+
+
+
+*/
+
+const meta: Meta<DropdownProps> = {
+  title: "Components/Dropdown",
+  component: Dropdown,
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "Dropdown is a fancy select/combobox built on top of [react-select](https://react-select.com), that can be used to select a value from a list.\n\nThe main (and Oakma specific) props can be seen below, however, a full list of accepted props can be found in the react-select [docs](https://react-select.com/props). For details on how to use the component with `react-hook-form` see [here](#usage-with-react-hook-form).",
+      },
+      page: renderDocsWithProps({ extraDocs }),
+    },
+    controls: {
+      exclude: ["className", "ref", "children"],
+    },
+  },
+  argTypes: {
+    options: {
+      type: {
+        name: "other",
+        value: "(Option | Group)[]",
+      },
+      description: "Array of options that populate the Dropdown menu.",
+      table: {
+        type: {
+          summary: "(Option | Group)[]",
+        },
+        defaultValue: {
+          summary: "undefined",
+        },
+      },
+    },
+    label: {
+      type: "string",
+      description: "Visible label rendered above the Dropdown.",
+      table: {
+        type: { summary: "string" },
+      },
+    },
+    size: {
+      type: "string",
+      description: "Determines the size of the Dropdown field.",
+      table: {
+        type: { summary: TEXT_FIELD_SIZES.map(size => `"${size}"`).join(" | ") },
+        defaultValue: { summary: '"md"' },
+      },
+      options: TEXT_FIELD_SIZES,
+      control: { type: "select" },
+    },
+    leadingIcon: {
+      type: {
+        name: "other",
+        value: "{ icon: ReactNode }",
+      },
+      description:
+        "An object with an `icon` property containing a React node to render inside the field, aligned to the left.",
+      table: {
+        type: {
+          summary: "{ icon: ReactNode }",
+        },
+        defaultValue: {
+          summary: "undefined",
+        },
+      },
+    },
+    showOptional: {
+      type: "boolean",
+      description:
+        'When `true`, and if the `required` prop is not set, an "Optional" tag will be displayed next to the label.',
+      table: {
+        type: { summary: "boolean" },
+        defaultValue: { summary: "true" },
+      },
+    },
+    isLoading: {
+      type: "boolean",
+      description: "Is the Dropdown in a state of loading (async).",
+      table: {
+        type: {
+          summary: "boolean",
+        },
+        defaultValue: {
+          summary: "false",
+        },
+      },
+    },
+    isMulti: {
+      type: "boolean",
+      description: "Support multiple selected options.",
+      table: {
+        type: {
+          summary: "boolean",
+        },
+        defaultValue: {
+          summary: "false",
+        },
+      },
+    },
+    isDisabled: {
+      type: "boolean",
+      description: "Is the Dropdown disabled.",
+      table: {
+        type: {
+          summary: "boolean",
+        },
+        defaultValue: {
+          summary: "false",
+        },
+      },
+    },
+    isClearable: {
+      type: "boolean",
+      description: "Is the Dropdown value clearable.",
+      table: {
+        type: {
+          summary: "boolean",
+        },
+        defaultValue: {
+          summary: "false",
+        },
+      },
+    },
+  },
+  args: {
+    label: "Label",
+    showOptional: true,
+    size: "md",
+    required: false,
+  },
+  decorators: [
+    Story => (
+      <div style={{ width: 450, height: 300 }}>
+        <Story />
+      </div>
+    ),
+  ],
+}
+
+//
+const Template: StoryFn<DropdownProps> = args => <Dropdown {...args} />
+
+const RequiredTemplate: StoryFn<DropdownProps> = args => (
+  <form
+    className="flex flex-col items-stretch gap-3"
+    onSubmit={e => {
+      e.preventDefault()
+      alert("Form submitted!")
+    }}
+  >
+    <Dropdown {...args} />
+    <StorybookActionButton type="submit">Submit</StorybookActionButton>
+  </form>
+)
+
+const mockLoadOptions = (inputValue: string) =>
+  new Promise<(typeof mockOptions.users)[number][]>(resolve => {
+    setTimeout(() => {
+      resolve(
+        mockOptions.users.filter(opt => opt.label.toLowerCase().includes(inputValue.toLowerCase())),
+      )
+    }, 600)
+  })
+
+const AsyncTemplate: StoryFn<DropdownProps> = args => (
+  <AsyncDropdown
+    id="async-dropdown"
+    label={args.label}
+    showOptional={args.showOptional}
+    size={args.size}
+    loadOptions={mockLoadOptions}
+    defaultOptions={mockOptions.users}
+    placeholder="Search users…"
+  />
+)
+
+const MultiSelectTemplate: StoryFn = () => {
+  return (
+    <p className="text-center text-base">
+      The{" "}
+      <code
+        className="inline rounded-sm p-0.5"
+        style={{ backgroundColor: "#f0f0f0", color: "#333", fontSize: 15 }}
+      >
+        isMulti
+      </code>{" "}
+      prop is not supported in the{" "}
+      <code
+        className="inline rounded-sm p-0.5"
+        style={{ backgroundColor: "#f0f0f0", color: "#333", fontSize: 15 }}
+      >
+        Dropdown
+      </code>{" "}
+      component. For multi-select functionality, use the{" "}
+      <a
+        href="/?path=/docs/components-multiselect--docs"
+        className="text-blue-primary inline rounded-sm p-0.5 hover:underline focus-visible:underline"
+        style={{
+          fontFamily: "monospace",
+          color: "#0000ff",
+          backgroundColor: "#f0f0f0",
+          fontSize: 15,
+        }}
+      >
+        {"<MultiSelect/>"}
+      </a>{" "}
+      component instead.
+    </p>
+  )
+}
+
+const Default = Template.bind({})
+const Subtitle = Template.bind({})
+const Grouped = Template.bind({})
+const LongOption = Template.bind({})
+const WithLeadingIcon = Template.bind({})
+const Async = AsyncTemplate.bind({})
+const Required = RequiredTemplate.bind({})
+const MultiSelect = MultiSelectTemplate.bind({})
+
+Default.args = {
+  options: mockOptions.default,
+}
+
+Grouped.args = {
+  options: mockOptions.grouped,
+}
+
+LongOption.args = {
+  options: mockOptions.long,
+}
+
+WithLeadingIcon.args = {
+  options: mockOptions.default,
+  leadingIcon: { icon: <DummyPhoneIcon className="size-5" /> },
+}
+
+Required.args = {
+  options: mockOptions.default,
+  required: true,
+}
+
+Subtitle.args = {
+  options: mockOptions.subTitle,
+}
+
+// Parameters
+Subtitle.parameters = {
+  docs: {
+    description: {
+      story:
+        "Options can include a `subTitle` string to provide additional context below the label.",
+    },
+  },
+}
+
+Grouped.parameters = {
+  docs: {
+    description: {
+      story: "Options can be grouped under labelled headings by passing an array of group objects.",
+    },
+  },
+}
+
+LongOption.parameters = {
+  docs: {
+    description: {
+      story: "Long option labels wrap naturally within the menu without truncation.",
+    },
+  },
+}
+
+WithLeadingIcon.parameters = {
+  docs: {
+    description: {
+      story: "The `leadingIcon` prop renders an icon inside the field, aligned to the left.",
+    },
+  },
+}
+
+Async.parameters = {
+  docs: {
+    description: {
+      story:
+        "Use `AsyncDropdown` when options are fetched remotely. Pass a `loadOptions` function that takes the current input string and returns a promise of options. `defaultOptions` populates the list before the user types.",
+    },
+  },
+}
+
+Required.parameters = {
+  docs: {
+    description: {
+      story:
+        'Setting `required` hides the "Optional" tag and marks the field as required. The form will not submit until a value is selected.',
+    },
+  },
+}
+
+export { Default, Subtitle, Grouped, LongOption, WithLeadingIcon, Async, Required, MultiSelect }
+export default meta

package/src/components/Dropdown/Dropdown.tsx

@@ -0,0 +1,104 @@
+"use client"
+
+import React from "react"
+
+// Components
+import { Container, ErrorMessage, Label } from "../TextField"
+import ReactSelect from "react-select"
+
+// Types
+import type { DropdownSharedProps } from "./types"
+
+// Utils
+import { useDropdown } from "./useDropdown"
+
+// Params
+type SelectProps = React.ComponentPropsWithRef<typeof ReactSelect>
+
+interface DropdownProps extends Omit<SelectProps, "isMulti">, DropdownSharedProps {
+  /**
+   * The `isMulti` prop is not supported in the `Dropdown` component. Please use the `MultiSelect` component for multi-select functionality.
+   */
+  isMulti?: never
+}
+
+/*
+
+
+
+
+
+*/
+
+const Dropdown: React.FC<DropdownProps> = ({
+  id,
+  label,
+  leadingIcon,
+  showOptional = true,
+  className,
+  required,
+  error,
+  size = "md",
+  // variant = "dark",
+  onMenuOpen,
+  inputId: _inputId,
+  instanceId: _instanceId,
+  components: _components,
+  classNames,
+  openMenuOnFocus = true,
+  showSelectedCount = true,
+  ...rest
+}) => {
+  const { fieldId, instanceId, inputId, handleMenuOpen, stableComponents, selectClassNames } =
+    useDropdown({
+      id,
+      leadingIcon,
+      onMenuOpen,
+      required,
+      classNames,
+      size,
+      showSelectedCount,
+      components: _components,
+      inputId: _inputId,
+      instanceId: _instanceId,
+    })
+
+  return (
+    <div className={className} id={fieldId}>
+      <Container
+        size={size}
+        hasButton={false}
+        label={label}
+        showOptional={showOptional}
+        required={required}
+        variant={"dark"}
+      >
+        {label && (
+          <Label
+            inputId={inputId}
+            label={label}
+            showOptional={showOptional}
+            required={required}
+            variant={"dark"}
+          />
+        )}
+
+        <ReactSelect
+          unstyled
+          inputId={inputId}
+          required={required}
+          onMenuOpen={handleMenuOpen}
+          openMenuOnFocus={openMenuOnFocus}
+          components={stableComponents}
+          classNames={selectClassNames}
+          instanceId={instanceId}
+          {...rest}
+        />
+      </Container>
+      {error && <ErrorMessage id={inputId} error={error} />}
+    </div>
+  )
+}
+
+export default Dropdown
+export type { DropdownProps }

package/src/components/Dropdown/MultiValue.tsx

@@ -0,0 +1,19 @@
+// Utils
+import { components } from "react-select"
+
+// Props
+type MultiValueComponent = typeof components.MultiValue & { displayName?: string }
+
+/*
+
+
+
+
+*/
+
+const MultiValueDisplayName = "MultiValue"
+
+const MutliValueComponent: MultiValueComponent = components.MultiValue
+MutliValueComponent.displayName = MultiValueDisplayName
+
+export { MutliValueComponent as MultiValue, MultiValueDisplayName }

package/src/components/Dropdown/ValueContainer.tsx

@@ -0,0 +1,114 @@
+"use client"
+
+import React, { useLayoutEffect, useMemo, useState, isValidElement } from "react"
+
+// Components
+import { Icon } from "../TextField"
+
+// Types
+import type { DropdownSize } from "../.."
+
+// Utils
+import {
+  type ValueContainerProps as ReactSelectValueContainerProps,
+  components,
+} from "react-select"
+import { MultiValueDisplayName } from "./MultiValue"
+import { clsx } from "clsx"
+import { useCombinedRefs } from "../../hooks"
+import { extractDisplayName } from "../../utils/react"
+import { isFunction } from "../../utils/common"
+
+// Params
+interface ValueContainerProps extends ReactSelectValueContainerProps {
+  leadingIcon?: { icon: React.ReactNode }
+  showSelectedCount?: boolean
+  size?: DropdownSize
+}
+
+/*
+
+
+
+*/
+
+const ValueContainer: React.FC<ValueContainerProps> = ({
+  children,
+  leadingIcon,
+  className,
+  showSelectedCount,
+  size = "md",
+  ...rest
+}) => {
+  // Refs
+  const combinedRef = useCombinedRefs<HTMLDivElement>(rest?.innerProps?.ref)
+
+  // State
+  const [isOverflowing, setIsOverflowing] = useState(false)
+
+  // Data
+  const childCount = useMemo(() => {
+    return React.Children.toArray(children)?.filter(i => {
+      return (
+        isValidElement(i) &&
+        isFunction(i.type) &&
+        extractDisplayName(i.type) === MultiValueDisplayName
+      )
+    }).length
+  }, [children])
+
+  // Effects
+  useLayoutEffect(() => {
+    const el = combinedRef?.current
+    if (!el) return
+
+    const observer = new ResizeObserver(() => {
+      setIsOverflowing(el.scrollWidth > el.clientWidth)
+    })
+
+    observer.observe(el)
+    return () => observer.disconnect()
+  }, [combinedRef, childCount])
+
+  return (
+    <>
+      {!!leadingIcon?.icon && (
+        <Icon position="leading" fieldSize={size} variant="dark">
+          {leadingIcon.icon}
+        </Icon>
+      )}
+      <components.ValueContainer
+        {...rest}
+        className={clsx(
+          className,
+          leadingIcon?.icon && "pl-12",
+          isOverflowing && "[&>div:not(:last-child)]:opacity-0!",
+        )}
+        innerProps={{ ...rest?.innerProps, ref: combinedRef }}
+      >
+        {children}
+      </components.ValueContainer>
+      {showSelectedCount && isOverflowing && (
+        <div
+          className={clsx(
+            "absolute top-0 flex h-full shrink-0 items-center font-medium whitespace-nowrap text-neutral-100",
+            !leadingIcon?.icon && "rounded-l-full",
+            size === "sm" && [
+              "pl-3",
+              !!leadingIcon?.icon ? "left-8 w-[calc(100%-4rem)]" : "left-0 w-[calc(100%-2rem)]",
+            ],
+            size === "md" && [
+              "pl-5",
+              !!leadingIcon?.icon ? "left-8 w-[calc(100%-4rem)]" : "left-0 w-[calc(100%-2.75rem)]",
+            ],
+          )}
+          style={{ fontSize: "inherit" }}
+        >
+          {childCount} Selected
+        </div>
+      )}
+    </>
+  )
+}
+
+export { ValueContainer }

package/src/components/Dropdown/index.ts

@@ -0,0 +1,4 @@
+export { default, type DropdownProps } from "./Dropdown"
+export { default as AsyncDropdown, type AsyncDropdownProps } from "./AsyncDropdown"
+
+export type { DropdownSharedProps, DropdownSize, DropdownVariant } from "./types"

package/src/components/Dropdown/types.ts

@@ -0,0 +1,29 @@
+import type { TextFieldSize, TextFieldVariant } from "../TextField"
+
+/*
+
+
+
+
+
+*/
+
+export type DropdownSize = TextFieldSize
+export type DropdownVariant = TextFieldVariant
+
+export interface DropdownSharedProps {
+  label?: string
+  size?: DropdownSize
+  // variant?: DropdownVariant
+  showOptional?: boolean
+  leadingIcon?: { icon: React.ReactNode }
+  required?: boolean
+  error?: {
+    message: string
+  }
+  /**
+   *  When `true`, the dropdown will display a count of selected options when multiple options are selected. This prop is only applicable when using the `MultiSelect` component.
+   *  @default true
+   */
+  showSelectedCount?: boolean
+}