Merge pull request #1747 from dolanmiu/feat/vanish

#1744 - Add `vanish` and `specVanish`

.nycrc

@@ -1,7 +1,7 @@
 {
   "check-coverage": true,
   "statements": 99.72,
-  "branches": 97.97,
+  "branches": 98.08,
   "functions": 99.83,
   "lines": 99.72,
   "include": [

demo/2-declaritive-styles.ts

@@ -195,6 +195,14 @@ const doc = new Document({
                         new TextRun({
                             text: "and back to normal.",
                         }),
+                        new TextRun({
+                            text: "This text will be invisible!",
+                            vanish: true,
+                        }),
+                        new TextRun({
+                            text: "This text will be VERY invisible! Word processors cannot override this!",
+                            specVanish: true,
+                        }),
                     ],
                 }),
                 new Paragraph({

docs/usage/text.md

@@ -151,6 +151,28 @@ const text = new TextRun({
 });
 ```
 
+### Vanish and SpecVanish
+
+You may want to hide your text in your document.
+
+`Vanish` should affect the normal display of text, but an application may have settings to force hidden text to be displayed.
+
+```ts
+const text = new TextRun({
+    text: "This text will be hidden",
+    vanish: true,
+});
+```
+
+`SpecVanish` was typically used to ensure that a paragraph style can be applied to a part of a paragraph, and still appear as in the Table of Contents (which in previous word processors would ignore the use of the style if it were being used as a character style).
+
+```ts
+const text = new TextRun({
+    text: "This text will be hidden forever.",
+    specVanish: true,
+});
+```
+
 ## Break
 
 Sometimes you would want to put text underneath another line of text but inside the same paragraph.

src/file/paragraph/run/properties.ts

@@ -45,6 +45,8 @@ export interface IRunStylePropertiesOptions {
     readonly imprint?: boolean;
     readonly revision?: IRunPropertiesChangeOptions;
     readonly border?: IBorderOptions;
+    readonly vanish?: boolean;
+    readonly specVanish?: boolean;
 }
 
 export interface IRunPropertiesOptions extends IRunStylePropertiesOptions {
@@ -215,6 +217,17 @@ export class RunProperties extends IgnoreIfEmptyXmlComponent {
         if (options.border) {
             this.push(new BorderElement("w:bdr", options.border));
         }
+
+        if (options.vanish) {
+            // https://c-rex.net/projects/samples/ooxml/e1/Part4/OOXML_P4_DOCX_vanish_topic_ID0E6W3O.html
+            // http://www.datypic.com/sc/ooxml/e-w_vanish-1.html
+            this.push(new OnOffElement("w:vanish", options.vanish));
+        }
+
+        if (options.specVanish) {
+            // https://c-rex.net/projects/samples/ooxml/e1/Part4/OOXML_P4_DOCX_specVanish_topic_ID0EIE1O.html
+            this.push(new OnOffElement("w:specVanish", options.vanish));
+        }
     }
 
     public push(item: XmlComponent): void {

src/file/paragraph/run/run.spec.ts

@@ -519,4 +519,42 @@ describe("Run", () => {
             });
         });
     });
+
+    describe("#vanish and #specVanish", () => {
+        it("should correctly set vanish", () => {
+            const run = new Run({
+                vanish: true,
+            });
+            const tree = new Formatter().format(run);
+            expect(tree).to.deep.equal({
+                "w:r": [
+                    {
+                        "w:rPr": [
+                            {
+                                "w:vanish": {},
+                            },
+                        ],
+                    },
+                ],
+            });
+        });
+
+        it("should correctly set specVanish", () => {
+            const run = new Run({
+                specVanish: true,
+            });
+            const tree = new Formatter().format(run);
+            expect(tree).to.deep.equal({
+                "w:r": [
+                    {
+                        "w:rPr": [
+                            {
+                                "w:specVanish": {},
+                            },
+                        ],
+                    },
+                ],
+            });
+        });
+    });
 });

src/file/paragraph/run/tab.ts

@@ -1,3 +1,4 @@
+// https://c-rex.net/projects/samples/ooxml/e1/Part4/OOXML_P4_DOCX_tab_topic_ID0EM6AO.html
 import { XmlComponent } from "@file/xml-components";
 
 // <xsd:group name="EG_RunInnerContent">