@pwrs/cem-darwin-arm64 0.0.1
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.
- package/README.md +109 -0
- package/cem +0 -0
- package/package.json +22 -0
package/README.md
ADDED
|
@@ -0,0 +1,109 @@
|
|
|
1
|
+
# cem
|
|
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.
|
|
4
|
+
|
|
5
|
+
## Features
|
|
6
|
+
|
|
7
|
+
### `cem generate`
|
|
8
|
+
|
|
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/).
|
|
10
|
+
- 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.
|
|
39
|
+
|
|
40
|
+
#### JSDoc
|
|
41
|
+
Use JSDoc comments to add metadata to your element classes, similar to other tools
|
|
42
|
+
|
|
43
|
+
- `@attr` / `@attribute` — Custom element attributes
|
|
44
|
+
- `@csspart` — CSS shadow parts
|
|
45
|
+
- `@cssprop` / `@cssproperty` — Custom CSS properties
|
|
46
|
+
- `@cssstate` — Custom CSS states
|
|
47
|
+
- `@deprecated` — Marks a feature or member as deprecated
|
|
48
|
+
- `@event` — Custom events dispatched by the element
|
|
49
|
+
- `@slot` — Named or default slots
|
|
50
|
+
- `@summary` — Short summary for documentation
|
|
51
|
+
|
|
52
|
+
#### CSS Custom Properties
|
|
53
|
+
Supports CSS Custom Properties by scanning css files and css tagged-template-literals
|
|
54
|
+
|
|
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
|
+
```
|
|
72
|
+
|
|
73
|
+
## Installation
|
|
74
|
+
|
|
75
|
+
```sh
|
|
76
|
+
go install bennypowers.dev/cem@latest
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
Or clone this repository and build from source:
|
|
80
|
+
|
|
81
|
+
```sh
|
|
82
|
+
git clone https://github.com/bennypowers/cem.git
|
|
83
|
+
cd cem
|
|
84
|
+
make
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
## Usage
|
|
88
|
+
|
|
89
|
+
Generate a custom elements manifest from your files:
|
|
90
|
+
|
|
91
|
+
```sh
|
|
92
|
+
cem generate \
|
|
93
|
+
"src/**/*.ts" \
|
|
94
|
+
--design-tokens npm:@my-ds/tokens/tokens.json \
|
|
95
|
+
--exclude "src/**/*.test.ts" \
|
|
96
|
+
--output custom-elements.json
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
- `generate`: Command to start manifest generation.
|
|
100
|
+
- Accepts file paths and glob patterns.
|
|
101
|
+
- `--design-tokens`: path to tokens file or npm:package specifier
|
|
102
|
+
- `--exclude` / `-e`: Specify patterns to exclude from the manifest.
|
|
103
|
+
- `--output` / `-o`: Write the manifest to a file instead of stdout.
|
|
104
|
+
|
|
105
|
+
## License
|
|
106
|
+
|
|
107
|
+
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).
|
|
108
|
+
|
|
109
|
+
© 2025 Benny Powers <web@bennypowers.com>
|
package/cem
ADDED
|
Binary file
|
package/package.json
ADDED
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "@pwrs/cem-darwin-arm64",
|
|
3
|
+
"version": "0.0.1",
|
|
4
|
+
"type": "module",
|
|
5
|
+
"os": [
|
|
6
|
+
"darwin"
|
|
7
|
+
],
|
|
8
|
+
"cpu": [
|
|
9
|
+
"arm64"
|
|
10
|
+
],
|
|
11
|
+
"files": [
|
|
12
|
+
"cem"
|
|
13
|
+
],
|
|
14
|
+
"bin": {
|
|
15
|
+
"cem": "cem"
|
|
16
|
+
},
|
|
17
|
+
"engines": {
|
|
18
|
+
"node": ">=22.0.0"
|
|
19
|
+
},
|
|
20
|
+
"license": "MIT",
|
|
21
|
+
"description": "Platform-specific binary for cem on darwin-arm64"
|
|
22
|
+
}
|