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

package/dist/BottomSheet/BottomSheet.d.ts

@@ -0,0 +1,95 @@
+/**
+ * @file BottomSheet.tsx
+ * @input Uses React, StyleX, theme tokens, Drawer, useSheetGestures, themeProps
+ * @output Exports BottomSheet component and BottomSheetProps
+ * @position Lab implementation; consumed by index.ts, tested by BottomSheet.test.tsx, demonstrated in Storybook
+ *
+ * A mobile touch surface that rises from the bottom edge with a grab handle
+ * and swipe-to-dismiss. Built ON TOP OF the lab Drawer's native `<dialog>`
+ * engine (`side="bottom"`) rather than forking it — Drawer owns
+ * showModal/show, the open/close slide animation, focus trap + restore,
+ * scroll lock, the Escape/scrim contract, and the LIFO overlay registry.
+ * BottomSheet layers the grab handle and the drag-to-dismiss gesture on top,
+ * inside the dialog.
+ *
+ * The gesture translate is applied to an inner sheet wrapper, not the
+ * `<dialog>` itself, so Drawer owns the open/close slide and the drag
+ * translates within it without the two transforms fighting.
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/lab/src/BottomSheet/BottomSheet.doc.mjs (props table, features, usage)
+ * - /packages/lab/src/BottomSheet/BottomSheet.test.tsx (tests for new/changed behavior)
+ * - /packages/lab/src/BottomSheet/index.ts (exports if types change)
+ * - /apps/storybook/stories/BottomSheet.stories.tsx (examples and visual coverage)
+ */
+import { type ReactNode } from 'react';
+import type { BaseProps } from '@astryxdesign/core';
+/**
+ * Height budget for each named size. `medium`/`tall` track the viewport so
+ * the sheet scales with the device; `short` is a fixed peek height. `auto`
+ * is handled separately (fits content, capped at the `tall` budget).
+ */
+declare const HEIGHT_BUDGETS: {
+    readonly short: "240px";
+    readonly medium: "50dvh";
+    readonly tall: "90dvh";
+    readonly auto: "90dvh";
+};
+export type BottomSheetHeight = keyof typeof HEIGHT_BUDGETS;
+export interface BottomSheetProps extends BaseProps<HTMLDialogElement> {
+    /** Ref forwarded to the underlying <dialog> element. */
+    ref?: React.Ref<HTMLDialogElement>;
+    /** Whether the sheet is open. Fully controlled — pair with `onOpenChange`. */
+    isOpen: boolean;
+    /**
+     * Called when the sheet opens or closes. The boolean is the requested
+     * next state (`false` on Escape, scrim click, or a swipe past the dismiss
+     * threshold). The caller owns the open state.
+     */
+    onOpenChange: (isOpen: boolean) => void;
+    /**
+     * Accessible label for the sheet (required — the sheet has no built-in
+     * heading to derive a name from).
+     */
+    label: string;
+    /** Sheet content, rendered below the grab handle in a scrollable area. */
+    children: ReactNode;
+    /**
+     * How tall the sheet is:
+     * - `'short'` — a fixed peek height
+     * - `'medium'` — half the viewport
+     * - `'tall'` — nearly the full viewport
+     * - `'auto'` — fits its content, capped at the `'tall'` budget
+     *
+     * On viewports shorter than the budget the sheet fills the available
+     * height.
+     * @default 'medium'
+     */
+    height?: BottomSheetHeight;
+    /** Test ID for the root element. */
+    'data-testid'?: string;
+}
+/**
+ * A mobile touch sheet that rises from the bottom edge, with a grab handle
+ * and swipe-to-dismiss. Built on the lab Drawer's `<dialog>` engine
+ * (`side="bottom"`): Drawer owns the open/close slide, focus trap + restore,
+ * scroll lock, and the Escape/scrim contract, while BottomSheet layers the
+ * grab handle and drag-to-dismiss on top.
+ *
+ * @example
+ * ```
+ * const [isOpen, setIsOpen] = useState(false);
+ * <BottomSheet
+ *   isOpen={isOpen}
+ *   onOpenChange={setIsOpen}
+ *   label="Filters">
+ *   <FilterControls />
+ * </BottomSheet>
+ * ```
+ */
+export declare function BottomSheet({ isOpen, onOpenChange, label, children, height, xstyle, ...props }: BottomSheetProps): import("react").JSX.Element;
+export declare namespace BottomSheet {
+    var displayName: string;
+}
+export {};
+//# sourceMappingURL=BottomSheet.d.ts.map

package/dist/BottomSheet/BottomSheet.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BottomSheet.d.ts","sourceRoot":"","sources":["../../src/BottomSheet/BottomSheet.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAC,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAErC,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,oBAAoB,CAAC;AAUlD;;;;GAIG;AACH,QAAA,MAAM,cAAc;;;;;CAKV,CAAC;AAEX,MAAM,MAAM,iBAAiB,GAAG,MAAM,OAAO,cAAc,CAAC;AAoE5D,MAAM,WAAW,gBAAiB,SAAQ,SAAS,CAAC,iBAAiB,CAAC;IACpE,wDAAwD;IACxD,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC;IAEnC,8EAA8E;IAC9E,MAAM,EAAE,OAAO,CAAC;IAEhB;;;;OAIG;IACH,YAAY,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;IAExC;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAC;IAEd,0EAA0E;IAC1E,QAAQ,EAAE,SAAS,CAAC;IAEpB;;;;;;;;;;OAUG;IACH,MAAM,CAAC,EAAE,iBAAiB,CAAC;IAE3B,oCAAoC;IACpC,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,WAAW,CAAC,EAC1B,MAAM,EACN,YAAY,EACZ,KAAK,EACL,QAAQ,EACR,MAAiB,EACjB,MAAM,EACN,GAAG,KAAK,EACT,EAAE,gBAAgB,+BAoClB;yBA5Ce,WAAW"}

package/dist/BottomSheet/BottomSheet.js

@@ -0,0 +1,150 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file BottomSheet.tsx
+ * @input Uses React, StyleX, theme tokens, Drawer, useSheetGestures, themeProps
+ * @output Exports BottomSheet component and BottomSheetProps
+ * @position Lab implementation; consumed by index.ts, tested by BottomSheet.test.tsx, demonstrated in Storybook
+ *
+ * A mobile touch surface that rises from the bottom edge with a grab handle
+ * and swipe-to-dismiss. Built ON TOP OF the lab Drawer's native `<dialog>`
+ * engine (`side="bottom"`) rather than forking it — Drawer owns
+ * showModal/show, the open/close slide animation, focus trap + restore,
+ * scroll lock, the Escape/scrim contract, and the LIFO overlay registry.
+ * BottomSheet layers the grab handle and the drag-to-dismiss gesture on top,
+ * inside the dialog.
+ *
+ * The gesture translate is applied to an inner sheet wrapper, not the
+ * `<dialog>` itself, so Drawer owns the open/close slide and the drag
+ * translates within it without the two transforms fighting.
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/lab/src/BottomSheet/BottomSheet.doc.mjs (props table, features, usage)
+ * - /packages/lab/src/BottomSheet/BottomSheet.test.tsx (tests for new/changed behavior)
+ * - /packages/lab/src/BottomSheet/index.ts (exports if types change)
+ * - /apps/storybook/stories/BottomSheet.stories.tsx (examples and visual coverage)
+ */
+import * as stylex from '@stylexjs/stylex';
+import '@astryxdesign/core/theme/tokens.stylex';
+import { colorVars, radiusVars, spacingVars } from '@astryxdesign/core/theme/tokens.stylex';
+import { mergeProps, themeProps } from '@astryxdesign/core/utils';
+import { Drawer } from "../Drawer/index.js";
+import { useSheetGestures } from "./useSheetGestures.js";
+
+/**
+ * Height budget for each named size. `medium`/`tall` track the viewport so
+ * the sheet scales with the device; `short` is a fixed peek height. `auto`
+ * is handled separately (fits content, capped at the `tall` budget).
+ */
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+const HEIGHT_BUDGETS = {
+  short: '240px',
+  medium: '50dvh',
+  tall: '90dvh',
+  auto: '90dvh'
+};
+// Sheets on wide touch devices (tablets) shouldn't stretch edge to edge;
+// cap and center them. Matches the `sm` layout breakpoint. On phones the
+// viewport is narrower than this, so the sheet stays full-width.
+const MAX_SHEET_WIDTH = 640;
+const styles = {
+  sheet: {
+    k1xSpc: "x78zum5",
+    kXwgrk: "xdt5ytf",
+    kAzted: "x2lwn1j",
+    kZKoxP: "x5yr21d",
+    kzqmXN: "xh8yej3",
+    ks0D6T: "x11gisft",
+    kUOVxO: "xvueqy4",
+    kWkggS: "x10xzikg",
+    krdFHd: "x183tx6i",
+    kfmiAY: "x663v1",
+    kVQacm: "xb3r6kr",
+    kGO01o: "x1a148e8",
+    k6sLGO: "x1so62im",
+    $$css: true
+  },
+  dialogSurface: {
+    kWkggS: "xjbqb8w",
+    kGVxlE: "x1gnnqk1",
+    kEafiO: "x972fbf",
+    $$css: true
+  },
+  autoHeight: {
+    kZKoxP: "xg7h5cd",
+    kskxy: "x1ismmbu",
+    $$css: true
+  }
+};
+/**
+ * A mobile touch sheet that rises from the bottom edge, with a grab handle
+ * and swipe-to-dismiss. Built on the lab Drawer's `<dialog>` engine
+ * (`side="bottom"`): Drawer owns the open/close slide, focus trap + restore,
+ * scroll lock, and the Escape/scrim contract, while BottomSheet layers the
+ * grab handle and drag-to-dismiss on top.
+ *
+ * @example
+ * ```
+ * const [isOpen, setIsOpen] = useState(false);
+ * <BottomSheet
+ *   isOpen={isOpen}
+ *   onOpenChange={setIsOpen}
+ *   label="Filters">
+ *   <FilterControls />
+ * </BottomSheet>
+ * ```
+ */
+export function BottomSheet({
+  isOpen,
+  onOpenChange,
+  label,
+  children,
+  height = 'medium',
+  xstyle,
+  ...props
+}) {
+  const close = () => onOpenChange(false);
+  const {
+    contentProps,
+    handleProps
+  } = useSheetGestures({
+    isOpen,
+    onDismiss: close
+  });
+  return /*#__PURE__*/_jsx(Drawer, {
+    isOpen: isOpen,
+    onClose: close,
+    side: "bottom",
+    size: HEIGHT_BUDGETS[height],
+    label: label,
+    hasScrim: true,
+    hasCloseButton: false,
+    xstyle: [styles.dialogSurface, height === 'auto' && styles.autoHeight],
+    ...props,
+    children: /*#__PURE__*/_jsxs("div", {
+      "data-astryx-sheet": "",
+      ...mergeProps(themeProps('bottom-sheet'), stylex.props(styles.sheet, xstyle), contentProps.style),
+      children: [/*#__PURE__*/_jsx("div", {
+        "data-astryx-sheet-handle": "",
+        ...{
+          className: "x2lah0s x78zum5 x6s0dn4 xl56j7k xce4md1 x5ve5x3 x1jm3nie"
+        },
+        ...handleProps,
+        "aria-hidden": "true",
+        children: /*#__PURE__*/_jsx("div", {
+          ...{
+            className: "x14qfxbe xqu0tyb xjspbzw x1m4xfpy"
+          }
+        })
+      }), /*#__PURE__*/_jsx("div", {
+        ...{
+          className: "x1iyjqo2 x2lwn1j x1odjw0f xish69e"
+        },
+        children: children
+      })]
+    })
+  });
+}
+BottomSheet.displayName = 'BottomSheet';

package/dist/BottomSheet/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @file index.ts
+ * @input BottomSheet.tsx
+ * @output Re-exports BottomSheet component and BottomSheetProps type
+ * @position Lab entry point for the BottomSheet directory
+ */
+export { BottomSheet } from './BottomSheet';
+export type { BottomSheetProps } from './BottomSheet';
+//# sourceMappingURL=index.d.ts.map

package/dist/BottomSheet/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/BottomSheet/index.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AAEH,OAAO,EAAC,WAAW,EAAC,MAAM,eAAe,CAAC;AAC1C,YAAY,EAAC,gBAAgB,EAAC,MAAM,eAAe,CAAC"}

package/dist/BottomSheet/index.js

@@ -0,0 +1,10 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file index.ts
+ * @input BottomSheet.tsx
+ * @output Re-exports BottomSheet component and BottomSheetProps type
+ * @position Lab entry point for the BottomSheet directory
+ */
+
+export { BottomSheet } from "./BottomSheet.js";

package/dist/BottomSheet/useSheetGestures.d.ts

@@ -0,0 +1,69 @@
+/**
+ * @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 { type CSSProperties, type PointerEvent as ReactPointerEvent } from 'react';
+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;
+}
+/**
+ * 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 declare function useSheetGestures({ isOpen, onDismiss, }: UseSheetGesturesOptions): UseSheetGesturesResult;
+//# sourceMappingURL=useSheetGestures.d.ts.map

package/dist/BottomSheet/useSheetGestures.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useSheetGestures.d.ts","sourceRoot":"","sources":["../../src/BottomSheet/useSheetGestures.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAML,KAAK,aAAa,EAClB,KAAK,YAAY,IAAI,iBAAiB,EACvC,MAAM,OAAO,CAAC;AAQf,MAAM,WAAW,uBAAuB;IACtC,0EAA0E;IAC1E,MAAM,EAAE,OAAO,CAAC;IAChB,4EAA4E;IAC5E,SAAS,EAAE,MAAM,IAAI,CAAC;CACvB;AAED,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,aAAa,CAAC;CACtB;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,aAAa,CAAC;IACrB,aAAa,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,CAAC;IAClD,aAAa,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,CAAC;IAClD,WAAW,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,CAAC;IAChD,eAAe,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,CAAC;CACrD;AAED,MAAM,WAAW,sBAAsB;IACrC,0EAA0E;IAC1E,YAAY,EAAE,iBAAiB,CAAC;IAChC,gEAAgE;IAChE,WAAW,EAAE,gBAAgB,CAAC;IAC9B,2EAA2E;IAC3E,UAAU,EAAE,MAAM,CAAC;IACnB,+CAA+C;IAC/C,UAAU,EAAE,OAAO,CAAC;CACrB;AASD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,gBAAgB,CAAC,EAC/B,MAAM,EACN,SAAS,GACV,EAAE,uBAAuB,GAAG,sBAAsB,CA4HlD"}

package/dist/BottomSheet/useSheetGestures.js

@@ -0,0 +1,163 @@
+// 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 } 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;
+function prefersReducedMotion() {
+  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
+}) {
+  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(null);
+
+  // Reset drag state each time the sheet re-opens.
+  useEffect(() => {
+    if (isOpen) {
+      setDragOffset(0);
+      setIsDragging(false);
+    }
+  }, [isOpen]);
+  const measureHeight = useCallback(el => {
+    const sheet = el?.closest('[data-astryx-sheet]') ?? el;
+    return sheet?.getBoundingClientRect().height ?? 0;
+  }, []);
+  const settleFromDrag = useCallback((offset, velocity, height) => {
+    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 => {
+    const target = event.currentTarget;
+    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 => {
+    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 => {
+    const state = dragStateRef.current;
+    if (!state || state.pointerId !== event.pointerId) {
+      return;
+    }
+    const target = event.currentTarget;
+    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(() => ({
+    style: {
+      transform: dragOffset !== 0 ? `translateY(${dragOffset}px)` : undefined,
+      transition: isDragging || reducedMotion ? 'none' : undefined,
+      touchAction: 'none',
+      overscrollBehavior: 'contain'
+    }
+  }), [dragOffset, isDragging, reducedMotion]);
+  const handleProps = useMemo(() => ({
+    style: {
+      touchAction: 'none',
+      cursor: 'grab'
+    },
+    onPointerDown: handlePointerDown,
+    onPointerMove: handlePointerMove,
+    onPointerUp: endDrag,
+    onPointerCancel: endDrag
+  }), [handlePointerDown, handlePointerMove, endDrag]);
+  return {
+    contentProps,
+    handleProps,
+    dragOffset,
+    isDragging
+  };
+}

package/dist/RichTextEditor/RichTextEditor.d.ts

@@ -22,6 +22,8 @@
 import { type ReactNode } from 'react';
 import type { BaseProps } from '@astryxdesign/core';
 import type { SizeValue } from '@astryxdesign/core/utils';
+import { type Transformer } from '@lexical/markdown';
+export type { Transformer } from '@lexical/markdown';
 import type { EditorState, Klass, LexicalEditor, LexicalNode } from 'lexical';
 export type RichTextEditorStatusType = 'warning' | 'error' | 'success';
 export type RichTextEditorSize = 'sm' | 'md' | 'lg';
@@ -31,6 +33,36 @@ export interface RichTextEditorStatus {
     /** Optional message to display below the editor. */
     message?: string;
 }
+/**
+ * Imperative handle exposed via `ref`. Lets callers focus, clear, and read the
+ * editor without wiring a custom plugin. Available after mount.
+ */
+export interface RichTextEditorRef {
+    /**
+     * Move focus into the editor's editable surface. No-op when the editor is
+     * read-only or disabled.
+     */
+    focus: () => void;
+    /**
+     * Remove all content, resetting the editor to a single empty paragraph.
+     * No-op when the editor is read-only or disabled.
+     */
+    clear: () => void;
+    /** Read the current `EditorState`. Serialize with `.toJSON()` to persist. */
+    getEditorState: () => EditorState;
+    /**
+     * Serialize the current content to a Markdown string, using the same
+     * `transformers` the editor is configured with (so custom transformers
+     * layered in via the `transformers` prop are honored). Equivalent to
+     * `$convertToMarkdownString` run in a read context.
+     */
+    getMarkdown: () => string;
+    /**
+     * Access the underlying `LexicalEditor` instance for advanced use cases
+     * (custom commands, listeners, node transforms).
+     */
+    getEditor: () => LexicalEditor;
+}
 export interface RichTextEditorProps extends Omit<BaseProps, 'onChange' | 'defaultValue'> {
     /** Label text for the editor (always rendered for accessibility). */
     label: string;
@@ -106,12 +138,39 @@ export interface RichTextEditorProps extends Omit<BaseProps, 'onChange' | 'defau
     plugins?: ReactNode;
     /**
      * Whether to enable Markdown shortcut typing (e.g. `# ` for a heading,
-     * `- ` for a list). Uses the default `@lexical/markdown` transformers.
+     * `- ` for a list). Uses the `transformers` prop (defaults to the standard
+     * `@lexical/markdown` transformers).
      * @default true
      */
     hasMarkdownShortcuts?: boolean;
+    /**
+     * Markdown transformers — the single source of truth for markdown behaviour.
+     * Defaults to the standard `@lexical/markdown` `TRANSFORMERS`.
+     *
+     * The same array drives all three markdown operations in Lexical (see the
+     * lexical-playground reference, where one `PLAYGROUND_TRANSFORMERS` array
+     * feeds each):
+     *  - shortcut typing        — `registerMarkdownShortcuts` (wired here today)
+     *  - markdown -> state       — `$convertFromMarkdownString` (future import API)
+     *  - state -> markdown       — `$convertToMarkdownString` (future `getMarkdown`)
+     *
+     * Pass a custom array to support additional node types (e.g. custom
+     * transformers layered in via the `nodes` extension point) consistently
+     * across all three. Shortcut typing is only applied when
+     * `hasMarkdownShortcuts` is true; the array is still the intended input for
+     * the serialization APIs added in later phases.
+     */
+    transformers?: ReadonlyArray<Transformer>;
     /** Whether to automatically focus the editor on mount. @default false */
     hasAutoFocus?: boolean;
+    /**
+     * Maximum number of characters. When set, a character counter
+     * (current/max) is displayed below the editor. Like TextArea, this does
+     * NOT enforce the limit natively — the counter shows error styling when the
+     * plain-text length exceeds the limit. Count is the editor's plain-text
+     * content length.
+     */
+    maxLength?: number;
     /**
      * The Lexical composer namespace, used for editor identity.
      * @default 'astryx-editor'
@@ -128,18 +187,20 @@ export interface RichTextEditorProps extends Omit<BaseProps, 'onChange' | 'defau
  * `plugins` to layer richer behaviour (toolbars, mentions, hover cards) on top
  * without forking.
  *
+ * The forwarded `RichTextEditorRef` exposes imperative `focus()` and `clear()`
+ * methods for callers that manage the editor from outside.
+ *
  * @example
  * ```
- * import {RichTextEditor} from '@astryxdesign/lab';
+ * import {RichTextEditor, type RichTextEditorRef} from '@astryxdesign/lab';
+ * const ref = useRef<RichTextEditorRef>(null);
  * <RichTextEditor
+ *   ref={ref}
  *   label="Notes"
  *   placeholder="Write something..."
  *   onChange={state => save(JSON.stringify(state.toJSON()))}
  * />
  * ```
  */
-export declare function RichTextEditor({ label, isLabelHidden, description, isOptional, isRequired, defaultValue, onChange, placeholder, isReadOnly, isDisabled, status, width, labelTooltip, size: sizeProp, nodes, plugins, hasMarkdownShortcuts, hasAutoFocus, namespace, xstyle, className, style, ...rest }: RichTextEditorProps): import("react").JSX.Element;
-export declare namespace RichTextEditor {
-    var displayName: string;
-}
+export declare const RichTextEditor: import("react").ForwardRefExoticComponent<RichTextEditorProps & import("react").RefAttributes<RichTextEditorRef>>;
 //# sourceMappingURL=RichTextEditor.d.ts.map

package/dist/RichTextEditor/RichTextEditor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"RichTextEditor.d.ts","sourceRoot":"","sources":["../../src/RichTextEditor/RichTextEditor.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAA2B,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAgB/D,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,oBAAoB,CAAC;AAClD,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,0BAA0B,CAAC;AAuBxD,OAAO,KAAK,EACV,WAAW,EACX,KAAK,EACL,aAAa,EACb,WAAW,EAEZ,MAAM,SAAS,CAAC;AAiEjB,MAAM,MAAM,wBAAwB,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS,CAAC;AAEvE,MAAM,MAAM,kBAAkB,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;AAEpD,MAAM,WAAW,oBAAoB;IACnC,qCAAqC;IACrC,IAAI,EAAE,wBAAwB,CAAC;IAC/B,oDAAoD;IACpD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,mBAAoB,SAAQ,IAAI,CAC/C,SAAS,EACT,UAAU,GAAG,cAAc,CAC5B;IACC,qEAAqE;IACrE,KAAK,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,+DAA+D;IAC/D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,CAAC,WAAW,EAAE,WAAW,EAAE,MAAM,EAAE,aAAa,KAAK,IAAI,CAAC;IACrE,uDAAuD;IACvD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;OAGG;IACH,MAAM,CAAC,EAAE,oBAAoB,CAAC;IAC9B;;;OAGG;IACH,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,uEAAuE;IACvE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,IAAI,CAAC,EAAE,kBAAkB,CAAC;IAC1B;;;;OAIG;IACH,KAAK,CAAC,EAAE,aAAa,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC,CAAC;IAC1C;;;;OAIG;IACH,OAAO,CAAC,EAAE,SAAS,CAAC;IACpB;;;;OAIG;IACH,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,yEAAyE;IACzE,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,cAAc,CAAC,EAC7B,KAAK,EACL,aAAqB,EACrB,WAAW,EACX,UAAkB,EAClB,UAAkB,EAClB,YAAY,EACZ,QAAQ,EACR,WAAW,EACX,UAAkB,EAClB,UAAkB,EAClB,MAAM,EACN,KAAK,EACL,YAAY,EACZ,IAAI,EAAE,QAAQ,EACd,KAAK,EACL,OAAO,EACP,oBAA2B,EAC3B,YAAoB,EACpB,SAA2B,EAC3B,MAAM,EACN,SAAS,EACT,KAAK,EACL,GAAG,IAAI,EACR,EAAE,mBAAmB,+BAkHrB;yBA1Ie,cAAc"}
+{"version":3,"file":"RichTextEditor.d.ts","sourceRoot":"","sources":["../../src/RichTextEditor/RichTextEditor.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAQL,KAAK,SAAS,EAEf,MAAM,OAAO,CAAC;AAgBf,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,oBAAoB,CAAC;AAElD,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,0BAA0B,CAAC;AAkBxD,OAAO,EAGL,KAAK,WAAW,EACjB,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EAAC,WAAW,EAAC,MAAM,mBAAmB,CAAC;AAKnD,OAAO,KAAK,EACV,WAAW,EACX,KAAK,EACL,aAAa,EACb,WAAW,EAEZ,MAAM,SAAS,CAAC;AAoHjB,MAAM,MAAM,wBAAwB,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS,CAAC;AAEvE,MAAM,MAAM,kBAAkB,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;AAEpD,MAAM,WAAW,oBAAoB;IACnC,qCAAqC;IACrC,IAAI,EAAE,wBAAwB,CAAC;IAC/B,oDAAoD;IACpD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB;;;OAGG;IACH,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,6EAA6E;IAC7E,cAAc,EAAE,MAAM,WAAW,CAAC;IAClC;;;;;OAKG;IACH,WAAW,EAAE,MAAM,MAAM,CAAC;IAC1B;;;OAGG;IACH,SAAS,EAAE,MAAM,aAAa,CAAC;CAChC;AAED,MAAM,WAAW,mBAAoB,SAAQ,IAAI,CAC/C,SAAS,EACT,UAAU,GAAG,cAAc,CAC5B;IACC,qEAAqE;IACrE,KAAK,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,+DAA+D;IAC/D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,CAAC,WAAW,EAAE,WAAW,EAAE,MAAM,EAAE,aAAa,KAAK,IAAI,CAAC;IACrE,uDAAuD;IACvD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;OAGG;IACH,MAAM,CAAC,EAAE,oBAAoB,CAAC;IAC9B;;;OAGG;IACH,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,uEAAuE;IACvE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,IAAI,CAAC,EAAE,kBAAkB,CAAC;IAC1B;;;;OAIG;IACH,KAAK,CAAC,EAAE,aAAa,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC,CAAC;IAC1C;;;;OAIG;IACH,OAAO,CAAC,EAAE,SAAS,CAAC;IACpB;;;;;OAKG;IACH,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B;;;;;;;;;;;;;;;;OAgBG;IACH,YAAY,CAAC,EAAE,aAAa,CAAC,WAAW,CAAC,CAAC;IAC1C,yEAAyE;IACzE,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,cAAc,mHAuLzB,CAAC"}