@alepha/ui 0.11.5 → 0.11.7

package/src/components/form/ControlQueryBuilder.tsx

@@ -0,0 +1,313 @@
+import type { TObject } from "@alepha/core";
+import { parseQueryString } from "@alepha/postgres";
+import { useEvents } from "@alepha/react";
+import {
+  ActionIcon,
+  Badge,
+  Divider,
+  Flex,
+  Group,
+  Popover,
+  Stack,
+  Text,
+  TextInput,
+  type TextInputProps,
+} from "@mantine/core";
+import { IconFilter, IconInfoTriangle, IconX } from "@tabler/icons-react";
+import { useRef, useState } from "react";
+import { ui } from "../../constants/ui.ts";
+import {
+  extractSchemaFields,
+  OPERATOR_INFO,
+  type SchemaField,
+} from "../../utils/extractSchemaFields.ts";
+import ActionButton from "../buttons/ActionButton.tsx";
+
+export interface ControlQueryBuilderProps
+  extends Omit<TextInputProps, "value" | "onChange"> {
+  schema?: TObject;
+  value?: string;
+  onChange?: (value: string) => void;
+  placeholder?: string;
+}
+
+/**
+ * Query builder with text input and help popover.
+ * Generates query strings for parseQueryString syntax.
+ */
+const ControlQueryBuilder = ({
+  schema,
+  value = "",
+  onChange,
+  placeholder = "Enter query or click for assistance...",
+  ...textInputProps
+}: ControlQueryBuilderProps) => {
+  const [helpOpened, setHelpOpened] = useState(false);
+  const [textValue, setTextValue] = useState(value);
+  const inputRef = useRef<HTMLInputElement>(null);
+  const fields = schema ? extractSchemaFields(schema) : [];
+  const [error, setError] = useState<string | null>(null);
+
+  const isValid = (value: string) => {
+    try {
+      parseQueryString(value.trim());
+    } catch (e) {
+      setError((e as Error).message);
+      return false;
+    }
+    setError(null);
+    return true;
+  };
+
+  const handleTextChange = (newValue: string) => {
+    setTextValue(newValue);
+    if (isValid(newValue)) {
+      onChange?.(newValue);
+    }
+  };
+
+  const handleClear = () => {
+    setTextValue("");
+    onChange?.("");
+    isValid("");
+  };
+
+  const handleInsert = (text: string) => {
+    const newValue = textValue ? `${textValue}${text} ` : `${text} `;
+    setTextValue(newValue);
+    if (isValid(newValue)) {
+      onChange?.(newValue);
+    }
+    // Refocus the input after inserting
+    setTimeout(() => {
+      inputRef.current?.focus();
+      // set cursor to end
+      const length = inputRef.current?.value.length || 0;
+      inputRef.current?.setSelectionRange(length, length);
+    }, 0);
+  };
+
+  useEvents(
+    {
+      "form:change": (event) => {
+        if (event.id === inputRef.current?.form?.id) {
+          if (event.path === (textInputProps as any)["data-path"]) {
+            setTextValue(event.value ?? "");
+          }
+        }
+      },
+    },
+    [],
+  );
+
+  return (
+    <Popover
+      width={800}
+      position="bottom-start"
+      shadow="md"
+      opened={helpOpened}
+      onChange={setHelpOpened}
+      closeOnClickOutside
+      closeOnEscape
+      transitionProps={{
+        transition: "fade-up",
+        duration: 200,
+        timingFunction: "ease",
+      }}
+    >
+      <Popover.Target>
+        <TextInput
+          ref={inputRef}
+          placeholder={placeholder}
+          value={textValue}
+          onChange={(e) => handleTextChange(e.currentTarget.value)}
+          onFocus={() => setHelpOpened(true)}
+          leftSection={
+            error ? <IconInfoTriangle size={16} /> : <IconFilter size={16} />
+          }
+          rightSection={
+            textValue && (
+              <ActionIcon
+                size="sm"
+                variant="subtle"
+                color="gray"
+                onClick={handleClear}
+              >
+                <IconX size={14} />
+              </ActionIcon>
+            )
+          }
+          {...textInputProps}
+        />
+      </Popover.Target>
+      <Popover.Dropdown
+        bg={"transparent"}
+        p={"xs"}
+        bd={`1px solid ${ui.colors.border}`}
+        style={{
+          backdropFilter: "blur(20px)",
+        }}
+      >
+        <QueryHelp fields={fields} onInsert={handleInsert} />
+      </Popover.Dropdown>
+    </Popover>
+  );
+};
+
+// ---------------------------------------------------------------------------------------------------------------------
+// Query Help Component
+// ---------------------------------------------------------------------------------------------------------------------
+
+interface QueryHelpProps {
+  fields: SchemaField[];
+  onInsert: (text: string) => void;
+}
+
+function QueryHelp({ fields, onInsert }: QueryHelpProps) {
+  return (
+    <Group
+      gap="md"
+      align="flex-start"
+      wrap="nowrap"
+      bg={ui.colors.surface}
+      p={"sm"}
+      bdrs={"sm"}
+    >
+      {/* Left Column: Operators */}
+      <Stack gap="md" style={{ flex: 1 }}>
+        {/* Available Operators */}
+        <Stack gap="xs">
+          <Text size="sm" fw={600}>
+            Operators
+          </Text>
+          <Stack gap={4}>
+            {Object.entries(OPERATOR_INFO).map(([key, info]) => (
+              <Group key={key} gap="xs" wrap="nowrap">
+                <ActionButton
+                  px={"xs"}
+                  size={"xs"}
+                  h={24}
+                  variant={"default"}
+                  justify={"center"}
+                  miw={48}
+                  onClick={() => onInsert(info.symbol)}
+                >
+                  {info.symbol}
+                </ActionButton>
+                <Text size="xs" c="dimmed" style={{ flex: 1 }}>
+                  {info.label}
+                </Text>
+              </Group>
+            ))}
+          </Stack>
+        </Stack>
+
+        <Divider />
+
+        {/* Logic Operators */}
+        <Stack gap="xs">
+          <Text size="sm" fw={600}>
+            Logic
+          </Text>
+          <Stack gap={4}>
+            <Group gap="xs" wrap="nowrap">
+              <ActionButton
+                px={"xs"}
+                size={"xs"}
+                h={24}
+                variant={"default"}
+                justify={"center"}
+                miw={48}
+                onClick={() => onInsert("&")}
+              >
+                &
+              </ActionButton>
+              <Text size="xs" c="dimmed">
+                AND
+              </Text>
+            </Group>
+            <Group gap="xs" wrap="nowrap">
+              <ActionButton
+                px={"xs"}
+                size={"xs"}
+                h={24}
+                variant={"default"}
+                justify={"center"}
+                miw={48}
+                onClick={() => onInsert("|")}
+              >
+                |
+              </ActionButton>
+              <Text size="xs" c="dimmed">
+                OR
+              </Text>
+            </Group>
+          </Stack>
+        </Stack>
+      </Stack>
+
+      {/* Divider */}
+      {fields.length > 0 && <Divider orientation="vertical" />}
+
+      {/* Right Column: Fields */}
+      {fields.length > 0 && (
+        <Flex direction={"column"} gap="xs" style={{ flex: 2 }}>
+          <Text size="sm" fw={600}>
+            Fields
+          </Text>
+          <Flex
+            direction={"column"}
+            gap={4}
+            style={{ maxHeight: 300, overflowY: "auto" }}
+          >
+            {fields.map((field) => (
+              <Flex key={field.path} gap="xs" wrap="nowrap" align="flex-start">
+                <ActionButton
+                  px={"xs"}
+                  size={"xs"}
+                  h={24}
+                  variant={"default"}
+                  justify={"end"}
+                  miw={120}
+                  onClick={() => onInsert(field.path)}
+                >
+                  {field.path}
+                </ActionButton>
+                <Flex
+                  mt={3}
+                  direction={"column"}
+                  gap={2}
+                  style={{ flex: 1, minWidth: 0 }}
+                >
+                  <Text size="xs" c="dimmed" lineClamp={1}>
+                    {field.description || field.type}
+                  </Text>
+                  {field.enum && (
+                    <Group gap={0} wrap="wrap">
+                      {field.enum.map((enumValue) => (
+                        <ActionButton
+                          px={"xs"}
+                          size={"xs"}
+                          h={24}
+                          key={enumValue}
+                          onClick={() => onInsert(enumValue)}
+                        >
+                          {enumValue}
+                        </ActionButton>
+                      ))}
+                    </Group>
+                  )}
+                </Flex>
+                <Badge size="xs" variant="light" style={{ flexShrink: 0 }}>
+                  {field.type}
+                </Badge>
+              </Flex>
+            ))}
+          </Flex>
+        </Flex>
+      )}
+    </Group>
+  );
+}
+
+export default ControlQueryBuilder;

package/src/components/form/ControlSelect.tsx

@@ -97,7 +97,7 @@ const ControlSelect = (props: ControlSelectProps) => {
 
     return (
       <Input.Wrapper {...inputProps}>
-        <Flex mt={"calc(var(--mantine-spacing-xs) / 2)"}>
+        <Flex>
           <SegmentedControl
             disabled={inputProps.disabled}
             defaultValue={String(props.input.props.defaultValue)}

package/src/components/form/TypeForm.tsx

@@ -19,6 +19,7 @@ export interface TypeFormProps<T extends TObject> {
         lg?: number;
         xl?: number;
       };
+  schema?: TObject;
   children?: (input: FormModel<T>["input"]) => ReactNode;
   controlProps?: Partial<Omit<ControlProps, "input">>;
   skipFormElement?: boolean;
@@ -63,11 +64,12 @@ const TypeForm = <T extends TObject>(props: TypeFormProps<T>) => {
     submitButtonProps,
   } = props;
 
-  if (!form.options?.schema?.properties) {
+  const schema = props.schema || form.options.schema;
+  if (!schema?.properties) {
     return null;
   }
 
-  const fieldNames = Object.keys(form.options.schema.properties);
+  const fieldNames = Object.keys(schema.properties);
 
   // Filter out unsupported field types (objects only, arrays are now supported)
   const supportedFields = fieldNames.filter((fieldName) => {
@@ -140,11 +142,11 @@ const TypeForm = <T extends TObject>(props: TypeFormProps<T>) => {
     <Flex direction={"column"} gap={"sm"}>
       {renderFields()}
       {!skipSubmitButton && (
-        <Flex>
+        <Flex gap={"sm"}>
           <ActionButton form={form} {...submitButtonProps}>
             {submitButtonProps?.children ?? "Submit"}
           </ActionButton>
-          <button type={"reset"}>Reset</button>
+          <ActionButton type={"reset"}>Reset</ActionButton>
         </Flex>
       )}
     </Flex>

package/src/components/layout/AdminShell.tsx

@@ -27,7 +27,14 @@ export interface AdminShellProps {
 
 declare module "@alepha/core" {
   interface State {
+    /**
+     * Whether the sidebar is opened or closed.
+     */
     "alepha.ui.sidebar.opened"?: boolean;
+
+    /**
+     * Whether the sidebar is collapsed (narrow) or expanded (wide).
+     */
     "alepha.ui.sidebar.collapsed"?: boolean;
   }
 }

package/src/components/layout/Sidebar.tsx

@@ -56,18 +56,20 @@ export const Sidebar = (props: SidebarProps) => {
       if (item.type === "section") {
         if (props.collapsed) return;
         return (
-          <Text
-            key={key}
-            size={"xs"}
-            c={"dimmed"}
-            mt={"md"}
-            mb={"xs"}
-            mx={"sm"}
-            tt={"uppercase"}
-            fw={"bold"}
-          >
-            {item.label}
-          </Text>
+          <Flex mt={"md"} mb={"xs"} align={"center"} gap={"xs"}>
+            <ThemeIcon c={"dimmed"} size={"xs"} variant={"transparent"}>
+              {item.icon}
+            </ThemeIcon>
+            <Text
+              key={key}
+              size={"xs"}
+              c={"dimmed"}
+              tt={"uppercase"}
+              fw={"bold"}
+            >
+              {item.label}
+            </Text>
+          </Flex>
         );
       }
     }
@@ -191,7 +193,9 @@ export const SidebarItem = (props: SidebarItemProps) => {
   if (level > maxLevel) return null;
 
   const handleItemClick = (e: MouseEvent) => {
-    e.preventDefault();
+    if (!props.item.target) {
+      e.preventDefault();
+    }
     if (item.children && item.children.length > 0) {
       setIsOpen(!isOpen);
     } else {
@@ -206,6 +210,7 @@ export const SidebarItem = (props: SidebarItemProps) => {
         w={"100%"}
         justify="space-between"
         href={props.item.href}
+        target={props.item.target}
         variant={"subtle"}
         size={
           props.item.theme?.size ??
@@ -310,7 +315,9 @@ const SidebarCollapsedItem = (props: SidebarItemProps) => {
   const [isOpen, setIsOpen] = useState<boolean>(isActive(item));
 
   const handleItemClick = (e: MouseEvent) => {
-    e.preventDefault();
+    if (!props.item.target) {
+      e.preventDefault();
+    }
     if (item.children && item.children.length > 0) {
       setIsOpen(!isOpen);
     } else {
@@ -332,6 +339,7 @@ const SidebarCollapsedItem = (props: SidebarItemProps) => {
       onClick={handleItemClick}
       icon={item.icon ?? <IconSquareRounded />}
       href={props.item.href}
+      target={props.item.target}
       menu={
         item.children
           ? {
@@ -384,6 +392,7 @@ export interface SidebarSearch extends SidebarAbstractItem {
 export interface SidebarSection extends SidebarAbstractItem {
   type: "section";
   label: string;
+  icon?: ReactNode;
 }
 
 export interface SidebarMenuItem extends SidebarAbstractItem {
@@ -391,6 +400,7 @@ export interface SidebarMenuItem extends SidebarAbstractItem {
   description?: string;
   icon?: ReactNode;
   href?: string;
+  target?: "_blank" | "_self" | "_parent" | "_top";
   activeStartsWith?: boolean; // Use startWith matching for active state
   onClick?: () => void;
   children?: SidebarMenuItem[];