@bronzelabs/oakma-ui 0.0.1

package/src/components/MultiSelect/MultiSelect.stories.tsx

@@ -0,0 +1,493 @@
+import React from "react"
+
+// Components
+import MultiSelect from "./MultiSelect"
+import AsyncMultiSelect from "./AsyncMultiSelect"
+import { DummyPhoneIcon, StorybookActionButton } from "../../../.storybook/components"
+
+// Types
+import type { StoryFn, Meta } from "@storybook/react-webpack5"
+
+// Utils
+import extraDocs from "./MultiSelect.docs.md"
+import { renderDocsWithProps } from "../../../.storybook/utils"
+import { TEXT_FIELD_SIZES } from "../TextField"
+
+// Data
+const mockOptions = {
+  default: [
+    {
+      label: "Item 1",
+      value: "item-1",
+      color: "blue",
+    },
+    {
+      label: "Item 2",
+      value: "item-2",
+      isDisabled: true,
+    },
+    {
+      label: "Item 3",
+      value: "item-3",
+    },
+    {
+      label: "Item 4",
+      value: "item-4",
+    },
+  ],
+  long: [
+    {
+      label: "This is a very long first item to have in a multiselect dropdown",
+      value: "item-1",
+      color: "blue",
+    },
+    {
+      label: "Long Item 2",
+      value: "item-2",
+    },
+    {
+      label:
+        "The third long multiselect item that should wrap onto multiple lines if the width of the dropdown is too narrow",
+      value: "item-3",
+    },
+  ],
+  subTitle: [
+    {
+      label: "Item 1",
+      value: "item-1",
+      subTitle: "Sub text for item 1",
+    },
+    {
+      label: "Item 2",
+      value: "item-2",
+      subTitle: "Sub text for item 2",
+      isDisabled: true,
+    },
+    {
+      label: "Item 3",
+      value: "item-3",
+      subTitle: "Sub text for item 3",
+    },
+  ],
+  icons: [
+    {
+      label: "Item 1",
+      value: "item-1",
+      icon: DummyPhoneIcon,
+    },
+    {
+      label: "Item 2",
+      value: "item-2",
+      icon: DummyPhoneIcon,
+    },
+    {
+      label: "Item 3",
+      value: "item-3",
+      icon: DummyPhoneIcon,
+    },
+  ],
+  iconsSubTitle: [
+    {
+      label: "Item 1",
+      value: "item-1",
+      icon: DummyPhoneIcon,
+      subTitle: "Sub text for item 1",
+    },
+    {
+      label: "Item 2",
+      value: "item-2",
+      icon: DummyPhoneIcon,
+      subTitle: "Sub text for item 2",
+      isDisabled: true,
+    },
+    {
+      label: "Item 3",
+      value: "item-3",
+      icon: DummyPhoneIcon,
+      subTitle: "Sub text for item 3",
+    },
+  ],
+  extra: [
+    {
+      label: "Item 1",
+      value: "item-1",
+      color: "blue",
+    },
+    {
+      label: "Item 2",
+      value: "item-2",
+    },
+    {
+      label: "Item 3",
+      value: "item-3",
+    },
+    {
+      label: "Item 4",
+      value: "item-4",
+    },
+    {
+      label: "Item 5",
+      value: "item-5",
+    },
+    {
+      label: "Item 6",
+      value: "item-6",
+    },
+    {
+      label: "Item 7",
+      value: "item-7",
+    },
+    {
+      label: "Item 8",
+      value: "item-8",
+    },
+  ],
+  users: [
+    { label: "John Doe", value: "john-doe" },
+    { label: "Jane Smith", value: "jane-smith" },
+    { label: "Bob Johnson", value: "bob-johnson" },
+  ],
+}
+
+/*
+
+
+
+
+*/
+
+const meta: Meta<typeof MultiSelect> = {
+  title: "Components/MultiSelect",
+  component: MultiSelect,
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "MultiSelect is a fancy select/combobox built on top of [react-select](https://react-select.com), that can be used to select multiple values 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", "name"],
+    },
+  },
+  argTypes: {
+    options: {
+      type: {
+        name: "other",
+        value: "(Option | Group)[]",
+      },
+      description: "Array of options that populate the MultiSelect menu.",
+      table: {
+        type: {
+          summary: "(Option | Group)[]",
+        },
+        defaultValue: {
+          summary: "undefined",
+        },
+      },
+    },
+    label: {
+      type: "string",
+      description: "Visible label rendered above the MultiSelect.",
+      table: {
+        type: { summary: "string" },
+        defaultValue: { summary: "undefined" },
+      },
+    },
+    size: {
+      type: "string",
+      description: "Determines the size of the MultiSelect field.",
+      table: {
+        type: { summary: TEXT_FIELD_SIZES.map(size => `"${size}"`).join(" | ") },
+        defaultValue: { summary: '"md"' },
+      },
+      options: TEXT_FIELD_SIZES,
+      control: { type: "select" },
+    },
+    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" },
+      },
+    },
+    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" },
+      },
+    },
+    isLoading: {
+      type: "boolean",
+      description: "Is the MultiSelect in a state of loading (async).",
+      table: {
+        type: { summary: "boolean" },
+        defaultValue: { summary: "false" },
+      },
+    },
+    isDisabled: {
+      type: "boolean",
+      description: "Is the MultiSelect disabled.",
+      table: {
+        type: { summary: "boolean" },
+        defaultValue: { summary: "false" },
+      },
+    },
+    isClearable: {
+      type: "boolean",
+      description: "Is the MultiSelect value clearable.",
+      table: {
+        type: { summary: "boolean" },
+        defaultValue: { summary: "false" },
+      },
+    },
+    required: {
+      type: "boolean",
+      description: "Whether the Dropdown is required.",
+      table: {
+        type: { summary: "boolean" },
+        defaultValue: { summary: "false" },
+      },
+    },
+    tabSelectsValue: {
+      type: "boolean",
+      description: "Select the currently focused option when the user presses tab",
+      table: {
+        type: { summary: "boolean" },
+        defaultValue: { summary: "false" },
+      },
+    },
+    closeMenuOnSelect: {
+      type: "boolean",
+      description: "Close the dropdown menu when an option is selected.",
+      table: {
+        type: { summary: "boolean" },
+        defaultValue: { summary: "false" },
+      },
+    },
+    hideSelectedOptions: {
+      type: "boolean",
+      description: "Hide options that have already been selected from the dropdown menu.",
+      table: {
+        type: { summary: "boolean" },
+        defaultValue: { summary: "false" },
+      },
+    },
+  },
+  args: {
+    name: "multi-select",
+    label: "Label",
+    size: "md",
+    showOptional: true,
+    options: mockOptions.default,
+    required: false,
+    tabSelectsValue: false,
+    closeMenuOnSelect: false,
+    hideSelectedOptions: false,
+    isLoading: false,
+    isDisabled: false,
+    isClearable: false,
+  },
+}
+
+const mockLoadOptions = (inputValue: string) =>
+  new Promise<(typeof mockOptions.users)[number][]>(resolve => {
+    setTimeout(() => {
+      resolve(
+        mockOptions.users.filter(opt => opt.label.toLowerCase().includes(inputValue.toLowerCase())),
+      )
+    }, 600)
+  })
+
+// Templates
+const Template: StoryFn<typeof MultiSelect> = args => <MultiSelect {...args} />
+
+const FormTemplate: StoryFn<typeof MultiSelect> = args => {
+  return (
+    <form
+      className="flex flex-col items-stretch gap-3"
+      onSubmit={e => {
+        e.preventDefault()
+        const formData = new FormData(e.currentTarget)
+        alert(`Selected values: ${JSON.stringify(formData.getAll("multi-select"))}`)
+      }}
+    >
+      <MultiSelect {...args} />
+      <StorybookActionButton type="submit">Submit</StorybookActionButton>
+    </form>
+  )
+}
+
+const ShowAllSelectedTemplate: StoryFn<typeof MultiSelect> = args => {
+  return (
+    <>
+      <MultiSelect {...args} />
+      <MultiSelect {...args} showSelectedCount={false} />
+    </>
+  )
+}
+
+const AsyncTemplate: StoryFn<typeof MultiSelect> = args => (
+  <AsyncMultiSelect
+    id="async-multi-select"
+    label={args.label}
+    showOptional={args.showOptional}
+    size={args.size}
+    loadOptions={mockLoadOptions}
+    defaultOptions={mockOptions.users}
+    placeholder="Search users…"
+  />
+)
+
+// Stories
+const Default = Template.bind({})
+const WithSubtitles = Template.bind({})
+const WithIcons = Template.bind({})
+const WithIconsAndSubtitles = Template.bind({})
+const WithLongOptions = Template.bind({})
+const Required = FormTemplate.bind({})
+const ShowAllSelected = ShowAllSelectedTemplate.bind({})
+const Async = AsyncTemplate.bind({})
+
+// Args
+WithSubtitles.args = {
+  options: mockOptions.subTitle,
+}
+
+WithIcons.args = {
+  options: mockOptions.icons,
+}
+
+WithIconsAndSubtitles.args = {
+  options: mockOptions.iconsSubTitle,
+}
+
+WithLongOptions.args = {
+  options: mockOptions.long,
+}
+
+Required.args = {
+  required: true,
+}
+
+ShowAllSelected.args = {
+  options: mockOptions.extra,
+}
+
+// Decorators
+Default.decorators = [
+  Story => (
+    <div className="flex flex-col" style={{ width: 450, height: 300 }}>
+      <Story />
+    </div>
+  ),
+]
+
+WithSubtitles.decorators = Default.decorators
+
+WithIcons.decorators = Default.decorators
+
+WithIconsAndSubtitles.decorators = Default.decorators
+
+WithLongOptions.decorators = Default.decorators
+
+Required.decorators = Default.decorators
+
+ShowAllSelected.decorators = [
+  Story => (
+    <div className="flex flex-col gap-6" style={{ width: 450, height: 450 }}>
+      <Story />
+    </div>
+  ),
+]
+
+Async.decorators = Default.decorators
+
+Default.parameters = {
+  docs: {
+    description: {
+      story: "A basic MultiSelect with a flat list of options.",
+    },
+  },
+}
+
+WithSubtitles.parameters = {
+  docs: {
+    description: {
+      story:
+        "Options can include a `subTitle` string to provide additional context below the label.",
+    },
+  },
+}
+
+WithIcons.parameters = {
+  docs: {
+    description: {
+      story: "Options can include an `icon` component to render a visual alongside each label.",
+    },
+  },
+}
+
+WithIconsAndSubtitles.parameters = {
+  docs: {
+    description: {
+      story: "Icons and subtitles can be combined to provide richer option content.",
+    },
+  },
+}
+
+WithLongOptions.parameters = {
+  docs: {
+    description: {
+      story: "Long option labels wrap naturally within the menu without truncation.",
+    },
+  },
+}
+
+Required.parameters = {
+  docs: {
+    description: {
+      story:
+        'Setting `required` hides the "Optional" tag and marks the field as required. The form will not submit until at least one value is selected.',
+    },
+  },
+}
+
+ShowAllSelected.parameters = {
+  docs: {
+    description: {
+      story:
+        "By default, selected options are summarised as a count badge once there are too many to display inline. Set `showSelectedCount={false}` to always show every selected option as an individual tag.",
+    },
+  },
+}
+
+Async.parameters = {
+  docs: {
+    description: {
+      story:
+        "Use `AsyncMultiSelect` 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.",
+    },
+  },
+}
+
+export {
+  Default,
+  WithSubtitles,
+  WithIcons,
+  WithIconsAndSubtitles,
+  WithLongOptions,
+  Required,
+  ShowAllSelected,
+  Async,
+}
+export default meta

package/src/components/MultiSelect/MultiSelect.tsx

@@ -0,0 +1,81 @@
+"use client"
+
+import React from "react"
+
+// Components
+import Dropdown, { type DropdownProps } from "../Dropdown"
+import Checkbox from "../Checkbox"
+
+// Utils
+import { clsx } from "clsx"
+import { components, type OptionProps } from "react-select"
+
+// Props
+interface MultiSelectProps extends Omit<DropdownProps, "isMulti"> {
+  cy?: string
+}
+
+const dataHasIcon = (check: any): check is { icon: React.ElementType } => {
+  return !!check?.icon && check?.icon !== null
+}
+
+const MultiSelectOption = (props: OptionProps<any>) => {
+  const Icon = dataHasIcon(props?.data) ? props.data.icon : undefined
+
+  return (
+    <components.Option
+      {...props}
+      className={clsx(props?.className, "flex! w-full items-center justify-between gap-3")}
+    >
+      {Icon && <Icon className="size-5" />}
+      <div className="flex grow flex-col">
+        <span>{props?.data?.label}</span>
+        {props?.data?.subTitle && <span>{props.data.subTitle}</span>}
+      </div>
+
+      <Checkbox checked={props?.isSelected} readOnly />
+    </components.Option>
+  )
+}
+
+const multiSelectComponents = { Option: MultiSelectOption }
+
+/*
+
+
+
+
+
+*/
+
+const MultiSelect: React.FC<MultiSelectProps> = ({
+  tabSelectsValue = false,
+  closeMenuOnSelect = false,
+  hideSelectedOptions = false,
+  isClearable = false,
+  ...rest
+}) => {
+  // Functions
+  //   const handleChange: typeof onChange = (newValue, data): void => {
+  //     onChange?.(newValue, data)
+  //     setTimeout(() => combinedRef.current?.focusInput(), 0)
+  //   }
+
+  return (
+    <Dropdown
+      closeMenuOnSelect={closeMenuOnSelect}
+      hideSelectedOptions={hideSelectedOptions}
+      tabSelectsValue={tabSelectsValue}
+      // @ts-expect-error - The `isMulti` prop is not supported when used by external consumers, however it is required internally to render the correct components and behavior.
+      isMulti
+      isClearable={isClearable}
+      components={multiSelectComponents}
+      {...rest}
+    />
+  )
+}
+
+MultiSelect.displayName = "MultiSelect"
+export default MultiSelect
+export { MultiSelectOption }
+export type { MultiSelectProps }

package/src/components/MultiSelect/index.ts

@@ -0,0 +1,2 @@
+export { default, type MultiSelectProps } from "./MultiSelect"
+export { default as AsyncMultiSelect, type AsyncMultiSelectProps } from "./AsyncMultiSelect"