@astryxdesign/core 0.2.0 → 0.3.0-canary.041a0ef

package/src/Button/Button.test.tsx

@@ -14,6 +14,7 @@ import {render, screen, fireEvent, act} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {Button} from './Button';
 import {Badge} from '../Badge/Badge';
+import {InternationalizationProvider} from '../i18n';
 
 describe('Button', () => {
   it('renders label as visible text', () => {
@@ -446,6 +447,21 @@ describe('Button', () => {
     expect(liveRegion).toHaveTextContent('Loading');
   });
 
+  it('localizes the loading announcement through the i18n catalog', () => {
+    render(
+      <InternationalizationProvider
+        locale="fr"
+        overrides={{fr: {'@astryx.button.loading': 'Chargement'}}}>
+        <Button label="Submit" isLoading />
+      </InternationalizationProvider>,
+    );
+    const button = screen.getByRole('button');
+    // The Spinner also has role="status", so grab the live region explicitly.
+    const regions = button.querySelectorAll('[role="status"]');
+    const liveRegion = regions[regions.length - 1];
+    expect(liveRegion).toHaveTextContent('Chargement');
+  });
+
   describe('elevation', () => {
     it('renders a distinct class for each elevation level', () => {
       const classFor = (elevation: 'none' | 'low' | 'med' | 'high') => {

package/src/Button/Button.tsx

@@ -4,7 +4,7 @@
 
 /**
  * @file Button.tsx
- * @input Uses React, ButtonHTMLAttributes, ReactNode
+ * @input Uses React, ButtonHTMLAttributes, ReactNode, i18n (useTranslator)
  * @output Exports Button component, ButtonProps, ButtonVariant types
  * @position Core implementation; consumed by index.ts, tested by Button.test.tsx
  *
@@ -13,7 +13,7 @@
  * - /packages/core/src/Button/Button.test.tsx (tests for new/changed behavior)
  * - /packages/core/src/Button/index.ts (exports if types change)
  * - /apps/storybook/stories/Button.stories.tsx (storybook stories)
- * - /packages/cli/templates/blocks/components/Button/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/Button/ (showcase blocks)
  *
  * Last synced props: label, variant, size, isDisabled, isLoading, isInterruptible, clickAction, icon, isIconOnly, width, children, tooltip, endContent, href, as, target, rel
  */
@@ -45,6 +45,9 @@ import {mergeProps, mergeRefs} from '../utils';
 import {useLinkComponent} from '../Link/useLinkComponent';
 import type {LinkComponentType} from '../Link/types';
 import {themeProps} from '../utils/themeProps';
+import {focusOutlineProps} from '../utils/focusOutline.stylex';
+import {useTranslator} from '../i18n';
+import type {ButtonVariantMap} from './index';
 
 /**
  * Base button styles
@@ -53,6 +56,15 @@ import {themeProps} from '../utils/themeProps';
  */
 const styles = stylex.create({
   base: {
+    // Kept as a public themeable var (documented in Button.doc.mjs) even though
+    // its default now matches the shared outline: removing it would break any
+    // theme setting it, for no gain. It overrides the shared offset, so a theme
+    // can still tune the ring distance on buttons specifically.
+    '--button-focus-offset': '3px',
+    outlineOffset: {
+      default: '0',
+      ':focus-visible': 'var(--button-focus-offset)',
+    },
     position: 'relative',
     display: 'inline-flex',
     alignItems: 'center',
@@ -177,7 +189,7 @@ const elevationStyles = stylex.create({
  * Variant styles using backgroundImage for layered colors
  * Pseudo-classes are nested within properties per StyleX recommendation
  * Overlay is stacked on top of base color using multiple linear-gradients
- * Focus outline color matches variant (destructive uses negative color)
+ * Focus outline is shared across variants for consistent keyboard affordance.
  */
 const variants = stylex.create({
   primary: {
@@ -190,15 +202,6 @@ const variants = stylex.create({
       },
       ':active': `linear-gradient(${colorVars['--color-overlay-pressed']}, ${colorVars['--color-overlay-pressed']})`,
     },
-    outline: {
-      default: null,
-      ':focus-visible': `2px solid ${colorVars['--color-accent']}`,
-    },
-    '--button-focus-offset': '3px',
-    outlineOffset: {
-      default: '0',
-      ':focus-visible': 'var(--button-focus-offset)',
-    },
   },
   secondary: {
     backgroundColor: colorVars['--color-neutral'],
@@ -210,15 +213,6 @@ const variants = stylex.create({
       },
       ':active': `linear-gradient(${colorVars['--color-overlay-pressed']}, ${colorVars['--color-overlay-pressed']})`,
     },
-    outline: {
-      default: null,
-      ':focus-visible': `2px solid ${colorVars['--color-accent']}`,
-    },
-    '--button-focus-offset': '3px',
-    outlineOffset: {
-      default: '0',
-      ':focus-visible': 'var(--button-focus-offset)',
-    },
   },
   ghost: {
     backgroundColor: 'transparent',
@@ -230,19 +224,14 @@ const variants = stylex.create({
       },
       ':active': `linear-gradient(${colorVars['--color-overlay-pressed']}, ${colorVars['--color-overlay-pressed']})`,
     },
-    outline: {
-      default: null,
-      ':focus-visible': `2px solid ${colorVars['--color-accent']}`,
-    },
-    '--button-focus-offset': '3px',
-    outlineOffset: {
-      default: '0',
-      ':focus-visible': 'var(--button-focus-offset)',
-    },
   },
   destructive: {
     backgroundColor: colorVars['--color-error'],
     color: colorVars['--color-on-error'],
+    // The ring matches the variant it rings: an accent-colored outline on a
+    // red button reads as another control's focus. Only the color differs —
+    // width, style and offset come from the shared outline.
+    outlineColor: {default: null, ':focus-visible': colorVars['--color-error']},
     backgroundImage: {
       default: null,
       ':hover': {
@@ -250,38 +239,9 @@ const variants = stylex.create({
       },
       ':active': `linear-gradient(${colorVars['--color-overlay-pressed']}, ${colorVars['--color-overlay-pressed']})`,
     },
-    outline: {
-      default: null,
-      ':focus-visible': `2px solid ${colorVars['--color-error']}`,
-    },
-    '--button-focus-offset': '3px',
-    outlineOffset: {
-      default: '0',
-      ':focus-visible': 'var(--button-focus-offset)',
-    },
   },
 });
 
-/**
- * Extensible variant map for Button.
- *
- * Theme packages can add custom variants via TypeScript module augmentation:
- * @example
- * ```
- * declare module '@astryxdesign/core/Button' {
- *   interface ButtonVariantMap {
- *     'primary-muted': true;
- *   }
- * }
- * ```
- */
-export interface ButtonVariantMap {
-  primary: true;
-  secondary: true;
-  ghost: true;
-  destructive: true;
-}
-
 /**
  * Button variant type derived from ButtonVariantMap.
  * Extensible via module augmentation of ButtonVariantMap.
@@ -611,6 +571,7 @@ export function Button({
   ref,
   ...props
 }: ButtonProps): ReactNode {
+  const t = useTranslator();
   const size = useSize(sizeProp, 'md');
   const buttonGroup = useButtonGroup();
 
@@ -693,10 +654,9 @@ export function Button({
   const edgeCompAttr = isFlat ? {[EDGE_COMP_ATTR]: ''} : null;
 
   // Shared StyleX props for both button and link rendering
-  const sharedStylexProps = stylex.props(
+  const sharedStylexProps = focusOutlineProps.focusVisible(
     styles.base,
     sizeStyles[size],
-    variants[variant],
     isIconOnly && styles.iconOnly,
     buttonDisabled && styles.disabled,
     useAriaDisabled && styles.ariaDisabled,
@@ -710,11 +670,14 @@ export function Button({
       (variant === 'primary' || variant === 'destructive') &&
       (buttonGroup.orientation === 'horizontal'
         ? groupStyles.onSolidHorizontal
-        : groupStyles.onSolidVertical),
-    // Standalone floating buttons only — a grouped button's elevation is owned
+        : groupStyles.onSolidVertical), // Standalone floating buttons only — a grouped button's elevation is owned
     // by the ButtonGroup so the shared surface lifts as one unit.
     !buttonGroup && elevationStyles[elevation],
     width != null && dynamicStyles.width(width),
+    // AFTER the shared focus outline: the outline supplies width/style/offset
+    // for every variant, and `destructive` re-colors just the ring to match
+    // its own surface. Ordering is the mechanism — StyleX is last-wins.
+    variants[variant],
     xstyle,
   );
 
@@ -760,7 +723,7 @@ export function Button({
       </span>
       {/* Live region for loading state announcements */}
       <VisuallyHidden role="status" aria-live="polite">
-        {isLoadingState ? 'Loading' : ''}
+        {isLoadingState ? t('@astryx.button.loading') : ''}
       </VisuallyHidden>
     </>
   );

package/src/Button/index.ts

@@ -5,16 +5,31 @@
 /**
  * @file index.ts
  * @input Imports Button component and types from Button.tsx
- * @output Exports Button, ButtonProps, ButtonVariant
+ * @output Exports Button, ButtonProps, ButtonVariant, ButtonVariantMap
  * @position Component entry point; re-exported by /packages/core/src/index.ts
  *
  * SYNC: When modified, update this header and /packages/core/src/Button/Button.doc.mjs
  */
 
+/**
+ * Extensible variant map for Button.
+ *
+ * Theme builds can add custom variants via TypeScript module augmentation:
+ * @example
+ * ```
+ * declare module '@astryxdesign/core/Button' {
+ *   interface ButtonVariantMap {
+ *     'primary-muted': true;
+ *   }
+ * }
+ * ```
+ */
+export interface ButtonVariantMap {
+  primary: true;
+  secondary: true;
+  ghost: true;
+  destructive: true;
+}
+
 export {Button} from './Button';
-export type {
-  ButtonProps,
-  ButtonVariant,
-  ButtonSize,
-} from './Button';
-export type {ButtonVariantMap} from './Button';
+export type {ButtonProps, ButtonVariant, ButtonSize} from './Button';

package/src/ButtonGroup/ButtonGroup.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'ButtonGroup',
@@ -54,7 +54,7 @@ export const docs = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsZh = {
   components: [
     {
@@ -92,7 +92,7 @@ export const docsZh = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description: 'connected button group w/ shared borders, outer-only radius, horizontal/vertical',
   usage: {

package/src/ButtonGroup/ButtonGroup.tsx

@@ -18,7 +18,7 @@
  * - /packages/core/src/ButtonGroup/ButtonGroup.test.tsx (tests)
  * - /packages/core/src/ButtonGroup/index.ts (exports if types change)
  * - /apps/storybook/stories/ButtonGroup.stories.tsx (storybook stories)
- * - /packages/cli/templates/blocks/components/ButtonGroup/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/ButtonGroup/ (showcase blocks)
  */
 
 import {useMemo, type ReactNode} from 'react';

package/src/Calendar/Calendar.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'Calendar',
@@ -117,7 +117,7 @@ export const docs = {
   },
 };
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 export const docsZh = {
   name: 'Calendar',
   displayName: 'Calendar',
@@ -181,7 +181,7 @@ export const docsZh = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description: 'month grid for picking a date or date range',
   usage: {

package/src/Calendar/Calendar.test.tsx

@@ -9,7 +9,7 @@
  * SYNC: When Calendar.tsx changes, update tests accordingly
  */
 
-import {describe, it, expect, vi, afterEach} from 'vitest';
+import {describe, it, expect, vi, beforeEach, afterEach} from 'vitest';
 import {act, render, screen, within, waitFor} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {getButton} from '../__tests__/fastRoleQueries';
@@ -19,9 +19,13 @@ import type {CalendarHandle} from './Calendar';
 import type {ISODateString} from './Calendar';
 import {calendarStyles} from './styles';
 import {defineTheme} from '../theme/defineTheme';
-import {generateThemeCSSFlat} from '../theme/generateThemeRules';
+import {generateThemeCSS} from '../theme/generateThemeRules';
 import {__resetLiveRegionsForTest} from '../hooks/useAnnounce';
 
+function generateThemeTestCSS(theme: Parameters<typeof generateThemeCSS>[0]) {
+  const {prose, component} = generateThemeCSS(theme);
+  return [prose, component].filter(Boolean).join('\n\n');
+}
 afterEach(() => {
   __resetLiveRegionsForTest();
 });
@@ -1038,8 +1042,20 @@ describe('Calendar', () => {
 
   // ─── Day-cell marker theming (#4286) ─────────────────────────
   describe('day-cell marker theme state', () => {
-    // Tests use the real "today" (as the existing aria-current tests do) since
-    // Calendar derives it internally. Helpers pin the exact ISO strings.
+    // Pin "today" to a mid-month date so the ±2-day range helpers below stay
+    // within a single rendered month. With the real clock, running near a month
+    // boundary (e.g. the 1st) pushed today-2 into the previous month, so the
+    // rendered grid didn't contain today's cell and the marker assertions
+    // flaked. Fake only Date (timers stay real; these tests are synchronous).
+    beforeEach(() => {
+      vi.useFakeTimers({toFake: ['Date']});
+      vi.setSystemTime(new Date(2026, 5, 15, 12, 0, 0));
+    });
+    afterEach(() => {
+      vi.useRealTimers();
+    });
+    // Tests use the (now-pinned) "today" since Calendar derives it internally.
+    // Helpers pin the exact ISO strings.
     function todayISO(): ISODateString {
       const n = new Date();
       return `${n.getFullYear()}-${String(n.getMonth() + 1).padStart(2, '0')}-${String(n.getDate()).padStart(2, '0')}` as ISODateString;
@@ -1136,7 +1152,7 @@ describe('Calendar', () => {
           },
         },
       });
-      const css = generateThemeCSSFlat(theme);
+      const css = generateThemeTestCSS(theme);
       expect(css).toContain('.astryx-calendar-day.today-only');
       expect(css).toContain('.astryx-calendar-day.today-in-range');
       expect(css).toContain('box-shadow: inset 0 0 0 2px var(--color-accent)');
@@ -1217,7 +1233,7 @@ describe('Calendar', () => {
           },
         },
       });
-      const css = generateThemeCSSFlat(theme);
+      const css = generateThemeTestCSS(theme);
       expect(css).toContain('.astryx-calendar-nav {');
       expect(css).toContain('color: var(--color-accent)');
       expect(css).toContain('.astryx-calendar-nav.next');

package/src/Calendar/Calendar.tsx

@@ -14,7 +14,7 @@
  * - /packages/core/src/Calendar/Calendar.test.tsx (tests for new/changed behavior)
  * - /packages/core/src/Calendar/index.ts (exports if types change)
  * - /apps/storybook/stories/Calendar.stories.tsx (storybook stories)
- * - /packages/cli/templates/blocks/components/Calendar/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/Calendar/ (showcase blocks)
  */
 
 import {
@@ -58,6 +58,7 @@ import {
   DATE_FORMAT_MONTH_YEAR,
 } from '../utils/plainDate';
 import {mergeProps, composeEventHandlers, rtlStyles} from '../utils';
+import {focusOutlineProps} from '../utils/focusOutline.stylex';
 import {
   computeDayCellState,
   computeRangeRounding,
@@ -1102,7 +1103,7 @@ function DayCell({
             // the default rendering.
             marker: markerState,
           }),
-          stylex.props(
+          focusOutlineProps.focusVisible(
             dayCellStyles.day,
             dayCellTheme.day,
             isOutside && dayCellStyles.dayOutside,

package/src/Calendar/index.ts

@@ -38,11 +38,6 @@ export type {
 } from './hooks';
 
 // Re-export calendar-specific utilities for advanced usage
-export {
-  isSameDay,
-  isDateInRange,
-  getWeekNumber,
-  formatAccessibleDate,
-} from './utils';
+export {isSameDay, isDateInRange, getWeekNumber} from './utils';
 
 // Re-export theme styles for customization

package/src/Calendar/styles.ts

@@ -215,9 +215,9 @@ export const dayCellStyles = stylex.create({
       content: '""',
       position: 'absolute',
       top: '-2px',
-      right: '-2px',
+      insetInlineEnd: '-2px',
       bottom: '-2px',
-      left: '-2px',
+      insetInlineStart: '-2px',
     },
   },
 
@@ -258,14 +258,6 @@ export const dayCellTheme = stylex.create({
         '@media (hover: hover)': `linear-gradient(${colorVars['--color-overlay-hover']}, ${colorVars['--color-overlay-hover']})`,
       },
     },
-    outline: {
-      default: null,
-      ':focus-visible': `2px solid ${colorVars['--color-accent']}`,
-    },
-    outlineOffset: {
-      default: '0',
-      ':focus-visible': '2px',
-    },
   },
 
   // Outside days (adjacent months)

package/src/Calendar/utils.ts

@@ -7,8 +7,6 @@
  * @position Shared utilities; used by Calendar, CalendarMonthGrid, CalendarDayCell
  */
 
-import {plainDateFormat, DATE_FORMAT_WITH_WEEKDAY} from '../utils/plainDate';
-
 export {
   type PlainDate,
   plainDateFromISO as parseISO,
@@ -17,12 +15,3 @@ export {
   plainDateIsInRange as isDateInRange,
   plainDateGetWeekNumber as getWeekNumber,
 } from '../utils/plainDate';
-
-export {plainDateFormat, DATE_FORMAT_WITH_WEEKDAY};
-
-/** @deprecated Use `plainDateFormat(pd, DATE_FORMAT_WITH_WEEKDAY)` instead. */
-export function formatAccessibleDate(
-  ...args: Parameters<typeof plainDateFormat>
-): string {
-  return plainDateFormat(args[0], DATE_FORMAT_WITH_WEEKDAY);
-}

package/src/Card/Card.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'Card',
@@ -103,7 +103,7 @@ export const docs = {
   },
 };
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 export const docsZh = {
   name: 'Card',
   displayName: 'Card',
@@ -151,7 +151,7 @@ export const docsZh = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description: 'bordered container for DISCRETE items; NOT the default layout tool. Most content doesn\'t need a card.',
   usage: {

package/src/Card/Card.tsx

@@ -12,7 +12,7 @@
  * - /packages/core/src/Card/Card.doc.mjs (props table, features)
  * - /packages/core/src/Card/index.ts (exports if types change)
  * - /apps/storybook/stories/Card.stories.tsx (storybook stories)
- * - /packages/cli/templates/blocks/components/Card/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/Card/ (showcase blocks)
  */
 
 import type {ReactNode} from 'react';

package/src/Carousel/Carousel.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'Carousel',
@@ -12,6 +12,7 @@ export const docs = {
       'Carousel scrolls a row of items horizontally when they overflow the available width. Use it for card grids, image galleries, product lists, or any set of items that should be browsable without taking up the full page.',
     bestPractices: [
       {guidance: true, description: 'Enable scroll-snap when each item should land precisely at the start edge, like a gallery or product list.'},
+      {guidance: true, description: 'Reach for hasLoop on small, cyclable sets like a photo gallery, where wrapping past the last item back to the first feels natural.'},
       {guidance: true, description: 'Always provide an aria-label that describes what the carousel contains, like "Featured products" or "Team members".'},
       {guidance: true, description: 'Use a consistent gap and item width so the carousel looks intentional, not like content overflowing by accident.'},
       {guidance: true, description: 'Trust the built-in navigation: trackpad users can swipe horizontally, and mouse users can hold Shift while scrolling the wheel to move through items.'},
@@ -31,10 +32,12 @@ export const docs = {
     {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 when content is scrollable.', 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: 'hasLoop', type: 'boolean', description: 'Wrap-around scrolling: next at the end scrolls to the start, prev at the start scrolls to the end. Buttons stay visible at both edges. Only engages when content overflows.', default: 'false'},
     {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: 'handleRef', type: 'React.Ref<CarouselHandle>', description: 'Imperative handle exposing scrollNext(), scrollPrev(), scrollTo(index), canScrollNext(), and canScrollPrev() for programmatic scroll control.'},
     {name: 'xstyle', type: 'StyleXStyles', description: 'StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value.'},
     {name: 'className', type: 'string', description: 'CSS class name for the root element. Prefer xstyle for styling.'},
     {name: 'style', type: 'CSSProperties', description: 'Inline styles for the root element. Prefer xstyle.'},
@@ -56,15 +59,17 @@ export const docs = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsZh = {
   usage: {
     description:
       'Carousel 在项目超出可用宽度时将一行项目水平滚动。适用于卡片网格、图片画廊、产品列表，或任何希望无需占据整页即可浏览的项目集合。',
     bestPractices: [
       {guidance: true, description: '当每个项目应精确对齐到起始边缘时启用滚动吸附，例如画廊或产品列表。'},
+      {guidance: true, description: '在小型可循环的集合（如照片画廊）上使用 hasLoop，此时从最后一项绕回第一项的滚动更自然。'},
       {guidance: true, description: '始终提供描述轮播内容的 aria-label，例如"精选产品"或"团队成员"。'},
       {guidance: true, description: '使用一致的间距和项目宽度，让轮播看起来是有意为之，而不是内容意外溢出。'},
+      {guidance: true, description: '信任内置导航：触控板用户可水平滑动，鼠标用户可按住 Shift 滚动滚轮来浏览项目。'},
       {guidance: false, description: '将每位用户都必须看到的内容放入轮播。并非所有人都会水平滚动，关键内容应放在首屏。'},
       {guidance: false, description: '自动轮播项目。让用户按自己的节奏滚动。'},
       {guidance: false, description: '嵌套轮播。轮播中嵌套轮播会造成困惑并破坏键盘导航。'},
@@ -75,13 +80,15 @@ export const docsZh = {
     gap: '使用间距令牌比例的项目间距。',
     hasButtons: '内容可滚动时显示上一个/下一个导航按钮。',
     hasEdgeFade: '内容溢出时显示渐变边缘遮罩，提示屏幕外还有更多项目。',
+    hasLoop: '环绕滚动：在末尾按"下一个"回到开头，在开头按"上一个"跳到末尾。按钮在两端始终可见。仅在内容溢出时生效。',
     hasSnap: '启用滚动吸附，使每个子元素吸附到起始边缘。',
     padding: '滚动容器内的内联内边距，并设置匹配的 scroll-padding，使吸附点与内容边缘对齐。',
     'aria-label': '轮播区域的无障碍标签。',
+    handleRef: '命令式句柄，暴露 scrollNext()、scrollPrev()、scrollTo(index)、canScrollNext() 和 canScrollPrev() 以进行编程式滚动控制。',
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description: 'horizontal scroll container w/ fade edges, nav buttons, scroll-snap',
   usage: {
@@ -89,6 +96,7 @@ export const docsDense = {
       'Carousel scrolls items horizontally when they overflow. Use for card grids, galleries, product lists.',
     bestPractices: [
       {guidance: true, description: 'Enable scroll-snap when each item should land precisely at the start edge: gallery, product list.'},
+      {guidance: true, description: 'Reach for hasLoop on small cyclable sets (photo gallery) where wrapping past the last item back to the first feels natural.'},
       {guidance: true, description: 'Always provide an aria-label describing what the carousel contains: "Featured products", "Team members".'},
       {guidance: true, description: 'Use consistent gap + item width so the carousel looks intentional, not like content overflowing by accident.'},
       {guidance: true, description: 'Trust built-in navigation: trackpad users swipe horizontally, mouse users hold Shift + wheel to move through items.'},
@@ -102,9 +110,11 @@ export const docsDense = {
     gap: 'item spacing via spacing token scale',
     hasButtons: 'prev/next buttons when content is scrollable',
     hasEdgeFade: 'gradient edge-fade mask on overflow',
+    hasLoop: 'wrap-around: next at end -> start, prev at start -> end; buttons stay visible; only when overflowing',
     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',
+    handleRef: 'imperative handle: scrollNext/scrollPrev/scrollTo(index)/canScrollNext/canScrollPrev',
     'data-testid': 'test selector for automated testing frameworks',
   },
 };