@pwrs/cem 0.1.11 → 0.1.13

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 (2) hide show
  1. package/README.md +117 -26
  2. package/package.json +7 -7
package/README.md CHANGED
@@ -6,9 +6,31 @@ rich metadata for your custom elements, facilitating documentation, tooling, and
6
6
  integration.
7
7
 
8
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].
9
+ > `cem` best supports LitElements written in idiomatic style with
10
+ > TypeScript decorators. There is rudimentary support for `extends HTMLElement`,
11
+ > but it is not a high priority for development. If you need something more
12
+ > specific [open an issue][issuenew].
13
+
14
+ ## Installation
15
+
16
+ For go binaries:
17
+ ```sh
18
+ go install bennypowers.dev/cem@latest
19
+ ```
20
+
21
+ For NPM projects:
22
+
23
+ ```sh
24
+ npm install --save-dev @pwrs/cem
25
+ ```
26
+
27
+ Or clone this repository and build from source:
28
+
29
+ ```sh
30
+ git clone https://github.com/bennypowers/cem.git
31
+ cd cem
32
+ make
33
+ ```
12
34
 
13
35
  ## Features
14
36
 
@@ -22,17 +44,20 @@ integration.
22
44
 
23
45
  #### JSDoc
24
46
  Use JSDoc comments to add metadata to your element classes, similar to other
25
- tools.
47
+ tools. Add a description by separating the name of the item with ` - `
26
48
 
27
49
  - `@attr` / `@attribute` — Custom element attributes
28
50
  - `@csspart` — CSS shadow parts
29
51
  - `@cssprop` / `@cssproperty` — Custom CSS properties
30
52
  - `@cssstate` — Custom CSS states
53
+ - `@demo` — Demo URL
31
54
  - `@deprecated` — Marks a feature or member as deprecated
32
55
  - `@event` — Custom events dispatched by the element
33
56
  - `@slot` — Named or default slots
34
57
  - `@summary` — Short summary for documentation
35
58
 
59
+ See the [test-fixtures](tree/main/generate/test-fixtures/) directory for examples
60
+
36
61
  #### HTML Template Analysis for Slots and Parts
37
62
 
38
63
  - **Automatically detects `<slot>` elements and `part` attributes in your element’s
@@ -95,27 +120,86 @@ variables
95
120
  }
96
121
  ```
97
122
 
98
- ## Installation
123
+ ---
99
124
 
100
- For go binaries:
101
- ```sh
102
- go install bennypowers.dev/cem@latest
103
- ```
125
+ ## Element Demos
104
126
 
105
- For NPM projects:
127
+ `cem generate` supports documenting your elements' demos by linking directly
128
+ from JSDoc, or by configurable file-system based discovery.
106
129
 
107
- ```sh
108
- npm install --save-dev @pwrs/cem
130
+ ### 1. JSDoc `@demo` Tag
131
+
132
+ Add demos directly to your element class or members with the `@demo` tag:
133
+
134
+ ```ts
135
+ /**
136
+ * @demo https://example.com/my-element-plain/
137
+ * @demo https://example.com/my-element-fancy/ - A fancier demo with description
138
+ */
139
+ @customElement('my-element')
140
+ class MyElement extends LitElement {
141
+ // ...
142
+ }
109
143
  ```
110
144
 
111
- Or clone this repository and build from source:
145
+ Demos defined this way will always appear in your manifest for the element.
112
146
 
113
- ```sh
114
- git clone https://github.com/bennypowers/cem.git
115
- cd cem
116
- make
147
+ ### 2. Demo Discovery
148
+
149
+ `cem` can automatically discover demos from your codebase based on your
150
+ repository structure and configuration.
151
+
152
+ #### Demo Discovery Options
153
+
154
+ Configure demo discovery with the `demoDiscovery` key in your `.config/cem.yaml` file
155
+
156
+ ```yaml
157
+ sourceControlRootUrl: "https://github.com/your/repo/tree/main/"
158
+ generate:
159
+ demoDiscovery:
160
+ fileGlob: "demos/**/*.html"
161
+ urlPattern: "demos/(?P<tag>[\w-]+)/(?P<demo>[\w-]+).html"
162
+ urlTemplate: "https://example.com/elements/{tag}/{demo}/"
117
163
  ```
118
164
 
165
+ **Demo discovery options:**
166
+
167
+ | Option | Type | Description |
168
+ | ---------------------- | ------ | -------------------------------------------------------------------------------------------- |
169
+ | `fileGlob` | string | Glob pattern for discovering demo files. |
170
+ | `sourceControlRootUrl` | string | Canonical public source control URL for your repository root (on the main branch). |
171
+ | `urlPattern` | string | Pattern for generating demo URLs, e.g. `"demos/{tag}.html"`. `{tag}` is replaced by tag name.|
172
+ | `urlTemplate` | string | (optional) Alternative URL template for demo links. |
173
+
174
+ ---
175
+
176
+ ## Configuration Reference
177
+
178
+ You can configure CEM via `.config/cem.yaml`, relative to your project root,
179
+ or via CLI flags.
180
+
181
+ ### Example Configuration
182
+
183
+ ```yaml
184
+ sourceControlRootUrl: "https://github.com/your/repo/tree/main/"
185
+ generate:
186
+ files:
187
+ - "src/**/*.ts"
188
+ exclude:
189
+ - "src/**/*.test.ts"
190
+ output: "custom-elements.json"
191
+ noDefaultExcludes: false
192
+ designTokens:
193
+ spec: "npm:@my-ds/tokens/tokens.json"
194
+ prefix: "--my-ds"
195
+ demoDiscovery:
196
+ fileGlob: "demos/**/*.html"
197
+ urlPattern: "demos/(?P<tag>[\w-]+)/(?P<demo>[\w-]+).html"
198
+ urlTemplate: "https://example.com/elements/{tag}/{demo}/"
199
+ ```
200
+
201
+ ---
202
+
119
203
  ## Usage
120
204
 
121
205
  Generate a custom elements manifest from your files:
@@ -129,15 +213,22 @@ cem generate \
129
213
  ```
130
214
 
131
215
  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) |
216
+
217
+ ### Command Line Arguments
218
+
219
+ | Argument | Type | Description |
220
+ | ------------------------------- | ------------------ | ------------------------------------------------------------------------------------------------- |
221
+ | `<files or globs>` | positional (array) | Files or glob patterns to include |
222
+ | `--output, -o` | string | Write the manifest to this file instead of stdout |
223
+ | `--exclude, -e` | array | Files or glob patterns to exclude |
224
+ | `--no-default-excludes` | bool | Do not exclude files by default (e.g., `.d.ts` files will be included unless excluded explicitly) |
225
+ | `--design-tokens, -t` | string | Path or npm specifier for DTCG-format design tokens |
226
+ | `--design-tokens-prefix, -p` | string | CSS custom property prefix for design tokens |
227
+ | `--demo-discovery-file-glob` | string | Glob pattern for discovering demo files |
228
+ | `--demo-discovery-url-pattern` | string | Go Regexp pattern with named capture groups for generating canonical demo urls |
229
+ | `--demo-discovery-url-template` | string | URL pattern string using {groupName} syntax to interpolate named captures from the URL pattern |
230
+ | `--source-control-root-url` | string | Glob pattern for discovering demo files |
231
+
141
232
 
142
233
  By default, some files (like `.d.ts` TypeScript declaration files) are excluded from the manifest.
143
234
  Use `--no-default-excludes` if you want to include all matching files and manage excludes yourself.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@pwrs/cem",
3
- "version": "0.1.11",
3
+ "version": "0.1.13",
4
4
  "description": "CLI tool for generating and working with Custom Elements Manifests",
5
5
  "type": "module",
6
6
  "engines": {
@@ -13,12 +13,12 @@
13
13
  "postinstall": "node ./install-platform-binary.js"
14
14
  },
15
15
  "optionalDependencies": {
16
- "@pwrs/cem-linux-x64": "0.1.11",
17
- "@pwrs/cem-linux-arm64": "0.1.11",
18
- "@pwrs/cem-darwin-x64": "0.1.11",
19
- "@pwrs/cem-darwin-arm64": "0.1.11",
20
- "@pwrs/cem-win32-x64": "0.1.11",
21
- "@pwrs/cem-win32-arm64": "0.1.11"
16
+ "@pwrs/cem-linux-x64": "0.1.13",
17
+ "@pwrs/cem-linux-arm64": "0.1.13",
18
+ "@pwrs/cem-darwin-x64": "0.1.13",
19
+ "@pwrs/cem-darwin-arm64": "0.1.13",
20
+ "@pwrs/cem-win32-x64": "0.1.13",
21
+ "@pwrs/cem-win32-arm64": "0.1.13"
22
22
  },
23
23
  "files": [
24
24
  "bin/cem.js",