@astryxdesign/core 0.1.9 → 0.2.0-canary.0b7a99e

package/src/Slider/Slider.tsx

@@ -13,7 +13,7 @@
  * - /packages/core/src/Slider/Slider.test.tsx
  * - /packages/core/src/Slider/index.ts
  * - /apps/storybook/stories/Slider.stories.tsx
- * - /packages/cli/templates/blocks/components/Slider/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/Slider/ (showcase blocks)
  */
 
 import {
@@ -40,7 +40,8 @@ import {Tooltip} from '../Tooltip/Tooltip';
 import {useTooltip} from '../Tooltip';
 import {VisuallyHidden} from '../VisuallyHidden';
 import type {InputStatus} from '../Field/types';
-import {mergeProps, mergeRefs} from '../utils';
+import {mergeProps, mergeRefs, rtlStyles} from '../utils';
+import {isRtlElement} from '../hooks/isRtlElement';
 import type {BaseProps} from '../BaseProps';
 import type {SizeValue} from '../utils/types';
 import {themeProps} from '../utils/themeProps';
@@ -192,8 +193,8 @@ const styles = stylex.create({
     borderRadius: radiusVars['--radius-full'],
   },
   trackHorizontal: {
-    left: 0,
-    right: 0,
+    insetInlineStart: 0,
+    insetInlineEnd: 0,
     height: TRACK_SIZE,
     top: '50%',
     transform: 'translateY(-50%)',
@@ -202,8 +203,6 @@ const styles = stylex.create({
     top: 0,
     bottom: 0,
     width: TRACK_SIZE,
-    left: '50%',
-    transform: 'translateX(-50%)',
   },
   filledTrack: {
     position: 'absolute',
@@ -217,8 +216,6 @@ const styles = stylex.create({
   },
   filledTrackVertical: {
     width: TRACK_SIZE,
-    left: '50%',
-    transform: 'translateX(-50%)',
   },
   thumb: {
     position: 'absolute',
@@ -239,10 +236,14 @@ const styles = stylex.create({
   },
   thumbHorizontal: {
     top: '50%',
-  },
-  thumbVertical: {
-    left: '50%',
-    transform: 'translate(-50%, 50%)',
+    // The thumb is positioned via logical `insetInlineStart`, which resolves
+    // from the right edge under RTL. The centering translate is a physical
+    // (screen-space) transform, so it must flip its X direction under RTL to
+    // keep the thumb centered on the value point.
+    transform: {
+      default: 'translate(-50%, -50%)',
+      ':is([dir="rtl"] *)': 'translate(50%, -50%)',
+    },
   },
   thumbHover: {
     backgroundColor: {
@@ -277,14 +278,14 @@ const styles = stylex.create({
     position: 'absolute',
   },
   marksContainerHorizontal: {
-    left: 0,
-    right: 0,
+    insetInlineStart: 0,
+    insetInlineEnd: 0,
     top: '50%',
   },
   marksContainerVertical: {
     top: 0,
     bottom: 0,
-    left: '50%',
+    insetInlineStart: '50%',
   },
   mark: {
     position: 'absolute',
@@ -294,7 +295,10 @@ const styles = stylex.create({
   markHorizontal: {
     width: 2,
     height: 8,
-    transform: 'translate(-50%, -50%)',
+    transform: {
+      default: 'translate(-50%, -50%)',
+      ':is([dir="rtl"] *)': 'translate(50%, -50%)',
+    },
   },
   markVertical: {
     height: 2,
@@ -309,12 +313,15 @@ const styles = stylex.create({
     whiteSpace: 'nowrap',
   },
   markLabelHorizontal: {
-    transform: 'translateX(-50%)',
+    transform: {
+      default: 'translateX(-50%)',
+      ':is([dir="rtl"] *)': 'translateX(50%)',
+    },
     top: THUMB_SIZE / 2 + 4,
   },
   markLabelVertical: {
     transform: 'translateY(50%)',
-    left: THUMB_SIZE / 2 + 4,
+    insetInlineStart: THUMB_SIZE / 2 + 4,
   },
 });
 
@@ -326,12 +333,39 @@ function clamp(val: number, min: number, max: number): number {
   return Math.min(Math.max(val, min), max);
 }
 
+/**
+ * Number of decimal places a value carries, including values in exponent
+ * notation (e.g. 1e-7 → 7). Used to round away binary floating-point error
+ * after step arithmetic.
+ */
+function getDecimalPrecision(num: number): number {
+  if (Math.abs(num) < 1) {
+    const parts = num.toExponential().split('e-');
+    if (parts.length === 2) {
+      const mantissaDecimals = parts[0].split('.')[1]?.length ?? 0;
+      return mantissaDecimals + parseInt(parts[1], 10);
+    }
+  }
+  const decimalPart = String(num).split('.')[1];
+  return decimalPart ? decimalPart.length : 0;
+}
+
 function snapToStep(val: number, min: number, step: number): number {
   if (step <= 0) {
     return val;
   }
   const steps = Math.round((val - min) / step);
-  return min + steps * step;
+  const snapped = min + steps * step;
+  // `min + steps * step` accumulates binary floating-point error with
+  // fractional steps (0 + 3 * 0.1 → 0.30000000000000004), which leaks into
+  // onChange/onChangeEnd payloads, aria-valuenow, and the value tooltip.
+  // Snapped values can never carry more decimals than min/step combined, so
+  // rounding to that precision removes only the error.
+  const precision = Math.min(
+    Math.max(getDecimalPrecision(min), getDecimalPrecision(step)),
+    20, // toFixed() throws past 20 digits
+  );
+  return Number(snapped.toFixed(precision));
 }
 
 function getPercent(val: number, min: number, max: number): number {
@@ -392,6 +426,7 @@ export function Slider({ref, ...props}: SliderProps) {
   const isHorizontal = orientation === 'horizontal';
 
   const id = useId();
+  const labelID = useId();
   const descriptionID = useId();
   const statusMessageID = useId();
   const requiredID = useId();
@@ -459,7 +494,12 @@ export function Slider({ref, ...props}: SliderProps) {
 
       let percent: number;
       if (isHorizontal) {
-        percent = (clientX - rect.left) / rect.width;
+        // In RTL the inline-start (value = min) is the right edge, so measure
+        // the pointer fraction from the right instead of the left. Detected
+        // from the track's computed direction (lazy, only on pointer move).
+        percent = isRtlElement(track)
+          ? (rect.right - clientX) / rect.width
+          : (clientX - rect.left) / rect.width;
       } else {
         // Vertical: bottom = min, top = max
         percent = 1 - (clientY - rect.top) / rect.height;
@@ -692,14 +732,28 @@ export function Slider({ref, ...props}: SliderProps) {
     const percent = getPercent(val, min, max);
 
     const positionStyle = isHorizontal
-      ? {left: `${percent}%`}
+      ? {insetInlineStart: `${percent}%`}
       : {bottom: `${percent}%`, left: '50%'};
 
+    // In range mode each thumb keeps a short individual name that composes
+    // with the group label (announced via the group's aria-labelledby), per
+    // the APG multi-thumb slider pattern. In single mode the thumb takes its
+    // name from the visible label element via aria-labelledby.
     const thumbLabel = isRange
       ? thumbIndex === 0
-        ? `${label}, minimum value`
-        : `${label}, maximum value`
-      : label;
+        ? 'Minimum value'
+        : 'Maximum value'
+      : undefined;
+
+    // ARIA bounds must agree with the movement clamping in updateValue: in
+    // range mode a thumb can't cross its sibling (minus the
+    // minStepsBetweenThumbs gap), and the result is always clamped to
+    // [min, max].
+    const minGap = minStepsBetweenThumbs * step;
+    const ariaValueMin =
+      isRange && thumbIndex === 1 ? clamp(values[0] + minGap, min, max) : min;
+    const ariaValueMax =
+      isRange && thumbIndex === 0 ? clamp(values[1] - minGap, min, max) : max;
 
     // Suppress the per-thumb value bubble while the disabled-message tooltip is
     // showing, so a disabled slider surfaces the *reason* on hover/focus rather
@@ -716,14 +770,15 @@ export function Slider({ref, ...props}: SliderProps) {
         // focus-discoverable; value changes stay blocked by the isDisabled
         // guards in the pointer/keyboard handlers.
         tabIndex={isDisabled && !showsDisabledMessage ? -1 : 0}
-        aria-valuemin={min}
-        aria-valuemax={max}
+        aria-valuemin={ariaValueMin}
+        aria-valuemax={ariaValueMax}
         aria-valuenow={val}
         aria-valuetext={formatValue ? formatValue(val) : undefined}
         aria-orientation={orientation}
         aria-disabled={isDisabled || undefined}
         aria-invalid={status?.type === 'error' ? true : undefined}
         aria-label={thumbLabel}
+        aria-labelledby={!isRange ? labelID : undefined}
         aria-describedby={ariaDescribedBy}
         onKeyDown={e => handleKeyDown(thumbIndex, e)}
         {...mergeProps(
@@ -733,7 +788,9 @@ export function Slider({ref, ...props}: SliderProps) {
           }),
           stylex.props(
             styles.thumb,
-            isHorizontal ? styles.thumbHorizontal : styles.thumbVertical,
+            isHorizontal
+              ? styles.thumbHorizontal
+              : rtlStyles.centerInline('50%'),
             !isDisabled && styles.thumbHover,
             !isDisabled && styles.thumbFocusVisible,
             isDisabled && styles.thumbDisabled,
@@ -768,13 +825,13 @@ export function Slider({ref, ...props}: SliderProps) {
       const p0 = getPercent(v0, min, max);
       const p1 = getPercent(v1, min, max);
       if (isHorizontal) {
-        return {left: `${p0}%`, width: `${p1 - p0}%`};
+        return {insetInlineStart: `${p0}%`, width: `${p1 - p0}%`};
       }
       return {bottom: `${p0}%`, height: `${p1 - p0}%`};
     }
     const p = getPercent(values[0], min, max);
     if (isHorizontal) {
-      return {left: '0%', width: `${p}%`};
+      return {insetInlineStart: '0%', width: `${p}%`};
     }
     return {bottom: '0%', height: `${p}%`};
   })();
@@ -796,6 +853,14 @@ export function Slider({ref, ...props}: SliderProps) {
       isLabelHidden={isLabelHidden}
       description={description}
       inputID={id}
+      labelID={labelID}
+      // The thumb is a div[role="slider"], which a <label htmlFor> can't
+      // name (only form-associated elements are labelable). Render the label
+      // as a group label and associate it via aria-labelledby instead: the
+      // single thumb references it directly, and in range mode the
+      // role="group" container references it while each thumb keeps its own
+      // "Minimum value"/"Maximum value" name.
+      isGroupLabel
       descriptionID={description ? descriptionID : undefined}
       isOptional={isOptional}
       isRequired={isRequired}
@@ -838,7 +903,9 @@ export function Slider({ref, ...props}: SliderProps) {
           ))}
         <div
           ref={mergeRefs(ref, trackRef, disabledMessageTooltip.ref)}
-          {...(isRange ? {role: 'group', 'aria-label': label} : undefined)}
+          {...(isRange
+            ? {role: 'group', 'aria-labelledby': labelID}
+            : undefined)}
           onPointerDown={handlePointerDown}
           onPointerMove={handlePointerMove}
           onPointerUp={handlePointerUp}
@@ -857,7 +924,9 @@ export function Slider({ref, ...props}: SliderProps) {
               themeProps('slider-track', {orientation}),
               stylex.props(
                 styles.track,
-                isHorizontal ? styles.trackHorizontal : styles.trackVertical,
+                isHorizontal
+                  ? styles.trackHorizontal
+                  : [styles.trackVertical, rtlStyles.centerInline('0px')],
               ),
             )}
           />
@@ -870,7 +939,7 @@ export function Slider({ref, ...props}: SliderProps) {
                 styles.filledTrack,
                 isHorizontal
                   ? styles.filledTrackHorizontal
-                  : styles.filledTrackVertical,
+                  : [styles.filledTrackVertical, rtlStyles.centerInline('0px')],
               ),
               {style: filledStyle},
             )}
@@ -889,7 +958,7 @@ export function Slider({ref, ...props}: SliderProps) {
               {marks.map(mark => {
                 const percent = getPercent(mark.value, min, max);
                 const markPos = isHorizontal
-                  ? {left: `${percent}%`}
+                  ? {insetInlineStart: `${percent}%`}
                   : {bottom: `${percent}%`};
                 return (
                   <div key={mark.value}>

package/src/Spinner/Spinner.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: 'Spinner',
@@ -56,7 +56,7 @@ export const docs = {
   },
 };
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 export const docsZh = {
   name: 'Spinner',
   displayName: 'Spinner',
@@ -108,7 +108,7 @@ export const docsZh = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   usage: {
     description:

package/src/Spinner/Spinner.test.tsx

@@ -64,12 +64,16 @@ describe('Spinner', () => {
     );
   });
 
-  it('uses string label as aria-label automatically', () => {
+  it('names the status element from the visible string label', () => {
     render(<Spinner label="Fetching data" data-testid="spinner" />);
-    expect(screen.getByRole('status')).toHaveAttribute(
-      'aria-label',
-      'Fetching data',
-    );
+    expect(screen.getByRole('status')).toHaveAccessibleName('Fetching data');
+  });
+
+  it('does not duplicate a visible string label as aria-label', () => {
+    render(<Spinner label="Fetching data" data-testid="spinner" />);
+    const status = screen.getByRole('status');
+    expect(status).not.toHaveAttribute('aria-label');
+    expect(status).toHaveAttribute('aria-labelledby');
   });
 
   it('uses explicit aria-label over string label', () => {
@@ -103,9 +107,7 @@ describe('Spinner', () => {
   });
 
   it('defaults aria-label to "Loading" for ReactNode label without explicit aria-label', () => {
-    render(
-      <Spinner label={<span>Rich content</span>} data-testid="spinner" />,
-    );
+    render(<Spinner label={<span>Rich content</span>} data-testid="spinner" />);
     expect(screen.getByRole('status')).toHaveAttribute('aria-label', 'Loading');
   });
 

package/src/Spinner/Spinner.tsx

@@ -13,10 +13,10 @@
  * - /packages/core/src/Spinner/Spinner.test.tsx
  * - /packages/core/src/Spinner/index.ts
  * - /apps/storybook/stories/Spinner.stories.tsx
- * - /packages/cli/templates/blocks/components/Spinner/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/Spinner/ (showcase blocks)
  */
 
-import {useEffect, useRef, type ReactNode} from 'react';
+import {useEffect, useId, useRef, type ReactNode} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import {durationVars, spacingVars} from '../theme/tokens.stylex';
 import {useTheme} from '../theme/useTheme';
@@ -119,8 +119,9 @@ export interface SpinnerProps extends BaseProps<HTMLSpanElement> {
    * Visible content displayed below the spinner.
    * Accepts a string or ReactNode for rich content.
    *
-   * When `label` is a string, it is also used as the accessible name
-   * (aria-label) unless `aria-label` is explicitly set.
+   * When `label` is a string, the visible text also provides the accessible
+   * name of the status element (via aria-labelledby, avoiding a duplicate
+   * announcement) unless `aria-label` is explicitly set.
    *
    * @example
    * ```
@@ -255,6 +256,14 @@ export function Spinner({
   const {border, diameter} = SIZES[size];
   const frameSize = diameter + border * 2;
   const hasLabel = label != null;
+  const labelId = useId();
+
+  // When a visible string label renders (and no explicit aria-label is set),
+  // name the status element from the visible Text via aria-labelledby instead
+  // of duplicating the same string as aria-label — the duplicate would be
+  // announced twice by screen readers (WCAG 4.1.2).
+  const namedByVisibleLabel =
+    hasLabel && typeof label === 'string' && ariaLabel == null;
 
   // Resolve accessible name: explicit aria-label > string label > "Loading"
   const resolvedAriaLabel =
@@ -264,7 +273,8 @@ export function Spinner({
     <span
       ref={hasLabel ? undefined : ref}
       role="status"
-      aria-label={resolvedAriaLabel}
+      aria-label={namedByVisibleLabel ? undefined : resolvedAriaLabel}
+      aria-labelledby={namedByVisibleLabel ? labelId : undefined}
       data-testid={hasLabel ? undefined : testId}
       {...(hasLabel ? {} : restProps)}
       {...mergeProps(
@@ -294,7 +304,7 @@ export function Spinner({
       )}>
       {spinner}
       {typeof label === 'string' ? (
-        <Text type="body" weight="bold">
+        <Text id={labelId} type="body" weight="bold">
           {label}
         </Text>
       ) : (

package/src/Stack/Stack.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: 'Stack',
@@ -268,7 +268,7 @@ export const docs = {
   },
 };
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 export const docsZh = {
   name: 'Stack',
   displayName: 'Stack',
@@ -457,7 +457,7 @@ export const docsZh = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description: 'Stack layout primitives for horizontal/vertical sequences using flexbox w/ themed spacing tokens.',
   usage: {

package/src/Stack/Stack.tsx

@@ -9,7 +9,7 @@
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/Stack/Stack.doc.mjs
  * - /apps/storybook/stories/Stack.stories.tsx
- * - /packages/cli/templates/blocks/components/Stack/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/Stack/ (showcase blocks)
  */
 
 import {createElement, type ElementType, type ReactNode, type Ref} from 'react';

package/src/Stack/StackItem.tsx

@@ -8,7 +8,7 @@
  *
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/Stack/Stack.doc.mjs
- * - /packages/cli/templates/blocks/components/Stack/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/Stack/ (showcase blocks)
  */
 
 import {createElement, type ElementType, type ReactNode, type Ref} from 'react';

package/src/StatusDot/StatusDot.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: 'StatusDot',
@@ -57,7 +57,7 @@ export const docs = {
   },
 };
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 export const docsZh = {
   name: 'StatusDot',
   displayName: 'Status Dot',
@@ -105,7 +105,7 @@ export const docsZh = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description: 'Small colored dot indicator for status display (online/offline, severity, etc).',
   usage: {

package/src/StatusDot/StatusDot.tsx

@@ -13,7 +13,7 @@
  * - /packages/core/src/StatusDot/StatusDot.test.tsx (tests for new/changed behavior)
  * - /packages/core/src/StatusDot/index.ts (exports if types change)
  * - /apps/storybook/stories/StatusDot.stories.tsx (storybook stories)
- * - /packages/cli/templates/blocks/components/StatusDot/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/StatusDot/ (showcase blocks)
  */
 
 import * as stylex from '@stylexjs/stylex';
@@ -22,6 +22,7 @@ import type {BaseProps} from '../BaseProps';
 import {Tooltip} from '../Tooltip/Tooltip';
 import {mergeProps} from '../utils';
 import {themeProps} from '../utils/themeProps';
+import type {StatusDotVariantMap} from './index';
 
 /**
  * Pulse animation keyframes
@@ -77,27 +78,6 @@ const variants = stylex.create({
   },
 });
 
-/**
- * Extensible variant map for StatusDot.
- *
- * Theme packages can add custom variants via TypeScript module augmentation:
- * @example
- * ```
- * declare module '@astryxdesign/core/StatusDot' {
- *   interface StatusDotVariantMap {
- *     'critical': true;
- *   }
- * }
- * ```
- */
-export interface StatusDotVariantMap {
-  success: true;
-  warning: true;
-  error: true;
-  accent: true;
-  neutral: true;
-}
-
 /**
  * Status dot variant type derived from StatusDotVariantMap.
  * Extensible via module augmentation of StatusDotVariantMap.

package/src/StatusDot/index.ts

@@ -9,9 +9,26 @@
  * @position Entry point for StatusDot; re-exported by /packages/core/src/index.ts
  */
 
+/**
+ * Extensible variant map for StatusDot.
+ *
+ * Theme packages can add custom variants via TypeScript module augmentation:
+ * @example
+ * ```
+ * declare module '@astryxdesign/core/StatusDot' {
+ *   interface StatusDotVariantMap {
+ *     'critical': true;
+ *   }
+ * }
+ * ```
+ */
+export interface StatusDotVariantMap {
+  success: true;
+  warning: true;
+  error: true;
+  accent: true;
+  neutral: true;
+}
+
 export {StatusDot} from './StatusDot';
-export type {
-  StatusDotProps,
-  StatusDotVariant,
-  StatusDotVariantMap,
-} from './StatusDot';
+export type {StatusDotProps, StatusDotVariant} from './StatusDot';