@astryxdesign/lab 0.1.9-canary.d2d84f8 → 0.1.9-canary.e00a241

package/src/BottomSheet/useSheetGestures.ts

@@ -0,0 +1,226 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file useSheetGestures.ts
+ * @input Uses React (useCallback, useEffect, useMemo, useRef, useState)
+ * @output Exports useSheetGestures hook and its option/result types
+ * @position Internal to BottomSheet; not exported from the lab entry point
+ *
+ * Drag-to-dismiss machinery for the bottom sheet. Tracks a pointer drag
+ * down the block axis, translates the sliding surface live, and on release
+ * either dismisses (past a distance or velocity threshold) or springs back
+ * to fully open. Pointer-events based so one code path covers mouse + touch.
+ *
+ * Kept private to BottomSheet: the behavior is sheet-specific (a dismiss
+ * edge on a bottom-anchored surface). It is not a general primitive and is
+ * intentionally not exported.
+ *
+ * SSR-safe: no window/document access at module scope; all measurement
+ * happens inside handlers. Respects prefers-reduced-motion by skipping the
+ * settle transition.
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/lab/src/BottomSheet/useSheetGestures.doc.mjs
+ * - /packages/lab/src/BottomSheet/useSheetGestures.test.ts
+ */
+
+import {
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  type CSSProperties,
+  type PointerEvent as ReactPointerEvent,
+} from 'react';
+
+// Fraction of the measured sheet height a drag must cross (with low
+// velocity) before release dismisses instead of springing back.
+const DISMISS_DISTANCE_RATIO = 0.25;
+// A quick flick past this speed (px/ms) dismisses regardless of distance.
+const DISMISS_VELOCITY = 0.5;
+
+export interface UseSheetGesturesOptions {
+  /** Whether the owning sheet is open. Drag state resets when it closes. */
+  isOpen: boolean;
+  /** Called when a drag crosses the dismiss threshold (distance or flick). */
+  onDismiss: () => void;
+}
+
+export interface SheetContentProps {
+  style: CSSProperties;
+}
+
+export interface SheetHandleProps {
+  style: CSSProperties;
+  onPointerDown: (event: ReactPointerEvent) => void;
+  onPointerMove: (event: ReactPointerEvent) => void;
+  onPointerUp: (event: ReactPointerEvent) => void;
+  onPointerCancel: (event: ReactPointerEvent) => void;
+}
+
+export interface UseSheetGesturesResult {
+  /** Spread on the sliding surface: live translate + touch-action guard. */
+  contentProps: SheetContentProps;
+  /** Spread on the grab-handle element: pointer drag handlers. */
+  handleProps: SheetHandleProps;
+  /** Current live drag offset in px (positive = dragged toward the edge). */
+  dragOffset: number;
+  /** Whether a drag is currently in progress. */
+  isDragging: boolean;
+}
+
+function prefersReducedMotion(): boolean {
+  if (typeof window === 'undefined' || !window.matchMedia) {
+    return false;
+  }
+  return window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+}
+
+/**
+ * Drag-to-dismiss machinery for the bottom sheet. Returns props to spread on
+ * the grab handle and the sliding surface, plus live drag state for callers
+ * that want to drive their own animation.
+ *
+ * @example
+ * ```
+ * const {contentProps, handleProps} = useSheetGestures({
+ *   isOpen,
+ *   onDismiss: () => onOpenChange(false),
+ * });
+ * <div {...contentProps}>
+ *   <div {...handleProps} />
+ *   {children}
+ * </div>
+ * ```
+ */
+export function useSheetGestures({
+  isOpen,
+  onDismiss,
+}: UseSheetGesturesOptions): UseSheetGesturesResult {
+  const [dragOffset, setDragOffset] = useState(0);
+  const [isDragging, setIsDragging] = useState(false);
+
+  // Latest callback ref so pointer handlers stay stable across renders.
+  const onDismissRef = useRef(onDismiss);
+  useEffect(() => {
+    onDismissRef.current = onDismiss;
+  });
+
+  // Live drag bookkeeping (refs so pointermove doesn't churn renders).
+  const dragStateRef = useRef<{
+    pointerId: number;
+    startCoord: number;
+    lastCoord: number;
+    lastTime: number;
+    velocity: number;
+    height: number;
+  } | null>(null);
+
+  // Reset drag state each time the sheet re-opens.
+  useEffect(() => {
+    if (isOpen) {
+      setDragOffset(0);
+      setIsDragging(false);
+    }
+  }, [isOpen]);
+
+  const measureHeight = useCallback((el: HTMLElement | null): number => {
+    const sheet = el?.closest<HTMLElement>('[data-astryx-sheet]') ?? el;
+    return sheet?.getBoundingClientRect().height ?? 0;
+  }, []);
+
+  const settleFromDrag = useCallback(
+    (offset: number, velocity: number, height: number) => {
+      const dismiss =
+        offset > height * DISMISS_DISTANCE_RATIO || velocity > DISMISS_VELOCITY;
+      if (dismiss) {
+        onDismissRef.current();
+        return;
+      }
+      // Below threshold: spring back to fully open.
+      setDragOffset(0);
+    },
+    [],
+  );
+
+  const handlePointerDown = useCallback(
+    (event: ReactPointerEvent) => {
+      const target = event.currentTarget as HTMLElement;
+      target.setPointerCapture?.(event.pointerId);
+      dragStateRef.current = {
+        pointerId: event.pointerId,
+        startCoord: event.clientY,
+        lastCoord: event.clientY,
+        lastTime: event.timeStamp,
+        velocity: 0,
+        height: measureHeight(target),
+      };
+      setIsDragging(true);
+    },
+    [measureHeight],
+  );
+
+  const handlePointerMove = useCallback((event: ReactPointerEvent) => {
+    const state = dragStateRef.current;
+    if (!state || state.pointerId !== event.pointerId) {
+      return;
+    }
+    // Dragging DOWN (increasing Y) collapses/dismisses. Only allow drag in
+    // the closing direction past the fully-open position (no overscroll).
+    const delta = event.clientY - state.startCoord;
+    const dt = event.timeStamp - state.lastTime;
+    if (dt > 0) {
+      state.velocity = (event.clientY - state.lastCoord) / dt;
+      state.lastCoord = event.clientY;
+      state.lastTime = event.timeStamp;
+    }
+    setDragOffset(Math.max(0, delta));
+  }, []);
+
+  const endDrag = useCallback(
+    (event: ReactPointerEvent) => {
+      const state = dragStateRef.current;
+      if (!state || state.pointerId !== event.pointerId) {
+        return;
+      }
+      const target = event.currentTarget as HTMLElement;
+      target.releasePointerCapture?.(event.pointerId);
+      const offset = Math.max(0, event.clientY - state.startCoord);
+      dragStateRef.current = null;
+      setIsDragging(false);
+      settleFromDrag(offset, state.velocity, state.height || 1);
+    },
+    [settleFromDrag],
+  );
+
+  // Reduced motion skips the settle transition (snaps instantly).
+  const reducedMotion = useMemo(prefersReducedMotion, [isOpen]);
+
+  const contentProps = useMemo<SheetContentProps>(
+    () => ({
+      style: {
+        transform: dragOffset !== 0 ? `translateY(${dragOffset}px)` : undefined,
+        transition: isDragging || reducedMotion ? 'none' : undefined,
+        touchAction: 'none',
+        overscrollBehavior: 'contain',
+      },
+    }),
+    [dragOffset, isDragging, reducedMotion],
+  );
+
+  const handleProps = useMemo<SheetHandleProps>(
+    () => ({
+      style: {touchAction: 'none', cursor: 'grab'},
+      onPointerDown: handlePointerDown,
+      onPointerMove: handlePointerMove,
+      onPointerUp: endDrag,
+      onPointerCancel: endDrag,
+    }),
+    [handlePointerDown, handlePointerMove, endDrag],
+  );
+
+  return {contentProps, handleProps, dragOffset, isDragging};
+}

package/src/ChatReasoning/ChatReasoning.doc.mjs

@@ -7,10 +7,57 @@ export const docs = {
   displayName: 'Chat Reasoning',
   group: 'Chat',
   category: 'Chat',
+  keywords: ['reasoning', 'thinking', 'thought', 'chain-of-thought', 'chat', 'llm', 'ai'],
 
   usage: {
-    description: '',
+    description:
+      'Compact collapsible container for displaying model reasoning or chain-of-thought details. Shows a single-line summary when collapsed and expands to reveal full reasoning text.',
   },
 
-  props: [],
+  props: [
+    {
+      name: 'children',
+      type: 'ReactNode',
+      description: 'Reasoning content string or custom ReactNode.',
+      required: true,
+    },
+    {
+      name: 'label',
+      type: 'string',
+      description: 'Header label displayed in the trigger line.',
+      default: "'Thinking'",
+    },
+    {
+      name: 'duration',
+      type: 'string',
+      description: 'Duration string shown next to the label (e.g. "12s").',
+    },
+    {
+      name: 'isStreaming',
+      type: 'boolean',
+      description: 'Whether reasoning content is actively streaming. Displays animated shimmer effect.',
+      default: 'false',
+    },
+    {
+      name: 'isExpanded',
+      type: 'boolean',
+      description: 'Controlled expanded state.',
+    },
+    {
+      name: 'defaultIsExpanded',
+      type: 'boolean',
+      description: 'Default expanded state for uncontrolled usage.',
+      default: 'false',
+    },
+    {
+      name: 'onExpandedChange',
+      type: '(isExpanded: boolean) => void',
+      description: 'Callback fired when the expanded state changes.',
+    },
+    {
+      name: 'xstyle',
+      type: 'StyleXStyles',
+      description: 'StyleX styles for layout customization.',
+    },
+  ],
 };

package/src/CodeEditor/CodeEditor.doc.mjs

@@ -7,10 +7,75 @@ export const docs = {
   displayName: 'Code Editor',
   group: 'CodeEditor',
   category: 'Data Input',
+  keywords: ['code', 'editor', 'syntax', 'highlight', 'input', 'textarea'],
 
   usage: {
-    description: '',
+    description:
+      'Editable code component with real-time syntax highlighting using the CSS Custom Highlight API. Supports line numbers, read-only state, placeholder text, and custom tokenizers.',
   },
 
-  props: [],
+  props: [
+    {
+      name: 'value',
+      type: 'string',
+      description: 'Controlled string value for the editor.',
+      required: true,
+    },
+    {
+      name: 'onChange',
+      type: '(value: string) => void',
+      description: 'Callback fired when the code content changes.',
+      required: true,
+    },
+    {
+      name: 'label',
+      type: 'string',
+      description: 'Accessible label for the editable region (aria-label).',
+      required: true,
+    },
+    {
+      name: 'language',
+      type: 'string',
+      description: 'Programming language for syntax highlighting.',
+      default: "'plaintext'",
+    },
+    {
+      name: 'hasLineNumbers',
+      type: 'boolean',
+      description: 'Display line number gutter on the left.',
+      default: 'false',
+    },
+    {
+      name: 'isReadOnly',
+      type: 'boolean',
+      description: 'Renders the editor in a read-only state.',
+      default: 'false',
+    },
+    {
+      name: 'placeholder',
+      type: 'string',
+      description: 'Placeholder text displayed when value is empty.',
+    },
+    {
+      name: 'maxHeight',
+      type: 'number | string',
+      description: 'Maximum container height before internal scrolling.',
+    },
+    {
+      name: 'size',
+      type: "'sm' | 'md'",
+      description: 'Font size variant for the code text.',
+      default: "'md'",
+    },
+    {
+      name: 'tokenizer',
+      type: '(code: string, language: string) => TokenLine[]',
+      description: 'Custom tokenizer function override for language parsing.',
+    },
+    {
+      name: 'xstyle',
+      type: 'StyleXStyles',
+      description: 'StyleX styles for layout customization.',
+    },
+  ],
 };

package/src/LogStream/LogStream.doc.mjs

@@ -7,11 +7,62 @@ export const docs = {
   displayName: 'Log Stream',
   group: 'LogStream',
   category: 'Content',
+  keywords: ['log', 'stream', 'terminal', 'console', 'output', 'logs', 'tail'],
 
   usage: {
     description:
-      'Experimental streaming log viewer: mono grid rows (timestamp | level | source | message) with token-derived level accents, expandable per-row detail panels, follow-scroll live tailing with a "Jump to latest" affordance, and an always-dark terminal variant. Appended rows fade in via @starting-style (instant under prefers-reduced-motion). No virtualization; window streams beyond a few thousand rows in the caller.',
+      'Experimental streaming log viewer: mono grid rows (timestamp | level | source | message) with token-derived level accents, expandable per-row detail panels, follow-scroll live tailing with a "Jump to latest" affordance, and an always-dark terminal variant. Appended rows fade in via @starting-style.',
   },
 
-  props: [],
+  props: [
+    {
+      name: 'entries',
+      type: 'LogEntry[]',
+      description: 'Array of log entry objects to render.',
+      required: true,
+    },
+    {
+      name: 'variant',
+      type: "'default' | 'terminal'",
+      description: "Visual variant style: 'default' uses theme surface background, 'terminal' uses fixed dark background.",
+      default: "'default'",
+    },
+    {
+      name: 'isFollowing',
+      type: 'boolean',
+      description: 'Controlled follow-pinning state to auto-scroll to the newest entry.',
+    },
+    {
+      name: 'onFollowChange',
+      type: '(following: boolean) => void',
+      description: 'Callback fired when follow-pinning state changes.',
+    },
+    {
+      name: 'maxHeight',
+      type: 'number | string',
+      description: 'Maximum container height before vertical scrolling.',
+    },
+    {
+      name: 'hasTimestamps',
+      type: 'boolean',
+      description: 'Show or hide the timestamp column.',
+      default: 'true',
+    },
+    {
+      name: 'label',
+      type: 'string',
+      description: 'Accessible label for the log region.',
+      default: "'Log stream'",
+    },
+    {
+      name: 'renderEntry',
+      type: '(entry: LogEntry) => ReactNode',
+      description: 'Custom render function for replacing individual row layout.',
+    },
+    {
+      name: 'xstyle',
+      type: 'StyleXStyles',
+      description: 'StyleX styles for layout customization.',
+    },
+  ],
 };

package/src/RichTextEditor/RichTextEditor.doc.mjs

@@ -93,15 +93,28 @@ export const docs = {
       name: 'hasMarkdownShortcuts',
       type: 'boolean',
       description:
-        'Enable Markdown shortcut typing (e.g. "# " for a heading). Uses default @lexical/markdown transformers.',
+        'Enable Markdown shortcut typing (e.g. "# " for a heading). Uses the transformers prop (defaults to the standard @lexical/markdown transformers).',
       default: 'true',
     },
+    {
+      name: 'transformers',
+      type: 'ReadonlyArray<Transformer>',
+      description:
+        'Markdown transformers: the single source of truth for markdown behaviour. Defaults to the standard @lexical/markdown TRANSFORMERS. In Lexical the same array drives all three markdown operations (shortcut typing, markdown->state import, state->markdown export); this prop wires shortcut typing today and is the intended input for the serialization APIs added in later phases. Pass a custom array to support additional node types (e.g. transformers layered in via the nodes extension point) consistently across all three. Shortcut typing is only applied when hasMarkdownShortcuts is true.',
+      default: 'TRANSFORMERS',
+    },
     {
       name: 'hasAutoFocus',
       type: 'boolean',
       description: 'Automatically focus the editor on mount.',
       default: 'false',
     },
+    {
+      name: 'maxLength',
+      type: 'number',
+      description:
+        'Maximum number of characters. When set, a character counter (current/max) is displayed below the editor. Like TextArea, does not enforce the limit natively; the counter shows error styling when the plain-text length exceeds the limit.',
+    },
     {
       name: 'width',
       type: 'number | string',
@@ -137,6 +150,11 @@ export const docs = {
         description:
           'Register custom node types via the nodes prop on BOTH the editor and the RichTextView so serialized content round-trips.',
       },
+      {
+        guidance: true,
+        description:
+          'Use a ref (RichTextEditorRef) to imperatively focus(), clear(), read the state via getEditorState(), serialize to Markdown via getMarkdown(), or reach the LexicalEditor via getEditor(). The handle is available after mount. getMarkdown() uses the same transformers prop the editor is configured with. focus() and clear() are no-ops when the editor is read-only or disabled, and clear() resets to a single empty paragraph.',
+      },
       {
         guidance: false,
         description: