forty-cdk 0.0.4 → 0.2.0

package/internationalized-date/README.md

@@ -1,23 +1,23 @@
-# forty-cdk/internationalized-date
-
-Secondary entry point holding the [`@internationalized/date`](https://react-spectrum.adobe.com/internationalized/date/) implementations of the `DateAdapter` contract:
-
-- `InternationalizedDateAdapter` / `provideInternationalizedDateAdapter()` — day-granular `CalendarDate`.
-- `InternationalizedDateTimeAdapter` / `provideInternationalizedDateTimeAdapter()` — time-capable `CalendarDateTime`.
-
-It exists so the main `forty-cdk` bundle never references `@internationalized/date`: the package is an **optional peer dependency**, required only by consumers who import this entry point. The date/time primitives themselves (`Calendar`, `DateField`, `DatePicker`, `TimeField`) depend only on the abstract `DateAdapter` from the main entry point — `provideNativeDateAdapter()` works with zero extra installs.
-
-```bash
-npm install @internationalized/date
-```
-
-```ts
-import { bootstrapApplication } from '@angular/platform-browser';
-import { provideInternationalizedDateAdapter } from 'forty-cdk/internationalized-date';
-
-bootstrapApplication(App, {
-  providers: [provideInternationalizedDateAdapter()],
-});
-```
-
-See the [Calendar README](../src/lib/calendar/README.md) for the full adapter table and usage examples.
+# forty-cdk/internationalized-date
+
+Secondary entry point holding the [`@internationalized/date`](https://react-spectrum.adobe.com/internationalized/date/) implementations of the `DateAdapter` contract:
+
+- `InternationalizedDateAdapter` / `provideInternationalizedDateAdapter()` — day-granular `CalendarDate`.
+- `InternationalizedDateTimeAdapter` / `provideInternationalizedDateTimeAdapter()` — time-capable `CalendarDateTime`.
+
+It exists so the main `forty-cdk` bundle never references `@internationalized/date`: the package is an **optional peer dependency**, required only by consumers who import this entry point. The date/time primitives themselves (`Calendar`, `DateField`, `DatePicker`, `TimeField`) depend only on the abstract `DateAdapter` from the main entry point — `provideNativeDateAdapter()` works with zero extra installs.
+
+```bash
+npm install @internationalized/date
+```
+
+```ts
+import { bootstrapApplication } from '@angular/platform-browser';
+import { provideInternationalizedDateAdapter } from 'forty-cdk/internationalized-date';
+
+bootstrapApplication(App, {
+  providers: [provideInternationalizedDateAdapter()],
+});
+```
+
+See the [Calendar README](../src/lib/calendar/README.md) for the full adapter table and usage examples.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forty-cdk",
-  "version": "0.0.4",
+  "version": "0.2.0",
   "description": "Headless / styleless UI primitives for Angular with WAI-ARIA accessibility built in.",
   "keywords": [
     "angular",
@@ -60,6 +60,10 @@
     "./internationalized-date": {
       "types": "./types/forty-cdk-internationalized-date.d.ts",
       "default": "./fesm2022/forty-cdk-internationalized-date.mjs"
+    },
+    "./virtualization": {
+      "types": "./types/forty-cdk-virtualization.d.ts",
+      "default": "./fesm2022/forty-cdk-virtualization.mjs"
     }
   },
   "type": "module"

package/types/forty-cdk-internationalized-date.d.ts

@@ -5,8 +5,8 @@ import { DateAdapter } from 'forty-cdk';
 
 /**
  * {@link DateAdapter} over `@internationalized/date`'s immutable `CalendarDate`.
- * This is the recommended adapter: it is the same date primitive React Aria and
- * Ark UI build on, it works in every browser today with no polyfill, and its
+ * This is the recommended adapter: it is a widely-used immutable date primitive,
+ * it works in every browser today with no polyfill, and its
  * reference-equality-on-mutation makes it signal-friendly.
  *
  * **Gregorian only.** `createDate` always builds a Gregorian `CalendarDate`, so

package/types/forty-cdk-virtualization.d.ts

@@ -0,0 +1,305 @@
+import * as _angular_core from '@angular/core';
+import { Signal, InjectionToken, OnInit } from '@angular/core';
+
+/**
+ * Configuration for {@link injectVirtualizer}. The consumer owns the data and
+ * the DOM; the virtualizer only computes which slice of the data is visible.
+ */
+interface VirtualizerOptions {
+    /** Reactive total number of items in the list. */
+    readonly count: Signal<number>;
+    /**
+     * Estimated size, in CSS pixels, of the item at `index` along the scroll
+     * axis (height when vertical, width when horizontal). Used until an item is
+     * measured. Should be a stable function reference.
+     */
+    readonly estimateSize: (index: number) => number;
+    /** Reactive reference to the scroll container element (e.g. a `viewChild`). */
+    readonly scrollElement: Signal<HTMLElement | null>;
+    /** Scroll axis. Defaults to `'vertical'`. */
+    readonly orientation?: 'vertical' | 'horizontal';
+    /**
+     * Number of items to render beyond the visible window on each side, to
+     * reduce blank flashes while scrolling. Defaults to `5`.
+     */
+    readonly overscan?: number;
+    /** Stable key for the item at `index`. Defaults to the index itself. */
+    readonly getItemKey?: (index: number) => string | number;
+}
+/** A single item in the currently rendered window. */
+interface VirtualItem {
+    /** Index of the item in the full list. */
+    readonly index: number;
+    /** Stable key (from `getItemKey`, or the index). */
+    readonly key: string | number;
+    /** Offset of the item from the start of the scroll container, in pixels. */
+    readonly start: number;
+    /** Size of the item along the scroll axis, in pixels. */
+    readonly size: number;
+}
+/** Reactive handle returned by {@link injectVirtualizer}. */
+interface ForVirtualizer {
+    /** The items in the currently visible window plus overscan. */
+    readonly virtualItems: Signal<readonly VirtualItem[]>;
+    /** Total scroll size of all items, in pixels (drives the spacer element). */
+    readonly totalSize: Signal<number>;
+    /**
+     * The inclusive-exclusive `[firstIndex, lastIndex + 1)` index window currently
+     * rendered (visible window plus overscan), or `[0, 0]` when nothing is rendered.
+     * Plugs straight into a list primitive's `[visibleRange]`-style input (e.g.
+     * `[forCombobox][visibleRange]`) so windowing composes without the consumer
+     * re-deriving the range from {@link ForVirtualizer.virtualItems}.
+     */
+    readonly range: Signal<readonly [number, number]>;
+    /** Scroll the container so the item at `index` is in view. */
+    scrollToIndex(index: number, options?: {
+        align?: 'start' | 'center' | 'end' | 'auto';
+    }): void;
+    /** Scroll the container to an absolute pixel offset. */
+    scrollToOffset(offset: number): void;
+    /** Record the measured size of a rendered item element (dynamic sizes). */
+    measureElement(element: HTMLElement): void;
+}
+/**
+ * Headless windowing core: given a reactive item count, a size estimator and a
+ * scroll container, returns the slice of items currently visible (plus
+ * overscan), the total scroll size, and imperative scroll/measure helpers. The
+ * consumer renders the items with their own `@for` and applies the position
+ * transform — this primitive owns no DOM.
+ *
+ * Backed by `@tanstack/virtual-core`. SSR-safe: off-browser it returns an empty
+ * window and the estimate-based total without touching `document`/`window`; the
+ * first real window is produced after the first browser render.
+ *
+ * Must be called from an injection context (a component/directive constructor
+ * or field initializer).
+ *
+ * @param options Reactive count, size estimator, scroll element and tuning.
+ * @returns A {@link ForVirtualizer} handle of signals + imperative methods.
+ */
+declare function injectVirtualizer(options: VirtualizerOptions): ForVirtualizer;
+
+/**
+ * Configuration for {@link injectInfiniteScroll}. The consumer owns the data and
+ * the fetch; this core only decides *when* to ask for more.
+ */
+interface InfiniteScrollOptions {
+    /**
+     * The rendered window, `[firstIndex, lastIndex + 1)` — e.g.
+     * `injectVirtualizer(...).range`. An empty `[0, 0]` window never fires.
+     */
+    readonly range: Signal<readonly [number, number]>;
+    /** Reactive total number of currently-loaded items. */
+    readonly count: Signal<number>;
+    /**
+     * Fire when the window's last index comes within this many items of `count`.
+     * Defaults to `5` (mirrors the windowing core's default overscan).
+     */
+    readonly threshold?: number;
+    /** When this resolves to `true` the detector never fires. */
+    readonly disabled?: Signal<boolean>;
+    /**
+     * Called once per threshold crossing. If it returns a promise, the next fire
+     * is suppressed until that promise settles (`pending` reflects the in-flight
+     * state); the detector re-arms when `count` grows.
+     */
+    readonly onLoadMore: () => void | Promise<unknown>;
+}
+/** Reactive handle returned by {@link injectInfiniteScroll}. */
+interface ForInfiniteScroll {
+    /** True while an `onLoadMore` promise is in flight. */
+    readonly pending: Signal<boolean>;
+}
+/**
+ * Headless infinite-scroll detector: composes on top of any windowed list's
+ * `range` + `count` signals and fires `onLoadMore` once per threshold crossing,
+ * suppressing re-fire while a returned promise is pending and re-arming when
+ * `count` grows (a page was appended). It owns no DOM, adds no scroll listener —
+ * the trigger rides the existing reactive recompute — and is SSR-safe by
+ * construction: off-browser the window is `[0, 0]`, so it never fires.
+ *
+ * Must be called from an injection context (a component/directive constructor
+ * or field initializer).
+ *
+ * @param options Reactive `range` + `count`, an optional `threshold`/`disabled`,
+ *   and the `onLoadMore` callback.
+ * @returns A {@link ForInfiniteScroll} handle exposing the `pending` signal.
+ */
+declare function injectInfiniteScroll(options: InfiniteScrollOptions): ForInfiniteScroll;
+
+/**
+ * Coordination surface a {@link ForVirtualViewport} exposes to the
+ * `*forVirtualFor` structural directive nested inside it.
+ */
+interface ForVirtualViewportContext {
+    /** The items in the currently visible window plus overscan. */
+    readonly virtualItems: Signal<readonly VirtualItem[]>;
+    /** The total number of items in the full (non-windowed) list. */
+    readonly count: Signal<number>;
+    /** Scroll axis, resolved once when the viewport initializes. */
+    readonly orientation: Signal<'vertical' | 'horizontal'>;
+}
+/** DI token carrying the {@link ForVirtualViewportContext}. */
+declare const FOR_VIRTUAL_VIEWPORT_CONTEXT: InjectionToken<ForVirtualViewportContext>;
+
+/**
+ * Scroll viewport for the ergonomic virtualization layer. Decorate a fixed-size
+ * scroll container with `[forVirtualViewport]`, give it `[virtualCount]` and an
+ * `[estimateSize]`, and nest a single `*forVirtualFor` inside it — the viewport
+ * owns the scroll container, the total-size sizer, and the windowing core, so
+ * the consumer writes no manual spacer or position transform.
+ *
+ * Built on the headless {@link injectVirtualizer} core; for full manual control
+ * (custom DOM, dynamic measurement, window/document scroller) use that directly.
+ *
+ * The viewport forces `overflow: auto` on its host and renders a relatively
+ * positioned sizer whose main-axis size tracks `totalSize()`; `*forVirtualFor`
+ * projects its rows into that sizer and positions each one absolutely.
+ *
+ * `orientation` and `overscan` are read once when the viewport initializes;
+ * change them before first render, not at runtime.
+ */
+declare class ForVirtualViewport implements ForVirtualViewportContext, OnInit {
+    #private;
+    /** Total number of items in the full list. */
+    readonly virtualCount: _angular_core.InputSignal<number>;
+    /** Estimated item size in px along the scroll axis: a number or a per-index estimator. */
+    readonly estimateSize: _angular_core.InputSignal<number | ((index: number) => number)>;
+    /** Scroll axis. Resolved once on init; runtime changes are not tracked by the core. */
+    readonly orientation: _angular_core.InputSignal<"vertical" | "horizontal">;
+    /** Items rendered beyond the visible window on each side. Resolved once on init. */
+    readonly overscan: _angular_core.InputSignal<number>;
+    /** Stable key for the item at `index`. Defaults to the index. */
+    readonly getItemKey: _angular_core.InputSignal<((index: number) => string | number) | undefined>;
+    /**
+     * Emits when the rendered window comes within ~`overscan` items of the end of
+     * the list, signalling the consumer to load the next page. Built on
+     * {@link injectInfiniteScroll}; fires once per threshold crossing and re-arms
+     * when the bound count grows. The consumer owns the fetch (e.g. via `resource()`).
+     */
+    readonly endReached: _angular_core.OutputEmitterRef<void>;
+    /**
+     * The total number of items in the full (non-windowed) list — the
+     * {@link ForVirtualViewportContext.count} the nested `*forVirtualFor` reads.
+     * Aliases the `virtualCount` input signal directly (no wrapper node).
+     */
+    readonly count: _angular_core.InputSignal<number>;
+    /** The items in the currently visible window plus overscan. */
+    readonly virtualItems: Signal<readonly VirtualItem[]>;
+    /** Total scroll size of all items, in pixels (drives the sizer). */
+    readonly totalSize: Signal<number>;
+    protected readonly sizerWidth: Signal<string>;
+    protected readonly sizerHeight: Signal<string>;
+    ngOnInit(): void;
+    /** Scroll the container so the item at `index` is in view. No-op until initialized. */
+    scrollToIndex(index: number, options?: {
+        align?: 'start' | 'center' | 'end' | 'auto';
+    }): void;
+    /** Scroll the container to an absolute pixel offset. No-op until initialized. */
+    scrollToOffset(offset: number): void;
+    /** Record the measured size of a rendered item element. No-op until initialized. */
+    measureElement(element: HTMLElement): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ForVirtualViewport, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<ForVirtualViewport, "for-virtual-viewport, [forVirtualViewport]", ["forVirtualViewport"], { "virtualCount": { "alias": "virtualCount"; "required": true; "isSignal": true; }; "estimateSize": { "alias": "estimateSize"; "required": false; "isSignal": true; }; "orientation": { "alias": "orientation"; "required": false; "isSignal": true; }; "overscan": { "alias": "overscan"; "required": false; "isSignal": true; }; "getItemKey": { "alias": "getItemKey"; "required": false; "isSignal": true; }; }, { "endReached": "endReached"; }, never, ["*"], true, never>;
+}
+
+/** Template context exposed to each row rendered by `*forVirtualFor`. */
+interface ForVirtualForContext<T> {
+    /** The row data at this index (`let row`). */
+    $implicit: T;
+    /** The virtual item metadata: index, key, start offset, size (`let item = virtualItem`). */
+    virtualItem: VirtualItem;
+    /** The item's index in the full list (`let i = index`). */
+    index: number;
+    /** The total number of items in the full list (`let n = count`). */
+    count: number;
+}
+/**
+ * Structural directive that renders only the visible window of a list inside a
+ * `[forVirtualViewport]`. Pass the full data array; the directive iterates the
+ * viewport's `virtualItems()`, exposes each row plus its `virtualItem` to the
+ * template, positions it absolutely (so the consumer writes no transform), and
+ * binds `aria-setsize` (true total) / `aria-posinset` (`index + 1`) so screen
+ * readers announce the real list size.
+ *
+ * ```html
+ * <div forVirtualViewport [virtualCount]="rows().length" [estimateSize]="44">
+ *   <div *forVirtualFor="let row of rows(); let item = virtualItem">{{ row.label }}</div>
+ * </div>
+ * ```
+ */
+declare class ForVirtualFor<T> {
+    #private;
+    /** The full list of items to virtualize. */
+    readonly forVirtualForOf: _angular_core.InputSignal<readonly T[]>;
+    constructor();
+    /** Narrows the template context type for `let row of …` strict template checking. */
+    static ngTemplateContextGuard<T>(_directive: ForVirtualFor<T>, _context: unknown): _context is ForVirtualForContext<T>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ForVirtualFor<any>, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<ForVirtualFor<any>, "[forVirtualFor][forVirtualForOf]", never, { "forVirtualForOf": { "alias": "forVirtualForOf"; "required": true; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+/**
+ * Opt-in row-virtualization companion for `[forTable]` in `<div role>` grid mode. Place it on the
+ * same element as `[forTable]`; it builds the windowing core from the table's `[rowCount]` and
+ * exposes the visible window for the consumer to render with their own `@for` + position transform.
+ *
+ * Tree-shakeable: `ForTable` never imports the virtualization core — only consumers that import
+ * `ForTableVirtualized` bundle `@tanstack/virtual-core`.
+ *
+ * The focused row is kept mounted even when scrolled out of the window so the roving-focused
+ * `gridcell` is never unmounted. SSR-safe: off-browser the window is empty and
+ * `totalSize` is the estimate-based total.
+ *
+ * Also drives cross-window keyboard navigation: when an Arrow / Page / Ctrl+Home / Ctrl+End grid
+ * action resolves a row outside the rendered window, it scrolls that row into view and moves roving
+ * focus onto the target cell once it mounts (preserving the current column). `ForTable` stays
+ * unaware of virtualization — it delegates the row-crossing move through the table context.
+ */
+declare class ForTableVirtualized {
+    #private;
+    /** Estimated row size in px along the scroll axis (the fixed-size fast path). Read for the size estimate. */
+    readonly estimateRowSize: _angular_core.InputSignalWithTransform<number, unknown>;
+    /**
+     * Scroll container. Defaults to the table root element (the scroll container in `<div>` grid
+     * mode). Bind it explicitly when the scroll container is an **ancestor** of the table — e.g. an
+     * app-shell viewport that scrolls projected content — since the table cannot inject an ancestor
+     * it does not own. A design-system wrapper can re-expose or rename this input through
+     * `hostDirectives` input aliasing (`inputs: ['scrollElement: scrollContainer']`) with no bridging
+     * effect required.
+     */
+    readonly scrollElement: _angular_core.InputSignal<HTMLElement | null>;
+    constructor();
+    /**
+     * The rows in the visible window plus overscan, augmented to always include the focused row and
+     * the row being reordered even when they are scrolled out of view (so the roving-focused cell
+     * stays mounted, and a pointer reorder drag never unmounts the lifted row). Render these with
+     * `@for (vrow of v.virtualRows(); track vrow.index)` and position each row absolutely with
+     * `transform: translateY(vrow.start + 'px')`. Bind each row's `[virtualIndex]="vrow.index"`.
+     */
+    readonly virtualRows: _angular_core.Signal<readonly VirtualItem[]>;
+    /** Total scroll size of all rows in px. Bind to the body container's height to size the scroll range. */
+    readonly totalSize: _angular_core.Signal<number>;
+    /**
+     * The rendered window as the inclusive-exclusive `[firstIndex, lastIndex + 1)` index range,
+     * sourced from the underlying virtualizer (the true window) — not from {@link virtualRows},
+     * which is augmented with the focused / reordering rows. So a row retained out of the window
+     * never widens this range. Plugs straight into `injectInfiniteScroll({ range, count, onLoadMore })`.
+     */
+    readonly range: _angular_core.Signal<readonly [number, number]>;
+    /**
+     * Scroll the container so the row at `index` is in view. Cross-window keyboard
+     * navigation calls this internally; consumers may also call it to scroll
+     * programmatically.
+     */
+    scrollToRow(index: number, options?: {
+        align?: 'start' | 'center' | 'end' | 'auto';
+    }): void;
+    /** Record the measured size of a rendered row element (dynamic / measured row heights). */
+    measureRow(element: HTMLElement): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ForTableVirtualized, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<ForTableVirtualized, "[forTableVirtualized]", ["forTableVirtualized"], { "estimateRowSize": { "alias": "estimateRowSize"; "required": false; "isSignal": true; }; "scrollElement": { "alias": "scrollElement"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+export { FOR_VIRTUAL_VIEWPORT_CONTEXT, ForTableVirtualized, ForVirtualFor, ForVirtualViewport, injectInfiniteScroll, injectVirtualizer };
+export type { ForInfiniteScroll, ForVirtualForContext, ForVirtualViewportContext, ForVirtualizer, InfiniteScrollOptions, VirtualItem, VirtualizerOptions };