@carissa-io/webkit-stats-band
v0.1.1
Published
Carissa web kit: stats band as a React component with SCSS variables
Readme
@carissa-io/webkit-stats-band
A row of real figures, each with its label, optionally under a title and a description. A React component, SCSS-themed, safe on the server, with no runtime dependency. It has no cards, no icons, no gradient, no default shadow and no motion.
The component has no strings of its own, and no numbers of its own. The site passes every figure and every label. The
look comes from the theme's second stylesheet, @carissa-io/theme-default/webkit.css, which apps do not load.
npm i @carissa-io/webkit-stats-bandUse
import { StatsBand } from '@carissa-io/webkit-stats-band'
<StatsBand
title={t('stats_title')}
items={[
{ id: 'sign-ins', value: '4.2M', label: t('sign_ins_label') },
{ id: 'delivery', value: '1.8 s', label: t('delivery_label'), note: t('delivery_note') },
{ id: 'passkeys', value: '38%', label: t('passkeys_label') },
]}
/>| Prop | |
|---|---|
| items | [{ id, value, label, note? }]. value is any node, label the text that says what it measures, note optional small text under the value, id the React key (the index when missing). An item without a value or a label is skipped; anything that is not an array renders no list |
| title | optional heading text; no heading when empty |
| title_level | 1 to 6, default 2; anything else falls back to 2 |
| description | optional paragraph under the title |
| as | the root tag, div by default; a value that is not a tag name falls back to div |
| className, id, aria-label, ... | className is appended; unknown props go to the root |
There is no eyebrow label. A value of 0 is a real figure and is kept; '', null, undefined and booleans are not.
Figures that count up are the site's choice
The band never animates. value takes any node, so a site that wants a figure to count up renders the library Counter
itself (@carissa-io/components-counter, which this package does not depend on):
import { Counter } from '@carissa-io/components-counter'
<StatsBand
items={[
{ id: 'sign-ins', value: <Counter value={4200000} locale="en-US" trigger="view" />, label: t('sign_ins_label') },
{ id: 'passkeys', value: <Counter value={38} suffix="%" trigger="view" />, label: t('passkeys_label') },
]}
/>Use a Counter only for real figures (the kit's motion budget): never animate a number that is not measured, and
keep it to one band per page. The Counter already shows the final value on the server and with reduced motion, and its
accessible text is the final value from the first render.
Accessibility
- A description list, label first. Each item is a
divgroup in adl:dtis the label,ddthe value, and a secondddthe note. The DOM order (label, value, note) is the reading order and is also the visual order: the band never reorders content with CSS (order,*-reverse), so a screen reader says "Median code delivery, 1.8 s, measured over the last 30 days" and what is read matches what is seen. The label sits above its figure. - Why not
figureandfigcaption: those mean an illustration with a caption, and put the caption after the figure; adlis the semantic for name and value pairs and lets assistive technology count the pairs. - The title is a real heading (
title_level) so a site can place the band in its outline. - The piece has no tab stops. Links a site puts in the description, a value or a note follow the piece colours
(
$c-stats-band-link-color) and the theme's focus ring; the piece styles nooutline.
Layout
An auto-fit grid: items sit in a row and wrap to the next row when one would be narrower than
$c-stats-band-item-min-width (12rem), so one, two, three or four figures fill the width without breakpoints. Each item
can carry a rule above it ($c-stats-band-item-border-width, none by default; the theme sets 1px). Long labels and values
wrap (overflow-wrap), nothing is truncated and there are no fixed widths.
Style
@use '@carissa-io/webkit-stats-band/scss' with (
$c-stats-band-value-font-size: 3.5rem,
$c-stats-band-item-border-width: 1px
);Classes: c-stats-band, c-stats-band__header, c-stats-band__title, c-stats-band__description, c-stats-band__list,
c-stats-band__item, c-stats-band__label, c-stats-band__value, c-stats-band__note. Every variable is !default
(see scss/_variables.scss); the defaults are neutral (inherited colours, transparent background,
no rules).
| Variable | Default |
|---|---|
| $c-stats-band-font-family, -color, -background | inherit, inherit, transparent |
| $c-stats-band-max-width | 80rem (header and list, centred) |
| $c-stats-band-padding-block, -padding-inline | 3rem, 1rem |
| $c-stats-band-header-gap, -header-margin-bottom | 1rem, 2.5rem |
| $c-stats-band-title-font-size, -font-weight, -line-height, -color, -max-width | 1.75rem, inherit, 1.15, inherit, 40ch |
| $c-stats-band-description-font-size, -line-height, -color, -max-width | 1rem, 1.5, inherit, 65ch |
| $c-stats-band-item-min-width, -gap | 12rem, 2rem |
| $c-stats-band-item-padding-block, -padding-inline, -item-gap | 1.25rem, 0, 0.5rem |
| $c-stats-band-item-border-width, -border-style, -border-color | 0, solid, currentcolor (the rule above each item) |
| $c-stats-band-label-font-size, -font-weight, -line-height, -color | 0.875rem, inherit, 1.3, inherit |
| $c-stats-band-value-font-size, -font-weight, -line-height, -letter-spacing, -color | 2.5rem, inherit, 1, normal, inherit |
| $c-stats-band-note-font-size, -line-height, -color | 0.875rem, 1.4, inherit |
| $c-stats-band-link-color, -link-text-decoration | inherit, underline |
