create-warlock 5.40.0 → 5.41.0

package/templates/design-system-mantine/src/web/design-system/components/email-input.tsx

@@ -0,0 +1,21 @@
+import { TextInput as MantineTextInput } from "@mantine/core";
+import { useControl } from "../hooks/use-control";
+import type { ControlProps } from "../types/control-props";
+import { frameProps } from "./field-frame";
+
+export default function EmailInput(props: ControlProps) {
+  const field = useControl(props, "email");
+  const { ref: bindRef } = field.binding;
+  return (
+    <MantineTextInput
+      {...frameProps(props, field.error, field.disabled, field.onBlur)}
+      ref={bindRef}
+      className={props.className}
+      type="email"
+      value={typeof field.value === "string" ? field.value : ""}
+      onChange={(event) => field.changeValue(event.currentTarget.value)}
+      placeholder={props.placeholder}
+      autoComplete={props.autoComplete}
+    />
+  );
+}

package/templates/design-system-mantine/src/web/design-system/components/field-frame.tsx

@@ -0,0 +1,65 @@
+import { Input } from "@mantine/core";
+import type { ReactNode } from "react";
+import type { ControlProps } from "../types/control-props";
+
+type FrameProps = Pick<ControlProps, "id" | "label" | "hint" | "error" | "dir" | "className"> & {
+  required?: boolean;
+  children: ReactNode;
+};
+
+/**
+ * The label, hint and error frame around a control that has no Mantine wrapper
+ * of its own. Mantine's own inputs take `label`, `description` and `error`
+ * directly, so they use `frameProps` instead and skip this wrapper.
+ */
+export default function FieldFrame({
+  id,
+  label,
+  hint,
+  error,
+  children,
+  dir,
+  className,
+  required,
+}: FrameProps) {
+  return (
+    <Input.Wrapper
+      id={id}
+      dir={dir}
+      className={className}
+      label={label ?? undefined}
+      description={hint}
+      error={error}
+      withAsterisk={required}
+    >
+      {children}
+    </Input.Wrapper>
+  );
+}
+
+/**
+ * The props every Mantine input shares, derived from the contract props and the
+ * value returned by `useControl`. Validation errors reach the control through
+ * Mantine's `error` prop, so Mantine owns the invalid styling and the
+ * `aria-invalid` / `aria-describedby` wiring.
+ */
+export function frameProps(
+  props: Pick<ControlProps, "id" | "name" | "label" | "hint" | "dir" | "required" | "readOnly">,
+  error: ReactNode,
+  disabled: boolean | undefined,
+  onBlur: (() => unknown) | undefined,
+) {
+  return {
+    id: props.id,
+    name: props.name,
+    label: props.label ?? undefined,
+    description: props.hint,
+    error,
+    withAsterisk: props.required,
+    disabled,
+    readOnly: props.readOnly,
+    dir: props.dir,
+    onBlur,
+    "aria-required": props.required || undefined,
+  } as const;
+}

package/templates/design-system-mantine/src/web/design-system/components/file-input.tsx

@@ -0,0 +1,32 @@
+import { FileInput as MantineFileInput } from "@mantine/core";
+import { useFileControl } from "../hooks/use-file-control";
+import type { ControlProps } from "../types/control-props";
+import { frameProps } from "./field-frame";
+
+export default function FileInput(props: ControlProps) {
+  const field = useFileControl(props);
+  const { ref: bindRef } = field.binding;
+  const files = Array.isArray(field.value)
+    ? field.value
+    : field.value instanceof File
+      ? field.value
+      : null;
+  return (
+    <MantineFileInput
+      {...frameProps(props, field.error, field.disabled, field.onBlur)}
+      ref={bindRef}
+      className={props.className}
+      disabled={field.disabled || props.readOnly}
+      accept={props.accept}
+      multiple={props.multiple}
+      placeholder={props.placeholder}
+      clearable
+      value={files as never}
+      onChange={(value: File | File[] | null) =>
+        field.changeValue(
+          props.multiple ? ((value as File[] | null) ?? []) : ((value as File | null) ?? ""),
+        )
+      }
+    />
+  );
+}

package/templates/design-system-mantine/src/web/design-system/components/multi-select-input.tsx

@@ -0,0 +1,28 @@
+import { MultiSelect } from "@mantine/core";
+import { useSelectControl } from "../hooks/use-select-control";
+import type { SelectProps } from "../types/control-props";
+import { frameProps } from "./field-frame";
+
+export default function MultiSelectInput(props: SelectProps) {
+  const field = useSelectControl(props, true);
+  const { ref: bindRef } = field.binding;
+  return (
+    <MultiSelect
+      {...frameProps(props, field.error, field.disabled, field.onBlur)}
+      ref={bindRef}
+      className={props.className}
+      data={props.options.map((option) => ({ ...option }))}
+      value={field.selected}
+      onChange={(values) => {
+        if (!field.disabled && !props.readOnly) {
+          field.changeValue(values);
+        }
+      }}
+      placeholder={props.placeholder}
+      searchable
+      clearable
+      nothingFoundMessage={props.emptyLabel ?? "No options found"}
+      clearButtonProps={{ "aria-label": props.clearLabel ?? "Clear" }}
+    />
+  );
+}

package/templates/design-system-mantine/src/web/design-system/components/paginated-table.tsx

@@ -0,0 +1,94 @@
+import { Center, Pagination, Stack, Table, Text } from "@mantine/core";
+import type { ReactNode } from "react";
+
+/** The `pagination` block of a Warlock paginated API response (`listEndpoint`, `paginate()`). */
+export type PaginationInfo = { page: number; pages: number; total?: number; limit?: number };
+
+export type PaginatedColumn<Row> = {
+  /** A stable key for the column. */
+  key: string;
+  header: ReactNode;
+  /** Render a cell; defaults to the row's `key` property as text. */
+  render?: (row: Row, index: number) => ReactNode;
+  align?: "start" | "center" | "end";
+};
+
+export type PaginatedTableProps<Row> = {
+  columns: readonly PaginatedColumn<Row>[];
+  rows: readonly Row[];
+  pagination: PaginationInfo;
+  onPageChange: (page: number) => void;
+  /** Reads a stable row key; defaults to the row's `id`, then its index. */
+  rowKey?: (row: Row, index: number) => string | number;
+  loading?: boolean;
+  emptyLabel?: ReactNode;
+  caption?: ReactNode;
+};
+
+function defaultKey(row: unknown, index: number): string | number {
+  const id = (row as { id?: unknown } | null)?.id;
+  return typeof id === "string" || typeof id === "number" ? id : index;
+}
+
+/**
+ * A Mantine `Table` with `Pagination`, driven by the response shape of a
+ * Warlock list endpoint: pass its items as `rows` and its `pagination` block
+ * as-is, then load the requested page in `onPageChange`.
+ */
+export default function PaginatedTable<Row>({
+  columns,
+  rows,
+  pagination,
+  onPageChange,
+  rowKey = defaultKey,
+  loading = false,
+  emptyLabel = "Nothing to show",
+  caption,
+}: PaginatedTableProps<Row>) {
+  return (
+    <Stack gap="md" aria-busy={loading}>
+      <Table.ScrollContainer minWidth={480}>
+        <Table striped highlightOnHover opacity={loading ? 0.6 : 1}>
+          {caption ? <Table.Caption>{caption}</Table.Caption> : null}
+          <Table.Thead>
+            <Table.Tr>
+              {columns.map((column) => (
+                <Table.Th key={column.key} ta={column.align}>
+                  {column.header}
+                </Table.Th>
+              ))}
+            </Table.Tr>
+          </Table.Thead>
+          <Table.Tbody>
+            {rows.map((row, index) => (
+              <Table.Tr key={rowKey(row, index)}>
+                {columns.map((column) => (
+                  <Table.Td key={column.key} ta={column.align}>
+                    {column.render
+                      ? column.render(row, index)
+                      : String((row as Record<string, unknown>)[column.key] ?? "")}
+                  </Table.Td>
+                ))}
+              </Table.Tr>
+            ))}
+          </Table.Tbody>
+        </Table>
+      </Table.ScrollContainer>
+      {rows.length === 0 ? (
+        <Text role="status" c="dimmed" ta="center">
+          {emptyLabel}
+        </Text>
+      ) : null}
+      {pagination.pages > 1 ? (
+        <Center>
+          <Pagination
+            total={pagination.pages}
+            value={pagination.page}
+            onChange={onPageChange}
+            disabled={loading}
+          />
+        </Center>
+      ) : null}
+    </Stack>
+  );
+}

package/templates/design-system-mantine/src/web/design-system/components/password-input.tsx

@@ -0,0 +1,20 @@
+import { PasswordInput as MantinePasswordInput } from "@mantine/core";
+import { useControl } from "../hooks/use-control";
+import type { ControlProps } from "../types/control-props";
+import { frameProps } from "./field-frame";
+
+export default function PasswordInput(props: ControlProps) {
+  const field = useControl(props, "password");
+  const { ref: bindRef } = field.binding;
+  return (
+    <MantinePasswordInput
+      {...frameProps(props, field.error, field.disabled, field.onBlur)}
+      ref={bindRef}
+      className={props.className}
+      value={typeof field.value === "string" ? field.value : ""}
+      onChange={(event) => field.changeValue(event.currentTarget.value)}
+      placeholder={props.placeholder}
+      autoComplete={props.autoComplete}
+    />
+  );
+}

package/templates/design-system-mantine/src/web/design-system/components/radio-input.tsx

@@ -0,0 +1,34 @@
+import { Radio } from "@mantine/core";
+import { useControl } from "../hooks/use-control";
+import type { RadioProps } from "../types/control-props";
+import { frameProps } from "./field-frame";
+
+export default function RadioInput(props: RadioProps) {
+  // One scalar for the whole group; the first enabled radio receives the focus ref.
+  const field = useControl(props);
+  const { ref: bindRef } = field.binding;
+  const firstEnabled = props.options.find((item) => !item.disabled);
+  return (
+    <Radio.Group
+      {...frameProps(props, field.error, field.disabled, field.onBlur)}
+      className={props.className}
+      value={typeof field.value === "string" ? field.value : ""}
+      onChange={field.changeValue}
+      readOnly={props.readOnly}
+    >
+      <div>
+        {props.options.map((option) => (
+          <Radio
+            key={option.value}
+            ref={option === firstEnabled ? bindRef : undefined}
+            id={`${props.id}-option-${encodeURIComponent(option.value)}`}
+            value={option.value}
+            label={option.label}
+            disabled={field.disabled || option.disabled}
+            mt="xs"
+          />
+        ))}
+      </div>
+    </Radio.Group>
+  );
+}

package/templates/design-system-mantine/src/web/design-system/components/select-input.tsx

@@ -0,0 +1,24 @@
+import { Select } from "@mantine/core";
+import { useSelectControl } from "../hooks/use-select-control";
+import type { SelectProps } from "../types/control-props";
+import { frameProps } from "./field-frame";
+
+export default function SelectInput(props: SelectProps) {
+  const field = useSelectControl(props, false);
+  const { ref: bindRef } = field.binding;
+  return (
+    <Select
+      {...frameProps(props, field.error, field.disabled, field.onBlur)}
+      ref={bindRef}
+      className={props.className}
+      data={props.options.map((option) => ({ ...option }))}
+      value={field.selected[0] ?? null}
+      onChange={(value) => (value === null ? field.clear() : field.select(value))}
+      placeholder={props.placeholder}
+      searchable
+      clearable
+      nothingFoundMessage={props.emptyLabel ?? "No options found"}
+      clearButtonProps={{ "aria-label": props.clearLabel ?? "Clear" }}
+    />
+  );
+}

package/templates/design-system-mantine/src/web/design-system/components/submit-button.tsx

@@ -0,0 +1,24 @@
+import { Button } from "@mantine/core";
+import { useSubmitControl } from "../hooks/use-submit-control";
+import type { ControlProps } from "../types/control-props";
+import FieldFrame from "./field-frame";
+
+export default function SubmitButton(props: ControlProps) {
+  const field = useSubmitControl(props);
+  const { ref: bindRef } = field.binding;
+  return (
+    <FieldFrame {...props} label={null} error={field.error}>
+      <Button
+        ref={bindRef}
+        id={props.id}
+        name={props.name}
+        type="submit"
+        disabled={field.disabled}
+        loading={field.isSubmitting}
+        aria-busy={field.isSubmitting}
+      >
+        {props.label}
+      </Button>
+    </FieldFrame>
+  );
+}

package/templates/design-system-mantine/src/web/design-system/components/switch-input.tsx

@@ -0,0 +1,19 @@
+import { Switch } from "@mantine/core";
+import { useControl } from "../hooks/use-control";
+import type { CheckProps } from "../types/control-props";
+import { frameProps } from "./field-frame";
+
+export default function SwitchInput(props: CheckProps) {
+  const field = useControl(props, "checkbox");
+  const { ref: bindRef } = field.binding;
+  return (
+    <Switch
+      {...frameProps(props, field.error, field.disabled, field.onBlur)}
+      ref={bindRef}
+      className={props.className}
+      disabled={field.disabled || props.readOnly}
+      checked={Boolean(field.checked)}
+      onChange={(event) => field.setChecked(event.currentTarget.checked)}
+    />
+  );
+}

package/templates/design-system-mantine/src/web/design-system/components/text-input.tsx

@@ -0,0 +1,21 @@
+import { TextInput as MantineTextInput } from "@mantine/core";
+import { useControl } from "../hooks/use-control";
+import type { ControlProps } from "../types/control-props";
+import { frameProps } from "./field-frame";
+
+export default function TextInput(props: ControlProps) {
+  const field = useControl(props, "text");
+  const { ref: bindRef } = field.binding;
+  return (
+    <MantineTextInput
+      {...frameProps(props, field.error, field.disabled, field.onBlur)}
+      ref={bindRef}
+      className={props.className}
+      type="text"
+      value={typeof field.value === "string" ? field.value : ""}
+      onChange={(event) => field.changeValue(event.currentTarget.value)}
+      placeholder={props.placeholder}
+      autoComplete={props.autoComplete}
+    />
+  );
+}

package/templates/design-system-mantine/src/web/design-system/components/textarea-input.tsx

@@ -0,0 +1,21 @@
+import { Textarea } from "@mantine/core";
+import { useControl } from "../hooks/use-control";
+import type { ControlProps } from "../types/control-props";
+import { frameProps } from "./field-frame";
+
+export default function TextareaInput(props: ControlProps) {
+  const field = useControl(props, "textarea");
+  const { ref: bindRef } = field.binding;
+  return (
+    <Textarea
+      {...frameProps(props, field.error, field.disabled, field.onBlur)}
+      ref={bindRef}
+      className={props.className}
+      rows={props.rows}
+      value={typeof field.value === "string" ? field.value : ""}
+      onChange={(event) => field.changeValue(event.currentTarget.value)}
+      placeholder={props.placeholder}
+      autoComplete={props.autoComplete}
+    />
+  );
+}

package/templates/design-system-mantine/src/web/design-system/components/time-picker-input.tsx

@@ -0,0 +1,19 @@
+import { TimeInput } from "@mantine/dates";
+import { useControl } from "../hooks/use-control";
+import type { ControlProps } from "../types/control-props";
+import { frameProps } from "./field-frame";
+
+export default function TimePickerInput(props: ControlProps) {
+  const field = useControl(props, "time");
+  const { ref: bindRef } = field.binding;
+  return (
+    <TimeInput
+      {...frameProps(props, field.error, field.disabled, field.onBlur)}
+      ref={bindRef}
+      className={props.className}
+      value={typeof field.value === "string" ? field.value : ""}
+      onChange={(event) => field.changeValue(event.currentTarget.value)}
+      placeholder={props.placeholder}
+    />
+  );
+}

package/templates/design-system-mantine/src/web/design-system/confirm.ts

@@ -0,0 +1,40 @@
+import { modals } from "@mantine/modals";
+import type { ReactNode } from "react";
+
+export type ConfirmOptions = {
+  title?: ReactNode;
+  message: ReactNode;
+  confirmLabel?: string;
+  cancelLabel?: string;
+  /** Paints the confirm button red, for deletes and other destructive actions. */
+  danger?: boolean;
+};
+
+/**
+ * Ask the visitor to confirm an action. Resolves `true` on confirm and `false`
+ * on cancel or when the modal is dismissed. Needs `DesignSystemProvider`.
+ */
+export function confirm(options: ConfirmOptions): Promise<boolean> {
+  return new Promise((resolve) => {
+    let settled = false;
+    const settle = (value: boolean) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      resolve(value);
+    };
+    modals.openConfirmModal({
+      title: options.title ?? "Please confirm",
+      children: options.message,
+      labels: {
+        confirm: options.confirmLabel ?? "Confirm",
+        cancel: options.cancelLabel ?? "Cancel",
+      },
+      confirmProps: options.danger ? { color: "red" } : undefined,
+      onConfirm: () => settle(true),
+      onCancel: () => settle(false),
+      onClose: () => settle(false),
+    });
+  });
+}

package/templates/design-system-mantine/src/web/design-system/hooks/use-control.ts

@@ -0,0 +1,30 @@
+import { useFormControl } from "@mongez/react-form";
+import type { ControlProps } from "../types/control-props";
+
+/** Explicit ids keep SSR, hydration, portal labels and repeated forms aligned. */
+export function useControl(props: ControlProps, type = "text", multiple = false) {
+  const control = useFormControl(
+    { ...props, type, multiple },
+    { multiple, isCollectable: type === "submit" ? () => false : undefined },
+  );
+  const { inputRef, visibleElementRef } = control;
+  const error = props.error ?? control.error;
+  const describedBy =
+    [props.hint ? `${props.id}-hint` : "", error ? `${props.id}-error` : ""]
+      .filter(Boolean)
+      .join(" ") || undefined;
+  const binding = {
+    id: props.id,
+    name: props.name,
+    disabled: control.disabled,
+    onBlur: control.onBlur,
+    ref: (element: HTMLElement | null) => {
+      inputRef.current = element;
+      visibleElementRef.current = element;
+    },
+    "aria-invalid": Boolean(error),
+    "aria-required": props.required || undefined,
+    "aria-describedby": describedBy,
+  };
+  return { ...control, error, binding };
+}

package/templates/design-system-mantine/src/web/design-system/hooks/use-date-control.ts

@@ -0,0 +1,51 @@
+import { useState } from "react";
+import { useControl } from "./use-control";
+import type { DateProps } from "../types/control-props";
+
+export function calendarDate(date: Date): string {
+  return `${date.getFullYear()}-${String(date.getMonth() + 1).padStart(2, "0")}-${String(date.getDate()).padStart(2, "0")}`;
+}
+export function parseCalendarDate(value: string): Date | undefined {
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(value)) {
+    return undefined;
+  }
+  const [year = 0, month = 0, day = 0] = value.split("-").map(Number);
+  const date = new Date(0);
+  date.setFullYear(year, month - 1, day);
+  date.setHours(12, 0, 0, 0);
+  return calendarDate(date) === value ? date : undefined;
+}
+export function useDateControl(props: DateProps, withTime = false) {
+  const field = useControl(props);
+  const [open, setOpen] = useState(false);
+  const value = typeof field.value === "string" ? field.value : "";
+  const [datePart = "", time = ""] = value.split("T");
+  return {
+    ...field,
+    open,
+    setOpen,
+    value,
+    time,
+    selected: parseCalendarDate(datePart),
+    select: (date: Date | undefined) => {
+      if (field.disabled || props.readOnly) {
+        return;
+      }
+      field.changeValue(date ? calendarDate(date) + (withTime ? `T${time || "00:00"}` : "") : "");
+      if (!withTime) {
+        setOpen(false);
+      }
+    },
+    changeTime: (next: string) => {
+      if (!field.disabled && !props.readOnly) {
+        field.changeValue(next && parseCalendarDate(datePart) ? `${datePart}T${next}` : "");
+      }
+    },
+    clear: () => {
+      if (!field.disabled && !props.readOnly) {
+        field.changeValue("");
+      }
+      setOpen(false);
+    },
+  };
+}

package/templates/design-system-mantine/src/web/design-system/hooks/use-file-control.ts

@@ -0,0 +1,26 @@
+import { useEffect } from "react";
+import { useControl } from "./use-control";
+import type { ControlProps } from "../types/control-props";
+
+export function useFileControl(props: ControlProps) {
+  const field = useControl(
+    { ...props, value: undefined, defaultValue: props.multiple ? [] : "" },
+    "file",
+    props.multiple,
+  );
+  useEffect(() => {
+    const clear = () => {
+      const input: HTMLInputElement | undefined = field.inputRef.current;
+      if (input) {
+        input.value = "";
+      }
+    };
+    const reset = field.formControl.onReset(clear);
+    const cleared = field.formControl.onClear(clear);
+    return () => {
+      reset.unsubscribe();
+      cleared.unsubscribe();
+    };
+  }, [field.formControl, field.inputRef]);
+  return field;
+}

package/templates/design-system-mantine/src/web/design-system/hooks/use-select-control.ts

@@ -0,0 +1,85 @@
+import { useState, type KeyboardEvent } from "react";
+import { useControl } from "./use-control";
+import type { SelectProps } from "../types/control-props";
+
+export function selectedValues(value: unknown): string[] {
+  return Array.isArray(value)
+    ? value.filter((item): item is string => typeof item === "string")
+    : typeof value === "string" && value !== ""
+      ? [value]
+      : [];
+}
+export function toggleSelection(values: readonly string[], value: string): string[] {
+  return values.includes(value) ? values.filter((item) => item !== value) : [...values, value];
+}
+export function useSelectControl(props: SelectProps, multiple = false) {
+  const field = useControl(props, "text", multiple);
+  const [open, setOpen] = useState(false);
+  const [search, setSearch] = useState("");
+  const [active, setActive] = useState(0);
+  const selected = selectedValues(field.value);
+  const filtered = props.options.filter((option) =>
+    option.label.toLocaleLowerCase().includes(search.toLocaleLowerCase()),
+  );
+  const enabled = filtered.filter((option) => !option.disabled);
+  const activeOption = enabled[Math.min(active, Math.max(0, enabled.length - 1))];
+  const select = (value: string) => {
+    if (field.disabled || props.readOnly) {
+      return;
+    }
+    field.changeValue(multiple ? toggleSelection(selected, value) : value);
+    if (!multiple) {
+      setOpen(false);
+    }
+  };
+  const onKeyDown = (event: KeyboardEvent<HTMLInputElement>) => {
+    if (["ArrowDown", "ArrowUp", "Home", "End"].includes(event.key)) {
+      event.preventDefault();
+      const current = activeOption ? enabled.indexOf(activeOption) : 0;
+      const next =
+        event.key === "Home"
+          ? 0
+          : event.key === "End"
+            ? enabled.length - 1
+            : (current + (event.key === "ArrowDown" ? 1 : -1) + enabled.length) %
+              Math.max(1, enabled.length);
+      setActive(Math.max(0, next));
+      const option = enabled[Math.max(0, next)];
+      if (option) {
+        document
+          .getElementById(`${props.id}-option-${encodeURIComponent(option.value)}`)
+          ?.scrollIntoView({ block: "nearest" });
+      }
+    } else if (
+      (event.key === "Enter" || (multiple && event.key === " " && search === "")) &&
+      activeOption
+    ) {
+      event.preventDefault();
+      select(activeOption.value);
+    }
+  };
+  return {
+    ...field,
+    open,
+    setOpen: (next: boolean) => {
+      setOpen(next && !field.disabled && !props.readOnly);
+      setSearch("");
+      setActive(0);
+    },
+    search,
+    setSearch: (next: string) => {
+      setSearch(next);
+      setActive(0);
+    },
+    selected,
+    filtered,
+    activeOption,
+    select,
+    onKeyDown,
+    clear: () => {
+      if (!field.disabled && !props.readOnly) {
+        field.changeValue(multiple ? [] : "");
+      }
+    },
+  };
+}