@cdx-ui/components 0.2.4 → 0.3.0

package/src/components/Breadcrumbs/index.tsx

@@ -19,7 +19,10 @@ import {
   type ILinkProps,
 } from '@cdx-ui/primitives';
 import { cn } from '@cdx-ui/utils';
+import { Icon } from '../Icon';
+import { Text as ForgeText } from '../Text';
 import {
+  breadcrumbContentColor,
   breadcrumbItemVariants,
   breadcrumbDisabledCursor,
   breadcrumbItemRootVariants,
@@ -35,7 +38,8 @@ type BreadcrumbItemState = 'current' | 'ancestor' | 'disabled';
 export interface BreadcrumbsProps extends IBreadcrumbsProps {
   className?: string;
   /**
-   * Separator rendered between breadcrumb items.
+   * Separator rendered between breadcrumb items. A direct `Icon` or `Text` child takes the
+   * separator color unless it sets `color`.
    * @default `/`
    */
   separator?: ReactNode;
@@ -48,6 +52,7 @@ interface BreadcrumbItemInternalProps {
 
 export interface BreadcrumbsItemProps extends Omit<ILinkProps, 'children' | 'disabled'> {
   className?: string;
+  /** Item content. A direct `Icon` or `Text` child takes the item's state color unless it sets `color`. */
   children?: ReactNode;
 }
 
@@ -65,6 +70,23 @@ function isTextOnlyChild(children: ReactNode): children is string | number {
   return typeof children === 'string' || typeof children === 'number';
 }
 
+// `Icon` and `Text` default to `text-content-primary` and native has no color cascade, so
+// direct children that leave `color` unset take the content color through `className`.
+function withContentColor(children: ReactNode, colorClassName: string): ReactNode {
+  return Children.map(children, (child) => {
+    if (!isValidElement<{ className?: string; color?: unknown }>(child)) {
+      return child;
+    }
+    if (child.type !== Icon && child.type !== ForgeText) {
+      return child;
+    }
+    if (child.props.color !== undefined) {
+      return child;
+    }
+    return cloneElement(child, { className: cn(colorClassName, child.props.className) });
+  });
+}
+
 function BreadcrumbItemContent({
   children,
   className,
@@ -74,6 +96,8 @@ function BreadcrumbItemContent({
   className: string;
   state: BreadcrumbItemState;
 }) {
+  const { color } = useBreadcrumbsContext();
+
   if (isTextOnlyChild(children)) {
     return (
       <Text className={className} {...dataAttributes({ state })}>
@@ -84,13 +108,13 @@ function BreadcrumbItemContent({
 
   return (
     <View className={cn('flex-row items-center gap-1', className)} {...dataAttributes({ state })}>
-      {children}
+      {withContentColor(children, breadcrumbContentColor(state, color))}
     </View>
   );
 }
 
 function BreadcrumbsSeparator({ separator }: { separator: ReactNode }) {
-  const { isDisabled } = useBreadcrumbsContext();
+  const { isDisabled, color } = useBreadcrumbsContext();
   const disabledClassName = isDisabled ? breadcrumbDisabledCursor : undefined;
   const slotProps = mergeDataAttributes({}, dataAttributes({ slot: 'breadcrumbs-separator' }));
   const a11yProps = {
@@ -121,7 +145,7 @@ function BreadcrumbsSeparator({ separator }: { separator: ReactNode }) {
       {...a11yProps}
       {...slotProps}
     >
-      {separator}
+      {withContentColor(separator, breadcrumbContentColor('separator', color))}
     </View>
   );
 }

package/src/components/Breadcrumbs/styles.ts

@@ -13,6 +13,36 @@ export const breadcrumbDisabledCursor = 'web:cursor-not-allowed';
 
 export const breadcrumbSeparatorVariants = cva(['body-md text-content-tertiary select-none px-1']);
 
+const breadcrumbAncestorContentColor = {
+  neutral: 'text-content-secondary',
+  action: 'text-content-action',
+  danger: 'text-content-danger',
+  warning: 'text-content-warning',
+  success: 'text-content-success',
+  info: 'text-content-info',
+} satisfies Record<BreadcrumbColor, string>;
+
+// Color for an `Icon` or `Text` placed directly in item or separator content. Web inherits
+// the CSS color of the content element, so hover follows it; native has no color cascade,
+// so it resolves the state's token.
+export function breadcrumbContentColor(
+  state: 'current' | 'ancestor' | 'disabled' | 'separator',
+  color: BreadcrumbColor,
+): string {
+  if (Platform.OS === 'web') {
+    return 'text-inherit';
+  }
+  switch (state) {
+    case 'current':
+      return 'text-content-primary';
+    case 'ancestor':
+      return breadcrumbAncestorContentColor[color];
+    case 'disabled':
+    case 'separator':
+      return 'text-content-tertiary';
+  }
+}
+
 export const breadcrumbItemRootVariants = cva([
   'self-start',
   'web:outline-none web:focus:outline-none web:focus-visible:outline-none',

package/src/components/Calendar/CalendarMonthHeader.tsx

@@ -94,28 +94,35 @@ export const CalendarMonthHeader = forwardRef<ComponentRef<typeof View>, Calenda
           />
         </Pressable>
 
-        {!isYearView ? (
-          <View className={calendarMonthHeaderNavVariants()}>
-            <IconButton
-              as={ChevronLeft}
-              variant="ghost"
-              color="neutral"
-              size="small"
-              accessibilityLabel={labels.previousMonth}
-              isDisabled={disabled}
-              onPress={() => shiftMonth(-1)}
-            />
-            <IconButton
-              as={ChevronRight}
-              variant="ghost"
-              color="neutral"
-              size="small"
-              accessibilityLabel={labels.nextMonth}
-              isDisabled={disabled}
-              onPress={() => shiftMonth(1)}
-            />
-          </View>
-        ) : null}
+        {/* Stays mounted in the year view so the header keeps its height and the label does not move. */}
+        <View
+          className={calendarMonthHeaderNavVariants({ hidden: isYearView })}
+          pointerEvents={isYearView ? 'none' : 'auto'}
+          accessibilityElementsHidden={isYearView}
+          importantForAccessibility={isYearView ? 'no-hide-descendants' : 'auto'}
+          {...(isYearView ? { 'aria-hidden': true } : {})}
+        >
+          <IconButton
+            as={ChevronLeft}
+            variant="ghost"
+            color="neutral"
+            size="small"
+            accessibilityLabel={labels.previousMonth}
+            isDisabled={disabled || isYearView}
+            focusable={!isYearView}
+            onPress={() => shiftMonth(-1)}
+          />
+          <IconButton
+            as={ChevronRight}
+            variant="ghost"
+            color="neutral"
+            size="small"
+            accessibilityLabel={labels.nextMonth}
+            isDisabled={disabled || isYearView}
+            focusable={!isYearView}
+            onPress={() => shiftMonth(1)}
+          />
+        </View>
       </View>
     );
   },

package/src/components/Calendar/CalendarYearList.tsx

@@ -0,0 +1,136 @@
+import { Fragment, useCallback, useMemo, useRef, type ReactElement } from 'react';
+import { ScrollView, View } from 'react-native';
+import { ScrollShadow } from '../ScrollShadow';
+import {
+  calendarYearPickerListContentVariants,
+  calendarYearPickerPlaceholderVariants,
+  calendarYearPickerRowVariants,
+} from './styles';
+
+/** Years listed before / after today's year on a side with no `minValue` / `maxValue`. */
+const DEFAULT_YEAR_WINDOW = 100;
+const YEAR_COLUMNS = 3;
+/** Pill cell (40px) plus its vertical margins and row gap; fixed so the initial offset is exact. */
+export const YEAR_ROW_HEIGHT = 52;
+
+const ROW_STYLE = { height: YEAR_ROW_HEIGHT };
+
+export interface YearRange {
+  first: number;
+  last: number;
+}
+
+export function getYearRange(
+  minYear: number | undefined,
+  maxYear: number | undefined,
+  visibleYear: number,
+  todayYear: number,
+): YearRange {
+  const first =
+    minYear ?? Math.min(todayYear - DEFAULT_YEAR_WINDOW, visibleYear, maxYear ?? Infinity);
+  const last = maxYear ?? Math.max(todayYear + DEFAULT_YEAR_WINDOW, visibleYear, first);
+  return { first, last: Math.max(first, last) };
+}
+
+function clamp(value: number, min: number, max: number): number {
+  return Math.min(Math.max(value, min), max);
+}
+
+export interface CalendarYearListProps extends YearRange {
+  selectedYear: number;
+  /** Fixed list height, matched to the sibling view so switching views does not resize. */
+  height: number;
+  renderYear: (year: number) => ReactElement;
+}
+
+/**
+ * Three-up year list shared by the Calendar, RangeCalendar, and MonthCalendar year views.
+ *
+ * A plain `ScrollView` rather than a `FlatList`: the pickers render this inside their popover
+ * `ScrollView`, and a nested `VirtualizedList` breaks windowing there. The list is a few hundred
+ * light cells at most, so virtualization buys little.
+ */
+export function CalendarYearList({
+  first,
+  last,
+  selectedYear,
+  height,
+  renderYear,
+}: CalendarYearListProps) {
+  const scrollRef = useRef<ScrollView>(null);
+  const hasAppliedInitialOffset = useRef(false);
+
+  const rows = useMemo<(number | null)[][]>(() => {
+    const count = last - first + 1;
+    return Array.from({ length: Math.ceil(count / YEAR_COLUMNS) }, (_, row) =>
+      Array.from({ length: YEAR_COLUMNS }, (_, column) => {
+        const index = row * YEAR_COLUMNS + column;
+        return index < count ? first + index : null;
+      }),
+    );
+  }, [first, last]);
+
+  const visibleRows = height / YEAR_ROW_HEIGHT;
+  const selectedRow = Math.floor((clamp(selectedYear, first, last) - first) / YEAR_COLUMNS);
+  const firstVisibleRow = Math.max(0, selectedRow - Math.floor((visibleRows - 1) / 2));
+  const maxOffset = Math.max(0, rows.length * YEAR_ROW_HEIGHT - height);
+  const initialOffsetY = Math.min(firstVisibleRow * YEAR_ROW_HEIGHT, maxOffset);
+
+  // `contentOffset` is computed once so later re-renders (a new selection) never yank the
+  // scroll position back.
+  const initialOffset = useRef({ x: 0, y: initialOffsetY }).current;
+  const listStyle = useMemo(() => ({ height }), [height]);
+
+  // iOS and Android apply `contentOffset` before first paint; React Native Web ignores it, so
+  // the same offset is applied once content has a size.
+  const handleContentSizeChange = useCallback(() => {
+    if (hasAppliedInitialOffset.current) {
+      return;
+    }
+    hasAppliedInitialOffset.current = true;
+    if (initialOffset.y > 0) {
+      scrollRef.current?.scrollTo({ x: 0, y: initialOffset.y, animated: false });
+    }
+  }, [initialOffset]);
+
+  const content = useMemo(
+    () =>
+      rows.map((cells, row) => (
+        <View
+          key={first + row * YEAR_COLUMNS}
+          className={calendarYearPickerRowVariants()}
+          style={ROW_STYLE}
+        >
+          {cells.map((year, column) =>
+            year === null ? (
+              <View
+                key={`placeholder-${String(column)}`}
+                className={calendarYearPickerPlaceholderVariants()}
+                accessibilityElementsHidden
+                importantForAccessibility="no-hide-descendants"
+                aria-hidden
+              />
+            ) : (
+              <Fragment key={year}>{renderYear(year)}</Fragment>
+            ),
+          )}
+        </View>
+      )),
+    [first, rows, renderYear],
+  );
+
+  return (
+    <ScrollShadow surface="primary" size="small">
+      <ScrollView
+        ref={scrollRef}
+        style={listStyle}
+        contentContainerClassName={calendarYearPickerListContentVariants()}
+        contentOffset={initialOffset}
+        onContentSizeChange={handleContentSizeChange}
+        nestedScrollEnabled
+      >
+        {content}
+      </ScrollView>
+    </ScrollShadow>
+  );
+}

package/src/components/Calendar/CalendarYearPickerGrid.tsx

@@ -1,27 +1,32 @@
-import { forwardRef, useCallback, useMemo, type ComponentRef } from 'react';
+import { forwardRef, useCallback, useMemo, useState, type ComponentRef } from 'react';
 import { Pressable, Text, View, type ViewProps } from 'react-native';
 import {
   formatMonthId,
   formatSelectYear,
+  parseDateId,
   parseMonthId,
   resolveDateComponentLabels,
   type DateComponentLabels,
+  type DateId,
   type MonthId,
 } from '@cdx-ui/formatters';
 import { cn } from '@cdx-ui/utils';
+import { CalendarYearList, getYearRange } from './CalendarYearList';
 import type { CalendarNavigationView } from './CalendarMonthHeader';
+import { getFlashCalendarGridHeight } from './flashCalendarAdapter';
 import {
   calendarPillCellTextVariants,
   calendarPillCellVariants,
-  calendarYearPickerGridVariants,
+  calendarYearPickerListVariants,
 } from './styles';
 
-const YEAR_RANGE_BEFORE = 9;
-const YEAR_RANGE_AFTER = 11;
-
 export interface CalendarYearPickerGridProps extends ViewProps {
   monthId: MonthId;
   onMonthIdChange: (monthId: MonthId) => void;
+  /** Earliest selectable date; its year is the first year listed. */
+  minValue?: DateId;
+  /** Latest selectable date; its year is the last year listed. */
+  maxValue?: DateId;
   disabled?: boolean;
   onViewChange: (view: CalendarNavigationView) => void;
   labels?: Partial<DateComponentLabels>;
@@ -35,6 +40,8 @@ export const CalendarYearPickerGrid = forwardRef<
     {
       monthId,
       onMonthIdChange,
+      minValue,
+      maxValue,
       disabled = false,
       onViewChange,
       labels: labelsProp,
@@ -45,54 +52,74 @@ export const CalendarYearPickerGrid = forwardRef<
     ref,
   ) => {
     const labels = useMemo(() => resolveDateComponentLabels(labelsProp), [labelsProp]);
+    const [todayYear] = useState(() => new Date().getFullYear());
     const parts = parseMonthId(monthId);
-    const currentYear = parts?.year ?? new Date().getFullYear();
+    const currentYear = parts?.year ?? todayYear;
     const currentMonth = parts?.month ?? 1;
+    const minParts = minValue ? parseDateId(minValue) : null;
+    const maxParts = maxValue ? parseDateId(maxValue) : null;
+    const minYear = minParts?.year;
+    const minMonth = minParts?.month;
+    const maxYear = maxParts?.year;
+    const maxMonth = maxParts?.month;
 
-    const years = useMemo(
-      () =>
-        Array.from(
-          { length: YEAR_RANGE_BEFORE + YEAR_RANGE_AFTER + 1 },
-          (_, i) => currentYear - YEAR_RANGE_BEFORE + i,
-        ),
-      [currentYear],
-    );
+    const { first, last } = getYearRange(minYear, maxYear, currentYear, todayYear);
+
+    // Matches the day grid so switching views does not change the Calendar's height.
+    const height = getFlashCalendarGridHeight(monthId);
 
     const selectYear = useCallback(
       (year: number) => {
         if (disabled) {
           return;
         }
-        onMonthIdChange(formatMonthId({ year, month: currentMonth }));
+        let month = currentMonth;
+        if (minYear === year && minMonth !== undefined) {
+          month = Math.max(month, minMonth);
+        }
+        if (maxYear === year && maxMonth !== undefined) {
+          month = Math.min(month, maxMonth);
+        }
+        onMonthIdChange(formatMonthId({ year, month }));
         onViewChange('month');
       },
-      [currentMonth, disabled, onMonthIdChange, onViewChange],
+      [currentMonth, disabled, maxMonth, maxYear, minMonth, minYear, onMonthIdChange, onViewChange],
+    );
+
+    const renderYear = useCallback(
+      (year: number) => {
+        const selected = year === currentYear;
+        return (
+          <Pressable
+            accessibilityRole="button"
+            accessibilityState={{ selected, disabled }}
+            accessibilityLabel={formatSelectYear(labels, year)}
+            disabled={disabled}
+            onPress={() => selectYear(year)}
+            className={calendarPillCellVariants({ selected, disabled })}
+          >
+            <Text className={calendarPillCellTextVariants({ selected })}>{String(year)}</Text>
+          </Pressable>
+        );
+      },
+      [currentYear, disabled, labels, selectYear],
     );
 
     return (
       <View
         ref={ref}
-        className={cn(calendarYearPickerGridVariants(), className)}
+        className={cn(calendarYearPickerListVariants(), className)}
         style={style}
         accessibilityRole="none"
         {...props}
       >
-        {years.map((year) => {
-          const selected = year === currentYear;
-          return (
-            <Pressable
-              key={year}
-              accessibilityRole="button"
-              accessibilityState={{ selected, disabled }}
-              accessibilityLabel={formatSelectYear(labels, year)}
-              disabled={disabled}
-              onPress={() => selectYear(year)}
-              className={calendarPillCellVariants({ selected, disabled })}
-            >
-              <Text className={calendarPillCellTextVariants({ selected })}>{String(year)}</Text>
-            </Pressable>
-          );
-        })}
+        <CalendarYearList
+          first={first}
+          last={last}
+          selectedYear={currentYear}
+          height={height}
+          renderYear={renderYear}
+        />
       </View>
     );
   },

package/src/components/Calendar/flashCalendarAdapter.ts

@@ -6,6 +6,9 @@ import { formatDateId, parseMonthId, type DateId, type MonthId } from '@cdx-ui/f
 const DAY_SIZE = 36;
 const DAY_RADIUS = DAY_SIZE / 2;
 
+/** Bottom padding the theme adds under the weekday header row (`rowWeek.container`). */
+const WEEK_HEADER_PADDING_BOTTOM = 4;
+
 const CALENDAR_COLOR_VARS = [
   '--color-surface-action-strong',
   '--color-content-action-on-strong',
@@ -159,7 +162,7 @@ export function useFlashCalendarTheme(selectedDateId?: DateId): CalendarTheme {
       },
       rowWeek: {
         container: {
-          paddingBottom: 4,
+          paddingBottom: WEEK_HEADER_PADDING_BOTTOM,
         },
       },
       itemWeekName: {
@@ -249,7 +252,7 @@ export function useFlashCalendarRangeTheme(range?: {
       },
       rowWeek: {
         container: {
-          paddingBottom: 4,
+          paddingBottom: WEEK_HEADER_PADDING_BOTTOM,
         },
       },
       itemWeekName: {
@@ -348,6 +351,28 @@ export const FLASH_CALENDAR_RANGE_DAY_SPACING = 0;
 
 export const FLASH_CALENDAR_DAY_HEIGHT = DAY_SIZE;
 
+export const FLASH_CALENDAR_WEEK_HEADER_HEIGHT = 28;
+
+export const FLASH_CALENDAR_ROW_VERTICAL_SPACING = 4;
+
+/**
+ * Rendered height of the Flash Calendar month grid for `monthId`, derived from the same layout
+ * values passed to Flash Calendar (zero-height month row, weekday header, one row per week with
+ * Sunday as the first day). Lets the year view match the day view without measuring.
+ */
+export function getFlashCalendarGridHeight(monthId: MonthId): number {
+  const parts = parseMonthId(monthId);
+  const firstWeekday = parts ? new Date(parts.year, parts.month - 1, 1).getDay() : 0;
+  const daysInMonth = parts ? new Date(parts.year, parts.month, 0).getDate() : 31;
+  const weekCount = Math.ceil((firstWeekday + daysInMonth) / 7);
+  return (
+    FLASH_CALENDAR_WEEK_HEADER_HEIGHT +
+    WEEK_HEADER_PADDING_BOTTOM +
+    weekCount * FLASH_CALENDAR_DAY_HEIGHT +
+    (weekCount + 1) * FLASH_CALENDAR_ROW_VERTICAL_SPACING
+  );
+}
+
 export function formatFlashCalendarWeekdayShort(date: Date, locale: string): string {
   return new Intl.DateTimeFormat(locale, { weekday: 'short' }).format(date);
 }

package/src/components/Calendar/index.tsx

@@ -15,6 +15,8 @@ import { CalendarMonthHeader } from './CalendarMonthHeader';
 import { CalendarYearPickerGrid } from './CalendarYearPickerGrid';
 import {
   FLASH_CALENDAR_DAY_HEIGHT,
+  FLASH_CALENDAR_ROW_VERTICAL_SPACING,
+  FLASH_CALENDAR_WEEK_HEADER_HEIGHT,
   formatFlashCalendarWeekdayShort,
   getMonthDateIds,
   toCalendarDateId,
@@ -143,8 +145,8 @@ const CalendarGrid = forwardRef<View, ViewProps>(({ className, style, ...props }
         calendarDisabledDateIds={unavailableDateIds}
         calendarMonthHeaderHeight={0}
         calendarDayHeight={FLASH_CALENDAR_DAY_HEIGHT}
-        calendarWeekHeaderHeight={28}
-        calendarRowVerticalSpacing={4}
+        calendarWeekHeaderHeight={FLASH_CALENDAR_WEEK_HEADER_HEIGHT}
+        calendarRowVerticalSpacing={FLASH_CALENDAR_ROW_VERTICAL_SPACING}
         calendarRowHorizontalSpacing={4}
         getCalendarMonthFormat={() => ''}
         getCalendarWeekDayFormat={formatWeekday}
@@ -158,12 +160,15 @@ const CalendarGrid = forwardRef<View, ViewProps>(({ className, style, ...props }
 CalendarGrid.displayName = 'Calendar.Grid';
 
 const CalendarYearPicker = forwardRef<View, ViewProps>(({ className, style, ...props }, ref) => {
-  const { monthId, onMonthIdChange, disabled, setView, labels } = useCalendarContext();
+  const { monthId, onMonthIdChange, minValue, maxValue, disabled, setView, labels } =
+    useCalendarContext();
   return (
     <CalendarYearPickerGrid
       ref={ref}
       monthId={monthId}
       onMonthIdChange={onMonthIdChange}
+      minValue={minValue}
+      maxValue={maxValue}
       disabled={disabled}
       onViewChange={setView}
       labels={labels}

package/src/components/Calendar/styles.ts

@@ -31,12 +31,28 @@ export const calendarMonthHeaderIconVariants = cva('size-5 shrink-0', {
   defaultVariants: { isYearView: false },
 });
 
-export const calendarMonthHeaderNavVariants = cva('flex-row items-center gap-1');
+export const calendarMonthHeaderNavVariants = cva('flex-row items-center gap-1', {
+  variants: {
+    hidden: {
+      true: 'opacity-0',
+      false: '',
+    },
+  },
+  defaultVariants: { hidden: false },
+});
 
 export const calendarYearPickerGridVariants = cva(
   'flex-row flex-wrap justify-between gap-y-2 px-1 py-1',
 );
 
+export const calendarYearPickerListVariants = cva('w-full');
+
+export const calendarYearPickerListContentVariants = cva('px-1');
+
+export const calendarYearPickerRowVariants = cva('flex-row items-center justify-between');
+
+export const calendarYearPickerPlaceholderVariants = cva('w-[31%]');
+
 export const calendarPillCellVariants = cva(
   'my-0.5 w-[31%] items-center justify-center rounded-[var(--border-radius-round)] py-2.5',
   {