@scalepad/ui 0.1.0

package/src/components/DatePicker/QuickPicksSidebar.tsx

@@ -0,0 +1,242 @@
+import { useCallback, useMemo } from 'react';
+
+import { Stack } from '@mantine/core';
+import type { DateValue } from '@mantine/dates';
+
+import {
+  addMonths,
+  addYears,
+  endOfMonth,
+  endOfYear,
+  getCurrentDate,
+  getCurrentQuarter,
+  getPreviousQuarter,
+  getQuarterRange,
+  isAfter,
+  isBefore,
+  startOfMonth,
+  startOfYear,
+} from '@scalepad/ui-utils/date';
+
+import { Text } from '../Typography';
+
+import type { DatePickerGranularity, DateRange } from './types';
+
+interface QuickPicksSidebarProps {
+  minDate?: DateValue;
+  maxDate: DateValue;
+  allowedRangeTypes?: DatePickerGranularity[];
+  onChange?: (range: DateRange, granularity: DatePickerGranularity) => void;
+}
+
+export function QuickPicksSidebar({
+  minDate,
+  maxDate,
+  allowedRangeTypes,
+  onChange,
+}: QuickPicksSidebarProps) {
+  const today = getCurrentDate();
+
+  // Filter allowed range types (default to all if not specified)
+  const allRangeTypes: DatePickerGranularity[] = [
+    'monthly',
+    'quarterly',
+    'yearly',
+    'custom',
+  ];
+  const availableRangeTypes = allowedRangeTypes || allRangeTypes;
+
+  // Check if a range type is allowed
+  const isRangeTypeAllowed = (granularity: DatePickerGranularity) =>
+    availableRangeTypes.includes(granularity);
+
+  // Quick pick handlers
+  const handleQuickPick = useCallback(
+    (type: string) => {
+      let newStartDate: Date | null = null;
+      let newEndDate: Date | null = null;
+      let newRangeType: DatePickerGranularity = 'custom';
+      let isThisQuarter = false;
+
+      switch (type) {
+        case 'thisMonth':
+          newStartDate = startOfMonth(today);
+          newEndDate = endOfMonth(today);
+          newRangeType = 'monthly';
+          break;
+        case 'lastMonth': {
+          const lastMonth = addMonths(today, -1);
+          newStartDate = startOfMonth(lastMonth);
+          newEndDate = endOfMonth(lastMonth);
+          newRangeType = 'monthly';
+          break;
+        }
+        case 'thisQuarter': {
+          const currentQ = getCurrentQuarter(today);
+          newStartDate = currentQ.start;
+          // Always use the full quarter end date, not clamped to today
+          newEndDate = currentQ.end;
+          newRangeType = 'quarterly';
+          isThisQuarter = true;
+          break;
+        }
+        case 'lastQuarter': {
+          const prevQ = getPreviousQuarter(today);
+          newStartDate = prevQ.start;
+          newEndDate = prevQ.end;
+          newRangeType = 'quarterly';
+          break;
+        }
+        case 'lastYear': {
+          const lastYear = addYears(today, -1);
+          newStartDate = startOfYear(lastYear);
+          newEndDate = endOfYear(lastYear);
+          newRangeType = 'yearly';
+          break;
+        }
+        case 'thisYear': {
+          newStartDate = startOfYear(today);
+          newEndDate = endOfYear(today);
+          newRangeType = 'yearly';
+          break;
+        }
+        default: {
+          // Handle quarter format like "Q3 2025"
+          const quarterMatch = type.match(/Q(\d)\s(\d{4})/);
+          if (quarterMatch) {
+            const quarter = parseInt(quarterMatch[1], 10) - 1;
+            const year = parseInt(quarterMatch[2], 10);
+            const quarterRange = getQuarterRange(year, quarter);
+            newStartDate = quarterRange.start;
+            newEndDate = quarterRange.end;
+            newRangeType = 'quarterly';
+          }
+          break;
+        }
+      }
+
+      if (newStartDate && newEndDate) {
+        // Ensure dates are within bounds
+        if (minDate) {
+          const minDateObj =
+            minDate instanceof Date
+              ? minDate
+              : minDate
+                ? new Date(minDate)
+                : null;
+          if (minDateObj && isBefore(newStartDate, minDateObj)) {
+            newStartDate = minDateObj;
+          }
+        }
+        const maxDateObj =
+          maxDate instanceof Date
+            ? maxDate
+            : maxDate
+              ? new Date(maxDate)
+              : null;
+        // Don't clamp end date for "thisQuarter" - always use full quarter end date
+        // For other cases, clamp if end date is after maxDate
+        if (maxDateObj && isAfter(newEndDate, maxDateObj) && !isThisQuarter) {
+          newEndDate = maxDateObj;
+        }
+
+        onChange?.(
+          {
+            startDate: newStartDate,
+            endDate: newEndDate,
+          },
+          newRangeType,
+        );
+      }
+    },
+    [today, minDate, maxDate, onChange],
+  );
+
+  // Generate recent quarters for quick picks
+  const recentQuarters = useMemo(() => {
+    const quarters: string[] = [];
+    let currentDate = today;
+    for (let i = 0; i < 3; i++) {
+      const quarterInfo =
+        i === 0
+          ? getCurrentQuarter(currentDate)
+          : getPreviousQuarter(currentDate);
+      quarters.push(`Q${quarterInfo.quarter + 1} ${quarterInfo.year}`);
+      // Move to the previous quarter for next iteration
+      currentDate = quarterInfo.start;
+    }
+    return quarters;
+  }, [today]);
+
+  return (
+    <Stack gap="md">
+      <Text variant="caption2.stronger" c="text.subdued.default">
+        Quick Picks
+      </Text>
+      {isRangeTypeAllowed('monthly') && (
+        <>
+          <Text
+            variant="caption1.strong"
+            style={{ cursor: 'pointer' }}
+            onClick={() => handleQuickPick('thisMonth')}
+          >
+            This Month
+          </Text>
+          <Text
+            variant="caption1.strong"
+            style={{ cursor: 'pointer' }}
+            onClick={() => handleQuickPick('lastMonth')}
+          >
+            Last Month
+          </Text>
+        </>
+      )}
+      {isRangeTypeAllowed('quarterly') && (
+        <>
+          <Text
+            variant="caption1.strong"
+            style={{ cursor: 'pointer' }}
+            onClick={() => handleQuickPick('thisQuarter')}
+          >
+            This Quarter
+          </Text>
+          <Text
+            variant="caption1.strong"
+            style={{ cursor: 'pointer' }}
+            onClick={() => handleQuickPick('lastQuarter')}
+          >
+            Last Quarter
+          </Text>
+          {recentQuarters.map(quarter => (
+            <Text
+              key={quarter}
+              variant="caption1.strong"
+              style={{ cursor: 'pointer' }}
+              onClick={() => handleQuickPick(quarter)}
+            >
+              {quarter}
+            </Text>
+          ))}
+        </>
+      )}
+      {isRangeTypeAllowed('yearly') && (
+        <>
+          <Text
+            variant="caption1.strong"
+            style={{ cursor: 'pointer' }}
+            onClick={() => handleQuickPick('lastYear')}
+          >
+            Last Year
+          </Text>
+          <Text
+            variant="caption1.strong"
+            style={{ cursor: 'pointer' }}
+            onClick={() => handleQuickPick('thisYear')}
+          >
+            This Year
+          </Text>
+        </>
+      )}
+    </Stack>
+  );
+}

package/src/components/DatePicker/YearlyRangePicker.tsx

@@ -0,0 +1,171 @@
+import { useMemo } from 'react';
+
+import { Box, Card, Flex, Group, Stack } from '@mantine/core';
+import type { DateValue } from '@mantine/dates';
+
+import {
+  createDate,
+  endOfYear,
+  getCurrentDate,
+  getYear,
+  isAfter,
+  isBefore,
+  isSameDay,
+  startOfYear,
+  toDate,
+} from '@scalepad/ui-utils/date';
+
+import { Text } from '../Typography';
+
+import type { DateRange } from './types';
+
+interface YearlyRangePickerProps {
+  startDate: DateValue;
+  endDate: DateValue;
+  minDate?: DateValue;
+  maxDate: DateValue; // Required, should not be null
+  onChange?: (range: DateRange) => void;
+}
+
+export function YearlyRangePicker({
+  startDate,
+  endDate,
+  minDate,
+  maxDate,
+  onChange,
+}: YearlyRangePickerProps) {
+  const today = getCurrentDate();
+  const currentYear = getYear(today);
+
+  // Generate years for display
+  const years = useMemo(() => {
+    const yearsList: number[] = [];
+    const startYear = minDate ? getYear(minDate) : currentYear - 5;
+    const endYear = currentYear;
+
+    for (let year = endYear; year >= startYear; year--) {
+      yearsList.push(year);
+    }
+
+    return yearsList;
+  }, [minDate, currentYear]);
+
+  // Check if a year is the current year
+  const isCurrentYear = (year: number) => {
+    return year === currentYear;
+  };
+
+  // Handle year selection
+  const handleYearSelect = (year: number) => {
+    const yearDate = createDate(year, 0, 1);
+    const yearStart = startOfYear(yearDate);
+    const yearEnd = endOfYear(yearDate);
+    // maxDate is required (non-null), safe to convert
+    const maxDateObj = maxDate ? toDate(maxDate) : getCurrentDate();
+
+    let newStartDate = yearStart;
+    let newEndDate = yearEnd;
+
+    // Ensure dates are within bounds
+    if (minDate) {
+      const minDateObj = toDate(minDate);
+      if (isBefore(newStartDate, minDateObj)) {
+        newStartDate = minDateObj;
+      }
+    }
+    if (isAfter(newEndDate, maxDateObj)) {
+      newEndDate = maxDateObj;
+    }
+
+    onChange?.({
+      startDate: newStartDate,
+      endDate: newEndDate,
+    });
+  };
+
+  // Check if year is selected
+  const isYearSelected = (year: number) => {
+    if (!startDate || !endDate) {
+      return false;
+    }
+    const yearDate = createDate(year, 0, 1);
+    const yearStart = startOfYear(yearDate);
+    const yearEnd = endOfYear(yearDate);
+    // Check if the selected range matches this year
+    return (
+      (isBefore(startDate, yearStart) || isSameDay(startDate, yearStart)) &&
+      (isAfter(endDate, yearEnd) ||
+        isSameDay(endDate, yearEnd) ||
+        (isAfter(endDate, yearStart) && isBefore(endDate, yearEnd)))
+    );
+  };
+
+  return (
+    <Stack gap="xs">
+      <Group gap="md">
+        {years.map(year => {
+          const isCurrent = isCurrentYear(year);
+          const isSelected = isYearSelected(year);
+          const yearDate = createDate(year, 0, 1);
+          const yearStart = startOfYear(yearDate);
+          const yearEnd = endOfYear(yearDate);
+          const minDateObj = minDate ? toDate(minDate) : null;
+          // Disable if before minDate or if the year hasn't started yet (completely in the future)
+          // Allow current year to be selected even if incomplete
+          const isDisabled =
+            (minDateObj && isBefore(yearEnd, minDateObj)) ||
+            isAfter(yearStart, today);
+
+          return (
+            <Card
+              key={year}
+              p="xs"
+              w={103}
+              mih={60}
+              withBorder
+              shadow="none"
+              pos="relative"
+              style={{
+                cursor: isDisabled ? 'not-allowed' : 'pointer',
+                opacity: isDisabled ? 0.5 : 1,
+                borderColor: isSelected
+                  ? 'var(--color-stroke-primary-default)'
+                  : undefined,
+              }}
+              onClick={() => !isDisabled && handleYearSelect(year)}
+            >
+              <Flex align="center" justify="center" h="100%">
+                <Text
+                  variant="caption1.stronger"
+                  c={
+                    isSelected
+                      ? 'text.primary.default'
+                      : isDisabled
+                        ? 'text.disabled.default'
+                        : undefined
+                  }
+                >
+                  {year}
+                </Text>
+              </Flex>
+              {isCurrent && (
+                <Box
+                  pos="absolute"
+                  bottom={4}
+                  left="50%"
+                  w={6}
+                  h={6}
+                  style={{
+                    transform: 'translateX(-50%)',
+                    borderRadius: '50%',
+                    backgroundColor: 'var(--color-background-primary-filled)',
+                  }}
+                />
+              )}
+            </Card>
+          );
+        })}
+      </Group>
+    </Stack>
+  );
+}

package/src/components/DatePicker/index.ts

@@ -0,0 +1,7 @@
+export { DateInput } from './DateInput';
+export type { DateInputProps } from './DateInput';
+export { DatePicker } from './DatePicker';
+export type { DatePickerProps } from './DatePicker';
+export { DateNavigator } from './DateNavigator';
+export type { DateNavigatorProps } from './DateNavigator';
+export type { DatePickerGranularity, DateRange } from './types';

package/src/components/DatePicker/types.ts

@@ -0,0 +1,12 @@
+import type { DateValue } from '@mantine/dates';
+
+export interface DateRange {
+  startDate: DateValue;
+  endDate: DateValue;
+}
+
+export type DatePickerGranularity =
+  | 'quarterly'
+  | 'monthly'
+  | 'yearly'
+  | 'custom';

package/src/components/DesignSystemPrimitives/FluidGrid.tsx

@@ -0,0 +1,44 @@
+import {
+  Flex as MantineFlex,
+  type FlexProps as MantineFlexProps,
+} from '@mantine/core';
+
+import {
+  createDesignComponent,
+  type WithDesignColors,
+} from '../../utils/createDesignComponent';
+
+export type FluidGridProps = WithDesignColors<MantineFlexProps> & {
+  minColumnWidth: number | string;
+  maxColumnWidth?: number | string;
+};
+
+const DesignFlex = createDesignComponent<
+  MantineFlexProps,
+  'div',
+  HTMLDivElement
+>(MantineFlex, 'FluidGrid');
+
+function toCssDimension(value: number | string): string {
+  return typeof value === 'number' ? `${value}px` : value;
+}
+
+export function FluidGrid({
+  minColumnWidth,
+  maxColumnWidth = '1fr',
+  style,
+  ...rest
+}: FluidGridProps) {
+  return (
+    <DesignFlex
+      {...rest}
+      style={[
+        {
+          display: 'grid',
+          gridTemplateColumns: `repeat(auto-fit, minmax(${toCssDimension(minColumnWidth)}, ${toCssDimension(maxColumnWidth)}))`,
+        },
+        style,
+      ]}
+    />
+  );
+}

package/src/components/DesignSystemPrimitives/InteractivePrimitives.tsx

@@ -0,0 +1,177 @@
+/**
+ * Design System Interactive Primitives
+ *
+ * Wrapped versions of Mantine interactive components that use the `color` prop.
+ * These restrict `color` to semantic design tokens.
+ */
+
+import { forwardRef, type ElementRef } from 'react';
+
+import {
+  createPolymorphicComponent,
+  Alert as MantineAlert,
+  Avatar as MantineAvatar,
+  Divider as MantineDivider,
+  Loader as MantineLoader,
+  NavLink as MantineNavLink,
+  Switch as MantineSwitch,
+  type AlertProps as MantineAlertProps,
+  type AvatarProps as MantineAvatarProps,
+  type DividerProps as MantineDividerProps,
+  type LoaderProps as MantineLoaderProps,
+  type NavLinkProps as MantineNavLinkProps,
+  type SwitchProps as MantineSwitchProps,
+} from '@mantine/core';
+
+import {
+  resolveColorToken,
+  type SemanticColor,
+  type StrokeColor,
+} from '../../utils/color-props';
+
+// ============ Alert ============
+
+export type AlertProps = Omit<MantineAlertProps, 'color'> & {
+  /** Alert accent color - accepts semantic color tokens */
+  color?: SemanticColor;
+};
+
+export const Alert = forwardRef<HTMLDivElement, AlertProps>(
+  ({ color, ...rest }, ref) => {
+    return (
+      <MantineAlert
+        ref={ref}
+        color={resolveColorToken(color) as string}
+        {...rest}
+      />
+    );
+  },
+);
+Alert.displayName = 'Alert';
+
+// ============ Avatar ============
+
+export type AvatarProps = Omit<MantineAvatarProps, 'color'> & {
+  /** Avatar accent color - accepts semantic color tokens */
+  color?: SemanticColor;
+};
+
+export const Avatar = forwardRef<HTMLDivElement, AvatarProps>(
+  ({ color, ...rest }, ref) => {
+    return (
+      <MantineAvatar
+        ref={ref}
+        color={resolveColorToken(color) as string}
+        {...rest}
+      />
+    );
+  },
+);
+Avatar.displayName = 'Avatar';
+
+// ============ Divider ============
+
+export type DividerProps = Omit<MantineDividerProps, 'color'> & {
+  /** Divider color - accepts semantic stroke tokens */
+  color?: StrokeColor;
+};
+
+export const Divider = forwardRef<HTMLDivElement, DividerProps>(
+  ({ color, ...rest }, ref) => {
+    return (
+      <MantineDivider
+        ref={ref}
+        color={resolveColorToken(color) as string}
+        {...rest}
+      />
+    );
+  },
+);
+Divider.displayName = 'Divider';
+
+// ============ Loader ============
+
+export type LoaderProps = Omit<MantineLoaderProps, 'color'> & {
+  /** Loader color - accepts semantic color tokens */
+  color?: SemanticColor;
+};
+
+export const Loader = forwardRef<ElementRef<typeof MantineLoader>, LoaderProps>(
+  ({ color, ...rest }, ref) => {
+    return (
+      <MantineLoader
+        ref={ref}
+        color={resolveColorToken(color) as string}
+        {...rest}
+      />
+    );
+  },
+);
+Loader.displayName = 'Loader';
+
+// ============ NavLink ============
+
+export type NavLinkProps = Omit<MantineNavLinkProps, 'color'> & {
+  /** NavLink accent color - accepts semantic color tokens */
+  color?: SemanticColor;
+};
+
+const NavLinkBase = forwardRef<HTMLAnchorElement, NavLinkProps>(
+  ({ color, ...rest }, ref) => {
+    return (
+      <MantineNavLink
+        ref={ref}
+        color={resolveColorToken(color) as string}
+        {...rest}
+      />
+    );
+  },
+);
+NavLinkBase.displayName = 'NavLink';
+// Use createPolymorphicComponent to preserve `component` prop support (e.g. component={Link})
+export const NavLink = createPolymorphicComponent<'a', NavLinkProps>(
+  NavLinkBase,
+);
+
+// ============ Switch ============
+
+export type SwitchProps = Omit<MantineSwitchProps, 'color'> & {
+  /** Switch accent color - accepts semantic color tokens */
+  color?: SemanticColor;
+};
+
+export const Switch = forwardRef<HTMLInputElement, SwitchProps>(
+  ({ color, ...rest }, ref) => {
+    return (
+      <MantineSwitch
+        ref={ref}
+        color={resolveColorToken(color) as string}
+        {...rest}
+      />
+    );
+  },
+);
+Switch.displayName = 'Switch';
+
+// ============ Menu ============
+
+/** Wrapped Menu.Item with typed color prop */
+// export type MenuItemProps = Omit<MantineMenuItemProps, 'color'> & {
+//   /** Menu item color - accepts semantic color tokens */
+//   color?: SemanticColor;
+// };
+
+// const _MenuItem = forwardRef<HTMLButtonElement, MenuItemProps>(({ color, ...rest }, ref) => {
+//   return <MantineMenu.Item ref={ref} color={'black'} {...rest} />;
+// });
+// _MenuItem.displayName = 'MenuItem';
+// const WrappedMenuItem = createPolymorphicComponent<'button', MenuItemProps>(_MenuItem);
+
+// /**
+//  * Menu with typed Menu.Item color prop.
+//  * All other sub-components (Target, Dropdown, Label, Divider) pass through from Mantine.
+//  */
+// export const Menu: typeof MantineMenu & { Item: typeof WrappedMenuItem } = Object.assign(
+//   MantineMenu,
+//   { Item: WrappedMenuItem }
+// ) as typeof MantineMenu & { Item: typeof WrappedMenuItem };