@sproutsocial/seeds-react-list 0.3.41 → 0.4.0

package/src/ListItemContentStyled.tsx

@@ -0,0 +1,59 @@
+import * as React from "react";
+import Box from "@sproutsocial/seeds-react-box";
+import Text from "@sproutsocial/seeds-react-text";
+import { Icon } from "@sproutsocial/seeds-react-icon";
+import type { TypeListItemContentProps } from "./ListItemTypes";
+
+/**
+ * Styled-components implementation of ListItemContent. Used by
+ * ListItemContentHybrid whenever a consumer passes a styled-system prop or a
+ * styled() extension. This is the unchanged legacy rendering path (Box/Text/Icon
+ * composition).
+ */
+const ListItemContentStyled = ({
+  text,
+  details,
+  aside,
+  iconName,
+  iconLabel,
+  actions,
+  ...rest
+}: TypeListItemContentProps) => {
+  return (
+    <Box
+      display="flex"
+      justifyContent="space-between"
+      borderRadius="outer"
+      alignItems="baseline"
+      {...rest}
+    >
+      <Box display="flex" flex="1">
+        {iconName && (
+          <span>
+            <Icon mr={300} name={iconName} size="small" ariaLabel={iconLabel} />
+          </span>
+        )}
+        <Box flex="1">
+          <Text.SmallSubHeadline as="div">{text}</Text.SmallSubHeadline>
+          {details && (
+            <Text.Byline as="div" mt={200}>
+              {details}
+            </Text.Byline>
+          )}
+        </Box>
+      </Box>
+      <Box display="flex" alignItems="center" gap={300} flexShrink={0}>
+        {aside && <Text.Byline as="div">{aside}</Text.Byline>}
+        {actions && (
+          <Box display="flex" alignItems="center">
+            {actions}
+          </Box>
+        )}
+      </Box>
+    </Box>
+  );
+};
+
+ListItemContentStyled.displayName = "ListItemContent";
+
+export default ListItemContentStyled;

package/src/ListItemContentTailwind.tsx

@@ -0,0 +1,56 @@
+import * as React from "react";
+import Text from "@sproutsocial/seeds-react-text";
+import { Icon } from "@sproutsocial/seeds-react-icon";
+import { cn } from "./cn";
+import type { TypeListItemContentProps } from "./ListItemTypes";
+
+/**
+ * Tailwind CSS implementation of ListItemContent. The Box layout scaffolding is
+ * expressed through semantic `seeds-list-item-content*` classes from list.css
+ * (no runtime CSS-in-JS). Text and Icon remain as primitives — the spacing they
+ * previously received via system props (Icon mr, Byline mt) is now applied by
+ * the parent classes so those primitives stay on their own static paths.
+ */
+const ListItemContentTailwind = ({
+  text,
+  details,
+  aside,
+  iconName,
+  iconLabel,
+  actions,
+  className,
+  ...rest
+}: TypeListItemContentProps) => {
+  return (
+    <div
+      className={cn("seeds-list-item-content", className)}
+      {...(rest as React.HTMLAttributes<HTMLDivElement>)}
+    >
+      <div className="seeds-list-item-content-main">
+        {iconName && (
+          <span className="seeds-list-item-content-icon">
+            <Icon name={iconName} size="small" ariaLabel={iconLabel} />
+          </span>
+        )}
+        <div className="seeds-list-item-content-text">
+          <Text.SmallSubHeadline as="div">{text}</Text.SmallSubHeadline>
+          {details && (
+            <Text.Byline as="div" className="seeds-list-item-content-details">
+              {details}
+            </Text.Byline>
+          )}
+        </div>
+      </div>
+      <div className="seeds-list-item-content-aside">
+        {aside && <Text.Byline as="div">{aside}</Text.Byline>}
+        {actions && (
+          <div className="seeds-list-item-content-actions">{actions}</div>
+        )}
+      </div>
+    </div>
+  );
+};
+
+ListItemContentTailwind.displayName = "ListItemContent";
+
+export default ListItemContentTailwind;

package/src/ListItemHybrid.tsx

@@ -0,0 +1,34 @@
+/**
+ * Hybrid ListItem Component
+ * Automatically chooses between Tailwind and styled-components based on props.
+ *
+ * Routes to the styled-components path when a styled-system prop is present
+ * (hasStyledProps) or the component was extended with styled()
+ * (isStyledExtension). Otherwise renders the Tailwind path (preferred — no
+ * runtime CSS-in-JS).
+ *
+ * `isBordered` is a semantic public prop, not a styled-system prop, so it maps
+ * to a class on the Tailwind path and does not force styled-components.
+ */
+import * as React from "react";
+import {
+  hasStyledProps,
+  isStyledExtension,
+} from "@sproutsocial/seeds-react-system-props";
+import type { TypeListItemProps } from "./ListItemTypes";
+import ListItemStyled from "./ListItemStyled";
+import ListItemTailwind from "./ListItemTailwind";
+
+const ListItemHybrid = React.forwardRef<HTMLLIElement, TypeListItemProps>(
+  (props, ref) => {
+    if (hasStyledProps(props) || isStyledExtension(props)) {
+      return <ListItemStyled {...props} ref={ref} />;
+    }
+
+    return <ListItemTailwind {...props} ref={ref} />;
+  }
+);
+
+ListItemHybrid.displayName = "ListItem";
+
+export default ListItemHybrid;

package/src/ListItemStyled.tsx

@@ -0,0 +1,41 @@
+import * as React from "react";
+import Box from "@sproutsocial/seeds-react-box";
+import type { TypeListItemProps } from "./ListItemTypes";
+
+/**
+ * Styled-components implementation of ListItem. Used by ListItemHybrid whenever
+ * a consumer passes a styled-system prop or a styled() extension. This is the
+ * unchanged legacy rendering path (a Box rendered as <li>).
+ */
+const ListItemStyled = React.forwardRef<HTMLLIElement, TypeListItemProps>(
+  ({ isBordered, children, ...rest }, ref) => {
+    return (
+      <Box
+        as="li"
+        // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+        // @ts-ignore legacy ref type mismatch: Box types its ref as a div, but
+        // it renders an <li> here and forwards the ref to that element.
+        ref={ref}
+        borderRadius="outer"
+        {...(isBordered
+          ? {
+              border: 500,
+              borderColor: "container.border.base",
+              p: 300,
+            }
+          : {})}
+        mt={300}
+        // rest carries system props + native <li> attributes. Box is typed to a
+        // div, so the li-specific event-handler element types are widened away;
+        // the ref (on its own line above) is unaffected by this spread cast.
+        {...(rest as Record<string, unknown>)}
+      >
+        {children}
+      </Box>
+    );
+  }
+);
+
+ListItemStyled.displayName = "ListItem";
+
+export default ListItemStyled;

package/src/ListItemTailwind.tsx

@@ -0,0 +1,35 @@
+import * as React from "react";
+import { cn } from "./cn";
+import type { TypeListItemProps } from "./ListItemTypes";
+
+/**
+ * Tailwind CSS implementation of ListItem. Renders an <li> with the semantic
+ * `seeds-list-item` class (plus `seeds-list-item-bordered` when isBordered)
+ * from list.css — no runtime CSS-in-JS.
+ *
+ * The semantic class is placed before the consumer `className` so consumer
+ * utilities can override the layered base styles.
+ */
+const ListItemTailwind = React.forwardRef<HTMLLIElement, TypeListItemProps>(
+  ({ isBordered, children, className, ...rest }, ref) => {
+    const classes = cn(
+      "seeds-list-item",
+      { "seeds-list-item-bordered": !!isBordered },
+      className
+    );
+
+    return (
+      <li
+        ref={ref}
+        className={classes}
+        {...(rest as React.LiHTMLAttributes<HTMLLIElement>)}
+      >
+        {children}
+      </li>
+    );
+  }
+);
+
+ListItemTailwind.displayName = "ListItem";
+
+export default ListItemTailwind;

package/src/ListItemTypes.ts

@@ -1,8 +1,28 @@
 import * as React from "react";
-import type { TypeStyledComponentsCommonProps } from "@sproutsocial/seeds-react-system-props";
+import type {
+  TypeStyledComponentsCommonProps,
+  TypeBorderSystemProps,
+  TypeColorSystemProps,
+  TypeFlexboxSystemProps,
+  TypeGridSystemProps,
+  TypeLayoutSystemProps,
+  TypePositionSystemProps,
+  TypeSpaceSystemProps,
+  TypeTypographySystemProps,
+} from "@sproutsocial/seeds-react-system-props";
 import type { TypeIconName } from "@sproutsocial/seeds-react-icon";
 
-export interface TypeListItemProps extends TypeStyledComponentsCommonProps {
+export interface TypeListItemProps
+  extends Omit<React.LiHTMLAttributes<HTMLLIElement>, "color">,
+    TypeStyledComponentsCommonProps,
+    TypeBorderSystemProps,
+    TypeColorSystemProps,
+    TypeFlexboxSystemProps,
+    TypeGridSystemProps,
+    TypeLayoutSystemProps,
+    TypePositionSystemProps,
+    TypeSpaceSystemProps,
+    TypeTypographySystemProps {
   /** If true, adds a border and padding around the list item which looks like a card or button */
   isBordered?: boolean;
   /** Children to display inside the list item */
@@ -12,7 +32,16 @@ export interface TypeListItemProps extends TypeStyledComponentsCommonProps {
 }
 
 export interface TypeListItemContentProps
-  extends TypeStyledComponentsCommonProps {
+  extends Omit<React.HTMLAttributes<HTMLDivElement>, "color">,
+    TypeStyledComponentsCommonProps,
+    TypeBorderSystemProps,
+    TypeColorSystemProps,
+    TypeFlexboxSystemProps,
+    TypeGridSystemProps,
+    TypeLayoutSystemProps,
+    TypePositionSystemProps,
+    TypeSpaceSystemProps,
+    TypeTypographySystemProps {
   /** Main text displayed as SmallSubheadline */
   text: React.ReactNode;
   /** Details text displayed as Byline below the main text */

package/src/ListStyled.tsx

@@ -0,0 +1,19 @@
+import Container from "./styles";
+import type { TypeListProps } from "./ListTypes";
+
+/**
+ * Styled-components implementation of List. Used by ListHybrid whenever a
+ * consumer passes a styled-system prop or a styled() extension. This is the
+ * unchanged legacy rendering path.
+ */
+const ListStyled = ({ as = "ul", children, ...rest }: TypeListProps) => {
+  return (
+    <Container as={as} {...rest}>
+      {children}
+    </Container>
+  );
+};
+
+ListStyled.displayName = "List";
+
+export default ListStyled;

package/src/ListTailwind.tsx

@@ -0,0 +1,32 @@
+import * as React from "react";
+import { cn } from "./cn";
+import type { TypeListProps } from "./ListTypes";
+
+/**
+ * Tailwind CSS implementation of List. Renders the `as` element (ul/ol) with
+ * the semantic `seeds-list` class from list.css — no runtime CSS-in-JS.
+ *
+ * The semantic class is placed before the consumer `className` so consumer
+ * utilities can override the layered base styles.
+ */
+const ListTailwind = ({
+  as: Element = "ul",
+  children,
+  className,
+  ...rest
+}: TypeListProps) => {
+  return (
+    <Element
+      className={cn("seeds-list", className)}
+      // On the Tailwind path system props are absent at runtime (they route to
+      // the styled path), so the remaining rest is native attributes only.
+      {...(rest as React.HTMLAttributes<HTMLUListElement | HTMLOListElement>)}
+    >
+      {children}
+    </Element>
+  );
+};
+
+ListTailwind.displayName = "List";
+
+export default ListTailwind;

package/src/ListTypes.ts

@@ -1,9 +1,32 @@
 import * as React from "react";
-import type { TypeStyledComponentsCommonProps } from "@sproutsocial/seeds-react-system-props";
+import type {
+  TypeStyledComponentsCommonProps,
+  TypeBorderSystemProps,
+  TypeColorSystemProps,
+  TypeFlexboxSystemProps,
+  TypeGridSystemProps,
+  TypeLayoutSystemProps,
+  TypePositionSystemProps,
+  TypeSpaceSystemProps,
+  TypeTypographySystemProps,
+} from "@sproutsocial/seeds-react-system-props";
 
 export type TypeListElement = "ul" | "ol";
 
-export interface TypeListProps extends TypeStyledComponentsCommonProps {
+export interface TypeListProps
+  extends Omit<
+      React.HTMLAttributes<HTMLUListElement | HTMLOListElement>,
+      "color"
+    >,
+    TypeStyledComponentsCommonProps,
+    TypeBorderSystemProps,
+    TypeColorSystemProps,
+    TypeFlexboxSystemProps,
+    TypeGridSystemProps,
+    TypeLayoutSystemProps,
+    TypePositionSystemProps,
+    TypeSpaceSystemProps,
+    TypeTypographySystemProps {
   /** The HTML element to render as - either "ul" or "ol" */
   as?: TypeListElement;
   /** Array of elements to render as list items */

package/src/__tests__/ListContract.test.tsx

@@ -0,0 +1,137 @@
+import React from "react";
+import { render, screen } from "@sproutsocial/seeds-react-testing-library";
+import { theme } from "@sproutsocial/seeds-react-theme";
+import List from "../List";
+import ListItem from "../ListItem";
+
+/**
+ * Permanent contract tests for List and ListItem.
+ *
+ * These freeze the observable public behavior of both components and must stay
+ * GREEN across the styled-components -> Tailwind hybrid migration. They assert
+ * behavior (element, ordering, spacing, ref, attribute forwarding) rather than
+ * implementation details, so the same file gates both the legacy and hybrid
+ * implementations.
+ */
+
+describe("List contract", () => {
+  it("renders a <ul> by default", () => {
+    const { container } = render(
+      <List>
+        <li>Item</li>
+      </List>
+    );
+    expect(container.querySelector("ul")).toBeInTheDocument();
+    expect(container.querySelector("ol")).not.toBeInTheDocument();
+  });
+
+  it("renders the element named by `as`", () => {
+    const { container } = render(
+      <List as="ol">
+        <li>Item</li>
+      </List>
+    );
+    expect(container.querySelector("ol")).toBeInTheDocument();
+    expect(container.querySelector("ul")).not.toBeInTheDocument();
+  });
+
+  it("resets list styling (no margin, padding, or marker)", () => {
+    // Asserted on the preserved styled path (routed via a styled() extension
+    // className), where the reset values are observable in jest. The default
+    // Tailwind path expresses the same reset through the `seeds-list` class,
+    // whose CSS is verified by the CSS-delivery check.
+    const { container } = render(
+      <List className="sc-reset">
+        <li>Item</li>
+      </List>
+    );
+    const list = container.querySelector("ul") as HTMLElement;
+    expect(list).toHaveStyleRule("margin", "0");
+    expect(list).toHaveStyleRule("padding", "0");
+    expect(list).toHaveStyleRule("list-style", "none");
+  });
+
+  it("forwards native attributes and inline style to the list element", () => {
+    const { container } = render(
+      <List id="my-list" data-testid="list" style={{ color: "red" }}>
+        <li>Item</li>
+      </List>
+    );
+    const list = container.querySelector("ul") as HTMLElement;
+    expect(list).toHaveAttribute("id", "my-list");
+    expect(list).toHaveAttribute("data-testid", "list");
+    expect(list.style.color).toBe("red");
+  });
+
+  it("renders its children", () => {
+    render(
+      <List>
+        <li>First</li>
+        <li>Second</li>
+      </List>
+    );
+    expect(screen.getByText("First")).toBeInTheDocument();
+    expect(screen.getByText("Second")).toBeInTheDocument();
+  });
+});
+
+describe("ListItem contract", () => {
+  it("renders an <li>", () => {
+    const { container } = render(<ListItem>Item</ListItem>);
+    expect(container.querySelector("li")).toBeInTheDocument();
+  });
+
+  it("forwards a ref to the <li> element", () => {
+    const ref = React.createRef<HTMLLIElement>();
+    render(<ListItem ref={ref}>Item</ListItem>);
+    expect(ref.current).toBeInstanceOf(HTMLLIElement);
+  });
+
+  it("applies top margin so items stack with spacing", () => {
+    // Asserted on the preserved styled path (routed via a styled() extension
+    // className), where the token value is observable in jest. The default
+    // Tailwind path expresses the same spacing through the `seeds-list-item`
+    // class.
+    const { container } = render(
+      <ListItem className="sc-spacing">Item</ListItem>
+    );
+    const item = container.querySelector("li") as HTMLElement;
+    expect(item).toHaveStyleRule("margin-top", theme.space[300]);
+  });
+
+  it("adds card-like border and padding when isBordered", () => {
+    // Asserted on the preserved styled path; the default Tailwind path expresses
+    // the same via the `seeds-list-item-bordered` class.
+    const { container } = render(
+      <ListItem className="sc-bordered" isBordered>
+        Item
+      </ListItem>
+    );
+    const item = container.querySelector("li") as HTMLElement;
+    expect(item).toHaveStyleRule("padding", theme.space[300]);
+    expect(item).toHaveStyleRule(
+      "border-color",
+      theme.colors.container.border.base
+    );
+  });
+
+  it("does not add border or padding when not bordered", () => {
+    const { container } = render(
+      <ListItem className="sc-plain">Item</ListItem>
+    );
+    const item = container.querySelector("li") as HTMLElement;
+    expect(item).not.toHaveStyleRule("padding", theme.space[300]);
+  });
+
+  it("forwards native attributes and inline style to the <li>", () => {
+    const { container } = render(
+      <ListItem id="row" data-testid="row" style={{ color: "red" }}>
+        Item
+      </ListItem>
+    );
+    const item = container.querySelector("li") as HTMLElement;
+    expect(item).toHaveAttribute("id", "row");
+    expect(item).toHaveAttribute("data-testid", "row");
+    expect(item.style.color).toBe("red");
+  });
+});

package/src/__tests__/ListItemButton.test.tsx

@@ -0,0 +1,57 @@
+import React from "react";
+import {
+  render,
+  screen,
+  fireEvent,
+} from "@sproutsocial/seeds-react-testing-library";
+import ListItemButton from "../ListItemButton";
+
+/**
+ * Contract + routing tests for the ListItemButton Tailwind hybrid.
+ *
+ * The default (Tailwind) path renders semantic `seeds-list-item-button*`
+ * classes; the styled-components path is retained for system props and styled()
+ * extensions. CSS is mocked in jest, so the Tailwind path is asserted via class
+ * names.
+ */
+
+describe("ListItemButton contract", () => {
+  it("renders its children", () => {
+    render(<ListItemButton>Card body</ListItemButton>);
+    expect(screen.getByText("Card body")).toBeInTheDocument();
+  });
+
+  it("renders an overlay button that fires onClick", () => {
+    const onClick = jest.fn();
+    render(<ListItemButton onClick={onClick}>Card body</ListItemButton>);
+    const button = screen.getByRole("button");
+    fireEvent.click(button);
+    expect(onClick).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe("ListItemButton routing", () => {
+  it("renders the Tailwind path by default", () => {
+    const { container } = render(<ListItemButton>Body</ListItemButton>);
+    expect(container.firstChild).toHaveClass("seeds-list-item-button");
+  });
+
+  it("applies the overlay class to the overlay button", () => {
+    render(<ListItemButton>Body</ListItemButton>);
+    expect(screen.getByRole("button")).toHaveClass(
+      "seeds-list-item-button-overlay"
+    );
+  });
+
+  it("routes to the styled-components path for a styled() extension className", () => {
+    const { container } = render(
+      <ListItemButton className="sc-abc123">Body</ListItemButton>
+    );
+    expect(container.firstChild).not.toHaveClass("seeds-list-item-button");
+  });
+
+  it("routes to the styled-components path when a system prop is present", () => {
+    const { container } = render(<ListItemButton p={300}>Body</ListItemButton>);
+    expect(container.firstChild).not.toHaveClass("seeds-list-item-button");
+  });
+});

package/src/__tests__/ListItemContent.test.tsx

@@ -0,0 +1,92 @@
+import React from "react";
+import { render, screen } from "@sproutsocial/seeds-react-testing-library";
+import ListItemContent from "../ListItemContent";
+
+/**
+ * Contract + routing tests for the ListItemContent Tailwind hybrid.
+ *
+ * The default (Tailwind) path renders semantic `seeds-list-item-content*`
+ * classes; the styled-components path is retained for system props and styled()
+ * extensions. CSS is mocked in jest, so the Tailwind path is asserted via class
+ * names.
+ */
+
+describe("ListItemContent contract", () => {
+  it("renders the main text", () => {
+    render(<ListItemContent text="Headline" />);
+    expect(screen.getByText("Headline")).toBeInTheDocument();
+  });
+
+  it("renders details, aside, and actions when provided", () => {
+    render(
+      <ListItemContent
+        text="Headline"
+        details="Some details"
+        aside="Nov 5"
+        actions={<button>Do</button>}
+      />
+    );
+    expect(screen.getByText("Some details")).toBeInTheDocument();
+    expect(screen.getByText("Nov 5")).toBeInTheDocument();
+    expect(screen.getByRole("button", { name: "Do" })).toBeInTheDocument();
+  });
+
+  it("renders an accessible icon when iconName + iconLabel are given", async () => {
+    const { runA11yCheck } = render(
+      <ListItemContent
+        text="Headline"
+        iconName="tag-solid"
+        iconLabel="Tagged"
+      />
+    );
+    expect(screen.getByLabelText("Tagged")).toBeInTheDocument();
+    await runA11yCheck();
+  });
+
+  it("omits optional slots when not provided", () => {
+    render(<ListItemContent text="Headline" />);
+    expect(screen.queryByText("Some details")).not.toBeInTheDocument();
+  });
+
+  it("spaces details below the headline via a parent-qualified rule", () => {
+    // The details node is a Text.Byline, so it also carries `.seeds-text`
+    // (margin: 0). The details margin only applies because list.css qualifies it
+    // as `.seeds-list-item-content .seeds-list-item-content-details` to outrank
+    // `.seeds-text`. Assert the class and the ancestor the selector depends on
+    // so a future refactor that breaks the nesting fails here.
+    render(<ListItemContent text="Headline" details="Some details" />);
+    const details = screen.getByText("Some details");
+    expect(details).toHaveClass("seeds-list-item-content-details");
+    expect(details.closest(".seeds-list-item-content")).not.toBeNull();
+  });
+});
+
+describe("ListItemContent routing", () => {
+  it("renders the Tailwind path by default", () => {
+    const { container } = render(<ListItemContent text="Headline" />);
+    expect(container.firstChild).toHaveClass("seeds-list-item-content");
+  });
+
+  it("places semantic class before consumer className", () => {
+    const { container } = render(
+      <ListItemContent text="Headline" className="consumer" />
+    );
+    expect((container.firstChild as HTMLElement).className).toBe(
+      "seeds-list-item-content consumer"
+    );
+  });
+
+  it("routes to the styled-components path for a styled() extension className", () => {
+    const { container } = render(
+      <ListItemContent text="Headline" className="sc-abc123" />
+    );
+    // The styled path renders through Box (styled-components), so the outer
+    // element does not carry the semantic Tailwind class.
+    expect(container.firstChild).not.toHaveClass("seeds-list-item-content");
+  });
+
+  it("routes to the styled-components path when a system prop is present", () => {
+    const { container } = render(<ListItemContent text="Headline" p={300} />);
+    expect(container.firstChild).not.toHaveClass("seeds-list-item-content");
+  });
+});