diff options
Diffstat (limited to '')
-rw-r--r-- | browser/components/storybook/docs/README.other-widgets.stories.md | 84 |
1 files changed, 84 insertions, 0 deletions
diff --git a/browser/components/storybook/docs/README.other-widgets.stories.md b/browser/components/storybook/docs/README.other-widgets.stories.md new file mode 100644 index 0000000000..b2614d88b6 --- /dev/null +++ b/browser/components/storybook/docs/README.other-widgets.stories.md @@ -0,0 +1,84 @@ +# Other types of UI Widgets + +In addition to the [new reusable UI widgets](https://firefox-source-docs.mozilla.org/browser/components/storybook/docs/README.reusable-widgets.stories.html) there are existing elements that serve a similar role. +These older elements are broken down into two groups: Mozilla Custom Elements and User Agent (UA) Widgets. +Additionally, we also have domain-specific widgets that are similar to the reusable widgets but are created to serve a specific need and may or may not adhere to the Design Systems specifications. + +## Older custom elements in `toolkit/widgets` + +There are existing UI widgets in `toolkit/content/widgets/` that belong to one of two groups: Mozilla Custom Elements or User Agent (UA) Widgets. +These [existing custom elements](https://searchfox.org/mozilla-central/rev/cde3d4a8d228491e8b7f1bd94c63bbe039850696/toolkit/content/customElements.js#792-809,847-866) are loaded into all privileged main process documents automatically. +You can determine if a custom element belongs to the existing UI widgets category by either [viewing the array](https://searchfox.org/mozilla-central/rev/cde3d4a8d228491e8b7f1bd94c63bbe039850696/toolkit/content/customElements.js#792-809,847-866) or by viewing the [files in toolkit/content/widgets](https://searchfox.org/mozilla-central/source/toolkit/content/widgets). +Additionally, these older custom elements are a mix of XUL and HTML elements. + + +### Mozilla Custom Elements + +Unlike newer reusable UI widgets, the older Mozilla Custom Elements do not have a dedicated directory. +For example `arrowscrollbox.js` is an older single file custom element versus `moz-button-group/moz-button-group.mjs` which exemplifies the structure followed by newer custom elements. + +### User Agent (UA) widgets + +User agent (UA) widgets are like custom elements but run in per-origin UA widget scope instead of the chrome or content scope. +There are a much smaller number of these widgets compared to the Mozilla Custom Elements: +- [datetimebox.js](https://searchfox.org/mozilla-central/source/toolkit/content/widgets/datetimebox.js) +- [marquee.js](https://searchfox.org/mozilla-central/source/toolkit/content/widgets/marquee.js) +- [textrecognition.js](https://searchfox.org/mozilla-central/source/toolkit/content/widgets/textrecognition.js) +- [videocontrols.js](https://searchfox.org/mozilla-central/source/toolkit/content/widgets/videocontrols.js) + +Please refer to the existing [UA widgets documentation](https://firefox-source-docs.mozilla.org/toolkit/content/toolkit_widgets/ua_widget.html) for more details. + +### How to use existing Mozilla Custom Elements + +The existing Mozilla Custom Elements are automatically imported into all chrome privileged documents. +These existing elements do not need to be imported individually via `<script>` tag or by using `window.ensureCustomElements()` when in a privileged main process document. +As long as you are working in a chrome privileged document, you will have access to the existing Mozilla Custom Elements. +You can dynamically create one of the existing custom elements by using `document.createDocument("customElement)` or `document.createXULElement("customElement")` in the relevant JS file, or by using the custom element tag in the relevant XHTML document. +For example, `document.createXULElement("checkbox")` creates an instance of [widgets/checkbox.js](https://searchfox.org/mozilla-central/source/toolkit/content/widgets/checkbox.js) while using `<checkbox>` declares an instance in the XUL document. +You can see the checkbox widget in use in about:preferences. + +### How to use existing UA Widgets + +Please refer to the [existing UA widgets documentation](https://firefox-source-docs.mozilla.org/toolkit/content/toolkit_widgets/ua_widget.html) for more details on how to use these widgets. + +### How these widgets behave in chrome versus in-content + +The UA widgets are intended for web content, they may or may not work in-content or in the chrome. +However since these widgets run in a specific UA widget scope, their DOM cannot be accessed while in a content process. + +The existing Mozilla Custom Elements can only be used in privileged content processes or in the chrome. +Since these elements cannot be used in regular web content, there is no difference in how they behave in the chrome versus in-content. + +## Domain-specific Widgets + +Not all reusable components should be used throughout the entirety of Firefox. +While we do have global UI patterns and components such as a button and modals, there are also specific features within the browser that include their own unique reusable patterns. +These patterns and components are known as "domain-specific widgets". +For example, the [login-timeline widget](https://searchfox.org/mozilla-central/source/browser/components/aboutlogins/content/components/login-timeline.mjs) is a domain-specific widget. + +### Adding new domain-specific widgets + +While we do have the `./mach addwidget` command, as noted in the [adding new design system components document](#adding-new-design-system-components), this command does not currently support the domain-specific widget case. +[See Bug 1828181 for more details on supporting this case](https://bugzilla.mozilla.org/show_bug.cgi?id=1828181). +Instead, you will need to use `./mach addstory your-widget "your-project-or-team-name"` to create a new story in `browser/components/storybook/stories`. +You can also use `./mach addstory your-widget "your-project-or-team-name" --path <your-widget-path>/<widget-source>` so that your widget's source is imported correctly. + +If you specified a path and have Storybook running, a blank story entry for your widget will appear under the Domain-Specific UI Widgets/your-project section. +Otherwise, if you have not added a path, Storybook will throw an error saying that it "Can't resolve 'None'" in the newly added story. +This is expected and serves as a reminder that you need to update the newly created story with the widget source import. + +Since Storybook is unaware of how the actual code is added or built, we won't go into detail about adding your new widget to the codebase. +It's recommended to have a `.html` test for your new widget since this lets you unit test the component directly rather than using integration tests with the domain. +To see what kind of files you may need for your widget, please refer back to [the output of the `./mach addwidget` command](#adding-new-design-system-components). +Just like with the UI widgets, [the `browser_all_files_referenced.js` will fail unless you use your component immediately outside of Storybook.](#known-browser_all_files_referencedjs-issue) + +### Using new domain-specific widgets + +This is effectively the same as [using new design system components](#using-new-design-system-components). +You will need to import your widget into the relevant `html`/`xhtml` files via a `script` tag with `type="module"`: + +```html +<script type="module" src="chrome://browser/content/<domain-directory>/<your-widget>.mjs"></script> +``` + +Or use `window.ensureCustomElements("<your-widget>")` as previously stated in [the using new design system components section.](#using-new-design-system-components) |