@astryxdesign/core 0.4.0 → 0.4.1-canary.1ce0b4c

package/src/Field/PanelSearchInput.tsx

@@ -0,0 +1,271 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file PanelSearchInput.tsx
+ * @input Uses React, StyleX, Icon, InputClearButton, theme tokens
+ * @output Exports PanelSearchInput — the search row that sits at the top of a
+ *   dropdown panel
+ * @position Shared internal primitive; used by Selector and MultiSelector
+ *
+ * A dropdown panel is already a bordered, elevated surface. Nesting a bordered
+ * TextInput inside it draws a second box within that box, so the field reads as
+ * a control dropped into the menu rather than part of it. This row is the
+ * seamless alternative — magnifier, borderless input, clear button — separated
+ * from the options by a divider the panel owns.
+ *
+ * The field is shaped like the option rows under it rather than like a form
+ * input: same inset from the panel edge, same `--radius-element` corners, same
+ * height. The focus ring is drawn on that rounded box, so focus reads as "this
+ * row of the panel" — the same visual language as an item's highlight — instead
+ * of ringing the whole panel header. It appears for keyboard focus only; see
+ * `fieldKeyboardFocus` for why `:focus-visible` alone does not mean that.
+ *
+ *   ┌─ panel ──────────────────┐
+ *   │ ┌──────────────────────┐ │  ← field: rounded, inset, item-sized
+ *   │ │ ⌕  Search…         ✕ │ │
+ *   │ └──────────────────────┘ │
+ *   ├──────────────────────────┤  ← divider (full-bleed)
+ *   │ ┌──────────────────────┐ │
+ *   │ │ Apple                │ │  ← option row: same box
+ *
+ * The clear button is the shared `InputClearButton`, so the affordance and its
+ * ghost-button behavior match every other input's clear. It renders AFTER the
+ * input in DOM order: the selector components' Tab handling depends on that
+ * order to keep the popup open while focus moves onto it.
+ *
+ * Not exported from the package: it is an implementation detail of the panels
+ * that use it, not public API.
+ */
+
+import {useCallback, useEffect, useState, type Ref} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import {Icon} from '../Icon';
+import {InputClearButton} from './InputClearButton';
+import {mergeProps} from '../utils';
+import {
+  getInteractionModality,
+  trackInteractionModality,
+} from '../utils/interactionModality';
+import {
+  colorVars,
+  durationVars,
+  easeVars,
+  radiusVars,
+  spacingVars,
+  typeScaleVars,
+  typographyVars,
+} from '../theme/tokens.stylex';
+import type {BaseProps} from '../BaseProps';
+
+const styles = stylex.create({
+  // Gutter only. Matches the option list's own padding so the field below
+  // lines up with the option rows rather than with the panel edge.
+  wrapper: {
+    paddingBlock: spacingVars['--spacing-1'],
+    paddingInline: spacingVars['--spacing-1'],
+  },
+  // The field proper — the same box an option row draws: `--radius-element`
+  // corners and, at md, a 6/8 padding pair that lands it on the option row's
+  // 32px height. Focus rings THIS, not the full-width row.
+  field: {
+    boxSizing: 'border-box',
+    display: 'flex',
+    alignItems: 'center',
+    gap: spacingVars['--spacing-2'],
+    width: '100%',
+    paddingBlock: spacingVars['--spacing-1-5'],
+    paddingInline: spacingVars['--spacing-2'],
+    borderRadius: radiusVars['--radius-element'],
+    transitionProperty: 'box-shadow',
+    transitionDuration: {
+      default: durationVars['--duration-fast'],
+      '@media (prefers-reduced-motion: reduce)': '0s',
+    },
+    transitionTimingFunction: easeVars['--ease-standard'],
+  },
+  // The focus ring, applied only while focus was taken by keyboard (see
+  // `isKeyboardFocus`). `:has(input:focus-visible)` stays the CSS condition —
+  // the browser's heuristic still decides, this only narrows it — and rings
+  // the field rather than the bare <input> so the magnifier and the clear
+  // button sit inside it, and so tabbing ONTO the clear button does not
+  // re-ring the field.
+  //
+  // Inset, not the shared 3px-offset outline: the field is inset 4-5px from
+  // the panel edge, so an outline at that offset would land on the panel's own
+  // border and the divider. Measured, not guessed.
+  fieldKeyboardFocus: {
+    boxShadow: {
+      default: 'none',
+      ':has(input:focus-visible)': `inset 0 0 0 2px ${colorVars['--color-accent']}`,
+    },
+  },
+  // The icon span needs explicit flex centering to avoid a line-height offset.
+  icon: {
+    display: 'flex',
+    alignItems: 'center',
+    flexShrink: 0,
+  },
+  input: {
+    flexGrow: 1,
+    flexShrink: 1,
+    minWidth: 0,
+    padding: 0,
+    margin: 0,
+    borderWidth: 0,
+    borderStyle: 'none',
+    backgroundColor: 'transparent',
+    color: colorVars['--color-text-primary'],
+    fontFamily: typographyVars['--font-family-body'],
+    // Matches the option rows below it, so the query reads as the first line of
+    // the list. The coarse-pointer floor keeps iOS from zooming on focus.
+    fontSize: {
+      default: typeScaleVars['--text-label-size'],
+      '@media (pointer: coarse)': `max(1rem, ${typeScaleVars['--text-label-size']})`,
+    },
+    lineHeight: typeScaleVars['--text-label-leading'],
+    // The field draws the focus ring (see `field`), so the bare input must not
+    // draw a second one inside it.
+    outline: 'none',
+    '::placeholder': {
+      color: colorVars['--color-text-secondary'],
+    },
+  },
+});
+
+export interface PanelSearchInputProps extends Omit<
+  BaseProps<HTMLInputElement>,
+  'onChange'
+> {
+  /** Ref forwarded to the input element (for focus management). */
+  ref?: Ref<HTMLInputElement>;
+
+  /**
+   * Accessible name for the input. Rendered as `aria-label`: the panel has no
+   * visible label for the field, and a placeholder is not a reliable name.
+   */
+  label: string;
+
+  /** Accessible name for the clear (✕) button, e.g. `Clear Search options`. */
+  clearLabel: string;
+
+  /** Placeholder text shown while the query is empty. */
+  placeholder?: string;
+
+  /** The current query. */
+  value: string;
+
+  /** Called with the next query on every keystroke and on clear. */
+  onValueChange: (value: string) => void;
+
+  /** Key handler for the input itself. */
+  onKeyDown?: React.KeyboardEventHandler<HTMLInputElement>;
+
+  /** Focus handler for the input; runs after the ring's own bookkeeping. */
+  onFocus?: React.FocusEventHandler<HTMLInputElement>;
+
+  /** Blur handler for the input; runs after the ring's own bookkeeping. */
+  onBlur?: React.FocusEventHandler<HTMLInputElement>;
+
+  /**
+   * Key handler for the row. Events from the input are handled by `onKeyDown`;
+   * this one exists for keys pressed on the clear button, which has no other
+   * handler of its own.
+   */
+  onContainerKeyDown?: React.KeyboardEventHandler<HTMLDivElement>;
+}
+
+/**
+ * Search row for the top of a dropdown panel: magnifier, borderless input, and
+ * a clear button once a query is typed, in a rounded box shaped like the
+ * option rows beneath it.
+ *
+ * `className`/`style`/`xstyle` apply to the outer row (use them to match the
+ * option list's inline padding); every other prop (`role`, `aria-*`, `id`, …)
+ * passes through to the `<input>`, so the caller owns the combobox wiring.
+ */
+export function PanelSearchInput({
+  ref,
+  label,
+  clearLabel,
+  placeholder,
+  value,
+  onValueChange,
+  onKeyDown,
+  onFocus,
+  onBlur,
+  onContainerKeyDown,
+  xstyle,
+  className,
+  style,
+  ...props
+}: PanelSearchInputProps) {
+  // `:focus-visible` matches a text input focused by POINTER as well (CSS
+  // Selectors 4, verified in Chromium), so it cannot express "keyboard focus"
+  // by itself. Gate it on how the user last interacted; the CSS condition
+  // stays `:focus-visible`, this only narrows it.
+  const [isKeyboardFocus, setIsKeyboardFocus] = useState(false);
+
+  useEffect(() => {
+    trackInteractionModality();
+  }, []);
+
+  const handleFocus = useCallback(
+    (e: React.FocusEvent<HTMLInputElement>) => {
+      setIsKeyboardFocus(getInteractionModality() === 'keyboard');
+      onFocus?.(e);
+    },
+    [onFocus],
+  );
+
+  const handleBlur = useCallback(
+    (e: React.FocusEvent<HTMLInputElement>) => {
+      setIsKeyboardFocus(false);
+      onBlur?.(e);
+    },
+    [onBlur],
+  );
+
+  const handleClear = useCallback(() => {
+    onValueChange('');
+    // Clearing puts the caret back where the user was typing, matching
+    // TextInput's built-in clear.
+    if (typeof ref === 'object' && ref?.current) {
+      ref.current.focus();
+    }
+  }, [onValueChange, ref]);
+
+  return (
+    <div
+      onKeyDown={onContainerKeyDown}
+      {...mergeProps(stylex.props(styles.wrapper, xstyle), className, style)}>
+      <div
+        data-keyboard-focus={isKeyboardFocus ? 'true' : undefined}
+        {...stylex.props(
+          styles.field,
+          isKeyboardFocus && styles.fieldKeyboardFocus,
+        )}>
+        <Icon icon="search" size="sm" color="secondary" xstyle={styles.icon} />
+        <input
+          ref={ref}
+          type="text"
+          aria-label={label}
+          placeholder={placeholder}
+          value={value}
+          onChange={e => onValueChange(e.target.value)}
+          onKeyDown={onKeyDown}
+          onFocus={handleFocus}
+          onBlur={handleBlur}
+          {...stylex.props(styles.input)}
+          {...props}
+        />
+        {value !== '' && (
+          <InputClearButton label={clearLabel} onClick={handleClear} />
+        )}
+      </div>
+    </div>
+  );
+}
+
+PanelSearchInput.displayName = 'PanelSearchInput';

package/src/FileInput/FileInput.tsx

@@ -59,6 +59,7 @@ import type {BaseProps} from '../BaseProps';
 import type {SizeValue} from '../utils/types';
 import {themeProps} from '../utils/themeProps';
 import {useTranslator} from '../i18n';
+import type {TranslatorFn} from '../i18n';
 
 function formatFileSize(bytes: number): string {
   if (bytes < 1024) {
@@ -76,12 +77,13 @@ function validateFiles(
   maxSize: number | undefined,
   maxFiles: number | undefined,
   isMultiple: boolean,
+  t: TranslatorFn,
 ): {valid: File[]; errors: string[]} {
   const errors: string[] = [];
   let valid = files;
 
   if (accept) {
-    const acceptedTypes = accept.split(',').map(t => t.trim().toLowerCase());
+    const acceptedTypes = accept.split(',').map(s => s.trim().toLowerCase());
     valid = valid.filter(file => {
       const matches = acceptedTypes.some(type => {
         if (type.startsWith('.')) {
@@ -93,7 +95,9 @@ function validateFiles(
         return file.type.toLowerCase() === type;
       });
       if (!matches) {
-        errors.push(`"${file.name}" is not an accepted file type`);
+        errors.push(
+          t('@astryx.fileInput.errorInvalidType', {fileName: file.name}),
+        );
       }
       return matches;
     });
@@ -102,7 +106,12 @@ function validateFiles(
   if (maxSize != null) {
     valid = valid.filter(file => {
       if (file.size > maxSize) {
-        errors.push(`"${file.name}" exceeds ${formatFileSize(maxSize)} limit`);
+        errors.push(
+          t('@astryx.fileInput.errorMaxSize', {
+            fileName: file.name,
+            maxSize: formatFileSize(maxSize),
+          }),
+        );
         return false;
       }
       return true;
@@ -110,7 +119,7 @@ function validateFiles(
   }
 
   if (isMultiple && maxFiles != null && valid.length > maxFiles) {
-    errors.push(`Maximum ${maxFiles} files allowed`);
+    errors.push(t('@astryx.fileInput.errorMaxFiles', {maxFiles}));
     valid = valid.slice(0, maxFiles);
   }
 
@@ -488,7 +497,9 @@ export function FileInput({
       .filter(Boolean)
       .join(' ') || undefined;
 
-  const defaultPlaceholder = isMultiple ? 'Choose files' : 'Choose file';
+  const defaultPlaceholder = isMultiple
+    ? t('@astryx.fileInput.placeholderMultiple')
+    : t('@astryx.fileInput.placeholder');
   const displayPlaceholder = placeholder ?? defaultPlaceholder;
 
   const handleFiles = useCallback(
@@ -503,6 +514,7 @@ export function FileInput({
         maxSize,
         maxFiles,
         isMultiple,
+        t,
       );
 
       if (errors.length > 0) {
@@ -526,8 +538,8 @@ export function FileInput({
       if (errors.length === 0) {
         announce(
           valid.length === 1
-            ? `1 file selected: ${valid[0].name}`
-            : `${valid.length} files selected`,
+            ? t('@astryx.fileInput.fileSelected', {fileName: valid[0].name})
+            : t('@astryx.fileInput.filesSelected', {count: valid.length}),
         );
       }
 
@@ -547,6 +559,7 @@ export function FileInput({
       changeAction,
       startTransition,
       announce,
+      t,
     ],
   );
 
@@ -679,7 +692,7 @@ export function FileInput({
       <>
         <Icon icon="arrowUp" size="md" color="secondary" />
         <span {...stylex.props(styles.placeholderText)}>
-          {isDragOver ? 'Drop files here' : displayPlaceholder}
+          {isDragOver ? t('@astryx.fileInput.dropHint') : displayPlaceholder}
         </span>
       </>
     );

package/src/Grid/Grid.tsx

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

package/src/Grid/index.ts

@@ -1,7 +1,5 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-'use client';
-
 /**
  * @file index.ts
  * @input Imports from Grid.tsx and GridSpan.tsx

package/src/HoverCard/HoverCard.doc.mjs

@@ -114,7 +114,7 @@ export const docs = {
       { guidance: false, description: 'Place critical actions or required information inside a hover card; users may miss content that only appears on hover.' },
       { guidance: false, description: 'Use a hover card when a simple Tooltip or Popover would suffice.' },
       { guidance: false, description: 'Use a HoverCard for content the user must interact with; it disappears when the cursor leaves.' },
-      { guidance: false, description: 'Nest a HoverCard whose content has block elements directly inside phrasing-only contexts such as a <p>, <label>, or heading. The card renders inline, so block content there is invalid HTML the browser reparents. Wrap the surrounding text in a block element (e.g. a <div>) instead.' },
+      { guidance: true, description: 'Prefer placing HoverCard in a block context rather than directly in a <p>, heading, or link. Those placements are supported when necessary through a corrective portal, but the DOM and tab order may differ.' },
     ],
     anatomy: [
       {name: 'Trigger', required: true, description: 'The element that opens the hover card on hover or focus: a button, link, or inline text.'},
@@ -229,7 +229,7 @@ export const docsZh = {
       { guidance: false, description: 'Place critical actions or required information inside a hover card; users may miss content that only appears on hover.' },
       { guidance: false, description: 'Use a hover card when a simple Tooltip or Popover would suffice.' },
       { guidance: false, description: 'Use a HoverCard for content the user must interact with; it disappears when the cursor leaves.' },
-      { guidance: false, description: 'Nest a HoverCard whose content has block elements directly inside phrasing-only contexts such as a <p>, <label>, or heading. The card renders inline, so block content there is invalid HTML the browser reparents. Wrap the surrounding text in a block element (e.g. a <div>) instead.' },
+      { guidance: true, description: 'Prefer placing HoverCard in a block context rather than directly in a <p>, heading, or link. Those placements are supported when necessary through a corrective portal, but the DOM and tab order may differ.' },
     ],
   },
 };
@@ -247,7 +247,7 @@ export const docsDense = {
       { guidance: false, description: 'Place critical actions or required information inside a hover card; users may miss content that only appears on hover.' },
       { guidance: false, description: 'Use a hover card when a simple Tooltip or Popover would suffice.' },
       { guidance: false, description: 'Use a HoverCard for content the user must interact with; it disappears when the cursor leaves.' },
-      { guidance: false, description: 'Nest a block-content HoverCard directly inside phrasing-only contexts (<p>, <label>, heading); it renders inline so block content is invalid HTML there. Wrap surrounding text in a block element instead.' },
+      { guidance: true, description: 'Prefer a block context over a direct <p>, heading, or link placement. Those placements work when necessary through a corrective portal, but DOM/tab order may differ.' },
     ],
   },
   components: [