uikit-react-public 0.49.5 → 0.50.0

package/lib/components/Filters/Filters.stories.tsx

@@ -0,0 +1,354 @@
+import { useState } from 'react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { css } from '@emotion/css';
+import { useTheme } from '../../theme';
+import Datepicker from '../Datepicker';
+import Field from '../Field';
+import Heading from '../Heading';
+import Label from '../Label';
+import { LabelledCheckbox } from '../Checkbox';
+import Select from '../Select';
+import Table from '../Table';
+import Filters from './Filters';
+import Filter from './Filter';
+import QuickFilter from './QuickFilter';
+
+const meta = {
+  title: 'Components/Filters',
+  component: Filters,
+  parameters: {
+    layout: 'padded',
+  },
+  tags: ['autodocs'],
+} satisfies Meta<typeof Filters>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+const records = [
+  {
+    name: 'Annual report',
+    type: 'PDF',
+    status: 'Endangered',
+    retained: '18 September 2026',
+    retainedDate: new Date(2026, 8, 18),
+  },
+  {
+    name: 'Research data',
+    type: 'Spreadsheet',
+    status: 'Stable',
+    retained: '2 August 2026',
+    retainedDate: new Date(2026, 7, 2),
+  },
+  {
+    name: 'Project archive',
+    type: 'ZIP',
+    status: 'Endangered',
+    retained: '14 May 2025',
+    retainedDate: new Date(2025, 4, 14),
+  },
+  {
+    name: 'Meeting notes',
+    type: 'Document',
+    status: 'Stable',
+    retained: '23 January 2025',
+    retainedDate: new Date(2025, 0, 23),
+  },
+];
+
+const DEFAULT_STORY_SOURCE = `const RecordsFilters = () => {
+  const [appliedFileTypes, setAppliedFileTypes] = useState<string[]>([]);
+  const [draftFileTypes, setDraftFileTypes] = useState<string[]>([]);
+
+  const resetFileTypes = () => {
+    setAppliedFileTypes([]);
+    setDraftFileTypes([]);
+  };
+
+  return (
+    <Filters
+      appliedCount={appliedFileTypes.length}
+      onOpenChange={(open) => {
+        if (open) setDraftFileTypes(appliedFileTypes);
+      }}
+      onApply={() => setAppliedFileTypes(draftFileTypes)}
+      onReset={resetFileTypes}
+    >
+      <Filter
+        label='File type'
+        appliedCount={appliedFileTypes.length}
+        onOpenChange={(open) => {
+          if (open) setDraftFileTypes(appliedFileTypes);
+        }}
+        onClear={() => setDraftFileTypes([])}
+        onApply={() => setAppliedFileTypes(draftFileTypes)}
+      >
+        {['PDF', 'Spreadsheet', 'ZIP', 'Document'].map((fileType) => (
+          <LabelledCheckbox
+            key={fileType}
+            checked={draftFileTypes.includes(fileType)}
+            onChange={(event) => {
+              setDraftFileTypes((current) =>
+                event.target.checked
+                  ? [...current, fileType]
+                  : current.filter((value) => value !== fileType)
+              );
+            }}
+          >
+            {fileType}
+          </LabelledCheckbox>
+        ))}
+      </Filter>
+    </Filters>
+  );
+};`;
+
+const datepickerStyle = css`
+  width: 100%;
+`;
+
+const FiltersExample = () => {
+  const [theme] = useTheme();
+  const [appliedStartDate, setAppliedStartDate] = useState<Date | null>(null);
+  const [appliedEndDate, setAppliedEndDate] = useState<Date | null>(null);
+  const [appliedFileTypes, setAppliedFileTypes] = useState<string[]>([]);
+  const [appliedStatus, setAppliedStatus] = useState<string | null>(null);
+  const [draftStartDate, setDraftStartDate] = useState<Date | null>(null);
+  const [draftEndDate, setDraftEndDate] = useState<Date | null>(null);
+  const [draftFileTypes, setDraftFileTypes] = useState<string[]>([]);
+  const [draftStatus, setDraftStatus] = useState<string | null>(null);
+
+  const retentionCount = Number(Boolean(appliedStartDate || appliedEndDate));
+  const appliedCount =
+    retentionCount + appliedFileTypes.length + Number(!!appliedStatus);
+  const visibleRecords = records.filter(
+    (record) =>
+      (!appliedStartDate || record.retainedDate >= appliedStartDate) &&
+      (!appliedEndDate || record.retainedDate <= appliedEndDate) &&
+      (appliedFileTypes.length === 0 ||
+        appliedFileTypes.includes(record.type)) &&
+      (!appliedStatus || record.status === appliedStatus)
+  );
+
+  const syncDrafts = () => {
+    setDraftStartDate(appliedStartDate);
+    setDraftEndDate(appliedEndDate);
+    setDraftFileTypes(appliedFileTypes);
+    setDraftStatus(appliedStatus);
+  };
+
+  const applyAll = () => {
+    setAppliedStartDate(draftStartDate);
+    setAppliedEndDate(draftEndDate);
+    setAppliedFileTypes(draftFileTypes);
+    setAppliedStatus(draftStatus);
+  };
+
+  const resetAll = () => {
+    setAppliedStartDate(null);
+    setAppliedEndDate(null);
+    setAppliedFileTypes([]);
+    setAppliedStatus(null);
+    setDraftStartDate(null);
+    setDraftEndDate(null);
+    setDraftFileTypes([]);
+    setDraftStatus(null);
+  };
+
+  const toggleFileType = (fileType: string, checked: boolean) => {
+    setDraftFileTypes((current) =>
+      checked
+        ? [...current, fileType]
+        : current.filter((value) => value !== fileType)
+    );
+  };
+
+  const pageStyle = css`
+    display: flex;
+    flex-direction: column;
+    gap: ${theme.margin.m24};
+    min-width: 0;
+  `;
+
+  const filterFieldsStyle = css`
+    display: grid;
+    grid-template-columns: repeat(2, minmax(0, 1fr));
+    gap: ${theme.margin.m24};
+  `;
+
+  const filterFieldStyle = css`
+    min-width: 0;
+    width: 100%;
+  `;
+
+  const checkboxGroupStyle = css`
+    display: grid;
+    grid-template-columns: repeat(2, minmax(0, 1fr));
+    gap: ${theme.margin.m8} ${theme.margin.m24};
+  `;
+
+  return (
+    <div className={pageStyle}>
+      <Heading
+        level='lg'
+        as='h2'
+        noMargins
+      >
+        Records
+      </Heading>
+      <Filters
+        appliedCount={appliedCount}
+        onOpenChange={(open) => {
+          if (open) syncDrafts();
+        }}
+        onApply={applyAll}
+        onReset={resetAll}
+      >
+        <Filter
+          label='Retention date'
+          appliedCount={retentionCount}
+          onOpenChange={(open) => {
+            if (!open) return;
+            setDraftStartDate(appliedStartDate);
+            setDraftEndDate(appliedEndDate);
+          }}
+          onClear={() => {
+            setDraftStartDate(null);
+            setDraftEndDate(null);
+          }}
+          onApply={() => {
+            setAppliedStartDate(draftStartDate);
+            setAppliedEndDate(draftEndDate);
+          }}
+          quickFilters={
+            <>
+              <QuickFilter
+                onClick={() => {
+                  setDraftStartDate(new Date(2026, 7, 24));
+                  setDraftEndDate(new Date(2026, 8, 23));
+                }}
+              >
+                Last 30 days
+              </QuickFilter>
+              <QuickFilter
+                onClick={() => {
+                  setDraftStartDate(new Date(2026, 5, 25));
+                  setDraftEndDate(new Date(2026, 8, 23));
+                }}
+              >
+                Last 90 days
+              </QuickFilter>
+              <QuickFilter
+                onClick={() => {
+                  setDraftStartDate(new Date(2025, 8, 23));
+                  setDraftEndDate(new Date(2026, 8, 23));
+                }}
+              >
+                Last year
+              </QuickFilter>
+            </>
+          }
+        >
+          <div className={filterFieldsStyle}>
+            <Field className={filterFieldStyle}>
+              <Label>Start date</Label>
+              <Datepicker
+                value={draftStartDate}
+                onValueChange={setDraftStartDate}
+                clearable
+                className={datepickerStyle}
+              />
+            </Field>
+            <Field className={filterFieldStyle}>
+              <Label>End date</Label>
+              <Datepicker
+                value={draftEndDate}
+                onValueChange={setDraftEndDate}
+                clearable
+                className={datepickerStyle}
+              />
+            </Field>
+          </div>
+        </Filter>
+        <Filter
+          label='File type'
+          appliedCount={appliedFileTypes.length}
+          onOpenChange={(open) => {
+            if (open) setDraftFileTypes(appliedFileTypes);
+          }}
+          onClear={() => setDraftFileTypes([])}
+          onApply={() => setAppliedFileTypes(draftFileTypes)}
+        >
+          <div className={checkboxGroupStyle}>
+            {['PDF', 'Spreadsheet', 'ZIP', 'Document'].map((fileType) => (
+              <LabelledCheckbox
+                key={fileType}
+                checked={draftFileTypes.includes(fileType)}
+                onChange={(event) =>
+                  toggleFileType(fileType, event.target.checked)
+                }
+                noMargins
+              >
+                {fileType}
+              </LabelledCheckbox>
+            ))}
+          </div>
+        </Filter>
+        <Filter
+          label='Endangered status'
+          appliedCount={Number(!!appliedStatus)}
+          onOpenChange={(open) => {
+            if (open) setDraftStatus(appliedStatus);
+          }}
+          onClear={() => setDraftStatus(null)}
+          onApply={() => setAppliedStatus(draftStatus)}
+        >
+          <Field>
+            <Label>Status</Label>
+            <Select<string>
+              options={[
+                { label: 'Endangered', value: 'Endangered' },
+                { label: 'Stable', value: 'Stable' },
+              ]}
+              value={draftStatus}
+              clearable
+              onValueChange={setDraftStatus}
+              placeholder='All statuses'
+              dropdownWidth='match-select'
+            />
+          </Field>
+        </Filter>
+      </Filters>
+      <Table ariaLabel='Filtered records'>
+        <Table.Head>
+          <Table.HeadCell showSortIcon={false}>Name</Table.HeadCell>
+          <Table.HeadCell showSortIcon={false}>File type</Table.HeadCell>
+          <Table.HeadCell showSortIcon={false}>Status</Table.HeadCell>
+          <Table.HeadCell showSortIcon={false}>Retention date</Table.HeadCell>
+        </Table.Head>
+        <Table.Body>
+          {visibleRecords.map((record) => (
+            <Table.Row key={record.name}>
+              <Table.Cell>{record.name}</Table.Cell>
+              <Table.Cell>{record.type}</Table.Cell>
+              <Table.Cell>{record.status}</Table.Cell>
+              <Table.Cell>{record.retained}</Table.Cell>
+            </Table.Row>
+          ))}
+        </Table.Body>
+      </Table>
+    </div>
+  );
+};
+
+export const Default: Story = {
+  render: () => <FiltersExample />,
+  parameters: {
+    docs: {
+      source: {
+        code: DEFAULT_STORY_SOURCE,
+        language: 'tsx',
+      },
+    },
+  },
+};

package/lib/components/Filters/Filters.tsx

@@ -0,0 +1,316 @@
+import {
+  HTMLAttributes,
+  memo,
+  useCallback,
+  useEffect,
+  useId,
+  useMemo,
+  useRef,
+  useState,
+} from 'react';
+import { css, cx } from '@emotion/css';
+import { useTheme } from '../../theme';
+import useMediaQuery from '../../hooks/useMediaQuery';
+import Button from '../Button';
+import Heading from '../Heading';
+import Icon from '../Icon';
+import Overlay from '../Overlay';
+import Filter from './Filter';
+import QuickFilter from './QuickFilter';
+import { FiltersContext } from './Filters.context';
+
+export const NAME = 'ucl-uikit-filters';
+
+export interface FiltersProps extends Omit<
+  HTMLAttributes<HTMLDivElement>,
+  'onChange' | 'onReset'
+> {
+  label?: string;
+  /** Accessible label for the icon-only mobile and tablet trigger. */
+  triggerLabel?: string;
+  appliedCount?: number;
+  open?: boolean;
+  defaultOpen?: boolean;
+  applyDisabled?: boolean;
+  applyLabel?: string;
+  resetLabel?: string;
+  onOpenChange?: (open: boolean) => void;
+  onApply?: React.MouseEventHandler<HTMLButtonElement>;
+  onReset?: React.MouseEventHandler<HTMLButtonElement>;
+  testId?: string;
+}
+
+const FOCUSABLE_SELECTOR =
+  'a[href], button:not([disabled]), textarea:not([disabled]), input:not([disabled]), select:not([disabled]), [tabindex]:not([tabindex="-1"])';
+
+const Filters = ({
+  label = 'Filters',
+  triggerLabel = 'Filters',
+  appliedCount = 0,
+  open,
+  defaultOpen = false,
+  applyDisabled = false,
+  applyLabel = 'Apply filters',
+  resetLabel = 'Reset all',
+  onOpenChange,
+  onApply,
+  onReset,
+  testId = NAME,
+  className,
+  children,
+  ...props
+}: FiltersProps) => {
+  const [theme] = useTheme();
+  const isDesktop = useMediaQuery(
+    `(min-width: ${theme.breakpoints.desktop}px)`
+  );
+  const [internalOpen, setInternalOpen] = useState(defaultOpen);
+  const [activeFilterId, setActiveFilterId] = useState<string | null>(null);
+  const isOpen = open ?? internalOpen;
+  const triggerRef = useRef<HTMLButtonElement>(null);
+  const sheetRef = useRef<HTMLDivElement>(null);
+  const sheetId = useId();
+  const openRef = useRef(open);
+  const onOpenChangeRef = useRef(onOpenChange);
+  openRef.current = open;
+  onOpenChangeRef.current = onOpenChange;
+
+  const setOpen = useCallback((nextOpen: boolean) => {
+    if (openRef.current === undefined) setInternalOpen(nextOpen);
+    onOpenChangeRef.current?.(nextOpen);
+  }, []);
+
+  useEffect(() => {
+    if (isDesktop || !isOpen) return;
+
+    const sheet = sheetRef.current;
+    const previousOverflow = document.body.style.overflow;
+    const previousActiveElement = document.activeElement as HTMLElement | null;
+    document.body.style.overflow = 'hidden';
+
+    const focusableElements = () =>
+      Array.from(
+        sheet?.querySelectorAll<HTMLElement>(FOCUSABLE_SELECTOR) ?? []
+      );
+
+    focusableElements()[0]?.focus();
+
+    const handleKeyDown = (event: KeyboardEvent) => {
+      if (event.key === 'Escape') {
+        setOpen(false);
+        triggerRef.current?.focus();
+        return;
+      }
+
+      if (event.key !== 'Tab') return;
+      const elements = focusableElements();
+      if (elements.length === 0) {
+        event.preventDefault();
+        sheet?.focus();
+        return;
+      }
+
+      const first = elements[0];
+      const last = elements[elements.length - 1];
+      if (event.shiftKey && document.activeElement === first) {
+        event.preventDefault();
+        last.focus();
+      } else if (!event.shiftKey && document.activeElement === last) {
+        event.preventDefault();
+        first.focus();
+      }
+    };
+
+    document.addEventListener('keydown', handleKeyDown);
+
+    return () => {
+      document.body.style.overflow = previousOverflow;
+      document.removeEventListener('keydown', handleKeyDown);
+      if (document.contains(previousActiveElement)) {
+        previousActiveElement?.focus();
+      }
+    };
+  }, [isDesktop, isOpen, setOpen]);
+
+  const contextValue = useMemo(
+    () => ({
+      isDesktop,
+      closeFilters: () => setOpen(false),
+      activeFilterId,
+      setActiveFilterId,
+    }),
+    [activeFilterId, isDesktop, setOpen]
+  );
+
+  const handleApply: React.MouseEventHandler<HTMLButtonElement> = (event) => {
+    onApply?.(event);
+    if (!event.defaultPrevented) setOpen(false);
+  };
+
+  const baseStyle = css`
+    display: flex;
+    align-items: center;
+    gap: ${theme.margin.m16};
+    color: ${theme.colour.text.default};
+  `;
+
+  const desktopStyle = css`
+    flex-wrap: wrap;
+  `;
+
+  const style = cx(NAME, baseStyle, isDesktop && desktopStyle, className);
+
+  const mobileTriggerLabel =
+    appliedCount > 0
+      ? `${triggerLabel}, ${appliedCount} applied`
+      : triggerLabel;
+
+  const mobileOverlayStyle = css`
+    position: fixed;
+    inset: auto 0 0;
+    width: 100vw;
+    max-height: calc(100dvh - ${theme.margin.m32});
+    overflow-y: auto;
+    border-radius: ${theme.radius.r4} ${theme.radius.r4} 0 0;
+    box-sizing: border-box;
+    background-color: ${theme.colour.surface.default};
+    color: ${theme.colour.text.default};
+  `;
+
+  const sheetStyle = css`
+    display: flex;
+    flex-direction: column;
+    gap: ${theme.margin.m16};
+    width: 100%;
+    padding: ${theme.padding.p24} ${theme.padding.p16};
+    box-sizing: border-box;
+  `;
+
+  const handleStyle = css`
+    width: 32px;
+    height: 4px;
+    margin: 0 auto;
+    border-radius: ${theme.radius.r4};
+    background-color: ${theme.colour.border.subtle};
+  `;
+
+  const sheetHeaderStyle = css`
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: ${theme.margin.m16};
+  `;
+
+  const filtersListStyle = css`
+    display: flex;
+    flex-direction: column;
+  `;
+
+  return (
+    <FiltersContext.Provider value={contextValue}>
+      <div
+        className={style}
+        data-testid={testId}
+        {...props}
+      >
+        {isDesktop ? (
+          <>
+            {children}
+            {onReset && (
+              <Button
+                variant='tertiary-no-padding'
+                size='small'
+                onClick={onReset}
+              >
+                {resetLabel}
+              </Button>
+            )}
+          </>
+        ) : (
+          <>
+            <Button
+              ref={triggerRef}
+              variant='secondary'
+              size='medium'
+              selected={isOpen || appliedCount > 0}
+              icon={<Icon.Filter size={20} />}
+              aria-label={mobileTriggerLabel}
+              aria-haspopup='dialog'
+              aria-expanded={isOpen}
+              aria-controls={sheetId}
+              onClick={() => setOpen(!isOpen)}
+            />
+            {isOpen && (
+              <Overlay
+                reference={triggerRef}
+                positioning='viewport'
+                placement='bottom'
+                blanket
+                flip={false}
+                shift={false}
+                className={mobileOverlayStyle}
+                onBlanketClick={() => setOpen(false)}
+              >
+                <div
+                  ref={sheetRef}
+                  id={sheetId}
+                  className={sheetStyle}
+                  role='dialog'
+                  aria-modal='true'
+                  aria-label={label}
+                  tabIndex={-1}
+                >
+                  <div
+                    className={handleStyle}
+                    aria-hidden='true'
+                  />
+                  <div className={sheetHeaderStyle}>
+                    <Heading
+                      as='h2'
+                      level='md'
+                      noMargins
+                    >
+                      {label}
+                    </Heading>
+                    {onReset && (
+                      <Button
+                        variant='tertiary-no-padding'
+                        size='small'
+                        onClick={onReset}
+                      >
+                        {resetLabel}
+                      </Button>
+                    )}
+                  </div>
+                  <div className={filtersListStyle}>{children}</div>
+                  {onApply && (
+                    <Button
+                      size='small'
+                      fullWidth
+                      disabled={applyDisabled}
+                      onClick={handleApply}
+                    >
+                      {applyLabel}
+                    </Button>
+                  )}
+                </div>
+              </Overlay>
+            )}
+          </>
+        )}
+      </div>
+    </FiltersContext.Provider>
+  );
+};
+
+export interface FiltersSubComponents {
+  Filter: typeof Filter;
+  QuickFilter: typeof QuickFilter;
+}
+
+const FiltersWithSubComponents = Object.assign(memo(Filters), {
+  Filter,
+  QuickFilter,
+});
+
+export default FiltersWithSubComponents;