@deepseek-ai/dsh-client-ui-primitives 0.1.7-rc.2 → 0.2.0-rc.2

package/lib/types/DisclosureRow.d.ts

@@ -1,12 +1,12 @@
 import { type ReactNode } from 'react';
-/** Shared 24px disclosure chrome for compact flow rows. */
+/** Shared 24px process row: tertiary text and icons, secondary on hover. */
 export interface DisclosureRowProps {
     icon: ReactNode;
     title: string;
     open: boolean;
     expandable: boolean;
     onToggle: () => void;
-    /** Animate the title while its owning operation is running. */
+    /** Animate the complete header while its owning operation is running. */
     running?: boolean | undefined;
     /** Makes the complete title row the disclosure target. */
     expandOnRowClick?: boolean | undefined;
@@ -18,6 +18,10 @@ export interface DisclosureRowProps {
     children?: ReactNode;
     className?: string | undefined;
     rowClassName?: string | undefined;
+    /** Sizing class for the header text area, beside the leading icon. */
+    contentClassName?: string | undefined;
+    /** Layout class shared by the header text and its decorative copy. */
+    contentLayoutClassName?: string | undefined;
     leadingClassName?: string | undefined;
     chevronClassName?: string | undefined;
     titleClassName?: string | undefined;
@@ -28,5 +32,5 @@ export interface DisclosureRowProps {
  * @param props - Visual content, controlled state, and interaction policy.
  * @returns the disclosure row.
  */
-export declare const DisclosureRow: import("react").MemoExoticComponent<({ icon, title, open, expandable, onToggle, running, expandOnRowClick, previewChevron, keepContentWhenOpen, collapsedContent, children, className, rowClassName, leadingClassName, chevronClassName, titleClassName, }: DisclosureRowProps) => import("react").JSX.Element>;
+export declare const DisclosureRow: import("react").MemoExoticComponent<({ icon, title, open, expandable, onToggle, running, expandOnRowClick, previewChevron, keepContentWhenOpen, collapsedContent, children, className, rowClassName, contentClassName, contentLayoutClassName, leadingClassName, chevronClassName, titleClassName, }: DisclosureRowProps) => import("react").JSX.Element>;
 //# sourceMappingURL=DisclosureRow.d.ts.map

package/lib/types/Input.d.ts

@@ -1,11 +1,12 @@
-import type { InputHTMLAttributes, ReactNode } from 'react';
+import { type InputHTMLAttributes, type ReactNode } from 'react';
 /**
  * Render a text input with an optional leading icon.
  * @param props.icon - optional 16px leading icon node.
+ * @param ref - the native input, cleared when it unmounts.
  * @returns wrapper span containing the native input; input attributes pass through.
  */
-export declare function Input({ icon, className, ...rest }: {
+export declare const Input: import("react").ForwardRefExoticComponent<{
     icon?: ReactNode;
     className?: string;
-} & InputHTMLAttributes<HTMLInputElement>): import("react").JSX.Element;
+} & InputHTMLAttributes<HTMLInputElement> & import("react").RefAttributes<HTMLInputElement>>;
 //# sourceMappingURL=Input.d.ts.map

package/lib/types/MenuGroup.d.ts

@@ -0,0 +1,22 @@
+/** Accessible menu groups with shared sticky-heading presentation and viewport observation. */
+import { type ReactNode } from 'react';
+/**
+ * Render a named group with an instance-owned heading id and an inaccessible position sentinel.
+ * @param props - Caller-localized label and optional menu rows.
+ * @returns A section named by its direct heading, followed by the supplied children.
+ */
+export declare function MenuGroup({ label, children }: {
+    label: string;
+    children?: ReactNode;
+}): import("react").JSX.Element;
+/**
+ * Update heading backgrounds asynchronously from native intersection and viewport-size observations.
+ * Headings remain transparent until observations identify a section crossing the viewport top.
+ * Without IntersectionObserver or ResizeObserver, CSS sticky headings remain transparent.
+ * Group membership is captured at setup; dispose before observing changed groups or the same viewport again.
+ * @param viewport - Unpadded, borderless scroll container with direct MenuGroup children.
+ * @returns Cleanup owning both intersection observers and the viewport resize observer; disconnects
+ * them, ignores queued callbacks, and clears managed data-stuck attributes. No valid groups acquires nothing.
+ */
+export declare function observeStickyMenuGroups(viewport: HTMLElement): () => void;
+//# sourceMappingURL=MenuGroup.d.ts.map

package/lib/types/TextShimmer.d.ts

@@ -1,13 +1,22 @@
+/** Text activity animation shared by a row and its nested text fragments. */
+import { type ReactNode } from 'react';
 /** Text and activity supplied by the owning row. */
 export interface TextShimmerProps {
-    children: string;
-    active: boolean;
+    /** Text or presentational children with text in nested TextShimmer instances. No effects or element ids. */
+    children: ReactNode;
+    /** Whether to animate; nested instances share the containing row's activity. */
+    active?: boolean | undefined;
     className?: string | undefined;
+    /** Layout class applied equally to the base and decorative content. */
+    contentClassName?: string | undefined;
 }
 /**
- * Render text with an optional moving highlight; inactive text keeps the same node.
+ * Render text with one shared highlight while retaining selectable, accessible content.
+ * Nested instances inherit the outer animation. Keep icons outside; mark decorative
+ * separators with data-shimmer-decoration so their background follows the highlight.
+ * Active children also render in an inert, clipped decoration; supply only presentation.
  * @param props - localized text, running state, and owner styling.
- * @returns the retained text span.
+ * @returns retained text and its optional decorative highlight.
  */
-export declare const TextShimmer: import("react").MemoExoticComponent<({ children, active, className }: TextShimmerProps) => import("react").JSX.Element>;
+export declare const TextShimmer: import("react").MemoExoticComponent<({ children, active, className, contentClassName }: TextShimmerProps) => import("react").JSX.Element>;
 //# sourceMappingURL=TextShimmer.d.ts.map

package/lib/types/Tooltip.d.ts

@@ -9,6 +9,7 @@ export type TooltipSide = 'right' | 'bottom' | 'top';
 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;
@@ -27,29 +28,35 @@ type TooltipLabel = string | (() => string);
  * bubble would overlap); default 'center'. Ignored for side 'right'.
  * @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; keyboard focus remains immediate.
+ * @param props.delayMs - hover delay in milliseconds (default 0).
+ * @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);
  * ignored for side 'right'.
  * @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.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 for ordinary action tooltips.
  * @param props.children - a single anchor element; its own ref (callback or object) is forwarded alongside the tooltip's.
  * @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 until the next trigger, and focus arriving after a pointer
+ * anchor dismisses the bubble unless openOnClick is enabled, and focus arriving after a pointer
  * interaction (a closing menu refocusing its trigger) never raises it.
  */
-export declare function Tooltip({ label, shortcutKeys, side, align, delayMs, gap, disabled, portal, maxWidth, children }: {
+export declare function Tooltip({ label, shortcutKeys, side, align, delayMs, focusDelayMs, gap, disabled, portal, maxWidth, openOnClick, 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;
     children: ReactElement<AnchorProps>;
 }): import("react").JSX.Element;
 export {};

package/lib/types/index.d.ts

@@ -24,6 +24,7 @@ export { Input } from './Input.tsx';
 export { Menu, MenuItemButton } from './Menu.tsx';
 export { MenuSurface } from './MenuSurface.tsx';
 export type { MenuSurfaceProps } from './MenuSurface.tsx';
+export { MenuGroup, observeStickyMenuGroups } from './MenuGroup.tsx';
 export type { MenuItemButtonProps, MenuEntry, MenuItem, MenuSeparator, MenuLabel } from './Menu.tsx';
 export { useAnchoredMaxHeight } from './useAnchoredMaxHeight.ts';
 export { useAnchoredPosition } from './useAnchoredPosition.ts';
@@ -52,6 +53,7 @@ export type { CodeFileType, FileType, FileTypeIconProps, FileTypeKind, FileTypeP
 export { projectUserText, type UserTextReferences } from './user-text.tsx';
 export { Tooltip } from './Tooltip.tsx';
 export type { TooltipSide } from './Tooltip.tsx';
+export { pointerModality } from './input-modality.ts';
 export { Toast } from './Toast.tsx';
 export { fileSizeText } from './file-size.ts';
 export { writeClipboard } from './clipboard.ts';

package/lib/types/overlay-top-margin.d.ts

@@ -1,14 +1,8 @@
-/**
- * Overlay clearance from the window's top strip. On macOS desktop the frame
- * publishes `--dsh-frame-top-clearance` on the root element — the constant
- * step below the traffic-light strip, where clicks drag the window instead of
- * the overlay. JS-clamped overlays keep at least that much air above them.
- * Elsewhere the property is absent and the caller's own margin applies.
- */
+/** Shared viewport inset for overlays, derived from the desktop frame's reserved top strip. */
 /**
  * Resolve the top margin an overlay keeps from the viewport edge.
  * @param min - the overlay's own viewport margin in px, used as the floor.
- * @returns the larger of `min` and the frame's published top clearance.
+ * @returns the larger of `min` and the frame clearance plus 20px; fullscreen keeps only the 20px gap.
  */
 export declare function overlayTopMargin(min: number): number;
 //# sourceMappingURL=overlay-top-margin.d.ts.map

package/lib/types/useAnchoredMaxHeight.d.ts

@@ -5,8 +5,8 @@ import type { RefObject } from 'react';
  * @param cap - design max-height in px (the clamp never exceeds it).
  * @param signal - re-measure trigger: pass the overlay's render state so anchor
  *   moves (composer growth) re-fit; resize/scroll re-fit while mounted.
- * @param margin - viewport top margin floor in px; the frame's published top
- *   clearance widens it. Callers under fixed chrome (the conversation header)
+ * @param margin - viewport top margin floor in px; the frame's overlay
+ *   inset widens it. Callers under fixed chrome (the conversation header)
  *   raise it past their chrome's height.
  * @returns the max-height to apply inline, in px.
  */

package/lib/types/useAnchoredPosition.d.ts

@@ -24,7 +24,7 @@ export interface AnchoredPositionOptions {
     align?: 'start' | 'end';
     /** Distance kept between the anchor edge named by `side` and the panel. */
     gap: number;
-    /** Distance kept between the panel and each viewport edge. */
+    /** Distance kept between the panel and each viewport edge; the frame's overlay inset widens the top margin. */
     margin: number;
 }
 /**

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-client-ui-primitives",
   "description": "Pure React atoms for the dsh web UI: controls, icons, markdown, and JSON inspectors (zero cordis)",
-  "version": "0.1.7-rc.2",
+  "version": "0.2.0-rc.2",
   "publishConfig": {
     "access": "public"
   },
@@ -47,10 +47,10 @@
     "micromark-extension-gfm": "^3.0.0",
     "micromark-util-sanitize-uri": "^2.0.1",
     "simple-icons": "16.31.0",
+    "@deepseek-ai/dsh-client-store": "0.2.0-rc.2",
     "@deepseek-ai/cordis": "~4.0.4",
-    "@deepseek-ai/dsh-client-store": "0.1.7-rc.2",
-    "@deepseek-ai/dsh-util-code-language": "0.1.7-rc.2",
-    "@deepseek-ai/dsh-util-workspace-path": "0.1.7-rc.2"
+    "@deepseek-ai/dsh-util-code-language": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-util-workspace-path": "0.2.0-rc.2"
   },
   "files": [
     "lib/index.js",