@astryxdesign/core 0.6.2 → 0.6.3-canary.0788c49

package/src/List/List.test.tsx

@@ -3,7 +3,7 @@
 /**
  * @file List.test.tsx
  * @input Uses vitest, @testing-library/react, List, ListItem
- * @output Unit tests for List and ListItem components
+ * @output Unit tests for List and ListItem, including bounded inline edge compensation
  * @position Testing; validates List.tsx and ListItem.tsx implementation
  *
  * SYNC: When modified, update this header
@@ -255,6 +255,122 @@ describe('List', () => {
     expect(item).toHaveAttribute('data-density', 'spacious');
   });
 
+  // ===========================================================================
+  // Inline edge compensation
+  // ===========================================================================
+
+  it('does not apply inline edge compensation styles by default', () => {
+    const {container} = render(
+      <List>
+        <ListItem label="Item" />
+      </List>,
+    );
+    const item = container.querySelector('li')!;
+    expect(item.className).not.toContain('inlineEdgeCompensation');
+  });
+
+  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);
+    for (const item of items) {
+      expect(item.className).toContain('inlineEdgeCompensation');
+    }
+    expect(container.querySelector('ul')!.className).not.toContain(
+      'inlineEdgeCompensation',
+    );
+  });
+
+  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.
+    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();
+    }
+  });
+
+  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('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
+      }
+    }
+    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', () => {
+    const {container} = render(<ListItem label="Standalone" />);
+    expect(container.querySelector('li')!.className).not.toContain(
+      'inlineEdgeCompensation',
+    );
+  });
+
   // ===========================================================================
   // Dividers
   // ===========================================================================

package/src/List/List.tsx

@@ -5,6 +5,7 @@
 /**
  * @file List.tsx
  * @input Uses React, ReactNode, StyleXStyles, theme tokens, ListContext
+ *   with optional inline edge compensation
  * @output Exports List component, ListProps, ListDensity, ListStyle types
  * @position Core implementation; consumed by index.ts, tested by List.test.tsx
  *
@@ -58,6 +59,20 @@ 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.
+   */
+  edgeCompensation?: 'inline';
+
   /**
    * Header content rendered above the list.
    * Semantically associated via aria-labelledby.
@@ -128,6 +143,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.
+ *
  * @example
  * ```
  * <List>
@@ -144,6 +163,7 @@ export function List({
   children,
   density = 'balanced',
   hasDividers = false,
+  edgeCompensation,
   header,
   listStyle = 'none',
   start,
@@ -159,8 +179,8 @@ export function List({
   const Tag = isOrdered ? 'ol' : 'ul';
 
   const contextValue = useMemo(
-    () => ({density, hasDividers, listStyle}),
-    [density, hasDividers, listStyle],
+    () => ({density, hasDividers, listStyle, edgeCompensation}),
+    [density, hasDividers, listStyle, edgeCompensation],
   );
 
   const listElement = (

package/src/List/ListContext.tsx

@@ -5,7 +5,8 @@
 /**
  * @file ListContext.tsx
  * @input Uses React createContext
- * @output Exports ListContext for sharing density between List and ListItem
+ * @output Exports ListContext for sharing density, dividers, marker style,
+ *   and optional inline edge compensation between List and ListItem
  * @position Internal context; consumed by List.tsx and ListItem.tsx
  */
 
@@ -18,6 +19,7 @@ export interface ListContextValue {
   density: ListDensity;
   hasDividers: boolean;
   listStyle: ListMarkerStyle;
+  edgeCompensation?: 'inline';
 }
 
 export const ListContext = createContext<ListContextValue | null>(null);

package/src/List/ListItem.doc.mjs

@@ -67,7 +67,7 @@ export const docs = {
     {
       name: 'href',
       type: 'string',
-      description: 'Link URL; enables the invisible anchor pattern.',
+      description: 'Link URL; enables the invisible anchor pattern. The destination follows the shared navigation rule described on the Link `href` prop.',
     },
     {
       name: 'target',
@@ -174,7 +174,7 @@ export const docsDense = {
     onClick: 'Click handler; enables invisible button pattern.',
     interactiveRef:
       'Ref to a nested control that owns the item\'s keyboard access/action; row delegates surface clicks to it (useClickableContainer), no invisible button/anchor, no second tab stop (WCAG 4.1.2). Mutually exclusive with onClick/href.',
-    href: 'Link URL; enables invisible anchor pattern.',
+    href: 'Link URL; enables invisible anchor pattern. Follows the shared navigation rule (see Link href).',
     target: 'Link target attribute, only when href provided. target="_blank" auto-adds noopener noreferrer.',
     rel: 'Link relationship tokens. noopener noreferrer are merged for target="_blank".',
     isDisabled: 'Disabled state; sets aria-disabled.',

package/src/List/ListItem.source-build.test.mjs

@@ -0,0 +1,41 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file ListItem.source-build.test.mjs
+ * @input Uses Babel, the core StyleX build config, and ListItem source
+ * @output Verifies the divider reset for the last item survives compilation
+ * @position Regression test for the shipped ListItem stylesheet
+ */
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {transformAsync} from '@babel/core';
+import {describe, expect, it} from 'vitest';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const CORE_ROOT = path.resolve(__dirname, '../..');
+const LIST_ITEM_SOURCE = path.join(__dirname, 'ListItem.tsx');
+
+async function compileListItemRules() {
+  const source = await fs.readFile(LIST_ITEM_SOURCE, 'utf8');
+  const result = await transformAsync(source, {
+    babelrc: false,
+    configFile: path.join(CORE_ROOT, 'babel.config.json'),
+    filename: LIST_ITEM_SOURCE,
+  });
+  return (result?.metadata?.stylex ?? []).map(([, rule]) => rule.ltr);
+}
+
+describe('ListItem divider stylesheet', () => {
+  it('emits a :last-child rule that removes the divider after the last item', async () => {
+    const rules = await compileListItemRules();
+
+    // The divider is the item's block-end border. StyleX's default
+    // property-specificity mode silently drops a `borderBlockEnd` shorthand,
+    // so the last-item reset must be a longhand to reach the shipped CSS.
+    expect(rules).toContainEqual(
+      expect.stringMatching(/:last-child\{border-bottom-width:0\}$/),
+    );
+  });
+});

package/src/List/ListItem.tsx

@@ -4,7 +4,7 @@
 
 /**
  * @file ListItem.tsx
- * @input Uses React, ReactNode, StyleXStyles, theme tokens
+ * @input Uses React, ReactNode, StyleXStyles, theme tokens, List edge compensation
  * @output Exports ListItem component, ListItemProps type
  * @position Core implementation; consumed by List, index.ts, tested by List.test.tsx
  *
@@ -124,12 +124,34 @@ 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: {
+    marginInlineStart:
+      'calc(-1 * min(var(--_item-inset-inline), var(--container-padding-inline-start, 0px)))',
+    marginInlineEnd:
+      'calc(-1 * min(var(--_item-inset-inline), var(--container-padding-inline-end, 0px)))',
+  },
   withDivider: {
     borderBlockEndWidth: borderVars['--border-width'],
     borderBlockEndStyle: 'solid',
     borderBlockEndColor: colorVars['--color-border'],
+    // A longhand, not the `borderBlockEnd` shorthand: StyleX's default
+    // property-specificity mode drops border shorthands silently, so the
+    // shorthand never reached the shipped CSS and the last item kept its
+    // divider.
     ':last-child': {
-      borderBlockEnd: 'none',
+      borderBlockEndWidth: 0,
     },
   },
 });
@@ -226,6 +248,7 @@ export function ListItem({
   const density = ctx?.density ?? 'balanced';
   const hasDividers = ctx?.hasDividers ?? false;
   const listStyle = ctx?.listStyle ?? 'none';
+  const edgeCompensation = ctx?.edgeCompensation;
   const hasMarkers = listStyle !== 'none';
 
   const marker =
@@ -262,6 +285,7 @@ export function ListItem({
         hasMarkers && styles.withCounter,
         hasDividers && styles.withDivider,
         hasDividers && embeddedStyles.noRadius,
+        edgeCompensation === 'inline' && styles.inlineEdgeCompensation,
         xstyle,
       ]}
       {...mergeProps(themeProps('list-item'), {className, style})}