@kubex/zinc 0.0.2 → 1.0.0

package/.editorconfig

@@ -0,0 +1,18 @@
+# https://editorconfig.org
+
+root = true
+
+[*]
+charset = utf-8
+indent_style = space
+indent_size = 2
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.md]
+insert_final_newline = false
+trim_trailing_whitespace = false
+
+[*.ts]
+ij_html_add_new_line_before_tags = none

package/.eslintignore

@@ -0,0 +1,8 @@
+.cache
+docs/dist
+docs/search.json
+docs/**/*.min.js
+dist
+node_modules
+scripts
+scss

package/.eslintrc.cjs

@@ -0,0 +1,208 @@
+/* eslint-env node */
+
+module.exports = {
+  plugins:       [
+    '@typescript-eslint',
+    'wc',
+    'lit',
+    'lit-a11y',
+    'chai-expect',
+    'chai-friendly',
+    'import',
+    'sort-imports-es6-autofix'
+  ],
+  extends:       [
+    'eslint:recommended',
+    'plugin:wc/recommended',
+    'plugin:wc/best-practice',
+    'plugin:lit/recommended',
+    'plugin:lit-a11y/recommended'
+  ],
+  env:           {
+    es2021:  true,
+    browser: true
+  },
+  parserOptions: {
+    sourceType: 'module'
+  },
+  overrides:     [
+    {
+      extends:       [
+        'plugin:@typescript-eslint/eslint-recommended',
+        'plugin:@typescript-eslint/recommended',
+        'plugin:@typescript-eslint/recommended-requiring-type-checking'
+      ],
+      parser:        '@typescript-eslint/parser',
+      parserOptions: {
+        sourceType:      'module',
+        project:         './tsconfig.json',
+        tsconfigRootDir: __dirname
+      },
+      files:         ['*.ts'],
+      rules:         {
+        'default-param-last':                                        'off',
+        '@typescript-eslint/default-param-last':                     'error',
+        'no-empty-function':                                         'off',
+        '@typescript-eslint/no-empty-function':                      'warn',
+        'no-implied-eval':                                           'off',
+        '@typescript-eslint/no-implied-eval':                        'error',
+        'no-invalid-this':                                           'off',
+        '@typescript-eslint/no-invalid-this':                        'error',
+        'no-shadow':                                                 'off',
+        '@typescript-eslint/no-shadow':                              'error',
+        'no-throw-literal':                                          'off',
+        '@typescript-eslint/no-throw-literal':                       'error',
+        'no-unused-expressions':                                     'off',
+        '@typescript-eslint/prefer-regexp-exec':                     'off',
+        '@typescript-eslint/no-unused-expressions':                  'error',
+        '@typescript-eslint/unbound-method':                         'off',
+        '@typescript-eslint/no-non-null-assertion':                  'off',
+        '@typescript-eslint/no-floating-promises':                   'off',
+        '@typescript-eslint/no-misused-promises':                    [
+          'error',
+          {
+            checksVoidReturn: false
+          }
+        ],
+        '@typescript-eslint/consistent-type-assertions':             [
+          'warn',
+          {
+            assertionStyle:              'as',
+            objectLiteralTypeAssertions: 'never'
+          }
+        ],
+        '@typescript-eslint/consistent-type-imports':                'warn',
+        '@typescript-eslint/no-base-to-string':                      'error',
+        '@typescript-eslint/no-confusing-non-null-assertion':        'error',
+        '@typescript-eslint/no-invalid-void-type':                   'error',
+        '@typescript-eslint/no-require-imports':                     'error',
+        '@typescript-eslint/no-unnecessary-boolean-literal-compare': 'warn',
+        '@typescript-eslint/no-unnecessary-condition':               'off',
+        '@typescript-eslint/no-unnecessary-qualifier':               'warn',
+        '@typescript-eslint/no-unnecessary-type-assertion':          'off',
+        '@typescript-eslint/non-nullable-type-assertion-style':      'warn',
+        '@typescript-eslint/prefer-for-of':                          'warn',
+        '@typescript-eslint/prefer-optional-chain':                  'warn',
+        '@typescript-eslint/prefer-return-this-type':                'error',
+        '@typescript-eslint/prefer-string-starts-ends-with':         'warn',
+        '@typescript-eslint/require-array-sort-compare':             'error',
+        '@typescript-eslint/unified-signatures':                     'warn',
+        '@typescript-eslint/array-type':                             'warn',
+        '@typescript-eslint/consistent-type-definitions':            ['warn', 'interface'],
+        '@typescript-eslint/member-delimiter-style':                 [
+          'warn',
+          {multiline: {delimiter: 'semi', requireLast: true}}
+        ],
+        '@typescript-eslint/method-signature-style':                 'warn',
+        '@typescript-eslint/no-extraneous-class':                    'error',
+        '@typescript-eslint/no-redundant-type-constituents':         'off',
+        '@typescript-eslint/parameter-properties':                   'error',
+        '@typescript-eslint/strict-boolean-expressions':             'off',
+        '@typescript-eslint/ban-ts-comment':                         'off',
+        '@typescript-eslint/no-explicit-any':                        'off'
+      }
+    },
+    {
+      files: ['**/*.cjs'],
+      env:   {
+        node: true
+      }
+    },
+    {
+      extends: ['plugin:chai-expect/recommended', 'plugin:chai-friendly/recommended'],
+      files:   ['*.test.ts'],
+      rules:   {
+        '@typescript-eslint/no-unsafe-call':        'off',
+        '@typescript-eslint/no-unused-expressions': 'off'
+      }
+    }
+  ],
+  rules:         {
+    'no-template-curly-in-string':               'error',
+    'array-callback-return':                     'error',
+    'comma-dangle':                              'off',
+    'consistent-return':                         'error',
+    curly:                                       'off',
+    'default-param-last':                        'error',
+    eqeqeq:                                      'error',
+    'lit-a11y/click-events-have-key-events':     'off',
+    'lit/binding-positions':                     'off',
+    'lit/no-invalid-html':                       'off',
+    'no-constructor-return':                     'error',
+    'no-empty-function':                         'warn',
+    'no-eval':                                   'error',
+    'no-extend-native':                          'error',
+    'no-extra-bind':                             'error',
+    'no-floating-decimal':                       'error',
+    'no-implicit-coercion':                      'off',
+    'no-implicit-globals':                       'error',
+    'no-implied-eval':                           'error',
+    'no-invalid-this':                           'error',
+    'no-labels':                                 'error',
+    'no-lone-blocks':                            'error',
+    'no-new':                                    'error',
+    'no-new-func':                               'error',
+    'no-new-wrappers':                           'error',
+    'no-octal-escape':                           'error',
+    'no-proto':                                  'error',
+    'no-return-assign':                          'warn',
+    'no-script-url':                             'error',
+    'no-self-compare':                           'warn',
+    'no-sequences':                              'warn',
+    'no-throw-literal':                          'error',
+    'no-unmodified-loop-condition':              'error',
+    'no-unused-expressions':                     'warn',
+    'no-useless-call':                           'error',
+    'no-useless-concat':                         'error',
+    'no-useless-return':                         'warn',
+    'prefer-promise-reject-errors':              'error',
+    radix:                                       'off',
+    'require-await':                             'error',
+    'wrap-iife':                                 ['warn', 'inside'],
+    'no-shadow':                                 'error',
+    'no-array-constructor':                      'error',
+    'no-bitwise':                                'error',
+    'no-multi-assign':                           'warn',
+    'no-new-object':                             'error',
+    'no-useless-computed-key':                   'warn',
+    'no-useless-rename':                         'warn',
+    'no-var':                                    'error',
+    'prefer-const':                              'warn',
+    'prefer-numeric-literals':                   'warn',
+    'prefer-object-spread':                      'warn',
+    'prefer-rest-params':                        'warn',
+    'prefer-spread':                             'warn',
+    'prefer-template':                           'off',
+    'no-else-return':                            'off',
+    'func-names':                                ['warn', 'never'],
+    'one-var':                                   ['warn', 'never'],
+    'operator-assignment':                       'warn',
+    'prefer-arrow-callback':                     'warn',
+    'no-restricted-imports':                     [
+      'warn',
+      {
+        paths: [
+          {
+            name:    '.',
+            message: 'Usage of local index imports is not allowed.'
+          },
+          {
+            name:    './index',
+            message: 'Import from the source file instead.'
+          }
+        ]
+      }
+    ],
+    'import/extensions':                         0,
+    'import/no-duplicates':                      'warn',
+    'sort-imports-es6-autofix/sort-imports-es6': [
+      2,
+      {
+        ignoreCase:            true,
+        ignoreMemberSort:      false,
+        memberSyntaxSortOrder: ['none', 'all', 'multiple', 'single']
+      }
+    ],
+    'wc/guard-super-call':                       'off'
+  }
+};

package/.github/workflows/eleventy_build.yml

@@ -0,0 +1,42 @@
+name: Eleventy Build
+
+on:
+  push:
+    branches:
+      - master
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    concurrency:
+      group: ${{ github.workflow }}-${{ github.ref }}
+    steps:
+      - uses: actions/checkout@v2 # Check out the repository
+
+      - name: Setup Node
+        uses: actions/setup-node@v2
+        with:
+          node-version: '18'
+
+      - name: Cache npm
+        uses: actions/cache@v3
+        with:
+          path: ~/.npm
+          key: ${{ runner.os }}-node-${{ hashFiles('**/package.json') }}
+
+      - run: npm ci # Install dependencies
+
+      - run: npm run build # Build the site
+
+      # Copy the dist/ folder into _site/dist
+      - run: cp -r dist/ _site/dist
+
+      - name: Deploy
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }} # GitHub token automatically generated
+          publish_dir: './_site' # Directory to deploy
+          exclude_assets: '.github,**/.gitignore'
+          cname: zinc.style

package/.github/workflows/js_build_and_deploy.yaml

@@ -0,0 +1,62 @@
+name: "Build And Deploy JS"
+on:
+  push:
+    branches:
+      - master
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3 # Check out the repository
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20.x'
+
+      - name: Cache npm
+        uses: actions/cache@v3
+        with:
+          path: ~/.npm
+          key: ${{ runner.os }}-node-${{ hashFiles('**/package.json') }}
+
+      - run: npm ci # Install dependencies
+
+      - run: npm run build # Build the site
+
+      # Store the dist folder
+      - uses: actions/upload-artifact@v4
+        with:
+          name: app-build
+          path: dist
+
+  deploy:
+    needs: [ build ]
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Release
+        id: release
+        uses: justincy/github-action-npm-release@2.0.2
+
+        # Setup .npmrc file to publish to npm
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20.x'
+          registry-url: 'https://registry.npmjs.org'
+
+        # Get the dist folder
+      - name: Download build artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: app-build
+
+      - run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+

package/custom-elements-manifest.config.js

@@ -0,0 +1,230 @@
+import * as path from 'path';
+import {customElementJetBrainsPlugin} from 'custom-element-jet-brains-integration';
+import {customElementVsCodePlugin} from 'custom-element-vs-code-integration';
+import {customElementVuejsPlugin} from 'custom-element-vuejs-integration';
+import {parse} from 'comment-parser';
+import {pascalCase} from 'pascal-case';
+import commandLineArgs from 'command-line-args';
+import fs from 'fs';
+
+const packageData = JSON.parse(fs.readFileSync('./package.json', 'utf8'));
+const {name, description, version, author, homepage, license} = packageData;
+
+const {outdir} = commandLineArgs([
+  {name: 'litelement', type: String},
+  {name: 'analyze', defaultOption: true},
+  {name: 'outdir', type: String}
+]);
+
+function noDash(string)
+{
+  return string.replace(/^\s?-/, '').trim();
+}
+
+function replace(string, terms)
+{
+  terms.forEach(({from, to}) =>
+  {
+    string = string?.replace(from, to);
+  });
+
+  return string;
+}
+
+export default {
+  globs:   ['src/components/**/*.component.ts'],
+  // Exclude the components specifically for the editor
+  exclude: ['**/*.scss', '**/*.test.ts', 'src/components/editor/modules/**/*'],
+  plugins: [
+    // Append package data
+    {
+      name: 'zinc-package-data',
+      packageLinkPhase({customElementsManifest})
+      {
+        customElementsManifest.package = {name, description, version, author, homepage, license};
+      }
+    },
+    // Infer tag names because we no longer use @customElement decorators.
+    {
+      name: 'zinc-infer-tag-names',
+      analyzePhase({ts, node, moduleDoc})
+      {
+        switch(node.kind)
+        {
+          case ts.SyntaxKind.ClassDeclaration:
+          {
+            const className = node.name.getText();
+            const classDoc = moduleDoc?.declarations?.find(declaration => declaration.name === className);
+
+            const importPath = moduleDoc.path;
+
+            // This is kind of a best guess at components. "thing.component.ts"
+            if(!importPath.endsWith('.component.ts'))
+            {
+              return;
+            }
+
+            const tagNameWithoutPrefix = path.basename(importPath, '.component.ts');
+            const tagName = 'zn-' + tagNameWithoutPrefix;
+
+            classDoc.tagNameWithoutPrefix = tagNameWithoutPrefix;
+            classDoc.tagName = tagName;
+
+            // This used to be set to true by @customElement
+            classDoc.customElement = true;
+          }
+        }
+      }
+    },
+    // Parse custom jsDoc tags
+    {
+      name: 'zinc-custom-tags',
+      analyzePhase({ts, node, moduleDoc})
+      {
+        switch(node.kind)
+        {
+          case ts.SyntaxKind.ClassDeclaration:
+          {
+            const className = node.name.getText();
+            const classDoc = moduleDoc?.declarations?.find(declaration => declaration.name === className);
+            const customTags = ['animation', 'dependency', 'documentation', 'since', 'status', 'title'];
+            let customComments = '/**';
+
+            node.jsDoc?.forEach(jsDoc =>
+            {
+              jsDoc?.tags?.forEach(tag =>
+              {
+                const tagName = tag.tagName.getText();
+
+                if(customTags.includes(tagName))
+                {
+                  customComments += `\n * @${tagName} ${tag.comment}`;
+                }
+              });
+            });
+
+            // This is what allows us to map JSDOC comments to ReactWrappers.
+            classDoc['jsDoc'] = node.jsDoc?.map(jsDoc => jsDoc.getFullText()).join('\n');
+
+            const parsed = parse(`${customComments}\n */`);
+            parsed[0].tags?.forEach(t =>
+            {
+              switch(t.tag)
+              {
+                // Animations
+                case 'animation':
+                  if(!Array.isArray(classDoc['animations']))
+                  {
+                    classDoc['animations'] = [];
+                  }
+                  classDoc['animations'].push({
+                    name:        t.name,
+                    description: noDash(t.description)
+                  });
+                  break;
+
+                // Dependencies
+                case 'dependency':
+                  if(!Array.isArray(classDoc['dependencies']))
+                  {
+                    classDoc['dependencies'] = [];
+                  }
+                  classDoc['dependencies'].push(t.name);
+                  break;
+
+                // Value-only metadata tags
+                case 'documentation':
+                case 'since':
+                case 'status':
+                case 'title':
+                  classDoc[t.tag] = t.name;
+                  break;
+
+                // All other tags
+                default:
+                  if(!Array.isArray(classDoc[t.tag]))
+                  {
+                    classDoc[t.tag] = [];
+                  }
+
+                  classDoc[t.tag].push({
+                    name:        t.name,
+                    description: t.description,
+                    type:        t.type || undefined
+                  });
+              }
+            });
+          }
+        }
+      }
+    },
+    {
+      name: 'zinc-translate-module-paths',
+      packageLinkPhase({customElementsManifest})
+      {
+        customElementsManifest?.modules?.forEach(mod =>
+        {
+          //
+          // CEM paths look like this:
+          //
+          //  src/components/button/button.ts
+          //
+          // But we want them to look like this:
+          //
+          //  components/button/button.js
+          //
+          const terms = [
+            {from: /^src\//, to: ''}, // Strip the src/ prefix
+            {from: /\.component.([tj])sx?$/, to: '.js'} // Convert .ts to .js
+          ];
+
+          mod.path = replace(mod.path, terms);
+
+          for(const ex of mod.exports ?? [])
+          {
+            ex.declaration.module = replace(ex.declaration.module, terms);
+          }
+
+          for(const dec of mod.declarations ?? [])
+          {
+            if(dec.kind === 'class')
+            {
+              for(const member of dec.members ?? [])
+              {
+                if(member.inheritedFrom)
+                {
+                  member.inheritedFrom.module = replace(member.inheritedFrom.module, terms);
+                }
+              }
+            }
+          }
+        });
+      }
+    },
+
+    // Generate custom VS Code data
+    customElementVsCodePlugin({
+      outdir,
+      cssFileName:        null,
+      referencesTemplate: (_, tag) => [
+        {
+          name: 'Documentation',
+          url:  `https://zinc.style/components/${tag.replace('zn-', '')}`
+        }
+      ]
+    }),
+
+    customElementJetBrainsPlugin({
+      outdir:             './dist',
+      excludeCss:         true,
+      packageJson:        false,
+      referencesTemplate: (_, tag) =>
+                          {
+                            return {
+                              name: 'Documentation',
+                              url:  `https://zinc.style/components/${tag.replace('zn-', '')}`
+                            };
+                          }
+    })
+  ]
+};