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

package/dist/RichTextEditor/RichTextEditor.js

@@ -23,12 +23,13 @@
  * Component Specification Protocol. `lexical` and `@lexical/*` are OPTIONAL peer
  * dependencies — install them to use this component.
  */
-import { useEffect, useId, useRef } from 'react';
+import { useEffect, useId, useImperativeHandle, useMemo, useRef, useState, forwardRef } from 'react';
 import * as stylex from '@stylexjs/stylex';
 import '@astryxdesign/core/theme/tokens.stylex';
 import { colorVars, spacingVars, typographyVars, typeScaleVars } from '@astryxdesign/core/theme/tokens.stylex';
 import { sharedEditorTheme } from "./editorTheme.js";
 import { Field, inputWrapperStyles, inputStatusBorderStyles, inputStatusHoverShadowStyles, inputStatusFocusWithinStyles } from '@astryxdesign/core/Field';
+import { VisuallyHidden } from '@astryxdesign/core/VisuallyHidden';
 import { useSize } from '@astryxdesign/core/SizeContext';
 import { themeProps } from '@astryxdesign/core/utils';
 import { LexicalComposer } from '@lexical/react/LexicalComposer';
@@ -42,12 +43,43 @@ import { LinkPlugin } from '@lexical/react/LexicalLinkPlugin';
 import { TabIndentationPlugin } from '@lexical/react/LexicalTabIndentationPlugin';
 import { MarkdownShortcutPlugin } from '@lexical/react/LexicalMarkdownShortcutPlugin';
 import { OnChangePlugin } from '@lexical/react/LexicalOnChangePlugin';
-import { TRANSFORMERS } from '@lexical/markdown';
+import { TRANSFORMERS, $convertToMarkdownString } from '@lexical/markdown';
 import { ListNode, ListItemNode } from '@lexical/list';
 import { HeadingNode, QuoteNode } from '@lexical/rich-text';
 import { LinkNode, AutoLinkNode } from '@lexical/link';
 import { CodeNode, CodeHighlightNode } from '@lexical/code';
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * Serialized state for an empty editor: a root containing a single empty
+ * paragraph. Used by the imperative `clear()` handle.
+ *
+ * We deliberately reset the editor via `editor.setEditorState(...)` rather than
+ * an `editor.update(() => { $getRoot()... })` callback, because `$getRoot` /
+ * `$createParagraphNode` are *runtime value* imports from the top-level
+ * `lexical` package. In the sandbox's Next build a top-level `lexical` value
+ * import forces Babel to transpile lexical's raw `src/*.ts` (which uses
+ * `declare` class fields) and fails the build. `parseEditorState` /
+ * `setEditorState` are methods on the editor instance, so no top-level
+ * `lexical` value import is needed. Setting a fresh state still notifies update
+ * listeners, so `onChange` fires.
+ */
+const EMPTY_EDITOR_STATE_JSON = JSON.stringify({
+  root: {
+    children: [{
+      children: [],
+      direction: null,
+      format: '',
+      indent: 0,
+      type: 'paragraph',
+      version: 1
+    }],
+    direction: null,
+    format: '',
+    indent: 0,
+    type: 'root',
+    version: 1
+  }
+});
 const styles = {
   wrapper: {
     kXwgrk: "xdt5ytf",
@@ -76,6 +108,18 @@ const sizeStyles = {
 
 /** The default OSS node set registered with the editor. */
 const DEFAULT_NODES = [HeadingNode, QuoteNode, ListNode, ListItemNode, LinkNode, AutoLinkNode, CodeNode, CodeHighlightNode];
+
+/**
+ * Fraction of `maxLength` at which the character counter begins announcing
+ * remaining/over-limit characters to screen readers. Matches TextArea.
+ */
+const COUNTER_WARNING_THRESHOLD = 0.8;
+
+/**
+ * Imperative handle exposed via `ref`. Lets callers focus, clear, and read the
+ * editor without wiring a custom plugin. Available after mount.
+ */
+
 /**
  * A WYSIWYG rich-text editor built on Lexical, styled with Astryx design
  * tokens. Experimental — ships from `@astryxdesign/lab` (canary). `lexical` and
@@ -86,17 +130,22 @@ const DEFAULT_NODES = [HeadingNode, QuoteNode, ListNode, ListItemNode, LinkNode,
  * `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 function RichTextEditor({
+export const RichTextEditor = /*#__PURE__*/forwardRef(function RichTextEditor({
   label,
   isLabelHidden = false,
   description,
@@ -114,18 +163,25 @@ export function RichTextEditor({
   nodes,
   plugins,
   hasMarkdownShortcuts = true,
+  transformers = TRANSFORMERS,
   hasAutoFocus = false,
+  maxLength,
   namespace = 'astryx-editor',
   xstyle,
   className,
   style,
   ...rest
-}) {
+}, ref) {
   const size = useSize(sizeProp, 'md');
   const id = useId();
   const descriptionID = useId();
   const statusMessageID = useId();
   const placeholderID = useId();
+  const counterID = useId();
+
+  // Plain-text character count, tracked from inside the composer via
+  // CharCountPlugin. Only used when maxLength is set.
+  const [charCount, setCharCount] = useState(0);
 
   // Theme is stable per render; build once.
   const themeRef = useRef(null);
@@ -133,6 +189,12 @@ export function RichTextEditor({
     themeRef.current = sharedEditorTheme();
   }
   const editable = !isReadOnly && !isDisabled;
+
+  // Stabilize the transformers array so MarkdownShortcutPlugin doesn't
+  // re-register on every render. `[...transformers]` would allocate a new
+  // array each time; memoize on the prop identity instead. (React Compiler
+  // isn't running the transform in this repo, so this isn't auto-memoized.)
+  const markdownTransformers = useMemo(() => [...transformers], [transformers]);
   const initialConfig = {
     namespace,
     theme: themeRef.current,
@@ -144,8 +206,8 @@ export function RichTextEditor({
       throw error;
     }
   };
-  const ariaDescribedBy = [description ? descriptionID : null, status?.message ? statusMessageID : null, placeholder ? placeholderID : null].filter(Boolean).join(' ') || undefined;
-  return /*#__PURE__*/_jsx(Field, {
+  const ariaDescribedBy = [description ? descriptionID : null, status?.message ? statusMessageID : null, placeholder ? placeholderID : null, maxLength != null ? counterID : null].filter(Boolean).join(' ') || undefined;
+  return /*#__PURE__*/_jsxs(Field, {
     label: label,
     isLabelHidden: isLabelHidden,
     description: description,
@@ -161,7 +223,7 @@ export function RichTextEditor({
     } : undefined,
     labelTooltip: labelTooltip,
     width: width,
-    children: /*#__PURE__*/_jsx("div", {
+    children: [/*#__PURE__*/_jsx("div", {
       ...themeProps('rich-text-editor', {
         size,
         status: status?.type ?? null
@@ -189,17 +251,37 @@ export function RichTextEditor({
             placeholder: null,
             ErrorBoundary: LexicalErrorBoundary
           }), /*#__PURE__*/_jsx(HistoryPlugin, {}), /*#__PURE__*/_jsx(ListPlugin, {}), /*#__PURE__*/_jsx(LinkPlugin, {}), /*#__PURE__*/_jsx(TabIndentationPlugin, {}), hasMarkdownShortcuts && /*#__PURE__*/_jsx(MarkdownShortcutPlugin, {
-            transformers: TRANSFORMERS
+            transformers: markdownTransformers
           }), hasAutoFocus && /*#__PURE__*/_jsx(AutoFocusOnMount, {}), onChange && /*#__PURE__*/_jsx(OnChangePlugin, {
             onChange: onChange,
             ignoreHistoryMergeTagChange: true,
             ignoreSelectionChange: true
-          }), plugins]
+          }), plugins, /*#__PURE__*/_jsx(EditorRefBridge, {
+            editorRef: ref,
+            editable: editable,
+            transformers: markdownTransformers
+          }), maxLength != null && /*#__PURE__*/_jsx(CharCountPlugin, {
+            onCountChange: setCharCount
+          })]
         })
       })
-    })
+    }), maxLength != null && /*#__PURE__*/_jsxs("div", {
+      id: counterID,
+      ...{
+        0: {
+          className: "x78zum5 x13a6bvl xcsaf9d x9ynric x141an7d xv1l7n4"
+        },
+        1: {
+          className: "x78zum5 x13a6bvl xcsaf9d x9ynric x141an7d xjt36v0"
+        }
+      }[!!(charCount > maxLength) << 0],
+      children: [charCount, "/", maxLength, /*#__PURE__*/_jsx(VisuallyHidden, {
+        "aria-live": "polite",
+        children: charCount >= maxLength * COUNTER_WARNING_THRESHOLD ? charCount > maxLength ? `${charCount - maxLength} characters over limit` : `${maxLength - charCount} characters remaining` : ''
+      })]
+    })]
   });
-}
+});
 RichTextEditor.displayName = 'RichTextEditor';
 
 /**
@@ -214,6 +296,77 @@ function AutoFocusOnMount() {
   return null;
 }
 
+/**
+ * Wires the imperative `RichTextEditorRef` handle. Split into its own plugin so
+ * it runs inside the composer context and can reach the `LexicalEditor` via
+ * `useLexicalComposerContext()`. Renders nothing.
+ *
+ * `focus()` and `clear()` are gated on `editable` so a read-only or disabled
+ * editor cannot be mutated or focused through the imperative handle — matching
+ * the behaviour of the editable surface itself.
+ */
+function EditorRefBridge({
+  editorRef,
+  editable,
+  transformers
+}) {
+  const [editor] = useLexicalComposerContext();
+  useImperativeHandle(editorRef, () => ({
+    focus: () => {
+      if (!editable) {
+        return;
+      }
+      editor.focus();
+    },
+    clear: () => {
+      if (!editable) {
+        return;
+      }
+      // Reset to a single empty paragraph via a fresh EditorState. Uses the
+      // editor instance's own parse/set methods so we avoid a top-level
+      // `lexical` value import (see EMPTY_EDITOR_STATE_JSON). This still
+      // notifies update listeners, so `onChange` fires.
+      editor.setEditorState(editor.parseEditorState(EMPTY_EDITOR_STATE_JSON));
+    },
+    getEditorState: () => editor.getEditorState(),
+    getMarkdown: () =>
+    // $convertToMarkdownString must run inside a read context. Honors the
+    // same transformers the editor uses for shortcuts, so custom
+    // transformers round-trip to Markdown. `@lexical/markdown` is a
+    // subpackage (built dist) — safe, unlike a top-level `lexical` import.
+    editor.getEditorState().read(() => $convertToMarkdownString(transformers)),
+    getEditor: () => editor
+  }), [editor, editable, transformers]);
+  return null;
+}
+
+/**
+ * Tracks the editor's plain-text length and reports it to the host component.
+ * Split into its own plugin so it runs inside the composer context and can
+ * read the editor state via `useLexicalComposerContext()`. Renders nothing.
+ */
+function CharCountPlugin({
+  onCountChange
+}) {
+  const [editor] = useLexicalComposerContext();
+  useEffect(() => {
+    // Report the initial count (e.g. seeded via defaultValue) from the mounted
+    // root element's text, then track changes via registerTextContentListener,
+    // which hands us the plain-text content directly.
+    //
+    // We deliberately avoid importing `$getRoot` from the top-level `lexical`
+    // package: that is a *runtime value* import, and in the sandbox's Next
+    // build it forces Babel to transpile lexical's raw `src/*.ts` (which uses
+    // `declare` class fields) and fails. Both APIs used here are methods on the
+    // editor instance, so no top-level `lexical` value import is needed.
+    onCountChange(editor.getRootElement()?.textContent?.length ?? 0);
+    return editor.registerTextContentListener(textContent => {
+      onCountChange(textContent.length);
+    });
+  }, [editor, onCountChange]);
+  return null;
+}
+
 /**
  * Renders the Lexical ContentEditable. Split out so the placeholder
  * discriminated union (`placeholder` + `aria-placeholder` present together, or

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

@@ -1 +1 @@
-{"version":3,"file":"editorTheme.d.ts","sourceRoot":"","sources":["../../src/RichTextEditor/editorTheme.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EAAC,kBAAkB,EAAC,MAAM,SAAS,CAAC;AAqEhD;;;GAGG;AACH,wBAAgB,iBAAiB,IAAI,kBAAkB,CAwBtD"}
+{"version":3,"file":"editorTheme.d.ts","sourceRoot":"","sources":["../../src/RichTextEditor/editorTheme.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EAAC,kBAAkB,EAAC,MAAM,SAAS,CAAC;AA2GhD;;;GAGG;AACH,wBAAgB,iBAAiB,IAAI,kBAAkB,CA8CtD"}

package/dist/RichTextEditor/editorTheme.js

@@ -19,6 +19,24 @@ import { colorVars, spacingVars, radiusVars, typographyVars, typeScaleVars, font
  * class-name strings, which `stylex.props(...).className` yields.
  */
 export function sharedEditorTheme() {
+  const ulClass = {
+    className: "xsq74q5 x31w388 xtaz4m5 x43c9pm"
+  }.className ?? '';
+  const olClass = {
+    className: "xsq74q5 x31w388 x3yw8vx x43c9pm"
+  }.className ?? '';
+  const ulDepth2Class = {
+    className: "x31w388 x43c9pm x10im51j xrylv2j"
+  }.className ?? '';
+  const ulDepth3Class = {
+    className: "x31w388 x43c9pm x10im51j x152237o"
+  }.className ?? '';
+  const olDepth2Class = {
+    className: "x31w388 x43c9pm x10im51j x1rrqm6h"
+  }.className ?? '';
+  const olDepth3Class = {
+    className: "x31w388 x43c9pm x10im51j x19k9dhg"
+  }.className ?? '';
   return {
     paragraph: {
       className: "xsq74q5"
@@ -38,15 +56,23 @@ export function sharedEditorTheme() {
       className: "x1g06x3t xrxpjvj x126nfab xct1zlm x1t7ytsu x14ydlgx xv1l7n4"
     }.className,
     list: {
-      ul: {
-        className: "xsq74q5 x31w388"
-      }.className,
-      ol: {
-        className: "xsq74q5 x31w388"
+      ul: ulClass,
+      ol: olClass,
+      checklist: {
+        className: "xsq74q5 x43c9pm x3ct3a4 x12gdq22"
       }.className,
       listitem: {
-        className: "x1yqqeh1"
-      }.className
+        className: "x1yqqeh1 x1sle589"
+      }.className,
+      nested: {
+        listitem: {
+          className: "x1yqqeh1 x1sle589"
+        }.className
+      },
+      // Depth arrays cycle via `depth % length`, so three entries give three
+      // distinct nesting levels before repeating (disc→circle→square, etc.).
+      ulDepth: [ulClass, ulDepth2Class, ulDepth3Class],
+      olDepth: [olClass, olDepth2Class, olDepth3Class]
     },
     link: {
       className: "xjse4m1 x1bvjpef x1ypdohk"

package/dist/RichTextEditor/index.d.ts

@@ -8,7 +8,7 @@
  * SYNC: When modified, update this header and the editor component doc files.
  */
 export { RichTextEditor } from './RichTextEditor';
-export type { RichTextEditorProps, RichTextEditorStatus, RichTextEditorStatusType, RichTextEditorSize, } from './RichTextEditor';
+export type { RichTextEditorProps, RichTextEditorRef, RichTextEditorStatus, RichTextEditorStatusType, RichTextEditorSize, Transformer, } from './RichTextEditor';
 export { RichTextView } from './RichTextView';
 export type { RichTextViewProps } from './RichTextView';
 export { sharedEditorTheme } from './editorTheme';

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/RichTextEditor/index.ts"],"names":[],"mappings":"AAIA;;;;;;;;GAQG;AAEH,OAAO,EAAC,cAAc,EAAC,MAAM,kBAAkB,CAAC;AAChD,YAAY,EACV,mBAAmB,EACnB,oBAAoB,EACpB,wBAAwB,EACxB,kBAAkB,GACnB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EAAC,YAAY,EAAC,MAAM,gBAAgB,CAAC;AAC5C,YAAY,EAAC,iBAAiB,EAAC,MAAM,gBAAgB,CAAC;AAEtD,OAAO,EAAC,iBAAiB,EAAC,MAAM,eAAe,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/RichTextEditor/index.ts"],"names":[],"mappings":"AAIA;;;;;;;;GAQG;AAEH,OAAO,EAAC,cAAc,EAAC,MAAM,kBAAkB,CAAC;AAChD,YAAY,EACV,mBAAmB,EACnB,iBAAiB,EACjB,oBAAoB,EACpB,wBAAwB,EACxB,kBAAkB,EAClB,WAAW,GACZ,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EAAC,YAAY,EAAC,MAAM,gBAAgB,CAAC;AAC5C,YAAY,EAAC,iBAAiB,EAAC,MAAM,gBAAgB,CAAC;AAEtD,OAAO,EAAC,iBAAiB,EAAC,MAAM,eAAe,CAAC"}

package/dist/index.d.ts

@@ -16,6 +16,7 @@ export { InfoTip, type InfoTipProps, type InfoTipSize } from './InfoTip';
 export { ChatReasoning, type ChatReasoningProps, } from './ChatReasoning/ChatReasoning';
 export * from './Chat';
 export { Drawer, type DrawerProps } from './Drawer';
+export { BottomSheet, type BottomSheetProps } from './BottomSheet';
 export { Stat, type StatProps, type StatDelta, type StatDeltaDirection, type StatDeltaSentiment, type StatSize, } from './Stat';
 export * from './Schedule';
 export { SVGIcon, type SVGIconProps, type SVGIconVariation, type SVGIconSize, type SVGIconColor, type SVGIconDef, type IconShape, type IconShapeRole, iconVars, variations, opticalSize, xIcon, checkIcon, bellIcon, homeIcon, settingsIcon, calendarIcon, menuIcon, heartIcon, eyeIcon, starIcon, folderIcon, shieldIcon, searchIcon, mailIcon, lockIcon, starterIcons, } from './SVGIcon';
@@ -27,5 +28,5 @@ export { SankeyChart, type SankeyChartProps, SankeyLink, type SankeyLinkProps, S
 export * from './Stepper';
 export * from './CircularProgress';
 export { LogStream, type LogStreamProps, type LogEntry, type LogStreamLevel, } from './LogStream';
-export { RichTextEditor, type RichTextEditorProps, type RichTextEditorStatus, type RichTextEditorStatusType, type RichTextEditorSize, RichTextView, type RichTextViewProps, sharedEditorTheme, } from './RichTextEditor';
+export { RichTextEditor, type RichTextEditorProps, type RichTextEditorRef, type RichTextEditorStatus, type RichTextEditorStatusType, type RichTextEditorSize, type Transformer, RichTextView, type RichTextViewProps, sharedEditorTheme, } from './RichTextEditor';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -27,6 +27,9 @@ export * from "./Chat/index.js";
 // Drawer — experimental overlay panel
 export { Drawer } from "./Drawer/index.js";
 
+// BottomSheet — mobile touch sheet built on the Drawer <dialog> engine
+export { BottomSheet } from "./BottomSheet/index.js";
+
 // Stat — experimental KPI/metric display
 export { Stat } from "./Stat/index.js";
 

package/dist/lab.css

@@ -111,11 +111,13 @@
   .xz51j44:not(#\#):not(#\#){grid-row:3}
   .x33j1x8:not(#\#):not(#\#){grid-row:var(--x-gridRow)}
   .x17y0mx6:not(#\#):not(#\#){inset-inline:0}
+  .x10im51j:not(#\#):not(#\#){margin-block:0}
   .x1yqqeh1:not(#\#):not(#\#){margin-block:var(--spacing-0-5)}
   .xsq74q5:not(#\#):not(#\#){margin-block:var(--spacing-1)}
   .x1g06x3t:not(#\#):not(#\#){margin-block:var(--spacing-2)}
   .x1oqu0vw:not(#\#):not(#\#){margin-block:var(--x-marginBlock)}
   .xrxpjvj:not(#\#):not(#\#){margin-inline:0}
+  .xvueqy4:not(#\#):not(#\#){margin-inline:auto}
   .x1a2a7pz:not(#\#):not(#\#){outline:none}
   .xysyzu8:not(#\#):not(#\#){overflow:auto}
   .xb3r6kr:not(#\#):not(#\#){overflow:hidden}
@@ -232,7 +234,10 @@
   .x1t7ytsu:not(#\#):not(#\#):not(#\#){border-inline-start-style:solid}
   .xct1zlm:not(#\#):not(#\#):not(#\#){border-inline-start-width:3px}
   .xgbv0en:not(#\#):not(#\#):not(#\#){border-inline-start-width:var(--border-width)}
+  .x663v1:not(#\#):not(#\#):not(#\#){border-start-end-radius:var(--radius-page)}
+  .x183tx6i:not(#\#):not(#\#):not(#\#){border-start-start-radius:var(--radius-page)}
   .x18oyj42:not(#\#):not(#\#):not(#\#){box-shadow:0 0 0 1px var(--color-accent)}
+  .x1gnnqk1:not(#\#):not(#\#):not(#\#){box-shadow:none}
   .x1kcpxr7:not(#\#):not(#\#):not(#\#){box-shadow:var(--shadow-high)}
   .x14hfi27:not(#\#):not(#\#):not(#\#){box-shadow:var(--shadow-med)}
   .x9f619:not(#\#):not(#\#):not(#\#){box-sizing:border-box}
@@ -287,6 +292,7 @@
   .xewh9hi:not(#\#):not(#\#):not(#\#){column-gap:var(--spacing-3)}
   .x1w36mze:not(#\#):not(#\#):not(#\#){contain-intrinsic-height:auto 28px}
   .xb5mbof:not(#\#):not(#\#):not(#\#){content-visibility:auto}
+  .x1jm3nie:not(#\#):not(#\#):not(#\#){cursor:grab}
   .x1h6gzvc:not(#\#):not(#\#):not(#\#){cursor:not-allowed}
   .x1ypdohk:not(#\#):not(#\#):not(#\#){cursor:pointer}
   .x1lliihq:not(#\#):not(#\#):not(#\#){display:block}
@@ -370,7 +376,15 @@
   .x1cpk1wn:not(#\#):not(#\#):not(#\#){line-height:var(--text-heading-2-leading)}
   .x1kq96og:not(#\#):not(#\#):not(#\#){line-height:var(--text-label-leading)}
   .x1ltkj2j:not(#\#):not(#\#):not(#\#){line-height:var(--text-supporting-leading)}
+  .x43c9pm:not(#\#):not(#\#):not(#\#){list-style-position:outside}
+  .xrylv2j:not(#\#):not(#\#):not(#\#){list-style-type:circle}
+  .x3yw8vx:not(#\#):not(#\#):not(#\#){list-style-type:decimal}
+  .xtaz4m5:not(#\#):not(#\#):not(#\#){list-style-type:disc}
+  .x1sle589:not(#\#):not(#\#):not(#\#){list-style-type:inherit}
+  .x1rrqm6h:not(#\#):not(#\#):not(#\#){list-style-type:lower-alpha}
+  .x19k9dhg:not(#\#):not(#\#):not(#\#){list-style-type:lower-roman}
   .x3ct3a4:not(#\#):not(#\#):not(#\#){list-style-type:none}
+  .x152237o:not(#\#):not(#\#):not(#\#){list-style-type:square}
   .x1h1dc9q:not(#\#):not(#\#):not(#\#){margin-inline-end:calc(var(--spacing-0-5) + var(--border-width))}
   .xhi58n4:not(#\#):not(#\#):not(#\#){margin-inline-start:calc(var(--spacing-1) * -1)}
   .xladpz9:not(#\#):not(#\#):not(#\#){margin-inline-start:var(--spacing-0-5)}
@@ -389,6 +403,7 @@
   .xmarwi5:not(#\#):not(#\#):not(#\#){padding-inline-start:var(--icon-inline-offset)}
   .x18gyask:not(#\#):not(#\#):not(#\#){padding-inline-start:var(--spacing-0)}
   .x1vsv5vr:not(#\#):not(#\#):not(#\#){padding-inline-start:var(--spacing-1)}
+  .x12gdq22:not(#\#):not(#\#):not(#\#){padding-inline-start:var(--spacing-2)}
   .x126nfab:not(#\#):not(#\#):not(#\#){padding-inline-start:var(--spacing-3)}
   .x1rey3nv:not(#\#):not(#\#):not(#\#){padding-inline-start:var(--spacing-4)}
   .x31w388:not(#\#):not(#\#):not(#\#){padding-inline-start:var(--spacing-6)}
@@ -417,6 +432,7 @@
   .x1yc453h:not(#\#):not(#\#):not(#\#){text-align:start}
   .xlyipyv:not(#\#):not(#\#):not(#\#){text-overflow:ellipsis}
   .xtvhhri:not(#\#):not(#\#):not(#\#){text-transform:uppercase}
+  .x5ve5x3:not(#\#):not(#\#):not(#\#){touch-action:none}
   .xx69xxh:not(#\#):not(#\#):not(#\#){touch-action:pan-y}
   .x9tu13d:not(#\#):not(#\#):not(#\#){transform:rotate(-90deg)}
   .x19jd1h0:not(#\#):not(#\#):not(#\#){transform:rotate(180deg)}
@@ -445,6 +461,7 @@
   .xuxw1ft:not(#\#):not(#\#):not(#\#){white-space:nowrap}
   .x126k92a:not(#\#):not(#\#):not(#\#){white-space:pre-wrap}
   .x1sdyfia:not(#\#):not(#\#):not(#\#){white-space:pre}
+  .x1so62im:not(#\#):not(#\#):not(#\#){will-change:transform}
   .x1lldw8n:not(#\#):not(#\#):not(#\#){word-break:normal}
   .x98t3bc:not(#\#):not(#\#):not(#\#){writing-mode:vertical-rl}
   .x1vjfegm:not(#\#):not(#\#):not(#\#){z-index:1}
@@ -482,6 +499,7 @@
   .x1ey2m1c:not(#\#):not(#\#):not(#\#):not(#\#){bottom:0}
   .xdd4er5:not(#\#):not(#\#):not(#\#):not(#\#){bottom:auto}
   .x1hmuevu:not(#\#):not(#\#):not(#\#):not(#\#){bottom:var(--spacing-3)}
+  .x5yr21d:not(#\#):not(#\#):not(#\#):not(#\#){height:100%}
   .xtdtrs8:not(#\#):not(#\#):not(#\#):not(#\#){height:100dvh}
   .x170jfvy:not(#\#):not(#\#):not(#\#):not(#\#){height:10px}
   .x1v9usgg:not(#\#):not(#\#):not(#\#):not(#\#){height:14px}
@@ -493,6 +511,7 @@
   .xqu0tyb:not(#\#):not(#\#):not(#\#):not(#\#){height:4px}
   .x1ycjhwn:not(#\#):not(#\#):not(#\#):not(#\#){height:5px}
   .x1d9x2de:not(#\#):not(#\#):not(#\#):not(#\#){height:640px}
+  .xg7h5cd:not(#\#):not(#\#):not(#\#):not(#\#){height:fit-content}
   .xhigkf7:not(#\#):not(#\#):not(#\#):not(#\#){height:var(--icon-size)}
   .x6b6gus:not(#\#):not(#\#):not(#\#):not(#\#){height:var(--spacing-4)}
   .x1grt7ep:not(#\#):not(#\#):not(#\#):not(#\#){height:var(--spacing-5)}
@@ -503,9 +522,11 @@
   .xcsaf9d:not(#\#):not(#\#):not(#\#):not(#\#){margin-top:var(--spacing-1)}
   .xtbrsbv:not(#\#):not(#\#):not(#\#):not(#\#){margin-top:var(--spacing-2)}
   .x1vhfslr:not(#\#):not(#\#):not(#\#):not(#\#){margin-top:var(--x-marginBlockStart)}
+  .x1ismmbu:not(#\#):not(#\#):not(#\#):not(#\#){max-height:90dvh}
   .x7ab17h:not(#\#):not(#\#):not(#\#):not(#\#){max-height:none}
   .x1jols5v:not(#\#):not(#\#):not(#\#):not(#\#){max-height:var(--x-maxHeight)}
   .x1k2d6hx:not(#\#):not(#\#):not(#\#):not(#\#){max-width:44px}
+  .x11gisft:not(#\#):not(#\#):not(#\#):not(#\#){max-width:640px}
   .x1x1rfll:not(#\#):not(#\#):not(#\#):not(#\#){max-width:none}
   .xf68679:not(#\#):not(#\#):not(#\#):not(#\#){max-width:var(--x-maxWidth)}
   .x2lwn1j:not(#\#):not(#\#):not(#\#):not(#\#){min-height:0}
@@ -525,6 +546,7 @@
   .x6ikm8r:not(#\#):not(#\#):not(#\#):not(#\#){overflow-x:hidden}
   .x1odjw0f:not(#\#):not(#\#):not(#\#):not(#\#){overflow-y:auto}
   .x1j85h84:not(#\#):not(#\#):not(#\#):not(#\#){padding-bottom:1px}
+  .x1a148e8:not(#\#):not(#\#):not(#\#):not(#\#){padding-bottom:env(safe-area-inset-bottom,0px)}
   .xy143xn:not(#\#):not(#\#):not(#\#):not(#\#){padding-bottom:var(--spacing-1)}
   .xpgmcrp:not(#\#):not(#\#):not(#\#):not(#\#){padding-top:var(--icon-block-offset)}
   .xbx876j:not(#\#):not(#\#):not(#\#):not(#\#){padding-top:var(--spacing-0-5)}
@@ -545,6 +567,7 @@
   .x1dz1jew:not(#\#):not(#\#):not(#\#):not(#\#){width:280px}
   .x1849jeq:not(#\#):not(#\#):not(#\#):not(#\#){width:30px}
   .x1td3qas:not(#\#):not(#\#):not(#\#):not(#\#){width:32px}
+  .x14qfxbe:not(#\#):not(#\#):not(#\#):not(#\#){width:36px}
   .x51ohtg:not(#\#):not(#\#):not(#\#):not(#\#){width:4px}
   .x1ftt334:not(#\#):not(#\#):not(#\#):not(#\#){width:5px}
   .x1oai4fc:not(#\#):not(#\#):not(#\#):not(#\#){width:var(--icon-size)}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/lab",
-  "version": "0.1.9-canary.d2d84f8",
+  "version": "0.1.9-canary.e00a241",
   "description": "Experimental Astryx components — published to npm only under the @canary dist-tag for early testing; never released as a stable (latest) version.",
   "author": "Meta Open Source",
   "license": "MIT",
@@ -45,7 +45,7 @@
   },
   "peerDependencies": {
     "@stylexjs/stylex": ">=0.10.0",
-    "@astryxdesign/core": "0.1.9-canary.d2d84f8",
+    "@astryxdesign/core": "0.1.9-canary.e00a241",
     "react": ">=19.0.0",
     "react-dom": ">=19.0.0",
     "lexical": "^0.46.0",

package/src/BottomSheet/BottomSheet.doc.mjs

@@ -0,0 +1,105 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+/** @type {import('../../../core/src/docs-types').ComponentDoc} */
+
+export const docs = {
+  name: 'BottomSheet',
+  displayName: 'BottomSheet',
+  group: 'BottomSheet',
+  category: 'Overlay',
+  keywords: ["bottom sheet","sheet","mobile","touch","drag","swipe","dismiss","grab handle","dialog","overlay","modal"],
+  theming: {
+    targets: [
+      {className: 'astryx-bottom-sheet', visualProps: []},
+    ],
+  },
+  description: 'A mobile touch sheet that rises from the bottom edge, with a grab handle and swipe-to-dismiss. Built on the Drawer <dialog> engine.',
+  props: [
+    {
+      name: 'isOpen',
+      type: 'boolean',
+      description: 'Whether the sheet is open. Fully controlled; pair with onOpenChange.',
+      required: true,
+    },
+    {
+      name: 'onOpenChange',
+      type: '(isOpen: boolean) => void',
+      description: '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.',
+      required: true,
+    },
+    {
+      name: 'label',
+      type: 'string',
+      description: 'Accessible label for the sheet. Required; the sheet has no built-in heading to derive a name from.',
+      required: true,
+    },
+    {
+      name: 'children',
+      type: 'ReactNode',
+      description: 'Sheet content, rendered below the grab handle in a scrollable area.',
+      required: true,
+    },
+    {
+      name: 'height',
+      type: "'short' | 'medium' | 'tall' | 'auto'",
+      description: "How tall the sheet is: 'short' is a fixed peek height, 'medium' is half the viewport, 'tall' is nearly the full viewport, and 'auto' fits its content up to the 'tall' budget. On shorter viewports the sheet fills the available height.",
+      default: "'medium'",
+    },
+  ],
+  usage: {
+    description: 'A mobile touch surface for filters, actions, and detail views that should rise from the bottom of the screen. The sheet is modal: focus is trapped while open and restored to the opener on close, and Escape dismisses, so the swipe gesture always has a keyboard equivalent. Content padding clears the home indicator via env(safe-area-inset-bottom).',
+    bestPractices: [
+      { guidance: true, description: 'Use for mobile-first surfaces (filters, share sheets, quick actions) where the content should rise from the bottom edge.' },
+      { guidance: true, description: 'Keep the caller as the source of truth: derive isOpen from state and clear it in onOpenChange.' },
+      { guidance: true, description: "Pick a height that fits the content: 'auto' for short sheets, 'medium'/'tall' for lists and forms." },
+      { guidance: false, description: 'Use a BottomSheet for desktop inspectors or master-detail; use Drawer (side="end", hasScrim={false}) instead.' },
+    ],
+  },
+  examples: [
+    {
+      label: 'Basic',
+      code: `const [isOpen, setIsOpen] = useState(false);
+<BottomSheet
+  isOpen={isOpen}
+  onOpenChange={setIsOpen}
+  label="Filters">
+  <FilterControls />
+</BottomSheet>`,
+    },
+    {
+      label: 'Tall sheet (a list)',
+      code: `const [isOpen, setIsOpen] = useState(false);
+<BottomSheet
+  isOpen={isOpen}
+  onOpenChange={setIsOpen}
+  label="Nearby places"
+  height="tall">
+  <PlaceList />
+</BottomSheet>`,
+    },
+    {
+      label: 'Auto height (fits content)',
+      code: `const [isOpen, setIsOpen] = useState(false);
+<BottomSheet
+  isOpen={isOpen}
+  onOpenChange={setIsOpen}
+  label="Share"
+  height="auto">
+  <ShareActions />
+</BottomSheet>`,
+    },
+  ],
+};
+
+/** @type {import('../../../core/src/docs-types').TranslationDoc} */
+export const docsDense = {
+  description: 'mobile touch sheet rising from the bottom edge (built on the Drawer <dialog> engine): grab handle, swipe-to-dismiss, named height scale',
+  usage: {
+    description: 'Mobile surface for filters, actions, and detail views. Modal: focus trap + restore, and Escape dismisses so swipe has a keyboard equivalent. Content clears the home indicator via safe-area inset.',
+    bestPractices: [
+      { guidance: true, description: 'Use for mobile-first bottom surfaces (filters, share sheets, quick actions).' },
+      { guidance: true, description: 'Derive isOpen from state; clear it in onOpenChange.' },
+      { guidance: true, description: "Pick a height that fits: 'auto' for short sheets, 'medium'/'tall' for lists and forms." },
+      { guidance: false, description: 'Use for desktop inspectors or master-detail; use Drawer instead.' },
+    ],
+  },
+};