DOC-2689: Documentation enhancements for autoresize plugin in v8 docs. (#3831)

* DOC-2689: Documentation enhancements for autoresize plugin.

* Update modules/ROOT/pages/autoresize.adoc

Co-authored-by: Mitchell Crompton <[email protected]>

* Update modules/ROOT/pages/autoresize.adoc

Co-authored-by: Mitchell Crompton <[email protected]>

---------

Co-authored-by: Mitchell Crompton <[email protected]>

Author: kemister85

modules/ROOT/examples/live-demos/autoresize/index.html

@@ -0,0 +1,15 @@
+<div id="container">
+    <textarea id="autoresize">
+    <h1>Autoresize Plugin Demo</h1>
+    <p>This demo shows the autoresize plugin in action. The editor automatically adjusts its height based on content. Try adding or removing content to see the dynamic resizing behavior.</p>
+    <div>
+        <div><strong>How it works:</strong></div>
+        <ul>
+          <li>Type or paste content to see the editor expand</li>
+          <li>Delete content to see the editor shrink</li>
+          <li>The editor respects min/max height set limits</li>
+        </ul>
+    </div>
+    </textarea>
+</div>
+  

modules/ROOT/examples/live-demos/autoresize/index.js

@@ -0,0 +1,10 @@
+tinymce.init({
+    selector: 'textarea#autoresize',
+    plugins: "autoresize lists code",
+    toolbar: 'undo redo | bold italic underline strikethrough | alignleft aligncenter alignright alignjustify | bullist numlist outdent indent',
+    // Autoresize options
+    min_height: 100,
+    max_height: 400,
+    autoresize_bottom_margin: 20,
+    autoresize_overflow_padding: 10,
+  });

modules/ROOT/pages/autoresize.adoc

@@ -2,11 +2,15 @@
 :navtitle: Autoresize
 :description_short:
 :description: Automatically resize TinyMCE to fit content.
-:keywords: height, width, max_height, min_height, autoresize_overflow_padding, autoresize_overflow_padding
+:keywords: height, width, max_height, min_height, autoresize_overflow_padding, autoresize_bottom_margin, resize
 :pluginname: Autoresize
 :plugincode: autoresize
 
-This plugin automatically resizes the editor to the content inside it. It is typically used to prevent the editor from expanding infinitely as a user types into the editable area. For example, by giving the `+max_height+` option a value the editor will stop resizing when the set value is reached.
+The {pluginname} plugin automatically adjusts the editor height to match its content. This creates a more intuitive editing experience where the editor grows and shrinks naturally with content. Setting the `+max_height+` option would allow you to still control when the content would become scrollable.
+
+== Interactive demo
+
+liveDemo::autoresize[]
 
 == Basic setup
 
@@ -18,9 +22,18 @@ tinymce.init({
 });
 ----
 
+== How it works
+
+The Autoresize plugin monitors content changes and automatically adjusts the editor height to accommodate the content. When enabled:
+
+* The editor initializes and renders based on the minimum height specified by `+min_height+` option.
+* As content is added, the editor expands vertically
+* The editor stops expanding when it reaches the `+max_height+` limit
+* The `+resize+` handle is removed from the editor.
+
 == Options
 
-These settings affect the execution of the Autoresize plugin, including changes to the minimum width, height, bottom margin, and default initialization state.
+These settings control the autoresize behavior, including height limits, padding, and margins.
 
 include::partial$configuration/autoresize_bottom_margin.adoc[leveloffset=+1]
 
@@ -34,4 +47,4 @@ include::partial$configuration/min_height.adoc[leveloffset=+1]
 
 The Autoresize plugin provides the following {productname} command.
 
-include::partial$commands/autoresize-cmds.adoc[]
+include::partial$commands/autoresize-cmds.adoc[leveloffset=+1]

modules/ROOT/partials/commands/autoresize-cmds.adoc

@@ -1,11 +1,24 @@
 [cols="1,3",options="header"]
 |===
 |Command |Description
-|mceAutoResize |Auto resizes the editor to the contents.
+|mceAutoResize |Automatically resizes the editor to fit its current content.
 |===
 
-.Example
+== Manual autoresize trigger
+
+The `+mceAutoResize+` command can be used to manually trigger the autoresize functionality. This is useful when:
+
+* Content is dynamically added or removed programmatically
+* The editor needs to be resized after external changes
+* You want to ensure the editor size matches its content at a specific moment
+
+.Example: triggering autoresize manually
 [source,js]
 ----
+// Resize the active editor
 tinymce.activeEditor.execCommand('mceAutoResize');
+
+// Resize a specific editor by ID
+tinymce.get('my-editor-id').execCommand('mceAutoResize');
 ----
+

modules/ROOT/partials/configuration/autoresize_bottom_margin.adoc

@@ -5,20 +5,20 @@ This option allows you to specify the size of the `+padding+` at the bottom of t
 
 *Type:* `+Number+`
 
-=== Example: using `+autoresize_bottom_margin+`
+*Default value:* `+50+`
+
+=== Example: adding bottom margin for better content spacing
 
 [source,js]
 ----
 tinymce.init({
   selector: 'textarea',  // change this value according to your HTML
   plugins: 'autoresize',
-  autoresize_bottom_margin: 50
+  autoresize_bottom_margin: 60 // 50px is the default value
 });
 ----
 
-As of version 6.3, `autoresize_bottom_margin` must be set to a value below the `+margin-bottom+` property of any content CSS, else it will be ignored and set to `+0+`.
-
-=== Example: setting `+autoresize_bottom_margin+` to zero because `+margin-bottom+` is set elsewhere
+=== Example: setting bottom margin to zero
 
 [source,js]
 ----

modules/ROOT/partials/configuration/autoresize_overflow_padding.adoc

@@ -5,7 +5,9 @@ This option allows you to specify the size of the `+padding+` at the sides of th
 
 *Type:* `+Number+`
 
-=== Example: `+autoresize_overflow_padding+`
+*Default value:* `+1+`
+
+=== Example: adding horizontal padding for better content spacing
 
 [source,js]
 ----
@@ -15,3 +17,14 @@ tinymce.init({
   autoresize_overflow_padding: 50
 });
 ----
+
+=== Example: setting horizontal padding to zero
+
+[source,js]
+----
+tinymce.init({
+  selector: 'textarea',  // change this value according to your HTML
+  plugins: 'autoresize',
+  autoresize_overflow_padding: 0
+});
+----

modules/ROOT/partials/configuration/max_height.adoc

@@ -1,10 +1,10 @@
 [[max_height]]
 == `+max_height+`
 
-The `+max_height+` option has two kinds of behaviors depending on the state of the xref:autoresize.adoc[`+autoresize+`] plugin:
+The `+max_height+` option has different behaviors depending on whether the xref:autoresize.adoc[`+autoresize+`] plugin is enabled:
 
-* `+autoresize+` OFF (Default): Without the `+autoresize+` plugin, this option sets the maximum height that a user can stretch the entire {productname} interface (by grabbing the draggable area in the bottom right of the editor interface).
-* `+autoresize+` ON: With the `+autoresize+` plugin, this option sets the maximum height the editor can automatically expand to.
+* **Without `+autoresize+` plugin**: Sets the maximum height that users can manually resize the entire {productname} interface by dragging the resize handle in the bottom-right corner.
+* **With `+autoresize+` plugin**: Sets the maximum height the editor can automatically expand to when content is added.
 
 *Type:* `+Number+`
 
@@ -25,9 +25,15 @@ ifeval::["{plugincode}" == "autoresize"]
 tinymce.init({
   selector: 'textarea',  // change this value according to your HTML
   plugins: 'autoresize',
-  max_height: 500
+  max_height: 600
 });
 ----
 endif::[]
 
-NOTE: If the xref:editor-size-options.adoc#resize[`+resize+`] option is set to `+false+` the resize handle will be disabled and a user will not be able to resize the editor (by manual dragging). Note that `+resize+` defaults to `+false+` when the `+autoresize+` plugin is enabled.
+[NOTE]
+====
+* If the xref:editor-size-options.adoc#resize[`+resize+`] option is set to `+false+`, the resize handle will be disabled and users cannot manually resize the editor.
+* The `+resize+` option defaults to `+false+` when the `+autoresize+` plugin is enabled.
+* Values are specified in pixels without units.
+* If `+max_height+` is not set when using the `+autoresize+` plugin, the editor will default to the standard `+max_height+` behavior (unlimited height expansion).
+====

modules/ROOT/partials/configuration/min_height.adoc

@@ -1,10 +1,10 @@
 [[min_height]]
 == `+min_height+`
 
-The *min_height* option has two kinds of behaviors depending on the state of the xref:autoresize.adoc[`+autoresize+`] plugin:
+The `+min_height+` option has different behaviors depending on whether the xref:autoresize.adoc[`+autoresize+`] plugin is enabled:
 
-* `+autoresize+` OFF (Default): Without the `+autoresize+` plugin, this option sets the minimum height that a user can shrink the entire {productname} interface (by grabbing the draggable area in the bottom right of the editor interface).
-* `+autoresize+` ON: With the `+autoresize+` plugin, this option sets the minimum height the editor can automatically shrink to.
+* **Without `+autoresize+` plugin**: Sets the minimum height that users can manually shrink the entire {productname} interface by dragging the resize handle in the bottom-right corner.
+* **With `+autoresize+` plugin**: Sets the minimum height the editor can automatically shrink to when content is removed.
 
 *Type:* `+Number+`
 
@@ -32,4 +32,11 @@ tinymce.init({
 ----
 endif::[]
 
-NOTE: If the xref:editor-size-options.adoc#resize[`+resize+`] option is set to `+false+` the resize handle will be disabled and a user will not be able to resize the editor (by manual dragging). Note that `+resize+` defaults to `+false+` when the `+autoresize+` plugin is enabled.
+[NOTE]
+====
+* If the xref:editor-size-options.adoc#resize[`+resize+`] option is set to `+false+`, the resize handle will be disabled and users cannot manually resize the editor.
+* The `+resize+` option defaults to `+false+` when the `+autoresize+` plugin is enabled.
+* Values are specified in pixels without units.
+* Setting `+min_height+` too low may cause usability issues on mobile devices.
+* If `+min_height+` is not set when using the `+autoresize+` plugin, the editor will default to the standard `+min_height+` value of `+100+` pixels.
+====