@astryxdesign/core 0.1.6 → 0.1.7-canary.04cd8f7

package/src/PowerSearch/types.ts

@@ -256,13 +256,7 @@ export type DateTimeRangePart =
       readonly type: 'RELATIVE';
       readonly backValue: number;
       readonly unit:
-        | 'second'
-        | 'minute'
-        | 'hour'
-        | 'day'
-        | 'week'
-        | 'month'
-        | 'year';
+        'second' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'year';
       readonly anchorKey?: string;
     };
 
@@ -285,12 +279,42 @@ export interface RelativeDateFilterPreset {
 // Config Types
 // =============================================================================
 
-export interface PowerSearchOperator {
+export interface PowerSearchOperatorBase {
   readonly key: string;
-  readonly label: string;
   readonly value: OperatorValue;
 }
 
+/**
+ * Operator variant that provides its label as raw text. The consumer owns
+ * translation of that string. Use this for genuinely custom operator labels
+ * that don't correspond to an entry in astryx's shipped translation catalog
+ * (e.g. `label: 'in my rotations'`).
+ */
+export interface PowerSearchOperatorWithLabel extends PowerSearchOperatorBase {
+  readonly label: string;
+  readonly i18nKey?: never;
+}
+
+/**
+ * Operator variant that references a translation-catalog key. The library
+ * looks the key up against the active InternationalizationProvider locale.
+ * Use `@astryx.powersearch.operator.*` for astryx's shipped defaults, or a
+ * key from your own catalog registered via InternationalizationProvider
+ * `messages` / `overrides` props.
+ */
+export interface PowerSearchOperatorWithI18nKey extends PowerSearchOperatorBase {
+  readonly i18nKey: string;
+  readonly label?: never;
+}
+
+/**
+ * A discriminated union: an operator must supply EXACTLY ONE of `label`
+ * (raw text) or `i18nKey` (catalog lookup). The type system prevents
+ * accidental omission — a bare `{key, value}` is a compile error.
+ */
+export type PowerSearchOperator =
+  PowerSearchOperatorWithLabel | PowerSearchOperatorWithI18nKey;
+
 export interface PowerSearchField {
   readonly key: string;
   readonly label: string;

package/src/PowerSearch/usePowerSearchConfig.ts

@@ -119,30 +119,46 @@ function stringOperators(): {
   return {
     defaultOperator: StringOps.CONTAINS,
     operators: [
-      {key: StringOps.CONTAINS, label: 'contains', value: {type: 'string'}},
+      {
+        key: StringOps.CONTAINS,
+        i18nKey: '@astryx.powersearch.operator.contains',
+        value: {type: 'string'},
+      },
       {
         key: StringOps.NOT_CONTAINS,
-        label: 'does not contain',
+        i18nKey: '@astryx.powersearch.operator.notContains',
         value: {type: 'string'},
       },
       {
         key: StringOps.STARTS_WITH,
-        label: 'starts with',
+        i18nKey: '@astryx.powersearch.operator.startsWith',
         value: {type: 'string'},
       },
       {
         key: StringOps.NOT_STARTS_WITH,
-        label: 'does not start with',
+        i18nKey: '@astryx.powersearch.operator.notStartsWith',
+        value: {type: 'string'},
+      },
+      {
+        key: StringOps.ENDS_WITH,
+        i18nKey: '@astryx.powersearch.operator.endsWith',
         value: {type: 'string'},
       },
-      {key: StringOps.ENDS_WITH, label: 'ends with', value: {type: 'string'}},
       {
         key: StringOps.NOT_ENDS_WITH,
-        label: 'does not end with',
+        i18nKey: '@astryx.powersearch.operator.notEndsWith',
+        value: {type: 'string'},
+      },
+      {
+        key: StringOps.IS,
+        i18nKey: '@astryx.powersearch.operator.is',
+        value: {type: 'string'},
+      },
+      {
+        key: StringOps.IS_NOT,
+        i18nKey: '@astryx.powersearch.operator.isNot',
         value: {type: 'string'},
       },
-      {key: StringOps.IS, label: 'is', value: {type: 'string'}},
-      {key: StringOps.IS_NOT, label: 'is not', value: {type: 'string'}},
     ],
   };
 }
@@ -156,32 +172,32 @@ function numberOperators(): {
     operators: [
       {
         key: NumberOps.EQUALS,
-        label: 'is',
+        i18nKey: '@astryx.powersearch.operator.equals',
         value: {type: 'float'},
       },
       {
         key: NumberOps.NOT_EQUALS,
-        label: 'is not',
+        i18nKey: '@astryx.powersearch.operator.notEquals',
         value: {type: 'float'},
       },
       {
         key: NumberOps.GREATER_THAN,
-        label: 'is greater than',
+        i18nKey: '@astryx.powersearch.operator.greaterThan',
         value: {type: 'float'},
       },
       {
         key: NumberOps.LESS_THAN,
-        label: 'is less than',
+        i18nKey: '@astryx.powersearch.operator.lessThan',
         value: {type: 'float'},
       },
       {
         key: NumberOps.GREATER_THAN_OR_EQUAL,
-        label: 'is greater than or equal to',
+        i18nKey: '@astryx.powersearch.operator.greaterThanOrEqual',
         value: {type: 'float'},
       },
       {
         key: NumberOps.LESS_THAN_OR_EQUAL,
-        label: 'is less than or equal to',
+        i18nKey: '@astryx.powersearch.operator.lessThanOrEqual',
         value: {type: 'float'},
       },
     ],
@@ -197,17 +213,17 @@ function dateOperators(): {
     operators: [
       {
         key: DateOps.BEFORE,
-        label: 'is before',
+        i18nKey: '@astryx.powersearch.operator.before',
         value: {type: 'date_absolute'},
       },
       {
         key: DateOps.AFTER,
-        label: 'is after',
+        i18nKey: '@astryx.powersearch.operator.after',
         value: {type: 'date_absolute'},
       },
       {
         key: DateOps.BETWEEN,
-        label: 'is between',
+        i18nKey: '@astryx.powersearch.operator.between',
         value: {type: 'date_range'},
       },
     ],
@@ -221,8 +237,16 @@ function booleanOperators(): {
   return {
     defaultOperator: BooleanOps.IS_TRUE,
     operators: [
-      {key: BooleanOps.IS_TRUE, label: 'is true', value: {type: 'empty'}},
-      {key: BooleanOps.IS_FALSE, label: 'is false', value: {type: 'empty'}},
+      {
+        key: BooleanOps.IS_TRUE,
+        i18nKey: '@astryx.powersearch.operator.isTrue',
+        value: {type: 'empty'},
+      },
+      {
+        key: BooleanOps.IS_FALSE,
+        i18nKey: '@astryx.powersearch.operator.isFalse',
+        value: {type: 'empty'},
+      },
     ],
   };
 }
@@ -234,16 +258,24 @@ function enumOperators(values: ReadonlyArray<EnumItem>): {
   return {
     defaultOperator: EnumOps.IS,
     operators: [
-      {key: EnumOps.IS, label: 'is', value: {type: 'enum', values}},
-      {key: EnumOps.IS_NOT, label: 'is not', value: {type: 'enum', values}},
+      {
+        key: EnumOps.IS,
+        i18nKey: '@astryx.powersearch.operator.is',
+        value: {type: 'enum', values},
+      },
+      {
+        key: EnumOps.IS_NOT,
+        i18nKey: '@astryx.powersearch.operator.isNot',
+        value: {type: 'enum', values},
+      },
       {
         key: EnumListOps.IS_ANY_OF,
-        label: 'is any of',
+        i18nKey: '@astryx.powersearch.operator.isAnyOf',
         value: {type: 'enum_list', values},
       },
       {
         key: EnumListOps.IS_NONE_OF,
-        label: 'is none of',
+        i18nKey: '@astryx.powersearch.operator.isNoneOf',
         value: {type: 'enum_list', values},
       },
     ],
@@ -259,12 +291,12 @@ function enumListOperators(values: ReadonlyArray<EnumItem>): {
     operators: [
       {
         key: EnumListOps.IS_ANY_OF,
-        label: 'is any of',
+        i18nKey: '@astryx.powersearch.operator.isAnyOf',
         value: {type: 'enum_list', values},
       },
       {
         key: EnumListOps.IS_NONE_OF,
-        label: 'is none of',
+        i18nKey: '@astryx.powersearch.operator.isNoneOf',
         value: {type: 'enum_list', values},
       },
     ],
@@ -280,12 +312,12 @@ function stringListOperators(): {
     operators: [
       {
         key: StringListOps.IS_ANY_OF,
-        label: 'is any of',
+        i18nKey: '@astryx.powersearch.operator.isAnyOf',
         value: {type: 'string_list'},
       },
       {
         key: StringListOps.IS_NONE_OF,
-        label: 'is none of',
+        i18nKey: '@astryx.powersearch.operator.isNoneOf',
         value: {type: 'string_list'},
       },
     ],

package/src/PowerSearch/usePowerSearchSource.ts

@@ -14,14 +14,22 @@
 
 import {useMemo} from 'react';
 import type {SearchSource} from '../Typeahead/types';
+import {useTranslator} from '../i18n';
+import {resolveOperatorLabel} from './resolveOperatorLabel';
 import type {InternalConfig} from './useInternalConfig';
 import type {PowerSearchItem, PowerSearchOperator, FilterValue} from './types';
 
 export function usePowerSearchSource(
   config: InternalConfig,
 ): SearchSource<PowerSearchItem> {
+  const t = useTranslator();
   return useMemo(() => {
     const allItems = buildFieldItems(config);
+    // Resolver stays inline — `t()` internally memoizes both catalog
+    // lookups and parsed IntlMessageFormat instances, so calling it
+    // per keystroke is already O(1).
+    const opLabel = (op: PowerSearchOperator): string =>
+      resolveOperatorLabel(op, t);
 
     return {
       search(query: string): PowerSearchItem[] {
@@ -68,14 +76,15 @@ export function usePowerSearchSource(
 
           // Check each field+operator combo against the query
           for (const op of field.operators) {
-            const combinedLabel = `${field.label} ${op.label}`.toLowerCase();
+            const combinedLabel =
+              `${field.label} ${opLabel(op)}`.toLowerCase();
             if (combinedLabel.includes(lower)) {
               const id = `${field.key}:${op.key}`;
               if (!seen.has(id)) {
                 seen.add(id);
                 results.push({
                   id,
-                  label: `${field.label} ${op.label}`,
+                  label: `${field.label} ${opLabel(op)}`,
                   auxiliaryData: {
                     fieldKey: field.key,
                     operatorKey: op.key,
@@ -100,7 +109,7 @@ export function usePowerSearchSource(
           // Try "<field> <operator> <value>" first (longer match wins)
           let hasExactOperatorMatch = false;
           for (const op of field.operators) {
-            const prefix = `${fieldLabel} ${op.label.toLowerCase()} `;
+            const prefix = `${fieldLabel} ${opLabel(op).toLowerCase()} `;
             if (lower.startsWith(prefix) && lower.length > prefix.length) {
               const rawValue = query.slice(prefix.length);
               const matches = resolveValueMatches(op, rawValue);
@@ -113,7 +122,7 @@ export function usePowerSearchSource(
                   seen.add(id);
                   results.push({
                     id,
-                    label: `${field.label} ${op.label} ${match.quoted ? `"${match.displayValue}"` : match.displayValue}`,
+                    label: `${field.label} ${opLabel(op)} ${match.quoted ? `"${match.displayValue}"` : match.displayValue}`,
                     auxiliaryData: {
                       fieldKey: field.key,
                       operatorKey: op.key,
@@ -136,7 +145,7 @@ export function usePowerSearchSource(
             // Check the remainder isn't the start of an operator name
             const remainder = lower.slice(fieldPrefix.length);
             const isOperatorPrefix = field.operators.some(op =>
-              op.label.toLowerCase().startsWith(remainder),
+              opLabel(op).toLowerCase().startsWith(remainder),
             );
             if (!isOperatorPrefix) {
               const rawValue = query.slice(fieldPrefix.length);
@@ -148,7 +157,7 @@ export function usePowerSearchSource(
                     seen.add(id);
                     results.push({
                       id,
-                      label: `${field.label} ${op.label} ${match.quoted ? `"${match.displayValue}"` : match.displayValue}`,
+                      label: `${field.label} ${opLabel(op)} ${match.quoted ? `"${match.displayValue}"` : match.displayValue}`,
                       auxiliaryData: {
                         fieldKey: field.key,
                         operatorKey: op.key,
@@ -171,7 +180,7 @@ export function usePowerSearchSource(
             f =>
               f.label.toLowerCase() === lower ||
               f.operators.some(
-                op => `${f.label} ${op.label}`.toLowerCase() === lower,
+                op => `${f.label} ${opLabel(op)}`.toLowerCase() === lower,
               ),
           );
         if (contentFieldKey && !hasExactMatch) {
@@ -197,7 +206,7 @@ export function usePowerSearchSource(
         return allItems;
       },
     };
-  }, [config]);
+  }, [config, t]);
 }
 
 interface ValueMatch {

package/src/RadioList/RadioList.doc.mjs

@@ -100,7 +100,7 @@ export const docs = {
     },
     {
       name: 'status',
-      type: 'InputStatus',
+      type: "{type: 'warning' | 'error' | 'success', message?: string}",
       description: 'Status indicator ({ type, message }).',
     },
     {

package/src/Resizable/ResizeHandle.tsx

@@ -33,6 +33,7 @@ import {
 import {mergeProps, mergeRefs} from '../utils';
 import type {ResizableProps} from './useResizable';
 import {themeProps} from '../utils/themeProps';
+import {useTranslator} from '../i18n';
 
 const KEYBOARD_STEP = 10;
 const KEYBOARD_LARGE_STEP = 50;
@@ -307,7 +308,7 @@ export function ResizeHandle({
   hasDivider = false,
   isAlwaysVisible = true,
   pillPlacement = 'auto',
-  label = 'Resize handle',
+  label: labelFromProps,
   resizable,
   children,
   xstyle,
@@ -315,6 +316,8 @@ export function ResizeHandle({
   ref,
   ...props
 }: ResizeHandleProps) {
+  const t = useTranslator();
+  const label = labelFromProps ?? t('@astryx.resizable.handle.label');
   const handleRef = useRef<HTMLDivElement>(null);
   // Removes the in-flight drag's window listeners (and resets body styles).
   // Held in a ref so unmount can tear down a drag that never got a pointerup.

package/src/Section/Section.doc.mjs

@@ -49,13 +49,13 @@ export const docs = {
     },
     {
       name: 'padding',
-      type: 'SpacingStep',
+      type: '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10',
       description: 'Internal padding using the spacing scale (0, 0.5, 1, 1.5, 2, 3, 4, 5, 6, 8, 10). Use padding={0} for edge-to-edge content.',
       default: '4',
     },
     {
       name: 'paddingBlock',
-      type: 'SpacingStep',
+      type: '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10',
       description: 'Block (vertical) padding override. Overrides only the block-axis padding while preserving inline padding from `padding` or the container theme default. Accepts the spacing scale (0, 0.5, 1, 1.5, 2, 3, 4, 5, 6, 8, 10).',
     },
     {
@@ -131,13 +131,13 @@ export const docsZh = {
     },
     {
       name: 'padding',
-      type: 'SpacingStep',
+      type: '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10',
       description: '使用间距比例的内部内边距（0, 0.5, 1, 1.5, 2, 3, 4, 5, 6, 8, 10）。使用 padding={0} 实现全宽内容。',
       default: '4',
     },
     {
       name: 'paddingBlock',
-      type: 'SpacingStep',
+      type: '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10',
       description: '块（垂直）方向内边距覆盖。仅覆盖块轴内边距，同时保留来自 padding 或容器主题默认值的行内内边距。使用间距比例（0, 0.5, 1, 1.5, 2, 3, 4, 5, 6, 8, 10）。',
     },
     {

package/src/SelectableCard/SelectableCard.doc.mjs

@@ -25,7 +25,7 @@ export const docs = {
     {name: 'onChange', type: '(isSelected: boolean) => void', description: 'Called when toggled.', required: true},
     {name: 'isDisabled', type: 'boolean', description: 'Disables the card.', default: 'false'},
     {name: 'children', type: 'ReactNode', description: 'Card content.'},
-    {name: 'padding', type: "SpacingStep", description: 'Inner padding.', default: '4'},
+    {name: 'padding', type: '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10', description: 'Inner padding.', default: '4'},
     {name: 'variant', type: "'default' | 'transparent' | 'muted' | 'blue' | 'cyan' | 'gray' | 'green' | 'orange' | 'pink' | 'purple' | 'red' | 'teal' | 'yellow'", description: 'Background color variant.', default: "'default'"},
     {name: 'width', type: 'SizeValue', description: 'Card width.'},
     {name: 'height', type: 'SizeValue', description: 'Card height.'},

package/src/Selector/Selector.doc.mjs

@@ -36,7 +36,8 @@ export const docs = {
     {
       name: 'options',
       type: 'SelectorOption[]',
-      description: 'Array of items: strings, objects with value/label/icon/disabled, dividers ({type: "divider"}), or sections ({type: "section", title, items}).',
+      description:
+        'Array of items: strings, objects with value/label/icon/disabled, dividers ({type: "divider"}), or sections ({type: "section", title, items}).',
       required: true,
     },
     {
@@ -59,7 +60,8 @@ export const docs = {
     {
       name: 'hasSearch',
       type: 'boolean',
-      description: 'Whether to show a search input for filtering options.',
+      description:
+        'Whether to show a search input for filtering options. As the user types, the match count (or "No results found") is announced to screen readers via a polite live region.',
       default: 'false',
     },
     {
@@ -135,7 +137,8 @@ export const docs = {
     {
       name: 'xstyle',
       type: 'StyleXStyles',
-      description: 'StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value: not an inline style object like style={{}}.',
+      description:
+        'StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value: not an inline style object like style={{}}.',
     },
   ],
   components: [{name: 'SelectorOption'}],

package/src/Selector/Selector.test.tsx

@@ -9,12 +9,23 @@
  * SYNC: When Selector.tsx API changes, update these tests.
  */
 
-import {describe, it, expect, vi, beforeEach} from 'vitest';
-import {render, screen, fireEvent, waitFor} from '@testing-library/react';
+import {describe, it, expect, vi, beforeEach, afterEach} from 'vitest';
+import {
+  render,
+  screen,
+  fireEvent,
+  waitFor,
+  within,
+} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {Selector} from './Selector';
 import {SelectorOption} from './SelectorOption';
 import {InputGroup, InputGroupText} from '../InputGroup';
+import {__resetLiveRegionsForTest} from '../hooks/useAnnounce';
+
+function politeRegion(): HTMLElement | null {
+  return document.querySelector('[data-astryx-live-region="polite"]');
+}
 
 // Mock showPopover and hidePopover methods since they're not implemented in jsdom
 beforeEach(() => {
@@ -42,6 +53,10 @@ beforeEach(() => {
   };
 });
 
+afterEach(() => {
+  __resetLiveRegionsForTest();
+});
+
 // Helper: jsdom popover content is in the DOM but may not be
 // "visible" in the accessibility tree. Use hidden: true to find it.
 const h = {hidden: true} as const;
@@ -536,7 +551,11 @@ describe('Selector', () => {
       await user.click(screen.getByRole('button', {name: 'Fruit'}));
       await user.type(screen.getByRole('combobox', h), 'xyz');
       expect(screen.queryAllByRole('option', h)).toHaveLength(0);
-      expect(screen.getByText('No results found')).toBeInTheDocument();
+      // Scope to the listbox: the polite live region also announces "No results
+      // found", so an unscoped query matches both the visible empty state and
+      // the a11y announcement.
+      const listbox = screen.getByRole('listbox', h);
+      expect(within(listbox).getByText('No results found')).toBeInTheDocument();
     });
 
     it('calls onChange when selecting a filtered option', async () => {
@@ -599,6 +618,82 @@ describe('Selector', () => {
         screen.getByPlaceholderText('Find a fruit...'),
       ).toBeInTheDocument();
     });
+
+    describe('result announcements', () => {
+      it('announces the match count politely while searching', async () => {
+        const user = userEvent.setup();
+        render(
+          <Selector
+            label="Fruit"
+            options={OPTIONS}
+            value="Apple"
+            onChange={() => {}}
+            hasSearch
+          />,
+        );
+        await user.click(screen.getByRole('button', {name: 'Fruit'}));
+        // "a" matches Apple and Banana.
+        await user.type(screen.getByRole('combobox', h), 'a');
+        await waitFor(() => {
+          expect(politeRegion()).toHaveTextContent('2 results');
+        });
+      });
+
+      it('announces the singular form when one option matches', async () => {
+        const user = userEvent.setup();
+        render(
+          <Selector
+            label="Fruit"
+            options={OPTIONS}
+            value="Apple"
+            onChange={() => {}}
+            hasSearch
+          />,
+        );
+        await user.click(screen.getByRole('button', {name: 'Fruit'}));
+        // "ban" matches only Banana. Anchored so it cannot pass on "1 results".
+        await user.type(screen.getByRole('combobox', h), 'ban');
+        await waitFor(() => {
+          expect(politeRegion()).toHaveTextContent(/^1 result$/);
+        });
+      });
+
+      it('announces "No results found" when nothing matches', async () => {
+        const user = userEvent.setup();
+        render(
+          <Selector
+            label="Fruit"
+            options={OPTIONS}
+            value="Apple"
+            onChange={() => {}}
+            hasSearch
+          />,
+        );
+        await user.click(screen.getByRole('button', {name: 'Fruit'}));
+        await user.type(screen.getByRole('combobox', h), 'xyz');
+        await waitFor(() => {
+          expect(politeRegion()).toHaveTextContent('No results found');
+        });
+      });
+
+      it('does not announce results until the user searches', async () => {
+        const user = userEvent.setup();
+        render(
+          <Selector
+            label="Fruit"
+            options={OPTIONS}
+            value="Apple"
+            onChange={() => {}}
+            hasSearch
+          />,
+        );
+        // Popover closed: nothing announced.
+        expect(politeRegion()?.textContent ?? '').toBe('');
+        // Open with an empty query: still nothing announced.
+        await user.click(screen.getByRole('button', {name: 'Fruit'}));
+        expect(politeRegion()?.textContent ?? '').toBe('');
+      });
+    });
   });
 
   describe('keyboard accessibility', () => {
@@ -869,7 +964,12 @@ describe('Selector', () => {
     it('submits the selected value under htmlName', () => {
       const {container} = render(
         <form>
-          <Selector label="Fruit" htmlName="fruit" options={OPTIONS} value="Banana" />
+          <Selector
+            label="Fruit"
+            htmlName="fruit"
+            options={OPTIONS}
+            value="Banana"
+          />
         </form>,
       );
       const data = new FormData(container.querySelector('form')!);
@@ -889,10 +989,18 @@ describe('Selector', () => {
     it('is excluded from form data when disabled', () => {
       const {container} = render(
         <form>
-          <Selector label="Fruit" htmlName="fruit" options={OPTIONS} value="Banana" isDisabled />
+          <Selector
+            label="Fruit"
+            htmlName="fruit"
+            options={OPTIONS}
+            value="Banana"
+            isDisabled
+          />
         </form>,
       );
-      expect([...new FormData(container.querySelector('form')!).keys()]).toEqual([]);
+      expect([
+        ...new FormData(container.querySelector('form')!).keys(),
+      ]).toEqual([]);
     });
   });
 });