@omicronenergy/oscd-shell 0.0.5 → 0.0.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (127) hide show
  1. package/dist/foundation/cyrb64.d.ts +6 -0
  2. package/dist/foundation/cyrb64.js +26 -0
  3. package/dist/foundation/cyrb64.js.map +1 -0
  4. package/dist/foundation.d.ts +1 -0
  5. package/dist/foundation.js +2 -0
  6. package/dist/foundation.js.map +1 -0
  7. package/dist/locales/de.d.ts +10 -0
  8. package/dist/locales/de.js +15 -0
  9. package/dist/locales/de.js.map +1 -0
  10. package/dist/locales.d.ts +13 -0
  11. package/dist/locales.js +21 -0
  12. package/dist/locales.js.map +1 -0
  13. package/dist/oscd-shell.d.ts +119 -0
  14. package/dist/oscd-shell.js +685 -0
  15. package/dist/oscd-shell.js.map +1 -0
  16. package/dist/utils/plugin-utils.d.ts +29 -0
  17. package/dist/utils/plugin-utils.js +138 -0
  18. package/dist/utils/plugin-utils.js.map +1 -0
  19. package/dist/utils/plugin-utils.spec.d.ts +1 -0
  20. package/dist/utils/plugin-utils.spec.js +115 -0
  21. package/dist/utils/plugin-utils.spec.js.map +1 -0
  22. package/package.json +40 -35
  23. package/.editorconfig +0 -22
  24. package/.github/actions/setup-node-env/action.yml +0 -49
  25. package/.github/workflows/release-please.yml +0 -84
  26. package/.github/workflows/test.yml +0 -18
  27. package/.github/workflows/update-screenshots.yml +0 -29
  28. package/.husky/commit-msg +0 -1
  29. package/.husky/pre-commit +0 -1
  30. package/.release-please-manifest.json +0 -1
  31. package/CHANGELOG.md +0 -73
  32. package/CONTRIBUTING.md +0 -393
  33. package/commitlint.config.js +0 -1
  34. package/demo/AddPlugins.js +0 -42
  35. package/demo/DemoPluginSrc.js +0 -9
  36. package/demo/embedded.html +0 -17
  37. package/demo/index.html +0 -95
  38. package/foundation/cyrb64.ts +0 -27
  39. package/foundation/edit-event.ts +0 -273
  40. package/foundation/open-event.ts +0 -21
  41. package/foundation.ts +0 -28
  42. package/lit-localize.json +0 -15
  43. package/localization/de.xlf +0 -75
  44. package/oscd-shell.editing.spec.ts +0 -813
  45. package/oscd-shell.plugging.spec.ts +0 -78
  46. package/oscd-shell.spec.ts +0 -431
  47. package/oscd-shell.test.ts +0 -382
  48. package/oscd-shell.ts +0 -906
  49. package/release-please-config.json +0 -21
  50. package/rollup.config.js +0 -51
  51. package/screenshots/Chromium/baseline/app-bar-de.png +0 -0
  52. package/screenshots/Chromium/baseline/app-bar-en.png +0 -0
  53. package/screenshots/Chromium/baseline/document-name-de.png +0 -0
  54. package/screenshots/Chromium/baseline/document-name-en.png +0 -0
  55. package/screenshots/Chromium/baseline/editor-plugins-de.png +0 -0
  56. package/screenshots/Chromium/baseline/editor-plugins-en.png +0 -0
  57. package/screenshots/Chromium/baseline/editor-plugins-selected-de.png +0 -0
  58. package/screenshots/Chromium/baseline/editor-plugins-selected-en.png +0 -0
  59. package/screenshots/Chromium/baseline/editor-plugins-with-doc-de.png +0 -0
  60. package/screenshots/Chromium/baseline/editor-plugins-with-doc-en.png +0 -0
  61. package/screenshots/Chromium/baseline/log-entries-de.png +0 -0
  62. package/screenshots/Chromium/baseline/log-entries-en.png +0 -0
  63. package/screenshots/Chromium/baseline/log-entries-redone-de.png +0 -0
  64. package/screenshots/Chromium/baseline/log-entries-redone-en.png +0 -0
  65. package/screenshots/Chromium/baseline/log-entries-undone-de.png +0 -0
  66. package/screenshots/Chromium/baseline/log-entries-undone-en.png +0 -0
  67. package/screenshots/Chromium/baseline/log-screen-de.png +0 -0
  68. package/screenshots/Chromium/baseline/log-screen-en.png +0 -0
  69. package/screenshots/Chromium/baseline/menu-drawer-de.png +0 -0
  70. package/screenshots/Chromium/baseline/menu-drawer-en.png +0 -0
  71. package/screenshots/Chromium/baseline/menu-plugins-de.png +0 -0
  72. package/screenshots/Chromium/baseline/menu-plugins-en.png +0 -0
  73. package/screenshots/Chromium/baseline/menu-plugins-triggered-de.png +0 -0
  74. package/screenshots/Chromium/baseline/menu-plugins-triggered-en.png +0 -0
  75. package/screenshots/Firefox/baseline/app-bar-de.png +0 -0
  76. package/screenshots/Firefox/baseline/app-bar-en.png +0 -0
  77. package/screenshots/Firefox/baseline/document-name-de.png +0 -0
  78. package/screenshots/Firefox/baseline/document-name-en.png +0 -0
  79. package/screenshots/Firefox/baseline/editor-plugins-de.png +0 -0
  80. package/screenshots/Firefox/baseline/editor-plugins-en.png +0 -0
  81. package/screenshots/Firefox/baseline/editor-plugins-selected-de.png +0 -0
  82. package/screenshots/Firefox/baseline/editor-plugins-selected-en.png +0 -0
  83. package/screenshots/Firefox/baseline/editor-plugins-with-doc-de.png +0 -0
  84. package/screenshots/Firefox/baseline/editor-plugins-with-doc-en.png +0 -0
  85. package/screenshots/Firefox/baseline/log-entries-de.png +0 -0
  86. package/screenshots/Firefox/baseline/log-entries-en.png +0 -0
  87. package/screenshots/Firefox/baseline/log-entries-redone-de.png +0 -0
  88. package/screenshots/Firefox/baseline/log-entries-redone-en.png +0 -0
  89. package/screenshots/Firefox/baseline/log-entries-undone-de.png +0 -0
  90. package/screenshots/Firefox/baseline/log-entries-undone-en.png +0 -0
  91. package/screenshots/Firefox/baseline/log-screen-de.png +0 -0
  92. package/screenshots/Firefox/baseline/log-screen-en.png +0 -0
  93. package/screenshots/Firefox/baseline/menu-drawer-de.png +0 -0
  94. package/screenshots/Firefox/baseline/menu-drawer-en.png +0 -0
  95. package/screenshots/Firefox/baseline/menu-plugins-de.png +0 -0
  96. package/screenshots/Firefox/baseline/menu-plugins-en.png +0 -0
  97. package/screenshots/Firefox/baseline/menu-plugins-triggered-de.png +0 -0
  98. package/screenshots/Firefox/baseline/menu-plugins-triggered-en.png +0 -0
  99. package/screenshots/Webkit/baseline/app-bar-de.png +0 -0
  100. package/screenshots/Webkit/baseline/app-bar-en.png +0 -0
  101. package/screenshots/Webkit/baseline/document-name-de.png +0 -0
  102. package/screenshots/Webkit/baseline/document-name-en.png +0 -0
  103. package/screenshots/Webkit/baseline/editor-plugins-de.png +0 -0
  104. package/screenshots/Webkit/baseline/editor-plugins-en.png +0 -0
  105. package/screenshots/Webkit/baseline/editor-plugins-selected-de.png +0 -0
  106. package/screenshots/Webkit/baseline/editor-plugins-selected-en.png +0 -0
  107. package/screenshots/Webkit/baseline/editor-plugins-with-doc-de.png +0 -0
  108. package/screenshots/Webkit/baseline/editor-plugins-with-doc-en.png +0 -0
  109. package/screenshots/Webkit/baseline/log-entries-de.png +0 -0
  110. package/screenshots/Webkit/baseline/log-entries-en.png +0 -0
  111. package/screenshots/Webkit/baseline/log-entries-redone-de.png +0 -0
  112. package/screenshots/Webkit/baseline/log-entries-redone-en.png +0 -0
  113. package/screenshots/Webkit/baseline/log-entries-undone-de.png +0 -0
  114. package/screenshots/Webkit/baseline/log-entries-undone-en.png +0 -0
  115. package/screenshots/Webkit/baseline/log-screen-de.png +0 -0
  116. package/screenshots/Webkit/baseline/log-screen-en.png +0 -0
  117. package/screenshots/Webkit/baseline/menu-drawer-de.png +0 -0
  118. package/screenshots/Webkit/baseline/menu-drawer-en.png +0 -0
  119. package/screenshots/Webkit/baseline/menu-plugins-de.png +0 -0
  120. package/screenshots/Webkit/baseline/menu-plugins-en.png +0 -0
  121. package/screenshots/Webkit/baseline/menu-plugins-triggered-de.png +0 -0
  122. package/screenshots/Webkit/baseline/menu-plugins-triggered-en.png +0 -0
  123. package/tsconfig.json +0 -23
  124. package/utils/testing.spec.ts +0 -210
  125. package/utils/testing.ts +0 -65
  126. package/web-dev-server.config.js +0 -24
  127. package/web-test-runner.config.js +0 -180
@@ -1,49 +0,0 @@
1
- name: 'Setup Node Environment'
2
- description: 'Setup Node, cache and clean install'
3
-
4
- inputs:
5
- registry-url:
6
- description: 'the url for the registry (github or npm)'
7
- required: false
8
- default: 'https://registry.npmjs.org'
9
-
10
- runs:
11
- using: composite
12
- steps:
13
- - name: Set up Node.js
14
- uses: actions/setup-node@v3
15
- with:
16
- node-version: '20'
17
- registry-url: ${{ inputs.registry-url }}
18
-
19
- - name: Cache Node Modules
20
- id: cache-node-modules
21
- uses: actions/cache@v4
22
- with:
23
- path: |
24
- node_modules
25
- key: modules-${{ hashFiles('package-lock.json') }}
26
-
27
- - name: Cache Playwright Binaries
28
- id: cache-playwright
29
- uses: actions/cache@v4
30
- with:
31
- path: |
32
- ~/.cache/ms-playwright
33
- key: playwright-${{ hashFiles('package-lock.json') }}
34
-
35
- - name: Install dependencies
36
- if: steps.cache-node-modules.outputs.cache-hit != 'true'
37
- run: npm ci
38
- shell: bash
39
-
40
- - name: Install playwright browsers
41
- if: steps.cache-playwright.outputs.cache-hit != 'true'
42
- run: npx playwright install --with-deps
43
- shell: bash
44
-
45
- - name: Install system dependencies for WebKit
46
- # Some WebKit dependencies seem to lay outside the cache and will need to be installed separately
47
- if: steps.cache-playwright.outputs.cache-hit == 'true'
48
- run: npx playwright install-deps webkit
49
- shell: bash
@@ -1,84 +0,0 @@
1
- name: release-please
2
-
3
- on:
4
- push:
5
- branches:
6
- - main
7
-
8
- jobs:
9
- release-please:
10
- runs-on: ubuntu-latest
11
- outputs:
12
- release_created: ${{ steps.release.outputs.release_created }}
13
- tag_name: ${{ steps.release.outputs.tag_name }}
14
- permissions:
15
- contents: write
16
- pull-requests: write
17
- issues: write
18
- steps:
19
- - uses: googleapis/release-please-action@v4
20
- id: release
21
- with:
22
- token: ${{ secrets.GITHUB_TOKEN }}
23
- config-file: release-please-config.json
24
- manifest-file: .release-please-manifest.json
25
-
26
- add-build-artifact-to-release:
27
- needs: release-please
28
- if: ${{ needs.release-please.outputs.release_created }}
29
- runs-on: ubuntu-latest
30
- permissions:
31
- contents: write
32
- pages: write
33
- steps:
34
- - uses: actions/checkout@v4
35
- - uses: ./.github/actions/setup-node-env
36
-
37
- - name: Build
38
- run: npm run build
39
-
40
- - name: Compress build output
41
- run: |
42
- (cd ./dist && zip -r ../oscd-shell.zip .)
43
- tar -C ./dist -czvf oscd-shell.tar.gz ./
44
-
45
- - name: Upload Compressed files
46
- env:
47
- GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
48
- run: gh release upload ${{ needs.release-please.outputs.tag_name }} oscd-shell.zip oscd-shell.tar.gz
49
-
50
- npm-publish:
51
- needs: release-please
52
- if: ${{ needs.release-please.outputs.release_created }}
53
- runs-on: ubuntu-latest
54
- permissions:
55
- contents: read
56
- id-token: write
57
- steps:
58
- - uses: actions/checkout@v4
59
- - uses: ./.github/actions/setup-node-env
60
- with:
61
- registry-url: 'https://registry.npmjs.org'
62
- - run: npm publish --provenance --access public
63
- env:
64
- NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
65
-
66
- deploy:
67
- needs: release-please
68
- if: ${{ needs.release-please.outputs.release_created }}
69
- runs-on: ubuntu-latest
70
- steps:
71
- - name: Checkout
72
- uses: actions/checkout@v4
73
-
74
- - uses: ./.github/actions/setup-node-env
75
-
76
- - name: Build
77
- run: npm run bundle
78
-
79
- - name: Deploy
80
- run: |
81
- git remote set-url origin https://git:${GITHUB_TOKEN}@github.com/${GITHUB_REPOSITORY}.git
82
- npx gh-pages -d dist -u "github-actions <support+actions@github.com>"
83
- env:
84
- GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
@@ -1,18 +0,0 @@
1
- name: Test
2
- on: [push, pull_request, workflow_dispatch]
3
-
4
- jobs:
5
- test:
6
- runs-on: ubuntu-latest
7
- steps:
8
- - name: Checkout
9
- uses: actions/checkout@v4
10
-
11
- - uses: ./.github/actions/setup-node-env
12
-
13
- - name: Run unit tests
14
- run: npm run-script test:unit
15
-
16
- - name: Run visual regression tests on PR
17
- if: github.event_name == 'pull_request' || github.event_name == 'workflow_dispatch'
18
- run: npm run-script test:visual
@@ -1,29 +0,0 @@
1
- name: Update Screenshots
2
-
3
- on: [push, workflow_dispatch]
4
-
5
- jobs:
6
- update-screenshots:
7
- runs-on: ubuntu-latest
8
- steps:
9
- - name: Checkout
10
- uses: actions/checkout@v4
11
- with:
12
- ref: ${{ github.head_ref }}
13
-
14
- - uses: ./.github/actions/setup-node-env
15
-
16
- - name: Run visual regression tests
17
- run: npm run test:visual
18
- id: tests
19
- continue-on-error: true
20
-
21
- - name: Update screenshots
22
- if: ${{ steps.tests.outcome == 'failure' }}
23
- run: |
24
- npm run test:update
25
- git config --global user.name "github-actions[bot]"
26
- git config --global user.email "41898282+github-actions[bot]@users.noreply.github.com"
27
- git add screenshots
28
- git commit -m "test: update screenshots"
29
- git push
package/.husky/commit-msg DELETED
@@ -1 +0,0 @@
1
- npx --no -- commitlint --edit $1
package/.husky/pre-commit DELETED
@@ -1 +0,0 @@
1
- npx lint-staged
@@ -1 +0,0 @@
1
- {".":"0.0.5"}
package/CHANGELOG.md DELETED
@@ -1,73 +0,0 @@
1
- # Changelog
2
-
3
- ## [0.0.5](https://github.com/OMICRONEnergyOSS/oscd-shell/compare/oscd-shell-v0.0.4...oscd-shell-v0.0.5) (2025-06-11)
4
-
5
-
6
- ### Features
7
-
8
- * add theming ([9f44494](https://github.com/OMICRONEnergyOSS/oscd-shell/commit/9f4449421ca1f8e6b2ea0225bf8f25dbf3163b99))
9
- * add UpdateNS edit type ([4e36a57](https://github.com/OMICRONEnergyOSS/oscd-shell/commit/4e36a575e468aa9867050ddc0b4402494e4a6205))
10
- * **demo:** add remote open and save plugins ([798fc93](https://github.com/OMICRONEnergyOSS/oscd-shell/commit/798fc93333408bf56d350e5130734c5d60d5657c))
11
- * edit multiple open files ([88bd287](https://github.com/OMICRONEnergyOSS/oscd-shell/commit/88bd2878e093763d4d848ed2dd0a0baa8421ae47))
12
- * **editing:** add editing user interface elements ([e834e4d](https://github.com/OMICRONEnergyOSS/oscd-shell/commit/e834e4d0853e3cd2e2a2ce9d74120c4d06ce92bd))
13
- * **editing:** insert and remove nodes ([65c99da](https://github.com/OMICRONEnergyOSS/oscd-shell/commit/65c99da931aa88c527504a362353da0ac443a23e))
14
- * **editing:** open documents ([e3a3199](https://github.com/OMICRONEnergyOSS/oscd-shell/commit/e3a31999046a29a7aa44467f9b7a7fde784b982f))
15
- * **editing:** update elements' attributes ([b29eff0](https://github.com/OMICRONEnergyOSS/oscd-shell/commit/b29eff04cdc9d14d9f002f183eeb51f7f6adaac9))
16
- * export open-scd and mixin types ([5415d2b](https://github.com/OMICRONEnergyOSS/oscd-shell/commit/5415d2b283e15870fb3d4eec32ec630fd174b28b))
17
- * **foundation:** export cyrb64 hash function ([5b13d94](https://github.com/OMICRONEnergyOSS/oscd-shell/commit/5b13d9466becc2f0922164b806f77d8f01a234ab))
18
- * migrated UI to new oscd-ui ([ae99e24](https://github.com/OMICRONEnergyOSS/oscd-shell/commit/ae99e24fda427e81bfd6088f5889ea44aa410478))
19
- * **open-scd:** pass editCount to editor and menu plugins ([2be53ab](https://github.com/OMICRONEnergyOSS/oscd-shell/commit/2be53ab8de8bad176097153240441db521b99ce8))
20
- * **plugging:** load menu and editor plugins ([e3fe982](https://github.com/OMICRONEnergyOSS/oscd-shell/commit/e3fe98223cefd7b3a9abd49c444f5bfba3c527a8))
21
- * switch shell to using scoped components ([4ec3ffa](https://github.com/OMICRONEnergyOSS/oscd-shell/commit/4ec3ffa2fa9a454646bcda314abe168da6693337))
22
-
23
-
24
- ### Bug Fixes
25
-
26
- * **open-scd:** allow menu plugins to show content ([c7dc849](https://github.com/OMICRONEnergyOSS/oscd-shell/commit/c7dc849fa84419ab605ffafd2b0ec7ce40136fc3))
27
- * **open-scd:** hide menu plugin element container ([02b026e](https://github.com/OMICRONEnergyOSS/oscd-shell/commit/02b026e645ebfa9c26f54afd5f292a10b56af7ef))
28
- * **open-scd:** import locales from relative URL ([5877314](https://github.com/OMICRONEnergyOSS/oscd-shell/commit/5877314f5e2de4c3613324e51328cb463dec2d5d))
29
- * **package:** localize as part of bundle script ([653a506](https://github.com/OMICRONEnergyOSS/oscd-shell/commit/653a50667163e9a9381d26ccb10e927f0758ec73))
30
- * **plugging:** import relative paths from origin ([abb5074](https://github.com/OMICRONEnergyOSS/oscd-shell/commit/abb50749877ce611e4eb58bcde2e39280c429150))
31
-
32
-
33
- ### Styles
34
-
35
- * disable quirks mode in demo and tests ([db1b6c8](https://github.com/OMICRONEnergyOSS/oscd-shell/commit/db1b6c858a97f6842526aa624311d9d1842dfc49))
36
-
37
- ## [0.0.4](https://github.com/OMICRONEnergyOSS/open-scd-core/compare/open-scd-core-v0.0.3...open-scd-core-v0.0.4) (2025-04-22)
38
-
39
-
40
- ### Bug Fixes
41
-
42
- * **package:** localize as part of bundle script ([653a506](https://github.com/OMICRONEnergyOSS/open-scd-core/commit/653a50667163e9a9381d26ccb10e927f0758ec73))
43
-
44
- ## [0.0.3](https://github.com/OMICRONEnergyOSS/open-scd-core/compare/open-scd-core-v0.0.2...open-scd-core-v0.0.3) (2025-04-22)
45
-
46
-
47
- ### Features
48
-
49
- * add theming ([9f44494](https://github.com/OMICRONEnergyOSS/open-scd-core/commit/9f4449421ca1f8e6b2ea0225bf8f25dbf3163b99))
50
- * add UpdateNS edit type ([4e36a57](https://github.com/OMICRONEnergyOSS/open-scd-core/commit/4e36a575e468aa9867050ddc0b4402494e4a6205))
51
- * **demo:** add remote open and save plugins ([798fc93](https://github.com/OMICRONEnergyOSS/open-scd-core/commit/798fc93333408bf56d350e5130734c5d60d5657c))
52
- * edit multiple open files ([88bd287](https://github.com/OMICRONEnergyOSS/open-scd-core/commit/88bd2878e093763d4d848ed2dd0a0baa8421ae47))
53
- * **editing:** add editing user interface elements ([e834e4d](https://github.com/OMICRONEnergyOSS/open-scd-core/commit/e834e4d0853e3cd2e2a2ce9d74120c4d06ce92bd))
54
- * **editing:** insert and remove nodes ([65c99da](https://github.com/OMICRONEnergyOSS/open-scd-core/commit/65c99da931aa88c527504a362353da0ac443a23e))
55
- * **editing:** open documents ([e3a3199](https://github.com/OMICRONEnergyOSS/open-scd-core/commit/e3a31999046a29a7aa44467f9b7a7fde784b982f))
56
- * **editing:** update elements' attributes ([b29eff0](https://github.com/OMICRONEnergyOSS/open-scd-core/commit/b29eff04cdc9d14d9f002f183eeb51f7f6adaac9))
57
- * export open-scd and mixin types ([5415d2b](https://github.com/OMICRONEnergyOSS/open-scd-core/commit/5415d2b283e15870fb3d4eec32ec630fd174b28b))
58
- * **foundation:** export cyrb64 hash function ([5b13d94](https://github.com/OMICRONEnergyOSS/open-scd-core/commit/5b13d9466becc2f0922164b806f77d8f01a234ab))
59
- * **open-scd:** pass editCount to editor and menu plugins ([2be53ab](https://github.com/OMICRONEnergyOSS/open-scd-core/commit/2be53ab8de8bad176097153240441db521b99ce8))
60
- * **plugging:** load menu and editor plugins ([e3fe982](https://github.com/OMICRONEnergyOSS/open-scd-core/commit/e3fe98223cefd7b3a9abd49c444f5bfba3c527a8))
61
-
62
-
63
- ### Bug Fixes
64
-
65
- * **open-scd:** allow menu plugins to show content ([c7dc849](https://github.com/OMICRONEnergyOSS/open-scd-core/commit/c7dc849fa84419ab605ffafd2b0ec7ce40136fc3))
66
- * **open-scd:** hide menu plugin element container ([02b026e](https://github.com/OMICRONEnergyOSS/open-scd-core/commit/02b026e645ebfa9c26f54afd5f292a10b56af7ef))
67
- * **open-scd:** import locales from relative URL ([5877314](https://github.com/OMICRONEnergyOSS/open-scd-core/commit/5877314f5e2de4c3613324e51328cb463dec2d5d))
68
- * **plugging:** import relative paths from origin ([abb5074](https://github.com/OMICRONEnergyOSS/open-scd-core/commit/abb50749877ce611e4eb58bcde2e39280c429150))
69
-
70
-
71
- ### Styles
72
-
73
- * disable quirks mode in demo and tests ([db1b6c8](https://github.com/OMICRONEnergyOSS/open-scd-core/commit/db1b6c858a97f6842526aa624311d9d1842dfc49))
package/CONTRIBUTING.md DELETED
@@ -1,393 +0,0 @@
1
- # Contributing to OpenSCD Core
2
-
3
- Thanks for taking the time to contribute to the OpenSCD project!
4
-
5
- ## Non-Code Contributions
6
-
7
- You don't need to be a software developer to contribute to this effort! Apart
8
- from contributions in the form of code we are also very thankful for
9
-
10
- - [bug reports](https://github.com/OMICRONEnergyOSS/oscd-shell/issues?q=is%3Aopen) alerting
11
- us of errors in the `oscd-shell` component or its `foundation` library
12
- functions,
13
- - [ideas for enhancements](https://github.com/OMICRONEnergyOSS/oscd-shell/discussions/categories/ideas)
14
- to `oscd-shell` or its `foundation` library,
15
- - [contributions to discussions](https://github.com/OMICRONEnergyOSS/oscd-shell/discussions) we're having
16
- about which direction the project should take, and
17
- - [improvements to our wiki](https://github.com/OMICRONEnergyOSS/oscd-shell/wiki)
18
- which contains knowledge about how to use both OpenSCD and SCL in general.
19
-
20
- ## Code Contributions
21
-
22
- > The following is a set of guidelines for contributing to [OpenSCD
23
- > Core](https://github.com/OMICRONEnergyOSS/oscd-shell#readme), not a list of
24
- > strict rules. Use your best judgment and feel free to propose changes to this
25
- > document in a pull request.
26
-
27
- ### Code Structure
28
-
29
- The OpenSCD Core project's [NPM package declaration file](https://github.com/OMICRONEnergyOSS/oscd-shell/blob/main/package.json) lists
30
- two entry points that can be referred to by package users:
31
-
32
- ```json
33
- "exports": {
34
- ".": "dist/foundation.js",
35
- "/oscd-shell.js": "dist/oscd-shell.js"
36
- },
37
- ```
38
-
39
- `foundation.ts` defines a host of types, utility functions, and constants which
40
- we hope will be useful for writing plugins that edit SCL files.
41
-
42
- `oscd-shell.ts` defines a custom element `<oscd-shell>`, a [web component](https://developer.mozilla.org/en-US/docs/Web/Web_Components)
43
- implemented as a [LitElement](https://lit.dev/docs) extended with our own
44
- [Mixins](https://lit.dev/docs/composition/mixins).
45
-
46
- ### Commit Messages
47
-
48
- - Use the [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/)
49
- format for commit messages.
50
-
51
- > A commit should contain only one single change, so you should always be
52
- > able to find a fitting type.
53
-
54
- - Use the present tense ("feat: add feature" not "feat: added feature")
55
- - Use the imperative mood ("fix: move cursor to..." not "fix: moves cursor
56
- to...")
57
- - Limit the first line to 72 characters or less
58
- - Reference issues and pull requests liberally after the first line
59
-
60
- ### Contributing Workflow and Branching Strategy
61
-
62
- We like to receive code contributions through the [Forking Workflow](https://www.atlassian.com/git/tutorials/comparing-workflows/forking-workflow),
63
- which means every contributor maintains their own independent fork and sends
64
- pull requests directly from their own copy of the repo. This enables
65
- contributors to work as independently as possible, with the only point of
66
- coordination happening when a maintainer merges the incoming pull request.
67
-
68
- A pull request should generally only ever contain at most one `fix` or `feat`
69
- commit, and never both. If you have several different bugs to fix or features to
70
- introduce, please create a separate pull request for each one. If a single bug
71
- fix or feature took you several commits to achieve, please squash those commits
72
- into one using an interactive rebase (see the great tutorial linked under
73
- "Forking Workflow" above) before submitting your pull request.
74
-
75
- Please make sure that all CI checks are passing before marking your pull request
76
- "Ready for review".
77
-
78
- ### Filenames
79
-
80
- If a file defines a custom element, it should always be named after its tag name
81
- (e.g. `my-component.ts`). Otherwise, files should generally be named after the
82
- most important symbol they export (e.g. `MyClass.ts`).
83
-
84
- ### Code Style and Linting
85
-
86
- We use eslint and prettier for formatting and linting. Both are run as part of
87
- a `husky` pre-commit hook defined in `package.json`. Nonetheless, we recommend
88
- you use your editor's or IED's eslint and prettier plugins for continuous
89
- formatting and linting while writing the code in order to avoid any surprises.
90
-
91
- Apart from the rules the linter and formatter enforce, we adopt the following
92
- guidelines taken from the terse but broad [Deno Style Guide](https://deno.land/manual/contributing/style_guide) with some minor adjustments:
93
-
94
- #### TODO Comments
95
-
96
- In general, don't commit TODO or FIXME comments. Their significance tends to get
97
- lost in the mists of time and they cause more confusion than anything else.
98
-
99
- If you are tempted to write a FIXME comment, please consider fixing the code
100
- immediately instead. If this is absolutely not possible, create a bug issue
101
- referencing your pull request which introduces the bug.
102
-
103
- If you are tempted to write a TODO comment, please consider opening an issue
104
- describing the changes to be made instead.
105
-
106
- If you still find it helpful to introduce a TODO comment, please include an
107
- issue or at least the author's github username in parentheses. Example:
108
-
109
- ```ts
110
- // TODO(ry): Add tests.
111
- // TODO(#123): Support Windows.
112
- // FIXME(#349): Sometimes panics.
113
- ```
114
-
115
- #### Exported functions: max 2 args, put the rest into an options object.
116
-
117
- When designing function interfaces, stick to the following rules.
118
-
119
- 1. A function that is part of the public API takes 0-2 required arguments, plus
120
- (if necessary) an options object (so max 3 total).
121
-
122
- 2. Optional parameters should generally go into the options object.
123
-
124
- An optional parameter that's not in an options object might be acceptable if
125
- there is only one, and it seems inconceivable that we would add more optional
126
- parameters in the future.
127
-
128
- 3. The 'options' argument is the only argument that is a regular 'Object'.
129
-
130
- Other arguments can be objects, but they must be distinguishable from a
131
- 'plain' Object runtime, by having either:
132
-
133
- - a distinguishing prototype (e.g. `Array`, `Map`, `Date`, `class MyThing`).
134
- - a well-known symbol property (e.g. an iterable with `Symbol.iterator`).
135
-
136
- This allows the API to evolve in a backwards compatible way, even when the
137
- position of the options object changes.
138
-
139
- ```ts, ignore
140
- // BAD: optional parameters not part of options object. (#2)
141
- export function resolve(
142
- hostname: string,
143
- family?: "ipv4" | "ipv6",
144
- timeout?: number,
145
- ): IPAddress[] {}
146
- ```
147
-
148
- ```ts, ignore
149
- // GOOD.
150
- export interface ResolveOptions {
151
- family?: "ipv4" | "ipv6";
152
- timeout?: number;
153
- }
154
- export function resolve(
155
- hostname: string,
156
- options: ResolveOptions = {},
157
- ): IPAddress[] {}
158
- ```
159
-
160
- ```ts, ignore
161
- export interface Environment {
162
- [key: string]: string;
163
- }
164
-
165
- // BAD: `env` could be a regular Object and is therefore indistinguishable
166
- // from an options object. (#3)
167
- export function runShellWithEnv(cmdline: string, env: Environment): string {}
168
-
169
- // GOOD.
170
- export interface RunShellOptions {
171
- env: Environment;
172
- }
173
- export function runShellWithEnv(
174
- cmdline: string,
175
- options: RunShellOptions,
176
- ): string {}
177
- ```
178
-
179
- ```ts
180
- // BAD: more than 3 arguments (#1), multiple optional parameters (#2).
181
- export function renameSync(
182
- oldname: string,
183
- newname: string,
184
- replaceExisting?: boolean,
185
- followLinks?: boolean,
186
- ) {}
187
- ```
188
-
189
- ```ts
190
- // GOOD.
191
- interface RenameOptions {
192
- replaceExisting?: boolean;
193
- followLinks?: boolean;
194
- }
195
- export function renameSync(
196
- oldname: string,
197
- newname: string,
198
- options: RenameOptions = {},
199
- ) {}
200
- ```
201
-
202
- ```ts
203
- // BAD: too many arguments. (#1)
204
- export function pwrite(
205
- fd: number,
206
- buffer: ArrayBuffer,
207
- offset: number,
208
- length: number,
209
- position: number,
210
- ) {}
211
- ```
212
-
213
- ```ts
214
- // BETTER.
215
- export interface PWrite {
216
- fd: number;
217
- buffer: ArrayBuffer;
218
- offset: number;
219
- length: number;
220
- position: number;
221
- }
222
- export function pwrite(options: PWrite) {}
223
- ```
224
-
225
- #### Export all interfaces that are used as parameters to an exported member
226
-
227
- Whenever you are using interfaces that are included in the parameters or return
228
- type of an exported member, you should export the interface that is used. Here
229
- is an example:
230
-
231
- ```ts, ignore
232
- // my-file.ts
233
- export interface Person {
234
- name: string;
235
- age: number;
236
- }
237
-
238
- export function createPerson(name: string, age: number): Person {
239
- return { name, age };
240
- }
241
-
242
- // mod.ts
243
- export { createPerson } from "./my-file.js";
244
- export type { Person } from "./my-file.js";
245
- ```
246
-
247
- #### Minimize dependencies; do not make circular imports.
248
-
249
- Try not to introduce external dependencies if you can avoid doing so.
250
- In particular, be careful not to introduce circular imports.
251
-
252
- #### If a filename starts with an underscore: `_foo.ts`, do not link to it.
253
-
254
- There may be situations where an internal module is necessary but its API is not
255
- meant to be stable or linked to. In this case prefix it with an underscore. By
256
- convention, only files in its own directory should import it.
257
-
258
- #### Use JSDoc for exported symbols.
259
-
260
- We strive for complete documentation. Every exported symbol ideally should have
261
- a documentation line.
262
-
263
- If possible, use a single line for the JSDoc. Example:
264
-
265
- ```ts
266
- /** foo does bar. */
267
- export function foo() {
268
- // ...
269
- }
270
- ```
271
-
272
- It is important that documentation is easily human-readable, but there is also a
273
- need to provide additional styling information to ensure generated documentation
274
- is more rich text. Therefore JSDoc should generally follow markdown markup to
275
- enrich the text.
276
-
277
- While markdown supports HTML tags, it is forbidden in JSDoc blocks.
278
-
279
- Code string literals should be braced with the back-tick (\`) instead of quotes.
280
- For example:
281
-
282
- ```ts
283
- /** Import something from the `foundation` module. */
284
- ```
285
-
286
- Do not document function arguments unless they are non-obvious of their intent
287
- (though if they are non-obvious intent, the API should be considered anyways).
288
- Therefore `@param` should generally not be used. If `@param` is used, it should
289
- not include the `type` as TypeScript is already strongly-typed.
290
-
291
- ```ts
292
- /**
293
- * Function with non-obvious param.
294
- * @param foo Description of non-obvious parameter.
295
- */
296
- ```
297
-
298
- Vertical spacing should be minimized whenever possible. Therefore, single-line
299
- comments should be written as:
300
-
301
- ```ts
302
- /** This is a good single-line JSDoc. */
303
- ```
304
-
305
- And not:
306
-
307
- ```ts
308
- /**
309
- * This is a bad single-line JSDoc.
310
- */
311
- ```
312
-
313
- Code examples should utilize markdown format, like so:
314
-
315
- ````ts
316
- /** A straightforward comment and an example:
317
- * ```ts
318
- * import { foo } from "foundation.js";
319
- * foo("bar");
320
- * ```
321
- */
322
- ````
323
-
324
- Code examples should not contain additional comments and must not be indented.
325
- It is already inside a comment. If it needs further comments, it is not a good
326
- example.
327
-
328
- #### Resolve linting problems using directives
329
-
330
- Currently, the building process uses `eslint` to lint the code. If the task
331
- requires code that is non-conformant to linter use `eslint-disable-next-line
332
- <code>` directive to suppress the warning.
333
-
334
- ```typescript
335
- /** Constructor type for defining `LitElement` mixins. */
336
- // eslint-disable-next-line @typescript-eslint/no-explicit-any
337
- export type LitElementConstructor = new (...args: any[]) => LitElement;
338
- ```
339
-
340
- This ensures the continuous integration process doesn't fail due to linting
341
- problems, but it should be used scarcely.
342
-
343
- #### Each module should come with a test module.
344
-
345
- Every module with public functionality `foo.ts` should come with a test module
346
- `foo.spec.ts`. This file should be a sibling to the tested module.
347
-
348
- #### Top-level functions should not use arrow syntax.
349
-
350
- Top-level functions should use the `function` keyword. Arrow syntax should be
351
- limited to closures.
352
-
353
- Bad:
354
-
355
- ```ts
356
- export const foo = (): string => {
357
- return 'bar';
358
- };
359
- ```
360
-
361
- Good:
362
-
363
- ```ts
364
- export function foo(): string {
365
- return 'bar';
366
- }
367
- ```
368
-
369
- #### Prefer `#` over `private`
370
-
371
- We prefer the private fields (`#`) syntax over `private` keyword of TypeScript
372
- in the standard modules codebase. The private fields make the properties and
373
- methods private even at runtime. On the other hand, `private` keyword of
374
- TypeScript guarantee it private only at compile time and the fields are publicly
375
- accessible at runtime.
376
-
377
- Good:
378
-
379
- ```ts
380
- class MyClass {
381
- #foo = 1;
382
- #bar() {}
383
- }
384
- ```
385
-
386
- Bad:
387
-
388
- ```ts
389
- class MyClass {
390
- private foo = 1;
391
- private bar() {}
392
- }
393
- ```
@@ -1 +0,0 @@
1
- export default { extends: ['@commitlint/config-conventional'] };