@astryxdesign/core 0.4.3 → 0.4.4-canary.0f4d45f

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/core",
-  "version": "0.4.3",
+  "version": "0.4.4-canary.0f4d45f",
   "displayName": "Astryx Core",
   "description": "The component library. Accessible, themeable React components with built-in spacing, dark mode, and StyleX styling.",
   "author": "Meta Open Source",
@@ -27,8 +27,6 @@
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
-  "unpkg": "./dist/astryx.umd.js",
-  "jsdelivr": "./dist/astryx.umd.js",
   "sideEffects": [
     "**/*.stylex.ts",
     "**/*.stylex.js",
@@ -49,7 +47,6 @@
       "types": "./src/astryx.css.d.ts",
       "default": "./dist/astryx.css"
     },
-    "./astryx.umd.js": "./dist/astryx.umd.js",
     "./tailwind-theme.css": {
       "types": "./src/tailwind-theme.css.d.ts",
       "default": "./src/tailwind-theme.css"
@@ -122,6 +119,11 @@
       "types": "./dist/Blockquote/index.d.ts",
       "default": "./dist/Blockquote/index.js"
     },
+    "./BottomSheet": {
+      "source": "./src/BottomSheet/index.ts",
+      "types": "./dist/BottomSheet/index.d.ts",
+      "default": "./dist/BottomSheet/index.js"
+    },
     "./Breadcrumbs": {
       "source": "./src/Breadcrumbs/index.ts",
       "types": "./dist/Breadcrumbs/index.d.ts",
@@ -654,6 +656,7 @@
     "react-dom": ">=19.0.0"
   },
   "devDependencies": {
+    "@astryxdesign/cli": "0.4.4-canary.0f4d45f",
     "@babel/cli": "^8.0.4",
     "@babel/core": "^7.29.7",
     "@babel/preset-react": "^8.0.1",
@@ -662,19 +665,17 @@
     "@testing-library/dom": "^10.0.0",
     "@testing-library/jest-dom": "^6.6.0",
     "@testing-library/react": "^16.3.2",
-    "rimraf": "^6.0.1",
-    "@astryxdesign/cli": "0.4.3"
+    "rimraf": "^6.0.1"
   },
   "dependencies": {
     "intl-messageformat": "^11.2.9"
   },
   "scripts": {
     "postinstall": "node scripts/postinstall.mjs",
-    "build": "rimraf dist && pnpm build:i18n && pnpm build:esm && tsc --project tsconfig.build.json && pnpm build:css && pnpm build:umd && node ../../scripts/check-no-dev-jsx.mjs && node ../../scripts/check-fully-specified.mjs",
+    "build": "rimraf dist && pnpm build:i18n && pnpm build:esm && tsc --project tsconfig.build.json && pnpm build:css && node ../../scripts/check-no-dev-jsx.mjs && node ../../scripts/check-fully-specified.mjs",
     "build:i18n": "node scripts/build-pseudo-locale.mjs",
     "build:esm": "babel src --out-dir dist --extensions .ts,.tsx --out-file-extension .js --ignore \"**/*.test.ts,**/*.test.tsx,**/__tests__/**,**/*.perf.test.*,**/*.doc.mjs,**/*.d.ts,**/*.css,**/*.css.d.ts\" --config-file ./babel.config.json",
     "build:css": "node ../../scripts/build-css.mjs",
-    "build:umd": "node ../../scripts/build-umd.mjs",
     "dev": "babel src --watch --out-dir dist --extensions .ts,.tsx --out-file-extension .js --ignore \"**/*.test.*,**/*.doc.mjs,**/*.d.ts,**/*.css*\" --config-file ./babel.config.json",
     "test": "vitest run --root ../..",
     "test:watch": "vitest --root ../..",

package/src/Banner/Banner.doc.mjs

@@ -70,7 +70,7 @@ export const docs = {
       name: 'endContent',
       type: 'ReactNode',
       description:
-        'Action content rendered in the header area, end-aligned. Typically a button or link.',
+        'Action content rendered in the header area, end-aligned. Wraps to its own row below the text when the header is too narrow to hold both.',
       slotElements: [
         {__element: 'Icon', props: {icon: 'chevronDown', size: 'sm'}},
         {__element: 'Badge', props: {label: '3'}},
@@ -164,7 +164,7 @@ export const docsZh = {
     {name: 'icon', type: 'ReactNode', description: '覆盖默认的状态图标。'},
     {name: 'isDismissable', type: 'boolean', description: '横幅是否可被用户关闭。', default: 'false'},
     {name: 'onDismiss', type: '() => void', description: '点击关闭按钮时调用；无论是否提供此回调，横幅都会自动隐藏。'},
-    {name: 'endContent', type: 'ReactNode', description: '渲染在头部区域末端对齐的操作内容，通常是按钮或链接。'},
+    {name: 'endContent', type: 'ReactNode', description: '渲染在头部区域末端对齐的操作内容，通常是按钮或链接。头部过窄时会整体换行到文本下方，自成一行。'},
     {name: 'container', type: "'card' | 'section'", description: '视觉变体：card 带圆角；section 无圆角全宽，适用于页面级场景。', default: "'card'"},
     {name: 'elevation', type: "'none' | 'low' | 'med' | 'high'", description: '静止阴影深度。用于悬浮于内容之上的浮动横幅；none 为默认内联横幅。', default: "'none'"},
     {name: 'children', type: 'ReactNode', description: '渲染在彩色头部下方卡片背景区域的内容。'},
@@ -238,7 +238,7 @@ export const docsDense = {
     icon: 'override default status icon',
     isDismissable: 'user can dismiss banner',
     onDismiss: 'dismiss callback; banner self-hides regardless',
-    endContent: 'end-aligned action in header, typically button/link',
+    endContent: 'end-aligned action in header, typically button/link; wraps to its own row when the header is too narrow',
     container: 'card=border-radius; section=full-width no radius for page-level',
     elevation: 'resting shadow depth: none|low|med|high; raise for a floating banner',
     children: 'content in card-bg area below colored header',

package/src/Banner/Banner.test.tsx

@@ -523,4 +523,44 @@ describe('Banner', () => {
       expect(header.children[1].children).toHaveLength(1);
     });
   });
+
+  // jsdom does no flex layout, so these read the declarations that produce the
+  // wrap. The rendered result is verified in Chromium at 320/375/480/768.
+  describe('narrow-viewport wrapping', () => {
+    const renderBanner = (endContent?: React.ReactNode) => {
+      const {container} = render(
+        <Banner
+          status="warning"
+          title="A compute node is required"
+          endContent={endContent}
+        />,
+      );
+      const header = container.firstElementChild!.firstElementChild!;
+      return {
+        header,
+        textColumn: screen.getByText('A compute node is required')
+          .parentElement!,
+      };
+    };
+
+    it('lets the header wrap so the end area can take its own row', () => {
+      const {header} = renderBanner(<button type="button">Retry</button>);
+      expect(getComputedStyle(header).flexWrap).toBe('wrap');
+    });
+
+    it('gives the text column a wrap threshold when endContent is present', () => {
+      const {textColumn} = renderBanner(<button type="button">Retry</button>);
+      expect(getComputedStyle(textColumn).flexBasis).toBe('8rem');
+    });
+
+    it('leaves the text column free to shrink when there is no endContent', () => {
+      const {textColumn} = renderBanner();
+      expect(getComputedStyle(textColumn).flexBasis).not.toBe('8rem');
+    });
+
+    it('leaves it free for an endContent that renders nothing', () => {
+      const {textColumn} = renderBanner(false);
+      expect(getComputedStyle(textColumn).flexBasis).not.toBe('8rem');
+    });
+  });
 });

package/src/Banner/Banner.tsx

@@ -116,6 +116,9 @@ export interface BannerProps extends BaseProps<HTMLDivElement> {
    * Action button rendered in the header area (end-aligned).
    * Typically an Button with a secondary or ghost variant.
    *
+   * When the header is too narrow to hold the actions and a readable text
+   * column, the whole end area wraps to its own row below the text.
+   *
    * @example
    * ```
    * endContent={<Button label="Retry" variant="ghost" onClick={handleRetry} />}
@@ -205,7 +208,11 @@ const styles = stylex.create({
   header: {
     display: 'flex',
     alignItems: 'flex-start',
-    gap: spacingVars['--spacing-2'],
+    flexWrap: 'wrap',
+    columnGap: spacingVars['--spacing-2'],
+    // The end area carries a -4px block margin (see endArea), so the wrapped
+    // row reads as one step of spacing rather than two.
+    rowGap: spacingVars['--spacing-3'],
     paddingBlock: spacingVars['--spacing-3'],
     paddingInline: spacingVars['--spacing-4'],
   },
@@ -231,6 +238,15 @@ const styles = stylex.create({
     flex: 1,
     minWidth: 0,
   },
+  // The wrap threshold, applied only when there is `endContent` to wrap. Flex
+  // breaks a line when the items no longer fit at their base size, so this
+  // basis is what moves the end area to its own row instead of letting it hold
+  // the header and squeeze the title down to one word per line. In rem so it
+  // tracks the user's font size. The dismiss and expand controls alone are
+  // narrow enough never to need it.
+  headerContentWithEndContent: {
+    flexBasis: '8rem',
+  },
   title: {
     margin: 0,
     fontFamily: 'inherit',
@@ -260,8 +276,13 @@ const styles = stylex.create({
   endArea: {
     display: 'flex',
     alignItems: 'center',
+    flexWrap: 'wrap',
+    justifyContent: 'flex-end',
     gap: spacingVars['--spacing-2'],
     flexShrink: 0,
+    // Bounded so a group of actions wider than the row wraps within itself
+    // rather than pushing the banner past the viewport (WCAG 1.4.10).
+    maxWidth: '100%',
     marginInlineStart: 'auto',
     marginBlock: `calc(-1 * (${spacingVars['--spacing-3']} - ${spacingVars['--spacing-2']}))`,
   },
@@ -537,7 +558,11 @@ export function Banner({
             />
           ) : null}
         </div>
-        <div {...stylex.props(styles.headerContent)}>
+        <div
+          {...stylex.props(
+            styles.headerContent,
+            isRenderable(endContent) && styles.headerContentWithEndContent,
+          )}>
           <div {...stylex.props(styles.title)}>{title}</div>
           {isRenderable(description) && (
             <div {...stylex.props(styles.description)}>{description}</div>

package/src/BottomSheet/BottomSheet.doc.mjs

@@ -0,0 +1,266 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
+
+export const docs = {
+  name: 'BottomSheet',
+  displayName: 'Bottom Sheet',
+  group: 'BottomSheet',
+  category: 'Overlay',
+  keywords: [
+    'bottom sheet',
+    'sheet',
+    'mobile',
+    'touch',
+    'drag',
+    'swipe',
+    'dismiss',
+    'grab handle',
+    'dialog',
+    'overlay',
+    'modal',
+    'form',
+    'mobile keyboard',
+    'visual viewport',
+  ],
+  playground: {
+    overlay: true,
+    defaults: {
+      isOpen: false,
+      label: 'Filters',
+      height: 'hug',
+      children: {
+        __element: 'Section',
+        props: {padding: 4},
+        children: {
+          __element: 'VStack',
+          props: {gap: 2},
+          children: [
+            {
+              __element: 'Heading',
+              props: {level: 3},
+              children: 'Filters',
+            },
+            {
+              __element: 'Text',
+              props: {type: 'body'},
+              children: 'Adjust the properties below, then open the preview.',
+            },
+          ],
+        },
+      },
+    },
+  },
+  theming: {
+    targets: [{className: 'astryx-bottom-sheet', visualProps: []}],
+  },
+  description:
+    "A mobile touch sheet that rises from the bottom edge, with animated entrance and exit, a grab handle, drag-to-resize snap points, and purpose-controlled dismissal. A standalone sheet owns a native <dialog>; inside BottomSheetSwitcher it renders a panel in the switcher's shared dialog. In both modes, ref and shared DOM props target the visual panel <div>.",
+  props: [
+    {
+      name: 'isOpen',
+      type: 'boolean',
+      description:
+        'Whether a standalone sheet is open. Fully controlled; pair with onOpenChange. Omit inside BottomSheetSwitcher.',
+    },
+    {
+      name: 'onOpenChange',
+      type: '(isOpen: boolean) => void',
+      description:
+        'For a standalone sheet, called when it requests an open-state change. Automatic calls follow purpose: info dismisses on Escape, scrim click, or swipe; form dismisses on Escape only; required never dismisses implicitly. Omit inside BottomSheetSwitcher.',
+    },
+    {
+      name: 'purpose',
+      type: "'required' | 'form' | 'info'",
+      description:
+        "Controls implicit dismissal behavior, matching Dialog. info allows Escape, scrim click, and swipe-to-dismiss. form protects entered data by blocking scrim click and swipe while allowing Escape. required blocks every implicit dismissal path and uses role='alertdialog'. Explicit controls may still update the controlled state. Works for standalone and BottomSheetSwitcher-managed sheets.",
+      default: "'info'",
+    },
+    {
+      name: 'sheetId',
+      type: 'string',
+      description:
+        'Unique ID for this sheet inside BottomSheetSwitcher. The switcher opens it when activeSheet matches. Omit isOpen and onOpenChange when sheetId is used.',
+    },
+    {
+      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. If it includes a text-entry control that can bring up the mobile keyboard, use height='tall' and keep the sheet fully expanded while editing.",
+      required: true,
+    },
+    {
+      name: 'height',
+      type: "'hug' | 'capped' | 'tall' | number | string",
+      description:
+        "How tall the sheet is. Named budgets: 'hug' fits its content up to 92% of the viewport, 'capped' is a scrolling mid-height panel (~62%), and 'tall' is a pinned near-full panel (~92%) for content that streams in. Or pass a number (px) / CSS length for a custom budget. The user can drag between snap points regardless. On shorter viewports the sheet fills the available height. Only a fully expanded 'tall' sheet provides mobile-keyboard accommodation: it stays put and scrolls each focused control above the keyboard. Hug, Capped, numeric and CSS-length heights never do, and a Tall sheet stops doing it the moment the user drags it to a shorter detent — resuming when they drag it back. Outside that state the sheet neither moves nor adds keyboard scroll space, and the browser's own focus reveal is left in place; on iOS that reveal can shift the whole page.",
+      default: "'capped'",
+    },
+    {
+      name: 'hasScrim',
+      type: 'boolean',
+      description:
+        "For a standalone BottomSheet, whether to render a scrim, the semi-transparent overlay that covers and blocks the background. true (default) uses showModal(): top layer, focus trap, ::backdrop scrim, body scroll lock, and tap-scrim-to-dismiss when purpose='info', with the background inert. false uses show() with no scrim, leaving the page behind interactive and scrollable. For a multi-step flow, configure hasScrim on BottomSheetSwitcher instead; it owns one shared dialog across every child.",
+      default: 'true',
+    },
+  ],
+  usage: {
+    description:
+      'A mobile touch surface for filters, actions, forms, and detail views that should rise from the bottom of the viewport; use BottomSheetSwitcher for multi-step flows.',
+    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:
+          "Pick the starting height that fits the content: 'hug' for short bounded content, 'capped' for lists, and 'tall' for forms or streaming/resizing content.",
+      },
+      {
+        guidance: true,
+        description:
+          "Use purpose='form' to protect entered data from scrim clicks and swipes while keeping Escape available; reserve purpose='required' for flows that must end through an explicit action.",
+      },
+      {
+        guidance: false,
+        description:
+          "Don't make the sheet content overly long. Consider breaking it into steps and using Bottom Sheet Switcher.",
+      },
+    ],
+  },
+  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: 'Hug height (fits content)',
+      code: `const [isOpen, setIsOpen] = useState(false);
+<BottomSheet
+  isOpen={isOpen}
+  onOpenChange={setIsOpen}
+  label="Share"
+  height="hug">
+  <ShareActions />
+</BottomSheet>`,
+    },
+    {
+      label: 'Long scrolling content',
+      code: `const [isOpen, setIsOpen] = useState(false);
+<BottomSheet
+  isOpen={isOpen}
+  onOpenChange={setIsOpen}
+  label="Release notes"
+  height="hug">
+  <ReleaseNotes />
+</BottomSheet>`,
+    },
+    {
+      label: 'Multi-step flow (one sheet at a time)',
+      code: `const [activeSheet, setActiveSheet] = useState(null);
+<>
+  <Button label="Start" onClick={() => setActiveSheet('details')} />
+  <BottomSheetSwitcher
+    activeSheet={activeSheet}
+    onActiveSheetChange={setActiveSheet}>
+    <BottomSheet sheetId="details" label="Details">
+      <Button label="Continue" onClick={() => setActiveSheet('confirm')} />
+    </BottomSheet>
+    <BottomSheet sheetId="confirm" label="Confirm">
+      <Button label="Back" onClick={() => setActiveSheet('details')} />
+    </BottomSheet>
+  </BottomSheetSwitcher>
+</>`,
+    },
+    {
+      label: 'Mobile keyboard',
+      code: `const [isOpen, setIsOpen] = useState(false);
+<BottomSheet
+  isOpen={isOpen}
+  onOpenChange={setIsOpen}
+  label="Add a comment"
+  height="tall">
+  <LongCommentForm />
+</BottomSheet>`,
+    },
+    {
+      label: 'No scrim',
+      code: `const [isOpen, setIsOpen] = useState(true);
+<BottomSheet
+  isOpen={isOpen}
+  onOpenChange={setIsOpen}
+  label="Nearby places"
+  hasScrim={false}>
+  <PlaceList />
+</BottomSheet>`,
+    },
+    {
+      label: 'Protect form input',
+      code: `const [isOpen, setIsOpen] = useState(false);
+<BottomSheet
+  isOpen={isOpen}
+  onOpenChange={setIsOpen}
+  purpose="form"
+  label="Edit profile">
+  <ProfileForm onSave={() => setIsOpen(false)} />
+</BottomSheet>`,
+    },
+  ],
+};
+
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
+export const docsDense = {
+  description:
+    'mobile touch sheet rising from the bottom edge (native <dialog>): grab handle, transform-based drag-to-resize snap points, scrolling area resizes to the snapped visible height on release (the peek detent keeps the full height and slides instead), Dialog-aligned dismissal purpose (info/form/required), purpose-gated swipe-to-dismiss, fully-expanded Tall visual-viewport mobile-keyboard handling, named height scale, modal (default) or non-modal (hasScrim={false}) presentation',
+  usage: {
+    description:
+      'Mobile touch surface for filters, actions, forms, and detail views that should rise from the bottom of the viewport; use BottomSheetSwitcher for multi-step flows.',
+    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:
+          "Pick the starting height that fits the content: 'hug' for short bounded content, 'capped' for lists, and 'tall' for forms or streaming/resizing content.",
+      },
+      {
+        guidance: true,
+        description:
+          "Use purpose='form' to protect entered data from scrim clicks and swipes while keeping Escape available; reserve purpose='required' for flows that must end through an explicit action.",
+      },
+      {
+        guidance: false,
+        description:
+          "Don't make the sheet content overly long. Consider breaking it into steps and using Bottom Sheet Switcher.",
+      },
+    ],
+  },
+};