Prepare for CEM

Author: clintcs

.changeset/twenty-pandas-brake.md

@@ -0,0 +1,21 @@
+---
+'@crowdstrike/glide-core': minor
+---
+
+- Toggle no longer has a `name` property. `name` only applies to form controls and was unused.
+- Tree Item's `hasChildTreeItems` and `hasExpandIcon` properties and its `toggleExpand()` method have been made private.
+- Tab Panel no longer has an static unused `instanceCount` property.
+
+Some internal changes we made to facillitate generating documentation programmatically forced us remove a few exported types and rename some custom properties:
+
+- Input no longer exports a `SUPPORTED_TYPES` interface.
+- Toast no longer exports a `Toast` interface. TODO: say more.
+- Tab Panel's custom properties have been renamed:
+
+  ```diff
+  - --panel-padding-inline-end
+  + --padding-inline-end
+
+  - --panel-padding-inline-start
+  + --padding-inline-start
+  ```

.husky/pre-push

@@ -1,4 +1,6 @@
 #!/bin/sh
 . "$(dirname "$0")/_/husky.sh"
 
-NODE_ENV=production pnpm typecheck && NODE_ENV=production pnpm test
+NODE_ENV=production pnpm start 
+NODE_ENV=production pnpm test 
+NODE_ENV=production pnpm typecheck 

.stylelintrc.js

@@ -6,6 +6,7 @@ export default {
     'stylelint-use-nesting',
     'stylelint-use-logical',
     'stylelint-order',
+    './dist/stylelint/plugin',
   ],
   rules: {
     // https://github.com/w3c/csswg-drafts/issues/9496
@@ -17,5 +18,6 @@ export default {
     'no-descending-specificity': null,
     'order/properties-alphabetical-order': true,
     'prettier/prettier': true,
+    'glide-core/no-unprefixed-private-custom-property': true,
   },
 };

.vscode/settings.json

@@ -1,11 +1,11 @@
 {
-  "eslint.workingDirectories": [{ "mode": "auto" }],
-  "editor.formatOnSave": true,
   "[javascript]": {
     "editor.defaultFormatter": "esbenp.prettier-vscode"
   },
-  "stylelint.validate": ["css", "postcss", "typescript"],
   "[typescript]": {
     "editor.defaultFormatter": "esbenp.prettier-vscode"
-  }
+  },
+  "editor.formatOnSave": true,
+  "eslint.workingDirectories": [{ "mode": "auto" }],
+  "stylelint.validate": ["css", "postcss", "typescript"]
 }

CONTRIBUTING.md

@@ -146,44 +146,35 @@ Embrace encapsulation wherever you can.
 
 #### Avoid styling `:host`
 
-Styling `:host` exposes the styles to consumers—allowing internal styles to be overridden.
-Due to that, we do not recommend styling `:host` in our components, but rather using CSS variables targeting the tag directly or using a class name.
+Styling `:host` exposes styles to consumers—allowing internal styles to be overridden.
+Style classes directly instead:
 
 ```css
 /* ✅ -- GOOD */
-/* Target the button tag directly */
-button {
-  background-color: var(--button-background-color);
-}
-
-/* Or use a class name <button class="button" */
 .button {
-  background-color: var(--button-background-color);
+  display: flex;
 }
 ```
 
 ```css
 /* ❌ -- BAD */
-/* Consumers can override via */
-/* <cool-button style="background-color: red" which */
-/* may not be your intention */
 :host {
-  background-color: #4095bf;
+  display: flex;
 }
 ```
 
 If you have styles or style variables that apply to the whole component, consider styling a containing element instead.
-If your component doesn't have a single containing element, you can add one:
+If your component doesn't have a single containing element, simply add one:
 
 ```ts
-// checkbox.ts
+// component.ts
 render() {
   return html`<div class="component"></div>`
 }
 ```
 
 ```ts
-// checkbox.styles.ts
+// component.styles.ts
 import { css } from 'lit';
 
 export default css`
@@ -194,26 +185,28 @@ export default css`
 
 #### Avoid exposing `part`s
 
-[`Part`s](https://developer.mozilla.org/en-US/docs/Web/CSS/::part) expose areas of your UI that consumers can target with CSS, which allows them to customize it to their needs.
-Presently, we have no use case for exposing a `part`.
-Instead, we should stick with exposing styles via CSS variables until the need arises.
+[Parts](https://developer.mozilla.org/en-US/docs/Web/CSS/::part) expose tags within components to arbitrary styling by consumers.
+We don't currently have a reason to allow arbitrary styling.
+Until we do, use custom properties to allow only certain styles to be overridden.
 
 ```ts
 // ✅ -- GOOD
 @customElement('glide-core-example')
 export default class GlideCoreExample extends LitElement {
   static override styles = css`
+    :host {
+      --font-weight: bold;
+    }
+
     .summary {
-      font-weight: var(--font-weight-bold);
+      font-weight: var(--font-weight);
     }
   `;
 
   override render() {
     return html`
       <details>
-        <!-- We style the summary directly ourselves -->
-        <summary class="summary">Details</summary>
-        <div><slot></slot></div>
+        <summary class="summary">Summary</summary>
       </details>
     `;
   }
@@ -227,9 +220,7 @@ export default class GlideCoreExample extends LitElement {
   override render() {
     return html`
       <details>
-        <!-- We do not want to expose a part -->
-        <summary part="summary">Details</summary>
-        <div><slot></slot></div>
+        <summary part="summary">Summary</summary>
       </details>
     `;
   }
@@ -352,19 +343,19 @@ Our accessibility team recommends only enabling animations when the user doesn't
 ```css
 /* ✅ -- GOOD */
 .animation {
-  background-color: purple;
+  transform: translateX(100%);
 
   @media (prefers-reduced-motion: no-preference) {
-    animation: pulse 1s linear infinite both;
+    animation: transform 1s linear;
   }
 }
 ```
 
 ```css
 /* ❌ -- BAD */
 .animation {
-  animation: pulse 1s linear infinite both;
-  background-color: purple;
+  animation: transform 1s linear;
+  transform: translateX(100%);
 }
 ```
 
@@ -552,7 +543,7 @@ There are many ways to target the root element of a component in CSS; however, w
 // ✅ -- GOOD
 css`
   .component {
-    background-color: red;
+    display: flex;
   }
 `;
 
@@ -565,7 +556,7 @@ render() {
 // ❌ -- BAD
 css`
   div {
-    background-color: red;
+    display: flex;
   }
 `;
 

eslint.config.js

@@ -45,6 +45,11 @@ export default [
       '@crowdstrike/glide-core/no-space-press': 'error',
       '@crowdstrike/glide-core/prefer-shadow-root-mode': 'error',
       '@crowdstrike/glide-core/prefixed-lit-element-class-declaration': 'error',
+      '@crowdstrike/glide-core/explicit-public-member-return-type': 'error',
+      '@crowdstrike/glide-core/public-getter-default-comment': 'error',
+      '@crowdstrike/glide-core/event-dispatch-from-this': 'error',
+      '@crowdstrike/glide-core/string-event-name': 'error',
+      '@crowdstrike/glide-core/slot-type-comment': 'error',
 
       // Enabling this rule would force us to `await` any function that returns a promise.
       // One example is a function that itself `await`s `updateComplete`. The rule is a bit
@@ -307,6 +312,11 @@ export default [
       '@crowdstrike/glide-core/no-skip-tests': 'error',
       '@crowdstrike/glide-core/no-to-have-attribute': 'error',
       '@crowdstrike/glide-core/prefer-to-be-true-or-false': 'error',
+      '@crowdstrike/glide-core/explicit-public-member-return-type': 'off',
+      '@crowdstrike/glide-core/public-getter-default-comment': 'off',
+      '@crowdstrike/glide-core/event-dispatch-from-this': 'off',
+      '@crowdstrike/glide-core/string-event-name': 'off',
+      '@crowdstrike/glide-core/slot-type-comment': 'off',
     },
   },
 ];

package.json

@@ -11,58 +11,68 @@
   },
   "files": [
     "dist",
+    "!dist/*.*.test.*.d.ts",
+    "!dist/*.*.test.*.js",
+    "!dist/*.stories.d.ts",
+    "!dist/*.stories.js",
+    "!dist/*.test.*.d.ts",
+    "!dist/*.test.*.js",
+    "!dist/cem-analyzer-plugins",
     "!dist/eslint",
     "!dist/icons/storybook.*",
     "!dist/storybook",
-    "!dist/*.test.js",
-    "!dist/*.test.*.d.ts",
-    "!dist/*.test.*.js",
-    "!dist/*.stories.js",
-    "!dist/*.stories.d.ts"
+    "!dist/stylelint",
+    "!dist/ts-morph"
   ],
   "exports": {
     "./*.js": {
       "types": "./dist/*.d.ts",
       "import": "./dist/*.js"
     },
-    "./*.styles.js": null,
-    "./library/*": null,
-    "./icons/*": null,
-    "./styles/*": null,
-    "./label.js": null,
-    "./toasts.toast.js": null,
+    "./translations/*": null,
     "./tooltip.container.js": null,
+    "./toasts.toast.js": null,
+    "./styles/variables.css": "./dist/styles/variables.css",
     "./styles/fonts.css": "./dist/styles/fonts.css",
-    "./styles/variables.css": "./dist/styles/variables.css"
+    "./styles/*": null,
+    "./library/*": null,
+    "./label.js": null,
+    "./icons/*": null,
+    "./*.styles.js": null
   },
   "scripts": {
     "start": "per-env",
-    "start:development": "storybook dev --config-dir .storybook --no-open --no-version-updates --port 6006",
-    "start:production": "rimraf ./dist && npm-run-all --parallel start:production:components start:production:storybook start:production:stylesheets --aggregate-output --print-label",
-    "start:production:components": "tsc --outDir ./dist && node ./terser.js",
+    "start:development": "npm-run-all --parallel --print-name start:development:*",
+    "start:development:storybook": "storybook dev --config-dir .storybook --no-open --no-version-updates --port 6006",
+    "start:production": "rimraf ./dist && npm-run-all --aggregate-output --print-label --parallel start:production:components start:production:storybook start:production:stylesheets",
+    "start:production:components": "tsc --noCheck --outDir ./dist && node ./terser.js",
     "start:production:figma": "pnpm dt export-variables && pnpm dt build-tokens && pnpm dt build-styles",
     "start:production:storybook": "storybook build --config-dir .storybook --disable-telemetry --output-dir ./dist/storybook",
     "start:production:stylesheets": "node ./esbuild.js",
     "format": "per-env",
-    "format:development": "prettier . --write && stylelint '**/*.styles.ts' --custom-syntax postcss-lit --fix",
-    "format:production": "prettier . --check && stylelint '**/*.styles.ts' --custom-syntax postcss-lit --no-color",
+    "format:development": "prettier . --write && stylelint",
+    "format:production": "prettier . --debug-check",
     "lint": "per-env",
-    "lint:development": "npm-run-all --print-name lint:development:*",
-    "lint:development:eslint": "tsc --outDir ./dist && eslint . --fix",
+    "lint:development": "npm-run-all --parallel --print-name lint:development:*",
+    "lint:development:eslint": "chokidar ./eslint-config.js ./src/eslint/** ./src/*.ts ./src/*.*.ts --initial --silent --command 'tsc --noCheck --outDir ./dist && eslint . --fix'",
     "lint:development:lit-analyzer": "lit-analyzer **/*.ts",
-    "lint:production": "npm-run-all --parallel --aggregate-output --print-label lint:production:*",
-    "lint:production:eslint": "tsc --outDir ./dist && eslint .",
+    "lint:development:stylelint": "chokidar ./.stylelintrc.js ./src/stylelint/** ./src/*.styles.ts ./src/*.*.styles.ts --initial --silent --command 'tsc --noCheck --outDir ./dist && stylelint '**/*.styles.ts' --custom-syntax postcss-lit --fix'",
+    "lint:production": "npm-run-all --aggregate-output --print-label --parallel lint:production:*",
+    "lint:production:eslint": "tsc --noCheck --outDir ./dist && eslint .",
     "lint:production:lit-analyzer": "lit-analyzer **/*.ts",
-    "typecheck": "tsc --noEmit",
+    "lint:production:stylelint": "tsc --noCheck --outDir ./dist && stylelint '**/*.styles.ts' --custom-syntax postcss-lit --no-color",
     "test": "per-env",
-    "test:development": "npm-run-all --parallel test:development:serve test:development:web-test-runner start:production:stylesheets",
-    "test:development:serve": "npx http-server dist/coverage/lcov-report --silent",
-    "test:development:web-test-runner": "web-test-runner --watch",
-    "test:development:vitest": "vitest --config ./vitest.config.js",
-    "test:development:vitest:comment": "Vitest is excluded from `test:development` because it muddies the console when running alongside Web Test Runner.",
-    "test:production": "npm-run-all --parallel test:production:* start:production:stylesheets --aggregate-output --print-label",
-    "test:production:vitest": "vitest run --config ./vitest.config.js",
-    "test:production:web-test-runner": "web-test-runner",
+    "test:development": "pnpm start:production:stylesheets && npm-run-all --parallel test:development:components test:development:serve-coverage",
+    "test:development:components": "web-test-runner --watch",
+    "test:development:lint-rules": "vitest --config ./vitest.config.js & chokidar './src/eslint/**' './src/stylelint/**' --ignore './src/eslint/rules/*.test.ts' './src/stylelint/*.test.ts' --initial --silent --command 'tsc --noCheck --outDir ./dist'",
+    "test:development:lint-rules:comment": "Excluded from `test:development` because Vitest muddies the console when running alongside Web Test Runner.",
+    "test:development:serve-coverage": "npx http-server dist/coverage/lcov-report --silent",
+    "test:production": "pnpm start:production:stylesheets && npm-run-all --aggregate-output --print-label --parallel test:production:*",
+    "test:production:lint-rules": "tsc --noCheck --outDir ./dist && vitest run --config ./vitest.config.js",
+    "test:production:components": "web-test-runner",
+    "typecheck": "per-env",
+    "typecheck:development": "tsc --outDir ./dist -w",
+    "typecheck:production": "tsc --outDir ./dist",
     "postinstall": "pnpm dlx [email protected] install --with-deps",
     "prepare": "is-ci || husky install",
     "release": "changeset publish"
@@ -106,6 +116,8 @@
     "@web/test-runner-commands": "^0.9.0",
     "@web/test-runner-playwright": "^0.11.0",
     "chalk": "^5.3.0",
+    "chokidar-cli": "^3.0.0",
+    "comment-parser": "^1.4.1",
     "esbuild": "^0.25.0",
     "eslint": "^9.17.0",
     "eslint-config-prettier": "^10.0.1",
@@ -123,6 +135,7 @@
     "lit": "^3.2.1",
     "lit-analyzer": "^2.0.3",
     "minify-literals": "^1.0.10",
+    "node-html-parser": "^7.0.1",
     "npm-run-all2": "^7.0.2",
     "per-env": "^1.0.2",
     "postcss": "^8.4.49",