@pwrs/cem 0.1.13 → 0.1.14

package/README.md

@@ -1,36 +1,17 @@
 # cem
 
-**cem** is a command-line tool for generating [Custom Elements Manifest][cem]
-(CEM) files from TypeScript sources. It analyzes your codebase and generates
+**cem** is a command-line tool for generating and querying
+[Custom Elements Manifest][cem] files. It can analyze your codebase and generate
 rich metadata for your custom elements, facilitating documentation, tooling, and
-integration.
-
-> [!NOTE]
-> `cem` best supports LitElements written in idiomatic style with
-> TypeScript decorators. There is rudimentary support for `extends HTMLElement`,
-> but it is not a high priority for development. If you need something more
-> specific [open an issue][issuenew].
+integration. It can also query that manifest for information about your package
 
 ## Installation
 
-For go binaries:
-```sh
-go install bennypowers.dev/cem@latest
-```
-
-For NPM projects:
-
 ```sh
 npm install --save-dev @pwrs/cem
 ```
 
-Or clone this repository and build from source:
-
-```sh
-git clone https://github.com/bennypowers/cem.git
-cd cem
-make
-```
+For more options, see [Installation docs][installationdocs]
 
 ## Features
 
@@ -42,6 +23,12 @@ make
 - Supports elements written in idiomatic Lit typescript style, with a
 `@customElement` decorator, and `@property` decorators on class fields.
 
+> [!NOTE]
+> `cem generate` best supports LitElements written in idiomatic style with
+> TypeScript decorators. There is rudimentary support for `extends HTMLElement`,
+> but it is not a high priority for development. If you need something more
+> specific [open an issue][issuenew].
+
 #### JSDoc
 Use JSDoc comments to add metadata to your element classes, similar to other
 tools. Add a description by separating the name of the item with ` - `
@@ -122,12 +109,12 @@ variables
 
 ---
 
-## Element Demos
+#### Element Demos
 
 `cem generate` supports documenting your elements' demos by linking directly
 from JSDoc, or by configurable file-system based discovery.
 
-### 1. JSDoc `@demo` Tag
+##### 1. JSDoc `@demo` Tag
 
 Add demos directly to your element class or members with the `@demo` tag:
 
@@ -144,7 +131,7 @@ class MyElement extends LitElement {
 
 Demos defined this way will always appear in your manifest for the element.
 
-### 2. Demo Discovery
+##### 2. Demo Discovery
 
 `cem` can automatically discover demos from your codebase based on your
 repository structure and configuration.
@@ -171,36 +158,7 @@ generate:
 | `urlPattern`           | string | Pattern for generating demo URLs, e.g. `"demos/{tag}.html"`. `{tag}` is replaced by tag name.|
 | `urlTemplate`          | string | (optional) Alternative URL template for demo links.                                          |
 
----
-
-## Configuration Reference
-
-You can configure CEM via `.config/cem.yaml`, relative to your project root,
-or via CLI flags.
-
-### Example Configuration
-
-```yaml
-sourceControlRootUrl: "https://github.com/your/repo/tree/main/"
-generate:
-  files:
-    - "src/**/*.ts"
-  exclude:
-    - "src/**/*.test.ts"
-  output: "custom-elements.json"
-  noDefaultExcludes: false
-  designTokens:
-    spec: "npm:@my-ds/tokens/tokens.json"
-    prefix: "--my-ds"
-  demoDiscovery:
-    fileGlob: "demos/**/*.html"
-    urlPattern: "demos/(?P<tag>[\w-]+)/(?P<demo>[\w-]+).html"
-    urlTemplate: "https://example.com/elements/{tag}/{demo}/"
-```
-
----
-
-## Usage
+#### Usage
 
 Generate a custom elements manifest from your files:
 
@@ -214,7 +172,7 @@ cem generate \
 
 For npm projects you can use `npx @pwrs/cem generate ...`.
 
-### Command Line Arguments
+##### Command Line Arguments
 
 | Argument                        | Type               | Description                                                                                       |
 | ------------------------------- | ------------------ | ------------------------------------------------------------------------------------------------- |
@@ -228,11 +186,71 @@ For npm projects you can use `npx @pwrs/cem generate ...`.
 | `--demo-discovery-url-pattern`  | string             | Go Regexp pattern with named capture groups for generating canonical demo urls                    |
 | `--demo-discovery-url-template` | string             | URL pattern string using {groupName} syntax to interpolate named captures from the URL pattern    |
 | `--source-control-root-url`     | string             | Glob pattern for discovering demo files                                                           |
-
+| `--project-dir`                 | string             | Specify the project root directory to use for resolving relative paths and configuration.         |
 
 By default, some files (like `.d.ts` TypeScript declaration files) are excluded from the manifest.
 Use `--no-default-excludes` if you want to include all matching files and manage excludes yourself.
 
+---
+
+### `cem list`
+
+The `cem list` command provides a fast, flexible way to inspect custom elements, their features, and their metadata directly from your manifest file.
+With `cem list`, you can quickly explore and audit your custom elements API surface, making it easier to document, test, and share your components.
+
+#### Available Subcommands
+
+- `cem list tags` — Lists all custom element tag names in the project.
+- `cem list -t <tag> attrs` — Lists all attributes for a given custom element tag.
+- `cem list -t <tag> slots` — Lists all named and default slots for a tag.
+- `cem list -t <tag> events` — Lists all custom events fired by a tag, including their types and descriptions.
+- `cem list -t <tag> css-properties` — Lists CSS custom properties (CSS variables) for a tag.
+- `cem list -t <tag> css-states` — Lists CSS custom states for a tag.
+- `cem list -t <tag> css-parts` — Lists CSS shadow parts for a tag.
+- `cem list -t <tag> methods` — Lists methods for a tag's DOM object.
+
+#### Column Filtering and Output
+
+- Use the `--columns,-c` flag to specify which columns to include in the output, e.g.:
+
+  ```sh
+  cem list events my-element -c name -c summary -c type
+  cem list attrs my-element -c description --columns default
+  ```
+Note that the name column is always included, and that if a column is specified but contains only empty values for all rows, it is automatically omitted from the output for clarity.
+
+#### Output Formats
+
+- By default, tables are shown in a human-readable table format.
+- [ ] TODO: json, markdown, flat lists, etc
+
+## Configuration Reference
+
+You can configure CEM via `.config/cem.yaml`, relative to your project root,
+or via CLI flags.
+
+### Example Configuration
+
+```yaml
+sourceControlRootUrl: "https://github.com/your/repo/tree/main/"
+generate:
+  files:
+    - "src/**/*.ts"
+  exclude:
+    - "src/**/*.test.ts"
+  output: "custom-elements.json"
+  noDefaultExcludes: false
+  designTokens:
+    spec: "npm:@my-ds/tokens/tokens.json"
+    prefix: "--my-ds"
+  demoDiscovery:
+    fileGlob: "demos/**/*.html"
+    urlPattern: "demos/(?P<tag>[\w-]+)/(?P<demo>[\w-]+).html"
+    urlTemplate: "https://example.com/elements/{tag}/{demo}/"
+```
+
+---
+
 ## Contributing
 
 For information on building and testing, please see
@@ -252,3 +270,4 @@ the terms of the [GNU General Public License v3.0][gpl3].
 [gpl3]: https://www.gnu.org/licenses/gpl-3.0.html
 [contributingmd]: ./CONTRIBUTING.md
 [issuenew]: https://github.com/bennypowers/cem/issues/new
+[installationdocs]: https://bennypowers.github.io/cem/installation/

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pwrs/cem",
-  "version": "0.1.13",
+  "version": "0.1.14",
   "description": "CLI tool for generating and working with Custom Elements Manifests",
   "type": "module",
   "engines": {
@@ -13,12 +13,12 @@
     "postinstall": "node ./install-platform-binary.js"
   },
   "optionalDependencies": {
-    "@pwrs/cem-linux-x64": "0.1.13",
-    "@pwrs/cem-linux-arm64": "0.1.13",
-    "@pwrs/cem-darwin-x64": "0.1.13",
-    "@pwrs/cem-darwin-arm64": "0.1.13",
-    "@pwrs/cem-win32-x64": "0.1.13",
-    "@pwrs/cem-win32-arm64": "0.1.13"
+    "@pwrs/cem-linux-x64": "0.1.14",
+    "@pwrs/cem-linux-arm64": "0.1.14",
+    "@pwrs/cem-darwin-x64": "0.1.14",
+    "@pwrs/cem-darwin-arm64": "0.1.14",
+    "@pwrs/cem-win32-x64": "0.1.14",
+    "@pwrs/cem-win32-arm64": "0.1.14"
   },
   "files": [
     "bin/cem.js",