uikit-react-public 0.49.6 → 0.50.0

package/lib/components/Filters/Filter.tsx

@@ -0,0 +1,327 @@
+import {
+  HTMLAttributes,
+  memo,
+  useCallback,
+  useEffect,
+  useId,
+  useRef,
+  useState,
+  type ReactNode,
+} from 'react';
+import { css, cx } from '@emotion/css';
+import { useTheme } from '../../theme';
+import Button from '../Button';
+import Icon from '../Icon';
+import Overlay from '../Overlay';
+import Text from '../Text';
+import FilterPanel from './FilterPanel';
+import { useFiltersContext } from './Filters.context';
+
+export const NAME = 'ucl-uikit-filter';
+
+export interface FilterProps extends Omit<
+  HTMLAttributes<HTMLDivElement>,
+  'onChange'
+> {
+  label: string;
+  appliedCount?: number;
+  disabled?: boolean;
+  open?: boolean;
+  defaultOpen?: boolean;
+  quickFilters?: ReactNode;
+  clearLabel?: string;
+  applyLabel?: string;
+  applyDisabled?: boolean;
+  onClear?: React.MouseEventHandler<HTMLButtonElement>;
+  onApply?: React.MouseEventHandler<HTMLButtonElement>;
+  panelClassName?: string;
+  onOpenChange?: (open: boolean) => void;
+  testId?: string;
+}
+
+const Filter = ({
+  label,
+  appliedCount = 0,
+  disabled = false,
+  open,
+  defaultOpen = false,
+  quickFilters,
+  clearLabel,
+  applyLabel,
+  applyDisabled = false,
+  onClear,
+  onApply,
+  panelClassName,
+  onOpenChange,
+  testId = NAME,
+  className,
+  children,
+  ...props
+}: FilterProps) => {
+  const [theme] = useTheme();
+  const filtersContext = useFiltersContext();
+  const isDesktop = filtersContext?.isDesktop ?? true;
+  const [internalOpen, setInternalOpen] = useState(defaultOpen);
+  const filterId = useId();
+  const groupedOpen = filtersContext?.activeFilterId === filterId;
+  const isOpen = open ?? (filtersContext ? groupedOpen : internalOpen);
+  const triggerRef = useRef<HTMLButtonElement>(null);
+  const panelContainerRef = useRef<HTMLDivElement>(null);
+  const didApplyDefaultOpenRef = useRef(false);
+  const panelId = useId();
+
+  const setOpen = useCallback(
+    (nextOpen: boolean) => {
+      if (open === undefined) {
+        if (filtersContext) {
+          filtersContext.setActiveFilterId(nextOpen ? filterId : null);
+        } else {
+          setInternalOpen(nextOpen);
+        }
+      }
+      onOpenChange?.(nextOpen);
+    },
+    [filterId, filtersContext, onOpenChange, open]
+  );
+
+  useEffect(() => {
+    if (didApplyDefaultOpenRef.current || !filtersContext) return;
+
+    didApplyDefaultOpenRef.current = true;
+    if (defaultOpen && open === undefined) {
+      filtersContext.setActiveFilterId(filterId);
+    }
+  }, [defaultOpen, filterId, filtersContext, open]);
+
+  useEffect(() => {
+    if (!isDesktop || !isOpen) return;
+
+    const handlePointerDown = (event: MouseEvent) => {
+      const target = event.target as Node;
+      if (
+        triggerRef.current?.contains(target) ||
+        panelContainerRef.current?.contains(target)
+      ) {
+        return;
+      }
+      setOpen(false);
+    };
+
+    const handleKeyDown = (event: KeyboardEvent) => {
+      if (event.key !== 'Escape') return;
+      setOpen(false);
+      triggerRef.current?.focus();
+    };
+
+    document.addEventListener('mousedown', handlePointerDown);
+    document.addEventListener('keydown', handleKeyDown);
+
+    return () => {
+      document.removeEventListener('mousedown', handlePointerDown);
+      document.removeEventListener('keydown', handleKeyDown);
+    };
+  }, [isDesktop, isOpen, setOpen]);
+
+  const baseStyle = css`
+    display: flex;
+    min-width: 0;
+    flex-direction: column;
+  `;
+
+  const mobileStyle = css`
+    width: 100%;
+    padding-top: ${theme.padding.p16};
+
+    &:first-of-type {
+      padding-top: 0;
+    }
+  `;
+
+  const style = cx(NAME, baseStyle, !isDesktop && mobileStyle, className);
+
+  const triggerStyle = css`
+    min-width: 0;
+    border-width: ${theme.border.b1};
+    border-radius: 0;
+  `;
+
+  const triggerLabelStyle = css`
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  `;
+
+  const countStyle = css`
+    display: inline-flex;
+    min-width: 24px;
+    height: 24px;
+    padding: ${theme.padding.p4} ${theme.padding.p8};
+    align-items: center;
+    justify-content: center;
+    box-sizing: border-box;
+    background-color: ${theme.colour.fill.brandSubtleSelected};
+    color: ${theme.colour.text.brandHover};
+  `;
+
+  const chevronStyle = css`
+    flex-shrink: 0;
+    transform: rotate(${isOpen ? '180deg' : '0deg'});
+    transition: transform 0.15s ease-out;
+
+    @media (prefers-reduced-motion: reduce) {
+      transition: none;
+    }
+  `;
+
+  const mobileTriggerStyle = css`
+    all: unset;
+    display: flex;
+    width: 100%;
+    min-height: 24px;
+    align-items: center;
+    justify-content: space-between;
+    gap: ${theme.margin.m16};
+    box-sizing: border-box;
+    color: ${theme.colour.text.default};
+    cursor: ${disabled ? 'not-allowed' : 'pointer'};
+
+    &:focus-visible {
+      box-shadow: ${theme.boxShadow.focus};
+    }
+  `;
+
+  const mobileLabelStyle = css`
+    display: flex;
+    min-width: 0;
+    align-items: center;
+    gap: ${theme.margin.m12};
+  `;
+
+  const mobileCountStyle = css`
+    min-width: 24px;
+    height: 24px;
+    padding: ${theme.padding.p4} ${theme.padding.p8};
+  `;
+
+  const mobilePanelStyle = css`
+    padding-top: ${theme.padding.p24};
+  `;
+
+  const dividerStyle = css`
+    width: 100%;
+    height: ${theme.border.b1};
+    margin-top: ${theme.margin.m16};
+    background-color: ${theme.colour.border.subtle};
+  `;
+
+  const panel = (
+    <FilterPanel
+      label={label}
+      isDesktop={isDesktop}
+      closeFilter={() => setOpen(false)}
+      quickFilters={quickFilters}
+      clearLabel={clearLabel}
+      applyLabel={applyLabel}
+      applyDisabled={applyDisabled}
+      onClear={onClear}
+      onApply={onApply}
+      className={panelClassName}
+    >
+      {children}
+    </FilterPanel>
+  );
+
+  return (
+    <div
+      className={style}
+      data-testid={testId}
+      {...props}
+    >
+      {isDesktop ? (
+        <>
+          <Button
+            ref={triggerRef}
+            variant='secondary'
+            size='small'
+            selected={isOpen || appliedCount > 0}
+            disabled={disabled}
+            className={triggerStyle}
+            aria-haspopup='dialog'
+            aria-expanded={isOpen}
+            aria-controls={panelId}
+            onClick={() => setOpen(!isOpen)}
+          >
+            <span className={triggerLabelStyle}>{label}</span>
+            {appliedCount > 0 && (
+              <Text
+                level='xs-medium'
+                className={countStyle}
+              >
+                {appliedCount}
+              </Text>
+            )}
+            <Icon.ChevronDown
+              size={16}
+              className={chevronStyle}
+            />
+          </Button>
+          {isOpen && (
+            <Overlay
+              reference={triggerRef}
+              placement='bottom-start'
+              offset={8}
+              size={{ padding: 16 }}
+            >
+              <div
+                ref={panelContainerRef}
+                id={panelId}
+                role='dialog'
+                aria-label={`${label} filter`}
+              >
+                {panel}
+              </div>
+            </Overlay>
+          )}
+        </>
+      ) : (
+        <>
+          <button
+            type='button'
+            className={mobileTriggerStyle}
+            disabled={disabled}
+            aria-expanded={isOpen}
+            aria-controls={panelId}
+            onClick={() => setOpen(!isOpen)}
+          >
+            <span className={mobileLabelStyle}>
+              <Text level='md-semibold'>{label}</Text>
+              {appliedCount > 0 && (
+                <Text
+                  level='xs-medium'
+                  className={cx(countStyle, mobileCountStyle)}
+                >
+                  {appliedCount}
+                </Text>
+              )}
+            </span>
+            <Icon.ChevronDown
+              size={24}
+              className={chevronStyle}
+            />
+          </button>
+          {isOpen && (
+            <div
+              id={panelId}
+              className={mobilePanelStyle}
+            >
+              {panel}
+            </div>
+          )}
+          <div className={dividerStyle} />
+        </>
+      )}
+    </div>
+  );
+};
+
+export default memo(Filter);

package/lib/components/Filters/FilterPanel.tsx

@@ -0,0 +1,152 @@
+import { HTMLAttributes, ReactNode, memo } from 'react';
+import { css, cx } from '@emotion/css';
+import { useTheme } from '../../theme';
+import Button from '../Button';
+import Heading from '../Heading';
+
+export const NAME = 'ucl-uikit-filter-panel';
+
+interface FilterPanelProps extends HTMLAttributes<HTMLDivElement> {
+  label: string;
+  isDesktop: boolean;
+  closeFilter: () => void;
+  quickFilters?: ReactNode;
+  clearLabel?: string;
+  applyLabel?: string;
+  applyDisabled?: boolean;
+  onClear?: React.MouseEventHandler<HTMLButtonElement>;
+  onApply?: React.MouseEventHandler<HTMLButtonElement>;
+  testId?: string;
+}
+
+const FilterPanel = ({
+  label,
+  isDesktop,
+  closeFilter,
+  quickFilters,
+  clearLabel = 'Clear',
+  applyLabel = 'Apply',
+  applyDisabled = false,
+  onClear,
+  onApply,
+  testId = NAME,
+  className,
+  children,
+  onClick,
+  ...props
+}: FilterPanelProps) => {
+  const [theme] = useTheme();
+
+  const handleApply: React.MouseEventHandler<HTMLButtonElement> = (event) => {
+    onApply?.(event);
+    if (!event.defaultPrevented) closeFilter();
+  };
+
+  const baseStyle = css`
+    display: flex;
+    flex-direction: column;
+    gap: ${theme.margin.m24};
+    width: ${isDesktop ? 'min(484px, calc(100vw - 32px))' : '100%'};
+    padding: ${isDesktop ? theme.padding.p32 : '0'};
+    border: ${
+      isDesktop
+        ? `${theme.border.b1} solid ${theme.colour.border.disabled}`
+        : 'none'
+    };
+    box-sizing: border-box;
+    background-color: ${theme.colour.surface.default};
+    color: ${theme.colour.text.default};
+    box-shadow: ${isDesktop ? theme.boxShadow.y1 : 'none'};
+  `;
+
+  const style = cx(NAME, baseStyle, className);
+
+  const headerStyle = css`
+    display: flex;
+    align-items: flex-start;
+    justify-content: space-between;
+    gap: ${theme.margin.m16};
+  `;
+
+  const headingAndQuickFiltersStyle = css`
+    display: flex;
+    min-width: 0;
+    flex: 1;
+    flex-direction: column;
+    gap: ${theme.margin.m24};
+  `;
+
+  const quickFiltersStyle = css`
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    gap: ${isDesktop ? theme.margin.m16 : theme.margin.m8};
+  `;
+
+  const contentStyle = css`
+    display: flex;
+    flex-direction: column;
+    gap: ${theme.margin.m24};
+    min-width: 0;
+  `;
+
+  const footerStyle = css`
+    display: flex;
+    justify-content: flex-end;
+  `;
+
+  return (
+    <div
+      className={style}
+      data-testid={testId}
+      onClick={(event) => {
+        event.stopPropagation();
+        onClick?.(event);
+      }}
+      {...props}
+    >
+      {isDesktop && (
+        <div className={headerStyle}>
+          <div className={headingAndQuickFiltersStyle}>
+            <Heading
+              as='h2'
+              level='sm'
+              noMargins
+            >
+              {label}
+            </Heading>
+            {quickFilters && (
+              <div className={quickFiltersStyle}>{quickFilters}</div>
+            )}
+          </div>
+          {onClear && (
+            <Button
+              variant='tertiary-no-padding'
+              size='small'
+              onClick={onClear}
+            >
+              {clearLabel}
+            </Button>
+          )}
+        </div>
+      )}
+      <div className={contentStyle}>{children}</div>
+      {!isDesktop && quickFilters && (
+        <div className={quickFiltersStyle}>{quickFilters}</div>
+      )}
+      {isDesktop && onApply && (
+        <div className={footerStyle}>
+          <Button
+            size='small'
+            disabled={applyDisabled}
+            onClick={handleApply}
+          >
+            {applyLabel}
+          </Button>
+        </div>
+      )}
+    </div>
+  );
+};
+
+export default memo(FilterPanel);

package/lib/components/Filters/Filters.context.ts

@@ -0,0 +1,12 @@
+import { createContext, use } from 'react';
+
+export interface FiltersContextValue {
+  isDesktop: boolean;
+  closeFilters: () => void;
+  activeFilterId: string | null;
+  setActiveFilterId: (id: string | null) => void;
+}
+
+export const FiltersContext = createContext<FiltersContextValue | null>(null);
+
+export const useFiltersContext = () => use(FiltersContext);

package/lib/components/Filters/Filters.mdx

@@ -0,0 +1,75 @@
+import * as FiltersStories from './Filters.stories';
+import {
+  Meta,
+  Title,
+  Subtitle,
+  Canvas,
+  Controls,
+} from '@storybook/addon-docs/blocks';
+
+<Meta of={FiltersStories} />
+<Title />
+<Subtitle>
+  A responsive, composable group of controls for filtering tables and other
+  content.
+</Subtitle>
+
+Use `Filters` to group one or more `Filter` components. Each `Filter` opens an
+anchored panel on desktop. On mobile and tablet, the group opens in a single
+modal bottom sheet and each filter expands inline.
+
+`Filter` accepts arbitrary controls as children, so filters can be composed
+from `Input`, `Datepicker`, `Select`, radios, checkboxes, `Chip`, `Toggle`,
+`Search`, or application-specific controls. `QuickFilter` is a compact toggle
+button for common preset values.
+
+<Canvas
+  of={FiltersStories.Default}
+  sourceState='shown'
+/>
+
+## Composition
+
+```tsx
+<Filters
+  appliedCount={selectedFileTypes.length}
+  onReset={resetFilters}
+  onApply={applyFilters}
+>
+  <Filter
+    label='File type'
+    appliedCount={selectedFileTypes.length}
+    onClear={clearFileTypes}
+    onApply={applyFileTypes}
+    quickFilters={
+      <QuickFilter onClick={selectDocuments}>Documents</QuickFilter>
+    }
+  >
+    <LabelledCheckbox>PDF</LabelledCheckbox>
+    <LabelledCheckbox>Spreadsheet</LabelledCheckbox>
+  </Filter>
+</Filters>
+```
+
+The same API is also available as compound properties:
+`Filters.Filter` and `Filters.QuickFilter`.
+
+## Responsive behaviour
+
+- **Desktop:** Filters are arranged horizontally. Each trigger opens its own
+  `Overlay`-positioned panel and provides panel-level clear/apply actions.
+- **Mobile and tablet:** A single Filters trigger opens a modal bottom sheet.
+  Filter headings behave as expandable sections, Reset all appears in the
+  sheet header, and Apply filters spans the sheet width.
+
+## State and accessibility
+
+Use `appliedCount` on each `Filter` and on the group to communicate active
+criteria. `open` and `onOpenChange` provide controlled opening; `defaultOpen`
+provides uncontrolled opening.
+
+Filter triggers expose `aria-expanded` and `aria-controls`. Desktop panels and
+the mobile sheet use dialog semantics, Escape closes an open panel, and focus
+returns to the trigger after the mobile sheet closes.
+
+<Controls />