@astryxdesign/core 0.4.5 → 0.4.6-canary.cea9ecd

package/src/Breadcrumbs/BreadcrumbItem.tsx

@@ -39,12 +39,13 @@ import {
   typeScaleVars,
   radiusVars,
 } from '../theme/tokens.stylex';
-import {BreadcrumbContext} from './Breadcrumbs';
+import {BreadcrumbContext, type BreadcrumbsVariant} from './Breadcrumbs';
 import {useLinkComponent} from '../Link/useLinkComponent';
 import type {LinkComponentType} from '../Link/types';
 import {mergeProps, mergeRefs} from '../utils';
 import type {BaseProps} from '../BaseProps';
 import {themeProps} from '../utils/themeProps';
+import {focusOutlineProps} from '../utils/focusOutline.stylex';
 import {Icon} from '../Icon';
 import {usePopover} from '../Popover/usePopover';
 import {useListFocus} from '../hooks/useListFocus';
@@ -158,17 +159,23 @@ const itemStyles = stylex.create({
     paddingBlock: spacingVars['--spacing-1'],
     textDecoration: {
       default: 'none',
-      ':hover': {
+      ':hover:where(:not(:disabled,[aria-disabled="true"]))': {
         '@media (hover: hover)': 'underline',
       },
     },
-    cursor: 'pointer',
+    cursor: {
+      default: 'pointer',
+      ':is(:disabled,[aria-disabled="true"])': 'default',
+    },
   },
-  // Reset native button styles so onClick-only items match link appearance
+  // Reset native button styles so onClick-only items match link appearance.
+  // paddingInline rather than padding: a blanket `padding` also overrides the
+  // paddingBlock `link` sets above, which shrank the button crumbs to 20px
+  // against their sibling links' 28px.
   buttonReset: {
     background: 'none',
     border: 'none',
-    padding: 0,
+    paddingInline: 0,
     margin: 0,
     font: 'inherit',
   },
@@ -351,7 +358,7 @@ export function BreadcrumbItem({
       <li
         ref={mergeRefs(ref, liRef)}
         {...mergeProps(
-          themeProps('breadcrumb-item'),
+          themeProps('breadcrumb-item', {variant: ctx.variant}),
           stylex.props(
             itemStyles.root,
             isSupporting ? itemStyles.supportingSize : itemStyles.defaultSize,
@@ -372,7 +379,7 @@ export function BreadcrumbItem({
             ref={contentRef}
             menu={menu}
             menuSize={resolvedMenuSize}
-            isSupporting={isSupporting}
+            variant={ctx.variant}
             isCurrent
             label={children}>
             {content}
@@ -400,7 +407,7 @@ export function BreadcrumbItem({
     <li
       ref={mergeRefs(ref, liRef)}
       {...mergeProps(
-        themeProps('breadcrumb-item'),
+        themeProps('breadcrumb-item', {variant: ctx.variant}),
         stylex.props(
           itemStyles.root,
           isSupporting ? itemStyles.supportingSize : itemStyles.defaultSize,
@@ -419,7 +426,7 @@ export function BreadcrumbItem({
           ref={contentRef}
           menu={menu}
           menuSize={resolvedMenuSize}
-          isSupporting={isSupporting}
+          variant={ctx.variant}
           label={children}>
           {content}
         </BreadcrumbMenuTrigger>
@@ -428,7 +435,7 @@ export function BreadcrumbItem({
           ref={contentRef}
           href={href}
           onClick={onClick}
-          {...stylex.props(
+          {...focusOutlineProps.focusVisible(
             itemStyles.link,
             isSupporting ? itemStyles.supportingLink : itemStyles.defaultLink,
           )}>
@@ -439,7 +446,7 @@ export function BreadcrumbItem({
           ref={contentRef as React.RefObject<HTMLButtonElement | null>}
           type="button"
           onClick={onClick}
-          {...stylex.props(
+          {...focusOutlineProps.focusVisible(
             itemStyles.link,
             itemStyles.buttonReset,
             isSupporting ? itemStyles.supportingLink : itemStyles.defaultLink,
@@ -477,7 +484,7 @@ interface BreadcrumbMenuTriggerProps {
   label: ReactNode;
   menu: DropdownMenuOption[] | ReactNode;
   menuSize: DropdownMenuSize;
-  isSupporting: boolean;
+  variant: BreadcrumbsVariant;
   isCurrent?: boolean;
 }
 
@@ -494,11 +501,12 @@ function BreadcrumbMenuTrigger({
   label,
   menu,
   menuSize,
-  isSupporting,
+  variant,
   isCurrent = false,
 }: BreadcrumbMenuTriggerProps) {
   const menuId = useId();
   const buttonRef = useRef<HTMLButtonElement>(null);
+  const isSupporting = variant === 'supporting';
 
   const popover = usePopover({
     onHide: useCallback(() => {
@@ -615,16 +623,21 @@ function BreadcrumbMenuTrigger({
         type="button"
         onClick={handleClick}
         onKeyDown={handleKeyDown}
-        {...mergeProps(themeProps('breadcrumb-item-menu-trigger'), {
-          ...popover.triggerProps,
-          'aria-haspopup': 'menu' as const,
-          'aria-controls': menuId,
-          'aria-current': isCurrent ? ('page' as const) : undefined,
-        })}
-        {...stylex.props(
-          itemStyles.link,
-          itemStyles.buttonReset,
-          isSupporting ? itemStyles.supportingLink : itemStyles.defaultLink,
+        {...popover.triggerProps}
+        aria-haspopup="menu"
+        aria-controls={menuId}
+        aria-current={isCurrent ? 'page' : undefined}
+        {...mergeProps(
+          themeProps('breadcrumb-item-menu-trigger', {variant}),
+          // Through mergeProps, not a second spread: a sibling stylex.props()
+          // spread replaces the className themeProps() built, which is how the
+          // documented breadcrumb-item-menu-trigger target came to render on
+          // nothing.
+          focusOutlineProps.focusVisible(
+            itemStyles.link,
+            itemStyles.buttonReset,
+            isSupporting ? itemStyles.supportingLink : itemStyles.defaultLink,
+          ),
         )}>
         {children}
         <Icon

package/src/Breadcrumbs/Breadcrumbs.doc.mjs

@@ -16,9 +16,12 @@ export const docs = {
       {guidance: true, description: 'Keep labels short and match the page titles they link to: "Settings" not "Application Settings Page".'},
       {guidance: true, description: 'Use the supporting variant in dense UIs like admin panels or sidebars where the breadcrumb should be subtle.'},
       {guidance: true, description: 'Make the last item plain text, not a link; it represents the current page. The component does this automatically when you set isCurrent.'},
+      {guidance: true, description: 'The component implements the WAI-ARIA APG Breadcrumb pattern: a labelled nav landmark wrapping an ordered list, with aria-current="page" on the current item. A crumb with a menu additionally implements the APG Menu Button pattern, opening on Enter, Space or ArrowDown and closing on Escape.'},
+      {guidance: true, description: 'Give each trail its own label when a page renders more than one, so the nav landmarks stay distinguishable in a screen reader landmark list.'},
       {guidance: false, description: 'Use breadcrumbs as the primary navigation. They supplement a sidebar or top nav, not replace it.'},
       {guidance: false, description: 'Show breadcrumbs on top-level pages that have no parent; they add clutter without helping the user.'},
       {guidance: false, description: 'Let the trail grow beyond 5 levels. If you need more, consider simplifying the page hierarchy instead.'},
+      {guidance: false, description: 'Mirror a separator the bidi algorithm already mirrors. An angle-quote glyph such as › is Bidi_Mirrored, so it flips under RTL on its own and rtlStyles.mirror would flip it back. An arrow glyph such as → and any Icon separator are not, so those do need rtlStyles.mirror through xstyle.'},
     ],
     anatomy: [
       {name: 'Trail', required: true, description: 'The ordered list of links from root to current page.'},
@@ -29,8 +32,11 @@ export const docs = {
   },
   theming: {
     targets: [
-      {className: 'astryx-breadcrumb-item'},
-      {className: 'astryx-breadcrumb-item-menu-trigger'},
+      {className: 'astryx-breadcrumb-item', visualProps: ['variant']},
+      {
+        className: 'astryx-breadcrumb-item-menu-trigger',
+        visualProps: ['variant'],
+      },
       {className: 'astryx-breadcrumb-menu'},
       {className: 'astryx-breadcrumbs', visualProps: ['variant']},
     ],
@@ -123,6 +129,18 @@ export const docs = {
           type: 'LinkComponentType',
           description: 'Custom link component to render instead of <a>. Overrides the provider-level default from LinkProvider. Only applies to non-current items.',
         },
+        {
+          name: 'menu',
+          type: 'DropdownMenuOption[] | ReactNode',
+          description:
+            'Menu opened when the item is activated, using the same item API as DropdownMenu/MoreMenu/ContextMenu (a DropdownMenuOption[] array or composed DropdownMenuItem children). Renders a link-styled menu trigger with a chevron and aria-haspopup="menu". Takes precedence over href/onClick.',
+        },
+        {
+          name: 'menuSize',
+          type: "'sm' | 'md' | 'lg'",
+          description:
+            "Size passed to the menu items. Defaults from the breadcrumb variant ('supporting' → 'sm', otherwise 'md').",
+        },
       ],
     },
   ],
@@ -138,9 +156,12 @@ export const docsZh = {
       {guidance: true, description: 'Keep labels short and match the page titles they link to: "Settings" not "Application Settings Page".'},
       {guidance: true, description: 'Use the supporting variant in dense UIs like admin panels or sidebars where the breadcrumb should be subtle.'},
       {guidance: true, description: 'Make the last item plain text, not a link; it represents the current page. The component does this automatically when you set isCurrent.'},
+      {guidance: true, description: 'The component implements the WAI-ARIA APG Breadcrumb pattern: a labelled nav landmark wrapping an ordered list, with aria-current="page" on the current item. A crumb with a menu additionally implements the APG Menu Button pattern, opening on Enter, Space or ArrowDown and closing on Escape.'},
+      {guidance: true, description: 'Give each trail its own label when a page renders more than one, so the nav landmarks stay distinguishable in a screen reader landmark list.'},
       {guidance: false, description: 'Use breadcrumbs as the primary navigation. They supplement a sidebar or top nav, not replace it.'},
       {guidance: false, description: 'Show breadcrumbs on top-level pages that have no parent; they add clutter without helping the user.'},
       {guidance: false, description: 'Let the trail grow beyond 5 levels. If you need more, consider simplifying the page hierarchy instead.'},
+      {guidance: false, description: 'Mirror a separator the bidi algorithm already mirrors. An angle-quote glyph such as › is Bidi_Mirrored, so it flips under RTL on its own and rtlStyles.mirror would flip it back. An arrow glyph such as → and any Icon separator are not, so those do need rtlStyles.mirror through xstyle.'},
     ],
   },
 };
@@ -156,9 +177,12 @@ export const docsDense = {
       {guidance: true, description: 'Keep labels short + matching page titles they link to: "Settings" not "Application Settings Page".'},
       {guidance: true, description: 'Use supporting variant in dense UIs where the breadcrumb should be subtle.'},
       {guidance: true, description: 'Last item plain text, not a link; represents current page; done automatically when you set isCurrent.'},
+      {guidance: true, description: 'Implements APG Breadcrumb: labelled nav landmark + ol + aria-current="page". A menu crumb also implements APG Menu Button (Enter/Space/ArrowDown to open, Escape to close).'},
+      {guidance: true, description: 'Give each trail its own label when a page renders more than one.'},
       {guidance: false, description: 'Use as primary navigation; breadcrumbs supplement, not replace, a main nav.'},
       {guidance: false, description: 'Show on top-level pages with no parent.'},
       {guidance: false, description: 'Let the trail exceed 5 levels; simplify the hierarchy instead.'},
+      {guidance: false, description: 'Mirror a separator that already mirrors itself: › is Bidi_Mirrored and flips under RTL on its own. → and Icon separators are not, so those need rtlStyles.mirror via xstyle.'},
     ],
   },
 };

package/src/Breadcrumbs/Breadcrumbs.test.tsx

@@ -676,6 +676,37 @@ describe('BreadcrumbItem menu', () => {
     warn.mockRestore();
   });
 
+  it('reflects the variant on the item and menu-trigger theme targets', () => {
+    const {container} = render(
+      <Breadcrumbs variant="supporting">
+        <BreadcrumbItem href="/">Home</BreadcrumbItem>
+        <BreadcrumbItem menu={items}>Teams</BreadcrumbItem>
+        <BreadcrumbItem isCurrent>Overview</BreadcrumbItem>
+      </Breadcrumbs>,
+    );
+    // The variant selects between style objects on both elements, so a theme
+    // needs it as a data attribute on both targets to reach them.
+    for (const item of container.querySelectorAll('.astryx-breadcrumb-item')) {
+      expect(item).toHaveAttribute('data-variant', 'supporting');
+    }
+    expect(
+      container.querySelector('.astryx-breadcrumb-item-menu-trigger'),
+    ).toHaveAttribute('data-variant', 'supporting');
+  });
+
+  it('defaults the item theme target to the default variant', () => {
+    const {container} = render(
+      <Breadcrumbs>
+        <BreadcrumbItem href="/">Home</BreadcrumbItem>
+        <BreadcrumbItem isCurrent>Overview</BreadcrumbItem>
+      </Breadcrumbs>,
+    );
+    expect(container.querySelector('.astryx-breadcrumb-item')).toHaveAttribute(
+      'data-variant',
+      'default',
+    );
+  });
+
   it('keeps mid-trail separators intact around a menu crumb', () => {
     const {container} = render(
       <Breadcrumbs>

package/src/Button/Button.tsx

@@ -82,7 +82,10 @@ const styles = stylex.create({
     lineHeight: typeScaleVars['--text-label-leading'],
     fontWeight: fontWeightVars['--font-weight-medium'],
     whiteSpace: 'nowrap',
-    cursor: 'pointer',
+    cursor: {
+      default: 'pointer',
+      ':is(:disabled,[aria-disabled="true"])': 'default',
+    },
     transitionProperty:
       'background-image, background-color, color, opacity, transform',
     transitionDuration: {
@@ -98,7 +101,7 @@ const styles = stylex.create({
     },
   },
   disabled: {
-    cursor: 'not-allowed',
+    cursor: 'default',
     opacity: 0.5,
     backgroundImage: 'none',
     transform: {
@@ -107,11 +110,11 @@ const styles = stylex.create({
     },
   },
   ariaDisabled: {
+    // The variants' hover treatment already steps aside for
+    // `[aria-disabled]`; `:active` still matches a press on an aria-disabled
+    // button, so that one is suppressed here.
     backgroundImage: {
       default: 'none',
-      ':hover': {
-        '@media (hover: hover)': 'none',
-      },
       ':active': 'none',
     },
   },
@@ -198,7 +201,7 @@ const variants = stylex.create({
     color: colorVars['--color-on-accent'],
     backgroundImage: {
       default: null,
-      ':hover': {
+      ':hover:where(:not(:disabled,[aria-disabled="true"]))': {
         '@media (hover: hover)': `linear-gradient(${colorVars['--color-overlay-hover']}, ${colorVars['--color-overlay-hover']})`,
       },
       ':active': `linear-gradient(${colorVars['--color-overlay-pressed']}, ${colorVars['--color-overlay-pressed']})`,
@@ -209,7 +212,7 @@ const variants = stylex.create({
     color: colorVars['--color-text-primary'],
     backgroundImage: {
       default: null,
-      ':hover': {
+      ':hover:where(:not(:disabled,[aria-disabled="true"]))': {
         '@media (hover: hover)': `linear-gradient(${colorVars['--color-overlay-hover']}, ${colorVars['--color-overlay-hover']})`,
       },
       ':active': `linear-gradient(${colorVars['--color-overlay-pressed']}, ${colorVars['--color-overlay-pressed']})`,
@@ -220,7 +223,7 @@ const variants = stylex.create({
     color: colorVars['--color-text-primary'],
     backgroundImage: {
       default: null,
-      ':hover': {
+      ':hover:where(:not(:disabled,[aria-disabled="true"]))': {
         '@media (hover: hover)': `linear-gradient(${colorVars['--color-overlay-hover']}, ${colorVars['--color-overlay-hover']})`,
       },
       ':active': `linear-gradient(${colorVars['--color-overlay-pressed']}, ${colorVars['--color-overlay-pressed']})`,
@@ -235,7 +238,7 @@ const variants = stylex.create({
     outlineColor: {default: null, ':focus-visible': colorVars['--color-error']},
     backgroundImage: {
       default: null,
-      ':hover': {
+      ':hover:where(:not(:disabled,[aria-disabled="true"]))': {
         '@media (hover: hover)': `linear-gradient(${colorVars['--color-overlay-hover']}, ${colorVars['--color-overlay-hover']})`,
       },
       ':active': `linear-gradient(${colorVars['--color-overlay-pressed']}, ${colorVars['--color-overlay-pressed']})`,

package/src/Calendar/Calendar.tsx

@@ -18,6 +18,7 @@
  */
 
 import {
+  use,
   useState,
   useMemo,
   useCallback,
@@ -86,7 +87,7 @@ import type {
 } from '../utils/dateTypes';
 import {normalizeDayOfWeek} from '../utils/dateTypes';
 import {themeProps} from '../utils/themeProps';
-import {useTranslator} from '../i18n';
+import {useTranslator, InternationalizationContext} from '../i18n';
 
 /** Imperative handle for Calendar handleRef */
 
@@ -220,6 +221,7 @@ export type CalendarProps = CalendarSingleProps | CalendarRangeProps;
  */
 export function Calendar({ref, ...props}: CalendarProps) {
   const t = useTranslator();
+  const {locale} = use(InternationalizationContext);
   const {
     handleRef,
     mode = 'single',
@@ -327,12 +329,12 @@ export function Calendar({ref, ...props}: CalendarProps) {
   // Format month header
   const monthYearLabel = useMemo(() => {
     if (numberOfMonths === 1) {
-      return plainDateFormat(visibleMonths[0], DATE_FORMAT_MONTH_YEAR);
+      return plainDateFormat(visibleMonths[0], DATE_FORMAT_MONTH_YEAR, locale);
     }
     return visibleMonths
-      .map(m => plainDateFormat(m, DATE_FORMAT_MONTH_YEAR))
+      .map(m => plainDateFormat(m, DATE_FORMAT_MONTH_YEAR, locale))
       .join(' – ');
-  }, [visibleMonths, numberOfMonths]);
+  }, [visibleMonths, numberOfMonths, locale]);
 
   // Announce the newly visible month to screen readers whenever it changes.
   // The visible month label (`<span>`) carries no live semantics, so paging the
@@ -440,7 +442,7 @@ export function Calendar({ref, ...props}: CalendarProps) {
           setRangeSelectionStart(iso);
           announce(
             t('@astryx.calendar.rangeStartAnnounce', {
-              date: plainDateFormat(date, DATE_FORMAT_WITH_WEEKDAY),
+              date: plainDateFormat(date, DATE_FORMAT_WITH_WEEKDAY, locale),
             }),
           );
         } else {
@@ -486,17 +488,19 @@ export function Calendar({ref, ...props}: CalendarProps) {
               start: plainDateFormat(
                 plainDateFromISO(start),
                 DATE_FORMAT_WITH_WEEKDAY,
+                locale,
               ),
               end: plainDateFormat(
                 plainDateFromISO(end),
                 DATE_FORMAT_WITH_WEEKDAY,
+                locale,
               ),
             }),
           );
         }
       }
     },
-    [mode, onChange, rangeSelectionStart, announce, t],
+    [mode, onChange, rangeSelectionStart, announce, t, locale],
   );
 
   return (
@@ -645,6 +649,7 @@ function MonthGrid({
   pendingFocus,
   onPendingFocusHandled,
 }: MonthGridProps) {
+  const {locale} = use(InternationalizationContext);
   const year = month.year;
 
   // Use hooks for days generation and constraints
@@ -866,8 +871,8 @@ function MonthGrid({
 
   // Month label for announcements
   const monthLabel = useMemo(() => {
-    return plainDateFormat(month, DATE_FORMAT_MONTH_YEAR);
-  }, [month]);
+    return plainDateFormat(month, DATE_FORMAT_MONTH_YEAR, locale);
+  }, [month, locale]);
 
   return (
     <div {...stylex.props(monthGridStyles.monthGrid)}>
@@ -1025,6 +1030,7 @@ function DayCell({
   onDayHover,
 }: DayCellProps) {
   const t = useTranslator();
+  const {locale} = use(InternationalizationContext);
   const {date, isOutside, dayNumber} = day;
 
   if (isOutside && !hasOutsideDays) {
@@ -1070,7 +1076,7 @@ function DayCell({
   // params rather than string concatenation. A mid-flight first pick (where
   // rangeStart === rangeEnd) reads as "range start" only; a completed one-day
   // range reads as both start and end.
-  const dateLabel = plainDateFormat(date, DATE_FORMAT_WITH_WEEKDAY);
+  const dateLabel = plainDateFormat(date, DATE_FORMAT_WITH_WEEKDAY, locale);
   const dayLabel = state.isSelected
     ? t('@astryx.calendar.daySelected', {date: dateLabel})
     : state.isRangeStart && state.isRangeEnd

package/src/Calendar/hooks/useCalendarNavigation.ts

@@ -12,7 +12,7 @@
  * - /packages/core/src/Calendar/hooks/index.ts
  */
 
-import {useState, useMemo, useCallback} from 'react';
+import {use, useState, useMemo, useCallback} from 'react';
 import type {ISODateString} from '../../utils/dateTypes';
 import {
   type PlainDate,
@@ -25,6 +25,7 @@ import {
   plainDateFormat,
   DATE_FORMAT_MONTH_YEAR,
 } from '../../utils/plainDate';
+import {InternationalizationContext} from '../../i18n';
 
 /**
  * Configuration for calendar navigation
@@ -98,6 +99,7 @@ export function useCalendarNavigation(
     onFocusDateChange,
     numberOfMonths = 1,
   } = options;
+  const {locale} = use(InternationalizationContext);
 
   // Pending focus target after month navigation
   const [pendingFocus, setPendingFocus] = useState<ISODateString | null>(null);
@@ -135,12 +137,12 @@ export function useCalendarNavigation(
   // Format month header
   const monthYearLabel = useMemo(() => {
     if (numberOfMonths === 1) {
-      return plainDateFormat(visibleMonths[0], DATE_FORMAT_MONTH_YEAR);
+      return plainDateFormat(visibleMonths[0], DATE_FORMAT_MONTH_YEAR, locale);
     }
     return visibleMonths
-      .map(m => plainDateFormat(m, DATE_FORMAT_MONTH_YEAR))
+      .map(m => plainDateFormat(m, DATE_FORMAT_MONTH_YEAR, locale))
       .join(' – ');
-  }, [visibleMonths, numberOfMonths]);
+  }, [visibleMonths, numberOfMonths, locale]);
 
   // Navigate to previous/next month
   const navigateMonth = useCallback(

package/src/Calendar/styles.ts

@@ -198,7 +198,10 @@ export const dayCellStyles = stylex.create({
     borderRadius: '50%',
     borderWidth: 0,
     borderStyle: 'none',
-    cursor: 'pointer',
+    cursor: {
+      default: 'pointer',
+      ':is(:disabled,[aria-disabled="true"])': 'default',
+    },
     fontFamily: 'inherit',
     fontSize: typeScaleVars['--text-body-size'],
     padding: 0,
@@ -229,7 +232,7 @@ export const dayCellStyles = stylex.create({
   dayTodayInRange: {},
   daySelected: {},
   dayDisabled: {
-    cursor: 'not-allowed',
+    cursor: 'default',
   },
 });
 
@@ -254,7 +257,7 @@ export const dayCellTheme = stylex.create({
     backgroundColor: 'transparent',
     backgroundImage: {
       default: null,
-      ':hover': {
+      ':hover:where(:not(:disabled,[aria-disabled="true"]))': {
         '@media (hover: hover)': `linear-gradient(${colorVars['--color-overlay-hover']}, ${colorVars['--color-overlay-hover']})`,
       },
     },
@@ -281,7 +284,7 @@ export const dayCellTheme = stylex.create({
     color: colorVars['--color-on-accent'],
     backgroundImage: {
       default: null,
-      ':hover': {
+      ':hover:where(:not(:disabled,[aria-disabled="true"]))': {
         '@media (hover: hover)': `linear-gradient(${colorVars['--color-overlay-hover']}, ${colorVars['--color-overlay-hover']})`,
       },
     },
@@ -292,7 +295,7 @@ export const dayCellTheme = stylex.create({
     opacity: 0.3,
     backgroundImage: {
       default: 'none',
-      ':hover': {
+      ':hover:where(:not(:disabled,[aria-disabled="true"]))': {
         '@media (hover: hover)': 'none',
       },
     },

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',