{"_id":"@auroratide/table-of-contents","name":"@auroratide/table-of-contents","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@auroratide/table-of-contents","version":"0.1.0","description":"Web component for auto-generating a table of contents","keywords":["contents","web component","table of contents","links","navigation"],"type":"module","main":"lib/index.js","module":"lib/index.js","author":{"name":"Timothy Foster","url":"https://auroratide.com"},"repository":{"type":"git","url":"git+https://github.com/Auroratide/web-components.git"},"license":"ISC","devDependencies":{"@open-wc/testing":"^4.0.0","@web/test-runner":"^0.18.0","typescript":"^5.3.3"},"scripts":{"clean":"rm -rf lib","build":"tsc","build:watch":"tsc -w","test":"wtr --node-resolve --port 10009 test","test:clean":"pnpm clean && pnpm build && pnpm test"},"types":"./lib/index.d.ts","bugs":{"url":"https://github.com/Auroratide/web-components/issues"},"homepage":"https://github.com/Auroratide/web-components#readme","_id":"@auroratide/table-of-contents@0.1.0","_integrity":"sha512-dmXZusDx7U3tsf1/jI9UPHKaKXS7HOTX0bu+I3z/rGGZSPQbqJYTNL57PAxkQKYz2JDP5tCX2AIGSJwIRP3m8Q==","_resolved":"/private/var/folders/bk/zbxm0bcj609gs34tt_wxngfr0000gn/T/10faccf7eb6207d5a59bcf9e1e9bab72/auroratide-table-of-contents-0.1.0.tgz","_from":"file:auroratide-table-of-contents-0.1.0.tgz","_nodeVersion":"20.11.1","_npmVersion":"10.2.4","dist":{"integrity":"sha512-dmXZusDx7U3tsf1/jI9UPHKaKXS7HOTX0bu+I3z/rGGZSPQbqJYTNL57PAxkQKYz2JDP5tCX2AIGSJwIRP3m8Q==","shasum":"930109acfa34a9937ebf8a9708026194465f2480","tarball":"https://registry.npmjs.org/@auroratide/table-of-contents/-/table-of-contents-0.1.0.tgz","fileCount":11,"unpackedSize":11102,"signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEQCIBYq3NHaXxGivQeuHnRCMum8NyxsBQDShgCUDTVSAMwtAiAkY4vBtlyMekcybW9oCapdTsJj1RPNHDvMKh/iA3ekww=="}]},"_npmUser":{"name":"auroratide","email":"tf.auroratide@gmail.com"},"directories":{},"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/table-of-contents_0.1.0_1719441796523_0.6763411995750079"},"_hasShrinkwrap":false}},"time":{"created":"2024-06-26T22:43:16.410Z","0.1.0":"2024-06-26T22:43:16.680Z","modified":"2024-06-26T22:43:17.021Z"},"maintainers":[{"name":"auroratide","email":"tf.auroratide@gmail.com"}],"description":"Web component for auto-generating a table of contents","homepage":"https://github.com/Auroratide/web-components#readme","keywords":["contents","web component","table of contents","links","navigation"],"repository":{"type":"git","url":"git+https://github.com/Auroratide/web-components.git"},"author":{"name":"Timothy Foster","url":"https://auroratide.com"},"bugs":{"url":"https://github.com/Auroratide/web-components/issues"},"license":"ISC","readme":"# The table-of-contents Element\n\n<p hidden><strong><a href=\"https://auroratide.github.io/web-components/table-of-contents\">View this page with live demos!</a></strong></p>\n\nThe `table-of-contents` element represents a navigable list of headings for some content. This component is able to automatically generate links needed to navigate to all the different headings in an article.\n\n\n<!--DEMO\n<wc-demo>\n\t<table-of-contents for=\"first-demo\" aria-label=\"Demo for Table of Contents Element\"></table-of-contents>\n\t<section id=\"first-demo\">\n\t\t<h2 id=\"one\">One</h2>\n\t\t<h3 id=\"one-one\">One One</h3>\n\t\t<h3 id=\"one-two\">One Two</h3>\n\t\t<h2 id=\"two\">Two</h2>\n\t</section>\n</wc-demo>\n/DEMO-->\n\n```html\n<table-of-contents\n\tfor=\"main-content\"\n\taria-label=\"Table of Contents\"\n></table-of-contents>\n\n<section id=\"main-content\">\n\t<h2 id=\"one\">One</h2>\n\t<h3 id=\"one-one\">One One</h3>\n\t<h3 id=\"one-two\">One Two</h3>\n\t<h2 id=\"two\">Two</h2>\n</section>\n```\n\n## Installation\n\nYou can import through CDN:\n\n```html\n<script type=\"module\" src=\"https://unpkg.com/@auroratide/table-of-contents/lib/define.js\"></script>\n```\n\nOr, you may install through [NPM](https://www.npmjs.com/package/@auroratide/table-of-contents) and include it as part of your build process:\n\n```\n$ npm i @auroratide/table-of-contents\n```\n\n```javascript\nimport '@auroratide/table-of-contents/lib/define.js'\n```\n\n## Usage\n\n`table-of-contents` is a **markup element** that you can use in your HTML document.\n\nThe `for` attribute can be set to the `id` of an element on the page. If you supply this, the `table-of-contents` will automatically generate a list of links to headings in the chosen element.\n\nFor this, your content must conform to the following:\n\n* Headings in your content are defined with the `h1` through `h6` tags.\n* Headings do not skip levels ([this is good accessibility practice anyway](https://webaim.org/techniques/semanticstructure/#headings)).\n* Each heading has an `id` defined that uniquely identifies it.\n* The first heading can be of any level, as long as no heading afterward is higher than it.\n  * For instance, if your content starts with an `h2`, there should not be an `h1` later in the document.\n\nThe following is a example of what a good heading structure looks like:\n\n```html\n<section id=\"main-content\">\n\t<h2 id=\"one\">One</h2>\n\t<h3 id=\"one-one\">One One</h3>\n\t<h3 id=\"one-two\">One Two</h3>\n\t<h4 id=\"one-two-one\">One Two One</h4>\n\t<h2 id=\"two\">Two</h2>\n\t<h3 id=\"two-one\">Two One</h3>\n\t<h4 id=\"two-one-one\">Two One One</h4>\n\t<h3 id=\"two-two\">Two Two</h3>\n</section>\n```\n\n### Labelling the Table of Contents\n\nThe table of contents represents a [navigation landmark](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/navigation_role). Therefore, it is good accessibility practice to label it.\n\nThis can be done with `aria-label`.\n\n```html\n<table-of-contents\n\tfor=\"main-content\"\n\taria-label=\"Table of Contents\"\n></table-of-contents>\n```\n\n### Manually Rebuilding the List\n\nThe `table-of-contents` element does **not** automatically react to changes in your document structure.\n\nInstead, the element provides a Javascript `build()` method so that you may define your own reaction logic, should it be needed. The `build()` method regenerates the list of links for the identified section.\n\n```javascript\nconst toc = document.querySelector(\"table-of-contents\")\n\ntoc.build()\n```\n\n### Fallback List\n\nChildren of the `table-of-contents` may serve as a fallback in case Javascript is disabled, fails, or takes a long time to execute. This is optional, but enhances the accessibility of your page.\n\nOnce the list generation occurs, the visible content is replaced with the new list. The fallback list will continue to exist in the DOM.\n\n```html\n<table-of-contents for=\"main-content\" aria-label=\"Contents\">\n\t<ol>\n\t\t<li><a href=\"#one\">One</a></li>\n\t\t<li><a href=\"#two\">Two</a></li>\n\t</ol>\n</table-of-contents>\n```\n\n## CSS Customization\n\nSince these are native custom elements, they can be styled the same way as regular HTML elements.\n\nThe `anchor` [part](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/part) exposes the links generated by the component.\n\n```css\ntable-of-contents::part(anchor) {\n\tcolor: red;\n}\n```\n\n## Accessibility\n\nThis custom element is built with accessibility in mind! A table of contents is a navigational landmark, and therefore the `table-of-contents` element gets granted the [navigation role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/navigation_role).\n\nThe best practice is to label your table of contents so readers know the content it is for. You may use `aria-label` or `aria-labelledby` for this.\n","readmeFilename":"README.md"}