@astryxdesign/core 0.4.4 → 0.4.5-canary.1fdecb1

package/src/Calendar/Calendar.test.tsx

@@ -21,6 +21,8 @@ import {calendarStyles} from './styles';
 import {defineTheme} from '../theme/defineTheme';
 import {generateThemeCSS} from '../theme/generateThemeRules';
 import {__resetLiveRegionsForTest} from '../hooks/useAnnounce';
+import {InternationalizationProvider} from '../i18n/InternationalizationProvider';
+import {standaloneShortWeekdayNamesByLocale} from './standaloneShortWeekdayNames.generated';
 
 function generateThemeTestCSS(theme: Parameters<typeof generateThemeCSS>[0]) {
   const {prose, component} = generateThemeCSS(theme);
@@ -120,6 +122,45 @@ describe('Calendar', () => {
     expect(screen.getByText('Sa')).toBeInTheDocument();
   });
 
+  it('uses the provider locale for stand-alone short day names', () => {
+    const localizedNames = standaloneShortWeekdayNamesByLocale.es;
+    const englishNames = standaloneShortWeekdayNamesByLocale.en;
+    expect(localizedNames).not.toEqual(englishNames);
+
+    const {rerender} = render(
+      <InternationalizationProvider locale="es-ES">
+        <Calendar />
+      </InternationalizationProvider>,
+    );
+
+    expect(
+      screen.getAllByRole('columnheader').map(header => header.textContent),
+    ).toEqual(localizedNames);
+
+    rerender(
+      <InternationalizationProvider locale="en">
+        <Calendar />
+      </InternationalizationProvider>,
+    );
+    expect(
+      screen.getAllByRole('columnheader').map(header => header.textContent),
+    ).toEqual(englishNames);
+  });
+
+  it('rotates localized day names by numeric weekday index', () => {
+    const localizedNames = standaloneShortWeekdayNamesByLocale.es;
+
+    render(
+      <InternationalizationProvider locale="es-ES">
+        <Calendar weekStartsOn={1} />
+      </InternationalizationProvider>,
+    );
+
+    expect(
+      screen.getAllByRole('columnheader').map(header => header.textContent),
+    ).toEqual([...localizedNames.slice(1), localizedNames[0]]);
+  });
+
   it('displays correct number of day cells', () => {
     render(<Calendar />);
 
@@ -236,6 +277,102 @@ describe('Calendar', () => {
     expect(sunday).toBeDisabled();
   });
 
+  it('caps the end date to maxRangeSpan once a start is picked', async () => {
+    const user = userEvent.setup();
+
+    render(<Calendar mode="range" focusDate="2026-01-01" maxRangeSpan={7} />);
+
+    // Before a start is picked every day is selectable.
+    expect(getDayButton(20)).not.toBeDisabled();
+
+    // Pick Jan 10 as the start. A 7-day window spans Jan 4–16 (start ± 6).
+    await user.click(getDayButton(10));
+
+    expect(getDayButton(16)).not.toBeDisabled(); // 6 days after — the edge
+    expect(getDayButton(17)).toBeDisabled(); // 7 days after — beyond the cap
+    expect(getDayButton(4)).not.toBeDisabled(); // 6 days before — symmetric
+    expect(getDayButton(3)).toBeDisabled(); // 7 days before — beyond the cap
+  });
+
+  it('enforces minRangeSpan once a start is picked', async () => {
+    const user = userEvent.setup();
+
+    render(<Calendar mode="range" focusDate="2026-01-01" minRangeSpan={3} />);
+
+    // Pick Jan 10. A 3-day minimum forbids ends closer than 2 days away.
+    await user.click(getDayButton(10));
+
+    // The picked start itself stays enabled — it is the active selection
+    // anchor, not an unreachable end.
+    expect(getDayButton(10)).not.toBeDisabled();
+    expect(getDayButton(11)).toBeDisabled(); // 1 day apart — too short
+    expect(getDayButton(12)).not.toBeDisabled(); // 3-day span — allowed
+    expect(getDayButton(8)).not.toBeDisabled(); // 3-day span the other way
+    expect(getDayButton(9)).toBeDisabled(); // 2-day span — too short
+  });
+
+  it('clears the in-progress start when the anchor is clicked again', async () => {
+    const user = userEvent.setup();
+    const handleChange = vi.fn();
+
+    render(
+      <Calendar
+        mode="range"
+        focusDate="2026-01-01"
+        onChange={handleChange}
+        minRangeSpan={3}
+      />,
+    );
+
+    // Pick Jan 10 as the start, then click it again.
+    await user.click(getDayButton(10));
+    await user.click(getDayButton(10));
+
+    // No zero-length range is committed…
+    expect(handleChange).not.toHaveBeenCalled();
+
+    // …and the start is cleared: the days that minRangeSpan disabled around
+    // the old anchor are selectable again, so a new start can be placed there.
+    expect(getDayButton(11)).not.toBeDisabled();
+    expect(getDayButton(9)).not.toBeDisabled();
+  });
+
+  it('does not apply range-span constraints in single mode', async () => {
+    const user = userEvent.setup();
+
+    render(<Calendar focusDate="2026-01-01" maxRangeSpan={7} />);
+
+    // A picked single date must not disable far-away days.
+    await user.click(getDayButton(10));
+    expect(getDayButton(25)).not.toBeDisabled();
+  });
+
+  it('keeps a controlled value that is wider than maxRangeSpan (selection-only)', () => {
+    // The span constraint governs which days are pickable, not validation of
+    // an already-set value — so a 15-day value under a 7-day cap stays
+    // rendered and is never silently rewritten.
+    render(
+      <Calendar
+        mode="range"
+        value={{start: '2026-01-05', end: '2026-01-20'}}
+        focusDate="2026-01-01"
+        maxRangeSpan={7}
+      />,
+    );
+
+    // No selection is in progress (both endpoints are set), so no anchor →
+    // every day is pickable and both endpoints render selected.
+    expect(getDayButton(20)).not.toBeDisabled();
+    expect(getDayButton(5).closest('[role="gridcell"]')).toHaveAttribute(
+      'aria-selected',
+      'true',
+    );
+    expect(getDayButton(20).closest('[role="gridcell"]')).toHaveAttribute(
+      'aria-selected',
+      'true',
+    );
+  });
+
   // ─── Multi-Month ─────────────────────────────────────────────
 
   it('renders two months when numberOfMonths={2}', () => {

package/src/Calendar/Calendar.tsx

@@ -120,6 +120,25 @@ interface CalendarBaseProps extends Omit<
    */
   dateConstraints?: ReadonlyArray<(date: Date) => boolean>;
 
+  /**
+   * Range mode only. Maximum number of days a selected range may span,
+   * counting both endpoints — `maxRangeSpan={7}` allows a 7-day window
+   * (start + 6 days). Once a start date is picked, days beyond this distance
+   * from it are disabled in either direction; before a start is picked every
+   * otherwise-valid day stays selectable. Use for rolling windows like "at
+   * most a week from the chosen day". For fixed calendar bounds use min/max.
+   */
+  maxRangeSpan?: number;
+
+  /**
+   * Range mode only. Minimum number of days a selected range must span,
+   * counting both endpoints — `minRangeSpan={2}` forbids a single-day range.
+   * Once a start date is picked, days closer than this to it are disabled —
+   * except the start itself, which stays selectable as the active anchor.
+   * Defaults to 1 (a same-day start and end is allowed).
+   */
+  minRangeSpan?: number;
+
   /**
    * Controlled focus date (which month is visible).
    * If not provided, defaults to selected date or today.
@@ -211,6 +230,8 @@ export function Calendar({ref, ...props}: CalendarProps) {
     min,
     max,
     dateConstraints,
+    maxRangeSpan,
+    minRangeSpan,
     focusDate: focusDateProp,
     onFocusDateChange,
     hasOutsideDays = true,
@@ -425,6 +446,23 @@ export function Calendar({ref, ...props}: CalendarProps) {
         } else {
           // Second click - complete the range
           const startPd = plainDateFromISO(rangeSelectionStart);
+
+          // Clicking the anchor again clears the in-progress start rather than
+          // committing a zero-length range. This is also the escape hatch when
+          // `minRangeSpan` disables the days around the anchor: without it the
+          // anchor would be the only clickable day left and the start could
+          // never be moved. `minRangeSpan` leaves the anchor itself enabled
+          // precisely so this toggle stays reachable.
+          if (plainDateIsEqual(date, startPd)) {
+            setRangeSelectionStart(null);
+            announce(
+              t('@astryx.calendar.rangeClearedAnnounce', {
+                date: plainDateFormat(date, DATE_FORMAT_WITH_WEEKDAY),
+              }),
+            );
+            return;
+          }
+
           let start: ISODateString;
           let end: ISODateString;
 
@@ -528,6 +566,8 @@ export function Calendar({ref, ...props}: CalendarProps) {
             min={min}
             max={max}
             dateConstraints={dateConstraints}
+            maxRangeSpan={maxRangeSpan}
+            minRangeSpan={minRangeSpan}
             hasOutsideDays={hasOutsideDays}
             hasWeekNumbers={hasWeekNumbers}
             hasVariableRowCount={hasVariableRowCount}
@@ -567,6 +607,8 @@ interface MonthGridProps {
   min?: ISODateString;
   max?: ISODateString;
   dateConstraints?: ReadonlyArray<(date: Date) => boolean>;
+  maxRangeSpan?: number;
+  minRangeSpan?: number;
   hasOutsideDays: boolean;
   hasWeekNumbers: boolean;
   hasVariableRowCount: boolean;
@@ -589,6 +631,8 @@ function MonthGrid({
   min,
   max,
   dateConstraints,
+  maxRangeSpan,
+  minRangeSpan,
   hasOutsideDays,
   hasWeekNumbers,
   hasVariableRowCount,
@@ -610,11 +654,30 @@ function MonthGrid({
     weekStartsOn,
     hasVariableRowCount,
   });
+  const dayNameHeaders = useMemo(
+    () =>
+      dayNames.map((name, offset) => ({
+        dayOfWeek: ((weekStartsOn + offset) % 7) as DayOfWeek,
+        name,
+      })),
+    [dayNames, weekStartsOn],
+  );
+
+  const rangeAnchor = useMemo(
+    () =>
+      mode === 'range' && rangeSelectionStart
+        ? plainDateFromISO(rangeSelectionStart)
+        : null,
+    [mode, rangeSelectionStart],
+  );
 
   const {isDateDisabled} = useCalendarConstraints({
     min,
     max,
     dateConstraints,
+    maxRangeSpan,
+    minRangeSpan,
+    rangeAnchor,
   });
 
   // Parse selected date for roving tabindex priority
@@ -833,9 +896,9 @@ function MonthGrid({
               )}
             />
           )}
-          {dayNames.map(name => (
+          {dayNameHeaders.map(({dayOfWeek, name}) => (
             <div
-              key={name}
+              key={dayOfWeek}
               role="columnheader"
               {...stylex.props(monthGridStyles.dayName)}>
               {name}

package/src/Calendar/getStandaloneShortWeekdayNames.test.ts

@@ -0,0 +1,54 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file getStandaloneShortWeekdayNames.test.ts
+ * @input Private Calendar weekday locale resolver and generated CLDR data
+ * @output Regression coverage for exact, language, extension, and safe fallback
+ * @position Tests for getStandaloneShortWeekdayNames.ts
+ */
+
+import {describe, expect, it} from 'vitest';
+import {getStandaloneShortWeekdayNames} from './getStandaloneShortWeekdayNames';
+import {standaloneShortWeekdayNamesByLocale} from './standaloneShortWeekdayNames.generated';
+
+describe('getStandaloneShortWeekdayNames', () => {
+  it('preserves the default English weekday names', () => {
+    expect(getStandaloneShortWeekdayNames('en')).toEqual([
+      'Su',
+      'Mo',
+      'Tu',
+      'We',
+      'Th',
+      'Fr',
+      'Sa',
+    ]);
+  });
+
+  it('returns an exact generated locale entry', () => {
+    expect(getStandaloneShortWeekdayNames('ar-SA')).toBe(
+      standaloneShortWeekdayNamesByLocale['ar-SA'],
+    );
+  });
+
+  it('ignores Unicode extensions when resolving an exact locale', () => {
+    const expected = standaloneShortWeekdayNamesByLocale['zh-TW'];
+
+    expect(getStandaloneShortWeekdayNames('zh-TW')).toBe(expected);
+    expect(getStandaloneShortWeekdayNames('zh-TW-u-ca-chinese')).toBe(expected);
+  });
+
+  it('falls back from a regional locale to its base language', () => {
+    expect(getStandaloneShortWeekdayNames('es-ES')).toBe(
+      standaloneShortWeekdayNamesByLocale.es,
+    );
+  });
+
+  it('safely falls back to English for malformed and unsupported locales', () => {
+    expect(getStandaloneShortWeekdayNames('not_a_locale')).toBe(
+      standaloneShortWeekdayNamesByLocale.en,
+    );
+    expect(getStandaloneShortWeekdayNames('xx-ZZ')).toBe(
+      standaloneShortWeekdayNamesByLocale.en,
+    );
+  });
+});

package/src/Calendar/getStandaloneShortWeekdayNames.ts

@@ -0,0 +1,38 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file getStandaloneShortWeekdayNames.ts
+ * @input Generated CLDR stand-alone-short weekday table
+ * @output Private locale resolver for Calendar weekday headers
+ * @position Calendar-internal pure utility; not exported from the package
+ */
+
+import {
+  standaloneShortWeekdayNamesByLocale,
+  type StandaloneShortWeekdayNames,
+} from './standaloneShortWeekdayNames.generated';
+
+const weekdayNamesByLocale: Readonly<
+  Record<string, StandaloneShortWeekdayNames>
+> = standaloneShortWeekdayNamesByLocale;
+const englishWeekdayNames = weekdayNamesByLocale.en;
+
+/**
+ * Resolve generated weekday reference data as exact locale -> language -> English.
+ * Unicode extensions are ignored through Intl.Locale.baseName. Invalid tags and
+ * valid but unsupported languages safely use English.
+ */
+export function getStandaloneShortWeekdayNames(
+  locale: string,
+): StandaloneShortWeekdayNames {
+  try {
+    const parsed = new Intl.Locale(locale);
+    return (
+      weekdayNamesByLocale[parsed.baseName] ??
+      weekdayNamesByLocale[parsed.language] ??
+      englishWeekdayNames
+    );
+  } catch {
+    return englishWeekdayNames;
+  }
+}

package/src/Calendar/hooks/useCalendarConstraints.ts

@@ -20,6 +20,7 @@ import {
   plainDateToDate,
   plainDateIsBefore,
   plainDateIsAfter,
+  plainDateDiffDays,
 } from '../../utils/plainDate';
 
 /**
@@ -35,6 +36,25 @@ export interface UseCalendarConstraintsOptions {
    * Date is disabled if ANY function returns false.
    */
   dateConstraints?: ReadonlyArray<(date: Date) => boolean>;
+  /**
+   * Maximum number of days a range may span, counting both endpoints
+   * (a value of 7 allows a 7-day window). In range mode, once a start is
+   * picked, dates further than this from it are disabled. No effect until a
+   * range anchor exists.
+   */
+  maxRangeSpan?: number;
+  /**
+   * Minimum number of days a range must span, counting both endpoints
+   * (a value of 2 forbids a single-day range). In range mode, once a start
+   * is picked, dates closer than this to it are disabled.
+   */
+  minRangeSpan?: number;
+  /**
+   * The in-progress range start (first click, awaiting the second). Span
+   * constraints are measured from this date. Null when no selection is
+   * underway.
+   */
+  rangeAnchor?: PlainDate | null;
 }
 
 /**
@@ -53,13 +73,15 @@ export interface UseCalendarConstraintsReturn {
  * Hook for managing calendar date validation constraints.
  *
  * Provides a function to check if a date is disabled based on
- * min/max bounds and custom constraint functions.
+ * min/max bounds, range-span bounds, and custom constraint functions.
  *
  * @example
  * ```
  * const {isDateDisabled} = useCalendarConstraints({
  *   min: '2026-01-01',
  *   max: '2026-12-31',
+ *   maxRangeSpan: 7, // once a start is picked, cap the window at 7 days
+ *   rangeAnchor, // the in-progress start (null before the first click)
  *   dateConstraints: [
  *     (date) => date.getDay() !== 0, // No Sundays (receives native Date)
  *   ],
@@ -74,7 +96,8 @@ export interface UseCalendarConstraintsReturn {
 export function useCalendarConstraints(
   options: UseCalendarConstraintsOptions,
 ): UseCalendarConstraintsReturn {
-  const {min, max, dateConstraints} = options;
+  const {min, max, dateConstraints, maxRangeSpan, minRangeSpan, rangeAnchor} =
+    options;
 
   // Parse min/max dates
   const minDate = useMemo(() => (min ? plainDateFromISO(min) : null), [min]);
@@ -93,6 +116,27 @@ export function useCalendarConstraints(
         return true;
       }
 
+      // Range-span bounds, measured from the in-progress start. Spans count
+      // both endpoints (a span of 7 spans a 7-day window), so the reachable
+      // distance from the anchor is `span - 1` days in either direction. Only
+      // active once a start is picked — before that, every day stays pickable.
+      if (rangeAnchor) {
+        const distance = Math.abs(plainDateDiffDays(rangeAnchor, date));
+        if (maxRangeSpan != null && distance > maxRangeSpan - 1) {
+          return true;
+        }
+        // The anchor itself (distance 0) is never disabled by minRangeSpan —
+        // it is the picked start, and disabling it would render the active
+        // selection start as aria-disabled to keyboard and screen-reader users.
+        if (
+          minRangeSpan != null &&
+          distance > 0 &&
+          distance < minRangeSpan - 1
+        ) {
+          return true;
+        }
+      }
+
       // Check custom constraints (convert to Date for public API compatibility)
       if (dateConstraints) {
         for (const constraint of dateConstraints) {
@@ -104,7 +148,14 @@ export function useCalendarConstraints(
 
       return false;
     },
-    [minDate, maxDate, dateConstraints],
+    [
+      minDate,
+      maxDate,
+      dateConstraints,
+      maxRangeSpan,
+      minRangeSpan,
+      rangeAnchor,
+    ],
   );
 
   return {

package/src/Calendar/hooks/useCalendarDays.ts

@@ -4,7 +4,7 @@
 
 /**
  * @file useCalendarDays.ts
- * @input Uses React useMemo, PlainDate utilities
+ * @input Uses React context via use(), useMemo, PlainDate utilities, generated CLDR weekday data
  * @output Exports useCalendarDays hook for generating calendar day grids
  * @position Calendar-specific hook; used by Calendar
  *
@@ -12,7 +12,7 @@
  * - /packages/core/src/Calendar/hooks/index.ts
  */
 
-import {useMemo} from 'react';
+import {use, useMemo} from 'react';
 import type {DayOfWeek, ISODateString} from '../../utils/dateTypes';
 import {
   type PlainDate,
@@ -21,6 +21,8 @@ import {
   plainDateDayOfWeek,
   plainDateAddDays,
 } from '../../utils/plainDate';
+import {InternationalizationContext} from '../../i18n/InternationalizationContext';
+import {getStandaloneShortWeekdayNames} from '../getStandaloneShortWeekdayNames';
 
 /**
  * Represents a single day in the calendar grid.
@@ -84,6 +86,7 @@ export function useCalendarDays(
   options: UseCalendarDaysOptions,
 ): UseCalendarDaysReturn {
   const {year, month, weekStartsOn = 0, hasVariableRowCount = false} = options;
+  const {locale} = use(InternationalizationContext);
 
   // Calculate grid structure
   const gridInfo = useMemo(() => {
@@ -108,15 +111,15 @@ export function useCalendarDays(
     };
   }, [year, month, weekStartsOn, hasVariableRowCount]);
 
-  // Generate day names
+  // Generated strings avoid Date anchors, so weekday headers cannot shift with
+  // the runtime timezone. Keep numeric indices as the rotation source of truth.
   const dayNames = useMemo(() => {
-    const names = ['Su', 'Mo', 'Tu', 'We', 'Th', 'Fr', 'Sa'];
-    const rotated: string[] = [];
-    for (let i = 0; i < 7; i++) {
-      rotated.push(names[(i + weekStartsOn) % 7]);
-    }
-    return rotated;
-  }, [weekStartsOn]);
+    const names = getStandaloneShortWeekdayNames(locale);
+    return Array.from(
+      {length: 7},
+      (_, index) => names[(index + weekStartsOn) % 7],
+    );
+  }, [locale, weekStartsOn]);
 
   // Generate days array
   const days = useMemo(() => {

package/src/Calendar/standaloneShortWeekdayNames.generated.ts

@@ -0,0 +1,50 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @generated by scripts/generate-cldr-weekdays.mjs from Unicode CLDR 48.2.0.
+ * Do not edit by hand. Run `pnpm generate:cldr-weekdays` instead.
+ */
+
+export type StandaloneShortWeekdayNames = readonly [
+  string,
+  string,
+  string,
+  string,
+  string,
+  string,
+  string,
+];
+
+export const standaloneShortWeekdayNamesByLocale = {
+  af: ['So.', 'Ma.', 'Di.', 'Wo.', 'Do.', 'Vr.', 'Sa.'],
+  ar: ['أحد', 'إثنين', 'ثلاثاء', 'أربعاء', 'خميس', 'جمعة', 'سبت'],
+  'ar-SA': ['أحد', 'إثنين', 'ثلاثاء', 'أربعاء', 'خميس', 'جمعة', 'سبت'],
+  ca: ['dg.', 'dl.', 'dt.', 'dc.', 'dj.', 'dv.', 'ds.'],
+  cs: ['ne', 'po', 'út', 'st', 'čt', 'pá', 'so'],
+  da: ['sø.', 'ma.', 'ti.', 'on.', 'to.', 'fr.', 'lø.'],
+  de: ['So.', 'Mo.', 'Di.', 'Mi.', 'Do.', 'Fr.', 'Sa.'],
+  el: ['Κυ', 'Δε', 'Τρ', 'Τε', 'Πέ', 'Πα', 'Σά'],
+  en: ['Su', 'Mo', 'Tu', 'We', 'Th', 'Fr', 'Sa'],
+  es: ['DO', 'LU', 'MA', 'MI', 'JU', 'VI', 'SA'],
+  fi: ['su', 'ma', 'ti', 'ke', 'to', 'pe', 'la'],
+  fr: ['di', 'lu', 'ma', 'me', 'je', 've', 'sa'],
+  he: ['א׳', 'ב׳', 'ג׳', 'ד׳', 'ה׳', 'ו׳', 'ש׳'],
+  hu: ['V', 'H', 'K', 'Sze', 'Cs', 'P', 'Szo'],
+  it: ['dom', 'lun', 'mar', 'mer', 'gio', 'ven', 'sab'],
+  ja: ['日', '月', '火', '水', '木', '金', '土'],
+  ko: ['일', '월', '화', '수', '목', '금', '토'],
+  nl: ['zo', 'ma', 'di', 'wo', 'do', 'vr', 'za'],
+  no: ['sø.', 'ma.', 'ti.', 'on.', 'to.', 'fr.', 'lø.'],
+  pl: ['nie', 'pon', 'wto', 'śro', 'czw', 'pią', 'sob'],
+  pt: ['dom.', 'seg.', 'ter.', 'qua.', 'qui.', 'sex.', 'sáb.'],
+  'pt-PT': ['dom.', 'seg.', 'ter.', 'qua.', 'qui.', 'sex.', 'sáb.'],
+  ro: ['du.', 'lu.', 'ma.', 'mi.', 'joi', 'vi.', 'sâ.'],
+  ru: ['вс', 'пн', 'вт', 'ср', 'чт', 'пт', 'сб'],
+  sr: ['не', 'по', 'ут', 'ср', 'че', 'пе', 'су'],
+  sv: ['sö', 'må', 'ti', 'on', 'to', 'fr', 'lö'],
+  tr: ['Pa', 'Pt', 'Sa', 'Ça', 'Pe', 'Cu', 'Ct'],
+  uk: ['нд', 'пн', 'вт', 'ср', 'чт', 'пт', 'сб'],
+  vi: ['CN', 'T2', 'T3', 'T4', 'T5', 'T6', 'T7'],
+  zh: ['周日', '周一', '周二', '周三', '周四', '周五', '周六'],
+  'zh-TW': ['日', '一', '二', '三', '四', '五', '六'],
+} as const satisfies Readonly<Record<string, StandaloneShortWeekdayNames>>;

package/src/Center/Center.doc.mjs

@@ -48,12 +48,36 @@ export const docs = {
       description:
         'Inline (horizontal) padding, using the spacing scale. Overrides padding on the inline axis when both are set.',
     },
+    {
+      name: 'paddingInlineStart',
+      type: '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10',
+      description:
+        'Inline-start padding, using the spacing scale (left in LTR, right in RTL). Overrides paddingInline and padding on that edge only.',
+    },
+    {
+      name: 'paddingInlineEnd',
+      type: '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10',
+      description:
+        'Inline-end padding, using the spacing scale (right in LTR, left in RTL). Overrides paddingInline and padding on that edge only.',
+    },
     {
       name: 'paddingBlock',
       type: '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10',
       description:
         'Block (vertical) padding, using the spacing scale. Overrides padding on the block axis when both are set.',
     },
+    {
+      name: 'paddingBlockStart',
+      type: '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10',
+      description:
+        'Block-start (top) padding, using the spacing scale. Overrides paddingBlock and padding on that edge only.',
+    },
+    {
+      name: 'paddingBlockEnd',
+      type: '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10',
+      description:
+        'Block-end (bottom) padding, using the spacing scale. Overrides paddingBlock and padding on that edge only.',
+    },
     {
       name: 'isInline',
       type: 'boolean',
@@ -124,11 +148,31 @@ export const docsZh = {
       type: '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10',
       description: '行内（水平）内边距，使用间距刻度。两者同时设置时在行内轴上覆盖 padding。',
     },
+    {
+      name: 'paddingInlineStart',
+      type: '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10',
+      description: '行内起始内边距，使用间距刻度（LTR 中为左侧，RTL 中为右侧）。仅在该边上覆盖 paddingInline 和 padding。',
+    },
+    {
+      name: 'paddingInlineEnd',
+      type: '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10',
+      description: '行内结束内边距，使用间距刻度（LTR 中为右侧，RTL 中为左侧）。仅在该边上覆盖 paddingInline 和 padding。',
+    },
     {
       name: 'paddingBlock',
       type: '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10',
       description: '块（垂直）内边距，使用间距刻度。两者同时设置时在块轴上覆盖 padding。',
     },
+    {
+      name: 'paddingBlockStart',
+      type: '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10',
+      description: '块起始（顶部）内边距，使用间距刻度。仅在该边上覆盖 paddingBlock 和 padding。',
+    },
+    {
+      name: 'paddingBlockEnd',
+      type: '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10',
+      description: '块结束（底部）内边距，使用间距刻度。仅在该边上覆盖 paddingBlock 和 padding。',
+    },
     {name: 'isInline', type: 'boolean', description: '使用 inline-flex（适用于文本/图标）。', default: 'false'},
     {name: 'children', type: 'ReactNode', description: '要居中的内容。'},
     {
@@ -171,7 +215,11 @@ export const docsDense = {
     padding:
       'inner padding on all sides (spacing step: 0, 0.5, 1, 1.5, 2, 3, 4, 5, 6, 8, 10)',
     paddingInline: 'inline (horizontal) padding; overrides padding on that axis',
+    paddingInlineStart: 'inline-start padding (left in LTR); overrides paddingInline/padding on that edge',
+    paddingInlineEnd: 'inline-end padding (right in LTR); overrides paddingInline/padding on that edge',
     paddingBlock: 'block (vertical) padding; overrides padding on that axis',
+    paddingBlockStart: 'block-start (top) padding; overrides paddingBlock/padding on that edge',
+    paddingBlockEnd: 'block-end (bottom) padding; overrides paddingBlock/padding on that edge',
     isInline: 'use inline-flex for text/icons',
     children: 'content to center',
     xstyle: 'StyleX styles for layout (margins, positioning, sizing); must be stylex.create() value',