GrValue — Components

Overview

When to take it

you are writing a component of your own with a quantity — a tile, a cell, a row of a report: the affixes will be styled the same way as in the rest of the package, with no copying of classes;
the currency stands on the right — 100 ₽ rather than $100: the side is set by which affix the symbol is put into;
the quantity is not a number — “2 h 15 min”, ”—”, “n/a” are printed as they are;
markup of your own is needed around the value — the sign, an arrow, a hidden label go into the slots between the parts of the record.

When to take something else

Need	Take
The sign and a tone by the sign inside a line of text	`GrDelta`
A large metric as a tile, with a label and a trend	`GrStatistic`
The value as a status or a label	`GrBadge`
A “property → value” pair	`GrDescriptionList`
Formatting a number by locale	`formatStatisticValue` from `GrStatistic`

Playground controls come from the API, not from hand

Stage

Loading…

0 changed· state is in the URL

Examples 4 each with a live demo and its code

A ready value and its affixes
The value arrives formatted — Intl on the caller’s side, «2 days 6 h» or «—» as they are — and the component only lays out the affixes: a prefix takes the colour and size of the number, a suffix is muted, smaller and set off.
Team plan · 9 seats
€432.00
Extra storage · 180 GB
€36.00
Automation runs over quota
€12.40
Discount
—
VAT
20%
Total due€576.48
Next charge in 2 days 6 h
A currency on the right
The side of the symbol is chosen by the affix, not by the locale. A currency after the number is still part of the amount, so --gr-value-suffix-color: currentColor and --gr-value-suffix-size: 1em lift the muting that suits a unit like ms.
- Germany€1,284.50
- Poland5 480,00zł
- Sweden14 990kr
- United States$1,399.00
Median response 182ms
Tone and size come from the parent
The value has no scale or tone of its own: a headline sets it large, a table cell sets it small and red, and the currency follows the number in both. The sign goes into the lead slot, before the prefix, and the column lines up on tabular figures.
Net revenue, September€55,963.80
Subscriptions +€48,920.00 72.4%
Services +€12,850.00 19.0%
Refunds −€4,320.00 6.4%
Payment fees −€1,486.20 2.2%
A price set by hand
Every part of the record has a slot: lead holds «from», prefix a raised currency, the default slot a number with smaller cents, suffix the period, and trail a phrase only a screen reader hears.
Starter
€ 0euros per seat a month/ seat · month
free for up to 3 members
Team
from€ 48.00euros per seat a month/ seat · month
billed yearly
Business
from€ 96.50euros per seat a month/ seat · month
billed yearly

API generated from the package · cannot drift

Props

Prop	Type	default	Description
`value`	`string \| number \| null \| undefined`	—	A value ready for display. It is not formatted: "2 h 15 min" and "—" are quantities too.
`prefix`	`string \| undefined`	—	An addition before the value: a currency, a sign of approximation.
`suffix`	`string \| undefined`	—	An addition after the value: a unit of measurement, a currency on the right.

Slots

Slot	Type	Description
`default`	`any`	The value instead of the prop.
`prefix`	`any`	An addition before the value.
`suffix`	`any`	An addition after the value.
`lead`	`any`	Before the prefix: the sign of the quantity in `GrDelta`, an arrow of the direction. A slot rather than a prop — the markup there belongs to the consumer.
`trail`	`any`	After the value: a hidden node for the screen reader in `GrStatistic`.

Types

Every exported type of the subpath, grouped by the file it lives in. Names, generics and bodies come from the package’s declaration files and cannot drift.

Import

import type { GrValueProps } from '@feugene/granularity/components/GrValue'

Filedist/types/components/GrValue/config.d.ts

grValueConfigconst

const grValueConfig: import("@feugene/granum/contract").GranumComponentDescriptor<"GrValue">;

Filedist/types/components/GrValue/GrValue.vue.d.ts

GrValuePropsinterface

interface GrValueProps {
    value?: string | number | null;
    prefix?: string;
    suffix?: string;
}

Filedist/types/components/GrValue/safelist.d.ts

grValueSafelistconst

const grValueSafelist: string[];

Usage from the library prose

The quantity arrives ready

The primitive formats nothing: the digit groups, the precision and the separators are the concern of whoever passes the value. That is not a saving but a boundary of responsibility: “2 h 15 min” and ”—” are quantities just as 1 284 500 is, and a component that tried to parse them would spoil both.

Formatting by locale exists in the package — formatStatisticValue; it is available separately and combines with the primitive in any way at all.

An affix is not necessarily a unit of measurement

The component does not decide what an affix is. That is its whole point: $, ₽, %, ms, “per order” are different things, and one rule for all of them will lie one day.

The defaults are chosen by frequency rather than by truth:

	The prefix	The suffix
the colour	as in the quantity	dimmed
the type size	as in the quantity	smaller
the spacing	none	there is some

Behind them stands an observation: on the left people more often write the currency, and it is part of the sum; on the right more often a unit, and it does not belong to the quantity. $14.99 and 42 % come out by themselves.

A currency on the right — remove the dimming

The rouble is written after the number, but it is as much part of the sum as the $ before it. The default of the suffix therefore does not fit it, and it is changed with tokens:

vue

<GrValue
  :value="formatted"
  suffix="₽"
  style="--gr-value-suffix-color: currentColor; --gr-value-suffix-size: 1em"
/>

An application where it is always so finds it more convenient to declare that in a class once:

css

.amount { --gr-value-suffix-color: currentColor; --gr-value-suffix-size: 1em; }

Precisely currentColor and 1em rather than inherit. For a custom property inherit is the keyword for inheriting the variable itself: it means “take its value from the parent”, and the parent does not have it, so the token stays undefined. The fallback then fires as usual, and the affix looks untouched — the edit silently gives nothing. currentColor and 1em are real values, and they mean exactly what is needed: the colour and the type size of the quantity.

The component does not choose the side of the symbol. The temptation to infer it from the locale is there, but Intl places the currency by locale rather than by currency: in ru-RU they all end up on the right, the dollar included (1 284 500,50 $), and in en-US all on the left, the rouble included (RUB 1,284,500.50). The familiar ”₽ on the right, $ and € on the left” is a mixed product rule, and there is nowhere to infer it from. It is decided by the consumer, by choosing the affix.

The tone reaches the affix by itself

The colour of the prefix is inherit by default rather than a copy of the tone role. The difference is visible on a negative sum: the whole record turns red, not the number without the currency sign. The tone is therefore set once on the parent — that is what GrStatistic does — and the primitive does not need to know about it.

The type size is inherited the same way: the primitive has no size scale of its own, and the quantity is set in the type size of the place it stands in.

Limits

The positions of the affixes are fixed: the prefix on the left, the suffix on the right. The order is changed neither by a prop nor by the locale — a quantity whose affixes swap places is two different records, and only the author of the screen can choose between them.