@arbor-education/design-system.components 0.13.0 → 0.14.0

package/src/components/articleCard/ArticleCard.stories.tsx

@@ -0,0 +1,132 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { fn } from 'storybook/test';
+import { ArticleCard } from './ArticleCard';
+
+const meta = {
+  title: 'Components/Card/ArticleCard',
+  component: ArticleCard,
+} satisfies Meta<typeof ArticleCard>;
+
+type Story = StoryObj<typeof meta>;
+
+export const CardWithTitleAndParagraph: Story = {
+  args: {
+    'title': 'Title of Card',
+    'paragraph': 'Lorem ipsum dolor sit amet consectetur adipiscing elit.',
+    'disabled': false,
+    'onClick': fn(),
+    'onKeyDown': fn(),
+    'aria-label': 'Clickable article card with title and paragraph',
+  },
+};
+
+export const CardWithTitleParagraphAndIcon: Story = {
+  args: {
+    'title': 'Title of Card',
+    'paragraph': 'Lorem ipsum dolor sit amet consectetur adipiscing elit.',
+    'icon': 'eye',
+    'disabled': false,
+    'onClick': fn(),
+    'onKeyDown': fn(),
+    'aria-label': 'Clickable article card with title paragraph and icon',
+  },
+};
+
+export const TheEverythingCard: Story = {
+  args: {
+    'title': 'Title of Card',
+    'paragraph': 'Lorem ipsum dolor sit amet consectetur adipiscing elit.',
+    'icon': 'eye',
+    'disabled': false,
+    'tagText': 'argle bargle',
+    'tagColor': 'orange',
+    'onClick': fn(),
+    'onKeyDown': fn(),
+    'aria-label': 'Clickable article card with all content',
+  },
+};
+
+export const CardWithTitleParagraphAndTag: Story = {
+  args: {
+    'title': 'Title of Card',
+    'paragraph': 'Lorem ipsum dolor sit amet consectetur adipiscing elit.',
+    'disabled': false,
+    'tagText': 'argle bargle',
+    'tagColor': 'orange',
+    'onClick': fn(),
+    'onKeyDown': fn(),
+    'aria-label': 'Clickable article card with title paragraph and tag',
+  },
+};
+
+export const CardWithTitleAndIcon: Story = {
+  args: {
+    'title': 'Title of Card',
+    'icon': 'eye',
+    'disabled': false,
+    'onClick': fn(),
+    'onKeyDown': fn(),
+    'aria-label': 'Clickable article card with title and icon',
+  },
+};
+
+export const CardWithParagraph: Story = {
+  args: {
+    'paragraph': 'Lorem ipsum dolor sit amet consectetur adipiscing elit.',
+    'disabled': false,
+    'onClick': fn(),
+    'onKeyDown': fn(),
+    'aria-label': 'Clickable article card with paragraph',
+  },
+};
+
+export const ClickableDisabledCard: Story = {
+  args: {
+    'title': 'Title of Card',
+    'paragraph': 'Lorem ipsum dolor sit amet consectetur adipiscing elit.',
+    'icon': 'eye',
+    'tagText': 'argle bargle',
+    'tagColor': 'orange',
+    'disabled': true,
+    'onClick': fn(),
+    'onKeyDown': fn(),
+    'aria-label': 'Disabled clickable article card',
+  },
+};
+
+export const UnclickableCard: Story = {
+  args: {
+    title: 'Title of Card',
+    paragraph: 'Lorem ipsum dolor sit amet consectetur adipiscing elit.',
+    icon: 'eye',
+    tagText: 'argle bargle',
+    tagColor: 'orange',
+  },
+};
+
+export const TextOnly: Story = {
+  args: {
+    title: 'Text-only article card',
+    paragraph: 'A compact way to present article-style content in the shared shell.',
+  },
+};
+
+export const LinkedArticle: Story = {
+  args: {
+    title: 'Primary article link',
+    href: '/articles/primary-article-link',
+    paragraph: (
+      <>
+        Read the full article or visit the
+        {' '}
+        <a href="/authors/design-system">author page</a>
+        .
+      </>
+    ),
+    icon: 'eye',
+    tagText: 'Featured',
+    tagColor: 'green',
+  },
+};
+
+export default meta;

package/src/components/articleCard/ArticleCard.test.tsx

@@ -0,0 +1,121 @@
+import { fireEvent, render, screen } from '@testing-library/react';
+import '@testing-library/jest-dom/vitest';
+import { describe, expect, test, vi } from 'vitest';
+import { ArticleCard } from './ArticleCard';
+
+describe('ArticleCard', () => {
+  test('renders the legacy card content composition', () => {
+    const { container } = render(
+      <ArticleCard
+        icon="eye"
+        paragraph="Helpful supporting copy"
+        tagColor="green"
+        tagText="Live"
+        title="Article summary"
+      />,
+    );
+
+    expect(screen.getByRole('article')).toBeInTheDocument();
+    expect(screen.getByRole('heading', { level: 4 })).toHaveTextContent('Article summary');
+    expect(screen.getByText('Helpful supporting copy')).toBeInTheDocument();
+    expect(screen.getByText('Live')).toBeInTheDocument();
+    expect(container.querySelector('.ds-icon-eye')).toBeInTheDocument();
+  });
+
+  test('renders content without an icon', () => {
+    const { container } = render(
+      <ArticleCard
+        paragraph="Helpful supporting copy"
+        title="Article summary"
+      />,
+    );
+
+    expect(screen.getByRole('heading', { level: 4 })).toHaveTextContent('Article summary');
+    expect(container.querySelector('.ds-ico-text__icon')).not.toBeInTheDocument();
+  });
+
+  test('renders a tag when provided', () => {
+    render(
+      <ArticleCard
+        paragraph="Helpful supporting copy"
+        tagColor="orange"
+        tagText="Pinned"
+        title="Article summary"
+      />,
+    );
+
+    expect(screen.getByText('Pinned')).toBeInTheDocument();
+  });
+
+  test('renders a primary title link without button semantics when href is provided', () => {
+    const { container } = render(
+      <ArticleCard
+        href="/articles/linked-article"
+        paragraph={(
+          <>
+            By
+            {' '}
+            <a href="/authors/design-system">Design System Team</a>
+          </>
+        )}
+        title="Linked article"
+      />,
+    );
+
+    expect(screen.getByRole('link', { name: 'Linked article' })).toHaveAttribute(
+      'href',
+      '/articles/linked-article',
+    );
+    expect(screen.getByRole('link', { name: 'Design System Team' })).toHaveAttribute(
+      'href',
+      '/authors/design-system',
+    );
+    expect(container.querySelector('figure')).not.toHaveAttribute('role', 'button');
+  });
+
+  test('suppresses the primary link when disabled even if href is provided', () => {
+    const { container } = render(
+      <ArticleCard
+        disabled
+        href="/articles/linked-article"
+        paragraph="Helpful supporting copy"
+        title="Linked article"
+      />,
+    );
+
+    expect(screen.queryByRole('link', { name: 'Linked article' })).not.toBeInTheDocument();
+    expect(container.querySelector('figure')).not.toHaveAttribute('role', 'button');
+  });
+
+  test('uses the shared card shell for interactivity', () => {
+    const handleClick = vi.fn();
+
+    render(
+      <ArticleCard
+        aria-label="Clickable article card"
+        onClick={handleClick}
+        paragraph="Helpful supporting copy"
+        title="Clickable article"
+      />,
+    );
+
+    const card = screen.getByRole('button', { name: 'Clickable article card' });
+    fireEvent.click(card);
+
+    expect(handleClick).toHaveBeenCalledTimes(1);
+  });
+
+  test('renders as a static figure when not clickable', () => {
+    const { container } = render(
+      <ArticleCard
+        paragraph="Helpful supporting copy"
+        title="Static article"
+      />,
+    );
+
+    const card = container.querySelector('figure');
+
+    expect(card).toBeInTheDocument();
+    expect(card).not.toHaveAttribute('role', 'button');
+  });
+});

package/src/components/articleCard/ArticleCard.tsx

@@ -0,0 +1,100 @@
+import classNames from 'classnames';
+import type { IcoTextIconProps } from 'Components/icoText/IcoText';
+import type { TagColor } from 'Components/tag/Tag';
+import { Tag } from 'Components/tag/Tag';
+import type { IconName } from 'Components/icon/allowedIcons';
+import { Card, getCardInteractionProps } from 'Components/card/Card';
+import { IcoText } from 'Components/icoText/IcoText';
+
+type ArticleCardBaseProps = {
+  className?: string;
+  paragraph?: React.ReactNode;
+  icon?: IconName;
+  iconColor?: IcoTextIconProps['color'];
+  disabled?: boolean;
+  tagText?: string;
+  tagColor?: TagColor;
+  iconScreenReaderText?: string;
+};
+
+type ArticleCardLinkedProps = {
+  'href': string;
+  'title': React.ReactNode;
+  'onClick'?: undefined;
+  'onKeyDown'?: undefined;
+  'aria-label'?: string;
+  'aria-labelledby'?: string;
+};
+
+type ArticleCardCardShellProps = {
+  href?: undefined;
+  title?: React.ReactNode;
+} & Card.InteractionProps;
+
+export type ArticleCardProps = ArticleCardBaseProps & (ArticleCardLinkedProps | ArticleCardCardShellProps);
+
+export const ArticleCard = (props: ArticleCardProps): React.JSX.Element => {
+  const {
+    className,
+    href,
+    title,
+    paragraph,
+    icon,
+    iconColor,
+    iconScreenReaderText,
+    disabled = false,
+    tagText,
+    tagColor,
+  } = props;
+  const hasPrimaryLink = Boolean(href && title && !disabled);
+
+  const cardClassName = classNames({
+    'ds-card__container--article-link': hasPrimaryLink,
+  }, className);
+
+  const cardInteractionProps = hasPrimaryLink
+    ? getCardInteractionProps({
+        'onKeyDown': undefined,
+        'aria-label': props['aria-label'],
+        'aria-labelledby': props['aria-labelledby'],
+      })
+    : getCardInteractionProps(props);
+
+  const content = (
+    <article className="ds-article-card">
+      <IcoText>
+        {icon && (
+          <IcoText.Icon
+            color={iconColor}
+            name={icon}
+            screenReaderText={iconScreenReaderText}
+          />
+        )}
+        {title && (
+          <IcoText.Heading>
+            {hasPrimaryLink
+              ? (
+                  <a className="ds-article-card__primary-link" href={href}>
+                    {title}
+                  </a>
+                )
+              : title}
+          </IcoText.Heading>
+        )}
+        {paragraph && <IcoText.Paragraph>{paragraph}</IcoText.Paragraph>}
+        {tagText && <Tag color={tagColor}>{tagText}</Tag>}
+      </IcoText>
+    </article>
+  );
+
+  return (
+    <Card
+      {...cardInteractionProps}
+      className={cardClassName}
+      disabled={disabled}
+      spacing="default"
+    >
+      {content}
+    </Card>
+  );
+};

package/src/components/articleCard/articleCard.scss

@@ -0,0 +1,39 @@
+.ds-card__container--article-link {
+  position: relative;
+
+  &:not(.ds-card__container--disabled) {
+    cursor: pointer;
+  }
+
+  &:focus-within:not(.ds-card__container--disabled) {
+    border: var(--border-weight) solid var(--card-focus-color-border);
+    background: var(--card-focus-color-background);
+    outline: var(--focus-border) solid var(--card-focus-focus);
+  }
+}
+
+.ds-article-card {
+  width: 100%;
+}
+
+.ds-article-card__primary-link {
+  color: inherit;
+  text-decoration: none;
+
+  &::after {
+    content: '';
+    position: absolute;
+    inset: 0;
+    z-index: 1;
+  }
+
+  &:hover,
+  &:focus-visible {
+    text-decoration: underline;
+  }
+}
+
+.ds-article-card a:not(.ds-article-card__primary-link) {
+  position: relative;
+  z-index: 2;
+}