wanderer/gitea
1
0
Fork 0
forked from mirror/gitea
Code Issues Pull Requests Releases Activity

Improve frontend guidelines (#23007)

Browse Source 
Some were out-dated, some are added.
This commit is contained in:
wxiaoguang 2023-02-21 14:13:37 +08:00 committed by GitHub
parent dc9cebdf45
commit e7be610d57
Signed by: GitHub
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 43 additions and 8 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
docs/content/doc/developers/guidelines-frontend.en-us.md
View File

@ -39,12 +39,20 @@ We recommend [Google HTML/CSS Style Guide](https://google.github.io/styleguide/h
### Gitea specific guidelines:
1. Every feature (Fomantic-UI/jQuery module) should be put in separate files/directories.
2. HTML ids and classes should use kebab-case.
2. HTML ids and classes should use kebab-case, it's preferred to contain 2-3 feature related keywords.
3. HTML ids and classes used in JavaScript should be unique for the whole project, and should contain 2-3 feature related keywords. We recommend to use the `js-` prefix for classes that are only used in JavaScript.
4. jQuery events across different features could use their own namespaces if there are potential conflicts.
5. CSS styling for classes provided by frameworks should not be overwritten. Always use new class-names with 2-3 feature related keywords to overwrite framework styles.
6. The backend can pass complex data to the frontend by using `ctx.PageData["myModuleData"] = map[]{}`
7. Simple pages and SEO-related pages use Go HTML Template render to generate static Fomantic-UI HTML output. Complex pages can use Vue3.
4. CSS styling for classes provided by frameworks should not be overwritten. Always use new class names with 2-3 feature related keywords to overwrite framework styles. Gitea's helper CSS classes in `helpers.less` could be helpful.
5. The backend can pass complex data to the frontend by using `ctx.PageData["myModuleData"] = map[]{}`, but do not expose whole models to the frontend to avoid leaking sensitive data.
6. Simple pages and SEO-related pages use Go HTML Template render to generate static Fomantic-UI HTML output. Complex pages can use Vue3.
7. Clarify variable types, prefer `elem.disabled = true` instead of `elem.setAttribute('disabled', 'anything')`, prefer `$el.prop('checked', var === 'yes')` instead of `$el.prop('checked', var)`.
8. Use semantic elements, prefer `<button class="ui button">` instead of `<div class="ui button">`.
9. Avoid unnecessary `!important` in CSS, add comments to explain why it's necessary if it can't be avoided.
### Accessibility / ARIA
In history, Gitea heavily uses Fomantic UI which is not an accessibility-friendly framework.
Gitea uses some patches to make Fomantic UI more accessible (see the `aria.js` and `aria.md`),
but there are still many problems which need a lot of work and time to fix.
### Framework Usage

33
web_src/js/features/aria.md
View File

@ -1,8 +1,35 @@
**This document is used as aria/a11y reference for future developers**
# Checkbox
## Accessibility-friendly Checkbox
The ideal checkboxes should be:
```html
<label><input type="checkbox"> ... </label>
```
However, related styles aren't supported (not implemented) yet, so at the moment, almost all the checkboxes are still using Fomantic UI checkbox.
## Fomantic UI Checkbox
```html
<div class="ui checkbox">
<input type="checkbox"> <!-- class "hidden" will be added by $.checkbox() -->
<label>...</label>
</div>
```
Then the JS `$.checkbox()` should be called to make it work with keyboard and label-clicking, then it works like the ideal checkboxes.
There is still a problem: Fomantic UI checkbox is not friendly to screen readers, so we add IDs to all the Fomantic UI checkboxes automatically by JS.
# Dropdown
## ARIA Dropdown
There are different solutions:
There are different solutions:
* combobox + listbox + option
* menu + menuitem
@ -27,7 +54,7 @@ At the moment, `menu + menuitem` seems to work better with Fomantic UI Dropdown,
<div class="ui dropdown"> <!-- focused here, then it's not perfect to use aria-activedescendant to point to the menu item -->
<input type="hidden" ...>
<div class="text">Default</div>
<div class="menu transition hidden" tabindex="-1">
<div class="menu" tabindex="-1"> <!-- "transition hidden|visible" classes will be added by $.dropdown() and when the dropdown is working -->
<div class="item active selected">Default</div>
<div class="item">...</div>
</div>
@ -38,7 +65,7 @@ At the moment, `menu + menuitem` seems to work better with Fomantic UI Dropdown,
<input type="hidden" ...>
<input class="search" autocomplete="off" tabindex="0"> <!-- focused here -->
<div class="text"></div>
<div class="menu transition visible" tabindex="-1">
<div class="menu" tabindex="-1"> <!-- "transition hidden|visible" classes will be added by $.dropdown() and when the dropdown is working -->
<div class="item selected">...</div>
<div class="item">...</div>
</div>