Redevelop the Inspector widget

bennothommo commented 2 years ago

The Inspector widget in Winter CMS is one of the many unique and powerful features of the framework, providing contextual "popup" forms for various elements, most prominently in the configuration of CMS components, but also used very liberally throughout some first party plugins like the Builder plugin.

The widget has remained virtually unchanged throughout the history of Winter CMS and October CMS before it due to its complexity (beyond a rewrite to support features in the Builder plugin), therefore we have determined that it is due an upgrade and refactor to simplify its usage. This issue will detail the goals that we intend to achieve with redeveloping this widget.

Primary Goals

Rewrite the widget using Vue and Snowboard: A lot of the functionality of this widget lends itself to using Vue. The current Inspector has a lot of boilerplate to handle things like templating, validation, data manipulation that could be done much easier using Vue's powerful templating and data management. Using our new Snowboard plugin and architecture, we can rewrite the Inspector to take advantage of Vue.
Document the entire front-end and back-end API: The docs for using or implementing the Inspector in your own plugins have been traditionally lacking. The documentation linked above only deal with the "data attributes" API of using the Inspector in a HTML template, with no real guidance towards handling the backend functionality beyond some sporatic code examples. We will tidy up and fully document this widget to allow people to harness the full potential of the Inspector.
Make form configuration consistent with the Form widget: The schema for the Inspector uses a custom schema which shares some common attributes to the Form schema, but also introduces some potential gotchas - for example, a text field in a Form is a single-line input, but in the Inspector, it is a multi-line input. To keep the development experience consistent, we will adopt the Form schema for all fields available in the Inspector, whilst keeping backwards-compatibility with the original schema.

Secondary Goals

Redesign the widget: While the widget does look great as it is currently, we feel it can be so much more. Using the power of single-file components in Vue, we will be able to construct several layouts for the widget to allow full customisation of the look and feel of the Inspector.
Ensure full keyboard accessibility: The way that the widget is currently formatted implies that the widget should be easily fillable using only keyboard navigation, but unfortunately, this is not entirely the case at the moment. We will put efforts into making sure that the entire Inspector form can be tabbed and entered using only the keyboard.
Add tabs functionality: Some implementations of the Inspector produce quite large forms that can be difficult to parse and navigate for a user. One of the ways to simplify the form that are currently available are to use "groups", which act as "accordion" elements that hide or show a set of grouped fields. However, we feel that implementing tabs would be able to simplify the UI even further and avoid bombarding the user with a huge list of fields on the outset.

Tasks

[ ] Make Inspector schema consistent with Form schema, whilst keeping backwards-compatibility with previous schema.
- [x] Rename properties property to fields
- [x] Rename type: string to type: text
- [x] Rename type: text to type: textarea
- [x] Rename type: set to type: checkboxlist
- [ ] Rename type: stringlist to type: taglist
- [ ] Rename type: object to type: nestedform
- [ ] Rename properties property to form and allow a nested field structure
- [ ] Rename type: objectlist to type: repeater
- [ ] Rename itemProperties property to form and allow a nested field structure
- [ ] Rename titleProperty property to titleFrom
- [ ] Rename keyProperty property to keyFrom
- [x] Rename title property to label
- [x] Rename description property to comment

Related tasks and issues

https://github.com/wintercms/winter/issues/342 (Borders on inspector fields not appearing on Firefox)
https://github.com/wintercms/winter/issues/28#issuecomment-1069770258 (Integer keys for the "set" property type get coerced to string, also see https://github.com/octobercms/october/issues/5530)
https://github.com/octobercms/october/issues/5501 (Add support for "triggers" in Inspector)
https://github.com/octobercms/october/issues/3603 (Responsive issues with Inspector on certain device sizes)

LukeTowers commented 2 years ago

Could we explore having the fields being managed by an embedded Form widget to bring the full power & flexibility of that to the inspector? Currently only a very limited set of fields are available to be used.

Also it would be great if it could support more types of data, I don't think anything complicated like raw markup is currently supported.

bennothommo commented 2 years ago

I'm not sure how well the Form widget will lend itself to the Inspector due to it being primarily front-end - it would also mean that we would have to be able to develop some way to allow the form widgets templates to be changed if displayed inside the Inspector. I also think the limited field set is intentional, but I can certainly look into though.

wintercms / winter