feat: create docs package for solid components (#1550)

This PR is intended to create a separate package which will include all documentation related to SDS. It's part of [#1131](#1131) --------- Co-authored-by: mariohamann <[email protected]>
solid-design-system · Nov 8, 2024 · 7555d18 · 7555d18
1 parent 5249cf2
commit 7555d18
Show file tree

Hide file tree

Showing 343 changed files with 11,284 additions and 9,295 deletions.
diff --git a/.eslintignore b/.eslintignore
@@ -6,5 +6,8 @@ packages/components/src/react
 packages/components/src/_components
 packages/components/scripts
 packages/components/custom-elements-manifest.config.ts
+packages/docs/src/stories
+packages/docs/scripts
+packages/docs/custom-elements-manifest.config.ts
 packages/theming/types/
 packages/placeholders/types/
diff --git a/.eslintrc.cjs b/.eslintrc.cjs
@@ -139,6 +139,93 @@ module.exports = {
         '@typescript-eslint/no-unsafe-call': 'off',
         '@typescript-eslint/no-unused-expressions': 'off'
       }
+    },
+    {
+      extends: [
+        'plugin:@typescript-eslint/eslint-recommended',
+        'plugin:@typescript-eslint/recommended',
+        'plugin:@typescript-eslint/recommended-requiring-type-checking'
+      ],
+      parser: '@typescript-eslint/parser',
+      parserOptions: {
+        sourceType: 'module',
+        tsconfigRootDir: __dirname,
+        project: ['./packages/docs/tsconfig.json']
+      },
+      files: ['packages/docs/**/*.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/non-nullable-type-assertion-style': 'warn',
+        '@typescript-eslint/prefer-for-of': 'warn',
+        '@typescript-eslint/prefer-optional-chain': 'warn',
+        '@typescript-eslint/prefer-ts-expect-error': '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',
+        '@typescript-eslint/method-signature-style': 'warn',
+        '@typescript-eslint/no-extraneous-class': 'error',
+        '@typescript-eslint/strict-boolean-expressions': 'off',
+        'no-restricted-imports': [
+          'error',
+          {
+            paths: [
+              {
+                name: 'lit/decorators.js',
+                importNames: ['customElement'],
+                message: "Use import 'customElement' from '../../../src/internal/register-custom-element' instead."
+              },
+              {
+                name: 'lit/decorators/custom-element.js',
+                importNames: ['customElement'],
+                message: "Use import 'customElement' from '../../../src/internal/register-custom-element' instead."
+              }
+            ]
+          }
+        ],
+        'lit-a11y/no-aria-slot': 'off'
+      }
     }
   ],
   rules: {

diff --git a/.github/workflows/check-pr.yml b/.github/workflows/check-pr.yml
@@ -32,9 +32,9 @@ jobs:
 
             - name: verify lint, format and not-components
               run: pnpm lint.verify && pnpm format.verify && pnpm --recursive --if-present --filter="\!components" verify
-            
+
             - name: verify components without tests
-              run : cd packages/components && pnpm ts.verify && pnpm build && echo '✅ Build verified' && node ./scripts/node-optimize-chromatic.cjs && echo '✅ Chromatic optimization verified'
+              run : cd packages/docs && pnpm ts.verify && pnpm build && echo '✅ Build verified' && node ./scripts/node-optimize-chromatic.cjs && echo '✅ Chromatic optimization verified'
 
     # Check Chromatic for visual changes after all other checks have passed
     chromatic-deployment-pr:
@@ -56,7 +56,7 @@ jobs:
           run: PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=true pnpm i
         # 👇 Build storybook with pnpm
         - name: Build storybook
-          run: cd packages/components && pnpm run build.chromatic
+          run: cd packages/docs && pnpm run build.chromatic
         # 👇 Adds Chromatic as a step in the workflow
         - name: Publish to Chromatic
           uses: chromaui/action@latest
@@ -69,7 +69,7 @@ jobs:
             # TurboSnap is an advanced Chromatic feature that speeds up builds for faster UI testing and review using Git and Webpack’s dependency graph
             onlyChanged: false
             # We need to manually build storybook with pnpm
-            storybookBuildDir: packages/components/dist/storybook
+            storybookBuildDir: packages/docs/dist/storybook
 
     quality-gate:
       name: Test components (do locally if failing)

diff --git a/.github/workflows/chromatic-main.yml b/.github/workflows/chromatic-main.yml
@@ -27,7 +27,7 @@ jobs:
         run: PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=true pnpm i
       # 👇 Build storybook with pnpm
       - name: Build storybook
-        run: cd packages/components && pnpm run build.chromatic
+        run: cd packages/docs && pnpm run build.chromatic
       # 👇 Adds Chromatic as a step in the workflow
       - name: Publish to Chromatic
         uses: chromaui/action@latest
@@ -40,4 +40,4 @@ jobs:
           # We don't need tests in the main branch, but want to accept everything
           autoAcceptChanges: true
           # We need to manually build storybook with pnpm
-          storybookBuildDir: packages/components/dist/storybook
+          storybookBuildDir: packages/docs/dist/storybook
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -20,9 +20,9 @@ jobs:
           persist-credentials: false
 
       - name: Setup pnpm
-        uses: pnpm/action-setup@v2
+        uses: pnpm/action-setup@v4
         with:
-          version: 8.6.2
+          version: 9
 
       - name: Install dependencies
         run: PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=true pnpm i
@@ -50,3 +50,8 @@ jobs:
           GH_TOKEN: ${{ secrets.PAT_RELEASE_KARL }}
           NPM_TOKEN: ${{ secrets.NPM_RELEASE_TOKEN_MARIO_HAMANN }}
         run: cd packages/theming && pnpm release
+
+      - name: (docs) Run Semantic Release
+        env:
+          GH_TOKEN: ${{ secrets.PAT_RELEASE_KARL }}
+        run: cd packages/docs && pnpm release
diff --git a/.github/workflows/upload-storybook-to-github-pages.yml b/.github/workflows/upload-storybook-to-github-pages.yml
@@ -50,13 +50,13 @@ jobs:
         run: pnpm i
 
       - name: Build storybook
-        run: cd packages/components && pnpm run build/storybook
+        run: cd packages/docs && pnpm run build
 
       - name: Prepare deployment directory
         run: |
           mkdir -p deployment/archives
           mkdir -p deployment/${{ env.GITHUB_SAFE_BRANCH }}
-          cp -r packages/components/dist/storybook/* deployment/${{ env.GITHUB_SAFE_BRANCH }}/
+          cp -r packages/docs/dist/storybook/* deployment/${{ env.GITHUB_SAFE_BRANCH }}/
 
       - name: Create archive
         run: |

diff --git a/DEVELOPER_STARTING_GUIDE.md b/DEVELOPER_STARTING_GUIDE.md
@@ -60,13 +60,15 @@ A good rule of thumb: **when in doubt, refer to Shoelace!**
 
 ## Storybook
 
-We present the library in a [Storybook](https://storybook.js.org/) with the following sections:
+We present the library in a [Storybook](https://storybook.js.org/) running on the **\*DOCS** package with the following sections:
 
 - **DOCS**: All .mdx documentation files.
+- **PACKAGES**: Information about each of the SDS packages.
 - **COMPONENTS**: Web Components built with Lit JS. Often more complex than Styles, and could feature reactivity, state, multiple slots, properties, and more.
 - **UTILITIES**: Web Components built with Lit JS, used as SDS-internal helper components. Technically necessary to build other components and generic enough to be used multiple times. Not officially part of the design system library and no respective component existing in Figma.
 - **STYLES**: These are standalone CSS files. They don't provide any logic and are often non-interactive.
 - **PATTERN**: Demonstrate how to combine several components to solve a specific problem.
+- **LEGAL**: Contains legal information.
 
 Each component / utility / style / pattern contains both [docs](https://storybook.js.org/addons/@storybook/addon-docs) and [stories](https://storybook.js.org/docs/writing-stories):
 
@@ -104,7 +106,7 @@ These will allow you to do things like present various properties along two axes
 
 If you are working on a component, follow the steps below:
 
-1. Move the component folder from `packages/components/src/_components` to `packages/components/src/components` or run `$pnpm plop` to generate a blank component template.
+1. Move the component folder from `packages/components/src/_components` to `packages/components/src/components` or run `$pnpm plop` to generate a blank component template. All `*.stories.ts` and `*.test.stories.ts` should be moved into `packages/docs/src/stories`.
 2. **Open the component's Storybook Docs or default Story.** Ensure this is working properly. You'll want to have a place to observe the component as you work.
 3. **Check the [Shoelace repo components folder](https://github.com/shoelace-style/shoelace/tree/next/src/components) for the latest published component code.** If you need to re-copy updated source code, ensure you _copy the whole component folder not just the component file_ (includes tests and styles) AND rename contained imports, variables, components etc... prefixed with `sl` to `sd` (e.g. `sl-component` becomes `sd-component` ) and likewise `Shoelace` to `Solid` (e.g. `ShoelaceFormControl` becomes `SolidFormControl`).
 4. **Remove any properties from the copied Shoelace code that are irrelevant to our design** (e.g. `pill` is a re-occurring prop in Shoelace that alters a component's border radius, our designs do not offer this). Refer to the [Figma design documentation](https://www.figma.com/files/1075429990769806468/project/67503549/Solid-DS-Documentation?fuid=883643809929820461) for the component you are working on.
@@ -146,11 +148,7 @@ Renovate also creates a “Dependency Dashboard” ticket to track all found upd
       - **`components`**: Primary folder containing our Web Components. Added as stories in the "COMPONENTS" section.
         - `accordion`: Lit JS web component that implements an accordion. The comments are automatically compiled into the Storybook docs and should be used for user clarification.
         - `accordion.tests.ts`: Suite of jest tests for the accordion component. Critical for deployment and maintenance.
-        - `accordion.stories.ts`: Collection of Storybook stories that are primarily used for visual testing with Chromatic. Any **samples** are added as stories here.
-      - `docs`: all ".mdx" doc files that appear in the "DOCS" section of our Storybook
-        - `migration`: Individual component migration guides
       - `internal`: A set of utilities that are reusable internally. Check here should you need something like a debounce, it may have already been implemented.
-      - **`patterns`**: Demonstrate how to combine several components to solve a specific problem. Added as stories in the "PATTERNS" section.
       - **`styles`**: These are standalone CSS files. They don't provide any logic and are often non-interactive. Added as stories in the "STYLES" section.
 
 ## Technologies

diff --git a/package.json b/package.json
@@ -48,7 +48,8 @@
   },
   "pnpm": {
     "patchedDependencies": {
-      "[email protected]": "patches/[email protected]"
+      "[email protected]": "patches/[email protected]",
+      "[email protected]": "patches/[email protected]"
     }
   }
 }
diff --git a/packages/components/.storybook/manager-head.html b/packages/components/.storybook/manager-head.html
diff --git a/packages/components/LICENSE.md b/packages/components/LICENSE.md
@@ -8,15 +8,3 @@ Permission is hereby granted, free of charge, to any person obtaining a copy of
 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.
-
-# ASSETS
-
-All code contained in this library is licensed under the [MIT License](LICENSE.md). However, please note that this does not extend to the included assets such as fonts, icons, or images.
-
-These assets are subject to their respective licenses and are included for demonstration purposes and use within the confines of this library. They should not be extracted and used separately without explicit permission from their copyright holders. The unauthorized use of these assets outside the context of this library may infringe on the rights of the respective copyright owners.
-
-If you intend to use any assets outside of this library, you must obtain the necessary permissions from the copyright holders or replace them with your own or license-free alternatives. Failure to comply with asset licensing requirements may result in legal consequences.
-
-Please consult the copyright holders or their licensing documents for further information on using these assets.
-
-> Explicit note on logos: All logos used in this repository are the property of their respective companies and are licensed accordingly. Unauthorized use, reproduction, or distribution of these logos is prohibited without explicit permission from the respective trademark holders.
diff --git a/packages/components/README.md b/packages/components/README.md
@@ -1,5 +1,7 @@
-[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
-![NPM Version](https://img.shields.io/npm/v/%40solid-design-system%2Fcomponents)
+<div className="flex gap-2">
+  ![MIT License](https://img.shields.io/badge/License-MIT-green.svg)
+  ![NPM Version](https://img.shields.io/npm/v/%40solid-design-system%2Fcomponents)
+</div>
 
 # Solid
 

diff --git a/packages/components/custom-elements-manifest.config.ts b/packages/components/custom-elements-manifest.config.ts
@@ -3,7 +3,6 @@
 
 import { generateCustomData } from 'cem-plugin-vs-code-custom-data-generator';
 import { parse } from 'comment-parser';
-// import { pascalCase } from 'pascal-case';
 
 import { author, description, homepage, license, name, version } from './package.json';
 
@@ -19,16 +18,6 @@ function replace(string: string, terms: { from: string; to: string }[]) {
   return string;
 }
 
-// function isQueryDecorator(decorator) {
-//   return decorator.name === 'query';
-// }
-
-// function markMemberAsPrivate(member) {
-//   if (member.decorators?.some(isQueryDecorator)) {
-//     member.privacy = 'private';
-//   }
-// }
-
 export default {
   files: ['./src/components/**/!(*.stories|*.spec|*.test|*.style).ts'],
   lit: true,
@@ -181,5 +170,5 @@ export default {
       outdir: 'dist',
       cssFileName: null
     })
-  ]
+  ] as any[]
 };