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

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

package/src/components/kvpList/KVPList.tsx

@@ -0,0 +1,109 @@
+import classNames from 'classnames';
+
+export type KVPListProps = React.HTMLAttributes<HTMLDivElement> & {
+  children?: React.ReactNode;
+};
+
+export type KVPListRowProps = React.HTMLAttributes<HTMLDListElement> & {
+  children?: React.ReactNode;
+  orientation?: 'horizontal' | 'vertical';
+};
+
+export type KVPListTermProps = React.HTMLAttributes<HTMLElement> & {
+  children?: React.ReactNode;
+};
+
+export type KVPListDefinitionProps = React.HTMLAttributes<HTMLElement> & {
+  children?: React.ReactNode;
+  isRow?: boolean;
+  isPercentage?: boolean;
+  prominence?: 'neutral' | 'strong';
+};
+
+const KVPListRoot = ({
+  children,
+  className,
+  role,
+  'aria-label': ariaLabel,
+  'aria-labelledby': ariaLabelledBy,
+  ...rest
+}: KVPListProps): React.JSX.Element => (
+  <div
+    className={classNames('ds-kvp-list', className)}
+    role={role ?? (ariaLabel || ariaLabelledBy ? 'group' : undefined)}
+    aria-label={ariaLabel}
+    aria-labelledby={ariaLabelledBy}
+    {...rest}
+  >
+    {children}
+  </div>
+);
+
+const KVPListRow = ({
+  children,
+  className,
+  orientation = 'vertical',
+  ...rest
+}: KVPListRowProps): React.JSX.Element => (
+  <dl
+    className={classNames(
+      'ds-kvp-list__row',
+      `ds-kvp-list__row--${orientation}`,
+      className,
+    )}
+    {...rest}
+  >
+    {children}
+  </dl>
+);
+
+const KVPListTerm = ({
+  children,
+  className,
+  ...rest
+}: KVPListTermProps): React.JSX.Element => (
+  <dt className={classNames('ds-kvp-list__term', className)} {...rest}>
+    {children}
+  </dt>
+);
+
+const KVPListDefinition = ({
+  children,
+  className,
+  isRow = false,
+  isPercentage = false,
+  prominence = 'neutral',
+  ...rest
+}: KVPListDefinitionProps): React.JSX.Element => (
+  <dd
+    className={classNames(
+      'ds-kvp-list__description',
+      `ds-kvp-list__description--${prominence}`,
+      {
+        'ds-kvp-list__description--row': isRow,
+      },
+      className,
+    )}
+    {...rest}
+  >
+    {children}
+    {isPercentage
+      ? (
+          <span className="ds-kvp-list__suffix">
+            %
+          </span>
+        )
+      : null}
+  </dd>
+);
+
+KVPListRoot.displayName = 'KVPList';
+KVPListRow.displayName = 'KVPList.Row';
+KVPListTerm.displayName = 'KVPList.Term';
+KVPListDefinition.displayName = 'KVPList.Definition';
+
+export const KVPList = Object.assign(KVPListRoot, {
+  Row: KVPListRow,
+  Term: KVPListTerm,
+  Definition: KVPListDefinition,
+});

package/src/components/kvpList/kvpList.scss

@@ -0,0 +1,64 @@
+.ds-kvp-list {
+  display: flex;
+  width: 100%;
+  flex-direction: column;
+  gap: var(--spacing-medium);
+  box-sizing: border-box;
+}
+
+.ds-kvp-list__term,
+.ds-kvp-list__description {
+  margin: 0;
+  flex: 1;
+}
+
+.ds-kvp-list__term,
+.ds-kvp-list__description--neutral {
+  color: var(--kvp-list-color-text-subtle);
+  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-kvp-list__description--strong {
+  color: var(--kvp-list-color-text-strong);
+  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-kvp-list__description--row {
+  flex-basis: 100%;
+  width: 100%;
+}
+
+.ds-kvp-list__suffix {
+  margin-left: var(--spacing-xsmall);
+  font: inherit;
+}
+
+.ds-kvp-list__description {
+  text-align: right;
+}
+
+.ds-kvp-list__row {
+  display: flex;
+  width: 100%;
+  margin: 0;
+  gap: var(--spacing-small);
+
+  &--vertical {
+    flex-direction: column;
+  }
+
+  &--horizontal {
+    flex-wrap: wrap;
+    align-items: center;
+
+    .ds-kvp-list__description:not(.ds-kvp-list__description--row) {
+      flex: 0 0 auto;
+    }
+  }
+}