progress indicator

See an article on piccalil.li/blog

Contents

• Install
• Example
• Use
  • render server-side
  • No build tools
  • Bundle
  • CSS
  • No build tools
  • link in HTML
  • Bundler
• develop
  • SSR

Install

npm i -S @substrate-system/progress-indicator

Example

See ./example/index.html.

See the demonstration.

This takes an attribute progress, which is a percent number from 0 - 100.

import { ProgressIndicator } from '@substrate-system/progress-indicator'
import '@substrate-system/progress-indicator/css'

ProgressIndicator.define()

<progress-indicator progress="10">
  <div role="alert" aria-live="polite">
    <!-- show this text iff the web component cannot render -->
    <p>Loading, please wait…</p>
  </div>
</progress-indicator>

Use

You've got options.

render server-side

This is factored as a "split component", which means it is easy to render server-side.

Import from the path /ssr. See ./example.

server

Import and build:

import { outerHTML } from '@substrate-system/progress-indicator/ssr'

// outerHTML takes the standard attributes

const myString = `
  <div id=root>
    ${outerHTML({ progress: 25 })}
  </div>
`

Client-side

If you pre-render the component server-side, then you can include a "light" version of the client-side JS, which just attaches event listeners and responds to attribute changes. It doesn't know how to render itself.

import { define } from '@substrate-system/progress-indicator/client'

define()

No build tools

It is possible to use this without building any JS. The package exposes a universal module, designed to be consumed directly.

After installing, copy the /umd.min.js path to your web server. It will define the component in the page registry, and any tags in the page will be hydrated.

copy

First copy the file to your server:

cp ./node_modules/@substrate-system/progress-indicator/dist/umd.min.js ./public/progress-indicator.js

<script src="/progress-indicator.js"></script>

HTML

And now you can use the tag in your markup:

<div id="root">
  <progress-indicator progress="0" stroke="8" viewbox="130">
    <!-- show  this text if we can't render web components -->
    <div role="alert" aria-live="polite">
      <p>Loading, please wait…</p>
    </div>
  </progress-indicator>
</div>

Bundle

If you are using a tool such as vite, just import, then use in your HTML.

Include the full version

import { ProgressIndicator } from '@substrate-system/progress-indicator'
import '@substrate-system/progress-indicator/css'

ProgressIndicator.define()

Include the light version

If you have already rendered server-side.

import { define } from '@substrate-system/progress-indicator/client'
import '@substrate-system/progress-indicator/css'

CSS

Include the CSS also.

No build tools

You can simply copy the CSS file to your server.

cp ./node_modules/@substrate-system/progress-indicator/dist/index.css ./public/progress-indicator.css

or the minified CSS:

cp ./node_modules/@substrate-system/progress-indicator/dist/index.min.css ./public/progress-indicator.css

link in HTML

<link rel="stylesheet" href="./progress-indicator.css">

Bundler

If you are using a tool such as vite, add a link to the css from within your javascript, at the /css path.

import '@substrate-system/progress-indicator/css'

develop

Start a localhost server of the ./example directory.

npm start

SSR

Use the /ssr path to render a static HTML file, and link to the "light" version of the client-side JS in HTML, then serve:

npm run example