{"id":26175442,"url":"https://github.com/break-stuff/wc-dox","last_synced_at":"2025-04-14T21:32:11.974Z","repository":{"id":270005723,"uuid":"909117330","full_name":"break-stuff/wc-dox","owner":"break-stuff","description":"A web component API documentation generator","archived":false,"fork":false,"pushed_at":"2025-01-14T21:36:34.000Z","size":7160,"stargazers_count":11,"open_issues_count":1,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-16T13:45:26.166Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/break-stuff.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-12-27T19:19:54.000Z","updated_at":"2025-01-17T01:24:13.000Z","dependencies_parsed_at":null,"dependency_job_id":"8b2b9051-0cbb-4e8b-871d-434e3b1648fd","html_url":"https://github.com/break-stuff/wc-dox","commit_stats":null,"previous_names":["break-stuff/wc-dox"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/break-stuff%2Fwc-dox","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/break-stuff%2Fwc-dox/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/break-stuff%2Fwc-dox/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/break-stuff%2Fwc-dox/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/break-stuff","download_url":"https://codeload.github.com/break-stuff/wc-dox/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243112169,"owners_count":20238183,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-03-11T20:56:33.462Z","updated_at":"2025-03-11T20:56:34.143Z","avatar_url":"https://github.com/break-stuff.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Web Component Documentation (`wc-dox`)\n\nThe `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).\n\n\u003e 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.\n\n![demo of documentation output](https://github.com/break-stuff/wc-dox/blob/main/assets/demo.gif?raw=true)\n\n\u003cdiv align=\"center\"\u003e\n\n[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/edit/github-tdtmrsak-3eijkyac?file=src%2Fmy-element.mdx)\n\n\u003c/div\u003e\n\n## Installation\n\n```bash\nnpm i wc-dox\n```\n\n## Usage\n\nAfter installing, you can load the documentation at the root of your project.\n\n```ts\nimport { setWcDoxConfig } from 'wc-dox/index.js';\nimport manifest from './custom-elements.json' with { type: json };\n\nsetWcDoxConfig(manifest);\n```\n\nNow that it's loaded, you can load the appropriate documentation by passing the component's tag name or class name to the component.\n\n```html\n\u003cwc-dox tag=\"my-element\"\u003e\u003c/wc-dox\u003e\n\n\u003c!-- or --\u003e\n\n\u003cwc-dox component-name=\"MyElement\"\u003e\u003c/wc-dox\u003e\n```\n\n### Content is in the Light DOM\n\nThe 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.\n\n### Flexible Implementation\n\nThe `\u003cwc-dox\u003e` 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.\n\n```html\n\u003c!-- CSS Parts docs --\u003e\n\u003cwc-css-parts tag=\"my-element\"\u003e\u003c/wc-css-parts\u003e\n\n\u003c!-- CSS Custom Properties docs --\u003e\n\u003cwc-css-props tag=\"my-element\"\u003e\u003c/wc-css-props\u003e\n\n\u003c!-- CSS Custom States docs --\u003e\n\u003cwc-css-states tag=\"my-element\"\u003e\u003c/wc-css-states\u003e\n\n\u003c!-- Events docs --\u003e\n\u003cwc-events tag=\"my-element\"\u003e\u003c/wc-events\u003e\n\n\u003c!-- Imports docs --\u003e\n\u003cwc-imports tag=\"my-element\"\u003e\u003c/wc-imports\u003e\n\n\u003c!-- Methods docs --\u003e\n\u003cwc-methods tag=\"my-element\"\u003e\u003c/wc-methods\u003e\n\n\u003c!-- Attributes and Properties docs --\u003e\n\u003cwc-props tag=\"my-element\"\u003e\u003c/wc-props\u003e\n\n\u003c!-- Slots docs --\u003e\n\u003cwc-slots tag=\"my-element\"\u003e\u003c/wc-slots\u003e\n```\n\n## Configuration\n\nThe `setWcDoxConfig` function can take a second parameter to configure the documentation.\n\nThe `\u003cwc-dox\u003e` and `\u003cwc-imports\u003e` components have unique configurations, but the others follow a consistent API.\n\n```ts\nimport { setWcDoxConfig, DoxConfig } from 'wc-dox/index.js';\nimport manifest from './custom-elements.json' with { type: json };\n\nconst options: DoxConfig = {};\n\nsetWcDoxConfig(manifest, options);\n```\n\n```ts\ntype DoxConfig = {\n  /** Configures the heading level for the API sections - default is 3 */\n  headingLevel?: 1 | 2 | 3 | 4 | 5 | 6;\n  /** Configures the `wc-dox` component contents */\n  dox?: DoxElementConfig;\n  /** Configures the `wc-imports` component contents */\n  imports?: ImportsElementConfig;\n  /** Configures the `wc-css-parts` component contents */\n  cssParts?: CssPartsElementConfig;\n  /** Configures the `wc-css-props` component contents */\n  cssProps?: CssPropsElementConfig;\n  /** Configures the `wc-states` component contents */\n  cssStates?: StatesElementConfig;\n  /** Configures the `wc-events` component contents */\n  events?: EventsElementConfig;\n  /** Configures the `wc-methods` component contents */\n  methods?: MethodsElementConfig;\n  /** Configures the `wc-props` component contents */\n  props?: PropsElementConfig;\n  /** Configures the `wc-slots` component contents */\n  slots?: SlotsElementConfig;\n};\n```\n\n### Heading Level\n\nThe `headingLevel` setting controls the heading level for each of the sections of the API sections.\n\n### Dox Element Config\n\nThe `\u003cwc-dox\u003e` 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.\n\n```ts\ntype DoxElementConfig = {\n  /**\n   * Controls the order in which the API documentation sections are displayed\n   *\n   * Default value is ['imports', 'props', 'slots', 'methods', 'events', 'css-props', 'css-parts', 'css-states']\n   */\n  apiOrder?: Array\u003c\n    | 'imports'\n    | 'props'\n    | 'slots'\n    | 'methods'\n    | 'events'\n    | 'css-props'\n    | 'css-parts'\n    | 'css-states'\n  \u003e;\n};\n```\n\n### Imports Element Config\n\nThe 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.\n\n```ts\ntype ImportsElementConfig = {\n  /** The heading for the imports section */\n  heading?: string;\n  /** The ID used for the skip-link */\n  headingId?: string;\n  /** The description for the imports section */\n  description?: string;\n  /** The copy button icon */\n  copyIcon?: string;\n  /** The copy button label */\n  copyLabel?: string;\n  /** The icon displayed when the content is copied */\n  copiedIcon?: string;\n  /** The label used when the content is copied */\n  copiedLabel?: string;\n  /** Sets the language class on `pre` tag instead of `code` tag */\n  langOnPreTag?: boolean;\n  /** The list of import options */\n  imports?: ImportConfig[];\n};\n\ntype ImportConfig = {\n  /** The text displayed in the tab option */\n  label?: string;\n  /** The language the code - `html`, `js`, `ts`, etc. */\n  lang?: string;\n  /** An additional description that is specific to this import */\n  description?: string;\n  /**\n   * 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.\n   * @param tagName The tag name specified using the @tag or @tagName in the component's jsDoc\n   * @param className The JS class name for the component\n   * @returns string\n   */\n  importTemplate?: (tagName: string, className: string) =\u003e string;\n};\n```\n\nHere's a sample configuration:\n\n```ts\nimports: {\n  heading: 'Imports',\n  headingId: 'imports',\n  description: 'You can import the component in the following ways:',\n  copyIcon:\n    '\u003c?xml version=\"1.0\" ?\u003e\u003csvg style=\"enable-background:new 0 0 24 24;\" version=\"1.1\" viewBox=\"0 0 24 24\" xml:space=\"preserve\" xmlns=\"http://www.w3.org/2000/svg\" xmlns:xlink=\"http://www.w3.org/1999/xlink\"\u003e\u003cg class=\"st0\" id=\"grid_system\"/\u003e\u003cg id=\"_icons\"\u003e\u003cpath d=\"M17,3h-6C8.8,3,7,4.8,7,7c-2.2,0-4,1.8-4,4v6c0,2.2,1.8,4,4,4h6c2.2,0,4-1.8,4-4c2.2,0,4-1.8,4-4V7C21,4.8,19.2,3,17,3z    M15,17c0,1.1-0.9,2-2,2H7c-1.1,0-2-0.9-2-2v-6c0-1.1,0.9-2,2-2h1h5c1.1,0,2,0.9,2,2v5V17z M19,13c0,1.1-0.9,2-2,2v-4   c0-2.2-1.8-4-4-4H9c0-1.1,0.9-2,2-2h6c1.1,0,2,0.9,2,2V13z\"/\u003e\u003c/g\u003e\u003c/svg\u003e',\n  copyLabel: 'Copy import',\n  copiedIcon:\n    '\u003c?xml version=\"1.0\" ?\u003e\u003csvg style=\"enable-background:new 0 0 36 36;\" version=\"1.1\" viewBox=\"0 0 36 36\" xml:space=\"preserve\" xmlns=\"http://www.w3.org/2000/svg\" xmlns:xlink=\"http://www.w3.org/1999/xlink\"\u003e\u003cg id=\"Layer_1\"/\u003e\u003cg id=\"icons\"\u003e\u003cpath class=\"st0\" d=\"M12.8,28.7l-9.5-9.5c-0.4-0.4-0.4-1.1,0-1.6l1.5-1.5c0.4-0.4,1.1-0.4,1.6,0l7.2,7.2   l16-16c0.4-0.4,1.1-0.4,1.6,0l1.5,1.5c0.4,0.4,0.4,1.1,0,1.6L14.4,28.7C13.9,29.1,13.2,29.1,12.8,28.7z\" id=\"check_x5F_mark_1_\"/\u003e\u003c/g\u003e\u003c/svg\u003e',\n  copiedLabel: 'Import copied',\n  imports: [\n    {\n      label: 'HTML',\n      lang: 'html',\n      importTemplate: (tagName, className) =\u003e\n        `\u003cscript type=\"module\" src=\"https://cdn.jsdelivr.net/npm/my-library/dist/${tagName}/${className}.js\"\u003e\u003c\\/script\u003e`,\n    },\n    {\n      label: 'NPM',\n      lang: 'js',\n      importTemplate: (tagName, className) =\u003e\n        `import 'my-library/dist/${tagName}/${className}.js';`,\n    },\n    {\n      label: 'React',\n      lang: 'js',\n      importTemplate: tagName =\u003e\n        `import 'my-library/react/${tagName}/index.js';`,\n    },\n  ],\n},\n```\n\n### Base Config\n\nThe other API blocks use the generic `BaseElementConfig\u003cT\u003e` type and follow a consistent pattern for documenting the APIs from the custom element manifest.\n\n```ts\ntype BaseElementConfig\u003cT\u003e = {\n  /** The heading for the section */\n  heading?: string;\n  /** The ID used for the skip-link */\n  headingId?: string;\n  /** The label used for the skip-link */\n  skipLinkLabel?: string;\n  /** The description for the section */\n  headings?: string[];\n  /** The description for the section */\n  description?: string;\n  /** The table row template for the section */\n  rowTemplate?: (x: T) =\u003e string;\n};\n```\n\n### Markdown Support\n\nMany of the JSDoc comments support markdown. To parse markdown in these API blocks, you can use the `markdownToHtml` utility helper provided by this project or you can install and use your own.\n\n### CSS Parts Element Config\n\n```ts\ntype CssPart = cem.CssPart \u0026 Record\u003cstring, any\u003e;\ntype CssPartsElementConfig = BaseElementConfig\u003cCssPart\u003e;\n```\n\nThe default value for this is:\n\n```ts\ncssParts: {\n  heading: 'CSS Parts',\n  headingId: 'css-parts',\n  skipLinkLabel: 'Skip to CSS parts',\n  description:\n    'The following [CSS shadow parts](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_shadow_parts) are available to customize the component:',\n  headings: ['Name', 'Description', 'Deprecated'],\n  rowTemplate: cssPart =\u003e\n    `\u003ctr\u003e\n      \u003ctd\u003e\u003cp\u003e\u003ccode\u003e${cssPart.name}\u003c/code\u003e\u003c/p\u003e\u003c/td\u003e\n      \u003ctd\u003e${markdownToHtml(cssPart.description || '')}\u003c/td\u003e\n      \u003ctd style=\"text-align: center;\"\u003e${cssPart.deprecated ? '✔️' : ''}\u003c/td\u003e\n    \u003c/tr\u003e`,\n},\n```\n\n### CSS Props Element Config\n\n```ts\ntype CssPropsElementConfig = BaseElementConfig\u003cCssProp\u003e;\ntype CssProp = cem.CssCustomProperty \u0026 Record\u003cstring, any\u003e;\n```\n\nThe default value for the CSS Custom Properties Element is:\n\n```ts\ncssProps: {\n  heading: 'CSS Custom Properties',\n  headingId: 'css-props',\n  skipLinkLabel: 'Skip to CSS custom properties',\n  description:\n    'You can use [CSS custom properties](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties) to customize the look and feel of the component using the following properties:',\n  headings: ['Name', 'Default', 'Description', 'Deprecated'],\n  rowTemplate: cssVar =\u003e\n    `\u003ctr\u003e\n      \u003ctd\u003e\u003cp\u003e\u003ccode\u003e${cssVar.name}\u003c/code\u003e\u003c/p\u003e\u003c/td\u003e\n      \u003ctd\u003e\u003cp\u003e\u003ccode\u003e${cssVar.default}\u003c/code\u003e\u003c/p\u003e\u003c/td\u003e\n      \u003ctd\u003e${markdownToHtml(cssVar.description || '')}\u003c/td\u003e\n      \u003ctd style=\"text-align: center;\"\u003e${cssVar.deprecated ? '✔️' : ''}\u003c/td\u003e\n    \u003c/tr\u003e`,\n},\n```\n\n### Events Element Config\n\n```ts\ntype EventsElementConfig = BaseElementConfig\u003cEvent\u003e;\ntype Event = cem.Event \u0026 Record\u003cstring, any\u003e;\n```\n\nThe default value for the Events Element is:\n\n```ts\nevents: {\n  heading: 'Events',\n  headingId: 'events',\n  skipLinkLabel: 'Skip to events',\n  description:\n    'The following [events](https://developer.mozilla.org/en-US/docs/Web/Events/Creating_and_triggering_events) are emitted by the component:',\n  headings: ['Name', 'Type', 'Description', 'Deprecated'],\n  rowTemplate: event =\u003e\n    `\u003ctr\u003e\n      \u003ctd\u003e\u003cp\u003e\u003ccode\u003e${event.name}\u003c/code\u003e\u003c/p\u003e\u003c/td\u003e\n      \u003ctd\u003e\u003cp\u003e\u003ccode\u003e${event.type.text === 'CustomEvent' ? 'CustomEvent' : `CustomEvent\u0026lt;${event.type.text}\u0026gt;`}\u003c/code\u003e\u003c/p\u003e\u003c/td\u003e\n      \u003ctd\u003e${markdownToHtml(event.description || '')}\u003c/td\u003e\n      \u003ctd style=\"text-align: center;\"\u003e${event.deprecated ? '✔️' : ''}\u003c/td\u003e\n    \u003c/tr\u003e`,\n},\n```\n\n### Methods Element Config\n\n```ts\ntype MethodsElementConfig = BaseElementConfig\u003cMethod\u003e;\ntype Method = cem.ClassMethod \u0026 Record\u003cstring, any\u003e;\n```\n\nThe default value for the Methods Element is:\n\n```ts\nmethods: {\n  heading: 'Methods',\n  headingId: 'methods',\n  skipLinkLabel: 'Skip to methods',\n  description: 'The following Methods are available:',\n  headings: ['Name', 'Description', 'Deprecated'],\n  rowTemplate: method =\u003e {\n    const getParameter = (p: Parameter) =\u003e p.name + getParamType(p) + getParamDefaultValue(p);\n    const getParamType = (p: Parameter) =\u003e p.type?.text ? `${p.optional ? '?' : ''}: ${p.type?.text}` : '';\n    const getParamDefaultValue = (p: Parameter) =\u003e p.default ? ` = ${p.default}` : '';\n    return `\u003ctr\u003e\n      \u003ctd\u003e\u003cp\u003e\u003ccode\u003e${method.name}(${method.parameters?.map(p =\u003e getParameter(p)).join(', ') || ''}) =\u003e ${method.return?.type?.text || 'void'}\u003c/code\u003e\u003c/p\u003e\u003c/td\u003e\n      \u003ctd\u003e${markdownToHtml(method.description || '')}\u003c/td\u003e\n      \u003ctd style=\"text-align: center;\"\u003e${method.deprecated ? '✔️' : ''}\u003c/td\u003e\n    \u003c/tr\u003e`;\n  }\n},\n```\n\n### Props Element Config\n\n```ts\ntype PropsElementConfig = BaseElementConfig\u003cProperty\u003e;\ntype Method = cem.ClassMethod \u0026 Record\u003cstring, any\u003e;\n```\n\nThe default value for the Props Element is:\n\n```ts\nprops: {\n  heading: 'Attributes and Properties',\n  headingId: 'props',\n  skipLinkLabel: 'Skip to attributes and properties',\n  description: 'The following Properties and Attributes are available:',\n  headings: [\n    'Name',\n    'Attribute',\n    'Description',\n    'Type',\n    'Default',\n    'Read-only',\n    'Deprecated',\n  ],\n  rowTemplate: prop =\u003e\n    `\u003ctr\u003e\n      \u003ctd\u003e\u003cp\u003e\u003ccode\u003e${prop.name}\u003c/code\u003e\u003c/p\u003e\u003c/td\u003e\n      \u003ctd\u003e\u003cp\u003e\u003ccode\u003e${prop.attribute || ''}\u003c/code\u003e\u003c/p\u003e\u003c/td\u003e\n      \u003ctd\u003e${markdownToHtml(prop.description || '')}\u003c/td\u003e\n      \u003ctd\u003e\u003cp\u003e\u003ccode\u003e${prop.type?.text || ''}\u003c/code\u003e\u003c/p\u003e\u003c/td\u003e\n      \u003ctd\u003e\u003cp\u003e\u003ccode\u003e${prop.default}\u003c/code\u003e\u003c/p\u003e\u003c/td\u003e\n      \u003ctd style=\"text-align: center;\"\u003e${prop.readonly ? '✔️' : ''}\u003c/td\u003e\n      \u003ctd style=\"text-align: center;\"\u003e${prop.deprecated ? '✔️' : ''}\u003c/td\u003e\n    \u003c/tr\u003e`,\n},\n```\n\n### Slots Element Config\n\n```ts\ntype SlotsElementConfig = BaseElementConfig\u003cSlot\u003e;\ntype Slot = cem.Slot \u0026 Record\u003cstring, any\u003e;\n```\n\nThe default value for the Slots Element is:\n\n```ts\nslots: {\n  heading: 'Slots',\n  headingId: 'slots',\n  skipLinkLabel: 'Skip to slots',\n  description: 'The following slots are available:',\n  headings: ['Name', 'Description', 'Deprecated'],\n  rowTemplate: slot =\u003e\n    `\u003ctr\u003e\n      \u003ctd\u003e\u003cp\u003e\u003ccode\u003e${slot.name || '\u003cem\u003e(default)\u003c/em\u003e'}\u003c/code\u003e\u003c/p\u003e\u003c/td\u003e\n      \u003ctd\u003e${markdownToHtml(slot.description || '')}\u003c/td\u003e\n      \u003ctd style=\"text-align: center;\"\u003e${slot.deprecated ? '✔️' : ''}\u003c/td\u003e\n    \u003c/tr\u003e`,\n},\n```\n\n### CssStatesElementConfig\n\n```ts\ntype CssStatesElementConfig = BaseElementConfig\u003cCssState\u003e;\ntype CssState = cem.CssCustomState \u0026 Record\u003cstring, any\u003e;\n```\n\nThe default value for the CSS States Element is:\n\n```ts\ncssStates: {\n  heading: 'CSS States',\n  headingId: 'css-states',\n  skipLinkLabel: 'Skip to CSS states',\n  description:\n    'The following [CSS states](https://developer.mozilla.org/en-US/docs/Web/CSS/:state) can be used to customize component styles:',\n  headings: ['Name', 'Description', 'Deprecated'],\n  rowTemplate: state =\u003e\n    `\u003ctr\u003e\n      \u003ctd\u003e\u003cp\u003e\u003ccode\u003e${state.name}\u003c/code\u003e\u003c/p\u003e\u003c/td\u003e\n      \u003ctd\u003e${markdownToHtml(state.description || '')}\u003c/td\u003e\n      \u003ctd style=\"text-align: center;\"\u003e${state.deprecated ? '✔️' : ''}\u003c/td\u003e\n    \u003c/tr\u003e`,\n},\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbreak-stuff%2Fwc-dox","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbreak-stuff%2Fwc-dox","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbreak-stuff%2Fwc-dox/lists"}