@qilin-agent/client-ui-primitives 3.1.6 → 3.1.8

package/lib/types/Tooltip.d.ts

@@ -1,17 +1,19 @@
-import type { FocusEventHandler, MouseEventHandler, ReactElement, Ref } from 'react';
-/** Bubble placement relative to the anchor. */
-export type TooltipSide = 'right' | 'bottom' | 'top';
+/** Anchor-preserving tooltips; an optional body portal escapes clipping containers and stacking contexts that cap the bubble's z-index. */
+import type { FocusEventHandler, MouseEventHandler, PointerEventHandler, ReactElement, Ref } from 'react';
+import { type TooltipSide } from './tooltip-placement.ts';
+export type { TooltipSide } from './tooltip-placement.ts';
 /**
- * Suppression channel for enclosing tooltip and hover-card anchors: a visible
- * tooltip within an anchor withdraws the enclosing preview while its bubble is shown.
+ * Suppression channel for nested tooltips: a visible descendant tooltip
+ * withdraws the enclosing tooltip while its bubble is shown.
  */
 export declare const TooltipSuppression: import("react").Context<((suppressed: boolean) => void) | null>;
 /** Props Tooltip injects into its anchor child; the child's own handlers are chained ahead of the tooltip's. */
 interface AnchorProps {
     'aria-describedby'?: string | undefined;
     ref?: Ref<HTMLElement> | undefined;
-    onMouseEnter?: MouseEventHandler | undefined;
-    onMouseLeave?: MouseEventHandler | undefined;
+    onPointerEnter?: PointerEventHandler | undefined;
+    onPointerLeave?: PointerEventHandler | undefined;
+    onPointerDown?: PointerEventHandler | undefined;
     onClick?: MouseEventHandler | undefined;
     onFocus?: FocusEventHandler | undefined;
     onBlur?: FocusEventHandler | undefined;
@@ -19,36 +21,49 @@ interface AnchorProps {
 type TooltipLabel = string | (() => string);
 /**
  * Attach a hover/focus tooltip to an anchor element.
- * @param props.label - bubble text, or a resolver evaluated only while the bubble is visible.
+ * @param props.label - bubble text, or a resolver evaluated only while visible; an empty string shows only shortcut keys.
  * @param props.shortcutKeys - effective key labels rendered as platform-formatted keycaps after optional text.
- * @param props.side - placement relative to the anchor (default 'right').
+ * @param props.side - preferred placement (default 'right'); fitting tries the opposite then perpendicular sides.
+ * @param props.align - horizontal anchor-edge alignment for 'bottom'/'top' bubbles: 'end' pins
+ * the bubble's right edge to the anchor's (for anchors beside other hover surfaces the centered
+ * bubble would overlap); default 'center'. Horizontal placements ignore it.
+ * @param props.portal - render the bubble under document.body, so an ancestor's clipping or its
+ * stacking context (which confines the bubble's z-index to that context) cannot hide it.
  * @param props.delayMs - hover delay in milliseconds (default 0).
- * @param props.focusDelayMs - keyboard focus delay in milliseconds (default 0); blur, mouse
- * leave, disabling, and unmount cancel a pending show.
+ * @param props.focusDelayMs - keyboard focus delay in milliseconds (default 0); blur, click,
+ * mouse leave, disabling, and unmount cancel a pending show.
+ * @param props.gap - anchor-to-bubble distance in pixels for 'bottom'/'top' bubbles (default 8);
+ * horizontal placements use 10px, including after a flip.
  * @param props.disabled - suppress the bubble while true; the anchor renders identically so
  * toggling never remounts it (which would cut its CSS transitions).
- * @param props.portal - render the bubble under document.body, so an ancestor's clipping or its
- * stacking context can neither clip the bubble nor paint over it.
  * @param props.maxWidth - bubble width cap in pixels, for labels long enough that the default
- * half-viewport cap would render a slab wider than the surface the anchor sits on.
- * @param props.openOnClick - clicking also pins the bubble for reading; another click, Escape,
- * Tab, or an outside pointerdown dismisses it. Defaults to false, leaving an ordinary action
- * tooltip to hover and focus alone.
+ * half-viewport cap would render a slab wider than the surface the anchor sits on; always bounded by viewport margins.
+ * @param props.openOnClick - clicking or tapping also pins the bubble for reading; another click, Escape,
+ * Tab, or an outside pointerdown dismisses it. Defaults to false for ordinary action tooltips.
+ * @param props.onlyWhenClipped - show the bubble only when the anchor or an HTML element inside it
+ * overflows horizontally, measured when the bubble is about to show; for labels that repeat
+ * text an ellipsis may cut off. Defaults to false.
  * @param props.children - a single anchor element; its own ref (callback or object) is forwarded alongside the tooltip's.
- * An anchor that accepts no ref still positions the bubble: a raise records the element the event ran on.
- * @returns the cloned anchor plus a fixed-position bubble while hovered/focused.
+ * @returns the cloned anchor plus a fixed-position bubble, optionally portaled to the body.
+ * The bubble stays hidden until ResizeObserver supplies its size for viewport fitting; clicking the
+ * anchor dismisses the bubble unless openOnClick is enabled, and focus arriving after a pointer
+ * interaction (a closing menu refocusing its trigger) never raises it. Touch cannot trigger hover
+ * tooltips; tapping still invokes the child's action and can open an openOnClick explanation.
+ * When no side fits, the viewport-bounded fallback may overlap the anchor; oversized content is scrollable when pinned.
  */
-export declare function Tooltip({ label, shortcutKeys, side, delayMs, focusDelayMs, disabled, portal, maxWidth, openOnClick, children }: {
+export declare function Tooltip({ label, shortcutKeys, side, align, delayMs, focusDelayMs, gap, disabled, portal, maxWidth, openOnClick, onlyWhenClipped, children }: {
     label: TooltipLabel;
     shortcutKeys?: readonly string[] | undefined;
     side?: TooltipSide;
+    align?: 'center' | 'end';
     delayMs?: number;
     focusDelayMs?: number;
+    gap?: number;
     disabled?: boolean;
     portal?: boolean;
     maxWidth?: number;
     openOnClick?: boolean;
+    onlyWhenClipped?: boolean;
     children: ReactElement<AnchorProps>;
 }): import("react").JSX.Element;
-export {};
 //# sourceMappingURL=Tooltip.d.ts.map

package/lib/types/UserMessageBubble.d.ts

@@ -0,0 +1,11 @@
+/** Shared user-message background, typography, and content inset. */
+import type { ComponentPropsWithoutRef } from 'react';
+/** Native div attributes for user-authored message content. */
+export type UserMessageBubbleProps = ComponentPropsWithoutRef<'div'>;
+/**
+ * Render user-style message content without row placement or actions.
+ * @param props - Native div attributes and the caller-owned content.
+ * @returns A theme-aware message surface that wraps its content.
+ */
+export declare function UserMessageBubble({ className, ...props }: UserMessageBubbleProps): import("react").JSX.Element;
+//# sourceMappingURL=UserMessageBubble.d.ts.map

package/lib/types/code-file-types.d.ts

@@ -14,7 +14,7 @@ export interface FileTypeProjectContext {
  */
 export declare function isCodeFileType(type: string): type is CodeFileType;
 /**
- * Test whether an extension belonged to the established coarse LinkIcon code category.
+ * Test whether an extension belongs to the established coarse link-icon code category.
  * @param extension - Extension without a leading dot.
  * @returns Whether clickable links keep the code glyph for this extension.
  */

package/lib/types/code-highlighting.d.ts

@@ -0,0 +1,12 @@
+import { type HighlightSpan } from './markdown/highlight.ts';
+export { CODE_HIGHLIGHT_EXTENSIONS, languageForPath } from '@qilin-agent/util-code-language';
+/** Highlight one source fragment into one token list per line. */
+export type CodeHighlighter = (code: string) => HighlightSpan[][] | undefined;
+/**
+ * Bind the shared lazy highlighter to one language and refresh after its grammar loads.
+ * @param language - grammar hint selected from the source filename.
+ * @returns a stable fragment highlighter; unknown and loading grammars return `undefined` for plain-text fallback.
+ */
+export declare function useCodeHighlighter(language: string | undefined): CodeHighlighter;
+export type { HighlightSpan };
+//# sourceMappingURL=code-highlighting.d.ts.map

package/lib/types/focus.d.ts

@@ -6,4 +6,12 @@
  * @param options - browser focus options, including scroll preservation.
  */
 export declare function focusWithoutRing(element: HTMLElement, options?: FocusOptions): void;
+/**
+ * Whether this browser runs on a touch-first mobile device.
+ *
+ * The answer is cached, so a caller must not expect it to follow a viewport
+ * resize. It drives input-shape choices only; layout reacts to container width.
+ * @returns `true` on a mobile browser, `false` on a desktop one.
+ */
+export declare function isMobileDevice(): boolean;
 //# sourceMappingURL=focus.d.ts.map