Improve Documentation for parseSchema in the Okta Sign-In Widget

[dr-bizz]

Describe the feature request

Description

First, I want to express my appreciation for the Okta team’s excellent documentation—it has been incredibly helpful! However, while working on a recent project, I found that understanding all available options within the parseSchema function required extensive source code review. To improve the developer experience and reduce the need for source code exploration, I suggest enhancing the documentation by explicitly detailing key properties of parseSchema.

Suggested Documentation Enhancements

parseSchema Function
Currently, the documentation lacks detailed explanations of some useful properties within parseSchema. Below is an improved version that could serve as a reference for developers:

parseSchema: (schema, onSuccess) => {
  // This example demonstrates how to add an additional field to the registration form.
  schema.push({
    name: 'userProfile.address',
    type: 'text',
    placeholder: 'Enter your street address',
    maxLength: 255,
    label: 'Street Address',
    'label-top': true, // Moves label above the field
    required: true,
    tooltip: 'Tooltip message',
    readOnly: false,
    
    // If the field is a select or radio input, options can be specified.
    options: {
      optionOne: 'Option One',
      optionTwo: 'Option Two'
    },

    // Allows fields to be conditionally displayed based on other field values.
    // Note: This only applies a CSS-based visibility toggle. 
    // If the field is required, custom validation in `preSubmit` may be necessary.
    showWhen: {
      inputName: 'Value'
    },

    // More complex implementation using a function:
    showWhen: {
      'userProfile.country': (value) => value !== 'US'
    }
  });

  onSuccess(schema);
};

Additionally, it would be helpful to explicitly list and describe the available properties in the documentation. For example:

• label-top: Determines whether the label appears above the field.
• tooltip: Provides a helper message displayed on hover.
• showWhen: Conditionally shows/hides a field based on another field’s value (CSS-only).
• options: Defines selectable values for radio buttons or dropdowns.
• autoRender: Model attributes change event to trigger rerendering of the input

Additional Resources
For developers who want to explore all available properties, it would be beneficial to reference the relevant source file directly in the documentation:
FormUtil.js

I would love to hear your thoughts! I’d be happy to contribute if needed.

New or Affected Resource(s)

https://github.com/okta/okta-signin-widget/blob/master/README.md

Provide a documentation link

No response

Additional Information?

No response