@astryxdesign/core 0.1.2 → 0.1.3-canary.102854d

package/src/Calendar/dayCellUtils.test.ts

@@ -5,10 +5,13 @@ import {
   computeDayCellState,
   computeRangeRounding,
   computePreviewRounding,
+  computeDayNeighborContinuity,
   isEndpoint,
+  isRangeHighlighted,
+  isPreviewHighlighted,
   type DayCellStateInput,
 } from './dayCellUtils';
-import {plainDateFromISO} from '../utils/plainDate';
+import {plainDateFromISO, plainDateIsEqual} from '../utils/plainDate';
 
 function makeInput(
   overrides: Partial<DayCellStateInput> = {},
@@ -118,6 +121,49 @@ describe('computeDayCellState', () => {
     expect(stateLast.isFirstColumn).toBe(false);
     expect(stateLast.isLastColumn).toBe(true);
   });
+
+  // Regression (#2715): outside (adjacent-month) days must not receive
+  // selection/range/preview state. In the two-month layout the same date
+  // renders in both panes, so highlighting the spillover copy would duplicate
+  // the selection onto the wrong month's pane.
+  it('does not apply range state to outside days', () => {
+    const state = computeDayCellState(
+      makeInput({
+        date: plainDateFromISO('2024-03-17'),
+        isOutside: true,
+        mode: 'range',
+        rangeStart: plainDateFromISO('2024-03-15'),
+        rangeEnd: plainDateFromISO('2024-03-20'),
+      }),
+    );
+    expect(state.isInRange).toBe(false);
+    expect(state.isRangeStart).toBe(false);
+    expect(state.isRangeEnd).toBe(false);
+  });
+
+  it('does not apply preview state to outside days', () => {
+    const state = computeDayCellState(
+      makeInput({
+        date: plainDateFromISO('2024-03-17'),
+        isOutside: true,
+        previewStart: plainDateFromISO('2024-03-15'),
+        previewEnd: plainDateFromISO('2024-03-20'),
+      }),
+    );
+    expect(state.isInPreview).toBe(false);
+    expect(state.isPreviewStart).toBe(false);
+    expect(state.isPreviewEnd).toBe(false);
+  });
+
+  it('does not mark an outside day as selected', () => {
+    const state = computeDayCellState(
+      makeInput({
+        isOutside: true,
+        selectedDate: plainDateFromISO('2024-03-15'),
+      }),
+    );
+    expect(state.isSelected).toBe(false);
+  });
 });
 
 describe('computeRangeRounding', () => {
@@ -161,6 +207,96 @@ describe('computeRangeRounding', () => {
     const rounding = computeRangeRounding(state);
     expect(rounding.roundRight).toBe(true);
   });
+
+  // #2715 follow-up: cap the highlight where the range meets a disabled or
+  // adjacent-month (outside) day. A mid-range day (neither endpoint nor grid
+  // edge) gets an end cap on the side whose neighbour breaks the run.
+  it('caps the right edge when the next day breaks the range (e.g. disabled)', () => {
+    const state = computeDayCellState(
+      makeInput({
+        date: plainDateFromISO('2024-03-17'),
+        dayIndex: 3,
+        mode: 'range',
+        rangeStart: plainDateFromISO('2024-03-15'),
+        rangeEnd: plainDateFromISO('2024-03-20'),
+      }),
+    );
+    const rounding = computeRangeRounding(state, {
+      prevInRange: true,
+      nextInRange: false,
+    });
+    expect(rounding.roundLeft).toBe(false);
+    expect(rounding.roundRight).toBe(true);
+  });
+
+  it('caps the left edge when the previous day breaks the range', () => {
+    const state = computeDayCellState(
+      makeInput({
+        date: plainDateFromISO('2024-03-17'),
+        dayIndex: 3,
+        mode: 'range',
+        rangeStart: plainDateFromISO('2024-03-15'),
+        rangeEnd: plainDateFromISO('2024-03-20'),
+      }),
+    );
+    const rounding = computeRangeRounding(state, {
+      prevInRange: false,
+      nextInRange: true,
+    });
+    expect(rounding.roundLeft).toBe(true);
+    expect(rounding.roundRight).toBe(false);
+  });
+
+  it('does not cap a mid-range day when both neighbours continue the range', () => {
+    const state = computeDayCellState(
+      makeInput({
+        date: plainDateFromISO('2024-03-17'),
+        dayIndex: 3,
+        mode: 'range',
+        rangeStart: plainDateFromISO('2024-03-15'),
+        rangeEnd: plainDateFromISO('2024-03-20'),
+      }),
+    );
+    const rounding = computeRangeRounding(state, {
+      prevInRange: true,
+      nextInRange: true,
+    });
+    expect(rounding.roundLeft).toBe(false);
+    expect(rounding.roundRight).toBe(false);
+  });
+});
+
+describe('isRangeHighlighted', () => {
+  const base = {
+    date: plainDateFromISO('2024-03-17'),
+    mode: 'range' as const,
+    rangeStart: plainDateFromISO('2024-03-15'),
+    rangeEnd: plainDateFromISO('2024-03-20'),
+    isDisabled: false,
+    isOutside: false,
+  };
+
+  it('true for an enabled in-month day inside the range', () => {
+    expect(isRangeHighlighted(base)).toBe(true);
+  });
+
+  it('false for a disabled day (breaks continuity)', () => {
+    expect(isRangeHighlighted({...base, isDisabled: true})).toBe(false);
+  });
+
+  it('false for an adjacent-month (outside) day', () => {
+    expect(isRangeHighlighted({...base, isOutside: true})).toBe(false);
+  });
+
+  it('false outside the range bounds', () => {
+    expect(
+      isRangeHighlighted({...base, date: plainDateFromISO('2024-03-25')}),
+    ).toBe(false);
+  });
+
+  it('false in single mode', () => {
+    expect(isRangeHighlighted({...base, mode: 'single'})).toBe(false);
+  });
 });
 
 describe('computePreviewRounding', () => {
@@ -175,6 +311,175 @@ describe('computePreviewRounding', () => {
     expect(rounding.roundLeft).toBe(true);
     expect(rounding.roundRight).toBe(false);
   });
+
+  // #2715: the hover preview needs the same disabled/outside caps as the
+  // committed range, so the transient highlight terminates cleanly at the gap.
+  it('caps the right edge when the next day breaks the preview run', () => {
+    const state = computeDayCellState(
+      makeInput({
+        date: plainDateFromISO('2024-03-17'),
+        dayIndex: 3,
+        previewStart: plainDateFromISO('2024-03-15'),
+        previewEnd: plainDateFromISO('2024-03-20'),
+      }),
+    );
+    const rounding = computePreviewRounding(state, {
+      prevInPreview: true,
+      nextInPreview: false,
+    });
+    expect(rounding.roundLeft).toBe(false);
+    expect(rounding.roundRight).toBe(true);
+  });
+
+  it('caps the left edge when the previous day breaks the preview run', () => {
+    const state = computeDayCellState(
+      makeInput({
+        date: plainDateFromISO('2024-03-17'),
+        dayIndex: 3,
+        previewStart: plainDateFromISO('2024-03-15'),
+        previewEnd: plainDateFromISO('2024-03-20'),
+      }),
+    );
+    const rounding = computePreviewRounding(state, {
+      prevInPreview: false,
+      nextInPreview: true,
+    });
+    expect(rounding.roundLeft).toBe(true);
+    expect(rounding.roundRight).toBe(false);
+  });
+
+  it('does not cap a mid-preview day when both neighbours continue', () => {
+    const state = computeDayCellState(
+      makeInput({
+        date: plainDateFromISO('2024-03-17'),
+        dayIndex: 3,
+        previewStart: plainDateFromISO('2024-03-15'),
+        previewEnd: plainDateFromISO('2024-03-20'),
+      }),
+    );
+    const rounding = computePreviewRounding(state, {
+      prevInPreview: true,
+      nextInPreview: true,
+    });
+    expect(rounding.roundLeft).toBe(false);
+    expect(rounding.roundRight).toBe(false);
+  });
+});
+
+describe('isPreviewHighlighted', () => {
+  const base = {
+    date: plainDateFromISO('2024-03-17'),
+    previewStart: plainDateFromISO('2024-03-15'),
+    previewEnd: plainDateFromISO('2024-03-20'),
+    isDisabled: false,
+    isOutside: false,
+  };
+
+  it('true for an enabled in-month day inside the preview span', () => {
+    expect(isPreviewHighlighted(base)).toBe(true);
+  });
+
+  it('false for a disabled day', () => {
+    expect(isPreviewHighlighted({...base, isDisabled: true})).toBe(false);
+  });
+
+  it('false for an adjacent-month (outside) day', () => {
+    expect(isPreviewHighlighted({...base, isOutside: true})).toBe(false);
+  });
+
+  it('false outside the preview bounds', () => {
+    expect(
+      isPreviewHighlighted({...base, date: plainDateFromISO('2024-03-25')}),
+    ).toBe(false);
+  });
+
+  it('false with no preview span', () => {
+    expect(
+      isPreviewHighlighted({...base, previewStart: null, previewEnd: null}),
+    ).toBe(false);
+  });
+});
+
+describe('computeDayNeighborContinuity', () => {
+  // A week row of 5 consecutive in-month days, Mar 15–19.
+  const week = (
+    [
+      '2024-03-15',
+      '2024-03-16',
+      '2024-03-17',
+      '2024-03-18',
+      '2024-03-19',
+    ] as const
+  ).map(iso => ({
+    date: plainDateFromISO(iso),
+    isOutside: false,
+  }));
+
+  const baseInput = {
+    week,
+    mode: 'range' as const,
+    rangeStart: plainDateFromISO('2024-03-15'),
+    rangeEnd: plainDateFromISO('2024-03-19'),
+    previewStart: null,
+    previewEnd: null,
+    isDisabled: () => false,
+  };
+
+  it('reports both range neighbours continuing for a mid-range day', () => {
+    const c = computeDayNeighborContinuity({...baseInput, dayIndex: 2});
+    expect(c.prevInRange).toBe(true);
+    expect(c.nextInRange).toBe(true);
+  });
+
+  it('breaks continuity where a neighbour is disabled', () => {
+    // Disable Mar 18 (index 3): its neighbour Mar 17 (index 2) sees a break to
+    // the right.
+    const disabledDay = plainDateFromISO('2024-03-18');
+    const c = computeDayNeighborContinuity({
+      ...baseInput,
+      dayIndex: 2,
+      isDisabled: date => plainDateIsEqual(date, disabledDay),
+    });
+    expect(c.prevInRange).toBe(true);
+    expect(c.nextInRange).toBe(false);
+  });
+
+  it('breaks continuity where a neighbour is an outside day', () => {
+    const weekWithOutside = week.map((d, i) =>
+      i === 3 ? {...d, isOutside: true} : d,
+    );
+    const c = computeDayNeighborContinuity({
+      ...baseInput,
+      week: weekWithOutside,
+      dayIndex: 2,
+    });
+    expect(c.nextInRange).toBe(false);
+  });
+
+  it('treats a missing neighbour (row edge) as a break', () => {
+    const first = computeDayNeighborContinuity({...baseInput, dayIndex: 0});
+    expect(first.prevInRange).toBe(false);
+    const last = computeDayNeighborContinuity({
+      ...baseInput,
+      dayIndex: week.length - 1,
+    });
+    expect(last.nextInRange).toBe(false);
+  });
+
+  it('derives preview continuity independently of range', () => {
+    const c = computeDayNeighborContinuity({
+      ...baseInput,
+      rangeStart: null,
+      rangeEnd: null,
+      previewStart: plainDateFromISO('2024-03-15'),
+      previewEnd: plainDateFromISO('2024-03-19'),
+      dayIndex: 2,
+    });
+    expect(c.prevInRange).toBe(false);
+    expect(c.nextInRange).toBe(false);
+    expect(c.prevInPreview).toBe(true);
+    expect(c.nextInPreview).toBe(true);
+  });
 });
 
 describe('isEndpoint', () => {

package/src/Calendar/dayCellUtils.ts

@@ -31,7 +31,14 @@ export interface DayCellStateInput {
   isOutside: boolean;
 }
 
-/** Derives all visual/interaction states for a single day cell. */
+/**
+ * Derives all visual/interaction states for a single day cell.
+ *
+ * Outside (adjacent-month) days never receive selection, range, or preview
+ * state: in the two-month layout the same date renders in both panes, and
+ * highlighting the spillover copy would duplicate the selection onto the wrong
+ * month's pane (#2715).
+ */
 export function computeDayCellState(input: DayCellStateInput): DayCellState {
   const {
     date,
@@ -51,55 +58,241 @@ export function computeDayCellState(input: DayCellStateInput): DayCellState {
     effectivelyDisabled: isDisabled || isOutside,
     isToday: plainDateIsEqual(date, today),
     isSelected: !!(
+      !isOutside &&
       mode === 'single' &&
       selectedDate &&
       plainDateIsEqual(date, selectedDate)
     ),
     isInRange: !!(
+      !isOutside &&
       mode === 'range' &&
       rangeStart &&
       rangeEnd &&
       plainDateIsInRange(date, [rangeStart, rangeEnd])
     ),
     isRangeStart: !!(
+      !isOutside &&
       mode === 'range' &&
       rangeStart &&
       plainDateIsEqual(date, rangeStart)
     ),
     isRangeEnd: !!(
+      !isOutside &&
       mode === 'range' &&
       rangeEnd &&
       plainDateIsEqual(date, rangeEnd)
     ),
     isInPreview: !!(
+      !isOutside &&
       previewStart &&
       previewEnd &&
       plainDateIsInRange(date, [previewStart, previewEnd])
     ),
-    isPreviewStart: !!(previewStart && plainDateIsEqual(date, previewStart)),
-    isPreviewEnd: !!(previewEnd && plainDateIsEqual(date, previewEnd)),
+    isPreviewStart: !!(
+      !isOutside &&
+      previewStart &&
+      plainDateIsEqual(date, previewStart)
+    ),
+    isPreviewEnd: !!(
+      !isOutside &&
+      previewEnd &&
+      plainDateIsEqual(date, previewEnd)
+    ),
     isFirstColumn: dayIndex === 0,
     isLastColumn: dayIndex === 6,
   };
 }
 
-/** Edge rounding for range background (rounds at grid edges and range endpoints). */
-export function computeRangeRounding(state: DayCellState) {
+/**
+ * Generic rounding for a highlight run (range or preview).
+ *
+ * Rounds at the run's endpoints and the grid row edges, and also caps the
+ * highlight where the run meets a break in continuity — a neighbouring cell
+ * that is disabled or an adjacent-month (outside) day (#2715).
+ */
+function computeHighlightRounding(input: {
+  isStart: boolean;
+  isEnd: boolean;
+  isFirstColumn: boolean;
+  isLastColumn: boolean;
+  prevContinues?: boolean;
+  nextContinues?: boolean;
+}) {
+  const prevBreaks =
+    input.prevContinues !== undefined ? !input.prevContinues : false;
+  const nextBreaks =
+    input.nextContinues !== undefined ? !input.nextContinues : false;
   return {
-    roundLeft: state.isRangeStart || state.isFirstColumn,
-    roundRight: state.isRangeEnd || state.isLastColumn,
+    roundLeft: input.isStart || input.isFirstColumn || prevBreaks,
+    roundRight: input.isEnd || input.isLastColumn || nextBreaks,
   };
 }
 
-/** Edge rounding for preview background. */
-export function computePreviewRounding(state: DayCellState) {
-  return {
-    roundLeft: state.isPreviewStart || state.isFirstColumn,
-    roundRight: state.isPreviewEnd || state.isLastColumn,
-  };
+/** Rounding for the committed range background. */
+export function computeRangeRounding(
+  state: DayCellState,
+  neighbors?: {prevInRange?: boolean; nextInRange?: boolean},
+) {
+  return computeHighlightRounding({
+    isStart: state.isRangeStart,
+    isEnd: state.isRangeEnd,
+    isFirstColumn: state.isFirstColumn,
+    isLastColumn: state.isLastColumn,
+    prevContinues: neighbors?.prevInRange,
+    nextContinues: neighbors?.nextInRange,
+  });
+}
+
+/** Rounding for the hover-preview background. */
+export function computePreviewRounding(
+  state: DayCellState,
+  neighbors?: {prevInPreview?: boolean; nextInPreview?: boolean},
+) {
+  return computeHighlightRounding({
+    isStart: state.isPreviewStart,
+    isEnd: state.isPreviewEnd,
+    isFirstColumn: state.isFirstColumn,
+    isLastColumn: state.isLastColumn,
+    prevContinues: neighbors?.prevInPreview,
+    nextContinues: neighbors?.nextInPreview,
+  });
 }
 
 /** Whether a day is a selection endpoint (selected, range start, or range end). */
 export function isEndpoint(state: DayCellState): boolean {
   return state.isSelected || state.isRangeStart || state.isRangeEnd;
 }
+
+/**
+ * Whether a day is part of an unbroken highlight run (enabled, in-month, inside
+ * the given span). Outside and disabled days break the run, producing end caps.
+ */
+function isSpanHighlighted(input: {
+  date: PlainDate;
+  spanStart: PlainDate | null;
+  spanEnd: PlainDate | null;
+  isDisabled: boolean;
+  isOutside: boolean;
+}): boolean {
+  const {date, spanStart, spanEnd, isDisabled, isOutside} = input;
+  return !!(
+    !isOutside &&
+    !isDisabled &&
+    spanStart &&
+    spanEnd &&
+    plainDateIsInRange(date, [spanStart, spanEnd])
+  );
+}
+
+/** Whether a day participates in the continuous committed-range highlight. */
+export function isRangeHighlighted(input: {
+  date: PlainDate;
+  mode: 'single' | 'range';
+  rangeStart: PlainDate | null;
+  rangeEnd: PlainDate | null;
+  isDisabled: boolean;
+  isOutside: boolean;
+}): boolean {
+  if (input.mode !== 'range') {return false;}
+  return isSpanHighlighted({
+    date: input.date,
+    spanStart: input.rangeStart,
+    spanEnd: input.rangeEnd,
+    isDisabled: input.isDisabled,
+    isOutside: input.isOutside,
+  });
+}
+
+/** Whether a day participates in the continuous hover-preview highlight. */
+export function isPreviewHighlighted(input: {
+  date: PlainDate;
+  previewStart: PlainDate | null;
+  previewEnd: PlainDate | null;
+  isDisabled: boolean;
+  isOutside: boolean;
+}): boolean {
+  return isSpanHighlighted({
+    date: input.date,
+    spanStart: input.previewStart,
+    spanEnd: input.previewEnd,
+    isDisabled: input.isDisabled,
+    isOutside: input.isOutside,
+  });
+}
+
+/**
+ * Continuity of the highlighted run through a day's immediate neighbours in the
+ * same week row, for both the committed range and the hover preview. A day gets
+ * an end cap on whichever side its neighbour does not continue the run (see
+ * {@link computeRangeRounding} / {@link computePreviewRounding}).
+ */
+export interface DayNeighborContinuity {
+  prevInRange: boolean;
+  nextInRange: boolean;
+  prevInPreview: boolean;
+  nextInPreview: boolean;
+}
+
+/** Minimal shape needed from a week's day cells to derive neighbour continuity. */
+export interface NeighborDay {
+  date: PlainDate;
+  isOutside: boolean;
+}
+
+/**
+ * Derives whether the previous/next day in the same week row continues the
+ * highlighted run, for both range and preview. Broken out from the render path
+ * so the neighbour logic is unit-testable in isolation.
+ */
+export function computeDayNeighborContinuity(input: {
+  week: ReadonlyArray<NeighborDay>;
+  dayIndex: number;
+  mode: 'single' | 'range';
+  rangeStart: PlainDate | null;
+  rangeEnd: PlainDate | null;
+  previewStart: PlainDate | null;
+  previewEnd: PlainDate | null;
+  isDisabled: (date: PlainDate) => boolean;
+}): DayNeighborContinuity {
+  const {
+    week,
+    dayIndex,
+    mode,
+    rangeStart,
+    rangeEnd,
+    previewStart,
+    previewEnd,
+    isDisabled,
+  } = input;
+
+  const prev = week[dayIndex - 1];
+  const next = week[dayIndex + 1];
+
+  const rangeContinues = (day: NeighborDay | undefined): boolean =>
+    day != null &&
+    isRangeHighlighted({
+      date: day.date,
+      mode,
+      rangeStart,
+      rangeEnd,
+      isDisabled: isDisabled(day.date),
+      isOutside: day.isOutside,
+    });
+
+  const previewContinues = (day: NeighborDay | undefined): boolean =>
+    day != null &&
+    isPreviewHighlighted({
+      date: day.date,
+      previewStart,
+      previewEnd,
+      isDisabled: isDisabled(day.date),
+      isOutside: day.isOutside,
+    });
+
+  return {
+    prevInRange: rangeContinues(prev),
+    nextInRange: rangeContinues(next),
+    prevInPreview: previewContinues(prev),
+    nextInPreview: previewContinues(next),
+  };
+}

package/src/Calendar/hooks/index.ts

@@ -27,9 +27,3 @@ export type {
   UseCalendarNavigationOptions,
   UseCalendarNavigationReturn,
 } from './useCalendarNavigation';
-
-export {useCalendarRovingTabindex} from './useCalendarRovingTabindex';
-export type {
-  UseCalendarRovingTabindexOptions,
-  UseCalendarRovingTabindexReturn,
-} from './useCalendarRovingTabindex';

package/src/Calendar/index.ts

@@ -17,6 +17,7 @@ export type {
   CalendarHandle,
   ISODateString,
   DayOfWeek,
+  DayOfWeekName,
   DateRange,
 } from './Calendar';
 
@@ -25,7 +26,6 @@ export {
   useCalendarDays,
   useCalendarConstraints,
   useCalendarNavigation,
-  useCalendarRovingTabindex,
 } from './hooks';
 export type {
   CalendarDay,
@@ -35,8 +35,6 @@ export type {
   UseCalendarConstraintsReturn,
   UseCalendarNavigationOptions,
   UseCalendarNavigationReturn,
-  UseCalendarRovingTabindexOptions,
-  UseCalendarRovingTabindexReturn,
 } from './hooks';
 
 // Re-export calendar-specific utilities for advanced usage

package/src/Calendar/styles.ts

@@ -78,17 +78,12 @@ export const monthGridStyles = stylex.create({
   monthGrid: {
     flex: '1 1 0',
   },
-  weekHeader: {
-    display: 'grid',
-    gridTemplateColumns: 'repeat(7, 1fr)',
-    marginBottom: spacingVars['--spacing-1'],
-  },
-  weekHeaderWithNumbers: {
-    gridTemplateColumns: 'auto repeat(7, 1fr)',
-  },
   dayName: {
     width: sizeVars['--size-element-md'],
-    height: sizeVars['--size-element-md'],
+    // Restores the small gap the standalone header used to have below it.
+    height: `calc(${sizeVars['--size-element-md']} + ${spacingVars['--spacing-1']})`,
+    paddingBottom: spacingVars['--spacing-1'],
+    boxSizing: 'border-box',
     display: 'flex',
     alignItems: 'center',
     justifyContent: 'center',

package/src/Carousel/Carousel.doc.mjs

@@ -21,7 +21,7 @@ export const docs = {
     anatomy: [
       {name: 'Scroll container', required: true, description: 'The horizontal overflow area that holds all items.'},
       {name: 'Items', required: true, description: 'The children rendered in a row. Each item is animated with a scroll-driven scale effect.'},
-      {name: 'Fade edges', required: true, description: 'Gradient fades on the left and right edges that indicate more content is available.'},
+      {name: 'Fade edges', required: false, description: 'Gradient fades on the left and right edges that indicate more content is available. Enabled by default, disable with hasEdgeFade={false}.'},
       {name: 'Navigation buttons', required: false, description: 'Prev/next buttons that appear on hover. Enabled by default, disable with hasButtons={false}.'},
     ],
   },
@@ -29,7 +29,9 @@ export const docs = {
     {name: 'children', type: 'ReactNode', description: 'Carousel items rendered in a horizontal scroll container.', required: true},
     {name: 'gap', type: "0 | 0.5 | 1 | 1.5 | 2 | 3 | 4", description: 'Gap between items using the spacing token scale.', default: '1'},
     {name: 'hasButtons', type: 'boolean', description: 'Show prev/next navigation buttons on hover (desktop only).', default: 'true'},
+    {name: 'hasEdgeFade', type: 'boolean', description: 'Show a gradient edge-fade mask when content overflows, signalling that more items exist off-screen.', default: 'true'},
     {name: 'hasSnap', type: 'boolean', description: 'Enable scroll-snap so each child snaps to the start edge.', default: 'false'},
+    {name: 'padding', type: '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10', description: 'Inline padding inside the scroll container, with matching scroll-padding so snap points align to the content edge.'},
     {name: 'aria-label', type: 'string', description: 'Accessible label for the carousel region.', default: "\'Carousel\'"},
     {name: 'ref', type: 'React.Ref<HTMLDivElement>', description: 'Ref forwarded to the root element.'},
     {name: 'xstyle', type: 'StyleXStyles', description: 'StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value.'},
@@ -71,7 +73,9 @@ export const docsZh = {
     children: '在水平滚动容器中渲染的轮播项目。',
     gap: '使用间距令牌比例的项目间距。',
     hasButtons: '悬停时显示上一个/下一个导航按钮（仅桌面端）。',
+    hasEdgeFade: '内容溢出时显示渐变边缘遮罩，提示屏幕外还有更多项目。',
     hasSnap: '启用滚动吸附，使每个子元素吸附到起始边缘。',
+    padding: '滚动容器内的内联内边距，并设置匹配的 scroll-padding，使吸附点与内容边缘对齐。',
     'aria-label': '轮播区域的无障碍标签。',
   },
 };
@@ -95,7 +99,9 @@ export const docsDense = {
     children: 'carousel items in horizontal scroll',
     gap: 'item spacing via spacing token scale',
     hasButtons: 'prev/next buttons on hover (desktop)',
+    hasEdgeFade: 'gradient edge-fade mask on overflow',
     hasSnap: 'scroll-snap; children snap to start edge',
+    padding: 'inline padding; scroll-padding keeps snap points on content edge',
     'aria-label': 'accessible label for carousel region',
     'data-testid': 'test selector for automated testing frameworks',
   },