@astryxdesign/core 0.7.2-canary.caec7ca → 0.7.2-canary.cbb7fa3

package/src/List/List.test.tsx

@@ -3,14 +3,14 @@
 /**
  * @file List.test.tsx
  * @input Uses vitest, @testing-library/react, List, ListItem
- * @output Unit tests for List and ListItem, including bounded inline edge compensation
+ * @output Unit tests for List and ListItem, including the row edge treatment
  * @position Testing; validates List.tsx and ListItem.tsx implementation
  *
  * SYNC: When modified, update this header
  */
 
 import {describe, it, expect, vi} from 'vitest';
-import {render, screen, waitFor} from '@testing-library/react';
+import {cleanup, render, screen, waitFor} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {rulesDeclaredFor} from '../__tests__/pressState';
 import {List} from './List';
@@ -277,121 +277,171 @@ describe('List', () => {
   });
 
   // ===========================================================================
-  // Inline edge compensation
+  // Edge treatment
   // ===========================================================================
 
-  it('does not apply inline edge compensation styles by default', () => {
+  /** Every injected rule that names one of the element's classes. */
+  function declarationsFor(el: Element): string {
+    return rulesDeclaredFor(el).join('\n').replace(/\s+/g, '');
+  }
+
+  /** The declarations of the row inset variable that reach the row. */
+  function insetDeclarations(item: Element): string[] {
+    return rulesDeclaredFor(item).filter(rule =>
+      rule.includes('--_item-inset-inline:'),
+    );
+  }
+
+  const ZERO_INSET = /--_item-inset-inline:\s*0(px)?\s*;/;
+  const LIST_REACH = [
+    'margin-inline-start:calc(-1*var(--container-padding-inline-start,0px))',
+    'margin-inline-end:calc(-1*var(--container-padding-inline-end,0px))',
+    'width:calc(100%+var(--container-padding-inline-start,0px)+var(--container-padding-inline-end,0px))',
+  ];
+  const OUTSET_ROW = [
+    'margin-inline-start:max(var(--container-padding-inline-start,0px)-var(--_item-inset-inline),0px)',
+    'margin-inline-end:max(var(--container-padding-inline-end,0px)-var(--_item-inset-inline),0px)',
+  ];
+  const BLEED_ROW = [
+    'padding-inline-start:max(var(--container-padding-inline-start,0px),var(--_item-inset-inline))',
+    'padding-inline-end:max(var(--container-padding-inline-end,0px),var(--_item-inset-inline))',
+  ];
+
+  function renderEdge(props: Partial<React.ComponentProps<typeof List>>) {
     const {container} = render(
-      <List>
-        <ListItem label="Item" />
+      <List header={<span>Items</span>} {...props}>
+        <ListItem label="Static" />
+        <ListItem label="Button" onClick={() => {}} />
+        <ListItem label="Link" href="/docs" />
       </List>,
     );
-    const item = container.querySelector('li')!;
-    expect(item.className).not.toContain('inlineEdgeCompensation');
-  });
+    const ul = container.querySelector('ul')!;
+    return {
+      ul,
+      header: ul.parentElement!,
+      items: [...ul.querySelectorAll('li')],
+    };
+  }
 
-  it('applies the clamped cancelling margin to each item when edgeCompensation is inline', () => {
-    // The margin lives on the row element itself — the only place that can
-    // read --_item-inset-inline, which Item sets on the same element (custom
-    // properties cascade downward, so the <ul> cannot read it).
-    const {container} = render(
-      <List edgeCompensation="inline">
-        <ListItem label="Item 1" />
-        <ListItem label="Item 2" />
-      </List>,
-    );
-    const items = container.querySelectorAll('li');
-    expect(items).toHaveLength(2);
+  it('keeps the row padding and leaves the list and rows in place by default', () => {
+    const {ul, items} = renderEdge({});
     for (const item of items) {
-      expect(item.className).toContain('inlineEdgeCompensation');
+      expect(item.className).not.toMatch(/edge(Flush|Outset|Bleed)/);
+      expect(insetDeclarations(item)).toHaveLength(1);
+      expect(insetDeclarations(item)[0]).not.toMatch(ZERO_INSET);
     }
-    expect(container.querySelector('ul')!.className).not.toContain(
-      'inlineEdgeCompensation',
-    );
+    expect(ul.className).not.toContain('reachesContainerPadding');
+    expect(edgeContext(ul)).toBe('padded');
   });
 
-  it('uses the same var-derived cancel for every density', () => {
-    // The cancelling margin reads --_item-inset-inline instead of hardcoding
-    // per-density values, so all densities (and theme paddingInline
-    // overrides on `item`) share one style.
+  /** The edge each row resolved, read from the row's own edge class. */
+  function edgeContext(ul: Element): string {
+    const edges = [...ul.querySelectorAll('li')].map(li => {
+      const match = /edge(Flush|Outset|Bleed)/.exec(li.className);
+      return match ? match[1].toLowerCase() : 'padded';
+    });
+    expect(new Set(edges).size).toBe(1);
+    return edges[0];
+  }
+
+  it('applies one treatment to every row, static or interactive, and never to the header', () => {
+    for (const edge of ['flush', 'outset', 'bleed'] as const) {
+      const {ul, header, items} = renderEdge({edge});
+      expect(items).toHaveLength(3);
+      expect(edgeContext(ul)).toBe(edge);
+      expect(header.className).not.toMatch(/edge|reachesContainerPadding/);
+      cleanup();
+    }
+  });
+
+  it('flush: zeroes the shared inset at every density and leaves the list in place', () => {
     for (const density of ['compact', 'balanced', 'spacious'] as const) {
-      const {container, unmount} = render(
-        <List edgeCompensation="inline" density={density}>
-          <ListItem label="Item" />
-        </List>,
-      );
-      expect(container.querySelector('li')!.className).toContain(
-        'inlineEdgeCompensation',
-      );
-      unmount();
+      const {ul, items} = renderEdge({edge: 'flush', density});
+      expect(ul.className).not.toContain('reachesContainerPadding');
+      for (const item of items) {
+        expect(item).toHaveAttribute('data-density', density);
+        const insets = insetDeclarations(item);
+        expect(insets).toHaveLength(1);
+        expect(insets[0]).toMatch(ZERO_INSET);
+      }
+      cleanup();
     }
   });
 
-  it('does not pull the header when edgeCompensation is inline', () => {
-    // The negative margin lives on the row elements, so the header keeps its
-    // position and the row text aligns up to it.
-    const {container} = render(
-      <List edgeCompensation="inline" header={<span>Items</span>}>
-        <ListItem label="Item" />
-      </List>,
-    );
-    expect(container.querySelector('li')!.className).toContain(
-      'inlineEdgeCompensation',
-    );
-    const ul = container.querySelector('ul')!;
-    expect(ul.className).not.toContain('inlineEdgeCompensation');
-    expect(ul.parentElement?.className).not.toContain('inlineEdgeCompensation');
+  it('outset: the list reaches the container padding and each row steps back in by what its inset does not fill, per edge', () => {
+    // Each edge reads its own container padding var: one var on both edges
+    // over-reaches the other edge under asymmetric padding (16px start /
+    // 4px end), so a selected row would paint past the outer border.
+    const {ul, items} = renderEdge({edge: 'outset'});
+    const listCss = declarationsFor(ul);
+    for (const declaration of LIST_REACH) {
+      expect(listCss).toContain(declaration);
+    }
+    for (const item of items) {
+      const css = declarationsFor(item);
+      for (const declaration of OUTSET_ROW) {
+        expect(css).toContain(declaration);
+      }
+      expect(css).not.toContain(
+        'margin-inline-end:max(var(--container-padding-inline-start',
+      );
+      expect(insetDeclarations(item)[0]).not.toMatch(ZERO_INSET);
+    }
   });
 
-  it('clamps each inline edge against its own container padding var', () => {
-    // Regression for asymmetric container padding (16px start / 4px end):
-    // clamping BOTH margins against --container-padding-inline-start
-    // over-cancels the end edge by the difference, and the selected row
-    // paints past the outer border (RTL mirrors the spill). Each edge must
-    // clamp against its matching var; logical properties keep RTL correct.
-    // jsdom does no real layout, so assert on the injected StyleX CSS
-    // (runtimeInjection is on in the test config).
-    const {container} = render(
-      <List edgeCompensation="inline">
-        <ListItem label="Item" />
-      </List>,
-    );
-    expect(container.querySelector('li')!.className).toContain(
-      'inlineEdgeCompensation',
-    );
-    let out = '';
-    for (const sheet of Array.from(document.styleSheets)) {
-      try {
-        for (const rule of Array.from(sheet.cssRules)) {
-          out += rule.cssText + '\n';
-        }
-      } catch {
-        // ignore cross-origin sheets
+  it('bleed: the list reaches the container padding and rows fill it with text on the padding line, per edge', () => {
+    const {ul, items} = renderEdge({edge: 'bleed'});
+    const listCss = declarationsFor(ul);
+    for (const declaration of LIST_REACH) {
+      expect(listCss).toContain(declaration);
+    }
+    for (const item of items) {
+      const css = declarationsFor(item);
+      for (const declaration of BLEED_ROW) {
+        expect(css).toContain(declaration);
       }
+      expect(css).toContain('border-radius:0');
+      expect(css).not.toMatch(/margin-inline-(start|end):max/);
     }
-    out += Array.from(document.querySelectorAll('style'))
-      .map(s => s.textContent || '')
-      .join('\n');
-    const css = out.replace(/\s+/g, '');
-    expect(css).toContain(
-      'margin-inline-start:calc(-1*min(var(--_item-inset-inline),var(--container-padding-inline-start,0px)))',
-    );
-    expect(css).toContain(
-      'margin-inline-end:calc(-1*min(var(--_item-inset-inline),var(--container-padding-inline-end,0px)))',
-    );
-    // The end edge must not clamp against the start var (the over-cancel).
-    expect(css).not.toContain(
-      'margin-inline-end:calc(-1*min(var(--_item-inset-inline),var(--container-padding-inline-start,0px)))',
-    );
   });
 
-  it('does not apply the cancelling margin to a ListItem outside a List', () => {
+  it('keeps the inline clip on the list for every treatment', () => {
+    for (const edge of ['padded', 'flush', 'outset', 'bleed'] as const) {
+      const {ul} = renderEdge({edge});
+      expect(declarationsFor(ul)).toContain('overflow-x:clip');
+      cleanup();
+    }
+  });
+
+  it('treats the deprecated edgeCompensation="inline" as edge="outset" without a runtime warning', () => {
+    // Plain use is reported statically by the @deprecated type; rendering
+    // never warns merely because the old name is used (spec:AST-017 FR29a).
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const {ul} = renderEdge({edgeCompensation: 'inline'});
+    expect(edgeContext(ul)).toBe('outset');
+    expect(ul.className).toContain('reachesContainerPadding');
+    expect(warn).not.toHaveBeenCalled();
+    warn.mockRestore();
+  });
+
+  it('lets edge win over the deprecated edgeCompensation and warns about the conflict', () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const {ul} = renderEdge({edge: 'flush', edgeCompensation: 'inline'});
+    expect(edgeContext(ul)).toBe('flush');
+    expect(ul.className).not.toContain('reachesContainerPadding');
+    expect(warn).toHaveBeenCalledTimes(1);
+    const message = String(warn.mock.calls[0][0]);
+    expect(message).toContain('`edge` wins');
+    expect(message).toContain('astryx upgrade');
+    warn.mockRestore();
+  });
+
+  it('keeps the inset of a ListItem outside a List', () => {
     const {container} = render(<ListItem label="Standalone" />);
-    expect(container.querySelector('li')!.className).not.toContain(
-      'inlineEdgeCompensation',
+    expect(container.querySelector('li')!.className).not.toMatch(
+      /edge(Flush|Outset|Bleed)/,
     );
   });
-
   // ===========================================================================
   // Dividers
   // ===========================================================================

package/src/List/List.tsx

@@ -4,9 +4,10 @@
 
 /**
  * @file List.tsx
- * @input Uses React, ReactNode, StyleXStyles, theme tokens, ListContext
- *   with optional inline edge compensation
- * @output Exports List component, ListProps, ListDensity, ListStyle types
+ * @input Uses React, ReactNode, StyleXStyles, theme tokens, useDevWarning,
+ *   and ListContext with the row edge treatment
+ * @output Exports List component, ListProps, ListDensity, ListEdge, ListStyle
+ *   types
  * @position Core implementation; consumed by index.ts, tested by List.test.tsx
  *
  * SYNC: When modified, update these files to stay in sync:
@@ -24,13 +25,16 @@ import type {BaseProps} from '../BaseProps';
 import {
   ListContext,
   type ListDensity,
+  type ListEdge,
   type ListMarkerStyle,
 } from './ListContext';
 import {mergeProps} from '../utils';
 import {themeProps} from '../utils/themeProps';
+import {useDevWarning} from '../hooks/useDevWarning';
 
 export {
   type ListDensity,
+  type ListEdge,
   type ListMarkerStyle as ListStyle,
 } from './ListContext';
 
@@ -60,16 +64,39 @@ export interface ListProps extends BaseProps<
   hasDividers?: boolean;
 
   /**
-   * Compensates for each item's built-in inline inset, up to the container
-   * padding available on each edge. Use "inline" to bring row content toward
-   * sibling content such as a section heading. Content aligns when the
-   * container padding is at least the item inset; smaller padding leaves
-   * some inset uncompensated.
-   * The cancelling margin reads the same variable the items derive their
-   * inline padding from, so it tracks density and theme padding overrides
-   * automatically. Hover and selection backgrounds still extend past the
-   * text by the inset.
-   * Omit to leave item positions unchanged.
+   * Where each row's text, dividers, and hover and selection backgrounds sit,
+   * relative to the list's edges and the container around it.
+   * - 'padded': text sits inside each row's padding, so it starts a little in
+   *   from a heading above the list and backgrounds have room around it
+   * - 'flush': rows drop their side padding, so 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. Works anywhere. Suits static rows
+   * - 'outset': text sits on the heading's line, and dividers and backgrounds
+   *   reach a little past it into the container's padding. Suits interactive
+   *   rows in a container
+   * - 'bleed': text sits on the heading's line, and dividers and backgrounds
+   *   reach 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'
+   */
+  edge?: ListEdge;
+
+  /**
+   * @deprecated Use `edge="outset"`, which this sets. Still works; `edge`
+   * wins when both are set. `astryx upgrade` rewrites existing usage.
    */
   edgeCompensation?: 'inline';
 
@@ -121,6 +148,18 @@ const styles = stylex.create({
     // vertical scroller. (StyleX emits the physical longhand of this axis.)
     overflowInline: 'clip',
   },
+  // 'outset' and 'bleed' rows reach into the container's padding. The list
+  // reaches the container's padding edge on each inline edge first, so its
+  // inline clip (above) moves out with the rows instead of cutting them; each
+  // row then places itself inside it. Container padding vars are inherited,
+  // so the list can read them, while the rows' own inset is scoped to the
+  // rows. Missing or reset container padding resolves to zero.
+  reachesContainerPadding: {
+    marginInlineStart: 'calc(-1 * var(--container-padding-inline-start, 0px))',
+    marginInlineEnd: 'calc(-1 * var(--container-padding-inline-end, 0px))',
+    width:
+      'calc(100% + var(--container-padding-inline-start, 0px) + var(--container-padding-inline-end, 0px))',
+  },
   withDividers: {
     gap: 0,
   },
@@ -148,9 +187,10 @@ const dynamicStyles = stylex.create({
  * Renders semantic `<ul>` or `<ol>` elements with configurable density,
  * dividers, marker styles, and an optional header.
  *
- * Set `edgeCompensation="inline"` to compensate for the items' inline inset
- * up to the container padding available on each edge, for alignment with
- * sibling content such as a section heading.
+ * Set `edge` to choose where row text, dividers, and backgrounds sit: inside
+ * each row's padding (`padded`, the default), at the list's edges (`flush`),
+ * on a heading's line with backgrounds reaching into the container's padding
+ * (`outset`), or reaching the container's edges like Table rows (`bleed`).
  *
  * @example
  * ```
@@ -162,12 +202,16 @@ const dynamicStyles = stylex.create({
  *   <ListItem label="First step" />
  *   <ListItem label="Second step" />
  * </List>
+ * <List edge="flush" hasDividers>
+ *   <ListItem label="Solstice Mug" description="Ceramic, 12 oz" />
+ * </List>
  * ```
  */
 export function List({
   children,
   density = 'balanced',
   hasDividers = false,
+  edge: edgeProp,
   edgeCompensation,
   header,
   listStyle = 'none',
@@ -182,10 +226,21 @@ export function List({
   const headerId = useId();
   const isOrdered = listStyle === 'decimal';
   const Tag = isOrdered ? 'ol' : 'ul';
+  // Plain use of the deprecated prop is reported by its @deprecated type;
+  // development warns only when the two names conflict (spec:AST-017 FR29).
+  useDevWarning(
+    'List',
+    '`edge` and the deprecated `edgeCompensation` are both set; `edge` wins. ' +
+      'Remove `edgeCompensation`. `astryx upgrade` rewrites existing usage.',
+    edgeProp != null && edgeCompensation != null,
+  );
+  const edge: ListEdge =
+    edgeProp ?? (edgeCompensation === 'inline' ? 'outset' : 'padded');
+  const reachesContainerPadding = edge === 'outset' || edge === 'bleed';
 
   const contextValue = useMemo(
-    () => ({density, hasDividers, listStyle, edgeCompensation}),
-    [density, hasDividers, listStyle, edgeCompensation],
+    () => ({density, hasDividers, edge, listStyle}),
+    [density, hasDividers, edge, listStyle],
   );
 
   const listElement = (
@@ -211,6 +266,7 @@ export function List({
         stylex.props(
           styles.list,
           hasDividers && styles.withDividers,
+          reachesContainerPadding && styles.reachesContainerPadding,
           listStyle !== 'none' &&
             (start != null && start !== 1
               ? dynamicStyles.counterStart(start - 1)

package/src/List/ListContext.tsx

@@ -5,8 +5,8 @@
 /**
  * @file ListContext.tsx
  * @input Layer-scoped React context
- * @output Exports ListContext for sharing density, dividers, marker style,
- *   and optional inline edge compensation between List and ListItem, and
+ * @output Exports ListContext for sharing density, dividers, the row edge
+ *   treatment, and marker style between List and ListItem, and
  *   ListMarkerScope, which sets the marker for the items inside it, or a
  *   task item's checkbox in its place
  * @position Internal context; consumed by List.tsx and ListItem.tsx
@@ -18,6 +18,12 @@ import {createLayerScopedContext as createContext} from '../Layer/layerScopedCon
 export type ListDensity = 'compact' | 'balanced' | 'spacious';
 export type ListMarkerStyle = 'none' | 'disc' | 'decimal' | 'circle';
 
+/**
+ * Where each row's content and its lines and backgrounds sit relative to the
+ * list's edges and the padding of the container around the list.
+ */
+export type ListEdge = 'padded' | 'flush' | 'outset' | 'bleed';
+
 /**
  * Every marker ListItem draws: the public styles, and the square, letter,
  * and roman markers Markdown's nested lists use (spec:AST-061 DEC-6).
@@ -35,8 +41,8 @@ export interface ListTaskMarker {
 export interface ListContextValue {
   density: ListDensity;
   hasDividers: boolean;
+  edge: ListEdge;
   listStyle: ListMarkerStyle;
-  edgeCompensation?: 'inline';
   /**
    * The marker items draw instead of the one `listStyle` names, set by
    * ListMarkerScope; internal. Ignored when `listStyle` is `'none'`.

package/src/List/ListItem.tsx

@@ -4,9 +4,10 @@
 
 /**
  * @file ListItem.tsx
- * @input Uses React, ReactNode, StyleXStyles, theme tokens, List edge compensation,
- *   CheckboxInput, and the marker or task checkbox a ListMarkerScope sets
- *   (Markdown's nested lists and the task items of mixed lists)
+ * @input Uses React, ReactNode, StyleXStyles, theme tokens, the List row edge
+ *   treatment, CheckboxInput, and the marker or task checkbox a
+ *   ListMarkerScope sets (Markdown's nested lists and the task items of mixed
+ *   lists)
  * @output Exports ListItem component, ListItemProps type
  * @position Core implementation; consumed by List, index.ts, tested by List.test.tsx
  *
@@ -23,6 +24,7 @@
 
 import {use, type ReactNode} from 'react';
 import * as stylex from '@stylexjs/stylex';
+import type {StyleXStyles} from '@stylexjs/stylex';
 import {
   colorVars,
   spacingVars,
@@ -149,23 +151,37 @@ const styles = stylex.create({
   withCounter: {
     counterIncrement: 'astryx-list',
   },
-  // List's inline edge compensation cancels as much of the row's built-in
-  // inline inset as the container padding allows (e.g. under a heading).
-  // The margins read --_item-inset-inline — the same variable Item derives
-  // its paddingInline from — on the row element itself (custom properties
-  // only cascade downward, so the <ul> could not read it). Density changes
-  // and theme paddingInline overrides on `item` move both values together.
-  // Each edge clamps against ITS OWN container padding var: a single
-  // start-var clamp on both margins over-cancels the end edge under
-  // asymmetric container padding (16px start / 4px end) and the selected
-  // row paints past the outer border. Logical properties keep RTL correct,
-  // and a zero-padding/full-bleed surface (min(inset, 0px) = 0px) leaves
-  // the row in place instead of pulling it outside its content edge.
-  inlineEdgeCompensation: {
+  // List's edge treatments. Each reads --_item-inset-inline, the variable
+  // Item derives its paddingInline from, on the row itself (custom properties
+  // only cascade downward, so the <ul> cannot read it); density and theme
+  // paddingInline overrides on `item` move it. Each edge resolves against ITS
+  // OWN container padding var, so asymmetric padding never over-reaches an
+  // edge, and logical properties keep RTL correct.
+  //
+  // 'flush': no inset, so content meets the row's edges.
+  edgeFlush: {
+    '--_item-inset-inline': '0px',
+  },
+  // 'outset': the list reaches the container's padding edge (List.tsx); the
+  // row steps back in by whatever padding its inset does not fill, so the row
+  // reaches min(inset, container padding) past the content line and its text
+  // lands on that line when the padding is at least the inset.
+  edgeOutset: {
     marginInlineStart:
-      'calc(-1 * min(var(--_item-inset-inline), var(--container-padding-inline-start, 0px)))',
+      'max(var(--container-padding-inline-start, 0px) - var(--_item-inset-inline), 0px)',
     marginInlineEnd:
-      'calc(-1 * min(var(--_item-inset-inline), var(--container-padding-inline-end, 0px)))',
+      'max(var(--container-padding-inline-end, 0px) - var(--_item-inset-inline), 0px)',
+  },
+  // 'bleed': the row fills the list, which reaches the container's padding
+  // edge (List.tsx); its text sits on the container's padding line, never
+  // closer to the row's edge than its own inset. Square corners: the row
+  // meets the container's straight sides.
+  edgeBleed: {
+    paddingInlineStart:
+      'max(var(--container-padding-inline-start, 0px), var(--_item-inset-inline))',
+    paddingInlineEnd:
+      'max(var(--container-padding-inline-end, 0px), var(--_item-inset-inline))',
+    borderRadius: 0,
   },
   withDivider: {
     borderBlockEndWidth: borderVars['--border-width'],
@@ -313,8 +329,8 @@ export function ListItem({
   const ctx = use(ListContext);
   const density = ctx?.density ?? 'balanced';
   const hasDividers = ctx?.hasDividers ?? false;
+  const edge = ctx?.edge ?? 'padded';
   const listStyle = ctx?.listStyle ?? 'none';
-  const edgeCompensation = ctx?.edgeCompensation;
   const hasMarkers = listStyle !== 'none';
   // ListMarkerScope may name another marker for this item.
   const markerKind: ListMarker | null =
@@ -370,13 +386,17 @@ export function ListItem({
       isSelected={isSelected}
       align={align}
       density={density}
-      xstyle={[
-        hasMarkers && styles.withCounter,
-        hasDividers && styles.withDivider,
-        hasDividers && embeddedStyles.noRadius,
-        edgeCompensation === 'inline' && styles.inlineEdgeCompensation,
-        xstyle,
-      ]}
+      xstyle={
+        [
+          hasMarkers && styles.withCounter,
+          hasDividers && styles.withDivider,
+          hasDividers && embeddedStyles.noRadius,
+          edge === 'flush' && styles.edgeFlush,
+          edge === 'outset' && styles.edgeOutset,
+          edge === 'bleed' && styles.edgeBleed,
+          xstyle,
+        ] as StyleXStyles
+      }
       {...mergeProps(themeProps('list-item'), {className, style})}
       {...restProps}
     />

package/src/List/index.ts

@@ -12,6 +12,6 @@
  */
 
 export {List} from './List';
-export type {ListProps, ListStyle, ListDensity} from './List';
+export type {ListProps, ListStyle, ListDensity, ListEdge} from './List';
 export {ListItem} from './ListItem';
 export type {ListItemProps} from './ListItem';

package/src/Markdown/Markdown.tsx

@@ -405,6 +405,16 @@ const markdownTableCellStyles = stylex.create({
   code: {
     wordBreak: 'normal',
   },
+  // The grid's outer edge. `dividers="grid"` draws the lines *between* cells
+  // and stops at the table's rim, so without this the top, bottom, and sides
+  // stay open and the grid reads as unfinished. On the table element, not the
+  // wrapper, so `border-collapse: collapse` merges it with the cell lines
+  // into one 1px rule rather than doubling up at the edge.
+  tableOuterEdge: {
+    borderWidth: borderVars['--border-width'],
+    borderStyle: 'solid',
+    borderColor: colorVars['--color-border'],
+  },
 });
 
 /**
@@ -1905,7 +1915,10 @@ function renderBlock(
             ),
           )}
           {...lineStamps}>
-          <Table dividers="rows" textOverflow="wrap">
+          <Table
+            dividers="grid"
+            textOverflow="wrap"
+            xstyle={markdownTableCellStyles.tableOuterEdge}>
             <TableHeader>
               <TableRow>
                 {header?.children.map((h, i) => (

package/src/MetadataList/MetadataList.doc.mjs

@@ -43,8 +43,8 @@ export const docs = {
     {
       name: 'label',
       type: "{ position?: 'start' | 'top', width?: number | string }",
-      description: "Label display configuration. position controls label placement, width sets a custom label column width. Defaults to { position: 'top' } for multi-column layouts.",
-      default: "{ position: 'start' } (single-column) / { position: 'top' } (multi-column)",
+      description: "Label display configuration. position controls label placement, width sets a custom label column width. Defaults to { position: 'top' } for multi-column layouts. Position is ignored in horizontal mode, which always uses { position: 'top' }.",
+      default: "{ position: 'start' } (vertical single-column) / { position: 'top' } (multi-column or horizontal)",
     },
     {
       name: 'maxNumOfItems',