@arbor-education/design-system.components 0.13.1 → 0.15.0

package/src/components/card/card.scss

@@ -1,6 +1,15 @@
+.ds-card__icon-click {
+  flex-shrink: 0;
+
+  &.ds-icon-arrow-right {
+    display: none;
+  }
+}
+
 .ds-card__container {
   display: flex;
   width: 100%;
+  margin: 0;
   padding: var(--card-spacing-vertical) var(--card-spacing-horizontal);
   flex-direction: column;
   align-items: flex-start;
@@ -12,18 +21,10 @@
   line-height: var(--line-height-default);
   box-sizing: border-box;
 
-  .ds-card__icon-click {
-    flex-shrink: 0;
-
-    &.ds-icon-arrow-right {
-      display: none;
-    }
-  }
-
   &:hover:not(.ds-card__container--disabled) {
     border: var(--border-weight) solid var(--card-hover-color-border);
     background: var(--card-hover-color-background);
-    box-shadow: 0 4px 12px 0 rgb(32 32 32 / 8%);
+    box-shadow: var(--shadow-small);
 
     .ds-card__icon-click {
       &.ds-icon-chevron-right {
@@ -45,6 +46,10 @@
   &--clickable {
     cursor: pointer;
   }
+
+  &--dense {
+    padding: var(--spacing-small);
+  }
 }
 
 .ds-card__content {
@@ -53,27 +58,9 @@
   align-items: flex-start;
   gap: var(--card-spacing-gap-horizontal);
   width: 100%;
+}
 
-  .ds-card__icon-left {
-    flex-shrink: 0;
-  }
-
-  .ds-card__text {
-    display: flex;
-    flex-direction: column;
-    justify-content: space-between;
-    gap: var(--card-spacing-gap-vertical);
-    flex-grow: 1;
-
-    .ds-card__title {
-      margin: 0;
-      font-family: var(--type-headings-h4-family);
-      font-size: var(--type-headings-h4-size);
-      font-weight: var(--type-headings-h4-weight);
-    }
-
-    .ds-card__paragraph {
-      margin: 0;
-    }
-  }
+.ds-card__body {
+  flex: 1 1 auto;
+  min-width: 0;
 }

package/src/components/formField/inputs/number/NumberInput.test.tsx

@@ -31,6 +31,34 @@ describe('NumberInput component', () => {
     expect(inputElement.value).toBe('12');
   });
 
+  describe('Keyboard controls', () => {
+    test('pressing Enter validates and clamps value to max', () => {
+      render(<NumberInput placeholder="Enter a number" defaultValue="5" min={0} max={10} />);
+      const inputElement = screen.getByPlaceholderText('Enter a number') as HTMLInputElement;
+
+      fireEvent.change(inputElement, { target: { value: '12' } });
+      fireEvent.keyDown(inputElement, { key: 'Enter' });
+
+      expect(inputElement.value).toBe('10');
+    });
+
+    test('ArrowUp increments by step', () => {
+      render(<NumberInput placeholder="Enter a number" defaultValue="10" step={2} />);
+      const inputElement = screen.getByPlaceholderText('Enter a number') as HTMLInputElement;
+
+      fireEvent.keyDown(inputElement, { key: 'ArrowUp' });
+      expect(inputElement.value).toBe('12');
+    });
+
+    test('ArrowDown decrements by step', () => {
+      render(<NumberInput placeholder="Enter a number" defaultValue="10" step={2} />);
+      const inputElement = screen.getByPlaceholderText('Enter a number') as HTMLInputElement;
+
+      fireEvent.keyDown(inputElement, { key: 'ArrowDown' });
+      expect(inputElement.value).toBe('8');
+    });
+  });
+
   describe('Decimal value handling', () => {
     test('handles decimal step values correctly', () => {
       render(<NumberInput placeholder="Enter a number" defaultValue="0.5" step={0.1} />);

package/src/components/formField/inputs/number/NumberInput.tsx

@@ -22,6 +22,7 @@ export const NumberInput = (props: NumberInputProps) => {
     disableSpinners,
     containerClassName,
     value: passedValue = '',
+    onKeyDown,
     ...rest
   } = props;
 
@@ -78,6 +79,19 @@ export const NumberInput = (props: NumberInputProps) => {
     checkOverOrUnderMaxOrMin(value);
   };
 
+  const handleOnKeyDown = (e: React.KeyboardEvent<HTMLInputElement>) => {
+    if (e.key === 'Enter') {
+      handleOnBlur();
+    }
+    if (e.key === 'ArrowUp') {
+      handleSpinner(step);
+    }
+    if (e.key === 'ArrowDown') {
+      handleSpinner(-step);
+    }
+    onKeyDown?.(e);
+  };
+
   return (
     <div className={classNames('ds-number-input__container', {
       'ds-number-input__container--error': hasError,
@@ -109,6 +123,7 @@ export const NumberInput = (props: NumberInputProps) => {
         defaultValue={defaultValue}
         onChange={(e: ChangeEvent<HTMLInputElement>) => handleOnChange(e.currentTarget.value)}
         onBlur={handleOnBlur}
+        onKeyDown={handleOnKeyDown}
         step={step}
         min={min}
         max={max}

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);
+}

package/src/components/kpiCard/KPICard.stories.tsx

@@ -0,0 +1,47 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { KVPList } from 'Components/kvpList/KVPList';
+import { Progress } from 'Components/progress/Progress';
+import { KPICard } from './KPICard';
+
+const meta = {
+  title: 'Components/Card/KPICard',
+  component: KPICard,
+} satisfies Meta<typeof KPICard>;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: {
+    label: 'KPI label text',
+    value: 'XX.X',
+    isPercentage: true,
+  },
+  render: args => (
+    <KPICard {...args}>
+      <KVPList aria-label="Summary values">
+        <KVPList.Row orientation="horizontal">
+          <KVPList.Term>Bar label text</KVPList.Term>
+          <KVPList.Definition prominence="strong">XX.X</KVPList.Definition>
+        </KVPList.Row>
+      </KVPList>
+      <KVPList aria-label="Progress values">
+        <KVPList.Row orientation="horizontal">
+          <KVPList.Term>Bar label text</KVPList.Term>
+          <KVPList.Definition prominence="neutral">X</KVPList.Definition>
+          <KVPList.Definition aria-hidden="true" isRow>
+            <Progress aria-label="Progress bar first" max={100} value={95} />
+          </KVPList.Definition>
+        </KVPList.Row>
+        <KVPList.Row orientation="horizontal">
+          <KVPList.Term>Bar label text</KVPList.Term>
+          <KVPList.Definition prominence="neutral">X</KVPList.Definition>
+          <KVPList.Definition aria-hidden="true" isRow>
+            <Progress aria-label="Progress bar second" max={100} value={95} />
+          </KVPList.Definition>
+        </KVPList.Row>
+      </KVPList>
+    </KPICard>
+  ),
+};
+
+export default meta;

package/src/components/kpiCard/KPICard.test.tsx

@@ -0,0 +1,60 @@
+import { fireEvent, render, screen } from '@testing-library/react';
+import '@testing-library/jest-dom/vitest';
+import { describe, expect, test, vi } from 'vitest';
+import { KPICard } from './KPICard';
+import { KVPList } from 'Components/kvpList/KVPList';
+
+describe('KPICard', () => {
+  test('renders header content and kvp rows', () => {
+    render(
+      <KPICard isPercentage label="Attendance" value="95.4">
+        <KVPList aria-label="Breakdown">
+          <KVPList.Row orientation="horizontal">
+            <KVPList.Term>Summary</KVPList.Term>
+            <KVPList.Definition prominence="strong">95.4</KVPList.Definition>
+          </KVPList.Row>
+        </KVPList>
+      </KPICard>,
+    );
+
+    expect(screen.getByText('Attendance')).toBeInTheDocument();
+    expect(screen.getAllByText('95.4')).toHaveLength(2);
+    expect(screen.getByText('%')).toBeInTheDocument();
+  });
+
+  test('does not render a percentage suffix when isPercentage is false', () => {
+    render(<KPICard label="Attendance" value="95.4" />);
+
+    expect(screen.queryByText('%')).not.toBeInTheDocument();
+  });
+
+  test('uses the shared card shell for click interaction', () => {
+    const handleClick = vi.fn();
+
+    render(<KPICard aria-label="Attendance KPI card" label="Attendance" onClick={handleClick} value="95.4" />);
+
+    fireEvent.click(screen.getByRole('button', { name: 'Attendance KPI card' }));
+
+    expect(handleClick).toHaveBeenCalledTimes(1);
+  });
+
+  test('supports keyboard activation through the shared card shell', () => {
+    const handleClick = vi.fn();
+
+    render(<KPICard aria-label="Attendance KPI card" label="Attendance" onClick={handleClick} value="95.4" />);
+
+    fireEvent.keyDown(screen.getByRole('button', { name: 'Attendance KPI card' }), { key: 'Enter' });
+
+    expect(handleClick).toHaveBeenCalledTimes(1);
+  });
+
+  test('does not invoke click handlers when disabled', () => {
+    const handleClick = vi.fn();
+
+    render(<KPICard aria-label="Attendance KPI card" disabled label="Attendance" onClick={handleClick} value="95.4" />);
+
+    fireEvent.click(screen.getByRole('button', { name: 'Attendance KPI card' }));
+
+    expect(handleClick).not.toHaveBeenCalled();
+  });
+});

package/src/components/kpiCard/KPICard.tsx

@@ -0,0 +1,45 @@
+import { Card, getCardInteractionProps } from 'Components/card/Card';
+
+type KPICardBaseProps = {
+  children?: React.ReactNode;
+  className?: string;
+  label: React.ReactNode;
+  value: React.ReactNode;
+  isPercentage?: boolean;
+  disabled?: boolean;
+};
+
+export type KPICardProps = KPICardBaseProps & Card.InteractionProps;
+
+export const KPICard = (props: KPICardProps): React.JSX.Element => {
+  const {
+    children,
+    className,
+    label,
+    value,
+    isPercentage = false,
+    disabled = false,
+  } = props;
+
+  const content = (
+    <div className="ds-kpi-card">
+      <p className="ds-kpi-card__label">{label}</p>
+      <p className="ds-kpi-card__value">
+        {value}
+        {isPercentage && <span className="ds-kpi-card__suffix">%</span>}
+      </p>
+      {children}
+    </div>
+  );
+
+  return (
+    <Card
+      {...getCardInteractionProps(props)}
+      className={className}
+      disabled={disabled}
+      spacing="dense"
+    >
+      {content}
+    </Card>
+  );
+};

package/src/components/kpiCard/kpiCard.scss

@@ -0,0 +1,35 @@
+.ds-kpi-card {
+  display: grid;
+  width: 100%;
+  grid-template-columns: minmax(0, 1fr) auto;
+  gap: var(--spacing-medium) var(--spacing-small);
+
+  > :not(.ds-kpi-card__label, .ds-kpi-card__value) {
+    grid-column: 1 / -1;
+  }
+}
+
+.ds-kpi-card__label {
+  align-self: end;
+  margin: 0;
+  color: var(--kpi-card-color-text-label);
+  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);
+}
+
+.ds-kpi-card__value {
+  justify-self: end;
+  margin: 0;
+  color: var(--kpi-card-color-text-value);
+  font-family: var(--type-headings-h2-family);
+  font-size: var(--type-headings-h2-size);
+  font-weight: var(--type-headings-h2-weight);
+  line-height: var(--type-headings-h2-line-height);
+}
+
+.ds-kpi-card__suffix {
+  margin-left: var(--spacing-xsmall);
+  font: inherit;
+}

package/src/components/kvpList/KVPList.stories.tsx

@@ -0,0 +1,51 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { Progress } from 'Components/progress/Progress';
+import { KVPList } from './KVPList';
+
+const meta = {
+  title: 'Components/KVPList',
+  component: KVPList,
+} satisfies Meta<typeof KVPList>;
+
+type Story = StoryObj<typeof meta>;
+
+export const Summary: Story = {
+  render: args => (
+    <KVPList {...args} aria-label="Attendance metrics">
+      <KVPList.Row orientation="horizontal">
+        <KVPList.Term>Attendance</KVPList.Term>
+        <KVPList.Definition isPercentage prominence="strong">95</KVPList.Definition>
+      </KVPList.Row>
+    </KVPList>
+  ),
+};
+
+export const WithProgressAndPercentage: Story = {
+  render: args => (
+    <KVPList {...args} aria-label="Attendance breakdown">
+      <KVPList.Row orientation="horizontal">
+        <KVPList.Term>Bar label text</KVPList.Term>
+        <KVPList.Definition isPercentage prominence="neutral">95</KVPList.Definition>
+        <KVPList.Definition aria-hidden="true" isRow>
+          <Progress aria-label="Attendance progress" max={100} value={95} />
+        </KVPList.Definition>
+      </KVPList.Row>
+    </KVPList>
+  ),
+};
+
+export const WithProgressNoPercentage: Story = {
+  render: args => (
+    <KVPList {...args} aria-label="Attendance breakdown without percentage">
+      <KVPList.Row orientation="horizontal">
+        <KVPList.Term>Bar label text</KVPList.Term>
+        <KVPList.Definition prominence="neutral">X</KVPList.Definition>
+        <KVPList.Definition aria-hidden="true" isRow>
+          <Progress aria-label="Attendance progress second" max={100} value={95} />
+        </KVPList.Definition>
+      </KVPList.Row>
+    </KVPList>
+  ),
+};
+
+export default meta;

package/src/components/kvpList/KVPList.test.tsx

@@ -0,0 +1,66 @@
+import '@testing-library/jest-dom/vitest';
+import { render, screen } from '@testing-library/react';
+import { describe, expect, test } from 'vitest';
+import { KVPList } from './KVPList';
+
+describe('KVPList', () => {
+  test('renders term and definition semantics', () => {
+    render(
+      <KVPList aria-label="Attendance metrics">
+        <KVPList.Row orientation="horizontal">
+          <KVPList.Term>Attendance</KVPList.Term>
+          <KVPList.Definition prominence="strong">95</KVPList.Definition>
+        </KVPList.Row>
+      </KVPList>,
+    );
+
+    expect(screen.getByText('Attendance').tagName).toBe('DT');
+    expect(screen.getByText('95').tagName).toBe('DD');
+    expect(screen.getByRole('group', { name: 'Attendance metrics' })).toBeInTheDocument();
+  });
+
+  test('renders a typed percentage suffix', () => {
+    render(
+      <KVPList>
+        <KVPList.Row orientation="horizontal">
+          <KVPList.Term>Attendance</KVPList.Term>
+          <KVPList.Definition isPercentage prominence="neutral">
+            95
+          </KVPList.Definition>
+        </KVPList.Row>
+      </KVPList>,
+    );
+
+    const percentageDefinition = screen.getByText('95').closest('dd');
+
+    expect(screen.getByText('%')).toBeInTheDocument();
+    expect(percentageDefinition).toHaveTextContent('95%');
+  });
+
+  test('supports horizontal rows and row-spanning definitions', () => {
+    const { container } = render(
+      <KVPList>
+        <KVPList.Row orientation="horizontal">
+          <KVPList.Term>Progress</KVPList.Term>
+          <KVPList.Definition isRow>Full width content</KVPList.Definition>
+        </KVPList.Row>
+      </KVPList>,
+    );
+
+    expect(container.querySelector('.ds-kvp-list__row--horizontal')).toBeInTheDocument();
+    expect(container.querySelector('.ds-kvp-list__description--row')).toBeInTheDocument();
+  });
+
+  test('does not add group semantics when no accessible label is provided', () => {
+    render(
+      <KVPList>
+        <KVPList.Row orientation="horizontal">
+          <KVPList.Term>Attendance</KVPList.Term>
+          <KVPList.Definition prominence="strong">95</KVPList.Definition>
+        </KVPList.Row>
+      </KVPList>,
+    );
+
+    expect(screen.queryByRole('group')).not.toBeInTheDocument();
+  });
+});