docs and todos

src/Umbraco.Web.UI.Client/libs/modal/stories/modal.mdx

@@ -42,7 +42,10 @@ class MyElement extends UmbElementMixin(LitElement) {
 
 ### Open a modal
 
-A modal is opened by calling the open method on the UmbModalContext. The methods will accept a modal token (or extension alias), an optional dataset, and optional modal options .It returns an instance of UmbModalHandler.
+TODO: consider the level of documentation we like to provide. Do we want user to have deep link able modals, or just simple modals like theses?
+TODO: referee to the doc on modal extension, and move the relevant into between these two.
+
+A modal can be opened by calling the open method on the UmbModalContext. The methods will accept a modal token (or extension alias), an optional dataset, and optional modal options. It returns an instance of UmbModalHandler.
 
 ```ts
 import { html, LitElement } from 'lit';

src/Umbraco.Web.UI.Client/src/stories/extending/modals/intro.mdx

@@ -0,0 +1,125 @@
+import { Meta } from '@storybook/addon-docs';
+
+<Meta title="Guides/Extending the Backoffice/Modals/Intro" parameters={{ previewTabs: { canvas: { hidden: true } } }} />
+
+# Modals
+
+// TODO: add description about what modals is
+
+- Sidebar
+- Infinite Editors
+- Dialogs
+
+## Define a Manifest for a Modal Type
+
+### Manifest
+
+```json
+{
+	"type": "modal",
+	"alias": "Our.Modal.SomethingPicker",
+	"name": "My Something Picker Modal",
+	"loader": "./my-something-picker-modal-element.js",
+},
+```
+
+## Implement a Modal
+
+### Modal Token
+
+For type safety we recommend that you make a Modal Token, Its posible to go without.
+The Modal Token binds the Modal Type to the Modal Data Type and Modal Result Type.
+
+``
+
+```ts
+import { ModalToken } from '@umbraco-cms/element';
+
+export type OurSomethingPickerModalData = {
+	key: string | null;
+};
+
+export type OurSomethingPickerModalResult = {
+	key: string;
+};
+
+export const MY_SOMETHING_PICKER_MODAL = new UmbModalToken<UmbLinkPickerModalData, UmbLinkPickerModalResult>(
+	'Our.Modal.SomethingPicker',
+	{
+		type: 'sidebar',
+		size: 'small',
+	}
+);
+```
+
+### Make a modal registration
+
+When registrering you need to be aware about the scope of the modal.
+A modal registred in a dashboard can be relatively simple.
+A modal registred in a property editor, needs to become specific for the property and the variant of that property.
+
+Notice we are using a Controller here, this means your element has to be a Controller Host (TODO: Insert link to story about Controller Host also available through the UmbElementMixin)
+
+#### Simple Modal Registration
+
+```ts
+new UmbModalRegistrationController(this, MY_SOMETHING_PICKER_MODAL, {
+	path: `:key`,
+	onSetup: (params) => {
+		const keyParam = params.key;
+		if (!keyParam) return false;
+
+		// Make a Data object to be used in the modal:
+		return {
+			key: keyParam,
+		};
+	},
+	onSubmit: (submitData) => {
+		// Here we got the Result object from the modal:
+		this._mySetPickedKey(submitData.key);
+	},
+	getUrlBuilder: (urlBuilder) => {
+		// Here we got a urlBuilder, read further down this document for more into on this:
+		this._myUrlBuilder = urlBuilder;
+	},
+});
+```
+
+#### Modal Registration in a Property Editor
+
+```ts
+new UmbPropertyEditorModalRegistrationController(this, MY_SOMETHING_PICKER_MODAL, {
+	path: `:key`,
+	onSetup: (params) => {
+		const keyParam = params.key;
+		if (!keyParam) return false;
+
+		// Make a Data object to be used in the modal:
+		return {
+			key: keyParam,
+		};
+	},
+	onSubmit: (submitData) => {
+		// Here we got the Result object from the modal:
+		this._mySetPickedKey(submitData.key);
+	},
+	getUrlBuilder: (urlBuilder) => {
+		// Here we got a urlBuilder, read further down this document for more into on this:
+		this._myUrlBuilder = urlBuilder;
+	},
+});
+```
+
+## Generate the URL to a Modal
+
+The Modal registration has an option to retrive a URL Builder, this is a function that can be used to generate a URL to a modal.
+
+```ts
+const modalLink = _myUrlBuilder?.({ key: 'my-key-1234' });
+```
+
+The modalLink from above could look like: /umbraco/backoffice/my/location/modal/Our.Modal.SomethingPicker/my-key-1234
+
+Notice the Property Editor registration will add the property alias and variant id to the URL, so it becomes:
+
+/umbraco/backoffice/my/location/modal/Our.Modal.SomethingPicker/my-property-alias/en-us/my-key-1234