create-warlock 5.40.1 → 5.41.0

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 ? [] : "");
+      }
+    },
+  };
+}

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

@@ -0,0 +1,13 @@
+import { useSubmitButton } from "@mongez/react-form";
+import { useControl } from "./use-control";
+import type { ControlProps } from "../types/control-props";
+
+export function useSubmitControl(props: ControlProps) {
+  const field = useControl(props, "submit");
+  const submit = useSubmitButton();
+  return {
+    ...field,
+    disabled: field.disabled || submit.disabled || submit.isSubmitting,
+    isSubmitting: submit.isSubmitting,
+  };
+}

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

@@ -0,0 +1,32 @@
+import { createTheme, type MantineColorScheme } from "@mantine/core";
+
+/**
+ * The design tokens of this app. Edit this file; everything Mantine renders
+ * reads it through `DesignSystemProvider`.
+ *
+ * `primaryColor` takes any key of Mantine's palette (`blue`, `violet`, `teal`
+ * and so on) or a custom palette you add under `colors`.
+ */
+export const theme = createTheme({
+  primaryColor: "blue",
+  defaultRadius: "md",
+  fontFamily: 'system-ui, -apple-system, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif',
+  fontFamilyMonospace: 'ui-monospace, "Cascadia Code", Consolas, "Liberation Mono", monospace',
+  headings: {
+    fontFamily: 'system-ui, -apple-system, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif',
+  },
+  spacing: {
+    xs: "0.625rem",
+    sm: "0.75rem",
+    md: "1rem",
+    lg: "1.25rem",
+    xl: "2rem",
+  },
+});
+
+/**
+ * `auto` follows the visitor's system preference. The same value feeds the
+ * `ColorSchemeScript` in the root and the provider, so the first paint and the
+ * hydrated page agree.
+ */
+export const defaultColorScheme: MantineColorScheme = "auto";

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

@@ -0,0 +1,72 @@
+import { notifications } from "@mantine/notifications";
+import type { ReactNode } from "react";
+
+type Message = ReactNode;
+
+function show(color: string, message: Message, title?: ReactNode) {
+  return notifications.show({ color, message, title });
+}
+
+/** Toast helpers on top of `@mantine/notifications`. Call them from event handlers and callbacks. */
+export const notify = {
+  success: (message: Message, title?: ReactNode) => show("green", message, title),
+  error: (message: Message, title?: ReactNode) => show("red", message, title),
+  info: (message: Message, title?: ReactNode) => show("blue", message, title),
+  warning: (message: Message, title?: ReactNode) => show("yellow", message, title),
+};
+
+/** The first human-readable message in an HTTP result, a page-action payload or an Error. */
+export function messageFrom(value: unknown): string | undefined {
+  if (!value || typeof value !== "object") {
+    return typeof value === "string" ? value : undefined;
+  }
+  const source = value as {
+    message?: unknown;
+    formErrors?: unknown;
+    error?: { body?: unknown; message?: unknown };
+    data?: unknown;
+  };
+  if (Array.isArray(source.formErrors) && typeof source.formErrors[0] === "string") {
+    return source.formErrors[0];
+  }
+  const body = source.error?.body ?? source.data;
+  const nested =
+    body && typeof body === "object" ? (body as { message?: unknown }).message : undefined;
+  for (const candidate of [nested, source.error?.message, source.message]) {
+    if (typeof candidate === "string" && candidate !== "") {
+      return candidate;
+    }
+  }
+  return undefined;
+}
+
+type SubmitMessages = {
+  success: Message | ((result: unknown) => Message);
+  error?: Message | ((result: unknown) => Message);
+};
+
+/**
+ * Spread the result into `useSubmitForm` or `useSubmitAction` to show a toast
+ * when the submission succeeds or fails:
+ *
+ * `useSubmitForm({ route: "contact.send", ...notifyOnSubmit({ success: "Sent" }) })`
+ *
+ * Without an `error` message the server's own message is shown, falling back to
+ * a generic line.
+ */
+export function notifyOnSubmit(messages: SubmitMessages) {
+  const resolve = (message: Message | ((result: unknown) => Message), result: unknown) =>
+    typeof message === "function" ? (message as (result: unknown) => Message)(result) : message;
+  return {
+    onSuccess: (result: unknown) => {
+      notify.success(resolve(messages.success, result));
+    },
+    onError: (result: unknown) => {
+      notify.error(
+        messages.error !== undefined
+          ? resolve(messages.error, result)
+          : (messageFrom(result) ?? "Something went wrong. Please try again."),
+      );
+    },
+  };
+}

package/templates/design-system-mantine/src/web/design-system/provider.tsx

@@ -0,0 +1,28 @@
+import { ColorSchemeScript, MantineProvider } from "@mantine/core";
+import { ModalsProvider } from "@mantine/modals";
+import { Notifications } from "@mantine/notifications";
+import type { ReactNode } from "react";
+import { defaultColorScheme, theme } from "./mantine-theme";
+
+/**
+ * Mounts Mantine's theme, the modals manager and the notifications host around
+ * the page. Render it once in `src/web/root.tsx`, around `#vessel`.
+ */
+export default function DesignSystemProvider({ children }: { children: ReactNode }) {
+  return (
+    <MantineProvider theme={theme} defaultColorScheme={defaultColorScheme}>
+      <ModalsProvider>
+        <Notifications />
+        {children}
+      </ModalsProvider>
+    </MantineProvider>
+  );
+}
+
+/**
+ * Sets the stored or system colour scheme on `<html>` before first paint, so a
+ * dark-mode visitor never sees a light flash. Render it inside `<head>`.
+ */
+export function DesignSystemColorScheme({ nonce }: { nonce?: string }) {
+  return <ColorSchemeScript defaultColorScheme={defaultColorScheme} nonce={nonce} />;
+}