@blakesteve/roster 4.7.0 → 4.8.1

package/README.md

@@ -144,6 +144,20 @@ document head:
 If you pass a custom `storageKey`, change the script to match — a mismatch means
 the script and the toggle disagree, which shows up as a flash on every reload.
 
+**Components that render into a portal**, such as `Select`'s menu, are attached
+to `<body>` rather than to the element you wrote them next to. When `.dark` is
+on `<html>` — what `ThemeToggle` does, and what the script above sets up — that
+makes no difference, because the portal is still a descendant. If you scope
+`.dark` to a subtree instead, `Select` detects the nearest `.dark` ancestor of
+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.
@@ -349,6 +363,157 @@ browser honors `scrollbar-width` / `scrollbar-color`, and drops the WebKit
 pseudo-elements for any element that sets either of them, so on anything modern
 `thin` is the whole shape control available.
 
+### 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.
+
+```css
+:root {
+  --roster-control-border: #d6d3d1;
+  --roster-control-bg: transparent;
+  --roster-control-text: #1c1917;
+  --roster-control-border-focus: #0f6498;
+}
+.dark {
+  --roster-control-border: #44403c;
+  --roster-control-bg: transparent;
+  --roster-control-text: #f5f5f4;
+  --roster-control-border-focus: #0f6498;
+}
+```
+
+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
+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.
+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
+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.
+
+One caveat worth knowing before you lean on these: like `--roster-card-*`,
+`--roster-nav-*` and `--roster-footer-*`, they are declared outside
+`@layer roster` and resolved at `:root`. A host that declares its override
+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
+right for layout — width, flex, margins — and useless for anything else: it
+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   | 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
+styleable inner parts — a combobox has an input *and* a toggle. `triggerClassName`
+also tells you something true: the thing you are styling is a `<button>`, so
+`placeholder:` and `disabled:` behave differently on it than they would on an
+`<input>`.
+
+These merge last and win, not because they come later in the attribute (CSS
+ignores that) but because `cn` is tailwind-merge and deletes the class they
+conflict with.
+
+### Control heights
+
+`Button`, `Input` and `Select` share one size scale, so they line up when set
+side by side in a row:
+
+| `size`    | Height | `Button` padding | `Input` padding | `Select` padding |
+| --------- | ------ | ---------------- | --------------- | ---------------- |
+| `sm`      | 36px   | `px-3`           | `px-3`          | `pl-3 pr-9`      |
+| `default` | 40px   | `px-4`           | `px-4`          | `pl-4 pr-10`     |
+| `lg`      | 44px   | `px-8`           | `px-4`          | `pl-4 pr-10`     |
+
+Padding diverges at `lg` on purpose. A button's label is centered and wants the
+room, while a field's text is left-aligned and a wide inset only pushes the
+caret toward the middle. `Select`'s right padding is clearance for the chevron,
+which is a fixed 14px at every size, so it has nothing to grow for.
+
+Unit tests assert the three components resolve to the same height at every
+shared size, so they cannot drift apart. `Button` also has `xs` and `icon`,
+which neither field has an equivalent for. `Textarea` is not on this scale — it
+is multi-line, so the answer there is a min-height rather than a height.
+
 ### Components that render links
 
 `Breadcrumbs` renders a plain `<a>` by default, which is right for a static
@@ -408,7 +573,7 @@ function App() {
 | `Disclosure`         | Show/hide toggle using HeadlessUI                                                                            |
 | `Eyebrow`            | Small tracked-out uppercase label above a heading or beside a rule; polymorphic via `as`                     |
 | `InlineCode`         | Inline `<code>` for identifiers in running prose                                                             |
-| `Input`              | Text input with label, error state, and icon slots                                                           |
+| `Input`              | Text input with label, error state, icon slots, and a size scale matching `Button`                           |
 | `LabeledDivider`     | Horizontal rule carrying a label, with an optional trailing count                                            |
 | `Link`               | Styled anchor with variant support                                                                           |
 | `PasswordInput`      | Password field with a show/hide reveal toggle                                                                |
@@ -416,7 +581,7 @@ function App() {
 | `AvatarStrip`        | Stacked avatar row with overflow chip, dismiss button, trailing slot, and label area                         |
 | `CollapsibleSection` | Clamps any content (prose, chips, image grids) to a fixed height with a fade and expand/collapse toggle      |
 | `LiquidTabs`         | Controlled tab strip with a liquid sliding pill indicator: pill and filled variants                          |
-| `Select`             | Dropdown selector                                                                                            |
+| `Select`             | Dropdown selector, on the same size scale as `Button` and `Input`                                            |
 | `SegmentBar`         | Proportional horizontal bar divided into colored segments with optional legend                               |
 | `Stat`               | A single figure with its label and, optionally, where the figure came from                                   |
 | `Spinner`            | Loading indicator                                                                                            |

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

@@ -1,12 +1,21 @@
 import { default as React } from 'react';
 import { VariantProps } from 'class-variance-authority';
 import { inputVariants } from './input-variants';
-export interface InputProps extends React.InputHTMLAttributes<HTMLInputElement>, VariantProps<typeof inputVariants> {
+export interface InputProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, "size">, VariantProps<typeof inputVariants> {
     label?: string;
     helperText?: string;
     errorMessage?: string;
     startIcon?: React.ReactNode;
     endIcon?: React.ReactNode;
+    /**
+     * Classes for the `<input>` itself.
+     *
+     * `className` lands on the outer `Field` wrapper, which is right for layout
+     * and useless for anything else: a consumer could not reach the control to
+     * change its height, border or background. `size` covers the common case;
+     * this is the escape hatch for the rest.
+     */
+    inputClassName?: string;
 }
 declare const Input: React.ForwardRefExoticComponent<InputProps & React.RefAttributes<HTMLInputElement>>;
 export { Input };

package/dist/components/atoms/Input/input-variants.d.ts

@@ -1,5 +1,6 @@
 export declare const inputVariants: (props?: ({
     variant?: "soft" | "outline" | "white" | "ghost" | "slate" | null | undefined;
+    size?: "sm" | "lg" | "default" | null | undefined;
     error?: boolean | null | undefined;
 } & import('class-variance-authority/types').ClassProp) | undefined) => string;
 export declare const iconVariants: (props?: ({

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

@@ -1,3 +1,4 @@
+import { default as React } from 'react';
 import { VariantProps } from 'class-variance-authority';
 import { selectTriggerVariants } from './select-variants';
 export type SelectOption = {
@@ -13,6 +14,31 @@ export interface SelectProps extends Omit<React.HTMLAttributes<HTMLDivElement>,
     disabled?: boolean;
     className?: string;
     label?: string;
+    /**
+     * Classes for the trigger button itself.
+     *
+     * `className` lands on the outer `Field` wrapper, which is right for layout
+     * and useless for anything else: a consumer could not reach the control to
+     * change its height, ring or background. `size` covers the common case; this
+     * 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, error, className, label, }: 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/Select/select-variants.d.ts

@@ -1,4 +1,8 @@
 export declare const selectTriggerVariants: (props?: ({
     variant?: "soft" | "outline" | "white" | "ghost" | "slate" | null | undefined;
+    size?: "sm" | "lg" | "default" | null | undefined;
     error?: boolean | null | undefined;
 } & import('class-variance-authority/types').ClassProp) | undefined) => string;
+export declare const selectOptionVariants: (props?: ({
+    size?: "sm" | "lg" | "default" | null | undefined;
+} & import('class-variance-authority/types').ClassProp) | undefined) => string;

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

@@ -5,6 +5,15 @@ export interface TextareaProps extends React.TextareaHTMLAttributes<HTMLTextArea
     label?: string;
     helperText?: string;
     errorMessage?: string;
+    /**
+     * Classes for the `<textarea>` itself.
+     *
+     * `className` lands on the outer `Field` wrapper, so `<Textarea
+     * className="rst:h-40" />` has always sized the wrapper and left the control
+     * alone. Mirrors `Input`'s `inputClassName` and `Select`'s
+     * `triggerClassName`: the hatch is named for the element it reaches.
+     */
+    textareaClassName?: string;
 }
 declare const Textarea: React.ForwardRefExoticComponent<TextareaProps & React.RefAttributes<HTMLTextAreaElement>>;
 export { Textarea };

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.7.0",
-  "tests": 1039,
+  "version": "4.8.1",
+  "tests": 1117,
   "testFiles": 93
 }