@alepha/ui 0.18.1 → 0.18.3

package/src/core/form/components/ControlSelect.tsx

@@ -3,6 +3,7 @@ import {
   type AutocompleteProps,
   Flex,
   Input,
+  Loader,
   MultiSelect,
   type MultiSelectProps,
   SegmentedControl,
@@ -12,39 +13,91 @@ import {
   TagsInput,
   type TagsInputProps,
 } from "@mantine/core";
-import { useFormState } from "alepha/react/form";
-import { useEffect, useState } from "react";
+import type { Async } from "alepha";
+import { useAction } from "alepha/react";
+import { useFieldValue, useFormState } from "alepha/react/form";
+import { useEffect, useRef, useState } from "react";
 import { type GenericControlProps, parseInput } from "../utils/parseInput.ts";
 
 export type SelectValueLabel =
   | string
   | { value: string; label: string; icon?: string };
 
+type LoaderMode = "static" | "short" | "long";
+
 export interface ControlSelectProps extends GenericControlProps {
-  select?: boolean | SelectProps;
-  multi?: boolean | MultiSelectProps;
-  tags?: boolean | TagsInputProps;
-  autocomplete?: boolean | AutocompleteProps;
-  segmented?: boolean | Partial<SegmentedControlProps>;
+  /**
+   * If true, allows creating new values not present in the options list.
+   * For single values, Select becomes an Autocomplete.
+   * For arrays, MultiSelect becomes a TagsInput.
+   */
+  creatable?: boolean;
+
+  /**
+   * Configure select with optional SelectProps.
+   */
+  selectProps?: boolean | SelectProps;
+
+  /**
+   * Configure select as multi-select (for array of enums) with optional MultiSelectProps.
+   */
+  multiSelectProps?: boolean | MultiSelectProps;
+
+  /**
+   * If true, renders a SegmentedControl instead of Select/MultiSelect.
+   */
+  segmentedProps?: boolean | Partial<SegmentedControlProps>;
+
+  /**
+   * Props passed to the Autocomplete component when creatable is true and the field is single-value.
+   */
+  autocompleteProps?: Partial<AutocompleteProps>;
+
+  /**
+   * Props passed to the TagsInput component when creatable is true and the field is array-value.
+   */
+  tagsInputProps?: Partial<TagsInputProps>;
+
+  /**
+   * Async loader for select options.
+   *
+   * @param search - Search text (empty string on initial load)
+   * @param resolve - Optional array of values to resolve labels for (used for default values in long mode)
+   */
+  loader?: (search: string, resolve?: string[]) => Async<SelectValueLabel[]>;
+
+  /**
+   * Threshold to distinguish short (client-filtered) from long (server-filtered) lists.
+   * If initial load returns <= threshold items, mode is "short" (cached, client-filtered).
+   * If > threshold, mode is "long" (debounced server search).
+   * @default 100
+   */
+  loaderThreshold?: number;
 
-  loader?: () => Promise<SelectValueLabel[]>;
+  /**
+   * Debounce delay in ms for server search in long mode.
+   * @default 300
+   */
+  loaderDebounce?: number;
 }
 
 /**
- * ControlSelect component for handling Select, MultiSelect, and TagsInput.
+ * ControlSelect component for handling Select, MultiSelect, Autocomplete, and TagsInput.
  *
  * Features:
  * - Basic Select with enum support
  * - MultiSelect for array of enums
- * - TagsInput for array of strings (no enum)
- * - Future: Lazy loading
- * - Future: Searchable/filterable options
- * - Future: Custom option rendering
+ * - Autocomplete for creatable single values
+ * - TagsInput for creatable array values
+ * - Async lazy loading with auto short/long mode detection
+ * - Short mode: client-side filtering with cached data
+ * - Long mode: debounced server search
  *
  * Automatically detects enum values and array types from schema.
  */
 const ControlSelect = (props: ControlSelectProps) => {
   const form = useFormState(props.input);
+  const [value, setValue] = useFieldValue(props.input);
   const { inputProps, id, icon } = parseInput(props, form);
 
   // Detect if schema is an array type
@@ -53,14 +106,18 @@ const ControlSelect = (props: ControlSelectProps) => {
     "type" in props.input.schema &&
     props.input.schema.type === "array";
 
-  // For arrays, check if items have enum (MultiSelect) or not (TagsInput)
-  let itemsEnum: string[] | undefined;
-  if (isArray && "items" in props.input.schema && props.input.schema.items) {
-    const items: any = props.input.schema.items;
-    if ("enum" in items && Array.isArray(items.enum)) {
-      itemsEnum = items.enum;
-    }
-  }
+  // Detect if schema is numeric (for value coercion)
+  const isNumeric =
+    props.input.schema &&
+    "type" in props.input.schema &&
+    (props.input.schema.type === "integer" ||
+      props.input.schema.type === "number");
+
+  // Detect if schema is boolean (for value coercion)
+  const isBoolean =
+    props.input.schema &&
+    "type" in props.input.schema &&
+    props.input.schema.type === "boolean";
 
   // Extract enum values from schema (for non-array select)
   const enumValues =
@@ -70,132 +127,277 @@ const ControlSelect = (props: ControlSelectProps) => {
       ? props.input.schema.enum
       : [];
 
-  const [data, setData] = useState<SelectValueLabel[]>([]);
+  // Async loader hook
+  const {
+    data: asyncData,
+    loading,
+    mode,
+    search,
+  } = useAsyncLoader(
+    props.loader,
+    props.loaderThreshold ?? 100,
+    props.loaderDebounce ?? 300,
+    props.input.initialValue,
+  );
 
-  useEffect(() => {
-    if (!props.input?.props) {
-      return;
-    }
+  // Static data from enum (no loader)
+  const [staticData, setStaticData] = useState<SelectValueLabel[]>([]);
 
-    if (props.loader) {
-      props.loader().then(setData);
+  const enumKey = JSON.stringify(enumValues);
+  useEffect(() => {
+    if (!props.input?.props || props.loader) return;
+    if (isBoolean && enumValues.length === 0) {
+      setStaticData([
+        { value: "true", label: "True" },
+        { value: "false", label: "False" },
+      ]);
     } else {
-      setData(enumValues);
+      setStaticData(enumValues);
     }
-  }, [props.input, props.loader]);
+  }, [props.input, props.loader, enumKey, isBoolean]);
+
+  const data = props.loader ? asyncData : staticData;
 
   if (!props.input?.props) {
     return null;
   }
 
-  if (props.segmented) {
+  /**
+   * Coerce value for numeric schemas — Select values are always strings.
+   */
+  const coerceValue = (val: string | null) => {
+    if (val == null) return val;
+    if (isNumeric) return Number(val);
+    if (isBoolean) return val === "true";
+    return val;
+  };
+
+  // region <SegmentedControl/> — early return
+  if (props.segmentedProps) {
     const segmentedControlProps: Partial<SegmentedControlProps> =
-      typeof props.segmented === "object" ? props.segmented : {};
+      typeof props.segmentedProps === "object" ? props.segmentedProps : {};
+    const segmentedData = segmentedControlProps.data ?? data.slice(0, 10);
 
     return (
       <Input.Wrapper {...inputProps}>
-        <Flex>
+        <Flex my={"calc(var(--mantine-spacing-xs) / 2)"}>
           <SegmentedControl
             disabled={inputProps.disabled}
-            defaultValue={String(props.input.props.defaultValue)}
+            value={value != null ? String(value) : ""}
             {...segmentedControlProps}
-            onChange={(value) => {
-              props.input.set(value);
+            onChange={(val) => {
+              setValue(coerceValue(val));
             }}
-            data={data.slice(0, 10)}
+            data={segmentedData}
           />
         </Flex>
       </Input.Wrapper>
     );
   }
+  // endregion
+
+  // Shared props used by all select-like components
+  const sharedProps = {
+    size: props.size,
+    id,
+    leftSection: loading ? <Loader color={"gray"} size={10} /> : icon,
+    data,
+  };
 
-  if (props.autocomplete) {
-    const autocompleteProps =
-      typeof props.autocomplete === "object" ? props.autocomplete : {};
+  // Select and MultiSelect: searchable + hide default chevron
+  const selectableProps = {
+    ...sharedProps,
+    searchable: true,
+    rightSection: <span />,
+  };
+
+  // Long mode additions: bypass client filter + wire server search
+  const longModeProps =
+    mode === "long"
+      ? {
+          filter: ({ options }: { options: any[] }) => options,
+          onSearchChange: search.run,
+        }
+      : {};
+
+  // region <TagsInput/> — creatable + array
+  if (props.creatable && (isArray || props.tagsInputProps)) {
+    const tagsInputExtraProps = props.tagsInputProps ?? {};
 
     return (
-      <Autocomplete
+      <TagsInput
         {...inputProps}
-        size={props.size}
-        id={id}
-        leftSection={icon}
-        data={data}
-        {...props.input.props}
-        {...autocompleteProps}
+        {...sharedProps}
+        {...longModeProps}
+        value={Array.isArray(value) ? value : []}
+        onChange={(val) => {
+          setValue(val);
+        }}
+        {...tagsInputExtraProps}
       />
     );
   }
+  // endregion
+
+  // region <Autocomplete/> — creatable + single
+  if (props.creatable) {
+    const autocompleteExtraProps = props.autocompleteProps ?? {};
 
-  // region <TagsInput/> - for array of strings without enum
-  if ((isArray && !itemsEnum) || props.tags) {
-    const tagsInputProps = typeof props.tags === "object" ? props.tags : {};
     return (
-      <TagsInput
+      <Autocomplete
         {...inputProps}
-        size={props.size}
-        id={id}
-        leftSection={icon}
-        defaultValue={
-          Array.isArray(props.input.props.defaultValue)
-            ? props.input.props.defaultValue
-            : []
-        }
-        onChange={(value) => {
-          props.input.set(value);
+        {...sharedProps}
+        {...longModeProps}
+        value={value != null ? String(value) : ""}
+        onChange={(val) => {
+          setValue(coerceValue(val));
         }}
-        {...tagsInputProps}
+        {...autocompleteExtraProps}
       />
     );
   }
   // endregion
 
-  // region <MultiSelect/> - for array of enums
-  if ((isArray && itemsEnum) || props.multi) {
-    const data =
-      itemsEnum?.map((value: string) => ({
-        value,
-        label: value,
-      })) || [];
-
-    const multiSelectProps = typeof props.multi === "object" ? props.multi : {};
+  // region <MultiSelect/> — array (non-creatable)
+  if (isArray || props.multiSelectProps) {
+    const multiSelectExtraProps =
+      typeof props.multiSelectProps === "object" ? props.multiSelectProps : {};
 
     return (
       <MultiSelect
         {...inputProps}
-        size={props.size}
-        id={id}
-        leftSection={icon}
-        data={data}
-        defaultValue={
-          Array.isArray(props.input.props.defaultValue)
-            ? props.input.props.defaultValue
-            : []
-        }
-        onChange={(value) => {
-          props.input.set(value);
+        {...selectableProps}
+        {...longModeProps}
+        value={Array.isArray(value) ? value : []}
+        onChange={(val) => {
+          setValue(val);
         }}
-        {...multiSelectProps}
+        {...multiSelectExtraProps}
       />
     );
   }
   // endregion
 
-  // region <Select/> - for single enum value
-  const selectProps = typeof props.select === "object" ? props.select : {};
+  // region <Select/> — single value (static, short, or long mode)
+  const selectExtraProps =
+    typeof props.selectProps === "object" ? props.selectProps : {};
+
+  // Static mode
+  if (mode === "static") {
+    return (
+      <Select
+        {...inputProps}
+        {...selectableProps}
+        value={value != null ? String(value) : null}
+        onChange={(val) => {
+          setValue(coerceValue(val));
+        }}
+        {...selectExtraProps}
+      />
+    );
+  }
 
+  // Short or long mode
   return (
     <Select
       {...inputProps}
-      size={props.size}
-      id={id}
-      leftSection={icon}
-      rightSection={null}
-      data={data}
-      {...props.input.props}
-      {...selectProps}
+      {...selectableProps}
+      {...longModeProps}
+      value={value != null ? String(value) : null}
+      onChange={(val) => {
+        setValue(coerceValue(val));
+      }}
+      {...selectExtraProps}
     />
   );
   // endregion
 };
 
 export default ControlSelect;
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+/**
+ * Hook for async select data loading with auto short/long mode detection.
+ */
+const useAsyncLoader = (
+  loader: ControlSelectProps["loader"],
+  threshold: number,
+  debounceMs: number,
+  defaultValue: any,
+) => {
+  const [data, setData] = useState<SelectValueLabel[]>([]);
+  const [loading, setLoading] = useState(false);
+  const [mode, setMode] = useState<LoaderMode>("static");
+  const cache = useRef(new Map<string, SelectValueLabel[]>());
+
+  useAction(
+    {
+      name: "select:loader:init",
+      runOnInit: true,
+      handler: async () => {
+        if (!loader) {
+          setMode("static");
+          return;
+        }
+
+        setLoading(true);
+        try {
+          const result = await loader("");
+          const isShort = result.length <= threshold;
+          setMode(isShort ? "short" : "long");
+          cache.current.set("", result);
+          setData(result);
+
+          // In long mode, resolve default value label before clearing loading
+          if (!isShort && defaultValue != null && String(defaultValue) !== "") {
+            const resolved = await loader("", [String(defaultValue)]);
+            if (resolved.length > 0) {
+              setData((prev) => {
+                const existing = new Set(
+                  prev.map((d) => (typeof d === "string" ? d : d.value)),
+                );
+                const newItems = resolved.filter((r) => {
+                  const val = typeof r === "string" ? r : r.value;
+                  return !existing.has(val);
+                });
+                return [...prev, ...newItems];
+              });
+            }
+          }
+        } finally {
+          setLoading(false);
+        }
+      },
+    },
+    [loader, threshold],
+  );
+
+  // Debounced search (long mode only)
+  const search = useAction<[string]>(
+    {
+      debounce: debounceMs,
+      handler: async (text) => {
+        if (!loader || mode !== "long") return;
+
+        // Check cache first (immediate, no network)
+        if (cache.current.has(text)) {
+          setData(cache.current.get(text)!);
+          return;
+        }
+
+        setLoading(true);
+        try {
+          const result = await loader(text);
+          cache.current.set(text, result);
+          setData(result);
+        } finally {
+          setLoading(false);
+        }
+      },
+    },
+    [loader, mode, debounceMs],
+  );
+
+  return { data, loading, mode, search };
+};

package/src/core/form/components/TypeForm.browser.spec.tsx

@@ -500,7 +500,7 @@ describe("TypeForm", () => {
         return (
           <TypeForm
             form={form}
-            controlProps={{ title: "Custom Title" }}
+            controlProps={{ label: "Custom Title" }}
             skipSubmitButton
           />
         );
@@ -530,8 +530,8 @@ describe("TypeForm", () => {
           <TypeForm
             form={form}
             fieldControlProps={{
-              field1: { title: "Field One" },
-              field2: { title: "Field Two" },
+              field1: { label: "Field One" },
+              field2: { label: "Field Two" },
             }}
             skipSubmitButton
           />

package/src/core/form/components/TypeForm.tsx

@@ -1,7 +1,7 @@
 import { ActionButton, type ActionSubmitButtonProps } from "@alepha/ui";
 import { Card, Flex, type FlexProps, Grid } from "@mantine/core";
 import type { TObject } from "alepha";
-import type { FormModel } from "alepha/react/form";
+import { type FormModel, useFormState } from "alepha/react/form";
 import type { ReactNode } from "react";
 import Control, { type ControlProps } from "./Control.tsx";
 
@@ -96,6 +96,8 @@ const TypeForm = <T extends TObject>(props: TypeFormProps<T>) => {
     size,
   } = props;
 
+  const { dirty } = useFormState(form, ["dirty"]);
+
   const schema = props.schema || form.options.schema;
   if (!schema?.properties) {
     return null;
@@ -194,12 +196,13 @@ const TypeForm = <T extends TObject>(props: TypeFormProps<T>) => {
             <Flex></Flex>
             <Flex flex={1}></Flex>
             <Flex gap={"sm"}>
-              <ActionButton variant={"subtle"} type={"reset"}>
+              <ActionButton variant={"subtle"} type={"reset"} disabled={!dirty}>
                 Reset
               </ActionButton>
               <ActionButton
                 intent={"primary"}
                 form={form}
+                disabled={!dirty}
                 {...submitButtonProps}
               >
                 {submitButtonProps?.children ?? "Submit"}

package/src/core/form/index.ts

@@ -2,13 +2,20 @@ import type { ControlProps } from "./components/Control.tsx";
 
 // ---------------------------------------------------------------------------------------------------------------------
 
-export type { ControlProps } from "./components/Control.tsx";
+export type {
+  ControlProps,
+  CustomControlProps,
+} from "./components/Control.tsx";
 export { default as Control } from "./components/Control.tsx";
 export { default as ControlArray } from "./components/ControlArray.tsx";
 export { default as ControlDate } from "./components/ControlDate.tsx";
 export { default as ControlNumber } from "./components/ControlNumber.tsx";
 export { default as ControlObject } from "./components/ControlObject.tsx";
 export { default as ControlQueryBuilder } from "./components/ControlQueryBuilder.tsx";
+export type {
+  ControlSelectProps,
+  SelectValueLabel,
+} from "./components/ControlSelect.tsx";
 export { default as ControlSelect } from "./components/ControlSelect.tsx";
 export type { TypeFormProps } from "./components/TypeForm.tsx";
 export { default as TypeForm } from "./components/TypeForm.tsx";

package/src/core/form/utils/parseInput.ts

@@ -18,7 +18,7 @@ export const parseInput = (
   const disabled = false; // form.loading;
   const id = props.input.props.id;
   const label =
-    props.title ??
+    props.label ??
     ("title" in props.input.schema &&
     typeof props.input.schema.title === "string"
       ? props.input.schema.title
@@ -57,10 +57,11 @@ export const parseInput = (
           props.input.schema &&
           "type" in props.input.schema &&
           props.input.schema.type === "array",
+        size: props.size,
       })
     : isValidElement(props.icon)
       ? props.icon
-      : createElement(props.icon, { size: ui.sizes.icon.md });
+      : createElement(props.icon, { size: ui.sizes.icon.sm });
 
   const format =
     props.input.schema &&
@@ -72,12 +73,15 @@ export const parseInput = (
   const required = props.input.required;
   const schema = props.input.schema as TObject & { $control?: ControlProps };
 
+  const testId = (props.input.props as any)?.["data-testid"];
+
   const inputProps: InputProps = {
     label,
     description,
     error,
     required,
     disabled,
+    ...(testId ? { "data-testid": testId } : {}),
   };
 
   if ("minLength" in schema && typeof schema.minLength === "number") {
@@ -104,7 +108,7 @@ export const parseInput = (
 
 export interface GenericControlProps {
   input: BaseInputField;
-  title?: string;
+  label?: string;
   description?: string;
   icon?: ReactElement | ((props: { size: number }) => ReactNode);
   size?: "xs" | "sm" | "md" | "lg" | "xl";

package/src/core/hooks/useTheme.ts

@@ -3,23 +3,36 @@ import {
   alephaThemeAtom,
   type CurrentAlephaTheme,
 } from "../atoms/alephaThemeAtom.ts";
+import {
+  type AlephaThemeOverrides,
+  alephaThemeOverridesAtom,
+} from "../atoms/alephaThemeOverridesAtom.ts";
 import type { AlephaTheme } from "../interfaces/AlephaTheme.ts";
 import { ThemeProvider } from "../providers/ThemeProvider.ts";
 
+export interface ThemeExpert {
+  overrides: AlephaThemeOverrides;
+  setOverrides: (overrides: AlephaThemeOverrides) => void;
+  resetOverrides: () => void;
+}
+
 /**
  * Hook to get and set the current theme.
  *
- * Returns a tuple with the current theme and a function to set the theme.
+ * Returns a tuple with the current theme, a function to set the theme,
+ * and expert mode controls for fine-grained customization.
  *
  * ```tsx
- * const [theme, setTheme] = useTheme();
+ * const [theme, setTheme, expert] = useTheme();
  * ```
  */
 export const useTheme = (): [
   AlephaTheme,
   (theme: CurrentAlephaTheme) => void,
+  ThemeExpert,
 ] => {
   useStore(alephaThemeAtom);
+  useStore(alephaThemeOverridesAtom);
 
   const themeProvider = useInject(ThemeProvider);
   const theme = themeProvider.getTheme();
@@ -27,5 +40,15 @@ export const useTheme = (): [
     themeProvider.setTheme(theme.index);
   };
 
-  return [theme, setTheme] as const;
+  const expert: ThemeExpert = {
+    overrides: themeProvider.getThemeOverrides(),
+    setOverrides: (overrides: AlephaThemeOverrides) => {
+      themeProvider.setThemeOverrides(overrides);
+    },
+    resetOverrides: () => {
+      themeProvider.resetThemeOverrides();
+    },
+  };
+
+  return [theme, setTheme, expert] as const;
 };