[Index template] Refactor index template wizard

[sebelga]

This PR adds 2 new pieces of reusable functionality to the "es_ui_shared/public/forms" folder.

• Form wizard
• Multi content

I then updated the current <TemplateForm /> component used to create and edit legacy index templates to make use of them.

I also added some small changes to the mappings editor, mainly around getting its validity fixed (see issue #55051) and removed unnecessary re-renders.

The end result of this PR should be the exact same behavior from the index template creation/editing flow that we have in master... but using the reusable components.

MultiContent

The problem

Building resource creations/edition flows in the UI, that have multiple contents that need to be merged together at the end of the flow and at the same time keeping a reference of each content state, is not trivial. Indeed, when we switch tab or we go to the next step, the old step data needs to be saved somewhere.

The first thing that comes to mind is: "Ok, I'll lift the state up" and make each step "content" a controlled component (when its value changes, it sends it to the global state and then it receives it back as prop). This works well up to a certain point. What happens if the internal state that the step content works with, is not the same as the outputted state?

Something like this:

// StepOne internal state, flat map of fields
const internalState: {
  fields: {
    ate426jn: { name: 'hello', value: 'world', parent: 'rwtsdg3' },
    rwtsdg3: { name: 'myObject', type: 'object' },
  }
}

// Outputed data

const output = {
  stepOne: {
    myObject: {
      hello: 'world'
    }
  }
}

We need some sort of serializer to go from the internal state to the output object. If we lift the state up this means that the global state needs to be aware of the intrinsic of the content, leaking implementation details.
This also means that the content can't be a reusable component as it depends on an external state to do part of its work (think: the mappings editor).

This is where MultiContent comes into play. It lets us declare content objects and automatically saves a snapshot of their content when the component unmounts (which occurs when switching a tab for example). If we navigate back to the tab, the tab content gets its defaultValue from that cache state.

Let see it through a concrete example

// Always good to have an interface for our contents
interface MyMultiContent {
  contentOne: { myField: string };
  contentTwo: { anotherField: string };
  contentThree: { yetAnotherField: boolean };
}

// Each content data will be a slice of the multi-content defaultValue
const defaultValue: MyMultiContent = {
  contentOne: {
    myField: 'value',
  },
  contentTwo: {
    anotherField: 'value',
  },
  contentThree: {
    yetAnotherField: true,
  },
};

// my_comp.tsx

/**
 * We wrap our component with the HOC that will provide the <MultiContentProvider /> and let us use the "useMultiContentContext()" hook
 * 
 * MyComponent connects to the multi-content context and renders each step
 * content without worrying about their internal state.
 */
const MyComponent = WithMultiContent(() => {
  const { validation, getData, validate } = useMultiContentContext<MyMultiContent>();

  const totalSteps = 3;
  const [currentStep, setCurrentStep] = useState(0);

  const renderContent = () => {
    switch (currentStep) {
      case 0:
        return <ContentOneContainer />;
      case 1:
        return <ContentTwoContainer />;
      case 2:
        return <ContentThreeContainer />;
    }
  };

  const onNext = () => {
    // Validate the multi content
    const isValid = await validate();

    if (!isValid) {
      return;
    }

    if (currentStep < totalSteps - 1) {
      // Navigate to the next content
      setCurrentStep((curentStep += 1));
    } else {
      // On last step we need to save so we read the multi-content data
      console.log('About to save:', getData());
    }
  };

  return (
    <>
      {renderContent()}

      {/* Each content validity is accessible from the `validation.contents` object */}
      <EuiButton onClick={onNext} disabled={validation.contents[currentStep] === false}>
        Next
      </EuiButton>
    </>
  );
});

// content_one_container.tsx

// From the good old days of Redux, it is a good practice to separate the connection to the multi-content
// from the UI that is rendered.
const ContentOneContainer = () => {

  // Declare a new content and get its default Value + a handler to update the content in the multi-content
  // This will update the "contentOne" slice of the multi-content.
  const { defaultValue, updateContent } = useContent<MyMultiContent>('contentOne');

  return <ContentOne defaultValue={defaultValue} onChange={updateContent} />
};

// content_one.tsx

const ContentOne = ({ defaultValue, onChange }) => {
  // Use the defaultValue as a starting point for the internal state
  const [internalStateValue, setInternalStateValue] = useState(defaultValue.myField);

  useEffect(() => {
    // Update the multi content state for this content
    onChange({
      isValid: true, // because in this example it is always valid
      validate: async () => true,
      getData: () => ({
        myField: internalStateValue,
      }),
    });
  }, [internalStateValue]);

  return (
    <input value={internalStateValue} onChange={(e) => setInternalStateValue(e.target.value)} />
  );
}

And just like that, <ContentOne /> is a reusable component that gets a defaultValue object and an onChange handler to communicate any internal state changes. He is responsible to provide a getData() handler as part of the onChange that will do any necessary serialization and sanitization, and the outside world does not need to know about it.

FormWizard

The <FormWizard /> and <FormWizardStep /> components lets us declare form wizard in a declarative way. It works hand in hand with the MultiContent explained above to make building form wizards a breeze. 😊

It takes care of enabling, disabling the <EuiStepsHorizontal /> steps as well as the "Back" and "Next" button.

Let's see it through an example

const MyForm = () => {
  return (
    <FormWizard<MyMultiContent>
      defaultValue={wizardDefaultValue} // The MultiContent default value as explained above
      onSave={onSaveTemplate} // A handler that will receive the multi-content data
      isEditing={isEditing} // A boolean that will indicate if all steps are already "completed" and thus valid or if we need to complete them in order
      isSaving={isSaving} // A boolean to show a "Saving..." text on the button on the last step
      apiError={apiError} // Any API error to display on top of wizard
      texts={i18nTexts} // i18n translations for the nav button.
    >
      <FormWizarStep id="contentOne" lable="Label for the step">
        <div>
          Here you can put anything... but you probably want to put a Container from the
          MultiContent example above.
        </div>
      </FormWizarStep>

      <FormWizarStep id="contentTwo" lable="Label for the step" isRequired>
        <div>
          Here you can put anything... but you probably want to put a Container from the
          MultiContent example above.
        </div>
      </FormWizarStep>

      <FormWizarStep id="contentThree" lable="Label for the step">
        <div>
          Here you can put anything... but you probably want to put a Container from the
          MultiContent example above.
        </div>
      </FormWizarStep>
    </FormWizard>
  );
};

That's all we need to build a multi-step form wizard, making sure the data is cached when switching steps.

Note to reviewer: In the current PR, try adding isRequired to some of the steps to see how we can easily let a user skip optional steps and at the same time not let him pass over a required step.

Items left TODO

In a separate PR I will

• Add README for both the <FormWizard />
• Add tests to the <FormWizard />
• Add README for both the MultiContent
• Add tests to the MultiContent

Fixes #55051

[elasticmachine]

Pinging @elastic/es-ui (Team:Elasticsearch UI)

[alisonelizabeth]

This looks great @sebelga! I'm excited to try it out with the component templates form wizard.

I had two questions that I commented on in the code. Everything else is minor typo fixes 😄. Tested locally and did not find any regressions.

Some other general comments:

• I think it would be preferred if the mappings editor changes were completed in a separate PR. It wasn't clear to me if they were necessary to get the existing flow working with the shared components, or it was just something you were addressing in parallel. I won't block on this though.

• I noticed now we have static/forms (form lib) and public/forms (wizard/multi-content) in the es_ui_shared directory. I think this is a little confusing. WDYT?

• Were you planning on moving the mappings/aliases/settings steps into es_ui_shared in a separate PR? I can also work on this if you'd like.

• The PR description you wrote is awesome! I know you mentioned adding a readme in a separate PR, but if it's not something you plan to address soon, I wonder if it makes sense to repurpose the description as the readme in the interim?

[alisonelizabeth]

What's the scenario where a string id would be provided instead of a number (or vice versa)?

[sebelga]

I wanted to leave it to the consumer to decide if he wants to navigate to a step through index (position) or id. I'd always recommend to navigate by Id so steps could be reordered, but I preferred to leave the decision to the consumer.

[alisonelizabeth]

Suggested change

	// Only update if if its true, don't override a previous "false" or "undefined"
	// Only update if it's true, don't override a previous "false" or "undefined"

[alisonelizabeth]

Should you be able to click "Back" in this scenario? The button is enabled, but it does not take you to the previous step.

[sebelga]

That was a bug, the "Back" button should be disabled when the step is invalid. I fixed it. 👍

[sebelga]

Thanks for the review @alisonelizabeth !

I think it would be preferred if the mappings editor changes were completed in a separate PR. It wasn't clear to me if they were necessary to get the existing flow working with the shared components, or it was just something you were addressing in parallel. I won't block on this though.

Most of the changes were required to make the whole flow work. For example the eslint comment for the form.subscribe() are especially important to avoid a infinite render loop. This is my top most priority to fix on the form lib. Then I fixed the validity issue not being sent to the consumer and a small glitch issue.

I noticed now we have static/forms (form lib) and public/forms (wizard/multi-content) in the es_ui_shared directory. I think this is a little confusing. WDYT?

Yes, the form lib will be moved to the "public/forms" folder, it is also a TODO on my list but this will have to be a separate PR as it will touch multiple plugins.

Were you planning on moving the mappings/aliases/settings steps into es_ui_shared in a separate PR? I can also work on this if you'd like.

I was not planning in moving them to the "es_ui_shared" folder but to the "shared" folder that you created. Also as a separate work, but you can go ahead and do it, I will rebase my branch as you will merge to master before me for sure 😊

The PR description you wrote is awesome! I know you mentioned adding a readme in a separate PR, but if it's not something you plan to address soon, I wonder if it makes sense to repurpose the description as the readme in the interim?

Great point. I went ahead and added 2 README.md for FormWizard and MultiContent. 👍

[alisonelizabeth]

Thanks @sebelga!

Most of the changes were required to make the whole flow work. For example the eslint comment for the form.subscribe() are especially important to avoid a infinite render loop. This is my top most priority to fix on the form lib. Then I fixed the validity issue not being sent to the consumer and a small glitch issue.

👍

Yes, the form lib will be moved to the "public/forms" folder, it is also a TODO on my list but this will have to be a separate PR as it will touch multiple plugins.

👍

I was not planning in moving them to the "es_ui_shared" folder but to the "shared" folder that you created. Also as a separate work, but you can go ahead and do it, I will rebase my branch as you will merge to master before me for sure

Ah, right. I forgot about that - makes sense and I can plan on taking care of it.

[kibanamachine]

💚 Build Succeeded

• continuous-integration/kibana-ci/pull-request
• Commit: 72d093d

Build metrics

@kbn/optimizer bundle module count

id	value	diff	baseline
indexManagement	143	+1	142

page load asset size

beta

id	value	diff	baseline
/bundles/plugin/esUiShared/esUiShared.plugin.js	924.0KB	+23.5KB	900.6KB
/bundles/plugin/indexManagement/indexManagement.plugin.js	200.8KB	+140.0B	200.7KB
total	-	+23.6KB	-

History

• 💚 Build #55053 succeeded c8330ac
• 💚 Build #54797 succeeded 1eddaa1
• 💚 Build #54728 succeeded 74f74a3
• 💔 Build #54680 failed 337b872
• 💔 Build #54670 failed b5920c99f049c5c96c530db99c09c4cd4008fdd1

To update your PR or re-run it, just comment with:
@elasticmachine merge upstream