Feat(exporter-js): Introduce JS exporter from Supernova #DS-1013

.commitlintrc.js

@@ -19,6 +19,7 @@ module.exports = {
         'web-react',
         'web-twig',
         // Use when committing changes/additions/removals to exact exporter
+        'exporter-js',
         'exporter-scss',
         'exporter-svg',
         // Use when affecting CI process

.eslintrc.js

@@ -19,7 +19,8 @@ module.exports = {
     'packages/web-react',
     'packages/web',
     'packages/form-validations',
-    'exporters/scss'
+    'exporters/scss',
+    'exporters/js',
   ],
 
   extends: ['@lmc-eu/eslint-config-react/base', '@lmc-eu/eslint-config-react/optional', 'prettier', 'plugin:prettier/recommended', 'plugin:storybook/recommended'],

CONTRIBUTING.md

@@ -52,8 +52,8 @@ The `footer` is optional. The [Commit Message Footer](#commit-footer) format des
   │       │             │
   │       │             └─⫸ Summary in present tense. Sentence case. No period at the end.
   │       │
-  │       └─⫸ Commit Scope: analytics|design-tokens|form-validations|icons|web|web-react|web-twig|exporter-scss|
-  │                          exporter-svg|ci|repo
+  │       └─⫸ Commit Scope: analytics|design-tokens|form-validations|icons|web|web-react|web-twig|exporter-js|
+  |                          exporter-scss|exporter-svg|ci|repo
   │
   └─⫸ Commit Type: Feat|Fix|Perf|Revert|Docs|Style|Refactor|Test|Chore|Deps
 ```
@@ -84,6 +84,7 @@ The following is the list of supported scopes:
 - Apps:
   - `demo`
 - Exporters:
+  - `exporter-js`
   - `exporter-scss`
   - `exporter-svg`
 - Packages:

exporters/js/.eslintignore

@@ -0,0 +1,2 @@
+# Generated files used by Supernova
+generated

exporters/js/.eslintrc.js

@@ -0,0 +1,46 @@
+module.exports = {
+  extends: [
+    '../../.eslintrc',
+    'plugin:@typescript-eslint/recommended',
+    'prettier',
+    'plugin:prettier/recommended',
+    '@lmc-eu/eslint-config-jest',
+  ],
+
+  parser: '@typescript-eslint/parser', // the TypeScript parser we installed earlier
+
+  parserOptions: {
+    ecmaVersion: 'latest',
+    project: './tsconfig.eslint.json',
+  },
+
+  settings: {
+    'import/resolver': {
+      node: {
+        extensions: ['.js', '.ts'],
+      },
+    },
+  },
+
+  plugins: ['promise', '@typescript-eslint', 'prettier'],
+  rules: {
+    // disable for `scripts` and `config`
+    '@typescript-eslint/no-var-requires': 'off',
+    // allow ++ in for loops
+    'no-plusplus': ['error', { allowForLoopAfterthoughts: true }],
+    // disabled due to typescript
+    'no-shadow': 'off',
+    '@typescript-eslint/no-shadow': ['error', { allow: ['resolve', 'reject', 'done', 'next', 'error'] }],
+    // disabled due to typescript
+    'no-use-before-define': 'off',
+    '@typescript-eslint/no-use-before-define': 'warn',
+    // We are using typescript, disable jsdoc rules
+    'jsdoc/require-jsdoc': 'off',
+    'jsdoc/require-returns': 'off',
+    'jsdoc/require-param-type': 'off',
+    // allow reassign in properties
+    'no-param-reassign': ['warn', { props: false }],
+    // support monorepos
+    'import/no-extraneous-dependencies': ['error', { packageDir: ['./', '../../'] }],
+  },
+};

exporters/js/.gitignore

@@ -0,0 +1,2 @@
+.build
+.coverage

exporters/js/CHANGELOG.md

@@ -0,0 +1,4 @@
+# Change Log
+
+All notable changes to this project will be documented in this file.
+See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.

exporters/js/CONTRIBUTING.md

@@ -0,0 +1,18 @@
+# Contributing
+
+## Development
+
+Please, read the Supernova Documentation below to start developing this package.
+You will need to install an extension to your IDE to start with development.
+
+Distribution file `generated/functions.js` is assembled by Vite and `build` script. Please, do not edit this file manually.
+All files in `src` directory is editable and buildable by `build` script.
+
+❗ Please, run `build` script for every change you make and commit generated file with other changes.
+Supernova Cloud loads exporters directly from GitHub repository.
+
+## Supernova Documentation
+
+- [Supernova - Function List](https://developers.supernova.io/latest/design-system-model/function-list.html#search-fb31ced2-ca07-11ec-885b-510a619c4a1b)
+- [Supernova - How to build Exporters](https://developers.supernova.io/latest/building-exporters/overview-1.html)
+- [Supernova - How to build Exporters using JavaScript](https://developers.supernova.io/latest/building-exporters/building-exporters-101/using-javascript.html)

exporters/js/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 LMC s.r.o.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

exporters/js/README.md

@@ -0,0 +1,44 @@
+# Exporter Spirit JS
+
+[Supernova][supernova-studio] JS exporter made for Spirit Design System developed by [LMC][lmc].
+
+## Token operations
+
+This exported does several operations with tokens:
+
+- All token groups except [Typography](#typography) are processed using a simple generate function.
+- The first step is sorting. Measures are sorted by number in the token name, Generic Tokens (Other) by value, and the rest by its name.
+- Next, each token is grouped and its value is prepared to print. Grouping is made using actual groups in Supernova and if these are not present, a common name prefix is used. Separate token values are printed as separate variables.
+- Groups are used for printing objects with references to separate tokens and pluralized names.
+- Shadows are grouped if same name.
+- If Gradient names start with `gradients/gradient`, they are not used from Figma, but from Supernova
+
+### Typography
+
+As typography in Figma and Supernova are stored in named text style groups, these groups are used to generate objects with all the values from Supernova. They are grouped by breakpoints.
+⚠️ We do not generate `link` typography tokens (styles that include `-link` in their name).
+
+#### Ebony Font Weight Exception
+
+Font Family Ebony has a different font weight mapping in Figma and in Adobe Fonts. To match these we set its own font weight numeric-name conversion.
+
+### Sorting
+
+Tokens are sorted alphabetically by origin (Figma) name or by name (Supernova). Except Measures - sorted by name number and Other - sorted by value.
+
+## Outputs:
+
+- borders.ts
+- colors.ts
+- gradients.ts
+- measures.ts
+- other.ts
+- radii.ts
+- shadows.ts
+- typography.ts
+- index.ts
+
+The index file contains exports from all other outputs.
+
+[supernova-studio]: https://github.com/Supernova-Studio
+[lmc]: https://github.com/lmc-eu

exporters/js/exporter.json

@@ -0,0 +1,48 @@
+{
+  "id": "eu.lmc.exporter-spirit-js",
+  "name": "Spirit JS Exporter",
+  "description": "Spirit JS Exporter",
+  "author": "Jan Kryšpín <[email protected]>",
+  "organization": "LMC s.r.o.",
+  "source_dir": "src",
+  "version": "1.0.0",
+  "usesBrands": true,
+  "config": {
+    "sources": "sources.json",
+    "output": "output.json",
+    "js": "generated/functions.js"
+  },
+  "engines": {
+    "pulsar": "1.0.0",
+    "supernova": "1.0.0"
+  },
+  "tags": ["JS", "Tokens", "Styles", "Spirit", "TS"],
+  "contributes": {
+    "configuration": [
+      {
+        "key": "defaultFontSize",
+        "default": 16,
+        "type": "number",
+        "label": "Default project font-size in px",
+        "description": "Used for calculation to rem",
+        "category": "Advanced"
+      },
+      {
+        "key": "fontFamilyFallback",
+        "default": ", sans-serif",
+        "type": "string",
+        "label": "Font Family fallback",
+        "description": "Font Family fallback",
+        "category": "Advanced"
+      },
+      {
+        "key": "breakpoints",
+        "default": "mobile,tablet,desktop",
+        "type": "string",
+        "label": "Breakpoints",
+        "description": "List available breakpoints. Separate them with comma. Example and default value: 'mobile,tablet,desktop'.",
+        "category": "Advanced"
+      }
+    ]
+  }
+}

exporters/js/jest.config.js

@@ -0,0 +1,49 @@
+const config = {
+  // The root directory that Jest should scan for tests and modules within.
+  // https://jestjs.io/docs/configuration#rootdir-string
+  rootDir: './',
+
+  // This option tells Jest that all imported modules in your tests should be mocked automatically.
+  // https://jestjs.io/docs/configuration#automock-boolean
+  automock: false,
+
+  // Indicates whether each individual test should be reported during the run.
+  // https://jestjs.io/docs/configuration#verbose-boolean
+  verbose: false,
+
+  // A map from regular expressions to paths to transformers
+  // https://jestjs.io/docs/configuration#transform-objectstring-pathtotransformer--pathtotransformer-object
+  transform: {
+    '^.+\\.(t|j)s?$': ['<rootDir>/../../node_modules/@swc/jest'],
+  },
+
+  // The test environment that will be used for testing.
+  // https://jestjs.io/docs/configuration#testenvironment-string
+  // testEnvironment: 'jsdom',
+
+  // An array of regexp pattern strings that are matched against all test paths before executing the test
+  // https://jestjs.io/docs/configuration#testpathignorepatterns-arraystring
+  testPathIgnorePatterns: ['<rootDir>/dist/', '<rootDir>/node_modules/', '.*__tests__/.*DataProvider.ts'],
+
+  // The directory where Jest should output its coverage files.
+  // https://jestjs.io/docs/configuration#coveragedirectory-string
+  coverageDirectory: './.coverage',
+
+  // An array of glob patterns indicating a set of files for which coverage information should be collected.
+  // https://jestjs.io/docs/configuration#collectcoveragefrom-array
+  collectCoverageFrom: ['<rootDir>/src/**/*.{js,ts}', '!<rootDir>/src/**/*.d.ts'],
+
+  // An array of regexp pattern strings that are matched against all file paths before executing the test.
+  // https://jestjs.io/docs/configuration#coveragepathignorepatterns-arraystring
+  coveragePathIgnorePatterns: ['__fixtures__'],
+
+  // A list of reporter names that Jest uses when writing coverage reports. Any istanbul reporter can be used.
+  // https://jestjs.io/docs/configuration#coveragereporters-arraystring--string-options
+  coverageReporters: ['text', 'text-summary', ['lcov', { projectRoot: '../../' }]],
+
+  // A list of paths to modules that run some code to configure or set up the testing framework before each test.
+  // https://jestjs.io/docs/configuration#setupfilesafterenv-array
+  // setupFilesAfterEnv: ['@testing-library/jest-dom'],
+};
+
+module.exports = config;

exporters/js/output.json

@@ -0,0 +1,40 @@
+{
+  "blueprints": [
+    {
+      "invoke": "borders.pr",
+      "write_to": "borders.ts"
+    },
+    {
+      "invoke": "colors.pr",
+      "write_to": "colors.ts"
+    },
+    {
+      "invoke": "gradients.pr",
+      "write_to": "gradients.ts"
+    },
+    {
+      "invoke": "measures.pr",
+      "write_to": "measures.ts"
+    },
+    {
+      "invoke": "other.pr",
+      "write_to": "other.ts"
+    },
+    {
+      "invoke": "radii.pr",
+      "write_to": "radii.ts"
+    },
+    {
+      "invoke": "shadows.pr",
+      "write_to": "shadows.ts"
+    },
+    {
+      "invoke": "typography.pr",
+      "write_to": "typography.ts"
+    },
+    {
+      "invoke": "index.pr",
+      "write_to": "index.ts"
+    }
+  ]
+}

exporters/js/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@lmc-eu/spirit-exporters-js",
+  "version": "1.0.0",
+  "description": "Spirit JS Exporter for Supernova",
+  "license": "MIT",
+  "private": true,
+  "scripts": {
+    "build": "vite build",
+    "lint": "eslint ./",
+    "lint:fix": "yarn lint --fix",
+    "test": "npm-run-all lint test:unit:coverage types",
+    "test:unit": "jest",
+    "test:unit:watch": "yarn test:unit --watchAll",
+    "test:unit:coverage": "yarn test:unit --coverage",
+    "types": "tsc"
+  },
+  "devDependencies": {
+    "@swc/core": "1.3.94",
+    "@swc/jest": "0.2.29",
+    "jest": "29.7.0",
+    "typescript": "4.9.5",
+    "vite": "4.5.0"
+  }
+}

exporters/js/sources.json

@@ -0,0 +1 @@
+{}

exporters/js/src/borders.pr

@@ -0,0 +1,4 @@
+// Generated Borders from Supernova. Do not edit manually.
+{[ if (ds.tokensByType("Border", ds.currentBrand().id)).count() > 0 ]}
+{{ generateSimple("borders", ds.tokensByType("Border", ds.currentBrand().id), ds.tokenGroupsOfType("Border", ds.currentBrand().id)) }}
+{[/]}

exporters/js/src/colors.pr

@@ -0,0 +1,4 @@
+// Generated Colors from Supernova. Do not edit manually.
+{[ if (ds.tokensByType("Color", ds.currentBrand().id)).count() > 0 ]}
+{{ generateSimple("colors", ds.tokensByType("Color", ds.currentBrand().id)) }}
+{[/]}

exporters/js/src/gradients.pr

@@ -0,0 +1,4 @@
+// Generated Gradients from Supernova. Do not edit manually.
+{[ if (ds.tokensByType("Gradient", ds.currentBrand().id)).count() > 0 ]}
+{{ generateSimple("gradients", ds.tokensByType("Gradient", ds.currentBrand().id)) }}
+{[/]}