forty-cdk 0.2.0 → 0.3.0

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

@@ -0,0 +1,214 @@
+import * as _angular_core from '@angular/core';
+import { InjectionToken, Signal, Provider } from '@angular/core';
+import { WritingDirection } from 'forty-cdk/core';
+import * as forty_cdk_pagination from 'forty-cdk/pagination';
+
+/**
+ * One entry in the computed visible-page list: either a clickable page number
+ * or an ellipsis gap standing in for a collapsed run of pages.
+ */
+interface PaginationItem {
+    /** Discriminator: a real page button, or a non-interactive ellipsis gap. */
+    readonly type: 'page' | 'ellipsis';
+    /** 1-based page number. Present only when `type` is `'page'`. */
+    readonly value?: number;
+}
+
+/**
+ * Coordination contract owned by `ForPagination`. Page buttons, previous, and
+ * next pieces inject it to read the current page / derived list and drive
+ * navigation from a single source of truth.
+ */
+interface ForPaginationContext {
+    /** Current 1-based page. */
+    readonly page: Signal<number>;
+    /** Total number of pages. */
+    readonly count: Signal<number>;
+    /** Whether the whole control is disabled. */
+    readonly disabled: Signal<boolean>;
+    /** The computed visible-page list (page numbers + ellipsis gaps). */
+    readonly items: Signal<readonly PaginationItem[]>;
+    /** Whether the current page is the first (no previous page). */
+    readonly isFirst: Signal<boolean>;
+    /** Whether the current page is the last (no next page). */
+    readonly isLast: Signal<boolean>;
+    /** Navigate to `page`, clamped to `[1, count]`. No-op when disabled. */
+    goToPage(page: number): void;
+    /** Navigate to the previous page. No-op at the first page or when disabled. */
+    previous(): void;
+    /** Navigate to the next page. No-op at the last page or when disabled. */
+    next(): void;
+}
+/** DI token providing the pagination context to descendant pieces. */
+declare const FOR_PAGINATION_CONTEXT: InjectionToken<ForPaginationContext>;
+
+/**
+ * Headless pagination navigation landmark, implementing the
+ * [WAI-ARIA `navigation` landmark](https://www.w3.org/WAI/ARIA/apg/patterns/landmarks/examples/navigation.html)
+ * with [`aria-current="page"`](https://www.w3.org/TR/wai-aria-1.2/#aria-current) on the active page.
+ *
+ * Derives the visible page list (with ellipsis gaps) from `page`, `count`,
+ * `siblingCount`, and `boundaryCount`. Exposes `items()`, `isFirst()`,
+ * `isLast()`, and navigation methods for the consumer template to render.
+ *
+ * There is no roving tabindex — each page button, previous, and next are their
+ * own tab stops. RTL is visual-only: the resolved `dir` reflects on the host
+ * for CSS; navigation semantics (previous = decrement, next = increment) never
+ * change based on direction.
+ *
+ * @example
+ * ```html
+ * <nav forPagination [(page)]="page" [count]="20" ariaLabel="Pagination" #pg="forPagination">
+ *   <button forPaginationPrevious ariaLabel="Previous page">‹</button>
+ *   @for (item of pg.items(); track $index) {
+ *     @if (item.type === 'page') {
+ *       <button forPaginationItem [page]="item.value!">{{ item.value }}</button>
+ *     } @else {
+ *       <span aria-hidden="true">…</span>
+ *     }
+ *   }
+ *   <button forPaginationNext ariaLabel="Next page">›</button>
+ * </nav>
+ * ```
+ */
+declare class ForPagination implements ForPaginationContext {
+    #private;
+    /**
+     * Current 1-based page number. Two-way bindable via `[(page)]`. The implicit
+     * `pageChange` output emits whenever the directive updates this value (via
+     * clicks, previous, or next). Do not add a separate `pageChange` output.
+     */
+    readonly page: _angular_core.ModelSignal<number>;
+    /**
+     * Total number of pages. Always bind as `[count]="n"` (a number, not a
+     * string). Required.
+     */
+    readonly count: _angular_core.InputSignal<number>;
+    /**
+     * Pages shown on each side of the current page before collapsing to an
+     * ellipsis. Default read from `provideForPaginationDefaults` for the
+     * surrounding scope (library fallback: `1`).
+     */
+    readonly siblingCount: _angular_core.InputSignalWithTransform<number, unknown>;
+    /**
+     * Pages always shown at each end (first and last). Default read from
+     * `provideForPaginationDefaults` for the surrounding scope (library
+     * fallback: `1`).
+     */
+    readonly boundaryCount: _angular_core.InputSignalWithTransform<number, unknown>;
+    /** Whether the entire pagination control is disabled. */
+    readonly disabled: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /**
+     * Writing direction. When unset (default `null`), the inherited ambient
+     * direction is resolved from the nearest ancestor carrying a `dir` attribute
+     * (or `<html dir>`), defaulting to `'ltr'`. An explicit `[dir]` always wins.
+     * The resolved value is reflected to the host `dir` attribute. RTL affects
+     * visual layout only — previous/next semantics do not change.
+     */
+    readonly _dirInput: _angular_core.InputSignal<WritingDirection | null>;
+    readonly dir: _angular_core.Signal<WritingDirection>;
+    /**
+     * Accessible label for the navigation landmark. Supply this (or point
+     * `aria-labelledby` at a visible label element) when the page contains more
+     * than one `<nav>`. A `null` or empty value emits no attribute.
+     */
+    readonly ariaLabel: _angular_core.InputSignal<string | null>;
+    /** The computed visible-page list (page numbers + ellipsis gaps). */
+    readonly items: _angular_core.Signal<readonly PaginationItem[]>;
+    /** Whether the current page is the first (no previous page). */
+    readonly isFirst: _angular_core.Signal<boolean>;
+    /** Whether the current page is the last (no next page). */
+    readonly isLast: _angular_core.Signal<boolean>;
+    /**
+     * Navigate to `page`, clamped to `[1, count]`. No-op when disabled.
+     */
+    goToPage(page: number): void;
+    /** Navigate to the previous page. No-op at the first page or when disabled. */
+    previous(): void;
+    /** Navigate to the next page. No-op at the last page or when disabled. */
+    next(): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ForPagination, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<ForPagination, "[forPagination]", ["forPagination"], { "page": { "alias": "page"; "required": false; "isSignal": true; }; "count": { "alias": "count"; "required": true; "isSignal": true; }; "siblingCount": { "alias": "siblingCount"; "required": false; "isSignal": true; }; "boundaryCount": { "alias": "boundaryCount"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "_dirInput": { "alias": "dir"; "required": false; "isSignal": true; }; "ariaLabel": { "alias": "ariaLabel"; "required": false; "isSignal": true; }; }, { "page": "pageChange"; }, never, never, true, never>;
+}
+
+/**
+ * Page number button. Apply on a `<button>` so Enter/Space activation is
+ * native. Reflects `aria-current="page"` when this button represents the
+ * currently active page. Clicking calls `ctx.goToPage(page)`.
+ */
+declare class ForPaginationItem {
+    protected readonly ctx: forty_cdk_pagination.ForPaginationContext;
+    /** The 1-based page number this button navigates to. */
+    readonly page: _angular_core.InputSignal<number>;
+    /** Per-item disabled override (in addition to the root's `disabled`). */
+    readonly disabled: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** Whether this item is effectively disabled (own or root disabled). */
+    readonly effectiveDisabled: _angular_core.Signal<boolean>;
+    /** Whether this button represents the currently active page. */
+    readonly isCurrent: _angular_core.Signal<boolean>;
+    constructor();
+    protected activate(): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ForPaginationItem, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<ForPaginationItem, "[forPaginationItem]", ["forPaginationItem"], { "page": { "alias": "page"; "required": true; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+/**
+ * Previous-page button. Apply on a `<button>` so Enter/Space activation is
+ * native. Disabled (via the native `disabled` attribute) when the current page
+ * is the first page or the root is disabled. Clicking calls `ctx.previous()`.
+ */
+declare class ForPaginationPrevious {
+    protected readonly ctx: forty_cdk_pagination.ForPaginationContext;
+    /**
+     * Accessible label for this button (e.g. "Previous page"). When `null`
+     * (default), no `aria-label` is emitted — the consumer should supply a
+     * visible label or set this input.
+     */
+    readonly ariaLabel: _angular_core.InputSignal<string | null>;
+    protected readonly isDisabled: _angular_core.Signal<boolean>;
+    constructor();
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ForPaginationPrevious, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<ForPaginationPrevious, "[forPaginationPrevious]", ["forPaginationPrevious"], { "ariaLabel": { "alias": "ariaLabel"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+/**
+ * Next-page button. Apply on a `<button>` so Enter/Space activation is
+ * native. Disabled (via the native `disabled` attribute) when the current page
+ * is the last page or the root is disabled. Clicking calls `ctx.next()`.
+ */
+declare class ForPaginationNext {
+    protected readonly ctx: forty_cdk_pagination.ForPaginationContext;
+    /**
+     * Accessible label for this button (e.g. "Next page"). When `null`
+     * (default), no `aria-label` is emitted — the consumer should supply a
+     * visible label or set this input.
+     */
+    readonly ariaLabel: _angular_core.InputSignal<string | null>;
+    protected readonly isDisabled: _angular_core.Signal<boolean>;
+    constructor();
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ForPaginationNext, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<ForPaginationNext, "[forPaginationNext]", ["forPaginationNext"], { "ariaLabel": { "alias": "ariaLabel"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+/**
+ * Defaults inherited by descendant paginations in the surrounding injector
+ * scope. Configure with `provideForPaginationDefaults` at the application root
+ * or in any component's `providers`; partial overrides merge with the parent.
+ */
+interface ForPaginationDefaults {
+    /** Pages shown on each side of the current page before collapsing to an ellipsis. */
+    siblingCount: number;
+    /** Pages always shown at each end (first/last). */
+    boundaryCount: number;
+}
+/** Token holding the resolved pagination defaults for the current scope. */
+declare const FOR_PAGINATION_DEFAULTS: _angular_core.InjectionToken<ForPaginationDefaults>;
+/**
+ * Configures forty-cdk pagination defaults for this injector scope. Partial
+ * overrides inherit unspecified keys from the parent scope (or library defaults
+ * at the root).
+ */
+declare function provideForPaginationDefaults(defaults?: Partial<ForPaginationDefaults>): Provider[];
+
+export { FOR_PAGINATION_CONTEXT, FOR_PAGINATION_DEFAULTS, ForPagination, ForPaginationItem, ForPaginationNext, ForPaginationPrevious, provideForPaginationDefaults };
+export type { ForPaginationContext, ForPaginationDefaults, PaginationItem };

package/types/forty-cdk-pane-resizer.d.ts

@@ -0,0 +1,145 @@
+import * as _angular_core from '@angular/core';
+import { Provider } from '@angular/core';
+import { WritingDirection } from 'forty-cdk/core';
+
+/**
+ * Headless implementation of the
+ * [WAI-ARIA Window Splitter pattern](https://www.w3.org/WAI/ARIA/apg/patterns/windowsplitter/):
+ * the focusable divider between two resizable panes. Carries `role="separator"`
+ * with live `aria-valuenow` / `aria-valuemin` / `aria-valuemax`, is tabbable,
+ * handles arrow keys / Page Up-Down / Home / End / (optional) Enter, and
+ * supports pointer drag with `setPointerCapture`. Emits `(resizing)` on every
+ * mutation and `(resizeCommit)` once per key release / drag end.
+ *
+ * It is essentially a 1-D slider wearing a separator role; the static
+ * `[forSeparator]` divider stays a separate, thinner primitive so a visual-only
+ * separator never pulls the drag / keyboard-resize code in.
+ *
+ * Pointer drag arms only after the pointer travels past a small dead-zone (a
+ * few px), so a plain click that fires a stray sub-threshold `pointermove`
+ * never mutates the value — `(resizing)` won't fire on a jittery click.
+ *
+ * @example
+ * ```html
+ * <!-- Vertical divider between two horizontally stacked panes. -->
+ * <div
+ *   forPaneResizer
+ *   orientation="vertical"
+ *   [(value)]="size"
+ *   [min]="100"
+ *   [max]="700"
+ *   [step]="8"
+ *   [largeStep]="80"
+ *   aria-controls="pane-a pane-b"
+ * ></div>
+ * ```
+ */
+declare class ForPaneResizer {
+    #private;
+    /**
+     * Axis the divider line runs along. `horizontal` splits content stacked
+     * vertically; `vertical` splits content arranged horizontally. Defaults to
+     * `horizontal`.
+     *
+     * `orientation` describes the *separator line*; the resize axis runs
+     * perpendicular to it. APG: a horizontal pane stack uses a vertical
+     * separator, and arrow keys move along the resize axis.
+     */
+    readonly orientation: _angular_core.InputSignal<"horizontal" | "vertical">;
+    /**
+     * Disables the resizer: it drops out of tab order, no keyboard or pointer
+     * mutation fires, and `aria-disabled` / `data-disabled` are reflected.
+     */
+    readonly disabled: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /**
+     * Two-way bindable. The current value along the resize axis. Units are
+     * consumer-defined (px, %, fr, rem, …) — the directive treats this as an
+     * opaque number constrained by `min` / `max`. Pointer drag adds raw px
+     * deltas, so use px units when wiring drag directly; keyboard navigation is
+     * unit-agnostic.
+     *
+     * The `model()` change emitter (`(valueChange)`) follows the project-wide
+     * contract: it fires only on internal updates (keyboard, drag), never on
+     * consumer writes via `[(value)]` — observe transitions without binding
+     * back. `(resizing)` carries the same value with a verb-named alias for
+     * one-way wiring.
+     */
+    readonly value: _angular_core.ModelSignal<number>;
+    /** Lower bound for `value`. Default `0`. */
+    readonly min: _angular_core.InputSignal<number>;
+    /** Upper bound for `value`. Default `100` (matches a percentage default). */
+    readonly max: _angular_core.InputSignal<number>;
+    /** Step applied by ArrowKeys along the resize axis. Default `1`. */
+    readonly step: _angular_core.InputSignal<number>;
+    /** Step applied by `Page Up` / `Page Down`. Default `10`. */
+    readonly largeStep: _angular_core.InputSignal<number>;
+    /**
+     * Optional human-readable value for `aria-valuetext`. Use when the bare
+     * number is not meaningful to AT (e.g. `"30 percent of viewport"`). When
+     * `null`, AT reads `aria-valuenow`.
+     */
+    readonly valueText: _angular_core.InputSignal<string | null>;
+    /**
+     * Space-separated list of element ids the resizer splits. Surfaces as
+     * `aria-controls`. Recommended per APG so AT can relate the resizer to the
+     * panes it affects.
+     */
+    readonly controls: _angular_core.InputSignal<string | null>;
+    /**
+     * Opt-in `Enter` (and `Space`) toggle: collapses the value to `min` and
+     * restores the last non-min value on the next press. APG-optional behaviour
+     * for resizers that back a collapsible pane. Off by default — enabling it
+     * changes the meaning of `Enter`.
+     */
+    readonly collapsible: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /**
+     * Reading direction. RTL inverts ArrowLeft / ArrowRight on a vertical
+     * separator (horizontal pane stack) and the horizontal axis of pointer
+     * drag. When unset (default `null`), the inherited ambient direction is
+     * resolved from the nearest ancestor carrying a `dir` attribute (or
+     * `<html dir>`), defaulting to `'ltr'`. An explicit `[dir]` always wins and
+     * the resolved value is reflected to the host `dir` attribute.
+     */
+    readonly _dirInput: _angular_core.InputSignal<WritingDirection | null>;
+    readonly dir: _angular_core.Signal<WritingDirection>;
+    /**
+     * Verb-named alias for the model change emitter. Fires on every value
+     * mutation (keyboard step, pointer-move tick). Emits the same value as
+     * `(valueChange)`; pick one or the other based on whether you want
+     * two-way binding (`[(value)]`) or one-shot observation.
+     */
+    readonly resizing: _angular_core.OutputEmitterRef<number>;
+    /**
+     * Fires once at the end of a resize burst — when the user releases the
+     * pointer (or it is cancelled) or releases an arrow / page key. Useful for
+     * persisting the final size after a drag, where `(resizing)` may fire 60+
+     * times per second.
+     */
+    readonly resizeCommit: _angular_core.OutputEmitterRef<number>;
+    constructor();
+    protected onKeyDown(event: KeyboardEvent): void;
+    protected onKeyUp(_event: KeyboardEvent): void;
+    protected onPointerDown(event: PointerEvent): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ForPaneResizer, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<ForPaneResizer, "[forPaneResizer]", ["forPaneResizer"], { "orientation": { "alias": "orientation"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "value": { "alias": "value"; "required": false; "isSignal": true; }; "min": { "alias": "min"; "required": false; "isSignal": true; }; "max": { "alias": "max"; "required": false; "isSignal": true; }; "step": { "alias": "step"; "required": false; "isSignal": true; }; "largeStep": { "alias": "largeStep"; "required": false; "isSignal": true; }; "valueText": { "alias": "valueText"; "required": false; "isSignal": true; }; "controls": { "alias": "controls"; "required": false; "isSignal": true; }; "collapsible": { "alias": "collapsible"; "required": false; "isSignal": true; }; "_dirInput": { "alias": "dir"; "required": false; "isSignal": true; }; }, { "value": "valueChange"; "resizing": "resizing"; "resizeCommit": "resizeCommit"; }, never, never, true, never>;
+}
+
+/**
+ * Defaults inherited by descendant pane resizers in the surrounding injector
+ * scope. Configure with `provideForPaneResizerDefaults`. The shape is a stub
+ * today — present so future per-scope tuning can land without churning the
+ * public surface.
+ */
+interface ForPaneResizerDefaults {
+}
+/** Token holding the resolved pane-resizer defaults for the current scope. */
+declare const FOR_PANE_RESIZER_DEFAULTS: _angular_core.InjectionToken<ForPaneResizerDefaults>;
+/**
+ * Configures forty-cdk pane-resizer defaults for this injector scope. Partial
+ * overrides inherit unspecified keys from the parent scope (or library
+ * defaults at the root).
+ */
+declare function provideForPaneResizerDefaults(defaults?: Partial<ForPaneResizerDefaults>): Provider[];
+
+export { FOR_PANE_RESIZER_DEFAULTS, ForPaneResizer, provideForPaneResizerDefaults };
+export type { ForPaneResizerDefaults };