From 7a70937527f3ea1473de35bb00bf0a35c1e8740c Mon Sep 17 00:00:00 2001 From: eidng8 Date: Mon, 25 May 2020 11:15:32 +0800 Subject: [PATCH 1/6] add document --- .gitignore | 1 - .npmignore | 1 + docs/inputs/input-encoding.md | 15 ++++ docs/inputs/input-name.md | 15 ++++ docs/menus/node-menu.md | 10 +++ docs/popup/popup-attribute.md | 16 ++++ docs/popup/popup-box.md | 25 ++++++ docs/popup/popup-declaration.md | 16 ++++ docs/popup/popup-node.md | 16 ++++ docs/xml-edit.md | 30 +++++++ src/components/inputs/input-encoding.vue | 23 ++++- src/components/inputs/input-name.vue | 21 ++++- src/components/menus/node-menu.vue | 18 ++++ src/components/popup/popup-attribute.vue | 35 ++++++-- src/components/popup/popup-box.vue | 40 ++++++++- src/components/popup/popup-declaration.vue | 49 ++++++++-- src/components/popup/popup-node.vue | 66 ++++++++++++-- src/components/xml-edit.vue | 100 +++++++++++++++------ src/styles/index.scss | 4 +- src/types/events.ts | 2 + 20 files changed, 442 insertions(+), 61 deletions(-) create mode 100644 .npmignore create mode 100644 docs/inputs/input-encoding.md create mode 100644 docs/inputs/input-name.md create mode 100644 docs/menus/node-menu.md create mode 100644 docs/popup/popup-attribute.md create mode 100644 docs/popup/popup-box.md create mode 100644 docs/popup/popup-declaration.md create mode 100644 docs/popup/popup-node.md create mode 100644 docs/xml-edit.md diff --git a/.gitignore b/.gitignore index f596e2f..c192f1f 100644 --- a/.gitignore +++ b/.gitignore @@ -1,6 +1,5 @@ /release /dist -/docs /lib /tests/e2e/reports diff --git a/.npmignore b/.npmignore new file mode 100644 index 0000000..2f88269 --- /dev/null +++ b/.npmignore @@ -0,0 +1 @@ +/docs diff --git a/docs/inputs/input-encoding.md b/docs/inputs/input-encoding.md new file mode 100644 index 0000000..24b3b9a --- /dev/null +++ b/docs/inputs/input-encoding.md @@ -0,0 +1,15 @@ +# input-encoding + +> An HTML input field for entering character encoding. It uses [iconv-lite](https://www.npmjs.com/package/iconv-lite) to validate the input. + +## Props + +| Prop name | Description | Type | Values | Default | +| --------- | ------------- | ------------ | ------ | ------- | +| value | Input's value | XmlAttribute | - | | + +## Events + +| Event name | Type | Description | +| ---------- | ---------- | ---------------------------------- | +| input | InputEvent | Emitted when there is valid input. | diff --git a/docs/inputs/input-name.md b/docs/inputs/input-name.md new file mode 100644 index 0000000..1287df2 --- /dev/null +++ b/docs/inputs/input-name.md @@ -0,0 +1,15 @@ +# input-name + +> An HTML input field for entering XML tag name. It uses [XRegExp](http://xregexp.com/) to validate the input. + +## Props + +| Prop name | Description | Type | Values | Default | +| --------- | ------------- | ----- | ------ | ------- | +| node | Input's value | union | - | | + +## Events + +| Event name | Type | Description | +| ---------- | ---------- | ---------------------------------- | +| input | InputEvent | Emitted when there is valid input. | diff --git a/docs/menus/node-menu.md b/docs/menus/node-menu.md new file mode 100644 index 0000000..209d2fb --- /dev/null +++ b/docs/menus/node-menu.md @@ -0,0 +1,10 @@ +# node-menu + +> Generate menu for a tree node. + +## Events + +| Event name | Type | Description | +| ---------- | ------------- | ----------------------------------------- | +| select | G8MenuItem | Emitted when a menu item has be selected. | +| menu-open | MenuOpenEvent | diff --git a/docs/popup/popup-attribute.md b/docs/popup/popup-attribute.md new file mode 100644 index 0000000..1f69508 --- /dev/null +++ b/docs/popup/popup-attribute.md @@ -0,0 +1,16 @@ +# popup-attribute + +> Popup box for editing attribute. + +## Props + +| Prop name | Description | Type | Values | Default | +| --------- | --------------- | ------------ | ------ | ------- | +| attribute | Attribute value | XmlAttribute | - | | + +## Events + +| Event name | Type | Description | +| ---------- | ------------------ | ----------------------------------- | +| save | SaveNodePopupEvent | The `save` button has been pressed. | +| close | UIEvent | The popup has been closed. | diff --git a/docs/popup/popup-box.md b/docs/popup/popup-box.md new file mode 100644 index 0000000..501e296 --- /dev/null +++ b/docs/popup/popup-box.md @@ -0,0 +1,25 @@ +# popup-box + +> Popup box + +## Props + +| Prop name | Description | Type | Values | Default | +| --- | --- | --- | --- | --- | +| message | Message to be shown in the popup box. | string | - | | +| messageHint | Message tooltip to the popup box message. | string | - | | + +## Events + +| Event name | Type | Description | +| ---------- | ------------------ | ----------------------------------- | +| close | UIEvent | The popup has been closed. | +| save | SaveNodePopupEvent | The `save` button has been pressed. | + +## Slots + +| Name | Description | Bindings | +| ------- | ----------- | -------- | +| title | | | +| default | | | +| footer | | | diff --git a/docs/popup/popup-declaration.md b/docs/popup/popup-declaration.md new file mode 100644 index 0000000..f295aa1 --- /dev/null +++ b/docs/popup/popup-declaration.md @@ -0,0 +1,16 @@ +# popup-declaration + +> Popup box for editing XML declaration. + +## Props + +| Prop name | Description | Type | Values | Default | +| --------- | ---------------------- | -------------- | ------ | ------- | +| node | The node to be edited. | XmlDeclaration | - | | + +## Events + +| Event name | Type | Description | +| ---------- | --------- | --------------------------------------------------- | +| save | undefined | The node passed in the `data` field shall be saved. | +| close | UIEvent | The popup has been closed. | diff --git a/docs/popup/popup-node.md b/docs/popup/popup-node.md new file mode 100644 index 0000000..27bccdf --- /dev/null +++ b/docs/popup/popup-node.md @@ -0,0 +1,16 @@ +# popup-node + +> Popup box for editing XML node. + +## Props + +| Prop name | Description | Type | Values | Default | +| --------- | ---------------------- | ------- | ------ | ------- | +| node | The node to be edited. | XmlNode | - | | + +## Events + +| Event name | Type | Description | +| --- | --- | --- | +| save | SaveNodePopupEvent | The node passed in the `data` field shall be saved. | +| close | UIEvent | The popup has been closed. | diff --git a/docs/xml-edit.md b/docs/xml-edit.md new file mode 100644 index 0000000..43f7502 --- /dev/null +++ b/docs/xml-edit.md @@ -0,0 +1,30 @@ +# g8-xml-edit + +> Presents an XML document in tree view for editing. + +## Props + +| Prop name | Description | Type | Values | Default | +| --- | --- | --- | --- | --- | +| showAttrValue | Whether to show attribute value in tree item badges. | boolean | - | false | +| piUseAttribute | Set to `false` to treat processing instruction as text;
or `true` to facilitate attributes. | boolean | - | false | +| xml | Input XML content. This component doesn't mutate the input XML content. | string | - | | + +## Events + +| Event name | Type | Description | +| --- | --- | --- | +| menu-open | MenuOpenEvent | A menu item has been selected. | +| default-declaration | DefaultDeclarationEvent | Emitted when the input XML document doesn't have declaration. | +| xml-reload | XmlReloadEvent | Emits when XML document has been reloaded. The `detail.document` field
holds the newly loaded XML object.
Please note that this event is fired only when {@see reloadXml} is
called. Changing the {@see xml} property will _not_ trigger this event. | +| select-node | SelectNodeEvent | Emitted when a node in the tree view has been selected. | +| edit-node | EditNodeEvent | A node is about to be edited. | +| save-node | SaveNodeEvent | A node is about to be saved. | +| declaration-changed | DeclarationChangedEvent | The XML declaration has been changed. | +| node-changed | NodeChangedEvent | An XML node has been changed. | +| node-created | NodeCreatedEvent | A new XML node has been created. | +| edit-attribute | EditAttributeEvent | An attribute is about to be edited. | +| save-attribute | SaveAttributeEvent | An attribute is about to be saved. | +| attribute-changed | AttributeChangedEvent | A XML node attribute has been changed. | +| delete-node | DeleteNodeEvent | A node is about to be deleted. | +| node-removed | NodeRemovedEvent | A new XML node has been deleted. | diff --git a/src/components/inputs/input-encoding.vue b/src/components/inputs/input-encoding.vue index e0432c1..f360461 100644 --- a/src/components/inputs/input-encoding.vue +++ b/src/components/inputs/input-encoding.vue @@ -18,15 +18,34 @@ import { Component, Prop, Vue } from 'vue-property-decorator'; import { getTexts } from '../../translations/translation'; import { XmlAttribute } from '../../types/types'; +/** + * An HTML input field for entering character encoding. It uses + * [iconv-lite](https://www.npmjs.com/package/iconv-lite) to + * validate the input. + */ @Component({ name: 'input-encoding' }) export default class InputEncoding extends Vue { + /** + * Input's value + */ @Prop() private value!: XmlAttribute; + /** + * Text translations + */ private texts = getTexts(); - private validate(evt: InputEvent): void { + /** + * Validates the input value, and reports validity error if invalid. + * @param event + */ + private validate(event: InputEvent): void { if (encodingExists(this.value.value!)) { - this.$emit('input', evt); + /** + * Emitted when there is valid input. + * @type {InputEvent} + */ + this.$emit('input', event); (this.$el as HTMLInputElement).setCustomValidity(''); return; } diff --git a/src/components/inputs/input-name.vue b/src/components/inputs/input-name.vue index c57bc30..8de7730 100644 --- a/src/components/inputs/input-name.vue +++ b/src/components/inputs/input-name.vue @@ -18,17 +18,34 @@ import { Component, Prop, Vue } from 'vue-property-decorator'; import { getTexts } from '../../translations/translation'; import { XmlAttribute, XmlElement, XmlInstruction } from '../../types/types'; +/** + * An HTML input field for entering XML tag name. It uses + * [XRegExp](http://xregexp.com/) to validate the input. + */ @Component({ name: 'input-name' }) export default class InputName extends Vue { + /** + * Input's value + */ @Prop() private node!: XmlElement | XmlInstruction | XmlAttribute; + /** + * Text translations + */ private texts = getTexts(); + /** + * Regular expression to validate value + */ private regex = XRegExp('^[_\\p{L}][-_:\\d\\p{L}]*$', 'nu'); - private validate(evt: InputEvent): void { + private validate(event: InputEvent): void { if (this.regex.test(this.node.name)) { - this.$emit('input', evt); + /** + * Emitted when there is valid input. + * @type {InputEvent} + */ + this.$emit('input', event); (this.$el as HTMLInputElement).setCustomValidity(''); return; } diff --git a/src/components/menus/node-menu.vue b/src/components/menus/node-menu.vue index 35e17e0..efc4689 100644 --- a/src/components/menus/node-menu.vue +++ b/src/components/menus/node-menu.vue @@ -5,6 +5,11 @@ -->