@astryxdesign/core 0.1.5 → 0.1.6-canary.02f2602

package/src/PowerSearch/formatFilterValue.test.ts

@@ -0,0 +1,282 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, expect, it} from 'vitest';
+import {formatFilterValue} from './formatFilterValue';
+import type {TranslatorFn} from '../i18n';
+import type {OperatorValue, FilterValue} from './types';
+
+// Minimal stand-in for the real translator: resolves just the count/range keys
+// formatFilterValue uses, with the same singular/plural forms as en.json so the
+// overflow-summary assertions ("3 items", "2 entities", "1 filter") hold.
+const t: TranslatorFn = (key, values) => {
+  const count = Number(values?.count ?? 0);
+  switch (key) {
+    case '@astryx.powersearch.valueEditor.itemsCount':
+      return `${count} ${count === 1 ? 'item' : 'items'}`;
+    case '@astryx.powersearch.valueEditor.entitiesCount':
+      return `${count} ${count === 1 ? 'entity' : 'entities'}`;
+    case '@astryx.powersearch.valueEditor.filtersCount':
+      return `${count} ${count === 1 ? 'filter' : 'filters'}`;
+    case '@astryx.powersearch.valueEditor.dateRange':
+      return 'date range';
+    default:
+      return key;
+  }
+};
+
+// _config is unused by formatFilterValue; a stub keeps the call type-clean.
+const fmt = (
+  operator: OperatorValue,
+  value: FilterValue,
+  maxLength = 20,
+  timezoneID?: string,
+): string =>
+  formatFilterValue({} as never, operator, value, maxLength, t, timezoneID);
+
+const ELLIPSIS = '…';
+
+describe('formatFilterValue', () => {
+  it('returns an empty string for an empty value', () => {
+    expect(fmt({type: 'empty'}, {type: 'empty'})).toBe('');
+  });
+
+  describe('string', () => {
+    it('returns the string unchanged when within maxLength', () => {
+      expect(fmt({type: 'string'}, {type: 'string', value: 'hello'})).toBe(
+        'hello',
+      );
+    });
+
+    it('truncates with an ellipsis when longer than maxLength', () => {
+      const out = fmt(
+        {type: 'string'},
+        {type: 'string', value: 'abcdefghij'},
+        5,
+      );
+      expect(out).toBe('abcd' + ELLIPSIS);
+      expect(out.length).toBe(5);
+    });
+
+    it('keeps a string exactly at the boundary intact', () => {
+      expect(fmt({type: 'string'}, {type: 'string', value: 'abcde'}, 5)).toBe(
+        'abcde',
+      );
+    });
+  });
+
+  describe('integer / float', () => {
+    it('formats an integer with locale grouping', () => {
+      const expected = new Intl.NumberFormat().format(1234567);
+      expect(
+        fmt({type: 'integer'}, {type: 'integer', value: 1234567}, 40),
+      ).toBe(expected);
+    });
+
+    it('appends integer units only when the operator is an integer', () => {
+      expect(
+        fmt({type: 'integer', units: 'ms'}, {type: 'integer', value: 42}),
+      ).toBe('42 ms');
+      // mismatched operator type → no units
+      expect(fmt({type: 'string'}, {type: 'integer', value: 42})).toBe('42');
+    });
+
+    it('appends float units only when the operator is a float', () => {
+      expect(
+        fmt({type: 'float', units: 'kg'}, {type: 'float', value: 3.5}),
+      ).toBe('3.5 kg');
+      expect(fmt({type: 'string'}, {type: 'float', value: 3.5})).toBe('3.5');
+    });
+  });
+
+  describe('enum', () => {
+    const enumOp: OperatorValue = {
+      type: 'enum',
+      values: [
+        {value: 'us', label: 'United States'},
+        {value: 'ca', label: 'Canada'},
+      ],
+    };
+
+    it('maps the stored value to its label', () => {
+      expect(fmt(enumOp, {type: 'enum', value: 'ca'}, 40)).toBe('Canada');
+    });
+
+    it('falls back to the raw value when no label matches', () => {
+      expect(fmt(enumOp, {type: 'enum', value: 'mx'}, 40)).toBe('mx');
+    });
+
+    it('uses the raw value when the operator is not an enum', () => {
+      expect(fmt({type: 'string'}, {type: 'enum', value: 'ca'}, 40)).toBe('ca');
+    });
+
+    it('truncates a long enum label', () => {
+      expect(fmt(enumOp, {type: 'enum', value: 'us'}, 5)).toBe(
+        'Unit' + ELLIPSIS,
+      );
+    });
+  });
+
+  describe('string_list', () => {
+    const op: OperatorValue = {type: 'string_list'};
+    it('returns an empty string for no items', () => {
+      expect(fmt(op, {type: 'string_list', value: []})).toBe('');
+    });
+    it('returns the single item, truncated', () => {
+      expect(fmt(op, {type: 'string_list', value: ['solo']})).toBe('solo');
+    });
+    it('joins multiple items when they fit', () => {
+      expect(fmt(op, {type: 'string_list', value: ['a', 'b', 'c']})).toBe(
+        'a, b, c',
+      );
+    });
+    it('summarizes as a count when the join exceeds maxLength', () => {
+      expect(
+        fmt(op, {type: 'string_list', value: ['alpha', 'bravo', 'charlie']}, 8),
+      ).toBe('3 items');
+    });
+  });
+
+  describe('enum_list', () => {
+    const enumOp: OperatorValue = {
+      type: 'enum_list',
+      values: [
+        {value: 'r', label: 'Red'},
+        {value: 'g', label: 'Green'},
+      ],
+    };
+    it('returns an empty string for no items', () => {
+      expect(fmt(enumOp, {type: 'enum_list', value: []})).toBe('');
+    });
+    it('maps a single value to its label', () => {
+      expect(fmt(enumOp, {type: 'enum_list', value: ['g']}, 40)).toBe('Green');
+    });
+    it('joins mapped labels when they fit', () => {
+      expect(fmt(enumOp, {type: 'enum_list', value: ['r', 'g']}, 40)).toBe(
+        'Red, Green',
+      );
+    });
+    it('summarizes labels as a count when too long', () => {
+      expect(fmt(enumOp, {type: 'enum_list', value: ['r', 'g']}, 5)).toBe(
+        '2 items',
+      );
+    });
+    it('uses raw values with a non-enum operator', () => {
+      expect(
+        fmt({type: 'string'}, {type: 'enum_list', value: ['x', 'y']}, 40),
+      ).toBe('2 items');
+      expect(
+        fmt({type: 'string'}, {type: 'enum_list', value: ['solo']}, 40),
+      ).toBe('solo');
+    });
+  });
+
+  describe('entity_list', () => {
+    const op: OperatorValue = {type: 'entity_list'};
+    it('returns an empty string for no entities', () => {
+      expect(fmt(op, {type: 'entity_list', value: []})).toBe('');
+    });
+    it('returns a single entity label', () => {
+      expect(
+        fmt(op, {type: 'entity_list', value: [{id: '1', label: 'Ada'}]}),
+      ).toBe('Ada');
+    });
+    it('joins entity labels when they fit', () => {
+      expect(
+        fmt(op, {
+          type: 'entity_list',
+          value: [
+            {id: '1', label: 'Ada'},
+            {id: '2', label: 'Bob'},
+          ],
+        }),
+      ).toBe('Ada, Bob');
+    });
+    it('summarizes as an entity count when too long', () => {
+      expect(
+        fmt(
+          op,
+          {
+            type: 'entity_list',
+            value: [
+              {id: '1', label: 'Alexander'},
+              {id: '2', label: 'Bartholomew'},
+            ],
+          },
+          8,
+        ),
+      ).toBe('2 entities');
+    });
+  });
+
+  describe('dates and time', () => {
+    it('returns a time value verbatim', () => {
+      expect(fmt({type: 'time'}, {type: 'time', value: '14:30'})).toBe('14:30');
+    });
+    it('returns a relative date value verbatim', () => {
+      expect(
+        fmt({type: 'date_relative'}, {type: 'date_relative', value: '7d'}),
+      ).toBe('7d');
+    });
+    it('renders a fixed placeholder for a date range', () => {
+      expect(
+        fmt(
+          {type: 'date_range'},
+          {
+            type: 'date_range',
+            value: {start: {type: 'NOW'}, end: {type: 'NOW'}},
+          },
+        ),
+      ).toBe('date range');
+    });
+    it('formats an absolute date and truncates to maxLength', () => {
+      const full = fmt(
+        {type: 'date_absolute'},
+        {type: 'date_absolute', unixSeconds: 0},
+        60,
+        'UTC',
+      );
+      expect(full).toContain('1970');
+      const short = fmt(
+        {type: 'date_absolute'},
+        {type: 'date_absolute', unixSeconds: 0},
+        6,
+        'UTC',
+      );
+      expect(short.length).toBe(6);
+      expect(short.endsWith(ELLIPSIS)).toBe(true);
+    });
+  });
+
+  describe('custom', () => {
+    it('stringifies via the operator getString and truncates', () => {
+      const op: OperatorValue = {
+        type: 'custom',
+        Editor: (() => null) as never,
+        getString: v => `custom:${v}`,
+      };
+      expect(fmt(op, {type: 'custom', value: 'x'})).toBe('custom:x');
+    });
+    it('returns the raw value when the operator is not custom', () => {
+      expect(fmt({type: 'string'}, {type: 'custom', value: 'raw'})).toBe('raw');
+    });
+  });
+
+  describe('nested', () => {
+    it('uses the singular form for a single nested filter', () => {
+      expect(
+        fmt({type: 'nested'}, {type: 'nested', value: [{} as never]}),
+      ).toBe('1 filter');
+    });
+    it('uses the plural form for multiple nested filters', () => {
+      expect(
+        fmt(
+          {type: 'nested'},
+          {
+            type: 'nested',
+            value: [{} as never, {} as never, {} as never],
+          },
+        ),
+      ).toBe('3 filters');
+    });
+  });
+});

package/src/PowerSearch/formatFilterValue.ts

@@ -12,6 +12,7 @@
 
 import type {OperatorValue, FilterValue, EnumItem} from './types';
 import type {InternalConfig} from './useInternalConfig';
+import type {TranslatorFn} from '../i18n';
 
 function truncate(str: string, maxLength: number): string {
   if (str.length <= maxLength) {
@@ -50,8 +51,11 @@ function formatRelativeDate(value: string): string {
   return value;
 }
 
-function formatDateRange(_value: {start: unknown; end: unknown}): string {
-  return 'date range';
+function formatDateRange(
+  _value: {start: unknown; end: unknown},
+  t: TranslatorFn,
+): string {
+  return t('@astryx.powersearch.valueEditor.dateRange');
 }
 
 export function formatFilterValue(
@@ -59,6 +63,7 @@ export function formatFilterValue(
   operatorValue: OperatorValue,
   filterValue: FilterValue,
   maxLength: number,
+  t: TranslatorFn,
   timezoneID?: string,
 ): string {
   switch (filterValue.type) {
@@ -101,7 +106,9 @@ export function formatFilterValue(
       if (joined.length <= maxLength) {
         return joined;
       }
-      return `${items.length} items`;
+      return t('@astryx.powersearch.valueEditor.itemsCount', {
+        count: items.length,
+      });
     }
 
     case 'enum_list': {
@@ -118,12 +125,16 @@ export function formatFilterValue(
         if (joined.length <= maxLength) {
           return joined;
         }
-        return `${labels.length} items`;
+        return t('@astryx.powersearch.valueEditor.itemsCount', {
+          count: labels.length,
+        });
       }
       if (items.length === 1) {
         return truncate(items[0], maxLength);
       }
-      return `${items.length} items`;
+      return t('@astryx.powersearch.valueEditor.itemsCount', {
+        count: items.length,
+      });
     }
 
     case 'entity_list': {
@@ -138,7 +149,9 @@ export function formatFilterValue(
       if (joined.length <= maxLength) {
         return joined;
       }
-      return `${entities.length} entities`;
+      return t('@astryx.powersearch.valueEditor.entitiesCount', {
+        count: entities.length,
+      });
     }
 
     case 'time':
@@ -154,7 +167,7 @@ export function formatFilterValue(
       return formatRelativeDate(filterValue.value);
 
     case 'date_range':
-      return formatDateRange(filterValue.value);
+      return formatDateRange(filterValue.value, t);
 
     case 'custom':
       if (operatorValue.type === 'custom') {
@@ -164,7 +177,7 @@ export function formatFilterValue(
 
     case 'nested': {
       const count = filterValue.value.length;
-      return count === 1 ? '1 filter' : `${count} filters`;
+      return t('@astryx.powersearch.valueEditor.filtersCount', {count});
     }
 
     default:

package/src/PowerSearch/index.ts

@@ -17,6 +17,8 @@ export type {PowerSearchProps, PowerSearchSize} from './PowerSearch';
 export {PowerSearchToken} from './PowerSearchToken';
 export {PowerSearchFilterEditor} from './PowerSearchFilterEditor';
 
+export {resolveOperatorLabel} from './resolveOperatorLabel';
+
 export {
   createPowerSearchConfig,
   usePowerSearchConfig,
@@ -28,6 +30,9 @@ export type {
   PowerSearchConfig,
   PowerSearchField,
   PowerSearchOperator,
+  PowerSearchOperatorBase,
+  PowerSearchOperatorWithLabel,
+  PowerSearchOperatorWithI18nKey,
 
   // Operator value types
   OperatorValue,

package/src/PowerSearch/resolveOperatorLabel.ts

@@ -0,0 +1,34 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file resolveOperatorLabel.ts
+ * @input PowerSearchOperator + translator function
+ * @output Display string for the operator label
+ * @position Shared label-resolution helper used at every render site that
+ *   reads an operator's display text (PowerSearch.tsx, PowerSearchToken.tsx,
+ *   PowerSearchEditPopover.tsx, usePowerSearchSource.ts).
+ *
+ * A PowerSearchOperator is a discriminated union of two variants:
+ *   - `{key, value, label}`     — consumer-supplied raw text (used verbatim)
+ *   - `{key, value, i18nKey}`   — catalog-driven text (looked up via t())
+ *
+ * Astryx's shipped default operators use the i18nKey variant; consumers
+ * writing custom operators typically use the label variant.
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/PowerSearch/types.ts (PowerSearchOperator type)
+ * - /packages/core/src/PowerSearch/index.ts (re-export)
+ */
+
+import type {TranslatorFn} from '../i18n';
+import type {PowerSearchOperator} from './types';
+
+export function resolveOperatorLabel(
+  operator: PowerSearchOperator,
+  t: TranslatorFn,
+): string {
+  if ('label' in operator && operator.label !== undefined) {
+    return operator.label;
+  }
+  return t(operator.i18nKey);
+}

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'},
       },
     ],