@astryxdesign/core 0.2.0 → 0.3.0

package/src/TextArea/TextArea.tsx

@@ -13,7 +13,7 @@
  * - /packages/core/src/TextArea/TextArea.test.tsx (tests for new/changed behavior)
  * - /packages/core/src/TextArea/index.ts (exports if types change)
  * - /apps/storybook/stories/TextArea.stories.tsx (storybook stories)
- * - /packages/cli/templates/blocks/components/TextArea/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/TextArea/ (showcase blocks)
  */
 
 import {
@@ -21,6 +21,7 @@ import {
   useOptimistic,
   useTransition,
   useRef,
+  useCallback,
   type ChangeEvent,
   type ClipboardEvent,
   type FocusEvent,
@@ -41,7 +42,7 @@ import {
   inputStatusFocusWithinStyles,
   type FieldStatusVariant,
 } from '../Field';
-import {renderIconSlot, type IconType} from '../Icon';
+import {Icon, renderIconSlot, type IconType} from '../Icon';
 import {Spinner} from '../Spinner';
 import {useTooltip} from '../Tooltip';
 import {mergeProps, mergeRefs} from '../utils';
@@ -49,25 +50,39 @@ import type {BaseProps} from '../BaseProps';
 import type {SizeValue} from '../utils/types';
 import {useInputContainer} from '../hooks/useInputContainer';
 import {useInputStatusIcon} from '../hooks/useInputStatusIcon';
+import {useAnnounce} from '../hooks/useAnnounce';
 import {useSize} from '../SizeContext/SizeContext';
 import {themeProps} from '../utils/themeProps';
-import {VisuallyHidden} from '../VisuallyHidden';
+import {useTranslator} from '../i18n';
 
 const COUNTER_WARNING_THRESHOLD = 0.8;
 
 const styles = stylex.create({
+  // The wrapper is a bare positioning context. The <textarea> spans the full
+  // container and carries its own internal padding; icons, status/spinner, and
+  // the character counter are absolutely-positioned overlays anchored to the
+  // container corners. This keeps the native resize grip in the true
+  // bottom-right corner and lets the scrollbar represent the full input area.
   wrapper: {
     zIndex: 1,
-    alignItems: 'flex-start',
-    paddingBlock: spacingVars['--spacing-1'],
+    display: 'block',
+    padding: 0,
+    // Internal inline padding for the textarea's text. Defined on the wrapper
+    // so the counter (a sibling overlay) inherits the same value and stays
+    // aligned with the text edge. Kept as an internal var so it can later be
+    // driven by a theme "padding" translation without touching either child.
+    '--_textarea-inline-padding': spacingVars['--spacing-2'],
   },
   textarea: {
     display: 'block',
-    flex: 1,
+    width: '100%',
+    boxSizing: 'border-box',
     minWidth: 0,
     borderWidth: 0,
     borderStyle: 'none',
-    padding: 0,
+    // Base internal padding; overlays get their own reserved space below.
+    paddingBlock: spacingVars['--spacing-1'],
+    paddingInline: 'var(--_textarea-inline-padding)',
     fontFamily: typographyVars['--font-family-body'],
     fontSize: {
       default: typeScaleVars['--text-body-size'],
@@ -85,29 +100,59 @@ const styles = stylex.create({
   textareaDisabled: {
     cursor: 'not-allowed',
   },
+  // Reserve start padding so text clears the start icon.
+  // inline inset + 16px icon (sm) + 8px gap
+  textareaWithStartIcon: {
+    paddingInlineStart: `calc(var(--_textarea-inline-padding) + ${spacingVars['--spacing-6']})`,
+  },
+  // Reserve end padding so text clears the status icon / spinner overlay.
+  // inline inset + 20px icon (md) + 4px gap
+  textareaWithStatus: {
+    paddingInlineEnd: `calc(var(--_textarea-inline-padding) + ${spacingVars['--spacing-6']})`,
+  },
+  // Reserve wider end padding when the spinner AND status icon both show.
+  // inline inset + 16px spinner + 8px gap + 20px icon + 4px gap
+  textareaWithBusyStatus: {
+    paddingInlineEnd: `calc(var(--_textarea-inline-padding) + ${spacingVars['--spacing-12']})`,
+  },
+  // Reserve bottom padding so text clears the character counter overlay.
+  textareaWithCounter: {
+    paddingBottom: spacingVars['--spacing-7'],
+  },
+  startIcon: {
+    position: 'absolute',
+    top: spacingVars['--spacing-2'],
+    insetInlineStart: 'var(--_textarea-inline-padding)',
+    pointerEvents: 'none',
+    display: 'flex',
+  },
+  endSlot: {
+    position: 'absolute',
+    top: spacingVars['--spacing-2'],
+    insetInlineEnd: 'var(--_textarea-inline-padding)',
+    pointerEvents: 'none',
+    display: 'flex',
+    alignItems: 'center',
+    gap: spacingVars['--spacing-2'],
+  },
+  // Character counter lives inside the input container, anchored bottom-right
+  // underneath the textarea, aligned to the same inline inset as the text.
   counter: {
+    position: 'absolute',
+    bottom: spacingVars['--spacing-1'],
+    insetInlineEnd: 'var(--_textarea-inline-padding)',
+    pointerEvents: 'none',
     display: 'flex',
-    justifyContent: 'flex-end',
-    marginTop: spacingVars['--spacing-1'],
+    alignItems: 'center',
+    gap: spacingVars['--spacing-1'],
     fontFamily: typographyVars['--font-family-body'],
     fontSize: typeScaleVars['--text-supporting-size'],
+    lineHeight: typeScaleVars['--text-supporting-leading'],
     color: colorVars['--color-text-secondary'],
   },
   counterError: {
     color: colorVars['--color-error'],
   },
-  statusIcon: {
-    position: 'absolute',
-    top: spacingVars['--spacing-2'],
-    insetInlineEnd: spacingVars['--spacing-2'],
-    pointerEvents: 'none',
-    display: 'flex',
-  },
-  textareaWithStatus: {
-    // Reserve space so text doesn't flow under the absolutely-positioned icon.
-    // 20px (icon md) + 4px gap = 24px (--spacing-6)
-    paddingInlineEnd: spacingVars['--spacing-6'],
-  },
 });
 
 const textareaSizeStyles = stylex.create({
@@ -326,12 +371,17 @@ export function TextArea({
   ...rest
 }: TextAreaProps) {
   const size = useSize(sizeProp, 'md');
+  const t = useTranslator();
+  const announce = useAnnounce();
   const id = useId();
   const descriptionID = useId();
   const statusMessageID = useId();
   const counterID = useId();
   const textareaRef = useRef<HTMLTextAreaElement | null>(null);
   const containerRef = useRef<HTMLDivElement | null>(null);
+  // Tracks the counter "zone" last announced (under / near / over) so we only
+  // announce on a zone change, not on every keystroke.
+  const counterZoneRef = useRef<'under' | 'near' | 'over' | null>(null);
 
   const [, startTransition] = useTransition();
   const [optimisticValue, setOptimisticValue] = useOptimistic(value);
@@ -370,6 +420,43 @@ export function TextArea({
       .filter(Boolean)
       .join(' ') || undefined;
 
+  // Announce the character-count status through the shared live region, but
+  // only when the value crosses into a new zone (near the limit / over the
+  // limit) so we don't speak on every keystroke. Over-limit is assertive (an
+  // error the user should hear immediately); nearing the limit is polite.
+  const announceCounter = useCallback(
+    (length: number) => {
+      if (maxLength == null) {
+        return;
+      }
+      const zone: 'under' | 'near' | 'over' =
+        length > maxLength
+          ? 'over'
+          : length >= maxLength * COUNTER_WARNING_THRESHOLD
+            ? 'near'
+            : 'under';
+      if (zone === counterZoneRef.current) {
+        return;
+      }
+      counterZoneRef.current = zone;
+      if (zone === 'over') {
+        announce(
+          t('@astryx.textArea.charactersOverLimit', {
+            count: length - maxLength,
+          }),
+          'assertive',
+        );
+      } else if (zone === 'near') {
+        announce(
+          t('@astryx.textArea.charactersRemaining', {
+            count: maxLength - length,
+          }),
+        );
+      }
+    },
+    [announce, t, maxLength],
+  );
+
   const handleChange = (e: ChangeEvent<HTMLTextAreaElement>) => {
     // Value can't change while showing a disabled message (the field is
     // read-only and non-native-disabled), but guard the handler too so the
@@ -378,6 +465,7 @@ export function TextArea({
       return;
     }
     const newValue = e.target.value;
+    announceCounter(newValue.length);
     onChange?.(newValue, e);
     if (changeAction && !e.defaultPrevented) {
       startTransition(async () => {
@@ -434,20 +522,20 @@ export function TextArea({
           stylex.props(
             inputWrapperStyles.base,
             styles.wrapper,
-            textareaSizeStyles[size],
-            effectivelyDisabled && inputWrapperStyles.disabled,
+            isDisabled && inputWrapperStyles.disabled,
             status && inputStatusBorderStyles[status.type],
-            status &&
-              !effectivelyDisabled &&
-              inputStatusHoverShadowStyles[status.type],
+            status && !isDisabled && inputStatusHoverShadowStyles[status.type],
             status && inputStatusFocusWithinStyles[status.type],
             xstyle,
           ),
           className,
           style,
         )}>
-        {startIcon &&
-          renderIconSlot(startIcon, {size: 'sm', color: 'secondary'})}
+        {startIcon && (
+          <span {...stylex.props(styles.startIcon)}>
+            {renderIconSlot(startIcon, {size: 'sm', color: 'secondary'})}
+          </span>
+        )}
         <textarea
           {...rest}
           ref={mergeRefs(ref, textareaRef)}
@@ -480,32 +568,37 @@ export function TextArea({
           aria-busy={isBusy || undefined}
           {...stylex.props(
             styles.textarea,
-            effectivelyDisabled && styles.textareaDisabled,
-            status && styles.textareaWithStatus,
+            textareaSizeStyles[size],
+            isDisabled && styles.textareaDisabled,
+            Boolean(startIcon) && styles.textareaWithStartIcon,
+            (status || isBusy) && styles.textareaWithStatus,
+            isBusy && !!statusIcon && styles.textareaWithBusyStatus,
+            maxLength != null && styles.textareaWithCounter,
           )}
         />
-        {isBusy && <Spinner size="sm" />}
-        {statusIcon && (
-          <span {...stylex.props(styles.statusIcon)}>{statusIcon}</span>
+        {(isBusy || statusIcon) && (
+          <span {...stylex.props(styles.endSlot)}>
+            {isBusy && <Spinner size="sm" />}
+            {statusIcon}
+          </span>
+        )}
+        {maxLength != null && (
+          <div
+            id={counterID}
+            {...stylex.props(
+              styles.counter,
+              optimisticValue.length > maxLength && styles.counterError,
+            )}>
+            {optimisticValue.length > maxLength && (
+              // Non-color cue so the over-limit state isn't conveyed by the red
+              // color alone (WCAG 1.4.1). Decorative — the count text and the
+              // live-region announcement carry the meaning.
+              <Icon icon="warning" size="sm" />
+            )}
+            {optimisticValue.length}/{maxLength}
+          </div>
         )}
       </div>
-      {maxLength != null && (
-        <div
-          id={counterID}
-          {...stylex.props(
-            styles.counter,
-            optimisticValue.length > maxLength && styles.counterError,
-          )}>
-          {optimisticValue.length}/{maxLength}
-          <VisuallyHidden aria-live="polite">
-            {optimisticValue.length >= maxLength * COUNTER_WARNING_THRESHOLD
-              ? optimisticValue.length > maxLength
-                ? `${optimisticValue.length - maxLength} characters over limit`
-                : `${maxLength - optimisticValue.length} characters remaining`
-              : ''}
-          </VisuallyHidden>
-        </div>
-      )}
       {showsDisabledMessage &&
         disabledMessageTooltip.renderTooltip(disabledMessage)}
     </Field>

package/src/TextInput/TextInput.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: 'TextInput',
@@ -177,7 +177,7 @@ export const docs = {
   },
 };
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 export const docsZh = {
   name: 'TextInput',
   displayName: 'Text Input',
@@ -343,7 +343,7 @@ export const docsZh = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description: 'Text input for collecting user text w/ label, description, validation status, optional/required indicators.',
   usage: {

package/src/TextInput/TextInput.tsx

@@ -13,7 +13,7 @@
  * - /packages/core/src/TextInput/TextInput.test.tsx (tests for new/changed behavior)
  * - /packages/core/src/TextInput/index.ts (exports if types change)
  * - /apps/storybook/stories/TextInput.stories.tsx (storybook stories)
- * - /packages/cli/templates/blocks/components/TextInput/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/TextInput/ (showcase blocks)
  */
 
 import {

package/src/Thumbnail/Thumbnail.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: 'Thumbnail',
@@ -98,7 +98,7 @@ export const docs = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsZh = {
   propDescriptions: {
     src: '\u56FE\u7247\u6E90 URL\u3002',

package/src/Thumbnail/Thumbnail.test.tsx

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 import {describe, it, expect, vi} from 'vitest';
-import {render, screen} from '@testing-library/react';
+import {render, screen, fireEvent} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {Thumbnail} from './Thumbnail';
 
@@ -219,4 +219,27 @@ describe('Thumbnail', () => {
       expect(onRemove).toHaveBeenCalledOnce();
     });
   });
+
+  it('shows the placeholder when the image fails to load', () => {
+    render(<Thumbnail src="/broken.jpg" alt="Broken" data-testid="thumb" />);
+
+    fireEvent.error(screen.getByRole('img'));
+
+    expect(screen.queryByRole('img')).toBeNull();
+    const root = screen.getByTestId('thumb');
+    expect(root.querySelector('svg')).toBeInTheDocument();
+  });
+
+  it('retries a changed src after a load error', () => {
+    const {rerender} = render(
+      <Thumbnail src="/broken.jpg" alt="Photo" data-testid="thumb" />,
+    );
+    fireEvent.error(screen.getByRole('img'));
+    expect(screen.queryByRole('img')).toBeNull();
+
+    rerender(<Thumbnail src="/fixed.jpg" alt="Photo" data-testid="thumb" />);
+
+    const img = screen.getByRole('img');
+    expect(img).toHaveAttribute('src', '/fixed.jpg');
+  });
 });

package/src/Thumbnail/Thumbnail.tsx

@@ -22,9 +22,10 @@
  * - /packages/core/src/Thumbnail/Thumbnail.test.tsx
  * - /packages/core/src/Thumbnail/index.ts
  * - /apps/storybook/stories/Thumbnail.stories.tsx
- * - /packages/cli/templates/blocks/components/Thumbnail/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/Thumbnail/ (showcase blocks)
  */
 
+import {useState} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import {
   colorVars,
@@ -39,11 +40,11 @@ import {Skeleton} from '../Skeleton';
 import {Spinner} from '../Spinner';
 import {Tooltip} from '../Tooltip/Tooltip';
 import {useDevWarning} from '../hooks/useDevWarning';
+import {useContainerReveal} from '../hooks/useContainerReveal';
 import type {BaseProps} from '../BaseProps';
 import {mergeProps} from '../utils';
 import {themeProps} from '../utils/themeProps';
 import {useTranslator} from '../i18n';
-import {thumbnailScope} from './thumbnail.markers.stylex';
 
 export interface ThumbnailProps extends BaseProps<HTMLDivElement> {
   /** Ref forwarded to the root element */
@@ -236,28 +237,6 @@ const styles = stylex.create({
     zIndex: 1,
     lineHeight: 0,
   },
-  // showRemoveOn="hover": the remove button is hidden at rest and revealed
-  // when the thumbnail is hovered or when focus enters it (keyboard). Only
-  // opacity is animated — the button stays mounted and focusable so tabbing
-  // to it triggers the :focus-within reveal. Any touch-capable device (incl.
-  // hybrid laptops that also report hover) keeps the button visible so the
-  // remove path is never gated behind an unavailable hover.
-  removeOnHover: {
-    opacity: {
-      default: 0,
-      [stylex.when.ancestor(':hover', thumbnailScope)]: {
-        '@media (hover: hover)': 1,
-      },
-      [stylex.when.ancestor(':focus-within', thumbnailScope)]: 1,
-      '@media (any-pointer: coarse)': 1,
-    },
-    transitionProperty: 'opacity',
-    transitionDuration: {
-      default: durationVars['--duration-fast'],
-      '@media (prefers-reduced-motion: reduce)': '0s',
-    },
-    transitionTimingFunction: easeVars['--ease-standard'],
-  },
 });
 
 // =============================================================================
@@ -318,14 +297,22 @@ export function Thumbnail({
 }: ThumbnailProps) {
   const t = useTranslator();
 
+  // Track the exact src that failed (rather than a boolean) so a changed src
+  // gets a fresh load attempt instead of the stale error.
+  const [erroredSrc, setErroredSrc] = useState<string | undefined>(undefined);
+
   const hasSrc = src != null;
+  const hasError = hasSrc && erroredSrc === src;
   const showSkeleton = isLoading && !hasSrc;
-  const showImage = hasSrc && !showSkeleton;
+  const showImage = hasSrc && !showSkeleton && !hasError;
   const showUploadOverlay = isLoading && hasSrc;
-  const showPlaceholder = !isLoading && !hasSrc;
+  const showPlaceholder = (!isLoading && !hasSrc) || hasError;
   const isInteractive = onClick != null && !isDisabled && !isLoading;
   const hasRemove = onRemove != null && !isDisabled;
   const isHoverReveal = hasRemove && showRemoveOn === 'hover';
+  const {getContainerProps, getContentRevealProps} = useContainerReveal({
+    isEnabled: isHoverReveal,
+  });
   const accessibleName =
     label && alt
       ? `${label} — ${alt}`
@@ -363,6 +350,7 @@ export function Thumbnail({
           alt={alt ?? ''}
           role={isImageDecorative ? 'presentation' : undefined}
           aria-hidden={isImageDecorative || undefined}
+          onError={() => setErroredSrc(src)}
           {...stylex.props(styles.image)}
         />
       )}
@@ -377,9 +365,12 @@ export function Thumbnail({
 
   const removeButtonEl = hasRemove ? (
     <div
-      {...stylex.props(
-        styles.removeSlot,
-        isHoverReveal && styles.removeOnHover,
+      {...mergeProps(
+        stylex.props(styles.removeSlot),
+        // The remove button is absolutely positioned in the corner, so it is
+        // already out of flow — an opacity-only reveal (layout preserved)
+        // matches its overlay placement instead of the clip recipe.
+        isHoverReveal ? getContentRevealProps({isLayoutPreserved: true}) : {},
       )}>
       <Button
         icon={<Icon icon="close" size="xsm" />}
@@ -410,12 +401,14 @@ export function Thumbnail({
       )}
       {...props}>
       <div
-        {...stylex.props(
-          styles.imageContainer,
-          isHoverReveal && thumbnailScope,
-          isInteractive && styles.interactive,
-          isInteractive && styles.overlay,
-          isInteractive && styles.hoverOnPointer,
+        {...mergeProps(
+          stylex.props(
+            styles.imageContainer,
+            isInteractive && styles.interactive,
+            isInteractive && styles.overlay,
+            isInteractive && styles.hoverOnPointer,
+          ),
+          isHoverReveal ? getContainerProps() : {},
         )}>
         {isInteractive ? (
           <button

package/src/TimeInput/TimeInput.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: 'TimeInput',
@@ -262,7 +262,7 @@ export const docs = {
   },
 };
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 export const docsZh = {
   name: 'TimeInput',
 
@@ -489,7 +489,7 @@ export const docsZh = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description:
     'Time input that converts free-text entry to standard format with arrow-key adjustment.',

package/src/TimeInput/TimeInput.tsx

@@ -13,7 +13,7 @@
  * - /packages/core/src/TimeInput/TimeInput.test.tsx (tests for new/changed behavior)
  * - /packages/core/src/TimeInput/index.ts (exports if types change)
  * - /apps/storybook/stories/TimeInput.stories.tsx (storybook stories)
- * - /packages/cli/templates/blocks/components/TimeInput/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/TimeInput/ (showcase blocks)
  */
 
 import {