plass-ui 1.5.0 → 1.6.0

package/dist/tailwind.css

@@ -53,8 +53,11 @@
  * surface rather than looked at.
  *
  * Three values are hand-picked per family and everything else is derived with
- * `color-mix()`, so **adding a colour family is two edits**: one entry in
- * `PlassColor` and three lines here (plus its `accent` in each theme).
+ * `color-mix()`. Adding a family is still five places, though: one entry in
+ * `PlassColor`, those three lines here, an `accent` in each of the three theme
+ * blocks below, the eight derived declarations, which are written out per
+ * family rather than generated, and the Flutter package's own enum and
+ * families.
  *
  * `solid` and `solid-to` are the two ends of the gradient, at 135° — the
  * top-left corner and the bottom-right one. They are a **hue sweep at one
@@ -564,11 +567,21 @@
  * resolves its `var()`s on the element that declares it — declaring these only
  * on `:root` would freeze `--plass-*-tint` to the light theme's
  * `--plass-tint-strength` inside a `.dark` subtree.
+ *
+ * `.plass-theme` is the same reasoning applied to a *colour* override. Setting
+ * `--plass-primary-solid` on a `<div>` changes the base and nothing else,
+ * because every value derived from it was computed further up, where the old
+ * colour still is. The class re-runs the whole block on that element, so the
+ * gradient, the tint, the hairline and the ring follow the base that was just
+ * written beside them. It is the one hook here that does not force a theme:
+ * `--plass-tint-strength` and the rest inherit from whichever theme root is
+ * above, so a scoped family works the same in light and in dark.
  * ------------------------------------------------------------------------- */
 
 :root,
 .dark,
 .light,
+.plass-theme,
 [data-theme='dark'],
 [data-theme='light'] {
   /* The elevation ladder. Neutral, wide and faint — it climbs by *blur* far
@@ -793,6 +806,17 @@
  * never re-renders — the component writes the two custom properties directly.
  * ------------------------------------------------------------------------- */
 
+/*
+ * A stacking context of the surface's own, which is what lets the bloom below
+ * sit at a negative depth without falling through the surface it belongs to.
+ * `isolation` rather than a `z-index`, because a z-index is a position in a
+ * stack somebody else owns and this is only a statement that the two layers are
+ * the surface's business.
+ */
+.plass-glow {
+  isolation: isolate;
+}
+
 .plass-glow::before,
 .plass-glow::after {
   content: '';
@@ -803,8 +827,20 @@
   opacity: 0;
 }
 
-/* The bloom trailing the pointer across the surface. */
+/*
+ * The bloom trailing the pointer across the surface.
+ *
+ * **Under the label, and over the fill.** A positioned pseudo-element otherwise
+ * paints above every in-flow thing in the box, so the bloom was laid over the
+ * words on a key and over the value in a field — faint enough to miss on a
+ * white label and not on dark ink. `z-index: -1` puts it where a stacking
+ * context paints a negative layer, which is after the element's own background
+ * and before its content: over the gradient, under what is written on it. The
+ * flash below stays where it is, over everything, which is the pair the Flutter
+ * build draws as two separate widgets on either side of the label.
+ */
 .plass-glow::before {
+  z-index: -1;
   background: radial-gradient(
     6rem circle at var(--p-mx, 50%) var(--p-my, 50%),
     var(--p-glow, transparent),
@@ -1866,13 +1902,28 @@
   animation-name: plass-anim-lighting;
   animation-duration: var(--p-anim-duration, 3s);
   animation-delay: var(--p-anim-delay, 0ms);
-  animation-timing-function: linear;
+  /* Linear unless a caller says otherwise, which is what `curve` does in the
+     Flutter build: an arc that eases at both ends of a turn that has no ends
+     reads as a stutter, and that is a default rather than a rule. */
+  animation-timing-function: var(--p-anim-ease, linear);
   animation-iteration-count: var(--p-anim-repeat, infinite);
   animation-direction: var(--p-anim-direction, normal);
   animation-fill-mode: both;
   animation-play-state: var(--p-anim-state, running);
 }
 
+/*
+ * The rewind, for the one effect that runs on a pseudo-element.
+ *
+ * Restarting a CSS animation means clearing its name, forcing the style to
+ * settle and putting the name back, and an inline style cannot reach a
+ * `::before`. So the root carries `data-plass-rewind` for the length of that
+ * read, and this is what answers it. Nothing is painted in between.
+ */
+.plass-anim-lighting[data-plass-rewind]::before {
+  animation-name: none;
+}
+
 /*
  * Marquee: two identical copies, both moving by exactly one copy plus the gap.
  *

package/dist/tokens.css

@@ -56,8 +56,11 @@
  * surface rather than looked at.
  *
  * Three values are hand-picked per family and everything else is derived with
- * `color-mix()`, so **adding a colour family is two edits**: one entry in
- * `PlassColor` and three lines here (plus its `accent` in each theme).
+ * `color-mix()`. Adding a family is still five places, though: one entry in
+ * `PlassColor`, those three lines here, an `accent` in each of the three theme
+ * blocks below, the eight derived declarations, which are written out per
+ * family rather than generated, and the Flutter package's own enum and
+ * families.
  *
  * `solid` and `solid-to` are the two ends of the gradient, at 135° — the
  * top-left corner and the bottom-right one. They are a **hue sweep at one
@@ -567,11 +570,21 @@
  * resolves its `var()`s on the element that declares it — declaring these only
  * on `:root` would freeze `--plass-*-tint` to the light theme's
  * `--plass-tint-strength` inside a `.dark` subtree.
+ *
+ * `.plass-theme` is the same reasoning applied to a *colour* override. Setting
+ * `--plass-primary-solid` on a `<div>` changes the base and nothing else,
+ * because every value derived from it was computed further up, where the old
+ * colour still is. The class re-runs the whole block on that element, so the
+ * gradient, the tint, the hairline and the ring follow the base that was just
+ * written beside them. It is the one hook here that does not force a theme:
+ * `--plass-tint-strength` and the rest inherit from whichever theme root is
+ * above, so a scoped family works the same in light and in dark.
  * ------------------------------------------------------------------------- */
 
 :root,
 .dark,
 .light,
+.plass-theme,
 [data-theme='dark'],
 [data-theme='light'] {
   /* The elevation ladder. Neutral, wide and faint — it climbs by *blur* far
@@ -796,6 +809,17 @@
  * never re-renders — the component writes the two custom properties directly.
  * ------------------------------------------------------------------------- */
 
+/*
+ * A stacking context of the surface's own, which is what lets the bloom below
+ * sit at a negative depth without falling through the surface it belongs to.
+ * `isolation` rather than a `z-index`, because a z-index is a position in a
+ * stack somebody else owns and this is only a statement that the two layers are
+ * the surface's business.
+ */
+.plass-glow {
+  isolation: isolate;
+}
+
 .plass-glow::before,
 .plass-glow::after {
   content: '';
@@ -806,8 +830,20 @@
   opacity: 0;
 }
 
-/* The bloom trailing the pointer across the surface. */
+/*
+ * The bloom trailing the pointer across the surface.
+ *
+ * **Under the label, and over the fill.** A positioned pseudo-element otherwise
+ * paints above every in-flow thing in the box, so the bloom was laid over the
+ * words on a key and over the value in a field — faint enough to miss on a
+ * white label and not on dark ink. `z-index: -1` puts it where a stacking
+ * context paints a negative layer, which is after the element's own background
+ * and before its content: over the gradient, under what is written on it. The
+ * flash below stays where it is, over everything, which is the pair the Flutter
+ * build draws as two separate widgets on either side of the label.
+ */
 .plass-glow::before {
+  z-index: -1;
   background: radial-gradient(
     6rem circle at var(--p-mx, 50%) var(--p-my, 50%),
     var(--p-glow, transparent),
@@ -1869,13 +1905,28 @@
   animation-name: plass-anim-lighting;
   animation-duration: var(--p-anim-duration, 3s);
   animation-delay: var(--p-anim-delay, 0ms);
-  animation-timing-function: linear;
+  /* Linear unless a caller says otherwise, which is what `curve` does in the
+     Flutter build: an arc that eases at both ends of a turn that has no ends
+     reads as a stutter, and that is a default rather than a rule. */
+  animation-timing-function: var(--p-anim-ease, linear);
   animation-iteration-count: var(--p-anim-repeat, infinite);
   animation-direction: var(--p-anim-direction, normal);
   animation-fill-mode: both;
   animation-play-state: var(--p-anim-state, running);
 }
 
+/*
+ * The rewind, for the one effect that runs on a pseudo-element.
+ *
+ * Restarting a CSS animation means clearing its name, forcing the style to
+ * settle and putting the name back, and an inline style cannot reach a
+ * `::before`. So the root carries `data-plass-rewind` for the length of that
+ * read, and this is what answers it. Nothing is painted in between.
+ */
+.plass-anim-lighting[data-plass-rewind]::before {
+  animation-name: none;
+}
+
 /*
  * Marquee: two identical copies, both moving by exactly one copy plus the gap.
  *

package/dist/types.d.ts

@@ -131,6 +131,52 @@ 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.
+ *
+ * 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';
 /**
  * What a surface is made of. This is the library's own name, and the two
  * materials in it are the whole design language.
@@ -531,6 +577,15 @@ 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.
+     * @default false
+     */
+    dashed?: boolean;
 }
 /**
  * One span on a `PlTimelineChart` — a stretch of time with two ends.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "plass-ui",
-  "version": "1.5.0",
+  "version": "1.6.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",