@lattice-ui/combobox 0.3.0

package/src/Combobox/ComboboxRoot.tsx

@@ -0,0 +1,202 @@
+import { React, useControllableState } from "@lattice-ui/core";
+import { ComboboxContextProvider } from "./context";
+import {
+  type ComboboxOption,
+  defaultComboboxFilter,
+  resolveComboboxInputValue,
+  resolveForcedComboboxValue,
+} from "./logic";
+import type { ComboboxItemRegistration, ComboboxProps } from "./types";
+
+function getOrderedItems(items: Array<ComboboxItemRegistration>) {
+  const ordered = [...items];
+  ordered.sort((left, right) => left.order < right.order);
+  return ordered;
+}
+
+function toOptions(items: Array<ComboboxItemRegistration>): Array<ComboboxOption> {
+  return items.map((item) => ({
+    value: item.value,
+    disabled: item.getDisabled(),
+    textValue: item.getTextValue(),
+  }));
+}
+
+export function ComboboxRoot(props: ComboboxProps) {
+  const [open, setOpenState] = useControllableState<boolean>({
+    value: props.open,
+    defaultValue: props.defaultOpen ?? false,
+    onChange: props.onOpenChange,
+  });
+
+  const [value, setValueState] = useControllableState<string | undefined>({
+    value: props.value,
+    defaultValue: props.defaultValue,
+    onChange: (nextValue) => {
+      if (nextValue !== undefined) {
+        props.onValueChange?.(nextValue);
+      }
+    },
+  });
+
+  const [inputValue, setInputValueState] = useControllableState<string>({
+    value: props.inputValue,
+    defaultValue: props.defaultInputValue ?? "",
+    onChange: props.onInputValueChange,
+  });
+
+  const disabled = props.disabled === true;
+  const readOnly = props.readOnly === true;
+  const required = props.required === true;
+  const loop = props.loop ?? true;
+  const filterFn = props.filterFn ?? defaultComboboxFilter;
+
+  const triggerRef = React.useRef<GuiObject>();
+  const inputRef = React.useRef<TextBox>();
+  const contentRef = React.useRef<GuiObject>();
+
+  const itemEntriesRef = React.useRef<Array<ComboboxItemRegistration>>([]);
+  const [registryRevision, setRegistryRevision] = React.useState(0);
+
+  const registerItem = React.useCallback((item: ComboboxItemRegistration) => {
+    itemEntriesRef.current.push(item);
+    setRegistryRevision((revision) => revision + 1);
+
+    return () => {
+      const index = itemEntriesRef.current.findIndex((entry) => entry.id === item.id);
+      if (index >= 0) {
+        itemEntriesRef.current.remove(index);
+        setRegistryRevision((revision) => revision + 1);
+      }
+    };
+  }, []);
+
+  const resolveOrderedItems = React.useCallback(() => {
+    return getOrderedItems(itemEntriesRef.current);
+  }, [registryRevision]);
+
+  const getItemText = React.useCallback(
+    (candidateValue: string) => {
+      const selected = resolveOrderedItems().find((item) => item.value === candidateValue);
+      return selected?.getTextValue();
+    },
+    [resolveOrderedItems],
+  );
+
+  const syncInputFromValue = React.useCallback(() => {
+    const nextInputValue = resolveComboboxInputValue(value, toOptions(resolveOrderedItems()), "");
+    setInputValueState(nextInputValue);
+  }, [resolveOrderedItems, setInputValueState, value]);
+
+  const setOpen = React.useCallback(
+    (nextOpen: boolean) => {
+      if (disabled && nextOpen) {
+        return;
+      }
+
+      setOpenState(nextOpen);
+
+      if (!nextOpen) {
+        syncInputFromValue();
+      }
+    },
+    [disabled, setOpenState, syncInputFromValue],
+  );
+
+  const setValue = React.useCallback(
+    (nextValue: string) => {
+      if (disabled) {
+        return;
+      }
+
+      const selected = resolveOrderedItems().find((item) => item.value === nextValue);
+      if (selected && selected.getDisabled()) {
+        return;
+      }
+
+      setValueState(nextValue);
+      const nextInputValue = getItemText(nextValue) ?? nextValue;
+      setInputValueState(nextInputValue);
+    },
+    [disabled, getItemText, resolveOrderedItems, setInputValueState, setValueState],
+  );
+
+  const setInputValue = React.useCallback(
+    (nextInputValue: string) => {
+      if (disabled || readOnly) {
+        return;
+      }
+
+      setInputValueState(nextInputValue);
+      setOpenState(true);
+    },
+    [disabled, readOnly, setInputValueState, setOpenState],
+  );
+
+  const getFilteredItems = React.useCallback(() => {
+    const query = inputValue;
+    return resolveOrderedItems().filter((item) => filterFn(item.getTextValue(), query));
+  }, [filterFn, inputValue, resolveOrderedItems]);
+
+  React.useEffect(() => {
+    const orderedItems = resolveOrderedItems();
+    const nextValue = resolveForcedComboboxValue(value, toOptions(orderedItems));
+    if (nextValue !== value) {
+      setValueState(nextValue);
+    }
+  }, [registryRevision, resolveOrderedItems, setValueState, value]);
+
+  React.useEffect(() => {
+    if (open) {
+      return;
+    }
+
+    syncInputFromValue();
+  }, [open, syncInputFromValue, value]);
+
+  const contextValue = React.useMemo(
+    () => ({
+      open,
+      setOpen,
+      value,
+      setValue,
+      inputValue,
+      setInputValue,
+      syncInputFromValue,
+      disabled,
+      readOnly,
+      required,
+      loop,
+      filterFn,
+      triggerRef,
+      inputRef,
+      contentRef,
+      registerItem,
+      getOrderedItems: resolveOrderedItems,
+      getFilteredItems,
+      getItemText,
+    }),
+    [
+      disabled,
+      filterFn,
+      getFilteredItems,
+      getItemText,
+      inputValue,
+      loop,
+      open,
+      readOnly,
+      registerItem,
+      required,
+      resolveOrderedItems,
+      setInputValue,
+      setOpen,
+      setValue,
+      syncInputFromValue,
+      value,
+    ],
+  );
+
+  return <ComboboxContextProvider value={contextValue}>{props.children}</ComboboxContextProvider>;
+}
+
+export { ComboboxRoot as Combobox };

package/src/Combobox/ComboboxSeparator.tsx

@@ -0,0 +1,19 @@
+import { React, Slot } from "@lattice-ui/core";
+import type { ComboboxSeparatorProps } from "./types";
+
+export function ComboboxSeparator(props: ComboboxSeparatorProps) {
+  if (props.asChild) {
+    const child = props.children;
+    if (!child) {
+      error("[ComboboxSeparator] `asChild` requires a child element.");
+    }
+
+    return <Slot>{child}</Slot>;
+  }
+
+  return (
+    <frame BackgroundColor3={Color3.fromRGB(78, 86, 104)} BorderSizePixel={0} Size={UDim2.fromOffset(220, 1)}>
+      {props.children}
+    </frame>
+  );
+}

package/src/Combobox/ComboboxTrigger.tsx

@@ -0,0 +1,89 @@
+import { React, Slot } from "@lattice-ui/core";
+import { useComboboxContext } from "./context";
+import type { ComboboxTriggerProps } from "./types";
+
+function toGuiObject(instance: Instance | undefined) {
+  if (!instance || !instance.IsA("GuiObject")) {
+    return undefined;
+  }
+
+  return instance;
+}
+
+export function ComboboxTrigger(props: ComboboxTriggerProps) {
+  const comboboxContext = useComboboxContext();
+  const disabled = comboboxContext.disabled || props.disabled === true;
+
+  const setTriggerRef = React.useCallback(
+    (instance: Instance | undefined) => {
+      comboboxContext.triggerRef.current = toGuiObject(instance);
+    },
+    [comboboxContext.triggerRef],
+  );
+
+  const handleActivated = React.useCallback(() => {
+    if (disabled) {
+      return;
+    }
+
+    comboboxContext.setOpen(!comboboxContext.open);
+  }, [comboboxContext, disabled]);
+
+  const handleInputBegan = React.useCallback(
+    (_rbx: GuiObject, inputObject: InputObject) => {
+      if (disabled) {
+        return;
+      }
+
+      const keyCode = inputObject.KeyCode;
+      if (keyCode === Enum.KeyCode.Return || keyCode === Enum.KeyCode.Space) {
+        comboboxContext.setOpen(!comboboxContext.open);
+        return;
+      }
+
+      if (keyCode === Enum.KeyCode.Down || keyCode === Enum.KeyCode.Up) {
+        comboboxContext.setOpen(true);
+      }
+    },
+    [comboboxContext, disabled],
+  );
+
+  const eventHandlers = React.useMemo(
+    () => ({
+      Activated: handleActivated,
+      InputBegan: handleInputBegan,
+    }),
+    [handleActivated, handleInputBegan],
+  );
+
+  if (props.asChild) {
+    const child = props.children;
+    if (!child) {
+      error("[ComboboxTrigger] `asChild` requires a child element.");
+    }
+
+    return (
+      <Slot Active={!disabled} Event={eventHandlers} Selectable={!disabled} ref={setTriggerRef}>
+        {child}
+      </Slot>
+    );
+  }
+
+  return (
+    <textbutton
+      Active={!disabled}
+      AutoButtonColor={false}
+      BackgroundColor3={Color3.fromRGB(41, 48, 63)}
+      BorderSizePixel={0}
+      Event={eventHandlers}
+      Selectable={!disabled}
+      Size={UDim2.fromOffset(220, 36)}
+      Text="Combobox"
+      TextColor3={disabled ? Color3.fromRGB(140, 148, 164) : Color3.fromRGB(235, 241, 248)}
+      TextSize={15}
+      ref={setTriggerRef}
+    >
+      {props.children}
+    </textbutton>
+  );
+}

package/src/Combobox/ComboboxValue.tsx

@@ -0,0 +1,42 @@
+import { React, Slot } from "@lattice-ui/core";
+import { useComboboxContext } from "./context";
+import type { ComboboxValueProps } from "./types";
+
+export function ComboboxValue(props: ComboboxValueProps) {
+  const comboboxContext = useComboboxContext();
+  const selectedValue = comboboxContext.value;
+  const hasValue = selectedValue !== undefined;
+
+  const resolvedText = React.useMemo(() => {
+    if (!hasValue || selectedValue === undefined) {
+      return props.placeholder ?? "";
+    }
+
+    return comboboxContext.getItemText(selectedValue) ?? selectedValue;
+  }, [comboboxContext, hasValue, props.placeholder, selectedValue]);
+
+  if (props.asChild) {
+    const child = props.children;
+    if (!child) {
+      error("[ComboboxValue] `asChild` requires a child element.");
+    }
+
+    return (
+      <Slot Name="ComboboxValue" Text={resolvedText}>
+        {child}
+      </Slot>
+    );
+  }
+
+  return (
+    <textlabel
+      BackgroundTransparency={1}
+      BorderSizePixel={0}
+      Size={UDim2.fromOffset(200, 20)}
+      Text={resolvedText}
+      TextColor3={hasValue ? Color3.fromRGB(235, 240, 248) : Color3.fromRGB(153, 161, 177)}
+      TextSize={14}
+      TextXAlignment={Enum.TextXAlignment.Left}
+    />
+  );
+}

package/src/Combobox/context.ts

@@ -0,0 +1,6 @@
+import { createStrictContext } from "@lattice-ui/core";
+import type { ComboboxContextValue } from "./types";
+
+const [ComboboxContextProvider, useComboboxContext] = createStrictContext<ComboboxContextValue>("Combobox");
+
+export { ComboboxContextProvider, useComboboxContext };

package/src/Combobox/logic.ts

@@ -0,0 +1,56 @@
+export type ComboboxOption = {
+  value: string;
+  disabled: boolean;
+  textValue: string;
+};
+
+export type ComboboxFilterFn = (itemText: string, query: string) => boolean;
+
+export function defaultComboboxFilter(itemText: string, query: string) {
+  const normalizedItemText = string.lower(itemText);
+  const normalizedQuery = string.lower(query);
+  return string.find(normalizedItemText, normalizedQuery, 1, true) !== undefined;
+}
+
+export function resolveForcedComboboxValue(currentValue: string | undefined, options: Array<ComboboxOption>) {
+  const enabled = options.filter((option) => !option.disabled);
+  if (enabled.size() === 0) {
+    return undefined;
+  }
+
+  if (currentValue === undefined) {
+    return enabled[0]?.value;
+  }
+
+  const selected = enabled.find((option) => option.value === currentValue);
+  if (selected) {
+    return selected.value;
+  }
+
+  return enabled[0]?.value;
+}
+
+export function resolveComboboxInputValue(
+  selectedValue: string | undefined,
+  options: Array<ComboboxOption>,
+  placeholder = "",
+) {
+  if (selectedValue === undefined) {
+    return placeholder;
+  }
+
+  const selected = options.find((option) => option.value === selectedValue && !option.disabled);
+  if (!selected) {
+    return placeholder;
+  }
+
+  return selected.textValue;
+}
+
+export function filterComboboxOptions(
+  options: Array<ComboboxOption>,
+  query: string,
+  filterFn: ComboboxFilterFn = defaultComboboxFilter,
+) {
+  return options.filter((option) => filterFn(option.textValue, query));
+}

package/src/Combobox/types.ts

@@ -0,0 +1,119 @@
+import type { LayerInteractEvent } from "@lattice-ui/layer";
+import type { PopperPlacement } from "@lattice-ui/popper";
+import type React from "@rbxts/react";
+
+export type ComboboxFilterFn = (itemText: string, query: string) => boolean;
+
+export type ComboboxSetOpen = (open: boolean) => void;
+export type ComboboxSetValue = (value: string) => void;
+export type ComboboxSetInputValue = (inputValue: string) => void;
+
+export type ComboboxItemRegistration = {
+  id: number;
+  value: string;
+  order: number;
+  getNode: () => GuiObject | undefined;
+  getDisabled: () => boolean;
+  getTextValue: () => string;
+};
+
+export type ComboboxContextValue = {
+  open: boolean;
+  setOpen: ComboboxSetOpen;
+  value?: string;
+  setValue: ComboboxSetValue;
+  inputValue: string;
+  setInputValue: ComboboxSetInputValue;
+  syncInputFromValue: () => void;
+  disabled: boolean;
+  readOnly: boolean;
+  required: boolean;
+  loop: boolean;
+  filterFn: ComboboxFilterFn;
+  triggerRef: React.MutableRefObject<GuiObject | undefined>;
+  inputRef: React.MutableRefObject<TextBox | undefined>;
+  contentRef: React.MutableRefObject<GuiObject | undefined>;
+  registerItem: (item: ComboboxItemRegistration) => () => void;
+  getOrderedItems: () => Array<ComboboxItemRegistration>;
+  getFilteredItems: () => Array<ComboboxItemRegistration>;
+  getItemText: (value: string) => string | undefined;
+};
+
+export type ComboboxProps = {
+  value?: string;
+  defaultValue?: string;
+  onValueChange?: (value: string) => void;
+  inputValue?: string;
+  defaultInputValue?: string;
+  onInputValueChange?: (inputValue: string) => void;
+  open?: boolean;
+  defaultOpen?: boolean;
+  onOpenChange?: (open: boolean) => void;
+  disabled?: boolean;
+  readOnly?: boolean;
+  required?: boolean;
+  loop?: boolean;
+  filterFn?: ComboboxFilterFn;
+  children?: React.ReactNode;
+};
+
+export type ComboboxTriggerProps = {
+  asChild?: boolean;
+  disabled?: boolean;
+  children?: React.ReactElement;
+};
+
+export type ComboboxInputProps = {
+  asChild?: boolean;
+  disabled?: boolean;
+  readOnly?: boolean;
+  placeholder?: string;
+  children?: React.ReactElement;
+};
+
+export type ComboboxValueProps = {
+  asChild?: boolean;
+  placeholder?: string;
+  children?: React.ReactElement;
+};
+
+export type ComboboxPortalProps = {
+  container?: BasePlayerGui;
+  displayOrderBase?: number;
+  children?: React.ReactNode;
+};
+
+export type ComboboxContentProps = {
+  asChild?: boolean;
+  forceMount?: boolean;
+  placement?: PopperPlacement;
+  offset?: Vector2;
+  padding?: number;
+  onEscapeKeyDown?: (event: LayerInteractEvent) => void;
+  onPointerDownOutside?: (event: LayerInteractEvent) => void;
+  onInteractOutside?: (event: LayerInteractEvent) => void;
+  children?: React.ReactNode;
+};
+
+export type ComboboxItemProps = {
+  value: string;
+  textValue?: string;
+  disabled?: boolean;
+  asChild?: boolean;
+  children?: React.ReactElement;
+};
+
+export type ComboboxSeparatorProps = {
+  asChild?: boolean;
+  children?: React.ReactElement;
+};
+
+export type ComboboxGroupProps = {
+  asChild?: boolean;
+  children?: React.ReactElement;
+};
+
+export type ComboboxLabelProps = {
+  asChild?: boolean;
+  children?: React.ReactElement;
+};

package/src/index.ts

@@ -0,0 +1,48 @@
+import { ComboboxContent } from "./Combobox/ComboboxContent";
+import { ComboboxGroup } from "./Combobox/ComboboxGroup";
+import { ComboboxInput } from "./Combobox/ComboboxInput";
+import { ComboboxItem } from "./Combobox/ComboboxItem";
+import { ComboboxLabel } from "./Combobox/ComboboxLabel";
+import { ComboboxPortal } from "./Combobox/ComboboxPortal";
+import { ComboboxRoot } from "./Combobox/ComboboxRoot";
+import { ComboboxSeparator } from "./Combobox/ComboboxSeparator";
+import { ComboboxTrigger } from "./Combobox/ComboboxTrigger";
+import { ComboboxValue } from "./Combobox/ComboboxValue";
+
+export const Combobox = {
+  Root: ComboboxRoot,
+  Trigger: ComboboxTrigger,
+  Input: ComboboxInput,
+  Value: ComboboxValue,
+  Portal: ComboboxPortal,
+  Content: ComboboxContent,
+  Item: ComboboxItem,
+  Group: ComboboxGroup,
+  Label: ComboboxLabel,
+  Separator: ComboboxSeparator,
+} as const;
+
+export {
+  defaultComboboxFilter,
+  filterComboboxOptions,
+  resolveComboboxInputValue,
+  resolveForcedComboboxValue,
+} from "./Combobox/logic";
+export type {
+  ComboboxContentProps,
+  ComboboxContextValue,
+  ComboboxFilterFn,
+  ComboboxGroupProps,
+  ComboboxInputProps,
+  ComboboxItemProps,
+  ComboboxItemRegistration,
+  ComboboxLabelProps,
+  ComboboxPortalProps,
+  ComboboxProps,
+  ComboboxSeparatorProps,
+  ComboboxSetInputValue,
+  ComboboxSetOpen,
+  ComboboxSetValue,
+  ComboboxTriggerProps,
+  ComboboxValueProps,
+} from "./Combobox/types";

package/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "out",
+    "declaration": true,
+    "typeRoots": [
+      "./node_modules/@rbxts",
+      "../../node_modules/@rbxts",
+      "./node_modules/@lattice-ui",
+      "../../node_modules/@lattice-ui"
+    ],
+    "types": ["types", "compiler-types"]
+  },
+  "include": ["src"]
+}

package/tsconfig.typecheck.json

@@ -0,0 +1,35 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "noEmit": true,
+    "baseUrl": "..",
+    "rootDir": "..",
+    "paths": {
+      "@lattice-ui/accordion": ["accordion/src/index.ts"],
+      "@lattice-ui/avatar": ["avatar/src/index.ts"],
+      "@lattice-ui/checkbox": ["checkbox/src/index.ts"],
+      "@lattice-ui/combobox": ["combobox/src/index.ts"],
+      "@lattice-ui/core": ["core/src/index.ts"],
+      "@lattice-ui/dialog": ["dialog/src/index.ts"],
+      "@lattice-ui/focus": ["focus/src/index.ts"],
+      "@lattice-ui/layer": ["layer/src/index.ts"],
+      "@lattice-ui/menu": ["menu/src/index.ts"],
+      "@lattice-ui/popover": ["popover/src/index.ts"],
+      "@lattice-ui/popper": ["popper/src/index.ts"],
+      "@lattice-ui/progress": ["progress/src/index.ts"],
+      "@lattice-ui/radio-group": ["radio-group/src/index.ts"],
+      "@lattice-ui/scroll-area": ["scroll-area/src/index.ts"],
+      "@lattice-ui/select": ["select/src/index.ts"],
+      "@lattice-ui/slider": ["slider/src/index.ts"],
+      "@lattice-ui/style": ["style/src/index.ts"],
+      "@lattice-ui/switch": ["switch/src/index.ts"],
+      "@lattice-ui/system": ["system/src/index.ts"],
+      "@lattice-ui/tabs": ["tabs/src/index.ts"],
+      "@lattice-ui/text-field": ["text-field/src/index.ts"],
+      "@lattice-ui/textarea": ["textarea/src/index.ts"],
+      "@lattice-ui/toast": ["toast/src/index.ts"],
+      "@lattice-ui/toggle-group": ["toggle-group/src/index.ts"],
+      "@lattice-ui/tooltip": ["tooltip/src/index.ts"]
+    }
+  }
+}