feat(docs): create get started icons documentation (#188)

.gitignore

@@ -8,6 +8,7 @@ packages/vue/src/components
 packages/**/coverage
 packages/**/components.d.ts
 packages/tokens/index.ts
+packages/icons/index.ts
 packages/core/react
 packages/core/vue
 packages/core/core.css

apps/docs/.storybook/preview-body.html

@@ -0,0 +1,11 @@
+<style>
+  .icon-gallery > summary {
+    border-bottom: 1px solid #0002;
+    cursor: pointer;
+    font-family: 'Nunito Sans', sans-serif;
+    font-size: 18px;
+    font-weight: 600;
+    margin-bottom: 16px;
+    user-select: none;
+  }
+</style>

apps/docs/package.json

@@ -4,5 +4,29 @@
   "scripts": {
     "start": "storybook dev -p 6006",
     "build": "storybook build"
+  },
+  "nx": {
+    "targets": {
+      "build": {
+        "dependsOn": [
+          {
+            "projects": [
+              "@juntossomosmais/atomium-icons"
+            ],
+            "target": "generate:types"
+          }
+        ]
+      },
+      "start": {
+        "dependsOn": [
+          {
+            "projects": [
+              "@juntossomosmais/atomium-icons"
+            ],
+            "target": "generate:types"
+          }
+        ]
+      }
+    }
   }
 }

apps/docs/stories/1_4_Icons.stories.mdx

@@ -0,0 +1,39 @@
+import { Meta, Title, IconGallery, IconItem } from '@storybook/blocks'
+
+import { iconsList } from '../utils/icons-list'
+
+<Meta title="Getting Started/Icons" />
+
+# Icons
+
+The icons are a collection of icons that can be used in your components. It is based on the [Material Design Icons](https://materialdesignicons.com/) library but we can also add our own custom icons.
+
+- [Architecture decisions](#architecture-decisions)
+- [Using icons](/docs/components-icon--docs)
+- [How add a custom icon](https://github.com/juntossomosmais/atomium/tree/main/packages/icons#adding-a-new-icon)
+
+## List of icons
+
+See the list of all available icons:
+
+<details class="icon-gallery">
+  <summary>Custom Icons</summary>
+  <IconGallery>
+    {iconsList?.custom?.map((icon) => (
+      <IconItem name={icon}>
+        <atom-icon icon={icon}></atom-icon>
+      </IconItem>
+    ))}
+  </IconGallery>
+</details>
+
+<details class="icon-gallery">
+  <summary>Material Design Icons</summary>
+  <IconGallery>
+    {iconsList?.mdi?.map((icon) => (
+      <IconItem name={icon}>
+        <atom-icon icon={icon}></atom-icon>
+      </IconItem>
+    ))}
+  </IconGallery>
+</details>

apps/docs/utils/icons-list.ts

@@ -0,0 +1,2 @@
+// @note: this export statement is placed here because Nx does not track imports inside .mdx files used for stories.
+export * from '@juntossomosmais/atomium-icons'

nx.json

@@ -13,30 +13,26 @@
     "default": {
       "runner": "nx/tasks-runners/default",
       "options": {
-        "cacheableOperations": [
-          "build",
-          "lint",
-          "test"
-        ]
+        "cacheableOperations": ["build", "lint", "test"]
       }
     }
   },
+  "targetDefaults": {
+    "build": {
+      "dependsOn": ["^build"]
+    }
+  },
   "pluginsConfig": {
     "@nrwl/js": {
       "analyzeSourceFiles": true
     }
   },
   "namedInputs": {
-    "default": [
-      "{projectRoot}/**/*",
-      "sharedGlobals"
-    ],
+    "default": ["{projectRoot}/**/*", "sharedGlobals"],
     "sharedGlobals": [
       "{workspaceRoot}/tsconfig.base.json",
       "{workspaceRoot}/nx.json"
     ],
-    "production": [
-      "default"
-    ]
+    "production": ["default"]
   }
 }

package.json

@@ -15,13 +15,12 @@
     "utils/*"
   ],
   "scripts": {
-    "core:build": "npm run icons:generate-types && npx nx build @juntossomosmais/atomium && npm run react:build",
+    "core:build": "npx nx build @juntossomosmais/atomium && npm run react:build",
     "docs:build": "npx nx build @atomium/docs && npx nx build @atomium/docs-react",
     "docs-react:start": "npx nx run @atomium/docs-react:start",
     "lint:pre-commit": "eslint --resolve-plugins-relative-to . -c ./.eslintrc.json $(git diff --cached --name-only --diff-filter=AM | grep  -E \"(.js$|.ts$)\") --cache --cache-location node_modules/.cache/eslint",
     "lint:styles": "stylelint '**/*.scss'",
     "icons:build": "npx nx build @juntossomosmais/atomium-icons",
-    "icons:generate-types": "cd packages/icons && npm run generate:types",
     "postinstall": "npx nx build @juntossomosmais/atomium:prebuild && npm run icons:build && npm run core:build && npm run tokens:build",
     "pre-commit": "lint-staged",
     "prepare": "husky install",

packages/core/package.json

@@ -35,5 +35,29 @@
     "generate": "stencil generate",
     "prebuild": "npx mkdirp react && npx mkdirp vue && cd > core.css",
     "publish-library": "npm publish --access public"
+  },
+  "nx": {
+    "targets": {
+      "build": {
+        "dependsOn": [
+          {
+            "projects": [
+              "@juntossomosmais/atomium-icons"
+            ],
+            "target": "generate:types"
+          }
+        ]
+      },
+      "start": {
+        "dependsOn": [
+          {
+            "projects": [
+              "@juntossomosmais/atomium-icons"
+            ],
+            "target": "generate:types"
+          }
+        ]
+      }
+    }
   }
 }

packages/icons/jest.config.js

@@ -0,0 +1,12 @@
+module.exports = {
+  testEnvironment: 'node',
+  transform: {
+    '^.+\\.tsx?$': 'ts-jest',
+  },
+  testMatch: ['**/*.spec.ts'],
+  moduleFileExtensions: ['ts', 'js'],
+  collectCoverage: true,
+  coverageReporters: ['lcov'],
+  coveragePathIgnorePatterns: ['/node_modules/'],
+  collectCoverageFrom: ['scripts/*.ts', '!scripts/*.spec.ts'],
+}

packages/icons/package.json

@@ -1,14 +1,31 @@
 {
   "name": "@juntossomosmais/atomium-icons",
   "private": true,
-  "type": "module",
   "types": "dist/index.d.ts",
+  "main": "dist/index.js",
   "files": [
     "dist/"
   ],
   "scripts": {
-    "build": "tsc && node dist/scripts/build.js && npm run generate:types",
-    "generate:types": "node dist/scripts/generate-types.js && npm run copy",
-    "copy": "npx copyfiles --flat ./dist/icons.d.ts ../core/src"
+    "compile": "tsc",
+    "build": "npx nx exec -- node dist/scripts/build.js",
+    "generate:types": "npx nx exec -- node dist/scripts/generate-types.js && npm run compile && npm run copy",
+    "copy": "npx copyfiles --flat ./dist/icons.d.ts ../core/src",
+    "test:ci": "jest --coverage --no-cache --updateSnapshot --ci",
+    "test": "jest --maxWorkers=50%"
+  },
+  "nx": {
+    "targets": {
+      "build": {
+        "dependsOn": [
+          "compile"
+        ]
+      },
+      "generate:types": {
+        "dependsOn": [
+          "compile"
+        ]
+      }
+    }
   }
 }

packages/icons/scripts/generate-types.ts

@@ -1,8 +1,13 @@
-import { readSvgDirectories, writeTypeDefinitionFile } from './helpers.js'
+import {
+  readSvgDirectories,
+  writeListFile,
+  writeTypeDefinitionFile,
+} from './helpers.js'
 
 function generateTypes() {
   console.log(`Generating types...`)
   const files = readSvgDirectories()
+  writeListFile(files)
   writeTypeDefinitionFile(files)
 }
 

packages/icons/scripts/helpers.spec.ts

@@ -0,0 +1,84 @@
+import fs from 'fs'
+import path from 'path'
+import {
+  readSvgDirectories,
+  writeListFile,
+  writeSvgFile,
+  writeTypeDefinitionFile,
+} from './helpers'
+
+const MOCK_SVG_DIR = path.resolve(__dirname, './__mocks__/svg')
+
+describe('readSvgDirectories', () => {
+  it('should return an array of all SVG files in the specified directory', () => {
+    const svgFiles = readSvgDirectories(MOCK_SVG_DIR)
+    expect(svgFiles).toHaveLength(2)
+    expect(svgFiles).toContain(path.join(MOCK_SVG_DIR, 'custom/icon.svg'))
+    expect(svgFiles).toContain(path.join(MOCK_SVG_DIR, 'mdi/icon.svg'))
+  })
+})
+
+describe('writeSvgFile', () => {
+  it('should mock the fs.writeFileSync function', () => {
+    jest.mock('fs')
+    const mockWriteFileSync = jest.fn()
+    fs.writeFileSync = mockWriteFileSync
+
+    const fileName = 'test.svg'
+    const content = '<svg viewBox="0 0 100 100"></svg>'
+    const outputDirectory = './dist'
+
+    writeSvgFile(fileName, content, outputDirectory)
+
+    expect(mockWriteFileSync).toHaveBeenCalledWith(
+      path.join(outputDirectory, fileName),
+      content,
+      'utf-8'
+    )
+  })
+})
+
+describe('writeTypeDefinitionFile', () => {
+  it('should write the type definition file for the specified SVG files', () => {
+    jest.mock('fs')
+    const mockWriteFileSync = jest.fn()
+    fs.writeFileSync = mockWriteFileSync
+
+    const svgFiles = ['./svg/custom/customIcon.svg', './svg/mdi/mdiIcon.svg']
+    const outputPath = './'
+    const output = `export type IconProps = ${[
+      `'customIcon'`,
+      `'mdiIcon'`,
+    ].join('\n | ')};`
+
+    writeTypeDefinitionFile(svgFiles, outputPath)
+
+    expect(mockWriteFileSync).toHaveBeenCalledWith('../icons.d.ts', output)
+  })
+})
+
+describe('writeListFile', () => {
+  it('should mock the fs.writeFileSync function', () => {
+    jest.mock('fs')
+    const mockWriteFileSync = jest.fn()
+    fs.writeFileSync = mockWriteFileSync
+
+    const svgFiles = ['./svg/custom/icon.svg', './svg/mdi/icon.svg']
+    const outputPath = './'
+    const list = {
+      custom: ['icon'],
+      mdi: ['icon'],
+    }
+    const output = [
+      '// THIS FILE IS GENERATED AUTOMATICALLY DO NOT EDIT MANUALLY\n\n',
+      `export const iconsList = ${JSON.stringify(list, null, 2)}`,
+    ]
+
+    writeListFile(svgFiles, outputPath)
+
+    expect(mockWriteFileSync).toHaveBeenCalledWith(
+      path.join(outputPath, '../..', 'index.ts'),
+      output.join('')
+    )
+  })
+})

packages/icons/scripts/helpers.ts

@@ -1,12 +1,9 @@
 import fs from 'fs'
 import path from 'path'
-import { fileURLToPath } from 'url'
 
-export const getCurrentDirPath = (currentUrl = import.meta.url) =>
-  path.dirname(fileURLToPath(currentUrl))
-
-const ICONS_DIR = path.resolve(getCurrentDirPath(), '../../svg')
-const DIST_DIR = path.resolve(getCurrentDirPath(), '../svg')
+const CURRENT_DIR = __dirname
+const ICONS_DIR = path.resolve(CURRENT_DIR, '../../svg')
+const DIST_DIR = path.resolve(CURRENT_DIR, '../svg')
 
 export const readSvg = (path: string) => fs.readFileSync(path, 'utf-8')
 
@@ -52,9 +49,34 @@ export const writeSvgFile = (
 
 export const writeTypeDefinitionFile = (
   svgFiles: string[],
-  outputPath = getCurrentDirPath()
+  outputPath = CURRENT_DIR
 ) => {
   const types = svgFiles.map((file) => `'${path.basename(file, '.svg')}'`)
   const typeDef = `export type IconProps = ${types.join('\n | ')};`
   fs.writeFileSync(path.join(outputPath, '..', 'icons.d.ts'), typeDef)
 }
+
+export const writeListFile = (svgFiles: string[], outputPath = CURRENT_DIR) => {
+  const list = svgFiles.reduce(
+    (acc, file) => {
+      const category = path.basename(path.dirname(file))
+      const name = path.basename(file, '.svg')
+
+      if (!acc[category]) {
+        acc[category] = []
+      }
+
+      acc[category].push(name)
+
+      return acc
+    },
+    {} as Record<'custom' | 'mdi', string[]>
+  )
+
+  const output = [
+    '// THIS FILE IS GENERATED AUTOMATICALLY DO NOT EDIT MANUALLY\n\n',
+    `export const iconsList = ${JSON.stringify(list, null, 2)}`,
+  ]
+
+  fs.writeFileSync(path.join(outputPath, '../..', 'index.ts'), output.join(''))
+}

packages/icons/tsconfig.json

@@ -1,7 +1,7 @@
 {
   "extends": "../../tsconfig.base.json",
   "compilerOptions": {
-    "module": "ESNext",
+    "module": "CommonJS",
     "moduleResolution": "node",
     "target": "ES6",
     "outDir": "./dist",