This class represents a style.
It is used to specify the formatting of a document or a portion of a document.
@@ -852,6 +861,7 @@ It is used to manage the named styles that are used in the document.
* [CommonStyles](#CommonStyles)
* [`new CommonStyles()`](#new_CommonStyles_new)
+ * [`.createListStyle(name)`](#CommonStyles+createListStyle) ⇒ [ListStyle](#ListStyle)
* [`.createParagraphStyle(name)`](#CommonStyles+createParagraphStyle) ⇒ ParagraphStyle
* [`.getName(displayName)`](#CommonStyles+getName) ⇒ string \| undefined
* [`.getAll()`](#CommonStyles+getAll)
@@ -871,6 +881,28 @@ const commonStyles = new CommonStyles();
* * *
+
+
+### `commonStyles.createListStyle(name)` ⇒ [ListStyle](#ListStyle)
+The `createListStyle()` method creates a new `ListStyle` instance with the given name.
+If a style with this name already exists, the existing style will be returned.
+
+#### Parameters
+- name string
+The unique name for the style
+
+**Return value**
+[ListStyle](#ListStyle) - A new `ListStyle` instance with the specified name or an existing style, if one with the specified name exists
+
+**Example**
+```js
+const commonStyles = new CommonStyles();
+commonStyles.createListStyle('Contents');
+```
+**Since**: 0.11.0
+
+* * *
+
### `commonStyles.createParagraphStyle(name)` ⇒ ParagraphStyle
@@ -1079,6 +1111,11 @@ Adds an empty list at the end of the document.
**Return value**
[List](#List) - The newly added list
+**Example**
+```js
+new TextBody()
+ .addList();
+```
**Since**: 0.7.0
* * *
@@ -1233,6 +1270,230 @@ Returns the string representation of this document in flat open document xml for
* * *
+
+
+## BulletListLevelStyle
+This class represents a list style where list items are preceded by bullets.
+
+**Since**: 0.11.0
+
+* [BulletListLevelStyle](#BulletListLevelStyle)
+ * [`new BulletListLevelStyle(level)`](#new_BulletListLevelStyle_new)
+ * [`.getBulletChar()`](#BulletListLevelStyle+getBulletChar) ⇒ string
+ * [`.setBulletChar(bulletChar)`](#BulletListLevelStyle+setBulletChar) ⇒ [BulletListLevelStyle](#BulletListLevelStyle)
+ * [`.getLevel()`](#BulletListLevelStyle+getLevel) ⇒ number
+ * [`.getNumberPrefix()`](#BulletListLevelStyle+getNumberPrefix) ⇒ string \| undefined
+ * [`.setNumberPrefix(prefix)`](#BulletListLevelStyle+setNumberPrefix) ⇒ [BulletListLevelStyle](#BulletListLevelStyle)
+ * [`.getNumberSuffix()`](#BulletListLevelStyle+getNumberSuffix) ⇒ string \| undefined
+ * [`.setNumberSuffix(suffix)`](#BulletListLevelStyle+setNumberSuffix) ⇒ [BulletListLevelStyle](#BulletListLevelStyle)
+ * [`.getRelativeBulletSize()`](#BulletListLevelStyle+getRelativeBulletSize) ⇒ string \| undefined
+ * [`.setRelativeBulletSize(relativeSize)`](#BulletListLevelStyle+setRelativeBulletSize) ⇒ [BulletListLevelStyle](#BulletListLevelStyle)
+
+
+* * *
+
+
+
+### `new BulletListLevelStyle(level)`
+Creates a `BulletListLevelStyle` instance that represents a list style where list items are preceded by bullets.
+
+#### Parameters
+- level number
+The level of the list style, starting with `1`
+
+**Example**
+```js
+const style = new BulletListLevelStyle(3);
+```
+
+* * *
+
+
+
+### `bulletListLevelStyle.getBulletChar()` ⇒ string
+The `getBulletChar()` method returns the character to use as the bullet.
+
+**Return value**
+string - The character to use as the bullet
+
+**Example**
+```js
+const style = new BulletListLevelStyle(3);
+style.getBulletChar(); // '\u2022'
+style.setBulletChar('~');
+style.getBulletChar(); // '~'
+```
+**Since**: 0.11.0
+
+* * *
+
+
+
+### `bulletListLevelStyle.setBulletChar(bulletChar)` ⇒ [BulletListLevelStyle](#BulletListLevelStyle)
+The `setBulletChar()` method sets the character to use as the bullet.
+
+If an illegal value is provided, the value will be ignored.
+
+#### Parameters
+- bulletChar string
+The character to use as the bullet
+
+**Return value**
+[BulletListLevelStyle](#BulletListLevelStyle) - The `BulletListLevelStyle` object
+
+**Example**
+```js
+const style = new BulletListLevelStyle(3);
+style.setBulletChar('~'); // '~'
+style.setBulletChar(''); // '~'
+```
+**Since**: 0.11.0
+
+* * *
+
+
+
+### `bulletListLevelStyle.getLevel()` ⇒ number
+The `getLevel()` method returns the level of the list style.
+
+**Return value**
+number - The level of the list style, starting with `1`
+
+**Example**
+```js
+const style = new BulletListLevelStyle(3);
+style.getLevel(); // 3
+```
+**Since**: 0.11.0
+
+* * *
+
+
+
+### `bulletListLevelStyle.getNumberPrefix()` ⇒ string \| undefined
+The `getNumberPrefix()` method returns the character to display before a bullet.
+
+**Return value**
+string \| undefined - The character to display before a bullet or `undefined` if no prefix is set
+
+**Example**
+```js
+const style = new BulletListLevelStyle(3);
+style.getNumberPrefix(); // undefined
+style.setNumberPrefix('~');
+style.getNumberPrefix(); // '~'
+```
+**Since**: 0.11.0
+
+* * *
+
+
+
+### `bulletListLevelStyle.setNumberPrefix(prefix)` ⇒ [BulletListLevelStyle](#BulletListLevelStyle)
+The `setNumberPrefix()` method sets the character to display before a bullet.
+
+#### Parameters
+- prefix string | undefined
+The character to display before a bullet or `undefined` to unset the prefix
+
+**Return value**
+[BulletListLevelStyle](#BulletListLevelStyle) - The `BulletListLevelStyle` object
+
+**Example**
+```js
+const style = new BulletListLevelStyle(3);
+style.setNumberPrefix('~'); // '~'
+style.setNumberPrefix(undefined); // undefined
+```
+**Since**: 0.11.0
+
+* * *
+
+
+
+### `bulletListLevelStyle.getNumberSuffix()` ⇒ string \| undefined
+The `getNumberSuffix()` method returns the character to display after a bullet.
+
+**Return value**
+string \| undefined - The character to display after a bullet or `undefined` if no suffix is set
+
+**Example**
+```js
+const style = new BulletListLevelStyle(3);
+style.getNumberSuffix(); // undefined
+style.setNumberSuffix('~');
+style.getNumberSuffix(); // '~'
+```
+**Since**: 0.11.0
+
+* * *
+
+
+
+### `bulletListLevelStyle.setNumberSuffix(suffix)` ⇒ [BulletListLevelStyle](#BulletListLevelStyle)
+The `setNumberSuffix()` method sets the character to display after a bullet.
+
+#### Parameters
+- suffix string | undefined
+The character to display after a bullet or `undefined` to unset the suffix
+
+**Return value**
+[BulletListLevelStyle](#BulletListLevelStyle) - The `BulletListLevelStyle` object
+
+**Example**
+```js
+const style = new BulletListLevelStyle(3);
+style.setNumberSuffix('~'); // '~'
+style.setNumberSuffix(undefined); // undefined
+```
+**Since**: 0.11.0
+
+* * *
+
+
+
+### `bulletListLevelStyle.getRelativeBulletSize()` ⇒ string \| undefined
+The `getRelativeBulletSize()` method returns the percentage value for the bullet size relative to the font size of the paragraphs in the bullet list.
+
+**Return value**
+string \| undefined - The percentage value for the bullet size or `undefined` if no relative bullet size is set
+
+**Example**
+```js
+const style = new BulletListLevelStyle(3);
+style.getRelativeBulletSize(); // undefined
+style.setRelativeBulletSize('23%');
+style.getRelativeBulletSize(); // '23%'
+```
+**Since**: 0.11.0
+
+* * *
+
+
+
+### `bulletListLevelStyle.setRelativeBulletSize(relativeSize)` ⇒ [BulletListLevelStyle](#BulletListLevelStyle)
+The `setNumberSuffix()` method sets the percentage value for the bullet size relative to the font size of the paragraphs in the bullet list.
+
+If an illegal value is provided, the value will be ignored.
+
+#### Parameters
+- relativeSize string | undefined
+The percentage value for the bullet size or `undefined` to unset the bullet size
+
+**Return value**
+[BulletListLevelStyle](#BulletListLevelStyle) - The `BulletListLevelStyle` object
+
+**Example**
+```js
+const style = new BulletListLevelStyle(3);
+style.setRelativeBulletSize('23%'); // '23%'
+style.setRelativeBulletSize('42px'); // '23%'
+style.setRelativeBulletSize(undefined); // undefined
+```
+**Since**: 0.11.0
+
+* * *
+
## FontFace
@@ -1467,6 +1728,175 @@ font.getName(); // 'FreeSans'
* * *
+
+
+## ListStyle
+This class represents a list style.
+
+List styles are used to specify the formatting of a list and its items.
+A list style contains a set of style elements for each list level (@see ListLevelStyle).
+If a list style is applied to a list but does not contain a list level specification for a specific level, the list level style of the next lower level is used.
+
+**Since**: 0.11.0
+
+* [ListStyle](#ListStyle)
+ * [`new ListStyle(displayName)`](#new_ListStyle_new)
+ * [`.getConsecutiveNumbering()`](#ListStyle+getConsecutiveNumbering) ⇒ boolean
+ * [`.setConsecutiveNumbering(consecutiveNumbering)`](#ListStyle+setConsecutiveNumbering) ⇒ [ListStyle](#ListStyle)
+ * [`.createBulletListLevelStyle(level)`](#ListStyle+createBulletListLevelStyle) ⇒ [BulletListLevelStyle](#BulletListLevelStyle)
+ * [`.getListLevelStyle(level)`](#ListStyle+getListLevelStyle) ⇒ [BulletListLevelStyle](#BulletListLevelStyle) \| undefined
+ * [`.getListLevelStyles()`](#ListStyle+getListLevelStyles) ⇒ [Array.<BulletListLevelStyle>](#BulletListLevelStyle)
+ * [`.removeListLevelStyle(level)`](#ListStyle+removeListLevelStyle) ⇒ [ListStyle](#ListStyle)
+
+
+* * *
+
+
+
+### `new ListStyle(displayName)`
+Creates a `ListStyle` instance that represents the formatting of a list.
+
+#### Parameters
+- displayName string
+The unique display name for the style
+
+**Example**
+```js
+const style = new ListStyle('Contents');
+```
+
+* * *
+
+
+
+### `listStyle.getConsecutiveNumbering()` ⇒ boolean
+The `getConsecutiveNumbering()` method returns whether the style uses consecutive numbering for all list levels or whether each list level restarts the numbering.
+
+**Return value**
+boolean - `true` if consecutive numbering is used for all list levels or `false` if each list level restarts numbering
+
+**Example**
+```js
+const style = new ListStyle('Contents');
+style.getConsecutiveNumbering(); // false
+style.setConsecutiveNumbering(true);
+style.getConsecutiveNumbering(); // true
+```
+**Since**: 0.11.0
+
+* * *
+
+
+
+### `listStyle.setConsecutiveNumbering(consecutiveNumbering)` ⇒ [ListStyle](#ListStyle)
+The `setConsecutiveNumbering()` method sets returns whether the style uses consecutive numbering for all list levels or whether each list level restarts the numbering.
+
+#### Parameters
+- consecutiveNumbering boolean
+`true` if consecutive numbering is used for all list levels or `false` if each list level restarts numbering
+
+**Return value**
+[ListStyle](#ListStyle) - The `ListStyle` object
+
+**Example**
+```js
+const style = new ListStyle('Contents');
+style.setConsecutiveNumbering(true); // true
+```
+**Since**: 0.11.0
+
+* * *
+
+
+
+### `listStyle.createBulletListLevelStyle(level)` ⇒ [BulletListLevelStyle](#BulletListLevelStyle)
+The `createBulletListLevelStyle()` method creates a new `BulletListLevelStyle` instance for the given list level.
+If a list level style for this level already exists, the existing style will be overwritten.
+
+#### Parameters
+- level number
+The level of the list style, starting with `1`
+
+**Return value**
+[BulletListLevelStyle](#BulletListLevelStyle) - A new `BulletListLevelStyle` instance with the specified level
+
+**Throws**:
+
+- Error if the given list level is invalid
+
+**Example**
+```js
+const style = new ListStyle('Contents');
+style.createBulletListLevelStyle(3);
+```
+**Since**: 0.11.0
+
+* * *
+
+
+
+### `listStyle.getListLevelStyle(level)` ⇒ [BulletListLevelStyle](#BulletListLevelStyle) \| undefined
+The `getListLevelStyle()` method returns the list level style for the given list level.
+If a list level style for this level already exists, the existing style will be overwritten.
+
+#### Parameters
+- level number
+The level of the list style, starting with `1`
+
+**Return value**
+[BulletListLevelStyle](#BulletListLevelStyle) \| undefined - The list level style for the specified level or `undefined` if no list level style is defined for the specified level
+
+**Example**
+```js
+const style = new ListStyle('Contents');
+style.getListLevelStyle(3);
+```
+**Since**: 0.11.0
+
+* * *
+
+
+
+### `listStyle.getListLevelStyles()` ⇒ [Array.<BulletListLevelStyle>](#BulletListLevelStyle)
+The `getListLevelStyles()` method returns a new `Array` object that contains all list level styles of a list style.
+
+**Return value**
+[Array.<BulletListLevelStyle>](#BulletListLevelStyle) - A new `Array` object that contains the list level styles of a list style
+
+**Example**
+```js
+const style = new ListStyle('Contents');
+style.createBulletListLevelStyle(1);
+style.createBulletListLevelStyle(2);
+styles.getListLevelStyles();
+```
+**Since**: 0.11.0
+
+* * *
+
+
+
+### `listStyle.removeListLevelStyle(level)` ⇒ [ListStyle](#ListStyle)
+The `removeListLevelStyle()` method removes the list level style for the given list level.
+
+#### Parameters
+- level number
+The level of the list style, starting with `1`
+
+**Return value**
+[ListStyle](#ListStyle) - The `ListStyle` object
+
+**Example**
+```js
+const style = new ListStyle('Contents');
+style.createBulletListLevelStyle(3);
+style.removeListLevelStyle(3);
+styles.getListLevelStyles(); // []
+```
+**Since**: 0.11.0
+
+* * *
+
## Style
@@ -2221,10 +2651,14 @@ This class represents a list and may contain any number list items.
* [List](#List)
* [`new List()`](#new_List_new)
* [`.addItem([item])`](#List+addItem) ⇒ [ListItem](#ListItem)
- * [`.insertItem(position, item)`](#List+insertItem) ⇒ [ListItem](#ListItem)
* [`.getItem(position)`](#List+getItem) ⇒ [ListItem](#ListItem) \| undefined
* [`.getItems()`](#List+getItems) ⇒ [Array.<ListItem>](#ListItem)
+ * [`.insertItem(position, item)`](#List+insertItem) ⇒ [ListItem](#ListItem)
* [`.removeItemAt(position)`](#List+removeItemAt) ⇒ [ListItem](#ListItem) \| undefined
+ * [`.getStyle()`](#List+getStyle) ⇒ [ListStyle](#ListStyle) \| undefined
+ * [`.setStyle(style)`](#List+setStyle) ⇒ [List](#List)
+ * [`.getStyleName()`](#List+getStyleName) ⇒ string \| undefined
+ * [`.setStyleName(styleName)`](#List+setStyleName) ⇒ [List](#List)
* [`.clear()`](#List+clear) ⇒ [List](#List)
* [`.size()`](#List+size) ⇒ number
@@ -2246,11 +2680,11 @@ new List();
### `list.addItem([item])` ⇒ [ListItem](#ListItem)
-The `addItem()` method adds a new list item with the specified text or adds the specified item to the list.
+The `addItem()` method adds a new list item or adds the specified item to the list.
#### Parameters
-- [item] string | [ListItem](#ListItem)
-The text content of the new item or the item to add
+- [item] [ListItem](#ListItem)
+The item to add
**Return value**
[ListItem](#ListItem) - The added `ListItem` object
@@ -2258,8 +2692,54 @@ The text content of the new item or the item to add
**Example**
```js
const list = new List();
-list.addItem('First item');
-list.addItem(new ListItem('Second item'));
+list.addItem();
+list.addItem(new ListItem());
+```
+**Since**: 0.2.0
+
+* * *
+
+
+
+### `list.getItem(position)` ⇒ [ListItem](#ListItem) \| undefined
+The `getItem()` method returns the item at the specified position in the list.
+If an invalid position is given, undefined is returned.
+
+#### Parameters
+- position number
+The index of the requested list item (starting from 0).
+
+**Return value**
+[ListItem](#ListItem) \| undefined - The `ListItem` object at the specified position
+or `undefined` if there is no list item at the specified position
+
+**Example**
+```js
+const list = new List();
+list.addItem();
+list.addItem();
+list.getItem(1); // second item
+list.getItem(2); // undefined
+```
+**Since**: 0.2.0
+
+* * *
+
+
+
+### `list.getItems()` ⇒ [Array.<ListItem>](#ListItem)
+The `getItems()` method returns all list items.
+
+**Return value**
+[Array.<ListItem>](#ListItem) - A copy of the list of `ListItem` objects
+
+**Example**
+```js
+const list = new List();
+list.getItems(); // []
+list.addItem();
+list.addItem();
+list.getItems(); // [first item, second item]
```
**Since**: 0.2.0
@@ -2268,18 +2748,17 @@ list.addItem(new ListItem('Second item'));
### `list.insertItem(position, item)` ⇒ [ListItem](#ListItem)
-The `insertItem` method inserts a new list item with the specified text
-or inserts the specified item at the specified position.
+The `insertItem` method inserts the specified item at the specified position.
The item is inserted before the item at the specified position.
-If the position is greater than the current number items, the new item is appended at the end of the list.
+If the position is greater than the current number of items, the new item is appended at the end of the list.
If the position is negative, the new item is inserted as first element.
#### Parameters
- position number
The index at which to insert the list item (starting from 0).
-- item string | [ListItem](#ListItem)
-The text content of the new item or the item to insert
+- item [ListItem](#ListItem)
+The item to insert
**Return value**
[ListItem](#ListItem) - The inserted `ListItem` object
@@ -2287,83 +2766,122 @@ The text content of the new item or the item to insert
**Example**
```js
const list = new List();
-list.addItem('First item'); // 'First item'
-list.addItem('Second item'); // 'First item', 'Second item'
-list.insertItem(1, 'After first item'); // 'First item', 'After first item', 'Second item'
+list.addItem();
+list.insertItem(0, new ListItem()); // insert before existing item
```
**Since**: 0.2.0
* * *
-
+
-### `list.getItem(position)` ⇒ [ListItem](#ListItem) \| undefined
-The `getItem()` method returns the item at the specified position in the list.
-If an invalid position is given, undefined is returned.
+### `list.removeItemAt(position)` ⇒ [ListItem](#ListItem) \| undefined
+The `removeItemAt()` method removes the list item from the specified position.
#### Parameters
- position number
-The index of the requested list item (starting from 0).
+The index of the list item to remove (starting from 0).
**Return value**
-[ListItem](#ListItem) \| undefined - The `ListItem` object at the specified position
-or `undefined` if there is no list item at the specified position
+[ListItem](#ListItem) \| undefined - The removed `ListItem` object
+or undefined if there is no list item at the specified position
**Example**
```js
const list = new List();
-list.addItem('First item');
-list.addItem('Second item');
-list.getItem(1); // 'Second item'
-list.getItem(2); // undefined
+list.addItem();
+list.addItem();
+list.removeItemAt(0); // first item
+list.getItems(); // [second item]
+list.removeItemAt(2); // undefined
```
**Since**: 0.2.0
* * *
-
+
-### `list.getItems()` ⇒ [Array.<ListItem>](#ListItem)
-The `getItems()` method returns all list items.
+### `list.getStyle()` ⇒ [ListStyle](#ListStyle) \| undefined
+Returns the style of the list.
**Return value**
-[Array.<ListItem>](#ListItem) - A copy of the list of `ListItem` objects
+[ListStyle](#ListStyle) \| undefined - The style of the list or `undefined` if no style was set
**Example**
```js
const list = new List();
-list.getItems(); // []
-list.addItem('First item');
-list.addItem('Second item');
-list.getItems(); // ['First item', 'Second item']
+list.getStyle(); // undefined
+list.setStyle(new ListStyle());
+list.getStyle(); // previously set style
```
-**Since**: 0.2.0
+**Since**: 0.11.0
* * *
-
+
-### `list.removeItemAt(position)` ⇒ [ListItem](#ListItem) \| undefined
-The `removeItemAt()` method removes the list item from the specified position.
+### `list.setStyle(style)` ⇒ [List](#List)
+Sets the new style of the list.
+To reset the style, `undefined` must be given.
+
+If style and style name are both set, the custom style will be set and the common style will be ignored.
#### Parameters
-- position number
-The index of the list item to remove (starting from 0).
+- style [ListStyle](#ListStyle) | undefined
+The new style or `undefined` to reset the style
**Return value**
-[ListItem](#ListItem) \| undefined - The removed `ListItem` object
-or undefined if there is no list item at the specified position
+[List](#List) - The `List` object
+
+**Example**
+```js
+new List()
+ .setStyle(new ListStyle());
+```
+**Since**: 0.11.0
+
+* * *
+
+
+
+### `list.getStyleName()` ⇒ string \| undefined
+Returns the name of the common style of the list.
+
+**Return value**
+string \| undefined - The name of the common style or `undefined` if no common style was set
**Example**
```js
const list = new List();
-list.addItem('First item');
-list.addItem('Second item');
-list.removeItemAt(0); // 'First item'
-list.getItems(); // ['Second item']
-list.removeItemAt(2); // undefined
+list.getStyleName(); // undefined
+list.setStyleName('Summary');
+list.getStyleName(); // 'Summary'
```
-**Since**: 0.2.0
+**Since**: 0.11.0
+
+* * *
+
+
+
+### `list.setStyleName(styleName)` ⇒ [List](#List)
+Sets the name of the common style that should be applied to the list.
+To reset the common style, `undefined` must be given.
+
+If style and style name are both set, the custom style will be set and the common style will be ignored.
+
+#### Parameters
+- styleName string | undefined
+The name of the common style or `undefined` to reset the common style
+
+**Return value**
+[List](#List) - The `List` object
+
+**Example**
+```js
+new List()
+ .setStyleName('Summary');
+```
+**Since**: 0.11.0
* * *
@@ -2378,9 +2896,10 @@ The `clear()` method removes all items from the list.
**Example**
```js
const list = new List();
-list.addItem('First item'); // 'First item'
-list.addItem('Second item'); // 'First item', 'Second item'
-list.clear(); // -
+list.addItem();
+list.addItem();
+list.clear();
+list.getItems(); // []
```
**Since**: 0.2.0
@@ -2397,10 +2916,10 @@ The `size()` method returns the number of items in the list.
**Example**
```js
const list = new List();
-list.size(); // 0
-list.addItem('First item');
-list.addItem('Second item');
-list.size(); // 2
+list.size(); // 0
+list.addItem();
+list.addItem();
+list.size(); // 2
```
**Since**: 0.2.0
@@ -2413,21 +2932,77 @@ This class represents an item in a list.
**Since**: 0.2.0
+* [ListItem](#ListItem)
+ * [`new ListItem()`](#new_ListItem_new)
+ * [`.addHeading([text], [level])`](#ListItem+addHeading) ⇒ [Heading](#Heading)
+ * [`.addList()`](#ListItem+addList) ⇒ [List](#List)
+ * [`.addParagraph([text])`](#ListItem+addParagraph) ⇒ [Paragraph](#Paragraph)
+
+
* * *
-### `new ListItem([text])`
+### `new ListItem()`
Creates a `ListItem` instance that represents an item in a list.
+**Example**
+```js
+new ListItem();
+```
+
+* * *
+
+
+
+### `listItem.addHeading([text], [level])` ⇒ [Heading](#Heading)
+Adds a heading at the end of the list item.
+If a text is given, this will be set as text content of the heading.
+
#### Parameters
-- [text] string = "''"
-The text content of the list item; defaults to an empty string if omitted
+- [text] string
+The text content of the heading
+- [level] number = 1
+The heading level; defaults to 1 if omitted
+
+**Return value**
+[Heading](#Heading) - The newly added heading
+
+**Since**: 0.11.0
+
+* * *
+
+
+
+### `listItem.addList()` ⇒ [List](#List)
+Adds an empty list at the end of the list item.
+
+**Return value**
+[List](#List) - The newly added list
**Example**
```js
-new ListItem('First item');
+new ListItem()
+ .addList();
```
+**Since**: 0.11.0
+
+* * *
+
+
+
+### `listItem.addParagraph([text])` ⇒ [Paragraph](#Paragraph)
+Adds a paragraph at the end of the list item.
+If a text is given, this will be set as text content of the paragraph.
+
+#### Parameters
+- [text] string
+The text content of the paragraph
+
+**Return value**
+[Paragraph](#Paragraph) - The newly added paragraph
+
+**Since**: 0.11.0
* * *
diff --git a/docs/Features.md b/docs/Features.md
index 63dd36f1..2483646c 100644
--- a/docs/Features.md
+++ b/docs/Features.md
@@ -10,91 +10,95 @@
## Style
### Character
+
- Font
- - :heavy_check_mark: Family
- - :heavy_check_mark: Style
- - :heavy_check_mark: Size
- - :x: Language
+ - ✔️ Family
+ - ✔️ Style
+ - ✔️ Size
+ - ❌ Language
- Font effects
- - :heavy_check_mark: Font color
- - :heavy_check_mark: Effects
- - :x: Relief
- - :x: Overlining
- - :x: Strikethrough
- - :x: Underlining
+ - ✔️ Font color
+ - ✔️ Effects
+ - ❌ Relief
+ - ❌ Overlining
+ - ❌ Strikethrough
+ - ❌ Underlining
- Position
- - :x: Position
- - :x: Rotation & scaling
- - :x: Spacing
+ - ❌ Position
+ - ❌ Rotation & scaling
+ - ❌ Spacing
- Hyperlink
- - :x: Hyperlink
- - :x: Events
- - :x: Character Styles
+ - ❌ Hyperlink
+ - ❌ Events
+ - ❌ Character Styles
- Highlighting
- - :x: Color
+ - ❌ Color
- Borders
- - :x: Line arrangement
- - :x: Line
- - :x: Spacing to contents
- - :x: Shadow style
+ - ❌ Line arrangement
+ - ❌ Line
+ - ❌ Spacing to contents
+ - ❌ Shadow style
### Paragraph
+
- Indents & spacing
- - :heavy_check_mark: Indent
- - :heavy_check_mark: Spacing
- - :heavy_check_mark: Line spacing
+ - ✔️ Indent
+ - ✔️ Spacing
+ - ✔️ Line spacing
- Alignment
- - :heavy_check_mark: horizontal
- - :heavy_check_mark: vertical
+ - ✔️ horizontal
+ - ✔️ vertical
- Text flow
- - :x: Hyphenation
- - :heavy_check_mark: Breaks
- - :heavy_check_mark: Break control
+ - ❌ Hyphenation
+ - ✔️ Breaks
+ - ✔️ Break control
- Outline & numbering
- - :x: Outline
- - :x: Numbering
- - :x: Line numbering
+ - ❌ Outline
+ - ❌ Numbering
+ - ❌ Line numbering
- Tabs
- - :heavy_check_mark: Type
- - :construction: Fill character
+ - ✔️ Type
+ - ❌ Fill character
- Drop caps
- Borders
- - :construction: Line arrangement
- - :construction: Line
- - :heavy_check_mark: Padding
- - :x: Shadow style
+ - ❌ Line arrangement
+ - ❌ Line
+ - ✔️ Padding
+ - ❌ Shadow style
- Background
- - :heavy_check_mark: Color
- - :x: Gradient
- - :x: Hatching
- - :x: Bitmap
+ - ✔️ Color
+ - ❌ Gradient
+ - ❌ Hatching
+ - ❌ Bitmap
## Text content
-- :heavy_check_mark: Heading
-- :heavy_check_mark: Paragraph
- - :heavy_check_mark: tab
- - :heavy_check_mark: line break
- - :x: hyphen
- - :x: span
- - :construction: hyperlink
- - :x: number
-- :construction: List
-- :x: Section
-- :x: Change Tracking
-- :x: Bookmark & Reference
-- :x: Note
-- :x: Text field
-- :x: Table
-- :x: Graphic content
- - :x: Drawing shape
- - :x: Frame
- - :x: 3D Shape
-- :x: Chart
-- :x: Form
+- ✔️ Heading
+- ✔️ Paragraph
+ - ✔️ tab
+ - ✔️ line break
+ - ❌ hyphen
+ - ❌ span
+ - ❌ hyperlink
+ - ❌ number
+- ✔️ List
+ - ❌ List header
+ - ✔️ List item
+- ❌ Section
+- ❌ Change Tracking
+- ❌ Bookmark & Reference
+- ❌ Note
+- ❌ Text field
+- ❌ Table
+- ❌ Graphic content
+ - ❌ Drawing shape
+ - ❌ Frame
+ - ❌ 3D Shape
+- ❌ Chart
+- ❌ Form
diff --git a/jest.config.js b/jest.config.js
index 4a5b465e..26112d7b 100644
--- a/jest.config.js
+++ b/jest.config.js
@@ -1,4 +1,5 @@
module.exports = {
+ collectCoverage: true,
preset: 'ts-jest',
testEnvironment: 'node',
};
diff --git a/package.json b/package.json
index bac9c632..c9edbd9f 100644
--- a/package.json
+++ b/package.json
@@ -26,14 +26,14 @@
"Cain Watson"
],
"files": [
- "lib",
+ "dist",
"package.json",
"CHANGELOG.md",
"LICENSE",
"README.md"
],
- "main": "./lib/index.js",
- "types": "./lib/index.d.ts",
+ "main": "./dist/index.js",
+ "types": "./dist/index.d.ts",
"scripts": {
"build": "tsc -p .",
"preversion": "npm test",
@@ -41,13 +41,12 @@
"prepublishOnly": "npm run build",
"pretest": "npm run build",
"posttest": "npm run lint",
- "test": "jest",
- "test:watch": "jest --watch",
+ "test": "jest --clearCache && jest",
+ "test:watch": "jest --clearCache && jest --watch",
"test:coverage": "jest --coverage",
- "coverage": "jest --coverage",
"lint": "eslint './{examples,src,test}/**/*.{ts,tsx}'",
"format": "prettier --write './{examples,src,test}/**/*.{ts,js,json,md}'",
- "docs": "rm -r ./lib && tsc && jsdoc2md --name-format --param-list-format list --separators --partial ./tools/jsdoc2md/body.hbs ./tools/jsdoc2md/params-list.hbs ./tools/jsdoc2md/returns.hbs ./tools/jsdoc2md/scope.hbs --files ./lib/api/**/*.js > ./docs/API.md"
+ "docs": "rm -r ./dist && tsc && jsdoc2md --name-format --param-list-format list --separators --partial ./tools/jsdoc2md/body.hbs ./tools/jsdoc2md/params-list.hbs ./tools/jsdoc2md/returns.hbs ./tools/jsdoc2md/scope.hbs --files ./dist/api/**/*.js > ./docs/API.md"
},
"dependencies": {
"xmldom": "^0.3.0"
diff --git a/src/api/meta/Meta.spec.ts b/src/api/meta/Meta.spec.ts
index faa65fcf..1f69c844 100644
--- a/src/api/meta/Meta.spec.ts
+++ b/src/api/meta/Meta.spec.ts
@@ -58,7 +58,6 @@ describe(Meta.name, () => {
});
it('return previous set date', () => {
- console.log({ testDate });
meta.setDate(testDate);
expect(meta.getDate()).toBe(testDate);
diff --git a/src/api/office/AutomaticStyles.spec.ts b/src/api/office/AutomaticStyles.spec.ts
index f2c9d954..aaed959a 100644
--- a/src/api/office/AutomaticStyles.spec.ts
+++ b/src/api/office/AutomaticStyles.spec.ts
@@ -1,48 +1,74 @@
-import { ParagraphStyle, TabStopType } from '../style';
+import { ListStyle, ParagraphStyle, TabStopType } from '../style';
import { AutomaticStyles } from './AutomaticStyles';
describe(AutomaticStyles.name, () => {
let automaticStyles: AutomaticStyles;
- let testStyle1: ParagraphStyle;
- let testStyle2: ParagraphStyle;
+ let listStyle: ListStyle;
+ let paragraphStyle1: ParagraphStyle;
+ let paragraphStyle2: ParagraphStyle;
beforeEach(() => {
- testStyle1 = new ParagraphStyle();
- testStyle2 = new ParagraphStyle().setFontSize(23);
- testStyle2.addTabStop(42, TabStopType.Right);
+ listStyle = new ListStyle();
+ paragraphStyle1 = new ParagraphStyle();
+ paragraphStyle2 = new ParagraphStyle().setFontSize(23);
+ paragraphStyle2.addTabStop(42, TabStopType.Right);
automaticStyles = new AutomaticStyles();
});
- describe('styles', () => {
- it('add similar styles only once', () => {
- automaticStyles.add(testStyle1);
- automaticStyles.add(new ParagraphStyle());
- const styles = automaticStyles.getAll();
+ it('should add a list style and name it L1', () => {
+ automaticStyles.add(listStyle);
- expect(styles.length).toBe(1);
- expect(styles[0]).toEqual(testStyle1);
+ const styles = automaticStyles.getAll();
+ expect(styles.length).toBe(1);
+ expect(automaticStyles.getName(listStyle)).toBe('L1');
+ });
+
+ it('should add different list styles', () => {
+ const listStyle2 = new ListStyle();
+ listStyle2.setConsecutiveNumbering(true).createBulletListLevelStyle(1);
+
+ automaticStyles.add(listStyle);
+ automaticStyles.add(listStyle2);
+
+ const styles = automaticStyles.getAll();
+ expect(styles.length).toBe(2);
+ expect(automaticStyles.getName(listStyle)).toBe('L1');
+ expect(automaticStyles.getName(listStyle2)).toBe('L2');
+ });
- expect(automaticStyles.getName(testStyle1)).toBe('P1');
- });
+ it('should add a paragraph style and name it P1', () => {
+ automaticStyles.add(paragraphStyle1);
- it('add different styles', () => {
- automaticStyles.add(testStyle1);
- automaticStyles.add(testStyle2);
- const styles = automaticStyles.getAll();
+ const styles = automaticStyles.getAll();
+ expect(styles.length).toBe(1);
+ expect(automaticStyles.getName(paragraphStyle1)).toBe('P1');
+ });
+
+ it('should add different paragraph styles', () => {
+ automaticStyles.add(paragraphStyle1);
+ automaticStyles.add(paragraphStyle2);
- expect(styles.length).toBe(2);
+ const styles = automaticStyles.getAll();
+ expect(styles.length).toBe(2);
+ expect(automaticStyles.getName(paragraphStyle1)).toBe('P1');
+ expect(automaticStyles.getName(paragraphStyle2)).toBe('P2');
+ });
- expect(automaticStyles.getName(testStyle1)).toBe('P1');
- expect(automaticStyles.getName(testStyle2)).toBe('P2');
- });
+ it('should add similar styles only once', () => {
+ automaticStyles.add(paragraphStyle1);
+ automaticStyles.add(new ParagraphStyle());
+
+ const styles = automaticStyles.getAll();
+ expect(styles.length).toBe(1);
+ expect(styles[0]).toEqual(paragraphStyle1);
+ });
- it('throw if the name of an unknown style is requested', () => {
- automaticStyles.add(testStyle1);
+ it('should throw if the name of an unknown style is requested', () => {
+ automaticStyles.add(paragraphStyle1);
- expect(() => {
- automaticStyles.getName(testStyle2);
- }).toThrow();
- });
+ expect(() => {
+ automaticStyles.getName(paragraphStyle2);
+ }).toThrow();
});
});
diff --git a/src/api/office/AutomaticStyles.ts b/src/api/office/AutomaticStyles.ts
index 02c0393f..455ae0c9 100644
--- a/src/api/office/AutomaticStyles.ts
+++ b/src/api/office/AutomaticStyles.ts
@@ -1,5 +1,12 @@
-import { createHash } from 'crypto';
-import { ParagraphStyle, Style, StyleFamily } from '../style';
+import { createHash, Hash } from 'crypto';
+import {
+ BulletListLevelStyle,
+ ListStyle,
+ ParagraphStyle,
+ Style,
+} from '../style';
+import { IParagraphProperties } from '../style/IParagraphProperties';
+import { ITextProperties } from '../style/ITextProperties';
import { IStyles } from './IStyles';
type IStyleInformation = {
@@ -23,6 +30,7 @@ type IStyleInformation = {
*/
export class AutomaticStyles implements IStyles {
private styles: Map;
+ private listStyleCounter: number;
private paragraphStyleCounter: number;
/**
@@ -35,6 +43,7 @@ export class AutomaticStyles implements IStyles {
*/
public constructor() {
this.styles = new Map();
+ this.listStyleCounter = 0;
this.paragraphStyleCounter = 0;
}
@@ -63,7 +72,7 @@ export class AutomaticStyles implements IStyles {
this.styles.set(hash, {
style: style,
- name: `P${++this.paragraphStyleCounter}`,
+ name: this.createUniqueName(style),
});
}
@@ -85,13 +94,13 @@ export class AutomaticStyles implements IStyles {
*/
public getName(style: Style): string | never {
const hash = this.getHash(style);
- const styleInformation = this.styles.get(hash);
+ const existingStyle = this.styles.get(hash);
- if (styleInformation === undefined) {
+ if (existingStyle === undefined) {
throw new Error(`Unknown style [${style}}]`);
}
- return styleInformation.name;
+ return existingStyle.name;
}
/** @inheritdoc */
@@ -101,6 +110,23 @@ export class AutomaticStyles implements IStyles {
.map((styleInformation) => styleInformation.style);
}
+ /**
+ * Creates the unique name for the given style.
+ * The name follows the pattern (e.g. P2 for the second paragraph style).
+ *
+ * @param {Style} style The style for which a unique name is being requested
+ * @returns {string} The unique name representing the given style
+ */
+ private createUniqueName(style: Style): string {
+ if (style instanceof ListStyle) {
+ return `L${++this.listStyleCounter}`;
+ } else if (style instanceof ParagraphStyle) {
+ return `P${++this.paragraphStyleCounter}`;
+ }
+
+ throw new Error(`Unknown style type [${style}}]`);
+ }
+
/**
* The `getHash()` method returns a representative hash for a given style.
*
@@ -113,50 +139,115 @@ export class AutomaticStyles implements IStyles {
hash.update(style.getClass() || '');
hash.update(style.getFamily());
- if (style.getFamily() === StyleFamily.Paragraph) {
- const paragraphStyle = style as ParagraphStyle;
-
- // paragraph properties
- hash.update('background-color' + paragraphStyle.getBackgroundColor());
- hash.update('border-bottom' + paragraphStyle.getBorderBottom());
- hash.update('border-left' + paragraphStyle.getBorderLeft());
- hash.update('border-right' + paragraphStyle.getBorderRight());
- hash.update('border-top' + paragraphStyle.getBorderTop());
- hash.update(paragraphStyle.getHorizontalAlignment());
- hash.update(paragraphStyle.getHorizontalAlignmentLastLine());
- hash.update(paragraphStyle.getKeepTogether() ? 'kt' : '');
- hash.update(paragraphStyle.getKeepWithNext() ? 'kwn' : '');
- hash.update('lh' + paragraphStyle.getLineHeight());
- hash.update('lhal' + paragraphStyle.getLineHeightAtLeast());
- hash.update('ls' + paragraphStyle.getLineSpacing());
- hash.update('margin-bottom' + paragraphStyle.getMarginBottom());
- hash.update('margin-left' + paragraphStyle.getMarginLeft());
- hash.update('margin-right' + paragraphStyle.getMarginRight());
- hash.update('margin-top' + paragraphStyle.getMarginTop());
- hash.update('orphans' + paragraphStyle.getOrphans());
- hash.update('padding-bottom' + paragraphStyle.getPaddingBottom());
- hash.update('padding-left' + paragraphStyle.getPaddingLeft());
- hash.update('padding-right' + paragraphStyle.getPaddingRight());
- hash.update('padding-top' + paragraphStyle.getPaddingTop());
- hash.update(paragraphStyle.getPageBreak().toString());
- hash.update('text-indent' + paragraphStyle.getTextIndent());
- hash.update(paragraphStyle.getVerticalAlignment());
- hash.update('widows' + paragraphStyle.getWidows());
- paragraphStyle.getTabStops().forEach((tabStop) => {
- hash.update(
- `tab${tabStop.getChar()}${tabStop.getLeaderColor()}${tabStop.getLeaderStyle()}${tabStop.getPosition()}${tabStop.getType()}`
- ); // eslint-disable-line max-len
+ if (style instanceof ListStyle) {
+ hash.update('consecutive-numbering' + style.getConsecutiveNumbering());
+ style.getListLevelStyles().forEach((listLevelStyle) => {
+ this.updateHashWithListLevelStyle(hash, listLevelStyle);
});
-
- // text properties
- hash.update('color' + paragraphStyle.getColor());
- hash.update(paragraphStyle.getFontName() || '');
- hash.update(paragraphStyle.getFontSize().toString());
- hash.update(paragraphStyle.getFontVariant());
- hash.update(paragraphStyle.getTextTransformation());
- hash.update(paragraphStyle.getTypeface().toString());
+ } else if (style instanceof ParagraphStyle) {
+ this.updateHashWithParagraphProperties(hash, style);
+ this.updateHashWithTextProperties(hash, style);
}
return hash.digest('hex');
}
+
+ /**
+ * Updates the hash with the list level style.
+ *
+ * @param {Hash} hash The hash to update
+ * @param {BulletListLevelStyle} listLevelStyle The list level style to evaluate
+ */
+ private updateHashWithListLevelStyle(
+ hash: Hash,
+ listLevelStyle: BulletListLevelStyle
+ ): void {
+ const level = listLevelStyle.getLevel();
+ const properties = [
+ 'bullet-char',
+ listLevelStyle.getBulletChar(),
+ 'bullet-relative-size',
+ listLevelStyle.getRelativeBulletSize(),
+ 'num-prefix',
+ listLevelStyle.getNumberPrefix(),
+ 'num-suffix',
+ listLevelStyle.getNumberSuffix(),
+ ];
+ const listLevelProperties = [
+ 'list-level-position-and-space-mode',
+ listLevelStyle.getListLevelPositionAndSpaceMode(),
+ 'label-followed-by',
+ listLevelStyle.getLabelFollowedBy(),
+ 'list-tab-stop-position',
+ listLevelStyle.getListTabStopPosition(),
+ 'text-indent',
+ listLevelStyle.getTextIndent(),
+ 'margin-left',
+ listLevelStyle.getMarginLeft(),
+ ];
+
+ hash.update(
+ `${level}${properties.join('')}${listLevelProperties.join('')}`
+ );
+ }
+
+ /**
+ * Updates the hash with the paragraph properties.
+ *
+ * @param {Hash} hash The hash to update
+ * @param {IParagraphProperties} paragraphProperties The paragraph properties to evaluate
+ */
+ private updateHashWithParagraphProperties(
+ hash: Hash,
+ paragraphProperties: IParagraphProperties
+ ): void {
+ hash.update('background-color' + paragraphProperties.getBackgroundColor());
+ hash.update('border-bottom' + paragraphProperties.getBorderBottom());
+ hash.update('border-left' + paragraphProperties.getBorderLeft());
+ hash.update('border-right' + paragraphProperties.getBorderRight());
+ hash.update('border-top' + paragraphProperties.getBorderTop());
+ hash.update(paragraphProperties.getHorizontalAlignment());
+ hash.update(paragraphProperties.getHorizontalAlignmentLastLine());
+ hash.update(paragraphProperties.getKeepTogether() ? 'kt' : '');
+ hash.update(paragraphProperties.getKeepWithNext() ? 'kwn' : '');
+ hash.update('lh' + paragraphProperties.getLineHeight());
+ hash.update('lhal' + paragraphProperties.getLineHeightAtLeast());
+ hash.update('ls' + paragraphProperties.getLineSpacing());
+ hash.update('margin-bottom' + paragraphProperties.getMarginBottom());
+ hash.update('margin-left' + paragraphProperties.getMarginLeft());
+ hash.update('margin-right' + paragraphProperties.getMarginRight());
+ hash.update('margin-top' + paragraphProperties.getMarginTop());
+ hash.update('orphans' + paragraphProperties.getOrphans());
+ hash.update('padding-bottom' + paragraphProperties.getPaddingBottom());
+ hash.update('padding-left' + paragraphProperties.getPaddingLeft());
+ hash.update('padding-right' + paragraphProperties.getPaddingRight());
+ hash.update('padding-top' + paragraphProperties.getPaddingTop());
+ hash.update(paragraphProperties.getPageBreak().toString());
+ hash.update('text-indent' + paragraphProperties.getTextIndent());
+ hash.update(paragraphProperties.getVerticalAlignment());
+ hash.update('widows' + paragraphProperties.getWidows());
+ paragraphProperties.getTabStops().forEach((tabStop) => {
+ hash.update(
+ `tab${tabStop.getChar()}${tabStop.getLeaderColor()}${tabStop.getLeaderStyle()}${tabStop.getPosition()}${tabStop.getType()}`
+ );
+ });
+ }
+
+ /**
+ * Updates the hash with the text properties.
+ *
+ * @param {Hash} hash The hash to update
+ * @param {ITextProperties} textProperties The text properties to evaluate
+ */
+ private updateHashWithTextProperties(
+ hash: Hash,
+ textProperties: ITextProperties
+ ): void {
+ hash.update('color' + textProperties.getColor());
+ hash.update(textProperties.getFontName() || '');
+ hash.update(textProperties.getFontSize().toString());
+ hash.update(textProperties.getFontVariant());
+ hash.update(textProperties.getTextTransformation());
+ hash.update(textProperties.getTypeface().toString());
+ }
}
diff --git a/src/api/office/CommonStyles.spec.ts b/src/api/office/CommonStyles.spec.ts
index 1ad7b4ee..1717c4df 100644
--- a/src/api/office/CommonStyles.spec.ts
+++ b/src/api/office/CommonStyles.spec.ts
@@ -1,4 +1,4 @@
-import { ParagraphStyle } from '../style';
+import { ListStyle, ParagraphStyle } from '../style';
import { CommonStyles } from './CommonStyles';
describe(CommonStyles.name, () => {
@@ -10,40 +10,52 @@ describe(CommonStyles.name, () => {
commonStyles = new CommonStyles();
});
- describe('styles', () => {
- it('create a style only once', () => {
- const style1 = commonStyles.createParagraphStyle(testStyleName);
- const style2 = commonStyles.createParagraphStyle(testStyleName);
- const styles = commonStyles.getAll();
+ it('should create and return a new list style', () => {
+ const style = commonStyles.createListStyle(testStyleName);
- expect(style1).toBe(style2);
- expect(styles.length).toBe(1);
- expect(styles[0]).toBe(style1);
- });
+ expect(style).toBeInstanceOf(ListStyle);
+ expect(style.getDisplayName()).toBe(testStyleName);
+ });
+
+ it('should create a list style only once', () => {
+ const style1 = commonStyles.createListStyle(testStyleName);
+ const style2 = commonStyles.createListStyle(testStyleName);
+ const styles = commonStyles.getAll();
+
+ expect(style1).toBe(style2);
+ expect(styles.length).toBe(1);
+ expect(styles[0]).toBe(style1);
+ });
- it('get name of previously created style', () => {
- const style = commonStyles.createParagraphStyle(testStyleName);
- const styleName = commonStyles.getName(testStyleName);
+ it('should create and return a new paragraph style', () => {
+ const style = commonStyles.createParagraphStyle(testStyleName);
- expect(styleName).toBe(style.getName());
- });
+ expect(style).toBeInstanceOf(ParagraphStyle);
+ expect(style.getDisplayName()).toBe(testStyleName);
+ });
+
+ it('should create a paragraph style only once', () => {
+ const style1 = commonStyles.createParagraphStyle(testStyleName);
+ const style2 = commonStyles.createParagraphStyle(testStyleName);
+ const styles = commonStyles.getAll();
- it('return undefined if unknown style is requested', () => {
- commonStyles.createParagraphStyle(testStyleName);
+ expect(style1).toBe(style2);
+ expect(styles.length).toBe(1);
+ expect(styles[0]).toBe(style1);
+ });
- const styleName = commonStyles.getName('unknownStyleName');
+ it('should return the name of previously created style', () => {
+ const style = commonStyles.createParagraphStyle(testStyleName);
+ const styleName = commonStyles.getName(testStyleName);
- expect(styleName).toBeUndefined();
- });
+ expect(styleName).toBe(style.getName());
});
- describe('paragraph style', () => {
- it('create and return a new paragraph style', () => {
- const style = commonStyles.createParagraphStyle(testStyleName);
+ it('should return undefined if the name of an unknown style is requested', () => {
+ commonStyles.createParagraphStyle(testStyleName);
+
+ const styleName = commonStyles.getName('unknownStyleName');
- expect(style).toBeInstanceOf(ParagraphStyle);
- expect(style.getDisplayName()).toBe(testStyleName);
- expect(style.getFamily()).toBe('paragraph');
- });
+ expect(styleName).toBeUndefined();
});
});
diff --git a/src/api/office/CommonStyles.ts b/src/api/office/CommonStyles.ts
index b9295180..8e79676a 100644
--- a/src/api/office/CommonStyles.ts
+++ b/src/api/office/CommonStyles.ts
@@ -1,4 +1,4 @@
-import { ParagraphStyle, Style } from '../style';
+import { ListStyle, ParagraphStyle, Style } from '../style';
import { IStyles } from './IStyles';
/**
@@ -27,6 +27,31 @@ export class CommonStyles implements IStyles {
this.styles = new Map();
}
+ /**
+ * The `createListStyle()` method creates a new `ListStyle` instance with the given name.
+ * If a style with this name already exists, the existing style will be returned.
+ *
+ * @example
+ * const commonStyles = new CommonStyles();
+ * commonStyles.createListStyle('Contents');
+ *
+ * @param {string} name The unique name for the style
+ * @returns {ListStyle} A new `ListStyle` instance with the specified name or an existing style, if one with the specified name exists
+ * @since 0.11.0
+ */
+ public createListStyle(name: string): ListStyle {
+ const existingStyle = this.styles.get(name);
+
+ if (existingStyle !== undefined) {
+ return existingStyle as ListStyle;
+ }
+
+ const newStyle = new ListStyle(name);
+ this.styles.set(name, newStyle);
+
+ return newStyle;
+ }
+
/**
* The `createParagraphStyle()` method creates a new `ParagraphStyle` instance with the given name.
* If a style with this name already exists, the existing style will be returned.
@@ -41,16 +66,16 @@ export class CommonStyles implements IStyles {
* @since 0.9.0
*/
public createParagraphStyle(name: string): ParagraphStyle {
- let style = this.styles.get(name);
+ const existingStyle = this.styles.get(name);
- if (style !== undefined) {
- return style as ParagraphStyle;
+ if (existingStyle !== undefined) {
+ return existingStyle as ParagraphStyle;
}
- style = new ParagraphStyle(name);
- this.styles.set(name, style);
+ const newStyle = new ParagraphStyle(name);
+ this.styles.set(name, newStyle);
- return style as ParagraphStyle;
+ return newStyle;
}
/**
diff --git a/src/api/style/BulletListLevelStyle.spec.ts b/src/api/style/BulletListLevelStyle.spec.ts
new file mode 100644
index 00000000..84c30907
--- /dev/null
+++ b/src/api/style/BulletListLevelStyle.spec.ts
@@ -0,0 +1,99 @@
+import { BulletListLevelStyle } from './BulletListLevelStyle';
+
+describe(BulletListLevelStyle.name, () => {
+ const level = 3;
+ const prefixOrSuffix = '§';
+ const relativeBulletSize = '23%';
+
+ let bulletListLevelStyle: BulletListLevelStyle;
+
+ beforeEach(() => {
+ bulletListLevelStyle = new BulletListLevelStyle(level);
+ });
+
+ it('should return initial bullet character', () => {
+ expect(bulletListLevelStyle.getBulletChar()).toBe('\u2022');
+ });
+
+ it('should return previously set bullet character', () => {
+ bulletListLevelStyle.setBulletChar('\u2714');
+
+ expect(bulletListLevelStyle.getBulletChar()).toBe('\u2714');
+ });
+
+ it('should ignore empty bullet character', () => {
+ bulletListLevelStyle.setBulletChar('');
+
+ expect(bulletListLevelStyle.getBulletChar()).toBe('\u2022');
+ });
+
+ it('should return initial level', () => {
+ expect(bulletListLevelStyle.getLevel()).toBe(level);
+ });
+
+ it('should have no number prefix by default', () => {
+ expect(bulletListLevelStyle.getNumberPrefix()).toBeUndefined();
+ });
+
+ it('should return previously set number prefix', () => {
+ bulletListLevelStyle.setNumberPrefix(prefixOrSuffix);
+
+ expect(bulletListLevelStyle.getNumberPrefix()).toBe(prefixOrSuffix);
+ });
+
+ it('should reset previously set number prefix', () => {
+ bulletListLevelStyle.setNumberPrefix(prefixOrSuffix);
+
+ bulletListLevelStyle.setNumberPrefix(undefined);
+
+ expect(bulletListLevelStyle.getNumberPrefix()).toBeUndefined();
+ });
+
+ it('should have no number suffix by default', () => {
+ expect(bulletListLevelStyle.getNumberSuffix()).toBeUndefined();
+ });
+
+ it('should return previously set number suffix', () => {
+ bulletListLevelStyle.setNumberSuffix(prefixOrSuffix);
+
+ expect(bulletListLevelStyle.getNumberSuffix()).toBe(prefixOrSuffix);
+ });
+
+ it('should reset previously set number suffix', () => {
+ bulletListLevelStyle.setNumberSuffix(prefixOrSuffix);
+
+ bulletListLevelStyle.setNumberSuffix(undefined);
+
+ expect(bulletListLevelStyle.getNumberSuffix()).toBeUndefined();
+ });
+
+ it('should have no relative bullet size by default', () => {
+ expect(bulletListLevelStyle.getRelativeBulletSize()).toBeUndefined();
+ });
+
+ it('should return previously set relative bullet size', () => {
+ bulletListLevelStyle.setRelativeBulletSize(relativeBulletSize);
+
+ expect(bulletListLevelStyle.getRelativeBulletSize()).toBe(
+ relativeBulletSize
+ );
+ });
+
+ it('should reset previously set relative bullet size', () => {
+ bulletListLevelStyle.setRelativeBulletSize(relativeBulletSize);
+
+ bulletListLevelStyle.setRelativeBulletSize(undefined);
+
+ expect(bulletListLevelStyle.getRelativeBulletSize()).toBeUndefined();
+ });
+
+ it('should ignore invalid values for relative bullet size', () => {
+ bulletListLevelStyle.setRelativeBulletSize(relativeBulletSize);
+
+ bulletListLevelStyle.setRelativeBulletSize('42px');
+
+ expect(bulletListLevelStyle.getRelativeBulletSize()).toBe(
+ relativeBulletSize
+ );
+ });
+});
diff --git a/src/api/style/BulletListLevelStyle.ts b/src/api/style/BulletListLevelStyle.ts
new file mode 100644
index 00000000..e08c465b
--- /dev/null
+++ b/src/api/style/BulletListLevelStyle.ts
@@ -0,0 +1,296 @@
+import { isPercent } from '../util';
+import { IListLevelProperties } from './IListLevelProperties';
+import { ListLevelProperties } from './ListLevelProperties';
+
+const DEFAULT_BULLET_CHAR = '\u2022';
+
+/**
+ * This class represents a list style where list items are preceded by bullets.
+ *
+ * @example
+ * document.getStyleManager()
+ * .createListStyle('Contents')
+ * .createBulletListLevelStyle(3);
+ *
+ * @since 0.11.0
+ */
+export class BulletListLevelStyle implements IListLevelProperties {
+ private bulletChar: string;
+ private bulletRelativeSize: string | undefined;
+ private level: number; // for all list level styles, regardless of the type
+ private numPrefix: string | undefined;
+ private numSuffix: string | undefined;
+
+ private listLevelProperties: IListLevelProperties;
+
+ /**
+ * Creates a `BulletListLevelStyle` instance that represents a list style where list items are preceded by bullets.
+ *
+ * @example
+ * const style = new BulletListLevelStyle(3);
+ *
+ * @param {number} level The level of the list style, starting with `1`
+ *
+ * @since 0.11.0
+ */
+ public constructor(level: number) {
+ this.bulletChar = DEFAULT_BULLET_CHAR;
+ this.level = level;
+
+ this.listLevelProperties = new ListLevelProperties();
+ }
+
+ /**
+ * The `getBulletChar()` method returns the character to use as the bullet.
+ *
+ * @example
+ * const style = new BulletListLevelStyle(3);
+ * style.getBulletChar(); // '\u2022'
+ * style.setBulletChar('~');
+ * style.getBulletChar(); // '~'
+ *
+ * @returns {string} The character to use as the bullet
+ * @since 0.11.0
+ */
+ public getBulletChar(): string {
+ return this.bulletChar;
+ }
+
+ /**
+ * The `setBulletChar()` method sets the character to use as the bullet.
+ *
+ * If an illegal value is provided, the value will be ignored.
+ *
+ * @example
+ * const style = new BulletListLevelStyle(3);
+ * style.setBulletChar('~'); // '~'
+ * style.setBulletChar(''); // '~'
+ *
+ * @param {string} bulletChar The character to use as the bullet
+ * @returns {BulletListLevelStyle} The `BulletListLevelStyle` object
+ * @since 0.11.0
+ */
+ public setBulletChar(bulletChar: string): BulletListLevelStyle {
+ this.bulletChar = bulletChar.trim().charAt(0) || this.bulletChar;
+
+ return this;
+ }
+
+ /**
+ * The `getLevel()` method returns the level of the list style.
+ *
+ * @example
+ * const style = new BulletListLevelStyle(3);
+ * style.getLevel(); // 3
+ *
+ * @returns {number} The level of the list style, starting with `1`
+ * @since 0.11.0
+ */
+ public getLevel(): number {
+ return this.level;
+ }
+
+ /**
+ * The `getNumberPrefix()` method returns the character to display before a bullet.
+ *
+ * @example
+ * const style = new BulletListLevelStyle(3);
+ * style.getNumberPrefix(); // undefined
+ * style.setNumberPrefix('~');
+ * style.getNumberPrefix(); // '~'
+ *
+ * @returns {string | undefined} The character to display before a bullet or `undefined` if no prefix is set
+ * @since 0.11.0
+ */
+ public getNumberPrefix(): string | undefined {
+ return this.numPrefix;
+ }
+
+ /**
+ * The `setNumberPrefix()` method sets the character to display before a bullet.
+ *
+ * @example
+ * const style = new BulletListLevelStyle(3);
+ * style.setNumberPrefix('~'); // '~'
+ * style.setNumberPrefix(undefined); // undefined
+ *
+ * @param {string | undefined} prefix The character to display before a bullet or `undefined` to unset the prefix
+ * @returns {BulletListLevelStyle} The `BulletListLevelStyle` object
+ * @since 0.11.0
+ */
+ public setNumberPrefix(prefix: string | undefined): this {
+ this.numPrefix = prefix;
+
+ return this;
+ }
+
+ /**
+ * The `getNumberSuffix()` method returns the character to display after a bullet.
+ *
+ * @example
+ * const style = new BulletListLevelStyle(3);
+ * style.getNumberSuffix(); // undefined
+ * style.setNumberSuffix('~');
+ * style.getNumberSuffix(); // '~'
+ *
+ * @returns {string | undefined} The character to display after a bullet or `undefined` if no suffix is set
+ * @since 0.11.0
+ */
+ public getNumberSuffix(): string | undefined {
+ return this.numSuffix;
+ }
+
+ /**
+ * The `setNumberSuffix()` method sets the character to display after a bullet.
+ *
+ * @example
+ * const style = new BulletListLevelStyle(3);
+ * style.setNumberSuffix('~'); // '~'
+ * style.setNumberSuffix(undefined); // undefined
+ *
+ * @param {string | undefined} suffix The character to display after a bullet or `undefined` to unset the suffix
+ * @returns {BulletListLevelStyle} The `BulletListLevelStyle` object
+ * @since 0.11.0
+ */
+ public setNumberSuffix(suffix: string | undefined): this {
+ this.numSuffix = suffix;
+
+ return this;
+ }
+
+ /**
+ * The `getRelativeBulletSize()` method returns the percentage value for the bullet size relative to the font size of the paragraphs in the bullet list.
+ *
+ * @example
+ * const style = new BulletListLevelStyle(3);
+ * style.getRelativeBulletSize(); // undefined
+ * style.setRelativeBulletSize('23%');
+ * style.getRelativeBulletSize(); // '23%'
+ *
+ * @returns {string | undefined} The percentage value for the bullet size or `undefined` if no relative bullet size is set
+ * @since 0.11.0
+ */
+ public getRelativeBulletSize(): string | undefined {
+ return this.bulletRelativeSize;
+ }
+
+ /**
+ * The `setNumberSuffix()` method sets the percentage value for the bullet size relative to the font size of the paragraphs in the bullet list.
+ *
+ * If an illegal value is provided, the value will be ignored.
+ *
+ * @example
+ * const style = new BulletListLevelStyle(3);
+ * style.setRelativeBulletSize('23%'); // '23%'
+ * style.setRelativeBulletSize('42px'); // '23%'
+ * style.setRelativeBulletSize(undefined); // undefined
+ *
+ * @param {string | undefined} relativeSize The percentage value for the bullet size or `undefined` to unset the bullet size
+ * @returns {BulletListLevelStyle} The `BulletListLevelStyle` object
+ * @since 0.11.0
+ */
+ public setRelativeBulletSize(
+ relativeSize: string | undefined
+ ): BulletListLevelStyle {
+ if (relativeSize === undefined || isPercent(relativeSize)) {
+ this.bulletRelativeSize = relativeSize;
+ }
+
+ return this;
+ }
+
+ // ListLevelProperties
+ /** @inheritdoc */
+ /* istanbul ignore next */
+ public getListLevelPositionAndSpaceMode(): string {
+ return this.listLevelProperties.getListLevelPositionAndSpaceMode();
+ }
+
+ /** @inheritdoc */
+ /* istanbul ignore next */
+ public getLabelFollowedBy(): string {
+ return this.listLevelProperties.getLabelFollowedBy();
+ }
+
+ /** @inheritdoc */
+ /* istanbul ignore next */
+ public setLabelFollowedBy(value: 'listtab' | 'space' | 'nothing'): this {
+ this.listLevelProperties.setLabelFollowedBy(value);
+
+ return this;
+ }
+
+ /** @inheritdoc */
+ /* istanbul ignore next */
+ public getListTabStopPosition(): number | undefined {
+ return this.listLevelProperties.getListTabStopPosition();
+ }
+
+ /** @inheritdoc */
+ /* istanbul ignore next */
+ public setListTabStopPosition(position: number | undefined): this {
+ this.listLevelProperties.setListTabStopPosition(position);
+
+ return this;
+ }
+
+ /** @inheritdoc */
+ /* istanbul ignore next */
+ public getTextIndent(): number | undefined {
+ return this.listLevelProperties.getTextIndent();
+ }
+
+ /** @inheritdoc */
+ /* istanbul ignore next */
+ public setTextIndent(indent: number | undefined): this {
+ this.listLevelProperties.setTextIndent(indent);
+
+ return this;
+ }
+
+ /** @inheritdoc */
+ /* istanbul ignore next */
+ public getMarginLeft(): number | undefined {
+ return this.listLevelProperties.getMarginLeft();
+ }
+
+ /** @inheritdoc */
+ /* istanbul ignore next */
+ public setMarginLeft(margin: number | undefined): this {
+ this.listLevelProperties.setMarginLeft(margin);
+
+ return this;
+ }
+}
+
+/*
+
+