v7 prep - includes redesigning parts of core, and unifying different types #956

devoidfury · 2021-05-24T02:51:42Z

The intent of this PR is to do a few things -

Refactor parts of core to better suit the newer declarative API
Simplify underlying code where possible
Unify and remove duplicate implementations of the same underlying type
Make the API a bit more consistent
Inline some or all of the XSD schemas for the types we're using as comments, as discussed in Add validator (Nonconformance to Office Open XML schema) #947
Clean up output values to be conformant to the spec, throw errors instead of silently failing

It's not ready to merge quite yet - I'm still working on things here; so far I've removed more code than I've added, even after adding a lot of comments and a few features. Opening this PR so you can review what's been done so far and start the discussion around these changes.

There may be a few items worth cherry-picking onto v6 - for example, commit 528be93, which fixes issue #507.

…ml; not useful in declarative style API

…s to declarative style

…splice`

… changed to val, and shadow alias removed

…type; BREAKING: paragraph border value attr renamed to style, to match other usages of borders

…d online

…olanmiu#954)

…s functions, which check and clean up values for specific defined types from the schema

codecov-commenter · 2021-05-24T06:31:40Z

Codecov Report

Merging #956 (034cd18) into master (37d099b) will increase coverage by 0.56%.
The diff coverage is 100.00%.

@@            Coverage Diff             @@
##           master     #956      +/-   ##
==========================================
+ Coverage   98.73%   99.29%   +0.56%     
==========================================
  Files         339      311      -28     
  Lines        3859     3541     -318     
  Branches      354      377      +23     
==========================================
- Hits         3810     3516     -294     
+ Misses         48       24      -24     
  Partials        1        1

Impacted Files	Coverage Δ
src/export/packer/next-compiler.ts	`90.00% <ø> (-0.17%)`	⬇️
src/file/document/document.ts	`100.00% <ø> (ø)`
src/file/drawing/anchor/anchor.ts	`100.00% <ø> (ø)`
src/file/drawing/drawing.ts	`100.00% <ø> (+16.66%)`	⬆️
src/file/drawing/extent/extent.ts	`100.00% <ø> (+22.22%)`	⬆️
...rawing/inline/graphic/graphic-data/graphic-data.ts	`100.00% <ø> (+18.18%)`	⬆️
...ile/drawing/inline/graphic/graphic-data/pic/pic.ts	`100.00% <ø> (+13.33%)`	⬆️
...-data/pic/shape-properties/form/extents/extents.ts	`100.00% <ø> (+22.22%)`	⬆️
...hic/graphic-data/pic/shape-properties/form/form.ts	`100.00% <ø> (+12.50%)`	⬆️
...phic-data/pic/shape-properties/shape-properties.ts	`100.00% <ø> (+15.38%)`	⬆️
... and 98 more

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 37d099b...034cd18. Read the comment docs.

… up tests

dolanmiu · 2021-05-24T14:03:44Z

Wow, very well done,

Could you add a list of breaking changes so I can add it to the release notes, like so:

https://github.com/dolanmiu/docx/releases

devoidfury · 2021-05-24T14:16:23Z

Yes, I'll make you a list when it's ready. I still need to go over:

~~export/~~
~~file/document~~
file/drawing
~~file/numbering~~
~~file/settings~~
~~file/styles~~

and a couple other areas first.

…umber value <foo w:val="1234"/>

…values

…es.updateFields = true setting

devoidfury · 2021-05-26T08:00:30Z

I'm wrapping it up, that's good enough for now. I did not get deep into file/drawing -- that should probably be done at some point, but for now we can move ahead without reworking it.

Here's the breaking changes and notes:

New features:

In several places, as allowed by the spec, Universal Measure units can now be used.
Universal Measure units are strings in the format /-?[0-9]+(.[0-9]+)?(mm|cm|in|pt|pc|pi)/, for example: "14pt", "20mm", "2in", "2cm".
These include page margins, page size, paragraph indents, and font sizes. These should be experimented with, some of these may not work and need testing -- even if it's technically valid according to the spec.
Added a bunch of formats to NumberFormat.
Much more compliant docx files, which should act more consistently in different editors.
Reduced bundle size slightly.
Boolean options like bold, etc can now be explicitly toggled off -- when set to false it adds the tag to disable it, rather than just omit the tag to enable it, which allows more flexibility.

Breaking changes:

Renamed enum PageNumberFormat -> NumberFormat.
Section vertical align enum changed: SectionVerticalAlignValue -> VerticalAlign
Runtime checks were added for some values. These can now throw errors for invalid arguments in some cases.
color values must now be in hex (eg "00CCFF") for Underline, Shading, run color, background color, border color
Paragraph border argument signature changed.
old:

  new Paragraph({
      border: {
          top: {
              value: "single",
              size: 6,
              color: "red",
          },
      }
  })

new:

  new Paragraph({
      border: {
          top: {
              style: BorderStyle.SINGLE,
              size: 6,
              color: "FF0000",
          },
      }
  })

For TableOfContents, updateFields option in Document must be explicitly set:

new Document({
  features: {
      updateFields: true,
  },
  // ...
})

ITableShadingAttributesProperties changed to IShadingAttributesProperties
Table and TableCell shading option signature changed to be consistent with shading everywhere else.

old:

  shading: {
      val: ShadingType.REVERSE_DIAGONAL_STRIPE,
      color: "00FFFF",
      fill: "FF0000",
  },

new:

  shading: {
      type: ShadingType.REVERSE_DIAGONAL_STRIPE,
      color: "00FFFF",
      fill: "FF0000",
  },

A great many internal classes were shifted around or removed. Internal methods were removed in several places. These changes should not affect you if you stuck to the public API (what's in the demos and docs)

dolanmiu · 2021-05-29T02:02:01Z

@devoidfury Been reviewing it recently

Will let you know!

docs/usage/text.md

src/convenience-functions.ts

src/file/core-properties/properties.ts

src/file/document/body/section-properties/doc-grid/doc-grid.ts

src/file/document/body/section-properties/properties/doc-grid.ts

src/file/paragraph/properties.ts

src/file/styles/style/paragraph-style.ts

src/file/table/table-cell/table-cell-components.ts

dolanmiu · 2021-05-29T02:27:57Z

src/file/table/table-cell/table-cell.ts


        for (const child of options.children) {
            this.root.push(child);
        }
-
-        if (options.width) {


Are these properties added back anywhere?

src/file/table/table-cell/table-cell-properties.ts

src/file/xml-components/simple-elements.ts

dolanmiu · 2021-05-29T02:31:48Z

@devoidfury Left some comments

Feel free to reply and address, will approve after!

dolanmiu · 2021-05-29T02:44:35Z

src/file/file.ts

@@ -132,18 +134,6 @@ export class File {
                this.footnotesWrapper.View.createFootNote(parseFloat(key), options.footnotes[key].children);
            }
        }
-
-        if (options.features) {
-            if (options.features.trackRevisions) {


@devoidfury If this gets deleted, then Demo 60 won't work?

https://github.com/dolanmiu/docx/blob/730e33b1644e541c18aab6413794220eb20edab9/demo/60-track-revisions.ts

dolanmiu · 2021-05-31T01:34:09Z

@devoidfury Does demo 60 still work?

devoidfury · 2021-05-31T01:42:27Z

@dolanmiu it appears to - I didn't remove the "trackRevisions" feature

devoidfury · 2021-05-31T01:43:04Z

src/file/settings/settings.ts

Rather than calling this.settings.addTrackRevisions(), it's passed straight as an option into the Settings object which handles it in the constructor.

dolanmiu · 2021-05-31T01:57:08Z

@devoidfury Thank you for clarifying

dolanmiu · 2021-06-01T00:12:42Z

@devoidfury Merged in!

devoidfury added 16 commits May 24, 2021 05:39

remove from API delete()/IsDeleted(), and deleted check from prepForX…

ff14fca

…ml; not useful in declarative style API

fix test descriptions

bdc0aa2

remove unnecessary function expression in prepForXml

acc23be

update table-row-properties, table-cell-properties, table-cell-border…

2611e0c

…s to declarative style

move break up higher in order, to use the simpler push instead of `…

fcc393a

…splice`

unify Shading; breaking change: Paragraph/Run shading option key type…

496fcb5

… changed to val, and shadow alias removed

unify Border type

5155cda

simplify section-properties

54ab55b

further clean up border code; update paragraph borders to use shared …

08bd274

…type; BREAKING: paragraph border value attr renamed to style, to match other usages of borders

add test for floating vertical position

1ea6017

fix dolanmiu#507 - docx file not opening in edit mode in word and wor…

528be93

…d online

Consolidate TableWidth and TableCellMargins types; add Table indent (d…

dd6d1bc

…olanmiu#954)

add test for table indent property

449e1ed

Simplify run format properties, removing duplicate classes. Add value…

ee105cd

…s functions, which check and clean up values for specific defined types from the schema

use hexColorValue in borders and underlines

097c6a5

add tests for values functions

56eecef

devoidfury force-pushed the experiment branch from a677acd to 56eecef Compare May 24, 2021 06:13

remove deprecated mutable drawing functions: scale, setXY

a56119e

remove more duplicate classes; add additional values functions; clean…

ce2a0fb

… up tests

devoidfury force-pushed the experiment branch from acc57a4 to 2755227 Compare May 24, 2021 09:02

add values checks to remaining file/table code

4466145

devoidfury force-pushed the experiment branch from 2755227 to 4466145 Compare May 24, 2021 09:04

progress on clean up file/paragraph

7bfe8f2

devoidfury added 4 commits May 24, 2021 21:03

Add additional values functions for defined types

d0036e6

update file/numbering with schema comments and values functions

c3e92c0

add NumberValueElement, representing a simple element with a single n…

22e62ed

…umber value <foo w:val="1234"/>

add schema comments and update file/document; unify VerticalAlign type

e198f07

devoidfury added 10 commits May 25, 2021 03:43

update file/document and section-properties

63cea76

update file/styles

b05748d

fix demos. BREAKING: PageNumberFormat enum renamed to NumberFormat

3a02bc0

fix measurementOrPercentValue definition to include UniversalMeasure …

da61a30

…values

clean up settings; BREAKING: TableOfContents requires Document featur…

60b7ce4

…es.updateFields = true setting

simplify core-properties; add xsd comment

e4709a7

add xsd comments to file/drawing

5a52541

improve test coverage

05a6ab7

fix "missing export NumberFormat"

6603aaf

fix demos

730e33b

dolanmiu requested changes May 29, 2021

View reviewed changes

change shading val -> type

034cd18

dolanmiu merged commit de145e0 into dolanmiu:master Jun 1, 2021

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

v7 prep - includes redesigning parts of core, and unifying different types #956

v7 prep - includes redesigning parts of core, and unifying different types #956

devoidfury commented May 24, 2021 •

edited

codecov-commenter commented May 24, 2021 •

edited

dolanmiu commented May 24, 2021

devoidfury commented May 24, 2021 •

edited

devoidfury commented May 26, 2021 •

edited

dolanmiu commented May 29, 2021 •

edited

dolanmiu May 29, 2021

devoidfury May 29, 2021

dolanmiu commented May 29, 2021

dolanmiu May 29, 2021 •

edited

dolanmiu commented May 31, 2021

devoidfury commented May 31, 2021

devoidfury commented May 31, 2021

dolanmiu commented May 31, 2021

dolanmiu commented Jun 1, 2021

v7 prep - includes redesigning parts of core, and unifying different types #956

v7 prep - includes redesigning parts of core, and unifying different types #956

Conversation

devoidfury commented May 24, 2021 • edited

codecov-commenter commented May 24, 2021 • edited

Codecov Report

dolanmiu commented May 24, 2021

devoidfury commented May 24, 2021 • edited

devoidfury commented May 26, 2021 • edited

dolanmiu commented May 29, 2021 • edited

dolanmiu May 29, 2021

Choose a reason for hiding this comment

devoidfury May 29, 2021

Choose a reason for hiding this comment

dolanmiu commented May 29, 2021

dolanmiu May 29, 2021 • edited

Choose a reason for hiding this comment

dolanmiu commented May 31, 2021

devoidfury commented May 31, 2021

devoidfury commented May 31, 2021

dolanmiu commented May 31, 2021

dolanmiu commented Jun 1, 2021

devoidfury commented May 24, 2021 •

edited

codecov-commenter commented May 24, 2021 •

edited

devoidfury commented May 24, 2021 •

edited

devoidfury commented May 26, 2021 •

edited

dolanmiu commented May 29, 2021 •

edited

dolanmiu May 29, 2021 •

edited