├── .gitignore ├── .husky ├── .gitignore └── pre-commit ├── .prettierignore ├── .prettierrc ├── .storybook ├── code-bubble-setup.js ├── custom-elements.json ├── main.ts ├── preview.ts └── styles.css ├── .vscode └── extensions.json ├── CHANGELOG.md ├── LICENSE ├── README.md ├── assets └── demo.gif ├── custom-elements-manifest.config.js ├── custom-elements.json ├── eslint.config.js ├── index.d.ts ├── index.js ├── package.json ├── plop-templates ├── component.definition.ts.hbs ├── component.docs.hbs ├── component.stories.ts.hbs ├── component.styles.ts.hbs ├── component.test.ts.hbs └── component.ts.hbs ├── plopfile.js ├── pnpm-lock.yaml ├── rollup.config.js ├── src ├── components │ ├── base │ │ └── dox-base.ts │ ├── css-parts │ │ ├── css-parts.mdx │ │ ├── css-parts.stories.ts │ │ ├── css-parts.styles.ts │ │ ├── css-parts.test.ts │ │ └── css-parts.ts │ ├── css-props │ │ ├── css-props.mdx │ │ ├── css-props.stories.ts │ │ ├── css-props.styles.ts │ │ ├── css-props.test.ts │ │ └── css-props.ts │ ├── css-states │ │ ├── css-states.mdx │ │ ├── css-states.stories.ts │ │ ├── css-states.styles.ts │ │ ├── css-states.test.ts │ │ └── css-states.ts │ ├── dox │ │ ├── dox.mdx │ │ ├── dox.stories.ts │ │ ├── dox.styles.ts │ │ ├── dox.test.ts │ │ └── dox.ts │ ├── events │ │ ├── events.mdx │ │ ├── events.stories.ts │ │ ├── events.styles.ts │ │ ├── events.test.ts │ │ └── events.ts │ ├── imports │ │ ├── imports.mdx │ │ ├── imports.stories.ts │ │ ├── imports.styles.ts │ │ ├── imports.test.ts │ │ └── imports.ts │ ├── methods │ │ ├── methods.mdx │ │ ├── methods.stories.ts │ │ ├── methods.styles.ts │ │ ├── methods.test.ts │ │ └── methods.ts │ ├── props │ │ ├── props.mdx │ │ ├── props.stories.ts │ │ ├── props.styles.ts │ │ ├── props.test.ts │ │ └── props.ts │ └── slots │ │ ├── slots.mdx │ │ ├── slots.stories.ts │ │ ├── slots.styles.ts │ │ ├── slots.test.ts │ │ └── slots.ts ├── configs │ ├── default-values.ts │ ├── index.ts │ └── types.ts ├── index.ts └── utils │ ├── cem-tools.ts │ ├── deep-merge.ts │ ├── define.ts │ └── markdown.ts ├── tsconfig.json └── web-test-runner.config.js /.gitignore: -------------------------------------------------------------------------------- 1 | # Logs 2 | logs 3 | *.log 4 | npm-debug.log* 5 | yarn-debug.log* 6 | yarn-error.log* 7 | lerna-debug.log* 8 | .pnpm-debug.log* 9 | 10 | # Diagnostic reports (https://nodejs.org/api/report.html) 11 | report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json 12 | 13 | # Runtime data 14 | pids 15 | *.pid 16 | *.seed 17 | *.pid.lock 18 | 19 | # Directory for instrumented libs generated by jscoverage/JSCover 20 | lib-cov 21 | 22 | # Coverage directory used by tools like istanbul 23 | coverage 24 | *.lcov 25 | 26 | # nyc test coverage 27 | .nyc_output 28 | 29 | # Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files) 30 | .grunt 31 | 32 | # Bower dependency directory (https://bower.io/) 33 | bower_components 34 | 35 | # node-waf configuration 36 | .lock-wscript 37 | 38 | # Compiled binary addons (https://nodejs.org/api/addons.html) 39 | build/Release 40 | 41 | # Dependency directories 42 | node_modules/ 43 | jspm_packages/ 44 | 45 | # Snowpack dependency directory (https://snowpack.dev/) 46 | web_modules/ 47 | 48 | # TypeScript cache 49 | *.tsbuildinfo 50 | 51 | # Optional npm cache directory 52 | .npm 53 | 54 | # Optional eslint cache 55 | .eslintcache 56 | 57 | # Optional stylelint cache 58 | .stylelintcache 59 | 60 | # Microbundle cache 61 | .rpt2_cache/ 62 | .rts2_cache_cjs/ 63 | .rts2_cache_es/ 64 | .rts2_cache_umd/ 65 | 66 | # Optional REPL history 67 | .node_repl_history 68 | 69 | # Output of 'npm pack' 70 | *.tgz 71 | 72 | # Yarn Integrity file 73 | .yarn-integrity 74 | 75 | # dotenv environment variable files 76 | .env 77 | .env.development.local 78 | .env.test.local 79 | .env.production.local 80 | .env.local 81 | 82 | # parcel-bundler cache (https://parceljs.org/) 83 | .cache 84 | .parcel-cache 85 | 86 | # Next.js build output 87 | .next 88 | out 89 | 90 | # Nuxt.js build / generate output 91 | .nuxt 92 | dist 93 | 94 | # Gatsby files 95 | .cache/ 96 | # Comment in the public line in if your project uses Gatsby and not Next.js 97 | # https://nextjs.org/blog/next-9-1#public-directory-support 98 | # public 99 | 100 | # vuepress build output 101 | .vuepress/dist 102 | 103 | # vuepress v2.x temp and cache directory 104 | .temp 105 | .cache 106 | 107 | # Docusaurus cache and generated files 108 | .docusaurus 109 | 110 | # Serverless directories 111 | .serverless/ 112 | 113 | # FuseBox cache 114 | .fusebox/ 115 | 116 | # DynamoDB Local files 117 | .dynamodb/ 118 | 119 | # TernJS port file 120 | .tern-port 121 | 122 | # Stores VSCode versions used for testing VSCode extensions 123 | .vscode-test 124 | 125 | # yarn v2 126 | .yarn/cache 127 | .yarn/unplugged 128 | .yarn/build-state.yml 129 | .yarn/install-state.gz 130 | .pnp.* 131 | 132 | # Custom 133 | /cdn 134 | /eslint 135 | /public 136 | /react 137 | /types 138 | ./custom-elements.json 139 | vscode.css-custom-data.json 140 | vscode.html-custom-data.json 141 | web-types.json -------------------------------------------------------------------------------- /.husky/.gitignore: -------------------------------------------------------------------------------- 1 | _ 2 | -------------------------------------------------------------------------------- /.husky/pre-commit: -------------------------------------------------------------------------------- 1 | #!/bin/sh 2 | . "$(dirname "$0")/_/husky.sh" 3 | 4 | npx lint-staged 5 | -------------------------------------------------------------------------------- /.prettierignore: -------------------------------------------------------------------------------- 1 | .gitignore 2 | cdn 3 | dist 4 | eslint 5 | plop-templates 6 | public 7 | react 8 | types -------------------------------------------------------------------------------- /.prettierrc: -------------------------------------------------------------------------------- 1 | { 2 | "singleQuote": true, 3 | "arrowParens": "avoid" 4 | } 5 | -------------------------------------------------------------------------------- /.storybook/code-bubble-setup.js: -------------------------------------------------------------------------------- 1 | import { CodeBubble } from 'code-bubble'; 2 | import packageJson from '../package.json'; 3 | 4 | (async () => { 5 | async function fetchLibData(url) { 6 | const baseUrl = window.location.href.includes('localhost') 7 | ? '' 8 | : window.location.href.split('/iframe')[0]; 9 | 10 | try { 11 | const response = await fetch(baseUrl + url); // Make the request 12 | return await response.text(); // Extract JSON data 13 | } catch (error) { 14 | console.error('Error fetching data:', url, error); 15 | return null; // Handle the error gracefully 16 | } 17 | } 18 | 19 | /** @type { import('code-bubble').CodeBubbleConfig } */ 20 | new CodeBubble({ 21 | sandbox: 'stackblitz', 22 | component: { 23 | frameworkButtons: { 24 | label: framework => 25 | ({ 26 | html: 'HTML', 27 | tsx: 'React', 28 | })[framework], 29 | }, 30 | }, 31 | sandboxConfig: { 32 | /** StackBlitz sandbox configuration */ 33 | stackBlitz: { 34 | html: { 35 | project: { 36 | title: packageJson.name + ' Demo', 37 | description: 'A live web component demo', 38 | files: { 39 | [`libs/${packageJson.name}/index.js`]: 40 | await fetchLibData('/html/index.js'), 41 | }, 42 | }, 43 | exampleTemplate: { 44 | fileName: 'index.html', 45 | template: ` 46 | 47 | 48 | 49 | ${packageJson.name} Demo 50 | 51 | 52 | 53 | 54 | 55 | 56 | 57 | %example% 58 | 59 | `, 60 | }, 61 | }, 62 | tsx: { 63 | project: { 64 | title: packageJson.name + ' React Demo', 65 | description: 'A live react/web component demo', 66 | files: { 67 | [`libs/${packageJson.name}/react/index.js`]: 68 | await fetchLibData('/react/index.js'), 69 | [`libs/${packageJson.name}/react/index.d.ts`]: 70 | await fetchLibData('/react/index.d.ts'), 71 | 'src/index.tsx': `import { createRoot } from "react-dom/client"; 72 | import App from "./App"; 73 | 74 | const rootElement = createRoot(document.getElementById("root")); 75 | rootElement.render();`, 76 | [`libs/${packageJson.name}/package.json`]: `{ 77 | "name": "${packageJson.name}", 78 | "version": "${packageJson.version}", 79 | "description": "A live react/web component demo", 80 | "main": "index.js" 81 | }`, 82 | 'package.json': `{ 83 | "name": "react-sandbox", 84 | "version": "1.0.0", 85 | "main": "src/index.tsx", 86 | "dependencies": { 87 | "react": "^18.2.0", 88 | "react-dom": "^18.2.0", 89 | "${packageJson.name}": "file:./libs/${packageJson.name}" 90 | }, 91 | "scripts": { 92 | "dev": "vite", 93 | "build": "vite build", 94 | "lint": "eslint . --ext js,jsx --report-unused-disable-directives --max-warnings 0", 95 | "preview": "vite preview" 96 | }, 97 | "devDependencies": { 98 | "@types/react": "^18.3.3", 99 | "@types/react-dom": "^18.3.0", 100 | "@typescript-eslint/eslint-plugin": "^7.15.0", 101 | "@typescript-eslint/parser": "^7.15.0", 102 | "@vitejs/plugin-react": "^4.3.1", 103 | "eslint": "^8.57.0", 104 | "eslint-plugin-react-hooks": "^4.6.2", 105 | "eslint-plugin-react-refresh": "^0.4.7", 106 | "typescript": "^5.2.2", 107 | "vite": "^5.3.2" 108 | } 109 | }`, 110 | 'tsconfig.json': `{ 111 | "include": ["./src/**/*"], 112 | "compilerOptions": { 113 | "strict": false, 114 | "esModuleInterop": true, 115 | "lib": ["ESNext", "DOM", "DOM.Iterable"], 116 | "jsx": "react-jsx", 117 | "baseUrl": "." 118 | } 119 | }`, 120 | 'vite.config.ts': `import { defineConfig } from 'vite'; 121 | import react from '@vitejs/plugin-react'; 122 | 123 | // https://vitejs.dev/config/ 124 | export default defineConfig({ 125 | plugins: [react()], 126 | });`, 127 | 'index.html': ` 128 | 129 | 130 | 131 | 132 | 133 | React code example 134 | 135 | 136 |
137 | 138 | 139 | `, 140 | }, 141 | }, 142 | exampleTemplate: { 143 | fileName: 'src/App.tsx', 144 | template: `%example%`, 145 | }, 146 | }, 147 | }, 148 | }, 149 | }); 150 | })(); 151 | -------------------------------------------------------------------------------- /.storybook/custom-elements.json: -------------------------------------------------------------------------------- 1 | { 2 | "schemaVersion": "1.0.0", 3 | "readme": "", 4 | "modules": [ 5 | { 6 | "kind": "javascript-module", 7 | "path": "src/my-element.ts", 8 | "declarations": [ 9 | { 10 | "kind": "class", 11 | "description": "An sample element.", 12 | "name": "MyElement", 13 | "cssProperties": [ 14 | { 15 | "description": "The card border color", 16 | "name": "--card-border-color", 17 | "default": "#ccc" 18 | }, 19 | { 20 | "description": "The card border color", 21 | "name": "--card-border-size", 22 | "default": "1px" 23 | }, 24 | { 25 | "description": "The card border color", 26 | "name": "--card-border-style", 27 | "default": "solid" 28 | }, 29 | { 30 | "description": "The card border radius", 31 | "name": "--card-border-radius", 32 | "default": "8px" 33 | } 34 | ], 35 | "cssParts": [ 36 | { 37 | "description": "The button", 38 | "name": "button" 39 | }, 40 | { 41 | "description": "Adds custom styles to the docs hint", 42 | "name": "docs-hint" 43 | } 44 | ], 45 | "slots": [ 46 | { 47 | "description": "This adds content between the logo and the counter button", 48 | "name": "" 49 | }, 50 | { 51 | "description": "This adds extra content into the counter button", 52 | "name": "button-content" 53 | } 54 | ], 55 | "members": [ 56 | { 57 | "kind": "field", 58 | "name": "docsHint", 59 | "type": { 60 | "text": "string" 61 | }, 62 | "default": "\"Click on the Storybook logo to learn more\"", 63 | "description": "Copy for the read the docs hint.", 64 | "attribute": "docs-hint", 65 | "reflects": true 66 | }, 67 | { 68 | "kind": "field", 69 | "name": "count", 70 | "type": { 71 | "text": "number" 72 | }, 73 | "default": "0", 74 | "description": "The number of times the button has been clicked.", 75 | "attribute": "count", 76 | "reflects": true 77 | }, 78 | { 79 | "kind": "field", 80 | "name": "label", 81 | "type": { 82 | "text": "string | undefined" 83 | }, 84 | "description": "Adds a label to the component", 85 | "attribute": "label" 86 | }, 87 | { 88 | "kind": "method", 89 | "name": "increaseCount", 90 | "privacy": "public" 91 | }, 92 | { 93 | "kind": "method", 94 | "name": "decreaseCount", 95 | "privacy": "public" 96 | }, 97 | { 98 | "kind": "method", 99 | "name": "setCount", 100 | "privacy": "public", 101 | "parameters": [ 102 | { 103 | "name": "value", 104 | "type": { 105 | "text": "number" 106 | } 107 | } 108 | ] 109 | }, 110 | { 111 | "kind": "method", 112 | "name": "getCount", 113 | "privacy": "public", 114 | "return": { 115 | "type": { 116 | "text": "number" 117 | } 118 | } 119 | }, 120 | { 121 | "kind": "method", 122 | "name": "_onClick", 123 | "privacy": "private" 124 | } 125 | ], 126 | "events": [ 127 | { 128 | "name": "count", 129 | "type": { 130 | "text": "number" 131 | }, 132 | "description": "This is emitted every time the count button is clicked" 133 | } 134 | ], 135 | "attributes": [ 136 | { 137 | "name": "docs-hint", 138 | "type": { 139 | "text": "string" 140 | }, 141 | "default": "\"Click on the Storybook logo to learn more\"", 142 | "description": "Copy for the read the docs hint.", 143 | "fieldName": "docsHint" 144 | }, 145 | { 146 | "name": "count", 147 | "type": { 148 | "text": "number" 149 | }, 150 | "default": "0", 151 | "description": "The number of times the button has been clicked.", 152 | "fieldName": "count" 153 | }, 154 | { 155 | "name": "label", 156 | "type": { 157 | "text": "string | undefined" 158 | }, 159 | "description": "Adds a label to the component", 160 | "fieldName": "label" 161 | } 162 | ], 163 | "cssStates": [ 164 | { 165 | "description": "used when the component is in a valid state", 166 | "name": "success" 167 | }, 168 | { 169 | "description": "used when the component is in a invalid state", 170 | "name": "invalid" 171 | }, 172 | { 173 | "description": "used when something has gone wrong in the component", 174 | "name": "error" 175 | } 176 | ], 177 | "superclass": { 178 | "name": "LitElement", 179 | "package": "lit" 180 | }, 181 | "tagName": "my-element", 182 | "customElement": true 183 | } 184 | ], 185 | "exports": [ 186 | { 187 | "kind": "js", 188 | "name": "MyElement", 189 | "declaration": { 190 | "name": "MyElement", 191 | "module": "src/my-element.ts" 192 | } 193 | }, 194 | { 195 | "kind": "custom-element-definition", 196 | "name": "my-element", 197 | "declaration": { 198 | "name": "MyElement", 199 | "module": "src/my-element.ts" 200 | } 201 | } 202 | ] 203 | } 204 | ] 205 | } 206 | -------------------------------------------------------------------------------- /.storybook/main.ts: -------------------------------------------------------------------------------- 1 | import type { StorybookConfig } from '@storybook/web-components-vite'; 2 | 3 | const config: StorybookConfig = { 4 | stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'], 5 | addons: [ 6 | '@storybook/addon-links', 7 | '@storybook/addon-essentials', 8 | '@storybook/addon-a11y', 9 | ], 10 | framework: { 11 | name: '@storybook/web-components-vite', 12 | options: {}, 13 | }, 14 | staticDirs: ['../public'], 15 | }; 16 | export default config; 17 | -------------------------------------------------------------------------------- /.storybook/preview.ts: -------------------------------------------------------------------------------- 1 | import { setCustomElementsManifest } from '@storybook/web-components'; 2 | import customElements from '../custom-elements.json'; 3 | import { setWcStorybookHelpersConfig } from 'wc-storybook-helpers'; 4 | import { withActions } from '@storybook/addon-actions/decorator'; 5 | import './code-bubble-setup.js'; 6 | import './styles.css'; 7 | import { setWcDoxConfig } from '../public/html/index.js'; 8 | import manifest from './custom-elements.json'; 9 | 10 | import type { Preview } from '@storybook/web-components'; 11 | 12 | setWcStorybookHelpersConfig({ typeRef: 'expandedType' }); 13 | setCustomElementsManifest(customElements); 14 | setWcDoxConfig(manifest, { 15 | imports: { 16 | langOnPreTag: true, 17 | imports: [ 18 | { 19 | label: 'HTML', 20 | lang: 'html', 21 | importTemplate: (tagName, className) => 22 | ``, 23 | }, 24 | { 25 | label: 'NPM', 26 | lang: 'js', 27 | importTemplate: (tagName, className) => 28 | `import 'my-library/dist/${tagName}/${className}.js';`, 29 | }, 30 | { 31 | label: 'React', 32 | lang: 'js', 33 | importTemplate: tagName => 34 | `import 'my-library/react/${tagName}/index.js';`, 35 | }, 36 | ], 37 | }, 38 | }); 39 | 40 | const preview: Preview = { 41 | parameters: { 42 | controls: { 43 | expanded: true, // provides descriptions and additional info for controls 44 | sort: 'alpha', // sorts controls in alphabetical order 45 | }, 46 | }, 47 | decorators: [withActions], 48 | }; 49 | 50 | export default preview; 51 | -------------------------------------------------------------------------------- /.storybook/styles.css: -------------------------------------------------------------------------------- 1 | :not(:defined) { 2 | opacity: 0; 3 | } 4 | 5 | code-bubble { 6 | margin-bottom: 2rem; 7 | } 8 | 9 | code-bubble[code-bubble] pre[slot] { 10 | margin: 0; 11 | } 12 | 13 | code-bubble[code-bubble] pre button { 14 | display: none; 15 | } 16 | 17 | .docblock-source.sb-unstyled { 18 | margin: 0; 19 | border: 0; 20 | box-shadow: none; 21 | } 22 | -------------------------------------------------------------------------------- /.vscode/extensions.json: -------------------------------------------------------------------------------- 1 | { 2 | "recommendations": [ 3 | "bierner.lit-html", 4 | "dbaeumer.vscode-eslint", 5 | "esbenp.prettier-vscode", 6 | "streetsidesoftware.code-spell-checker", 7 | "unifiedjs.vscode-mdx", 8 | "yzhang.markdown-all-in-one" 9 | ] 10 | } 11 | -------------------------------------------------------------------------------- /CHANGELOG.md: -------------------------------------------------------------------------------- 1 | # Changelog 2 | 3 | ## 1.2.0 4 | 5 | - Added templating for optional parameters and default values for methods 6 | 7 | ## 1.1.1 8 | 9 | - Fixed type-o in README.md 10 | - Fixed type-o in default values 11 | 12 | ## 1.1.0 13 | 14 | - Added `langOnPreTag` setting to `imports` to set the language class on the `pre` element instead of the `code` element 15 | - Fixed parameters for `importTemplate` to use content from the CEM rather than the component properties 16 | 17 | ## 1.0.4 18 | 19 | - Fixed logic for hiding components when there is no content 20 | - Fixed logic that cause exceptions when components and APIs are undefined 21 | 22 | ## 1.0.3 23 | 24 | - Fixed type-o in README 25 | 26 | ## 1.0.2 27 | 28 | - Removed default imports 29 | 30 | ## 1.0.1 31 | 32 | - Updated documentation 33 | 34 | ## 1.0.0 35 | 36 | - Initial release -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2024 Burton Smith 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Web Component Documentation (`wc-dox`) 2 | 3 | The `wc-dox` package and it's components are designed to be a way to quickly and consistently document your custom element APIs using the [Custom Elements Manifest](https://github.com/webcomponents/custom-elements-manifest). 4 | 5 | > If you're not already generating a Custom Elements Manifest, [here is a list of options](https://dev.to/stuffbreaker/you-should-be-shipping-a-manifest-with-your-web-components-2da0) you can use to generate one. 6 | 7 | ![demo of documentation output](https://github.com/break-stuff/wc-dox/blob/main/assets/demo.gif?raw=true) 8 | 9 |
10 | 11 | [![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/edit/github-tdtmrsak-3eijkyac?file=src%2Fmy-element.mdx) 12 | 13 |
14 | 15 | ## Installation 16 | 17 | ```bash 18 | npm i wc-dox 19 | ``` 20 | 21 | ## Usage 22 | 23 | After installing, you can load the documentation at the root of your project. 24 | 25 | ```ts 26 | import { setWcDoxConfig } from 'wc-dox/index.js'; 27 | import manifest from './custom-elements.json' with { type: json }; 28 | 29 | setWcDoxConfig(manifest); 30 | ``` 31 | 32 | Now that it's loaded, you can load the appropriate documentation by passing the component's tag name or class name to the component. 33 | 34 | ```html 35 | 36 | 37 | 38 | 39 | 40 | ``` 41 | 42 | ### Content is in the Light DOM 43 | 44 | The content generated by these components is all render in the light DOM so that styles can be easily inherited from the rest of your application or so that customizations can easily be applied. 45 | 46 | ### Flexible Implementation 47 | 48 | The `` element should be all that you need, but if you eed more flexibility, each of the sections can also be used independently as individual components. 49 | 50 | ```html 51 | 52 | 53 | 54 | 55 | 56 | 57 | 58 | 59 | 60 | 61 | 62 | 63 | 64 | 65 | 66 | 67 | 68 | 69 | 70 | 71 | 72 | 73 | 74 | ``` 75 | 76 | ## Configuration 77 | 78 | The `setWcDoxConfig` function can take a second parameter to configure the documentation. 79 | 80 | The `` and `` components have unique configurations, but the others follow a consistent API. 81 | 82 | ```ts 83 | import { setWcDoxConfig, DoxConfig } from 'wc-dox/index.js'; 84 | import manifest from './custom-elements.json' with { type: json }; 85 | 86 | const options: DoxConfig = {}; 87 | 88 | setWcDoxConfig(manifest, options); 89 | ``` 90 | 91 | ```ts 92 | type DoxConfig = { 93 | /** Configures the heading level for the API sections - default is 3 */ 94 | headingLevel?: 1 | 2 | 3 | 4 | 5 | 6; 95 | /** Configures the `wc-dox` component contents */ 96 | dox?: DoxElementConfig; 97 | /** Configures the `wc-imports` component contents */ 98 | imports?: ImportsElementConfig; 99 | /** Configures the `wc-css-parts` component contents */ 100 | cssParts?: CssPartsElementConfig; 101 | /** Configures the `wc-css-props` component contents */ 102 | cssProps?: CssPropsElementConfig; 103 | /** Configures the `wc-states` component contents */ 104 | cssStates?: StatesElementConfig; 105 | /** Configures the `wc-events` component contents */ 106 | events?: EventsElementConfig; 107 | /** Configures the `wc-methods` component contents */ 108 | methods?: MethodsElementConfig; 109 | /** Configures the `wc-props` component contents */ 110 | props?: PropsElementConfig; 111 | /** Configures the `wc-slots` component contents */ 112 | slots?: SlotsElementConfig; 113 | }; 114 | ``` 115 | 116 | ### Heading Level 117 | 118 | The `headingLevel` setting controls the heading level for each of the sections of the API sections. 119 | 120 | ### Dox Element Config 121 | 122 | The `` element works as a wrapper for the API components. The `apiOrder` setting controls the order in which the API sections are rendered. If you do not want a section to render at all, you can exclude it from the array. 123 | 124 | ```ts 125 | type DoxElementConfig = { 126 | /** 127 | * Controls the order in which the API documentation sections are displayed 128 | * 129 | * Default value is ['imports', 'props', 'slots', 'methods', 'events', 'css-props', 'css-parts', 'css-states'] 130 | */ 131 | apiOrder?: Array< 132 | | 'imports' 133 | | 'props' 134 | | 'slots' 135 | | 'methods' 136 | | 'events' 137 | | 'css-props' 138 | | 'css-parts' 139 | | 'css-states' 140 | >; 141 | }; 142 | ``` 143 | 144 | ### Imports Element Config 145 | 146 | The imports element is a way for you to document the various ways to import your components. Each of the imports will be displayed in it's own tab. 147 | 148 | ```ts 149 | type ImportsElementConfig = { 150 | /** The heading for the imports section */ 151 | heading?: string; 152 | /** The ID used for the skip-link */ 153 | headingId?: string; 154 | /** The description for the imports section */ 155 | description?: string; 156 | /** The copy button icon */ 157 | copyIcon?: string; 158 | /** The copy button label */ 159 | copyLabel?: string; 160 | /** The icon displayed when the content is copied */ 161 | copiedIcon?: string; 162 | /** The label used when the content is copied */ 163 | copiedLabel?: string; 164 | /** Sets the language class on `pre` tag instead of `code` tag */ 165 | langOnPreTag?: boolean; 166 | /** The list of import options */ 167 | imports?: ImportConfig[]; 168 | }; 169 | 170 | type ImportConfig = { 171 | /** The text displayed in the tab option */ 172 | label?: string; 173 | /** The language the code - `html`, `js`, `ts`, etc. */ 174 | lang?: string; 175 | /** An additional description that is specific to this import */ 176 | description?: string; 177 | /** 178 | * Use this function to specify import information for a given language. The tag and class names can be used to create dynamic component-specific import paths. 179 | * @param tagName The tag name specified using the @tag or @tagName in the component's jsDoc 180 | * @param className The JS class name for the component 181 | * @returns string 182 | */ 183 | importTemplate?: (tagName: string, className: string) => string; 184 | }; 185 | ``` 186 | 187 | Here's a sample configuration: 188 | 189 | ```ts 190 | imports: { 191 | heading: 'Imports', 192 | headingId: 'imports', 193 | description: 'You can import the component in the following ways:', 194 | copyIcon: 195 | '', 196 | copyLabel: 'Copy import', 197 | copiedIcon: 198 | '', 199 | copiedLabel: 'Import copied', 200 | imports: [ 201 | { 202 | label: 'HTML', 203 | lang: 'html', 204 | importTemplate: (tagName, className) => 205 | ` 36 | 37 | 38 | 39 | `, 40 | }; 41 | --------------------------------------------------------------------------------