@astryxdesign/core 0.1.6-canary.1b61ba6 → 0.1.6-canary.1d64659

package/src/Chat/useChatStreamScroll.test.tsx

@@ -1,168 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-import {describe, it, expect, vi, beforeEach, afterEach} from 'vitest';
-import {act, render} from '@testing-library/react';
-import {useRef} from 'react';
-import {
-  useChatStreamScroll,
-  type UseChatStreamScrollOptions,
-  type UseChatStreamScrollReturn,
-} from './useChatStreamScroll';
-
-// ---------------------------------------------------------------------------
-// Test infrastructure
-//
-// jsdom has no layout engine, so these tests cover only the SYNCHRONOUS
-// scroll paths (instant positioning, lock state, rAF scheduling decisions).
-// The spring physics itself (frame-by-frame integration, scrollend re-lock,
-// user-scroll detection) is layout/browser-dependent and is verified
-// manually via Storybook — mocking it here would only test the mock.
-// ---------------------------------------------------------------------------
-
-let rafQueue: FrameRequestCallback[] = [];
-
-function flushRaf() {
-  // One flush = one frame: callbacks scheduled during a flush run next flush.
-  const frame = rafQueue;
-  rafQueue = [];
-  act(() => {
-    for (const cb of frame) {
-      cb(performance.now());
-    }
-  });
-}
-
-beforeEach(() => {
-  rafQueue = [];
-  vi.stubGlobal('requestAnimationFrame', (cb: FrameRequestCallback) => {
-    rafQueue.push(cb);
-    return rafQueue.length;
-  });
-  vi.stubGlobal('cancelAnimationFrame', () => {});
-});
-
-afterEach(() => {
-  vi.unstubAllGlobals();
-});
-
-function setGeometry(
-  el: HTMLElement,
-  {scrollHeight, clientHeight}: {scrollHeight: number; clientHeight: number},
-) {
-  Object.defineProperty(el, 'scrollHeight', {
-    value: scrollHeight,
-    configurable: true,
-  });
-  Object.defineProperty(el, 'clientHeight', {
-    value: clientHeight,
-    configurable: true,
-  });
-  Object.defineProperty(el, 'offsetHeight', {
-    value: clientHeight,
-    configurable: true,
-  });
-}
-
-function Harness({
-  options,
-  api,
-}: {
-  options?: Partial<UseChatStreamScrollOptions>;
-  api: {current: UseChatStreamScrollReturn | null};
-}) {
-  const scrollRef = useRef<HTMLDivElement>(null);
-  api.current = useChatStreamScroll({scrollRef, ...options});
-  return <div ref={scrollRef} data-testid="scroller" />;
-}
-
-function renderHook(options?: Partial<UseChatStreamScrollOptions>) {
-  const api: {current: UseChatStreamScrollReturn | null} = {current: null};
-  const utils = render(<Harness options={options} api={api} />);
-  const el = utils.getByTestId('scroller');
-  return {api, el, ...utils};
-}
-
-describe('useChatStreamScroll — initial positioning', () => {
-  it('default: jumps to the bottom on mount when content is scrollable', () => {
-    const {el} = renderHook();
-    setGeometry(el, {scrollHeight: 1000, clientHeight: 400});
-    flushRaf();
-    expect(el.scrollTop).toBe(600);
-  });
-
-  it('positions the first async fill in one synchronous step', () => {
-    const {api, el} = renderHook();
-    // Mount while loading — nothing scrollable yet.
-    setGeometry(el, {scrollHeight: 400, clientHeight: 400});
-    flushRaf();
-    expect(el.scrollTop).toBe(0);
-
-    // Async content lands; the layout's ResizeObserver calls scrollIfLocked.
-    setGeometry(el, {scrollHeight: 1200, clientHeight: 400});
-    act(() => api.current!.scrollIfLocked());
-    // Positioned synchronously — no animation frames needed.
-    expect(el.scrollTop).toBe(800);
-
-    // Subsequent growth (streaming) goes back to the spring: nothing moves
-    // until animation frames run.
-    setGeometry(el, {scrollHeight: 1600, clientHeight: 400});
-    act(() => api.current!.scrollIfLocked());
-    expect(el.scrollTop).toBe(800);
-  });
-
-  it('consumes the pending first fill via the mount jump too', () => {
-    const {api, el} = renderHook();
-    // Content already present at mount.
-    setGeometry(el, {scrollHeight: 1000, clientHeight: 400});
-    flushRaf();
-    expect(el.scrollTop).toBe(600);
-
-    // Growth after the mount jump is streaming — spring path, not instant.
-    setGeometry(el, {scrollHeight: 1400, clientHeight: 400});
-    act(() => api.current!.scrollIfLocked());
-    expect(el.scrollTop).toBe(600);
-  });
-
-  it('default: starts locked', () => {
-    const {api} = renderHook();
-    expect(api.current!.isLocked).toBe(true);
-  });
-});
-
-describe("useChatStreamScroll — scrollToBottom({behavior: 'instant'})", () => {
-  it('jumps synchronously without scheduling animation frames', () => {
-    const {api, el} = renderHook();
-    setGeometry(el, {scrollHeight: 1000, clientHeight: 400});
-    flushRaf(); // consume the mount jump
-    el.scrollTop = 100; // user scrolled up
-
-    rafQueue = [];
-    act(() => api.current!.scrollToBottom({behavior: 'instant'}));
-    expect(el.scrollTop).toBe(600);
-    expect(rafQueue).toHaveLength(0);
-  });
-
-  it('re-locks after an instant jump', () => {
-    const {api, el} = renderHook();
-    setGeometry(el, {scrollHeight: 1000, clientHeight: 400});
-    flushRaf();
-    act(() => api.current!.unlock());
-    expect(api.current!.isLocked).toBe(false);
-
-    act(() => api.current!.scrollToBottom({behavior: 'instant'}));
-    expect(api.current!.isLocked).toBe(true);
-    expect(el.scrollTop).toBe(600);
-  });
-
-  it('default scrollToBottom animates instead of jumping', () => {
-    const {api, el} = renderHook();
-    setGeometry(el, {scrollHeight: 1000, clientHeight: 400});
-    flushRaf();
-    el.scrollTop = 100;
-
-    act(() => api.current!.scrollToBottom());
-    // Spring path: position is untouched until animation frames run.
-    expect(el.scrollTop).toBe(100);
-    expect(rafQueue.length).toBeGreaterThan(0);
-  });
-});

package/src/PowerSearch/formatFilterValue.test.ts

@@ -1,282 +0,0 @@
-// 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/resolveOperatorLabel.ts

@@ -1,34 +0,0 @@
-// 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/authoring/doc.ts

@@ -1,166 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/**
- * @file doc.ts
- * @input A component/function/generic doc object (without the `type` tag).
- * @output Type-preserving `createComponentDoc`/`createFunctionDoc`/`createDoc`
- *   helpers plus the doc-authoring TypeScript surface.
- * @position Integration-author authoring surface. See `./index.ts` for why
- *   these authoring factories live in `@astryxdesign/core`.
- *
- * A doc describes a documentable unit of the design system so the CLI and docs
- * surfaces can list, search, and render it. There are three kinds, each a tiny
- * runtime identity helper that stamps a `type` discriminant:
- *
- *   - `createComponentDoc` -> `type: 'component'` — a component (or a family).
- *   - `createFunctionDoc`  -> `type: 'function'`  — any function, including
- *      hooks: an "inputs + outputs" surface (`params` + `returns`).
- *   - `createDoc`          -> `type: 'generic'`   — reference/topic docs.
- *
- * These factories do NOT validate. Validation happens at the CLI load boundary,
- * where doc discovery runs the loaded value through a schema that accepts BOTH
- * the stamped formats and the legacy loose `export const docs = {...}` shape.
- */
-
-/**
- * Fields shared by every doc kind (component + function + generic).
- *
- * `group` vs `parent` are distinct:
- *   - `group` is a FLAT sidebar bucket label; many docs can share it and it is
- *     NOT an inheritance key.
- *   - `parent` is a DIRECTED inheritance/composition pointer — a doc naming the
- *     doc it belongs to (e.g. a sub-component naming its parent component). The
- *     legacy `subComponentOf` field is a synonym.
- *
- * `relatedDocs` is a single flat curated cross-reference list; it replaces the
- * legacy split `relatedComponents` + `relatedHooks`.
- */
-export interface AstryxBaseDocInput {
-  /** Name of the documented unit, without any prefix, PascalCase. Required. */
-  name: string;
-  /** Human-readable display name for gallery/sidebar. */
-  displayName?: string;
-  /** Short description. */
-  description?: string;
-  /** Usage documentation (description, best practices, anatomy, slotElements). */
-  usage?: unknown;
-  /** Flat sidebar grouping label (not an inheritance key). */
-  group?: string;
-  /** Overview-page functional category. */
-  category?: string;
-  /** CLI fuzzy-search keywords. */
-  keywords?: string[];
-  /** Directed inheritance/composition pointer to the doc this belongs to. */
-  parent?: string;
-  /** Flat curated cross-reference list of related doc names. */
-  relatedDocs?: string[];
-  /** Hide the whole doc from human-facing UI (stays importable/discoverable). */
-  hidden?: boolean;
-  /** Exclude from the categorized overview page (kept in sidebar/CLI). */
-  isHiddenFromOverview?: boolean;
-  /** Any additional fields the rich doc surface carries. */
-  [key: string]: unknown;
-}
-
-/** A single documented prop (mirrors `PropDoc` from core docs-types). */
-export interface AstryxPropInput {
-  name: string;
-  type: string;
-  description: string;
-  default?: string;
-  required?: boolean;
-  [key: string]: unknown;
-}
-
-/** A single documented param (mirrors `HookParamDoc`). */
-export interface AstryxParamInput {
-  name: string;
-  type: string;
-  description: string;
-  default?: string;
-  required?: boolean;
-  [key: string]: unknown;
-}
-
-/** A single documented return field (mirrors `HookReturnDoc`). */
-export interface AstryxReturnInput {
-  name: string;
-  type: string;
-  description: string;
-  [key: string]: unknown;
-}
-
-/**
- * Input accepted by {@link createComponentDoc}. A component (or a family). The
- * `type` discriminant is injected by the factory. `anatomy`/`slotElements` live
- * inside `usage`; `importPath` is DERIVED (never authored).
- */
-export interface AstryxComponentDocInput extends AstryxBaseDocInput {
-  /** All public props for the component. */
-  props: AstryxPropInput[];
-  /** Theming/selector-surface metadata. */
-  theming?: unknown;
-  /** Interactive-preview playground configuration. */
-  playground?: unknown;
-  /** Short code examples rendered after the props table. */
-  examples?: unknown[];
-}
-
-/**
- * Input accepted by {@link createFunctionDoc}. Covers any function, including
- * hooks: an inputs (`params`) + outputs (`returns`) surface. The `type`
- * discriminant is injected by the factory; `importPath` is DERIVED.
- */
-export interface AstryxFunctionDocInput extends AstryxBaseDocInput {
-  /** Function/hook parameters or options-object fields. */
-  params: AstryxParamInput[];
-  /** Return value documentation. One entry per field (or a single primitive). */
-  returns: AstryxReturnInput[];
-}
-
-/**
- * Input accepted by {@link createDoc}. A generic reference/topic doc — just the
- * shared base. The `type` discriminant is injected by the factory.
- */
-export type AstryxGenericDocInput = AstryxBaseDocInput;
-
-/**
- * Back-compat alias. Previously `createDoc` accepted a broad component-doc
- * record; the union of the three input kinds preserves that permissiveness for
- * any code referring to the old name.
- */
-export type AstryxComponentDoc =
-  | AstryxComponentDocInput
-  | AstryxFunctionDocInput
-  | AstryxGenericDocInput;
-
-/**
- * Author a component doc. Stamp-only: returns the def with `type: 'component'`
- * injected. Validation happens at the CLI load boundary.
- */
-export function createComponentDoc<T extends AstryxComponentDocInput>(
-  def: T,
-): T & {type: 'component'} {
-  return {...def, type: 'component'};
-}
-
-/**
- * Author a function doc (covers any function, including hooks). Stamp-only:
- * returns the def with `type: 'function'` injected. Validation happens at the
- * CLI load boundary.
- */
-export function createFunctionDoc<T extends AstryxFunctionDocInput>(
-  def: T,
-): T & {type: 'function'} {
-  return {...def, type: 'function'};
-}
-
-/**
- * Author a generic reference/topic doc. Stamp-only: returns the def with
- * `type: 'generic'` injected. Validation happens at the CLI load boundary.
- */
-export function createDoc<T extends AstryxGenericDocInput>(
-  def: T,
-): T & {type: 'generic'} {
-  return {...def, type: 'generic'};
-}