codeforlife 2.6.1

package/src/components/OrderedGrid.tsx

@@ -0,0 +1,92 @@
+import type React from "react"
+import { Unstable_Grid2 as Grid, type Grid2Props } from "@mui/material"
+
+interface ItemProps
+  extends Omit<
+    Grid2Props,
+    | "key"
+    | "order"
+    | "xs"
+    | "sm"
+    | "md"
+    | "lg"
+    | "xl"
+    | "xsOffset"
+    | "smOffset"
+    | "mdOffset"
+    | "lgOffset"
+    | "xlOffset"
+  > {}
+
+interface GlobalItemProps extends ItemProps {
+  xs: number
+  sm: number
+  md: number
+  lg: number
+  xl: number
+}
+
+export interface OrderedGridProps {
+  rows: Array<
+    Array<{
+      element: React.ReactElement
+      itemProps?: ItemProps
+    }>
+  >
+  containerProps?: Omit<Grid2Props, "container">
+  globalItemProps: GlobalItemProps
+}
+
+const OrderedGrid: React.FC<OrderedGridProps> = ({
+  rows,
+  containerProps = {},
+  globalItemProps,
+}) => {
+  const columns = Number(containerProps.columns ?? 12)
+
+  const getItemsPerRow = (size: number): number => Math.floor(columns / size)
+
+  const getOrder = (
+    rowIndex: number,
+    itemIndex: number,
+    size: number,
+  ): number =>
+    Math.floor(itemIndex / getItemsPerRow(size)) * rows.length + rowIndex
+
+  const getOffset = (itemIndex: number, size: number): number => {
+    const itemsOnLastRow = rows[0].length % getItemsPerRow(size)
+    return itemsOnLastRow !== 0 && itemIndex === rows[0].length - 1
+      ? (columns - itemsOnLastRow * size) / 2
+      : 0
+  }
+
+  return (
+    <Grid container {...containerProps}>
+      {rows.map((row, rowIndex) =>
+        row.map(({ element, itemProps = {} }, itemIndex) => (
+          <Grid
+            key={`${rowIndex}-${itemIndex}`}
+            order={{
+              xs: getOrder(rowIndex, itemIndex, globalItemProps.xs),
+              sm: getOrder(rowIndex, itemIndex, globalItemProps.sm),
+              md: getOrder(rowIndex, itemIndex, globalItemProps.md),
+              lg: getOrder(rowIndex, itemIndex, globalItemProps.lg),
+              xl: getOrder(rowIndex, itemIndex, globalItemProps.xl),
+            }}
+            xsOffset={getOffset(itemIndex, globalItemProps.xs)}
+            smOffset={getOffset(itemIndex, globalItemProps.sm)}
+            mdOffset={getOffset(itemIndex, globalItemProps.md)}
+            lgOffset={getOffset(itemIndex, globalItemProps.lg)}
+            xlOffset={getOffset(itemIndex, globalItemProps.xl)}
+            {...globalItemProps}
+            {...itemProps}
+          >
+            {element}
+          </Grid>
+        )),
+      )}
+    </Grid>
+  )
+}
+
+export default OrderedGrid

package/src/components/ScrollIntoViewLink.tsx

@@ -0,0 +1,23 @@
+import { type FC } from "react"
+import { Link, type LinkProps } from "@mui/material"
+
+export interface ScrollIntoViewLinkProps extends Omit<LinkProps, "onClick"> {
+  elementId: string
+  options?: ScrollIntoViewOptions
+}
+
+const ScrollIntoViewLink: FC<ScrollIntoViewLinkProps> = ({
+  elementId,
+  options,
+  ...linkProps
+}) => (
+  <Link
+    {...linkProps}
+    onClick={() => {
+      const element = document.getElementById(elementId)
+      element?.scrollIntoView(options)
+    }}
+  />
+)
+
+export default ScrollIntoViewLink

package/src/components/SyncError.tsx

@@ -0,0 +1,14 @@
+import { SyncProblem as SyncProblemIcon } from "@mui/icons-material"
+import { Stack, Typography } from "@mui/material"
+import { type FC } from "react"
+
+export interface SyncErrorProps {}
+
+const SyncError: FC<SyncErrorProps> = () => (
+  <Stack alignItems="center" alignContent="center">
+    <SyncProblemIcon color="error" />
+    <Typography color="error.main">Failed to sync data</Typography>
+  </Stack>
+)
+
+export default SyncError

package/src/components/TablePagination.tsx

@@ -0,0 +1,132 @@
+import {
+  TablePagination as MuiTablePagination,
+  type TablePaginationProps as MuiTablePaginationProps,
+  Stack,
+  type StackProps,
+  type TablePaginationBaseProps,
+} from "@mui/material"
+import type { TypedUseLazyQuery } from "@reduxjs/toolkit/query/react"
+import {
+  type ElementType,
+  type JSXElementConstructor,
+  type ReactNode,
+  useEffect,
+} from "react"
+
+import { type Pagination, usePagination } from "../hooks/api"
+import { type ListArg, type ListResult, handleResultState } from "../utils/api"
+
+export type TablePaginationProps<
+  QueryArg extends ListArg,
+  ResultType extends ListResult<any>,
+  RootComponent extends
+    ElementType = JSXElementConstructor<TablePaginationBaseProps>,
+  AdditionalProps = {},
+> = Omit<
+  MuiTablePaginationProps<RootComponent, AdditionalProps>,
+  | "component"
+  | "count"
+  | "rowsPerPage"
+  | "onRowsPerPageChange"
+  | "rowsPerPageOptions"
+  | "page"
+  | "onPageChange"
+> &
+  Partial<
+    Pick<
+      MuiTablePaginationProps<RootComponent, AdditionalProps>,
+      "onRowsPerPageChange" | "onPageChange"
+    >
+  > & {
+    children: (
+      data: ResultType["data"],
+      pagination: Pagination & { count?: number; maxLimit?: number },
+    ) => ReactNode
+    useLazyListQuery: TypedUseLazyQuery<ResultType, QueryArg, any>
+    preferCacheValue?: boolean
+    filters?: Omit<QueryArg, "limit" | "offset">
+    rowsPerPageOptions?: number[]
+    stackProps?: StackProps
+    page?: number
+    rowsPerPage?: number
+  }
+
+const TablePagination = <
+  QueryArg extends ListArg,
+  ResultType extends ListResult<any>,
+  RootComponent extends
+    ElementType = JSXElementConstructor<TablePaginationBaseProps>,
+  AdditionalProps = {},
+>({
+  children,
+  useLazyListQuery,
+  preferCacheValue,
+  filters,
+  page: initialPage = 0,
+  rowsPerPage: initialLimit = 50,
+  rowsPerPageOptions = [50, 100, 150],
+  stackProps,
+  onRowsPerPageChange,
+  onPageChange,
+  ...tablePaginationProps
+}: TablePaginationProps<
+  QueryArg,
+  ResultType,
+  RootComponent,
+  AdditionalProps
+>): JSX.Element => {
+  const [trigger, result] = useLazyListQuery()
+  const [{ limit, page, offset }, setPagination] = usePagination({
+    page: initialPage,
+    limit: initialLimit,
+  })
+
+  useEffect(
+    () => {
+      trigger({ limit, offset, ...filters } as QueryArg, preferCacheValue)
+    },
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [trigger, limit, offset, ...Object.values(filters || {}), preferCacheValue],
+  )
+
+  const { count, max_limit } = result.data || {}
+
+  if (max_limit) {
+    rowsPerPageOptions = rowsPerPageOptions.filter(
+      option => option <= max_limit,
+    )
+  }
+
+  return (
+    <Stack {...stackProps}>
+      {handleResultState(result, ({ data }) =>
+        children(data, {
+          limit,
+          page,
+          offset,
+          count,
+          maxLimit: max_limit,
+        }),
+      )}
+      <MuiTablePagination
+        component="div"
+        count={count ?? 0}
+        rowsPerPage={limit}
+        onRowsPerPageChange={event => {
+          setPagination({ limit: parseInt(event.target.value), page: 0 })
+          if (onRowsPerPageChange) onRowsPerPageChange(event)
+        }}
+        page={page}
+        onPageChange={(event, page) => {
+          setPagination(({ limit }) => ({ limit, page }))
+          if (onPageChange) onPageChange(event, page)
+        }}
+        // ascending order
+        rowsPerPageOptions={rowsPerPageOptions.sort((a, b) => a - b)}
+        {...tablePaginationProps}
+      />
+    </Stack>
+  )
+}
+
+export default TablePagination

package/src/components/YouTubeVideo.tsx

@@ -0,0 +1,26 @@
+import type React from "react"
+import { Box, type BoxProps } from "@mui/material"
+
+export interface YouTubeVideoProps extends Omit<BoxProps, "component"> {
+  src: string
+}
+
+const YouTubeVideo: React.FC<YouTubeVideoProps> = ({
+  src,
+  style = {},
+  ...otherProps
+}) => {
+  return (
+    <Box
+      component="iframe"
+      width="100%"
+      src={src}
+      title="YouTube video player"
+      allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share; fullscreen"
+      style={{ border: "0px", aspectRatio: "16 / 9", ...style }}
+      {...otherProps}
+    />
+  )
+}
+
+export default YouTubeVideo

package/src/components/form/ApiAutocompleteField.tsx

@@ -0,0 +1,180 @@
+import { Button, CircularProgress, type ChipTypeMap } from "@mui/material"
+import type { TypedUseLazyQuery } from "@reduxjs/toolkit/query/react"
+import {
+  Children,
+  forwardRef,
+  useEffect,
+  useState,
+  type ElementType,
+} from "react"
+
+import {
+  AutocompleteField,
+  type AutocompleteFieldProps,
+} from "../../components/form"
+import { usePagination } from "../../hooks/api"
+import type { ListArg, ListResult, ModelId } from "../../utils/api"
+import SyncError from "../SyncError"
+
+export interface ApiAutocompleteFieldProps<
+  SearchKey extends keyof Omit<QueryArg, "limit" | "offset">,
+  // api type args
+  QueryArg extends ListArg,
+  ResultType extends ListResult<any>,
+  // autocomplete type args
+  Multiple extends boolean | undefined = false,
+  DisableClearable extends boolean | undefined = false,
+  FreeSolo extends boolean | undefined = false,
+  ChipComponent extends ElementType = ChipTypeMap["defaultComponent"],
+> extends Omit<
+    AutocompleteFieldProps<
+      ModelId,
+      Multiple,
+      DisableClearable,
+      FreeSolo,
+      ChipComponent
+    >,
+    | "options"
+    | "ListboxComponent"
+    | "filterOptions"
+    | "getOptionLabel"
+    | "getOptionKey"
+    | "onInputChange"
+  > {
+  useLazyListQuery: TypedUseLazyQuery<ResultType, QueryArg, any>
+  filterOptions?: Omit<QueryArg, "limit" | "offset" | SearchKey>
+  getOptionLabel: (result: ResultType["data"][number]) => string
+  getOptionKey?: (result: ResultType["data"][number]) => ModelId
+  searchKey: SearchKey
+}
+
+const ApiAutocompleteField = <
+  SearchKey extends keyof Omit<QueryArg, "limit" | "offset">,
+  // api type args
+  QueryArg extends ListArg,
+  ResultType extends ListResult<any>,
+  // autocomplete type args
+  Multiple extends boolean | undefined = false,
+  DisableClearable extends boolean | undefined = false,
+  FreeSolo extends boolean | undefined = false,
+  ChipComponent extends ElementType = ChipTypeMap["defaultComponent"],
+>({
+  useLazyListQuery,
+  filterOptions,
+  getOptionLabel,
+  getOptionKey = result => result.id,
+  searchKey,
+  ...otherAutocompleteFieldProps
+}: ApiAutocompleteFieldProps<
+  SearchKey,
+  // api type args
+  QueryArg,
+  ResultType,
+  // autocomplete type args
+  Multiple,
+  DisableClearable,
+  FreeSolo,
+  ChipComponent
+>): JSX.Element => {
+  const [search, setSearch] = useState("")
+  const [trigger, { isLoading, isError }] = useLazyListQuery()
+  const [{ limit, offset }, setPagination] = usePagination()
+  const [{ options, hasMore }, setState] = useState<{
+    options: Record<ModelId, ResultType["data"][number]>
+    hasMore: boolean
+  }>({ options: {}, hasMore: true })
+
+  // Call api
+  useEffect(
+    () => {
+      const arg = { limit, offset, ...filterOptions } as QueryArg
+      // @ts-expect-error
+      if (search) arg[searchKey] = search
+
+      trigger(arg, true)
+        .unwrap()
+        .then(({ data, offset, limit, count }) => {
+          setState(({ options: previousOptions }) => {
+            const options = { ...previousOptions }
+            data.forEach(result => {
+              options[getOptionKey(result)] = result
+            })
+            return { options, hasMore: offset + limit < count }
+          })
+        })
+        .catch(error => {
+          if (error) console.error(error)
+          // TODO: gracefully handle error
+        })
+    },
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [
+      trigger,
+      limit,
+      offset,
+      searchKey,
+      search,
+      // eslint-disable-next-line react-hooks/exhaustive-deps
+      ...Object.values(filterOptions || {}),
+    ],
+  )
+
+  // Get options keys
+  let optionKeys: ModelId[] = Object.keys(options)
+  if (!optionKeys.length) return <></>
+  if (typeof getOptionKey(Object.values(options)[0]) === "number") {
+    optionKeys = optionKeys.map(Number)
+  }
+
+  function loadNextPage() {
+    setPagination(({ page, limit }) => ({ page: page + 1, limit }))
+  }
+
+  return (
+    <AutocompleteField
+      options={optionKeys}
+      getOptionLabel={id => getOptionLabel(options[id])}
+      onInputChange={(_, value, reason) => {
+        setSearch(reason === "input" ? value : "")
+      }}
+      ListboxComponent={forwardRef(({ children, ...props }, ref) => {
+        const listItems = Children.toArray(children)
+        if (isLoading) listItems.push(<CircularProgress key="is-loading" />)
+        else {
+          if (isError) listItems.push(<SyncError key="is-error" />)
+          if (hasMore) {
+            listItems.push(
+              <Button key="load-more" onClick={loadNextPage}>
+                Load more
+              </Button>,
+            )
+          }
+        }
+
+        return (
+          <ul
+            {...props}
+            // @ts-expect-error
+            ref={ref}
+            onScroll={event => {
+              // If not already loading and scrolled to bottom
+              if (
+                !isLoading &&
+                event.currentTarget.clientHeight +
+                  event.currentTarget.scrollTop >=
+                  event.currentTarget.scrollHeight
+              ) {
+                loadNextPage()
+              }
+            }}
+          >
+            {listItems}
+          </ul>
+        )
+      })}
+      {...otherAutocompleteFieldProps}
+    />
+  )
+}
+
+export default ApiAutocompleteField

package/src/components/form/AutocompleteField.tsx

@@ -0,0 +1,124 @@
+import {
+  Autocomplete,
+  TextField,
+  type AutocompleteProps,
+  type ChipTypeMap,
+  type TextFieldProps,
+} from "@mui/material"
+import { Field, type FieldConfig, type FieldProps } from "formik"
+import { type ElementType } from "react"
+import {
+  number as YupNumber,
+  string as YupString,
+  type ValidateOptions,
+} from "yup"
+
+import { schemaToFieldValidator } from "../../utils/form"
+import { getNestedProperty } from "../../utils/general"
+
+export interface AutocompleteFieldProps<
+  Value extends string | number,
+  Multiple extends boolean | undefined = false,
+  DisableClearable extends boolean | undefined = false,
+  FreeSolo extends boolean | undefined = false,
+  ChipComponent extends ElementType = ChipTypeMap["defaultComponent"],
+> extends Omit<
+    AutocompleteProps<
+      Value,
+      Multiple,
+      DisableClearable,
+      FreeSolo,
+      ChipComponent
+    >,
+    "renderInput" | "defaultValue" | "onChange" | "onBlur" | "value"
+  > {
+  textFieldProps: Omit<
+    TextFieldProps,
+    | "name"
+    | "value"
+    | "onChange"
+    | "onBlur"
+    | "error"
+    | "helperText"
+    | "defaultValue"
+    | "type"
+  > & {
+    name: string
+  }
+  validateOptions?: ValidateOptions
+}
+
+const AutocompleteField = <
+  Value extends string | number,
+  Multiple extends boolean | undefined = false,
+  DisableClearable extends boolean | undefined = false,
+  FreeSolo extends boolean | undefined = false,
+  ChipComponent extends ElementType = ChipTypeMap["defaultComponent"],
+>({
+  textFieldProps,
+  options,
+  validateOptions,
+  ...otherAutocompleteProps
+}: AutocompleteFieldProps<
+  Value,
+  Multiple,
+  DisableClearable,
+  FreeSolo,
+  ChipComponent
+>): JSX.Element => {
+  const { id, name, required, ...otherTextFieldProps } = textFieldProps
+
+  const dotPath = name.split(".")
+
+  const message = "not a valid option"
+  let schema =
+    typeof options[0] === "string"
+      ? YupString().oneOf(options as readonly string[], message)
+      : YupNumber().oneOf(options as readonly number[], message)
+  if (required) schema = schema.required()
+
+  const fieldConfig: FieldConfig = {
+    name,
+    type: typeof options[0] === "string" ? "text" : "number",
+    validate: schemaToFieldValidator(schema, validateOptions),
+  }
+
+  return (
+    <Field {...fieldConfig}>
+      {({ form, meta }: FieldProps) => {
+        const value = getNestedProperty(form.values, dotPath)
+        const touched = getNestedProperty(form.touched, dotPath)
+        const error = getNestedProperty(form.errors, dotPath)
+
+        return (
+          <Autocomplete
+            options={options}
+            defaultValue={
+              meta.initialValue === "" ? undefined : meta.initialValue
+            }
+            renderInput={({ id: _, ...otherParams }) => (
+              <TextField
+                id={id ?? name}
+                name={name}
+                required={required}
+                type="text" // Force to be string to avoid number incrementor/decrementor
+                value={value}
+                error={touched && Boolean(error)}
+                helperText={(touched && error) as false | string}
+                {...otherTextFieldProps}
+                {...otherParams}
+              />
+            )}
+            onChange={(_, value) => {
+              form.setFieldValue(name, value ?? undefined, true)
+            }}
+            onBlur={form.handleBlur}
+            {...otherAutocompleteProps}
+          />
+        )
+      }}
+    </Field>
+  )
+}
+
+export default AutocompleteField

package/src/components/form/CheckboxField.tsx

@@ -0,0 +1,81 @@
+import {
+  Checkbox,
+  FormControl,
+  FormControlLabel,
+  FormHelperText,
+  type CheckboxProps,
+  type FormControlLabelProps,
+} from "@mui/material"
+import { Field, type FieldConfig, type FieldProps } from "formik"
+import { type FC } from "react"
+import { bool as YupBool, type ValidateOptions } from "yup"
+
+import { schemaToFieldValidator } from "../../utils/form"
+import { getNestedProperty } from "../../utils/general"
+
+export interface CheckboxFieldProps
+  extends Omit<
+    CheckboxProps,
+    "defaultChecked" | "value" | "onChange" | "onBlur"
+  > {
+  name: string
+  formControlLabelProps: Omit<FormControlLabelProps, "control">
+  errorMessage?: string
+  validateOptions?: ValidateOptions
+}
+
+const CheckboxField: FC<CheckboxFieldProps> = ({
+  id,
+  name,
+  formControlLabelProps,
+  required = false,
+  errorMessage = "this is a required field",
+  validateOptions,
+  ...otherCheckboxProps
+}) => {
+  const dotPath = name.split(".")
+
+  let schema = YupBool()
+  if (required) schema = schema.oneOf([true], errorMessage)
+
+  const fieldConfig: FieldConfig = {
+    name,
+    type: "checkbox",
+    validate: schemaToFieldValidator(schema, validateOptions),
+  }
+
+  return (
+    <Field {...fieldConfig}>
+      {({ form, meta }: FieldProps) => {
+        const touched = getNestedProperty(form.touched, dotPath)
+        const error = getNestedProperty(form.errors, dotPath)
+        const value = getNestedProperty(form.values, dotPath)
+
+        const hasError = touched && Boolean(error)
+
+        // https://mui.com/material-ui/react-checkbox/#formgroup
+        return (
+          <FormControl error={hasError} required={required}>
+            <FormControlLabel
+              control={
+                <Checkbox
+                  defaultChecked={meta.initialValue}
+                  id={id ?? name}
+                  name={name}
+                  value={value}
+                  onChange={form.handleChange}
+                  onBlur={form.handleBlur}
+                  {...otherCheckboxProps}
+                />
+              }
+              {...formControlLabelProps}
+            />
+            {hasError && <FormHelperText>{error as string}</FormHelperText>}
+          </FormControl>
+        )
+      }}
+    </Field>
+  )
+}
+
+export default CheckboxField