TINYDOC-3570: Resizable sidebars documentation (TINYMCE-14486)

modules/ROOT/pages/8.9.0-release-notes.adoc

@@ -116,6 +116,14 @@ For information on using Enhanced Skins & Icon Packs, see: xref:enhanced-skins-a
 
 // CCFR here.
 
+=== Sidebars can now be resized by dragging their edge, and their width can be configured with the new `sidebar_width` option.
+// #TINYMCE-14527
+// #TINYMCE-14530
+
+Previously, the styles applied to the content of a sidebar fixed the width of that sidebar. A user working in a wide editor could not give a sidebar more room, and a user working in a narrow editor could not reclaim space for the editable area.
+
+In {productname} {release-version}, {productname} renders a resize handle on sidebars registered with the xref:customsidebar.adoc#resizable[`+resizable+`] property set to `+true+`, and a user can drag that handle to resize the sidebar. The sidebars registered by the xref:introduction-to-tiny-comments.adoc[Comments] and xref:tinymceai.adoc[{productname} AI] plugins are resizable by default. To keep the editable area usable, {productname} does not allow the editable area to shrink below 280 pixels, whatever width a user requests.
+
 
 [[additions]]
 == Additions
@@ -127,6 +135,20 @@ For information on using Enhanced Skins & Icon Packs, see: xref:enhanced-skins-a
 
 // CCFR here.
 
+=== New options for configuring the width of resizable sidebars
+// #TINYMCE-14528
+
+Previously, the content styles of a sidebar determined the width of that sidebar, and no editor option set that width.
+
+In {productname} {release-version}, three new options configure the width of any sidebar registered with the xref:customsidebar.adoc#resizable[`+resizable+`] property set to `+true+`. The xref:customsidebar.adoc#sidebar_width[`+sidebar_width+`] option sets the width the sidebar opens at and defaults to `+440+`. The xref:customsidebar.adoc#sidebar_min_width[`+sidebar_min_width+`] and xref:customsidebar.adoc#sidebar_max_width[`+sidebar_max_width+`] options set the smallest and largest widths a user can drag the sidebar to and default to `+300+` and `+800+`. All three options set widths in pixels. To keep the editable area usable, {productname} does not allow the editable area to shrink below 280 pixels, and this limit takes precedence over all three options.
+
+=== New `SidebarResizeStart` and `SidebarResized` events for tracking sidebar resizing
+// #TINYMCE-14529
+
+In {productname} {release-version}, two new events report when a user resizes a sidebar. {productname} fires xref:events.adoc[`+SidebarResizeStart+`] when a user starts dragging the resize handle, and xref:events.adoc[`+SidebarResized+`] when a user stops dragging. The `+SidebarResized+` event carries a `+{ width: number }+` payload holding the width of the sidebar, in pixels, after the resize.
+
+Together with the xref:customsidebar.adoc#sidebar_width[`+sidebar_width+`] option, these events allow an integration to store the width a user chooses and restore it the next time the editor loads. For an example, see: xref:customsidebar.adoc#persisting-the-sidebar-width[Persisting the sidebar width].
+
 
 [[changes]]
 == Changes
@@ -138,6 +160,16 @@ For information on using Enhanced Skins & Icon Packs, see: xref:enhanced-skins-a
 
 // CCFR here.
 
+=== The new `resizable` property controls whether a custom sidebar can be resized
+// #TINYMCE-14678
+// #TINYMCE-14683
+
+Previously, the styles applied to the content of a sidebar registered through `+addSidebar+` controlled the width of that sidebar. Resizable sidebars require {productname} to control that width instead, and that change of control would alter how every existing custom sidebar renders.
+
+In {productname} {release-version}, the `+addSidebar+` specification object accepts a new optional xref:customsidebar.adoc#resizable[`+resizable+`] property that defaults to `+false+`. A custom sidebar registered without the property renders as it did in earlier versions and is not resizable, so existing integrations are unaffected. Setting the property to `+true+` makes the sidebar resizable and requires the content of the sidebar to follow the width of the parent element. For information, see: xref:customsidebar.adoc#styling-a-resizable-sidebar[Styling a resizable sidebar].
+
+The sidebars registered by the xref:introduction-to-tiny-comments.adoc[Comments] and xref:tinymceai.adoc[{productname} AI] plugins set `+resizable+` to `+true+` and are resizable by default.
+
 
 [[removed]]
 == Removed

modules/ROOT/pages/customsidebar.adoc

@@ -32,6 +32,19 @@ The `+icon+` specifies an icon for the sidebar toggle button. The icon should be
 
 *Type:* `+String+`
 
+[[resizable]]
+==== `+resizable+`
+
+The `+resizable+` specifies whether a user can resize the sidebar by dragging the edge of the sidebar. The default is `+false+`.
+
+include::partial$misc/admon-requires-8.9v.adoc[]
+
+When set to `+true+`, {productname} renders a resize handle and controls the width of the sidebar using the xref:customsidebar.adoc#sidebar_width[`+sidebar_width+`], xref:customsidebar.adoc#sidebar_min_width[`+sidebar_min_width+`], and xref:customsidebar.adoc#sidebar_max_width[`+sidebar_max_width+`] options. The content of a sidebar registered with `+resizable+` set to `+true+` needs to follow the width of the parent element. For information, see: xref:customsidebar.adoc#styling-a-resizable-sidebar[Styling a resizable sidebar].
+
+When `+resizable+` is omitted or set to `+false+`, {productname} does not render a resize handle, ignores the three sidebar width options, and renders the sidebar at the width defined by the content styles of that sidebar.
+
+*Type:* `+Boolean+`
+
 [[onSetup]]
 ==== `+onSetup+`
 
@@ -62,10 +75,108 @@ The `+onHide+` specifies a function to be called when the panel is hidden. It pa
 
 The `+element():HTMLElement+` function returns the root element of the sidebar panel.
 
+[[resizable-sidebars]]
+== Resizable sidebars
+
+include::partial$misc/admon-requires-8.9v.adoc[]
+
+A user can resize a sidebar by dragging the edge of the sidebar toward or away from the editable area. {productname} renders a resize handle only for sidebars registered with the xref:customsidebar.adoc#resizable[`+resizable+`] property set to `+true+`.
+
+The sidebars registered by the xref:introduction-to-tiny-comments.adoc[Comments] and xref:tinymceai.adoc[{productname} AI] plugins are resizable by default. Sidebars registered through `+addSidebar+` are not resizable by default, so a custom sidebar created before {productname} 8.9 renders as it did previously.
+
+The xref:customsidebar.adoc#sidebar_width[`+sidebar_width+`], xref:customsidebar.adoc#sidebar_min_width[`+sidebar_min_width+`], and xref:customsidebar.adoc#sidebar_max_width[`+sidebar_max_width+`] options apply to every resizable sidebar in an editor. {productname} cannot set a separate width for an individual sidebar.
+
+[[styling-a-resizable-sidebar]]
+=== Styling a resizable sidebar
+
+The content styles of a sidebar that is not resizable determine how wide the sidebar renders.
+
+[source,js]
+----
+tinymce.init({
+  selector: 'textarea', // change this value according to your HTML
+  sidebar_show: 'mysidebar',
+  setup: (editor) => {
+    editor.ui.registry.addSidebar('mysidebar', {
+      tooltip: 'My sidebar',
+      icon: 'comment',
+      onShow: (api) => {
+        const container = document.createElement('div');
+        container.style.width = '600px';
+        api.element().appendChild(container);
+      },
+    });
+  }
+});
+----
+
+{productname} sets the width of a resizable sidebar, so the content styles need to follow the width of the parent element rather than set a width. Set the width of the content to `+100%+` so that the content inherits the width from xref:customsidebar.adoc#element[`+api.element()+`].
+
+[source,js]
+----
+tinymce.init({
+  selector: 'textarea', // change this value according to your HTML
+  sidebar_show: 'mysidebar',
+  sidebar_width: 500,
+  setup: (editor) => {
+    editor.ui.registry.addSidebar('mysidebar', {
+      tooltip: 'My sidebar',
+      icon: 'comment',
+      resizable: true,
+      onShow: (api) => {
+        const container = document.createElement('div');
+        container.style.width = '100%';
+        api.element().appendChild(container);
+      },
+    });
+  }
+});
+----
+
+IMPORTANT: A sidebar whose content styles set a fixed width does not render correctly when `+resizable+` is set to `+true+`. Update the content styles to `+100%+` before enabling the property.
+
+[[persisting-the-sidebar-width]]
+=== Persisting the sidebar width
+
+{productname} does not store the width a user drags a sidebar to. To keep a width between editor loads, store the width reported by the xref:events.adoc#editor-core-events[`+SidebarResized+`] event and pass the stored value to xref:customsidebar.adoc#sidebar_width[`+sidebar_width+`] when the editor is next created.
+
+[source,js]
+----
+const storedWidth = window.localStorage.getItem('sidebar-width');
+
+tinymce.init({
+  selector: 'textarea', // change this value according to your HTML
+  sidebar_show: 'mysidebar',
+  sidebar_width: storedWidth ? parseInt(storedWidth, 10) : 440,
+  setup: (editor) => {
+    editor.ui.registry.addSidebar('mysidebar', {
+      tooltip: 'My sidebar',
+      icon: 'comment',
+      resizable: true,
+      onShow: (api) => {
+        const container = document.createElement('div');
+        container.style.width = '100%';
+        api.element().appendChild(container);
+      },
+    });
+
+    editor.on('SidebarResized', (e) => {
+      window.localStorage.setItem('sidebar-width', e.width);
+    });
+  }
+});
+----
+
 == Options
 
+include::partial$configuration/sidebar_max_width.adoc[leveloffset=+1]
+
+include::partial$configuration/sidebar_min_width.adoc[leveloffset=+1]
+
 include::partial$configuration/sidebar_show.adoc[leveloffset=+1]
 
+include::partial$configuration/sidebar_width.adoc[leveloffset=+1]
+
 [[example-inside-the-tinymceinit]]
 == Example inside the tinymce.init
 

modules/ROOT/pages/events.adoc

@@ -229,6 +229,8 @@ The following events are provided by the {productname} editor.
 |LanguageLoadError |`+{ message: string }+` |Fired when the editor language pack fails to load.
 |BeforeRenderUI |N/A |Fired before the theme UI is rendered.
 |ToggleSidebar |N/A |Fired when a sidebar is toggled opened/closed.
+|SidebarResizeStart |N/A |Fired when a user starts dragging the resize handle of a sidebar. This event requires the sidebar to be registered with the xref:customsidebar.adoc#resizable[`+resizable+`] property set to `+true+`.
+|SidebarResized |`+{ width: number }+` |Fired when a user stops dragging the resize handle of a sidebar. The `+width+` is the width of the sidebar, in pixels, after the resize. This event requires the sidebar to be registered with the xref:customsidebar.adoc#resizable[`+resizable+`] property set to `+true+`.
 |longpress |(Same data as the native https://developer.mozilla.org/en-US/docs/Web/API/Element/touchstart_event[touchstart event]) |Fired when a long press occurs on a touch device inside the editor.
 |tap |(Same data as the native https://developer.mozilla.org/en-US/docs/Web/API/Document/touchend_event[touchend event]) |Fired when a tap occurs on a touch device inside the editor (simulated event similar to click).
 |ScrollContent |(Same data as the native https://developer.mozilla.org/en-US/docs/Web/API/Element/scroll_event[scroll event]) |(iframe mode only) Fired when the content inside an iframe window has been scrolled.

modules/ROOT/partials/configuration/sidebar_max_width.adoc

@@ -0,0 +1,41 @@
+[[sidebar_max_width]]
+== `+sidebar_max_width+`
+
+This option sets the largest width, in pixels, that a user can drag the sidebar to.
+
+The option applies only to sidebars registered with the `+resizable+` property set to `+true+`. A user cannot resize a sidebar registered without that property, and {productname} ignores this option.
+
+This option restricts dragging only. This option does not restrict the width set by xref:customsidebar.adoc#sidebar_width[`+sidebar_width+`], so a sidebar can open wider than the value set here.
+
+include::partial$misc/admon-iframe-only.adoc[]
+
+*Type:* `+Number+`
+
+*Default value:* `+800+`
+
+=== Example: using `+sidebar_max_width+`
+
+[source,js]
+----
+tinymce.init({
+  selector: 'textarea', // change this value according to your HTML
+  sidebar_show: 'mysidebar',
+  sidebar_max_width: 600,
+  setup: (editor) => {
+    editor.ui.registry.addSidebar('mysidebar', {
+      tooltip: 'My sidebar',
+      icon: 'comment',
+      resizable: true,
+      onShow: (api) => {
+        api.element().innerHTML = 'Hello world!';
+      },
+    });
+  }
+});
+----
+
+=== Limitations of the `+sidebar_max_width+` option
+
+The editable area cannot shrink below 280 pixels, and this limit takes precedence over `+sidebar_max_width+`. For information on this restriction, see: xref:customsidebar.adoc#limitations-of-the-sidebar-width-option[Limitations of the `+sidebar_width+` option].
+
+In a narrow editor, the width that remains beside a 280-pixel editable area can be smaller than the value set by `+sidebar_max_width+`. In that case, the remaining width becomes the effective maximum, and a user cannot drag the sidebar beyond that width.

modules/ROOT/partials/configuration/sidebar_min_width.adoc

@@ -0,0 +1,41 @@
+[[sidebar_min_width]]
+== `+sidebar_min_width+`
+
+This option sets the smallest width, in pixels, that a user can drag the sidebar to.
+
+The option applies only to sidebars registered with the `+resizable+` property set to `+true+`. A user cannot resize a sidebar registered without that property, and {productname} ignores this option.
+
+This option restricts dragging only. This option does not restrict the width set by xref:customsidebar.adoc#sidebar_width[`+sidebar_width+`], so a sidebar can open narrower than the value set here.
+
+include::partial$misc/admon-iframe-only.adoc[]
+
+*Type:* `+Number+`
+
+*Default value:* `+300+`
+
+=== Example: using `+sidebar_min_width+`
+
+[source,js]
+----
+tinymce.init({
+  selector: 'textarea', // change this value according to your HTML
+  sidebar_show: 'mysidebar',
+  sidebar_min_width: 400,
+  setup: (editor) => {
+    editor.ui.registry.addSidebar('mysidebar', {
+      tooltip: 'My sidebar',
+      icon: 'comment',
+      resizable: true,
+      onShow: (api) => {
+        api.element().innerHTML = 'Hello world!';
+      },
+    });
+  }
+});
+----
+
+=== Limitations of the `+sidebar_min_width+` option
+
+The editable area cannot shrink below 280 pixels, and this limit takes precedence over `+sidebar_min_width+`. For information on this restriction, see: xref:customsidebar.adoc#limitations-of-the-sidebar-width-option[Limitations of the `+sidebar_width+` option].
+
+When the editor is too narrow to provide the width set by `+sidebar_min_width+` alongside a 280-pixel editable area, {productname} does not resize the sidebar on drag, and the sidebar keeps the current width.

modules/ROOT/partials/configuration/sidebar_width.adoc

@@ -0,0 +1,42 @@
+[[sidebar_width]]
+== `+sidebar_width+`
+
+This option sets the width, in pixels, that the sidebar opens at on editor initialization.
+
+The option applies only to sidebars registered with the `+resizable+` property set to `+true+`. A sidebar registered without that property keeps the width defined by the content styles of that sidebar, and {productname} ignores this option.
+
+The xref:customsidebar.adoc#sidebar_min_width[`+sidebar_min_width+`] and xref:customsidebar.adoc#sidebar_max_width[`+sidebar_max_width+`] options do not restrict the width set by this option. Those options restrict only the widths a user can drag the sidebar to. The minimum width of the editable area does restrict this width. For information on this restriction, see: xref:customsidebar.adoc#limitations-of-the-sidebar-width-option[Limitations of the `+sidebar_width+` option].
+
+include::partial$misc/admon-iframe-only.adoc[]
+
+*Type:* `+Number+`
+
+*Default value:* `+440+`
+
+=== Example: using `+sidebar_width+`
+
+[source,js]
+----
+tinymce.init({
+  selector: 'textarea', // change this value according to your HTML
+  sidebar_show: 'mysidebar',
+  sidebar_width: 500,
+  setup: (editor) => {
+    editor.ui.registry.addSidebar('mysidebar', {
+      tooltip: 'My sidebar',
+      icon: 'comment',
+      resizable: true,
+      onShow: (api) => {
+        api.element().innerHTML = 'Hello world!';
+      },
+    });
+  }
+});
+----
+
+[[limitations-of-the-sidebar-width-option]]
+=== Limitations of the `+sidebar_width+` option
+
+The editable area and the sidebar share the same container. To keep the editable area usable, {productname} does not allow the editable area to shrink below 280 pixels. This limit is fixed and takes precedence over `+sidebar_width+`, xref:customsidebar.adoc#sidebar_min_width[`+sidebar_min_width+`], and xref:customsidebar.adoc#sidebar_max_width[`+sidebar_max_width+`].
+
+When the editor is too narrow to provide the requested width alongside a 280-pixel editable area, {productname} reduces the sidebar to the width that remains. For example, in an editor 1000 pixels wide, a `+sidebar_width+` of 2000 results in a sidebar approximately 716 pixels wide, because the editable area reserves 280 pixels and the editor border occupies the remaining pixels.

modules/ROOT/partials/misc/admon-requires-8.9v.adoc

@@ -0,0 +1 @@
+NOTE: This feature is only available for {productname} 8.9 and later.