Front end XWiki APIs (Proposal.FrontendXWikiAPIs)

(% class="box warningmessage" %)

(((

This page is a brainstorming document to define criteria of what should be an API or not. What is written should be understood as proposal only, and not something voted or even discussed.

)))

== Goal ==

Define for all non java resources:

11

12

* How do we mark an element public or internal?

13

* How do we deprecate them?

14

* How we do introduce a new element?

15

* How do we keep backward compatibility?

16

* What elements are public or internal

17

18

All non java resources:

* vms

* javascript API

* velocity macros

* CSS / LESS elements

24

25

== Front end components ==

26

27

On [[Front End resources>>doc:xwiki:Documentation.DevGuide.FrontendResources.WebHome||anchor="HFront-endComponents"]], we already have a list of components. The features(+)(+)(+), style (+) and architecture (+)(+) of these components would be part of the API as they are meant to be exposed publicly, reused and augmented.

28

29

There's [[velocity macros>>https://extensions.xwiki.org/xwiki/bin/view/Extension/Velocity%20Macro#HXWikiStandardVelocityMacros]] bundled in the default flavor, some of them match the resources above.

== DOM API ==

Any style attribute should never be considered as API: it's been a long time that we indicate in our [[documentation>>dev:Community.CodeStyle.XhtmlCssCodeStyle.WebHome]] to not use inline style, so scripts should never rely on it, and it should always be ok to remove them in old code. Example of such change: [[https:~~/~~/github.com/xwiki/xwiki-platform/pull/2812/files/95f349912c19b66f00b684153dcf8be6ec526db1#r1504545037>>https://github.com/xwiki/xwiki-platform/pull/2812/files/95f349912c19b66f00b684153dcf8be6ec526db1#r1504545037]]

35

36

The changes on this basic layout should be documented and backward compatible (CSS or DOM or both ?): [[https:~~/~~/www.xwiki.org/xwiki/bin/view/Documentation/DevGuide/Tutorials/Skins/CSSLayout/>>https://www.xwiki.org/xwiki/bin/view/Documentation/DevGuide/Tutorials/Skins/CSSLayout/]]

37

38

39

The DOM of the different Admin sections are not considered part of the API : admins shouldn't have to extend them. Extensions should only provide their admin UI through dedicated extension points and templates.

Discussed on [[https:~~/~~/forum.xwiki.org/t/front-end-api-html-ids/16947/4>>https://forum.xwiki.org/t/front-end-api-html-ids/16947/4]] :

44

45

Seems like using the `xwiki-` prefix on class and id names would make it clear classes and ids we consider as APIs (and also mean that all the others are not API and subject to changes :~)~)~) )

46

47

Here is the search I went with to find all of those classes and ids. It should be a bit too wide, finding a few things that are not of interest to us, but not miss any of the items we're looking for:

48

https://github.com/search?q=repo%3Axwiki%2Fxwiki-platform+%28language%3ACSS+OR+language%3ALess+OR+language%3Avelocity%29+%2F%5B%5C.%23%22%27%5Dxwiki-%2F&type=code

49

50

51

Good news, in XS, there's almost only classes starting with `xwiki-` and no useful IDs starting with `xwiki-`.

52

53

|=Name|=Semantics|=Source filename|=Keep in API?

54

|.xwiki-whatsnew-container|Main node of the whatsnew template.|whatsnew.vm|Yes

55

|.xwiki-whatsnew-item|Container for one piece of news displayed in the whatsnew template.|whatsnew.vm|No?

56

|.xwiki-whatsnew-item-title|Title of one piece of news displayed in the whatsnew template.|whatsnew.vm|No

57

|.xwiki-whatsnew-item-date|Publish date of one piece of news displayed in the whatsnew template.|whatsnew.vm|No

58

|.xwiki-whatsnew-item-description|Content of one piece of news displayed in the whatsnew template.|whatsnew.vm|No

59

|.xwiki-livedata|Container for a livedata|livedata webjar variables.less, general.less|Yes

60

|.xwiki-flavor-select-small|Style only class for the flavorPicker|web template flavor macros.vm, picker.css|No?

61

|.xwiki-flavor-select-medium|Style only class for the flavorPicker|web template flavor macros.vm, picker.css|No?

62

|.xwiki-flavor-select-tall|Style only class for the flavorPicker|web template flavor macros.vm, picker.css|No?

63

|.xwiki-flavor-picker|Main container of the flavorPicker velocimacro|web template flavor macros.vm, picker.css|Yes

64

|.xwiki-flavor-picker-filter|Text input to filter entries displayed in the rich input of the flavorPicker velocimacro|web template flavor macros.vm, picker.css|No?

65

|#xwiki-flavor-picker-progress-background|TODO, part of the flavorPicker velocimacro|web template flavor macros.vm|No?

66

|#xwiki-flavor-picker-progress-bar|TODO, part of the flavorPicker velocimacro|web template flavor macros.vm|No?

67

|.xwiki-flavor-picker-results-container|Container of the richselect used in the flavorPicker velocimacro. Style only class because repeated semantics with child?|web template flavor macros.vm, picker.css|No?

68

|.xwiki-flavor-picker-noflavor|Button to not pick any flavor in the flavorPicker velocimacro|web template flavor macros.vm|No?

69

|.xwiki-flavor-picker-results|Container of the richselect used in the flavorPicker velocimacro.|web template flavor macros.vm|No?

70

|.xwiki-flavor-picker-option|Display of one flavor in the flavorPicker velocimacro.|web template flavor macros.vm, picker.css|No?

71

|.xwiki-flavor-picker-option-selected|Display of one flavor in a specific state in the flavorPicker velocimacro.|web template flavor macros.vm, picker.css|No?

72

|.xwiki-flavor-picker-option-icon|Icon of one flavor in the flavorPicker velocimacro.|web template flavor macros.vm, picker.css|No

73

|.xwiki-livetable|Container of the table for the livetable. Does not include tagclouds and topfilters but does include pagination elements.|livetable.css, rightsUI.vm, flamingo misc.less, flamingo skin macros.vm, web templates macros.vm|No?

74

|.xwiki-livetable-loader|Element displayed while waiting for a livetable content to be retrieved.|livetable.css, rightsUI.vm, flamingo skin macros.vm, web templates macros.vm|No

75

|.xwiki-livetable-pagination|Container for the livetable pagination controls.|livetable.css, rightsUI.vm, flamingo skin macros.vm, web templates macros.vm|No?

76

|.xwiki-livetable-pagination-content|Child of livedata-pagination. Probably layout only class.|livetable.css, rightsUI.vm, flamingo skin macros.vm, web templates macros.vm|No

77

|.xwiki-livetable-pagination-text|Child of livedata-pagination. Probably layout only class. Quite an unspecific name...|livetable.css, rightsUI.vm, flamingo skin macros.vm|No

78

|.xwiki-livetable-limits|Status of elements displayed currently in the livetable, next to pagination.|livetable.css, rightsUI.vm, flamingo skin macros.vm|No?

79

|.xwiki-livetable-pagesize|Label and input to select the page size for a livetable, next to pagination.|livetable.css, flamingo skin macros.vm|No?

80

|.xwiki-livetable-pagesize-content|Input to select the page size for a livetable, next to pagination.|flamingo skin macros.vm|No?

81

|.xwiki-livetable-display-container|Main container for the livetable actual content.|livetable.css, rightsUI.vm, flamingo skin macros.vm|Yes?

82

|.xwiki-livetable-display|Not sure? Could not find it quick. Might be layout only class and probably duplicated semantics with container...|livetable.css, rightsUI.vm, livetable.less, flamingo skin macros.vm|No?

83

|.xwiki-livetable-display-header|thead of the live table.|livetable.css, rightsUI.vm, livetable.less, flamingo skin macros.vm|Yes?

84

|.xwiki-livetable-display-header-text|Layout only class... elements in the first row of the thead|livetable.css, livetable.less, flamingo skin macros.vm|Yes?

85

|.xwiki-livetable-display-header-filter|One filter in the second row of the thead.|livetable.css, xwiki.selectize.css, livetable.less|No?

86

|.xwiki-livetable-display-filters|second row of the thead, containing filters.|livetable.css, livetable.less|Yes?

87

|.xwiki-livetable-filter-active|Specific state on a livetable filter.|livetable.css|No

88

|.xwiki-livetable-display-body|tbody of the livetable.|livetable.css, rightsUI.vm, livetable.less, flamingo skin macros.vm|No?

89

|.xwiki-livetable-topfilters-container|Container for the optional HTML provided in the topFilters option|livetable.css, flamingo skin macros.vm|No?

90

|.xwiki-livetable-tagcloud-container|Container for the optional tagcloud. Note that this contains a legacy icon still hardcoded...|livetable.css, flamingo skin macros.vm|No

91

|.xwiki-livetable-tagcloud|Mostly used for layout/JS, no specific meaning added upon what's already meant by the container|livetable.css, flamingo skin macros.vm|No

92

|.xwiki-livetable-topfilters-tip|Technical class added above the container, not sure what tip it's needed for though... Definitely internal|livetable.css, flamingo skin macros.vm|No

93

|.xwiki-livetable-tagcloud-tip|Technical class added above the container, not sure what tip it's needed for though... Definitely internal|livetable.css, flamingo skin macros.vm|No

94

|.xwiki-livetable-container|Container for live tables,|livetable.css, admin.less, general.less, flamingo skin macros.vm, web templates macros.vm|No?

95

|.xwiki-livetable-initial-message|Container for a live table warning in the table head.|flamingo skin macros.vm, web templates macros.vm|No?

96

|.xwiki-livetable-multilist|Container a specific kind of filter select node.|flamingo skin macros.vm, web templates macros.vm|No?

97

|.xwiki-selectize-option|One entry int he selectize dropdown.|xwiki.selectize.css|No?

98

|.xwiki-selectize-option-icon-wrapper|Layout only, duplicated semantics with selectize-option-icon|xwiki.selectize.css|No

99

|.xwiki-selectize-option-icon|Icon used to represent one option|xwiki.selectize.css|No?

100

|.xwiki-selectize-option-label|Anchor used for the name of the option|xwiki.selectize.css|No?

101

|.xwiki-selectize-option-hint|Hint of the option? When selecting a page, this is the path to navigate to this page|xwiki.selectize.css|No?

102

|.xwiki-select|Main node of the xwikiSelect component|web templates macros.vm, select.css|Yes

103

|.xwiki-select-options|Container for all options in the rich select input component xwikiSelect|web templates macros.vm, select.css|Yes?

104

|.xwiki-select-small|Styling only class, no semantics|select.css|No

105

|.xwiki-select-medium|Styling only class, no semantics|select.css|No

106

|.xwiki-select-tall|Styling only class, no semantics|select.css|No (would need a rename to use `large` instead of `tall`)

107

|.xwiki-select-adaptable-medium|Styling only class, no semantics|select.css, createinline.vm|No

108

|.xwiki-select-option|Option in the rich select input component xwikiSelect|web templates macros.vm, select.css|Yes?

109

|.xwiki-export-3-columns|Styling only class, no semantics|export_modal.vm, select.css|No

110

|.xwiki-select-option-icon|Icon of the option in the rich select input component xwikiSelect|web templates macros.vm, select.css|No?

111

|.xwiki-metadata-container|Technical class for inline editable properties in inline edit mode.|messages.less|No

112

|.xwiki-select-option-highlighted|Status for option in xwikiSelect|flamingo misc.less|No

113

|.xwiki-select-option-selected|Status for option in xwikiSelect|flamingo misc.less|No

114

|.xwiki-form-listclass|Class used on the label of a form listclass field? Could not find doc, name is not clear to me (because too generic)|forms.less,delete.vm|No

115

|.xwiki-export-formats|This is a class but could is only used to identify one element in the content of the export modal. |export_modal.vm|No?

116

|.xwiki-select-3-columns|Style only class. Could probably be factorized with xwiki-export-3-columns... |export_modal.vm|No

117

|.xwiki-select-filter|Text input to filter entries displayed in the rich input of xwikiSelect|web templates macros.vm|Yes?

118

|.xwiki-select-category|Group of options in the rich select input component xwikiSelect|web templates macros.vm|Yes?

119

|.xwiki-select-category-count|Count display for the group of options in the rich select input component xwikiSelect|web templates macros.vm|No

120

121

I (CharpentierLucas) used four types of annotations when commenting my idea of whether we should keep those in the API:

122

123

* Yes: Keep it in the API, the class is common and nicely named, I expect it to be used in a lot of customizations. The class has a clear meaning for an existing concept.

124

* Yes? : Can keep it in the API, not strongly against removing it. The class is clear, but usually it's not really useful for much, selectors can already rely on another class.

125

* No? Should probably remove from the API (renaming the class), but not strongly opposed to keeping it. The class is never useful for customization IMO, poorly worded or very specific with easy selectors on the parent. Often those classes are used in XS only for a couple styles.

126

* No: Should remove from the API, keeping good support and backward compatibility for those will have a relatively high timecost for relatively low usefulness. The class is either very poorly worded, its scope is very very specific and it's purely cosmetic. In order to apply styles, XS developers should instead use 1. a standard styling class. 2. a non API custom class.

127

128

IMO it'd make sense we only support classes as API for now, most of XS interface element IDs do not have any naming rules.

* For all of those, decide whether we rename them to make sure they are not interpreted as API OR we keep them and we'll support them as API

133

* Find a solution for those that are generated depending on context or use (with a large or infinite number of possible values). As I see things now, we should probably never support them as API, but support a common ID/class instead if needed.

=== What should we support? ===

138

139

For every single class starting with xwiki- in XS, we ensure that we keep backward compatibility on:

140

141

* the node architecture under it (node nature + how they are nested/ordered)

142

* the styles associated to this class

143

* the styles associated to the expected children of this class

144

145

I don't think it's a good idea to engage ourselves to respect backward compatibility on:

146

147

* the content of this element and its children

148

* the attributes of this element and its children

149

150

The first one is very often contained in a translation, which AFAIK are not API (i.e. we can edit them without making an announcement and waiting for feedback). The second one should be something only XS relies on IMO. Customizations don't need it much, and it's very difficult to make any change to the UI if we block ourselves on this. Customizations shouldn't need to rely on those, either they have enough with the class and node structure, or they use their own component. E.g. if I want to style livetable, I can make CSS selectors with the API classes and the way their children are arranged. If I want to have a custom script run when a livetable filter is selected, what I'm doing is an extension of the livetable behaviour, and the XS devs can't assure full backward compatibility for this one (if for one reason or another, we need to remove the `selected` attribute, it won't go through the API breakage process).

== CSS API ==

Elements to include in the API:

155

156

~1. Bootstrap 3 classes: used everywhere, for a long time. When moving to a new design system, we want to consider how to keep support for those classes. E.g. `.btn`, `.btn-default`, ...

157

158

2. Special CSS classes defined in [[https:~~/~~/www.xwiki.org/xwiki/bin/view/Documentation/DevGuide/FrontendResources/SpecialCSSClasses/>>https://www.xwiki.org/xwiki/bin/view/Documentation/DevGuide/FrontendResources/SpecialCSSClasses/]]

159

160

161

Get a list of all classes used in the XWiki interface with their meaning, possibly the docs it's used in and a screenshot?

== Javascript API ==

Already pretty well defined in [[https:~~/~~/www.xwiki.org/xwiki/bin/view/Documentation/DevGuide/FrontendResources/JavaScriptAPI/>>https://www.xwiki.org/xwiki/bin/view/Documentation/DevGuide/FrontendResources/JavaScriptAPI/]]

== Resources ==

Previous research about defining a CSS API: [[https:~~/~~/design.xwiki.org/xwiki/bin/view/Standards/CSSAPI>>https://design.xwiki.org/xwiki/bin/view/Standards/CSSAPI]]

Wiki source code of Front end XWiki APIs

About

About

Support

Platform

User Guide

Admin Guide

Developer Guide

Projects

XWiki

Extensions

Other

Contribute

Status

Practices

Under the Hood

Get Involved

Get Connected

author	version	line-number	content
		1	{{toc/}}
		2
		3	(% class="box warningmessage" %)
		4	(((
		5	This page is a brainstorming document to define criteria of what should be an API or not. What is written should be understood as proposal only, and not something voted or even discussed.
		6	)))
		7
		8	== Goal ==
		9
		10	Define for all non java resources:
		11
		12	* How do we mark an element public or internal?
		13	* How do we deprecate them?
		14	* How we do introduce a new element?
		15	* How do we keep backward compatibility?
		16	* What elements are public or internal
		17
		18	All non java resources:
		19
		20	* vms
		21	* javascript API
		22	* velocity macros
		23	* CSS / LESS elements
		24
		25	== Front end components ==
		26
		27	On [[Front End resources>>doc:xwiki:Documentation.DevGuide.FrontendResources.WebHome\|\|anchor="HFront-endComponents"]], we already have a list of components. The features(+)(+)(+), style (+) and architecture (+)(+) of these components would be part of the API as they are meant to be exposed publicly, reused and augmented.
		28
		29	There's [[velocity macros>>https://extensions.xwiki.org/xwiki/bin/view/Extension/Velocity%20Macro#HXWikiStandardVelocityMacros]] bundled in the default flavor, some of them match the resources above.
		30
		31	== DOM API ==
		32
		33
		34	Any style attribute should never be considered as API: it's been a long time that we indicate in our [[documentation>>dev:Community.CodeStyle.XhtmlCssCodeStyle.WebHome]] to not use inline style, so scripts should never rely on it, and it should always be ok to remove them in old code. Example of such change: [[https:~~/~~/github.com/xwiki/xwiki-platform/pull/2812/files/95f349912c19b66f00b684153dcf8be6ec526db1#r1504545037>>https://github.com/xwiki/xwiki-platform/pull/2812/files/95f349912c19b66f00b684153dcf8be6ec526db1#r1504545037]]
		35
		36	The changes on this basic layout should be documented and backward compatible (CSS or DOM or both ?): [[https:~~/~~/www.xwiki.org/xwiki/bin/view/Documentation/DevGuide/Tutorials/Skins/CSSLayout/>>https://www.xwiki.org/xwiki/bin/view/Documentation/DevGuide/Tutorials/Skins/CSSLayout/]]
		37
		38	{{warning}}
		39	The DOM of the different Admin sections are not considered part of the API : admins shouldn't have to extend them. Extensions should only provide their admin UI through dedicated extension points and templates.
		40	{{/warning}}
		41
		42
		43	Discussed on [[https:~~/~~/forum.xwiki.org/t/front-end-api-html-ids/16947/4>>https://forum.xwiki.org/t/front-end-api-html-ids/16947/4]] :
		44
		45	Seems like using the `xwiki-` prefix on class and id names would make it clear classes and ids we consider as APIs (and also mean that all the others are not API and subject to changes :~)~)~) )
		46
		47	Here is the search I went with to find all of those classes and ids. It should be a bit too wide, finding a few things that are not of interest to us, but not miss any of the items we're looking for:
		48	https://github.com/search?q=repo%3Axwiki%2Fxwiki-platform+%28language%3ACSS+OR+language%3ALess+OR+language%3Avelocity%29+%2F%5B%5C.%23%22%27%5Dxwiki-%2F&type=code
		49
		50
		51	Good news, in XS, there's almost only classes starting with `xwiki-` and no useful IDs starting with `xwiki-`.
		52
		53	\|=Name\|=Semantics\|=Source filename\|=Keep in API?
		54	\|.xwiki-whatsnew-container\|Main node of the whatsnew template.\|whatsnew.vm\|Yes
		55	\|.xwiki-whatsnew-item\|Container for one piece of news displayed in the whatsnew template.\|whatsnew.vm\|No?
		56	\|.xwiki-whatsnew-item-title\|Title of one piece of news displayed in the whatsnew template.\|whatsnew.vm\|No
		57	\|.xwiki-whatsnew-item-date\|Publish date of one piece of news displayed in the whatsnew template.\|whatsnew.vm\|No
		58	\|.xwiki-whatsnew-item-description\|Content of one piece of news displayed in the whatsnew template.\|whatsnew.vm\|No
		59	\|.xwiki-livedata\|Container for a livedata\|livedata webjar variables.less, general.less\|Yes
		60	\|.xwiki-flavor-select-small\|Style only class for the flavorPicker\|web template flavor macros.vm, picker.css\|No?
		61	\|.xwiki-flavor-select-medium\|Style only class for the flavorPicker\|web template flavor macros.vm, picker.css\|No?
		62	\|.xwiki-flavor-select-tall\|Style only class for the flavorPicker\|web template flavor macros.vm, picker.css\|No?
		63	\|.xwiki-flavor-picker\|Main container of the flavorPicker velocimacro\|web template flavor macros.vm, picker.css\|Yes
		64	\|.xwiki-flavor-picker-filter\|Text input to filter entries displayed in the rich input of the flavorPicker velocimacro\|web template flavor macros.vm, picker.css\|No?
		65	\|#xwiki-flavor-picker-progress-background\|TODO, part of the flavorPicker velocimacro\|web template flavor macros.vm\|No?
		66	\|#xwiki-flavor-picker-progress-bar\|TODO, part of the flavorPicker velocimacro\|web template flavor macros.vm\|No?
		67	\|.xwiki-flavor-picker-results-container\|Container of the richselect used in the flavorPicker velocimacro. Style only class because repeated semantics with child?\|web template flavor macros.vm, picker.css\|No?
		68	\|.xwiki-flavor-picker-noflavor\|Button to not pick any flavor in the flavorPicker velocimacro\|web template flavor macros.vm\|No?
		69	\|.xwiki-flavor-picker-results\|Container of the richselect used in the flavorPicker velocimacro.\|web template flavor macros.vm\|No?
		70	\|.xwiki-flavor-picker-option\|Display of one flavor in the flavorPicker velocimacro.\|web template flavor macros.vm, picker.css\|No?
		71	\|.xwiki-flavor-picker-option-selected\|Display of one flavor in a specific state in the flavorPicker velocimacro.\|web template flavor macros.vm, picker.css\|No?
		72	\|.xwiki-flavor-picker-option-icon\|Icon of one flavor in the flavorPicker velocimacro.\|web template flavor macros.vm, picker.css\|No
		73	\|.xwiki-livetable\|Container of the table for the livetable. Does not include tagclouds and topfilters but does include pagination elements.\|livetable.css, rightsUI.vm, flamingo misc.less, flamingo skin macros.vm, web templates macros.vm\|No?
		74	\|.xwiki-livetable-loader\|Element displayed while waiting for a livetable content to be retrieved.\|livetable.css, rightsUI.vm, flamingo skin macros.vm, web templates macros.vm\|No
		75	\|.xwiki-livetable-pagination\|Container for the livetable pagination controls.\|livetable.css, rightsUI.vm, flamingo skin macros.vm, web templates macros.vm\|No?
		76	\|.xwiki-livetable-pagination-content\|Child of livedata-pagination. Probably layout only class.\|livetable.css, rightsUI.vm, flamingo skin macros.vm, web templates macros.vm\|No
		77	\|.xwiki-livetable-pagination-text\|Child of livedata-pagination. Probably layout only class. Quite an unspecific name...\|livetable.css, rightsUI.vm, flamingo skin macros.vm\|No
		78	\|.xwiki-livetable-limits\|Status of elements displayed currently in the livetable, next to pagination.\|livetable.css, rightsUI.vm, flamingo skin macros.vm\|No?
		79	\|.xwiki-livetable-pagesize\|Label and input to select the page size for a livetable, next to pagination.\|livetable.css, flamingo skin macros.vm\|No?
		80	\|.xwiki-livetable-pagesize-content\|Input to select the page size for a livetable, next to pagination.\|flamingo skin macros.vm\|No?
		81	\|.xwiki-livetable-display-container\|Main container for the livetable actual content.\|livetable.css, rightsUI.vm, flamingo skin macros.vm\|Yes?
		82	\|.xwiki-livetable-display\|Not sure? Could not find it quick. Might be layout only class and probably duplicated semantics with container...\|livetable.css, rightsUI.vm, livetable.less, flamingo skin macros.vm\|No?
		83	\|.xwiki-livetable-display-header\|thead of the live table.\|livetable.css, rightsUI.vm, livetable.less, flamingo skin macros.vm\|Yes?
		84	\|.xwiki-livetable-display-header-text\|Layout only class... elements in the first row of the thead\|livetable.css, livetable.less, flamingo skin macros.vm\|Yes?
		85	\|.xwiki-livetable-display-header-filter\|One filter in the second row of the thead.\|livetable.css, xwiki.selectize.css, livetable.less\|No?
		86	\|.xwiki-livetable-display-filters\|second row of the thead, containing filters.\|livetable.css, livetable.less\|Yes?
		87	\|.xwiki-livetable-filter-active\|Specific state on a livetable filter.\|livetable.css\|No
		88	\|.xwiki-livetable-display-body\|tbody of the livetable.\|livetable.css, rightsUI.vm, livetable.less, flamingo skin macros.vm\|No?
		89	\|.xwiki-livetable-topfilters-container\|Container for the optional HTML provided in the topFilters option\|livetable.css, flamingo skin macros.vm\|No?
		90	\|.xwiki-livetable-tagcloud-container\|Container for the optional tagcloud. Note that this contains a legacy icon still hardcoded...\|livetable.css, flamingo skin macros.vm\|No
		91	\|.xwiki-livetable-tagcloud\|Mostly used for layout/JS, no specific meaning added upon what's already meant by the container\|livetable.css, flamingo skin macros.vm\|No
		92	\|.xwiki-livetable-topfilters-tip\|Technical class added above the container, not sure what tip it's needed for though... Definitely internal\|livetable.css, flamingo skin macros.vm\|No
		93	\|.xwiki-livetable-tagcloud-tip\|Technical class added above the container, not sure what tip it's needed for though... Definitely internal\|livetable.css, flamingo skin macros.vm\|No
		94	\|.xwiki-livetable-container\|Container for live tables,\|livetable.css, admin.less, general.less, flamingo skin macros.vm, web templates macros.vm\|No?
		95	\|.xwiki-livetable-initial-message\|Container for a live table warning in the table head.\|flamingo skin macros.vm, web templates macros.vm\|No?
		96	\|.xwiki-livetable-multilist\|Container a specific kind of filter select node.\|flamingo skin macros.vm, web templates macros.vm\|No?
		97	\|.xwiki-selectize-option\|One entry int he selectize dropdown.\|xwiki.selectize.css\|No?
		98	\|.xwiki-selectize-option-icon-wrapper\|Layout only, duplicated semantics with selectize-option-icon\|xwiki.selectize.css\|No
		99	\|.xwiki-selectize-option-icon\|Icon used to represent one option\|xwiki.selectize.css\|No?
		100	\|.xwiki-selectize-option-label\|Anchor used for the name of the option\|xwiki.selectize.css\|No?
		101	\|.xwiki-selectize-option-hint\|Hint of the option? When selecting a page, this is the path to navigate to this page\|xwiki.selectize.css\|No?
		102	\|.xwiki-select\|Main node of the xwikiSelect component\|web templates macros.vm, select.css\|Yes
		103	\|.xwiki-select-options\|Container for all options in the rich select input component xwikiSelect\|web templates macros.vm, select.css\|Yes?
		104	\|.xwiki-select-small\|Styling only class, no semantics\|select.css\|No
		105	\|.xwiki-select-medium\|Styling only class, no semantics\|select.css\|No
		106	\|.xwiki-select-tall\|Styling only class, no semantics\|select.css\|No (would need a rename to use `large` instead of `tall`)
		107	\|.xwiki-select-adaptable-medium\|Styling only class, no semantics\|select.css, createinline.vm\|No
		108	\|.xwiki-select-option\|Option in the rich select input component xwikiSelect\|web templates macros.vm, select.css\|Yes?
		109	\|.xwiki-export-3-columns\|Styling only class, no semantics\|export_modal.vm, select.css\|No
		110	\|.xwiki-select-option-icon\|Icon of the option in the rich select input component xwikiSelect\|web templates macros.vm, select.css\|No?
		111	\|.xwiki-metadata-container\|Technical class for inline editable properties in inline edit mode.\|messages.less\|No
		112	\|.xwiki-select-option-highlighted\|Status for option in xwikiSelect\|flamingo misc.less\|No
		113	\|.xwiki-select-option-selected\|Status for option in xwikiSelect\|flamingo misc.less\|No
		114	\|.xwiki-form-listclass\|Class used on the label of a form listclass field? Could not find doc, name is not clear to me (because too generic)\|forms.less,delete.vm\|No
		115	\|.xwiki-export-formats\|This is a class but could is only used to identify one element in the content of the export modal. \|export_modal.vm\|No?
		116	\|.xwiki-select-3-columns\|Style only class. Could probably be factorized with xwiki-export-3-columns... \|export_modal.vm\|No
		117	\|.xwiki-select-filter\|Text input to filter entries displayed in the rich input of xwikiSelect\|web templates macros.vm\|Yes?
		118	\|.xwiki-select-category\|Group of options in the rich select input component xwikiSelect\|web templates macros.vm\|Yes?
		119	\|.xwiki-select-category-count\|Count display for the group of options in the rich select input component xwikiSelect\|web templates macros.vm\|No
		120
		121	I (CharpentierLucas) used four types of annotations when commenting my idea of whether we should keep those in the API:
		122
		123	* Yes: Keep it in the API, the class is common and nicely named, I expect it to be used in a lot of customizations. The class has a clear meaning for an existing concept.
		124	* Yes? : Can keep it in the API, not strongly against removing it. The class is clear, but usually it's not really useful for much, selectors can already rely on another class.
		125	* No? Should probably remove from the API (renaming the class), but not strongly opposed to keeping it. The class is never useful for customization IMO, poorly worded or very specific with easy selectors on the parent. Often those classes are used in XS only for a couple styles.
		126	* No: Should remove from the API, keeping good support and backward compatibility for those will have a relatively high timecost for relatively low usefulness. The class is either very poorly worded, its scope is very very specific and it's purely cosmetic. In order to apply styles, XS developers should instead use 1. a standard styling class. 2. a non API custom class.
		127
		128	IMO it'd make sense we only support classes as API for now, most of XS interface element IDs do not have any naming rules.
		129
		130
		131	{{todo}}
		132	* For all of those, decide whether we rename them to make sure they are not interpreted as API OR we keep them and we'll support them as API
		133	* Find a solution for those that are generated depending on context or use (with a large or infinite number of possible values). As I see things now, we should probably never support them as API, but support a common ID/class instead if needed.
		134
		135	{{/todo}}
		136
		137	=== What should we support? ===
		138
		139	For every single class starting with xwiki- in XS, we ensure that we keep backward compatibility on:
		140
		141	* the node architecture under it (node nature + how they are nested/ordered)
		142	* the styles associated to this class
		143	* the styles associated to the expected children of this class
		144
		145	I don't think it's a good idea to engage ourselves to respect backward compatibility on:
		146
		147	* the content of this element and its children
		148	* the attributes of this element and its children
		149
		150	The first one is very often contained in a translation, which AFAIK are not API (i.e. we can edit them without making an announcement and waiting for feedback). The second one should be something only XS relies on IMO. Customizations don't need it much, and it's very difficult to make any change to the UI if we block ourselves on this. Customizations shouldn't need to rely on those, either they have enough with the class and node structure, or they use their own component. E.g. if I want to style livetable, I can make CSS selectors with the API classes and the way their children are arranged. If I want to have a custom script run when a livetable filter is selected, what I'm doing is an extension of the livetable behaviour, and the XS devs can't assure full backward compatibility for this one (if for one reason or another, we need to remove the `selected` attribute, it won't go through the API breakage process).
		151
		152	== CSS API ==
		153
		154	Elements to include in the API:
		155
		156	~1. Bootstrap 3 classes: used everywhere, for a long time. When moving to a new design system, we want to consider how to keep support for those classes. E.g. `.btn`, `.btn-default`, ...
		157
		158	2. Special CSS classes defined in [[https:~~/~~/www.xwiki.org/xwiki/bin/view/Documentation/DevGuide/FrontendResources/SpecialCSSClasses/>>https://www.xwiki.org/xwiki/bin/view/Documentation/DevGuide/FrontendResources/SpecialCSSClasses/]]
		159
		160	{{info}}
		161	Get a list of all classes used in the XWiki interface with their meaning, possibly the docs it's used in and a screenshot?
		162	{{/info}}
		163
		164	== Javascript API ==
		165
		166	Already pretty well defined in [[https:~~/~~/www.xwiki.org/xwiki/bin/view/Documentation/DevGuide/FrontendResources/JavaScriptAPI/>>https://www.xwiki.org/xwiki/bin/view/Documentation/DevGuide/FrontendResources/JavaScriptAPI/]]
		167
		168	== Resources ==
		169
		170	Previous research about defining a CSS API: [[https:~~/~~/design.xwiki.org/xwiki/bin/view/Standards/CSSAPI>>https://design.xwiki.org/xwiki/bin/view/Standards/CSSAPI]]