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

package/src/MobileNav/MobileNavScrollbarGutter.test.tsx

@@ -0,0 +1,109 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file MobileNavScrollbarGutter.test.tsx
+ * @input Uses vitest, @testing-library/react, MobileNav, a stubbed viewport
+ * @output Unit tests for the scrollbar gutter MobileNav reserves while open
+ * @position Testing; guards MobileNav.tsx against the open-drawer page shift
+ *
+ * MobileNav clips the document to lock background scroll, which hides a
+ * classic scrollbar and widens the layout viewport by its width — the page
+ * behind the drawer jumps sideways. The clip has to be paired with holding
+ * that gutter open.
+ *
+ * SYNC: When MobileNav.tsx changes, update tests to match new behavior
+ */
+
+import {describe, it, expect, beforeAll, afterEach} from 'vitest';
+import {render, cleanup} from '@testing-library/react';
+import {MobileNav} from './MobileNav';
+
+beforeAll(() => {
+  // jsdom doesn't implement showModal/close on <dialog>
+  HTMLDialogElement.prototype.showModal =
+    HTMLDialogElement.prototype.showModal ||
+    function (this: HTMLDialogElement) {
+      this.setAttribute('open', '');
+    };
+  HTMLDialogElement.prototype.close =
+    HTMLDialogElement.prototype.close ||
+    function (this: HTMLDialogElement) {
+      this.removeAttribute('open');
+    };
+});
+
+/** jsdom does no layout, so both halves of the measurement are stubbed. */
+function stubViewport(innerWidth: number, clientWidth: number) {
+  Object.defineProperty(window, 'innerWidth', {
+    value: innerWidth,
+    configurable: true,
+    writable: true,
+  });
+  Object.defineProperty(document.documentElement, 'clientWidth', {
+    value: clientWidth,
+    configurable: true,
+  });
+}
+
+const rootGutter = () => document.documentElement.style.scrollbarGutter;
+
+describe('MobileNav scrollbar gutter', () => {
+  afterEach(() => {
+    cleanup();
+    document.documentElement.style.cssText = '';
+    // @ts-expect-error -- drop the viewport stub so jsdom's own value comes back
+    delete document.documentElement.clientWidth;
+  });
+
+  it('holds the gutter open while the drawer is open', () => {
+    stubViewport(1024, 1009);
+
+    const view = render(
+      <MobileNav isOpen={true} onOpenChange={() => {}}>
+        <span>Nav content</span>
+      </MobileNav>,
+    );
+
+    expect(document.documentElement.style.overflow).toBe('clip');
+    expect(rootGutter()).toBe('stable');
+
+    view.unmount();
+
+    expect(document.documentElement.style.overflow).toBe('');
+    expect(rootGutter()).toBe('');
+  });
+
+  it('gives the gutter back when the drawer closes', () => {
+    stubViewport(1024, 1009);
+
+    const view = render(
+      <MobileNav isOpen={true} onOpenChange={() => {}}>
+        <span>Nav content</span>
+      </MobileNav>,
+    );
+
+    expect(rootGutter()).toBe('stable');
+
+    view.rerender(
+      <MobileNav isOpen={false} onOpenChange={() => {}}>
+        <span>Nav content</span>
+      </MobileNav>,
+    );
+
+    expect(rootGutter()).toBe('');
+  });
+
+  it('holds nothing when the scrollbar is an overlay one', () => {
+    stubViewport(1024, 1024);
+
+    render(
+      <MobileNav isOpen={true} onOpenChange={() => {}}>
+        <span>Nav content</span>
+      </MobileNav>,
+    );
+
+    expect(document.documentElement.style.overflow).toBe('clip');
+    expect(rootGutter()).toBe('');
+    expect(document.documentElement.style.paddingRight).toBe('');
+  });
+});

package/src/MultiSelector/MultiSelector.tsx

@@ -73,6 +73,7 @@ import {
 import {useMultiCombobox} from './hooks';
 import {getInputARIA, isImeKeyEvent, mergeProps} from '../utils';
 import {useAnnounce} from '../hooks/useAnnounce';
+import {useResolvedRequired} from '../hooks/useResolvedRequired';
 import type {BaseProps} from '../BaseProps';
 import type {SizeValue} from '../utils/types';
 import {useSize} from '../SizeContext/SizeContext';
@@ -706,6 +707,7 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
   style,
 }: MultiSelectorProps<T>) {
   const t = useTranslator();
+  const isEffectivelyRequired = useResolvedRequired({isRequired, isOptional});
   const placeholder =
     placeholderFromProps ?? t('@astryx.multiSelector.selectPlaceholder');
   const selectAllLabel =
@@ -1526,7 +1528,7 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
           }
           aria-describedby={ariaDescribedBy}
           aria-labelledby={ariaLabelledBy}
-          aria-required={isRequired ? 'true' : undefined}
+          aria-required={isEffectivelyRequired ? 'true' : undefined}
           aria-invalid={status?.type === 'error' ? 'true' : undefined}
           aria-busy={isBusy || undefined}
           // With a disabledMessage the trigger keeps focusability via

package/src/NumberInput/NumberInput.doc.mjs

@@ -219,6 +219,19 @@ export const docs = {
         states: ['disabled', 'readonly'],
       },
     ],
+    derived: [
+      // `padding` in any spelling — the shorthand, `paddingBlock`, or a lone
+      // `paddingBlockStart` — is parsed by the shared container expansion and
+      // emitted as normalized per-side `--astryx-number-input-padding-*`
+      // tokens. The wrapper and the number-stepper column both read those, so
+      // the column stays flush with the field edges under a themed padding.
+      {property: 'padding', expand: 'container'},
+      // Scoped to this component's own subtree: the stepper column's outer
+      // corners follow the field radius, so a themed `number-input`
+      // borderRadius has to reach the var the column reads, not just the
+      // wrapper's own `border-radius`.
+      {property: 'borderRadius', vars: ['--_field-radius']},
+    ],
   },
   usage: {
     description:
@@ -475,6 +488,17 @@ export const docsZh = {
         states: ['disabled', 'readonly'],
       },
     ],
+    derived: [
+      // 任何写法的 `padding`（简写、`paddingBlock`，或单独的
+      // `paddingBlockStart`）都由共享的 container 展开解析，并输出为规范化的
+      // 每侧 `--astryx-number-input-padding-*` 令牌。容器与数字步进器列都读取
+      // 这些令牌，因此在主题化内边距下步进器仍与字段边缘齐平。
+      {property: 'padding', expand: 'container'},
+      // 作用域限于该组件自身的子树：步进器列的外角跟随字段圆角，因此主题化的
+      // `number-input` borderRadius 必须传到步进器读取的变量，而不只是容器
+      // 自身的 `border-radius`。
+      {property: 'borderRadius', vars: ['--_field-radius']},
+    ],
   },
   usage: {
     description:

package/src/NumberInput/NumberInput.test.tsx

@@ -15,6 +15,8 @@ import userEvent from '@testing-library/user-event';
 import {TestIcon} from '../__tests__/TestIcon';
 import {InputGroup} from '../InputGroup';
 import {NumberInput} from './NumberInput';
+import {defineTheme} from '../theme/defineTheme';
+import {generateThemeCSS} from '../theme/generateThemeRules';
 import {__resetLiveRegionsForTest} from '../hooks/useAnnounce';
 
 // FieldStatus announces status messages through the persistent useAnnounce
@@ -1745,3 +1747,139 @@ describe('NumberInput readonly theme state', () => {
     expect(root).not.toHaveAttribute('data-readonly');
   });
 });
+
+describe('NumberInput stepper padding coupling', () => {
+  function generateThemeTestCSS(theme: Parameters<typeof generateThemeCSS>[0]) {
+    const {prose, component} = generateThemeCSS(theme);
+    return [prose, component].filter(Boolean).join('\n\n');
+  }
+
+  // The chains the wrapper and the stepper column both read. Spelled out here
+  // rather than imported so the test pins the actual token names a theme sets:
+  // if the chain is renamed or a level is dropped, this fails.
+  const BLOCK_START =
+    'var(--astryx-number-input-padding-block-start, var(--astryx-number-input-padding, var(--spacing-1)))';
+  const BLOCK_END =
+    'var(--astryx-number-input-padding-block-end, var(--astryx-number-input-padding, var(--spacing-1)))';
+
+  // jsdom re-serializes a var() chain without the spaces after its commas.
+  const noSpace = (value: string) => value.replace(/\s+/g, '');
+
+  it('reads its padding from the public number-input padding tokens', () => {
+    const {container} = render(
+      <NumberInput
+        label="Quantity"
+        value={5}
+        onChange={() => {}}
+        hasNumberSteppers
+      />,
+    );
+    const root = container.querySelector('.astryx-number-input') as HTMLElement;
+    // Read as physical properties: StyleX compiles the block-axis logical
+    // properties to `padding-top`/`padding-bottom` (identical in every
+    // horizontal writing mode). Per side, not through the shared field base's
+    // `paddingBlock` shorthand, so each edge can be cancelled on its own.
+    const wrapper = getComputedStyle(root);
+    expect(noSpace(wrapper.paddingTop)).toBe(noSpace(BLOCK_START));
+    expect(noSpace(wrapper.paddingBottom)).toBe(noSpace(BLOCK_END));
+
+    // The column cancels the wrapper's block padding by reading the same
+    // tokens — not a hardcoded default — so it stays flush when a theme
+    // changes the padding. The column is the stepper buttons' direct parent.
+    const steppers = container.querySelector(
+      'button[aria-label="Increment Quantity"]',
+    )?.parentElement as HTMLElement;
+    const column = getComputedStyle(steppers);
+    expect(noSpace(column.marginTop)).toBe(
+      noSpace(`calc(-1 * ${BLOCK_START})`),
+    );
+    expect(noSpace(column.marginBottom)).toBe(
+      noSpace(`calc(-1 * ${BLOCK_END})`),
+    );
+  });
+
+  // jsdom cannot resolve the @layer cascade, so the generated CSS is the
+  // proof. Each case is a spelling of the SAME declaration: the column has to
+  // track all of them, not just the one the component happened to name.
+  describe('a themed padding reaches the steppers in every spelling', () => {
+    it.each([
+      [
+        'the padding shorthand, two values',
+        {padding: '14px 20px'},
+        [
+          '--astryx-number-input-padding-block-start: 14px',
+          '--astryx-number-input-padding-block-end: 14px',
+          '--astryx-number-input-padding-inline: 20px',
+        ],
+      ],
+      [
+        'the padding shorthand, one value',
+        {padding: '10px'},
+        ['--astryx-number-input-padding: 10px'],
+      ],
+      [
+        'the block/inline longhands',
+        {paddingBlock: '10px', paddingInline: '20px'},
+        [
+          '--astryx-number-input-padding-block-start: 10px',
+          '--astryx-number-input-padding-block-end: 10px',
+          '--astryx-number-input-padding-inline: 20px',
+        ],
+      ],
+      [
+        'a single edge longhand',
+        {paddingBlockStart: '12px'},
+        ['--astryx-number-input-padding-block-start: 12px'],
+      ],
+      [
+        // A single var carrying "4px 12px" would make the column's
+        // calc(-1 * …) invalid and drop the margin outright; the expansion
+        // splits the two values into their own edges instead.
+        'an asymmetric block padding',
+        {paddingBlock: '4px 12px'},
+        [
+          '--astryx-number-input-padding-block-start: 4px',
+          '--astryx-number-input-padding-block-end: 12px',
+        ],
+      ],
+      [
+        // `paddingTop` is `paddingBlockStart` in every horizontal writing
+        // mode, so it normalizes onto the same tokens. The physical inline
+        // pair is deliberately not mapped — see generateThemeRules.
+        'the physical block longhands',
+        {paddingTop: '14px', paddingBottom: '6px'},
+        [
+          '--astryx-number-input-padding-block-start: 14px',
+          '--astryx-number-input-padding-block-end: 6px',
+        ],
+      ],
+    ])('%s', (_label, base, expected) => {
+      const theme = defineTheme({
+        name: 'number-input-padding-spelling-test',
+        components: {'number-input': {base}},
+      });
+      const css = generateThemeTestCSS(theme);
+      for (const declaration of expected) {
+        expect(css).toContain(declaration);
+      }
+      // The expansion consumes the padding: a raw declaration left on the
+      // wrapper is padding the column cannot see, which is the gap itself.
+      expect(css).not.toMatch(
+        /^\s*padding(-block|-inline|-top|-bottom)?(-start|-end)?:/m,
+      );
+    });
+  });
+
+  it('carries a themed border radius to the stepper column corners', () => {
+    // The column's outer corners read --_field-radius. Emitting only
+    // `border-radius` on the wrapper rounds the field and leaves the steppers
+    // at the default radius, which is visible wherever the two differ.
+    const theme = defineTheme({
+      name: 'number-input-radius-test',
+      components: {'number-input': {base: {borderRadius: '2px'}}},
+    });
+    const css = generateThemeTestCSS(theme);
+    expect(css).toContain('--_field-radius: 2px');
+    expect(css).toContain('border-radius: 2px');
+  });
+});

package/src/NumberInput/NumberInput.tsx

@@ -31,7 +31,6 @@ import {
   colorVars,
   sizeVars,
   spacingVars,
-  radiusVars,
   typographyVars,
   typeScaleVars,
   borderVars,
@@ -53,11 +52,44 @@ import {getInputARIA} from '../utils';
 import {useSize} from '../SizeContext/SizeContext';
 import {useInputContainer} from '../hooks/useInputContainer';
 import {useInputStatusIcon} from '../hooks/useInputStatusIcon';
+import {useResolvedRequired} from '../hooks/useResolvedRequired';
 import {useInputGroup} from '../InputGroup/InputGroupContext';
 
+// Public padding tokens for the `number-input` theme target. A theme writes an
+// ordinary `padding` (in ANY spelling — the shorthand, `paddingBlock`, or a
+// single `paddingBlockStart`) and the pipeline's `container` expansion parses
+// it and emits these normalized per-side tokens; the wrapper and the stepper
+// column both read them, so the column tracks whatever the theme sets instead
+// of assuming the default. Routing through the shared expansion rather than a
+// hand-rolled property→var mapping is what makes every spelling work: a
+// mapping only fires for the exact property name it names.
+//
+// Read order per level: `var(--astryx-…, <next level>)`, terminating at the
+// shared field defaults (NOT the container default --spacing-4, which is a
+// layout metric and would resize every themed field). Built as chained const
+// strings — no function calls — so StyleX can statically analyze them; same
+// shape as the card/section/dialog chains in Layout/container.stylex.ts.
+const FIELD_PAD_BLOCK = spacingVars['--spacing-1'];
+const FIELD_PAD_INLINE = spacingVars['--spacing-2'];
+const padBlockAll = `var(--astryx-number-input-padding, ${FIELD_PAD_BLOCK})`;
+const padInlineAll = `var(--astryx-number-input-padding, ${FIELD_PAD_INLINE})`;
+const padInline = `var(--astryx-number-input-padding-inline, ${padInlineAll})`;
+const padInlineStart = `var(--astryx-number-input-padding-inline-start, ${padInline})`;
+const padInlineEnd = `var(--astryx-number-input-padding-inline-end, ${padInline})`;
+const padBlockStart = `var(--astryx-number-input-padding-block-start, ${padBlockAll})`;
+const padBlockEnd = `var(--astryx-number-input-padding-block-end, ${padBlockAll})`;
+
 const styles = stylex.create({
   wrapper: {
     zIndex: 1,
+    // Applied per side rather than through the shared field base's
+    // `paddingBlock`/`paddingInline` shorthands, because the stepper column
+    // has to cancel the block padding edge by edge — an asymmetric
+    // `paddingBlock: 4px 12px` needs two different negative margins.
+    paddingBlockStart: padBlockStart,
+    paddingBlockEnd: padBlockEnd,
+    paddingInlineStart: padInlineStart,
+    paddingInlineEnd: padInlineEnd,
   },
   wrapperWithNumberSteppers: {
     paddingInlineEnd: 0,
@@ -101,13 +133,18 @@ const styles = stylex.create({
     flexDirection: 'column',
     flexShrink: 0,
     width: spacingVars['--spacing-4'],
-    marginBlock: `calc(-1 * ${spacingVars['--spacing-1']})`,
+    // Cancel the wrapper's block padding edge by edge so the column spans the
+    // field's full height. Reading the same tokens the wrapper applies is what
+    // keeps it flush under a themed padding — including an asymmetric one,
+    // where a single `marginBlock` would be wrong at one end.
+    marginBlockStart: `calc(-1 * ${padBlockStart})`,
+    marginBlockEnd: `calc(-1 * ${padBlockEnd})`,
     borderInlineStartWidth: borderVars['--border-width'],
     borderInlineStartStyle: 'solid',
     borderInlineStartColor: colorVars['--color-border-emphasized'],
     overflow: 'hidden',
-    borderStartEndRadius: radiusVars['--radius-element'],
-    borderEndEndRadius: radiusVars['--radius-element'],
+    borderStartEndRadius: 'var(--_field-radius)',
+    borderEndEndRadius: 'var(--_field-radius)',
   },
   numberStepperButton: {
     boxSizing: 'border-box',
@@ -559,6 +596,7 @@ export function NumberInput({
   ...rest
 }: NumberInputProps) {
   const t = useTranslator();
+  const isEffectivelyRequired = useResolvedRequired({isRequired, isOptional});
   const size = useSize(sizeProp, 'md');
   const id = useId();
   const inputLabelID = useId();
@@ -927,7 +965,7 @@ export function NumberInput({
           value == null || !formatValue ? undefined : formattedValue
         }
         aria-describedby={ariaDescribedBy}
-        aria-required={isRequired === true ? 'true' : undefined}
+        aria-required={isEffectivelyRequired ? 'true' : undefined}
         aria-invalid={
           status?.type === 'error' || !isInputValid ? 'true' : undefined
         }

package/src/Outline/Outline.doc.mjs

@@ -166,6 +166,8 @@ import {Outline, useOutlineFromMarkdown} from '@astryxdesign/core/Outline';
 
 function MarkdownOutline({markdown}) {
   // Derives {id, label, level} items from headings in the source.
+  // The Markdown component renders the same generated ids on its
+  // headings, so outline links scroll without any extra wiring.
   const items = useOutlineFromMarkdown(markdown);
   return <Outline items={items} />;
 }

package/src/Outline/parseOutlineFromMarkdown.ts

@@ -2,7 +2,8 @@
 
 /**
  * @file parseOutlineFromMarkdown.ts
- * @input Uses Markdown parser internals and OutlineItem type
+ * @input Uses Markdown parser internals (parseMarkdown + heading slug
+ *   helpers) and OutlineItem type
  * @output Exports parseOutlineFromMarkdown for extracting heading outlines from Markdown
  * @position Pure utility; consumed by useOutlineFromMarkdown and public exports
  *
@@ -11,52 +12,21 @@
  * - /packages/core/src/Outline/index.ts
  */
 
-import {parseMarkdown, type InlineNode} from '../Markdown/parser';
+import {
+  parseMarkdown,
+  inlineText,
+  slugify,
+  uniqueSlug,
+} from '../Markdown/parser';
 import type {OutlineItem} from './types';
 
-function inlineText(nodes: InlineNode[]): string {
-  return nodes
-    .map(node => {
-      switch (node.type) {
-        case 'text':
-        case 'code':
-          return node.content;
-        case 'bold':
-        case 'italic':
-        case 'strikethrough':
-        case 'link':
-          return inlineText(node.children);
-        case 'image':
-          return node.alt;
-        case 'citation':
-        case 'break':
-          return '';
-      }
-    })
-    .join('');
-}
-
-function slugify(value: string): string {
-  return value
-    .trim()
-    .toLowerCase()
-    .replace(/['"]/g, '')
-    .replace(/[^a-z0-9]+/g, '-')
-    .replace(/^-+|-+$/g, '');
-}
-
-function uniqueSlug(baseSlug: string, counts: Map<string, number>): string {
-  const fallbackSlug = baseSlug || 'section';
-  const count = counts.get(fallbackSlug) ?? 0;
-  counts.set(fallbackSlug, count + 1);
-  return count === 0 ? fallbackSlug : `${fallbackSlug}-${count}`;
-}
-
 /**
  * Extract heading items from a Markdown string.
  *
  * Uses Markdown's parser so fenced code blocks, tables, lists, and inline
  * formatting are interpreted consistently with rendered Markdown output.
+ * Ids come from the parser's shared slug helpers, so they always match the
+ * `id` attributes Markdown renders on its headings.
  */
 export function parseOutlineFromMarkdown(markdown: string): OutlineItem[] {
   const counts = new Map<string, number>();

package/src/RadioList/RadioList.tsx

@@ -29,6 +29,7 @@ import {spacingVars} from '../theme/tokens.stylex';
 import {Field} from '../Field/Field';
 import type {InputStatus} from '../Field/types';
 import {useTooltip} from '../Tooltip';
+import {useResolvedRequired} from '../hooks/useResolvedRequired';
 import {mergeProps} from '../utils';
 import type {BaseProps} from '../BaseProps';
 import type {SizeValue} from '../utils/types';
@@ -218,6 +219,13 @@ export function RadioList({
 
   const groupRef = useRef<HTMLDivElement>(null);
 
+  // The radiogroup exposes the *effective* required state so a form-wide
+  // `defaultOptionality="required"` is announced even when the group carries no
+  // visible indicator. Individual radios keep their native `required` bound to
+  // the explicit `isRequired` (via context), so a layout default never switches
+  // on browser validation for the group.
+  const isEffectivelyRequired = useResolvedRequired({isRequired, isOptional});
+
   // Disabled-reason tooltip. Applies to the whole-group disabled state. Disabled
   // controls swallow pointer events, so the tooltip listeners attach to the
   // radiogroup container and the radios stay perceivable via aria-disabled
@@ -387,7 +395,7 @@ export function RadioList({
             .join(' ') || undefined
         }
         aria-invalid={status?.type === 'error' ? true : undefined}
-        aria-required={isRequired || undefined}
+        aria-required={isEffectivelyRequired || undefined}
         {...mergeProps(
           themeProps('radio-list', {orientation, size}),
           stylex.props(

package/src/Resizable/ResizeHandle.test.tsx

@@ -344,6 +344,28 @@ describe('ResizeHandle', () => {
     expect(hitArea.className).not.toContain('hitAreaOffsetX');
   });
 
+  // The grab zone is stretched along the handle by its 0/0 insets, so anything
+  // that moves it across the handle displaces the whole zone off the divider —
+  // a percentage does it by half the handle's length, so the taller the panel
+  // the larger the dead region, and nothing about it is visible on screen.
+  it.each([
+    ['horizontal' as const, 'translateX'],
+    ['vertical' as const, 'translateY'],
+  ])('offsets the %s grab zone along the pill axis only', (direction, axis) => {
+    render(<Harness handleProps={{direction, pillPlacement: 'start'}} />);
+    const hitArea = getSeparator().firstElementChild as HTMLElement;
+    const translates = (hitArea.getAttribute('style') ?? '')
+      .split(';')
+      .map(decl => decl.split(/:(.*)/s)[1]?.trim() ?? '')
+      .filter(value => value.startsWith('translate'));
+
+    // Both the LTR and RTL declarations of the horizontal offset.
+    expect(translates.length).toBeGreaterThan(0);
+    for (const translate of translates) {
+      expect(translate.startsWith(`${axis}(`)).toBe(true);
+    }
+  });
+
   // --- Prop composition (ordering choice: handler sits after {...props}) ---
 
   it('runs a consumer onKeyDown alongside keyboard resizing', () => {

package/src/Resizable/ResizeHandle.tsx

@@ -219,16 +219,22 @@ const dynamicStyles = stylex.create({
   // directions because the pill's own offset is physical. Mixing the previous
   // divider-relative `50%` anchor with a percentage translate stranded the grab
   // zone to one side under RTL; this construction keeps it on the pill.
+  //
+  // Only the offset axis is translated. Unlike the pill — a small box anchored
+  // at the divider's midpoint, so it needs a −50% self-shift to centre — the
+  // grab zone is STRETCHED along the handle by hitAreaHorizontal/Vertical's
+  // 0/0 insets, so it is already in place on that axis. A percentage there
+  // would displace it by half the handle's own length, growing with the panel.
   hitAreaOffsetX: (dir: number) => ({
     insetInlineStart: 0,
     transform: {
-      default: `translate(calc(${dir} * (3px + ${spacingVars['--spacing-1']}) - 6.5px), -50%)`,
-      ':is([dir="rtl"] *)': `translate(calc(${dir} * (3px + ${spacingVars['--spacing-1']}) + 6.5px), -50%)`,
+      default: `translateX(calc(${dir} * (3px + ${spacingVars['--spacing-1']}) - 6.5px))`,
+      ':is([dir="rtl"] *)': `translateX(calc(${dir} * (3px + ${spacingVars['--spacing-1']}) + 6.5px))`,
     },
   }),
   hitAreaOffsetY: (dir: number) => ({
     insetBlockStart: 0,
-    transform: `translate(-50%, calc(${dir} * (3px + ${spacingVars['--spacing-1']}) - 6.5px))`,
+    transform: `translateY(calc(${dir} * (3px + ${spacingVars['--spacing-1']}) - 6.5px))`,
   }),
   pillOffsetX: (dir: number) => ({
     insetInlineStart: 0,

package/src/Section/Section.doc.mjs

@@ -53,11 +53,36 @@ export const docs = {
       description: 'Internal padding using the spacing scale (0, 0.5, 1, 1.5, 2, 3, 4, 5, 6, 8, 10). Use padding={0} for edge-to-edge content.',
       default: '4',
     },
+    {
+      name: 'paddingInline',
+      type: '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10',
+      description: 'Inline (horizontal) padding override. Overrides only the inline-axis padding while preserving block padding from `padding` or the container theme default. Accepts the spacing scale (0, 0.5, 1, 1.5, 2, 3, 4, 5, 6, 8, 10).',
+    },
+    {
+      name: 'paddingInlineStart',
+      type: '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10',
+      description: 'Inline-start padding override (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 override (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 override. Overrides only the block-axis padding while preserving inline padding from `padding` or the container theme default. Accepts the spacing scale (0, 0.5, 1, 1.5, 2, 3, 4, 5, 6, 8, 10).',
     },
+    {
+      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: 'xstyle',
       type: 'StyleXStyles',
@@ -135,11 +160,36 @@ export const docsZh = {
       description: '使用间距比例的内部内边距（0, 0.5, 1, 1.5, 2, 3, 4, 5, 6, 8, 10）。使用 padding={0} 实现全宽内容。',
       default: '4',
     },
+    {
+      name: 'paddingInline',
+      type: '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10',
+      description: '行内（水平）方向内边距覆盖。仅覆盖行内轴内边距，同时保留来自 padding 或容器主题默认值的块内边距。使用间距比例（0, 0.5, 1, 1.5, 2, 3, 4, 5, 6, 8, 10）。',
+    },
+    {
+      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 或容器主题默认值的行内内边距。使用间距比例（0, 0.5, 1, 1.5, 2, 3, 4, 5, 6, 8, 10）。',
     },
+    {
+      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: 'xstyle',
       type: 'StyleXStyles',
@@ -192,7 +242,12 @@ export const docsDense = {
     children: 'Content rendered inside section.',
     dividers: 'Which sides of section have divider borders.',
     padding: 'Internal padding via spacing scale; 0 for edge-to-edge content.',
+    paddingInline: 'Inline-axis padding override; preserves block padding from padding/theme.',
+    paddingInlineStart: 'Inline-start (left in LTR) padding override; wins over paddingInline/padding on that edge.',
+    paddingInlineEnd: 'Inline-end (right in LTR) padding override; wins over paddingInline/padding on that edge.',
     paddingBlock: 'Block-axis padding override; preserves inline padding from padding/theme.',
+    paddingBlockStart: 'Block-start (top) padding override; wins over paddingBlock/padding on that edge.',
+    paddingBlockEnd: 'Block-end (bottom) padding override; wins over paddingBlock/padding on that edge.',
     xstyle: 'StyleX styles for layout customization; must be stylex.create() value.',
   },
 };