@slithy/base-ui 0.1.0

package/README.md

@@ -0,0 +1,230 @@
+# @slithy/base-ui
+
+Compound UI components built on [Base UI](https://base-ui.com/). Provides accessible, unstyled primitives with sensible defaults, deferred rendering for performance, and full compatibility with animation libraries.
+
+## Components
+
+### Tooltip
+
+```tsx
+import { Tooltip } from "@slithy/base-ui";
+
+<Tooltip.Provider>
+  <Tooltip.Root>
+    <Tooltip.Trigger>Hover me</Tooltip.Trigger>
+    <Tooltip.Portal>
+      <Tooltip.Positioner sideOffset={8}>
+        <Tooltip.Popup>
+          <Tooltip.Arrow />
+          Tooltip content
+        </Tooltip.Popup>
+      </Tooltip.Positioner>
+    </Tooltip.Portal>
+  </Tooltip.Root>
+</Tooltip.Provider>
+```
+
+**Parts:** `Provider`, `Root`, `Trigger`, `Portal`, `Positioner`, `Popup`, `Arrow`
+
+#### Props
+
+**`Root`** accepts all Base UI Tooltip.Root props, plus:
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `touchDisabled` | `boolean` | `true` | Block activation from touch interactions. Mouse/keyboard still work on hybrid devices. |
+| `unmountOnClose` | `boolean` | `false` | Unmount Base UI after close animation completes, returning to the lightweight pre-activation state. Useful for pages with many tooltips where accumulated mounted instances add up. |
+
+**`Trigger`** accepts all Base UI Tooltip.Trigger props, plus:
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `render` | `ReactElement \| (props, state) => ReactElement` | — | Replace the default `<button>` with a custom element. Works in both pre- and post-activation states. See [Custom trigger element](#custom-trigger-element). |
+
+### Dropdown
+
+```tsx
+import { Dropdown } from "@slithy/base-ui";
+
+<Dropdown.Root>
+  <Dropdown.Trigger>Open menu</Dropdown.Trigger>
+  <Dropdown.Portal>
+    <Dropdown.Positioner sideOffset={4}>
+      <Dropdown.Popup>
+        <Dropdown.Item onClick={handleEdit}>Edit</Dropdown.Item>
+        <Dropdown.Item onClick={handleDuplicate}>Duplicate</Dropdown.Item>
+        <Dropdown.Separator />
+        <Dropdown.Item onClick={handleDelete}>Delete</Dropdown.Item>
+      </Dropdown.Popup>
+    </Dropdown.Positioner>
+  </Dropdown.Portal>
+</Dropdown.Root>
+```
+
+**Parts:** `Root`, `Trigger`, `Portal`, `Positioner`, `Popup`, `Arrow`, `Item`, `Separator`, `Group`, `GroupLabel`, `CheckboxItem`, `CheckboxItemIndicator`, `RadioGroup`, `RadioItem`, `RadioItemIndicator`
+
+#### Disabling the dropdown
+
+Set `disabled` on `Root` to prevent the dropdown from opening while keeping the trigger interactive. This is useful when you want alternate behavior for the same trigger — for example, opening a modal on mobile instead of a dropdown:
+
+```tsx
+const isMobile = useIsMobile();
+const [modalOpen, setModalOpen] = useState(false);
+
+<Dropdown.Root disabled={isMobile}>
+  <Dropdown.Trigger onClick={isMobile ? () => setModalOpen(true) : undefined}>
+    Options
+  </Dropdown.Trigger>
+  <Dropdown.Portal>
+    <Dropdown.Positioner sideOffset={4}>
+      <Dropdown.Popup>
+        <Dropdown.Item onClick={handleEdit}>Edit</Dropdown.Item>
+        <Dropdown.Item onClick={handleDelete}>Delete</Dropdown.Item>
+      </Dropdown.Popup>
+    </Dropdown.Positioner>
+  </Dropdown.Portal>
+</Dropdown.Root>
+```
+
+Event handlers on `Trigger` (`onClick`, `onPointerDown`, `onKeyDown`) always fire, regardless of the `disabled` state — only the dropdown activation is suppressed.
+
+#### Props
+
+**`Root`** accepts all Base UI Menu.Root props, plus:
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `disabled` | `boolean` | `false` | Prevent the dropdown from opening. The trigger button remains interactive so consumers can attach alternate behavior (e.g. opening a modal on mobile) via event handlers on `Trigger`. |
+| `unmountOnClose` | `boolean` | `false` | Unmount Base UI after close animation completes, returning to the lightweight pre-activation state. Useful for pages with many dropdowns where accumulated mounted instances add up. |
+
+**`Trigger`** accepts all Base UI Menu.Trigger props, plus:
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `tooltip` | `ReactNode` | — | Show a tooltip on hover. The tooltip is deferred (not mounted until first hover) and automatically dismissed when the dropdown menu opens. |
+| `render` | `ReactElement \| (props, state) => ReactElement` | — | Replace the default `<button>` with a custom element. Works in both pre- and post-activation states. See [Custom trigger element](#custom-trigger-element). |
+
+## Deferred rendering
+
+Both components use a deferred rendering pattern that avoids mounting Base UI's hooks and floating-ui positioning until the user first interacts with the trigger. Before activation, the trigger renders as a plain `<button>` and portal content is not mounted. This keeps initial JS overhead minimal when rendering many tooltips or dropdowns on a page.
+
+The activation latch is one-way by default: once triggered, it stays active so that leave animations can play. Controlled `open` or `defaultOpen` bypass the latch entirely.
+
+Set `unmountOnClose` on Root to reset the latch after the close animation completes. This returns the component to its lightweight pre-activation state, freeing Base UI hooks and floating-ui listeners. Useful for long-lived pages with many tooltips or dropdowns where accumulated mounted instances add up.
+
+## Custom trigger element
+
+Both `Tooltip.Trigger` and `Dropdown.Trigger` accept a `render` prop to replace the default `<button>` with a custom element. This works across both pre- and post-activation states — the deferred rendering layer applies the same prop to whichever element is currently rendered.
+
+**Element form** — pass a React element. All required event handlers, `ref`, `className`, `style`, and `disabled` are merged in via `cloneElement`. Existing props on the element are preserved for any key that isn't overridden:
+
+```tsx
+<Dropdown.Trigger render={<MyButton variant="ghost" />}>
+  Open menu
+</Dropdown.Trigger>
+```
+
+**Function form** — receive the full props object and spread it onto your element. Use this form when you need to compose your own handlers alongside the trigger's, or when your component needs additional logic:
+
+```tsx
+<Tooltip.Trigger
+  render={(props) => (
+    <MyButton
+      {...props}
+      onFocus={(e) => {
+        props.onFocus?.(e);
+        trackFocusEvent();
+      }}
+    />
+  )}
+>
+  Hover me
+</Tooltip.Trigger>
+```
+
+> **Note:** For the element form, event handlers defined on the render element (e.g. `<MyButton onClick={...} />`) are overridden by the trigger's activation handlers. Use the function form if you need to run your own handlers alongside them.
+
+Your custom component must forward `ref` to its underlying DOM element so that focus restoration and synthetic event dispatch work correctly after activation.
+
+## Styling
+
+Each component applies default class names (`slithy-tooltip-*`, `slithy-dropdown-*`) that can be overridden by passing your own `className`. Default styles use CSS custom properties for theming:
+
+```css
+/* Tooltip */
+--slithy-tooltip-bg
+--slithy-tooltip-color
+--slithy-tooltip-font-size
+--slithy-tooltip-padding
+--slithy-tooltip-radius
+--slithy-tooltip-max-width
+
+/* Dropdown */
+--slithy-dropdown-bg
+--slithy-dropdown-color
+--slithy-dropdown-font-size
+--slithy-dropdown-padding
+--slithy-dropdown-radius
+--slithy-dropdown-min-width
+--slithy-dropdown-shadow
+--slithy-dropdown-border
+--slithy-dropdown-item-padding
+--slithy-dropdown-item-highlighted-bg
+--slithy-dropdown-separator-color
+--slithy-dropdown-group-label-padding
+--slithy-dropdown-group-label-color
+```
+
+## Positioning
+
+Both components pass all props through to Base UI's Positioner, which wraps floating-ui internally. Common positioning props:
+
+```tsx
+<Tooltip.Positioner
+  side="bottom"       // "top" | "bottom" | "left" | "right"
+  sideOffset={8}      // distance from trigger (px)
+  align="center"      // "start" | "center" | "end"
+  alignOffset={0}     // alignment offset (px)
+  collisionPadding={5} // viewport edge padding (px)
+/>
+```
+
+## Custom animations
+
+The `Popup` and `Positioner` components accept a `render` prop (from Base UI) that lets you replace the rendered element. (The `Trigger` `render` prop is documented separately under [Custom trigger element](#custom-trigger-element).) This makes it straightforward to use animation libraries like react-spring:
+
+```tsx
+import { useTransition, animated } from "@react-spring/web";
+
+function AnimatedTooltip({ children }: { children: React.ReactNode }) {
+  return (
+    <Tooltip.Provider>
+      <Tooltip.Root>
+        <Tooltip.Trigger>Hover me</Tooltip.Trigger>
+        <Tooltip.Portal>
+          <Tooltip.Positioner sideOffset={8}>
+            <Tooltip.Popup
+              render={(props) => (
+                <animated.div
+                  {...props}
+                  style={{
+                    ...props.style,
+                    opacity: /* your spring value */,
+                    transform: /* your spring value */,
+                  }}
+                />
+              )}
+            >
+              {children}
+            </Tooltip.Popup>
+          </Tooltip.Positioner>
+        </Tooltip.Portal>
+      </Tooltip.Root>
+    </Tooltip.Provider>
+  );
+}
+```
+
+Base UI exposes `data-open`, `data-starting-style`, and `data-ending-style` attributes on popup elements, and `onOpenChangeComplete` on Root, so you can drive enter/leave animations from open state and signal completion.
+
+The deferred rendering layer does not interfere with animations -- by the time they run, the activation latch has flipped and Base UI is fully mounted.

package/dist/index.d.ts

@@ -0,0 +1,97 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { Menu } from '@base-ui/react/menu';
+import * as react from 'react';
+import { ComponentPropsWithoutRef, ReactNode } from 'react';
+import * as _base_ui_react from '@base-ui/react';
+import { Tooltip as Tooltip$1 } from '@base-ui/react/tooltip';
+
+type RootProps$1 = ComponentPropsWithoutRef<typeof Menu.Root> & {
+    children?: ReactNode;
+    /** When `true`, the dropdown will not open. The trigger button remains
+     *  interactive so consumers can attach alternate behavior (e.g. opening
+     *  a modal on mobile) via event handlers on `Dropdown.Trigger`. */
+    disabled?: boolean;
+    /** Unmount Base UI after close animation completes, returning to the
+     *  lightweight pre-activation state. Defaults to `false`. */
+    unmountOnClose?: boolean;
+};
+declare function Root$1({ children, open, defaultOpen, disabled, unmountOnClose, onOpenChangeComplete, ...props }: RootProps$1): react_jsx_runtime.JSX.Element;
+type TriggerProps$1 = ComponentPropsWithoutRef<typeof Menu.Trigger> & {
+    /** Show a tooltip on hover. Accepts any ReactNode content. */
+    tooltip?: ReactNode;
+};
+declare function Trigger$1({ children, className, style, disabled, tooltip, ...rest }: TriggerProps$1): react_jsx_runtime.JSX.Element;
+type PortalProps$1 = ComponentPropsWithoutRef<typeof Menu.Portal>;
+declare function Portal$1(props: PortalProps$1): react_jsx_runtime.JSX.Element | null;
+type PositionerProps$1 = ComponentPropsWithoutRef<typeof Menu.Positioner>;
+declare function Positioner$1({ className, ...props }: PositionerProps$1): react_jsx_runtime.JSX.Element;
+type PopupProps$1 = ComponentPropsWithoutRef<typeof Menu.Popup>;
+declare function Popup$1({ className, ...props }: PopupProps$1): react_jsx_runtime.JSX.Element;
+type ArrowProps$1 = ComponentPropsWithoutRef<typeof Menu.Arrow>;
+declare function Arrow$1({ className, ...props }: ArrowProps$1): react_jsx_runtime.JSX.Element;
+type ItemProps = ComponentPropsWithoutRef<typeof Menu.Item>;
+declare function Item({ className, ...props }: ItemProps): react_jsx_runtime.JSX.Element;
+type SeparatorProps = ComponentPropsWithoutRef<typeof Menu.Separator>;
+declare function Separator({ className, ...props }: SeparatorProps): react_jsx_runtime.JSX.Element;
+type GroupProps = ComponentPropsWithoutRef<typeof Menu.Group>;
+declare function Group({ className, ...props }: GroupProps): react_jsx_runtime.JSX.Element;
+type GroupLabelProps = ComponentPropsWithoutRef<typeof Menu.GroupLabel>;
+declare function GroupLabel({ className, ...props }: GroupLabelProps): react_jsx_runtime.JSX.Element;
+type CheckboxItemProps = ComponentPropsWithoutRef<typeof Menu.CheckboxItem>;
+declare function CheckboxItem({ className, ...props }: CheckboxItemProps): react_jsx_runtime.JSX.Element;
+type CheckboxItemIndicatorProps = ComponentPropsWithoutRef<typeof Menu.CheckboxItemIndicator>;
+declare function CheckboxItemIndicator({ className, ...props }: CheckboxItemIndicatorProps): react_jsx_runtime.JSX.Element;
+type RadioGroupProps = ComponentPropsWithoutRef<typeof Menu.RadioGroup>;
+declare function RadioGroup({ className, ...props }: RadioGroupProps): react_jsx_runtime.JSX.Element;
+type RadioItemProps = ComponentPropsWithoutRef<typeof Menu.RadioItem>;
+declare function RadioItem({ className, ...props }: RadioItemProps): react_jsx_runtime.JSX.Element;
+type RadioItemIndicatorProps = ComponentPropsWithoutRef<typeof Menu.RadioItemIndicator>;
+declare function RadioItemIndicator({ className, ...props }: RadioItemIndicatorProps): react_jsx_runtime.JSX.Element;
+declare const Dropdown: {
+    Root: typeof Root$1;
+    Trigger: typeof Trigger$1;
+    Portal: typeof Portal$1;
+    Positioner: typeof Positioner$1;
+    Popup: typeof Popup$1;
+    Arrow: typeof Arrow$1;
+    Item: typeof Item;
+    Separator: typeof Separator;
+    Group: typeof Group;
+    GroupLabel: typeof GroupLabel;
+    CheckboxItem: typeof CheckboxItem;
+    CheckboxItemIndicator: typeof CheckboxItemIndicator;
+    RadioGroup: typeof RadioGroup;
+    RadioItem: typeof RadioItem;
+    RadioItemIndicator: typeof RadioItemIndicator;
+};
+
+type RootProps = ComponentPropsWithoutRef<typeof Tooltip$1.Root> & {
+    children?: ReactNode;
+    /** Block activation from touch interactions. Defaults to `true`. */
+    touchDisabled?: boolean;
+    /** Unmount Base UI after close animation completes, returning to the
+     *  lightweight pre-activation state. Defaults to `false`. */
+    unmountOnClose?: boolean;
+};
+declare function Root({ children, open, defaultOpen, disabled, touchDisabled, unmountOnClose, onOpenChangeComplete, ...props }: RootProps): react_jsx_runtime.JSX.Element;
+type TriggerProps = ComponentPropsWithoutRef<typeof Tooltip$1.Trigger>;
+declare function Trigger({ children, className, style, disabled, ...rest }: TriggerProps): react_jsx_runtime.JSX.Element;
+type PortalProps = ComponentPropsWithoutRef<typeof Tooltip$1.Portal>;
+declare function Portal(props: PortalProps): react_jsx_runtime.JSX.Element | null;
+type PositionerProps = ComponentPropsWithoutRef<typeof Tooltip$1.Positioner>;
+declare function Positioner({ className, ...props }: PositionerProps): react_jsx_runtime.JSX.Element;
+type PopupProps = ComponentPropsWithoutRef<typeof Tooltip$1.Popup>;
+declare function Popup({ className, ...props }: PopupProps): react_jsx_runtime.JSX.Element;
+type ArrowProps = ComponentPropsWithoutRef<typeof Tooltip$1.Arrow>;
+declare function Arrow({ className, ...props }: ArrowProps): react_jsx_runtime.JSX.Element;
+declare const Tooltip: {
+    Provider: react.FC<_base_ui_react.TooltipProviderProps>;
+    Root: typeof Root;
+    Trigger: typeof Trigger;
+    Portal: typeof Portal;
+    Positioner: typeof Positioner;
+    Popup: typeof Popup;
+    Arrow: typeof Arrow;
+};
+
+export { Dropdown, Tooltip };