@stencil-community/web-types-output-target - npm Package Compare versions

Comparing version 0.1.0 to 0.2.0

dist/contributions/html-contributions.d.ts

@@ -6,4 +6,6 @@ import type { ComponentCompilerMeta } from '@stencil/core/internal';
  * @param componentMetadata the Stencil component metadata to generate info for to contribute to the HTML namespace
+ * @param stencilRootDir the root directory of a Stencil project
+ * @returns the symbol contributions to the HTML namespace
  */
-export declare const generateElementInfo: (componentMetadata: ComponentCompilerMeta[]) => ElementInfo[];
+export declare const generateElementInfo: (componentMetadata: ComponentCompilerMeta[], stencilRootDir: string) => ElementInfo[];
 /**
@@ -10,0 +12,0 @@ * Attribution: https://github.com/ionic-team/stencil/blob/84e1a14048bc34e64a866659d39376af605f8f9a/src/utils/helpers.ts#L79

dist/contributions/html-contributions.js

 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.unique = exports.sortBy = exports.generateElementInfo = void 0;
+const path_1 = require("path");
 // https://plugins.jetbrains.com/docs/intellij/websymbols-web-types.html#web-components
@@ -11,4 +12,6 @@ // https://github.com/JetBrains/web-types/blob/2c07137416e4151bfaf44bf3226dca7f1a5e9bd3/schema/web-types.json#L303
  * @param componentMetadata the Stencil component metadata to generate info for to contribute to the HTML namespace
+ * @param stencilRootDir the root directory of a Stencil project
+ * @returns the symbol contributions to the HTML namespace
  */
-const generateElementInfo = (componentMetadata) => {
+const generateElementInfo = (componentMetadata, stencilRootDir) => {
     return componentMetadata.map((cmpMeta) => {
@@ -24,2 +27,6 @@ // avoid serializing parts for css contributions for an element if we can avoid it
             description: cmpMeta.docs.text,
+            source: {
+                module: (0, path_1.relative)(stencilRootDir, cmpMeta.sourceFilePath),
+                symbol: cmpMeta.componentClassName,
+            },
             attributes: cmpMeta.properties
@@ -26,0 +33,0 @@ .filter((prop) => {

dist/generate-web-types.d.ts

@@ -6,5 +6,6 @@ import type { BuildCtx } from '@stencil/core/internal';
  * @param buildCtx the Stencil build context, which holds the build-time metadata for a project's Stencil components
+ * @param stencilRootDir the root directory of a Stencil project
  * @returns the generated web-types document contents
  */
-export declare const generateWebTypes: (buildCtx: BuildCtx) => WebType;
+export declare const generateWebTypes: (buildCtx: BuildCtx, stencilRootDir: string) => WebType;
 /**
@@ -11,0 +12,0 @@ * Generate the base information to be included in the Web Types file.

dist/generate-web-types.js

@@ -9,5 +9,6 @@ "use strict";
  * @param buildCtx the Stencil build context, which holds the build-time metadata for a project's Stencil components
+ * @param stencilRootDir the root directory of a Stencil project
  * @returns the generated web-types document contents
  */
-const generateWebTypes = (buildCtx) => {
+const generateWebTypes = (buildCtx, stencilRootDir) => {
     var _a, _b;
@@ -22,3 +23,3 @@ const { components, packageJson } = buildCtx;
                 // the full list can be found here: https://plugins.jetbrains.com/docs/intellij/websymbols-web-types.html#direct-support
-                elements: (0, html_contributions_1.generateElementInfo)(components),
+                elements: (0, html_contributions_1.generateElementInfo)(components, stencilRootDir),
             },
@@ -25,0 +26,0 @@ js: {

dist/index.d.ts

@@ -37,2 +37,15 @@ import type { OutputTargetCustom } from '@stencil/core/internal';
     description: string;
+    /**
+     * Link the custom HTML element back to the Stencil component
+     */
+    source: {
+        /**
+         * The TSX file containing the definition of the component, relative to the generated web-types.json
+         */
+        module: string;
+        /**
+         * The exported symbol (i.e. the Stencil component name)
+         */
+        symbol: string;
+    };
     attributes: AttributeInfo[];
@@ -39,0 +52,0 @@ /**

dist/index.js

@@ -31,6 +31,19 @@ "use strict";
     name: 'web-types-output-target',
-    generator(_config, compilerCtx, buildCtx) {
+    validate(config, _diagnostics) {
+        if (typeof config.rootDir === 'undefined') {
+            // defer to Stencil to create & load ths into its diagnostics, rather than us having to generate one ourselves
+            throw new Error('Unable to determine the Stencil root directory. Exiting without generating web types.');
+        }
+    },
+    generator(config, compilerCtx, buildCtx) {
         return __awaiter(this, void 0, void 0, function* () {
             const timespan = buildCtx.createTimeSpan('generate web-types started', true);
-            const webTypes = (0, generate_web_types_js_1.generateWebTypes)(buildCtx);
+            /**
+             * One source of truth to rule them all - plus, this makes testing a skosh easier, as we can mock easily.
+             * This should have been validated in the `validate` fn, hence the bang operator - Stencil doesn't allow us to
+             * return a value from `validate`, which makes a type guard that gets used in `validate` unusable in any meaningful
+             * way in `generator`
+             */
+            const stencilRootDirectory = config.rootDir;
+            const webTypes = (0, generate_web_types_js_1.generateWebTypes)(buildCtx, stencilRootDirectory);
             yield compilerCtx.fs.writeFile('web-types.json', JSON.stringify(webTypes, null, 2));
@@ -37,0 +50,0 @@ timespan.finish('generate web-types finished');

package.json

 {
   "name": "@stencil-community/web-types-output-target",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "an experimental stencil output target supporting web-types",
@@ -28,4 +28,5 @@ "main": "dist/index.js",
     "@stencil/core": "^4.13.0",
+    "@types/node": "^20.12.8",
     "@vitest/coverage-v8": "^1.5.0",
-    "prettier": "3.2.4",
+    "prettier": "3.2.5",
     "release-it": "^17.2.0",
@@ -37,5 +38,5 @@ "typescript": "^5.4.3",
   "volta": {
-    "node": "20.12.0",
-    "npm": "10.5.0"
+    "node": "20.12.2",
+    "npm": "10.6.0"
   }
 }

README.md

@@ -1,26 +0,44 @@
-# Stencil Web-Types Output Target
+# Stencil Web Types Output Target
 
-A Stencil output target for generating [web-types](https://plugins.jetbrains.com/docs/intellij/websymbols-web-types.html#file-structure) to provide intellisense for Stencil components for HTML files.
+<p align="center">
+  <a href="https://www.npmjs.com/package/@stencil-community/web-types-output-target">
+    <img src="https://img.shields.io/npm/v/@stencil-community/web-types-output-target.svg" alt="The npm package version" /></a>
+  <a href="https://github.com/ionic-team/stencil/blob/main/LICENSE.md">
+    <img src="https://img.shields.io/badge/license-MIT-yellow.svg" alt="Released under the MIT license." />
+  </a>
+  <a href="https://github.com/stencil-community/stencil-web-types/blob/main/CONTRIBUTING.md">
+    <img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg" alt="PRs welcome!" />
+  </a>
+  <a href="https://twitter.com/stenciljs">
+    <img src="https://img.shields.io/badge/follow-%40stenciljs-1DA1F2?logo=twitter" alt="Follow @stenciljs">
+  </a>
+  <a href="https://chat.stenciljs.com">
+    <img src="https://img.shields.io/discord/520266681499779082?color=7289DA&label=%23stencil&logo=discord&logoColor=white" alt="Official Ionic Discord" />
+  </a>
+</p>
 
+A Stencil output target for generating [web types](https://plugins.jetbrains.com/docs/intellij/websymbols-web-types.html#file-structure) to provide intellisense for Stencil components in HTML files.
+
 > [!NOTE]
-> This package is experimental - It's pre-v1.0, things may change over time.
+> This package follows [semantic versioning](https://semver.org).
+> Small breaking changes to the API may occur prior to hitting v1.0.
 
 ## Overview
 
-One of the core features of web components is the ability to create [custom elements](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements), which allow developers to reuse custom functionality defined in their components.
+One of the core features of web components is the ability to create [custom elements](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements), which allow developers to reuse custom functionality defined by their components.
 When Stencil compiles a project, it generates a custom element for each component in the project.
-Each of these [custom elements has an associated `tag` name](../components/component.md#component-options) that allows the custom element to be used in HTML files.
 
-By default, integrated development environments (IDEs) like JetBrains' WebStorm are not aware of a project's custom elements when authoring HTML.
-In order to enable more intelligent features in JetBrains products such as auto-completion, hover tooltips, etc., developers need to inform it of their project's custom elements.
+By default, integrated development environments (IDEs) like JetBrains' WebStorm are not aware of a project's custom elements.
+This causes the IDE to often warn developers that it doesn't have any information about their custom elements, and results in a poorer developement experience.
+In order to enable more intelligent features in JetBrains products, such as auto-completion, hover tooltips, etc., developers need to inform it of their project's custom elements.
 
-The `docs-web-types` output target tells Stencil to generate a JSON file containing this information.
+The `webTypesOutputTarget` output target tells Stencil to generate a JSON file containing this information.
 
-This is an opt-in feature and will save a JSON file containing web-types in a directory specified by the output target.
-Once the feature is enabled and your IDE is informed of the JSON file's location, HTML files can gain code editing features similar to TSX files.
+This is an opt-in feature and will write a JSON file containing web types in a directory specified by the output target.
+Once the feature is enabled and your IDE is informed of the JSON file's location, writing code in HTML files will have similar intellisense to that of TSX files.
 
 ## Set Up
 
-The web-types output target is not built in to Stencil itself.
-Instead, it's a third party package, that needs to be installed as a dev dependency:
+The output target is not built in to Stencil itself.
+It's a third party package, that needs to be installed as a dev-dependency:
 ```bash
@@ -30,3 +48,3 @@ $ npm i --save-dev @stencil-community/web-types-output-target
 
-To generate custom element information for JetBrains IDE's, add the `docs-web-types` output target to your `stencil.config.ts`:
+To generate custom element information for JetBrains IDE's, add the `webTypesOutputTarget` output target to your `stencil.config.ts`:
 ```tsx
@@ -43,8 +61,8 @@ import { Config } from '@stencil/core';
 
-To generate the JSON file, have Stencil build your project.
-Stencil will write a `web-types.json` to your project's root directory.
+Stencil will write a `web-types.json` to your project's root directory the next time the Stencil [build task](https://stenciljs.com/docs/cli#stencil-build) is run.
 
 ## Usage
 
-Web Types for your project can be picked by JetBrains IDEs by setting the `web-types` property in your project's `package.json` file:
+Once web types have been written to disk, they need to be picked up by the IDE.
+Web types for your project can be picked by JetBrains IDEs by setting the `web-types` property at the root level of your project's `package.json` file:
 
@@ -61,3 +79,3 @@ ```json
 Having this file locally on disk will allow your JetBrains IDE to pick up additional typings automatically.
-To provide these IDE-specific typings to users of your library, be sure to include the generated web-types file in your package's distributable by adding it to your `package.json#files` array.
+To provide these IDE-specific typings to users of your library, be sure to include the generated web types file in your package's distributable by adding it to your `package.json#files` array.
 
@@ -64,0 +82,0 @@ ## References

No alert changes

Improved metrics

Total package byte prevSize

26303

increased by13.38%

Lines of code

457

increased by8.81%

Number of lines in readme file

82

increased by28.13%

Worsened metrics

Dev dependency count

9

increased by12.5%

No dependency changes