@forwardreach/saas-ui 0.11.0 → 0.13.0

package/dist/components/select-menu.js

@@ -0,0 +1,219 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { ChevronDown } from "lucide-react";
+import * as React from "react";
+import { cn } from "../utils/cn.js";
+import { useFormFieldProps } from "./form-field.js";
+import { OptionListbox, defaultOptionFilter, nextActiveIndex, optionElementId, scrollOptionIntoView, } from "./option-list.js";
+import { Popover, PopoverContent, PopoverTrigger } from "./popover.js";
+/**
+ * The option count at which `SelectMenu` shows a filter when the consumer has
+ * not said either way. Below it the whole list is on screen at once, and a
+ * filter is a row to skip past on the way to an answer already visible; above
+ * it the reader is scanning. Exported so a consumer can compare against it
+ * rather than duplicate the number.
+ */
+export const SELECT_MENU_SEARCH_THRESHOLD = 8;
+// Height, text and padding are held together per size rather than split across
+// rules, matching `Select`, so the two controls line up when swapped.
+const CONTROL_SIZE_CLASSES = {
+    md: "h-10 py-2 pl-3 pr-3 text-sm",
+    sm: "h-8 py-1 pl-2.5 pr-2.5 text-xs",
+};
+/**
+ * Single choice from a list, in a popup this package draws.
+ *
+ * The fourth answer to "choose one" here, and the one to reach for when the
+ * popup's appearance is the point: `Select` is the native control, whose popup
+ * belongs to the platform and cannot be themed past its background colour;
+ * `Combobox` is a search field for lists too long to read; `RoleMenu` is for
+ * two or three options that each need a sentence. `SelectMenu` is the `Select`
+ * slot drawn as a menu — a trigger that can read as bounded field or as plain
+ * text, an option list with headings, and a filter once the list is long
+ * enough to want one. The table in `docs/packages/saas-ui.md` says which of the
+ * four answers which case.
+ *
+ * Built on `Popover` rather than `DropdownMenu` because a menu's roving focus
+ * and typeahead both fight a filter field. Inside the popup the list runs the
+ * listbox pattern with `aria-activedescendant`: focus stays in the filter field
+ * when there is one, or on the listbox itself when there is not, and the
+ * highlight moves independently — the model `Combobox` already implements, and
+ * the same option list rendering, extracted so the two cannot drift.
+ *
+ * What it gives up, stated plainly: on a phone a native `<select>` opens the
+ * platform's own picker, and this cannot. `Select` stays for the bounded form
+ * field where that is worth more than a themed popup.
+ */
+export function SelectMenu({ options, value, onValueChange, variant = "control", size = "md", searchable, searchPlaceholder = "Search", emptyMessage, emptyLabel, placeholder, name, disabled, align = "start", open: openProp, defaultOpen = false, onOpenChange, className, ...ariaProps }) {
+    // An enclosing `FormField` owns the trigger's id and error wiring, as it does
+    // for `Input`, `Combobox` and `RoleMenu`.
+    const { "aria-label": ariaLabel, ...fieldProps } = useFormFieldProps(ariaProps);
+    const generatedId = React.useId();
+    const id = fieldProps.id ?? generatedId;
+    const listboxId = `${id}-listbox`;
+    const filterId = `${id}-filter`;
+    const [uncontrolledOpen, setUncontrolledOpen] = React.useState(defaultOpen);
+    const open = openProp ?? uncontrolledOpen;
+    const [query, setQuery] = React.useState("");
+    const [activeIndex, setActiveIndex] = React.useState(-1);
+    const filterRef = React.useRef(null);
+    const listRef = React.useRef(null);
+    const triggerRef = React.useRef(null);
+    // The empty choice is a real option at the head of the list — it shares the
+    // index space, the highlight and `aria-activedescendant` — so no second
+    // keyboard path exists for it. `""` is what it reports. An empty `value` is
+    // "nothing chosen" everywhere below rather than "the empty row is chosen":
+    // the trigger shows its placeholder, no row is marked current, and the list
+    // opens with nothing highlighted.
+    const chosen = value === "" ? undefined : value;
+    const selected = options.find((option) => option.value === chosen);
+    const selectedLabel = selected?.inputLabel ?? selected?.label;
+    const offered = emptyLabel !== undefined ? [{ value: "", label: emptyLabel }, ...options] : [...options];
+    const showFilter = searchable ?? options.length >= SELECT_MENU_SEARCH_THRESHOLD;
+    // A freshly opened list starts with nothing typed and the current value
+    // highlighted, so Enter with no other key confirms what is already set and an
+    // arrow moves from it rather than from the top. The reset keys on the open
+    // state itself rather than on the trigger, because the trigger is only one
+    // way in: `defaultOpen` and a consumer flipping `open` from its own gesture —
+    // the click-to-edit row this component exists for — never touch it. Done
+    // during render, in the pattern React documents for reacting to a prop
+    // change, so the popup's first frame is already reset rather than one frame
+    // stale.
+    const [wasOpen, setWasOpen] = React.useState(false);
+    if (open !== wasOpen) {
+        setWasOpen(open);
+        if (open) {
+            setQuery("");
+            setActiveIndex(chosen === undefined ? -1 : offered.findIndex((option) => option.value === chosen));
+        }
+    }
+    const navigable = showFilter ? offered.filter((option) => defaultOptionFilter(option, query)) : offered;
+    const activeOption = activeIndex >= 0 ? navigable[activeIndex] : undefined;
+    function setOpen(next) {
+        if (next === open)
+            return;
+        if (openProp === undefined)
+            setUncontrolledOpen(next);
+        onOpenChange?.(next);
+    }
+    function commit(option) {
+        if (option.value !== (value ?? ""))
+            void onValueChange?.(option.value);
+        setOpen(false);
+    }
+    function moveActive(delta) {
+        if (navigable.length === 0)
+            return;
+        const next = nextActiveIndex(activeIndex, delta, navigable.length);
+        setActiveIndex(next);
+        scrollOptionIntoView(listRef.current, next);
+    }
+    function handleKeyDown(event) {
+        if (event.key === "ArrowDown" || event.key === "ArrowUp") {
+            event.preventDefault();
+            moveActive(event.key === "ArrowDown" ? 1 : -1);
+            return;
+        }
+        if (event.key === "Home" || event.key === "End") {
+            if (navigable.length === 0)
+                return;
+            event.preventDefault();
+            const next = event.key === "Home" ? 0 : navigable.length - 1;
+            setActiveIndex(next);
+            scrollOptionIntoView(listRef.current, next);
+            return;
+        }
+        if (event.key === "Enter") {
+            // The open popup owns Enter whether or not anything is highlighted, so a
+            // stray press cannot reach the form behind the control.
+            event.preventDefault();
+            if (activeOption)
+                commit(activeOption);
+        }
+        // Escape is left to the popover, which closes on it and returns focus to
+        // the trigger; stopping it here would keep the popup open.
+    }
+    function handleTriggerKeyDown(event) {
+        // A native `<select>` opens on either arrow, and so does `RoleMenu`; a user
+        // swapping `Select` for this keeps the key. Space and Enter are the button's
+        // own, and the open state's reset above does the rest.
+        if (open || (event.key !== "ArrowDown" && event.key !== "ArrowUp"))
+            return;
+        event.preventDefault();
+        setOpen(true);
+    }
+    // The name carries purpose and current value, as `RoleMenu`'s does. A
+    // `FormField`'s visible label does that job better, so a consumer inside one
+    // passes no `aria-label`; one that does gets what it asked for, as it would
+    // from `RoleMenu`. With neither, the button's own text — the current value —
+    // is its name.
+    const currentText = selectedLabel ?? (typeof placeholder === "string" ? placeholder : "none");
+    const triggerLabel = ariaLabel ? `${ariaLabel} (current: ${currentText})` : undefined;
+    const activeDescendant = open && activeOption ? optionElementId(id, activeOption.value) : undefined;
+    return (_jsxs(_Fragment, { children: [name ? _jsx("input", { disabled: disabled, name: name, type: "hidden", value: value ?? "" }) : null, _jsxs(Popover, { onOpenChange: setOpen, open: open, children: [_jsx(PopoverTrigger, { asChild: true, children: _jsxs("button", { ...fieldProps, "aria-controls": open ? listboxId : undefined, "aria-haspopup": "listbox", "aria-label": triggerLabel, className: cn("group/select-menu inline-flex items-center gap-1.5 text-left transition-colors focus-visible:outline-none", variant === "control"
+                                ? cn(
+                                // `Select`'s field, so the two line up when swapped: same
+                                // radius, border, shadow, sizes, and ring with an offset.
+                                "w-full justify-between rounded-[var(--ssui-radius)] border border-[color:var(--ssui-border-control,var(--ssui-border))] bg-[color:var(--ssui-surface)] text-[color:var(--ssui-text)] shadow-sm focus-visible:ring-2 focus-visible:ring-[color:var(--ssui-focus-ring)] focus-visible:ring-offset-2 focus-visible:ring-offset-[color:var(--ssui-bg)] disabled:pointer-events-none disabled:cursor-not-allowed disabled:bg-[color:var(--ssui-surface-muted)] disabled:opacity-70", CONTROL_SIZE_CLASSES[size])
+                                : // No box at rest: the row's own text on the row's own background,
+                                    // and only as wide as that text — `w-fit`, because a grid or flex
+                                    // cell would otherwise stretch it, and a hover surface the width
+                                    // of the row reads as a bar rather than as the value lighting up.
+                                    // The hover surface and the chevron arrive on hover, focus and
+                                    // while open, and the focus ring carries no offset — an inline
+                                    // trigger sits in a line with a couple of pixels to give, and a
+                                    // ring pushed outside it lands on the lines above and below
+                                    // rather than on this one. The ring is 2px, so with no offset
+                                    // it fits exactly the gutter a dense list keeps. Disabled, the
+                                    // pointer gets nothing: hover is the whole signal this variant
+                                    // uses to say "operable", so it must not light up and grow a
+                                    // chevron for a trigger that will then do nothing.
+                                    "-mx-1 w-fit max-w-full rounded-[var(--ssui-radius-sm)] px-1 text-[color:var(--ssui-text)] hover:bg-[color:var(--ssui-overlay-hover)] focus-visible:ring-2 focus-visible:ring-[color:var(--ssui-focus-ring)] data-[state=open]:bg-[color:var(--ssui-overlay-hover)] disabled:pointer-events-none disabled:cursor-not-allowed disabled:opacity-70", className), disabled: disabled, onKeyDown: handleTriggerKeyDown, ref: triggerRef, type: "button", children: [_jsx("span", { className: cn("min-w-0 truncate", selectedLabel === undefined && "text-[color:var(--ssui-text-subtle)]"), children: selectedLabel ?? placeholder }), _jsx(ChevronDown, { "aria-hidden": "true", className: cn("shrink-0 text-[color:var(--ssui-text-subtle)]", variant === "control"
+                                        ? size === "sm"
+                                            ? "size-3.5"
+                                            : "size-4"
+                                        : "size-3.5 opacity-0 transition-opacity group-hover/select-menu:opacity-100 group-focus-visible/select-menu:opacity-100 group-data-[state=open]/select-menu:opacity-100") })] }) }), _jsxs(PopoverContent, { align: align, 
+                        // The panel's own padding plus a row's puts an option's text 12px
+                        // inside the panel, while an inline trigger's text sits 4px inside the
+                        // box the panel aligns to. Pulling the panel back by the difference
+                        // lands the options directly under the value they replace, so the
+                        // popup reads as that value opening rather than as a panel arriving
+                        // beside it. A bounded trigger's own padding already matches, so it
+                        // needs no correction.
+                        alignOffset: variant === "inline" ? -8 : 0, className: cn("p-1", 
+                        // A bounded trigger's popup starts at the field's own width, so the two
+                        // read as one control rather than as a panel that happens to be near it,
+                        // and grows only if an option needs more than the field has. A fixed
+                        // width would truncate those options; a fixed minimum — which this used
+                        // to carry for both variants — made every narrow field's popup overhang
+                        // it, which is what the field-type control showed. An inline trigger is
+                        // as wide as its text, which is no width for a list, so it keeps a floor
+                        // of its own.
+                        variant === "control" ? "min-w-[var(--radix-popover-trigger-width)]" : "min-w-56"), onCloseAutoFocus: (event) => {
+                            // Focus returns to the trigger on close — unless the trigger has
+                            // left the document with the popup, as it does when a consumer
+                            // unmounts the control on a choice or a cancel. Returning focus to
+                            // a detached element is a no-op that still pre-empts wherever the
+                            // consumer then puts it, so the return is skipped and left to them.
+                            if (!triggerRef.current?.isConnected)
+                                event.preventDefault();
+                        }, onOpenAutoFocus: (event) => {
+                            // Focus goes to whichever element runs the keyboard model — the
+                            // filter field, or the listbox itself when there is none — not to
+                            // the first tabbable thing Radix would pick.
+                            event.preventDefault();
+                            (filterRef.current ?? listRef.current)?.focus();
+                        }, 
+                        // The panel is a listbox popup, not a dialog: the element that holds
+                        // focus inside it announces itself, and a "dialog" wrapper around a
+                        // select's options would be one more thing to hear on the way to them.
+                        role: "presentation", children: [showFilter ? (_jsx("input", { "aria-activedescendant": activeDescendant, "aria-autocomplete": "list", "aria-controls": listboxId, "aria-expanded": "true", "aria-label": searchPlaceholder, autoComplete: "off", className: "mb-1 flex h-8 w-full rounded-[var(--ssui-radius-sm)] border border-[color:var(--ssui-border-control,var(--ssui-border))] bg-[color:var(--ssui-surface)] px-2 text-sm text-[color:var(--ssui-text)] placeholder:text-[color:var(--ssui-text-subtle)] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[color:var(--ssui-focus-ring)]", id: filterId, onChange: (event) => {
+                                    setQuery(event.target.value);
+                                    setActiveIndex(-1);
+                                }, onKeyDown: handleKeyDown, placeholder: searchPlaceholder, ref: filterRef, role: "combobox", type: "text", value: query })) : null, _jsx(OptionListbox, { activeIndex: activeIndex, "aria-activedescendant": showFilter ? undefined : activeDescendant, "aria-label": showFilter ? undefined : ariaLabel, className: "max-h-64 overflow-y-auto outline-none", 
+                                // `undefined` is "the consumer said nothing"; `null` is "show
+                                // nothing", which the list documents and `Combobox` honours. `??`
+                                // would swallow the second, so the test is on `undefined` alone.
+                                emptyMessage: emptyMessage !== undefined ? emptyMessage : showFilter ? "No matches" : "No options", id: listboxId, idPrefix: id, onActivate: setActiveIndex, onCommit: commit, onKeyDown: showFilter ? undefined : handleKeyDown, options: navigable, ref: listRef, tabIndex: showFilter ? undefined : -1, value: chosen })] })] })] }));
+}
+SelectMenu.displayName = "SelectMenu";

package/dist/components/select.d.ts

@@ -12,5 +12,11 @@ export interface SelectProps extends Omit<React.SelectHTMLAttributes<HTMLSelectE
  * Styled native `<select>` matching the shared `Input` look, with a trailing
  * chevron. Native on purpose: correct mobile behavior and form participation
  * with zero positioning code. Participates in `FormField` wiring.
+ *
+ * The default for a bounded field in an ordinary form. Its popup belongs to the
+ * platform and cannot be themed past its background colour; where that popup is
+ * the whole of what the reader sees — a choice presented as inline text — reach
+ * for `SelectMenu` instead. The four single-choice controls and which case each
+ * answers are tabled once, in `docs/packages/saas-ui.md`.
  */
 export declare const Select: React.ForwardRefExoticComponent<SelectProps & React.RefAttributes<HTMLSelectElement>>;

package/dist/components/select.js

@@ -14,6 +14,12 @@ const SIZE_CLASSES = {
  * Styled native `<select>` matching the shared `Input` look, with a trailing
  * chevron. Native on purpose: correct mobile behavior and form participation
  * with zero positioning code. Participates in `FormField` wiring.
+ *
+ * The default for a bounded field in an ordinary form. Its popup belongs to the
+ * platform and cannot be themed past its background colour; where that popup is
+ * the whole of what the reader sees — a choice presented as inline text — reach
+ * for `SelectMenu` instead. The four single-choice controls and which case each
+ * answers are tabled once, in `docs/packages/saas-ui.md`.
  */
 export const Select = React.forwardRef(({ className, children, size = "md", ...props }, ref) => (_jsxs("div", { className: cn("relative", className), children: [_jsx("select", { ref: ref, className: cn("flex w-full cursor-pointer appearance-none rounded-[var(--ssui-radius)] border border-[color:var(--ssui-border-control,var(--ssui-border))] bg-[color:var(--ssui-surface)] text-[color:var(--ssui-text)] shadow-sm transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[color:var(--ssui-focus-ring)] focus-visible:ring-offset-2 focus-visible:ring-offset-[color:var(--ssui-bg)] disabled:cursor-not-allowed disabled:bg-[color:var(--ssui-surface-muted)] disabled:opacity-70", SIZE_CLASSES[size].select), ...useFormFieldProps(props), children: children }), _jsx(ChevronDown, { "aria-hidden": "true", className: cn("pointer-events-none absolute top-1/2 -translate-y-1/2 text-[color:var(--ssui-text-subtle)]", SIZE_CLASSES[size].chevron) })] })));
 Select.displayName = "Select";

package/dist/styles/index.css

@@ -63,6 +63,20 @@
   --ssui-avatar-4-text: #9d174d;
   --ssui-avatar-5-bg: #f0f9ff;
   --ssui-avatar-5-text: #075985;
+  /* Pill tones: a reference (a link to a record), a tag, an attribute (a field), a date, and
+     a category (a grouping tag). Each defaults to a DERIVATION of the base contract rather
+     than a literal, so a consumer that has mapped the status and accent ramps sees a
+     coherent pair in both of its themes before it maps a single pill token. */
+  --ssui-pill-reference-bg: var(--ssui-accent-subtle);
+  --ssui-pill-reference-text: var(--ssui-accent-subtle-foreground);
+  --ssui-pill-tag-bg: var(--ssui-status-info-bg);
+  --ssui-pill-tag-text: var(--ssui-status-info-text);
+  --ssui-pill-attribute-bg: var(--ssui-status-neutral-bg);
+  --ssui-pill-attribute-text: var(--ssui-status-neutral-text);
+  --ssui-pill-date-bg: var(--ssui-status-warning-bg);
+  --ssui-pill-date-text: var(--ssui-status-warning-text);
+  --ssui-pill-category-bg: var(--ssui-status-success-bg);
+  --ssui-pill-category-text: var(--ssui-status-success-text);
 }
 
 @media (prefers-reduced-motion: reduce) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forwardreach/saas-ui",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "description": "Brand-neutral React UI primitives and SaaS app patterns for ForwardReach-owned business applications.",
   "type": "module",
   "private": false,
@@ -51,6 +51,7 @@
     "@radix-ui/react-avatar": "^1.1.10",
     "@radix-ui/react-dialog": "^1.1.15",
     "@radix-ui/react-dropdown-menu": "^2.1.16",
+    "@radix-ui/react-popover": "^1.1.23",
     "@radix-ui/react-scroll-area": "^1.2.10",
     "@radix-ui/react-separator": "^1.1.7",
     "@radix-ui/react-slot": "^1.2.4",
@@ -72,7 +73,7 @@
     "typescript": "^5.8.3",
     "vitest": "^3.2.4"
   },
-  "gitHead": "544931dd34ff3f738a58cf9e7ad161fb8fa8763f",
+  "gitHead": "519fa3eab663bd95bba8a6dae8ac056538d25431",
   "scripts": {
     "build": "pnpm clean && tsc -p tsconfig.build.json && node scripts/copy-styles.mjs",
     "dev": "node scripts/copy-styles.mjs && tsc -p tsconfig.build.json --watch",