@sableui/react 0.6.2 → 0.7.1

package/dist/components/select/select.js

@@ -0,0 +1,191 @@
+"use client";
+
+// src/components/select/select.tsx
+import { Select as Base } from "@base-ui/react/select";
+import {
+  Children,
+  isValidElement
+} from "react";
+import { Icon } from "../../icon/index.js";
+import { anchoredListScroll } from "../../lib/anchored-scroll.js";
+import { cn } from "../../lib/cn.js";
+import { FIELD_INVALID, FIELD_SHELL_XS, MOBILE_FIELD_TIER } from "../../lib/field-shell.js";
+import { withPortalThemeScope } from "../../lib/portal-theme-scope.js";
+import { useAnchoredDensity, useDensity, useTypeTier } from "../../lib/density.js";
+import { HighlightGlide } from "../../lib/highlight-glide.js";
+import { jsx, jsxs } from "react/jsx-runtime";
+function textContent(node) {
+  if (typeof node === "string") return node;
+  if (typeof node === "number") return String(node);
+  if (Array.isArray(node)) {
+    let text = "";
+    for (const part of node) {
+      const t = textContent(part);
+      if (t === void 0) return void 0;
+      text += t;
+    }
+    return text;
+  }
+  return void 0;
+}
+function deriveItemLabels(node, out = {}) {
+  for (const child of Children.toArray(node)) {
+    if (!isValidElement(child)) continue;
+    const props = child.props;
+    if (child.type === SelectItem) {
+      const label = props.label ?? textContent(props.children);
+      const { value } = props;
+      if ((typeof value === "string" || typeof value === "number") && label !== void 0) {
+        out[String(value)] = label;
+      }
+      continue;
+    }
+    if (props.children) deriveItemLabels(props.children, out);
+  }
+  return out;
+}
+function Select({
+  items,
+  children,
+  ...props
+}) {
+  const derived = items === void 0 ? deriveItemLabels(children) : void 0;
+  const resolvedItems = items ?? (derived && Object.keys(derived).length > 0 ? derived : void 0);
+  return /* @__PURE__ */ jsx(Base.Root, { items: resolvedItems, ...props, children });
+}
+var SelectPortal = withPortalThemeScope(Base.Portal);
+var SelectGroup = Base.Group;
+var SelectValue = Base.Value;
+function SelectTrigger({
+  className,
+  placeholder,
+  size = "md",
+  children,
+  ...props
+}) {
+  const tier = useTypeTier();
+  const density = useDensity();
+  const mobileTier = density === "comfortable" && size === "md" && MOBILE_FIELD_TIER;
+  return /* @__PURE__ */ jsxs(
+    Base.Trigger,
+    {
+      className: cn(
+        `flex w-full items-center justify-between ${tier.body} text-foreground motion-interactive`,
+        mobileTier,
+        size === "xs" ? cn("h-(--control-xs) gap-1 px-1.5", FIELD_SHELL_XS) : "h-(--control-md) gap-2 rounded-sm border border-input bg-card px-3",
+        "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+        "data-[popup-open]:ring-2 data-[popup-open]:ring-ring",
+        // Invalid like every other field: Base UI marks the trigger
+        // `data-invalid` inside a Field, an explicit aria-invalid works too.
+        "data-[invalid]:border-destructive data-[invalid]:ring-destructive/30",
+        FIELD_INVALID,
+        "disabled:cursor-not-allowed disabled:opacity-50",
+        className
+      ),
+      ...props,
+      children: [
+        /* @__PURE__ */ jsx(Base.Value, { placeholder, children }),
+        /* @__PURE__ */ jsx(Base.Icon, { className: "flex items-center justify-center", children: /* @__PURE__ */ jsx(
+          Icon,
+          {
+            name: "chevron-down",
+            className: "text-xs opacity-60 motion-interactive data-[popup-open]:rotate-180"
+          }
+        ) })
+      ]
+    }
+  );
+}
+function SelectContent({
+  className,
+  children,
+  side = "bottom",
+  align = "start",
+  sideOffset = 6,
+  ...props
+}) {
+  const anchoredDensity = useAnchoredDensity();
+  return /* @__PURE__ */ jsx(SelectPortal, { children: /* @__PURE__ */ jsx(
+    Base.Positioner,
+    {
+      side,
+      align,
+      sideOffset,
+      className: "z-(--z-overlay)",
+      children: /* @__PURE__ */ jsxs(
+        Base.Popup,
+        {
+          ...anchoredDensity,
+          className: cn(
+            "min-w-[var(--anchor-width)] rounded-md border border-border-floating bg-popover popup-inset text-popover-foreground shadow-md outline-none",
+            // 18rem at rest, but never taller than the room the positioner
+            // measured. See lib/anchored-scroll.
+            anchoredListScroll,
+            "motion-pop",
+            className
+          ),
+          ...props,
+          children: [
+            /* @__PURE__ */ jsx(HighlightGlide, {}),
+            /* @__PURE__ */ jsx(Base.List, { children })
+          ]
+        }
+      )
+    }
+  ) });
+}
+function SelectItem({ className, children, label, ...props }) {
+  const tier = useTypeTier();
+  return /* @__PURE__ */ jsxs(
+    Base.Item,
+    {
+      label: label ?? textContent(children),
+      className: cn(
+        `relative flex cursor-default items-center justify-between gap-(--item-gap) rounded-popup-item px-(--item-px) py-1.5 ${tier.body} outline-none`,
+        "data-[highlighted]:bg-accent data-[highlighted]:text-accent-foreground",
+        "data-[disabled]:pointer-events-none data-[disabled]:opacity-50",
+        className
+      ),
+      ...props,
+      children: [
+        /* @__PURE__ */ jsx(Base.ItemText, { children }),
+        /* @__PURE__ */ jsx(Base.ItemIndicator, { className: "flex items-center justify-center", children: /* @__PURE__ */ jsx(Icon, { name: "check", className: "text-xs" }) })
+      ]
+    }
+  );
+}
+function SelectGroupLabel({ className, ...props }) {
+  const tier = useTypeTier();
+  return /* @__PURE__ */ jsx(
+    Base.GroupLabel,
+    {
+      className: cn(
+        // The item inset, not a fixed px-2: the heading's text starts on the
+        // same column as the option labels beneath it at every density.
+        `px-(--item-px) py-1.5 ${tier.label} text-muted-foreground`,
+        className
+      ),
+      ...props
+    }
+  );
+}
+function SelectSeparator({ className, ...props }) {
+  return /* @__PURE__ */ jsx(
+    Base.Separator,
+    {
+      className: cn("popup-bleed my-1 h-px bg-border", className),
+      ...props
+    }
+  );
+}
+export {
+  Select,
+  SelectContent,
+  SelectGroup,
+  SelectGroupLabel,
+  SelectItem,
+  SelectPortal,
+  SelectSeparator,
+  SelectTrigger,
+  SelectValue
+};

package/dist/components/select/select.meta.js

@@ -0,0 +1,189 @@
+// src/components/select/select.meta.ts
+var selectMeta = {
+  name: "Select",
+  summary: "Listbox over Base UI Select \u2014 typeahead, roving focus, collision-aware popup, ARIA option wiring, and form integration. Trigger shows the selected value; the popup portals to <body>.",
+  keywords: [
+    "select",
+    "listbox",
+    "dropdown",
+    "picker",
+    "option",
+    "choice",
+    "typeahead",
+    "form"
+  ],
+  usage: {
+    description: "Use Select when users choose one value from a known, finite set. Use Combobox for searchable or user-entered values, Combobox `multiple` for several choices, and Radio when all options should remain visible.",
+    bestPractices: [
+      {
+        guidance: "do",
+        description: "Use clear item labels and pass label explicitly when children are richer than plain text."
+      },
+      {
+        guidance: "do",
+        description: "Group long option sets with SelectGroup and SelectGroupLabel when categories improve scanning."
+      },
+      {
+        guidance: "do",
+        description: "Wrap in Field when the select belongs to a form so label, helper text, and errors are wired automatically."
+      },
+      {
+        guidance: "dont",
+        description: "Use Select for very large or fuzzy lists. Use Combobox when typing is the primary way to find an option."
+      },
+      {
+        guidance: "dont",
+        description: "Use Select for binary on/off settings. Use Switch or Checkbox instead."
+      },
+      {
+        guidance: "do",
+        description: "Leave the trigger's type alone on mobile. Below the sm breakpoint the md trigger renders text-body-lg (17px) so it matches the Input and Textarea beside it, which carry that tier because iOS Safari zooms the page when a focused field computes under 16px. A custom field in the same row should follow: a second paired tier under a max-sm: variant, never a hand-set font-size."
+      },
+      {
+        guidance: "do",
+        description: "Inside a <Workspace> a Select adapts automatically \u2014 trigger and popup both pick up the compact density, including across the portal. Do NOT hand-size it per call site; that was necessary before v0.41 and is now drift."
+      }
+    ],
+    anatomy: [
+      {
+        name: "Root",
+        required: true,
+        description: "Owns value, open state, form integration, and item collection."
+      },
+      {
+        name: "Trigger",
+        required: true,
+        description: "The button that shows the selected value and opens the listbox."
+      },
+      {
+        name: "Content",
+        required: true,
+        description: "The positioned popup containing options and optional groups."
+      },
+      {
+        name: "Item",
+        required: true,
+        description: "A selectable option with selected and highlighted states."
+      }
+    ]
+  },
+  related: {
+    components: ["Combobox", "Radio", "Field", "Input"],
+    patterns: ["SettingsPage", "AuthPage"]
+  },
+  status: "stable",
+  props: [
+    {
+      name: "items",
+      type: "Record<string, ReactNode> | { value: string; label: ReactNode }[]",
+      description: "value \u2192 label map (a record, or an array of { value, label }). Derived automatically from literal SelectItem children; pass it explicitly when the items are generated in a loop, or a closed trigger renders the raw value instead of the label."
+    },
+    {
+      name: "Select (Root)",
+      type: "Base UI Select.Root props (value, defaultValue, onValueChange, open, defaultOpen, onOpenChange, disabled, required, name, multiple, items)",
+      description: "Controls the selected value and open state. Uncontrolled by default. When `items` isn't passed, it is derived from the SelectItem children so the closed trigger shows display text instead of the raw value; pass `items` explicitly when item children aren't plain strings."
+    }
+  ],
+  subcomponents: [
+    {
+      name: "SelectTrigger",
+      type: 'Base UI Trigger props + placeholder?: ReactNode + size?: "md" | "xs" + className',
+      description: 'The button. Composes Trigger + Value + a chevron Icon that flips on open (data-[popup-open]). `size="xs"` is the property-grid rung \u2014 height, padding, radius AND surface move together, which is why it is a prop and not a className: the xs trigger is an inset `bg-panel-field` field with no border, matching ScrubField on the same row. A consumer overriding only the height gets an md-register 8px radius on a 24px box and a raised card sitting among inset fields; one inspector panel had eleven of those, and both tells are visible at a glance.'
+    },
+    {
+      name: "SelectContent",
+      type: "Base UI Popup props + side, align, sideOffset + className",
+      description: 'Portal + Positioner + Popup + List. side="bottom", align="start", sideOffset=6 by default; matches trigger width.'
+    },
+    {
+      name: "SelectItem",
+      type: "{ value: string; disabled?: boolean; label?: string } + className",
+      description: "An option. Composes Item + ItemText + a check ItemIndicator for the selected row. String children double as the item's `label`, so the closed trigger shows the display text \u2014 pass `label` explicitly only when children are richer than a string."
+    },
+    {
+      name: "SelectGroup",
+      type: "Base UI Group props + className",
+      description: "Optional grouping of related options."
+    },
+    {
+      name: "SelectGroupLabel",
+      type: "Base UI GroupLabel props + className",
+      description: "The heading associated with a SelectGroup for screen readers."
+    },
+    {
+      name: "SelectValue",
+      type: "Base UI Value props (children render fn) + placeholder",
+      description: "Renders the selected option's label with a placeholder fallback. Already composed inside SelectTrigger; exported for advanced layouts that render the value outside the default trigger."
+    },
+    {
+      name: "SelectSeparator",
+      type: "Base UI Separator props + className",
+      description: "A thin themed divider between groups of items. Decorative \u2014 Base UI marks it aria-hidden."
+    }
+  ],
+  tokensUsed: [
+    "input",
+    "card",
+    "foreground",
+    "ring",
+    "border",
+    "popover",
+    "popover-foreground",
+    "accent",
+    "accent-foreground",
+    "muted-foreground"
+  ],
+  motion: [
+    {
+      slot: "arrival",
+      recipe: "motion-pop",
+      part: "SelectContent",
+      why: "The popup's transform-origin follows Base UI's anchor, so it grows out of the trigger it belongs to. On a dense form with several selects in a column, that origin is the only thing identifying which field the open list is for."
+    },
+    {
+      slot: "response",
+      recipe: "motion-interactive",
+      part: "SelectItem",
+      why: "Highlight follows both pointer and keyboard. Easing it means arrow-keying down a list is continuous motion rather than a background teleporting between rows, which is what makes a long list readable while moving."
+    },
+    {
+      slot: "transition",
+      recipe: "motion-pop",
+      part: "SelectContent",
+      why: "Closing collapses back toward the trigger, so the reader's eye is returned to the field that now holds the value they just picked."
+    },
+    {
+      slot: "activity",
+      recipe: "none",
+      part: "SelectContent",
+      why: "Select takes a resident list of options. Anything that has to be fetched or filtered as you type is Combobox, which owns that state."
+    }
+  ],
+  a11y: [
+    "Base UI provides listbox/option roles, aria-expanded, typeahead, roving focus, and a hidden form input.",
+    "Esc and click-outside dismiss; arrow keys and Home/End navigate the list.",
+    "Selected option carries data-[selected]; the highlighted option carries data-[highlighted].",
+    "Animate the popup via data-[starting-style] / data-[ending-style]."
+  ],
+  examples: [
+    {
+      label: "Basic (controlled)",
+      code: '<Select value={value} onValueChange={setValue}><SelectTrigger placeholder="Choose a font" /><SelectContent><SelectItem value="sans">Sans-serif</SelectItem><SelectItem value="serif">Serif</SelectItem><SelectItem value="mono">Monospace</SelectItem></SelectContent></Select>'
+    },
+    {
+      label: "Grouped",
+      code: '<SelectContent><SelectGroup><SelectGroupLabel>Weights</SelectGroupLabel><SelectItem value="regular">Regular</SelectItem><SelectItem value="bold">Bold</SelectItem></SelectGroup></SelectContent>'
+    },
+    {
+      label: "Inside Field",
+      code: '<Field label="Default visibility" description="Controls how new editions appear."><Select defaultValue="public"><SelectTrigger placeholder="Choose visibility" /><SelectContent><SelectItem value="public">Public</SelectItem><SelectItem value="private">Private</SelectItem><SelectItem value="unlisted">Unlisted</SelectItem></SelectContent></Select></Field>'
+    },
+    {
+      label: "Rich item labels",
+      code: '<Select defaultValue="edition" items={[{ value: "edition", label: "Edition" }, { value: "collectible", label: "Collectible" }]}><SelectTrigger /><SelectContent><SelectItem value="edition" label="Edition"><span className="flex items-center gap-2"><Badge tone="edition">Edition</Badge><span>Edition drop</span></span></SelectItem><SelectItem value="collectible" label="Collectible"><span className="flex items-center gap-2"><Badge tone="collectible">Collectible</Badge><span>Collectible</span></span></SelectItem></SelectContent></Select>'
+    }
+  ]
+};
+export {
+  selectMeta
+};

package/dist/components/separator/index.js

@@ -0,0 +1,7 @@
+// src/components/separator/index.ts
+import { Separator } from "./separator.js";
+import { separatorMeta } from "./separator.meta.js";
+export {
+  Separator,
+  separatorMeta
+};

package/dist/components/separator/separator.js

@@ -0,0 +1,42 @@
+// src/components/separator/separator.tsx
+import { Separator as Base } from "@base-ui/react/separator";
+import { cn } from "../../lib/cn.js";
+import { jsx, jsxs } from "react/jsx-runtime";
+function Separator({
+  orientation = "horizontal",
+  label,
+  className,
+  ...props
+}) {
+  if (label != null && orientation === "horizontal") {
+    return /* @__PURE__ */ jsxs(
+      "div",
+      {
+        role: "separator",
+        "aria-orientation": "horizontal",
+        className: cn("flex items-center gap-3", className),
+        children: [
+          /* @__PURE__ */ jsx("span", { className: "h-px flex-1 bg-border" }),
+          /* @__PURE__ */ jsx("span", { className: "text-body-xs text-muted-foreground", children: label }),
+          /* @__PURE__ */ jsx("span", { className: "h-px flex-1 bg-border" })
+        ]
+      }
+    );
+  }
+  return /* @__PURE__ */ jsx(
+    Base,
+    {
+      orientation,
+      className: cn(
+        "shrink-0 bg-border",
+        orientation === "horizontal" ? "h-px w-full" : "h-full w-px self-stretch",
+        className
+      ),
+      ...props
+    }
+  );
+}
+Separator.displayName = "Separator";
+export {
+  Separator
+};

package/dist/components/separator/separator.meta.js

@@ -0,0 +1,84 @@
+// src/components/separator/separator.meta.ts
+var separatorMeta = {
+  name: "Separator",
+  summary: "A hairline divider. Horizontal full-width rule or vertical 1px column, tinted with the border token. Optional centered label (horizontal) for a captioned section divider.",
+  status: "stable",
+  keywords: [
+    "separator",
+    "divider",
+    "section break",
+    "rule"
+  ],
+  usage: {
+    description: "Use Separator to divide related groups where spacing alone does not provide enough structure.",
+    bestPractices: [
+      {
+        guidance: "do",
+        description: "Use it sparingly between sections, menu groups, or dense rows."
+      },
+      {
+        guidance: "do",
+        description: "Choose orientation based on the layout direction it separates."
+      },
+      {
+        guidance: "dont",
+        description: "Do not use Separator as decoration when hierarchy, spacing, or headings would explain the layout better."
+      },
+      {
+        guidance: "dont",
+        description: "Do not use it where space would do. A page whose every section is divided by a rule reads as a form; the rule should mark a real change of subject."
+      }
+    ]
+  },
+  related: {
+    components: [
+      "Menu",
+      "ContextMenu",
+      "Card"
+    ]
+  },
+  props: [
+    {
+      name: "orientation",
+      type: '"horizontal" | "vertical"',
+      default: '"horizontal"',
+      description: "Axis of the rule. Vertical stretches to its flex parent's height."
+    },
+    {
+      name: "label",
+      type: "ReactNode",
+      description: "When set (horizontal only), centers a muted caption between two hairline rules."
+    },
+    {
+      name: "render",
+      type: "ReactElement | (props, state) => ReactElement",
+      description: "Compose with another element/component through the Base UI render prop. Ignored on the labeled variant."
+    }
+  ],
+  variants: {
+    orientation: ["horizontal", "vertical"]
+  },
+  tokensUsed: ["border", "muted-foreground"],
+  a11y: [
+    "Base UI sets role=separator and aria-orientation for assistive tech.",
+    "The labeled variant renders a div with explicit role=separator + aria-orientation (the caption is the visible context).",
+    "Purely decorative dividers can carry aria-hidden when adjacent content already conveys the grouping."
+  ],
+  examples: [
+    {
+      label: "Horizontal",
+      code: "<Separator />"
+    },
+    {
+      label: "Labeled section divider",
+      code: '<Separator label="Other holdings" />'
+    },
+    {
+      label: "Vertical (inside a flex row)",
+      code: '<Row gap={3} className="h-6 items-center"><span>Edit</span><Separator orientation="vertical" /><span>Delete</span></Row>'
+    }
+  ]
+};
+export {
+  separatorMeta
+};

package/dist/components/settings-menu/index.js

@@ -0,0 +1,11 @@
+// src/components/settings-menu/index.ts
+import {
+  SettingsMenu,
+  SettingsRow
+} from "./settings-menu.js";
+import { settingsMenuMeta } from "./settings-menu.meta.js";
+export {
+  SettingsMenu,
+  SettingsRow,
+  settingsMenuMeta
+};

package/dist/components/settings-menu/settings-menu.js

@@ -0,0 +1,101 @@
+// src/components/settings-menu/settings-menu.tsx
+import { Icon } from "../../icon/index.js";
+import { cn } from "../../lib/cn.js";
+import { useTypeTier } from "../../lib/density.js";
+import {
+  Menu,
+  MenuContent,
+  MenuSubmenu,
+  MenuSubmenuTrigger,
+  MenuTrigger
+} from "../menu/index.js";
+import { Button } from "../button/button.js";
+import {
+  SETTINGS_TRIGGER_SIZE,
+  SETTINGS_TRIGGER_VARIANT,
+  settingsMenuTriggerClassName
+} from "./settings-menu.variants.js";
+import { jsx, jsxs } from "react/jsx-runtime";
+function SettingsMenu({
+  summary,
+  label = "Change settings",
+  variant = "ghost",
+  size = "sm",
+  side = "top",
+  align = "end",
+  disabled,
+  className,
+  children,
+  ...props
+}) {
+  const tier = useTypeTier();
+  return /* @__PURE__ */ jsxs(Menu, { ...props, children: [
+    /* @__PURE__ */ jsxs(
+      MenuTrigger,
+      {
+        "aria-label": label,
+        disabled,
+        render: /* @__PURE__ */ jsx(
+          Button,
+          {
+            variant: SETTINGS_TRIGGER_VARIANT[variant],
+            size: SETTINGS_TRIGGER_SIZE[size],
+            className: cn(settingsMenuTriggerClassName, tier.body, className)
+          }
+        ),
+        children: [
+          /* @__PURE__ */ jsx("span", { className: "truncate", children: summary }),
+          /* @__PURE__ */ jsx(Icon, { name: "chevron-down", className: "opacity-60" })
+        ]
+      }
+    ),
+    /* @__PURE__ */ jsx(MenuContent, { side, align, className: "min-w-56", children })
+  ] });
+}
+SettingsMenu.displayName = "SettingsMenu";
+function SettingsRow({
+  label,
+  value,
+  disabled,
+  className,
+  children
+}) {
+  const tier = useTypeTier();
+  if (!children) {
+    return /* @__PURE__ */ jsxs(
+      "div",
+      {
+        className: cn(
+          // MenuItem's row recipe — inset, gap, concentric radius and tier — so a
+          // flat row and a nesting row in the same list are the same shape.
+          "flex select-none items-center gap-(--item-gap) rounded-popup-item px-(--item-px) py-1.5",
+          tier.body,
+          disabled && "opacity-50",
+          className
+        ),
+        children: [
+          /* @__PURE__ */ jsx("span", { className: "flex-1 truncate", children: label }),
+          value !== void 0 ? /* @__PURE__ */ jsx("span", { className: "truncate text-muted-foreground", children: value }) : null,
+          /* @__PURE__ */ jsx(Icon, { name: "chevron-right", className: "invisible text-xs" })
+        ]
+      }
+    );
+  }
+  return /* @__PURE__ */ jsxs(MenuSubmenu, { children: [
+    /* @__PURE__ */ jsx(
+      MenuSubmenuTrigger,
+      {
+        value,
+        disabled,
+        className,
+        children: label
+      }
+    ),
+    /* @__PURE__ */ jsx(MenuContent, { side: "inline-end", align: "start", sideOffset: 4, children })
+  ] });
+}
+SettingsRow.displayName = "SettingsRow";
+export {
+  SettingsMenu,
+  SettingsRow
+};