@astryxdesign/core 0.5.1 → 0.5.2-canary.00477a5

package/src/ContextMenu/ContextMenu.tsx

@@ -3,8 +3,9 @@
 
 /**
  * @file ContextMenu.tsx
- * @input Uses React, StyleX, useLayer (context mode), useListFocus
- * @output Exports ContextMenu component
+ * @input Uses React, StyleX, useLayer, BottomSheet, useListFocus, and the
+ *   shared menu-presentation resolver
+ * @output Exports ContextMenu with cursor-popover and touch-sheet presentations
  * @position Core implementation; consumed by index.ts
  *
  * Right-click context menu positioned at the cursor. The cursor point is
@@ -34,13 +35,19 @@ import React, {
   useCallback,
   useEffect,
   useId,
+  lazy,
   useMemo,
   useRef,
   useState,
+  Suspense,
 } from 'react';
 import type {ReactNode} from 'react';
 import * as stylex from '@stylexjs/stylex';
+import {Button} from '../Button';
+import {Heading} from '../Heading';
+import {Icon} from '../Icon';
 import {useLayer} from '../Layer/useLayer';
+import {MenuBottomSheetActionList} from '../DropdownMenu/MenuBottomSheetActionList';
 import {renderDropdownItems} from '../DropdownMenu/renderDropdownItems';
 import {
   DropdownMenuContext,
@@ -63,7 +70,7 @@ import {
   easeVars,
   shadowVars,
 } from '../theme/tokens.stylex';
-import {mergeProps, isImeKeyEvent} from '../utils';
+import {mergeProps, isImeKeyEvent, rtlStyles} from '../utils';
 import type {BaseProps} from '../BaseProps';
 import type {StyleXStyles} from '../theme/types';
 import {themeProps} from '../utils/themeProps';
@@ -76,6 +83,16 @@ import type {
 } from '../DropdownMenu/DropdownMenu';
 
 import {useMergedRefs} from '../hooks/useMergedRefs';
+import {
+  useAdaptivePresentation,
+  type AdaptivePresentation,
+} from '../hooks/useAdaptivePresentation';
+
+const LazyMenuBottomSheet = lazy(async () =>
+  import('../DropdownMenu/MenuBottomSheet').then(module => ({
+    default: module.MenuBottomSheet,
+  })),
+);
 const styles = stylex.create({
   // Trigger wrapper: suppress the iOS long-press callout/selection so the
   // long-press opens our context menu instead of the native text/callout UI.
@@ -85,6 +102,8 @@ const styles = stylex.create({
   trigger: {
     position: 'relative',
     WebkitTouchCallout: 'none',
+    WebkitUserSelect: 'none',
+    userSelect: 'none',
   },
   // Zero-size anchor placed at the cursor point within the trigger. The menu
   // is anchored to this element, so it sits under the cursor yet is positioned
@@ -121,6 +140,33 @@ const styles = stylex.create({
   popoverCustomWidth: (width: string | number) => ({
     minWidth: typeof width === 'number' ? `${width}px` : width,
   }),
+  sheetMenu: {
+    boxSizing: 'border-box',
+    display: 'flex',
+    flexDirection: 'column',
+    gap: spacingVars['--spacing-0-5'],
+    width: '100%',
+    '--_dropdown-menu-radius': radiusVars['--radius-container'],
+    '--_dropdown-menu-padding': spacingVars['--spacing-1'],
+    padding: spacingVars['--spacing-1'],
+    borderRadius: 'var(--_dropdown-menu-radius)',
+    backgroundColor: colorVars['--color-background-surface'],
+    outline: 'none',
+    userSelect: 'none',
+  },
+  sheetHeader: {
+    display: 'flex',
+    flexDirection: 'row',
+    alignItems: 'center',
+    gap: spacingVars['--spacing-1'],
+    marginBottom: spacingVars['--spacing-2'],
+  },
+  sheetRootHeading: {
+    marginInlineStart: spacingVars['--spacing-3'],
+  },
+  sheetViewHeading: {
+    outline: 'none',
+  },
 });
 
 // =============================================================================
@@ -164,6 +210,15 @@ interface ContextMenuBaseProps extends BaseProps {
   isDisabled?: boolean;
   /** Called when the menu opens or closes. */
   onOpenChange?: (isOpen: boolean) => void;
+  /**
+   * Presentation policy for the menu.
+   * - `popover`: open beside the pointer position.
+   * - `bottom-sheet`: open as an action sheet.
+   * - `adaptive`: use a BottomSheet on compact coarse-pointer viewports and
+   *   the cursor-positioned popover elsewhere.
+   * @default 'popover'
+   */
+  presentation?: AdaptivePresentation;
   'data-testid'?: string;
 }
 
@@ -215,6 +270,7 @@ export function ContextMenu({
   label: labelFromProps,
   isDisabled = false,
   onOpenChange,
+  presentation = 'popover',
   ref,
   className,
   style,
@@ -225,6 +281,9 @@ export function ContextMenu({
 }: ContextMenuProps) {
   const t = useTranslator();
   const label = labelFromProps ?? t('@astryx.contextMenu.label');
+  const backLabel = t('@astryx.dropdownMenu.back');
+  const resolvedPresentation = useAdaptivePresentation(presentation);
+  const usesBottomSheet = resolvedPresentation === 'bottom-sheet';
   // Separate content props (union discriminant) from DOM pass-through attrs.
   // The union means exactly one of items/menuContent exists in rest; destructure
   // both so triggerProps contains only DOM-safe attributes.
@@ -250,8 +309,25 @@ export function ContextMenu({
   // Element focused before the menu opened, restored when it closes so focus
   // does not fall to <body> after Escape or outside-click dismissal.
   const triggerFocusRef = useRef<HTMLElement | null>(null);
+  const sheetHeadingRef = useRef<HTMLHeadingElement>(null);
 
   const [isOpen, setIsOpen] = useState(false);
+  const [submenuPath, setSubmenuPath] = useState<ContextMenuItemData[]>([]);
+  const currentSubmenu = submenuPath.at(-1);
+  const currentItems = currentSubmenu?.items ?? items;
+  const currentTitle = currentSubmenu?.label ?? label;
+  const sheetLabel = typeof currentTitle === 'string' ? currentTitle : label;
+
+  const updateOpenState = useCallback(
+    (nextIsOpen: boolean) => {
+      if (!nextIsOpen) {
+        setSubmenuPath([]);
+      }
+      setIsOpen(nextIsOpen);
+      onOpenChange?.(nextIsOpen);
+    },
+    [onOpenChange],
+  );
 
   const layer = useLayer({
     mode: 'context',
@@ -273,8 +349,35 @@ export function ContextMenu({
   });
 
   const closeMenu = useCallback(() => {
-    layer.hide();
-  }, [layer]);
+    if (usesBottomSheet) {
+      updateOpenState(false);
+    } else {
+      layer.hide();
+    }
+  }, [layer, updateOpenState, usesBottomSheet]);
+
+  const handleBottomSheetSelect = useCallback(
+    (item: ContextMenuItemData) => {
+      if (item.isDisabled) {
+        return;
+      }
+      item.onClick?.();
+      if (item.hasCloseOnSelect !== false) {
+        closeMenu();
+      }
+    },
+    [closeMenu],
+  );
+
+  useEffect(() => {
+    if (!isOpen || submenuPath.length === 0) {
+      return;
+    }
+    const frame = requestAnimationFrame(() => {
+      sheetHeadingRef.current?.focus({preventScroll: true});
+    });
+    return () => cancelAnimationFrame(frame);
+  }, [isOpen, submenuPath.length]);
 
   const {
     listRef,
@@ -308,7 +411,7 @@ export function ContextMenu({
   // opening right-click as a dismiss event. Handling it ourselves via
   // mousedown avoids that race.
   useEffect(() => {
-    if (!isOpen) {
+    if (!isOpen || usesBottomSheet) {
       return;
     }
     const handleClickOutside = (e: MouseEvent) => {
@@ -321,14 +424,14 @@ export function ContextMenu({
     return () => {
       document.removeEventListener('mousedown', handleClickOutside);
     };
-  }, [isOpen, closeMenu, listRef]);
+  }, [isOpen, closeMenu, listRef, usesBottomSheet]);
 
   // Dismiss on Escape from anywhere while open. The menu div's own onKeyDown
   // only fires when focus is inside the menu; a document-level listener is
   // kept as a reliable fallback Escape path (e.g. if focus has moved out of
   // the menu). Guards against IME composition-cancel.
   useEffect(() => {
-    if (!isOpen) {
+    if (!isOpen || usesBottomSheet) {
       return;
     }
     const handleEscape = (e: KeyboardEvent) => {
@@ -347,7 +450,7 @@ export function ContextMenu({
     return () => {
       document.removeEventListener('keydown', handleEscape);
     };
-  }, [isOpen, closeMenu]);
+  }, [isOpen, closeMenu, usesBottomSheet]);
 
   const listKeyDown = useCallback(
     (e: React.KeyboardEvent) => {
@@ -404,10 +507,14 @@ export function ContextMenu({
         document.activeElement instanceof HTMLElement
           ? document.activeElement
           : focusEl;
-      layer.show();
-      requestAnimationFrame(() => focusFirst());
+      if (usesBottomSheet) {
+        updateOpenState(true);
+      } else {
+        layer.show();
+        requestAnimationFrame(() => focusFirst());
+      }
     },
-    [layer, focusFirst],
+    [layer, focusFirst, updateOpenState, usesBottomSheet],
   );
 
   const handleContextMenu = useCallback(
@@ -465,6 +572,74 @@ export function ContextMenu({
   const resolvedMenuContent =
     itemsProp !== undefined ? renderDropdownItems(items) : menuContent;
 
+  const renderedMenu = (
+    <div
+      ref={listRef}
+      id={menuId}
+      role="menu"
+      data-autofocus={usesBottomSheet ? '' : undefined}
+      tabIndex={usesBottomSheet ? 0 : -1}
+      aria-label={label}
+      onKeyDown={listKeyDown}
+      onContextMenu={e => e.preventDefault()}
+      {...mergeProps(
+        themeProps('context-menu'),
+        stylex.props(usesBottomSheet ? styles.sheetMenu : styles.menu, xstyle),
+        className,
+        style,
+      )}>
+      <DropdownMenuContext value={contextValue}>
+        {resolvedMenuContent}
+      </DropdownMenuContext>
+    </div>
+  );
+
+  const renderedBottomSheetContent =
+    itemsProp !== undefined ? (
+      <div
+        ref={listRef}
+        data-autofocus=""
+        tabIndex={0}
+        {...mergeProps(
+          themeProps('context-menu'),
+          stylex.props(styles.sheetMenu, xstyle),
+          className,
+          style,
+        )}>
+        <div {...stylex.props(styles.sheetHeader)}>
+          {submenuPath.length > 0 && (
+            <Button
+              label={backLabel}
+              variant="ghost"
+              size="sm"
+              icon={
+                <Icon icon="chevronLeft" size="sm" xstyle={rtlStyles.mirror} />
+              }
+              isIconOnly
+              onClick={() => setSubmenuPath(path => path.slice(0, -1))}
+            />
+          )}
+          <Heading
+            ref={sheetHeadingRef}
+            level={3}
+            tabIndex={-1}
+            xstyle={[
+              styles.sheetViewHeading,
+              submenuPath.length === 0 && styles.sheetRootHeading,
+            ]}>
+            {currentTitle}
+          </Heading>
+        </div>
+        <MenuBottomSheetActionList
+          items={currentItems}
+          onSelect={handleBottomSheetSelect}
+          onOpenSubmenu={item => setSubmenuPath(path => [...path, item])}
+        />
+      </div>
+    ) : (
+      renderedMenu
+    );
+
   return (
     <>
       <div
@@ -494,29 +669,21 @@ export function ContextMenu({
         />
       </div>
 
-      {layer.render(
-        <div
-          ref={listRef}
-          id={menuId}
-          role="menu"
-          aria-label={label}
-          onKeyDown={listKeyDown}
-          onContextMenu={e => e.preventDefault()}
-          {...mergeProps(
-            themeProps('context-menu'),
-            stylex.props(styles.menu, xstyle),
-            className,
-            style,
-          )}>
-          <DropdownMenuContext value={contextValue}>
-            {resolvedMenuContent}
-          </DropdownMenuContext>
-        </div>,
-        {
+      {usesBottomSheet ? (
+        <Suspense fallback={null}>
+          <LazyMenuBottomSheet
+            isOpen={isOpen}
+            onOpenChange={updateOpenState}
+            label={sheetLabel}>
+            {renderedBottomSheetContent}
+          </LazyMenuBottomSheet>
+        </Suspense>
+      ) : (
+        layer.render(renderedMenu, {
           placement: 'below',
           alignment: 'start',
           xstyle: [popoverXstyle, layerAnimations.below],
-        },
+        })
       )}
     </>
   );

package/src/ContextMenu/index.ts

@@ -15,6 +15,7 @@ export {
   type ContextMenuSection,
   type ContextMenuOption,
 } from './ContextMenu';
+export type {AdaptivePresentation as MenuPresentation} from '../hooks/useAdaptivePresentation';
 
 export {
   DropdownMenuItem as ContextMenuItem,

package/src/DateInput/DateInput.doc.mjs

@@ -6,7 +6,7 @@ export const docs = {
   name: 'DateInput',
   displayName: 'Date Input',
   group: 'DateInput',
-  category: 'Data Input',
+  category: 'Form Controls',
   keywords: [
     'dateinput',
     'datepicker',

package/src/DateRangeInput/DateRangeInput.doc.mjs

@@ -6,7 +6,7 @@ export const docs = {
   name: 'DateRangeInput',
   displayName: 'Date Range Input',
   group: 'DateInput',
-  category: 'Data Input',
+  category: 'Form Controls',
   keywords: [
     'daterangepicker',
     'daterange',

package/src/DateTimeInput/DateTimeInput.doc.mjs

@@ -6,7 +6,7 @@ export const docs = {
   name: 'DateTimeInput',
   displayName: 'Date Time Input',
   group: 'DateInput',
-  category: 'Data Input',
+  category: 'Form Controls',
   keywords: [
     'datetimepicker',
     'datetime',

package/src/Divider/Divider.doc.mjs

@@ -1,5 +1,26 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
+/** @type {import('@astryxdesign/cli/authoring').ComponentAnatomyElement[]} */
+const anatomy = [
+  {
+    name: 'Divider group',
+    required: true,
+    description:
+      'Separator group that arranges one or two rules around an optional label.',
+  },
+  {
+    name: 'Rule',
+    required: true,
+    description:
+      'Painted line segment; a second segment renders when a label is present.',
+  },
+  {
+    name: 'Label',
+    required: false,
+    description: 'Optional content displayed between two rule segments.',
+  },
+];
+
 
 
 /** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
@@ -47,6 +68,7 @@ export const docs = {
     ],
   },
   usage: {
+    anatomy,
     description: 'A visual separator that divides content into distinct sections. Use to create clear boundaries between groups of related content, or to demarcate interactive regions within a layout.',
     bestPractices: [
       { guidance: true, description: 'Use subtle dividers between related content sections and strong dividers for high-contrast boundaries.' },
@@ -97,6 +119,7 @@ export const docsZh = {
     ],
   },
   usage: {
+    anatomy,
     description: 'A visual separator that divides content into distinct sections. Use to create clear boundaries between groups of related content, or to demarcate interactive regions within a layout.',
     bestPractices: [
       { guidance: true, description: 'Use subtle dividers between related content sections and strong dividers for high-contrast boundaries.' },
@@ -110,6 +133,7 @@ export const docsZh = {
 export const docsDense = {
   description: 'visual separator w/ optional label, using Astryx design tokens',
   usage: {
+    anatomy,
     description: 'A visual separator that divides content into distinct sections. Use to create clear boundaries between groups of related content, or to demarcate interactive regions within a layout.',
     bestPractices: [
       { guidance: true, description: 'Use subtle dividers between related content sections and strong dividers for high-contrast boundaries.' },

package/src/Divider/Divider.spec.md

@@ -0,0 +1,150 @@
+---
+schema_version: 1
+template_version: 3
+kind: component
+id: component:Divider
+authority: draft
+archive_reason: null
+superseded_by: null
+approved_by: null
+approved_at: null
+owners: [cixzhang]
+review_triggers: [theming]
+verified_by:
+  [packages/core/src/Divider/Divider.test.tsx, scripts/check-knowledge.mjs]
+families: []
+design_specs: []
+architecture: [architecture:component-theming-surface]
+contributing: []
+system_specs: []
+---
+
+# Divider component contract
+
+## Intent
+
+Divider presents a separator group as one rule, or as two rules around an
+optional label. This draft records current consumer anatomy and theming
+reachability without changing runtime behavior, styling, targets, or public API.
+
+## Compatibility and migration
+
+- Released default preserved: `yes`
+- Compatibility class: additive documentation only; runtime, DOM, styling,
+  targets, aliases, and public API remain unchanged
+- Controlled/uncontrolled behavior: not applicable
+- Migration decision: none
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Ownership boundary
+
+**Owns**
+
+- The separator group, its current `divider` target, the painted rule segments,
+  and the optional label placement.
+
+**Does not own / non-goals**
+
+- The meaning of the content regions separated by the divider — owned by the
+  product callsite.
+- Whether Rule or Label should gain public targets — unresolved by this factual
+  backfill.
+
+## Public concepts
+
+No new public concept is introduced. Consumer props and usage remain documented
+in `Divider.doc.mjs`.
+
+## Behavioral and layout contract
+
+| ID  | Candidate invariant                                                                                      | Basis                           | Draft review state                                  |
+| --- | -------------------------------------------------------------------------------------------------------- | ------------------------------- | --------------------------------------------------- |
+| FR1 | The current render contains one rule without a label and two rules with the optional label between them. | Current source, docs, and tests | Verified current behavior; no new behavior decided  |
+| FR2 | The divider group carries the current `divider` target; Rule and Label currently carry no public target. | Current source, docs, and tests | Verified current behavior; theming intent unsettled |
+
+### Allowed variation
+
+- Orientation, visual weight, full-bleed layout, and label content may vary
+  without changing the three-part anatomy recorded here.
+
+### Representative states
+
+- Unlabelled horizontal and vertical dividers render one Rule.
+- Labelled horizontal and vertical dividers render Label between two instances
+  of Rule.
+
+### Transformation and precedence order
+
+- No new layout or styling precedence rule is introduced.
+
+### Performance and resources
+
+- No new performance or resource rule is introduced.
+
+## Accessibility contract
+
+This draft does not change or extend Divider's existing separator naming or
+orientation behavior.
+
+## Design relationships
+
+| Anatomy or state | Design requirement                                                | Representation authority       | Hierarchy role | Component contract |
+| ---------------- | ----------------------------------------------------------------- | ------------------------------ | -------------- | ------------------ |
+| Divider group    | Arranges the separator's rule segments and optional label.        | Current source and public docs | Supporting     | FR1, FR2           |
+| Rule             | Paints the separator line in the selected orientation and weight. | Current source and public docs | Supporting     | FR1, FR2           |
+| Label            | Presents optional content between two rule segments.              | Current source and public docs | Prominent      | FR1, FR2           |
+
+### Theming anatomy
+
+<!-- anatomy-theming:v1 -->
+
+```json
+{
+  "Divider group": {"target": "divider"},
+  "Rule": {
+    "none": {
+      "reason": "unsettled: No current public target reaches this part"
+    }
+  },
+  "Label": {
+    "none": {
+      "reason": "unsettled: No current public target reaches this part"
+    }
+  }
+}
+```
+
+The two `none` dispositions record current reachability while target exposure
+remains unsettled. They do not decide that Rule or Label should remain without
+public targets.
+
+## Family and system relationships
+
+- `architecture:component-theming-surface` owns anatomy qualification, target
+  mapping, and the difference between factual reachability and intended public
+  theming API.
+
+## Verification map
+
+| Contract            | Verification                                     | Representative states                | Mutation or failure expectation                                                                   | Audit section           |
+| ------------------- | ------------------------------------------------ | ------------------------------------ | ------------------------------------------------------------------------------------------------- | ----------------------- |
+| FR1                 | `Divider.test.tsx` structure and label suites    | Labelled and unlabelled; both axes   | Removing or reordering Rule or Label instances fails existing child-count and content assertions. | `audit:Divider/anatomy` |
+| FR2                 | Source inspection and current target inventories | Group, Rule, and Label               | Adding or documenting a current target without updating the anatomy map fails repository checks.  | `audit:Divider/theming` |
+| Theming anatomy map | `scripts/check-knowledge.mjs`                    | Canonical anatomy and current target | Missing, extra, prefixed, stale, or alias-backed mappings fail repository validation.             | `audit:Divider/theming` |
+
+## Decision log
+
+None. This draft records current facts and introduces no component-local design
+or theming decision.
+
+## Open questions
+
+- **OQ1 — Should Rule or Label gain stable public theming targets?** (`human-api`)
+  Their target exposure is unsettled; the current lack of reachability does not
+  decide the answer.
+
+## Content boundary
+
+This file does not duplicate consumer prop tables/examples, current audit
+results, implementation steps, or system rules. It links to their owners.