@usefragments/ui 1.0.0

package/src/components/Select/Select.stories.tsx

@@ -0,0 +1,127 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { Select } from ".";
+
+/**
+ * Select is a dropdown for choosing from a list of options. It is a compound
+ * component requiring Select.Trigger and Select.Content children, with
+ * Select.Item entries (optionally organized via Select.Group).
+ */
+const meta = {
+  title: "Forms/Select",
+  component: Select,
+  tags: ["autodocs", "canonical"],
+  parameters: {
+    docs: {
+      description: {
+        component: "Dropdown for choosing from a list of options.",
+      },
+    },
+  },
+  argTypes: {
+    size: {
+      control: "select",
+      options: ["sm", "md", "lg"],
+      description: "Size variant",
+    },
+    disabled: { control: "boolean", description: "Disable the select" },
+    required: { control: "boolean", description: "Whether a selection is required" },
+    placeholder: { control: "text", description: "Placeholder text when no value selected" },
+  },
+  args: { placeholder: "Select a fruit", size: "md" },
+  render: (args) => (
+    <Select {...args}>
+      <Select.Trigger />
+      <Select.Content>
+        <Select.Item value="apple">Apple</Select.Item>
+        <Select.Item value="banana">Banana</Select.Item>
+        <Select.Item value="orange">Orange</Select.Item>
+        <Select.Item value="grape">Grape</Select.Item>
+      </Select.Content>
+    </Select>
+  ),
+} satisfies Meta<typeof Select>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {};
+
+export const WithGroups: Story = {
+  args: { placeholder: "Select a country" },
+  render: (args) => (
+    <Select {...args}>
+      <Select.Trigger />
+      <Select.Content>
+        <Select.Group>
+          <Select.GroupLabel>North America</Select.GroupLabel>
+          <Select.Item value="us">United States</Select.Item>
+          <Select.Item value="ca">Canada</Select.Item>
+        </Select.Group>
+        <Select.Group>
+          <Select.GroupLabel>Europe</Select.GroupLabel>
+          <Select.Item value="uk">United Kingdom</Select.Item>
+          <Select.Item value="de">Germany</Select.Item>
+        </Select.Group>
+      </Select.Content>
+    </Select>
+  ),
+};
+
+export const WithLabelAndHelper: Story = {
+  args: {
+    label: "Timezone",
+    placeholder: "Select a timezone",
+    helperText: "Used for reminders and calendar notifications.",
+  },
+  render: (args) => (
+    <Select {...args}>
+      <Select.Trigger />
+      <Select.Content>
+        <Select.Item value="pt">Pacific Time</Select.Item>
+        <Select.Item value="mt">Mountain Time</Select.Item>
+        <Select.Item value="ct">Central Time</Select.Item>
+        <Select.Item value="et">Eastern Time</Select.Item>
+      </Select.Content>
+    </Select>
+  ),
+};
+
+export const OptionsProp: Story = {
+  args: { placeholder: "Select a team" },
+  render: (args) => (
+    <Select
+      {...args}
+      options={[
+        { value: "eng", label: "Engineering" },
+        { value: "design", label: "Design" },
+        { value: "pm", label: "Product" },
+      ]}
+    />
+  ),
+};
+
+export const ErrorState: Story = {
+  args: { label: "Country", placeholder: "Select a country", error: "Please select a country" },
+  render: (args) => (
+    <Select {...args}>
+      <Select.Trigger />
+      <Select.Content>
+        <Select.Item value="us">United States</Select.Item>
+        <Select.Item value="uk">United Kingdom</Select.Item>
+      </Select.Content>
+    </Select>
+  ),
+};
+
+export const Disabled: Story = {
+  args: { placeholder: "Select an option", disabled: true },
+  render: (args) => (
+    <Select {...args}>
+      <Select.Trigger />
+      <Select.Content>
+        <Select.Item value="1">Option 1</Select.Item>
+      </Select.Content>
+    </Select>
+  ),
+};

package/src/components/Select/index.tsx

@@ -0,0 +1,457 @@
+"use client";
+
+import * as React from "react";
+import { Select as BaseSelect } from "@base-ui/react/select";
+import { useResolvedControlSize } from "../ComponentDefaults";
+import { mergeAriaIds, useFormFieldIds, type FormFieldProps } from "../../utils/aria";
+import styles from "./Select.module.scss";
+
+// ============================================
+// Types
+// ============================================
+
+export type SelectValue = string;
+
+export interface SelectOption {
+  value: SelectValue;
+  label: string;
+  disabled?: boolean;
+}
+
+/**
+ * Select dropdown for choosing from a list of options.
+ * @see https://usefragments.com/components/select
+ */
+export interface SelectProps extends FormFieldProps {
+  children?: React.ReactNode;
+  /** Controlled selected value */
+  value?: SelectValue | null;
+  /** Default value for uncontrolled usage */
+  defaultValue?: SelectValue;
+  /** Called when selection changes */
+  onValueChange?: (value: SelectValue | null) => void;
+  /** Alias for onValueChange */
+  onChange?: (value: SelectValue | null) => void;
+  /** Controlled open state */
+  open?: boolean;
+  /** Default open state */
+  defaultOpen?: boolean;
+  /** Called when open state changes */
+  onOpenChange?: (open: boolean) => void;
+  // disabled inherited from FormFieldProps
+  /** Whether the user cannot choose a different option */
+  readOnly?: boolean;
+  /** Whether a selection is required */
+  required?: boolean;
+  /** Form field name */
+  name?: string;
+  /** ID of the form that owns the hidden input */
+  form?: string;
+  /** Browser autofill hint for the hidden input */
+  autoComplete?: string;
+  /** Ref to the hidden input element */
+  inputRef?: React.Ref<HTMLInputElement>;
+  /** Placeholder text when no value is selected */
+  placeholder?: string;
+  /** Convenience API for simple selects (renders Select.Item entries when children are omitted) */
+  options?: SelectOption[];
+  /** Size variant.
+   * @default "md" */
+  size?: "sm" | "md" | "lg";
+  /** Wrapper class name */
+  className?: string;
+}
+
+export interface SelectTriggerProps extends React.HTMLAttributes<HTMLButtonElement> {
+  children?: React.ReactNode;
+  placeholder?: string;
+}
+
+export interface SelectContentProps extends React.HTMLAttributes<HTMLDivElement> {
+  children: React.ReactNode;
+  sideOffset?: number;
+  align?: "start" | "center" | "end";
+  /** Maximum number of visible options before scrolling. Shows half of the next item as a scroll hint. @default 4 */
+  maxVisibleItems?: number;
+}
+
+export interface SelectItemProps extends Omit<React.HTMLAttributes<HTMLElement>, "children"> {
+  children: React.ReactNode;
+  value: SelectValue;
+  disabled?: boolean;
+}
+
+export interface SelectGroupProps extends React.HTMLAttributes<HTMLElement> {
+  children: React.ReactNode;
+}
+
+export interface SelectGroupLabelProps extends React.HTMLAttributes<HTMLElement> {
+  children: React.ReactNode;
+}
+
+// ============================================
+// Icons
+// ============================================
+
+function ChevronDownIcon() {
+  return (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      width="16"
+      height="16"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="2"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+    >
+      <polyline points="6 9 12 15 18 9" />
+    </svg>
+  );
+}
+
+function CheckIcon() {
+  return (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      width="14"
+      height="14"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="2.5"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+    >
+      <polyline points="20 6 9 17 4 12" />
+    </svg>
+  );
+}
+
+// ============================================
+// Context for Select state
+// ============================================
+
+interface SelectContextValue {
+  placeholder?: string;
+  value?: SelectValue | null;
+  items: Map<SelectValue, React.ReactNode>;
+  registerItem: (value: SelectValue, content: React.ReactNode) => void;
+  unregisterItem: (value: SelectValue) => void;
+  size: "sm" | "md" | "lg";
+}
+
+const SelectContext = React.createContext<SelectContextValue>({
+  items: new Map(),
+  registerItem: () => {},
+  unregisterItem: () => {},
+  size: "md",
+});
+
+// Walk the declared Select children at render time to build a value→label map.
+// The trigger reads this so a preselected value renders its label immediately,
+// without waiting for the lazily-portaled popup to mount and register items.
+function collectDeclaredItems(children: React.ReactNode, map: Map<SelectValue, React.ReactNode>) {
+  React.Children.forEach(children, (child) => {
+    if (!React.isValidElement(child)) return;
+    if (child.type === SelectItem) {
+      const props = child.props as SelectItemProps;
+      map.set(props.value, props.children);
+      return;
+    }
+    const nested = (child.props as { children?: React.ReactNode })?.children;
+    if (nested) collectDeclaredItems(nested, map);
+  });
+}
+
+// ============================================
+// Components
+// ============================================
+
+const SelectRoot = React.forwardRef<HTMLDivElement, SelectProps>(function SelectRoot(
+  {
+    children,
+    value,
+    defaultValue,
+    onValueChange,
+    onChange,
+    open,
+    defaultOpen,
+    onOpenChange,
+    disabled,
+    readOnly,
+    required,
+    name,
+    form,
+    autoComplete,
+    inputRef,
+    placeholder,
+    options,
+    label,
+    helperText,
+    error,
+    size: sizeProp,
+    className,
+  }: SelectProps,
+  ref
+) {
+  const size = useResolvedControlSize(sizeProp);
+  // Track current value for controlled and uncontrolled modes
+  const [internalValue, setInternalValue] = React.useState<SelectValue | null | undefined>(
+    value ?? defaultValue ?? null
+  );
+
+  // Registry for item children - allows trigger to render selected item's content
+  const [items, setItems] = React.useState<Map<SelectValue, React.ReactNode>>(() => new Map());
+  const registerItem = React.useCallback((itemValue: SelectValue, content: React.ReactNode) => {
+    setItems((prev) => {
+      const next = new Map(prev);
+      next.set(itemValue, content);
+      return next;
+    });
+  }, []);
+  const unregisterItem = React.useCallback((itemValue: SelectValue) => {
+    setItems((prev) => {
+      if (!prev.has(itemValue)) return prev;
+      const next = new Map(prev);
+      next.delete(itemValue);
+      return next;
+    });
+  }, []);
+
+  // Sync internal value with controlled value
+  React.useEffect(() => {
+    if (value !== undefined) {
+      setInternalValue(value);
+    }
+  }, [value]);
+
+  const selectedValue = value !== undefined ? value : internalValue;
+
+  const optionItems = React.useMemo(
+    () =>
+      options?.map((option) => (
+        <SelectItem key={option.value} value={option.value} disabled={option.disabled}>
+          {option.label}
+        </SelectItem>
+      )) ?? null,
+    [options]
+  );
+
+  const resolvedChildren =
+    children ??
+    (optionItems ? (
+      <>
+        <SelectTrigger />
+        <SelectContent>{optionItems}</SelectContent>
+      </>
+    ) : null);
+
+  const handleValueChange = React.useCallback(
+    (newValue: SelectValue | null) => {
+      if (readOnly) return;
+      if (value === undefined) {
+        // Uncontrolled mode
+        setInternalValue(newValue);
+      }
+      (onChange ?? onValueChange)?.(newValue);
+    },
+    [readOnly, value, onChange, onValueChange]
+  );
+
+  // Labels declared up-front via children/options, so the trigger can show the
+  // selected value before the popup has ever opened. Merged with the live
+  // registry, which still wins for items that register dynamically.
+  const declaredItems = React.useMemo(() => {
+    const map = new Map<SelectValue, React.ReactNode>();
+    options?.forEach((option) => map.set(option.value, option.label));
+    collectDeclaredItems(children, map);
+    return map;
+  }, [children, options]);
+
+  const resolvedItems = React.useMemo(() => {
+    if (declaredItems.size === 0) return items;
+    const merged = new Map(declaredItems);
+    items.forEach((content, itemValue) => merged.set(itemValue, content));
+    return merged;
+  }, [declaredItems, items]);
+
+  const contextValue = React.useMemo(
+    () => ({
+      placeholder,
+      value: selectedValue,
+      items: resolvedItems,
+      registerItem,
+      unregisterItem,
+      size,
+    }),
+    [placeholder, selectedValue, resolvedItems, registerItem, unregisterItem, size]
+  );
+
+  const { helperId, errorId, hasError, errorMessage } = useFormFieldIds("select", {
+    label,
+    helperText,
+    error,
+  });
+
+  const wrapperClasses = [styles.wrapper, className].filter(Boolean).join(" ");
+  const helperClasses = [styles.helper, hasError && styles.helperError].filter(Boolean).join(" ");
+
+  return (
+    <SelectContext.Provider value={contextValue}>
+      <div ref={ref} className={wrapperClasses}>
+        <BaseSelect.Root
+          value={value !== undefined || readOnly ? selectedValue : undefined}
+          defaultValue={value === undefined && !readOnly ? defaultValue : undefined}
+          onValueChange={handleValueChange}
+          open={open}
+          defaultOpen={defaultOpen}
+          onOpenChange={onOpenChange}
+          disabled={disabled}
+          readOnly={readOnly}
+          required={required}
+          name={name}
+          form={form}
+          autoComplete={autoComplete}
+          inputRef={inputRef}
+          aria-describedby={mergeAriaIds(errorId, helperId)}
+        >
+          {label && <BaseSelect.Label className={styles.label}>{label}</BaseSelect.Label>}
+          {resolvedChildren}
+        </BaseSelect.Root>
+        {helperText && (
+          <span id={helperId} className={helperClasses}>
+            {helperText}
+          </span>
+        )}
+        {errorMessage && (
+          <span id={errorId} className={styles.errorMessage}>
+            {errorMessage}
+          </span>
+        )}
+      </div>
+    </SelectContext.Provider>
+  );
+});
+
+function SelectTrigger({ children, placeholder, className, ...htmlProps }: SelectTriggerProps) {
+  const context = React.useContext(SelectContext);
+  const placeholderText = placeholder ?? context.placeholder;
+
+  const classes = [
+    styles.trigger,
+    context.size === "sm" && styles.triggerSm,
+    context.size === "lg" && styles.triggerLg,
+    className,
+  ]
+    .filter(Boolean)
+    .join(" ");
+
+  // Get the selected item's children from the registry
+  const selectedContent = context.value != null ? context.items.get(context.value) : null;
+
+  // Determine what to show in the value area
+  const displayContent =
+    selectedContent ??
+    (placeholderText ? <span className={styles.placeholder}>{placeholderText}</span> : null);
+
+  return (
+    <BaseSelect.Trigger {...htmlProps} className={classes}>
+      {children ?? (
+        <>
+          <span className={styles.value}>{displayContent}</span>
+          <BaseSelect.Icon className={styles.icon}>
+            <ChevronDownIcon />
+          </BaseSelect.Icon>
+        </>
+      )}
+    </BaseSelect.Trigger>
+  );
+}
+
+function SelectContent({
+  children,
+  className,
+  sideOffset = 4,
+  align = "start",
+  maxVisibleItems,
+  ...htmlProps
+}: SelectContentProps) {
+  const popupClasses = [styles.popup, className].filter(Boolean).join(" ");
+
+  const popupStyle =
+    maxVisibleItems != null
+      ? ({
+          "--fui-select-max-items": maxVisibleItems + 0.5,
+          ...htmlProps.style,
+        } as React.CSSProperties)
+      : htmlProps.style;
+
+  return (
+    <BaseSelect.Portal>
+      <BaseSelect.Positioner sideOffset={sideOffset} align={align} className={styles.positioner}>
+        <BaseSelect.Popup {...htmlProps} className={popupClasses} style={popupStyle}>
+          {children}
+        </BaseSelect.Popup>
+      </BaseSelect.Positioner>
+    </BaseSelect.Portal>
+  );
+}
+
+function SelectItem({ children, value, disabled, className, ...htmlProps }: SelectItemProps) {
+  const { registerItem, unregisterItem } = React.useContext(SelectContext);
+  const classes = [styles.item, className].filter(Boolean).join(" ");
+
+  // Register this item's children in the registry so the trigger can display them
+  React.useEffect(() => {
+    registerItem(value, children);
+    return () => {
+      unregisterItem(value);
+    };
+  }, [registerItem, unregisterItem, value, children]);
+
+  return (
+    <BaseSelect.Item {...htmlProps} value={value} disabled={disabled} className={classes}>
+      <BaseSelect.ItemText>{children}</BaseSelect.ItemText>
+      <BaseSelect.ItemIndicator className={styles.itemIndicator}>
+        <CheckIcon />
+      </BaseSelect.ItemIndicator>
+    </BaseSelect.Item>
+  );
+}
+
+function SelectGroup({ children, className, ...htmlProps }: SelectGroupProps) {
+  const classes = [styles.group, className].filter(Boolean).join(" ");
+  return (
+    <BaseSelect.Group {...htmlProps} className={classes}>
+      {children}
+    </BaseSelect.Group>
+  );
+}
+
+function SelectGroupLabel({ children, className, ...htmlProps }: SelectGroupLabelProps) {
+  const classes = [styles.groupLabel, className].filter(Boolean).join(" ");
+  return (
+    <BaseSelect.GroupLabel {...htmlProps} className={classes}>
+      {children}
+    </BaseSelect.GroupLabel>
+  );
+}
+
+// ============================================
+// Export compound component
+// ============================================
+
+export const Select = Object.assign(SelectRoot, {
+  Trigger: SelectTrigger,
+  Content: SelectContent,
+  Item: SelectItem,
+  Group: SelectGroup,
+  GroupLabel: SelectGroupLabel,
+});
+
+// Re-export individual components
+export { SelectRoot, SelectTrigger, SelectContent, SelectItem, SelectGroup, SelectGroupLabel };