@gusnips/react 0.1.0

package/src/ui/select.tsx

@@ -0,0 +1,191 @@
+import { Select as Primitive } from "@base-ui/react/select";
+import type { ReactNode } from "react";
+import { mergeClassName, type StateClassName } from "./class-name.ts";
+import { CheckGlyph, ChevronGlyph } from "./glyphs.tsx";
+
+// The parts, for a select this wrapper's option list cannot express — groups, separators,
+// a scrollable list with arrows.
+export const SelectRoot = Primitive.Root;
+export const SelectTrigger = Primitive.Trigger;
+export const SelectValue = Primitive.Value;
+export const SelectIcon = Primitive.Icon;
+export const SelectPortal = Primitive.Portal;
+export const SelectPositioner = Primitive.Positioner;
+export const SelectPopup = Primitive.Popup;
+export const SelectList = Primitive.List;
+export const SelectItem = Primitive.Item;
+export const SelectItemIndicator = Primitive.ItemIndicator;
+export const SelectItemText = Primitive.ItemText;
+export const SelectGroup = Primitive.Group;
+export const SelectGroupLabel = Primitive.GroupLabel;
+export const SelectSeparator = Primitive.Separator;
+
+export interface SelectOption<T extends string = string> {
+  value: T;
+  label: string;
+  disabled?: boolean;
+  icon?: ReactNode;
+}
+
+export type SelectProps<T extends string = string> = Omit<
+  Primitive.Root.Props<T, false>,
+  "children" | "items" | "defaultValue" | "multiple"
+> & {
+  options?: readonly SelectOption<T>[];
+  /** Shown while nothing is selected. No default — a default would be English. */
+  placeholder?: ReactNode;
+  /**
+   * Shown instead of the list when `options` is empty. Required, because a popup that opens
+   * on nothing is a dead end: this is the line that says why it is empty.
+   */
+  emptyLabel: ReactNode;
+  /**
+   * Label of an entry that puts the field back to nothing selected — for an optional
+   * question, where "I'd rather not say" has to stay reachable after the first answer.
+   * Rendered only once there is a value to take back; picking it calls `onValueChange(null)`.
+   */
+  clearLabel?: string;
+  /** Accessible name for the trigger, when no visible label points at it. */
+  label?: string;
+  /** Mark that says "this opens". */
+  chevron?: ReactNode;
+  /** Mark next to the selected option. */
+  indicator?: ReactNode;
+  /** Classes for the trigger — the button you see when the popup is closed. */
+  className?: StateClassName<Primitive.Trigger.State>;
+  popupClassName?: StateClassName<Primitive.Popup.State>;
+  triggerProps?: Primitive.Trigger.Props;
+  /**
+   * Positioner props — `align`, `side`, `sideOffset`, `collisionPadding`, and the stacking
+   * order. The default `z-[60]` puts the list above the overlay layer (z-50: dialog, drawer);
+   * raise it with `positionerProps={{ className: "z-[80]" }}` if the app stacks something
+   * higher than a dialog above it.
+   */
+  positionerProps?: Primitive.Positioner.Props;
+};
+
+/**
+ * A single-choice field. Trigger, portal, positioner, popup and list composed once; `name`,
+ * `form`, `required`, `id`, `disabled` and every other root prop pass straight through to
+ * Base UI's hidden input, so this submits inside a `<form>` like a native `<select>`.
+ *
+ * Controlled only, and that is the point of `value ?? null`: React and Base UI both read
+ * `value={undefined}` as "uncontrolled", so a caller holding `T | undefined` in state would
+ * silently hand the field back to the primitive the moment the value cleared, and every
+ * later render would be ignored. `null` says "nothing selected" out loud. `defaultValue` is
+ * not accepted here for the same reason — use the parts for an uncontrolled select.
+ */
+export function Select<T extends string = string>({
+  value,
+  options = [],
+  placeholder,
+  emptyLabel,
+  clearLabel,
+  label,
+  chevron,
+  indicator,
+  className,
+  popupClassName,
+  triggerProps,
+  positionerProps,
+  ...rest
+}: SelectProps<T>) {
+  const selected = options.find((option) => option.value === value);
+  // `undefined` when nothing is selected, and it has to be exactly that. Base UI's Value part
+  // falls back to `placeholder` only when it is handed NO children at all — an empty fragment
+  // still counts as children, which is how the donor ended up with a select that showed a
+  // blank trigger instead of "Choose one".
+  const selectedLabel = selected ? (
+    <>
+      {selected.icon ? (
+        <span className="mr-2 inline-flex align-middle">{selected.icon}</span>
+      ) : null}
+      {selected.label}
+    </>
+  ) : undefined;
+
+  return (
+    <Primitive.Root<T, false> value={value ?? null} items={options} {...rest}>
+      <Primitive.Trigger
+        aria-label={label}
+        {...triggerProps}
+        className={mergeClassName(
+          // No focus style: the trigger keeps the app's one `:focus-visible` outline. Swapping
+          // it for a `ring-*` loses forced-colors mode, where a box-shadow is forced to none.
+          "flex w-full items-center justify-between gap-2 rounded-md border border-input bg-background px-3 py-2 text-left text-foreground disabled:pointer-events-none disabled:opacity-50",
+          className,
+        )}
+      >
+        <Primitive.Value
+          placeholder={placeholder}
+          className="min-w-0 flex-1 truncate data-placeholder:text-muted-foreground"
+        >
+          {selectedLabel}
+        </Primitive.Value>
+        <Primitive.Icon className="shrink-0 text-muted-foreground">
+          {chevron ?? <ChevronGlyph />}
+        </Primitive.Icon>
+      </Primitive.Trigger>
+      <Primitive.Portal>
+        {/* Above the overlay layer (z-50: dialog, drawer). A select opened inside a dialog
+            portals to the body just like the dialog does, so nesting decides nothing and z
+            decides everything — one step lower and the list paints behind the panel that
+            anchors it. */}
+        <Primitive.Positioner
+          sideOffset={4}
+          {...positionerProps}
+          className={mergeClassName(
+            "z-[60] max-w-[var(--available-width)] outline-none",
+            positionerProps?.className,
+          )}
+        >
+          <Primitive.Popup
+            className={mergeClassName(
+              "min-w-[var(--anchor-width)] origin-[var(--transform-origin)] overflow-hidden border border-border bg-popover text-popover-foreground outline-none transition-[scale,opacity] data-ending-style:scale-95 data-ending-style:opacity-0 data-starting-style:scale-95 data-starting-style:opacity-0",
+              popupClassName,
+            )}
+          >
+            <Primitive.List className="max-h-[var(--available-height)] overflow-y-auto">
+              {clearLabel !== undefined && value != null ? (
+                // An Item with `value={null}`, not a button above the list: only an item is
+                // reachable by arrow keys and typeahead, and only an item closes the popup
+                // on its own. `null` is what arrives at `onValueChange`.
+                <Primitive.Item
+                  value={null}
+                  className="flex cursor-default items-center gap-2 px-3 py-2 text-muted-foreground outline-none data-highlighted:bg-accent data-highlighted:text-accent-foreground"
+                >
+                  <span className="size-4 shrink-0" aria-hidden="true" />
+                  <Primitive.ItemText>{clearLabel}</Primitive.ItemText>
+                </Primitive.Item>
+              ) : null}
+              {options.length === 0 ? (
+                <div className="px-3 py-2 text-muted-foreground">{emptyLabel}</div>
+              ) : (
+                options.map((option) => (
+                  <Primitive.Item
+                    key={option.value}
+                    value={option.value}
+                    disabled={option.disabled}
+                    className="flex cursor-default items-center gap-2 px-3 py-2 outline-none data-disabled:pointer-events-none data-disabled:opacity-50 data-highlighted:bg-accent data-highlighted:text-accent-foreground"
+                  >
+                    {/* The mark keeps a column of its own whether or not it is showing, so
+                        the labels do not shift by 16px when the selection moves. */}
+                    <span className="size-4 shrink-0">
+                      <Primitive.ItemIndicator>
+                        {indicator ?? <CheckGlyph />}
+                      </Primitive.ItemIndicator>
+                    </span>
+                    {option.icon ? (
+                      <span className="inline-flex shrink-0">{option.icon}</span>
+                    ) : null}
+                    <Primitive.ItemText>{option.label}</Primitive.ItemText>
+                  </Primitive.Item>
+                ))
+              )}
+            </Primitive.List>
+          </Primitive.Popup>
+        </Primitive.Positioner>
+      </Primitive.Portal>
+    </Primitive.Root>
+  );
+}

package/src/ui/tabs.tsx

@@ -0,0 +1,95 @@
+import { Tabs as Primitive } from "@base-ui/react/tabs";
+import { cn } from "../cn.ts";
+import { mergeClassName } from "./class-name.ts";
+
+// Root and Panel pass straight through: a wrapper around either would add a class string and
+// nothing else, and Base UI already owns arrow-key navigation, activation mode and the
+// tab/panel `aria-controls` wiring.
+export const Tabs = Primitive.Root;
+export const TabPanel = Primitive.Panel;
+
+type TabListLabel =
+  | { label: string; "aria-labelledby"?: undefined }
+  | { label?: undefined; "aria-labelledby": string };
+
+export type TabListProps = Omit<Primitive.List.Props, "aria-labelledby"> &
+  TabListLabel & {
+    /** Classes for the scroll wrapper — the element that owns the sideways scroll. */
+    wrapperClassName?: string;
+  };
+
+/**
+ * The rail, and the reason this file exists.
+ *
+ * It scrolls sideways rather than wrapping, because a second row of tabs pushes the panel
+ * below the fold on a phone. But the scroll cannot live on the rail itself: `overflow-x: auto`
+ * makes the element a scroll container, a scroll container clips everything its children paint
+ * outside the padding box, and a computed `overflow-x` of `auto` forces `overflow-y` from
+ * `visible` to `auto` as well. A self-scrolling rail therefore crops the focus ring on all
+ * FOUR sides of whichever tab the keyboard is on — top and bottom always, the left of the
+ * first tab and the right of the last.
+ *
+ * So the scroll goes on a wrapper, and the wrapper's padding is the room the ring needs. The
+ * number is derived, not inherited: `@gusnips/tokens` draws `outline: 2px solid` at
+ * `outline-offset: 2px`, so the ring paints from 2px to 4px beyond a tab's border box, and
+ * `p-1` is exactly those 4px. An outline reaches FURTHER than the `ring-2` box-shadow the
+ * donor had here, so the wrapper matters more now than it did there, not less.
+ *
+ * Naming the rail is not optional and not a comment: pass `label`, or point
+ * `aria-labelledby` at a heading. A tablist with neither is announced as nothing at all.
+ */
+export function TabList({ label, className, wrapperClassName, children, ...rest }: TabListProps) {
+  return (
+    <div className={cn("w-fit max-w-full overflow-x-auto p-1", wrapperClassName)}>
+      <Primitive.List
+        aria-label={label}
+        {...rest}
+        // `relative`, because TabIndicator positions itself against the rail.
+        className={mergeClassName("relative flex w-fit", className)}
+      >
+        {children}
+      </Primitive.List>
+    </div>
+  );
+}
+
+// Styled off `aria-selected`, never a parallel `data-active`: the primitive writes both from
+// one state, and styling the accessibility contract is what keeps what a screen reader
+// announces and what an eye sees from ever drifting apart.
+//
+// `shrink-0` and `whitespace-nowrap` are what make the rail scroll instead of squashing — a
+// tab that shrinks to fit is a tab nobody can read, and the scroll above exists precisely so
+// it does not have to.
+const tabClasses =
+  "shrink-0 cursor-pointer px-3 py-1.5 whitespace-nowrap text-muted-foreground select-none aria-selected:text-foreground [@media(pointer:coarse)]:min-h-11";
+
+export function Tab({ className, ...rest }: Primitive.Tab.Props) {
+  return <Primitive.Tab {...rest} className={mergeClassName(tabClasses, className)} />;
+}
+
+/**
+ * The travelling marker under the active tab — a SEPARATE part, because the two donors
+ * disagreed about whether to have one at all and both were right about their own app. Render
+ * it or do not; the rail works either way.
+ *
+ * It must be a child of `TabList`: Base UI measures the active tab against the enclosing
+ * `[role="tablist"]` and writes `--active-tab-left` / `--active-tab-width` onto this element.
+ *
+ * `renderBeforeHydration` is on by default because this package's apps are prerendered — with
+ * it off, every prerendered page shows the rail with no marker until React arrives. It writes
+ * one inline script to do that; under a strict CSP without Base UI's `CspProvider` the script
+ * is blocked and the behaviour falls back to exactly what `false` would have done.
+ */
+export function TabIndicator({ className, ...rest }: Primitive.Indicator.Props) {
+  return (
+    <Primitive.Indicator
+      aria-hidden="true"
+      renderBeforeHydration
+      {...rest}
+      className={mergeClassName(
+        "absolute bottom-0 left-0 h-0.5 w-[var(--active-tab-width)] translate-x-[var(--active-tab-left)] bg-foreground transition-[translate,width]",
+        className,
+      )}
+    />
+  );
+}