@usefragments/ui 1.3.2 → 1.4.0

package/src/components/Select/index.tsx

@@ -12,9 +12,15 @@ import styles from "./Select.module.scss";
 
 export type SelectValue = string;
 
+export type SelectVariant = "field" | "ghost";
+
 export interface SelectOption {
   value: SelectValue;
   label: string;
+  /** A dimmed qualifier after the label, in the trigger as well as the list —
+   * a tier beside a model, a path beside a filename. Use it when the label
+   * alone is ambiguous but the qualifier is not what you are choosing by. */
+  hint?: string;
   disabled?: boolean;
 }
 
@@ -58,6 +64,11 @@ export interface SelectProps extends FormFieldProps {
   /** Size variant.
    * @default "md" */
   size?: "sm" | "md" | "lg";
+  /** Visual treatment. `ghost` drops the field shell for a compact, borderless
+   * control — for toolbars and dense rows, where a bordered field reads as a
+   * form. Pair with `size="sm"`.
+   * @default "field" */
+  variant?: SelectVariant;
   /** Wrapper class name */
   className?: string;
 }
@@ -65,10 +76,15 @@ export interface SelectProps extends FormFieldProps {
 export interface SelectTriggerProps extends React.HTMLAttributes<HTMLButtonElement> {
   children?: React.ReactNode;
   placeholder?: string;
+  /** Leading adornment shown before the value — usually says what the choice is
+   * about, so the visible text can be the choice itself. Ignored when you pass
+   * your own `children`. */
+  icon?: React.ReactNode;
 }
 
 export interface SelectContentProps extends React.HTMLAttributes<HTMLDivElement> {
-  children: React.ReactNode;
+  /** Omit to render the items the root's `options` prop describes. */
+  children?: React.ReactNode;
   sideOffset?: number;
   align?: "start" | "center" | "end";
   /** Maximum number of visible options before scrolling. Shows half of the next item as a scroll hint. @default 4 */
@@ -142,6 +158,12 @@ interface SelectContextValue {
   registerItem: (value: SelectValue, content: React.ReactNode) => void;
   unregisterItem: (value: SelectValue) => void;
   size: "sm" | "md" | "lg";
+  variant: SelectVariant;
+  /** Items built from the `options` prop, so a custom composition can put the
+   * trigger where it wants without having to re-render the list itself — and
+   * without losing whatever the root knows about an option that a bare label
+   * does not carry. */
+  optionItems: React.ReactNode;
 }
 
 const SelectContext = React.createContext<SelectContextValue>({
@@ -149,8 +171,22 @@ const SelectContext = React.createContext<SelectContextValue>({
   registerItem: () => {},
   unregisterItem: () => {},
   size: "md",
+  variant: "field",
+  optionItems: null,
 });
 
+// Label and qualifier as one node, so the trigger and the list render the same
+// thing and the registry has a single entry to hand back.
+function renderOptionLabel(option: SelectOption): React.ReactNode {
+  if (!option.hint) return option.label;
+  return (
+    <>
+      {option.label}
+      <span className={styles.hint}>{option.hint}</span>
+    </>
+  );
+}
+
 // Walk the declared Select children at render time to build a value→label map.
 // The trigger reads this so a preselected value renders its label immediately,
 // without waiting for the lazily-portaled popup to mount and register items.
@@ -194,6 +230,7 @@ const SelectRoot = React.forwardRef<HTMLDivElement, SelectProps>(function Select
     helperText,
     error,
     size: sizeProp,
+    variant = "field",
     className,
   }: SelectProps,
   ref
@@ -235,7 +272,7 @@ const SelectRoot = React.forwardRef<HTMLDivElement, SelectProps>(function Select
     () =>
       options?.map((option) => (
         <SelectItem key={option.value} value={option.value} disabled={option.disabled}>
-          {option.label}
+          {renderOptionLabel(option)}
         </SelectItem>
       )) ?? null,
     [options]
@@ -267,7 +304,7 @@ const SelectRoot = React.forwardRef<HTMLDivElement, SelectProps>(function Select
   // registry, which still wins for items that register dynamically.
   const declaredItems = React.useMemo(() => {
     const map = new Map<SelectValue, React.ReactNode>();
-    options?.forEach((option) => map.set(option.value, option.label));
+    options?.forEach((option) => map.set(option.value, renderOptionLabel(option)));
     collectDeclaredItems(children, map);
     return map;
   }, [children, options]);
@@ -287,8 +324,19 @@ const SelectRoot = React.forwardRef<HTMLDivElement, SelectProps>(function Select
       registerItem,
       unregisterItem,
       size,
+      variant,
+      optionItems,
     }),
-    [placeholder, selectedValue, resolvedItems, registerItem, unregisterItem, size]
+    [
+      placeholder,
+      selectedValue,
+      resolvedItems,
+      registerItem,
+      unregisterItem,
+      size,
+      variant,
+      optionItems,
+    ]
   );
 
   const { helperId, errorId, hasError, errorMessage } = useFormFieldIds("select", {
@@ -297,7 +345,13 @@ const SelectRoot = React.forwardRef<HTMLDivElement, SelectProps>(function Select
     error,
   });
 
-  const wrapperClasses = [styles.wrapper, className].filter(Boolean).join(" ");
+  const wrapperClasses = [
+    styles.wrapper,
+    variant === "ghost" && styles.wrapperGhost,
+    className,
+  ]
+    .filter(Boolean)
+    .join(" ");
   const helperClasses = [styles.helper, hasError && styles.helperError].filter(Boolean).join(" ");
 
   return (
@@ -337,7 +391,13 @@ const SelectRoot = React.forwardRef<HTMLDivElement, SelectProps>(function Select
   );
 });
 
-function SelectTrigger({ children, placeholder, className, ...htmlProps }: SelectTriggerProps) {
+function SelectTrigger({
+  children,
+  placeholder,
+  icon,
+  className,
+  ...htmlProps
+}: SelectTriggerProps) {
   const context = React.useContext(SelectContext);
   const placeholderText = placeholder ?? context.placeholder;
 
@@ -345,6 +405,10 @@ function SelectTrigger({ children, placeholder, className, ...htmlProps }: Selec
     styles.trigger,
     context.size === "sm" && styles.triggerSm,
     context.size === "lg" && styles.triggerLg,
+    // Ghost unsets the field shell and the size mixin's box. Both are single
+    // classes like this one, so it wins on being declared after them in
+    // Select.module.scss — the one place that ordering is guaranteed.
+    context.variant === "ghost" && styles.triggerGhost,
     className,
   ]
     .filter(Boolean)
@@ -362,6 +426,7 @@ function SelectTrigger({ children, placeholder, className, ...htmlProps }: Selec
     <BaseSelect.Trigger {...htmlProps} className={classes}>
       {children ?? (
         <>
+          {icon && <span className={styles.triggerIcon}>{icon}</span>}
           <span className={styles.value}>{displayContent}</span>
           <BaseSelect.Icon className={styles.icon}>
             <ChevronDownIcon />
@@ -380,6 +445,7 @@ function SelectContent({
   maxVisibleItems,
   ...htmlProps
 }: SelectContentProps) {
+  const { optionItems } = React.useContext(SelectContext);
   const popupClasses = [styles.popup, className].filter(Boolean).join(" ");
 
   const popupStyle =
@@ -394,7 +460,7 @@ function SelectContent({
     <BaseSelect.Portal>
       <BaseSelect.Positioner sideOffset={sideOffset} align={align} className={styles.positioner}>
         <BaseSelect.Popup {...htmlProps} className={popupClasses} style={popupStyle}>
-          {children}
+          {children ?? optionItems}
         </BaseSelect.Popup>
       </BaseSelect.Positioner>
     </BaseSelect.Portal>

package/src/components/Sidebar/Sidebar.contract.json

@@ -129,6 +129,7 @@
       "Use SidebarProvider to enable external triggers and keyboard shortcuts",
       "Use asChild with routing libraries (Next.js Link, React Router NavLink)",
       "Sidebar.Item and Sidebar.SubItem onClick handlers receive the click event object",
+      "Use `multiline` on Sidebar.Item when the row is a list entry rather than a nav link — a title over a status or preview line. Without it the label is one truncating line",
       "Use Sidebar.MenuSkeleton while loading navigation data"
     ],
     "accessibility": [

package/src/components/Sidebar/Sidebar.module.scss

@@ -388,6 +388,16 @@ $fui-sidebar-rail-indicator-height-hover: 4rem !default; // 56px
   padding-top: 0.071rem;
 }
 
+// A row whose label is a block rather than a link: a title over a status line,
+// a name over an address, a subject over a preview. The single-line ellipsis is
+// right for navigation and wrong here, so it comes off — but the label keeps
+// bounding itself, so anything inside it that truncates still truncates against
+// the rail's width instead of widening it.
+.itemMultiline .itemLabel {
+  white-space: normal;
+  min-width: 0;
+}
+
 .itemBadge {
   display: flex;
   align-items: center;

package/src/components/Sidebar/index.tsx

@@ -144,6 +144,11 @@ export interface SidebarItemProps extends Omit<React.HTMLAttributes<HTMLElement>
   href?: string;
   /** Click handler (renders as button) */
   onClick?: React.MouseEventHandler<HTMLElement>;
+  /**
+   * Let the label be a block instead of one truncating line — a title over a
+   * status line, a subject over a preview. For list rows rather than nav links.
+   */
+  multiline?: boolean;
   /** Whether this item has a submenu */
   hasSubmenu?: boolean;
   /** Whether submenu is expanded (controlled) */
@@ -774,6 +779,7 @@ function SidebarItem({
   badge,
   href,
   onClick,
+  multiline = false,
   hasSubmenu = false,
   expanded: controlledExpanded,
   defaultExpanded = false,
@@ -796,6 +802,7 @@ function SidebarItem({
     styles.item,
     active && styles.itemActive,
     disabled && styles.itemDisabled,
+    multiline && styles.itemMultiline,
     hasSubmenu && styles.itemHasSubmenu,
     expanded && styles.itemExpanded,
     className,

package/src/components/Text/Text.contract.json

@@ -19,7 +19,7 @@
     "variant: section-label",
     "size: 2xs|xs|sm|base|md|lg|xl|2xl|3xl|4xl",
     "weight: normal|medium|semibold|bold (default: \"normal\")",
-    "color: primary|secondary|tertiary|muted (default: \"primary\")",
+    "color: primary|secondary|tertiary|muted|success|warning|danger (default: \"primary\")",
     "font: sans|mono (default: sans)",
     "truncate: boolean",
     "lineClamp: number",
@@ -102,14 +102,17 @@
     },
     "color": {
       "type": "enum",
-      "description": "Text color (muted is an alias for tertiary)",
+      "description": "Text color (muted is an alias for tertiary; success/warning/danger are for a run of text that carries a state on its own \u2014 prefer Badge or Alert when the state deserves a container)",
       "default": "\"primary\"",
       "required": false,
       "values": [
         "primary",
         "secondary",
         "tertiary",
-        "muted"
+        "muted",
+        "success",
+        "warning",
+        "danger"
       ]
     },
     "font": {
@@ -216,7 +219,7 @@
       "as: string - HTML element",
       "size: 2xs|xs|sm|base|md|lg|xl|2xl|3xl|4xl - font size (px: 10/12/14/14/15/20/24/30/36/48)",
       "weight: normal|medium|semibold|bold - font weight",
-      "color: primary|secondary|tertiary|muted - text color (muted = tertiary)",
+      "color: primary|secondary|tertiary|muted|success|warning|danger - text color (muted = tertiary; semantic colours for inline state)",
       "font: sans|mono - font family",
       "truncate: boolean - enable truncation",
       "lineClamp: number - max lines"

package/src/components/Text/Text.module.scss

@@ -88,6 +88,24 @@
   color: var(--fui-text-tertiary, $fui-text-tertiary);
 }
 
+// Semantic colours, for a run of text that carries a state on its own — a
+// count going over budget, an inline "expired", a figure in the red. Where
+// there is a component for the job (Badge, Alert, Callout) use that instead:
+// this is for the cases where the state is one word inside a line, and
+// wrapping it in a box would be more chrome than the fact is worth. Colour is
+// never the only carrier — the words still have to say it.
+.color-success {
+  color: var(--fui-color-success, $fui-color-success);
+}
+
+.color-warning {
+  color: var(--fui-color-warning, $fui-color-warning);
+}
+
+.color-danger {
+  color: var(--fui-color-danger, $fui-color-danger);
+}
+
 // Font family
 .mono {
   font-family: var(--fui-font-mono, $fui-font-mono);

package/src/components/Text/index.tsx

@@ -19,9 +19,11 @@ export interface TextProps extends Omit<React.HTMLAttributes<HTMLElement>, 'colo
   /** Font weight.
    * @default "normal" */
   weight?: 'normal' | 'medium' | 'semibold' | 'bold';
-  /** Text color. `"muted"` is an alias for `"tertiary"`.
+  /** Text color. `"muted"` is an alias for `"tertiary"`. `"success" | "warning" | "danger"`
+   * are for a run of text that carries a state on its own; prefer Badge or Alert when the
+   * state deserves a container.
    * @default "primary" */
-  color?: 'primary' | 'secondary' | 'tertiary' | 'muted';
+  color?: 'primary' | 'secondary' | 'tertiary' | 'muted' | 'success' | 'warning' | 'danger';
   /** Font family.
    * @default "sans" */
   font?: 'sans' | 'mono';

package/src/index.ts

@@ -567,6 +567,7 @@ export {
 
 // Chart
 export {
+  Chart,
   ChartContainer,
   ChartTooltip,
   ChartTooltipContent,

package/src/tokens/_mixins.scss

@@ -114,11 +114,41 @@
 @mixin popup-container {
   display: flex;
   flex-direction: column;
-  gap: 1px;
-  padding: var(--fui-space-1, #{$fui-space-1});
+  gap: var(--fui-popup-row-gap, #{$fui-popup-row-gap});
+  padding: var(--fui-popup-padding, #{$fui-popup-padding});
   box-shadow: var(--fui-shadow-md, #{$fui-shadow-md});
 }
 
+// Scroll viewport for the popups that peek — Select, Listbox, Combobox. Sets
+// `--_popup-scroll-max-h`; the consumer applies it, because Base UI puts an
+// inline `max-height: 100%` on some of these popups that only `!important` beats.
+//
+// Row *pitch*, not row height: `popup-container` is a flex column, so N rows
+// occupy N pitches less the trailing gap. (A grouped popup nests its rows one
+// level down, where that gap does not reach, so the peek there runs a few
+// pixels shy of half a row — visible only as a slightly smaller sliver.)
+// Every term here reads the token that actually draws it — which is the point.
+// Written out longhand in three separate stylesheets, this calc billed
+// $fui-space-2 of vertical padding for a row `popup-item` pads with
+// $fui-space-1, deriving a 46px row against a real 32px one, so all three
+// popups outgrew their own content and never scrolled at all.
+@mixin popup-scroll-viewport {
+  --_popup-row-h: calc(
+    var(--fui-popup-item-font-size, #{$fui-popup-item-font-size}) *
+      var(--fui-line-height-normal, #{$fui-line-height-normal}) +
+      var(--fui-popup-item-padding-block, #{$fui-popup-item-padding-block}) * 2 +
+      var(--fui-popup-row-gap, #{$fui-popup-row-gap})
+  );
+
+  // The + 2px is the 1px border `surface-elevated` draws top and bottom: these
+  // popups are border-box, so max-height pays for the frame before the rows.
+  --_popup-scroll-max-h: calc(
+    var(--_popup-row-h) *
+      var(--fui-select-max-items, 4.5) - var(--fui-popup-row-gap, #{$fui-popup-row-gap}) +
+      var(--fui-popup-padding, #{$fui-popup-padding}) * 2 + 2px
+  );
+}
+
 // ============================================
 // Popup / menu item — canonical interaction model
 // ============================================
@@ -136,16 +166,21 @@
 // `&[data-highlighted] { @include popup-item-highlight; }` covers both. Custom popups
 // should map `&:hover, &.<active>, &[data-highlighted]` to the same mixin.
 
-// Dropdown/popup item base. Includes button-reset and text-base.
+// Dropdown/popup item base. Includes button-reset and text-base, then steps the
+// size down to the popup scale — see $fui-popup-item-font-size. Select, Listbox
+// and Combobox size their scroll viewport from the same token, so read it there
+// too rather than re-deriving an item height from the body size.
 @mixin popup-item {
   @include button-reset;
   @include text-base;
 
+  font-size: var(--fui-popup-item-font-size, #{$fui-popup-item-font-size});
   display: flex;
   align-items: center;
   gap: var(--fui-space-1, #{$fui-space-1});
   width: 100%;
-  padding: var(--fui-space-1, #{$fui-space-1}) var(--fui-space-2, #{$fui-space-2});
+  padding: var(--fui-popup-item-padding-block, #{$fui-popup-item-padding-block})
+    var(--fui-popup-item-padding-inline, #{$fui-popup-item-padding-inline});
   border-radius: var(--fui-radius-sm, #{$fui-radius-sm});
   cursor: pointer;
   outline: none;

package/src/tokens/_variables.scss

@@ -73,6 +73,14 @@ $fui-font-size-2xl: 2.143rem !default; // 30px (large display)
 $fui-font-size-3xl: 2.571rem !default; // 36px (h1, page title)
 $fui-font-size-4xl: 3.429rem !default; // 48px (hero display)
 
+// Dropdown/popup list items — menus, selects, comboboxes, listboxes, command
+// palettes. One step below chrome text: a popup is a dense list scanned against
+// the trigger that opened it, and matching the trigger's own size made the list
+// read heavier than the control. Named rather than inlined because Select,
+// Listbox and Combobox derive their scroll height from this exact number; a
+// literal in the mixin would let the height calcs drift out of step with it.
+$fui-popup-item-font-size: $fui-font-size-xs !default; // 12px
+
 $fui-font-weight-normal: 400 !default;
 $fui-font-weight-medium: 500 !default;
 $fui-font-weight-semibold: 600 !default;
@@ -110,6 +118,20 @@ $fui-space-8: computed.$computed-space-8 !default;
 $fui-space-10: computed.$computed-space-10 !default;
 $fui-space-12: computed.$computed-space-12 !default;
 
+// --------------------------------------------
+// Popup geometry
+// --------------------------------------------
+// The insets a popup list and its rows carry. Named rather than inlined because
+// Select, Listbox and Combobox size their scroll viewport from these exact
+// numbers to show N rows plus a half-peek hint. Left as literals in the mixin,
+// the two sides drifted: the height calcs charged $fui-space-2 of vertical
+// padding for a row `popup-item` pads with $fui-space-1, so every one of those
+// popups peeked further than its own "4.5 items" comment promised.
+$fui-popup-padding: $fui-space-1 !default; // container inset
+$fui-popup-row-gap: 1px !default; // flex gap between rows
+$fui-popup-item-padding-block: $fui-space-1 !default;
+$fui-popup-item-padding-inline: $fui-space-2 !default;
+
 // --------------------------------------------
 // Border Radius (derived from radius-style seed)
 // --------------------------------------------
@@ -397,6 +419,7 @@ $fui-code-selection-bg: color-mix(
     --fui-font-size-2xl: #{$fui-font-size-2xl};
     --fui-font-size-3xl: #{$fui-font-size-3xl};
     --fui-font-size-4xl: #{$fui-font-size-4xl};
+    --fui-popup-item-font-size: #{$fui-popup-item-font-size};
     --fui-font-weight-normal: #{$fui-font-weight-normal};
     --fui-font-weight-medium: #{$fui-font-weight-medium};
     --fui-font-weight-semibold: #{$fui-font-weight-semibold};
@@ -427,6 +450,13 @@ $fui-code-selection-bg: color-mix(
     --fui-space-10: #{$fui-space-10};
     --fui-space-12: #{$fui-space-12};
 
+    // Popup geometry — the numbers Select/Listbox/Combobox derive their scroll
+    // viewport from. Override these and the peek height follows.
+    --fui-popup-padding: #{$fui-popup-padding};
+    --fui-popup-row-gap: #{$fui-popup-row-gap};
+    --fui-popup-item-padding-block: #{$fui-popup-item-padding-block};
+    --fui-popup-item-padding-inline: #{$fui-popup-item-padding-inline};
+
     // Border radius
     --fui-radius-sm: #{$fui-radius-sm};
     --fui-radius-md: #{$fui-radius-md};