@astryxdesign/core 0.7.1 → 0.7.2-canary.151434a

package/src/Item/Item.tsx

@@ -67,7 +67,7 @@ const LazyItemSwipeLayer = lazy(async () => import('./ItemSwipeLayer'));
 // Types
 // =============================================================================
 
-export type ItemAlign = 'center' | 'start';
+export type ItemAlign = 'center' | 'start' | 'first-line';
 export type ItemDensity = 'compact' | 'balanced' | 'spacious';
 
 /**
@@ -168,7 +168,11 @@ export interface ItemProps extends BaseProps<HTMLElement> {
   endContent?: ReactNode;
 
   /**
-   * Vertical alignment of the start/end content slots.
+   * Vertical alignment of the start/end content slots. `center` centers each
+   * slot on the whole text block; `start` lines up slot tops with the text's
+   * top; `first-line` centers each slot on the label's first line, so a small
+   * mark (a status dot, a radio, a timestamp) stays level with the first line
+   * of a wrapped label. A slot taller than that line moves the text down.
    * @default 'center'
    */
   align?: ItemAlign;
@@ -338,7 +342,7 @@ const styles = stylex.create({
     gap: spacingVars['--spacing-2'],
     // The inline inset is published as --_item-inset-inline and the padding
     // derives from it, so consumers that need to compensate for the inset
-    // (List's edgeCompensation) read the var instead of mirroring the values.
+    // (List's edge treatments) read the var instead of mirroring the values.
     // Themes that set paddingInline on `item` also feed this var via the
     // derived var registry, keeping padding and compensation in sync.
     '--_item-inset-inline': spacingVars['--spacing-2'],
@@ -351,6 +355,30 @@ const styles = stylex.create({
   alignStart: {
     alignItems: 'flex-start',
   },
+  // `first-line`: the row aligns its children on their first baselines. The
+  // label's first baseline is its first line's; each slot gets the same
+  // baseline from its strut (below), which the slot centers against its
+  // content. So each slot's center lands on the first line's center for any
+  // slot height, and a taller slot pushes the text down instead of leaving
+  // the row. Pure CSS: no measurement.
+  alignFirstLine: {
+    alignItems: 'baseline',
+  },
+  // A zero-width line of label text inside the slot: same size and leading as
+  // the label, so its line box is the label's first line box. The slot centers
+  // it against the slot's content, and the row's baseline alignment puts it on
+  // the label's first line. Its content carries empty alternative text so
+  // assistive technology reads nothing from it.
+  firstLineSlot: {
+    alignItems: 'center',
+    '::before': {
+      content: stylex.firstThatWorks('"\\200B" / ""', '"\\200B"'),
+      inlineSize: 0,
+      overflow: 'hidden',
+      fontSize: typeScaleVars['--text-body-size'],
+      lineHeight: typeScaleVars['--text-body-leading'],
+    },
+  },
   interactive: {
     cursor: {
       default: 'pointer',
@@ -712,7 +740,13 @@ export function Item({
     <>
       {marker}
       {startContent != null && (
-        <span {...stylex.props(styles.startContent)}>{startContent}</span>
+        <span
+          {...stylex.props(
+            styles.startContent,
+            align === 'first-line' && styles.firstLineSlot,
+          )}>
+          {startContent}
+        </span>
       )}
 
       {hasParentRole || isDelegate ? (
@@ -768,6 +802,7 @@ export function Item({
         <span
           {...stylex.props(
             styles.endContent,
+            align === 'first-line' && styles.firstLineSlot,
             isDisabled && styles.disabledContent,
           )}>
           {endContent}
@@ -846,6 +881,7 @@ export function Item({
           styles.root,
           densityStyles[density],
           align === 'start' && styles.alignStart,
+          align === 'first-line' && styles.alignFirstLine,
           isInteractive && styles.interactive,
           isInteractive && interactionOverlayStyles.backgroundColor,
           isLinkRoot && styles.linkRoot,

package/src/Layer/layerViewportInset.source-build.test.mjs

@@ -0,0 +1,90 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file layerViewportInset.source-build.test.mjs
+ * @input Uses Babel, the core StyleX build config, the StyleX rule processor,
+ *   and the sources that cap or inset anchored layers
+ * @output Verifies the shipped stylesheet carries the dynamic-viewport,
+ *   safe-area gutter and caps (spec:AST-059 FR1–FR3), not only the fallbacks
+ * @position Regression test for the compiled layer viewport inset
+ *
+ * `stylex.firstThatWorks(a, b)` turns two `var()` arguments into one nested
+ * `var(a, b)`. A `defineConsts` reference compiles to such a `var()`, and the
+ * rule processor inlines a constant only where its `var()` stands alone, so a
+ * pair of bare constant references shipped as `var(--<hash>, <fallback>)`
+ * with `--<hash>` defined nowhere: every engine took the fallback.
+ */
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {transformAsync} from '@babel/core';
+import stylexBabelPlugin from '@stylexjs/babel-plugin';
+import {describe, expect, it} from 'vitest';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const SRC = path.resolve(__dirname, '..');
+const CORE_ROOT = path.resolve(SRC, '..');
+
+const SOURCES = [
+  'Layer/layerViewportInset.stylex.ts',
+  'Layer/useLayer.tsx',
+  'Popover/Popover.tsx',
+  'DropdownMenu/DropdownMenu.tsx',
+  'DropdownMenu/DropdownMenuSubMenu.tsx',
+];
+
+async function compileStylesheet() {
+  const rules = [];
+  for (const relative of SOURCES) {
+    const filename = path.join(SRC, relative);
+    const result = await transformAsync(await fs.readFile(filename, 'utf8'), {
+      babelrc: false,
+      configFile: path.join(CORE_ROOT, 'babel.config.json'),
+      filename,
+    });
+    rules.push(...(result?.metadata?.stylex ?? []));
+  }
+  return stylexBabelPlugin.processStylexRules(rules, false);
+}
+
+/** Every declaration of `property` in the compiled sheet. */
+function declarations(css, property) {
+  return [...css.matchAll(new RegExp(`[{;]${property}:([^;}]+)`, 'g'))].map(
+    match => match[1],
+  );
+}
+
+describe('layer viewport inset stylesheet (spec:AST-059)', () => {
+  it('leaves no constant reference unresolved behind a fallback', async () => {
+    const css = await compileStylesheet();
+    const defined = new Set(
+      [...css.matchAll(/(--[\w-]+)\s*:/g)].map(match => match[1]),
+    );
+    const undefinedReferences = [
+      ...css.matchAll(/var\((--x[a-z0-9]+),/g),
+    ].flatMap(match => (defined.has(match[1]) ? [] : [match[0]]));
+    // Covers the caps and the four alignment-axis gutter margins.
+    expect(undefinedReferences).toEqual([]);
+  });
+
+  it('caps both axes against the dynamic viewport and the safe-area gutters', async () => {
+    const css = await compileStylesheet();
+    const blockCaps = declarations(css, 'max-height');
+    const inlineCaps = declarations(css, 'max-width');
+
+    expect(blockCaps).toContainEqual(
+      expect.stringMatching(/^calc\(calc\(100dvb - .*safe-area-inset-top/),
+    );
+    expect(inlineCaps).toContainEqual(
+      expect.stringMatching(/^calc\(calc\(100vi - .*safe-area-inset-left/),
+    );
+    // The older-engine fallbacks still ship, ahead of the preferred value.
+    expect(blockCaps).toContainEqual(
+      expect.stringMatching(/^calc\(calc\(100vh - /),
+    );
+    expect(inlineCaps).toContainEqual(
+      expect.stringMatching(/^calc\(calc\(100vw - /),
+    );
+  });
+});

package/src/Layer/layerViewportInset.stylex.ts

@@ -56,8 +56,12 @@ const GUTTER_BLOCK = `calc(max(${SPACING}, env(safe-area-inset-top, 0px), env(sa
 
 /**
  * The viewport gutter and the caps derived from it. Every value has an
- * `env()`-less fallback for engines without safe-area support; pair them with
- * `stylex.firstThatWorks(cap, capFallback)`.
+ * `env()`-less fallback for engines without safe-area support; pair them as
+ * `stylex.firstThatWorks(`calc(${cap})`, `calc(${capFallback})`)`. Pass
+ * each inside a `calc()` (or another function), never as a bare reference: a
+ * constant reference compiles to a `var()`, and `firstThatWorks` folds two
+ * `var()` arguments into one `var(cap, capFallback)` whose constant is never
+ * inlined, so every engine would take the fallback.
  */
 export const layerViewportInset = stylex.defineConsts({
   /** Gutter from the block-start viewport edge. */

package/src/Layer/layerViewportInset.test.ts

@@ -22,6 +22,7 @@ const GUTTER_OWNERS = new Set([
   'Dialog/Dialog.tsx',
   'Toast/ToastViewport.tsx',
   'BottomSheet/BottomSheetPanel.tsx',
+  'Drawer/Drawer.tsx',
   'Stepper/Step.tsx',
   'Tokenizer/useEndLaneReserve.ts',
 ]);

package/src/Layer/useLayer.tsx

@@ -102,15 +102,17 @@ const styles = stylex.create({
   // The cap is on the layer box itself: content wider than the viewport
   // overflows inside the layer, where the composing component decides
   // whether it scrolls or clips; the box never leaves the viewport.
+  // Each constant is wrapped in `calc()` so both declarations ship (see
+  // layerViewportInset).
   viewportFit: {
     boxSizing: 'border-box',
     maxInlineSize: stylex.firstThatWorks(
-      layerViewportInset.maxInlineSize,
-      layerViewportInset.maxInlineSizeFallback,
+      `calc(${layerViewportInset.maxInlineSize})`,
+      `calc(${layerViewportInset.maxInlineSizeFallback})`,
     ),
     maxBlockSize: stylex.firstThatWorks(
-      layerViewportInset.maxBlockSize,
-      layerViewportInset.maxBlockSizeFallback,
+      `calc(${layerViewportInset.maxBlockSize})`,
+      `calc(${layerViewportInset.maxBlockSizeFallback})`,
     ),
   },
   // Alignment-axis gutter (spec:AST-059 FR1): a margin on the far viewport
@@ -120,26 +122,26 @@ const styles = stylex.create({
   // (see layerSlideRules.ts).
   gutterInlineEnd: {
     marginInlineEnd: stylex.firstThatWorks(
-      layerViewportInset.gutterInline,
-      layerViewportInset.gutterInlineFallback,
+      `calc(${layerViewportInset.gutterInline})`,
+      `calc(${layerViewportInset.gutterInlineFallback})`,
     ),
   },
   gutterInlineStart: {
     marginInlineStart: stylex.firstThatWorks(
-      layerViewportInset.gutterInline,
-      layerViewportInset.gutterInlineFallback,
+      `calc(${layerViewportInset.gutterInline})`,
+      `calc(${layerViewportInset.gutterInlineFallback})`,
     ),
   },
   gutterBlockEnd: {
     marginBlockEnd: stylex.firstThatWorks(
-      layerViewportInset.gutterBlock,
-      layerViewportInset.gutterBlockFallback,
+      `calc(${layerViewportInset.gutterBlock})`,
+      `calc(${layerViewportInset.gutterBlockFallback})`,
     ),
   },
   gutterBlockStart: {
     marginBlockStart: stylex.firstThatWorks(
-      layerViewportInset.gutterBlock,
-      layerViewportInset.gutterBlockFallback,
+      `calc(${layerViewportInset.gutterBlock})`,
+      `calc(${layerViewportInset.gutterBlockFallback})`,
     ),
   },
 });
@@ -760,7 +762,16 @@ function useLayerImplementation(
         // hosted away from its trigger then still takes its sequential focus
         // order (and its popover nesting) from the trigger rather than from
         // its own DOM position. Browsers without the option ignore it.
-        popover.showPopover({source: triggerRef.current ?? undefined});
+        // `source` is declared as an `HTMLElement`. A caller-rendered icon
+        // trigger is an `SVGElement`, whose dictionary conversion throws
+        // before the popover opens. Omitting the option for it still anchors
+        // the layer, because positioning reads the anchor-name pair, and only
+        // gives up the invoker's focus order.
+        const trigger =
+          triggerRef.current instanceof HTMLElement
+            ? triggerRef.current
+            : undefined;
+        popover.showPopover({source: trigger});
       });
     } else {
       popover.style.display = 'block';

package/src/Layer/useLayerDismissal.ts

@@ -98,7 +98,7 @@ export interface UseLayerDismissalReturn {
  * routes each Escape press to the top-most REGISTERED layer, so one press
  * dismisses exactly one of them. Dialog (and what is built on it, including
  * CommandPalette), Popover and the menus built on it, ContextMenu, Tooltip,
- * HoverCard, Lightbox, MobileNav, BottomSheet, BottomSheetSwitcher and lab's
+ * HoverCard, Lightbox, MobileNav, BottomSheet, BottomSheetSwitcher and
  * `Drawer` register today.
  *
  * `DropdownMenuSubMenu` and `PowerSearchEditPopover` still run their own Escape

package/src/Layout/container.stylex.ts

@@ -4,8 +4,8 @@
  * @file container.stylex.ts
  * @input Uses @stylexjs/stylex, spacing from theme
  * @output StyleX utility for layout container styling
- * @position Layout utility; used by Card, Section, Dialog, BottomSheet, and the
- * Lab Drawer
+ * @position Layout utility; used by Card, Section, Dialog, BottomSheet, and
+ * Drawer
  *
  * ## Public API for themes
  *
@@ -19,7 +19,7 @@
  *   --astryx-card-padding-block-end
  *
  * Read order per level: `var(--astryx-…, <next level>)`, terminating at
- * `--spacing-4`. Same pattern for section, dialog, bottom-sheet, and the Lab
+ * `--spacing-4`. Same pattern for section, dialog, bottom-sheet, and
  * drawer.
  *
  * ```ts
@@ -150,7 +150,7 @@ const bottomSheetInlineEnd = `var(--astryx-bottom-sheet-padding-inline-end, ${bo
 const bottomSheetBlockStart = `var(--astryx-bottom-sheet-padding-block-start, ${bottomSheetShorthand})`;
 const bottomSheetBlockEnd = `var(--astryx-bottom-sheet-padding-block-end, ${bottomSheetShorthand})`;
 
-// Drawer (Lab) padding chains: --astryx-* then the next specificity level,
+// Drawer padding chains: --astryx-* then the next specificity level,
 // terminating at --spacing-4 like Dialog. Built as chained const strings (no
 // function calls) so StyleX can statically analyze them; see naming.ts for the
 // prefix policy.
@@ -522,8 +522,8 @@ export interface ContainerOptions {
    * This allows themes to override container padding via component-specific
    * public CSS custom properties without touching internal vars.
    *
-   * Used by Card, Section, Dialog, BottomSheet, and the Lab Drawer when no
-   * explicit padding prop is provided.
+   * Used by Card, Section, Dialog, BottomSheet, and Drawer when no explicit
+   * padding prop is provided.
    * @default undefined (uses explicit spacing token values)
    */
   useThemeDefault?: ContainerComponent;

package/src/List/List.doc.mjs

@@ -41,11 +41,18 @@ export const docs = {
       description: 'Show dividers between items.',
       default: 'false',
     },
+    {
+      name: 'edge',
+      type: "'padded' | 'flush' | 'outset' | 'bleed'",
+      description:
+        "Where each row's text, dividers, and hover and selection backgrounds sit, relative to the list's edges and the container around it. 'padded' keeps text inside each row's padding, so it starts a little in from a heading above the list and backgrounds have room around it. 'flush' drops the rows' side padding: text starts on the heading's line, and dividers and backgrounds stop at the row's content, with no room beyond it on either side. It works anywhere and suits static rows. 'outset' puts text on the heading's line and reaches dividers and backgrounds a little past it into the container's padding; it suits interactive rows in a container. 'bleed' puts text on the heading's line and reaches dividers and backgrounds to the container's edges with square corners, like Table rows in a Card. A row's first content is what lines up with the heading: its marker, icon, or avatar when it has one, otherwise its label. 'outset' and 'bleed' reach into the padding of the nearest container that shares its padding: a Card, Section, Dialog, or BottomSheet, or a transparent container such as a Layout region with explicit padding or a padded ScrollableArea. Place the List directly in that container's padding: padding that Stack, Center, or your own styles add in between is not counted. Drawers and the automatic padding of LayoutContent and LayoutPanel aren't supported yet. With no such container, including in a Popover, they look like 'padded'. In a container with less padding than the rows' own, text starts a little after the heading's line. A theme's inline padding on `item` replaces the row padding of every value, including the zero padding of flush.",
+      default: "'padded'",
+    },
     {
       name: 'edgeCompensation',
       type: "'inline'",
       description:
-        "Compensate for item content inset on each inline edge by cancelling the smaller of each item's built-in horizontal inset and the container's published inline padding. The margin reads the same variable the items derive their inline padding from, so it tracks density and theme padding overrides automatically without pulling rows outside zero-padding or full-bleed surfaces. Use under a section heading to bring row text toward the heading text. Content aligns when container padding is at least the item inset; smaller padding leaves some inset uncompensated. Omit to leave item positions unchanged.",
+        "Deprecated: use edge=\"outset\", which this sets. Still works; edge wins when both are set. `astryx upgrade` rewrites existing usage.",
     },
     {
       name: 'header',
@@ -89,6 +96,8 @@ export const docs = {
     bestPractices: [
       { guidance: true, description: 'Provide a header to label the list and give context to screen readers.' },
       { guidance: true, description: 'Use start and end content slots to add icons, avatars, or badges to each item.' },
+      { guidance: true, description: 'Set edge to line row text up with a heading above the list: flush for static rows, outset or bleed for rows in a Card, Section, or Dialog.' },
+      { guidance: true, description: 'To line text up with a heading and keep room around the highlight where there is no Card, such as a sidebar, put the heading and the list in a Section with variant="transparent" and set edge="outset".' },
       { guidance: false, description: 'Place interactive elements inside an interactive list item; it creates nested click targets and confusing focus behavior.' },
       { guidance: false, description: 'Use a list for a single item or for laying out unrelated content; lists imply a meaningful collection.' },
       { guidance: false, description: 'Mix clickable and non-clickable items in the same list without clear visual distinction.' },
@@ -109,6 +118,8 @@ export const docsZh = {
     bestPractices: [
       { guidance: true, description: 'Provide a header to label the list and give context to screen readers.' },
       { guidance: true, description: 'Use start and end content slots to add icons, avatars, or badges to each item.' },
+      { guidance: true, description: 'Set edge to line row text up with a heading above the list: flush for static rows, outset or bleed for rows in a Card, Section, or Dialog.' },
+      { guidance: true, description: 'To line text up with a heading and keep room around the highlight where there is no Card, such as a sidebar, put the heading and the list in a Section with variant="transparent" and set edge="outset".' },
       { guidance: false, description: 'Place interactive elements inside an interactive list item; it creates nested click targets and confusing focus behavior.' },
       { guidance: false, description: 'Use a list for a single item or for laying out unrelated content; lists imply a meaningful collection.' },
       { guidance: false, description: 'Mix clickable and non-clickable items in the same list without clear visual distinction.' },
@@ -132,6 +143,8 @@ export const docsDense = {
     bestPractices: [
       { guidance: true, description: 'Provide a header to label the list and give context to screen readers.' },
       { guidance: true, description: 'Use start and end content slots to add icons, avatars, or badges to each item.' },
+      { guidance: true, description: 'Set edge to line row text up with a heading above the list: flush for static rows, outset or bleed for rows in a Card, Section, or Dialog.' },
+      { guidance: true, description: 'To line text up with a heading and keep room around the highlight where there is no Card, such as a sidebar, put the heading and the list in a Section with variant="transparent" and set edge="outset".' },
       { guidance: false, description: 'Place interactive elements inside an interactive list item; it creates nested click targets and confusing focus behavior.' },
       { guidance: false, description: 'Use a list for a single item or for laying out unrelated content; lists imply a meaningful collection.' },
       { guidance: false, description: 'Mix clickable and non-clickable items in the same list without clear visual distinction.' },