@astryxdesign/core 0.3.0 → 0.4.0-canary.058f476

package/src/CheckboxInput/CheckboxInput.test.tsx

@@ -13,8 +13,11 @@ 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 {CheckboxInput} from './CheckboxInput';
+import {Theme} from '../theme/Theme';
+import {defineTheme} from '../theme/defineTheme';
 import {getForcedColorsRules} from '../__tests__/forcedColors';
 import {__resetLiveRegionsForTest} from '../hooks/useAnnounce';
+import {FOCUS_OUTLINE_PARTS} from '../utils/focusOutline.stylex';
 
 afterEach(() => {
   __resetLiveRegionsForTest();
@@ -542,6 +545,38 @@ describe('CheckboxInput', () => {
       expect(data.get('terms')).toBe('on');
     });
 
+    it('does not block form submission when required and disabled with a disabledMessage', () => {
+      const {container} = render(
+        <form>
+          <CheckboxInput
+            label="Terms"
+            htmlName="terms"
+            value={false}
+            onChange={() => {}}
+            isRequired
+            isDisabled
+            disabledMessage="Terms are managed by your administrator"
+          />
+        </form>,
+      );
+      expect(container.querySelector('form')!.checkValidity()).toBe(true);
+    });
+
+    it('still blocks submission when required and unchecked but enabled', () => {
+      const {container} = render(
+        <form>
+          <CheckboxInput
+            label="Terms"
+            htmlName="terms"
+            value={false}
+            onChange={() => {}}
+            isRequired
+          />
+        </form>,
+      );
+      expect(container.querySelector('form')!.checkValidity()).toBe(false);
+    });
+
     it('is excluded from form data when disabled, even with a disabledMessage', () => {
       const {container} = render(
         <form>
@@ -599,3 +634,88 @@ describe('forced colors (WCAG 1.4.11)', () => {
     expect(getForcedColorsRules()).toContain('color: canvastext;');
   });
 });
+
+// The control's native input is `opacity: 0`, so the visible focus indicator
+// has to land on the indicator beside it — which is themeable, third-party
+// code. If drawing the ring were the indicator's job, a replacement that
+// simply doesn't would ship a control with no visible focus (WCAG 2.4.7), and
+// that is the default: our own sample replacement destructures
+// {state, size, isDisabled} and drops the rest.
+//
+// So the owner paints it, on the indicator's own element, at focus time. The
+// shape is right because `outline` follows that element's border-radius, and
+// no cooperation is required.
+describe('focus ring ownership (WCAG 2.4.7)', () => {
+  /** What a theme author plausibly writes: state in, picture out. */
+  const BareIndicator = ({state}: {state: string}) => (
+    <span aria-hidden="true" data-testid="bare-indicator">
+      {state === 'checked' ? 'x' : ''}
+    </span>
+  );
+
+  const bareTheme = defineTheme({
+    name: 'bare-indicator-theme',
+    indicators: {checkbox: BareIndicator},
+  });
+
+  /**
+   * The element the ring is painted on: the indicator slot's only child — the
+   * indicator's own root, whatever a theme renders there.
+   */
+  const indicatorOf = (container: HTMLElement) => {
+    const input = container.querySelector('input[type="checkbox"]');
+    const slot = input?.nextElementSibling;
+    return slot?.firstElementChild as HTMLElement;
+  };
+
+  const focusInput = (container: HTMLElement) => {
+    const input = container.querySelector(
+      'input[type="checkbox"]',
+    ) as HTMLInputElement;
+    // A keydown first, so jsdom's :focus-visible heuristic sees keyboard
+    // modality — the ring is deliberately keyboard-only, and a bare
+    // fireEvent.focus() reads as a pointer focus. Same approach as the
+    // TreeList focus test.
+    fireEvent.keyDown(document.body, {key: 'Tab'});
+    input.focus();
+    fireEvent.focus(input);
+    return input;
+  };
+
+  it('paints the ring on the built-in indicator', () => {
+    const {container} = render(
+      <CheckboxInput label="Accept" value={false} onChange={() => {}} />,
+    );
+    focusInput(container);
+    expect(indicatorOf(container).style.outlineStyle).toBe(
+      FOCUS_OUTLINE_PARTS.outlineStyle,
+    );
+  });
+
+  it('paints it on a replacement that forwards nothing', () => {
+    const {container} = render(
+      <Theme theme={bareTheme}>
+        <CheckboxInput label="Accept" value={false} onChange={() => {}} />
+      </Theme>,
+    );
+
+    // The replacement really took effect, and really is bare.
+    const replaced = screen.getByTestId('bare-indicator');
+    expect(replaced.className).toBe('');
+    // ...and it still gets a ring, because the owner drew it.
+    focusInput(container);
+    expect(replaced.style.outlineStyle).toBe(FOCUS_OUTLINE_PARTS.outlineStyle);
+  });
+
+  it('clears the ring on blur', () => {
+    const {container} = render(
+      <CheckboxInput label="Accept" value={false} onChange={() => {}} />,
+    );
+    const input = focusInput(container);
+    expect(indicatorOf(container).style.outlineStyle).toBe(
+      FOCUS_OUTLINE_PARTS.outlineStyle,
+    );
+    fireEvent.blur(input);
+    expect(indicatorOf(container).style.outlineStyle).toBe('');
+  });
+});

package/src/CheckboxInput/CheckboxInput.tsx

@@ -21,6 +21,7 @@ import {
   useCallback,
   use,
   useOptimistic,
+  useRef,
   useTransition,
   type ChangeEvent,
   type FocusEvent,
@@ -31,12 +32,9 @@ import {
   colorVars,
   spacingVars,
   radiusVars,
-  durationVars,
-  easeVars,
   typographyVars,
   typeScaleVars,
   fontWeightVars,
-  borderVars,
 } from '../theme/tokens.stylex';
 import type {BaseProps} from '../BaseProps';
 import type {SizeValue} from '../utils/types';
@@ -47,7 +45,9 @@ import type {InputStatus} from '../Field/types';
 import {Spinner} from '../Spinner';
 import {useTooltip} from '../Tooltip';
 import {mergeProps, mergeRefs} from '../utils';
-import {checkboxScope} from './checkbox.markers.stylex';
+import {indicatorScope} from '../Indicator/indicator.markers.stylex';
+import {useIndicatorFocusRing} from '../hooks/useIndicatorFocusRing';
+import {useIndicator} from '../Indicator';
 import {themeProps} from '../utils/themeProps';
 import {CheckboxListContext} from '../CheckboxList/CheckboxListContext';
 
@@ -68,6 +68,12 @@ const styles = stylex.create({
     flexShrink: 0,
     isolation: 'isolate',
   },
+  // Holds only the indicator, so the focus ring has one unambiguous target.
+  // `display: contents` adds no box of its own — the indicator keeps whatever
+  // layout relationship it already had with the wrapper.
+  indicatorSlot: {
+    display: 'contents',
+  },
   input: {
     position: 'absolute',
     margin: 0,
@@ -79,113 +85,6 @@ const styles = stylex.create({
   inputDisabled: {
     cursor: 'not-allowed',
   },
-  checkbox: {
-    display: 'flex',
-    alignItems: 'center',
-    justifyContent: 'center',
-    borderWidth: borderVars['--border-width'],
-    borderStyle: 'solid',
-    borderRadius: radiusVars['--radius-inner'],
-    transitionProperty: 'background-color, border-color',
-    transitionDuration: {
-      default: durationVars['--duration-fast'],
-      '@media (prefers-reduced-motion: reduce)': '0s',
-    },
-    transitionTimingFunction: easeVars['--ease-standard'],
-  },
-  checkboxFocus: {
-    outline: {
-      default: 'none',
-      [stylex.when.ancestor(':has(:focus-visible)', checkboxScope)]:
-        `2px solid ${colorVars['--color-accent']}`,
-    },
-    outlineOffset: {
-      default: null,
-      [stylex.when.ancestor(':has(:focus-visible)', checkboxScope)]: '2px',
-    },
-  },
-  // State-dependent colors with ancestor hover behavior
-  checkboxUnchecked: {
-    // Foreground for the inherit-shade loading spinner (reads currentColor):
-    // brand accent on the light surface fill.
-    color: colorVars['--color-accent'],
-    borderColor: {
-      default: colorVars['--color-border-emphasized'],
-      [stylex.when.ancestor(':hover', checkboxScope)]: {
-        '@media (hover: hover)': `color-mix(in srgb, ${colorVars['--color-border-emphasized']}, ${colorVars['--color-tint-hover']} 20%)`,
-      },
-    },
-    backgroundColor: {
-      default: colorVars['--color-background-surface'],
-      [stylex.when.ancestor(':hover', checkboxScope)]: {
-        '@media (hover: hover)': `color-mix(in srgb, ${colorVars['--color-background-surface']}, ${colorVars['--color-tint-hover']} 5%)`,
-      },
-    },
-  },
-  checkboxChecked: {
-    // Foreground for the inherit-shade loading spinner (reads currentColor):
-    // on-accent color against the accent fill.
-    color: colorVars['--color-on-accent'],
-    borderColor: {
-      default: colorVars['--color-accent'],
-      [stylex.when.ancestor(':hover', checkboxScope)]: {
-        '@media (hover: hover)': `color-mix(in srgb, ${colorVars['--color-accent']}, ${colorVars['--color-tint-hover']} 15%)`,
-      },
-    },
-    backgroundColor: {
-      default: colorVars['--color-accent'],
-      [stylex.when.ancestor(':hover', checkboxScope)]: {
-        '@media (hover: hover)': `color-mix(in srgb, ${colorVars['--color-accent']}, ${colorVars['--color-tint-hover']} 15%)`,
-      },
-    },
-  },
-  checkboxDisabled: {
-    opacity: 0.5,
-    borderColor: {
-      default: colorVars['--color-border'],
-      [stylex.when.ancestor(':hover', checkboxScope)]: {
-        '@media (hover: hover)': colorVars['--color-border'],
-      },
-    },
-  },
-  checkboxDisabledUnchecked: {
-    backgroundColor: {
-      default: colorVars['--color-background-muted'],
-      [stylex.when.ancestor(':hover', checkboxScope)]: {
-        '@media (hover: hover)': colorVars['--color-background-muted'],
-      },
-    },
-  },
-  checkmark: {
-    display: 'none',
-    color: {
-      default: colorVars['--color-on-accent'],
-      // Forced colors (Windows High Contrast) does not reliably force an SVG
-      // stroke painted with currentColor, so the check stays the same white as
-      // the flattened (Canvas) box fill — a white check on a white box.
-      // CanvasText keeps it perceivable on the Canvas box, matching the
-      // indeterminate mark (WCAG 1.4.11).
-      '@media (forced-colors: active)': 'CanvasText',
-    },
-  },
-  checkmarkVisible: {
-    display: 'block',
-  },
-  indeterminateMark: {
-    display: 'none',
-    backgroundColor: {
-      default: colorVars['--color-on-accent'],
-      // Forced colors (Windows High Contrast) strips painted backgrounds,
-      // which would make the indeterminate bar invisible; CanvasText keeps it
-      // perceivable on the Canvas box fill (WCAG 1.4.11). The checkmark carries
-      // the matching CanvasText treatment on its own style.
-      '@media (forced-colors: active)': 'CanvasText',
-    },
-    borderRadius: radiusVars['--radius-full'],
-  },
-  indeterminateMarkVisible: {
-    display: 'block',
-  },
   labelWrapper: {
     display: 'flex',
     flexDirection: 'column',
@@ -211,39 +110,6 @@ const wrapperSizeStyles = stylex.create({
   },
 });
 
-const checkboxSizeStyles = stylex.create({
-  sm: {
-    width: 20,
-    height: 20,
-  },
-  md: {
-    width: 24,
-    height: 24,
-  },
-});
-
-const checkmarkSizeStyles = stylex.create({
-  sm: {
-    width: 12,
-    height: 12,
-  },
-  md: {
-    width: 14,
-    height: 14,
-  },
-});
-
-const indeterminateSizeStyles = stylex.create({
-  sm: {
-    width: 10,
-    height: 2,
-  },
-  md: {
-    width: 12,
-    height: 2,
-  },
-});
-
 export type CheckboxInputSize = keyof typeof wrapperSizeStyles;
 
 export interface CheckboxInputProps extends Omit<BaseProps, 'onChange'> {
@@ -443,9 +309,17 @@ export function CheckboxInput({
     isEnabled: showsDisabledMessage,
   });
 
+  // The checkbox visual is an indicator: a theme can restyle it through the
+  // `checkbox` target or replace the component outright.
+  const CheckboxControl = useIndicator('checkbox');
+  // The ring is drawn on the indicator itself: the native input is
+  // `opacity: 0`, and only the indicator's own element can shape the outline
+  // to match it. See useIndicatorFocusRing.
+  const indicatorRef = useRef<HTMLSpanElement>(null);
+  const {focusProps} = useIndicatorFocusRing(indicatorRef, isDisabled);
+
   const isIndeterminate = optimisticValue === 'indeterminate';
   const isChecked = optimisticValue === true;
-  const isCheckedOrIndeterminate = isChecked || isIndeterminate;
 
   // Sync the native indeterminate DOM property (can't be set via JSX
   // attribute). On a native checkbox this is the authoritative way to expose
@@ -498,9 +372,13 @@ export function CheckboxInput({
         {...stylex.props(
           styles.container,
           isLabelHidden && styles.containerLabelHidden,
-          !isDisabled && checkboxScope,
+          // Hover and focus reach the checkbox visual through this ancestor
+          // marker rather than props, so the whole row drives it.
+          !isDisabled && indicatorScope,
         )}>
-        <div {...stylex.props(styles.checkboxWrapper, wrapperSizeStyles[size])}>
+        <div
+          {...stylex.props(styles.checkboxWrapper, wrapperSizeStyles[size])}
+          {...focusProps}>
           <input
             {...rest}
             ref={mergeRefs(
@@ -520,6 +398,7 @@ export function CheckboxInput({
             // still blocked by the isDisabled guard in onChange below.
             disabled={isDisabled && !isFocusableDisabled}
             aria-disabled={isFocusableDisabled ? 'true' : undefined}
+            form={isFocusableDisabled ? '' : undefined}
             readOnly={isReadOnly}
             required={isRequired}
             onChange={e => {
@@ -547,61 +426,25 @@ export function CheckboxInput({
               isDisabled && styles.inputDisabled,
             )}
           />
-          <div
-            aria-hidden="true"
-            {...mergeProps(
-              themeProps('checkbox', {
-                size,
-                checked: isChecked
-                  ? 'checked'
-                  : isIndeterminate
-                    ? 'indeterminate'
-                    : null,
-                disabled: isDisabled ? 'disabled' : null,
-              }),
-              stylex.props(
-                styles.checkbox,
-                checkboxSizeStyles[size],
-                !isDisabled && styles.checkboxFocus,
-                isCheckedOrIndeterminate
-                  ? styles.checkboxChecked
-                  : styles.checkboxUnchecked,
-                isDisabled && styles.checkboxDisabled,
-                isDisabled &&
-                  !isCheckedOrIndeterminate &&
-                  styles.checkboxDisabledUnchecked,
-              ),
-            )}>
-            {isBusy ? (
-              <Spinner size="sm" shade="inherit" />
-            ) : (
-              <>
-                <svg
-                  viewBox="0 0 10 10"
-                  {...stylex.props(
-                    styles.checkmark,
-                    checkmarkSizeStyles[size],
-                    isChecked && styles.checkmarkVisible,
-                  )}>
-                  <path
-                    d="M8.5 2.5L4 7.5L1.5 5"
-                    stroke="currentColor"
-                    strokeWidth="1.5"
-                    fill="none"
-                    strokeLinecap="round"
-                    strokeLinejoin="round"
-                  />
-                </svg>
-                <div
-                  {...stylex.props(
-                    styles.indeterminateMark,
-                    indeterminateSizeStyles[size],
-                    isIndeterminate && styles.indeterminateMarkVisible,
-                  )}
-                />
-              </>
-            )}
-          </div>
+          {/*
+           * A container holding ONLY the indicator, so the focus ring has an
+           * unambiguous target whatever a theme renders. `display: contents`
+           * keeps it out of layout entirely.
+           */}
+          <span ref={indicatorRef} {...stylex.props(styles.indicatorSlot)}>
+            <CheckboxControl
+              state={
+                isIndeterminate
+                  ? 'indeterminate'
+                  : isChecked
+                    ? 'checked'
+                    : 'unchecked'
+              }
+              size={size}
+              isDisabled={isDisabled}>
+              {isBusy ? <Spinner size="sm" shade="inherit" /> : null}
+            </CheckboxControl>
+          </span>
         </div>
         <div {...stylex.props(styles.labelWrapper)}>
           <FieldLabel

package/src/ClickableCard/ClickableCard.tsx

@@ -46,6 +46,7 @@ import {useClickableContainer} from '../hooks/useClickableContainer';
 import type {BaseProps} from '../BaseProps';
 import {useLinkComponent} from '../Link/useLinkComponent';
 import {themeProps} from '../utils/themeProps';
+import {focusOutlineProps} from '../utils/focusOutline.stylex';
 
 // =============================================================================
 // Styles — only the interactive layer, Card handles everything else
@@ -57,13 +58,6 @@ const styles = stylex.create({
     cursor: 'pointer',
     textDecoration: 'none',
     color: 'inherit',
-    outlineOffset: '2px',
-  },
-  focusWithin: {
-    ':has(:focus-visible)': {
-      outline: `2px solid ${colorVars['--color-accent']}`,
-      outlineOffset: '2px',
-    },
   },
   // Hover overlay — guarded by @media (hover: hover) so touch devices
   // don't show a stuck hover state. Active/pressed state works everywhere.
@@ -307,14 +301,15 @@ export function ClickableCard({
       padding={padding}
       variant={variant}
       elevation={elevation}
-      {...mergeProps(themeProps('clickable-card', {variant}), {
-        className: classNameProp,
+      {...mergeProps(
+        themeProps('clickable-card', {variant}),
+        focusOutlineProps.focusWithin(),
+        classNameProp,
         style,
-      })}
+      )}
       xstyle={
         [
           styles.interactive,
-          styles.focusWithin,
           hasBorder ? styles.bordered : styles.borderless,
           !isDisabled && styles.overlay,
           !isDisabled && styles.hoverOnPointer,

package/src/Code/Code.tsx

@@ -1,7 +1,5 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-'use client';
-
 /**
  * @file Code.tsx
  * @input Uses React, StyleX, theme tokens

package/src/CodeBlock/CodeBlock.doc.mjs

@@ -142,6 +142,9 @@ export const docs = {
     targets: [
       {className: 'astryx-code', visualProps: ['color']},
       {className: 'astryx-codeblock', visualProps: ['size', 'language', 'container']},
+      {className: 'astryx-codeblock-header', visualProps: ['size', 'language', 'container']},
+      {className: 'astryx-codeblock-title', visualProps: ['size', 'language']},
+      {className: 'astryx-codeblock-copy-button'},
     ],
   },
   usage: {

package/src/CodeBlock/CodeBlock.test.tsx

@@ -15,6 +15,13 @@ import {CodeBlock} from './CodeBlock';
 import {__resetLiveRegionsForTest} from '../hooks/useAnnounce';
 import {dracula} from '../theme/syntax';
 import {InternationalizationProvider} from '../i18n';
+import {defineTheme} from '../theme/defineTheme';
+import {generateThemeCSS} from '../theme/generateThemeRules';
+
+function generateThemeTestCSS(theme: Parameters<typeof generateThemeCSS>[0]) {
+  const {prose, component} = generateThemeCSS(theme);
+  return [prose, component].filter(Boolean).join('\n\n');
+}
 
 function politeRegion(): HTMLElement | null {
   return document.querySelector('[data-astryx-live-region="polite"]');
@@ -64,6 +71,30 @@ describe('CodeBlock', () => {
     expect(navigator.clipboard.writeText).toHaveBeenCalledWith('const x = 1;');
   });
 
+  it('renders the copy button as a themeable target with a "Copy code" tooltip', () => {
+    render(<CodeBlock code="const x = 1;" language="javascript" />);
+    const copyButton = screen.getByRole('button', {name: 'Copy code'});
+    // Theme seam: a design system can restyle the copy control via this class
+    // without turning the button off and re-implementing it.
+    expect(copyButton).toHaveClass('astryx-codeblock-copy-button');
+    // The button carries a visible "Copy code" hover/focus hint (tooltip),
+    // wired through aria-describedby — a bare <button> could not.
+    expect(copyButton).toHaveAttribute('aria-describedby');
+  });
+
+  it('keeps the copy button tooltip as "Copy code" after copying', async () => {
+    render(<CodeBlock code="const x = 1;" language="javascript" />);
+    fireEvent.click(screen.getByRole('button', {name: 'Copy code'}));
+    await act(async () => {});
+    // The icon flip (copy → check) is the confirmation; the tooltip text does
+    // not change. The accessible name still swaps to "Copied" for AT.
+    const copyButton = screen.getByRole('button', {name: 'Copied'});
+    const tooltipId = copyButton.getAttribute('aria-describedby');
+    expect(tooltipId).toBeTruthy();
+    const tooltip = document.getElementById(tooltipId as string);
+    expect(tooltip).toHaveTextContent('Copy code');
+  });
+
   it('announces "Copied" to a polite live region after copying', async () => {
     render(<CodeBlock code="const x = 1;" language="javascript" />);
     const copyButton = screen.getByRole('button', {name: 'Copy code'});
@@ -304,4 +335,64 @@ describe('CodeBlock', () => {
     expect(container.querySelector('[data-astryx-syntax-theme]')).toBeNull();
     expect(container.firstElementChild?.tagName).toBe('PRE');
   });
+
+  describe('header theming targets', () => {
+    it('puts astryx-codeblock-header on the header row when a header shows', () => {
+      const {container} = render(
+        <CodeBlock
+          code="const x = 1;"
+          language="javascript"
+          title="example.js"
+        />,
+      );
+      expect(
+        container.querySelector('.astryx-codeblock-header'),
+      ).not.toBeNull();
+    });
+
+    it('puts astryx-codeblock-title on the header title element', () => {
+      const {container} = render(
+        <CodeBlock
+          code="const x = 1;"
+          language="javascript"
+          title="example.js"
+        />,
+      );
+      const titleEl = container.querySelector('.astryx-codeblock-title');
+      expect(titleEl).not.toBeNull();
+      // The language label + title text live in this element.
+      expect(titleEl).toHaveTextContent('example.js');
+    });
+
+    it('renders no header targets when there is no header', () => {
+      // plaintext hides the language label and no title is given, so the
+      // header row is not rendered at all.
+      const {container} = render(
+        <CodeBlock code="const x = 1;" language="plaintext" />,
+      );
+      expect(container.querySelector('.astryx-codeblock-header')).toBeNull();
+      expect(container.querySelector('.astryx-codeblock-title')).toBeNull();
+    });
+
+    it('exposes the header and title as themeable defineTheme targets', () => {
+      // jsdom can't resolve the @layer cascade, so this asserts the targets are
+      // reachable by a theme via the sanctioned defineTheme channel — replacing
+      // the structural `> div:first-child > div > span` header/title selectors a
+      // consumer would otherwise need to restyle the header padding and title.
+      const theme = defineTheme({
+        name: 'codeblock-header-target-test',
+        components: {
+          'codeblock-header': {
+            base: {paddingBlock: 'var(--spacing-1)'},
+          },
+          'codeblock-title': {
+            base: {fontSize: 'var(--text-body-size)'},
+          },
+        },
+      });
+      const css = generateThemeTestCSS(theme);
+      expect(css).toContain('.astryx-codeblock-header');
+      expect(css).toContain('.astryx-codeblock-title');
+    });
+  });
 });