@scalepad/ui 0.1.0

package/src/components/ErrorBoundary.tsx

@@ -0,0 +1,135 @@
+import React, { Component, type ReactNode } from 'react';
+
+import { Alert, Stack } from '@mantine/core';
+
+import { Button } from './Button';
+import { Text } from './Typography';
+
+export interface ErrorBoundaryProps {
+  /**
+   * Content to render when no error has occurred
+   */
+  children: ReactNode;
+
+  /**
+   * Fallback UI to render when an error is caught
+   * Can be a ReactNode or a function that receives the error and reset function
+   */
+  fallback?: ReactNode | ((error: Error, reset: () => void) => ReactNode);
+
+  /**
+   * Optional callback when an error is caught
+   */
+  onError?: (error: Error, errorInfo: React.ErrorInfo) => void;
+
+  /**
+   * Optional callback when the error boundary is reset
+   */
+  onReset?: () => void;
+}
+
+interface ErrorBoundaryState {
+  hasError: boolean;
+  error: Error | null;
+}
+
+/**
+ * Error boundary component that catches JavaScript errors in child components
+ *
+ * Provides a fallback UI when errors occur and allows recovery via reset.
+ * Use this to prevent entire sections from crashing when a component fails.
+ *
+ * @example Basic usage with default fallback
+ * ```tsx
+ * <ErrorBoundary>
+ *   <MyComponent />
+ * </ErrorBoundary>
+ * ```
+ *
+ * @example Custom fallback UI
+ * ```tsx
+ * <ErrorBoundary
+ *   fallback={(error, reset) => (
+ *     <Alert color="red">
+ *       <Text>Failed to load data</Text>
+ *       <Button onClick={reset}>Retry</Button>
+ *     </Alert>
+ *   )}
+ * >
+ *   <MyComponent />
+ * </ErrorBoundary>
+ * ```
+ *
+ * @example With error logging
+ * ```tsx
+ * <ErrorBoundary
+ *   onError={(error, errorInfo) => {
+ *     console.error('Caught error:', error, errorInfo);
+ *     // Send to error tracking service
+ *   }}
+ * >
+ *   <MyComponent />
+ * </ErrorBoundary>
+ * ```
+ */
+export class ErrorBoundary extends Component<
+  ErrorBoundaryProps,
+  ErrorBoundaryState
+> {
+  constructor(props: ErrorBoundaryProps) {
+    super(props);
+    this.state = { hasError: false, error: null };
+  }
+
+  static getDerivedStateFromError(error: Error): ErrorBoundaryState {
+    return { hasError: true, error };
+  }
+
+  componentDidCatch(error: Error, errorInfo: React.ErrorInfo): void {
+    // Call optional error callback
+    this.props.onError?.(error, errorInfo);
+
+    // Log error to console in development (Vite: import.meta.env.DEV)
+    const isDev =
+      typeof import.meta !== 'undefined' &&
+      (import.meta as { env?: { DEV?: boolean } }).env?.DEV;
+    if (isDev) {
+      console.error('ErrorBoundary caught an error:', error, errorInfo);
+    }
+  }
+
+  resetErrorBoundary = (): void => {
+    this.props.onReset?.();
+    this.setState({ hasError: false, error: null });
+  };
+
+  render(): ReactNode {
+    if (this.state.hasError && this.state.error) {
+      // Use custom fallback if provided
+      if (this.props.fallback) {
+        if (typeof this.props.fallback === 'function') {
+          return this.props.fallback(this.state.error, this.resetErrorBoundary);
+        }
+        return this.props.fallback;
+      }
+
+      // Default fallback UI
+      return (
+        <Alert color="red" title="Something went wrong">
+          <Stack gap="sm">
+            <Text variant="caption1">{this.state.error.message}</Text>
+            <Button
+              size="sm"
+              variant="destructive"
+              onClick={this.resetErrorBoundary}
+            >
+              Try Again
+            </Button>
+          </Stack>
+        </Alert>
+      );
+    }
+
+    return this.props.children;
+  }
+}

package/src/components/ErrorState/ErrorState.tsx

@@ -0,0 +1,197 @@
+import type { ElementType, FunctionComponent, ReactNode } from 'react';
+
+import { AlertCircle } from 'lucide-react';
+
+import { Box, Card, Stack } from '@mantine/core';
+
+import { tokens } from '../../theme/themeContract.css';
+import { toCssVar, type BackgroundColorVar } from '../../theme/themeVars';
+import { Button } from '../Button';
+import { Text } from '../Typography';
+
+export interface ErrorStateAction {
+  label: string;
+  onClick?: () => void;
+  /** React Router Link component or other polymorphic component */
+  component?: ElementType;
+  /** Link destination (when using component) */
+  to?: string;
+  /** Icon to show on the right side of button */
+  rightSection?: ReactNode;
+}
+
+export interface ErrorStateProps {
+  /**
+   * The icon to display at the top
+   * @default <AlertCircle size={48} />
+   */
+  icon?: ReactNode;
+  /**
+   * Icon size (width and height in pixels)
+   * @default 48
+   */
+  iconSize?: number;
+  /**
+   * The title/heading text
+   */
+  title?: string;
+  /**
+   * The description/body text
+   */
+  description?: string;
+  /**
+   * Primary action button configuration
+   */
+  action?: ErrorStateAction;
+  /**
+   * Secondary action button configuration (ghost variant)
+   */
+  secondaryAction?: ErrorStateAction;
+  /**
+   * Maximum width of the content area
+   * @default 400
+   */
+  maxWidth?: number | string;
+  /**
+   * Minimum height of the error container
+   * @default 200
+   */
+  minHeight?: number;
+  /**
+   * Wrap content in a Card with background and border
+   * @default true
+   */
+  showCard?: boolean;
+  /**
+   * Card background (theme contract background token). Only used when showCard=true.
+   * Pass tokens.color.background.* from @scalepad/ui.
+   */
+  cardBg?: BackgroundColorVar;
+}
+
+/**
+ * ErrorState component
+ * Displays a contained error message without breaking the page layout
+ * Similar API to EmptyState for consistency
+ *
+ * @example
+ * // Simple error state
+ * <ErrorState
+ *   title="Failed to load data"
+ *   description="An error occurred while fetching the data"
+ *   action={{ label: 'Try Again', onClick: retry }}
+ * />
+ *
+ * @example
+ * // Compact error with custom icon
+ * <ErrorState
+ *   icon={<XCircle size={32} />}
+ *   iconSize={32}
+ *   title="Connection failed"
+ *   minHeight={120}
+ * />
+ */
+export function ErrorState({
+  icon = <AlertCircle size={48} />,
+  iconSize = 48,
+  title,
+  description,
+  action,
+  secondaryAction,
+  maxWidth = 400,
+  minHeight = 200,
+  showCard = true,
+  cardBg = tokens.color.background.subduedLight,
+}: ErrorStateProps) {
+  const iconElement = (
+    <Box
+      w={iconSize}
+      h={iconSize}
+      display="flex"
+      style={{
+        alignItems: 'center',
+        justifyContent: 'center',
+        color: toCssVar(tokens.color.icon.dangerDefault),
+      }}
+    >
+      {icon}
+    </Box>
+  );
+
+  const content = (
+    <Stack gap="md" align="center">
+      {iconElement}
+
+      <Stack gap="xs" align="center" maw={maxWidth}>
+        {title && (
+          <Text variant="body1.stronger" ta="center">
+            {title}
+          </Text>
+        )}
+        {description && (
+          <Text variant="caption1" c="text.subdued.default" ta="center">
+            {description}
+          </Text>
+        )}
+      </Stack>
+
+      {action && (
+        <Button
+          variant="outline"
+          onClick={action.onClick}
+          component={
+            action.component as
+              | FunctionComponent<Record<string, unknown>>
+              | undefined
+          }
+          to={action.to}
+          rightSection={action.rightSection}
+          radius="lg"
+          size="sm"
+          mt="xs"
+        >
+          {action.label}
+        </Button>
+      )}
+
+      {secondaryAction && (
+        <Button
+          variant="ghost"
+          color="dark"
+          onClick={secondaryAction.onClick}
+          component={
+            secondaryAction.component as
+              | FunctionComponent<Record<string, unknown>>
+              | undefined
+          }
+          to={secondaryAction.to}
+          rightSection={secondaryAction.rightSection}
+          radius="lg"
+          size="sm"
+        >
+          {secondaryAction.label}
+        </Button>
+      )}
+    </Stack>
+  );
+
+  if (showCard) {
+    return (
+      <Card
+        p="xl"
+        bg={cardBg != null ? toCssVar(cardBg) : undefined}
+        bd="1px solid var(--color-general-border)"
+        radius="lg"
+        style={{ minHeight }}
+      >
+        {content}
+      </Card>
+    );
+  }
+
+  return (
+    <Box py="2xl" maw={maxWidth} mx="auto" style={{ minHeight }}>
+      {content}
+    </Box>
+  );
+}

package/src/components/ErrorState/index.ts

@@ -0,0 +1,2 @@
+export { ErrorState } from './ErrorState';
+export type { ErrorStateAction, ErrorStateProps } from './ErrorState';

package/src/components/FeatureCard.tsx

@@ -0,0 +1,42 @@
+import type { ReactNode } from 'react';
+
+import { Card, Flex, ThemeIcon } from '@mantine/core';
+
+import { Text, Title } from './Typography';
+
+export interface FeatureCardProps {
+  title: string;
+  description: string;
+  icon: ReactNode;
+  color?: string;
+}
+
+/**
+ * FeatureCard component for showcasing features
+ * Displays an icon, title, and description
+ */
+export function FeatureCard({
+  title,
+  description,
+  icon,
+  color = 'blue',
+}: FeatureCardProps) {
+  return (
+    <Card shadow="sm" padding="lg" radius="md" withBorder>
+      <Flex direction="column" gap="md">
+        <ThemeIcon size="xl" radius="md" variant="light" color={color}>
+          {icon}
+        </ThemeIcon>
+
+        <Flex direction="column">
+          <Title variant="heading4" mb="xs">
+            {title}
+          </Title>
+          <Text variant="caption1" c="text.subdued.default">
+            {description}
+          </Text>
+        </Flex>
+      </Flex>
+    </Card>
+  );
+}

package/src/components/FilterMenu/FilterMenu.figma.tsx

@@ -0,0 +1,30 @@
+import figma from '@figma/code-connect';
+
+import { FilterMenu } from './FilterMenu';
+
+/**
+ * -- This file was auto-generated by Code Connect --
+ * None of your props could be automatically mapped to Figma properties.
+ * You should update the `props` object to include a mapping from your
+ * code props to Figma properties, and update the `example` function to
+ * return the code example you'd like to see in Figma
+ */
+
+figma.connect(
+  FilterMenu,
+  'https://www.figma.com/design/VCLfybgU3OaUUPrQdBaVmP/LM-Design-System?node-id=2291%3A16391',
+  {
+    props: {
+      // No matching props could be found for these Figma properties:
+      // "component": figma.instance('Component'),
+      // "spacing": figma.enum('Spacing', {
+      //   "None": "none",
+      //   "2px": "2px",
+      //   "8px": "8px",
+      //   "16px": "16px",
+      //   "24px": "24px"
+      // })
+    },
+    example: _props => <FilterMenu filters={[]} />,
+  }
+);

package/src/components/FilterMenu/FilterMenu.tsx

@@ -0,0 +1,198 @@
+import { useCallback, useMemo, useState } from 'react';
+
+import { ListFilter } from 'lucide-react';
+
+import { Flex } from '@mantine/core';
+
+import { Button } from '../Button';
+import { Menu, type MenuProps } from '../Menu';
+import { Text } from '../Typography';
+import { defaultFilterSchemas } from './defaultFilterSchemas';
+import { BooleanFilterSubmenu } from './FilterSubMenuTypes/BooleanFilterSubmenu';
+import { SearchableFilterSubmenu } from './FilterSubMenuTypes/SearchableFilterSubmenu';
+import { extractFilterValue, updateFilterCategories } from './helpers';
+
+import type { FilterSchema, FilterValue } from './types';
+import type { FilterCategory } from '../AppliedFiltersManagerBar/AppliedFiltersManagerBar';
+
+export interface FilterItem {
+  id: string;
+  name: string;
+}
+
+export interface FilterMenuProps {
+  /** Current filter categories */
+  filters: FilterCategory[];
+  /** Callback when filters change */
+  onFiltersChange?: (filters: FilterCategory[]) => void;
+  /** Filter schemas defining available filter types (defaults to defaultFilterSchemas) */
+  filterSchemas?: FilterSchema[];
+  /** Whether to show the filter button trigger */
+  showButton?: boolean;
+  /** Custom button content */
+  buttonContent?: React.ReactNode;
+  /** Additional Mantine Menu props */
+  menuProps?: Partial<MenuProps>;
+}
+
+export function FilterMenu({
+  filters,
+  onFiltersChange,
+  filterSchemas = defaultFilterSchemas,
+  showButton = true,
+  buttonContent,
+  menuProps,
+}: FilterMenuProps) {
+  const [menuOpened, setMenuOpened] = useState(false);
+
+  // Extract filter values from FilterCategory[] structure using schemas
+  const filterValues = useMemo(() => {
+    const values: Record<string, FilterValue> = {};
+    filterSchemas.forEach(schema => {
+      values[schema.key] = extractFilterValue(schema, filters);
+    });
+    return values;
+  }, [filterSchemas, filters]);
+
+  // Helper to update FilterCategory[] structure using schemas
+  const updateFilters = useCallback(
+    (updates: Record<string, FilterValue>) => {
+      if (!onFiltersChange) return;
+
+      const newFilters = updateFilterCategories(
+        filterSchemas,
+        updates,
+        filters,
+      );
+      onFiltersChange(newFilters);
+    },
+    [filterSchemas, filters, onFiltersChange],
+  );
+
+  // Create change handlers for each filter schema
+  const createChangeHandler = useCallback(
+    (schema: FilterSchema) => {
+      if (schema.type === 'boolean') {
+        return (checked: boolean) => {
+          updateFilters({ [schema.key]: checked });
+        };
+      }
+
+      if (schema.type === 'multi-select') {
+        return (selectedItems: FilterItem[]) => {
+          updateFilters({ [schema.key]: selectedItems });
+        };
+      }
+
+      // Fallback (should never reach here with proper typing)
+      return () => {};
+    },
+    [updateFilters],
+  );
+
+  const defaultButtonContent = (
+    <Flex align="center" gap="xs">
+      <ListFilter size={16} />
+      <Text variant="caption1">Filter</Text>
+    </Flex>
+  );
+
+  return (
+    <>
+      {showButton && (
+        <Menu
+          opened={menuOpened}
+          onChange={setMenuOpened}
+          position="bottom-start"
+          width={280}
+          {...menuProps}
+        >
+          <Menu.Target>
+            <Button variant="outline" size="sm" radius="lg">
+              {buttonContent || defaultButtonContent}
+            </Button>
+          </Menu.Target>
+
+          <Menu.Dropdown>
+            {filterSchemas.map((schema, index) => {
+              const isLast = index === filterSchemas.length - 1;
+
+              if (
+                schema.type === 'boolean' &&
+                schema.submenuType === 'boolean'
+              ) {
+                const checked = (filterValues[schema.key] as boolean) || false;
+                const onChange = createChangeHandler(schema) as (
+                  checked: boolean,
+                ) => void;
+
+                return (
+                  <div key={schema.key}>
+                    <BooleanFilterSubmenu
+                      label={schema.label}
+                      checked={checked}
+                      onChange={onChange}
+                    />
+                    {!isLast && <Menu.Divider />}
+                  </div>
+                );
+              }
+
+              if (
+                schema.type === 'multi-select' &&
+                schema.submenuType === 'searchable'
+              ) {
+                const selectedItems =
+                  (filterValues[schema.key] as FilterItem[]) || [];
+                const onSelectionChange = createChangeHandler(schema) as (
+                  selectedItems: FilterItem[],
+                ) => void;
+
+                // Show "Clear All" option if showClearAll is true, or if custom onClearAll is provided
+                const handleClearAll =
+                  schema.showClearAll || schema.onClearAll
+                    ? schema.onClearAll ||
+                      (() => {
+                        onSelectionChange([]);
+                      })
+                    : undefined;
+
+                const itemsController = schema.itemsController;
+                const isLoading = itemsController?.status === 'loading';
+                const isError = itemsController?.status === 'error';
+
+                return (
+                  <div key={schema.key}>
+                    <SearchableFilterSubmenu
+                      label={schema.label}
+                      items={schema.items}
+                      selectedItems={selectedItems}
+                      onSelectionChange={onSelectionChange}
+                      onClearAll={handleClearAll}
+                      placeholder={schema.placeholder}
+                      showSearch={schema.showSearch}
+                      emptyMessage={schema.emptyMessage}
+                      searchMode={schema.search?.mode ?? 'client'}
+                      onSearchChange={schema.search?.onSearchChange}
+                      searchDebounceMs={schema.search?.debounceMs}
+                      isLoading={isLoading}
+                      isError={isError}
+                      errorMessage={itemsController?.errorMessage}
+                      onRetry={itemsController?.retry}
+                      hasMore={itemsController?.hasMore}
+                      onLoadMore={itemsController?.loadMore}
+                      isLoadingMore={itemsController?.isLoadingMore}
+                    />
+                    {!isLast && <Menu.Divider />}
+                  </div>
+                );
+              }
+
+              return null;
+            })}
+          </Menu.Dropdown>
+        </Menu>
+      )}
+    </>
+  );
+}

package/src/components/FilterMenu/FilterSubMenuTypes/BooleanFilterSubmenu.tsx

@@ -0,0 +1,46 @@
+import { Checkbox } from '@mantine/core';
+
+import { Menu } from '../../Menu';
+
+export interface BooleanFilterSubmenuProps {
+  /** Label for the submenu (e.g., "Favourites") */
+  label: string;
+  /** Whether the filter is checked */
+  checked: boolean;
+  /** Callback when the checkbox toggle changes */
+  onChange: (checked: boolean) => void;
+}
+
+/**
+ * Boolean filter sub-menu: renders a checkbox whose label and input both
+ * toggle the value. The containing `Menu.Item` opts out of the default
+ * close-on-click so the user can see the checkbox flip state and then
+ * dismiss the menu explicitly (click outside or keyboard escape).
+ *
+ * All toggle events flow through the `Checkbox`'s native `onChange` — we
+ * don't also handle the surrounding `Menu.Item` click, because clicking the
+ * label would otherwise double-fire and net-cancel the toggle.
+ */
+export function BooleanFilterSubmenu({
+  label,
+  checked,
+  onChange,
+}: BooleanFilterSubmenuProps) {
+  return (
+    <Menu.Sub>
+      <Menu.Sub.Target>
+        <Menu.Sub.Item>{label}</Menu.Sub.Item>
+      </Menu.Sub.Target>
+      <Menu.Sub.Dropdown>
+        <Menu.Item closeMenuOnClick={false}>
+          <Checkbox
+            checked={checked}
+            onChange={event => onChange(event.currentTarget.checked)}
+            size="sm"
+            label={label}
+          />
+        </Menu.Item>
+      </Menu.Sub.Dropdown>
+    </Menu.Sub>
+  );
+}