@astryxdesign/core 0.7.7-canary.fc68123 → 0.7.7

package/src/PowerSearch/formatTokenValue.ts

@@ -1,215 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/**
- * @fileoverview The text a PowerSearch filter token shows for a value.
- *
- * @input `OperatorValue`, `FilterValue`, a width budget, and the locale.
- * @output `formatTokenValueText` — one string, or null for an empty value.
- * @position Shared by the token itself (`PowerSearch.tsx`) and the sheet
- * presentation's Filters rows and removal announcement
- * (`PowerSearchBottomSheet.tsx`), so every reading of a value on the field
- * uses the same words and the same zone handling.
- */
-
-import type {OperatorValue, FilterValue, EnumItem} from './types';
-import type {Locale, TranslatorFn} from '../i18n';
-import {truncateCharacters} from '../utils/characters';
-import {
-  formatDateAbsoluteCompact,
-  formatSharedNumber,
-} from './formatFilterValue';
-import {registerEnglishFallback} from '../i18n/englishFallback';
-import english from '../i18n/generated-english/PowerSearch/formatTokenValue.generated';
-
-registerEnglishFallback(english);
-
-type ListFormatFn = (items: ReadonlyArray<string>) => string;
-
-function truncateString(value: string, limit: number): string {
-  // Same semantics as before — strings within limit + 3 pass through, longer
-  // ones cut to limit + '...' — but counted in characters, not code units.
-  return truncateCharacters(value, limit + 3, '...');
-}
-
-function getEnumLabel(values: ReadonlyArray<EnumItem>, value: string): string {
-  return values.find(v => v.value === value)?.label ?? value;
-}
-
-// Intl's maximum fraction cap: no number the row formats is rounded.
-const MAX_FRACTION_DIGITS = 100;
-
-// Whether a locale writes a number with the token's own numerals: Latin
-// digits and a `.` decimal mark, so `String(value)` is already the locale's
-// reading. Probed once per locale through the shared number helper.
-const tokenNumeralLocales = new Map<string, boolean>();
-function usesTokenNumerals(locale: Locale): boolean {
-  let uses = tokenNumeralLocales.get(locale);
-  if (uses == null) {
-    uses =
-      formatSharedNumber(1234567.5, locale, {
-        useGrouping: false,
-        maximumFractionDigits: MAX_FRACTION_DIGITS,
-      }) === '1234567.5';
-    tokenNumeralLocales.set(locale, uses);
-  }
-  return uses;
-}
-
-// A number as the token reads it. Where the locale writes Latin digits and a
-// `.` decimal mark, use the token's own text, `String(value)`. Elsewhere, use
-// the locale's digits and decimal mark, with no grouping and no rounding: the
-// fraction cap is Intl's maximum, so `1e-21` keeps its digits.
-function formatNumberAsToken(value: number, locale: Locale): string {
-  return usesTokenNumerals(locale)
-    ? String(value)
-    : formatSharedNumber(value, locale, {
-        useGrouping: false,
-        maximumFractionDigits: MAX_FRACTION_DIGITS,
-      });
-}
-
-// The summaries, lists, and numbers the token writes as English literals, and
-// the locale-aware readings of the same: with a translator (the sheet
-// presentation's rows and announcements) the summaries resolve through the
-// catalog, lists through the provider locale's list format, and numbers
-// through its number format; without one they stay the token's own literals,
-// the released popover token's text. In English the two read identically.
-function itemsSummary(count: number, t: TranslatorFn | undefined): string {
-  return t
-    ? t('@astryx.powersearch.valueEditor.itemsCount', {count})
-    : // eslint-disable-next-line @astryx/no-hardcoded-i18n-string -- the popover token's released English text; translating it is a separate stable change
-      `${count} items`;
-}
-
-function formatListText(
-  labels: ReadonlyArray<string>,
-  maxLength: number,
-  t: TranslatorFn | undefined,
-  formatList: ListFormatFn | undefined,
-): string | null {
-  if (labels.length === 0) {
-    return null;
-  }
-  if (labels.length === 1) {
-    return truncateString(labels[0], maxLength);
-  }
-  const totalLength = labels.reduce((sum, s) => sum + s.length, 0);
-  if (totalLength > maxLength) {
-    return itemsSummary(labels.length, t);
-  }
-  return formatList ? formatList(labels) : labels.join(', ');
-}
-
-/**
- * The text a filter token shows for a value: the one place that decides how
- * a value reads on the field, so every other reading of the same value —
- * the sheet presentation's Filters rows and its removal announcement — can
- * use the same words and the same zone handling. `maxLength` is the token's
- * width budget; pass `Number.MAX_SAFE_INTEGER` for the untruncated text.
- * With `t`, the list, date-range and nested summaries resolve through the
- * catalog (`@astryx.powersearch.valueEditor.*`); without it they are the
- * token's own literals. With `formatList` (the provider's list formatter),
- * several labels join as a list in the locale; without it they join with
- * the token's literal ", ".
- */
-export function formatTokenValueText(
-  operatorValue: OperatorValue,
-  filterValue: FilterValue,
-  maxLength: number,
-  locale: Locale,
-  t?: TranslatorFn,
-  formatList?: ListFormatFn,
-): string | null {
-  switch (filterValue.type) {
-    case 'empty':
-      return null;
-
-    case 'string':
-      return truncateString(filterValue.value, maxLength);
-
-    case 'integer':
-    case 'float':
-      return t
-        ? formatNumberAsToken(filterValue.value, locale)
-        : String(filterValue.value);
-
-    case 'enum':
-      if (operatorValue.type === 'enum') {
-        return truncateString(
-          getEnumLabel(operatorValue.values, filterValue.value),
-          maxLength,
-        );
-      }
-      return truncateString(filterValue.value, maxLength);
-
-    case 'string_list':
-      return formatListText(filterValue.value, maxLength, t, formatList);
-
-    case 'enum_list': {
-      const items = filterValue.value;
-      if (items.length === 0) {
-        return null;
-      }
-      if (operatorValue.type === 'enum_list') {
-        return formatListText(
-          items.map(v => getEnumLabel(operatorValue.values, v)),
-          maxLength,
-          t,
-          formatList,
-        );
-      }
-      if (items.length === 1) {
-        return truncateString(items[0], maxLength);
-      }
-      return itemsSummary(items.length, t);
-    }
-
-    case 'entity_list':
-      return formatListText(
-        filterValue.value.map(e => e.label),
-        maxLength,
-        t,
-        formatList,
-      );
-
-    case 'time':
-      return filterValue.value;
-
-    case 'date_absolute':
-      return truncateString(
-        formatDateAbsoluteCompact(filterValue.unixSeconds, locale),
-        maxLength,
-      );
-
-    case 'date_relative':
-      return truncateString(filterValue.value, maxLength);
-
-    case 'date_range':
-      if (t) {
-        return t('@astryx.powersearch.valueEditor.dateRange');
-      }
-      // eslint-disable-next-line @astryx/no-hardcoded-i18n-string -- the popover token's released English text; translating it is a separate stable change
-      return 'date range';
-
-    case 'custom':
-      if (operatorValue.type === 'custom') {
-        return truncateString(
-          operatorValue.getString(filterValue.value),
-          maxLength,
-        );
-      }
-      return filterValue.value;
-
-    case 'nested': {
-      const count = filterValue.value.length;
-      if (t) {
-        return t('@astryx.powersearch.valueEditor.filtersCount', {count});
-      }
-      // eslint-disable-next-line @astryx/no-hardcoded-i18n-string -- the popover token's released English text; translating it is a separate stable change
-      return count === 1 ? '1 filter' : `${count} filters`;
-    }
-
-    default:
-      return null;
-  }
-}

package/src/PowerSearch/powerSearchSheetUtils.ts

@@ -1,224 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/**
- * @file powerSearchSheetUtils.ts
- * @input PowerSearch config/filter types and the field typeahead source
- * @output Pure helpers for the sheet presentation: which operators the
- *   sheet's own controls edit, field matching, filter identity tracking
- *   across controlled re-renders, the focus target after a removal, and the
- *   content search's suggestion source over the field typeahead
- * @position Helper module; consumed by PowerSearchBottomSheet.tsx and its
- *   tests
- */
-
-import type {SearchSource} from '../Typeahead/types';
-import type {InternalConfig} from './useInternalConfig';
-import type {
-  PowerSearchField,
-  PowerSearchFilter,
-  PowerSearchItem,
-  PowerSearchOperator,
-} from './types';
-
-// =============================================================================
-// Operators and fields
-// =============================================================================
-
-/**
- * Whether the value step edits an operator's value with a sheet-native
- * control (choice rows, or the popover's editor in its sheet presentation).
- * A `nested` value is the exception: it is edited by the popover's built-in
- * NestedEditor, rendered in the step's body,
- * so every operator opens an editable step and no field is left out.
- */
-export function isSupportedOperator(operator: PowerSearchOperator): boolean {
-  return operator.value.type !== 'nested';
-}
-
-export function fieldMatchesQuery(
-  field: PowerSearchField,
-  normalizedQuery: string,
-): boolean {
-  if (normalizedQuery === '') {
-    return true;
-  }
-  if (field.label.toLowerCase().includes(normalizedQuery)) {
-    return true;
-  }
-  return (
-    field.typeaheadAliases?.some(alias =>
-      alias.toLowerCase().includes(normalizedQuery),
-    ) ?? false
-  );
-}
-
-/** Synchronous suggestion source; the sheet renders results inline. */
-export interface SheetSuggestionSource {
-  search(query: string): PowerSearchItem[];
-  bootstrap(): PowerSearchItem[];
-}
-
-/**
- * The field typeahead source as the content search's rows: the popover
- * presentation's own suggestions, minus any whose field the config no longer
- * knows. That source resolves synchronously from the config; a promise (none
- * today) yields no rows rather than a stale list.
- */
-export function createSheetSuggestionSource(
-  config: InternalConfig,
-  source: SearchSource<PowerSearchItem>,
-): SheetSuggestionSource {
-  // Every suggestion whose field the config knows is offered: the value step
-  // edits every operator, `nested` included.
-  const isEditable = (item: PowerSearchItem): boolean => {
-    const aux = item.auxiliaryData;
-    return aux != null && config.getField(aux.fieldKey) != null;
-  };
-  const settle = (
-    results: PowerSearchItem[] | Promise<PowerSearchItem[]>,
-  ): PowerSearchItem[] =>
-    Array.isArray(results) ? results.filter(isEditable) : [];
-  return {
-    search: query => settle(source.search(query)),
-    bootstrap: () => settle(source.bootstrap()),
-  };
-}
-
-// =============================================================================
-// Filter identity across controlled updates
-// =============================================================================
-
-function stableSerialize(value: unknown): string {
-  if (Array.isArray(value)) {
-    return `[${value.map(stableSerialize).join(',')}]`;
-  }
-  if (value != null && typeof value === 'object') {
-    return `{${Object.entries(value)
-      .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0))
-      .map(([key, entry]) => `${JSON.stringify(key)}:${stableSerialize(entry)}`)
-      .join(',')}}`;
-  }
-  return JSON.stringify(value) ?? 'undefined';
-}
-
-/**
- * Stable identities for the Filters rows across controlled updates, so a row
- * keeps its element — and its focus — when the parent reorders the filters or
- * removes one above it. A filter object seen before keeps its
- * id; a new object takes the id of a filter from the previous update with the
- * same signature that no present object claims (a parent that clones its
- * values on every change); anything else mints a new id. Two equal filters
- * are told apart by order. Call `next` once per render with the current list.
- */
-export function createFilterIdentities(): {
-  next: (filters: ReadonlyArray<PowerSearchFilter>) => number[];
-} {
-  const byObject = new WeakMap<PowerSearchFilter, number>();
-  let previousBySignature = new Map<string, number[]>();
-  let nextId = 0;
-  return {
-    next(filters) {
-      const used = new Set<number>();
-      const ids: (number | null)[] = filters.map(filter => {
-        const known = byObject.get(filter);
-        if (known == null || used.has(known)) {
-          return null;
-        }
-        used.add(known);
-        return known;
-      });
-      const bySignature = new Map<string, number[]>();
-      filters.forEach((filter, index) => {
-        const signature = filterSignature(filter);
-        let id = ids[index];
-        if (id == null) {
-          id =
-            previousBySignature
-              .get(signature)
-              ?.find(candidate => !used.has(candidate)) ?? nextId++;
-          used.add(id);
-          byObject.set(filter, id);
-          ids[index] = id;
-        }
-        bySignature.set(signature, [...(bySignature.get(signature) ?? []), id]);
-      });
-      previousBySignature = bySignature;
-      return ids as number[];
-    },
-  };
-}
-
-/** Structural snapshot of a filter, for parents that clone their values. */
-export function filterSignature(filter: PowerSearchFilter): string {
-  return stableSerialize({
-    field: filter.field,
-    operator: filter.operator,
-    value: filter.value,
-    isReadOnly: filter.isReadOnly ?? false,
-  });
-}
-
-/**
- * Finds the filter a step was opened on after the controlled parent may have
- * reordered, cloned, or removed it: object identity first, then the original
- * slot when it still holds a structurally equal filter, then a unique
- * structural match anywhere. Returns null when the target is gone or
- * ambiguous, so an edit never lands on a different filter.
- */
-export function resolveFilterIdentityIndex(
-  filters: ReadonlyArray<PowerSearchFilter>,
-  sourceFilter: PowerSearchFilter,
-  sourceSignature: string,
-  preferredIndex: number,
-): number | null {
-  const identityIndex = filters.indexOf(sourceFilter);
-  if (identityIndex >= 0) {
-    return identityIndex;
-  }
-  if (
-    filters[preferredIndex] != null &&
-    filterSignature(filters[preferredIndex]) === sourceSignature
-  ) {
-    return preferredIndex;
-  }
-  const matchingIndices = filters.flatMap((filter, index) =>
-    filterSignature(filter) === sourceSignature ? [index] : [],
-  );
-  return matchingIndices.length === 1 ? matchingIndices[0] : null;
-}
-
-/**
- * After removing the filter at `removedIndex`, focus should land on the
- * nearest remaining row that is a button, preferring the one after it.
- * `isRowButton` is the Filters sheet's own rule for which rows are buttons:
- * the field interactive and the filter not read-only (a `nested` or stale
- * filter's row is a button too).
- */
-export function nearestEditableIndex(
-  nextFilters: ReadonlyArray<PowerSearchFilter>,
-  removedIndex: number,
-  isRowButton: (filter: PowerSearchFilter) => boolean = filter =>
-    !filter.isReadOnly,
-): number | undefined {
-  const editableIndices = nextFilters.flatMap((candidate, candidateIndex) =>
-    isRowButton(candidate) ? [candidateIndex] : [],
-  );
-  return editableIndices.reduce<number | undefined>((nearest, candidate) => {
-    if (nearest == null) {
-      return candidate;
-    }
-    const candidateDistance = Math.abs(candidate - removedIndex);
-    const nearestDistance = Math.abs(nearest - removedIndex);
-    if (candidateDistance < nearestDistance) {
-      return candidate;
-    }
-    if (
-      candidateDistance === nearestDistance &&
-      candidate >= removedIndex &&
-      nearest < removedIndex
-    ) {
-      return candidate;
-    }
-    return nearest;
-  }, undefined);
-}

package/src/animator/createAnimator.doc.mjs

@@ -1,153 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/** @type {import('@astryxdesign/cli/authoring').HookDoc} */
-export const docs = {
-  name: 'createAnimator',
-  displayName: 'createAnimator',
-  // A factory documented as a hook: listed with the utilities, beside its
-  // hook, not as a tile in the components gallery.
-  group: 'Utilities',
-  keywords: [
-    'animate',
-    'animation',
-    'animator',
-    'spring',
-    'decay',
-    'momentum',
-    'fling',
-    'motion',
-    'transform',
-    'opacity',
-    'vanilla',
-    'factory',
-  ],
-  params: [
-    {
-      name: 'element',
-      type: 'HTMLElement',
-      description:
-        'The element to animate. The animator writes its `translate`, `scale`, `rotate` and `opacity`, and while it moves an inline `will-change` for them, merged with any it already has and restored 500 ms after its last motion; nothing else, so lay it out and style it as usual. Use one animator per element: two on one element overwrite each other.',
-      required: true,
-    },
-  ],
-  returns: [
-    {
-      name: 'animate',
-      type: '(target: {x?, y?, scale?, rotate?, opacity?}, options?: {velocity?}) => Promise<void>',
-      description:
-        "Springs the given channels to `target` from wherever they are on screen, on the state-change motion Astryx's components use, and resolves when they arrive (or as soon as a later call takes them over). `x` and `y` are px, `scale` is 1 at the element's size, `rotate` is degrees and `opacity` runs from 0 to 1. Pass `velocity` (units per second, such as a drag's release velocity) to start with it; without it a channel keeps the velocity it has on screen, so interrupting a motion never jumps.",
-    },
-    {
-      name: 'decay',
-      type: '(velocity: {x?, y?, scale?, rotate?, opacity?}) => Promise<void>',
-      description:
-        "Coasts the given channels from a release velocity in their units per second, slowing as a scroll view's momentum does, and resolves when they stop (or as soon as a later call takes any of them over); opacity stops at 0 or 1. The distance follows from the velocity: use it to fling something away, then remove or reset it.",
-    },
-    {
-      name: 'set',
-      type: '(values: {x?, y?, scale?, rotate?, opacity?}) => void',
-      description:
-        'Puts the given channels at these values at once, ending their motion: follow a finger with it, frame by frame.',
-    },
-    {
-      name: 'get',
-      type: '() => {x, y, scale, rotate, opacity}',
-      description: "Every channel's value on screen now.",
-    },
-    {
-      name: 'getVelocity',
-      type: '() => {x, y, scale, rotate, opacity}',
-      description:
-        "Every channel's velocity on screen now, in units per second.",
-    },
-    {
-      name: 'stop',
-      type: '() => void',
-      description: 'Halts every channel where it is on screen.',
-    },
-    {
-      name: 'destroy',
-      type: '() => void',
-      description:
-        'Stops every motion and lets the element go; the element keeps the values it shows. Call it when you remove the element or no longer animate it.',
-    },
-  ],
-  usage: {
-    description:
-      "Animates one element with the motion Astryx's own components use, without React. `animate` springs an element to new values on the state-change motion, `decay` flings it with the momentum of a released scroll view, and `set` moves it directly, so a card can follow a finger, snap back and be thrown away. Use the `useAnimator` hook in React. To animate an area's layout as its items change, use `useAnimatedLayout`; for what a component already animates, such as a sheet's detents or a carousel's snapping, use the component's own props.",
-    bestPractices: [
-      {
-        guidance: true,
-        description:
-          'Start every `animate` that follows a drag with the release velocity, so the element carries on as it was thrown.',
-      },
-      {
-        guidance: true,
-        description:
-          'Reach every state an animation shows without the animation too: a key, a button or a menu item that calls the same code.',
-      },
-      {
-        guidance: true,
-        description:
-          '`await` the promise before removing an element you animate out, and call `destroy` once it is gone.',
-      },
-      {
-        guidance: false,
-        description:
-          'Read the element\u2019s position from layout while it moves: `get` gives the value on screen, wherever the motion runs.',
-      },
-    ],
-    accessibility: [
-      {
-        name: 'Keyboard and assistive technology',
-        category: 'Keyboard',
-        description:
-          'An animator moves an element; it adds no way to act. Give every action an animation stands for a control a keyboard and a screen reader can reach, such as a button that discards a card, and have it call `animate`, which Reduce Motion turns into a fade in place. Keep `decay` for a throw the person made: Reduce Motion keeps the momentum of a coast, as it continues that throw. Keep focus on an element that stays on screen: move it before you fling its element away.',
-      },
-      {
-        name: 'Reduce Motion',
-        category: 'Content',
-        criterion: '2.3.3 Animation from Interactions',
-        description:
-          'When the person asks for reduced motion, every call is planned for them. On a touch screen a move or a scale becomes a short opacity cross-fade: the element fades out where it was and fades back in where it lands. With a mouse it lands at once. A decay of `x` and `y` keeps its momentum, as it continues the throw the person made; a decay of `scale`, `rotate` or `opacity` is planned like a move. No option turns this off.',
-      },
-    ],
-  },
-  relatedHooks: ['useAnimator', 'useAnimatedLayout'],
-  importPath: '@astryxdesign/core',
-  category: 'interaction',
-};
-
-/** @type {import('@astryxdesign/cli/authoring').HookTranslationDoc} */
-export const docsDense = {
-  description:
-    "Animates one element (x, y, scale, rotate, opacity) with Astryx's motion, without React.",
-  paramDescriptions: {
-    element: 'The element to animate; one animator per element.',
-  },
-  returnDescriptions: {
-    animate:
-      '(target, {velocity?}) => Promise<void>; springs on the state-change motion.',
-    decay:
-      '({x?, y?, scale?, rotate?, opacity?}) => Promise<void>; coasts from a release velocity.',
-    set: '(values) => void; jumps, ending motion.',
-    get: '() => every value on screen.',
-    getVelocity: '() => every velocity on screen.',
-    stop: '() => void; halts where it is.',
-    destroy: '() => void; lets the element go.',
-  },
-  usage: {
-    description:
-      'Spring with animate, fling with decay, follow a finger with set. Reduce Motion: a cross-fade on touch, at once with a mouse; decay keeps its momentum.',
-    bestPractices: [
-      {
-        guidance: true,
-        description: 'Pass the release velocity to animate after a drag.',
-      },
-      {
-        guidance: false,
-        description: 'Read layout for the position mid-motion; use get.',
-      },
-    ],
-  },
-};