@astryxdesign/core 0.6.2 → 0.6.3-canary.0899f21

package/src/Link/useLinkComponent.ts

@@ -4,89 +4,61 @@
 
 /**
  * @file useLinkComponent.ts
- * @input React use, useMemo, createElement, forwardRef, LinkContext, LinkComponentType
- * @output Exports useLinkComponent hook
- * @position Hook for resolving the link component in Astryx components
+ * @input Per-component override, LinkProvider context, and navigation props
+ * @output Stable link component with destination checks and custom-router `to` injection
+ * @position Shared native and custom link boundary; rejected destinations render
+ *   as destination-less anchors without invoking a router.
  *
- * Resolution order: per-component `as` prop > LinkProvider context > native `<a>`.
- *
- * When the resolved component is a custom component (not native `<a>`),
- * wraps it to pass `to={href}` alongside `href`. This enables compatibility
- * with routers that use `to` (React Router, TanStack Router)
- * without requiring an adapter component.
- *
- * SYNC: When modified, update these files to stay in sync:
- * - /packages/core/src/Link/index.ts
- * - /packages/core/src/Link/Link.doc.mjs
+ * SYNC: Link.doc.mjs and LinkProvider.doc.mjs describe this boundary.
  */
 
 import {use, useMemo, createElement} from 'react';
 import {LinkContext} from './LinkContext';
+import {isSafeDestination} from '../utils/safeUrl';
 import type {LinkComponentType} from './types';
 
-/**
- * Creates a wrapper component that passes both `href` and `to` props
- * to the underlying link component. This enables routers that use `to`
- * (React Router, TanStack Router) to work without an adapter.
- *
- * The wrapper is transparent: it forwards refs and all other props unchanged.
- * Native `<a>` elements ignore the unknown `to` prop harmlessly.
- */
-function createLinkWithTo(
-  Component: LinkComponentType,
-): LinkComponentType {
-  function LinkWithTo({
+function createSafeLink(Component: LinkComponentType): LinkComponentType {
+  function SafeLink({
     href,
+    to,
     ref,
     ...rest
   }: {
-    href?: string;
-    to?: string;
+    href?: unknown;
+    to?: unknown;
     ref?: React.Ref<unknown>;
   }) {
-    return createElement(Component, {ref, href, to: href, ...rest});
+    // An undefined destination can crash a router or resolve to the current
+    // route. Reject the whole handoff, not just one prop or a fallback value.
+    if (!isSafeDestination(href) || !isSafeDestination(to)) {
+      return createElement('a', {ref, ...rest});
+    }
+    if (Component === 'a') {
+      return createElement('a', {ref, ...rest, href});
+    }
+    return createElement(Component, {ref, ...rest, href, to: to ?? href});
   }
-  LinkWithTo.displayName = `LinkWithTo(${
+  SafeLink.displayName = `SafeLink(${
     typeof Component === 'string'
       ? Component
       : Component.displayName || Component.name || 'Component'
   })`;
-  return LinkWithTo as LinkComponentType;
+  return SafeLink as LinkComponentType;
 }
 
 /**
- * Resolves the link component to use.
- *
- * Priority: `as` prop > `LinkProvider` context > native `<a>`.
- *
- * When the resolved component is a custom component (not the native `<a>`),
- * it is wrapped to receive both `href` and `to` props set to the same value.
- * This allows `to`-based routers (React Router, TanStack Router) to work
- * out of the box without a manual adapter.
- *
- * @param as - Per-component override. If provided, takes highest priority.
- * @returns The resolved link component (with `to` injection for custom components).
+ * Resolve `as`, then LinkProvider, then a native anchor. Both destination props
+ * are checked before rendering; accepted structured values retain identity.
+ * Custom components receive `to={href}` unless an explicit `to` is supplied.
  *
  * @example
  * ```
- * function MyComponent({ as }: { as?: LinkComponentType }) {
- *   const LinkComponent = useLinkComponent(as);
- *   return <LinkComponent href="/foo">Click me</LinkComponent>;
- * }
+ * const LinkComponent = useLinkComponent(as);
+ * return <LinkComponent href="/docs">Documentation</LinkComponent>;
  * ```
  */
-export function useLinkComponent(
-  as?: LinkComponentType,
-): LinkComponentType {
+export function useLinkComponent(as?: LinkComponentType): LinkComponentType {
   const ctx = use(LinkContext);
   const resolved = as ?? ctx?.component ?? 'a';
-
-  // Memoize the wrapper to maintain referential stability.
-  // The wrapper is only created for custom components (not native <a>).
-  return useMemo(() => {
-    if (resolved === 'a') {
-      return 'a';
-    }
-    return createLinkWithTo(resolved);
-  }, [resolved]);
+  return useMemo(() => createSafeLink(resolved), [resolved]);
 }

package/src/List/List.doc.mjs

@@ -41,6 +41,12 @@ export const docs = {
       description: 'Show dividers between items.',
       default: 'false',
     },
+    {
+      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.",
+    },
     {
       name: 'header',
       type: 'ReactNode',

package/src/List/List.spec.md

@@ -0,0 +1,200 @@
+---
+schema_version: 3
+template_version: 5
+kind: component
+id: component:List
+authority: current
+archive_reason: null
+superseded_by: null
+approved_by: cixzhang
+approved_at: 2026-09-21
+owners: [cixzhang]
+review_triggers: [public-api, behavior, layout, theming]
+verified_by:
+  [
+    packages/core/src/List/List.test.tsx,
+    packages/core/src/Item/Item.test.tsx,
+    packages/core/src/theme/derivedVarRegistry.test.ts,
+    packages/core/src/theme/generateThemeRules.test.ts,
+    apps/storybook/stories/List.stories.tsx,
+    scripts/check-knowledge.mjs,
+  ]
+modules: []
+families: []
+design_specs: []
+architecture:
+  [architecture:container-padding, architecture:public-component-api]
+contributing: [contributing:api-conventions]
+system_specs: [spec:AST-002/DEC-1, spec:AST-002/DEC-2]
+---
+
+# List component contract
+
+## Contract at a glance
+
+| Area                    | Contract                                                                                                                                                                                         |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Public contract         | Add optional `edgeCompensation?: 'inline'`; omission preserves current layout.                                                                                                                   |
+| Behavior                | Every ListItem row moves its content toward a neutral host's inline content edges, reaching them when the host inset is at least the Item inset, while retaining Item-owned interaction padding. |
+| End-user impact         | List content can reduce or remove the extra inset beside its optional header and adjacent content without shrinking hover, press, selection, or focus paint.                                     |
+| Builder impact          | Builders opt in only when the List is placed directly in an eligible container-padding host state.                                                                                               |
+| Compatibility/readiness | Additive API; implementation and required real-browser evidence are pending.                                                                                                                     |
+| Review checks           | Reject header movement, unbounded negative margins, duplicated padding values, physical-edge logic, automatic opt-in, or a ListItem-level public prop.                                           |
+| Governing rules         | `architecture:container-padding/INV9–INV11`; `spec:AST-002/DEC-1–DEC-2`.                                                                                                                         |
+
+This table is a review projection; the body below is authoritative.
+
+## Intent
+
+List owns collection-wide edge alignment because its optional header is not
+horizontally inset while every ListItem retains Item's inline padding. The caller
+knows whether the List is placed in a neutral host where these content lines
+should align; List cannot derive that design relationship from its children.
+
+## Compatibility and migration
+
+- Released default preserved: `yes`; omission keeps current List and ListItem geometry.
+- Compatibility class: additive optional prop with no default behavior change.
+- Controlled/uncontrolled behavior: not applicable.
+- Migration decision: `component:List/DEC-1` and `component:List/DEC-2`.
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Ownership boundary
+
+**Owns**
+
+- The collection-wide `edgeCompensation` opt-in and its propagation to every
+  ListItem row.
+- Keeping the optional header in place while moving row content toward its line.
+- The supported relationship between ListItem row geometry and Item's normal
+  density- and theme-aware inline inset.
+
+**Does not own / non-goals**
+
+- Container padding values, nesting, or overlay resets — owned by
+  `architecture:container-padding`.
+- A ListItem-level compensation prop, automatic host detection, full bleed, or
+  arbitrary margin controls.
+- TabList or Button projections.
+
+## Public concepts
+
+| Concept           | Closed values or states | Meaning                                                                                               | Availability by variant/orientation/state               | Default | Owner            | Stability                        | Invalid-value behavior                       |
+| ----------------- | ----------------------- | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | ------- | ---------------- | -------------------------------- | -------------------------------------------- |
+| Edge compensation | omitted, `inline`       | Move row content toward both logical host content edges while retaining row-local interaction padding | Every List density and marker style in an eligible host | omitted | `component:List` | accepted; implementation pending | Other values are rejected by the public type |
+
+## Behavioral and layout contract
+
+| ID  | Invariant                                                                                                                                                                                                                                                                                                                                                         | Basis                                                               | Status                                    |
+| --- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- | ----------------------------------------- |
+| FR1 | List MUST own `edgeCompensation?: 'inline'`; ListItem MUST NOT expose a parallel public prop.                                                                                                                                                                                                                                                                     | `component:List/DEC-1`                                              | Accepted contract; implementation pending |
+| FR2 | Omission MUST preserve current header, list, and row geometry. Enabling `inline` MUST leave the optional header in place and apply one compensation policy to every ListItem, including non-interactive rows.                                                                                                                                                     | Owner direction                                                     | Accepted contract; implementation pending |
+| FR3 | Each row MUST resolve each logical margin independently as the negative smaller of its own component-owned inline inset and the matching available host inset. Missing host inset MUST resolve to zero. Content reaches the host line only when the host inset is at least the row inset; otherwise it moves toward that line without crossing the host boundary. | `architecture:container-padding/INV9–INV10`; `component:List/DEC-2` | Accepted contract; implementation pending |
+| FR4 | The retained row inset MUST come from the same private density- and theme-derived source as Item's applied inline padding. A consumer override of row padding through `xstyle`, `className`, or `style` is outside the alignment guarantee; `edgeCompensation` MUST NOT mirror or infer that arbitrary CSS.                                                       | Shared two-owner geometry contract                                  | Accepted contract; implementation pending |
+| FR5 | Compensation MUST preserve Item's hover, press, selection, focus, content, semantics, and hit target. It MUST NOT make the row a full-bleed surface or pull it past either available host edge.                                                                                                                                                                   | Owner direction                                                     | Accepted contract; implementation pending |
+| FR6 | The opt-in is valid only under a host state whose published inline inset matches its applied padding and whose relevant boundary is visually neutral. Current automatic LayoutContent/LayoutPanel states with known publication mismatch are not eligible until that conformance gap is fixed.                                                                    | `architecture:container-padding/INV8–INV11`                         | Accepted contract; implementation pending |
+
+### Allowed variation
+
+- Density and `item.paddingInline` theme overrides may change the retained inset;
+  compensation follows the same derived value.
+- Container padding may be uniform, asymmetric, zero, or absent; each logical
+  edge resolves independently.
+- Labels, descriptions, markers, start/end content, interactivity, and selection
+  may vary without changing the collection-wide alignment rule.
+
+### Representative states
+
+| State                                | Required invariant                                                                      | Allowed variation                                         |
+| ------------------------------------ | --------------------------------------------------------------------------------------- | --------------------------------------------------------- |
+| Default/omitted                      | Header and every row keep current geometry.                                             | Any current List content and density.                     |
+| Host inset at least Item inset       | Row content reaches the host content line; row-local paint keeps Item padding.          | Uniform or asymmetric inline padding.                     |
+| Smaller, zero, or missing host inset | The row moves only by the available inset and is never pulled beyond the host boundary. | Either logical edge may independently be smaller or zero. |
+| LTR or RTL                           | Logical start/end mapping follows direction without changing the `inline` meaning.      | Writing direction.                                        |
+| Themed Item padding                  | Row padding and compensation move together.                                             | Supported `item.paddingInline` value.                     |
+
+### Transformation and precedence order
+
+- **ORD1 — Host bound.** Read the matching published host inset for each selected
+  logical edge, with missing values falling back to zero.
+- **ORD2 — Local inset.** Resolve Item's component-owned inline inset from density
+  and theme through the same private value that supplies applied padding.
+- **ORD3 — Compensation.** Apply the negative minimum of those values to the row;
+  then compose supported consumer styles without claiming alignment for a consumer
+  override of row inline padding.
+
+### Performance and resources
+
+- **PR1 — CSS geometry only.** Edge compensation MUST add no measurement,
+  observer, listener, state, Effect, or render pass.
+
+## Accessibility contract
+
+- **AR1 — Interaction geometry remains local.** Compensation MUST NOT change the
+  interactive element, accessible role/name/state, focus target, tab order, or
+  hit target.
+- **AR2 — Direction remains logical.** The same `inline` value MUST produce the
+  corresponding mirrored geometry under RTL without changing DOM order.
+
+## Design relationships
+
+| Anatomy or state | Design requirement                                                                                          | Representation authority | Hierarchy role     | Component contract |
+| ---------------- | ----------------------------------------------------------------------------------------------------------- | ------------------------ | ------------------ | ------------------ |
+| Optional header  | Stays on the host content line and is not moved by row compensation.                                        | `component:List/DEC-1`   | Context            | FR2                |
+| ListItem row     | Retains local interaction paint and hit-target padding.                                                     | Item composition         | Supporting surface | FR3–FR5            |
+| Row content      | Moves toward each host content line and reaches it only when the host inset can fully absorb the row inset. | `component:List/DEC-2`   | Prominent          | FR2–FR5            |
+
+## Family and system relationships
+
+- `architecture:container-padding` owns host publication, the shared
+  `edgeCompensation` vocabulary, eligibility, logical-edge semantics, and overlay
+  reset.
+- `architecture:public-component-api` and `spec:AST-002` own public API admission.
+- Item remains the implementation owner of row padding and interaction paint;
+  List owns only the collection-level opt-in and row application.
+
+## Verification map
+
+| Contract         | Verification                                                 | Representative states                                                                                                               | Mutation or failure expectation                                                                          | Audit section       |
+| ---------------- | ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | ------------------- |
+| FR1–FR4          | List, Item, and theme-registry tests                         | omitted/enabled; all densities; theme override; static/interactive rows                                                             | Removing context propagation, duplicating a padding value, or using one host edge for both margins fails | `audit:List/layout` |
+| FR2–FR6, AR1–AR2 | Real-browser List geometry evidence                          | header; LTR/RTL; uniform/asymmetric/zero/missing host inset; host inset smaller/equal/larger than Item inset; hover/selection/focus | Header movement, over-pull, wrong bounded movement, or lost row-local paint fails                        | `audit:List/visual` |
+| Documentation    | `List.doc.mjs`, Storybook, and `scripts/check-knowledge.mjs` | public prop/default and representative composition                                                                                  | Missing or stale contract, docs, or example fails                                                        | `audit:List/docs`   |
+
+## Decision log
+
+### DEC-1 — List owns the collection-wide opt-in
+
+**Reference:** `component:List/DEC-1`
+
+**Decider:** cixzhang, 2026-09-21
+
+The List header and ListItem rows otherwise begin on different content lines.
+Only the caller knows when the containing composition requires alignment, while
+List can apply one consistent decision to every row without exposing Item-level
+configuration.
+
+### DEC-2 — Compensation is row-local and bounded
+
+**Reference:** `component:List/DEC-2`
+
+**Decider:** cixzhang, 2026-09-21
+
+Each row cancels no more than its own component-owned inline inset or the
+matching host inset. When the host inset is at least the row inset, content
+reaches the host content line. When it is smaller, content moves toward that line
+without pulling row paint beyond the host boundary.
+
+Rejected: `isFullBleed`, because the row may stop inside the host padding and the
+name would promise outer-edge bleed that the component does not provide.
+
+## Open questions
+
+None.
+
+## Content boundary
+
+This claim-scoped contract does not duplicate List's complete prop table,
+container-padding internals, consumer examples, implementation steps, or future
+TabList/Button projections. Those remain with their named owners.

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\}$/),
+    );
+  });
+});