@astryxdesign/core 0.7.2-canary.fe2c655 → 0.7.2

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';
@@ -18,6 +18,25 @@ import {ListItem} from './ListItem';
 import {ListMarkerScope} from './ListContext';
 
 describe('List', () => {
+  it('forwards ListItem align to its Item row unchanged', () => {
+    render(
+      <List>
+        <ListItem label="Default" data-testid="default" />
+        <ListItem label="Start" align="start" data-testid="start" />
+        <ListItem label="First" align="first-line" data-testid="first" />
+      </List>,
+    );
+    expect(screen.getByTestId('default')).toHaveAttribute(
+      'data-align',
+      'center',
+    );
+    expect(screen.getByTestId('start')).toHaveAttribute('data-align', 'start');
+    expect(screen.getByTestId('first')).toHaveAttribute(
+      'data-align',
+      'first-line',
+    );
+  });
+
   // ===========================================================================
   // Basic rendering
   // ===========================================================================
@@ -258,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.doc.mjs

@@ -88,6 +88,13 @@ export const docs = {
       description:
         'Link relationship tokens. noopener noreferrer are merged automatically for target="_blank".',
     },
+    {
+      name: 'align',
+      type: "'center' | 'start' | 'first-line'",
+      description:
+        'Vertical alignment of the start and end content against the label, passed through to Item unchanged. `first-line` keeps a small mark (a status dot, an icon) level with the first line of a wrapped label. See Item.align.',
+      default: "'center'",
+    },
     {
       name: 'isDisabled',
       type: 'boolean',
@@ -173,6 +180,13 @@ export const docsZh = {
       description:
         '链接关系标记。target="_blank" 会自动合并 noopener noreferrer。',
     },
+    {
+      name: 'align',
+      type: "'center' | 'start' | 'first-line'",
+      description:
+        '起始和结束内容相对于标签的垂直对齐方式，原样传递给 Item。`first-line` 让小标记（状态点、图标）与换行标签的第一行保持水平。参见 Item.align。',
+      default: "'center'",
+    },
     {
       name: 'isDisabled',
       type: 'boolean',
@@ -207,6 +221,8 @@ export const docsDense = {
   description:
     'List item w/ label, description, start/end content slots, interactive patterns.',
   propDescriptions: {
+    align:
+      "Start/end content alignment, passed to Item: 'center' (default), 'start', or 'first-line' (centered on the label's first line).",
     label:
       'Primary content. String auto-truncates; ReactNode renders as given.',
     description: 'Secondary text below label.',