@blakesteve/roster 4.8.0 → 4.8.2

package/README.md

@@ -152,6 +152,12 @@ makes no difference, because the portal is still a descendant. If you scope
 the field and carries it across the portal, so the menu follows the same scope
 the trigger is in.
 
+That mechanism carries the `.dark` CLASS across the portal. It does not carry
+custom properties: `--roster-popover-*` and any other variable you scope to a
+container reach the trigger and stop at the portal boundary, because the panel
+is not a descendant of your container. Set those at `:root`. See
+[Floating surface colors](#floating-surface-colors).
+
 `Navbar`'s `themeMode` prop is a different thing: it describes what palette the
 bar paints _itself_ with. Pair them with `themeMode="auto"` and the nav follows
 whatever `ThemeToggle` sets.
@@ -254,6 +260,9 @@ Note also that a solid fill's contrast against the surface _behind_ it is a
 separate requirement (WCAG 1.4.11, 3:1) and is not covered here. Solid amber on
 a white page is 1.67:1, so it has effectively no visible edge.
 
+Form controls **are** covered for that requirement, separately: see
+`--roster-control-border` under [Control surface colors](#control-surface-colors).
+
 ### Focus
 
 Every focusable control draws the same ring: `--roster-ring` for the ring
@@ -262,6 +271,24 @@ control's own fill. Both flip with the theme — `primary-500` on white in light
 `primary-400` on `gray-950` in dark — which puts the indicator at 6.37:1 and
 7.31:1 against the surface either side of it, where WCAG 1.4.11 asks for 3:1.
 
+Both tokens follow the **page**, which is right until a component deliberately
+inverts against it. `Dialog`'s `slate` and `primary` are dark whatever the page
+is doing, so on a light page they were handing their contents the light-mode
+ring: `primary-500` on `gray-700` is **1.61:1**, and the white offset behind it
+was 10.27:1, making the gap the most visible part of the indicator. Those two
+variants now set both tokens on their own subtree, so a field inside them gets
+3.80:1 and 4.04:1 instead. `white` and `glass` are left alone because they
+follow the page like everything else.
+
+If you build your own inverted surface, do the same on it:
+
+```css
+.my-dark-panel {
+  --roster-ring: var(--roster-primary-400);
+  --roster-ring-offset: /* that panel's own background */;
+}
+```
+
 Retint it for your own accent:
 
 ```css
@@ -359,40 +386,55 @@ pseudo-elements for any element that sets either of them, so on anything modern
 
 ### Control surface colors
 
-`Input`, `PasswordInput` and `Select` read these variables in their `outline`
-variant, so a consumer can repaint a form control without restating the class
-list.
+`Input`, `PasswordInput`, `Textarea` and `Select` read these variables, so a
+consumer can repaint a form control without restating the class list. Both
+`outline` and `soft` read the border: `soft` used to be borderless and lean on
+its fill alone, which fails the moment the fill matches the surface — a `soft`
+field inside a `white` Dialog in dark mode was exactly 1.00:1 and invisible
+until focus.
 
 ```css
 :root {
-  --roster-control-border: #d6d3d1;
+  --roster-control-border: #65635f; /* gray-500 */
   --roster-control-bg: transparent;
   --roster-control-text: #1c1917;
   --roster-control-border-focus: #0f6498;
 }
 .dark {
-  --roster-control-border: #44403c;
+  --roster-control-border: #a8a29e; /* gray-400 */
   --roster-control-bg: transparent;
   --roster-control-text: #f5f5f4;
-  --roster-control-border-focus: #0f6498;
+  --roster-control-border-focus: #5ea3de; /* primary-400 */
 }
 ```
 
+`--roster-control-border` is the one token here whose two scopes hold different
+values, and that is deliberate. WCAG 1.4.11 asks 3:1 to identify a control, and
+a border has to move opposite its surface to get there: gray-500 reaches 5.99
+on white but only 2.53 on a gray-800 Dialog, while gray-400 reaches 6.01 there
+and 2.52 on white. No single step of the ramp clears 3:1 both ways. The old
+gray-300 / gray-700 pair was 1.49 and 1.48 — a hairline rather than a boundary.
+
 Set them in both scopes, for the same reason the scrollbar thumb needs both:
 Roster's own `.dark` rule has equal specificity and comes later.
 
-The defaults are the values the component used to hardcode, so installing this
-version changes nothing on its own. Placeholder color, the error state, and the
+Three of the four still default to what the components used to hardcode.
+`--roster-control-border` does not — the 1.4.11 pass moved it two ramp steps —
+so installing this version **does** change how your fields look, deliberately. Placeholder color, the error state, and the
 focus ring are deliberately not on tokens — the ring is already
 `--roster-ring`, and error styling should stay recognizably an error.
 
 Not every control uses every token: `Select` takes the first three, because
-focus on its trigger is the shared `--roster-ring` rather than a border color.
+focus on its trigger is the shared `--roster-ring` rather than a border color,
+and it draws the border as a ring rather than a border.
 One family rather than one per component is deliberate — these controls sit in
 the same row of the same form and are drawn to look identical, so being able to
 repaint one and not the other would be a bug, not a choice.
 
-The `outline` variant is the only one that reads them, in every component, and
+`outline` reads all four. `soft` reads the border only, because a boundary is
+the one thing a filled field cannot supply for itself on an arbitrary surface;
+`white`, `slate` and `ghost` stay opinionated. `Checkbox` reads the border too,
+for its unchecked box. Historically `outline` was the only reader, and
 it carries no hover fill. The other variants each name a concrete surface
 (`white`, `soft`, `slate`, `ghost`) and stay opinionated: a token that meant
 something different in each would not be a token.
@@ -403,6 +445,56 @@ One caveat worth knowing before you lean on these: like `--roster-card-*`,
 inside `@layer base` is outranked, and an override scoped to a subtree rather
 than the document root will not reach them.
 
+### Floating surface colors
+
+`Select`'s menu, `Dialog`'s `white` variant and `Tooltip`'s `themed` variant
+read these, so one palette covers every panel that floats over the page.
+
+```css
+:root {
+  --roster-popover-bg: #fff;
+  --roster-popover-border: #e7e5e4;
+  --roster-popover-text: #1c1917;
+}
+.dark {
+  --roster-popover-bg: #292524;
+  --roster-popover-border: #44403c;
+  --roster-popover-text: #f5f5f4;
+}
+```
+
+Separate from `--roster-control-*` on purpose, and the default is the reason:
+`--roster-control-bg` is `transparent`, which is right for a field drawn on a
+page and actively broken for a panel drawn over one. A control and the menu it
+opens are also legitimately different surfaces in plenty of palettes.
+
+**Set these at `:root`, not on a container.** The menu and the tooltip bubble
+are portaled to `<body>`, so they are not descendants of whatever you rendered
+the component inside: properties set on a wrapper reach the trigger and stop
+there. Any ancestor of `<body>` works — `:root` is simply the one that always
+is, which is also why the `.dark` block below reaches a menu whose `.dark`
+scope `Select` copies across the portal. The result is a themed trigger opening an unthemed panel, which is the
+exact problem this family exists to fix. Set them in both scopes too, for the
+same reason the control family needs both.
+
+Where each component takes them, and why not everywhere:
+
+- **`Select`'s menu** has no variants, so it reads all three outright — panel
+  fill, hairline, and the option labels, which are `text-inherit` so the text
+  token actually reaches the only text in the panel.
+- **`Dialog`** takes them in `white` only. `slate`, `primary` and `glass` each
+  name a specific surface, and a token that meant something different inside
+  each name would not be a token. The defaults are `white`'s previous values
+  exactly, in both schemes, so nothing moves.
+- **`Tooltip`** has a `themed` variant that reads them. Its `dark` and `light`
+  variants are untouched: `dark` is the default, an inverted bubble that
+  deliberately reads the same on a light or a dark page, and pointing that at a
+  token whose light default is white would not theme it, it would delete it.
+
+One appearance change ships with this: `Select`'s menu ring moves from
+`black/5` to `--roster-gray-200` in light mode, which is the hairline the rest
+of the library already draws.
+
 ### Reaching the control
 
 `className` on a field component lands on the outer `Field` wrapper. That is
@@ -411,12 +503,20 @@ cannot reach the element that draws the border, the height or the font.
 
 Every field therefore has a second prop, **named for the element it reaches**:
 
-| Component      | Wrapper     | The control itself   |
-| -------------- | ----------- | -------------------- |
-| `Input`        | `className` | `inputClassName`     |
-| `PasswordInput`| `className` | `inputClassName`     |
-| `Select`       | `className` | `triggerClassName`   |
-| `Textarea`     | `className` | `textareaClassName`  |
+| Component      | Wrapper     | The control itself   | Other inner parts   |
+| -------------- | ----------- | -------------------- | ------------------- |
+| `Input`        | `className` | `inputClassName`     | —                   |
+| `PasswordInput`| `className` | `inputClassName`     | —                   |
+| `Select`       | `className` | `triggerClassName`   | `optionsClassName`  |
+| `Textarea`     | `className` | `textareaClassName`  | —                   |
+
+`Select` is the first component with two styleable inner parts, which is the
+case the naming scheme was chosen for: `optionsClassName` reaches the popup
+panel. One caveat that is a property of Headless UI rather than of this prop —
+the panel's `max-height` and `overflow` are written inline by its `size`
+middleware, so a height passed here lands in the class list and is outranked.
+To cap the menu, set the variable that inline rule reads:
+`optionsClassName="rst:[--anchor-max-height:20rem]"`.
 
 The names differ on purpose. A single `controlClassName` would name a concept
 rather than an element, and it breaks the first time a component has two

package/dist/components/atoms/Select/Select.d.ts

@@ -23,6 +23,22 @@ export interface SelectProps extends Omit<React.HTMLAttributes<HTMLDivElement>,
      * is the escape hatch for the rest. Mirrors `Input`'s `inputClassName`.
      */
     triggerClassName?: string;
+    /**
+     * Classes for the popup panel.
+     *
+     * The escape-hatch rule already covers the wrapper (`className`) and the
+     * control (`triggerClassName`); the panel was the one styleable element with
+     * no way in. Mirrors `Input`'s `inputClassName`.
+     */
+    optionsClassName?: string;
+    /** Supporting text under the trigger. */
+    helperText?: string;
+    /**
+     * The message for an invalid selection. Implies `error`, so a caller cannot
+     * set the red ring and forget to say why — which is what `error` on its own
+     * did: a red outline and no text anywhere for anyone.
+     */
+    errorMessage?: string;
 }
-declare const Select: ({ options, value, onChange, placeholder, disabled, variant, size, error, className, triggerClassName, label, ...props }: SelectProps) => import("react/jsx-runtime").JSX.Element;
+declare const Select: ({ options, value, onChange, placeholder, disabled, variant, size, error, className, triggerClassName, optionsClassName, helperText, errorMessage, label, ...props }: SelectProps) => import("react/jsx-runtime").JSX.Element;
 export { Select };

package/dist/components/atoms/Tooltip/Tooltip.d.ts

@@ -1,6 +1,14 @@
 import * as React from "react";
 export type TooltipPlacement = "top" | "bottom" | "left" | "right";
-export type TooltipVariant = "dark" | "light";
+/**
+ * `dark` is an inverted bubble that deliberately reads the same on a light or
+ * a dark page, and `light` is its counterpart — both NAME a surface, so
+ * neither can be repointed at a consumer token without becoming something
+ * else. `themed` is the opt-in third: it reads `--roster-popover-*`, the same
+ * family Select's menu and Dialog's `white` variant read, so a host palette
+ * covers every floating surface at once.
+ */
+export type TooltipVariant = "dark" | "light" | "themed";
 export interface TooltipProps {
     /** The tooltip's popup content. Accepts a string or any React node. */
     content: React.ReactNode;

package/dist/meta.json

@@ -1,5 +1,5 @@
 {
-  "version": "4.8.0",
-  "tests": 1100,
+  "version": "4.8.2",
+  "tests": 1132,
   "testFiles": 93
 }