@pwrs/cem 0.1.8 → 0.1.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/README.md +100 -56
  2. package/bin/cem.js +2 -2
  3. package/install-platform-binary.js +2 -0
  4. package/package.json +7 -5
package/README.md CHANGED
@@ -1,44 +1,28 @@
1
1
  # cem
2
2
 
3
- **cem** is a command-line tool for generating [Custom Elements Manifest](https://github.com/webcomponents/custom-elements-manifest) (CEM) files from TypeScript sources. It analyzes your codebase and generates rich metadata for your custom elements, facilitating documentation, tooling, and integration.
3
+ **cem** is a command-line tool for generating [Custom Elements Manifest][cem]
4
+ (CEM) files from TypeScript sources. It analyzes your codebase and generates
5
+ rich metadata for your custom elements, facilitating documentation, tooling, and
6
+ integration.
7
+
8
+ > [!NOTE]
9
+ > `cem` currently supports LitElements written in idiomatic style with
10
+ > TypeScript decorators. If you need something more specific,
11
+ > [open an issue][issuenew].
4
12
 
5
13
  ## Features
6
14
 
7
15
  ### `cem generate`
8
16
 
9
- - **Generates CEM files** from source code using syntax analysis powered by [go](https://go.dev) and [tree-sitter](https://tree-sitter.github.io/tree-sitter/).
17
+ - **Generates CEM files** from source code using syntax analysis powered by
18
+ [go][go] and [tree-sitter][treesitter].
10
19
  - Identifies custom elements, classes, variables, functions, and exports.
11
- - Supports elements written in idiomatic Lit typescript style, with a `@customElement` decorator, and `@property` decorators on class fields.
12
-
13
- #### HTML Template Analysis for Slots and Parts
14
-
15
- - **Automatically detects `<slot>` and `part` attributes in your element’s `render()` template.**
16
- - Extracts slot names and CSS shadow parts directly from HTML templates returned by the `render()` method.
17
- - **Supports documenting slots and parts inline in your template HTML** using HTML comments with YAML blocks. For example:
18
- ```html
19
- <!--
20
- summary: The main slot for content
21
- description: |
22
- This slot displays user-provided content.
23
- Supports multiline **markdown**.
24
- deprecated: true
25
- -->
26
- <slot></slot>
27
- ```
28
- - You can document named slots, default slots, and CSS parts:
29
- ```html
30
- <!-- slot:
31
- summary: Named slot summary
32
- part:
33
- summary: Part summary
34
- -->
35
- <slot name="info" part="info-part"></slot>
36
- ```
37
- - The tool merges slot and part information found in templates with any provided via JSDoc, ensuring comprehensive documentation in the generated manifest.
38
- - **Deprecation and other metadata** for slots and parts can be specified via YAML in HTML comments.
20
+ - Supports elements written in idiomatic Lit typescript style, with a
21
+ `@customElement` decorator, and `@property` decorators on class fields.
39
22
 
40
23
  #### JSDoc
41
- Use JSDoc comments to add metadata to your element classes, similar to other tools
24
+ Use JSDoc comments to add metadata to your element classes, similar to other
25
+ tools.
42
26
 
43
27
  - `@attr` / `@attribute` — Custom element attributes
44
28
  - `@csspart` — CSS shadow parts
@@ -49,26 +33,67 @@ Use JSDoc comments to add metadata to your element classes, similar to other too
49
33
  - `@slot` — Named or default slots
50
34
  - `@summary` — Short summary for documentation
51
35
 
36
+ #### HTML Template Analysis for Slots and Parts
37
+
38
+ - **Automatically detects `<slot>` elements and `part` attributes in your element’s
39
+ `render()` template.**
40
+ - Merges slot and part information found in templates with any provided
41
+ via JSDoc, ensuring comprehensive documentation in the generated manifest.
42
+ - **Deprecation and other metadata** for slots and parts can be specified via
43
+ YAML in HTML comments.
44
+ - **Supports documenting slots and parts inline in your template HTML** using
45
+ HTML comments with YAML blocks.
46
+ - YAML comments are not necessary to detect slots and parts, but help in
47
+ documenting them for your users.
48
+
49
+ ##### Examples
50
+ ```html
51
+ <!--
52
+ summary: The main slot for content
53
+ description: |
54
+ This slot displays user-provided content.
55
+ Supports multiline **markdown**.
56
+ deprecated: true
57
+ -->
58
+ <slot></slot>
59
+ <!-- slot:
60
+ summary: Named slot summary
61
+ part:
62
+ summary: Part summary
63
+ -->
64
+ <slot name="info" part="info-part"></slot>
65
+ ```
66
+
52
67
  #### CSS Custom Properties
53
68
  Supports CSS Custom Properties by scanning css files and css tagged-template-literals
54
69
 
55
- - Custom properties beginning with `_` will be ignored (treated as "private") e.g. `var(--_private)`
56
- - If you provide a [Design Tokens Community
57
- Group](https://tr.designtokens.org/format/) format module (JSON) to `cem` via the `--design-tokens` flag,
58
- `cem` will add metadata from your design system to any matching css variables it finds in your elements
59
- - You can use jsdoc-like comment syntax before each var call to document your
60
- variables
61
- ```css
62
- :host {
63
- color:
64
- /**
65
- * custom color for use in this element
66
- * @summary color
67
- * @deprecated just use the `color` property
68
- */
69
- var(--custom-color);
70
- }
71
- ```
70
+ - Custom properties beginning with `_` will be ignored (treated as "private")
71
+ e.g. `var(--_private)`
72
+ - If you provide a [Design Tokens Community Group][dtcg] format module (JSON) to
73
+ `cem` via the `--design-tokens` flag,
74
+ `cem` will add metadata from your design system to any matching css variables it
75
+ finds in your elements
76
+ - You can use jsdoc-like comment syntax before each var call to document your
77
+ variables
78
+
79
+ ##### Example
80
+
81
+ ```css
82
+ :host {
83
+ color:
84
+ /**
85
+ * custom color for use in this element
86
+ * @summary color
87
+ * @deprecated just use the `color` property
88
+ */
89
+ var(--custom-color);
90
+ border:
91
+ 1px
92
+ solid
93
+ /** Border color of the element */
94
+ var(--border-color);
95
+ }
96
+ ```
72
97
 
73
98
  ## Installation
74
99
 
@@ -103,17 +128,36 @@ cem generate \
103
128
  --output custom-elements.json
104
129
  ```
105
130
 
106
- for npm projects you can use `npx @pwrs/cem generate ...`, just be sure to
107
- install the package first.
131
+ For npm projects you can use `npx @pwrs/cem generate ...`.
132
+ ### Arguments
133
+ | Argument | Type | Description |
134
+ | ---------------------------- | ------------------ | ------------------------------------------------------------------------------------------------- |
135
+ | `<files or globs>` | positional (array) | Files or glob patterns to include |
136
+ | `--exclude, -e` | array | Files or glob patterns to exclude |
137
+ | `--design-tokens, -t` | string | Path or npm specifier for DTCG-format design tokens |
138
+ | `--design-tokens-prefix, -p` | string | CSS custom property prefix for design tokens |
139
+ | `--output, -o` | string | Write the manifest to this file instead of stdout |
140
+ | `--no-default-excludes` | bool | Do not exclude files by default (e.g., `.d.ts` files will be included unless excluded explicitly) |
108
141
 
109
- - `generate`: Command to start manifest generation.
110
- - Accepts file paths and glob patterns.
111
- - `--design-tokens`: path to tokens file or npm:package specifier
112
- - `--exclude` / `-e`: Specify patterns to exclude from the manifest.
113
- - `--output` / `-o`: Write the manifest to a file instead of stdout.
142
+ By default, some files (like `.d.ts` TypeScript declaration files) are excluded from the manifest.
143
+ Use `--no-default-excludes` if you want to include all matching files and manage excludes yourself.
144
+
145
+ ## Contributing
146
+
147
+ For information on building and testing, please see
148
+ [CONTRIBUTING.md][contributingmd].
114
149
 
115
150
  ## License
116
151
 
117
- This program is free software: you can redistribute it and/or modify it under the terms of the [GNU General Public License v3.0](https://www.gnu.org/licenses/gpl-3.0.html).
152
+ This program is free software: you can redistribute it and/or modify it under
153
+ the terms of the [GNU General Public License v3.0][gpl3].
118
154
 
119
155
  &copy; 2025 Benny Powers <web@bennypowers.com>
156
+
157
+ [cem]: https://github.com/webcomponents/custom-elements-manifest
158
+ [dtcg]: https://tr.designtokens.org/format/
159
+ [go]: https://go.dev
160
+ [treesitter]: https://tree-sitter.github.io/tree-sitter/
161
+ [gpl3]: https://www.gnu.org/licenses/gpl-3.0.html
162
+ [contributingmd]: ./CONTRIBUTING.md
163
+ [issuenew]: https://github.com/bennypowers/cem/issues/new
package/bin/cem.js CHANGED
@@ -9,8 +9,8 @@ const supportedTargets = new Set([
9
9
  "linux-arm64",
10
10
  "darwin-x64",
11
11
  "darwin-arm64",
12
- // "win32-x64",
13
- // "win32-arm64",
12
+ "win32-x64",
13
+ "win32-arm64",
14
14
  ]);
15
15
 
16
16
  const target = `${platform()}-${arch()}`
package/install-platform-binary.js CHANGED
@@ -6,6 +6,8 @@ const pkg = {
6
6
  "darwin-arm64": "@pwrs/cem-darwin-arm64",
7
7
  "linux-x64": "@pwrs/cem-linux-x64",
8
8
  "linux-arm64": "@pwrs/cem-linux-arm64"
9
+ "win32-x64": "@pwrs/cem-win32-x64",
10
+ "win32-arm64": "@pwrs/cem-win32-arm64"
9
11
  }[`${platform}-${arch}`];
10
12
 
11
13
  if (!pkg) {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@pwrs/cem",
3
- "version": "0.1.8",
3
+ "version": "0.1.9",
4
4
  "description": "CLI tool for generating and working with Custom Elements Manifests",
5
5
  "type": "module",
6
6
  "engines": {
@@ -13,10 +13,12 @@
13
13
  "postinstall": "node ./install-platform-binary.js"
14
14
  },
15
15
  "optionalDependencies": {
16
- "@pwrs/cem-linux-x64": "0.1.8",
17
- "@pwrs/cem-linux-arm64": "0.1.8",
18
- "@pwrs/cem-darwin-x64": "0.1.8",
19
- "@pwrs/cem-darwin-arm64": "0.1.8"
16
+ "@pwrs/cem-linux-x64": "0.1.9",
17
+ "@pwrs/cem-linux-arm64": "0.1.9",
18
+ "@pwrs/cem-darwin-x64": "0.1.9",
19
+ "@pwrs/cem-darwin-arm64": "0.1.9",
20
+ "@pwrs/cem-win32-x64": "0.1.9",
21
+ "@pwrs/cem-win32-arm64": "0.1.9"
20
22
  },
21
23
  "files": [
22
24
  "bin/cem.js",