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

package/src/Switch/Switch.doc.mjs

@@ -1,12 +1,19 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'Switch',
   displayName: 'Switch',
   category: 'Data Input',
-  keywords: ["switch","toggle","onoff","flipswitch","boolean","toggleswitch"],
+  keywords: [
+    'switch',
+    'toggle',
+    'onoff',
+    'flipswitch',
+    'boolean',
+    'toggleswitch',
+  ],
   props: [
     {
       name: 'ref',
@@ -62,6 +69,13 @@ export const docs = {
       description: 'Whether the switch is disabled.',
       default: 'false',
     },
+    {
+      name: 'size',
+      type: "'sm' | 'md'",
+      description:
+        'Size variant controlling track and thumb dimensions. sm (32x20px) matches sm checkbox/radio vertical rhythm; md (40x24px, default) matches md checkbox/radio vertical rhythm.',
+      default: "'md'",
+    },
     {
       name: 'htmlName',
       type: 'string',
@@ -107,7 +121,8 @@ export const docs = {
     {
       name: 'labelIcon',
       type: 'IconType',
-      description: 'Icon displayed before the label text. See `astryx docs icons` for valid semantic names.',
+      description:
+        'Icon displayed before the label text. See `astryx docs icons` for valid semantic names.',
     },
     {
       name: 'labelTooltip',
@@ -129,28 +144,65 @@ export const docs = {
         'Spacing behavior between label and switch. "hug" places them next to each other; "spread" pushes them to opposite ends of the container (full width). "default" is a deprecated alias for "hug".',
       default: "'hug'",
     },
+    {
+      name: 'width',
+      type: 'SizeValue',
+      description:
+        'Width of the field (number = pixels, string used as-is, e.g. "100%"). Sizes the whole field (label, control, and status) so they stay aligned.',
+    },
   ],
   theming: {
     targets: [
-      {className: 'astryx-switch', states: ['checked', 'disabled']},
-      {className: 'astryx-switch-thumb', states: ['checked']},
-      {className: 'astryx-switch-field', visualProps: ['labelPosition', 'labelSpacing']},
+      {
+        className: 'astryx-switch',
+        visualProps: ['size'],
+        states: ['checked', 'disabled'],
+      },
+      {
+        className: 'astryx-switch-thumb',
+        visualProps: ['size'],
+        states: ['checked'],
+      },
+      {
+        className: 'astryx-switch-field',
+        visualProps: ['labelPosition', 'labelSpacing'],
+      },
     ],
   },
   usage: {
     description:
       'A toggle control for on/off states that take effect immediately. Supports labels, descriptions, loading states, and validation. Use it for settings or preferences that apply instantly. For changes requiring a form submission, use a checkbox instead.',
     bestPractices: [
-      { guidance: true, description: 'Use for settings that apply immediately; the toggle should take effect without a separate save action.' },
-      { guidance: true, description: 'Pair with a clear, concise label that describes the setting being controlled.' },
-      { guidance: false, description: 'Use for options that require a form submission to take effect; use a checkbox instead.' },
-      { guidance: false, description: 'Use a switch for multi-state values; it\'s strictly on/off.' },
-      { guidance: false, description: 'Wrap a disabled switch in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.' },
+      {
+        guidance: true,
+        description:
+          'Use for settings that apply immediately; the toggle should take effect without a separate save action.',
+      },
+      {
+        guidance: true,
+        description:
+          'Pair with a clear, concise label that describes the setting being controlled.',
+      },
+      {
+        guidance: false,
+        description:
+          'Use for options that require a form submission to take effect; use a checkbox instead.',
+      },
+      {
+        guidance: false,
+        description:
+          "Use a switch for multi-state values; it's strictly on/off.",
+      },
+      {
+        guidance: false,
+        description:
+          'Wrap a disabled switch in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.',
+      },
     ],
   },
 };
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 export const docsZh = {
   name: 'Switch',
   displayName: 'Switch',
@@ -163,8 +215,7 @@ export const docsZh = {
     {
       name: 'label',
       type: 'string',
-      description:
-        '开关的标签文本（始终渲染以确保无障碍性）。',
+      description: '开关的标签文本（始终渲染以确保无障碍性）。',
       required: true,
     },
     {
@@ -187,15 +238,13 @@ export const docsZh = {
     {
       name: 'isLoading',
       type: 'boolean',
-      description:
-        '开关是否处于加载状态，在滑块内显示旋转器。',
+      description: '开关是否处于加载状态，在滑块内显示旋转器。',
       default: 'false',
     },
     {
       name: 'isLabelHidden',
       type: 'boolean',
-      description:
-        '视觉上隐藏标签，同时保持屏幕阅读器的无障碍性。',
+      description: '视觉上隐藏标签，同时保持屏幕阅读器的无障碍性。',
       default: 'false',
     },
     {
@@ -212,7 +261,8 @@ export const docsZh = {
     {
       name: 'htmlName',
       type: 'string',
-      description: '底层复选框输入的 HTML name 属性，用于表单提交（开启时提交 "on"）。',
+      description:
+        '底层复选框输入的 HTML name 属性，用于表单提交（开启时提交 "on"）。',
     },
     {
       name: 'disabledMessage',
@@ -223,15 +273,13 @@ export const docsZh = {
     {
       name: 'isOptional',
       type: 'boolean',
-      description:
-        '字段是否为可选。与 isRequired 互斥。',
+      description: '字段是否为可选。与 isRequired 互斥。',
       default: 'false',
     },
     {
       name: 'isRequired',
       type: 'boolean',
-      description:
-        '开关是否为必填。与 isOptional 互斥。',
+      description: '开关是否为必填。与 isOptional 互斥。',
       default: 'false',
     },
     {
@@ -258,14 +306,12 @@ export const docsZh = {
     {
       name: 'labelTooltip',
       type: 'string',
-      description:
-        '在标签末尾的信息图标中显示的工具提示文本。',
+      description: '在标签末尾的信息图标中显示的工具提示文本。',
     },
     {
       name: 'labelPosition',
       type: "'start' | 'end'",
-      description:
-        '标签出现在开关的哪一侧。"start" 将标签放在开关前面。',
+      description: '标签出现在开关的哪一侧。"start" 将标签放在开关前面。',
       default: "'end'",
     },
     {
@@ -278,36 +324,87 @@ export const docsZh = {
   ],
   theming: {
     targets: [
-      {className: 'astryx-switch', states: ['checked', 'disabled']},
-      {className: 'astryx-switch-thumb', states: ['checked']},
-      {className: 'astryx-switch-field', visualProps: ['labelPosition', 'labelSpacing']},
+      {
+        className: 'astryx-switch',
+        visualProps: ['size'],
+        states: ['checked', 'disabled'],
+      },
+      {
+        className: 'astryx-switch-thumb',
+        visualProps: ['size'],
+        states: ['checked'],
+      },
+      {
+        className: 'astryx-switch-field',
+        visualProps: ['labelPosition', 'labelSpacing'],
+      },
     ],
   },
   usage: {
     description:
       'A toggle control for on/off states that take effect immediately. Supports labels, descriptions, loading states, and validation. Use it for settings or preferences that apply instantly. For changes requiring a form submission, use a checkbox instead.',
     bestPractices: [
-      { guidance: true, description: 'Use for settings that apply immediately; the toggle should take effect without a separate save action.' },
-      { guidance: true, description: 'Pair with a clear, concise label that describes the setting being controlled.' },
-      { guidance: false, description: 'Use for options that require a form submission to take effect; use a checkbox instead.' },
-      { guidance: false, description: 'Use a switch for multi-state values; it\'s strictly on/off.' },
-      { guidance: false, description: 'Wrap a disabled switch in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.' },
+      {
+        guidance: true,
+        description:
+          'Use for settings that apply immediately; the toggle should take effect without a separate save action.',
+      },
+      {
+        guidance: true,
+        description:
+          'Pair with a clear, concise label that describes the setting being controlled.',
+      },
+      {
+        guidance: false,
+        description:
+          'Use for options that require a form submission to take effect; use a checkbox instead.',
+      },
+      {
+        guidance: false,
+        description:
+          "Use a switch for multi-state values; it's strictly on/off.",
+      },
+      {
+        guidance: false,
+        description:
+          'Wrap a disabled switch in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.',
+      },
     ],
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description: 'Toggle switch for boolean values w/ integrated label support.',
   usage: {
     description:
       'A toggle control for on/off states that take effect immediately. Supports labels, descriptions, loading states, and validation. Use it for settings or preferences that apply instantly. For changes requiring a form submission, use a checkbox instead.',
     bestPractices: [
-      { guidance: true, description: 'Use for settings that apply immediately; the toggle should take effect without a separate save action.' },
-      { guidance: true, description: 'Pair with a clear, concise label that describes the setting being controlled.' },
-      { guidance: false, description: 'Use for options that require a form submission to take effect; use a checkbox instead.' },
-      { guidance: false, description: 'Use a switch for multi-state values; it\'s strictly on/off.' },
-      { guidance: false, description: 'Wrap a disabled switch in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.' },
+      {
+        guidance: true,
+        description:
+          'Use for settings that apply immediately; the toggle should take effect without a separate save action.',
+      },
+      {
+        guidance: true,
+        description:
+          'Pair with a clear, concise label that describes the setting being controlled.',
+      },
+      {
+        guidance: false,
+        description:
+          'Use for options that require a form submission to take effect; use a checkbox instead.',
+      },
+      {
+        guidance: false,
+        description:
+          "Use a switch for multi-state values; it's strictly on/off.",
+      },
+      {
+        guidance: false,
+        description:
+          'Wrap a disabled switch in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.',
+      },
     ],
   },
   propDescriptions: {
@@ -315,7 +412,8 @@ export const docsDense = {
     label: 'Label text (always rendered for a11y).',
     value: 'Whether switch is on or off.',
     onChange: 'Fired when switch state changes.',
-    changeAction: 'Async action after onChange; triggers optimistic UI + loading spinner until resolved.',
+    changeAction:
+      'Async action after onChange; triggers optimistic UI + loading spinner until resolved.',
     isLoading: 'Loading state; shows spinner in thumb.',
     isLabelHidden: 'Visually hides label; still accessible to screen readers.',
     description: 'Description text below label.',
@@ -323,12 +421,14 @@ export const docsDense = {
     htmlName: 'HTML name attr for the checkbox; submits "on" when on.',
     isOptional: 'Whether field is optional; mutually exclusive w/ isRequired.',
     isRequired: 'Whether switch is required; mutually exclusive w/ isOptional.',
-    status: 'Status indicator w/ type + message; colored message box, sets aria-invalid on error.',
+    status:
+      'Status indicator w/ type + message; colored message box, sets aria-invalid on error.',
     onFocus: 'Fired when switch receives focus.',
     onBlur: 'Fired when switch loses focus.',
     labelIcon: 'Icon before label text.',
     labelTooltip: 'Tooltip text in info icon at label end.',
     labelPosition: 'Which side label appears; "start" places before switch.',
-    labelSpacing: 'Spacing behavior; "hug" places next to each other, "spread" pushes to opposite ends (full width). "default" is deprecated alias for "hug".',
+    labelSpacing:
+      'Spacing behavior; "hug" places next to each other, "spread" pushes to opposite ends (full width). "default" is deprecated alias for "hug".',
   },
-};
+};

package/src/Switch/Switch.test.tsx

@@ -13,6 +13,10 @@ import {describe, it, expect, vi, beforeEach, afterEach} from 'vitest';
 import {render, screen, fireEvent, waitFor} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {Switch} from './Switch';
+import {
+  getAllInjectedCss,
+  getForcedColorsRules,
+} from '../__tests__/forcedColors';
 import {__resetLiveRegionsForTest} from '../hooks/useAnnounce';
 
 afterEach(() => {
@@ -68,6 +72,28 @@ describe('Switch', () => {
     expect(screen.getByRole('switch')).toBeChecked();
   });
 
+  it('renders with custom size prop (sm / md)', () => {
+    const {rerender} = render(
+      <Switch
+        label="Small switch"
+        value={false}
+        size="sm"
+        onChange={() => {}}
+      />,
+    );
+    expect(screen.getByRole('switch')).toBeInTheDocument();
+
+    rerender(
+      <Switch
+        label="Medium switch"
+        value={false}
+        size="md"
+        onChange={() => {}}
+      />,
+    );
+    expect(screen.getByRole('switch')).toBeInTheDocument();
+  });
+
   it('calls onChange with new checked state when clicked', async () => {
     const user = userEvent.setup();
     const handleChange = vi.fn();
@@ -145,6 +171,40 @@ describe('Switch', () => {
     expect(switchEl).toHaveAttribute('aria-describedby', description.id);
   });
 
+  it('toggles when clicking on the description', async () => {
+    const user = userEvent.setup();
+    const handleChange = vi.fn();
+    render(
+      <Switch
+        label="Dark mode"
+        description="Switch to a darker color scheme"
+        value={false}
+        onChange={handleChange}
+      />,
+    );
+    await user.click(screen.getByText('Switch to a darker color scheme'));
+    expect(handleChange).toHaveBeenCalledWith(true, expect.any(Object));
+  });
+
+  it('does not fold the description into the switch accessible name', () => {
+    // Description stays a sibling of the <label>, so it must not become part
+    // of the switch's accessible name — it belongs in the accessible
+    // description (aria-describedby) only, to avoid double announcement.
+    render(
+      <Switch
+        label="Dark mode"
+        description="Switch to a darker color scheme"
+        value={false}
+        onChange={() => {}}
+      />,
+    );
+    const switchEl = screen.getByRole('switch');
+    expect(switchEl).toHaveAccessibleName('Dark mode');
+    expect(switchEl).toHaveAccessibleDescription(
+      'Switch to a darker color scheme',
+    );
+  });
+
   it('is disabled when isDisabled prop is true', () => {
     render(
       <Switch
@@ -636,6 +696,58 @@ describe('Switch', () => {
     });
   });
 
+  describe('RTL thumb travel direction', () => {
+    // StyleX injects atomic rules into the document; scan them so we can assert
+    // the direction-aware transform without relying on jsdom to resolve the
+    // `:is([dir="rtl"] *)` descendant selector against computed style.
+    function injectedCss(): string {
+      let out = '';
+      for (const sheet of Array.from(document.styleSheets)) {
+        try {
+          for (const rule of Array.from(sheet.cssRules)) {
+            out += rule.cssText + '\n';
+          }
+        } catch {
+          // ignore cross-origin sheets
+        }
+      }
+      out += Array.from(document.querySelectorAll('style'))
+        .map(s => s.textContent || '')
+        .join('\n');
+      return out;
+    }
+
+    it('applies a distinct thumb style when on vs off (on-travel is wired)', () => {
+      const on = render(<Switch label="On" value={true} onChange={() => {}} />);
+      const off = render(
+        <Switch label="Off" value={false} onChange={() => {}} />,
+      );
+      const onThumb = on.container.querySelector(
+        '[class*="thumbOnSizeStyles"]',
+      );
+      const offThumb = off.container.querySelector(
+        '[class*="thumbOffSizeStyles"]',
+      );
+      expect(onThumb).not.toBeNull();
+      expect(offThumb).not.toBeNull();
+      expect(onThumb!.getAttribute('class')).not.toBe(
+        offThumb!.getAttribute('class'),
+      );
+    });
+
+    it('mirrors the on-state thumb travel under RTL (negative translateX)', () => {
+      render(<Switch label="Toggle" value={true} onChange={() => {}} />);
+      const css = injectedCss();
+      // LTR on-travel moves the thumb toward the physical right (positive px).
+      expect(css).toMatch(/transform:\s*translateX\(1[24]px\)/);
+      // RTL mirrors it: the on-thumb lands on the inline-end (physical left)
+      // side, so the travel flips sign, scoped to `[dir="rtl"]`.
+      expect(css).toMatch(
+        /:is\(\[dir="rtl"\][^)]*\)[^{]*\{\s*transform:\s*translateX\(-1[24]px\)/,
+      );
+    });
+  });
+
   describe('rest forwarding', () => {
     it('forwards data-testid, id, and aria-* to the root element', () => {
       const {container} = render(
@@ -655,3 +767,36 @@ describe('Switch', () => {
     });
   });
 });
+
+// jsdom cannot emulate forced-colors rendering, so these assert that the
+// compiled output includes the forced-colors rules; visual behavior needs
+// manual verification under Windows High Contrast.
+describe('forced colors (WCAG 1.4.11)', () => {
+  it('compiles forced-colors overrides so on/off state survives Windows High Contrast', () => {
+    render(<Switch label="Notifications" value={true} onChange={() => {}} />);
+    const css = getForcedColorsRules();
+    // Track outline (backgrounds are stripped; the border keeps the bounds).
+    expect(css).toContain('border-color: canvastext;');
+    // Off track stays empty; on track uses the selection color.
+    expect(css).toContain('background-color: canvas;');
+    expect(css).toContain('background-color: highlight;');
+    // Thumb fill per state.
+    expect(css).toContain('background-color: canvastext;');
+    expect(css).toContain('background-color: highlighttext;');
+    // Disabled affordance (opacity dimming does not survive forcing).
+    expect(css).toContain('border-color: graytext;');
+  });
+
+  it('gates the hover tint out of forced colors so the thumb stays visible on hover', () => {
+    render(<Switch label="Notifications" value={true} onChange={() => {}} />);
+    // The ancestor-hover tint is a non-system color-mix whose rule outranks the
+    // plain forced-colors track rule. It is gated behind `forced-colors: none`
+    // so it cannot reassert on hover and flatten the Highlight track to white
+    // under the HighlightText thumb (white-on-white).
+    expect(getAllInjectedCss()).toContain(
+      '(hover: hover) and (forced-colors: none)',
+    );
+    // And the tint never leaks into the forced-colors output.
+    expect(getForcedColorsRules()).not.toContain('color-mix');
+  });
+});