@sybilion/uilib 1.0.20

package/src/docs/registry.ts

@@ -0,0 +1,338 @@
+import { ComponentType, LazyExoticComponent, lazy } from 'react';
+
+export type DocEntry = {
+  slug: string;
+  title: string;
+  section: string;
+  load: () => Promise<{ default: ComponentType<object> }>;
+};
+
+/** Sidebar group order */
+export const DOC_SECTION_ORDER = [
+  'Forms',
+  'Feedback',
+  'Layout',
+  'Navigation',
+  'Overlays',
+  'Data display',
+  'Charts',
+  'Chat',
+  'Media',
+  'Misc',
+] as const;
+
+export const DOC_DEFAULT_SLUG = 'button';
+
+export const DOC_REGISTRY: DocEntry[] = [
+  {
+    slug: 'button',
+    title: 'Button',
+    section: 'Forms',
+    load: () => import('./pages/ButtonPage'),
+  },
+  {
+    slug: 'analyses-selector',
+    title: 'AnalysesSelector',
+    section: 'Data display',
+    load: () => import('./pages/AnalysesSelectorPage'),
+  },
+  {
+    slug: 'analysis-line-icon',
+    title: 'AnalysisLineIcon',
+    section: 'Data display',
+    load: () => import('./pages/AnalysisLineIconPage'),
+  },
+  // {
+  //   slug: 'app-header',
+  //   title: 'AppHeader',
+  //   section: 'Layout',
+  //   load: () => import('./pages/AppHeaderPage'),
+  // },
+  {
+    slug: 'avatar',
+    title: 'Avatar',
+    section: 'Data display',
+    load: () => import('./pages/AvatarPage'),
+  },
+  {
+    slug: 'badge',
+    title: 'Badge',
+    section: 'Data display',
+    load: () => import('./pages/BadgePage'),
+  },
+  {
+    slug: 'breadcrumb',
+    title: 'Breadcrumb',
+    section: 'Navigation',
+    load: () => import('./pages/BreadcrumbPage'),
+  },
+  {
+    slug: 'card',
+    title: 'Card',
+    section: 'Layout',
+    load: () => import('./pages/CardPage'),
+  },
+  {
+    slug: 'chart',
+    title: 'Chart',
+    section: 'Charts',
+    load: () => import('./pages/ChartPage'),
+  },
+  {
+    slug: 'chart-area-interactive',
+    title: 'ChartAreaInteractive',
+    section: 'Charts',
+    load: () => import('./pages/ChartAreaInteractivePage'),
+  },
+  {
+    slug: 'chat',
+    title: 'Chat',
+    section: 'Chat',
+    load: () => import('./pages/ChatPage'),
+  },
+  {
+    slug: 'checkbox',
+    title: 'Checkbox',
+    section: 'Forms',
+    load: () => import('./pages/CheckboxPage'),
+  },
+  {
+    slug: 'dialog',
+    title: 'Dialog',
+    section: 'Overlays',
+    load: () => import('./pages/DialogPage'),
+  },
+  {
+    slug: 'drawer',
+    title: 'Drawer',
+    section: 'Overlays',
+    load: () => import('./pages/DrawerPage'),
+  },
+  {
+    slug: 'dropdown-menu',
+    title: 'DropdownMenu',
+    section: 'Overlays',
+    load: () => import('./pages/DropdownMenuPage'),
+  },
+  {
+    slug: 'drop-zone',
+    title: 'DropZone',
+    section: 'Forms',
+    load: () => import('./pages/DropZonePage'),
+  },
+  {
+    slug: 'flickering-grid',
+    title: 'FlickeringGrid',
+    section: 'Misc',
+    load: () => import('./pages/FlickeringGridPage'),
+  },
+  {
+    slug: 'foldable',
+    title: 'Foldable',
+    section: 'Layout',
+    load: () => import('./pages/FoldablePage'),
+  },
+  {
+    slug: 'image',
+    title: 'Image',
+    section: 'Media',
+    load: () => import('./pages/ImagePage'),
+  },
+  {
+    slug: 'image-with-fallback',
+    title: 'ImageWithFallback',
+    section: 'Media',
+    load: () => import('./pages/ImageWithFallbackPage'),
+  },
+  {
+    slug: 'input',
+    title: 'Input',
+    section: 'Forms',
+    load: () => import('./pages/InputPage'),
+  },
+  {
+    slug: 'interactive-content',
+    title: 'InteractiveContent',
+    section: 'Layout',
+    load: () => import('./pages/InteractiveContentPage'),
+  },
+  {
+    slug: 'label',
+    title: 'Label',
+    section: 'Forms',
+    load: () => import('./pages/LabelPage'),
+  },
+  {
+    slug: 'labeled-input',
+    title: 'LabeledInput',
+    section: 'Forms',
+    load: () => import('./pages/LabeledInputPage'),
+  },
+  {
+    slug: 'label-with-id',
+    title: 'LabelWithId',
+    section: 'Forms',
+    load: () => import('./pages/LabelWithIdPage'),
+  },
+  {
+    slug: 'legacy-platform-link',
+    title: 'LegacyPlatformLink',
+    section: 'Navigation',
+    load: () => import('./pages/LegacyPlatformLinkPage'),
+  },
+  {
+    slug: 'logo',
+    title: 'Logo',
+    section: 'Media',
+    load: () => import('./pages/LogoPage'),
+  },
+  {
+    slug: 'mobile-adaptive-selector',
+    title: 'MobileAdaptiveSelector',
+    section: 'Forms',
+    load: () => import('./pages/MobileAdaptiveSelectorPage'),
+  },
+  {
+    slug: 'number-control',
+    title: 'NumberControl',
+    section: 'Forms',
+    load: () => import('./pages/NumberControlPage'),
+  },
+  {
+    slug: 'page',
+    title: 'Page',
+    section: 'Layout',
+    load: () => import('./pages/PagePage'),
+  },
+  {
+    slug: 'progress',
+    title: 'Progress',
+    section: 'Feedback',
+    load: () => import('./pages/ProgressPage'),
+  },
+  {
+    slug: 'region-coords',
+    title: 'RegionCoords',
+    section: 'Forms',
+    load: () => import('./pages/RegionCoordsPage'),
+  },
+  {
+    slug: 'renamer',
+    title: 'Renamer',
+    section: 'Forms',
+    load: () => import('./pages/RenamerPage'),
+  },
+  {
+    slug: 'select',
+    title: 'Select',
+    section: 'Forms',
+    load: () => import('./pages/SelectPage'),
+  },
+  {
+    slug: 'separator',
+    title: 'Separator',
+    section: 'Layout',
+    load: () => import('./pages/SeparatorPage'),
+  },
+  {
+    slug: 'sheet',
+    title: 'Sheet',
+    section: 'Overlays',
+    load: () => import('./pages/SheetPage'),
+  },
+  {
+    slug: 'sidebar',
+    title: 'Sidebar',
+    section: 'Layout',
+    load: () => import('./pages/SidebarPage'),
+  },
+  {
+    slug: 'skeleton',
+    title: 'Skeleton',
+    section: 'Feedback',
+    load: () => import('./pages/SkeletonPage'),
+  },
+  {
+    slug: 'slider',
+    title: 'Slider',
+    section: 'Forms',
+    load: () => import('./pages/SliderPage'),
+  },
+  {
+    slug: 'smart-text-truncate',
+    title: 'SmartTextTruncate',
+    section: 'Data display',
+    load: () => import('./pages/SmartTextTruncatePage'),
+  },
+  {
+    slug: 'sparkline',
+    title: 'Sparkline',
+    section: 'Charts',
+    load: () => import('./pages/SparklinePage'),
+  },
+  {
+    slug: 'switch',
+    title: 'Switch',
+    section: 'Forms',
+    load: () => import('./pages/SwitchPage'),
+  },
+  {
+    slug: 'table',
+    title: 'Table',
+    section: 'Data display',
+    load: () => import('./pages/TablePage'),
+  },
+  {
+    slug: 'tabs',
+    title: 'Tabs',
+    section: 'Layout',
+    load: () => import('./pages/TabsPage'),
+  },
+  {
+    slug: 'text-shimmer',
+    title: 'TextShimmer',
+    section: 'Feedback',
+    load: () => import('./pages/TextShimmerPage'),
+  },
+  {
+    slug: 'text-with-defer-tooltip',
+    title: 'TextWithDeferTooltip',
+    section: 'Data display',
+    load: () => import('./pages/TextWithDeferTooltipPage'),
+  },
+  {
+    slug: 'time-range-controls',
+    title: 'TimeRangeControls',
+    section: 'Forms',
+    load: () => import('./pages/TimeRangeControlsPage'),
+  },
+  {
+    slug: 'toggle',
+    title: 'Toggle',
+    section: 'Forms',
+    load: () => import('./pages/TogglePage'),
+  },
+  {
+    slug: 'toggle-group',
+    title: 'ToggleGroup',
+    section: 'Forms',
+    load: () => import('./pages/ToggleGroupPage'),
+  },
+  {
+    slug: 'tooltip',
+    title: 'Tooltip',
+    section: 'Overlays',
+    load: () => import('./pages/TooltipPage'),
+  },
+  {
+    slug: 'vimeo-embed',
+    title: 'VimeoEmbed',
+    section: 'Media',
+    load: () => import('./pages/VimeoEmbedPage'),
+  },
+];
+
+export const docPageComponents: Record<
+  string,
+  LazyExoticComponent<ComponentType<object>>
+> = Object.fromEntries(DOC_REGISTRY.map(e => [e.slug, lazy(e.load)]));

package/src/hooks/panelWidth.ts

@@ -0,0 +1,72 @@
+export const SIDEBAR_WIDTH_STORAGE_KEY_PX = 'sidebarWidthPx';
+export const SIDEBAR_WIDTH_STORAGE_KEY_PCT = 'sidebarWidthPercent';
+export const CHAT_WIDTH_STORAGE_KEY = 'chatWidthPx';
+
+export const SIDEBAR_WIDTH_MIN_PX = 300;
+export const CHAT_WIDTH_MIN_PX = 500;
+export const SIDEBAR_WIDTH_DEFAULT_PX = 300;
+export const CHAT_WIDTH_DEFAULT_PX = 800;
+export const SHELL_MAX_FRACTION = 0.4;
+export const CHAT_WIDTH_ABS_MAX_PX = 800;
+export const CENTRAL_AREA_MIN_PX = 800;
+
+export type ClampSidebarWidthOpts = {
+  chatPanelOpen: boolean;
+  chatWidthPx: number;
+};
+
+export function maxSidebarWidthPx(shellWidth: number): number {
+  return Math.floor(shellWidth * SHELL_MAX_FRACTION);
+}
+
+export function maxChatWidthPx(shellWidth: number): number {
+  return Math.min(CHAT_WIDTH_ABS_MAX_PX, maxSidebarWidthPx(shellWidth));
+}
+
+function clampWithPanelMin(
+  px: number,
+  panelMin: number,
+  maxPx: number,
+): number {
+  const hi = Math.max(0, maxPx);
+  const lo = Math.min(panelMin, hi);
+  return Math.max(lo, Math.min(hi, Math.round(px)));
+}
+
+export function clampSidebarWidthPx(
+  px: number,
+  shellWidth: number,
+  opts: ClampSidebarWidthOpts,
+): number {
+  if (shellWidth <= 0) {
+    return Math.max(SIDEBAR_WIDTH_MIN_PX, Math.round(px));
+  }
+  const maxFraction = maxSidebarWidthPx(shellWidth);
+  const reservedChat = opts.chatPanelOpen ? opts.chatWidthPx : 0;
+  const capCentral = shellWidth - CENTRAL_AREA_MIN_PX - reservedChat;
+  const maxPx = Math.min(maxFraction, capCentral);
+  return clampWithPanelMin(px, SIDEBAR_WIDTH_MIN_PX, maxPx);
+}
+
+/** Width that reduces the main column when the nav sidebar is expanded; use 0 when collapsed. */
+export function clampChatWidthPx(
+  px: number,
+  shellWidth: number,
+  effectiveSidebarWidthPx: number,
+): number {
+  if (shellWidth <= 0) {
+    return Math.max(CHAT_WIDTH_MIN_PX, Math.round(px));
+  }
+  const maxFraction = maxChatWidthPx(shellWidth);
+  const capCentral = shellWidth - CENTRAL_AREA_MIN_PX - effectiveSidebarWidthPx;
+  const maxPx = Math.min(maxFraction, capCentral);
+  return clampWithPanelMin(px, CHAT_WIDTH_MIN_PX, maxPx);
+}
+
+export function defaultChatWidthPx(shellWidth: number): number {
+  return clampChatWidthPx(
+    CHAT_WIDTH_DEFAULT_PX,
+    shellWidth,
+    SIDEBAR_WIDTH_DEFAULT_PX,
+  );
+}

package/src/hooks/useClickOutside.ts

@@ -0,0 +1,36 @@
+import { RefObject } from 'react';
+
+import useEvent from '#uilib/hooks/useEvent';
+
+type Options = {
+  elem: RefObject<HTMLElement>;
+  isCapture?: boolean;
+  isPassive?: boolean;
+  isActive?: boolean;
+  callback: (e: MouseEvent) => void;
+};
+
+export default function useClickOutside({
+  elem,
+  callback,
+  isActive = true,
+  isCapture = false,
+  isPassive = false,
+}: Options) {
+  const handleClick = (e: MouseEvent) => {
+    if (
+      !elem.current?.contains(e.target as Node) &&
+      document.body.contains(e.target as Node)
+    ) {
+      callback(e);
+    }
+  };
+
+  useEvent({
+    elem,
+    event: 'click',
+    callback: handleClick,
+    isActive,
+    isCapture,
+  });
+}

package/src/hooks/useDebounceCallback.ts

@@ -0,0 +1,18 @@
+import { useCallback } from 'react';
+
+import debounce from '#uilib/tools/debounce';
+
+export function useDebounceCallback<T extends (...args: unknown[]) => void>(
+  fn: T,
+  delay: number,
+  deps: unknown[],
+  debounceOptions?: { leading?: boolean },
+) {
+  const leading = debounceOptions?.leading;
+  return useCallback(debounce(fn ?? (() => {}), delay, debounceOptions), [
+    ...deps,
+    fn,
+    delay,
+    leading,
+  ]);
+}

package/src/hooks/useDragElem.ts

@@ -0,0 +1,153 @@
+import { useRef, useState } from 'react';
+
+import useEvent from './useEvent';
+import type { UseEventParams } from './useEvent';
+
+export type Delta = {
+  x: number;
+  y: number;
+};
+
+type Props = Pick<UseEventParams, 'elem'> & {
+  onDrag: (delta: Delta, e: PointerEvent) => void;
+  onDragStart?: (e: PointerEvent) => void;
+  onDragEnd?: (e: PointerEvent) => void;
+  isActive?: boolean;
+};
+
+export default function useElemDrag({
+  elem,
+  onDrag,
+  onDragStart,
+  onDragEnd,
+  isActive = true,
+}: Props): { isDragging: boolean } {
+  const state = useRef({ startX: 0, startY: 0, x: 0, y: 0, isDragging: false });
+  const [isDragging, setIsDragging] = useState(false);
+  const isStarted = useRef(false);
+  const pointerTypeRef = useRef<PointerEvent['pointerType'] | null>(null);
+  const hasDragIntentRef = useRef(false);
+  const lastMoveRef = useRef({ x: 0, y: 0 });
+
+  const dropDelta = () => {
+    state.current.x = 0;
+    state.current.y = 0;
+    state.current.startX = 0;
+    state.current.startY = 0;
+  };
+
+  const enable = () => {
+    state.current.isDragging = true;
+    dropDelta();
+  };
+
+  const onPointerDown = (e: Event) => {
+    if (!(e instanceof PointerEvent)) return;
+    dropDelta();
+    isStarted.current = true;
+    pointerTypeRef.current = e.pointerType;
+    hasDragIntentRef.current = false;
+    lastMoveRef.current = { x: e.clientX, y: e.clientY };
+    onDragStart?.(e);
+    state.current.startX = e.clientX;
+    state.current.startY = e.clientY;
+  };
+
+  const onPointerMove = (e: Event) => {
+    if (!(e instanceof PointerEvent)) return;
+    if (!isStarted.current) {
+      return;
+    }
+
+    const delta = {
+      x: e.clientX - state.current.startX,
+      y: e.clientY - state.current.startY,
+    };
+    const absDeltaX = Math.abs(delta.x);
+    const absDeltaY = Math.abs(delta.y);
+
+    const recentDelta = {
+      x: e.clientX - lastMoveRef.current.x,
+      y: e.clientY - lastMoveRef.current.y,
+    };
+    const absRecentDeltaX = Math.abs(recentDelta.x);
+    const absRecentDeltaY = Math.abs(recentDelta.y);
+
+    const isTouch = pointerTypeRef.current === 'touch';
+    const isHorizontalDrag = absDeltaX > absDeltaY * 1.5 && absDeltaX > 6;
+    const isVerticalDrag = absDeltaY > absDeltaX * 1.5 && absDeltaY > 6;
+
+    // Cancel drag if it was started horizontally but then moves vertically (to allow scrolling)
+    // Only apply this if drag was already started (hasDragIntentRef.current is true)
+    if (
+      isTouch &&
+      hasDragIntentRef.current &&
+      isHorizontalDrag &&
+      absRecentDeltaY > absRecentDeltaX * 2 &&
+      absRecentDeltaY > 3
+    ) {
+      hasDragIntentRef.current = false;
+      state.current.isDragging = false;
+      setIsDragging(false);
+      lastMoveRef.current = { x: e.clientX, y: e.clientY };
+      return;
+    }
+
+    // Allow dragging to start if:
+    // - Not touch (mouse/pen), OR
+    // - Horizontal drag detected, OR
+    // - Vertical drag detected (fix for mobile), OR
+    // - Drag intent already established
+    const shouldStartDrag =
+      !isTouch ||
+      isHorizontalDrag ||
+      isVerticalDrag ||
+      hasDragIntentRef.current;
+
+    if (shouldStartDrag) {
+      hasDragIntentRef.current = true;
+      e.stopPropagation();
+      e.preventDefault();
+    } else {
+      lastMoveRef.current = { x: e.clientX, y: e.clientY };
+      return;
+    }
+
+    lastMoveRef.current = { x: e.clientX, y: e.clientY };
+    state.current.isDragging = true;
+    setIsDragging(true);
+    onDrag?.(delta, e);
+  };
+
+  const onPointerEnd = (e: Event) => {
+    if (!(e instanceof PointerEvent)) return;
+    if (state.current.isDragging) onDragEnd?.(e);
+
+    isStarted.current = false;
+    state.current.isDragging = false;
+    setIsDragging(false);
+
+    dropDelta();
+  };
+
+  useEvent({
+    elem,
+    event: 'pointerdown',
+    callback: onPointerDown,
+    isActive,
+  });
+
+  useEvent({
+    event: 'pointermove',
+    callback: onPointerMove,
+    isActive,
+  });
+
+  useEvent({
+    event: ['pointerup', 'pointercancel'],
+    callback: onPointerEnd,
+    isActive,
+  });
+
+  return { isDragging };
+}

package/src/hooks/useEvent.ts

@@ -0,0 +1,73 @@
+import { RefObject, useEffect, useRef, useState } from 'react';
+
+type ElementType = RefObject<HTMLElement | null> | null;
+
+export type UseEventParams = {
+  elem?: ElementType[] | ElementType;
+  event: string | string[];
+  callback: (e: Event) => void;
+  isActive?: boolean;
+  isCapture?: boolean;
+};
+
+export default function useEvent({
+  elem,
+  event,
+  callback,
+  isActive = true,
+  isCapture = false,
+}: UseEventParams) {
+  const callbackRef = useRef(callback);
+  callbackRef.current = callback;
+
+  // Track when elem.current changes to force effect re-run
+  const [elemKey, setElemKey] = useState(0);
+  const prevElemRef = useRef<HTMLElement | null>(null);
+
+  // Watch for elem.current changes and update state to trigger main effect re-run
+  useEffect(() => {
+    const currentElem = Array.isArray(elem)
+      ? elem.find(ref => ref?.current)?.current || null
+      : elem?.current || null;
+
+    if (currentElem !== prevElemRef.current) {
+      prevElemRef.current = currentElem;
+      if (currentElem) {
+        setElemKey(prev => prev + 1);
+      }
+    }
+  });
+
+  useEffect(() => {
+    if (!isActive) return;
+
+    const handler = (e: Event) => callbackRef.current(e);
+    const events = Array.isArray(event) ? event : [event];
+
+    const targets: (Document | HTMLElement)[] = elem
+      ? Array.isArray(elem)
+        ? elem
+            .map(ref => ref?.current)
+            .filter((x): x is HTMLElement => Boolean(x))
+        : elem.current
+          ? [elem.current]
+          : []
+      : [document];
+
+    targets.forEach(target => {
+      events.forEach(eventName => {
+        target.addEventListener(eventName, handler as EventListener, {
+          capture: isCapture,
+        });
+      });
+    });
+
+    return () => {
+      targets.forEach(target => {
+        events.forEach(eventName => {
+          target.removeEventListener(eventName, handler as EventListener);
+        });
+      });
+    };
+  }, [elem, event, isActive, elemKey]);
+}

package/src/hooks/useIsMobile.ts

@@ -0,0 +1,21 @@
+import { useEffect, useState } from 'react';
+
+const MOBILE_BREAKPOINT = 768;
+
+export function useIsMobile() {
+  const [isMobile, setIsMobile] = useState<boolean | undefined>(
+    window.innerWidth < MOBILE_BREAKPOINT,
+  );
+
+  useEffect(() => {
+    const mql = window.matchMedia(`(max-width: ${MOBILE_BREAKPOINT - 1}px)`);
+    const onChange = () => {
+      setIsMobile(window.innerWidth < MOBILE_BREAKPOINT);
+    };
+    mql.addEventListener('change', onChange);
+    setIsMobile(window.innerWidth < MOBILE_BREAKPOINT);
+    return () => mql.removeEventListener('change', onChange);
+  }, []);
+
+  return !!isMobile;
+}