npm i -S @internetarchive/elementsimport "@internetarchive/elements/ia-button/ia-button";
...
<ia-button @click=() => alert('Clicked!')>Click Me</ia-button>npm i
npm run devEach component has its own directory in src/elements (or src/labs if it's still in development). The basic structure looks like this, though components can have additional files and directories if neededd. Take a look at other elements to see what they each contain.
src
- elements
- ia-foobar // the name of the element
- ia-foobar.ts // the main element class
- ia-foobar.test.ts // the element's tests
- ia-foobar-story.ts // an element that demos your element
Export your component in src/index.ts
To demo your component, we have a component catalog that you can add your demo to. Create a component in your component directory. Name it COMPONENT-NAME-story.ts, ie ia-button-story.ts.
We have a story template you can use for consistency. More info on story-template. The easiest way to use this is to copy an existing story and modify it for your needs.
Import your story in /demo/app-root.ts and add it to the page.
The story template is a component you can use in your story to demo your component. This lets us present them in a consistent way.
It has 5 main configurations:
Properties
elementTag(string) your component's name, ieia-buttonexampleUsage(string) your element's example usage, displays it with syntax highlightinglabs(boolean) if your component is inlabsto update links
Slots
demoput your component demo in heresettingsput your component settings in here
Here's an example:
import '@demo/story-template';
...
render() {
return html`
<story-template elementTag="ia-button" .exampleUsage=${this.exampleUsage}>
<div slot="demo">
<ia-button @click=${() => alert('Button clicked!')}
>Click Me</ia-button
>
</div>
<div slot="settings">
<table>
<tr>
<td>Color</td>
<td><input type="color" value="#007bff" id="color" /></td>
</tr>
</table>
<button @click=${this.apply}>Apply</button>
</div>
</story-template>
`;
}
// return a string of your element's usage and it will
// be displayed with syntax highlighting
// can be dynamic
private get exampleUsage(): string {
return `<ia-button @click=\${() => alert('Button clicked!')}>
Click Me
</ia-button>`;
}
private apply(): void {
// update component settings based on settings change
}To kickstart our library, we are going to take inventory of what already exists and can be ported, repurposed, or deprecated in favor of the single, common solution we are building here.
Below is a list of Lit web components that developers across the Internet Archive have built thus far for their respective teams.
- ads-button - 3 varieties, a few CSS params, and borderless styles. @jeffwklein (link)
- ia-button - Many CSS-based style variations, plus loading and disabled state support, including optional custom loading message. Point: @rebecca-shoptaw. (link)
- ads-table - Sortable columns, arrow key navigation, and multiselect support. @jeffwklein (link)
- modal-element (vault) - Latest modal for ADS, globally in use on Vault site. (ignore ads-modal) @jeffwklein (link)
- iaux-modal-manager - Finicky but powerful modal manager with a number of config options. Point: likely @latonv. (link)
- ads-tree (vault) - Basic tree component, CSS animation arrow rotation on folder expansion, powers Vault file explorer, has material-UI icon dependency. @jeffwklein (link)
- ads-card (vault) - Very basic card component, in use in Vault a couple places. @jeffwklein (link)
- ia-image-card - Simple component to display an image as a card, with an optional overlay color, hover-title, and on-click link. Used by various custom collections such as Democracy's Library. Point: @rebecca-shoptaw. (link)
- ads-toggle-switch (vault) - Nice toggle switch with CSS animation moving toggle back and forth. @jeffwklein (link)
- toggle-switch (UX team) - Toggle switch with screen-reader support and a lot of CSS customization options. Point: @latonv & @nsharma123. (link)
- ia-password-toggle - Intended for password inputs but definitely extensible, renders an eye open/closed icon that switches the type of any input passed in from
texttopasswordand back. Point: @rebecca-shoptaw. (link)
- Vault (@jeffwklein) uses material-web's
md-iconfont-based icon system. This project is unfor tunately in maintenance mode, but it nevertheless works well for Lit 3. - ia-icon - Icon designed to remove need for CSS-filtering, inherits current color by default and can inherit custom color via
color:or CSS variable. Point: @rebecca-shoptaw. (link) - iaux-icons - Icon monorepo that also exports an
ia-icon. Hopefully theia-iconabove can be folded into this one either by adding both to the library or using a library-hosted component within the icons repo. Point: @iisa & @jbuckner? (link) - ia-icons - Another icon repo, this one with separate widgets for individual icons, i.e.
ia-icon-video. Hopefully all three icon implementations here can be somehow standardized/combined in the new world. Point: @traceypooh. (link)
- ads-library - Includes: Helpful
fetch()abstraction, data formatters, event abstractions, a place for common code dependencies within the broader component library. @jeffwklein (link)
- basic-carousel (UX team) - Transforms any slotted content into a fully functioning carousel, including nav button showing/hiding, pagination-style-snapping, and custom arrow BG colors. Point: @rebecca-shoptaw. (link)
- ia-text-divider - Lightweight component to handle styling/rendering for the big ---OR--- divider used on i.e. the account settings page, can use custom text instead of
ORif desired. Point: @rebecca-shoptaw. (link)
- alert-banner (UX team) - Straightforward banner component with 3 urgency levels and an optional close button. Point: @jbuckner. (link)
- ia-otp-input (UX team) - Complex little component to handle rendering a 6-box OTP input. Autofocuses first input, hops between inputs, supports pasting, autocomplete, a custom number of boxes and a custom allowed-characters regex (defaults to numeric-only). Used i.e. in the
Email me a codemodal on the account settings page. Point: @rebecca-shoptaw. (link) - ia-clearable-text-input - Text input with a clear button and substantial a11y support. Point: @latonv. (link)
- infinite-scroller (UX team) - Supports virtualized buffered scrolling of large lists. Point: @latonv. (link)
- collection-histogram (UX team) - Histogram component, only used on collection pages at the moment, but the component is fairly general already. Point: @latonv. (link)
- histogram-date-range (UX team) - Date range component for histogram, which we might explore consolidating with the above. Point: @latonv. (link)
- ia-activity-indicator - SVG-based circular activity indicator with two mode options, used in
ia-buttonand throughout site. Point: @jbuckner. (link) - circular-activity-indicator (UX team) - Variation on the IA activity indicator with CSS variable customization. Point: @jbuckner. (link)
- horizontal-activity-indicator (UX team) - Horizontal page-wide activity indicator, relies on the
sharedResizeObserverwhich we'd need to convert and generalize as well. Point: @jbuckner. (link)
- SharedResizeObserver - Could be made into a more declarative component similar to what Shoelace has done. I.e., the component itself manages attaching/detaching the shared observer instance from its slotted children as part of its lifecycle, so that we don't have to repeat that logic all over our other components. Used by horizontal activity indicator and carousel. Point: @latonv. (link)
- ia-sronly - Importable CSS class to quickly style screen-reader-only text. Point: @nsharma123. (link)