code-anatomy v1.1.0

<code-anatomy/>

A native web-component which can identify parts of code; expected to be used in documentation pages to annotate.

Install

The project is distributed as an IIFE, so the easiest way is to just create a script tag pointing to the export hosted on unpkg.

<script src="unpkg.com/code-anatomy" defer></script>

However, you can also install the package and add the script through some build process.

<script src="dist/code-anatomy.iife.js" defer></script>

Usage

Once the script is loaded, you can add the new component to a page.

<code-anatomy language="css">
  body {
    font-family: sans-serif;
  }
</code-anatomy>

html, css, js languages are supported.

Edit Mode

When adding a new component to the page, no indicators will appear. You'll need to update the component with the edit attribute in order to allow editing. When in edit mode, you can click parts of the code to create markers and describe the feature in the numbered list that appears.

<code-anatomy language="css" edit>
  body {
    font-family: sans-serif;
  }
</code-anatomy>

Once you've completed editing, remove the edit attribute and copy the resulting HTML; specifically the data left in the definitions attribute. This describes your anatomy to be rendered the same way each time the component is loaded, assuming the content within the tags is the same.

<code-anatomy language="css" definitions="W3sieCI6IjMzJSIsInkiOiI0MCUiLC...">
  body {
    font-family: sans-serif;
  }
</code-anatomy>

You can also hit the Esc key on your keyboard to exit out of edit mode. This will also copy the resulting HTML to your clipboard, assuming your browser supports document.execCommand. Otherwise, you'll just need to view the resulting source code.

Additional Features

• The markers will become hidden in size when the figure is hovered; reducing the visual obstruction they would cause at normal size.
• You can hover any numbered list item to highlight the corresponding marker. This also occurs in edit mode.
• If you clear the description entirely in edit mode, the marker will be removed.
• You can create links using markdown syntax in the list items. After losing focus, the text will transform into a link. If you attempt to re-edit the link, it'll be lost. No other special formatting is included.

Manipulating Definitions

The definitions attribute value is an encoded JSON string. You can potentially update this yourself through JavaScript. For example, if you are storing the examples in a database or generating your own through some computed process. Manipulating this way isn't advised but it is possible.

const anatomy = document.querySelector('code-anatomy');
anatomy.remove(2) // Removes the third item
anatomy.update(0, { term: 'Update the description' }); // Updates the text of the first item

Each definition is an object ({ match, occurrence, term }). The match is the string found in the code to match. occurrence identifies which one of those to match within the code. This is useful if there's multiple of the same match found in the sample code. term is the description found in the list.

const anatomy = document.querySelector('code-anatomy');
anatomy.create({
  term: 'The description of the marker',
  match: 'font-family',
  occurrence: 0,
});

You may also clear all of the definitions with one command.

const anatomy = document.querySelector('code-anatomy');
anatomy.clear(); // Clears all items

You can also adjust the definitions array directly with varying degrees of freedom.

const anatomy = document.querySelector('code-anatomy');
anatomy.definitions = anatomy.definitions.concat({
  term: 'The description of the marker',
  match: 'body',
  occurrence: 0,
});

You must set a new array of definitions to re-render. Simply mutating the current array will not cause any changes to occur.

Attributes

Accessibility

Each marker is tabbable and aria-describedby an id that references the related item in the numbered list. When a numbered item is hovered, aria-current is applied to the marker.

Edit Mode is less accessible; the descriptions aren't tabbable. This is due to the re-render that occurs on blur of the description and focus is lost.

Customizing

Font styles are inherited from the components' ancestors. Changing the font attributes is as simple as changing them on the containing element or higher up. A <ol/> is used to display the list items; pay attention to the alignment of the numbers here. Monospaced fonts might look better as the list is aligned to the bullet, not to the left.

The text color for the numbered list items is also inherited. Other colors can be changed using CSS Custom Properties: