plass-ui 1.5.0 → 1.7.0

package/dist/types.d.ts

@@ -131,6 +131,65 @@ export type PlassOverscroll = 'auto' | 'contain';
  * a caller spell `{ vertical: 'left' }`.
  */
 export type PlassCorner = 'top-start' | 'top-end' | 'bottom-start' | 'bottom-end';
+/**
+ * Where a **field-shaped** control puts the name of what it holds.
+ *
+ * The placements a box has to offer, which are not the placements a tick has:
+ * a PlCheckbox, a PlRadio and a PlSwitch put their label beside themselves and
+ * take `labelPlacement` out of `PlassAlign` instead — same question, same prop
+ * name, the answers each shape actually has. See `PlSwitchLabelPlacement`.
+ *
+ * - `top` — above the control, on its own line. The default, and the one that
+ *   is always safe: the label is a block of text in the layout, it can wrap, it
+ *   can be as long as it needs to be, and nothing about the control's edge has
+ *   to make room for it.
+ * - `notch` — in the control's own top edge, with the hairline cut away behind
+ *   it. The label stops being a line of the form and becomes part of the field,
+ *   which buys back a row of vertical space and ties the name to the box rather
+ *   than to whatever is above it.
+ * - `float` — inside the control, where its value would be written, while the
+ *   control is empty and nothing in it has the focus; it rises into the notch
+ *   the moment either stops being true, and comes back down when both are true
+ *   again. At rest it is set as the placeholder it stands in for is — the
+ *   control's text size, the regular weight and the muted ink — and the
+ *   placeholder waits until the label has risen.
+ *
+ * A `float` label moves on its position, its font size and its weight and
+ * never on a `transform`: it is set again at every size on the way, so no
+ * frame of it is a scaled picture of the word. A control that draws something at its start —
+ * a `startIcon`, a picker's glyph, a number field's split steppers — keeps a
+ * `float` label in the notch, because the place it would rest is taken, and so
+ * does a `PlFilePicker`, whose box has words of its own there.
+ *
+ * The cut is a real one — a `<legend>` in a `<fieldset>`, which is the only way
+ * to take a segment out of a border without knowing what is behind it. Nothing
+ * here paints over the line with the page's colour, because a library that does
+ * not paint the page cannot know what colour that is, and a Plass field is
+ * translucent besides.
+ *
+ * Two things follow from the label sitting on the edge, and both are deliberate:
+ *
+ * - **Focus is the edge thickening rather than a ring.** An outline is a
+ *   rectangle and would run straight through the label. The edge that is
+ *   already there goes to 2px and takes the family's colour instead, which is
+ *   what the flush ring was drawn to look like anyway.
+ * - **The label no longer widens the control.** It is out of the flow, so a
+ *   label longer than a narrow field runs past its end. Give the field
+ *   `fullWidth`, or keep the word short — a notch is a place for "Email", not
+ *   for a sentence.
+ *
+ * Only `glass` has a hairline to cut. On `solid` and `ghost` the label sits in
+ * the same place and there is simply nothing there to take out, so a form that
+ * mixes the three keeps one baseline for its labels.
+ *
+ * **`PlOtpField` is the one labelled field that does not take this**, and the
+ * reason is the same one that decides everything above: a notch is a segment
+ * taken out of one continuous edge, and a row of separate boxes with gaps
+ * between them has no such edge. Cutting only the first box leaves the word
+ * lying across the two after it, which is worse than the label above the row
+ * that it keeps.
+ */
+export type PlassFieldLabelPlacement = 'top' | 'notch' | 'float';
 /**
  * What a surface is made of. This is the library's own name, and the two
  * materials in it are the whole design language.
@@ -254,7 +313,7 @@ export type PlassColorSlot = 'accent' | 'fill' | 'line' | 'line-hover' | 'on-sol
  * sets one is setting the answer rather than the question. `color`, `variant`
  * and `elevation` are the props that decide them.
  */
-export type PlassToken = `--plass-${PlassColor}-${PlassColorSlot}` | `--plass-radius-${PlassSize}` | `--plass-shadow-${0 | 1 | 2 | 3 | 4}` | `--plass-chart-${1 | 2 | 3 | 4 | 5 | 6 | 7 | 8}` | `--plass-chart-seq-${1 | 2 | 3 | 4 | 5}` | `--plass-chart-div-${1 | 2 | 3 | 4 | 5}` | `--plass-chart-seq-on-${1 | 2 | 3 | 4 | 5}` | `--plass-chart-div-on-${1 | 2 | 3 | 4 | 5}` | '--plass-chart-grid' | '--plass-chart-axis' | '--plass-chart-baseline' | '--plass-chart-gap' | '--plass-shadow-ambient' | '--plass-bg-from' | '--plass-bg-to' | '--plass-blur' | '--plass-border' | '--plass-breakpoint-sm' | '--plass-breakpoint-md' | '--plass-breakpoint-lg' | '--plass-breakpoint-xl' | '--plass-divider' | '--plass-duration' | '--plass-duration-slow' | '--plass-ease' | '--plass-fg' | '--plass-flash-on-fill' | '--plass-glass' | '--plass-glass-hover' | '--plass-glass-line' | '--plass-glass-press' | '--plass-gloss-glass' | '--plass-glow-angle' | '--plass-glow-on-fill' | '--plass-muted-fg' | '--plass-scrim' | '--plass-stripe' | '--plass-surface' | '--plass-tint-strength' | '--plass-track' | '--plass-well' | '--plass-z-portal';
+export type PlassToken = `--plass-${PlassColor}-${PlassColorSlot}` | `--plass-radius-${PlassSize}` | `--plass-shadow-${0 | 1 | 2 | 3 | 4}` | `--plass-chart-${1 | 2 | 3 | 4 | 5 | 6 | 7 | 8}` | `--plass-chart-seq-${1 | 2 | 3 | 4 | 5}` | `--plass-chart-div-${1 | 2 | 3 | 4 | 5}` | `--plass-chart-seq-on-${1 | 2 | 3 | 4 | 5}` | `--plass-chart-div-on-${1 | 2 | 3 | 4 | 5}` | '--plass-chart-grid' | '--plass-chart-axis' | '--plass-chart-baseline' | '--plass-chart-gap' | '--plass-shadow-ambient' | '--plass-bg-from' | '--plass-bg-to' | '--plass-blur' | '--plass-border' | '--plass-bottom-navigation-height' | '--plass-breakpoint-sm' | '--plass-breakpoint-md' | '--plass-breakpoint-lg' | '--plass-breakpoint-xl' | '--plass-divider' | '--plass-duration' | '--plass-duration-slow' | '--plass-ease' | '--plass-fg' | '--plass-flash-on-fill' | '--plass-glass' | '--plass-glass-hover' | '--plass-glass-line' | '--plass-glass-press' | '--plass-gloss-glass' | '--plass-glow-angle' | '--plass-glow-field-strength' | '--plass-glow-on-fill' | '--plass-muted-fg' | '--plass-scrim' | '--plass-stripe' | '--plass-surface' | '--plass-tint-strength' | '--plass-track' | '--plass-well' | '--plass-z-portal';
 /**
  * A set of token overrides, on its own.
  *
@@ -512,6 +571,17 @@ export interface PlassChartSeries {
      * the reader cannot identify.
      */
     name?: string;
+    /**
+     * What the chart knows it by from one render to the next, for a series whose
+     * name is not enough: one that shares its name with another, or one whose
+     * name changes.
+     *
+     * Its legend entry, whether the legend has it switched off, the pointer
+     * resting on that entry and a mark of it being read are held by it. Without
+     * one, a series is known by its name and how many series before it have that
+     * name, or by its place in the array when it has no name.
+     */
+    id?: string;
     /** The values, in category order. */
     data: readonly PlassChartDatum[];
     /**
@@ -531,6 +601,16 @@ export interface PlassChartSeries {
      * @default false
      */
     hidden?: boolean;
+    /**
+     * Draws the line dashed — a forecast, a target, a last year.
+     *
+     * Only a line has a line to dash, so it does nothing on a bar, and nothing on
+     * a stacked area either, where the band's fill *is* the mark and there is no
+     * stroke along its top. Where the line is dashed, its legend entry is a short
+     * dashed rule rather than a square.
+     * @default false
+     */
+    dashed?: boolean;
 }
 /**
  * One span on a `PlTimelineChart` — a stretch of time with two ends.
@@ -574,6 +654,27 @@ export interface PlassTimelineSeries {
 }
 /** How a line gets from one point to the next. */
 export type PlassChartCurve = 'linear' | 'smooth' | 'step';
+/**
+ * What a gap in a series does to the line drawn through it.
+ *
+ * A `null` in the data means *nothing was measured*, which is a different claim
+ * from *nothing happened*, and the three answers here are the three ways a
+ * chart can respond to it. Picking the wrong one is how a chart comes to say
+ * something the data did not.
+ *
+ * - `gap` — the line stops at the last reading and starts again at the next
+ *   one. The default, and the only answer that adds nothing: the blank says the
+ *   month is missing, which is what the data says.
+ * - `connect` — the two sides are joined by one straight segment. Right when the
+ *   gap is an artefact of how the data was collected — a sensor that missed a
+ *   reading, a day the export skipped — and wrong otherwise, because the line
+ *   between the two ends is a number the chart made up.
+ * - `zero` — the gap is read as a zero, on the axis, in the tooltip and in the
+ *   table as well as under the line. Right when a missing row genuinely means
+ *   none: no orders that day, no errors that hour. It moves the scale, which is
+ *   the point — a zero is a value, and it has to be somewhere on the axis.
+ */
+export type PlassChartNulls = 'gap' | 'connect' | 'zero';
 /**
  * Which values are written onto the marks themselves.
  *
@@ -584,19 +685,56 @@ export type PlassChartCurve = 'linear' | 'smooth' | 'step';
  */
 export type PlassChartValueLabels = 'none' | 'last' | 'extremes' | 'all';
 /**
- * What the pointer uncovers.
- *
- * - `index` — every series at the category under the pointer, with a crosshair.
- *   The default on anything with a shared x axis, because the question a line
- *   chart is asked is "what happened in March", not "what is this pixel".
- * - `item` — the one mark being pointed at.
- * - `none` — no tooltip. The values still have to be readable some other way.
- */
-export type PlassChartTooltipMode = 'index' | 'item' | 'none';
+ * What colour the numbers written on the marks are.
+ *
+ * - `series` — each label in the colour of the line or the bar it is sitting
+ *   on. The default: a plot with four labelled series says which number belongs
+ *   to which mark without the reader tracing it back.
+ * - `ink` — the page's own foreground, for every label. The palette clears 4:1
+ *   against the sheet, which is the floor a chart *mark* is held to rather than
+ *   the 4.5:1 body text wants, so this is the answer for a chart whose labels
+ *   have to meet the text contrast rule on their own.
+ */
+export type PlassChartLabelColor = 'series' | 'ink';
+/**
+ * Which way a chart's categories are put in order.
+ *
+ * A bar chart is the one shape whose categories can be shuffled without losing
+ * anything — that is the test for reaching for it over a line chart — so
+ * sorting them is free, and it is what turns a wall of bars into a ranking a
+ * reader can scan down. `none` leaves them in the order they were given, which
+ * is right wherever that order already means something: months, sizes, a
+ * funnel's steps.
+ */
+export type PlassChartSort = 'none' | 'ascending' | 'descending';
+/**
+ * How much of a chart a pointer summons.
+ *
+ * - `index` — every series at the category the pointer is over, with a
+ *   crosshair down the column to say which one that is. The default on a chart
+ *   whose marks sit in a grid, and the right answer when the reader is
+ *   comparing series *at* a moment.
+ * - `item` — the same column narrowed to the one series the pointer is nearest
+ *   along the value axis. For a plot with more series than a panel can hold.
+ * - `nearest` — the one **mark** the pointer is nearest, measured in both
+ *   directions rather than down a column. It is what a scatter has always done,
+ *   and on a line or an area it is the answer when two series cross and the
+ *   reader is pointing at one of them rather than at the month they share.
+ *   There is no crosshair with it: a crosshair says "these numbers all belong
+ *   to this column", and there is no column. It measures to the mark, which on
+ *   a bar is the bar's data end.
+ * - `none` — no tooltip at all. The table under the chart still has every
+ *   number.
+ */
+export type PlassChartTooltipMode = 'index' | 'item' | 'nearest' | 'none';
 /** One series' answer at the category the pointer is on. */
 export interface PlassChartTooltipItem {
     /** Its place in the `series` array — the same index its colour came from. */
     seriesIndex: number;
+    /**
+     * The series' name. On a `PlTimelineChart`, whose `category` is the row, it
+     * is the span's own `label` in words, and absent for a span with none.
+     */
     name?: string;
     color: string;
     value: number | null;
@@ -645,8 +783,69 @@ export interface PlassChartAxis {
     max?: number;
     /** Roughly how many ticks. The scale still rounds to clean numbers. */
     tickCount?: number;
-    /** How a tick is written, overriding the chart's own `format`. */
+    /**
+     * Whether the axis steps by adding or by multiplying.
+     *
+     * `log` is the one scale in the library that changes what a distance on the
+     * plot means: the same length becomes the same **ratio** rather than the same
+     * number of units, so the gap from 10 to 100 is the gap from 100 to 1,000.
+     * It is the only way a series that runs from 3 to 3,000,000 can be drawn with
+     * the small end still legible, and it has to be labelled as what it is — a
+     * reader who takes it for linear reads every shape on it wrong.
+     *
+     * There is no zero on it, and nothing below one either. An axis whose data
+     * reaches either floors at the smallest positive power of ten it needs, or
+     * three decades under the top when the data offers none, and those values are
+     * drawn on that floor. A bar is the wrong mark for it for the same reason a
+     * bar's axis cannot be cropped: what a bar encodes is a length, and on a log
+     * axis a bar twice as long is not twice as much.
+     *
+     * Read on the **value** axis, and on a category axis only where that axis is
+     * a second value axis — a `PlScatterChart`'s. A band of categories has no
+     * arithmetic to do, and a time axis has its own.
+     * @default 'linear'
+     */
+    scale?: 'linear' | 'log';
+    /**
+     * How a tick is written, overriding the chart's own `format`.
+     *
+     * An element it returns is written as the words in it, so `<b>12</b>` puts
+     * `12` on the axis: a tick is SVG text, which holds words and no markup.
+     */
     tickFormat?: (value: PlassChartCategory, index: number) => React.ReactNode;
+    /**
+     * Turns the labels, in degrees, so long names fit without being cut.
+     *
+     * An axis runs out of room across and not down, so a name wider than its slot
+     * is cut to it — and past about four characters a cut stops telling two names
+     * apart, which is when this is the answer instead. A turned label takes one
+     * line of text across the axis however long it is, and spends the room under
+     * the plot, where a chart usually has some.
+     *
+     * `-45` is the one to reach for: it reads at a glance, and the negative sign
+     * runs the text up towards the right, the way every chart that does this
+     * draws it. `-90` stands it on end, which fits the most labels in the least
+     * width and is the one that has to be read with a tilted head. A positive
+     * angle leans the other way, down to the right.
+     *
+     * `'auto'` asks the axis: it stays upright while every name fits its slot,
+     * and turns to `-45` as soon as one of them would be cut. Upright is the best
+     * an axis can do when there is room for it, and a diagonal beats a cut at
+     * every width — so this is the setting for a chart whose categories are the
+     * caller's data rather than the caller's choice. It settles on one of those
+     * two angles and never on a third: an angle fitted to the longest name would
+     * be a different angle on every chart on a dashboard, and would change under
+     * the reader as the window is dragged.
+     *
+     * The band under the plot grows to hold whatever is asked for, up to about
+     * two fifths of the chart's height; a name longer than that is still cut, and
+     * the tooltip and the table still have all of it. Only the **category** axis
+     * turns — a value axis' ticks are numbers already rounded to be short — and
+     * only where that axis runs along the bottom, so it does nothing on a
+     * horizontal bar chart, whose category names are already one to a row.
+     * @default 0
+     */
+    tickAngle?: number | 'auto';
     /**
      * How much room the axis keeps for its ticks and its label, in pixels.
      * Measured from the ticks themselves otherwise; set it when a long category
@@ -655,6 +854,50 @@ export interface PlassChartAxis {
      */
     thickness?: number;
 }
+/**
+ * A line drawn across the plot at one value — a target, an average, a limit.
+ *
+ * It is **not data**, and it is drawn as if it knows that: dashed by default,
+ * in the muted ink rather than in a palette slot, under the marks rather than
+ * over them. A reference that looks like a series is a reference a reader will
+ * try to read a value off.
+ *
+ * It sits on the **value** axis, which means it runs across a vertical chart
+ * and down a horizontal one — the same line, drawn on whichever axis the values
+ * are on. A marker on the category axis is a different thing and is not this:
+ * a band of categories has no value to put a line at, and a column a reader
+ * should be looking at is a column that wants its own colour rather than a rule
+ * beside it.
+ *
+ * Every reference is also written into the description a screen reader is given
+ * with the chart, because a target is a fact about the picture rather than
+ * decoration on it.
+ */
+export interface PlassChartReference {
+    /** Where it sits, read on the value axis. */
+    value: number;
+    /**
+     * A short word set at the end of the line — "Target", "Last year". Left out,
+     * the line is drawn and says nothing, which is right when the page around the
+     * chart has already named it.
+     */
+    label?: string;
+    /**
+     * Overrides the muted ink it is otherwise drawn in. A `PlassColor` family
+     * name, or any CSS colour.
+     *
+     * Reach for it where the line means something the page already has a colour
+     * for — a `danger` limit, a `success` target — and not to make it louder: a
+     * reference that outshouts the data has inverted the chart.
+     */
+    color?: PlassColor | (string & {});
+    /**
+     * Whether the line is dashed. On, because a solid rule across a plot is what
+     * a gridline is, and the two must not be confused.
+     * @default true
+     */
+    dashed?: boolean;
+}
 /** Where the legend sits, and whether it does anything when clicked. */
 export interface PlassChartLegend {
     /** Which edge of the plot. @default 'bottom' */
@@ -668,4 +911,20 @@ export interface PlassChartLegend {
     interactive?: boolean;
     /** Draws each series' current value beside its name. @default false */
     showValue?: boolean;
+    /**
+     * Shows this many entries and folds the rest behind a button that opens them.
+     *
+     * A legend is a key, and a key of twelve names wrapped over four rows is a
+     * paragraph the reader has to search — on a card, it is also four rows the
+     * plot no longer has. Folding keeps the legend one or two rows tall and
+     * leaves the rest one press away, which is the right trade whenever the
+     * reader is looking up *one* series rather than reading the list.
+     *
+     * The entries kept are the first ones, in the order the series were passed,
+     * because that is the order their colours were handed out in and the order
+     * the reader has already learned. Nothing is hidden from a screen reader by
+     * it: the fold is a real button that says how many are behind it, and every
+     * series is in the table under the chart either way.
+     */
+    maxEntries?: number;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "plass-ui",
-  "version": "1.5.0",
+  "version": "1.7.0",
   "description": "A React UI component library made of glass and gradients — smooth tinted surfaces, shadows in their own colour, and light that follows the pointer. Accessible and themeable, ESM only, types included, dark mode built in.",
   "type": "module",
   "types": "dist/index.d.ts",