DOC-2270_TINY-9980: add new `addCustomElements` documentation to `content-filtering.adoc` and release notes entry. (#3132)

* DOC-2270_TINY-9980: add new addCustomElements documentation to content-filtering.adoc, and release notes entry.

* improve custom element spec explanation

* added example of using `schema.addCustomElements` API

* Update modules/ROOT/pages/7.0-release-notes.adoc

Co-authored-by: spocke <spocke@moxiecode.com>

* Update modules/ROOT/partials/configuration/improved_custom_elements.adoc

Co-authored-by: spocke <spocke@moxiecode.com>

* Update modules/ROOT/pages/7.0-release-notes.adoc

* Update modules/ROOT/partials/configuration/improved_custom_elements.adoc

Co-authored-by: Mitchell Crompton <mitchell.crompton@tiny.cloud>

* Update modules/ROOT/partials/configuration/improved_custom_elements.adoc

Co-authored-by: Mitchell Crompton <mitchell.crompton@tiny.cloud>

* Update modules/ROOT/pages/7.0-release-notes.adoc

Co-authored-by: Mitchell Crompton <mitchell.crompton@tiny.cloud>

* DOC-2270: remove improved custom element page, update api links and copy edits for custom elements.adoc

---------

Co-authored-by: Farzad Hayat <farzad.hayatbakhsh@tiny.cloud>
Co-authored-by: spocke <spocke@moxiecode.com>
Co-authored-by: Mitchell Crompton <mitchell.crompton@tiny.cloud>

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

@@ -384,6 +384,19 @@ For more information about `highlight_on_focus` see the xref:accessibility.adoc#
 [NOTE]
 Any editors using this `highlight_on_focus: true` option, can remove this option from their {productname} init configuration when upgrading to {productname} 7.0.
 
+=== Improved Custom Elements
+// #TINY-9980 / TINY-9979
+
+{productname} 7.0 introduces enhancements to the existing xref:content-filtering.adoc#custom_elements.adoc[custom_elements] option and xref:apis/tinymce.html.schema.adoc#addCustomElements[addCustomElements] API. This update allows the structure of custom elements to be refined, offering users more flexibility and customization options.
+
+Key Improvements:
+
+* **New Custom Element Structure:** The custom_elements option and `addCustomElements` API now support a more complex structure. Each element is defined by a key-value pair, allowing for detailed specifications.
+* **Attributes and Inheritance:** Elements can inherit attributes and children from other specified elements using the extends property in the Custom Element Spec.
+* **Attribute and Children Specifications:** The Custom Element Spec includes properties such as attributes and children, enabling precise customization of element behavior.
+
+For more information and details for `addCustomElements` see xref:content-filtering.adoc#custom-elements[custom_elements].
+
 === Optional Tooltip for Dialog Footer Toggle Buttons
 //#TINY-10672
 

modules/ROOT/partials/configuration/custom_elements.adoc

@@ -15,3 +15,85 @@ tinymce.init({
   custom_elements: 'mycustomblock,~mycustominline' // Notice the ~ prefix to force a span element for the element
 });
 ----
+
+* **Custom Element Structure:** The custom_elements option and the `addCustomElements` API supports more complex structures. This structure is defined by a record where the key represents the name of the element, and the value corresponds to a detailed specification.
+* **Attributes and Inheritance:** Elements inherit attributes and children from other specified elements using the `+extends: "div"+` property in the `custom_elements` spec.
+* **Attribute and Children Specifications:** The `custom_elements` spec includes properties such as `attributes` which lists attribute names, or `children` which lists valid child element names. The `children` property includes presets like `@global`, `@blocks`, `@phrasing`, and `@flow`.
+
+HTML Element Sets: The exact element sets for each preset, depending on the schema set (html4, html5, or html5-strict), can be found in the below tables.
+
+[[html4]]
+=== HTML Element Sets: `html4`
+
+[cols="1,3",options="header"]
+|===
+| Type | Expected
+| @blocks | address, blockquote, div, dl, fieldset, form, h1, h2, h3, h4, h5, h6, hr, menu, ol, p, pre, table, ul, center, dir, isindex, noframes
+| @phrasing | a, abbr, b, bdo, br, button, cite, code, del, dfn, em, embed, i, iframe, img, input, ins, kbd, label, map, noscript, object, q, s, samp, script, select, small, span, strong, sub, sup, textarea, u, var, #text, #comment, acronym, applet, basefont, big, font, strike, tt
+| @flow | Same as @blocks + @phrasing
+|===
+
+[[html5]]
+=== HTML Element Sets: `html5`
+
+[cols="1,3",options="header"]
+|===
+| Type | Expected
+| @blocks | address, blockquote, div, dl, fieldset, form, h1, h2, h3, h4, h5, h6, hr, menu, ol, p, pre, table, ul, article, aside, details, dialog, figure, main, header, footer, hgroup, section, nav, a, ins, del, canvas, map, center, dir, isindex, noframes
+| @phrasing | a, abbr, b, bdo, br, button, cite, code, del, dfn, em, embed, i, iframe, img, input, ins, kbd, label, map, noscript, object, q, s, samp, script, select, small, span, strong, sub, sup, textarea, u, var, #text, #comment, audio, canvas, command, data, datalist, mark, meter, output, picture, progress, time, wbr, video, ruby, bdi, keygen, svg, acronym, applet, basefont, big, font, strike, tt
+| @flow | Same as @blocks + @phrasing
+|===
+
+[[html5-strict]]
+=== HTML Element Sets: `html5-strict`
+
+[cols="1,3",options="header"]
+|===
+| Type | Expected
+| @blocks | address, blockquote, div, dl, fieldset, form, h1, h2, h3, h4, h5, h6, hr, menu, ol, p, pre, table, ul, article, aside, details, dialog, figure, main, header, footer, hgroup, section, nav, a, ins, del, canvas, map
+| @phrasing | a, abbr, b, bdo, br, button, cite, code, del, dfn, em, embed, i, iframe, img, input, ins, kbd, label, map, noscript, object, q, s, samp, script, select, small, span, strong, sub, sup, textarea, u, var, #text, #comment, audio, canvas, command, data, datalist, mark, meter, output, picture, progress, time, wbr, video, ruby, bdi, keygen, svg
+| @flow | Same as @blocks + @phrasing
+|===
+
+=== Example using `+custom_elements+` with presets such as `@blocks`, `@phrasing`, and `@flow`.
+
+[source, js]
+----
+tinymce.init({
+  selector: "textarea",
+  // Add custom elements using the custom_elements option
+  custom_elements: {
+    // Custom element 'foo-bar' extends 'div' with attributes 'attr1' and 'attr2'
+    "foo-bar": {
+      extends: "div",
+      attributes: ["attr1", "attr2"],
+    },
+    // Custom element 'foo-baz' extends 'span' allowing children '@phrasing' and 'foo-child'
+    "foo-baz": {
+      extends: "span",
+      children: ["@phrasing", "foo-child"],
+    },
+    // Custom element 'foo-child' has no specific configuration
+    "foo-child": {},
+  },
+  // You can also use the addCustomElements API to add custom elements
+  setup: (editor) => {
+    editor.on("preinit", () => {
+      editor.schema.addCustomElements({
+        // Custom element 'hey-bar' extends 'div' with attributes 'attr1' and 'attr2' as well as all global attributes
+        "hey-bar": {
+          extends: "div",
+          attributes: ["@global", "attr1", "attr2"],
+        },
+        // Custom element 'hey-baz' extends 'span' allowing children 'hey-child' as well as all phrasing content
+        "hey-baz": {
+          extends: "span",
+          children: ["@phrasing", "hey-child"],
+        },
+        // Custom element 'hey-child' has no specific configuration
+        "hey-child": {},
+      });
+    });
+  },
+});
+----