Imported from bghcore/formosaic (packages/mui/AGENTS.md). Install upstream with npx skills add bghcore/formosaic --skill mui. Copyright stays with the author.

AGENTS.md -- @formosaic/mui

Package Purpose

Material UI (MUI) field component implementations for @formosaic/core. Provides 22 editable and 6 read-only field types, plus a one-line registry setup via createMuiFieldRegistry().

Critical Constraints

• MUI v5 or v6 only. Use @mui/material components. Do NOT import from @material-ui/core (v4).
• @emotion/react and @emotion/styled are required peer dependencies of MUI -- consumers must install them.
• All field components receive IFieldProps<T> via React.cloneElement -- this is the contract with core's RenderField.
• Import core types from @formosaic/core, not from relative paths into the core package.
• Use React.JSX.Element not bare JSX.Element for return types.

Key Files

Adding a New Field

1. Create src/fields/MyField.tsx implementing IFieldProps<T>
2. Add export { default as MyField } from "./fields/MyField" to src/index.ts
3. Add the component key to ComponentTypes in core's src/constants.ts
4. Register it in src/registry.ts inside createMuiFieldRegistry()

Field Component Pattern

import { IFieldProps } from "@formosaic/core";
import { TextField } from "@mui/material";
import React from "react";
import { ReadOnlyText } from "../components/ReadOnlyText";
import { FieldClassName, GetFieldDataTestId } from "../helpers";

interface IMyFieldProps {
  customOption?: string;
}

const MyField = (props: IFieldProps<IMyFieldProps>) => {
  const { fieldName, testId, value, readOnly, error, setFieldValue } = props;

  const onChange = (event: React.ChangeEvent<HTMLInputElement>) => {
    setFieldValue(fieldName, event.target.value, false, 3000);
  };

  return readOnly ? (
    <ReadOnlyText fieldName={fieldName} value={value as string} />
  ) : (
    <TextField
      className={FieldClassName("my-field", error)}
      autoComplete="off"
      value={(value as string) ?? ""}
      onChange={onChange}
      size="small"
      fullWidth
      error={!!error}
      helperText={error?.message}
      inputProps={{
        "data-testid": GetFieldDataTestId(fieldName, testId),
      }}
    />
  );
};

export default MyField;

Key points:

• Props type is IFieldProps<T> where T is your custom meta props interface
• Use setFieldValue(fieldName, newValue, skipSave, debounceMs) to update the form
• Handle readOnly state by rendering ReadOnlyText or a disabled variant
• Use MUI's error and helperText props for inline validation display
• Use size="small" and fullWidth for consistent sizing with other fields
• Use FieldClassName() for consistent error styling
• Use GetFieldDataTestId() for consistent test ID generation
• Export as default export