@arbor-education/design-system.components 0.25.5 → 0.25.6

package/src/components/grid/Grid.test.tsx

@@ -0,0 +1,67 @@
+import { expect, test, describe } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import '@testing-library/jest-dom/vitest';
+import { Grid } from './Grid.js';
+
+describe('Grid', () => {
+  test('renders govuk-main-wrapper class', () => {
+    const { container } = render(<Grid />);
+    expect(container.firstChild).toHaveClass('govuk-main-wrapper');
+  });
+
+  test('renders children', () => {
+    render(<Grid><span>School report</span></Grid>);
+    expect(screen.getByText('School report')).toBeInTheDocument();
+  });
+
+  test('merges custom className with govuk-main-wrapper', () => {
+    const { container } = render(<Grid className="my-layout" />);
+    expect(container.firstChild).toHaveClass('govuk-main-wrapper', 'my-layout');
+  });
+});
+
+describe('Grid.Row', () => {
+  test('renders govuk-grid-row class', () => {
+    const { container } = render(<Grid.Row />);
+    expect(container.firstChild).toHaveClass('govuk-grid-row');
+  });
+
+  test('renders children', () => {
+    render(<Grid.Row><span>Attendance data</span></Grid.Row>);
+    expect(screen.getByText('Attendance data')).toBeInTheDocument();
+  });
+
+  test('merges custom className with govuk-grid-row', () => {
+    const { container } = render(<Grid.Row className="my-row" />);
+    expect(container.firstChild).toHaveClass('govuk-grid-row', 'my-row');
+  });
+});
+
+describe('Grid.Column', () => {
+  test('defaults to govuk-grid-column-full when columnWidth is omitted', () => {
+    const { container } = render(<Grid.Column />);
+    expect(container.firstChild).toHaveClass('govuk-grid-column-full');
+  });
+
+  test('renders children', () => {
+    render(<Grid.Column columnWidth="full"><span>Student profile</span></Grid.Column>);
+    expect(screen.getByText('Student profile')).toBeInTheDocument();
+  });
+
+  test('merges custom className', () => {
+    const { container } = render(<Grid.Column columnWidth="full" className="my-col" />);
+    expect(container.firstChild).toHaveClass('govuk-grid-column-full', 'my-col');
+  });
+
+  test.each([
+    ['full', 'govuk-grid-column-full'],
+    ['one-half', 'govuk-grid-column-one-half'],
+    ['one-third', 'govuk-grid-column-one-third'],
+    ['two-thirds', 'govuk-grid-column-two-thirds'],
+    ['one-quarter', 'govuk-grid-column-one-quarter'],
+    ['three-quarters', 'govuk-grid-column-three-quarters'],
+  ] as const)('applies %s class for columnWidth="%s"', (width, expectedClass) => {
+    const { container } = render(<Grid.Column columnWidth={width} />);
+    expect(container.firstChild).toHaveClass(expectedClass);
+  });
+});

package/src/components/grid/Grid.tsx

@@ -0,0 +1,34 @@
+import classNames from 'classnames';
+import type { ReactNode } from 'react';
+import { GridRow } from './GridRow.js';
+import { GridColumn } from './GridColumn.js';
+
+export type GridProps = {
+  className?: string;
+  children?: ReactNode;
+};
+
+export const Grid = (props: GridProps) => {
+  const {
+    className,
+    children,
+  } = props;
+
+  return (
+    <div
+      className={classNames(
+        'govuk-main-wrapper',
+        className,
+      )}
+    >
+      {children}
+    </div>
+  );
+};
+
+Grid.Row = GridRow;
+Grid.Column = GridColumn;
+
+export namespace Grid {
+  export type Props = GridProps;
+}

package/src/components/grid/GridColumn.tsx

@@ -0,0 +1,31 @@
+import classNames from 'classnames';
+import type { ReactNode } from 'react';
+
+export type GridColumnProps = {
+  className?: string;
+  children?: ReactNode;
+  columnWidth?: 'one-quarter' | 'three-quarters' | 'one-third' | 'two-thirds' | 'one-half' | 'full';
+};
+
+export const GridColumn = (props: GridColumnProps) => {
+  const {
+    className,
+    children,
+    columnWidth = 'full',
+  } = props;
+
+  return (
+    <div
+      className={classNames(
+        `govuk-grid-column-${columnWidth}`,
+        className,
+      )}
+    >
+      {children}
+    </div>
+  );
+};
+
+export namespace GridColumn {
+  export type Props = GridColumnProps;
+}

package/src/components/grid/GridRow.tsx

@@ -0,0 +1,29 @@
+import classNames from 'classnames';
+import type { ReactNode } from 'react';
+
+export type GridRowProps = {
+  className?: string;
+  children?: ReactNode;
+};
+
+export const GridRow = (props: GridRowProps) => {
+  const {
+    className,
+    children,
+  } = props;
+
+  return (
+    <div
+      className={classNames(
+        'govuk-grid-row',
+        className,
+      )}
+    >
+      {children}
+    </div>
+  );
+};
+
+export namespace GridRow {
+  export type Props = GridRowProps;
+}

package/src/docs/Contributing.mdx

@@ -52,6 +52,8 @@ It also automatically adds the component's exports to `src/index.ts` and `src/in
 
 ## Key conventions
 
+Most of these are enforced automatically by ESLint — run `yarn eslint --fix` and let it guide you. A few the linter can't catch are worth knowing.
+
 ### File and directory naming
 
 <table>
@@ -97,6 +99,20 @@ import { Button } from '../../components/button/Button';  // ✗
   </tbody>
 </table>
 
+### Prefer team hooks
+
+Before writing your own hook, check `Utils/hooks` — reuse one that already exists, and reach for one that encapsulates a common pattern rather than hand-rolling it. For example, use `useComponentDidMount` for run-once-on-mount effects rather than `useEffect(fn, [])`. Always give `useEffect` a dependency array, even an empty one.
+
+### One component per file
+
+Keep one component per file. This applies to compound components too: define each part in its own file and assemble the public API in the root component's file by importing the parts. `Table` is a good example — it pulls in `TableHeader`, `TableFooter`, and its cell renderers from their own files. See the **Compound components** design principle below for the API pattern itself.
+
+### Keep comments rare and meaningful
+
+Good code is self-documenting, so comments should be the exception rather than the rule. Before writing one, make the code explain itself instead: choose descriptive names, and lift complex expressions or conditions into well-named constants. A clear name is worth more than a sentence describing it.
+
+Reserve comments for the _why_ behind something unusual — a constraint, a workaround, a non-obvious decision — never the _what_ the code already says plainly. If you feel the need to explain a piece of code, that's often a sign the code itself should be clearer. This matters especially for agent-assisted changes, which tend to over-narrate — strip the running commentary before opening a PR.
+
 ---
 
 ## Design principles

package/src/index.scss

@@ -1,4 +1,5 @@
 @use "../node_modules/react-day-picker/src/style.css";
+@use "../node_modules/govuk-frontend/dist/govuk/objects/grid.import.scss";
 @use "./tokens.scss";
 @use "./global.scss";
 @use "components/breadcrumbs/breadcrumbs.scss";

package/src/index.ts

@@ -89,3 +89,4 @@ export { SlideoverUtils } from 'Utils/SlideoverUtils';
 export { ArborLogo, type ArborLogoProps } from 'Components/arborLogo/ArborLogo';
 export { DataViewCard, type DataViewCardProps } from 'Components/dataViewCard/DataViewCard';
 export { FileUpload, type FileUploadProps } from 'Components/fileUpload/FileUpload';
+export { Grid, type GridProps } from 'Components/grid/Grid';