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

package/src/components/icoText/IcoText.stories.tsx

@@ -0,0 +1,47 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { IcoText } from './IcoText';
+
+const meta = {
+  title: 'Components/IcoText',
+  component: IcoText,
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'Use `IcoText.Icon` as a direct child of `IcoText` so it is hoisted into the leading icon rail.',
+      },
+    },
+  },
+} satisfies Meta<typeof IcoText>;
+
+type Story = StoryObj<typeof meta>;
+
+export const WithIconAndParagraph: Story = {
+  render: args => (
+    <IcoText {...args}>
+      <IcoText.Icon name="eye" />
+      <IcoText.Heading>Article heading</IcoText.Heading>
+      <IcoText.Paragraph>Supporting text for an article card layout.</IcoText.Paragraph>
+    </IcoText>
+  ),
+};
+
+export const TextOnly: Story = {
+  render: args => (
+    <IcoText {...args}>
+      <IcoText.Heading>Article heading</IcoText.Heading>
+      <IcoText.Paragraph>Supporting text with no leading icon.</IcoText.Paragraph>
+    </IcoText>
+  ),
+};
+
+export const HeadingWithIcon: Story = {
+  render: args => (
+    <IcoText {...args}>
+      <IcoText.Icon name="eye" />
+      <IcoText.Heading>Heading only</IcoText.Heading>
+    </IcoText>
+  ),
+};
+
+export default meta;

package/src/components/icoText/IcoText.test.tsx

@@ -0,0 +1,41 @@
+import { render, screen, within } from '@testing-library/react';
+import '@testing-library/jest-dom/vitest';
+import { describe, expect, test } from 'vitest';
+import { IcoText } from './IcoText';
+
+describe('IcoText', () => {
+  test('renders icon children before content children and keeps content in the content wrapper', () => {
+    const { container } = render(
+      <IcoText>
+        <IcoText.Heading>Article title</IcoText.Heading>
+        <IcoText.Icon name="eye" screenReaderText="Views" />
+        <IcoText.Paragraph>Helpful supporting copy</IcoText.Paragraph>
+        <span>Metadata</span>
+        <IcoText.Icon name="eye" screenReaderText="More views" />
+      </IcoText>,
+    );
+
+    const root = container.querySelector<HTMLDivElement>('.ds-ico-text');
+    const content = container.querySelector<HTMLDivElement>('.ds-ico-text__content');
+
+    if (!content) {
+      throw new Error('Expected IcoText content wrapper to exist');
+    }
+
+    const iconElements = Array.from(root?.querySelectorAll(':scope > .ds-ico-text__icon') ?? []);
+
+    expect(iconElements).toHaveLength(2);
+    expect(root?.lastElementChild).toBe(content);
+    expect(content.querySelectorAll('.ds-ico-text__icon')).toHaveLength(0);
+    iconElements.forEach((iconElement) => {
+      expect(
+        iconElement.compareDocumentPosition(content) & Node.DOCUMENT_POSITION_FOLLOWING,
+      ).not.toBe(0);
+    });
+
+    expect(within(content).getByRole('heading', { level: 4 })).toHaveTextContent('Article title');
+    expect(within(content).getByText('Helpful supporting copy')).toBeInTheDocument();
+    expect(within(content).getByText('Metadata')).toBeInTheDocument();
+    expect(screen.getAllByRole('img', { hidden: true })).toHaveLength(2);
+  });
+});

package/src/components/icoText/IcoText.tsx

@@ -0,0 +1,93 @@
+import classNames from 'classnames';
+import type { IconName } from 'Components/icon/allowedIcons';
+import { Icon } from 'Components/icon/Icon';
+import { Children, isValidElement } from 'react';
+
+export type IcoTextProps = {
+  children?: React.ReactNode;
+  className?: string;
+};
+
+export type IcoTextHeadingProps = React.HTMLAttributes<HTMLHeadingElement> & {
+  children: React.ReactNode;
+};
+
+export type IcoTextParagraphProps = React.HTMLAttributes<HTMLParagraphElement> & {
+  children: React.ReactNode;
+};
+
+export type IcoTextIconProps = {
+  className?: string;
+  color?: Icon.Props['color'];
+  name: IconName;
+  screenReaderText?: string;
+  size?: 12 | 16 | 24;
+};
+
+const IcoTextHeading = ({
+  children,
+  className,
+  ...rest
+}: IcoTextHeadingProps): React.JSX.Element => (
+  <h4 className={classNames('ds-ico-text__heading', className)} {...rest}>
+    {children}
+  </h4>
+);
+
+const IcoTextParagraph = ({
+  children,
+  className,
+  ...rest
+}: IcoTextParagraphProps): React.JSX.Element => (
+  <p className={classNames('ds-ico-text__paragraph', className)} {...rest}>
+    {children}
+  </p>
+);
+
+const IcoTextIcon = ({
+  className,
+  color,
+  name,
+  screenReaderText,
+  size = 24,
+}: IcoTextIconProps): React.JSX.Element => (
+  <Icon
+    name={name}
+    className={classNames('ds-ico-text__icon', className)}
+    color={color}
+    screenReaderText={screenReaderText}
+    size={size}
+  />
+);
+
+const IcoTextRoot = ({ children, className }: IcoTextProps): React.JSX.Element => {
+  const iconChildren: React.ReactNode[] = [];
+  const contentChildren: React.ReactNode[] = [];
+
+  Children.forEach(children, (child) => {
+    if (isValidElement(child) && child.type === IcoTextIcon) {
+      iconChildren.push(child);
+      return;
+    }
+
+    contentChildren.push(child);
+  });
+
+  return (
+    <div className={classNames('ds-ico-text', className)}>
+      {iconChildren}
+      <div className="ds-ico-text__content">{contentChildren}</div>
+    </div>
+  );
+};
+
+IcoTextHeading.displayName = 'IcoText.Heading';
+IcoTextParagraph.displayName = 'IcoText.Paragraph';
+IcoTextIcon.displayName = 'IcoText.Icon';
+IcoTextRoot.displayName = 'IcoText';
+
+export const IcoText = Object.assign(IcoTextRoot, {
+  Heading: IcoTextHeading,
+  Paragraph: IcoTextParagraph,
+  Icon: IcoTextIcon,
+});

package/src/components/icoText/icoText.scss

@@ -0,0 +1,34 @@
+.ds-ico-text {
+  display: flex;
+  align-items: flex-start;
+  gap: var(--ico-text-spacing-gap-horizontal);
+  width: 100%;
+}
+
+.ds-ico-text__icon {
+  flex-shrink: 0;
+}
+
+.ds-ico-text__content {
+  display: flex;
+  flex: 1 1 auto;
+  min-width: 0;
+  flex-direction: column;
+  gap: var(--ico-text-spacing-gap-vertical);
+}
+
+.ds-ico-text__heading {
+  margin: 0;
+  font-family: var(--type-headings-h4-family);
+  font-size: var(--type-headings-h4-size);
+  font-weight: var(--type-headings-h4-weight);
+  line-height: var(--type-headings-h4-line-height);
+}
+
+.ds-ico-text__paragraph {
+  margin: 0;
+  font-family: var(--type-body-p-family);
+  font-size: var(--type-body-p-size);
+  font-weight: var(--type-body-p-weight);
+  line-height: var(--type-body-line-height);
+}