ui/components/base/AutoForm.yaml

name: AutoForm
purpose: Render and submit a form from a schema array.

attributes:
  vertical: boolean
  horizontal: boolean
  inline: boolean
  nobutton: boolean
  submitlabel: string

state:
  data: object; form values, keyed by schema.name
  schema: array; field definitions

properties:
  api: API element used by submit when present.
  request: HTTP request defaults used when api is absent.
  response: Latest full HTTP response after submit.
  result: Latest response.result after submit.

schema:
  item: "{name, type, label?, setting?, options?, placeholder?, if?}"
  types: "text|password|email|number|date|datetime|file|select|checkbox|radio|switch|textarea|label|divider|DatePicker|ColorPicker|IconPicker|TagsInput"
  options: "select/checkbox/radio options: ['A', {value:'b', label:'B'}]"
  setting: "attributes copied to the control; DatePicker rangeEnd is an example"
  if: 'JavaScript expression evaluated by `$$if`; use component data through `this.data`, for example `this.data.role === "admin"`.'
  label: Read-only text displaying item.value or data[item.name].
  divider: Full-width section divider; label is its optional section title.
  database_fields: 'Data-API field definitions with tableID are accepted and converted for rendering only: name stays the data key; settings.type is the control type; settings.options are control options; settings.attrs become control attributes. The original fields and data are not changed.'

submit:
  source: Set api to an API element, or set request.url.
  method: form.submit(options); options override request defaults.
  events: "submit (cancelable, detail=data), response (detail=response), error (detail=Error)"
  result: "response is full HTTP response; result is response.result"

examples:
  basic: |
    <script>
      const profile = { name: 'Ada', role: 'admin', tags: ['math'] }
      const profileSchema = [
        { name: 'name', label: 'Name', type: 'text', setting: { required: true } },
        { name: 'role', label: 'Role', type: 'select', options: [{ value: 'admin', label: 'Admin' }, { value: 'user', label: 'User' }] },
        { name: 'tags', label: 'Tags', type: 'TagsInput' }
      ]
    </script>
    <AutoForm $.state.data="profile" $.state.schema="profileSchema"></AutoForm>
  database_fields: |
    <script>
      const fields = [{ id: 'f-role', tableID: 'users', name: 'Role', type: 'v30', settings: { type: 'select', options: ['Admin', 'User'] } }]
      const user = { Role: 'Admin' }
    </script>
    <AutoForm $.state.data="user" $.state.schema="fields"></AutoForm>
  submit_api: |
    <script>
      const profile = { name: 'Ada' }
      const profileSchema = [{ name: 'name', label: 'Name', type: 'text' }]
    </script>
    <API id="saveApi" $.request="{ url: '/api/profile', method: 'POST' }"></API>
    <AutoForm id="form" $.api="saveApi" $.state.data="profile" $.state.schema="profileSchema" $onresponse="console.log(event.detail.result)"></AutoForm>
  custom_actions: |
    <AutoForm id="form" nobutton $.state.data="profile" $.state.schema="profileSchema">
      <div slot="actions" $onclick="this.submit()">Save</div>
    </AutoForm>

related:
  - API.yaml
  - ../form/DatePicker.yaml
  - ../form/ColorPicker.yaml
  - ../form/IconPicker.yaml
  - ../form/TagsInput.yaml

tests:
  - AutoForm.test.html